@ctrl-spc/cs 0.7.2 → 0.7.4

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 ?? ''}`);
 }
@@ -4756,7 +4717,13 @@ export async function listCredentialsHandler(client) {
  * returns `{secret, username}`; that maps to screen 8's shapes —
  * api_key → `{kind, secret}`, login → `{kind, username, password}`.
  */
-export async function getCredentialHandler(client, args, 
+export async function getCredentialHandler(client, 
+// `id` is the web's copy-for-agent handle, and it is the ONLY thing that can
+// resolve the ambiguity the name path can only report: names are unique per
+// (org, creator), so two credentials the caller can read may share one, and
+// by name this tool could previously do nothing but tell the user to go
+// rename something. A pasted id names the row the user actually clicked.
+args, 
 // 18d Slice 3. OPTIONAL and trailing, so the existing two-argument call sites
 // (and their tests) are untouched. Absent means "not a run" — see
 // `rememberSecret`.
@@ -4765,26 +4732,38 @@ runTodoId = null) {
     // whatever casing the agent happened to type: the match below is
     // case-insensitive, so "talenttrack read token" must still redact as
     // "[redacted: TalentTrack read token]".
+    const wantedId = typeof args.id === 'string' ? args.id.trim() : '';
+    if (!wantedId && !args.name) {
+        return errorResult('get_credential requires name — as listed by list_credentials.');
+    }
     let match;
     try {
         const rows = (await must(client
             .from('credentials')
             .select('id, name, kind, org_id, created_by')
             .order('created_at', { ascending: true }))) ?? [];
-        const wanted = args.name.toLowerCase();
-        // Uniqueness is per (org, creator): the caller can see two credentials
-        // with the same lowercased name across two of their orgs, or within one
-        // org (their own plus one shared to them by another creator). Never guess
-        // which secret was meant. org_id/created_by are read only to word this
-        // error; they never appear in tool output.
-        const matches = rows.filter((row) => row.name.toLowerCase() === wanted);
-        if (matches.length > 1) {
-            const sameOrg = matches.every((row) => row.org_id === matches[0].org_id);
-            return errorResult(sameOrg
-                ? `credential name "${args.name}" is ambiguous — you can access more than one credential with this name in the same organization (e.g. your own and one shared with you); delete or re-create yours under a different name, or ask an org owner to revoke a shared copy`
-                : `credential name "${args.name}" is ambiguous — you have access to credentials with this name in more than one of your organizations; delete or re-create one under a different name`);
-        }
-        match = matches[0];
+        if (wantedId) {
+            // An id names one row, so there is no ambiguity branch to reach. RLS
+            // already filtered the rows, so a credential the caller cannot read is
+            // simply absent and falls through to the uniform not-found below.
+            match = rows.find((row) => row.id === wantedId);
+        }
+        else {
+            const wanted = args.name.toLowerCase();
+            // Uniqueness is per (org, creator): the caller can see two credentials
+            // with the same lowercased name across two of their orgs, or within one
+            // org (their own plus one shared to them by another creator). Never guess
+            // which secret was meant. org_id/created_by are read only to word this
+            // error; they never appear in tool output.
+            const matches = rows.filter((row) => row.name.toLowerCase() === wanted);
+            if (matches.length > 1) {
+                const sameOrg = matches.every((row) => row.org_id === matches[0].org_id);
+                return errorResult(sameOrg
+                    ? `credential name "${args.name}" is ambiguous — you can access more than one credential with this name in the same organization (e.g. your own and one shared with you); delete or re-create yours under a different name, or ask an org owner to revoke a shared copy`
+                    : `credential name "${args.name}" is ambiguous — you have access to credentials with this name in more than one of your organizations; delete or re-create one under a different name`);
+            }
+            match = matches[0];
+        }
     }
     catch (err) {
         return errorResult(`get_credential failed: ${err.message}`);
@@ -4978,9 +4957,51 @@ export async function listSkillsHandler(client, args) {
  * survives a compaction — an agent that has lost `get_skill`'s output still has
  * the skill's name in the conversation and can still reach its files.
  */
-async function resolveSkill(client, rawName, rawOrgId, tool) {
+/**
+ * Resolve a skill by its row id — the handle the web's copy-for-agent button
+ * pastes. An id names ONE row, so neither of the name path's two ambiguity
+ * errors can arise and `org_id` has nothing left to disambiguate: the id
+ * already decided which org's skill this is, and the bundle it belongs to says
+ * which org that was. RLS does the access check, so a row the caller cannot see
+ * is simply not found.
+ */
+async function resolveSkillById(client, id, tool) {
+    const rows = (await must(client
+        .from('skills')
+        .select('id, bundle_id, name, description, relative_path, status, status_reason')
+        .eq('id', id)
+        .is('deleted_at', null))) ?? [];
+    const row = rows[0];
+    if (!row) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: no skill with id ${id}. It may have been deleted, or belong to an organization you ` +
+                'cannot see. Call list_skills to see the skills that exist.'),
+        };
+    }
+    // The bundle is what carries the org, and only a LIVE bundle counts: a skill
+    // row can outlive the archiving of the bundle that brought it in.
+    const bundles = await liveSkillBundles(client, null);
+    const orgId = bundles.find((bundle) => bundle.id === row.bundle_id)?.org_id;
+    if (!orgId) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: skill "${row.name}" belongs to a skill pack that is no longer active. ` +
+                'Re-import the pack in the web app.'),
+        };
+    }
+    return { ok: true, value: { row, orgId } };
+}
+async function resolveSkill(client, rawName, rawOrgId, tool, 
+// The web's copy-for-agent handle. A name is still the addressing an agent
+// reaches for unaided (it survives a compaction; see this section's header),
+// so `id` is the ALTERNATIVE, not the replacement: it exists because the
+// Skills page copies `/ctrl-spc skill <id>` and a pasted row must resolve to
+// the row the user clicked, never to a same-named skill in another org.
+rawId = undefined) {
+    const wantedId = typeof rawId === 'string' ? rawId.trim() : '';
     const wanted = typeof rawName === 'string' ? rawName.trim() : '';
-    if (!wanted) {
+    if (!wantedId && !wanted) {
         return {
             ok: false,
             error: errorResult(`${tool} requires name — the name of the skill to read, as listed by list_skills.`),
@@ -4989,6 +5010,8 @@ async function resolveSkill(client, rawName, rawOrgId, tool) {
     const filter = skillOrgFilter(rawOrgId, tool);
     if (!filter.ok)
         return filter;
+    if (wantedId)
+        return resolveSkillById(client, wantedId, tool);
     const bundles = await liveSkillBundles(client, filter.value);
     const orgIdByBundle = new Map(bundles.map((bundle) => [bundle.id, bundle.org_id]));
     const rows = orgIdByBundle.size
@@ -5167,7 +5190,7 @@ async function listSkillBundleFiles(client, orgId, bundleId, relativePath) {
 }
 export async function getSkillHandler(client, args) {
     try {
-        const resolved = await resolveSkill(client, args?.name, args?.org_id, 'get_skill');
+        const resolved = await resolveSkill(client, args?.name, args?.org_id, 'get_skill', args?.id);
         if (!resolved.ok)
             return resolved.error;
         const { row: match, orgId } = resolved.value;
@@ -5276,7 +5299,7 @@ export async function readSkillFileHandler(client, args) {
         if (!wantedPath) {
             return errorResult('read_skill_file requires path — one of the paths get_skill listed in bundle_files.');
         }
-        const resolved = await resolveSkill(client, args?.name, args?.org_id, 'read_skill_file');
+        const resolved = await resolveSkill(client, args?.name, args?.org_id, 'read_skill_file', args?.id);
         if (!resolved.ok)
             return resolved.error;
         const { row: match, orgId } = resolved.value;
@@ -5883,6 +5906,58 @@ async function unnarrowedEmptyNote(client, projectId) {
     }
     return NO_PROJECT_DOCUMENTS_NOTE;
 }
+export async function getDocumentHandler(client, args) {
+    const id = typeof args.id === 'string' ? args.id.trim() : '';
+    if (!id) {
+        return errorResult('get_document requires id — the id of the document to read, as the web app’s “Copy for agent” ' +
+            'button pastes it.');
+    }
+    // Shape-checked once, here at the boundary, exactly as resolveContextProject
+    // does with task_id: without it a mistyped id comes back as a Postgres
+    // "invalid input syntax for type uuid", which reads like a bug in the tool.
+    if (!UUID_RE.test(id)) {
+        return errorResult(`get_document: not a valid document id: "${id}".`);
+    }
+    try {
+        // Context documents first, then instructions. RLS scopes both reads, so a
+        // row the caller may not see is simply absent and falls through to the
+        // not-found below.
+        const documents = await must(client
+            .from('project_documents')
+            .select('title, content, codebase_id, type')
+            .eq('id', id));
+        const document = (documents ?? [])[0];
+        if (document)
+            return textResult(shapeDocument(document));
+        const instructions = await must(client.from('agent_instructions').select('title, content, codebase_id').eq('id', id));
+        const instruction = (instructions ?? [])[0];
+        if (instruction) {
+            return textResult({
+                ...shapeDocument(instruction),
+                // Said plainly, so an agent that fetched one does not conclude these are
+                // reference material it may choose to consult: it already has them.
+                note: 'This is an agent instruction. Every instruction on this project is already delivered in ' +
+                    'your prompt — reading one here does not make it optional.',
+            });
+        }
+        return errorResult(`get_document: no document with id ${id}. It may have been deleted, or belong to a project you ` +
+            'cannot see. Call get_project_context to read the documents on the project you are working.');
+    }
+    catch (err) {
+        return errorResult(`get_document failed: ${errorMessage(err)}`);
+    }
+}
+/** The one shape both tables report in, so a caller never has to branch on
+ *  which table answered. `scope` is what `codebase_id` MEANS — null is the
+ *  project's own document, a value is that codebase's. */
+function shapeDocument(row) {
+    return {
+        title: row.title,
+        ...(row.type ? { type: row.type } : {}),
+        scope: row.codebase_id === null ? 'project' : 'codebase',
+        content: row.content,
+    };
+}
 // ---------------------------------------------------------------------------
 // Project context (feature 13a, Phase 4) — `propose_project_context`.
 //
@@ -5957,19 +6032,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. */
@@ -7584,220 +7646,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. */
@@ -9802,6 +9650,7 @@ export const TOOL_NAMES = [
     'get_skill',
     'read_skill_file',
     'get_project_context',
+    'get_document',
     'propose_project_context',
     'list_product_ideas',
     'create_product_idea',
@@ -9900,7 +9749,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
@@ -9964,7 +9815,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
@@ -10018,7 +9870,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']),
@@ -10111,7 +9964,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
@@ -10133,7 +9987,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
@@ -10205,7 +10060,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),
@@ -10225,7 +10081,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),
@@ -10997,7 +10854,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"),
@@ -11047,7 +10905,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
@@ -11132,7 +10991,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),
         },
@@ -11216,7 +11076,16 @@ runTodoIdSource = null) {
             'comments, artifacts, documents and questions, and name the credential instead. Never refuse the ' +
             'work to avoid touching the value.',
         inputSchema: {
-            name: z.string().min(1).describe('Credential name, as listed by list_credentials'),
+            name: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Credential name, as listed by list_credentials'),
+            id: z
+                .string()
+                .optional()
+                .describe('Credential id, as pasted by the web app\'s "Copy for agent" button. Use it instead of ' +
+                'name; it names exactly one credential, where a name can be ambiguous.'),
         },
     }, async (args) => {
         touchSession(connectionId);
@@ -11250,7 +11119,12 @@ runTodoIdSource = null) {
             'about to do. If two organizations hold a skill of the same name this refuses rather than ' +
             'guessing: pass org_id to say which you mean. Read-only.',
         inputSchema: {
-            name: z.string().min(1).describe('Skill name, as listed by list_skills'),
+            name: z.string().min(1).optional().describe('Skill name, as listed by list_skills'),
+            id: z
+                .string()
+                .optional()
+                .describe('Skill id, as pasted by the web app\'s "Copy for agent" button. Use it instead of name; ' +
+                'it names exactly one skill, so org_id is never needed with it.'),
             org_id: z
                 .string()
                 .optional()
@@ -11266,7 +11140,11 @@ runTodoIdSource = null) {
             'those paths here. WHEN A SKILL POINTS AT A FILE BESIDE IT, FETCH IT AND FOLLOW IT — never ask ' +
             'the user to supply a file the organization already stored. Text only, up to 512 KB. Read-only.',
         inputSchema: {
-            name: z.string().min(1).describe('Skill name, as listed by list_skills'),
+            name: z.string().min(1).optional().describe('Skill name, as listed by list_skills'),
+            id: z
+                .string()
+                .optional()
+                .describe('Skill id. Use it instead of name; it names exactly one skill.'),
             path: z
                 .string()
                 .min(1)
@@ -11313,6 +11191,22 @@ runTodoIdSource = null) {
         touchSession(connectionId);
         return getProjectContextHandler(client, openSessions.get(connectionId) ?? null, args);
     });
+    server.registerTool('get_document', {
+        description: 'Read ONE context document or agent instruction by its id — the whole document, not an excerpt. ' +
+            'Use it when someone hands you an id (the web app’s “Copy for agent” button pastes one), or when ' +
+            'get_project_context named a document you need in full. It resolves either kind, so you do not ' +
+            'need to know which one the id belongs to. To read a project’s context as a whole instead, call ' +
+            'get_project_context. Read-only.',
+        inputSchema: {
+            id: z
+                .string()
+                .min(1)
+                .describe('Document id, as the web app’s “Copy for agent” button pastes it'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return getDocumentHandler(client, args);
+    });
     server.registerTool('propose_project_context', {
         // The description TEACHES: when to reach for this (after reading a repo),
         // what a good proposal is (content it actually read, one line of why),
@@ -11327,7 +11221,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()
@@ -12168,8 +12063,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;
@@ -12578,6 +12491,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