@ctrl-spc/cs 0.6.0 → 0.7.0

package/dist/panel3/tools.js

@@ -0,0 +1,1601 @@
+/**
+ * ═══ AGENT PANEL v3: the tools server, and the per-level allowlist. ═══
+ *
+ * THIS FILE BELONGS TO AGENT PANEL v3. Nothing outside `src/panel3/` may
+ * import it.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ WHY v3 SERVES ITS OWN TOOLS INSTEAD OF IMPORTING `mcp.ts`. ═══
+ *
+ * conventions.md left exactly one line unsettled — "the tools server" — and this
+ * is the file that settles it. `cli-v2/src/mcp.ts` holds every product tool in
+ * 20,143 lines. Its handler BODIES are generation-neutral, and its session
+ * anchoring and its permission gate are not: both branch on whether the
+ * connection belongs to v1 or v2, so reuse means adding a third branch to the
+ * one file that would then be unremovable. Finding F2 records the trade in full,
+ * including what it costs: two implementations of "create a work item" exist
+ * until v1 and v2 are retired. A temporary duplication was chosen over a
+ * permanent coupling.
+ *
+ * So this serves the tools plan.md's Task 5 table names, against the same
+ * Supabase and the same RLS, AND NO MORE. It is not a framework. There is no
+ * registry, no plugin surface and no second server behind an interface: one
+ * array of definitions, each one carrying the levels it belongs to.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ RULE A — THE LEVEL RIDES THE CONNECTION, NEVER AN ARGUMENT. ═══
+ *
+ * ux.md: "the run id is on the tools server URL, and the server resolves that
+ * run's level from the record." The URL is `/mcp/<run-id>`, the run row answers
+ * what level it is, and no tool below takes a `level` parameter — there is
+ * nothing for an agent to claim, correctly or otherwise.
+ *
+ * This is the same doctrine the product already applies to attribution:
+ * provenance is not a matter of agent judgement. An agent that could name its
+ * own level could grant itself `ask_question` by saying it was level 1, and the
+ * whole allowlist would be advice.
+ *
+ * IT IS BOUND ONCE, AT `initialize`, AND CHECKED ON EVERY REQUEST AFTER. The
+ * session's run id is remembered when the connection is made and every later
+ * request on that session has to arrive on the same path, so a connection cannot
+ * change which run it is partway through.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ RULE B — A TOOL A LEVEL MAY NOT USE IS ABSENT. ═══
+ *
+ * Not present and refusing. The server built for a connection registers only the
+ * definitions whose `levels` include that run's level, so the list an agent is
+ * handed at `initialize` IS the allowlist. Level 2 sees `ask_question`; level 3
+ * does not.
+ *
+ * The reason is about behaviour, not tidiness: an agent that can see a tool it
+ * may not call will spend turns discovering that, and will then report the
+ * refusal to the user as the product being broken. Absence is unambiguous.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ NO CODE TOOL IS SERVED HERE, AT ANY LEVEL. ═══
+ *
+ * Reading and editing code is the harness's own, and which levels get it is
+ * decided in `spawn.ts` by what is passed to `--allowedTools`. Level 1 is
+ * spawned without any of them (ux.md: "level 1 is never granted a code tool"),
+ * levels 2 and 3 with them. Serving a second, weaker copy of `Read` from here
+ * would give level 1 a route to the thing the rule exists to deny it.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ STARTING A PROCESS IS THE DAEMON'S, NOT THIS FILE'S. ═══
+ *
+ * `dispatch` is the one tool whose effect is a running program, and this server
+ * does not spawn it: it calls a function the daemon hands in. That is not
+ * indirection for its own sake. The daemon already owns everything about a
+ * child's life — writing its row before it starts, recording its pid, waiting
+ * for it, writing its answer, giving up on it when its process is gone, and
+ * holding it open long enough for `--once` to be honest — and a second spawn
+ * path here would be a second owner of all of it, each with its own idea of what
+ * happens when the process dies.
+ *
+ * ═══ AND IT RETURNS THE MOMENT THE PROCESS EXISTS. ═══ ux.md: "Level 1 never
+ * blocks waiting for it. It dispatched and moved on." A handler that awaited the
+ * child's answer would hold the coordinator's own run open for the length of the
+ * work, which is the one thing the level structure exists to prevent.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ ASKING IS TERMINAL, AND THE TOOLS SAY SO IN AS MANY WORDS. ═══
+ *
+ * `escalate`, `ask_question` and `answer_escalation` are three tools over one
+ * statement, `panel3_ask` and `panel3_answer_ask`. The rule they carry is ux.md's:
+ * an agent that cannot proceed writes its question and EXITS. It does not block,
+ * does not poll, and is not sitting there to be woken, because the harness is
+ * one-shot with no inbound channel — so every one of these descriptions ends by
+ * telling the agent to stop, and none of them promises it will be told anything.
+ *
+ * WHAT HAPPENS INSTEAD IS THAT IT IS RE-CREATED with the answer already in its
+ * prompt, which is the daemon's business and not something an agent has to know
+ * or could do anything about.
+ *
+ * ---------------------------------------------------------------------------
+ * ═══ STOPPING IS A RECORD WRITE HERE TOO, AND THE SCOPE IS NOT THIS FILE'S.
+ *     ═══
+ *
+ * `stop_run` refused for the whole plumbing build, honestly, because nothing
+ * behind it was built. What it reaches now is `panel3_stop_run`, which stops the
+ * run named and everything it dispatched, and which decides FOR ITSELF whether
+ * this caller may: it reads the caller's own level and card off its row and
+ * walks the ancestry of the run it named. So the rule below is a description of
+ * what the record will do, not an instruction this file carries out, and an
+ * agent naming something out of its reach stops nothing and is told so.
+ *
+ * ═══ AND THE KILL IS STILL THE DAEMON'S. ═══ The record is the intent, exactly
+ * as it is for the person's own Stop: `cs3 run` kills the processes of stopped
+ * runs on its own machine, on the poll it already has. Nothing here waits for
+ * that, and nothing here claims it has happened.
+ */
+// The runtime import comes FIRST, deliberately: `tsc` elides a type-only import
+// and takes the leading comment with it, so a file whose first statement is
+// `import type` loses its v3 header in the published `dist/`.
+import { createServer as createHttpServer } from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { returned } from './client.js';
+import { rememberSecret, redactArgs } from './secrets.js';
+import { workBrief } from './prompt.js';
+import { listCodebases } from '../codebases.js';
+import { ASK_CONTENT_COLUMNS, attachmentLine, loadAttachments, withAskContent, } from './show.js';
+// ---------------------------------------------------------------------------
+// READING AND WRITING. Every query goes through the same guard every other v3
+// command uses, so a failed read can never reach an agent as an empty list.
+const rows = (query, verb, subject) => returned(query, verb, subject);
+/** One row that must be there, or the reason it is not. `maybeSingle()` is
+ *  deliberately not used: it returns null both for "no such row" and for "the
+ *  caller cannot see it", and the caller here needs to say which. */
+async function only(query, verb, subject) {
+    const found = await rows(query, verb, subject);
+    if (found.length === 0)
+        throw new Error(`could not ${verb} ${subject}: there is no such row, or it is not yours`);
+    return found[0];
+}
+/**
+ * ═══ A RUN THAT HAS ENDED MUST NOT GO ON WRITING. ═══
+ *
+ * The level is resolved once, when the connection is made, and a run can end
+ * underneath a session that is still open: `panel3_give_up` sets `state='failed'`
+ * and hands the turns back the moment recovery decides the process is gone, and
+ * a second agent is then spawned for the same card. The orphan's socket is still
+ * there and its next `write_report` would overwrite the report of a run the panel
+ * has already settled.
+ *
+ * `panel3_answer` already carries the same guard for exactly this reason. This is
+ * it in the same statement as the write, wherever the write is an update: there
+ * is no read-then-decide window, because the predicate and the write are one
+ * round trip.
+ *
+ * ═══ AND THE END IS `ended_at`, NOT THE STATE, BECAUSE A RUN THAT ASKED IS
+ *     STOPPING RATHER THAN STOPPED. ═══ `escalate` and `ask_question` put a run
+ * in `asked` while its process is still alive, and the last thing it does is
+ * write down what it got as far as — which is the whole of what comes back with
+ * it when the answer arrives. A guard on the state alone would refuse that
+ * report and lose it. `ended_at` is stamped when the process actually exits, so
+ * it is the fact that separates "winding up" from "gone", and it is null for a
+ * running run too, so nothing else is loosened.
+ *
+ * ═══ AND IT IS SAID, NOT SWALLOWED. ═══ An update that matches nothing comes
+ * back as an empty list, which is the shape a guard is most easily lost in. The
+ * connection was only established because the run existed and was the user's, so
+ * zero rows after this predicate means one thing and it is stated: the run has
+ * ended. Returning "Noted." here would have an orphan reporting progress to
+ * nobody and telling its agent the work landed.
+ */
+async function whileRunning(query, runId, verb) {
+    const written = await rows(query, verb, `run ${runId}`);
+    if (written.length === 0)
+        throw new Error(ended(runId, verb));
+}
+const ended = (runId, verb) => `could not ${verb} run ${runId}: THIS RUN HAS ENDED and its card has been handed to another agent. `
+    + 'Nothing was written. Stop rather than carrying on.';
+/** The two states a run may still be written to in, as PostgREST takes them.
+ *  See `whileRunning`: `asked` is a process winding up, not a run that is gone. */
+const STILL_WRITING = ['running', 'asked'];
+/**
+ * ═══ ASKING AND PASSING A QUESTION ON ARE ONE ACT, SO THEY ARE ONE FUNCTION.
+ *     ═══
+ *
+ * `escalate` and `ask_question` are two tools because ux.md makes them two — one
+ * asks the person and one asks whoever dispatched the run — and they are ONE
+ * statement because everything except that destination is the same. The tool,
+ * not the agent, supplies that destination, and `panel3_ask` checks it against
+ * the run's own level so a level cannot grant itself a route it was not served.
+ *
+ * ═══ AND THE SENTENCE THAT COMES BACK IS SHARED FOR THE SAME REASON THE BRIEF
+ *     IS. ═══ What an agent is told about stopping decides whether it stops. Two
+ * copies would drift, and the drift would show up as one level in three carrying
+ * on after it asked, holding a question nobody can answer while it works on top
+ * of the assumption it could not make.
+ */
+async function asked(client, runId, args, askPerson) {
+    const { question, category, context, answer_mode, options, question_id, work_item_id } = args;
+    const [ask] = await rows(client.rpc('panel3_ask', {
+        p_run_id: runId,
+        p_question: question,
+        p_category: category,
+        p_context: context,
+        /* Undefined, not a default: the defaults live in the function signature,
+           so there is one place that says what an unshaped question is. */
+        p_answer_mode: answer_mode,
+        p_options: options,
+        p_question_id: question_id ?? null,
+        p_ask_person: askPerson,
+        /* ═══ ONLY `ask_question` OFFERS THIS, AND THE DATABASE REFUSES IT ON AN
+           ESCALATION ANYWAY. ═══ `escalate` shares this function and passes
+           nothing, so the argument is absent rather than null-and-ignored there. */
+        p_work_item_id: work_item_id ?? null,
+    }), 'put', 'your question where it can be answered');
+    if (!ask) {
+        /* NOTHING WAS WRITTEN, and the reasons are said together because the agent
+           cannot tell them apart from where it sits and all of them mean the same
+           thing to it: stop. */
+        throw new Error(`NOTHING WAS WRITTEN and nobody was asked: run ${runId} has already ended, it has already `
+            + 'asked something and is stopping, or the question you named is not one that is waiting on '
+            + 'you. Say plainly what you could not settle, and stop.');
+    }
+    if (ask.ask_id === null) {
+        /* ═══ REFUSED, BECAUSE BOTH READINGS ARE PLAUSIBLE AND EITHER GUESS IS
+           EXPENSIVE. ═══ Merging the two loses the wording of the question this run
+           was handed and aims its answer at the wrong agent; inserting a second
+           sends a duplicate up while the original stops dead. Recoverable in this
+           same turn, which is why it is a refusal rather than a rule in a prompt. */
+        throw new Error(`NOTHING WAS WRITTEN. Question ${ask.held_question} is waiting on you, so this call is `
+            + 'ambiguous: pass THAT one further up by calling this again with question_id set to it, or '
+            + 'answer it first with answer_escalation and then ask yours.');
+    }
+    return [
+        ask.asked_of === null
+            /* ═══ AND IT SAYS WHERE THE ANSWER WILL BE KEPT, BECAUSE THAT IS WHY THE
+               ITEM IS WORTH NAMING. ═══ questions-2/ux.md Slice 2: a question that
+               names a work item IS that item's decision, so an agent that named one
+               can tell the person where to find it, and one that named none can see
+               that it did. */
+            ? `Your question is with the person now, id ${ask.ask_id}.`
+                + (work_item_id ? ` It is a decision on work item ${work_item_id}.` : '')
+            : `Your question is with whoever sent you, id ${ask.ask_id}.`,
+        'YOU HAVE STOPPED. Nothing is waiting for a reply and there is nothing here to wait for: when',
+        'there is an answer, whoever needs it is started again with it. Make sure what you have done is',
+        'written down, and then stop.',
+    ].join('\n');
+}
+/**
+ * ═══ THE ONE ARGUMENT THAT SEPARATES PASSING A QUESTION ON FROM ASKING YOUR
+ *     OWN. ═══
+ *
+ * Shared by `escalate` and `ask_question` because it means the same thing in
+ * both, and because the failure it prevents is the same failure: a run handed a
+ * question that then stops for something unrelated of its own used to overwrite
+ * the first with the second, and send the answer to whoever asked the first.
+ */
+const PASSING_ON = z.string().optional().describe('The id of a question that is waiting on YOU, when what you are doing is passing that one '
+    + 'further up because you cannot settle it either. Leave it out when the question is your own.');
+/**
+ * ═══ A QUESTION IS A DECISION, AND CARRIES WHAT A WORK ITEM'S DECISION
+ *     CARRIES. ═══
+ *
+ * questions-2/ux.md: the person answering is being interrupted, so an agent
+ * that has already worked out that there are three plausible answers should say
+ * so, and the person should be able to settle it with one press rather than by
+ * typing a sentence an agent then has to parse. `app.decision_configuration_valid`
+ * is what refuses a badly shaped one, in the database, because it is the same
+ * function the work item's decisions are checked by and two validators would
+ * eventually disagree about what a structured question is.
+ *
+ * SHARED BY `ask_question` AND `escalate` for the same reason `PASSING_ON` is:
+ * a question that walks up a level is rewritten whole by the agent passing it
+ * on, in words the person can read without having seen any of the work, and a
+ * rewritten question above the options its worker offered is a new question
+ * with an old ballot.
+ */
+const DECIDING = {
+    category: z.string().min(1).describe('What kind of decision this is, in two or three words the person would use: "Rate limiting", '
+        + '"Which codebase", "Scope". It is the first thing they read.'),
+    context: z.string().min(1).describe('WHY you are asking, for somebody who has seen none of the work. What you found, what turns on '
+        + 'it, and what you will do with each answer. Not a restatement of the question.'),
+    answer_mode: z.enum(['free_text', 'single_select', 'multi_select']).optional().describe('single_select when you have worked out the plausible answers and one of them is the decision; '
+        + 'multi_select when several can be chosen together; free_text only when it genuinely cannot be '
+        + 'reduced to a shortlist. Defaults to free_text.'),
+    options: z.array(z.string()).optional().describe('The answers you think are plausible: between 2 and 12, each distinct and non-blank, and none '
+        + 'for free_text. A SUGGESTION, NOT A BALLOT — the person may always answer in their own words '
+        + 'instead, so offer what you would act on rather than every possibility.'),
+};
+const ALL = [1, 2, 3];
+const line = (...parts) => parts.filter(Boolean).join('  ');
+const listed = (items, empty) => (items.length === 0 ? empty : items.join('\n'));
+/** How long a run has been, or was, going — computed here rather than left to
+ *  an agent doing date arithmetic on two timestamps. `endedAt` stops the clock
+ *  where the run itself stopped; `null` stops it at the moment of the read, so
+ *  the same still-running run reads a little longer on a second question later,
+ *  which is the true fact and not a bug.
+ *
+ *  ═══ AND IT MEASURES THE ATTEMPT THAT IS RUNNING NOW. ═══ `resumedAt` is when
+ *  a run was last started again as itself, which `runProcessIsAlive` in `run.ts`
+ *  already treats as the beginning of the attempt that exists. Measuring from
+ *  the first attempt reports a run resumed a minute ago as hours old, and this
+ *  string is what a coordinator reads aloud when the person asks what is
+ *  happening. */
+function elapsed(startedAt, endedAt, resumedAt) {
+    const ms = (endedAt ? new Date(endedAt) : new Date()).getTime()
+        - new Date(resumedAt ?? startedAt).getTime();
+    const minutes = Math.round(ms / 60000);
+    if (minutes < 1)
+        return 'under a minute';
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+    const hours = Math.floor(minutes / 60);
+    const rest = minutes % 60;
+    return `${hours} hour${hours === 1 ? '' : 's'}${rest ? ` ${rest} minute${rest === 1 ? '' : 's'}` : ''}`;
+}
+// ---------------------------------------------------------------------------
+// ═══ A SKILL IS A ROW IN ONE PLACE AND A FILE IN ANOTHER, AND IT TAKES BOTH TO
+//     READ ONE. ═══
+//
+// `public.skills` holds the row; `public.skill_bundles` holds the org. That is
+// not an arrangement worth arguing with here, it is the schema: `skills` HAS NO
+// `org_id` COLUMN, and a skill is org-scoped only through its bundle. So a
+// storage key cannot be built from the skill row on its own, and both tools
+// below make the same two reads before they touch the bucket.
+//
+// THESE ARE PRODUCT TABLES v3 DOES NOT OWN, AND IT ONLY READS THEM. AGENTS.md
+// permits exactly that: shared product data, through the signed-in user's own
+// RLS, the same way the web app reads it. There is no write side here and there
+// must never be one, for the reason v2 already wrote down: an agent that could
+// rewrite the skill it is about to follow is an agent that can rewrite its own
+// instructions, and the whole point of a skill is that a person decided what it
+// says.
+/** The private bucket every uploaded bundle tree lives in. The same string as
+ *  `SKILL_BUNDLES_BUCKET` in `cli-v2/src/mcp.ts`, written out rather than
+ *  imported, because v3 imports nothing from v1 or v2 and the isolation contract
+ *  enforces it. Both copies are reading the same authority: the bucket the
+ *  migration created (20260722180000_skills.sql). */
+const SKILL_BUNDLES_BUCKET = 'skill-bundles';
+/**
+ * ═══ A REMOVED SKILL IS NOT A MISSING ONE, AND AN AGENT TOLD OTHERWISE SAYS
+ *     THE WRONG THING TO THE PERSON. ═══
+ *
+ * `deleted_at` could have been an `.is('deleted_at', null)` on the query, which
+ * is how v2 and the web both do it, and then a removed skill would come back
+ * through `only` as "there is no such row, or it is not yours". That is a lie
+ * about a row the person can still see the history of, and it sends the agent
+ * looking for a typo in an id that is perfectly correct.
+ *
+ * It is refused either way. What changes is that this says WHICH of the two
+ * happened and what the person can do about it, because only one of them has a
+ * fix and it is not one the agent can carry out.
+ *
+ * ═══ AND THE ATTACHMENT IS NOT WRONG FOR STILL NAMING IT. ═══ `ref_id` is by
+ * value with no foreign key, deliberately, so that a card's history survives the
+ * removal of what it pointed at. The row is right, the skill is gone, and the
+ * agent has to be able to tell the person exactly that.
+ */
+const removed = (what, skillId) => new Error(`NOTHING WAS READ: ${what} was removed on the Skills page, so skill ${skillId} is not there to `
+    + 'follow any more. It is still attached to this conversation, because what was attached is kept '
+    + 'as it was, but a removed skill is not a method anybody is standing behind now. Tell the person '
+    + 'it has been removed and ask them to attach a current one, and do not guess at what it said.');
+/**
+ * The skill, if it is still a skill, and everywhere in storage it reaches.
+ *
+ * ═══ THE CONVENTION IS KNOWN HERE AND NOWHERE ELSE. ═══
+ * `<org_id>/<bundle_id>/<relative path>`, from
+ * 20260723120000_skills_org_scope.sql and the web's own upload. The org comes
+ * from the bundle because `skills` HAS NO `org_id` COLUMN, and neither handler
+ * composes a key for itself: they are handed the two they can want. Two copies
+ * of a path convention is how the two come to disagree about where a bundle
+ * lives, in whichever tool nobody re-read, and spelling `${orgId}/${bundleId}`
+ * out again in each handler was that duplication starting.
+ *
+ * BOTH ROWS MUST BE LIVE, AND THAT IS TWO CHECKS RATHER THAN ONE. `deleted_at`
+ * is on both tables and archiving a whole pack does not touch the skills inside
+ * it, so a skill row can be perfectly live inside a bundle nobody kept. The web
+ * app honours both (`bundleIdsForOrg` in `web/src/lib/skills.ts`, and the
+ * skills query beside it), and honouring only the first would have agents
+ * following a pack the person retired in one go.
+ */
+async function skillInItsBundle(client, skillId) {
+    const row = await only(client.from('skills')
+        .select('id, bundle_id, name, description, relative_path, status, status_reason, deleted_at')
+        .eq('id', skillId), 'read', `skill ${skillId}`);
+    if (row.deleted_at)
+        throw removed(`the skill "${row.name}"`, skillId);
+    const bundle = await only(client.from('skill_bundles').select('org_id, deleted_at').eq('id', row.bundle_id), 'read', `the bundle skill ${skillId} belongs to`);
+    if (bundle.deleted_at)
+        throw removed(`the pack "${row.name}" came in`, skillId);
+    /* The skill's OWN folder, which is usually the bundle root: importing a folder
+       strips the picked folder's own leading segment, so `relative_path` is
+       commonly just `SKILL.md` with no directory at all. The ternary is the point
+       rather than tidiness, because joining an empty directory emits a double
+       slash and 404s with the cause invisible. */
+    const slash = row.relative_path.lastIndexOf('/');
+    const dir = slash === -1 ? '' : row.relative_path.slice(0, slash);
+    const bundleRoot = `${bundle.org_id}/${row.bundle_id}`;
+    const skillRoot = dir ? `${bundleRoot}/${dir}` : bundleRoot;
+    return {
+        row,
+        document: `${bundleRoot}/${row.relative_path}`,
+        beside: (path) => `${skillRoot}/${path}`,
+    };
+}
+/**
+ * What is stored at one key in that bucket, or the reason there is nothing to
+ * hand back.
+ *
+ * ═══ A MISSING FILE THROWS, AND SAYS THE RETRY IS POINTLESS. ═══ The row and
+ * the file are separate systems: a skill can be listed on the Skills page and
+ * have lost its file, and what fixes that is a person re-importing the pack,
+ * which no amount of trying again from here brings any closer. So the message
+ * names the key it looked at and says what would actually help.
+ *
+ * AND IT NEVER RETURNS AN EMPTY DOCUMENT, which is the failure that would matter
+ * most: an agent handed `''` follows nothing, notices nothing, and reports the
+ * skill as read.
+ */
+async function skillDocument(client, storagePath, what) {
+    const { data, error } = await client.storage.from(SKILL_BUNDLES_BUCKET).download(storagePath);
+    if (error || !data) {
+        throw new Error(`${what} is missing from storage at "${storagePath}"${error ? ` (${error.message})` : ''}. `
+            + 'Retrying will not help: the skill row and its file are stored separately, and this one lost '
+            + 'its file. Tell the person to re-import the skill pack on the Skills page in the web app, and '
+            + 'do not guess at what it would have said.');
+    }
+    return await data.text();
+}
+/**
+ * ═══ THE PATH A SKILL NAMED IS NOT TRUSTED. ═══
+ *
+ * A skill document is content a person imported, and the agent reading it passes
+ * whatever it says straight back through this tool. So a path that would leave
+ * the skill's own folder is REFUSED BY NAME rather than normalised away:
+ * normalising invites the question of what it normalises to, and no legitimate
+ * caller ever needs to go up a level.
+ *
+ * ═══ THE PERCENT-DECODED SPELLING IS CHECKED TOO, AND THAT IS THE HALF THAT
+ *     LOOKS REDUNDANT. ═══ supabase-js interpolates the key into a URL raw and
+ * unencoded, and the URL parser then decodes and collapses what it finds, so
+ * `%2e%2e/` arrives at storage as `../` having walked past a check that read
+ * only the literal characters. `mcp.ts`'s own `read_skill_file` records that it
+ * verified exactly that, out of the skill's folder and out of the bucket
+ * entirely, which is why a check on one spelling is not a check.
+ */
+function insideTheSkill(path) {
+    const wanted = path.trim();
+    let decoded = wanted;
+    try {
+        decoded = decodeURIComponent(wanted);
+    }
+    catch {
+        /* An escape too malformed to decode is still handed to the URL parser, so
+           nothing is assumed from the failure: the raw spelling is checked below
+           either way, and a stray `%` never becomes a reason to allow something. */
+    }
+    for (const spelling of [wanted, decoded]) {
+        if (spelling === '' || spelling.includes('..') || spelling.startsWith('/')) {
+            throw new Error(`REFUSED, and nothing was read: "${path}" is not a path inside this skill. A file beside a `
+                + 'skill document is named relative to that document, with no leading "/" and no "..". Read '
+                + 'what the skill actually named, and do not guess at a path outside it.');
+        }
+    }
+    return wanted;
+}
+/** The one refusal, for every way a credential can be out of reach. See the
+ *  handler for why it does not say which. */
+const CREDENTIAL_NOT_ACCESSIBLE = 'NOTHING WAS READ: credential not found or not accessible. Tell the person which credential you '
+    + 'were asked for and that you cannot reach it, and do not carry on as though you had it.';
+/**
+ * ═══ THE SENTENCE THAT DECIDES WHETHER THE WORK GETS DONE. ═══
+ *
+ * Carried over from v2's `CREDENTIAL_INSTRUCTION` in substance word for word,
+ * including the last line, which reads like belt and braces and is not. `mcp.ts`
+ * records what happened without it: BOTH harnesses read the secret, decided that
+ * holding it was itself the danger, and refused the work. A product whose
+ * credentials cannot be used is worse than one with no credentials, because the
+ * person put the secret in and got a refusal back.
+ *
+ * So the shape is deliberate. USING it is named explicitly and expected. The
+ * single prohibition is on PUBLISHING it to what is shared and permanent — which
+ * in v3 is everything an agent writes, since every word goes to a hosted row.
+ */
+const CREDENTIAL_INSTRUCTION = 'This is a SECRET, and it is yours to USE. Make the call you were asked to make with it: in a '
+    + 'request header, an environment variable, a command, a config file on this machine, whatever the '
+    + 'work needs. That is what it is for. The ONE rule is about what you PUBLISH: never put the value '
+    + 'itself into your report, your answer, a progress line, a question, a comment, an artifact or a '
+    + 'file you commit, because all of those are shared and permanent. Name the credential you used '
+    + 'instead. Never refuse the work to avoid touching the value.';
+// ---------------------------------------------------------------------------
+// THE TOOLS.
+//
+// One array, in plan.md's own grouping and order, so the served surface can be
+// read against the table it came from without hunting. `levels` on each entry is
+// the whole of the per-level rule; there is no second place where a level is
+// granted or taken away.
+const TOOLS = [
+    // ── Read the record ──────────────────────────────────────────────────────
+    {
+        name: 'list_projects',
+        levels: ALL,
+        description: 'Every CTRL+SPC project you can see, with the organization it belongs to. Start here when a '
+            + 'request names a project by name rather than by id.',
+        input: {},
+        handler: async ({ client }) => {
+            const projects = await rows(client.from('projects').select('id, name, created_at, organizations(name)').order('created_at'), 'read', 'projects');
+            return listed(projects.map((p) => line(p.id, p.name, `org ${p.organizations?.name ?? 'unknown'}`)), 'You can see no projects.');
+        },
+    },
+    {
+        name: 'list_work_items',
+        levels: ALL,
+        description: 'The work items (tasks) on the board, newest first. Optionally filtered to one project and one '
+            + 'status. Archived items and product ideas are not work items and are not listed.',
+        input: {
+            project_id: z.string().optional().describe('Only items in this project.'),
+            status: z.enum(['backlog', 'in_progress', 'done']).optional().describe('Only items in this status.'),
+        },
+        handler: async ({ client }, args) => {
+            const { project_id, status } = args;
+            let query = client
+                .from('tasks')
+                .select('id, name, status, project_id, epic_id, sprint_id, due_date, created_at')
+                .eq('is_idea', false)
+                .is('archived_at', null)
+                .order('created_at', { ascending: false });
+            if (project_id)
+                query = query.eq('project_id', project_id);
+            if (status)
+                query = query.eq('status', status);
+            const items = await rows(query, 'read', 'work items');
+            return listed(items.map((t) => line(t.id, t.status.padEnd(11), t.name, t.due_date ? `due ${t.due_date}` : null)), 'There are no work items matching that.');
+        },
+    },
+    {
+        name: 'get_work_item',
+        levels: ALL,
+        description: 'One work item in full: its description, status, placement, and the artifacts on it.',
+        input: { work_item_id: z.string() },
+        handler: async ({ client }, args) => {
+            const { work_item_id } = args;
+            const item = await only(client
+                .from('tasks')
+                .select('id, name, description, status, due_date, project_id, created_at, epics(name), sprints(name)')
+                .eq('id', work_item_id), 'read', `work item ${work_item_id}`);
+            const artifacts = await rows(client.from('artifacts').select('id, type, title, created_at').eq('task_id', work_item_id)
+                .is('deleted_at', null).order('created_at'), 'read', `the artifacts on work item ${work_item_id}`);
+            return [
+                `${item.name}`,
+                `id        ${item.id}`,
+                `status    ${item.status}`,
+                `project   ${item.project_id}`,
+                `epic      ${item.epics?.name ?? 'none'}`,
+                `sprint    ${item.sprints?.name ?? 'none'}`,
+                `due       ${item.due_date ?? 'no date'}`,
+                '',
+                'DESCRIPTION',
+                item.description.trim() === '' ? '(empty)' : item.description,
+                '',
+                `ARTIFACTS  ${artifacts.length}`,
+                listed(artifacts.map((a) => line(a.id, a.type, a.title ?? '(untitled)')), 'none'),
+            ].join('\n');
+        },
+    },
+    {
+        name: 'get_skill',
+        /* ═══ EVERY LEVEL, AND THAT INCLUDES THE ONE WITH NO CODE TOOL. ═══ Levels 2
+           and 3 are the ones that follow a skill line by line, and they are both
+           inside `ALL`. Level 1 is in it for a different reason worth stating,
+           because the obvious reading is that a coordinator has no use for one:
+           reading what the person attached is not doing the work. A coordinator that
+           cannot read the skill cannot write a responsibility that respects it, and
+           would send somebody off against a method the person had already chosen.
+    
+           AND THERE IS NO `list_skills` BESIDE IT, deliberately. v2 has one because
+           its agent meets a skill as a NAME in a stage document and has to go
+           looking. A v3 agent never searches: the id arrived in its brief, off the
+           card's own attachment row, put there by the person. */
+        levels: ALL,
+        description: 'Read a skill attached to this conversation. A skill is a document your team wrote to be '
+            + 'FOLLOWED, not reference material: call this with the id printed beside the skill in what was '
+            + 'attached, read all of it, and do what it says for the rest of this work.',
+        /* ═══ BY ID, NOT BY NAME, WHICH IS THE OPPOSITE OF v2's TOOL. ═══ v2 resolves
+           a name because a name is what a stage document says and what survives a
+           compaction, and it carries an `org_id` to disambiguate when two libraries
+           hold that name. Neither problem exists here: the id came off the
+           attachment row, so there is one row it can mean and no org argument to get
+           wrong. */
+        input: { skill_id: z.string() },
+        handler: async ({ client }, args) => {
+            const { skill_id } = args;
+            const { row, document: key } = await skillInItsBundle(client, skill_id);
+            const document = await skillDocument(client, key, `skill "${row.name}" is listed, but its document`);
+            return [
+                row.name,
+                `id        ${row.id}`,
+                /* THE STATUS IS REPORTED AND NEVER FILTERED ON, which is v2's rule and
+                   its reasoning: a `warning` is a cataloguing nit about the document's
+                   own header, the person ticked the box and imported it anyway, and
+                   hiding it would have an agent claim it cannot read a skill the person
+                   is looking at on their own Skills page. */
+                `status    ${row.status}${row.status_reason ? `  ${row.status_reason}` : ''}`,
+                `about     ${row.description ?? 'no description'}`,
+                '',
+                'SKILL',
+                /* Byte for byte as it was imported, FRONTMATTER INCLUDED. What a skill
+                   declares about itself at the top is part of what it tells you, and
+                   trimming it here would be this tool deciding which of the person's
+                   words the agent gets. */
+                document,
+                '',
+                /* ═══ THE LAST LINE IS THE ONE THAT MAKES THE DIFFERENCE, AND IT IS
+                   CARRIED OVER FROM v2 WORD FOR WORD IN SUBSTANCE. ═══ A document handed
+                   over without it gets summarised back to the person and then set aside;
+                   the same document with it gets followed. It is one sentence and it is
+                   the whole point of the tool. */
+                'This is a SKILL: a document written to be FOLLOWED for the rest of this work, exactly like a '
+                    + 'stage document. Read all of it and do what it says. It is not reference material to '
+                    + 'summarise, quote back or file away. Where it points at another file beside it, call '
+                    + 'read_skill_file with this skill id and that path, and follow that too.',
+            ].join('\n');
+        },
+    },
+    {
+        name: 'read_skill_file',
+        /* ALL, for `get_skill`'s reasons: whoever may read a skill must be able to
+           read the file it sends them to, or the skill dead-ends at its own first
+           reference and the agent goes to the person for something the org already
+           stored. */
+        levels: ALL,
+        description: 'Read one file that lives beside a skill document, when that document points at it. The path is '
+            + "the one the skill named, relative to the skill's own folder. What it says is part of the "
+            + 'skill: follow it the same way.',
+        input: {
+            skill_id: z.string(),
+            path: z.string().describe("The path the skill document named, exactly as it named it, relative to the skill's own "
+                + 'folder.'),
+        },
+        handler: async ({ client }, args) => {
+            const { skill_id, path } = args;
+            /* REFUSED BEFORE ANYTHING IS READ, so an argument that should not exist
+               never becomes a request. */
+            const wanted = insideTheSkill(path);
+            const { row, beside } = await skillInItsBundle(client, skill_id);
+            const document = await skillDocument(client, beside(wanted), `skill "${row.name}" names "${wanted}", but that file`);
+            return [
+                `${wanted}, beside the skill ${row.name}`,
+                '',
+                document,
+                '',
+                'This is part of the SKILL you are following. Do what it says, exactly as you do what the '
+                    + 'skill document itself says.',
+            ].join('\n');
+        },
+    },
+    {
+        name: 'get_credential',
+        /* ═══ LEVELS 2 AND 3, AND THAT IS A CORRECTION TO ux.md's OWN TABLE. ═══
+           ux.md puts `get_credential` in the "Read the record" row, which is
+           yes/yes/yes. Lane's instruction (2026-08-19) splits it: the NAME is level
+           1's, the VALUE is levels 2 and 3's, and ux.md is corrected to match.
+    
+           THE REASON IT IS THE BETTER RULE, because the table will be read again by
+           somebody who did not hear the instruction: level 1 has no code tool, on
+           purpose. It never makes the call a secret is for. A secret in its context
+           is a secret in the coordinating run of the card, held for work it cannot
+           do. What a coordinator needs is the NAME, so it can write "use the Stripe
+           test key" into a responsibility, and the name is already in front of it —
+           `attachmentLine` prints it in the prompt this run was started with. So
+           level 1 gets nothing new here, rather than getting a narrower tool.
+    
+           AND THERE IS NO `list_credentials` BESIDE IT, for `get_skill`'s reason:
+           the id arrived in the brief, off the card's own attachment row, put there
+           by the person. A v3 agent never goes looking for a credential. */
+        levels: [2, 3],
+        description: 'Read a credential attached to this conversation, and use it. Call this with the id printed '
+            + 'beside the credential in what was attached. The value is yours to USE in the work you were '
+            + 'sent to do; what you must not do is publish it.',
+        input: { credential_id: z.string() },
+        handler: async ({ client, runId }, args) => {
+            const { credential_id } = args;
+            const found = await rows(client.from('credentials').select('id, name, kind, username').eq('id', credential_id), 'read', `credential ${credential_id}`);
+            /* ═══ ONE MESSAGE FOR THREE DIFFERENT FACTS, AND THAT IS DELIBERATE. ═══
+               `get_skill` goes out of its way to say WHICH of "no such row" and "not
+               yours" happened, because a person can act on the difference. Here the
+               opposite is right, and 20260723130000_credentials.sql says why: names
+               and existence are themselves what the access rule protects, so a caller
+               that could tell "there is no such credential" from "there is one and it
+               is not yours" has a probe. `only()` is not used for exactly this
+               reason — its message names the distinction this one must not. */
+            if (found.length === 0)
+                throw new Error(CREDENTIAL_NOT_ACCESSIBLE);
+            const row = found[0];
+            /* ═══ THE ONLY READ PATH FOR THE VALUE. ═══ `credentials` has no secret
+               column to select: the value is in the vault and `reveal_credential` is
+               the DEFINER function that decrypts it, re-checking the same predicate
+               the select policy carries. So "if the user is permitted to use it" is
+               not a rule v3 implements — it is the database's, twice, and the daemon
+               is holding the user's own token when it asks. */
+            const { data, error } = await client.rpc('reveal_credential', { p_id: row.id });
+            if (error)
+                throw new Error(`could not read credential ${credential_id}: ${error.message}`);
+            const value = (data ?? {});
+            const secret = typeof value.secret === 'string' ? value.secret : '';
+            /* NEVER AN EMPTY SECRET. An agent handed `''` sends an empty header, gets
+               a 401 it cannot explain, and reports the credential as wrong. */
+            if (secret === '') {
+                throw new Error(`NOTHING WAS READ: credential "${row.name}" has no value stored against it. Retrying will `
+                    + 'not help. Tell the person to open the Credentials page and set it again, and do not '
+                    + 'guess at the value or carry on without it.');
+            }
+            /* ═══ RECORDED BEFORE IT IS RETURNED, so the substitution is in place
+               BEFORE the agent can write anything containing it. ═══ See secrets.ts:
+               from here on, this value cannot reach a panel3_ row through any tool
+               this run calls or through the answer it ends with. */
+            rememberSecret(runId, secret, row.name);
+            const username = typeof value.username === 'string' ? value.username : null;
+            return [
+                row.name,
+                `id        ${row.id}`,
+                `kind      ${row.kind}`,
+                ...(username === null ? [] : [`username  ${username}`]),
+                '',
+                row.kind === 'login' ? 'PASSWORD' : 'SECRET',
+                secret,
+                '',
+                CREDENTIAL_INSTRUCTION,
+            ].join('\n');
+        },
+    },
+    {
+        name: 'list_artifacts',
+        levels: ALL,
+        description: 'The live artifacts on one work item, without their bodies. Use get_artifact to read one.',
+        input: { work_item_id: z.string() },
+        handler: async ({ client }, args) => {
+            const { work_item_id } = args;
+            const artifacts = await rows(client.from('artifacts').select('id, type, format, title, created_at').eq('task_id', work_item_id)
+                .is('deleted_at', null).order('created_at'), 'read', `the artifacts on work item ${work_item_id}`);
+            return listed(artifacts.map((a) => line(a.id, a.type, a.format, a.title ?? '(untitled)')), 'That work item has no artifacts.');
+        },
+    },
+    {
+        name: 'get_artifact',
+        levels: ALL,
+        description: 'One artifact in full, including its body.',
+        input: { artifact_id: z.string() },
+        handler: async ({ client }, args) => {
+            const { artifact_id } = args;
+            const artifact = await only(client.from('artifacts')
+                .select('id, task_id, type, format, title, content, storage_path, created_at')
+                .eq('id', artifact_id), 'read', `artifact ${artifact_id}`);
+            return [
+                `${artifact.title ?? '(untitled)'}`,
+                `id           ${artifact.id}`,
+                `work item    ${artifact.task_id}`,
+                `type         ${artifact.type} (${artifact.format})`,
+                '',
+                /* A stored file and an empty body are different facts and are said
+                   differently. Returning '' for a PNG would read as an artifact with
+                   nothing in it. */
+                artifact.content ?? `This artifact is a stored file, not text: ${artifact.storage_path}`,
+            ].join('\n');
+        },
+    },
+    {
+        name: 'list_cards',
+        /* ═══ LEVEL 1 ONLY, AND THIS OVERRIDES plan.md's TABLE. ═══ The plan grants
+           it to all three levels; ux.md scopes level 2 to one user ask and gives
+           only the coordinator the view across everything ("only level 1 sees
+           everything"). The spec is binding over the plan, and the ruling is Lane's.
+    
+           It also matters in practice: a level 2 agent that can read every other
+           card is a level 2 agent that can decide its own work is less important
+           than something on another card, which is exactly the coordination
+           judgement level 1 exists to hold. */
+        levels: [1],
+        description: 'Every card on this panel, newest first, with what each is doing. This is the view across all '
+            + 'the work, which only the coordinator has.',
+        input: {},
+        handler: async ({ client }) => {
+            const cards = await rows(client.from('panel3_cards').select('id, title, state, created_at')
+                .is('archived_at', null).order('created_at', { ascending: false }), 'read', 'the cards');
+            return listed(cards.map((c) => line(c.id, c.state.padEnd(10), c.title)), 'There are no cards.');
+        },
+    },
+    {
+        name: 'list_card_agents',
+        /* ═══ LEVEL 1 ONLY, FOR THE SAME REASON list_cards IS. ═══ ux.md gives the
+           view across the work to the coordinator, and an agent that could see the
+           whole tree on its own card is one deciding its own priority against work
+           it was never sent to look at.
+    
+           ═══ AND IT ANSWERS FOR A CARD THIS RUN CANNOT DISPATCH FROM. ═══
+           `list_child_runs` answers for the asking run's OWN children, and a fresh
+           coordinator taking a message mid-work has none: the agents already
+           running are children of the run that took the earlier turn, not of this
+           one. What is shared between them is the card, so this reads by card
+           rather than by parent — which is what lets a status question be answered
+           without waking anything that is still working. */
+        levels: [1],
+        description: 'Everything running or already run on this card, whoever started it, with what each one is '
+            + 'doing and how long it has been going. Read this to answer what is happening without starting '
+            + 'anything new and without disturbing whatever is already under way.',
+        input: {},
+        handler: async ({ client, cardId }) => {
+            const agents = await rows(client.from('panel3_runs')
+                // `resumed_at` is read because "how long it has been going" is about
+                // the attempt that is running now. See `elapsed`.
+                .select('id, level, parent_run_id, state, activity, started_at, resumed_at, ended_at')
+                .eq('card_id', cardId).order('started_at'), 'read', 'the agents on this card');
+            return listed(agents.map((a) => {
+                const live = a.state === 'running' && !a.ended_at;
+                return line(a.id, `L${a.level}`, a.parent_run_id ? `parent ${a.parent_run_id}` : 'no parent, dispatched by the daemon', live ? 'still running' : a.state, a.activity ?? null, live
+                    ? `going ${elapsed(a.started_at, null, a.resumed_at)}`
+                    : `went ${elapsed(a.started_at, a.ended_at, a.resumed_at)}`);
+            }), 'Nothing has run on this card.');
+        },
+    },
+    // ── Read my own ──────────────────────────────────────────────────────────
+    {
+        name: 'get_my_brief_and_report',
+        levels: ALL,
+        description: 'What you were sent to do, and what you have already written down about doing it. Both are also '
+            + 'in your prompt; this is here for when you need to re-read them mid-run.',
+        input: {},
+        handler: async ({ client, runId }) => {
+            const run = await only(client.from('panel3_runs').select('level, brief, report, activity').eq('id', runId), 'read', 'your own run');
+            return [
+                `You are a level ${run.level} agent.`,
+                '',
+                'BRIEF, written when you were dispatched and never changed',
+                run.brief,
+                '',
+                'REPORT, what you last wrote down',
+                run.report ?? 'You have not written a report yet.',
+                '',
+                `ACTIVITY  ${run.activity ?? 'nothing reported'}`,
+            ].join('\n');
+        },
+    },
+    // ── Read my children ─────────────────────────────────────────────────────
+    //
+    // ABSENT AT LEVEL 3, because level 3 has no children: `dispatch` stops at
+    // level 2, so a level 3 agent asking what its children reported is asking
+    // about something that cannot exist.
+    {
+        name: 'list_child_runs',
+        levels: [1, 2],
+        description: 'The agents you dispatched, with what each is doing. READ THIS RATHER THAN REMEMBERING: what you '
+            + 'already dispatched is a fact in the record, so a respawn of you can see it too and will not '
+            + 'dispatch the same work twice.',
+        input: {},
+        handler: async ({ client, runId }) => {
+            const children = await rows(client.from('panel3_runs').select('id, level, state, activity, started_at, ended_at')
+                .eq('parent_run_id', runId).order('started_at'), 'read', 'the runs you dispatched');
+            return listed(children.map((c) => line(c.id, `L${c.level}`, c.state === 'running' && !c.ended_at ? 'still running' : c.state, c.activity ?? null)), 'You have dispatched nothing.');
+        },
+    },
+    {
+        name: 'get_child_report',
+        levels: [1, 2],
+        description: 'What one agent you dispatched has written down about its work.',
+        input: { run_id: z.string() },
+        handler: async ({ client, runId }, args) => {
+            const { run_id } = args;
+            /* THE PARENT LINK IS THE FILTER, not a check after the read. ux.md grants
+               an agent its OWN children's reports, and a run id is guessable enough
+               that reading first and refusing second would be a lookup an agent could
+               use to find out that some other run exists. */
+            const child = await only(client.from('panel3_runs').select('id, level, state, report')
+                .eq('id', run_id).eq('parent_run_id', runId), 'read', `run ${run_id} as one of yours`);
+            return [
+                `Run ${child.id}, level ${child.level}, ${child.state}.`,
+                '',
+                child.report ?? 'It has written no report.',
+            ].join('\n');
+        },
+    },
+    // ── Write structure ──────────────────────────────────────────────────────
+    //
+    // ═══ LEVEL 1's ALONE, AND THAT IS ux.md's SECOND RULE. ═══ "The board changes
+    // because the coordinator decided it should, never because a worker created
+    // something mid-refactor." A level 2 or 3 agent reports a finding; turning a
+    // finding into structure is coordination.
+    //
+    // ═══ IT IS CREATING STRUCTURE THAT IS LEVEL 1's, NOT EVERY WRITE. ═══ ux.md's
+    // "Create structure" row is `create_epic`, `create_sprint`, `create_task` and
+    // the placement tools. Editing an item as the work moves, and producing an
+    // object, are two other rows of that same table and they are NOT level 1's:
+    // see the next section, which is where they now live.
+    {
+        name: 'create_epic',
+        levels: [1],
+        description: 'Create an epic in a project. An epic groups work items that belong to one body of work.',
+        input: { project_id: z.string(), name: z.string().min(1) },
+        handler: async (caller, args) => {
+            const { project_id, name } = args;
+            const epic = await only(caller.client.from('epics').insert({ project_id, name }).select('id, name'), 'create', `an epic called ${name}`);
+            await receipt(caller, 'epic', epic.id, epic.name);
+            return `Created epic ${epic.name}, id ${epic.id}.`;
+        },
+    },
+    {
+        name: 'create_sprint',
+        levels: [1],
+        description: 'Create a sprint in a project. Both dates are required and the start must not be after the end.',
+        input: {
+            project_id: z.string(),
+            name: z.string().min(1),
+            start_date: z.string().describe('YYYY-MM-DD'),
+            end_date: z.string().describe('YYYY-MM-DD'),
+        },
+        handler: async (caller, args) => {
+            const { project_id, name, start_date, end_date } = args;
+            const sprint = await only(caller.client.from('sprints').insert({ project_id, name, start_date, end_date }).select('id, name'), 'create', `a sprint called ${name}`);
+            await receipt(caller, 'sprint', sprint.id, sprint.name);
+            return `Created sprint ${sprint.name}, id ${sprint.id}.`;
+        },
+    },
+    {
+        name: 'create_work_item',
+        levels: [1],
+        description: 'Create a work item on the board. Put what is to be done in the description: a name alone leaves '
+            + 'whoever picks it up guessing.',
+        input: {
+            project_id: z.string(),
+            name: z.string().min(1),
+            description: z.string().optional(),
+            epic_id: z.string().optional(),
+            sprint_id: z.string().optional(),
+            due_date: z.string().optional().describe('YYYY-MM-DD'),
+        },
+        handler: async (caller, args) => {
+            const a = args;
+            const item = await only(caller.client.from('tasks').insert({
+                project_id: a.project_id,
+                name: a.name,
+                description: a.description ?? '',
+                /* THE SIGNED-IN USER OWNS IT. `owner_id` is `not null` and has no
+                   default, and the schema's own guard refuses an owner who is not a
+                   member of the project's organization, so there is nothing to
+                   invent here: the person whose account this panel is running as is
+                   the owner. */
+                owner_id: caller.userId,
+                epic_id: a.epic_id ?? null,
+                sprint_id: a.sprint_id ?? null,
+                due_date: a.due_date ?? null,
+            }).select('id, name'), 'create', `a work item called ${a.name}`);
+            await receipt(caller, 'work_item', item.id, item.name);
+            return `Created work item ${item.name}, id ${item.id}.`;
+        },
+    },
+    // ── Do the work, and produce objects ─────────────────────────────────────
+    //
+    // ═══ EVERY LEVEL, AND THAT IS ux.md's FOURTH RULE. ═══ "Producing an object
+    // is everyone's. A receipt, an artifact, a screenshot, a mock reaching the
+    // user is not a conversation. The invariant is one conversational addressee,
+    // not one source of output."
+    //
+    // ═══ AND IT IS LOAD-BEARING RATHER THAN TIDY. ═══ ux.md: "when an agent
+    // learns something durable, it writes it down as an object... an artifact.
+    // This is the existing rule that output goes into objects rather than into a
+    // conversation, doing real work: it is what makes stage four's worker able to
+    // know what stage two discovered, without anybody holding a transcript." A
+    // level 2 or 3 agent that cannot create one has no way to leave a finding
+    // where a later stage can read it, and the whole no-side-channel design rests
+    // on it being able to.
+    //
+    // plan.md's Task 5 table grants all three of these to level 1 alone. The spec
+    // is binding over the plan, which is the ruling finding F4 already made in the
+    // other direction; F9 records that it was not applied here when it should have
+    // been.
+    {
+        name: 'update_work_item',
+        /* ═══ EVERY LEVEL, AND THIS OVERRIDES plan.md's TABLE. ═══ ux.md puts
+           `update_task` under "Do the work", which is levels 2 and 3, and NOT under
+           "Create structure", which is level 1's alone. The build had it exactly
+           inverted. Rule 2 is about CREATING structure — "the board changes because
+           the coordinator decided it should" — and moving an item a worker is
+           already on through its own statuses is the work, not the board changing.
+           LEVEL 1 KEEPS IT rather than being narrowed to ux.md's letter: it creates
+           work items, and an agent that cannot correct the item it just made in the
+           same turn would have to make a second one beside it. */
+        levels: ALL,
+        description: 'Change a work item. Pass only what changes; anything you leave out stays as it is.',
+        input: {
+            work_item_id: z.string(),
+            name: z.string().min(1).optional(),
+            description: z.string().optional(),
+            status: z.enum(['backlog', 'in_progress', 'done']).optional(),
+            epic_id: z.string().optional(),
+            sprint_id: z.string().optional(),
+            due_date: z.string().optional().describe('YYYY-MM-DD'),
+        },
+        handler: async ({ client }, args) => {
+            const { work_item_id, ...rest } = args;
+            const changes = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
+            /* AN UPDATE WITH NOTHING IN IT IS REFUSED, not quietly treated as a
+               success. Supabase would happily run it and return the row, and the
+               agent would read "updated" having changed nothing at all. */
+            if (Object.keys(changes).length === 0) {
+                throw new Error('nothing to change: pass at least one field besides work_item_id');
+            }
+            const item = await only(client.from('tasks').update(changes).eq('id', work_item_id).select('id, name'), 'update', `work item ${work_item_id}`);
+            return `Updated ${item.name}: ${Object.keys(changes).join(', ')}.`;
+        },
+    },
+    {
+        name: 'create_artifact',
+        // Everyone's. See the section header: this is how a level 2 or 3 agent
+        // writes down what it learned so a later stage can read it.
+        levels: ALL,
+        description: 'Attach a document to a work item: a plan, a spec, an analysis. Artifacts are always on a work '
+            + 'item, so create the work item first if there is not one yet.',
+        input: {
+            work_item_id: z.string(),
+            title: z.string().min(1),
+            content: z.string().min(1),
+            type: z.enum(['plan', 'spec', 'analysis', 'diagram', 'mock', 'wireframe', 'user_story']).optional(),
+        },
+        handler: async (caller, args) => {
+            const a = args;
+            const artifact = await only(caller.client.from('artifacts').insert({
+                task_id: a.work_item_id,
+                title: a.title,
+                content: a.content,
+                type: a.type ?? 'plan',
+                format: 'md',
+                // `not null`, no default, and the table's own policy requires it to be
+                // the caller. Stated rather than left to be defaulted somewhere else.
+                created_by: caller.userId,
+            }).select('id, title'), 'create', `an artifact called ${a.title}`);
+            await receipt(caller, 'artifact', artifact.id, artifact.title);
+            return `Created artifact ${a.title}, id ${artifact.id}.`;
+        },
+    },
+    {
+        name: 'update_artifact',
+        // Everyone's, for the same reason `create_artifact` is: an object that can
+        // be made and never corrected is an object that goes stale in the record.
+        levels: ALL,
+        description: 'Replace an artifact\'s body. The whole body is replaced, so send it complete.',
+        input: { artifact_id: z.string(), content: z.string().min(1), title: z.string().min(1).optional() },
+        handler: async ({ client, userId }, args) => {
+            const a = args;
+            const artifact = await only(client.from('artifacts')
+                .update({
+                content: a.content,
+                ...(a.title ? { title: a.title } : {}),
+                updated_at: new Date().toISOString(),
+                updated_by: userId,
+            })
+                .eq('id', a.artifact_id).select('id, title'), 'update', `artifact ${a.artifact_id}`);
+            return `Updated artifact ${artifact.title ?? artifact.id}.`;
+        },
+    },
+    // ── Report ───────────────────────────────────────────────────────────────
+    {
+        name: 'report_activity',
+        levels: ALL,
+        description: 'Say what you are doing right now, in one short line, in the words a person watching would use. '
+            + 'It replaces whatever you last said. Call it when you start something that will take a while, '
+            + 'so a run that is working and a run that is wedged do not look the same.',
+        input: { activity: z.string().min(1).describe('One line, present tense. "Reading the checkout for where auth is decided".') },
+        handler: async ({ client, runId }, args) => {
+            const { activity } = args;
+            /* ═══ THROUGH AN RPC, SO THE LINE AND ITS TIME ARE ONE STATEMENT ON ONE
+               CLOCK. ═══ This was a plain table update. The card is now one list in
+               the order things happened, sorted against times the database wrote, and
+               a stamp supplied from here would be this laptop's clock compared with
+               Supabase's. `panel3_report_activity` carries the same liveness
+               predicate the update did, in the same statement, so `whileRunning` is
+               still what reads the refusal. */
+            await whileRunning(client.rpc('panel3_report_activity', { p_run_id: runId, p_activity: activity }), runId, 'record what you are doing on');
+            return 'Noted.';
+        },
+    },
+    {
+        name: 'write_report',
+        levels: ALL,
+        description: 'Write down what is true NOW: what you have done, what you decided and why, and what is still '
+            + 'open. It REPLACES your last report rather than adding to it, and it is what you are handed if '
+            + 'you are respawned, so write it as the thing you would want to read to carry on. Write it as '
+            + 'you go, not only at the end.',
+        input: { report: z.string().min(1) },
+        handler: async ({ client, runId }, args) => {
+            const { report } = args;
+            await whileRunning(
+            // STILL RUNNING, IN THE SAME STATEMENT. See `whileRunning`.
+            client.from('panel3_runs').update({ report }).eq('id', runId)
+                .in('state', STILL_WRITING).is('ended_at', null).select('id'), runId, 'write the report on');
+            return 'Report written.';
+        },
+    },
+    {
+        name: 'record_output',
+        levels: ALL,
+        description: 'Record that this card produced something the user should be able to open. Anything you create '
+            + 'with create_epic, create_sprint, create_work_item or create_artifact is recorded for you; use '
+            + 'this for anything else that should show on the card.',
+        input: {
+            kind: z.string().min(1).describe('What sort of thing it is: work_item, artifact, epic, sprint, commit.'),
+            ref_id: z.string().describe('The id of the thing itself.'),
+            label: z.string().optional().describe('What to call it on the card.'),
+        },
+        handler: async (caller, args) => {
+            const a = args;
+            await receipt(caller, a.kind, a.ref_id, a.label ?? null);
+            return `Recorded ${a.kind} ${a.ref_id} on the card.`;
+        },
+    },
+    // ── Questions ────────────────────────────────────────────────────────────
+    {
+        name: 'list_questions',
+        /* ═══ EVERY LEVEL, BECAUSE THE QUESTION BELONGS TO THE CARD. ═══ ux.md: "the
+           question and its answer are recorded against the card, so they are context
+           for everything running on it rather than private to the run that asked. A
+           sibling worker that would have asked the same thing reads it instead." */
+        levels: ALL,
+        description: 'Everything that has been asked on this piece of work and what it was answered with, whoever '
+            + 'asked it. READ THIS BEFORE YOU ASK: somebody working beside you may have asked the same '
+            + 'thing already, and asking again costs the person twice.',
+        input: {},
+        handler: async ({ client, cardId }) => {
+            const asks = await withAskContent(client, await rows(client.from('panel3_asks')
+                .select(`id, answered_at, pending_run_id, run_id, ${ASK_CONTENT_COLUMNS}`)
+                .eq('card_id', cardId).order('created_at'), 'read', 'what has been asked here'));
+            return listed(asks.map((a) => [
+                `${a.id}  ${a.answered_at ? 'answered' : a.pending_run_id ? 'waiting on the agent it went to' : 'waiting on the person'}`,
+                /* THE WHOLE QUESTION, NOT ITS TITLE. A sibling reading only the
+                   question of a shortlisted one cannot tell whether its own is the
+                   same thing, which is the entire reason to read this before asking:
+                   the context says what was already worked out and the options say
+                   what was already ruled plausible. Null on questions asked before a
+                   question carried them, and absent rather than printed as empty. */
+                ...(a.category ? [`  ${a.category}`] : []),
+                ...(a.context ? [`  why  ${a.context}`] : []),
+                `  Q  ${a.question ?? '(this question could not be read)'}`,
+                ...(a.options ?? []).map((option) => `  -  ${option}`),
+                `  A  ${a.answer ?? 'not answered yet'}`,
+            ].join('\n')), 'Nothing has been asked here.');
+        },
+    },
+    {
+        name: 'ask_question',
+        /* ═══ LEVELS 1 AND 2. ═══ The coordinator keeps it for a loose ask and the
+           level 2 agent doing the work keeps it because it has the best view of the
+           decision. Level 3 still escalates, and the tool is absent there rather
+           than present and refusing. */
+        levels: [1, 2],
+        description: 'Put a question to the person, and stop. Ask only what you genuinely cannot settle from the '
+            + 'record, by dispatching someone to find out, or by answering it yourself. Ask ONE thing, in '
+            + 'the words they would use, and say what you will do with each answer. If you are putting on '
+            + 'a question that came up from work you sent out, name it in question_id and write it as they '
+            + 'need to read it: they have not seen any of it.',
+        input: {
+            question: z.string().min(1),
+            ...DECIDING,
+            question_id: PASSING_ON,
+            work_item_id: z.string().optional().describe('The work item this question is a decision ABOUT, if it is about one. The answer is kept on '
+                + 'that item, where anybody reading it later will find it, so name the item the decision '
+                + 'belongs to even if it is not the one attached to this conversation. Leave it out when the '
+                + 'question is not about a work item — whether a second item should exist, which item a '
+                + 'request means, or anything about the conversation itself — rather than picking the '
+                + 'nearest one.'),
+        },
+        handler: async ({ client, runId }, args) => asked(client, runId, args, true),
+    },
+    {
+        name: 'escalate',
+        /* n/a at level 1, which escalates to the USER through `ask_question`
+           instead — there is nothing above it to ask. */
+        levels: [2, 3],
+        description: 'Ask whoever sent you something you cannot decide, and stop. Use it when you genuinely cannot '
+            + 'go on: what you have done stays where it is, and you are started again with the answer when '
+            + 'there is one. If a question came to you from somebody you sent and you cannot settle it '
+            + 'either, this is how it goes further up: name it in question_id and write it in your own '
+            + 'words, with what you already know added.',
+        input: { question: z.string().min(1), ...DECIDING, question_id: PASSING_ON },
+        handler: async ({ client, runId }, args) => asked(client, runId, args, false),
+    },
+    {
+        name: 'answer_escalation',
+        /* ═══ ABSENT AT LEVEL 3, WHICH HAS NO CHILDREN TO BE ASKED BY. ═══ `dispatch`
+           stops at level 2, so a level 3 agent answering one of its own children is
+           answering something that cannot exist. */
+        levels: [1, 2],
+        description: 'Answer a question that came up from work you sent out, so whoever asked it can carry on. '
+            + 'Answer it yourself wherever you can: every question you pass further up is one the person '
+            + 'has to stop and deal with. The one who asked is started again with your answer, so write it '
+            + 'to them, plainly, and say what to do rather than what you would have done.',
+        input: { question_id: z.string(), answer: z.string().min(1) },
+        handler: async ({ client, runId }, args) => {
+            const { question_id, answer } = args;
+            /* ═══ AN AGENT ANSWERS IN ITS OWN WORDS, WHATEVER SHAPE THE QUESTION WAS
+               ASKED IN. ═══ No selection and the answer as the note, which is the
+               product's "own words" answer: `app.canonical_decision_answer` returns
+               the note verbatim for it, so this needs no case for the mode and cannot
+               drift from what the person's answer composes to. */
+            const { data, error } = await client
+                .rpc('panel3_answer_ask', {
+                p_ask_id: question_id,
+                p_selected_options: [],
+                p_answer_note: answer,
+                p_by_run_id: runId,
+            });
+            if (error)
+                throw new Error(`could not answer question ${question_id}: ${error.message}`);
+            if (data === null) {
+                /* REFUSED, AND THE THREE REASONS ARE ONE SENTENCE because the caller
+                   cannot tell them apart and all three mean the same thing to it: this
+                   is not yours to settle, and nothing was written. */
+                throw new Error(`NOTHING WAS WRITTEN: question ${question_id} is not waiting on you. It has been answered `
+                    + 'already, or it went somewhere else, or there is no such question. Do not tell anybody it '
+                    + 'is settled.');
+            }
+            return (`Answered. Whoever asked is started again with it, so there is nothing to pass on and nobody `
+                + 'to tell.');
+        },
+    },
+    // ── Dispatch and stop ────────────────────────────────────────────────────
+    {
+        name: 'dispatch',
+        /* ═══ ABSENT AT LEVEL 3, WHICH IS HOW "DEPTH STOPS AT THREE" IS ENFORCED.
+           ═══ ux.md puts it in the mechanical column, not the judgement one, so it
+           cannot be a sentence in a prompt asking a worker not to spawn. A level 3
+           agent has no tool to spawn with.
+    
+           AND THERE IS NO `level` ARGUMENT, deliberately. A child is one level below
+           its parent, and `panel3_dispatch` reads the parent's own row to work that
+           out, so the depth of a dispatch is arithmetic the DATABASE does rather
+           than a number anything above it chooses. The same statement refuses a
+           parent at level 3, which is this rule enforced a second time in the one
+           place a bug in the served list above could not reach. */
+        levels: [1, 2],
+        /* ═══ AND WHAT IT SAYS IS TRUE AT BOTH LEVELS THAT HOLD IT. ═══ Where the
+           agent's words end up differs — level 2's go to the person, level 3's go to
+           whoever sent it — so that fact belongs in each level's own brief, and this
+           says only what is true of a dispatch wherever it is made. A description
+           that described one level's outcome would be wrong at the other exactly
+           half the time, and read as authoritative both times. */
+        description: 'Send an agent to read or change one named codebase, with a responsibility and a boundary. It gets a working '
+            + 'copy and the two things you write here AND NOTHING ELSE — it never sees this conversation — '
+            + 'so put everything it needs in the responsibility rather than making it search. People sent to '
+            + 'the same codebase work in the SAME working copy at the same time, so give them pieces that do not touch '
+            + 'the same files, or send them one at a time. Do not wait for it: what it writes goes on as it '
+            + 'wrote it, and nobody edits it on the way.',
+        input: {
+            codebase_id: z.string().uuid().describe('The id of the registered project codebase this work belongs to.'),
+            responsibility: z.string().min(1).describe('What this agent owns, in one or two sentences, complete enough to act on with no other '
+                + 'context: what to find out or change, and in which part of the codebase.'),
+            boundary: z.string().min(1).describe('What it must not touch, and where its work stops.'),
+            work_item_id: z.string().optional().describe('The work item it is working, if there is one.'),
+        },
+        handler: async (caller, args) => {
+            const { codebase_id, responsibility, boundary, work_item_id } = args;
+            const cards = await rows(caller.client.from('panel3_cards').select('project_id').eq('id', caller.cardId), 'read', `the project for card ${caller.cardId}`);
+            const projectId = cards[0]?.project_id;
+            if (!projectId) {
+                throw new Error('This conversation is not filed under a project, so it has no codebase to use.');
+            }
+            const codebase = (await listCodebases(caller.client, projectId))
+                .find((candidate) => candidate.id === codebase_id);
+            if (!codebase) {
+                throw new Error('That codebase is not registered on this project. Read the current project codebases and choose one of them.');
+            }
+            /* ONE LEVEL DOWN, AND THE SAME ARITHMETIC THE DATABASE DOES. This decides
+               the words in the brief; `panel3_dispatch` decides the level on the row,
+               from the parent it reads, and that row is what the tools server serves
+               the child from. The record is authoritative and no agent is asked. */
+            const childLevel = (caller.level + 1);
+            /* ═══ WHAT WAS ATTACHED TO THE CARD, NOT WHAT THIS AGENT CHOSE. ═══
+               `work_item_id` above is one item THIS dispatcher named for this one
+               piece of work; the card's own attachments are what the PERSON pointed
+               the whole conversation at, and they travel to every dispatch on it:
+               level 2's workers and their own workers alike, so a level 3 agent
+               three hops from level 1 still knows which item it is working, without
+               asking. See `workBrief`'s own doc for why the two are different things
+               carried the same way. */
+            const attachments = (await loadAttachments(caller.client, caller.cardId)).map(attachmentLine);
+            const { runId } = await caller.dispatch(caller.runId, workBrief(childLevel, responsibility, boundary, work_item_id, attachments, {
+                id: codebase.id,
+                name: codebase.name,
+                identity: codebase.gitRemoteUrl,
+            }), codebase);
+            /* ═══ WHERE ITS ANSWER GOES DEPENDS ON WHICH LEVEL THIS IS, AND THAT IS
+               KNOWN HERE RATHER THAN GUESSED. ═══ The description above cannot say it,
+               because it is registered once for both levels that hold the tool; this
+               sentence is written for one caller whose level came off its own run row.
+               Getting it wrong either way is expensive and invisible: a level 1 agent
+               told the answer comes back to it waits for something that never will,
+               and a level 2 agent told the worker writes to the person leaves three
+               findings in the record with nobody to put them together. */
+            return (`Started, and it is working now. Its id is ${runId}, and list_child_runs will say how it is `
+                + 'getting on. '
+                + (childLevel === 2
+                    ? 'It writes to the person itself when it is done, so nothing about that answer is yours '
+                        + 'to wait for or to repeat.'
+                    : 'What it writes comes back to you and to nobody else. When everybody you have sent has '
+                        + 'finished you are started again with what each of them wrote, and the one answer that '
+                        + 'covers them is yours to write, so do not wait here for it.'));
+        },
+    },
+    {
+        name: 'stop_run',
+        /* Level 1 may stop anything on its own card; level 2 only its own subtree;
+           level 3 nothing, so the tool is absent there. `panel3_stop_run` enforces
+           all three from the two run rows, which is why this list is the only thing
+           said about scope here: a second copy of the rule in a handler is one that
+           can disagree with the one that actually decides. */
+        levels: [1, 2],
+        description: 'Stop an agent that is running, and everything it dispatched. You may stop work you are '
+            + 'responsible for: the coordinator may stop anything on its card, and an agent may stop what '
+            + 'it sent out. Use it when the person says to stop, or when work you started is no longer '
+            + 'worth finishing. It says how many agents it stopped, and it stops nothing rather than '
+            + 'reaching outside what is yours. To stop your own work, just finish.',
+        input: { run_id: z.string() },
+        handler: async ({ client, runId }, args) => {
+            const { run_id } = args;
+            const { data, error } = await client
+                .rpc('panel3_stop_run', { p_by_run_id: runId, p_run_id: run_id });
+            if (error)
+                throw new Error(`could not stop run ${run_id}: ${error.message}`);
+            const stopped = data;
+            if (stopped === 0) {
+                /* NOTHING WAS STOPPED, and the reasons are one sentence because the
+                   agent cannot tell them apart from where it sits and every one of them
+                   means the same thing to it: that run is still going and you did not
+                   stop it. Thrown rather than returned, exactly as the other refusals in
+                   this file are, so there is no shape in which this reads as success. */
+                throw new Error(`NOTHING WAS STOPPED and run ${run_id} is untouched: it is not on your card, it is not `
+                    + 'yours to stop, it had already ended, it is you, or there is no such run. Say that it '
+                    + 'is still going rather than reporting it stopped.');
+            }
+            /* WHAT WAS WRITTEN, AND WHAT HAS NOT HAPPENED YET, both said. The row is
+               ended the instant this returns; the process is killed by the daemon on
+               its next poll, and an agent told otherwise would report the work gone
+               while its output was still arriving. */
+            return (`Stopped ${stopped} agent${stopped === 1 ? '' : 's'}: the one you named and everything it `
+                + 'had dispatched. They are ended on the record now, and their processes are killed within '
+                + 'a poll, so nothing more of theirs is coming. Nothing is waiting for you to do anything '
+                + 'about that.');
+        },
+    },
+];
+/**
+ * ═══ THE RECEIPT IS WRITTEN BY THE TOOL THAT MADE THE THING. ═══
+ *
+ * ux.md puts attribution in the mechanical column — "attribution is never agent
+ * judgement" — and `record_output` alone would put it squarely in the other one:
+ * an agent that created an epic and then forgot the second call leaves a card
+ * that produced nothing visible. So every `create_*` above writes its own
+ * receipt, and `record_output` stays for what these tools did not create.
+ *
+ * UPDATES DELIBERATELY WRITE NOTHING. A receipt answers "what did this card
+ * produce", and editing something twice did not produce it twice.
+ *
+ * ═══ AND AN ENDED RUN DOES NOT LEAVE RECEIPTS, WHICH IS THE ONE GUARD HERE
+ *     THAT IS NOT ATOMIC. ═══
+ *
+ * `report_activity` and `write_report` carry the liveness predicate in the same
+ * statement as their write. An INSERT into `panel3_outputs` cannot: the predicate
+ * is on a different table, and PostgREST has nowhere to put it. So this reads
+ * first and inserts second, and the window between them is stated rather than
+ * hidden.
+ *
+ * WHAT THE WINDOW COSTS IS SMALL AND IS NOT A FALSE CLAIM. A receipt written in
+ * it points at an object that genuinely exists and was genuinely made by that
+ * run; what is wrong is only that the run had just been given up on. The receipt
+ * is a duplicate of work another agent may redo, not an attribution to something
+ * that never happened, which is why it does not earn an RPC of its own today.
+ */
+async function receipt({ client, runId, cardId }, kind, refId, label) {
+    const live = await rows(client.from('panel3_runs').select('id').eq('id', runId)
+        .in('state', STILL_WRITING).is('ended_at', null), 'check', `whether run ${runId} is still running`);
+    if (live.length === 0) {
+        /* IT NAMES WHAT WAS MADE. The product row exists — it was created before
+           this was reached — so an error that only said "refused" would leave the
+           agent unable to say whether the thing is there. */
+        throw new Error(`the ${kind} ${refId} was created, but THIS RUN HAS ENDED so no receipt was written for it and `
+            + 'its card has been handed to another agent. Say what you made and stop.');
+    }
+    await only(client.from('panel3_outputs').insert({ card_id: cardId, run_id: runId, kind, ref_id: refId, label }).select('id'), 'record', `the ${kind} on the card`);
+}
+/** The names one level is served, in the order they are registered. Exported for
+ *  the same reason `cs3 show` exists: a rule nobody can print is a rule nobody
+ *  can check. */
+export function toolNamesForLevel(level) {
+    return TOOLS.filter((t) => t.levels.includes(level)).map((t) => t.name);
+}
+/**
+ * One tool's handler, by name. Exported for the same reason `toolNamesForLevel`
+ * is: a test that only calls `workBrief` with a hand-built array proves the
+ * formatter, not the wiring inside `dispatch` that reads a card's own
+ * attachments and threads them in. This is the seam that lets a test call the
+ * real handler with a fake `Caller` and see what it actually queried, without
+ * standing up the MCP transport `buildServer` wraps it in.
+ */
+export function toolHandler(name) {
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool)
+        throw new Error(`no tool named ${name}`);
+    return tool.handler;
+}
+// ---------------------------------------------------------------------------
+/**
+ * The server for ONE connection, carrying only that run's level's tools.
+ *
+ * Built per connection rather than once, which is what makes rule B structural:
+ * the tool list is assembled from the level, so there is no shared server whose
+ * list would have to be filtered on the way out.
+ */
+function buildServer(caller) {
+    const server = new McpServer({ name: 'ctrl-spc', version: '3.0.0' }, {
+        instructions: `You are a level ${caller.level} agent in CTRL+SPC. The tools you have are the tools your level `
+            + 'has: there are no others to ask for, and a tool you cannot see is one your level does not '
+            + 'hold rather than one that is missing.',
+    });
+    for (const tool of TOOLS) {
+        if (!tool.levels.includes(caller.level))
+            continue;
+        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.input }, (async (args) => {
+            try {
+                /* ═══ NOTHING THIS RUN READ GOES BACK OUT THROUGH A TOOL. ═══ Every
+                   argument of every tool, redacted before the handler sees it: see
+                   `redactArgs` for why the set is "all of them" rather than a list of
+                   the risky ones. This is one of the two chokepoints the rule rests
+                   on; `writeAnswer` in run.ts is the other. It is identity for the
+                   runs that read no credential, which is nearly all of them. */
+                const safe = redactArgs(caller.runId, args);
+                return { content: [{ type: 'text', text: await tool.handler(caller, safe) }] };
+            }
+            catch (error) {
+                /* ═══ A FAILURE REACHES THE AGENT AS A FAILURE. ═══ Constraint 7, at
+                   the one boundary where breaking it is invisible: an MCP tool that
+                   returned its error as ordinary content would have the agent read a
+                   refusal as a result, and report to the user that the work was done.
+                   `isError` is what makes the harness treat it as the failure it is. */
+                return {
+                    isError: true,
+                    content: [{
+                            type: 'text',
+                            text: error instanceof Error ? error.message : String(error),
+                        }],
+                };
+            }
+        }));
+    }
+    return server;
+}
+/**
+ * Start the v3 tools server on loopback, for the signed-in user this client
+ * carries.
+ *
+ * ═══ AN EPHEMERAL PORT, NOT A FIXED ONE. ═══ The daemon is the only thing that
+ * needs to know it, and it learns it here and puts it in each spawn's config, so
+ * a fixed port would buy nothing and cost a collision with whatever else on this
+ * machine is listening — including v1's and v2's own tools servers, and a second
+ * v3 daemon, which is a configuration this build's lease is proved with.
+ *
+ * ═══ THE RUN ID IS THE CREDENTIAL. ═══ v2's server carries a per-install token
+ * on the URL because it serves one long-lived connection surface that anything
+ * on the machine could find. This one is different in kind: the URL names ONE
+ * run, it is minted by the take, it is a v4 uuid, and it is handed to exactly
+ * one child process. A second token beside it would be a second secret guarding
+ * the same door. What it is NOT is a substitute for RLS: every read and write
+ * below goes through the signed-in user's own token, so guessing a run id would
+ * still only ever reach that user's own record.
+ */
+export async function startToolsServer(client, dispatch) {
+    const { data, error } = await client.auth.getUser();
+    if (error)
+        throw new Error(`could not start the tools server: ${error.message}`);
+    if (!data.user)
+        throw new Error('could not start the tools server: the client is not signed in');
+    const userId = data.user.id;
+    const transports = new Map();
+    /** Which run each open session belongs to, so a connection cannot change run
+     *  partway through. Bound at `initialize`, cleared with the session. */
+    const sessionRuns = new Map();
+    /** Known once the socket is bound, which is before any request can arrive. */
+    let port = 0;
+    const fail = (res, status, why) => {
+        res.writeHead(status, { 'Content-Type': 'text/plain' }).end(why);
+    };
+    async function handle(req, res) {
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        const runId = url.pathname.startsWith('/mcp/') ? url.pathname.slice('/mcp/'.length) : null;
+        if (!runId) {
+            fail(res, 404, 'Not found. The v3 tools server serves /mcp/<run-id> and nothing else.');
+            return;
+        }
+        const sessionHeader = req.headers['mcp-session-id'];
+        const sessionId = typeof sessionHeader === 'string' ? sessionHeader : undefined;
+        const existing = sessionId ? transports.get(sessionId) : undefined;
+        if (sessionId && existing) {
+            /* ═══ THE RUN A SESSION BELONGS TO NEVER CHANGES. ═══ Rule A is only worth
+               anything if it holds for every request, not just the first: a session
+               that could arrive on a different run's path would be an agent choosing
+               its own level after the fact. */
+            if (sessionRuns.get(sessionId) !== runId) {
+                fail(res, 400, 'Bad Request: this session belongs to a different run.');
+                return;
+            }
+            await existing.handleRequest(req, res);
+            return;
+        }
+        if (req.method !== 'POST') {
+            fail(res, 400, 'Bad Request: no valid session id.');
+            return;
+        }
+        const body = await readJson(req);
+        if (!isInitializeRequest(body)) {
+            fail(res, 400, 'Bad Request: no valid session id.');
+            return;
+        }
+        /* ═══ THE LEVEL, FROM THE RECORD, KEYED BY THE URL. ═══ Read through the
+           signed-in user's RLS, so a run belonging to somebody else is not found
+           rather than refused — which is the same answer, told without confirming
+           the row exists. */
+        const runs = await rows(client.from('panel3_runs').select('id, card_id, level, state, ended_at').eq('id', runId), 'read', `run ${runId}`);
+        const run = runs[0];
+        if (!run) {
+            fail(res, 404, `Not found: there is no run ${runId}.`);
+            return;
+        }
+        if (!STILL_WRITING.includes(run.state) || run.ended_at) {
+            /* A run that has ended has no tools. Serving it would let a process that
+               outlived its own row keep writing to the record under a run the panel
+               has already settled. `asked` is served for the reason `whileRunning`
+               gives: it is a process winding up, and what it writes down last is the
+               whole of what comes back with it. */
+            fail(res, 403, `Run ${runId} is ${run.state} and is no longer served.`);
+            return;
+        }
+        if (run.level !== 1 && run.level !== 2 && run.level !== 3) {
+            throw new Error(`run ${runId} has level ${run.level}, which is not a level this product has`);
+        }
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => crypto.randomUUID(),
+            onsessioninitialized: (sid) => {
+                transports.set(sid, transport);
+                sessionRuns.set(sid, runId);
+            },
+            // The same DNS-rebinding guard v2's server carries: a page on a public
+            // domain that re-resolves to 127.0.0.1 cannot drive this server from a
+            // browser, because the Host header will not be one we bound.
+            enableDnsRebindingProtection: true,
+            allowedHosts: [`127.0.0.1:${port}`, `localhost:${port}`],
+        });
+        transport.onclose = () => {
+            const sid = transport.sessionId;
+            if (sid) {
+                transports.delete(sid);
+                sessionRuns.delete(sid);
+            }
+        };
+        const server = buildServer({
+            client, userId, runId, cardId: run.card_id, level: run.level, dispatch,
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    }
+    const http = createHttpServer((req, res) => {
+        void handle(req, res).catch((err) => {
+            // Said, not swallowed. A tools server that answered 200 to a request it
+            // could not serve would have the agent read an empty result as an answer.
+            if (!res.headersSent) {
+                fail(res, 500, err instanceof Error ? err.message : String(err));
+            }
+            else
+                res.end();
+        });
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (err) => { http.off('listening', onListening); reject(err); };
+        const onListening = () => { http.off('error', onError); resolve(); };
+        http.once('error', onError);
+        http.once('listening', onListening);
+        // Loopback only, never all interfaces, and port 0 for "whatever is free".
+        http.listen(0, '127.0.0.1');
+    });
+    port = http.address().port;
+    return {
+        urlFor: (runId) => `http://127.0.0.1:${port}/mcp/${runId}`,
+        async close() {
+            await Promise.all([...transports.values()].map((t) => t.close().catch(() => { })));
+            transports.clear();
+            sessionRuns.clear();
+            await new Promise((resolve, reject) => {
+                http.close((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+}
+async function readJson(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    const raw = Buffer.concat(chunks).toString('utf8');
+    return raw ? JSON.parse(raw) : undefined;
+}