@ctrl-spc/cli 1.3.3 → 1.3.5

package/dist/commands/init.js

@@ -9,6 +9,7 @@ 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';
+import { installWakeAgent } from '../wake.js';
 function setGrouping(flags, grouping) {
     if (flags.grouping) {
         throw new Error(`Choose exactly one grouping option: --combine, --split, or --manifest <file>.`);
@@ -448,6 +449,9 @@ export async function init(argv = [], deps = {}) {
         return;
     }
     const client = await getClient();
+    if (installWakeAgent()) {
+        console.log('Remote start enabled — this computer checks in every 60s so you can start it from the web. Disable: ctrl-spc wake off');
+    }
     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'}`);

package/dist/commands/login.js

@@ -4,6 +4,7 @@ import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { SUPABASE_URL, SUPABASE_KEY } from '../env.js';
 import { writeSession } from '../config.js';
 import { getClient } from '../supabase.js';
+import { installWakeAgent } from '../wake.js';
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 /** POST /callback bodies larger than this are rejected before JSON parsing. */
 const MAX_CALLBACK_BODY_BYTES = 64 * 1024;
@@ -16,6 +17,9 @@ export async function login() {
     const outcome = await runLoginServer();
     if (outcome.ok) {
         console.log(`Signed in as ${outcome.email}`);
+        if (installWakeAgent()) {
+            console.log('Remote start enabled — this computer checks in every 60s so you can start it from the web. Disable: ctrl-spc wake off');
+        }
         process.exitCode = 0;
     }
     else {

package/dist/commands/logout.js

@@ -1,12 +1,41 @@
-import { clearSession } from '../config.js';
+import { clearSession, getMachineIdentity } from '../config.js';
+import { getClient } from '../supabase.js';
+import { removeWakeAgent } from '../wake.js';
+async function defaultNullHeartbeats() {
+    const client = await getClient();
+    const { error } = await client
+        .from('machines')
+        .update({ waker_seen_at: null, broker_seen_at: null })
+        .eq('id', getMachineIdentity().id);
+    if (error)
+        throw error;
+}
 /**
  * `ctrl-spc logout`: deletes the stored session. Local-only — the refresh
  * token is discarded, not revoked server-side (Supabase revokes it on next
  * rotation attempt; fine for v1's single-session CLI).
  */
-export function logout() {
-    if (clearSession()) {
-        console.log('Logged out — stored session removed.');
+export async function logout(deps = {}) {
+    try {
+        await (deps.nullHeartbeats ?? defaultNullHeartbeats)();
+    }
+    catch {
+        // Offline or already signed out. The freshness window removes stale UI.
+    }
+    let wakeRemovalFailed = false;
+    try {
+        ;
+        (deps.removeWake ?? removeWakeAgent)();
+    }
+    catch {
+        // Clearing the authenticated session is the security boundary. A stale
+        // plist without a session can only wake, fail authentication, and exit.
+        wakeRemovalFailed = true;
+    }
+    if ((deps.clear ?? clearSession)()) {
+        console.log(wakeRemovalFailed
+            ? 'Logged out — stored session removed. The background start check could not be removed, but it no longer has access to your account.'
+            : 'Logged out — stored session removed and remote start disabled.');
     }
     else {
         console.log('No stored session — already logged out.');

package/dist/commands/run.js

@@ -13,6 +13,7 @@ import { startMcpServer } from '../mcp.js';
 import { getMachineIdentity } from '../config.js';
 import { discoverRepositoryTopology } from '../topology.js';
 import { createAgentDispatchController } from '../dispatch.js';
+import { installWakeAgent, stampMachineHeartbeat } from '../wake.js';
 function mcpUrl() {
     return `http://localhost:${MCP_PORT}/mcp`;
 }
@@ -697,8 +698,9 @@ export function createProjectPresenceReconciler(client, userId, profileName, mac
     const intervalMs = deps.intervalMs ?? 30_000;
     let timer;
     let chain = Promise.resolve();
-    const runReconcile = async () => {
-        await deps.refreshWorkspaces?.();
+    const runReconcile = async (refreshWorkspaces) => {
+        if (refreshWorkspaces)
+            await deps.refreshWorkspaces?.();
         const projects = await loadProjects(client, userId, machine.id);
         const currentIds = new Set(projects.map((project) => project.id));
         for (const project of projects) {
@@ -722,10 +724,10 @@ export function createProjectPresenceReconciler(client, userId, profileName, mac
         }
     };
     return {
-        reconcile() {
+        reconcile(options = {}) {
             // 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);
+            chain = chain.catch(() => { }).then(() => runReconcile(options.refreshWorkspaces !== false));
             return chain;
         },
         start() {
@@ -757,12 +759,13 @@ export function createProjectPresenceReconciler(client, userId, profileName, mac
  * tool call can flip presence back to "working" mid-shutdown) and only then
  * untracks presence, before exiting.
  */
-function installShutdownHandler(presence, mcpServer, dispatch) {
+function installShutdownHandler(presence, mcpServer, dispatch, onShutdown) {
     let shuttingDown = false;
     const shutdown = () => {
         if (shuttingDown)
             return;
         shuttingDown = true;
+        onShutdown?.();
         dispatch?.stop();
         console.log('\nShutting down — closing MCP server, untracking presence...');
         mcpServer
@@ -784,6 +787,8 @@ export async function run() {
     if (retireLegacyDaemon()) {
         console.log('Removed obsolete CTRL+SPC background launcher.');
     }
+    if (process.argv[2] !== '__broker')
+        installWakeAgent();
     const cwd = process.cwd();
     const client = await getClient();
     const { data: userData, error: userError } = await client.auth.getUser();
@@ -841,7 +846,7 @@ export async function run() {
         loadProjects: loadRunnableMachineProjects,
         refreshWorkspaces: () => reconcileMachineWorkspaces(client, userId, machine),
     });
-    await presence.reconcile();
+    await presence.reconcile({ refreshWorkspaces: false });
     presence.start();
     let mcpServer;
     try {
@@ -864,6 +869,14 @@ export async function run() {
         await presence.stop().catch(() => { });
         throw formatMcpStartupError(err, MCP_PORT);
     }
+    // A broker heartbeat means the local server is genuinely accepting work.
+    // Stamp only after startMcpServer succeeds; otherwise a port/startup failure
+    // would make the web app show this computer as online for three minutes.
+    await stampMachineHeartbeat(client, machine.id, true).catch(() => { });
+    const heartbeatTimer = setInterval(() => {
+        void stampMachineHeartbeat(client, machine.id, true).catch(() => { });
+    }, 60_000);
+    heartbeatTimer.unref();
     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, ' +
         'set_task_role_slugs, ' +
@@ -872,5 +885,5 @@ export async function run() {
     console.log(`Projects: ${projects.length > 0 ? projects.map((project) => project.name).join(', ') : 'none initialized on this machine'}`);
     console.log('Presence: available');
     const dispatch = createAgentDispatchController(client, machine.id, registeredAgents);
-    installShutdownHandler(presence, mcpServer, dispatch);
+    installShutdownHandler(presence, mcpServer, dispatch, () => clearInterval(heartbeatTimer));
 }

package/dist/companion-ui.js

@@ -1143,17 +1143,18 @@ export function renderCompanionUi(token, kind, runtimePort = kind === 'local' ?
       const profile = snapshot.profiles.find((candidate) => candidate.kind === kind);
       const action = profile.state === 'ready' ? 'stop' : 'start';
       lastError = '';
+      let succeeded = false;
       setBusy(true, action === 'start' ? 'Switching connection…' : 'Turning connection off…');
       try {
-        await api('/api/runtime/' + kind + '/' + action, { method: 'POST' });
-        await refresh(true);
+        render(await api('/api/runtime/' + kind + '/' + action, { method: 'POST' }));
+        succeeded = true;
       } catch (error) {
         lastError = error.message;
         notice.className = 'notice error';
         notice.textContent = lastError;
       } finally {
         setBusy(false);
-        await refresh(false);
+        if (!succeeded) await refresh(false);
       }
     }
 

package/dist/index.js

@@ -6,6 +6,7 @@ import { link } from './commands/link.js';
 import { fetchRepository } from './commands/fetch.js';
 import { run } from './commands/run.js';
 import { openCompanion, serveCompanion } from './companion.js';
+import { installWakeAgent, removeWakeAgent, wakeCheck } from './wake.js';
 export const HELP_TEXT = `ctrl-spc — CTRL+SPC CLI
 
 Usage:
@@ -18,6 +19,8 @@ Usage:
   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 wake     Enable/disable starting this computer's agents from the web
+                    on|off
   ctrl-spc          Run the local agent process (presence + MCP server)
   ctrl-spc --help   Show this help text
 `;
@@ -28,7 +31,7 @@ export async function main(argv = process.argv.slice(2)) {
             await login();
             return;
         case 'logout':
-            logout();
+            await logout();
             return;
         case 'init':
             await init(argv.slice(1));
@@ -42,6 +45,25 @@ export async function main(argv = process.argv.slice(2)) {
         case 'open':
             await openCompanion();
             return;
+        case 'wake':
+            if (argv[1] === 'off') {
+                console.log(removeWakeAgent()
+                    ? 'Remote start disabled on this computer.'
+                    : 'Remote start was not enabled.');
+            }
+            else if (argv[1] === 'on') {
+                console.log(installWakeAgent()
+                    ? 'Remote start enabled — this computer checks in every 60s. Disable: ctrl-spc wake off'
+                    : 'Remote start requires macOS.');
+            }
+            else {
+                console.error('Usage: ctrl-spc wake on|off');
+                process.exitCode = 1;
+            }
+            return;
+        case '__wake-check':
+            await wakeCheck();
+            return;
         case '__broker':
             await run();
             return;

package/dist/runtime-control.js

@@ -2,7 +2,10 @@ import { execFileSync, spawn } from 'node:child_process';
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { configDir } from './config.js';
+import { configDir, getMachineIdentity } from './config.js';
+export function brokerMatchesRuntime(health, kind, machineId) {
+    return health?.runtime?.kind === kind && health.machine_id === machineId;
+}
 const CURRENT_PACKAGE_PATH = fileURLToPath(new URL('../package.json', import.meta.url));
 const CURRENT_ENTRY_PATH = fileURLToPath(new URL('./index.js', import.meta.url));
 export const LOCAL_RUNTIME_PORT = Number(process.env.CTRL_SPC_LOCAL_PORT) || 4572;
@@ -209,13 +212,16 @@ export async function startRuntime(kind) {
             'Stop it from its terminal before switching connections.');
     }
     const currentHealth = await probeBroker(profile.port);
-    if (currentHealth?.runtime?.kind === kind)
-        return;
+    if (currentHealth?.runtime?.kind === kind) {
+        if (brokerMatchesRuntime(currentHealth, kind, getMachineIdentity().id))
+            return;
+        throw new Error('Another CTRL+SPC connection is already running for a different computer identity. Stop it and try again.');
+    }
     if (currentHealth) {
         throw new Error(`Port ${profile.port} is already used by an unlabeled process. Turn it off before continuing.`);
     }
     mkdirSync(runtimeDir(), { recursive: true });
-    const logFd = openSync(logPath(kind), 'a', 0o600);
+    const logFd = openSync(logPath(kind), 'w', 0o600);
     let child;
     try {
         child = spawn(process.execPath, [profile.entryPath, '__broker'], {
@@ -236,11 +242,16 @@ export async function startRuntime(kind) {
     if (!child.pid)
         throw new Error(`${profile.label} did not start.`);
     writePrivateFile(pidPath(kind), String(child.pid));
+    let childExited = false;
+    child.once('exit', () => { childExited = true; });
     const ready = await waitFor(async () => {
+        if (childExited)
+            return true;
         const health = await probeBroker(profile.port);
-        return health?.runtime?.kind === kind;
+        return brokerMatchesRuntime(health, kind, getMachineIdentity().id);
     }, 30_000, 250);
-    if (!ready) {
+    const health = await probeBroker(profile.port);
+    if (!ready || !brokerMatchesRuntime(health, kind, getMachineIdentity().id)) {
         rmSync(pidPath(kind), { force: true });
         const log = existsSync(logPath(kind)) ? readFileSync(logPath(kind), 'utf8').trim().split('\n').slice(-4).join('\n') : '';
         throw new Error(`${profile.label} did not become ready.${log ? `\n${log}` : ''}`);

package/dist/wake.js

@@ -0,0 +1,237 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getClient } from './supabase.js';
+import { getMachineIdentity } from './config.js';
+import { currentCompanionKind, runtimeStatuses, startRuntime, } from './runtime-control.js';
+const WAKE_LABEL = 'com.ctrl-spc.wake';
+const WAKE_INTERVAL_SECONDS = 60;
+const CURRENT_ENTRY_PATH = fileURLToPath(new URL('./index.js', import.meta.url));
+export const WAKE_REQUEST_FRESH_SECONDS = 150;
+const FAILED_CLEANUP_MINUTES = 10;
+export function wakeAgentPlistPath() {
+    return join(homedir(), 'Library', 'LaunchAgents', `${WAKE_LABEL}.plist`);
+}
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+export function renderWakePlist(nodePath, entryPath, pathEnv) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${WAKE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(nodePath)}</string>
+    <string>${xmlEscape(entryPath)}</string>
+    <string>__wake-check</string>
+  </array>
+  <key>StartInterval</key><integer>${WAKE_INTERVAL_SECONDS}</integer>
+  <key>RunAtLoad</key><true/>
+  <key>ProcessType</key><string>Background</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${xmlEscape(pathEnv)}</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+function defaultLaunchctl(args) {
+    execFileSync('launchctl', args, { stdio: 'ignore' });
+}
+function defaultWrite(path, contents) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, contents, { mode: 0o644 });
+    chmodSync(path, 0o644);
+}
+function defaultRead(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function installWakeAgent(deps = {}) {
+    if (process.env.CTRL_SPC_NO_WAKE_AGENT === '1')
+        return false;
+    if (process.platform !== 'darwin' && !deps.plistPath)
+        return false;
+    const plistPath = deps.plistPath ?? wakeAgentPlistPath();
+    const contents = renderWakePlist(deps.nodePath ?? process.execPath, deps.entryPath ?? CURRENT_ENTRY_PATH, deps.pathEnv ?? process.env.PATH ?? '/usr/bin:/bin');
+    if ((deps.read ?? defaultRead)(plistPath) === contents)
+        return true;
+    (deps.write ?? defaultWrite)(plistPath, contents);
+    const uid = deps.uid ?? process.getuid?.();
+    if (uid === undefined)
+        return true;
+    const launchctl = deps.launchctl ?? defaultLaunchctl;
+    try {
+        launchctl(['bootout', `gui/${uid}`, plistPath]);
+    }
+    catch {
+        // The job was not loaded yet.
+    }
+    try {
+        launchctl(['bootstrap', `gui/${uid}`, plistPath]);
+    }
+    catch (error) {
+        // Do not leave a byte-identical plist behind after a failed bootstrap:
+        // installWakeAgent intentionally skips launchctl for identical files, so
+        // keeping it would make every later retry report success without loading
+        // the job.
+        try {
+            ;
+            (deps.remove ?? rmSync)(plistPath);
+        }
+        catch {
+            // Preserve the launchctl error, which is the actionable failure.
+        }
+        throw error;
+    }
+    return true;
+}
+export function removeWakeAgent(deps = {}) {
+    if (process.platform !== 'darwin' && !deps.plistPath)
+        return false;
+    const plistPath = deps.plistPath ?? wakeAgentPlistPath();
+    if (!(deps.exists ?? existsSync)(plistPath))
+        return false;
+    const uid = deps.uid ?? process.getuid?.();
+    if (uid !== undefined) {
+        try {
+            ;
+            (deps.launchctl ?? defaultLaunchctl)(['bootout', `gui/${uid}`, plistPath]);
+        }
+        catch {
+            // An unloaded job is already stopped; the file still needs removal.
+        }
+    }
+    ;
+    (deps.remove ?? rmSync)(plistPath);
+    return true;
+}
+export async function stampMachineHeartbeat(client, machineId, brokerRunning) {
+    const now = new Date().toISOString();
+    const patch = { waker_seen_at: now };
+    if (brokerRunning)
+        patch.broker_seen_at = now;
+    const { error } = await client.from('machines').update(patch).eq('id', machineId);
+    if (error)
+        throw error;
+}
+function assertNoError(error) {
+    if (error)
+        throw error;
+}
+function supabaseWakeDb(client, machineId) {
+    const table = () => client.from('machine_wake_requests');
+    const freshCutoff = () => new Date(Date.now() - WAKE_REQUEST_FRESH_SECONDS * 1000).toISOString();
+    return {
+        stampHeartbeat: (brokerRunning) => stampMachineHeartbeat(client, machineId, brokerRunning),
+        async claimFreshPending() {
+            const { data, error } = await table()
+                .select('id')
+                .eq('machine_id', machineId)
+                .eq('status', 'pending')
+                .gte('requested_at', freshCutoff())
+                .order('requested_at', { ascending: false })
+                .limit(1)
+                .maybeSingle();
+            assertNoError(error);
+            return data ?? null;
+        },
+        async failStalePending() {
+            const { error } = await table().update({
+                status: 'failed',
+                error: 'Request expired before this machine checked in.',
+                updated_at: new Date().toISOString(),
+            })
+                .eq('machine_id', machineId)
+                .eq('status', 'pending')
+                .lt('requested_at', freshCutoff());
+            assertNoError(error);
+        },
+        async resolvePending(id) {
+            const { error } = await table()
+                .delete()
+                .eq('id', id)
+                .eq('machine_id', machineId)
+                .eq('status', 'pending');
+            assertNoError(error);
+        },
+        async failRequest(id, message) {
+            const { error } = await table()
+                .update({ status: 'failed', error: message, updated_at: new Date().toISOString() })
+                .eq('id', id);
+            assertNoError(error);
+        },
+        async cleanupFailed() {
+            const cutoff = new Date(Date.now() - FAILED_CLEANUP_MINUTES * 60 * 1000).toISOString();
+            const { error } = await table()
+                .delete()
+                .eq('machine_id', machineId)
+                .eq('status', 'failed')
+                .lt('updated_at', cutoff);
+            assertNoError(error);
+        },
+    };
+}
+async function defaultGetDb() {
+    const client = await getClient();
+    return supabaseWakeDb(client, getMachineIdentity().id);
+}
+async function defaultBrokerRunning() {
+    const statuses = await runtimeStatuses();
+    const machineId = getMachineIdentity().id;
+    return statuses.some((status) => status.running && status.health?.machine_id === machineId);
+}
+export async function wakeCheck(deps = {}) {
+    try {
+        if (await (deps.brokerRunning ?? defaultBrokerRunning)())
+            return 'broker_running';
+    }
+    catch {
+        // A failed probe is treated as not running so the poller can recover it.
+    }
+    let db;
+    try {
+        db = await (deps.getDb ?? defaultGetDb)();
+    }
+    catch {
+        return 'no_session';
+    }
+    try {
+        await db.stampHeartbeat(false);
+        await db.failStalePending();
+        const pending = await db.claimFreshPending();
+        if (!pending) {
+            await db.cleanupFailed();
+            return 'idle';
+        }
+        try {
+            await (deps.start ?? startRuntime)((deps.runtimeKind ?? currentCompanionKind)());
+            await db.resolvePending(pending.id);
+            await db.stampHeartbeat(true);
+            await db.cleanupFailed();
+            return 'started';
+        }
+        catch (error) {
+            await db.failRequest(pending.id, error instanceof Error ? error.message : String(error));
+            await db.cleanupFailed();
+            return 'start_failed';
+        }
+    }
+    catch {
+        return 'idle';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cli",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "CTRL+SPC CLI — per-machine agent for browser login, project linking, presence, and the local MCP server.",
   "engines": {
     "node": ">=22"