@ctrl-spc/cs 0.7.13 → 0.7.15

package/README.md

@@ -7,10 +7,11 @@ signing in and attaching your codebases to your projects.
 ## Install
 
 ```sh
-npm i -g @ctrl-spc/cs && cs
+npm i -g @ctrl-spc/cs
+cs
 ```
 
-That's it. The `&& cs` opens your browser straight to sign-in — you barely touch
+Running `cs` opens your browser straight to sign-in — you barely touch
 the terminal:
 
 ```
@@ -43,7 +44,11 @@ cs                Open the Companion app (the front door)
 cs open           Open the Companion app in your browser
 cs login          Sign in from the terminal and link this computer
 cs start          Come online now, no window (used by auto-start)
-cs status         Show the whole setup state and the one next step to take
+cs status         Inspect this service, its running version and cloud connection
+cs stop           Stop this service when no owned work is active
+cs restart        Load the installed CLI and keep it running in the background
+cs stop --force   Interrupt owned work, preserve recovery, then stop
+cs restart --force Interrupt owned work, then load the installed CLI
 cs autostart on   Come online automatically at login
 cs autostart off  Stop coming online at login
 cs logout         Sign this computer out
@@ -53,5 +58,47 @@ cs help           Show this help
 ## Requirements
 
 - Node.js >= 22.
+- Service stop and restart support macOS and Windows.
+
+## Updating and restarting
+
+Installing a package does not replace a service already running in memory. On
+the computer you want to update, run:
+
+```sh
+npm install -g @ctrl-spc/cs
+cs restart
+cs status
+```
+
+`cs status` separates the version of the installed command from the verified
+version running in the service. A successful restart stays running after the
+terminal closes. `cs stop` leaves the computer's next-login startup preference
+unchanged; `cs autostart off` changes that future preference.
+
+A normal stop or restart refuses while an assignment is active. Let the work
+finish, or explicitly use `--force` to interrupt the owned assignments. Saved
+files and conversations remain; open each interrupted card and send a new
+message to continue. Restarting the service does not automatically replay work.
+
+Local service controls remain available without a cloud connection or usable
+sign-in. Cloud readiness is reported separately. An offline interruption appears
+in the app after the service can reconnect and reconcile it.
+
+### One-time upgrade from an older service
+
+A service installed before these lifecycle controls cannot prove which work is
+still running. The new command prepares the future-login launcher and explains
+when a one-time **computer restart** is required. Save your work, restart that
+computer, then run `cs status` after signing in. If automatic startup is off, run
+`cs start` first. Interrupted work needs an explicit new message to continue.
+
+Later service stop and restart do not need a computer restart. If ownership or
+execution cannot be verified, the command reports that problem and does not
+start a second service.
+
+The app's **Restart worker** control reconnects work processing inside the
+current service. Activating an installed CLI update uses `cs restart` in a
+terminal on the named computer.
 
 Not sure what a piece does? Open the Companion (`cs`) and click **How it works**.

package/dist/autostart.js

@@ -1,141 +1,122 @@
-import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import { configDir } from './config.js';
-const LABEL = 'com.ctrl-spc.presence';
-/** Set once the user runs `cs autostart off`, so default-on never re-enables it. */
-function offMarkerPath() {
-    return join(configDir(), 'autostart-off');
-}
-/** True if the login item is currently installed for this OS. */
-export function autostartEnabled() {
-    if (process.platform === 'darwin')
-        return existsSync(plistPath());
-    if (process.platform === 'win32')
-        return existsSync(startupVbsPath());
-    return false;
+const BASE_LABEL = 'com.ctrl-spc.presence';
+const execute = promisify(execFile);
+/** Capture a loaded job only while its PID is the verified service owner. */
+export async function loadedStartupJob(pid, deadline) {
+    if (process.platform !== 'darwin')
+        return null;
+    const target = 'gui/' + process.getuid() + '/' + startupLabel();
+    try {
+        const { stdout } = await execute('/bin/launchctl', ['print', target], { timeout: Math.max(1, Math.min(2000, deadline - Date.now())) });
+        const match = stdout.match(/^\s*pid = (\d+)\s*$/m);
+        return match && Number(match[1]) === pid ? target : null;
+    }
+    catch (error) {
+        if (error.code === 113)
+            return null;
+        throw new Error('The login service could not be inspected. No replacement was started.', { cause: error });
+    }
 }
-/**
- * Default-on: install the login item the first time we come online, unless the
- * user explicitly opted out. Idempotent and best-effort — already-enabled is a
- * no-op (so the launchd/VBS-spawned `cs start` doesn't re-install itself), and
- * an unsupported platform or transient error never breaks coming online.
- */
-export function ensureAutostart() {
-    if (existsSync(offMarkerPath()) || autostartEnabled())
+/** Work has already drained. Unload the current job, retaining its next-login file. */
+export async function unloadStoppedStartupJob(target, deadline) {
+    if (!target)
         return;
     try {
-        autostartOn();
+        await execute('/bin/launchctl', ['bootout', target], { timeout: Math.max(1, deadline - Date.now()) });
+    }
+    catch (error) {
+        if (error.code !== 113)
+            throw new Error('The previous login service could not be unloaded. No replacement was started.', { cause: error });
     }
-    catch { /* unsupported platform or transient failure — ignore */ }
-}
-function plistPath() {
-    return join(homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
 }
-/** Absolute path to this package's built entry (dist/index.js). */
-function entryPath() {
-    return join(dirname(fileURLToPath(import.meta.url)), 'index.js');
+function offMarkerPath() { return join(configDir(), 'autostart-off'); }
+export function startupLabel() {
+    if (resolve(configDir()) === resolve(join(homedir(), '.config', 'ctrl-spc-v2')) && !process.env.CTRL_SPC_V2_MACHINE_ID)
+        return BASE_LABEL;
+    return BASE_LABEL + '.' + createHash('sha256').update(resolve(configDir()) + '\0' + (process.env.CTRL_SPC_V2_MACHINE_ID ?? '')).digest('hex').slice(0, 12);
 }
-/** Comes online automatically at login. Backend per OS. */
-export function autostartOn() {
-    if (existsSync(offMarkerPath()))
-        rmSync(offMarkerPath());
+export function entryPath() { return join(dirname(fileURLToPath(import.meta.url)), 'index.js'); }
+export function startupPath() {
     if (process.platform === 'darwin')
-        return macOn();
-    if (process.platform === 'win32')
-        return winOn();
-    throw new Error('Auto-start supports macOS and Windows only.');
+        return join(homedir(), 'Library', 'LaunchAgents', startupLabel() + '.plist');
+    const appData = process.env.APPDATA || join(homedir(), 'AppData', 'Roaming');
+    const stem = startupLabel() === BASE_LABEL ? 'ctrl-spc-presence' : startupLabel();
+    return join(appData, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup', stem + '.vbs');
 }
-/** Stops coming online at login, and pins it off so default-on won't re-enable. */
-export function autostartOff() {
-    mkdirSync(configDir(), { recursive: true });
-    writeFileSync(offMarkerPath(), '');
-    if (process.platform === 'darwin')
-        return macOff();
-    if (process.platform === 'win32')
-        return winOff();
-    throw new Error('Auto-start supports macOS and Windows only.');
+export function autostartEnabled() {
+    return !existsSync(offMarkerPath()) && ['darwin', 'win32'].includes(process.platform) && existsSync(startupPath());
 }
-// --- Windows: hidden VBS shim in the user's Startup folder --------------------
-// Runs `cs start` at login with no console window (WScript window style 0).
-// ponytail: no crash-restart supervision like launchd's KeepAlive — a plain
-// login shim. Upgrade to a Scheduled Task with restart settings if the daemon
-// crashing between logins ever matters.
-function startupVbsPath() {
-    const appData = process.env.APPDATA || join(homedir(), 'AppData', 'Roaming');
-    return join(appData, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup', 'ctrl-spc-presence.vbs');
+export function autostartDisabled() { return existsSync(offMarkerPath()); }
+function escapeXml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
-function winOn() {
-    const path = startupVbsPath();
-    mkdirSync(dirname(path), { recursive: true });
-    // Doubled quotes escape quotes inside a VBS string literal, so the Run target
-    // becomes: "<node>" "<dist/index.js>" start
-    const command = `"${process.execPath}" "${entryPath()}" start`.replace(/"/g, '""');
-    writeFileSync(path, `Set s = CreateObject("WScript.Shell")\r\ns.Run "${command}", 0, False\r\n`);
-    console.log('Auto-start enabled. CTRL+SPC comes online at login. Disable: cs autostart off');
+function instanceEnvironment() {
+    const env = { PATH: process.env.PATH ?? '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin', HOME: homedir(), USER: process.env.USER ?? process.env.USERNAME ?? '' };
+    for (const key of ['CTRL_SPC_V2_CONFIG_DIR', 'CTRL_SPC_V2_MACHINE_ID', 'CTRL_SPC_V2_COMPANION_PORT', 'CTRL_SPC_V2_TOOLS_PORT', 'CTRL_SPC_SUPABASE_URL', 'CTRL_SPC_SUPABASE_KEY', 'CTRL_SPC_V3_AGENT', 'CTRL_SPC_V2_MAX_CONCURRENT', 'CTRL_SPC_WEB_URL', 'CODEX_HOME', 'CLAUDE_CONFIG_DIR']) {
+        if (process.env[key])
+            env[key] = process.env[key];
+    }
+    return env;
 }
-function winOff() {
-    const path = startupVbsPath();
-    if (existsSync(path))
-        rmSync(path);
-    console.log('Auto-start disabled.');
+function launcherContents() {
+    if (process.platform === 'win32') {
+        const quoted = (value) => value.replace(/"/g, '""');
+        const command = '"' + process.execPath + '" "' + entryPath() + '" start';
+        const env = Object.entries(instanceEnvironment()).map(([key, value]) => 's.Environment("PROCESS")("' + quoted(key) + '") = "' + quoted(value) + '"').join('\r\n');
+        return 'Set s = CreateObject("WScript.Shell")\r\n' + env + '\r\ns.Run "' + quoted(command) + '", 0, False\r\n';
+    }
+    const env = Object.entries(instanceEnvironment()).map(([key, value]) => '<key>' + escapeXml(key) + '</key><string>' + escapeXml(value) + '</string>').join('');
+    return '<?xml version="1.0" encoding="UTF-8"?>\n<plist version="1.0"><dict>' +
+        '<key>Label</key><string>' + startupLabel() + '</string>' +
+        '<key>ProgramArguments</key><array><string>' + escapeXml(process.execPath) + '</string><string>' + escapeXml(entryPath()) + '</string><string>start</string></array>' +
+        '<key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>' +
+        '<key>StandardOutPath</key><string>' + escapeXml(join(configDir(), 'daemon.log')) + '</string>' +
+        '<key>StandardErrorPath</key><string>' + escapeXml(join(configDir(), 'daemon.log')) + '</string>' +
+        '<key>EnvironmentVariables</key><dict>' + env + '</dict></dict></plist>\n';
 }
-// --- macOS: launchd LaunchAgent ----------------------------------------------
-/** Installs a LaunchAgent that comes online at login, KeepAlive-supervised. */
-function macOn() {
-    const uid = process.getuid?.() ?? 0;
-    const node = process.execPath;
-    const entry = entryPath();
-    /* ═══ `USER` IS LOAD-BEARING, AND ITS ABSENCE IS SILENT. ═══
-       launchd starts an agent with almost no environment: PATH was set here
-       because the daemon could not otherwise FIND `claude`, and `USER` is the
-       same class of bug one layer down. The agents the daemon spawns inherit
-       `process.env`, and the Claude Code CLI resolves its stored credential by
-       the current user's name — with `USER` unset it reports "Not logged in ·
-       Please run /login" while the very same binary, run from a shell one second
-       earlier, authenticates fine.
-       THE COST OF MISSING IT: every claude-designated request fails with "Claude
-       is not signed in on this machine", which reads as an expired token and
-       sends you to re-authenticate something that was never broken. Reproduced
-       by hand: `env -i HOME=… PATH=… claude -p` fails, and adding USER alone
-       fixes it. HOME is set for the same reason, though launchd does supply it. */
-    const userName = process.env.USER ?? process.env.LOGNAME ?? '';
-    const logDir = join(homedir(), '.config', 'ctrl-spc-v2');
-    mkdirSync(logDir, { recursive: true });
-    mkdirSync(dirname(plistPath()), { recursive: true });
-    const plist = `<?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>${LABEL}</string>
-  <key>ProgramArguments</key><array>
-    <string>${node}</string><string>${entry}</string><string>start</string>
-  </array>
-  <key>RunAtLoad</key><true/>
-  <key>KeepAlive</key><true/>
-  <key>StandardOutPath</key><string>${join(logDir, 'daemon.log')}</string>
-  <key>StandardErrorPath</key><string>${join(logDir, 'daemon.log')}</string>
-  <key>EnvironmentVariables</key><dict><key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string><key>USER</key><string>${userName}</string><key>HOME</key><string>${homedir()}</string></dict>
-</dict></plist>
-`;
-    writeFileSync(plistPath(), plist);
+/** Writes future-login configuration only. The lifecycle controller owns launch. */
+export function prepareAutostart({ defaultOn = false } = {}) {
+    if (autostartDisabled())
+        return;
+    if (!['darwin', 'win32'].includes(process.platform)) {
+        if (defaultOn)
+            return; // Existing CLI permits manually launched Linux instances.
+        throw new Error('Automatic login startup supports macOS and Windows.');
+    }
+    if (!defaultOn && !autostartEnabled())
+        return;
+    mkdirSync(configDir(), { recursive: true });
+    const path = startupPath();
+    mkdirSync(dirname(path), { recursive: true });
+    const text = launcherContents();
+    const temp = path + '.' + randomUUID() + '.tmp';
     try {
-        execFileSync('launchctl', ['bootout', `gui/${uid}`, plistPath()], { stdio: 'ignore' });
+        writeFileSync(temp, text, { mode: 0o600 });
+        renameSync(temp, path);
     }
-    catch { /* not loaded yet — fine */ }
-    execFileSync('launchctl', ['bootstrap', `gui/${uid}`, plistPath()]);
-    console.log('Auto-start enabled. CTRL+SPC comes online at login. Disable: cs autostart off');
-}
-/** Removes the LaunchAgent. */
-function macOff() {
-    const uid = process.getuid?.() ?? 0;
-    if (existsSync(plistPath())) {
-        try {
-            execFileSync('launchctl', ['bootout', `gui/${uid}`, plistPath()], { stdio: 'ignore' });
-        }
-        catch { /* already out */ }
-        rmSync(plistPath());
+    finally {
+        rmSync(temp, { force: true });
     }
-    console.log('Auto-start disabled.');
+    if (readFileSync(path, 'utf8') !== text)
+        throw new Error('The future-login launcher could not be verified. Retry before restarting this computer.');
+}
+export function ensureAutostart() { prepareAutostart({ defaultOn: true }); }
+export function autostartOn() {
+    rmSync(offMarkerPath(), { force: true });
+    prepareAutostart({ defaultOn: true });
+    console.log('Auto-start enabled for the next login. Start now: cs start');
+}
+export function autostartOff() {
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(offMarkerPath(), '', { mode: 0o600 });
+    if (['darwin', 'win32'].includes(process.platform))
+        rmSync(startupPath(), { force: true });
+    console.log('Auto-start disabled for future logins. Stop this service: cs stop');
 }

package/dist/companion-ui.js

@@ -286,9 +286,27 @@ async function api(path, opts) {
 }
 
 async function boot() {
-  const r = await api('/api/session');
-  if (r.data && r.data.signedIn) renderHome(r.data);
-  else renderSignIn(r.data || {});
+  try {
+    const r = await api('/api/session');
+    if (!r.ok || r.data.signedIn === null) {
+      renderSessionUnavailable(r.data.sessionError || r.data.error);
+    } else if (r.data.signedIn) renderHome(r.data);
+    else renderSignIn(r.data || {});
+  } catch (_) { renderSessionUnavailable(); }
+}
+
+function renderSessionUnavailable(message) {
+  stopBadgePoll();
+  app.replaceChildren();
+  const wrap = el('div', 'auth');
+  const card = el('div', 'auth-card');
+  card.append(logo(), el('h1', 'auth-title', 'Connection unavailable'));
+  card.append(el('p', 'auth-sub', message || 'Sign-in could not be checked. Check your connection and try again.'));
+  const retry = el('button', 'btn btn-primary', 'Try again');
+  retry.addEventListener('click', boot);
+  card.append(retry);
+  wrap.append(card);
+  app.append(wrap);
 }
 
 /** The passive "Agent tools" badge (feature 05). Read-only: no button, no
@@ -308,6 +326,9 @@ function agentToolsBadge(state) {
   if (reason === 'connected') {
     title = 'Agent tools: connected \\u2713';
     sub = (state.agent || 'Claude') + ' \\u00b7 ' + (state.server || 'ctrl-spc');
+  } else if (reason === 'unavailable') {
+    title = 'Connection unavailable';
+    sub = state.message || 'Sign-in could not be checked. Retrying.';
   } else if (reason === 'connecting') {
     title = 'Agent tools: connecting\\u2026';
     sub = state.agent || '';
@@ -348,13 +369,20 @@ async function pollBadgeOnce() {
     const r = await api('/api/session');
     // Home may have been torn down while the fetch was in flight.
     if (!badge.isConnected) return;
-    if (!(r.data && r.data.signedIn)) { stopBadgePoll(); return; }
-    const fresh = agentToolsBadge(r.data.agentTools);
+    if (r.ok && r.data.signedIn === false) { renderSignIn(r.data); return; }
+    const fresh = agentToolsBadge(!r.ok || r.data.signedIn === null
+      ? { reason: 'unavailable', message: r.data.sessionError }
+      : r.data.agentTools);
     fresh.id = 'agent-tools';
     fresh.style.marginBottom = 'var(--sp-5)';
     badge.replaceWith(fresh);
   } catch (e) {
-    /* transient — try again next tick */
+    if (badge.isConnected) {
+      const fresh = agentToolsBadge({ reason: 'unavailable' });
+      fresh.id = 'agent-tools';
+      fresh.style.marginBottom = 'var(--sp-5)';
+      badge.replaceWith(fresh);
+    }
   } finally {
     badgePolling = false;
   }