@ctrl-spc/cs 0.6.0 → 0.7.0

package/dist/presence.js

@@ -1,10 +1,13 @@
 import { platform } from 'node:os';
 import { getClient } from './supabase.js';
-import { getMachineIdentity, supersededMachineIds, clearSupersededMachineIds } from './config.js';
+import { getMachineIdentity, mcpToken, supersededMachineIds, clearSupersededMachineIds } from './config.js';
 import { detectAgents } from './agents.js';
 import { startToolsServer, stopToolsServer, toolsServerStatus, registerWithClaude, registerWithCodex, unregisterFromClaude, unregisterFromCodex, agentRegStatus, heartbeatOpenSessions, setToolsClient, } from './mcp.js';
-import { HEARTBEAT_INTERVAL_MS, COMMAND_POLL_INTERVAL_MS } from './env.js';
+import { HEARTBEAT_INTERVAL_MS, COMMAND_POLL_INTERVAL_MS, ORCHESTRATOR_POLL_INTERVAL_MS } from './env.js';
 import { buildPresenceHeartbeatPayload } from './presence-heartbeat.js';
+import { createListenerState, orchestratorTick, reapDeadWorkers, recoverStrandedWorkers, takeRunMessages, liveAgents, } from './orchestrator.js';
+/* 18c Slice 8 — the on-disk half of the crash recovery beside it. */
+import { sweepStrandedCodexHomes } from './codex-home.js';
 let presence = null;
 /** In-flight guard: startPresence yields to the event loop (network setSession)
  *  before `presence` is assigned, so a plain `if (presence)` check lets two
@@ -39,6 +42,41 @@ async function heartbeat(p) {
             // heartbeat 401ing forever (the CLI-v1 stale-token root cause). No-op unless
             // the tools server is running.
             setToolsClient(p.client);
+            /* ═══ !Cleanup PHASE 0 (I1) — RE-RESOLVE WHO WE ARE, NOT JUST THE TOKEN.
+               THE WEDGE THIS FIXES, read off this machine's own 6.1 MB log: an
+               unbroken wall of
+      
+                 heartbeat failed, will retry: new row violates row-level security
+                 policy for table "cliv2_agents"
+      
+               and presence stayed dead until the daemon was killed by hand.
+      
+               `p.userId` is resolved ONCE, at startPresence, and the payload sends it
+               EXPLICITLY while the table's policy is `with check (auth.uid() =
+               user_id)`. The recovery above rebuilt the CLIENT from disk but left
+               `p.userId` alone — so the moment `session.json` came to hold a different
+               account (a second install on this box signing in; a demo lane; a
+               re-login as someone else), every heartbeat sent one user's id under
+               another user's token and the database correctly refused it. Rebuilding
+               the client changed nothing, because the disk session was not the stale
+               half. It could never recover on its own: the retry re-sent the same
+               disagreement, several times a minute, forever.
+      
+               Evidence it really happened here rather than in theory: `cliv2_agents`
+               holds TWO rows for this machine_id under two different user_ids, one of
+               them stuck at the epoch.
+      
+               THE TOKEN IS THE AUTHORITY. `auth.uid()` is what the database will
+               believe whatever this process thinks, so the id is taken FROM the
+               rebuilt client rather than held against it. Warned rather than silent:
+               a daemon that starts heartbeating as a different user has had the
+               machine change owner underneath it, and that is worth a line. */
+            const { data } = await p.client.auth.getUser();
+            const currentUserId = data.user?.id;
+            if (currentUserId && currentUserId !== p.userId) {
+                console.warn('the signed-in account changed underneath this daemon — heartbeating as the account now on disk');
+                p.userId = currentUserId;
+            }
         }
         catch { /* stay down until the next tick */ }
     }
@@ -115,12 +153,45 @@ async function pollCommands(p) {
         console.warn(`command poll failed, will retry: ${err.message}`);
     }
 }
+/**
+ * One turn of the orchestrator listener (feature 16, Slice 3). All the logic is
+ * in orchestrator.ts as a pure, dependency-injected function; this is only the
+ * glue that hands it live process state, exactly as `heartbeat` hands
+ * `buildPresenceHeartbeatPayload` its inputs. Nothing here can throw —
+ * `orchestratorTick` catches everything internally — so `void`-ing it into an
+ * interval is safe.
+ *
+ * `liveAgents()` rather than `p.agents`: `p.agents` is a snapshot from
+ * `startPresence`, and a user who installs Claude AFTER `cs start` would
+ * otherwise never satisfy the designation's agent half until they restarted the
+ * daemon. Same reasoning as the heartbeat's per-tick `detectAgents()`.
+ */
+async function pollOrchestrator(p) {
+    /* !Cleanup Phase 0 (I5c) — WHICH CTRL+SPC SERVER THE WORKER MAY REACH.
+       Read here, per tick, for the same reason `liveAgents()` is: the tools server
+       can come up after the first tick, and a snapshot taken at `startPresence`
+       would leave every worker for the rest of the session with no tools. Null
+       while it is down, which dispatches the worker with none rather than letting
+       it inherit the user's own agent config — where a second CTRL+SPC server
+       pointed at a different account was found registered and listening. */
+    const server = toolsServerStatus();
+    await orchestratorTick({
+        client: p.client,
+        userId: p.userId,
+        machineId: p.identity.id,
+        machineName: p.identity.name,
+        agents: liveAgents(),
+        state: p.listener,
+        mcpServer: server.running ? { port: server.port, token: mcpToken() } : null,
+    });
+}
 /** Come online. Throws NotLoggedIn (from getClient) if no session — callers in
  *  the companion guard for that; the terminal daemon lets it surface. No-op if
  *  already running. */
 export async function startPresence() {
-    if (presence)
-        return { machineName: presence.identity.name, agents: presence.agents };
+    if (presence) {
+        return { machineName: presence.identity.name, agents: presence.agents, client: presence.client };
+    }
     if (starting)
         return starting;
     starting = (async () => {
@@ -139,14 +210,107 @@ export async function startPresence() {
             platform: platform(),
             hb: setInterval(() => { }, HEARTBEAT_INTERVAL_MS),
             cp: setInterval(() => { }, COMMAND_POLL_INTERVAL_MS),
+            ot: setInterval(() => { }, ORCHESTRATOR_POLL_INTERVAL_MS),
+            listener: createListenerState(),
         };
         clearInterval(p.hb);
         clearInterval(p.cp);
+        clearInterval(p.ot);
         presence = p;
         await heartbeat(p);
         await cleanupSupersededRows(p);
-        p.hb = setInterval(() => void heartbeat(p), HEARTBEAT_INTERVAL_MS);
+        /* 16c Slice 1 — reclaim what a previous life stranded, BEFORE the first
+           tick. A killed process runs no `catch` and no `finally`, so a daemon that
+           died mid-run leaves a claimed todo and a live worker row; neither
+           self-heals, and the worker's unique index would refuse the retry. Scoped
+           to this machine's own id: if this daemon is starting, nothing it started
+           is still running. */
+        await recoverStrandedWorkers(p.client, identity.id);
+        /* 18c SLICE 8 — AND RECLAIM WHAT A PREVIOUS LIFE LEFT ON DISK. A codex worker
+           runs against a per-run `$CODEX_HOME` seeded with a COPY OF THE USER'S
+           CREDENTIAL, swept when the run's child closes. A killed process closes no
+           child: SIGKILL, a panic, an OS restart, launchd restarting a crashed
+           daemon, and this daemon's own shutdown (which calls `process.exit(0)`
+           without awaiting in-flight spawns) all leave the directory behind, and
+           nothing else would ever look at it again.
+    
+           IT DOES *NOT* BORROW THE RECOVERY ABOVE'S SAFETY ARGUMENT, and this comment
+           used to say it did. "If this daemon is starting, nothing it started is
+           still running" holds for `recoverStrandedWorkers`, which is scoped by
+           `machine_id` to rows THIS install owns on a server. It is FALSE for a
+           shared local directory: TWO independent processes reach this line — the
+           terminal daemon (`cs start`) and the companion (`cs open`, and again after
+           browser sign-in) — the daemon has no cross-process guard, and both resolve
+           the same `configDir()`. Acting on that borrowed argument, this swept the
+           whole root and deleted a LIVE worker's home when `cs start` ran while the
+           companion was mid-run.
+    
+           So the sweep is scoped by the OWNING PROCESS instead: each home is stamped
+           with the pid that built it and only an ownerless one is removed. The full
+           argument, including why an age-based scope was measured and rejected, is
+           in `sweepStrandedCodexHomes`. Do not re-widen this to the root. */
+        sweepStrandedCodexHomes();
+        p.hb = setInterval(() => {
+            /* ═══ 18k SLICE 7 — TAKE THE MESSAGES, AWAITED AFTER THE HEARTBEAT. ═══
+      
+               ON THE HEARTBEAT AND NOT THE TICK. `orchestratorTick` returns 'busy' at
+               its concurrency cap, so a busy daemon would not look at the queue for
+               hours; and the designation read lives INSIDE `runTick`, after the slot
+               is taken, so hoisting the take in there would break the atomicity that
+               placement protects. Work that must run at the cap goes here — the
+               liveness watch below records the same reason.
+      
+               SEQUENCED AFTER `heartbeat(p)`, NOT DISPATCHED BESIDE IT, and that is
+               not tidiness. `heartbeat()` can REASSIGN `p.userId` when the account on
+               disk changes, because the token is the authority (see its comment, and
+               the wedge it records). A take dispatched in the same synchronous
+               callback as `void heartbeat(p)` would capture the PRE-reconciliation
+               `p.userId` for its designation read while the RPC scopes itself by
+               `auth.uid()` from the token: two different users, one deciding whether
+               to take and the other deciding what.
+      
+               PRESENCE IS STILL WRITTEN EVEN IF THE TAKE THROWS, guaranteed by
+               placement rather than by a promise: `heartbeat` has already returned
+               before the take is called, so nothing the take does can reach the
+               upsert. `takeRunMessages` also never throws, matching the rule for
+               anything on an interval here. */
+            void (async () => {
+                await heartbeat(p);
+                /* 18k SLICE 10b — THE ANSWERER NOW HOLDS THE WORKER'S TOOLSET, so it
+                   needs the same server the tick hands a dispatched worker. Resolved
+                   INSIDE the callback rather than captured once, for the reason
+                   `pollOrchestrator` resolves its own per tick: the tools server can
+                   come up after the daemon does, and a snapshot taken at start would
+                   leave every answer for the rest of the session with no tools. Null
+                   while it is down, and `takeRunMessages` then answers nothing rather
+                   than starting an agent that could read none of the work. */
+                const server = toolsServerStatus();
+                void takeRunMessages(p.client, p.userId, p.identity.id, liveAgents(), p.listener, console.log, console.warn, server.running ? { port: server.port, token: mcpToken() } : null);
+            })();
+            /* !Cleanup Phase 6b (I43) — THE LIVENESS WATCH, on the heartbeat rather
+               than the orchestrator tick.
+      
+               It cannot live on the tick: `orchestratorTick` returns early on
+               `state.busy`, so while a run is in flight it does nothing at all — which
+               is exactly the window in which a worker can die. A watch hosted there
+               could never observe the thing it exists to observe.
+      
+               Scoped to this machine's own workers and gated on BOTH a stale
+               `updated_at` and a genuinely dead process, so an agent inside a long
+               tool call is never reaped for being quiet. */
+            void reapDeadWorkers(p.client, p.identity.id, p.listener.livePids);
+        }, HEARTBEAT_INTERVAL_MS);
         p.cp = setInterval(() => void pollCommands(p), COMMAND_POLL_INTERVAL_MS);
+        p.ot = setInterval(() => void pollOrchestrator(p), ORCHESTRATOR_POLL_INTERVAL_MS);
+        // Kick one tick immediately so the daemon prints its "Orchestrator: …" line
+        // at startup (ux.md transcript states A, B and C all show it in the opening
+        // block) rather than up to a poll interval later. FIRE-AND-FORGET, NOT
+        // awaited: that first tick can claim a todo and then sit inside a headless
+        // agent run for minutes, and awaiting it here would hold `startPresence`
+        // open — freezing `cs start` before it prints "Online", and freezing the
+        // companion's sign-in, which is the same class of bug mcp.ts's async
+        // registration fixed. Cannot throw (orchestratorTick catches everything).
+        void pollOrchestrator(p);
         // Bring up the local ctrl-spc MCP tools server and register it into Claude
         // so any agent run on this machine has the tools with zero setup. Strictly
         // best-effort: a tools-server or registration failure must never break the
@@ -161,7 +325,7 @@ export async function startPresence() {
         catch (err) {
             console.warn(`Agent tools server did not start: ${err.message}`);
         }
-        return { machineName: identity.name, agents };
+        return { machineName: identity.name, agents, client };
     })();
     try {
         return await starting;
@@ -181,6 +345,14 @@ export async function stopPresence({ markOffline = true, unregister = false } =
     presence = null;
     clearInterval(p.hb);
     clearInterval(p.cp);
+    // The orchestrator listener stops with the presence. A surviving interval
+    // would keep claiming and answering todos for a user who just signed out,
+    // using a client whose session is about to be deleted. An agent already
+    // spawned is left to finish — killing it mid-run would abandon real work and
+    // leave the todo claimed with no answer, which is the outcome the release
+    // path exists to avoid; its answer write is the last thing it does, and the
+    // ListenerState dies with `p` so nothing restarts on top of it.
+    clearInterval(p.ot);
     // On logout (unregister), scrub the ctrl-spc entry from each detected agent's
     // config so a logged-out machine leaves no dead server that would read "failed
     // to connect" on the next agent run. Fire-and-forget best-effort — never blocks

package/dist/win-shell.js

@@ -0,0 +1,162 @@
+/**
+ * 18a SLICE 7 — RUNNING AN npm CLI ON WINDOWS.
+ *
+ * Every agent this product shells out to is installed by npm, which on Windows
+ * means a `.cmd` shim rather than an executable. Three facts follow, and the
+ * first two shipped as defects because each was fixed in one place and not the
+ * other. The third is Slice 8's, and it is the same shape: a Windows rule about
+ * child processes that one call site had and its sibling did not.
+ *
+ *   1. `spawn`/`execFile` REFUSE to run a `.cmd` or `.bat` without a shell.
+ *      Node 20 hardened this (CVE-2024-27980) and the refusal is
+ *      `spawn EINVAL` — which is exactly the line the daemon printed on every
+ *      start while registering its tools: "Could not register ctrl-spc tools
+ *      with claude: spawn EINVAL". The orchestrator had learned this and passed
+ *      `shell`; the MCP registration had not.
+ *
+ *   2. ONCE A SHELL IS INVOLVED, THE ARGUMENTS MUST BE ESCAPED. Node joins argv
+ *      with spaces and hands it to `cmd.exe` unquoted, so anything with a space
+ *      is split and anything with `&`, `|`, `>` or `%` is ACTED ON. The
+ *      registration URL carries `?token=…`, and `?` and `&` are both
+ *      metacharacters.
+ *
+ *   3. THE SHELL PUTS A PROCESS BETWEEN US AND THE AGENT, AND KILLING IS NOT
+ *      TRANSITIVE. `spawn(shim, { shell: true })` runs `cmd.exe /c claude.cmd`,
+ *      so the handle we hold is cmd.exe's and the agent is its grandchild.
+ *      `child.kill()` on Windows is `TerminateProcess` on that one handle, and
+ *      Windows has no process groups to carry it further. See `killTree`.
+ *
+ * This module is where all three live, so a further caller cannot take one and
+ * miss the others.
+ */
+import { spawn } from 'node:child_process';
+/** Does this binary have to go through `cmd.exe` to run at all? Scoped to the
+ *  binary rather than to the platform: a real `.exe` on Windows runs directly,
+ *  and putting it through a shell would re-parse its argv for nothing. */
+export function needsShell(bin) {
+    if (process.platform !== 'win32')
+        return false;
+    return /\.(cmd|bat)$/i.test(bin);
+}
+/**
+ * Quote one argument so `cmd.exe` passes it through untouched.
+ *
+ * THE ALGORITHM IS qntm's, by way of cross-spawn, and it is copied rather than
+ * invented because inventing it is how the defect above happened. Two passes of
+ * metacharacter escaping, deliberately: `cmd.exe` processes the line once for
+ * the shim and the shim's own `cmd.exe` processes it again, which is why
+ * cross-spawn double-escapes for `.cmd` and `.bat` specifically.
+ *
+ * CHOSEN BY MEASUREMENT, NOT BY READING. Four candidate encodings were run on
+ * the Windows box through the SAME path the product uses (a `.cmd` shim
+ * forwarding `%*`, spawned with `shell: true`), against eleven arguments
+ * including the adversarial ones. What ships is the only one that returned all
+ * eleven verbatim:
+ *
+ *   raw (what shipped)  1/11   words split, `%PATH%` expanded INTO the argument,
+ *                              `>` redirected, and `" & echo … & "` RAN.
+ *   quote only          9/11   still expands `%PATH%`, injection still ran.
+ *   carets once        10/11   injection still ran.
+ *   carets twice       11/11   everything verbatim, nothing executed.
+ *
+ * The `%PATH%` row is not merely cosmetic: an expansion puts this machine's
+ * absolute paths into the value, and AGENTS.md's hard rule is that an absolute
+ * local path never leaves the machine.
+ *
+ * IT CANNOT CARRY A NEWLINE, and nothing here can fix that: `^` plus a newline
+ * is cmd's line continuation, which swallows it. Anything multi-line has to
+ * travel by another channel — see the prompt, which goes on stdin.
+ */
+export function quoteForCmd(arg) {
+    /* Backslashes before a quote are doubled and the quote escaped; backslashes
+       at the end are doubled, because the closing quote is about to follow them.
+       Every other backslash is literal. */
+    let out = arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1');
+    out = `"${out}"`;
+    const meta = /([()\][%!^"`<>&|;,\s*?])/g;
+    return out.replace(meta, '^$1').replace(meta, '^$1');
+}
+/** The options every child process on Windows needs, and the argv it needs them
+ *  with. Returned together so a caller cannot take the shell and forget the
+ *  quoting, which is the mistake this module exists to make impossible. */
+export function windowsSafeSpawn(bin, args) {
+    const shell = needsShell(bin);
+    return { args: shell ? args.map(quoteForCmd) : args, shell };
+}
+/**
+ * 18a SLICE 8 (I38). END THE AGENT, NOT THE WRAPPER.
+ *
+ * `child.kill('SIGKILL')` is what Stop and the elapsed-time bound both used, and
+ * on Windows it ends ONE process. Rule 3 above means that process is `cmd.exe`,
+ * so the run settled as stopped, its slot was freed and its card read Stopped
+ * while the agent carried on editing files and spending tokens with nothing on
+ * any screen saying so. MEASURED on the Windows box before this was written, on
+ * the same path the product uses (a `.cmd` shim, `shell: true`): the agent was
+ * still in `tasklist` after the kill.
+ *
+ * `taskkill /T` walks the tree DOWNWARD from the pid it is given and ends every
+ * descendant. Also measured, on the same fixture: the agent went, and every
+ * other `node.exe` on the machine survived, INCLUDING THE DAEMON THAT SPAWNED
+ * THE WRAPPER. That direction is the whole safety argument. The daemon is the
+ * wrapper's parent, never its descendant, so it can never be in the set. (The
+ * blunt instrument, `taskkill /IM node.exe`, does not have that property. It was
+ * used once, by hand, while proving this, and it killed the user's daemon.)
+ *
+ * `/F` because SIGTERM's Windows analogue is not reliably honoured by a headless
+ * agent mid-tool-call, which is the same reason the POSIX side sends SIGKILL:
+ * I17's requirement is that the child is REALLY gone.
+ *
+ * NOTHING HERE THROWS AND NOTHING IS AWAITED. Both callers are inside a poll
+ * that must not be stalled by a kill, and the run's own `close` event is what
+ * actually reports the outcome. `taskkill` exits non-zero when the process is
+ * already gone, which is not an error here: the caller wanted it gone.
+ */
+export function killTree(child, { platform = process.platform, spawnProcess = spawn } = {}) {
+    /* Everywhere else `spawn` hands argv to the kernel with no shell in between,
+       so the handle IS the agent and SIGKILL reaches it. */
+    const direct = () => {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            /* Already gone. `close` still fires and reports the outcome. */
+        }
+    };
+    if (platform !== 'win32' || typeof child.pid !== 'number')
+        return direct();
+    try {
+        const killer = spawnProcess('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], {
+            // MEMORY: "Windows silence decision". No console may EVER flash, and this
+            // one fires while the user is watching the panel.
+            windowsHide: true,
+            stdio: 'ignore',
+        });
+        /* THE FALLBACK MATTERS. If `taskkill.exe` cannot run at all, doing nothing
+           would mean Stop does nothing, which is worse than today: today at least
+           the wrapper dies and the request settles. So take the wrapper. */
+        killer.on('error', direct);
+    }
+    catch {
+        direct();
+    }
+}
+/** Is a process with this pid alive? `kill(pid, 0)` signals nothing and only
+ *  tests for existence. EPERM means it exists and belongs to someone else,
+ *  which still answers "alive", so only ESRCH ("no such process") is death.
+ *
+ *  18c SLICE 9 MOVED IT HERE, from orchestrator.ts, and the move is structural
+ *  rather than tidying. `recoverStrandedSessions` (mcp.ts) needs the same check,
+ *  and orchestrator.ts imports mcp.ts, so leaving it there would have made a
+ *  cycle. This module is the right home anyway: it is where the process-control
+ *  primitives already live (`killTree`, `windowsSafeSpawn`) and it imports
+ *  nothing of the project's own, so anything may depend on it. Re-exported from
+ *  orchestrator.ts so every existing caller and test is unaffected. */
+export function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}