@ctrl-spc/cs 0.1.0 → 0.2.0

package/dist/companion.js

@@ -0,0 +1,374 @@
+import { createServer } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+import { COMPANION_PORT } from './env.js';
+import { openBrowser } from './browser.js';
+import { companionToken, getMachineIdentity, readSession, clearSession, readCodebasePaths, writeCodebasePath } from './config.js';
+import { getClient, signIn, NotLoggedIn } from './supabase.js';
+import { startPresence, stopPresence } from './presence.js';
+import { loadProjects, saveMapping } from './projects.js';
+import { listCodebases, addCodebase, reportLocated, removeCodebase, NotHostedRemoteError } from './codebases.js';
+import { hostedRemoteIdentity } from './git-remote.js';
+import { chooseFolder, detectGitRemote } from './folders.js';
+import { renderCompanionUi } from './companion-ui.js';
+const MAX_BODY_BYTES = 64 * 1024;
+const VERSION = '0.1.0';
+function url(token = companionToken()) {
+    return `http://127.0.0.1:${COMPANION_PORT}/?token=${encodeURIComponent(token)}`;
+}
+/** Confirms the process already holding the port is really our companion before
+ *  we hand it the token via the browser URL. */
+async function isOurCompanion(token) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${COMPANION_PORT}/api/session`, {
+            headers: { 'x-ctrl-spc-token': token },
+            signal: AbortSignal.timeout(1000),
+        });
+        if (!res.ok)
+            return false;
+        const body = (await res.json().catch(() => null));
+        return !!body && typeof body.machineName === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `cs open`: opens the Companion GUI. If a companion is already resident, just
+ * points the browser at it; otherwise becomes the resident server itself.
+ */
+export async function openCompanion() {
+    await serveCompanion({ open: true });
+}
+/**
+ * The resident companion server. Serves the GUI + a small local API on
+ * 127.0.0.1, and runs the presence loop whenever a session exists. `open`
+ * launches the browser once it's listening.
+ */
+export async function serveCompanion({ open = false } = {}) {
+    const token = companionToken();
+    const server = createServer((req, res) => {
+        void handle(req, res, token).catch((err) => {
+            if (!res.headersSent)
+                json(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        });
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(COMPANION_PORT, '127.0.0.1', resolve);
+        });
+    }
+    catch (err) {
+        if (err.code === 'EADDRINUSE') {
+            // Port is taken. Only treat it as our own resident companion (and hand it
+            // the token via the browser) once a health probe confirms it — otherwise
+            // some unrelated process holds the port and must not receive the token.
+            if (await isOurCompanion(token)) {
+                console.log(`Companion already running — ${url(token)}`);
+                if (open)
+                    openBrowser(url(token));
+            }
+            else {
+                console.error(`Port ${COMPANION_PORT} is in use by another process. ` +
+                    `Set CTRL_SPC_V2_COMPANION_PORT to a free port and try again.`);
+                process.exitCode = 1;
+            }
+            return;
+        }
+        throw err;
+    }
+    // Come online immediately if already signed in (terminal `cs login` or a
+    // prior GUI sign-in). Not signed in is fine — the GUI shows the sign-in screen.
+    if (readSession()) {
+        try {
+            await startPresence();
+        }
+        catch (err) {
+            if (!(err instanceof NotLoggedIn))
+                console.warn(`Presence did not start: ${err.message}`);
+        }
+    }
+    console.log(`Companion running — ${url(token)}`);
+    if (open)
+        openBrowser(url(token));
+    await new Promise((resolve) => {
+        let closing = false;
+        const shutdown = () => {
+            if (closing)
+                return;
+            closing = true;
+            void stopPresence({ markOffline: true }).finally(() => {
+                server.close(() => resolve());
+                process.exit(0);
+            });
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    });
+}
+// --- request handling --------------------------------------------------------
+/** Two legitimate Host values for a loopback service. Anything else is a
+ *  DNS-rebinding attempt from a page whose domain re-resolves to 127.0.0.1. */
+function allowedHost(host) {
+    return host === `127.0.0.1:${COMPANION_PORT}` || host === `localhost:${COMPANION_PORT}`;
+}
+function tokenMatches(given, token) {
+    if (typeof given !== 'string')
+        return false;
+    const a = Buffer.from(given);
+    const b = Buffer.from(token);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+function json(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify(body));
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new Error('Request too large.');
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new Error('Request contains invalid JSON.');
+    }
+    // Only a JSON object is a valid body; null/array/primitive would make the
+    // field reads below throw and leak a raw TypeError to the client.
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed
+        : {};
+}
+function str(value) {
+    return typeof value === 'string' ? value : '';
+}
+async function handle(req, res, token) {
+    if (!allowedHost(req.headers.host)) {
+        res.writeHead(421, { 'Content-Type': 'text/plain' }).end('Misdirected request.');
+        return;
+    }
+    const parsed = new URL(req.url ?? '/', `http://127.0.0.1:${COMPANION_PORT}`);
+    const path = parsed.pathname;
+    // The GUI page: token comes in the query (the tokenized URL `cs open` opens).
+    if (req.method === 'GET' && path === '/') {
+        if (!tokenMatches(parsed.searchParams.get('token') ?? undefined, token)) {
+            res.writeHead(403, { 'Content-Type': 'text/plain' }).end('Invalid companion session. Run `cs open`.');
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/html; charset=utf-8',
+            'Cache-Control': 'no-store',
+            'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; frame-ancestors 'none'",
+        });
+        res.end(renderCompanionUi(token));
+        return;
+    }
+    if (req.method === 'GET' && path === '/favicon.ico') {
+        res.writeHead(204).end();
+        return;
+    }
+    // Every API call echoes the token so other local pages can't drive us.
+    if (path.startsWith('/api/')) {
+        if (!tokenMatches(str(req.headers['x-ctrl-spc-token']) || undefined, token)) {
+            json(res, 403, { error: 'Invalid companion session.' });
+            return;
+        }
+        await handleApi(req, res, path, parsed.searchParams);
+        return;
+    }
+    res.writeHead(404, { 'Content-Type': 'text/plain' }).end('Not found');
+}
+async function handleApi(req, res, path, query) {
+    if (req.method === 'GET' && path === '/api/session') {
+        const machine = getMachineIdentity();
+        let email = null;
+        if (readSession()) {
+            try {
+                email = (await (await getClient()).auth.getUser()).data.user?.email ?? null;
+            }
+            catch { /* stale/expired session reads as signed out */ }
+        }
+        json(res, 200, {
+            signedIn: email !== null,
+            email,
+            machineName: machine.name,
+            platform: process.platform,
+            version: VERSION,
+        });
+        return;
+    }
+    if (req.method === 'POST' && path === '/api/login') {
+        const body = await readBody(req);
+        const email = str(body.email).trim();
+        const password = str(body.password);
+        if (!email || !password) {
+            json(res, 400, { ok: false, error: 'Enter your email and password.' });
+            return;
+        }
+        try {
+            const result = await signIn(email, password);
+            try {
+                await startPresence();
+            }
+            catch (err) {
+                console.warn(`Presence did not start after sign-in: ${err.message}`);
+            }
+            json(res, 200, { ok: true, email: result.email });
+        }
+        catch (err) {
+            json(res, 401, { ok: false, error: err.message || 'Sign-in failed.' });
+        }
+        return;
+    }
+    if (req.method === 'POST' && path === '/api/logout') {
+        await stopPresence({ markOffline: true });
+        clearSession();
+        json(res, 200, { ok: true });
+        return;
+    }
+    // Everything below needs a signed-in session.
+    let client;
+    try {
+        client = await getClient();
+    }
+    catch (err) {
+        if (err instanceof NotLoggedIn) {
+            json(res, 401, { error: 'Sign in to continue.' });
+            return;
+        }
+        throw err;
+    }
+    if (req.method === 'GET' && path === '/api/projects') {
+        json(res, 200, { projects: await loadProjects(client) });
+        return;
+    }
+    if (req.method === 'POST' && path === '/api/projects/choose-folder') {
+        const folder = await chooseFolder();
+        if (!folder) {
+            json(res, 200, { cancelled: true });
+            return;
+        }
+        const gitRemoteUrl = await detectGitRemote(folder);
+        // `codebaseRemote` is the canonical, path-free identity the folder can be
+        // added as (or null when its remote isn't a hosted repo). Additive field —
+        // the folder-map dialog ignores it and still reads `gitRemoteUrl` verbatim.
+        json(res, 200, {
+            localPath: folder,
+            gitRemoteUrl,
+            codebaseRemote: gitRemoteUrl ? hostedRemoteIdentity(gitRemoteUrl) : null,
+        });
+        return;
+    }
+    if (req.method === 'POST' && path === '/api/projects/map') {
+        const body = await readBody(req);
+        const projectId = str(body.projectId);
+        if (!projectId) {
+            json(res, 400, { error: 'A project is required.' });
+            return;
+        }
+        saveMapping(projectId, {
+            localPath: str(body.localPath).trim() || null,
+            gitRemoteUrl: str(body.gitRemoteUrl).trim() || null,
+        });
+        json(res, 200, { ok: true });
+        return;
+    }
+    if (req.method === 'GET' && path === '/api/projects/codebases') {
+        const projectId = query.get('projectId')?.trim();
+        if (!projectId) {
+            json(res, 400, { error: 'A project is required.' });
+            return;
+        }
+        // Merge each org-shared codebase with THIS machine's local folder, if any.
+        // `localPath` is a companion-only (localhost) field read from local config —
+        // it is never stored in the cloud and never leaves this loopback response.
+        const paths = readCodebasePaths();
+        const codebases = (await listCodebases(client, projectId)).map((c) => ({
+            ...c,
+            localPath: paths[c.gitRemoteUrl] ?? null,
+        }));
+        json(res, 200, { codebases });
+        return;
+    }
+    if (req.method === 'POST' && path === '/api/projects/locate-codebase') {
+        const body = await readBody(req);
+        const codebaseRemote = str(body.codebaseRemote).trim();
+        const localPath = str(body.localPath).trim();
+        if (!codebaseRemote || !localPath) {
+            json(res, 400, { error: 'A codebase and a folder are required to locate.' });
+            return;
+        }
+        // Re-detect + re-canonicalize the folder's remote SERVER-SIDE. The client's
+        // "matches" pill is only UX; this is the real guard that the picked folder
+        // genuinely is this codebase before its availability is recorded.
+        const raw = await detectGitRemote(localPath);
+        const detected = raw ? hostedRemoteIdentity(raw) : null;
+        if (!detected) {
+            json(res, 400, { error: "This folder has no git remote, so it can't be this codebase." });
+            return;
+        }
+        if (detected !== codebaseRemote) {
+            json(res, 400, { error: 'This folder is a different repo (' + detected + '), not ' + codebaseRemote + '.' });
+            return;
+        }
+        // Report path-free availability to the cloud FIRST (identity + this machine's
+        // id — never the path), and only persist the local path AFTER it resolves. If
+        // the cloud write throws (expired token / network / RLS), both stay unset —
+        // consistently "not located" — rather than the companion showing "On this
+        // computer" while the web shows "not on any of your computers". Persist the
+        // SERVER-re-detected identity (proven equal to codebaseRemote by the guard
+        // above), so only the server-validated value is ever written.
+        await reportLocated(client, getMachineIdentity().id, detected);
+        writeCodebasePath(detected, localPath);
+        json(res, 200, { ok: true });
+        return;
+    }
+    if (req.method === 'POST' && path === '/api/projects/remove-codebase') {
+        const body = await readBody(req);
+        const codebaseId = str(body.codebaseId).trim();
+        if (!codebaseId) {
+            json(res, 400, { error: 'A codebase is required to remove.' });
+            return;
+        }
+        // Deletes only the org-shared codebase row. Per-machine availability and the
+        // local folder mapping are intentionally left intact (see removeCodebase).
+        await removeCodebase(client, codebaseId);
+        json(res, 200, { ok: true });
+        return;
+    }
+    if (req.method === 'POST' && path === '/api/projects/add-codebase') {
+        const body = await readBody(req);
+        const projectId = str(body.projectId).trim();
+        const gitRemoteUrl = str(body.gitRemoteUrl).trim();
+        if (!projectId) {
+            json(res, 400, { error: 'A project is required.' });
+            return;
+        }
+        if (!gitRemoteUrl) {
+            json(res, 400, { error: 'A git remote is required to add a codebase.' });
+            return;
+        }
+        try {
+            const { added } = await addCodebase(client, projectId, gitRemoteUrl);
+            json(res, 200, { ok: true, added });
+        }
+        catch (err) {
+            // A non-hosted remote is a user-visible refusal (400), not a server error.
+            if (err instanceof NotHostedRemoteError) {
+                json(res, 400, { error: err.message });
+                return;
+            }
+            throw err;
+        }
+        return;
+    }
+    json(res, 404, { error: 'Not found.' });
+}

package/dist/config.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
-import { homedir, hostname } from 'node:os';
-import { randomUUID } from 'node:crypto';
+import { homedir, hostname, platform } from 'node:os';
+import { randomBytes, createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
 import { join } from 'node:path';
 /** Own config dir, isolated from the v1 CLI: `~/.config/ctrl-spc-v2`. */
 export function configDir() {
@@ -18,21 +19,108 @@ function writeJson(name, value) {
 export function machineHostname() {
     return hostname().replace(/\.local$/i, '') || 'This machine';
 }
-/** Stable per-machine identity, created once and reused. */
+/** Raw stable hardware/OS-install id for this physical machine, or null when the
+ *  platform lookup fails. Stable across CLI reinstalls, corrupt config, and
+ *  distinct config dirs — so the same box resolves to one presence row.
+ *
+ *  Binaries are invoked by ABSOLUTE path on purpose: launchd (macOS autostart)
+ *  and other minimal-PATH contexts don't include /usr/sbin (ioreg) or rely on
+ *  %PATH% for reg.exe, so a bare command would throw and the machine would fail
+ *  to identify itself. */
+function hardwareId() {
+    try {
+        if (platform() === 'darwin') {
+            const out = execSync('/usr/sbin/ioreg -rd1 -c IOPlatformExpertDevice', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+            return out.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/)?.[1] ?? null;
+        }
+        if (platform() === 'win32') {
+            const reg = `${process.env.SystemRoot || 'C:\\Windows'}\\System32\\reg.exe`;
+            const out = execSync(`"${reg}" query "HKLM\\SOFTWARE\\Microsoft\\Cryptography" /v MachineGuid`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+            return out.match(/MachineGuid\s+REG_SZ\s+([\w-]+)/i)?.[1]?.trim() ?? null;
+        }
+        // linux and the rest: the systemd/D-Bus machine id (already absolute paths)
+        for (const p of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
+            if (existsSync(p)) {
+                const v = readFileSync(p, 'utf8').trim();
+                if (v)
+                    return v;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** This machine's presence id: hashed hardware id, or an explicit
+ *  `CTRL_SPC_V2_MACHINE_ID` override for the deliberate two-instances-on-one-box
+ *  dev workflow.
+ *
+ *  There is NO random fallback, by design. A random id would mint a phantom
+ *  machine — a fresh second row — every time the hardware lookup failed (e.g. a
+ *  wrong PATH). If the hardware id genuinely can't be read we throw rather than
+ *  invent an identity; the caller surfaces the failure instead of duplicating. */
+function computeMachineId() {
+    const override = process.env.CTRL_SPC_V2_MACHINE_ID;
+    if (override)
+        return override;
+    const hw = hardwareId();
+    if (!hw)
+        throw new Error('Could not read this machine\'s hardware id (IOPlatformUUID / MachineGuid / machine-id). Refusing to invent a random id.');
+    return createHash('sha256').update(hw).digest('hex');
+}
+/** Stable per-machine identity. Re-derived each call so a machine that upgrades
+ *  from a random id to a hardware id migrates cleanly; the superseded id is
+ *  recorded for [[presence]] to delete its now-orphaned cloud row. */
 export function getMachineIdentity() {
     const path = filePath('machine.json');
+    let stored = {};
     if (existsSync(path)) {
         try {
-            const s = JSON.parse(readFileSync(path, 'utf8'));
-            if (typeof s.id === 'string' && s.id && typeof s.name === 'string' && s.name) {
-                return { id: s.id, name: s.name };
-            }
+            stored = JSON.parse(readFileSync(path, 'utf8'));
         }
         catch { /* corrupt → recreate */ }
     }
-    const identity = { id: randomUUID(), name: machineHostname() };
-    writeJson('machine.json', identity);
-    return identity;
+    const prevId = typeof stored.id === 'string' && stored.id ? stored.id : undefined;
+    const id = computeMachineId();
+    const name = machineHostname();
+    const superseded = (Array.isArray(stored.supersededIds) ? stored.supersededIds : [])
+        .filter((x) => typeof x === 'string');
+    const changed = prevId !== id || stored.name !== name;
+    if (prevId && prevId !== id && !superseded.includes(prevId))
+        superseded.push(prevId);
+    if (changed) {
+        writeJson('machine.json', superseded.length ? { id, name, supersededIds: superseded } : { id, name });
+    }
+    return { id, name };
+}
+/** Old machine ids this install has migrated off of (random → hardware, or an
+ *  override change). The presence heartbeat deletes these orphaned cloud rows,
+ *  then clears the list via [[clearSupersededMachineIds]]. */
+export function supersededMachineIds() {
+    const path = filePath('machine.json');
+    if (!existsSync(path))
+        return [];
+    try {
+        const s = JSON.parse(readFileSync(path, 'utf8'));
+        return (Array.isArray(s.supersededIds) ? s.supersededIds : []).filter((x) => typeof x === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+/** Clear the superseded-id list once the orphaned rows are deleted. Left intact
+ *  on failure so the next heartbeat retries the cleanup. */
+export function clearSupersededMachineIds() {
+    const path = filePath('machine.json');
+    if (!existsSync(path))
+        return;
+    try {
+        const s = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof s.id === 'string' && typeof s.name === 'string')
+            writeJson('machine.json', { id: s.id, name: s.name });
+    }
+    catch { /* leave as-is */ }
 }
 export function readSession() {
     const path = filePath('session.json');
@@ -55,3 +143,74 @@ export function clearSession() {
     rmSync(path);
     return true;
 }
+/** This machine's project mappings, stored locally (not in the cloud) so
+ *  absolute paths never leave the machine. Keyed by project id. */
+export function readMappings() {
+    const path = filePath('mappings.json');
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function writeMapping(projectId, mapping) {
+    const all = readMappings();
+    all[projectId] = mapping;
+    writeJson('mappings.json', all);
+}
+/** Per-codebase local folder on THIS machine, keyed by the codebase's canonical
+ *  `host/path` identity. Stored strictly locally (never in the cloud) for the
+ *  same reason as [[readMappings]]: absolute paths must never leave the machine
+ *  (path-privacy invariant). Only the path-free identity + machine_id are ever
+ *  reported to a `cliv2_*` table; this file is what stays behind. */
+export function readCodebasePaths() {
+    const path = filePath('codebase-paths.json');
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object')
+            return {};
+        // Keep only string values — a corrupt/hand-edited file shouldn't crash reads.
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v === 'string')
+                out[k] = v;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+export function writeCodebasePath(identity, localPath) {
+    const all = readCodebasePaths();
+    all[identity] = localPath;
+    writeJson('codebase-paths.json', all);
+}
+/**
+ * Stable per-install companion API token, created once (0600). The companion
+ * page is served with this token and echoes it back on every API call, so other
+ * local browser pages — which can't read this file — can't drive the companion.
+ * On disk (not per-process) so `cs open` and the resident server agree on it.
+ */
+export function companionToken() {
+    const path = filePath('companion-token');
+    if (existsSync(path)) {
+        try {
+            const token = readFileSync(path, 'utf8').trim();
+            if (token)
+                return token;
+        }
+        catch { /* corrupt → recreate */ }
+    }
+    const token = randomBytes(24).toString('hex');
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(path, token, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return token;
+}

package/dist/daemon.js

@@ -1,94 +1,27 @@
-import { getClient } from './supabase.js';
-import { getMachineIdentity } from './config.js';
 import { ensureAutostart } from './autostart.js';
-import { detectAgents } from './agents.js';
-import { HEARTBEAT_INTERVAL_MS, COMMAND_POLL_INTERVAL_MS } from './env.js';
+import { startPresence, stopPresence } from './presence.js';
 /**
- * The resident process. Two dumb PostgREST loops — no Realtime, no sockets:
- *  - heartbeat: upsert this machine's presence row every ~10s.
- *  - poll: ack any pending ping commands aimed at this machine.
- *
- * Reliability comes from the same stack as the reliable v1 prototype: an
- * auto-refreshing token (supabase.ts), a TypeError-retrying fetch, and
- * rebuild-on-error here. Under launchd/KeepAlive (autostart), a hard crash is
- * restarted by the OS. Nothing here throws on a transient failure.
+ * The terminal presence daemon (`cs start`). Comes online and heartbeats until
+ * the process is signalled. Under launchd/KeepAlive (autostart) a hard crash is
+ * restarted by the OS. The companion server (`cs open`) shares the same presence
+ * loop via presence.ts, so the two front-ends never diverge.
  */
 export async function runDaemon() {
-    const identity = getMachineIdentity();
-    const agents = detectAgents();
     ensureAutostart(); // default-on: install the login item unless the user opted out
-    console.log(`CTRL+SPC — this computer: ${identity.name}`);
+    const { machineName, agents } = await startPresence();
+    console.log(`CTRL+SPC — this computer: ${machineName}`);
     console.log(`Agents detected: ${agents.length ? agents.join(', ') : 'none'}`);
-    let client = await getClient();
-    const { data: userData } = await client.auth.getUser();
-    const userId = userData.user?.id;
-    if (!userId)
-        throw new Error('Signed-in user could not be resolved. Run `cs login` again.');
-    let running = true;
-    async function heartbeat() {
-        try {
-            const { error } = await client
-                .from('cliv2_agents')
-                .upsert({
-                user_id: userId,
-                machine_id: identity.id,
-                machine_name: identity.name,
-                agents,
-                last_seen_at: new Date().toISOString(),
-            }, { onConflict: 'user_id,machine_id' });
-            if (error)
-                throw error;
-        }
-        catch (err) {
-            // Most likely a rotated/expired session or a network blip. Rebuild the
-            // client from disk (picks up any refreshed token) and try next tick.
-            console.warn(`heartbeat failed, will retry: ${err.message}`);
-            try {
-                client = await getClient();
-            }
-            catch { /* stay down until the next tick */ }
-        }
-    }
-    async function pollCommands() {
-        try {
-            const { data, error } = await client
-                .from('cliv2_commands')
-                .update({ status: 'ack', acked_at: new Date().toISOString() })
-                .eq('machine_id', identity.id)
-                .eq('status', 'pending')
-                .select('id, command');
-            if (error)
-                throw error;
-            for (const cmd of data ?? [])
-                console.log(`Acked ${cmd.command} (${cmd.id})`);
-        }
-        catch (err) {
-            console.warn(`command poll failed, will retry: ${err.message}`);
-        }
-    }
-    await heartbeat();
-    const hb = setInterval(() => void heartbeat(), HEARTBEAT_INTERVAL_MS);
-    const cp = setInterval(() => void pollCommands(), COMMAND_POLL_INTERVAL_MS);
+    console.log('Online. Heartbeating presence. Ctrl-C to stop.');
+    let stopping = false;
     async function shutdown() {
-        if (!running)
+        if (stopping)
             return;
-        running = false;
-        clearInterval(hb);
-        clearInterval(cp);
-        // Best-effort: mark offline immediately so the web sheet doesn't wait out
-        // the freshness window. A stale timestamp reads as offline.
-        try {
-            await client
-                .from('cliv2_agents')
-                .update({ last_seen_at: new Date(0).toISOString() })
-                .eq('machine_id', identity.id);
-        }
-        catch { /* ignore */ }
+        stopping = true;
+        await stopPresence({ markOffline: true });
         process.exit(0);
     }
     process.on('SIGINT', () => void shutdown());
     process.on('SIGTERM', () => void shutdown());
-    console.log('Online. Heartbeating presence. Ctrl-C to stop.');
     // Keep the event loop alive.
     await new Promise(() => { });
 }