@ctrl-spc/cs 0.7.3 → 0.7.5

package/dist/mcp.js

@@ -14,7 +14,12 @@ import { z } from 'zod';
 import { TOOLS_SERVER_PORT, SESSION_TTL_MS } from './env.js';
 import { agentPath } from './agents.js';
 import { mcpToken, readMcpToken, readSession } from './config.js';
-import { readPngScreenshot, } from './screenshots.js';
+import { readableWriteError, FIREWALL_WRITING_RULE } from './firewall.js';
+/* The path rule itself, moved out so `workflows.ts` can ask the same question
+   before it builds a workflow. `refuseAbsolutePaths` below is still v2's own
+   wrapper: it is the one that answers in a `CallToolResult`. */
+import { ABSOLUTE_PATH_RE, absolutePathToken } from './local-paths.js';
+import { readPngScreenshot, screenshotArtifactId, screenshotRequestId, } from './screenshots.js';
 /* 18c Slice 7 correction: the product captures the PNG itself, because a
    spawned worker has no reachable way to run a capture command. The whole
    argument is on `captureUrlScreenshot`. */
@@ -239,7 +244,7 @@ function validateGrounding(value) {
 async function must(query) {
     const { data, error } = await query;
     if (error)
-        throw new Error(error.message);
+        throw new Error(readableWriteError(error.message));
     return data;
 }
 /** The message of a thrown value, WITHOUT assuming it is an `Error`. `(err as
@@ -987,50 +992,6 @@ const SCREENSHOT_PLATFORM_LABEL = {
 function attachScreenshotFailure(title, reason, created = 'artifact') {
     return errorResult(`Couldn’t attach "${title}": ${reason}. No ${created} was created.`);
 }
-/** 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)}`;
-}
 function isDuplicateStorageObject(error) {
     return /duplicate|already exists|resource exists/i.test(`${error.message} ${error.error ?? ''} ${error.name ?? ''}`);
 }
@@ -2058,11 +2019,8 @@ async function resolvePlacementTarget(client, table, noun, id, projectId) {
  * `epic_id` / `sprint_id` since 20260727080000 — with the fresh row's
  * revision, so the CAS contract is honored rather than bypassed.
  *
- * Sequencing fix: the create RPC's own position (min-1, top of backlog) is
- * right for a single human quick-add but inverts an agent-authored sequence,
- * so the placement pass runs for EVERY creation and moves the task to the
- * project's max(position)+1 — creation order equals board order. The
- * `position` key rides the same save_task_if_current p_changes whitelist.
+ * The create_task RPC appends at the bottom of the backlog, so creation order
+ * equals board order with no follow-up write.
  */
 export async function createTaskHandler(client, userId, currentSession, args, 
 /** 18c Slice 6: the request THIS CONNECTION is working. See
@@ -2083,25 +2041,6 @@ connectionTodoId = null) {
             if (!sprint.ok)
                 return sprint.error;
         }
-        // Feature 32 sequencing: the create_task RPC assigns position = min-1 (top
-        // of backlog — right for a single human quick-add), so N sequential agent
-        // creates would render NEWEST-FIRST on the board, inverting the skeleton's
-        // sequence. Read the project's current max position BEFORE the create so
-        // the placement pass below can APPEND the fresh task at max+1 — for every
-        // creation, placed or not, so creation order equals board order.
-        // (save_task_if_current's p_changes whitelist accepts `position`.) A
-        // concurrent-agent race on max+1 costs at worst an adjacent swap.
-        const maxPositionRow = await must(client
-            .from('tasks')
-            .select('position')
-            .eq('project_id', args.project_id)
-            .is('archived_at', null)
-            .order('position', { ascending: false })
-            .limit(1)
-            .maybeSingle());
-        const nextPosition = (typeof maxPositionRow?.position === 'number' && Number.isFinite(maxPositionRow.position)
-            ? maxPositionRow.position
-            : 0) + 1;
         const taskId = await must(client.rpc('create_task', {
             p_project: args.project_id,
             p_name: args.name,
@@ -2113,37 +2052,37 @@ connectionTodoId = null) {
         let task = await fetchTask(client, taskId);
         if (!task)
             throw new Error('Created task could not be re-fetched.');
-        // Place the fresh task on the board: append it at the project's max+1
-        // position (EVERY create — see the sequencing note above), plus its
-        // epic/sprint when given. The task row is COMMITTED by this point, so a
-        // placement failure is surfaced as a warning on the real result —
-        // reporting it as a failed create would make the agent retry and
-        // duplicate the task (the create_product_idea read-back lesson).
+        // Place the fresh task in its epic/sprint when either was given. The task
+        // row is COMMITTED by this point, so a placement failure is surfaced as a
+        // warning on the real result: reporting it as a failed create would make
+        // the agent retry and duplicate the task (the create_product_idea
+        // read-back lesson).
         let placementWarning;
-        try {
-            const revision = task.revision;
-            if (typeof revision !== 'number' || !Number.isInteger(revision) || revision < 1) {
-                throw new Error('the created task carried no usable revision');
+        if (args.epic_id !== undefined || args.sprint_id !== undefined) {
+            try {
+                const revision = task.revision;
+                if (typeof revision !== 'number' || !Number.isInteger(revision) || revision < 1) {
+                    throw new Error('the created task carried no usable revision');
+                }
+                await must(client.rpc('save_task_if_current', {
+                    p_task_id: taskId,
+                    p_expected_revision: revision,
+                    p_changes: {
+                        ...(args.epic_id !== undefined ? { epic_id: args.epic_id } : {}),
+                        ...(args.sprint_id !== undefined ? { sprint_id: args.sprint_id } : {}),
+                    },
+                    p_tag_ids: null,
+                    p_reorder: false,
+                    p_before_task_id: null,
+                }));
+                task = (await fetchTask(client, taskId)) ?? task;
+            }
+            catch (err) {
+                placementWarning =
+                    `The task was created (id ${taskId}) but placing it on the board (its epic/sprint) failed: ` +
+                        `${errorMessage(err)}. Do NOT create the task again; report the failed placement, ` +
+                        'a human can place it from the board.';
             }
-            await must(client.rpc('save_task_if_current', {
-                p_task_id: taskId,
-                p_expected_revision: revision,
-                p_changes: {
-                    position: nextPosition,
-                    ...(args.epic_id !== undefined ? { epic_id: args.epic_id } : {}),
-                    ...(args.sprint_id !== undefined ? { sprint_id: args.sprint_id } : {}),
-                },
-                p_tag_ids: null,
-                p_reorder: false,
-                p_before_task_id: null,
-            }));
-            task = (await fetchTask(client, taskId)) ?? task;
-        }
-        catch (err) {
-            placementWarning =
-                `The task was created (id ${taskId}) but placing it on the board (its position/epic/sprint) failed: ` +
-                    `${errorMessage(err)}. Do NOT create the task again — report the failed placement; ` +
-                    'a human can place it from the board.';
         }
         // D2a attribution: if this connection has an open session, record that the
         // session produced this NEW task — one cliv2_agent_outputs row referencing the
@@ -6071,19 +6010,6 @@ const MAX_PROPOSALS = 50;
  *  make a legal document un-acceptable — so the BATCH is what is bounded, which
  *  is the thing that actually protects the write. */
 const MAX_PROPOSAL_BATCH_CHARS = 400_000;
-/** Absolute in any form a repo path can arrive in: POSIX (`/etc`), UNC and
- *  root-relative Windows (`\\server\share`, `\Users\Lane\repo`), Windows
- *  drive-letter (`C:\repo`, `C:/repo`) and drive-RELATIVE (`C:AGENTS.md`, which
- *  resolves against that drive's current directory and still discloses a local
- *  layout). One leading separator of EITHER kind, or any drive letter, is
- *  enough — a single leading backslash is a Windows absolute path just as `/`
- *  is a POSIX one.
- *
- *  `cliv2_work_reservations_path_relative`
- *  (20260722160000_cliv2_coordination.sql) is the same rule for the same
- *  reason, and it has the narrower form with both of those holes. That is a
- *  pre-existing bug on that table, not a licence to repeat it here. */
-const ABSOLUTE_PATH_RE = /^(?:[\\/]|[A-Za-z]:)/;
 /** A `..` segment under either separator. A relative path that climbs out of
  *  the scanned repo names a file the scan had no business reading, and it is
  *  refused for the same privacy reason an absolute path is. */
@@ -7698,220 +7624,6 @@ const STEP_SOURCE_KINDS = ['workflow', 'plan'];
  *  sets the opening value; `update_step` writes every transition after it —
  *  including 'done', which is the only one `cliv2_steps_up_next` advances on. */
 const STEP_STATUSES = ['pending', 'in_progress', 'blocked', 'interrupted', 'done'];
-/** Decode the HTML entities a browser would decode, so the guard scans what
- *  the USER will eventually read rather than what the agent happened to type.
- *  Without this, `&#47;Users&#47;lane&#47;x` sails past every scan and then
- *  `interactiveArtifactHtml()` — which parses with DOMParser — paints the
- *  real absolute path into hosted browser JS. The guard and the renderer must
- *  agree about what a string SAYS; entities are exactly where they diverge.
- *  Numeric (decimal and hex) plus the small set of named entities that can
- *  spell a path separator or a drive colon. */
-const NAMED_ENTITIES = {
-    sol: '/',
-    bsol: '\\',
-    colon: ':',
-    period: '.',
-    lowbar: '_',
-    quot: '"',
-    apos: "'",
-    amp: '&',
-    lt: '<',
-    gt: '>',
-};
-/* The trailing `;` is OPTIONAL for numeric entities, because browsers accept
-   it that way: `&#47Users` renders as `/Users`. A guard that required the
-   semicolon allowed exactly that string through while the renderer painted a
-   real path — found by differentially testing this function against jsdom's
-   DOMParser, which is the same parser interactiveArtifactHtml() uses. Named
-   entities keep the required `;` (that is what browsers do outside a short
-   legacy list, and dropping it would eat `&sole` in ordinary prose). */
-function decodeEntities(text) {
-    return text.replace(/&(?:(#[Xx][0-9A-Fa-f]+|#\d+);?|([A-Za-z][A-Za-z0-9]*);)/g, (whole, numericBody, namedBody) => {
-        const body = numericBody ?? namedBody ?? '';
-        if (body.startsWith('#')) {
-            const code = body[1] === 'x' || body[1] === 'X'
-                ? Number.parseInt(body.slice(2), 16)
-                : Number.parseInt(body.slice(1), 10);
-            return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
-        }
-        // Named entities are case-SENSITIVE in HTML: `&Colon;` is U+2237 (∷), not
-        // a colon, so lower-casing here refused text the browser never renders as
-        // a path. Exact match only.
-        const named = NAMED_ENTITIES[body];
-        return named ?? whole;
-    });
-}
-/**
- * The first absolute local path inside `text`, or null.
- *
- * THE DESIGN, and why it is not the previous one. This helper used to split
- * the text into tokens on a separator list and test each token. Three review
- * rounds each answered a leak by adding characters to that list (`(,=;`, then
- * `<>"'`), and the third round proved the approach is wrong rather than
- * incomplete: a quote *inside* a path (`/'Users/lane/x`, `/Users/lane/Lane's
- * Docs/x`) SPLIT the path into fragments, none of which starts with a root
- * marker — so widening the separator list to catch markup simultaneously
- * opened a hole for paths containing that markup, and the refusal message for
- * a legitimate apostrophe path named a truncated path that did not exist.
- * Separators cannot both be inside and outside the thing being matched.
- *
- * So: do not tokenise. SCAN for the path shape itself, anchored at a root
- * marker, and let the match end where a character that cannot appear in a
- * path appears. A path is a match, not a token. The exclusions below are the
- * genuine false positives, tested against the same corpus as before:
- *
- *   - a URL's authority (`https://host/path`) is not a local path — a match
- *     immediately preceded by `//` of a non-`file:` scheme is skipped, while
- *     `file:///Users/…` IS reported (its body is a real local path);
- *   - a bare drive label `A:` with no path body is a list marker;
- *   - a single-segment `/word` (`/dashboard`, `/api/`) is a URL path — local
- *     paths in prose always carry a second separator.
- *
- * Entities are decoded first (see `decodeEntities`), because the renderer
- * decodes them too.
- */
-/* The scan finds the path SHAPE anywhere in the text and decides what it is
-   from WHAT MATCHED, not from what precedes it.
- *
- * A previous round anchored this with a lookbehind excluding "characters a
- * path cannot follow". That was the separator-list mistake one layer down: the
- * exclusion set is itself a character list, and every character in it became a
- * hiding place. `~/Users/lane/x`, `x./Users/lane/x` and a path embedded in a
- * URL all leaked, and `~/…` is an entirely ordinary thing for an agent to
- * write. A rule that says "not after these characters" can always be defeated
- * by writing one of them first.
- *
- * So there is no lookbehind. Instead the two genuine false positives are
- * excluded by structure, below:
- *   - a repo-relative path (`web/src/App.tsx`) never starts at a root marker,
- *     so requiring the match to BEGIN with `/`, `\\` or `C:` already excludes
- *     it — `/src/App.tsx` inside it is only reachable mid-token, which the
- *     single-segment and second-separator rules then handle;
- *   - a URL's authority is recognised by its own scheme, checked explicitly.
- *
- * `'` and `"` are NOT body terminators — a quote inside a path is exactly the
- * case that made the separator-splitting design leak. */
-const ABSOLUTE_PATH_SCAN = /(?:[A-Za-z]:[\\/'"]|\\\\|\/)[^\s<>`(){}\[\],;|&*?\n\r\t]*/g;
-/* The POSIX roots that actually hold a user's files. A leading `/` alone does
-   NOT make a machine path — `/api/items`, `/img/logo.png` and `/dashboard` are
-   site paths, and an agent's panel is full of them (href, src, srcset, CSS
-   url()). Refusing those would make the house style unusable and agents would
-   route around the guard, which is worse than a narrower rule. These roots are
-   the ones whose contents are private to the machine. */
-const POSIX_MACHINE_ROOT = /^\/(?:Users|home|root|var|etc|opt|srv|private|tmp|mnt|media|Volumes|Applications|Library|System|usr\/local|dev)(?:\/|$)/i;
-/** A machine path buried inside a longer match — the segment of a remote URL
- *  that spells one (`https://host/x/Users/lane/secret.txt`). The scan's body
- *  is greedy, so such a path never gets a match of its own; it has to be dug
- *  out of the match that swallowed it. Rendered in front of a viewer, it
- *  discloses exactly what bare text would. */
-function buriedMachinePath(candidate) {
-    // A Windows path can be buried too — `https://host/xC:\Users\Lane\x` — and
-    // it does not begin at a `/`, so scanning only slash positions missed it.
-    // Shape, not just a colon-slash: a drive letter, a separator, then at least
-    // one real segment. `a:/b` in a URL query is not a Windows path; the `\` or
-    // a `Users`-style segment is what makes it one. Requiring a BACKSLASH
-    // separator keeps this narrow — a forward-slash drive path (`C:/x`) inside a
-    // URL is indistinguishable from an ordinary URL fragment, and the POSIX pass
-    // below already covers the roots that matter.
-    const drive = /[A-Za-z]:\\[^\s<>"'`]+/.exec(candidate);
-    if (drive)
-        return candidate.slice(drive.index);
-    for (let at = candidate.indexOf('/'); at !== -1; at = candidate.indexOf('/', at + 1)) {
-        const tail = candidate.slice(at);
-        if (POSIX_MACHINE_ROOT.test(tail))
-            return tail;
-    }
-    return null;
-}
-function absolutePathToken(text) {
-    const decoded = decodeEntities(text);
-    // `file:///Users/lane/x` is a local path wearing a URL. Handle it up front
-    // and by NAME, rather than leaving the generic scan to reason about where a
-    // scheme ends — that reasoning is what produced two of this function's bugs.
-    const fileUrl = /\bfile:\/\/(\/\S*)/i.exec(decoded);
-    if (fileUrl && POSIX_MACHINE_ROOT.test(fileUrl[1]))
-        return fileUrl[1];
-    ABSOLUTE_PATH_SCAN.lastIndex = 0;
-    let match;
-    while ((match = ABSOLUTE_PATH_SCAN.exec(decoded)) !== null) {
-        // Trailing wrapping punctuation belongs to the prose, not the path:
-        // `("/Users/lane/x.md")` and `see /Users/lane/x.md.` both end early.
-        const candidate = match[0].replace(/["')\].,:;]+$/, '');
-        if (!candidate || !ABSOLUTE_PATH_RE.test(candidate))
-            continue;
-        const before = decoded.slice(0, match.index);
-        // A URL: skip its authority and its ordinary path — `https://host/a/b`
-        // matches at `//host/a/b` and again at `/b`, and neither is a local path.
-        // The scheme identifies it, so look for the scheme rather than testing the
-        // character immediately before. (`file:` never reaches here; it is handled
-        // by name above.)
-        //
-        // EXCEPT when the URL's path is itself rooted at a machine root. A remote
-        // URL spelling `…/x/Users/lane/private/secret.txt` puts that path in front
-        // of a viewer just as plainly as bare text does, and the contract is about
-        // the string reaching hosted browser JS, not about how it got there. A
-        // false alarm costs the agent one retry; a leak is permanent, so this errs
-        // toward refusing.
-        if (/([A-Za-z][A-Za-z0-9+.-]*):\/\/\S*$/.test(before) && !POSIX_MACHINE_ROOT.test(candidate)) {
-            const buried = buriedMachinePath(candidate);
-            if (buried)
-                return buried;
-            continue;
-        }
-        // `https://host/x` also matches AT the scheme's own `s://…`, which reads
-        // as a one-letter drive. A real drive letter is followed by a separator
-        // and then a path segment — never by `//`. Before discarding it, check
-        // whether a machine root is buried INSIDE: the scan's body is greedy, so
-        // `s://example.com/x/Users/lane/x` is one match and the `/Users/…` inside
-        // it never gets a match of its own. A remote URL spelling a machine path
-        // discloses it to a viewer just as plainly as bare text does.
-        if (/^[A-Za-z]:\/\//.test(candidate)) {
-            const buried = buriedMachinePath(candidate);
-            if (buried)
-                return buried;
-            continue;
-        }
-        // A CONTINUATION of a relative path: `web/src/App.tsx` matches at
-        // `/src/App.tsx`, which is not a local path — the token it belongs to
-        // began with a bare word. Walk back to the start of the whole token and
-        // ask what IT begins with. This is deliberately not "is the preceding
-        // character in a set": `~/Users/lane/x` and `x./Users/lane/x` both have a
-        // path-ish character before the slash, and both DO carry a real absolute
-        // path, so a character test leaks them. Reading the token's own first
-        // character answers correctly in every one of those cases.
-        // The token runs back to whitespace OR a markup boundary (`<>"'=`) — a
-        // quote or a tag bracket ends the token even though it is not whitespace,
-        // which is what lets `class="mono">/Users/…` be seen as a path rather than
-        // as the tail of the token `class`.
-        // Only a token that is itself a plausible RELATIVE PATH suppresses the
-        // match — `web/src` in `web/src/App.tsx`. A bare word (`x.`), a number
-        // (`1`), or anything not shaped like a path segment does not, because
-        // `x./Users/lane/x` and `1/Users/lane/x` still carry a real absolute path.
-        const tokenStart = /([^\s<>"'=]+)$/.exec(before)?.[1] ?? '';
-        if (/^[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9._-]+)*\/?$/.test(tokenStart)
-            && tokenStart.includes('/')
-            && !POSIX_MACHINE_ROOT.test(candidate))
-            continue;
-        if (/^[A-Za-z]:$/.test(candidate))
-            continue;
-        // A POSIX candidate is only a MACHINE path if it starts at a real root.
-        // `/img/x.png`, `/api/items`, `/dashboard` and `2026/07/31` are site paths
-        // and dates — they are not local paths, they are the ordinary content of
-        // an agent's panel (CSS urls, hrefs, srcset), and refusing them makes the
-        // house style unusable. The roots below are the ones that actually carry a
-        // user's files; a path under any of them is refused, everything else is
-        // left alone. Windows (`C:\…`) and UNC (`\\host\share`) are unambiguous by
-        // construction and are not filtered here.
-        // Strip a quote sitting immediately after the root before classifying:
-        // `/'Users/lane/x` is the separator-design leak, and the root test must
-        // see `/Users/…` to recognise it.
-        const rooted = candidate.replace(/^([\\/]+)["']/, '$1');
-        if (rooted.startsWith('/') && !POSIX_MACHINE_ROOT.test(rooted))
-            continue;
-        return candidate;
-    }
-    return null;
-}
 /** Refuse the WHOLE call when any field carries an absolute local path —
  *  naming the field and the offending token, so the agent can fix exactly
  *  that. Refusal happens before any write; nothing is rewritten. */
@@ -10015,7 +9727,9 @@ const SERVER_INSTRUCTIONS = `You are connected to CTRL+SPC, where this user's wo
 
 3. KEEP THE TERMINAL TERSE. The user is watching CTRL+SPC, not this conversation. Do not narrate, do not paste long output, do not hold the discussion here. Say in one or two lines what you did and point them at CTRL+SPC to see it. Ask questions through ask_question so the answer is recorded, not through terminal prose that vanishes.
 
-The terminal conversation disappears when the process does. What you put in CTRL+SPC is what survives.`;
+The terminal conversation disappears when the process does. What you put in CTRL+SPC is what survives.
+
+Everything you write into CTRL+SPC is saved the same way, whichever tool you use. ${FIREWALL_WRITING_RULE}`;
 export function buildToolsServer(client, userId, machineId, connectionId, 
 /** 18c SLICE 1 — the request (`cliv2_loose_todos.id`) this connection is
  *  working, from the connection's own URL rather than a tool argument the
@@ -10079,7 +9793,8 @@ runTodoIdSource = null) {
             + 'client (get_client_context lists them under `projects` — one project resolves the choice itself, several means '
             + "you choose and say why). Ground the idea in the client's own words in a CITED ARTIFACT on it "
             + '(create_artifact) — the description is the human\'s plain-text surface and carries no citation lines. '
-            + CITATION_LINE_TEACHING,
+            + CITATION_LINE_TEACHING + ' '
+            + FIREWALL_WRITING_RULE,
         inputSchema: {
             project_id: z.string(),
             title: z
@@ -10133,7 +9848,8 @@ runTodoIdSource = null) {
             '`grounding` naming exactly what you read. The manifest is stored with the artifact and its ' +
             'absence is visible to every reader: a user_story written WITHOUT reading available client ' +
             'context must say so in its opening line. ' +
-            CITATION_LINE_TEACHING,
+            CITATION_LINE_TEACHING + ' ' +
+            FIREWALL_WRITING_RULE,
         inputSchema: {
             task_id: z.string(),
             type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe', 'user_story']),
@@ -10226,7 +9942,8 @@ runTodoIdSource = null) {
             + 'That is not a default you can be talked out of: if the user asks you to rewrite a description that has content, say you cannot and offer the artifact, rather than offering to do it anyway. '
             + 'Update a task you own — its status (backlog / in_progress / done), name, description, or due_date. ' +
             'Pass expected_revision from the most recent get_task for optimistic concurrency; on a conflict, ' +
-            'call get_task again to re-read and retry. The change appears in the web board.',
+            'call get_task again to re-read and retry. The change appears in the web board. ' +
+            FIREWALL_WRITING_RULE,
         inputSchema: {
             id: z.string().describe('Task id'),
             expected_revision: z
@@ -10248,7 +9965,8 @@ runTodoIdSource = null) {
     server.registerTool('update_artifact', {
         description: 'Edit an artifact you can access — its title, content, type, or format. Pass expected_revision from the ' +
             'most recent get_task (optimistic concurrency); on a conflict, call get_task again and retry. ' +
-            'The change appears in the web UI.',
+            'The change appears in the web UI. ' +
+            FIREWALL_WRITING_RULE,
         inputSchema: {
             id: z.string(),
             expected_revision: z
@@ -10320,7 +10038,8 @@ runTodoIdSource = null) {
         return setTaskRoleSlugsHandler(client, args);
     });
     server.registerTool('add_comment', {
-        description: 'Leave a note on a task. The comment appears in the web UI, authored by you.',
+        description: 'Leave a note on a task. The comment appears in the web UI, authored by you. ' +
+            FIREWALL_WRITING_RULE,
         inputSchema: {
             task_id: z.string().describe('Task id'),
             body: z.string().min(1),
@@ -10340,7 +10059,8 @@ runTodoIdSource = null) {
             'READ BEFORE YOU WRITE: list what exists (list_tasks) before adding structure, and cut items ' +
             'along real seams — separately buildable, separately testable — not one item per noun in the ' +
             'ask. Add NO duration estimates to names or descriptions unless the user asked: agents ' +
-            'overestimate toward human timelines, and sequencing, not duration, is the value.',
+            'overestimate toward human timelines, and sequencing, not duration, is the value. ' +
+            FIREWALL_WRITING_RULE,
         inputSchema: {
             project_id: z.string().describe('Project id the task belongs to'),
             name: z.string().min(1),
@@ -11112,7 +10832,8 @@ runTodoIdSource = null) {
             'present_wireframes ' +
             'again for iterations of the same design. Requires an open session (begin_work). If diagrams are created ' +
             'but the review request fails, the error includes the created artifacts and exact recovery instructions ' +
-            '— follow them instead of calling this tool again.',
+            '— follow them instead of calling this tool again. ' +
+            FIREWALL_WRITING_RULE,
         inputSchema: {
             title: z.string().min(1).describe('Short title for the presentation (shown on the work item)'),
             kind: z.enum(['ui', 'architecture']).describe("'ui' for wireframes, 'architecture' for code/flow diagrams"),
@@ -11162,7 +10883,8 @@ runTodoIdSource = null) {
             'present_mocks ' +
             'again for iterations of the same design. Requires an open session (begin_work). If mocks are created ' +
             'but the review request fails, the error includes the created artifacts and exact recovery instructions ' +
-            '— follow them instead of calling this tool again.',
+            '— follow them instead of calling this tool again. ' +
+            FIREWALL_WRITING_RULE,
         // This schema DECLARES every field the handler reads and CONSTRAINS none
         // of what the handler validates — the two halves of the Phase 1 defect.
         // DECLARE, because the SDK parses args with z.object(inputSchema) and
@@ -11247,7 +10969,8 @@ runTodoIdSource = null) {
     });
     server.registerTool('record_context_exploration', {
         description: "Record what you explored for this work item as its context document (the canonical 'Work item context' " +
-            'for the item). Repeated calls update the same document. Appears in the web UI.',
+            'for the item). Repeated calls update the same document. Appears in the web UI. ' +
+            FIREWALL_WRITING_RULE,
         inputSchema: {
             content: z.string().min(1),
         },
@@ -11476,7 +11199,8 @@ runTodoIdSource = null) {
             'writes proposals the user accepts or rejects in the web app, under Project settings → Project ' +
             'context. Say so when you report back. Re-running replaces this codebase\'s pending proposals; send ' +
             'an empty `proposals` array to report that the repo holds no standing context, which clears them. ' +
-            "Uses the open session's task when `task_id` is omitted.",
+            "Uses the open session's task when `task_id` is omitted. " +
+            FIREWALL_WRITING_RULE,
         inputSchema: {
             task_id: z
                 .string()
@@ -12317,8 +12041,26 @@ function sessionForAttribution(connectionId) {
  *  token the presence loop rebuilt after a wedge/refresh flows into the session
  *  heartbeat too (FIX 2 — the CLI-v1 stale-token root cause). Only takes effect
  *  while the tools server is running; the per-connection tool handlers keep their
- *  own captured client, which is acceptable — the session heartbeat is what must
- *  stay healthy for the presence chip. */
+ *  own captured client, which is acceptable here, because the session heartbeat
+ *  is what must stay healthy for the presence chip.
+ *
+ *  THAT REASONING IS LOCAL TO THIS FILE AND DOES NOT CARRY ACROSS. A `panel3`
+ *  tool handler serves project writes rather than a heartbeat, so a captured
+ *  client there is a refused write against real work, not a chip that goes grey.
+ *  `panel3/tools.ts` takes its client by value and fans it out to every handler
+ *  for that connection's life, and the poll-storm fix deliberately stopped at
+ *  that boundary. The gap is named, with what closing it would cost, in the
+ *  out-of-scope list of
+ *  `.bugs/20260831-supabase-health/plan-03-dead-session-poll-loop.md`.
+ *
+ *  ═══ THE `handle` GUARD IS WHY presence.ts CALLS THIS TWICE. ═══ Refusing
+ *  while the server is down is right, since there is nothing to serve and no
+ *  reason to hold a client. It also means the first `heartbeat`'s own
+ *  `setToolsClient` is a no-op, because that heartbeat runs BEFORE
+ *  `startToolsServer` sets `handle`. `startPresence` therefore calls this again
+ *  the moment the server is up, with the client that is live by then rather
+ *  than the one it started the server with. Without that second call a rebuild
+ *  during startup would leave `toolsClient` on the original client forever. */
 export function setToolsClient(client) {
     if (handle)
         toolsClient = client;
@@ -12727,6 +12469,15 @@ export async function heartbeatOpenSessions() {
  * healed, while a per-statement refusal is recorded by either. That is the
  * whole reason this lives here rather than in the handler.
  *
+ * ═══ AND IT REALLY IS THE REBUILT ONE, WHICH IT WAS NOT UNTIL THE ORDERING WAS
+ * FIXED. ═══ `startToolsServer` sets `toolsClient = deps.client`, and
+ * `startPresence` starts the server AFTER its first heartbeat, so a rebuild in
+ * that first heartbeat used to be lost twice over: `setToolsClient` refused it
+ * (no `handle` yet) and the later `startToolsServer` then overwrote the field
+ * with the pre-rebuild client anyway. `startPresence` now calls
+ * `setToolsClient` once more the moment the server is up, so the sentence above
+ * is true from the first tick rather than only after a second rebuild.
+ *
  * BEST-EFFORT AND NEVER THROWS, following `writeWorkerStep` and the session
  * helpers above. This is bookkeeping about a failure; it must not turn one
  * refused line into a failed tool call, because the tool's own error is the

package/dist/panel3/client.js

@@ -118,6 +118,7 @@
 import { createClient } from '@supabase/supabase-js';
 import { SUPABASE_URL, SUPABASE_KEY } from '../env.js';
 import { readSession } from '../config.js';
+import { readableWriteError } from '../firewall.js';
 /**
  * How a v3 client holds its session, for the two lifetimes v3 has.
  *
@@ -202,7 +203,7 @@ export async function signedInClient(living = false) {
 export async function returned(query, verb, subject) {
     const { data, error } = await query;
     if (error)
-        throw new Error(`could not ${verb} ${subject}: ${error.message}`);
+        throw new Error(`could not ${verb} ${subject}: ${readableWriteError(error.message)}`);
     if (!data) {
         throw new Error(`could not ${verb} ${subject}: neither data nor an error came back`);
     }