@ctrl-spc/cs 0.7.2 → 0.7.4

package/dist/presence-heartbeat.js

@@ -9,5 +9,8 @@ export function buildPresenceHeartbeatPayload(input, seenAt = new Date()) {
         platform: input.platform,
         cli_version: CLI_VERSION,
         last_seen_at: seenAt.toISOString(),
+        // A beating heart is not stopped: clears the stamp a clean shutdown left,
+        // so a machine that comes back reads online again.
+        stopped_at: null,
     };
 }

package/dist/presence.js

@@ -1,6 +1,6 @@
 import { platform } from 'node:os';
 import { getClient } from './supabase.js';
-import { getMachineIdentity, mcpToken, supersededMachineIds, clearSupersededMachineIds } from './config.js';
+import { getMachineIdentity, mcpToken, readSession, supersededMachineIds, clearSupersededMachineIds } from './config.js';
 import { detectAgents } from './agents.js';
 import { installSkills } from './skills.js';
 import { startToolsServer, stopToolsServer, toolsServerStatus, registerWithClaude, registerWithCodex, unregisterFromClaude, unregisterFromCodex, agentRegStatus, heartbeatOpenSessions, setToolsClient, } from './mcp.js';
@@ -15,9 +15,90 @@ let presence = null;
  *  concurrent callers both build interval pairs — the first pair then leaks and
  *  keeps heartbeating "online" past sign-out. Concurrent callers await this. */
 let starting = null;
+/** In-flight guard for stopPresence, mirroring `starting` above. `stopPresence`
+ *  clears the module singleton synchronously and then awaits its
+ *  `cliv2_agents.stopped_at` write, so a second caller arriving mid-write used
+ *  to see `presence === null` and return immediately. On the SIGNED_OUT path
+ *  that second caller is real: presence's own watcher calls `stopPresence()`,
+ *  and the daemon's watcher calls `shutdown(1)`, which calls `stopPresence()`
+ *  again. `daemon.ts`'s `Promise.all([panel.stop(), stopPresence()])` then
+ *  resolved on that early return, and `process.exit(code)` truncated the
+ *  first call's write still in flight, leaving the machine reading online in
+ *  the web UI until its freshness window lapsed. A second caller now awaits
+ *  the same in-flight work instead. */
+let stopping = null;
 export function isPresenceRunning() {
     return presence !== null;
 }
+/**
+ * ═══ WHICHEVER CLIENT PRESENCE IS ACTUALLY HOLDING RIGHT NOW. ═══
+ *
+ * The heartbeat's catch block REASSIGNS `p.client` when `session.json` comes to
+ * hold a different refresh token (a concurrent `cs login`, another install on
+ * this box signing in as someone else). Before the rebuild guard landed that
+ * reassignment effectively never happened, because the rebuild threw every time
+ * against the same dead token, so every other holder of the client
+ * `startPresence` built was accidentally correct. It is not any more: a
+ * successful rebuild is now the normal path, and a caller holding the original
+ * is holding a client whose token the database refuses and whose `SIGNED_OUT`
+ * nobody is watching. `panel3_machines` took 37,051 writes that way in one
+ * window, read off this machine's own logs.
+ *
+ * So the client is READ rather than handed over, through the module singleton
+ * that already owns the presence lifecycle, in the exported-accessor style
+ * `isPresenceRunning` above is written in.
+ *
+ * NULL WHEN PRESENCE IS NOT RUNNING, and truthfully so: there is no client to
+ * give, and inventing one here would build a second refresh loop in a process
+ * that is supposed to have exactly one. A caller that starts presence and then
+ * reads this has a non-null answer for as long as presence is up, which is the
+ * whole of the daemon's life.
+ */
+export function liveClient() {
+    return presence?.client ?? null;
+}
+/** Whether the heartbeat's catch block should rebuild its client from disk.
+ *
+ * Exact, not heuristic: a rebuild only ever helps when `session.json` holds a
+ * DIFFERENT refresh token than the one the live client was built from (a
+ * concurrent `cs login`, or another install on this box signing in as someone
+ * else). When it holds the SAME token, `getClient` -> `setSession` -> auth-js
+ * will decode it, see the exact expiry it saw last tick, and call
+ * `_callRefreshToken` again against a refresh token GoTrue has already
+ * revoked, repeating the same 400 `refresh_token_not_found` that ran once per
+ * heartbeat tick (every 10s) instead of once per auth-js's own 60s cooldown,
+ * because a brand-new client has no memory of the failure. `onDisk` null/undefined
+ * (`readSession()` returns null on a missing or corrupt file, and the field is
+ * optional on `StoredSession` reads) means there is nothing new to try, so it
+ * also answers false rather than forcing a rebuild against nothing.
+ *
+ * No SupabaseClient type appears here on purpose: the decision is a pure
+ * string comparison, so a test can call it with two strings and nothing else. */
+export function shouldRebuildClient(builtFrom, onDisk) {
+    if (onDisk == null)
+        return false;
+    return builtFrom !== onDisk;
+}
+/** Register the one `SIGNED_OUT` handler presence relies on, and return its
+ *  subscription so the caller can unsubscribe it later. Extracted so
+ *  `startPresence`'s initial binding and the heartbeat's post-rebuild rebind
+ *  are the same code, not two copies that could drift, and so a test can pass
+ *  a fake client and fire the callback directly without a real Supabase
+ *  client.
+ *
+ *  `SIGNED_OUT` is the truthful signal (see the block comment on
+ *  `startPresence` for why): auth-js fires it from `_removeSession` only when
+ *  a refresh fails non-retryably AND the access token has already expired.
+ *  Nothing on disk is touched here; `cs logout` owns deleting `session.json`. */
+export function bindSignedOutWatcher(client) {
+    const { data } = client.auth.onAuthStateChange((event) => {
+        if (event !== 'SIGNED_OUT')
+            return;
+        console.error('Session expired and could not be refreshed. Run `cs login` to sign in again.');
+        void stopPresence();
+    });
+    return data.subscription;
+}
 async function heartbeat(p) {
     try {
         const { error } = await p.client
@@ -33,50 +114,77 @@ async function heartbeat(p) {
             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.
+        // A failure here used to rebuild the client from disk unconditionally, and
+        // that was the production incident: `getClient` -> `setSession` decodes
+        // whatever refresh token is on disk and hands it to auth-js, which refreshes
+        // it UNCONDITIONALLY if the access token has expired. When the disk token is
+        // the same dead one this client was already built from, that is a guaranteed
+        // repeat of the exact 400 `refresh_token_not_found` that got us here, once
+        // per 10s heartbeat tick instead of once per auth-js's own 60s cooldown (that
+        // cooldown lives on the client instance, and a fresh client every tick never
+        // accumulates it). 7,028 refresh requests in one window, read off this
+        // machine's own logs. `shouldRebuildClient` below is the guard: only rebuild
+        // when `session.json` disagrees with the token this client holds.
         console.warn(`heartbeat failed, will retry: ${err.message}`);
         try {
-            p.client = await getClient();
-            // FIX 2: flow the rebuilt client (fresh/refreshed token) into the tools
-            // session-lifecycle heartbeat too, so a wedged token can't leave the session
-            // 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;
+            const onDisk = readSession()?.refresh_token;
+            if (shouldRebuildClient(p.builtFromRefreshToken, onDisk)) {
+                // KEEPING THE REBUILD, NOT DELETING IT: every client here is built with
+                // `persistSession: false`, which selects auth-js's in-memory storage
+                // adapter, so `getUser()` reads that client's own memory and never reads
+                // `session.json`. `getClient()` -> `readSession()` -> `setSession()` is the
+                // ONLY path in this process from disk to a live client. Deleting the
+                // rebuild (proposed twice already in earlier drafts of this fix) would make
+                // the account-reconciliation below unreachable and a concurrent `cs login`
+                // unrecoverable without restarting the daemon.
+                const rebuilt = await getClient();
+                p.authSubscription.unsubscribe();
+                p.authSubscription = bindSignedOutWatcher(rebuilt);
+                p.client = rebuilt;
+                // shouldRebuildClient already ruled out onDisk being null/undefined to
+                // reach this branch; the `as string` reflects that guarantee rather
+                // than reintroducing a null fallback that can't occur.
+                p.builtFromRefreshToken = onDisk;
+                // FIX 2: flow the rebuilt client (fresh/refreshed token) into the tools
+                // session-lifecycle heartbeat too, so a wedged token can't leave the session
+                // 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 */ }
@@ -191,7 +299,7 @@ async function pollOrchestrator(p) {
  *  already running. */
 export async function startPresence() {
     if (presence) {
-        return { machineName: presence.identity.name, agents: presence.agents, client: presence.client };
+        return { machineName: presence.identity.name, agents: presence.agents };
     }
     if (starting)
         return starting;
@@ -199,6 +307,30 @@ export async function startPresence() {
         const identity = getMachineIdentity();
         const agents = detectAgents();
         const client = await getClient();
+        /* ═══ A DEAD SESSION STOPS THE LOOPS. IT DOES NOT SLOW THEM DOWN. ═══
+           The refresh token can die while the daemon runs (a re-login elsewhere
+           rotates it out from under this process), and until this existed nothing
+           reacted: `getClient`'s auto-refresh 400'd every ten seconds while all
+           three intervals kept firing with the expired access token. Read off the
+           hosted project's own logs, two minutes of it was 500 lines — 13 refusals
+           to refresh, and 487 401s and matching `42501 permission denied` rows
+           behind them, forever, because no poller here treats its own 401 as
+           terminal (`heartbeat` explicitly retries it, which is right for a blip
+           and wrong for this).
+    
+           `SIGNED_OUT` is the truthful signal and the only one: auth-js fires it
+           from `_removeSession` only when a refresh fails non-retryably AND the
+           access token has already expired — a proactive refresh failure over a
+           still-valid token preserves the session, and a network blip is retryable,
+           so neither reaches here. Nothing on disk is touched: `cs logout` owns
+           deleting `session.json`, and this must not, or a machine that merely
+           needs a fresh token would look to the user like one that was signed out
+           deliberately.
+    
+           Bound through `bindSignedOutWatcher` rather than inline, so this initial
+           binding and the heartbeat's post-rebuild rebind are the same code and
+           can never drift out of sync with each other. */
+        const authSubscription = bindSignedOutWatcher(client);
         const { data } = await client.auth.getUser();
         const userId = data.user?.id;
         if (!userId)
@@ -213,6 +345,8 @@ export async function startPresence() {
             cp: setInterval(() => { }, COMMAND_POLL_INTERVAL_MS),
             ot: setInterval(() => { }, ORCHESTRATOR_POLL_INTERVAL_MS),
             listener: createListenerState(),
+            builtFromRefreshToken: readSession()?.refresh_token ?? null,
+            authSubscription,
         };
         clearInterval(p.hb);
         clearInterval(p.cp);
@@ -318,6 +452,21 @@ export async function startPresence() {
         // presence heartbeat above, so it's caught and warned like everything here.
         try {
             await startToolsServer({ client, userId, machineId: identity.id });
+            /* ═══ AND THE TOOLS SERVER IS POINTED AT WHATEVER CLIENT IS LIVE BY NOW,
+               WHICH IS NOT NECESSARILY THE ONE IT WAS JUST STARTED WITH. ═══
+               `startToolsServer` sets `toolsClient = deps.client`, and `deps.client`
+               is the local const above, which is the client this function built before
+               the first `heartbeat(p)` ran. That heartbeat can rebuild `p.client` (a
+               concurrent `cs login`, an account change on disk), and its own
+               `setToolsClient(p.client)` call was a SILENT NO-OP when it did, because
+               `setToolsClient` refuses while `handle` is unset and `handle` is only
+               set here, AFTER the first heartbeat. So a rebuild during startup left
+               the session-lifecycle heartbeat on the original client for the life of
+               the process, 401ing forever with nothing to re-set it: the CLI-v1
+               stale-token root cause, reintroduced by ordering alone.
+               `p.client` rather than `client`, because the whole point is to pick up a
+               rebuild the local const cannot see. */
+            setToolsClient(p.client);
             /* The instructions belong to the release, so they are rewritten beside
                registration on every start: the pair is "make this machine's agents
                ready", and a machine registered against current tools while reading a
@@ -333,7 +482,7 @@ export async function startPresence() {
         catch (err) {
             console.warn(`Agent tools server did not start: ${err.message}`);
         }
-        return { machineName: identity.name, agents, client };
+        return { machineName: identity.name, agents };
     })();
     try {
         return await starting;
@@ -342,45 +491,75 @@ export async function startPresence() {
         starting = null;
     }
 }
-/** Go offline. Best-effort stamps last_seen_at into the past so the web sheet
- *  reads offline immediately instead of waiting out the freshness window. Pass
- *  `unregister` (logout only, never plain shutdown) to also remove the ctrl-spc
- *  entry from each detected agent's config. */
-export async function stopPresence({ markOffline = true, unregister = false } = {}) {
+/** Go offline. Best-effort stamps stopped_at so the web reads offline
+ *  immediately; last_seen_at keeps the real last heartbeat (a Date(0) stamp
+ *  here once rendered as "last seen 20694d ago"). Pass `unregister` (logout
+ *  only, never plain shutdown) to also remove the ctrl-spc entry from each
+ *  detected agent's config.
+ *
+ *  A second call while one is already in flight AWAITS THE SAME WORK rather
+ *  than returning early, mirroring `startPresence`'s `starting` guard above.
+ *  `unregister` is read only from the caller that actually starts the stop;
+ *  a second caller arriving mid-stop cannot change what is already running,
+ *  so its own `unregister` value is not consulted. In practice the real
+ *  collision is a plain shutdown racing a `SIGNED_OUT` stop with no
+ *  `unregister` on either side (see `stopping`'s comment); `unregister: true`
+ *  only ever comes from `cs logout`, called directly by the user, not from a
+ *  watcher, so it is never the losing side of this race in practice. */
+export async function stopPresence({ unregister = false } = {}) {
+    if (stopping)
+        return stopping;
     const p = presence;
     if (!p)
         return;
     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
-    // logout. On a plain SIGINT shutdown the entries are intentionally left in place
-    // (the caller passes no `unregister`); the badge just reads not-connected
-    // because the server below is torn down.
-    if (unregister) {
-        if (p.agents.includes('claude'))
-            void unregisterFromClaude();
-        if (p.agents.includes('codex'))
-            void unregisterFromCodex();
-    }
-    await stopToolsServer().catch((err) => console.warn(`Agent tools server did not stop cleanly: ${err.message}`));
-    if (markOffline) {
+    stopping = (async () => {
+        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);
+        /* AND THE SIGNED_OUT WATCHER GOES WITH THE INTERVALS, for the same reason
+           the heartbeat's rebuild unsubscribes before it rebinds: an unsubscribed
+           handler cannot stop a presence the process no longer means it to. `cs
+           start` exits, so this is invisible there, but the companion does not:
+           `companion.ts` calls `stopPresence({ unregister: true })` on logout and
+           can call `startPresence()` again in the same process on a fresh sign-in.
+           The old client is still alive with `autoRefreshToken: true` and a revoked
+           token, and when it finally emits `SIGNED_OUT` its orphaned watcher would
+           call `stopPresence()` and kill the presence belonging to a DIFFERENT
+           session, one that is signed in and healthy. */
+        p.authSubscription.unsubscribe();
+        // 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
+        // logout. On a plain SIGINT shutdown the entries are intentionally left in place
+        // (the caller passes no `unregister`); the badge just reads not-connected
+        // because the server below is torn down.
+        if (unregister) {
+            if (p.agents.includes('claude'))
+                void unregisterFromClaude();
+            if (p.agents.includes('codex'))
+                void unregisterFromCodex();
+        }
+        await stopToolsServer().catch((err) => console.warn(`Agent tools server did not stop cleanly: ${err.message}`));
         try {
             await p.client
                 .from('cliv2_agents')
-                .update({ last_seen_at: new Date(0).toISOString() })
+                .update({ stopped_at: new Date().toISOString() })
                 .eq('machine_id', p.identity.id);
         }
-        catch { /* ignore — a stale timestamp already reads as offline */ }
+        catch { /* ignore — a lapsed heartbeat reads as offline anyway */ }
+    })();
+    try {
+        await stopping;
+    }
+    finally {
+        stopping = null;
     }
 }

package/dist/screenshots.js

@@ -1,6 +1,7 @@
 import { lstat, readFile } from 'node:fs/promises';
 import { isAbsolute } from 'node:path';
 import { inflateSync } from 'node:zlib';
+import { createHash } from 'node:crypto';
 export const MAX_SCREENSHOT_BYTES = 20 * 1024 * 1024;
 const MAX_DECODED_SCREENSHOT_BYTES = 256 * 1024 * 1024;
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
@@ -194,3 +195,47 @@ export async function readPngScreenshot(localPath) {
     }
     return { bytes, width, height, sizeBytes: bytes.length };
 }
+/** 18c Slice 7. The deterministic id for a REQUEST-anchored screenshot.
+ *
+ *  IT IS THE SAME DERIVATION WITH A DIFFERENT ANCHOR AND A DIFFERENT DOMAIN
+ *  TAG, and both halves of that matter. Same derivation, because the property it
+ *  buys is the one the work-item path already needs: an interrupted call that
+ *  uploaded the object but never wrote the row retries onto the SAME key and
+ *  converges, instead of leaking one private object per attempt. Different
+ *  domain tag (`:todo:`), because the two anchors must not be able to collide —
+ *  a task id and a request id are both uuids, and without the tag a screenshot
+ *  with the same title, platform, target and bytes could derive one id under two
+ *  anchors and have the second insert fail against the first's object. */
+export function screenshotRequestId(todoId, title, platform, target, bytes) {
+    return screenshotDeterministicId('ctrl-spc:screenshot:todo:v1\0', todoId, title, platform, target, bytes);
+}
+export function screenshotArtifactId(taskId, title, platform, target, bytes) {
+    return screenshotDeterministicId('ctrl-spc:screenshot:v1\0', taskId, title, platform, target, bytes);
+}
+/** The shared body of the two id derivations above. Extracted rather than
+ *  duplicated so the two anchors cannot drift into hashing different things:
+ *  the whole point of a content-addressed id is that the same picture yields the
+ *  same key, and two copies of this would eventually disagree about what "the
+ *  same picture" means. `domain` is what keeps them distinct. */
+function screenshotDeterministicId(domain, anchorId, title, platform, target, bytes) {
+    const digest = createHash('sha256')
+        .update(domain)
+        .update(anchorId)
+        .update('\0')
+        .update(title)
+        .update('\0')
+        .update(platform)
+        .update('\0')
+        .update(target)
+        .update('\0')
+        .update(bytes)
+        .digest()
+        .subarray(0, 16);
+    // RFC 9562-shaped, deterministic UUID. The content-addressed identity makes
+    // a retry after Storage succeeded but Postgres failed converge on the same
+    // object instead of leaking one new object per retry.
+    digest[6] = (digest[6] & 0x0f) | 0x50;
+    digest[8] = (digest[8] & 0x3f) | 0x80;
+    const hex = digest.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/dist/skills.js

@@ -15,7 +15,7 @@ import { dirname, join } from 'node:path';
  */
 // Verbatim from the web/skill contract the copied `/ctrl-spc work <id>`
 // invocation depends on.
-const SKILL_DESCRIPTION = 'Work a CTRL+SPC work item or artifact by ID — delegates read-only exploration and writes analysis/plans/specs/diagrams/mocks/wireframes back via the ctrl-spc MCP tools. Use when the user pastes /ctrl-spc work <id> or /ctrl-spc artifact <id>.';
+const SKILL_DESCRIPTION = 'Work a CTRL+SPC work item or artifact by ID — delegates read-only exploration and writes analysis/plans/specs/diagrams/mocks/wireframes back via the ctrl-spc MCP tools. Use when the user pastes /ctrl-spc work <id> or /ctrl-spc artifact <id>, and to fetch one object when they paste /ctrl-spc workflow <id>, /ctrl-spc skill <id>, /ctrl-spc credential <id> or /ctrl-spc document <id>.';
 /** Home the skill files are written under. `CTRL_SPC_HOME` is the existing
  *  documented name for exactly this (docs/cli-surface-catalog.md), reused
  *  rather than renamed so one machine has one sandbox-home concept. */
@@ -77,6 +77,15 @@ export function installSkills(agents) {
  */
 const PROTOCOL_BODY = `Resolve a CTRL+SPC work item or artifact pasted as \`/ctrl-spc work <id>\` or \`/ctrl-spc artifact <id>\`, then follow the ctrl-spc working protocol:
 
+FETCH VERBS — \`workflow\`, \`skill\`, \`credential\` and \`document\` are NOT the working protocol. They name ONE object the user copied so they can use it in this conversation, and nothing below applies to them: no \`begin_work\`, no subagents, no context artifact, no question, no \`end_work\`. Fetch the object, use it for what the user asked, and answer.
+
+- \`/ctrl-spc workflow <id>\` — call \`read_workflow_library\` and use the workflow whose \`id\` matches, with the full body of each stage it holds. To RUN it on a work item, call \`start_workflow\` with that workflow id, then follow the working protocol below for the item. Report and stop when the user only asked to see it.
+- \`/ctrl-spc skill <id>\` — call \`get_skill\` with \`id\`. THE RESULT IS A DOCUMENT TO FOLLOW for the rest of this work, not reference material to summarise. Its supporting files come from \`read_skill_file\` with the same \`id\`.
+- \`/ctrl-spc credential <id>\` — call \`get_credential\` with \`id\`, then USE the value to do the work: a header, an environment variable, a command, local config. Never publish it: keep it out of your answer, comments, artifacts and questions, and name the credential instead.
+- \`/ctrl-spc document <id>\` — call \`get_document\` with \`id\`. One context document or one agent instruction, whole. It resolves either kind, so you do not need to know which the id names. To read a project's context as a whole instead, call \`get_project_context\`.
+
+Pass the pasted id as \`id\`. It names exactly one object, so \`org_id\` is never needed with it and a duplicate name cannot send you to the wrong one. Everything that follows is the WORK ITEM protocol:
+
 WORKFLOW AUTHORITY — when \`get_task.workflow.enabled\` is true, follow only its current stage, stored instructions, capabilities, requirements, and gate. Never infer or skip a stage. Persist each required artifact, then call \`hand_off_stage\` with the work item id and this request id, and stop: the next stage is worked by a fresh agent reading the record. It refuses a stage with unfinished steps and the last stage of the process, where you answer and stop instead. Review gates advance only after explicit user approval in the web app or conversation; requested changes stay in the same stage. Only final approval sets Done.
 
 HARD STOP — unclear novel feature (No workflow only): when \`workflow.enabled\` is false, after \`record_context_exploration\` succeeds, if the task does not explicitly request a build or name a deliverable, the next tool call MUST be \`ask_question\` with category \`intent\`, the exact question “What should I produce for this feature?”, \`answer_mode = multi_select\`, and options \`build\`, \`plan\`, \`spec\`, \`diagram\`, \`mock\`, and \`wireframe\`. Then call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`. In that run, never call \`get_task\` again, \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or any other tool between the context artifact and \`ask_question\`. The context artifact is the only allowed artifact. Do not copy findings into the task description before the user answers. A read-only execution sandbox is not a missing checkout and must not change this intent question. The user may select one or more: build, plan, spec, diagram, mock, wireframe.

package/dist/supabase.js

@@ -58,11 +58,38 @@ const retryingFetch = async (input, init) => {
  * lifetime: `autoRefreshToken: true` (v1 had it false with no refresh loop, so
  * after an hour every write 401'd silently) and the retrying fetch above.
  * Rotated tokens are written straight back to disk via onAuthStateChange.
+ *
+ * Pass `{ refreshing: false }` for a client that can never rotate the stored
+ * refresh token, for a caller that shares session.json with another process:
+ * two processes refreshing the same token family revoke it for both.
  */
-export async function getClient() {
+export async function getClient({ refreshing = true } = {}) {
     const stored = readSession();
-    if (!stored?.access_token || !stored?.refresh_token)
+    // The refreshing path still requires both, exactly as today. The
+    // non-refreshing one is never handed a refresh token, so it must not demand
+    // one: requiring it would refuse a session this client can legitimately use.
+    if (!stored?.access_token)
+        throw new NotLoggedIn();
+    if (refreshing && !stored?.refresh_token)
         throw new NotLoggedIn();
+    /* ═══ NOT REFRESHING MEANS NEVER HANDED THE REFRESH TOKEN. ═══ Not merely
+       `autoRefreshToken: false`: auth-js refreshes inside `setSession` whenever
+       the access token has already expired, regardless of that flag
+       (`GoTrueClient.js:2994`). A client never given the refresh token has
+       nothing to rotate, which is the only guarantee that holds. Two processes
+       rotating one `session.json` revoke the family for both.
+  
+       An already-expired token is refused here rather than left to fail at the
+       first query, so callers keep the `NotLoggedIn` boundary they have today.
+       Same pattern as `scripts/prove-scope-history.mjs:34-41`. */
+    if (!refreshing) {
+        if (accessTokenExpired(stored.access_token))
+            throw new NotLoggedIn();
+        return createClient(SUPABASE_URL, SUPABASE_KEY, {
+            auth: { persistSession: false, autoRefreshToken: false },
+            global: { fetch: retryingFetch, headers: { Authorization: `Bearer ${stored.access_token}` } },
+        });
+    }
     const client = createClient(SUPABASE_URL, SUPABASE_KEY, {
         auth: { persistSession: false, autoRefreshToken: true },
         global: { fetch: retryingFetch },
@@ -84,3 +111,17 @@ export async function getClient() {
     }
     return client;
 }
+/** Whether a stored access token's own `exp` claim has already passed. A token
+ *  this process cannot parse is treated as unusable rather than trusted: the
+ *  caller's next request would 401 anyway, and `NotLoggedIn` is the honest
+ *  answer at the boundary rather than a raw SyntaxError from the middle of a
+ *  request handler. Exported so a test can pass a string and nothing else. */
+export function accessTokenExpired(token) {
+    try {
+        const claims = JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString());
+        return typeof claims.exp !== 'number' || claims.exp * 1000 <= Date.now();
+    }
+    catch {
+        return true;
+    }
+}