@ctrl-spc/cs 0.7.3 → 0.7.5

package/dist/companion.js

@@ -4,9 +4,9 @@ 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 { startPresence, stopPresence, liveClient, isPresenceRunning } from './presence.js';
 import { detectAgents } from './agents.js';
-import { agentToolsBadgeState } from './mcp.js';
+import { agentToolsBadgeState, foreignToolsServerAlive, unregisterFromClaude, unregisterFromCodex, } from './mcp.js';
 import { loadProjects, saveMapping } from './projects.js';
 import { listCodebases, addCodebase, reportLocated, removeCodebase, NotHostedRemoteError } from './codebases.js';
 import { hostedRemoteIdentity } from './git-remote.js';
@@ -14,9 +14,64 @@ import { chooseFolder, detectGitRemote } from './folders.js';
 import { renderCompanionUi } from './companion-ui.js';
 const MAX_BODY_BYTES = 64 * 1024;
 const VERSION = '0.1.0';
+/** Whether THIS process is the one refreshing the machine's token. False once
+ *  the companion has found a daemon already serving and deferred to it, so
+ *  `requestClient`'s fallback stops building a rival refresher. Starts true
+ *  because a companion with no daemon beside it is the common case (bare `cs`
+ *  is `openCompanion()`, and `cs open` never installs autostart). */
+let companionRefreshing = true;
+/**
+ * Resolves once `companionRefreshing` holds this boot's real decision.
+ *
+ * The server starts listening before that decision is taken: the probe inside
+ * `startPresenceUnlessDaemonServes` costs up to a second, and the
+ * `startPresence()` behind it costs seconds more. A browser tab left open by a
+ * previous `cs open` polls `GET /api/session` every two seconds, so without
+ * this it can be served during that window, while `companionRefreshing` is
+ * still its `true` initializer, by a refreshing client on a machine where a
+ * daemon is already rotating the token. That is the very collision the
+ * deferral exists to prevent, so no authenticated request is served until the
+ * decision is in.
+ *
+ * It is only ever a decision barrier. A failure to start presence is already
+ * handled by the `onError` callback and must not become a permanently wedged
+ * server, so the assignment below settles this promise on every path.
+ */
+let refreshDecided = Promise.resolve();
 function url(token = companionToken()) {
     return `http://127.0.0.1:${COMPANION_PORT}/?token=${encodeURIComponent(token)}`;
 }
+/**
+ * Come online, unless a daemon on this machine already has.
+ *
+ * `foreignToolsServerAlive()` probes the fixed tools-server port over loopback
+ * and does NOT exclude the calling process, so this must be asked before
+ * anything in this process could bind that port. Both call sites (boot and
+ * `POST /api/login`) ask exactly once, at a moment where only another `cs` could
+ * be answering.
+ *
+ * When one is: presence, the tools server, agent registration, the orchestrator
+ * and the recovery sweeps are all the daemon's job, and running a second copy
+ * here duplicates them on the one rotating refresh token this machine has.
+ *
+ * `companionRefreshing` is assigned on BOTH branches rather than left at its
+ * initializer, because login runs this again: a companion that deferred to a
+ * daemon and later signs in with that daemon gone must stop reading as
+ * non-refreshing.
+ */
+async function startPresenceUnlessDaemonServes(onError) {
+    if (await foreignToolsServerAlive()) {
+        companionRefreshing = false;
+        return;
+    }
+    companionRefreshing = true;
+    try {
+        await startPresence();
+    }
+    catch (err) {
+        onError(err);
+    }
+}
 /** 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) {
@@ -50,6 +105,14 @@ export async function openCompanion() {
  */
 export async function serveCompanion({ open = false } = {}) {
     const token = companionToken();
+    // Assigned BEFORE the socket is accepting, so there is no instant at which a
+    // request could be served without waiting for the decision. `resolve` is
+    // called on every path out of the block below, including the failures, so a
+    // presence that never started leaves the server answering rather than hung.
+    let decided;
+    refreshDecided = new Promise((resolve) => {
+        decided = resolve;
+    });
     const server = createServer((req, res) => {
         void handle(req, res, token).catch((err) => {
             if (!res.headersSent)
@@ -63,6 +126,9 @@ export async function serveCompanion({ open = false } = {}) {
         });
     }
     catch (err) {
+        // This process never took the port, so it will serve nothing; settle anyway
+        // rather than leave a resolved-by-nobody promise behind for a later caller.
+        decided();
         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
@@ -83,15 +149,19 @@ export async function serveCompanion({ open = false } = {}) {
     }
     // 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}`);
+    try {
+        if (readSession()) {
+            await startPresenceUnlessDaemonServes((err) => {
+                if (!(err instanceof NotLoggedIn))
+                    console.warn(`Presence did not start: ${err.message}`);
+            });
         }
     }
+    finally {
+        // Signed out, presence started, or the probe itself threw: the decision is
+        // as made as it is going to get, and requests must not wait past it.
+        decided();
+    }
     console.log(`Companion running — ${url(token)}`);
     if (open)
         openBrowser(url(token));
@@ -101,7 +171,7 @@ export async function serveCompanion({ open = false } = {}) {
             if (closing)
                 return;
             closing = true;
-            void stopPresence({ markOffline: true }).finally(() => {
+            void stopPresence().finally(() => {
                 server.close(() => resolve());
                 process.exit(0);
             });
@@ -166,6 +236,75 @@ function agentToolsState(signedIn) {
     const installed = detectAgents().filter((a) => a === 'claude' || a === 'codex');
     return agentToolsBadgeState({ signedIn, installed });
 }
+/**
+ * The client an authenticated API request is served through.
+ *
+ * ═══ IT REUSES PRESENCE'S CLIENT, AND THAT IS THE WHOLE POINT OF THIS
+ *     FUNCTION. ═══ `getClient()` builds a BRAND NEW client every call, with
+ * `autoRefreshToken: true` and an `onAuthStateChange` that writes
+ * `session.json` back (`supabase.ts:61-89`). Calling it per HTTP request meant
+ * `cs open` ran a whole family of refreshing, disk-writing clients beside the
+ * daemon's, all on the ONE rotating refresh token the machine has. Supabase
+ * rotates that token on every refresh and revokes the previous family member
+ * outside a 10-second reuse window (`supabase/config.toml:171-175`), so two
+ * independent refreshers race: one wins, the loser replays a superseded token,
+ * GoTrue revokes the family, and the token on disk is PERMANENTLY dead rather
+ * than merely stale. Investigation
+ * `.bugs/20260831-supabase-health/investigations/04-refresh-token-loop.md` §3
+ * names this row 6 of its rotation-collision map and calls it the most likely
+ * precipitating cause of the 2026-08-30 incident, after which the daemon's
+ * heartbeat spun on `400 refresh_token_not_found` roughly 360 times an hour
+ * with no way to self-heal.
+ *
+ * So the rule `daemon.ts` and `panel3/run.ts` already state in their own
+ * comments now holds here too: ONE REFRESH LOOP PER PROCESS, and one writer of
+ * `session.json`. When presence is running, its client is the one that owns
+ * refreshing, and the companion reads it rather than standing up a rival.
+ *
+ * Per process was never enough on its own, because `cs start` and `cs open` are
+ * two processes over one `session.json`: the rule is ONE REFRESH LOOP PER
+ * MACHINE. A companion that boots (or signs in) while a daemon is already
+ * serving defers to it entirely, starting no presence of its own, and everything
+ * below follows from that decision.
+ *
+ * ═══ AND `getClient()` REMAINS THE FALLBACK, BECAUSE NULL HERE MEANS "NO
+ *     PRESENCE", NOT "SIGNED OUT". ═══ `liveClient()` is null before the first
+ * sign-in, and after `stopPresence()`, and in a companion serving on a machine
+ * whose presence failed to start, and in one that found a daemon already
+ * serving and deferred to it. Only `getClient()` can answer the signed-in
+ * question, by reading the session off disk and throwing `NotLoggedIn` when
+ * there is none, so the fallback is what every caller's 401 path still hangs
+ * off.
+ *
+ * What the fallback may NOT do is refresh while another `cs` process on this
+ * machine is refreshing, which is the deferring case above: `cs start` is
+ * already rotating the one token family, and a client built here with
+ * `refreshing: true` would race it exactly as the per-request family did.
+ * `companionRefreshing` carries the decision this process took at boot or at
+ * sign-in, and `getClient({ refreshing: false })` then returns a client that was
+ * never handed the refresh token, so it cannot rotate anything. It still reads
+ * the session off disk and still throws `NotLoggedIn`, including when the stored
+ * access token has already expired, so the 401 boundary is unchanged. A single
+ * companion request building a single client is not the defect; a client per
+ * request forever, beside the daemon's, is.
+ *
+ * ═══ READ AT CALL TIME, NEVER CACHED. ═══ `POST /api/login` signs in and then
+ * takes the deferral decision above, which on the no-daemon branch starts
+ * presence. A companion that resolved this once at startup would hold the
+ * pre-login null for the life of the process and go on building its own clients
+ * after the very moment presence became available to share. The login path also
+ * reassigns `companionRefreshing`, so caching would freeze the boot decision
+ * too, past a sign-in that legitimately changed it.
+ *
+ * Exported so the rule above is what a test holds: with no presence running it
+ * falls through to `getClient()`, refreshing only when no other `cs` process on
+ * this machine is, and lets `NotLoggedIn` out rather than softening it into a
+ * null, which is the half of the behaviour reachable without a real session and
+ * a live network.
+ */
+export async function requestClient() {
+    return liveClient() ?? (await getClient({ refreshing: companionRefreshing }));
+}
 async function handle(req, res, token) {
     if (!allowedHost(req.headers.host)) {
         res.writeHead(421, { 'Content-Type': 'text/plain' }).end('Misdirected request.');
@@ -203,12 +342,16 @@ async function handle(req, res, token) {
     res.writeHead(404, { 'Content-Type': 'text/plain' }).end('Not found');
 }
 async function handleApi(req, res, path, query) {
+    // Nothing here is served until this boot's refresh decision is in, so no
+    // request can be answered by a client built from the `true` initializer on a
+    // machine where a daemon is the one refreshing. See `refreshDecided`.
+    await refreshDecided;
     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;
+                email = (await (await requestClient()).auth.getUser()).data.user?.email ?? null;
             }
             catch { /* stale/expired session reads as signed out */ }
         }
@@ -232,12 +375,9 @@ async function handleApi(req, res, path, query) {
         }
         try {
             const result = await signIn(email, password);
-            try {
-                await startPresence();
-            }
-            catch (err) {
+            await startPresenceUnlessDaemonServes((err) => {
                 console.warn(`Presence did not start after sign-in: ${err.message}`);
-            }
+            });
             json(res, 200, { ok: true, email: result.email });
         }
         catch (err) {
@@ -248,7 +388,27 @@ async function handleApi(req, res, path, query) {
     if (req.method === 'POST' && path === '/api/logout') {
         // Logout also unregisters ctrl-spc from the detected agents (Phase 3), so no
         // dead server entry is left behind for the next agent run.
-        await stopPresence({ markOffline: true, unregister: true });
+        if (isPresenceRunning()) {
+            await stopPresence({ unregister: true });
+        }
+        else {
+            /* ═══ A COMPANION THAT DEFERRED TO A DAEMON STILL HAS TO UNREGISTER. ═══
+               `stopPresence` returns early when this process holds no presence
+               (`presence.ts:603-604`), so without this branch logout would delete
+               `session.json` and leave the `ctrl-spc` entry in Claude's and Codex's
+               configs pointing at a server whose session is gone.
+      
+               Only the unregistration is copied, deliberately. The other two things
+               `stopPresence` does belong to a process that owns them, and this one
+               owns neither: the running tools server is the daemon's, and the daemon
+               still owns and heartbeats `cliv2_agents`. Stamping `stopped_at` from
+               here would mark a machine offline that is genuinely online. */
+            const agents = detectAgents();
+            if (agents.includes('claude'))
+                void unregisterFromClaude();
+            if (agents.includes('codex'))
+                void unregisterFromCodex();
+        }
         clearSession();
         json(res, 200, { ok: true });
         return;
@@ -256,7 +416,7 @@ async function handleApi(req, res, path, query) {
     // Everything below needs a signed-in session.
     let client;
     try {
-        client = await getClient();
+        client = await requestClient();
     }
     catch (err) {
         if (err instanceof NotLoggedIn) {

package/dist/daemon-lock.js

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configDir } from './config.js';
+import { processIsAlive } from './win-shell.js';
+/**
+ * One `cs start` per config dir.
+ *
+ * Two daemons on one machine share one `cliv2_agents` row and take turns
+ * overwriting it every heartbeat. The case that produced it: `cs start` was
+ * running, `npm i -g` replaced dist under it, and a second `cs start` came up
+ * on the new code. The row then flipped between 0.7.0 and 0.7.4 every few
+ * seconds and the Machines popover flickered with it.
+ *
+ * Keyed on the config dir, not the machine id, so the documented two-instance
+ * setup (`CTRL_SPC_V2_CONFIG_DIR` plus `CTRL_SPC_V2_MACHINE_ID`) still works.
+ *
+ * ponytail: a pid file, not an OS lock. A pid recycled onto an unrelated
+ * process after a crash reads as "already running" until that process exits;
+ * `rm ~/.config/ctrl-spc-v2/daemon.pid` is the way out. Upgrade to an
+ * exclusive-open lock if that is ever hit in practice.
+ */
+function lockPath() {
+    return join(configDir(), 'daemon.pid');
+}
+/** Claims the lock for this process, or returns the pid of the daemon that holds it. */
+export function claimDaemonLock() {
+    const path = lockPath();
+    if (existsSync(path)) {
+        const pid = Number(readFileSync(path, 'utf8').trim());
+        if (Number.isInteger(pid) && pid > 0 && pid !== process.pid && processIsAlive(pid)) {
+            return { held: true, pid };
+        }
+    }
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(path, String(process.pid));
+    return { held: false };
+}
+/** Removes the lock if this process wrote it. Never throws: it runs during shutdown. */
+export function releaseDaemonLock() {
+    try {
+        const path = lockPath();
+        if (Number(readFileSync(path, 'utf8').trim()) === process.pid)
+            rmSync(path);
+    }
+    catch {
+        // no lock, or not ours
+    }
+}

package/dist/daemon.js

@@ -1,5 +1,6 @@
 import { ensureAutostart } from './autostart.js';
-import { startPresence, stopPresence } from './presence.js';
+import { claimDaemonLock, releaseDaemonLock } from './daemon-lock.js';
+import { liveClient, startPresence, stopPresence } from './presence.js';
 /* ═══ THE ONE IMPORT ANYTHING OUTSIDE `panel3/` MAKES INTO IT. ═══ Named in
    `.implementations/19-agent-panel-v3/conventions.md` and enforced by
    `test/panel3-isolation.contract.test.mjs`, whose MOUNTS map allows this file
@@ -28,14 +29,87 @@ import { startPanel } from './panel3/run.js';
  * starts doing the right thing with nothing else typed.
  */
 export async function runDaemon() {
+    /* One daemon per config dir. See daemon-lock.ts for the flicker this stops.
+       Exits rather than replacing the holder: under launchd's KeepAlive a
+       replacement would be restarted and would then replace the replacer. */
+    const lock = claimDaemonLock();
+    if (lock.held) {
+        console.error(`cs start is already running on this computer (pid ${lock.pid}). Stop it first to start another.`);
+        process.exitCode = 1;
+        return;
+    }
     ensureAutostart(); // default-on: install the login item unless the user opted out
-    const { machineName, agents, client } = await startPresence();
-    const panel = startPanel(client);
+    const { machineName, agents } = await startPresence();
+    /* ═══ THE PANEL READS PRESENCE'S CLIENT, IT IS NOT HANDED A COPY OF IT. ═══
+       `startPresence` used to return the client it had just built and this line
+       passed that value to `startPanel`, which held it for the process's life. The
+       heartbeat's catch block REBUILDS that client when `session.json` comes to
+       hold a different refresh token, and since the rebuild guard landed a
+       successful rebuild is the normal path rather than a throw. The value handed
+       over here was therefore a client the database refuses and nobody watches,
+       while the panel's two-second poll went on writing `panel3_machines` with it.
+       That table took 37,051 writes in the incident window, the largest single
+       share of it.
+       `liveClient` is presence's own accessor, so the panel asks the module that
+       owns the presence lifecycle rather than being told once. It cannot answer
+       null here: `startPresence` has returned, so presence is running. */
+    /* ═══ AND THE LAST CLIENT IT SAW IS KEPT, FOR THE ONE READ THAT HAPPENS AFTER
+       PRESENCE HAS ALREADY STOPPED. ═══ `startPanel` returns `stop: () =>
+       stopListening(current(), ...)`, and `current()` is evaluated in the arrow,
+       BEFORE `stopListening` is entered, so `stopListening`'s own best-effort
+       try/catch cannot cover it. On `SIGNED_OUT` both watchers are bound to this
+       same client and auth-js runs them in registration order: presence's fires
+       first and `stopPresence` sets its module singleton to null synchronously,
+       so by the time the daemon's watcher reaches `shutdown` -> `panel.stop()`
+       the getter below has nothing live to answer with. Throwing there is a throw
+       inside `shutdown` before its first await, which `void shutdown(1)` does not
+       contain: `panel3_machines.stopped_at` never gets written, the card goes on
+       saying an agent is working, `Promise.all` rejects, `process.exit` is never
+       reached, and the panel's `for(;;)` spins on a caught-and-logged failure
+       every two seconds forever. launchd's `KeepAlive` cannot help a process that
+       never exits. `shutdown()` must reach `process.exit` on every path.
+  
+       THE FALLBACK IS THE LAST CLIENT PRESENCE ITSELF HELD, not the one it built
+       at startup: a rebuild replaces `p.client`, and a goodbye written with the
+       pre-rebuild snapshot is the same refused write this branch exists to stop.
+       Recording it on every successful read is what keeps it current without a
+       second subscription to the presence lifecycle.
+  
+       THE THROW IS NOT WEAKENED FOR THE POLL, and that is the point of ordering
+       the two lines this way. A poll only reaches the fallback once presence has
+       stopped, which in this process means a shutdown is already in flight and
+       the exit is milliseconds away; every other poll, for the whole life of the
+       daemon, reads a live client or fails loudly exactly as before. What the
+       fallback buys is the goodbye write, which `stopListening` documents as
+       best-effort precisely because it is the last thing this process does.
+  
+       THE ONE THING THAT WINDOW COSTS, NAMED RATHER THAN LEFT TO BE REDISCOVERED:
+       a poll landing in it used to throw at the getter and be swallowed by the
+       per-poll catch, so it could not write at all. Now it takes the fallback and
+       reaches `sayListening`, whose upsert deliberately sends `stopped_at: null`
+       on every poll, since that is what lets a restarted daemon come back on a row
+       stamped as gone. If such a poll's write lands AFTER `stopListening`'s stamp,
+       it erases the goodbye and the row reads listening again. That is bounded and
+       self-healing: `LISTENING_WINDOW_MS` is 15s, so the freshness check calls the
+       machine gone 15 seconds later whatever the column says, and the process is
+       already exiting. Not worth a second seam to close, and worth knowing about
+       if a machine is ever seen lingering for a few seconds after `cs start` ends. */
+    let lastKnownClient = liveClient();
+    const panel = startPanel(() => {
+        const live = liveClient();
+        if (live) {
+            lastKnownClient = live;
+            return live;
+        }
+        if (!lastKnownClient)
+            throw new Error('the presence loop is not running, so there is no session to work through');
+        return lastKnownClient;
+    });
     console.log(`CTRL+SPC — this computer: ${machineName}`);
     console.log(`Agents detected: ${agents.length ? agents.join(', ') : 'none'}`);
     console.log('Online. Heartbeating presence and answering cards. Ctrl-C to stop.');
     let stopping = false;
-    async function shutdown() {
+    async function shutdown(code = 0) {
         if (stopping)
             return;
         stopping = true;
@@ -47,11 +121,45 @@ export async function runDaemon() {
            so the panel's own signal handling stands down when it is started from
            here (see `run()`). Both are best-effort and neither throws, which is why
            they can settle together. */
-        await Promise.all([panel.stop(), stopPresence({ markOffline: true })]);
-        process.exit(0);
+        await Promise.all([panel.stop(), stopPresence()]);
+        releaseDaemonLock();
+        process.exit(code);
     }
     process.on('SIGINT', () => void shutdown());
     process.on('SIGTERM', () => void shutdown());
+    /* ═══ AND THE PANEL GOES DOWN WITH THE SESSION TOO. ═══ presence.ts stops its
+       own three loops on `SIGNED_OUT`, which leaves this process holding a panel
+       that would go on upserting `panel3_machines` every few seconds with a token
+       the database refuses. It shares this client, so it hears the same event: one
+       shutdown, both halves, and the exit says the daemon needs a person rather
+       than pretending it is still online. Non-zero because this is a failure, not
+       a Ctrl-C. The login item's `KeepAlive` restarts either way, and that is the
+       point: a restart refuses at `getClient` after one refresh attempt and exits
+       again, so an unattended machine retries on launchd's throttle instead of
+       polling four times a second forever. */
+    /* ═══ BOUND TO WHATEVER CLIENT IS LIVE AT THIS INSTANT, WHICH IS WHY IT IS
+       READ AND NOT CAPTURED. ═══ This used to bind to the client `startPresence`
+       returned. A rebuild replaces that client, and presence re-binds its OWN
+       watcher to the replacement (`bindSignedOutWatcher`) while this one would
+       stay on the discarded client, where `SIGNED_OUT` can never fire again. That
+       leaves the daemon's half of the shutdown deaf for the rest of the process.
+       Reading it here binds to the current one; a client rebuilt LATER is
+       presence's watcher to carry, and that one calls `stopPresence`, which clears
+       the intervals this process depends on. This is not a second terminal stop,
+       it is the same one bound to a client that exists.
+  
+       THE NULL IS THROWN ON RATHER THAN SKIPPED, matching the getter above. `?.`
+       would read as though no client were an expected state, and it is not:
+       `startPresence` has returned, so presence is running. Worse, it would
+       silently drop half the shutdown in exactly the state it claims to guard
+       against, leaving a daemon that answers a dead session by doing nothing. */
+    const live = liveClient();
+    if (!live)
+        throw new Error('the presence loop is not running, so there is no session to watch');
+    live.auth.onAuthStateChange((event) => {
+        if (event === 'SIGNED_OUT')
+            void shutdown(1);
+    });
     // Keep the event loop alive.
     await new Promise(() => { });
 }

package/dist/firewall.js

@@ -0,0 +1,95 @@
+/**
+ * ═══ THE WEB FIREWALL IN FRONT OF THE DATABASE. ═══
+ *
+ * Supabase puts a Cloudflare web application firewall in front of PostgREST.
+ * When a request body carries text its pattern matcher reads as an injection
+ * payload, the edge answers 403 with a 4.5 KB HTML block page, the row is never
+ * written, and — because of how the database client handles a non-JSON error
+ * body — that entire page arrives as `error.message`.
+ *
+ * WHAT THE CLIENT ACTUALLY HANDS BACK, established by reading its source rather
+ * than inferred: the promise RESOLVES, `error` is `{ message: <the whole page> }`
+ * with no `code`, `details` or `hint`, and the 403 status is real but is thrown
+ * away by both of this package's error guards, which destructure only the data
+ * and the error. So recognition is on the body. There is no other option here
+ * short of changing every call site of both guards.
+ *
+ * THE PHRASES BELOW WERE CAPTURED FROM A REAL REFUSAL, not paraphrased from
+ * memory. One request carrying the shape the incident report describes was sent
+ * to this project's REST endpoint with no credentials; the firewall answers
+ * ahead of authentication, so the page is reproducible at will and costs
+ * nothing. Inventing the markers and the test fixture from the same paraphrase
+ * would have agreed with itself and matched nothing in production.
+ *
+ * WHY THE RAY IDENTIFIER SURVIVES when the rest of the page does not. Supabase
+ * exposes no control over this firewall on any plan: no dashboard setting, no
+ * management endpoint, no documented exception procedure. The one route to a
+ * rule exclusion is a support ticket, and that ticket needs the ray identifier
+ * of a real refusal. It appears in the page body and in a response header, and
+ * the header is not visible where this runs. Discard the page and keep twelve
+ * characters, or the only copy anyone ever holds is gone.
+ *
+ * THE FALLBACK IS TO CHANGE NOTHING. A message this does not recognise is
+ * returned byte for byte, so an ordinary database failure still reads exactly as
+ * it does today, and if Cloudflare rewords the page one day the caller is back
+ * to the behaviour that prompted this work rather than to a new wrong one.
+ */
+/** The heading, the sub-line and the footer element of the block page, exactly
+ *  as captured. The title says "Attention Required", which a CHALLENGE page also
+ *  says, so the title is deliberately not one of these: a challenge is not a body
+ *  problem and telling somebody to reword their document would be a lie. */
+const BLOCK_PAGE_MARKERS = ['you have been blocked', 'you are unable to access', 'cf-error-details'];
+/** `Cloudflare Ray ID: ` then the identifier, wrapped in a tag on the real page. */
+const RAY_ID = /cloudflare ray id:\s*(?:<[^>]*>\s*)*([0-9a-f]{8,})/i;
+/**
+ * What a caller reads instead of the block page.
+ *
+ * It says REQUEST rather than body, and makes the advice conditional, because
+ * both guards this passes through carry more reads than writes and one of them
+ * also sits behind the commands a person types. Telling somebody who ran a read
+ * to reword their document would be worse than the HTML.
+ */
+function refusalSentence(rayId) {
+    const reference = rayId ? ` (Cloudflare ray ${rayId})` : '';
+    return ('the firewall in front of the database refused this request because something in it reads as ' +
+        'attack-shaped text; if you were saving a document, reword the part that reads like an injection ' +
+        `and try again${reference}`);
+}
+/**
+ * Translate a database error message, leaving anything that is not the
+ * firewall's block page exactly as it was.
+ *
+ * Takes and returns a string so every call site is one call and nothing has to
+ * learn a new shape. Callers keep their own `could not <verb> <subject>: ` or
+ * `<tool> failed: ` prefix, so the operation that failed is still named.
+ */
+export function readableWriteError(message) {
+    const lowered = message.toLowerCase();
+    const isBlockPage = message.trimStart().startsWith('<') &&
+        lowered.includes('cloudflare') &&
+        BLOCK_PAGE_MARKERS.some((marker) => lowered.includes(marker));
+    if (!isBlockPage)
+        return message;
+    return refusalSentence(RAY_ID.exec(message)?.[1]);
+}
+/**
+ * Taught VERBATIM in the description of every tool that writes a body, and in
+ * the standing instructions of both agent surfaces, for the reason the citation
+ * teaching constant in mcp.ts records: a convention that lives in only one
+ * description is a convention half the flows never see.
+ *
+ * EVERY SHAPE IS NAMED IN WORDS AND NONE IS DEMONSTRATED. This paragraph is not
+ * only read by agents, it is WRITTEN THROUGH THE FIREWALL IT DESCRIBES — into
+ * the stored brief on every start and every dispatch. A worked example here
+ * would refuse every brief write and stop the product from starting anything.
+ */
+export const FIREWALL_WRITING_RULE = 'This body is saved through a web firewall that refuses text shaped like an attack. Keep out of it: ' +
+    'query fragments that read as database injection, such as a quoted value closed early and followed by ' +
+    'an always-true comparison, a set-combining select, or a statement that drops a table; shell injection, ' +
+    'such as a pipe or semicolon followed by a command name, a command inside backticks, or a command inside ' +
+    'a dollar-parenthesis substitution; an interpolation placed next to a call that executes or matches a ' +
+    'string; script-carrying links and inline error or load handlers on a tag; repeated parent-directory ' +
+    'steps in a path; and template expressions wrapping a call in double braces or in a dollar-brace. When ' +
+    'you must describe one of these, describe it in words rather than writing it out. If a save comes back ' +
+    'refused by the firewall, that is why: reword the body, do not retry it unchanged, and do not write ' +
+    'around the tool.';