@ctrl-spc/cs 0.7.0 → 0.7.2

package/dist/panel3/tools.js

@@ -105,7 +105,7 @@
  * 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
+ * as it is for the person's own Stop: `panel3/cli.js 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.
  */
@@ -121,7 +121,8 @@ 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';
+import { readWorkflow } from '../workflows.js';
+import { ASK_CONTENT_COLUMNS, attachmentLine, gitRulesFor, loadAttachments, setMainBranch, 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.
@@ -176,6 +177,7 @@ const ended = (runId, verb) => `could not ${verb} run ${runId}: THIS RUN HAS END
 /** 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'];
+const secretScope = ({ runId, processToken }) => processToken === undefined ? runId : `${runId}:${processToken}`;
 /**
  * ═══ ASKING AND PASSING A QUESTION ON ARE ONE ACT, SO THEY ARE ONE FUNCTION.
  *     ═══
@@ -192,8 +194,61 @@ const STILL_WRITING = ['running', 'asked'];
  * 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;
+/**
+ * ═══ HOW MUCH A PERSON IS ASKED TO READ ON ONE CARD, AND WHY IT IS 700. ═══
+ *
+ * Issue 7. Measured, not chosen: every person-facing question this product has
+ * ever asked splits cleanly at this line. The five Lane read and called
+ * unreadable ran 959 to 1373 characters; every question nobody objected to was
+ * 594 or less. 700 is above the largest accepted and below the smallest
+ * rejected, so no question anybody has been happy with is refused by it.
+ *
+ * IT COUNTS EVERYTHING THE PERSON READS, not one field: the card renders the
+ * question, the context and every option together, so a bound on `context`
+ * alone is satisfied by moving the paragraph into `question` and the card is
+ * exactly as unreadable.
+ *
+ * AND IT LIVES IN THE HANDLERS, NOT IN A ZOD `.max()`. A schema rejection
+ * happens before the callback runs, so it never reaches `buildServer`'s
+ * try/catch and the agent gets a protocol error rather than a correctable tool
+ * failure. A throw from here comes back as `isError`, which is a refusal the
+ * caller can fix in the same turn. It is also why the bound reaches
+ * `ask_question` and `say` and NOT `escalate` or the shared `DECIDING` schema:
+ * an escalation is rewritten whole by whoever passes it on, so no unbounded
+ * child text is ever inherited by what the person reads.
+ */
+const PERSON_READS_LIMIT = 700;
+async function asked(caller, args, askPerson) {
+    const { client, runId, processToken } = caller;
+    const { question, category, context, answer_mode, options, question_id, work_item_id, related_artifact_id, } = args;
+    if (askPerson) {
+        /* ═══ REFUSED BEFORE ANYTHING IS WRITTEN, AND TOLD WHICH HALF TO CUT. ═══
+           Issue 6 made a question say what answering it causes, which is the half
+           worth keeping; what makes a question unreadable is the findings that got
+           carried in with it. So the refusal does not say "be brief" — it names the
+           total, the limit, and where the findings belong instead. */
+        const total = question.length + context.length
+            + (options ?? []).reduce((sum, option) => sum + option.length, 0);
+        if (total > PERSON_READS_LIMIT) {
+            throw new Error(`NOTHING WAS WRITTEN and nobody was asked: that question is ${total} characters and they `
+                + `read it on a card three inches wide. The limit is ${PERSON_READS_LIMIT}, counting the `
+                + 'question, the context and every option together. Cut what you found, not what each '
+                + 'answer causes; findings belong in the artifact or your report.');
+        }
+    }
+    if (related_artifact_id !== undefined
+        && (!askPerson || caller.level !== 2 || !caller.isOwner || processToken === undefined)) {
+        throw new Error('NOTHING WAS WRITTEN. An artifact approval question can be opened only by the current '
+            + 'Level 2 conversation owner with its current process token.');
+    }
+    if (related_artifact_id !== undefined && (!work_item_id?.trim()
+        || answer_mode !== 'single_select'
+        || options?.length !== 2
+        || options[0] !== 'approve'
+        || options[1] !== 'request changes')) {
+        throw new Error('NOTHING WAS WRITTEN. An artifact approval question requires its Work Item, '
+            + 'answer_mode single_select, and exactly these options in order: approve, request changes.');
+    }
     const [ask] = await rows(client.rpc('panel3_ask', {
         p_run_id: runId,
         p_question: question,
@@ -209,6 +264,9 @@ async function asked(client, runId, args, askPerson) {
            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,
+        ...(related_artifact_id === undefined
+            ? (processToken === undefined ? {} : { p_process_token: processToken })
+            : { p_process_token: processToken, p_related_artifact_id: related_artifact_id }),
     }), 'put', 'your question where it can be answered');
     if (!ask) {
         /* NOTHING WAS WRITTEN, and the reasons are said together because the agent
@@ -284,6 +342,48 @@ const DECIDING = {
         + '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.'),
 };
+// ---------------------------------------------------------------------------
+// PROJECT CONTEXT (19/project-context-7b). `public.project_documents` — the
+// reference a team writes in the web app: architecture, design notes, how a
+// subsystem came to be the way it is. Read when the work needs it, at every
+// level, and ADDED TO by the levels that do the work.
+//
+// ═══ IT IS NOT THE SAME TABLE AS THE STANDING RULES, AND THAT IS THE POINT.
+// ═══ `public.agent_instructions` is an OBLIGATION and arrives in the prompt,
+// whole, before an agent acts; no tool here reads or writes it, at any level. A
+// reference an agent chooses to read and a mandate it is handed are two
+// different things, and the schema keeps them apart so a tool cannot confuse
+// them (see 20260919090000_agent_instructions.sql).
+/**
+ * ═══ THE READ IS BOUNDED, AND IT SAYS WHEN IT BOUNDED SOMETHING. ═══
+ *
+ * `project_documents.content` is unbounded `text` and a project may hold any
+ * number of documents, so an unbounded read would put a team's whole corpus into
+ * the same window the mandatory standing-rules block needs — and would do it
+ * silently. There is no existing row or byte limit anywhere in this file to
+ * inherit: `mcp.ts` has one of the right shape, and conventions.md rule 2 forbids
+ * `panel3/` to import it.
+ *
+ * TWO BOUNDS RATHER THAN ONE, because they catch different shapes: many small
+ * documents, and one enormous one. Whichever bites, the response ends by saying
+ * how many documents it did not show and how to ask for fewer — a truncation
+ * nobody is told about reads as a project with nothing else written down, which
+ * is worse than the read failing.
+ */
+const CONTEXT_DOCUMENT_ROWS = 50;
+const CONTEXT_DOCUMENT_CHARACTERS = 60000;
+/**
+ * Which project the caller's card is filed under, or null when it has none.
+ *
+ * `panel3_cards.project_id` IS NULLABLE and a record-only card genuinely has no
+ * project, so null is a fact rather than a failure and each caller words its own
+ * refusal. A failed READ throws through `rows`, which is a different thing again
+ * and must never be flattened into "no project".
+ */
+async function projectOfCard(caller) {
+    const cards = await rows(caller.client.from('panel3_cards').select('project_id').eq('id', caller.cardId), 'read', `the project for card ${caller.cardId}`);
+    return cards[0]?.project_id ?? null;
+}
 const ALL = [1, 2, 3];
 const line = (...parts) => parts.filter(Boolean).join('  ');
 const listed = (items, empty) => (items.length === 0 ? empty : items.join('\n'));
@@ -651,6 +751,92 @@ const TOOLS = [
             ].join('\n');
         },
     },
+    {
+        name: 'get_workflow',
+        /* ═══ LEVEL 2 ALONE, AND THAT IS A DELIBERATE DIVERGENCE FROM `get_skill`'s
+           `ALL`. ═══ `get_skill`'s own comment argues level 1 needs it because "a
+           coordinator that cannot read the skill cannot write a responsibility that
+           respects it". That argument does not carry across, and the difference is
+           what a launcher is writing. A skill is a METHOD that applies to whatever
+           single responsibility level 1 writes, so a launcher ignorant of it writes
+           a responsibility that contradicts it. A workflow is not applied to the
+           launcher's responsibility: it is a SEQUENCE the OWNER decomposes, and the
+           launcher writes one line — see this conversation through — for the agent
+           that reads the process itself. `attachmentLine` already prints the
+           workflow's NAME in the launcher's prompt, so it can name the process in
+           what it writes without reading a stage of it.
+    
+           AND NOT LEVEL 3 EITHER. A worker owns one piece and nothing else; handing
+           it the whole recipe invites it to run stages that are not its. What it
+           does need — its own stage's document — reaches it in its brief, because
+           `workBrief` tells the owner to put it there. Same narrowing, same reason,
+           as `get_credential` below.
+    
+           AND THERE IS NO `list_workflows` 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 workflow. */
+        levels: [2],
+        description: 'Read the workflow attached to this conversation. A workflow is the PROCESS this work '
+            + 'follows: named stages in an order, each with a document to work to. Call this with the id '
+            + 'printed beside the workflow in what was attached, and read all of it before you decide how '
+            + 'this work is split.',
+        input: { workflow_id: z.string() },
+        handler: async ({ client }, args) => {
+            const { workflow_id } = args;
+            const workflow = await readWorkflow(client, workflow_id);
+            /* ═══ EXITS RESOLVE TO A NUMBERED STAGE, NEVER TO A RAW UUID. ═══
+               `to_stage_id` is a uuid and no v3 tool at any level takes one, so a raw
+               id would be a reference the reader cannot follow. This matters
+               concretely: exits are the only surviving representation of a REPEAT, and
+               every org is seeded with a feature loop whose exits are mostly backward.
+               A rendering that dropped them would present the one workflow every org
+               actually has as a straight line, which is a different process. */
+            const numberOf = new Map(workflow.stages.map((stage, i) => [stage.id, i + 1]));
+            const exitsOf = (stageId) => workflow.exits
+                .filter((exit) => exit.stageId === stageId)
+                .map((exit) => {
+                const number = numberOf.get(exit.toStageId);
+                const stage = workflow.stages.find((candidate) => candidate.id === exit.toStageId);
+                return number && stage
+                    ? `if ${exit.condition}, go to stage ${number} ${stage.name}`
+                    : `if ${exit.condition}, go back to an earlier stage`;
+            });
+            return [
+                workflow.name,
+                `id        ${workflow.id}`,
+                `about     ${workflow.description.trim() === '' ? 'no description' : workflow.description}`,
+                '',
+                `STAGES  ${workflow.stages.length}`,
+                ...workflow.stages.flatMap((stage, i) => [
+                    '',
+                    line(`${i + 1}. ${stage.name}`, stage.description.trim() === '' ? null : stage.description),
+                    '',
+                    /* THE WHOLE BODY. The body IS the stage document, so truncating it is
+                       truncating the process. An empty one is a stage nobody has written
+                       yet, which is a real state and is said rather than hidden. */
+                    stage.body.trim() === '' ? '(this stage has not been written yet)' : stage.body,
+                    ...exitsOf(stage.id),
+                ]),
+                '',
+                /* ═══ THE PERSON'S ENDING CHOICE, SAID RATHER THAN OBEYED OR DISCARDED.
+                   ═══ They picked it in the web app's own picker. v3 has no backlog read
+                   at any level — `list_work_items` is newest-first with no rank — so
+                   this cannot be done here. Rendering the raw value would invite
+                   improvisation and rendering nothing would silently discard their
+                   choice, which is the untruthful failure the guide forbids. The slice
+                   that gives v3 a backlog read replaces this sentence. */
+                ...(workflow.ending === 'next-in-backlog'
+                    ? [
+                        'This workflow is set to start again on the next backlog item. That is not available '
+                            + 'here: stop when the last stage is done, and say so.',
+                        '',
+                    ]
+                    : []),
+                'This is a WORKFLOW: the process to FOLLOW for this work, stage by stage in the order '
+                    + 'above. It is not a document to summarise, quote back or file away.',
+            ].join('\n');
+        },
+    },
     {
         name: 'get_credential',
         /* ═══ LEVELS 2 AND 3, AND THAT IS A CORRECTION TO ux.md's OWN TABLE. ═══
@@ -675,7 +861,7 @@ const TOOLS = [
             + '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) => {
+        handler: async ({ client, runId, processToken }, 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. ═══
@@ -711,7 +897,7 @@ const TOOLS = [
                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);
+            rememberSecret(secretScope({ runId, processToken }), secret, row.name);
             const username = typeof value.username === 'string' ? value.username : null;
             return [
                 row.name,
@@ -746,13 +932,14 @@ const TOOLS = [
         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')
+                .select('id, task_id, type, format, title, content, storage_path, revision, 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})`,
+                `revision     ${artifact.revision}`,
                 '',
                 /* A stored file and an empty body are different facts and are said
                    differently. Returning '' for a PNG would read as an artifact with
@@ -761,6 +948,85 @@ const TOOLS = [
             ].join('\n');
         },
     },
+    {
+        name: 'get_project_context',
+        /* ALL THREE, straight off ux.md's "Who gets what" table, where
+           `get_project_context` has always sat in the "Read the record" row. Reading
+           what a team has written down is not a privilege any level is denied. */
+        levels: ALL,
+        description: 'The documentation this project\'s team has written: architecture, design notes, conventions, '
+            + 'how a subsystem came to be the way it is. Read it when the work needs it — before you '
+            + 'design something, before you follow a convention you are guessing at, and before you tell '
+            + 'the person how this project does something. Pass a codebase id to get that codebase\'s own '
+            + 'documents as well as the project\'s.',
+        input: {
+            codebase_id: z.string().uuid().optional().describe('A registered project codebase, to get its OWN documents alongside the project-wide ones. '
+                + 'Leave it out for the project-wide documents alone.'),
+        },
+        handler: async (caller, args) => {
+            const { codebase_id } = args;
+            const projectId = await projectOfCard(caller);
+            if (!projectId) {
+                return 'This conversation is not filed under a project, so there is no project context to read.';
+            }
+            const scoped = caller.client
+                .from('project_documents')
+                .select('id, title, type, codebase_id, content')
+                .eq('project_id', projectId);
+            const documents = await rows((codebase_id === undefined
+                ? scoped.is('codebase_id', null)
+                : scoped.or(`codebase_id.is.null,codebase_id.eq.${codebase_id}`))
+                /* MOST SPECIFIC FIRST, the order ux.md gives for the two scopes: a
+                   codebase's documents beat the project's for work in that codebase,
+                   so they are read first and are the ones that survive the bound. */
+                .order('codebase_id', { nullsFirst: false })
+                .order('created_at')
+                /* ONE MORE THAN THE CAP, so "there are more" is something this read
+                   OBSERVED rather than something it assumed from a full page. The
+                   extra row is never rendered; it only makes the closing line honest,
+                   and it is why the count below is "at least". */
+                .limit(CONTEXT_DOCUMENT_ROWS + 1), 'read', `the project context on project ${projectId}`);
+            const withinRows = documents.slice(0, CONTEXT_DOCUMENT_ROWS);
+            const pastRowCap = documents.length > CONTEXT_DOCUMENT_ROWS;
+            /* THE CHARACTER WALK. The first document is always included whatever its
+               size: a project whose one document is larger than the whole budget must
+               still get an answer, and truncating a document's BODY would hand an
+               agent half a convention with no sign of where it stopped. */
+            const shown = [];
+            let used = 0;
+            for (const document of withinRows) {
+                if (used + document.content.length > CONTEXT_DOCUMENT_CHARACTERS && shown.length > 0)
+                    break;
+                shown.push(document);
+                used += document.content.length;
+            }
+            if (shown.length === 0) {
+                return codebase_id === undefined
+                    ? 'This project has no context documents yet.'
+                    : 'This project and that codebase have no context documents yet.';
+            }
+            const cut = withinRows.length - shown.length;
+            return [
+                ...shown.flatMap((document) => [
+                    `--- ${document.title}  (${document.type}${document.codebase_id === null ? ', project' : ', this codebase'})  id ${document.id} ---`,
+                    document.content,
+                    '',
+                ]),
+                /* ═══ SAID WHENEVER SOMETHING WAS LEFT OUT, AND NEVER OTHERWISE. ═══ A
+                   complete answer that ends by discussing its own limits teaches an
+                   agent to distrust a read that was fine. */
+                ...(cut > 0 || pastRowCap
+                    ? [
+                        `NOT EVERYTHING IS ABOVE: at least ${cut + (pastRowCap ? 1 : 0)} more `
+                            + `${cut + (pastRowCap ? 1 : 0) === 1 ? 'document was' : 'documents were'} not shown. `
+                            + `This read is capped at ${CONTEXT_DOCUMENT_ROWS} documents and `
+                            + `${CONTEXT_DOCUMENT_CHARACTERS} characters, and the most specific documents come `
+                            + 'first. Ask again without a codebase, or for one codebase at a time, to narrow it.',
+                    ]
+                    : []),
+            ].join('\n');
+        },
+    },
     {
         name: 'list_cards',
         /* ═══ LEVEL 1 ONLY, AND THIS OVERRIDES plan.md's TABLE. ═══ The plan grants
@@ -887,6 +1153,136 @@ const TOOLS = [
     // 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.
+    /**
+     * ═══ THE ANSWER TO THE ONE GIT QUESTION A PERSON IS EVER ASKED. ═══
+     *
+     * worktrees-8, story 3: a codebase whose base branch is genuinely ambiguous is
+     * settled by asking the person ONCE, and the answer is stored on the CODEBASE
+     * rather than on the card that prompted it, so nobody is asked twice.
+     *
+     * A TOOL RATHER THAN A SIDE EFFECT OF THE ANSWER, for two reasons. The answer
+     * has to land on the codebase and an ask lands on a card. And the only other
+     * route is teaching the questions surface to write a settings table, which
+     * would couple two things that have no reason to know each other.
+     *
+     * LEVEL 1 ONLY. It is the coordinator that sees across cards, that holds
+     * `ask_question`, and that needs the fact before it dispatches. A level 2 or 3
+     * agent asking would be asking about a card, mid-work, having already started
+     * in the wrong place.
+     */
+    {
+        name: 'set_main_branch',
+        levels: [1],
+        description: 'Record which branch finished work in a codebase should go back to. Use this ONLY after asking '
+            + 'the person and getting an answer: it is the organization\'s setting, it applies to every '
+            + 'member and every future card in that codebase, and nobody is asked again. Never guess it, '
+            + 'and never call this to change a branch somebody already set.',
+        input: {
+            codebase_id: z.string().describe('The codebase id, as the codebase list gave it to you.'),
+            branch: z.string().min(1).describe('The branch name exactly as the person chose it.'),
+        },
+        handler: async (caller, args) => {
+            const { codebase_id, branch } = args;
+            /* THROUGH `show.ts`, WHICH IS THE ONE FILE UNDER panel3/ THAT MAY NAME
+               THIS TABLE. conventions.md records why, and
+               panel3-isolation.contract.test.mjs pins it: reads and writes alike go
+               through one file, so a grep for the table finds every caller. */
+            await setMainBranch(caller.client, codebase_id, branch);
+            return `Work in that codebase now starts from ${branch} and goes back to it. `
+                + 'Nobody will be asked again.';
+        },
+    },
+    /**
+     * ═══ THE AGENT ASKS FOR THE OFFER; THE PRODUCT WRITES IT. ═══
+     *
+     * worktrees-8 C1. `ask_question`'s options are typed by a model out of prose,
+     * so any product rule that reads them back is a rule about transcription. This
+     * tool carries ONE agent-typed string, `what_was_done`, and nothing is ever
+     * compared against it: the question, both answers and the merge itself are the
+     * product's, exactly as an artifact approval already is.
+     *
+     * ═══ IT READS STAMPS, IT DOES NOT RESOLVE ANYTHING. ═══ `branch` and `base`
+     * were written by `cardWorktree` precisely so a second reader would not
+     * re-implement the derivation. No git runs here.
+     */
+    {
+        name: 'offer_ending',
+        /* ═══ LEVEL 2 ONLY, AND THE DATABASE RECHECKS THAT IT IS THE OWNER. ═══
+           Level 1 never holds a card's branch, and level 3 has no ending and does
+           not speak to the person. */
+        levels: [2],
+        description: 'Offer the person the ending for this card: put the finished work onto the main branch, or '
+            + 'leave it on its branch. Call this when the card\'s work is DONE and the codebase lands on '
+            + 'the main branch. You do not write the question or the answers and you never merge anything: '
+            + 'the product composes both, and it performs the merge itself if they choose to put the work '
+            + 'back. Say in one sentence what was done, in their words. After this call, stop immediately: '
+            + 'you are started again with what the product did with their answer.',
+        input: {
+            what_was_done: z.string().min(1).describe('One sentence, in the person\'s words, saying what this card\'s work actually changed. It is '
+                + 'the only part of the offer you write.'),
+        },
+        handler: async (caller, args) => {
+            const { what_was_done } = args;
+            const { client, runId, processToken } = caller;
+            if (!caller.isOwner || processToken === undefined) {
+                throw new Error('NOTHING WAS WRITTEN. Only this card\'s current conversation owner can offer the ending.');
+            }
+            if (what_was_done.length > PERSON_READS_LIMIT) {
+                throw new Error(`NOTHING WAS WRITTEN and nobody was asked: that is ${what_was_done.length} characters and `
+                    + `they read it on a card three inches wide. The limit is ${PERSON_READS_LIMIT}. One `
+                    + 'sentence saying what changed.');
+            }
+            const run = await only(client.from('panel3_runs')
+                .select('codebase_id, branch, base, card:panel3_cards!panel3_runs_card_id_fkey(project_id)')
+                .eq('id', runId), 'read', 'which branch this card\'s work is on');
+            if (!run.codebase_id || !run.branch || !run.base || !run.card?.project_id) {
+                throw new Error('NOTHING WAS WRITTEN. This card has no codebase, branch and base recorded, so there is no '
+                    + 'ending to offer. Say what you did and finish the card.');
+            }
+            const rules = await gitRulesFor(client, run.codebase_id, run.card.project_id);
+            if (rules.landing !== 'main') {
+                throw new Error('NOTHING WAS WRITTEN. Finished work in this codebase does not go onto the main branch, so '
+                    + 'there is no ending to offer. Say where the work is and finish the card.');
+            }
+            const [ask] = await rows(client.rpc('panel3_ask', {
+                p_run_id: runId,
+                /* THE QUESTION AND THE CONTEXT ARE COMPOSED HERE, from the two stamps,
+                   which is why story 4's scenario can promise the branch and the
+                   separation are in it. The agent's sentence is appended to the
+                   context and decides nothing. */
+                p_question: `Put this work onto ${run.base}?`,
+                p_category: 'Finished work',
+                p_context: `The work on this card is finished and is on branch ${run.branch}, in a copy of its own, `
+                    + 'apart from anything else working in this codebase on this computer. '
+                    + what_was_done,
+                /* ═══ PASSED AND THEN IGNORED, AND BOTH HALVES ARE DELIBERATE. ═══ The
+                   statement overwrites the mode and the options with the product's own
+                   when `p_offers_landing` is true, which is where they are enforced.
+                   They are named here only because the twelve-argument core carries no
+                   defaults, so PostgREST resolves the overload by the exact argument
+                   set it is given. */
+                p_answer_mode: 'single_select',
+                p_options: [],
+                p_question_id: null,
+                p_work_item_id: null,
+                p_ask_person: true,
+                p_process_token: processToken,
+                p_related_artifact_id: null,
+                p_offers_landing: true,
+            }), 'put', 'the ending where it can be answered');
+            if (!ask || ask.ask_id === null) {
+                throw new Error(`NOTHING WAS WRITTEN and nobody was asked: run ${runId} has already ended, or a question `
+                    + `is already waiting on you${ask?.held_question ? ` (${ask.held_question})` : ''}. Deal `
+                    + 'with that first.');
+            }
+            return [
+                `The ending is with the person now, id ${ask.ask_id}. They were asked whether this work `
+                    + `should go onto ${run.base}, with the product's own two answers.`,
+                'YOU HAVE STOPPED. Do not merge anything and do not finish the card: when they answer, you',
+                'are started again and told what the product did.',
+            ].join('\n');
+        },
+    },
     {
         name: 'create_epic',
         levels: [1],
@@ -1053,15 +1449,152 @@ const TOOLS = [
             return `Updated artifact ${artifact.title ?? artifact.id}.`;
         },
     },
+    {
+        name: 'add_project_context',
+        /* ═══ THE LEVELS THAT DO THE WORK, AND ux.md IS AMENDED RATHER THAN ARGUED
+           PAST. ═══ A context document is a PRODUCED OBJECT, not board structure, so
+           it does not fall under "product structure is level 1's alone"; and the
+           levels that do the work are the levels that learn something worth keeping,
+           while level 1 launches and exits. ux.md's "Who gets what" table carries
+           this ruling, and `panel3-tools.contract.test.mjs` pins all three lists to
+           it exhaustively. */
+        levels: [2, 3],
+        /* ═══ ADD, AND NEVER CHANGE OR REMOVE. ═══ `project_documents` has no
+           history, no version UI and no DELETE policy — hard delete is unreachable
+           rather than merely un-surfaced. That was safe while no agent could write
+           these rows at all. An agent UPDATE would permanently overwrite a person's
+           own text with nothing to restore from, policed only by a sentence in a
+           description. So the tool adds and never changes, and the name says so
+           rather than the description having to. */
+        description: 'Write one new document into this project\'s context — the reference the team keeps for work '
+            + 'like this. Use it when the conversation SETTLES something the project should keep: a '
+            + 'convention agreed, how a subsystem actually fits together, why an approach was rejected. '
+            + 'It adds a document and never changes or removes one, so do not use it to correct something '
+            + 'already written; say what is wrong in your report instead. Not for the work you were sent '
+            + 'to do — that goes in an artifact on the work item.',
+        input: {
+            title: z.string().min(1).max(100).describe('What this document is, in a few words a teammate would search for. 100 characters at most.'),
+            type: z.enum(['instructions', 'architecture', 'design', 'conventions', 'other']).describe('Which kind of reference this is, matching the five the web app offers.'),
+            content: z.string().min(1).describe('The document itself, in markdown, complete. It is read by people and by agents on later '
+                + 'work, neither of whom has seen this conversation.'),
+            scope: z.enum(['project', 'codebase']).optional().describe('`codebase` files it under the codebase you are working in, for something true of that repo '
+                + 'and no other. Defaults to `project`, which every codebase inherits.'),
+        },
+        handler: async (caller, args) => {
+            const a = args;
+            /* ═══ THE PROJECT COMES OFF THE RUN'S OWN CARD, NEVER OFF AN ARGUMENT.
+               ═══ There is no `project_id` input, deliberately: RLS is org-scoped, so
+               a card in one project could otherwise write a document into a sibling
+               project in the same organization, and nothing about that would look like
+               a mistake afterwards. */
+            const projectId = await projectOfCard(caller);
+            if (!projectId) {
+                throw new Error('NOTHING WAS WRITTEN: this conversation is not filed under a project, so there is no '
+                    + 'project context to add to. Put what you learned in your report instead.');
+            }
+            let codebaseId = null;
+            if (a.scope === 'codebase') {
+                /* THE RUN'S OWN CODEBASE, AND NO OTHER, for the same reason the project
+                   is not an argument. A level 2 owner on a record-only card has none,
+                   and that is a refusal rather than a silent fall back to project
+                   scope: filing a codebase-specific note project-wide puts it in front
+                   of work it does not apply to. */
+                const runs = await rows(caller.client.from('panel3_runs').select('codebase_id').eq('id', caller.runId), 'read', `the codebase run ${caller.runId} belongs to`);
+                codebaseId = runs[0]?.codebase_id ?? null;
+                if (!codebaseId) {
+                    throw new Error('NOTHING WAS WRITTEN: this work is not attached to a codebase, so it has no codebase '
+                        + 'to file a document under. Call this again with scope `project` if it holds for the '
+                        + 'whole project.');
+                }
+            }
+            const document = await only(caller.client.from('project_documents').insert({
+                project_id: projectId,
+                codebase_id: codebaseId,
+                title: a.title.trim(),
+                type: a.type,
+                content: a.content,
+            }).select('id, title'), 'write', 'a project context document');
+            return (`Written. "${document.title}" is in this project's context now, id ${document.id}`
+                + `${codebaseId === null ? '' : ', filed under this codebase'}. `
+                + 'The person will find it under Project settings. You cannot change or remove it, so if it '
+                + 'needs correcting, say so rather than writing a second one.');
+        },
+    },
+    // ── Say something now ────────────────────────────────────────────────────
+    //
+    // ═══ LEVEL 2 ONLY, AND THE DATABASE IS WHAT ENFORCES IT. ═══ `panel3_say`
+    // refuses any run that is not the one `panel3_cards.conversation_run_id`
+    // names, and only a level 2 run is ever appointed, so a worker cannot reach
+    // the person through this however the list below is edited. The tool is absent
+    // at 1 and 3 as well, so an agent that has no business calling it is not
+    // offered it and then refused.
+    //
+    // ═══ WHY IT EXISTS AT ALL, GIVEN `panel3_answer`. ═══ Nothing reached the
+    // person until the owner's process exited, and a turn that ends by asking
+    // writes no message at all. Measured 2026-08-24: "Write a plan for this item"
+    // was silent for two and a half minutes and then said a question. An
+    // acknowledgement cannot be an exit, because an exit is the end of the turn.
+    {
+        name: 'say',
+        levels: [2],
+        description: 'Say something to the person NOW, without stopping. Use it the moment you know what you are '
+            + 'going to do, before you start doing it: they have seen only their own message, and until '
+            + 'you say something the card shows them a pulse. One or two sentences in their words, saying '
+            + 'what you are about to do and what they will get. Use it again if what you are doing changes '
+            + 'in a way they would want to know about. It does NOT end your turn, does not answer them, '
+            + 'and does not replace the reply or the question you finish with: keep working after it. Do '
+            + 'not use it for a running commentary, and do not use it to ask anything.',
+        input: {
+            message: z.string().min(1).describe('What they should read, in their words. "Reading the search screen first, then I\'ll write '
+                + 'the plan and bring it to you."'),
+        },
+        handler: async ({ client, runId, processToken }, args) => {
+            const { message } = args;
+            /* ═══ THE SAME BOUND AS A QUESTION, BECAUSE IT IS THE SAME CARD. ═══
+               Issue 7. Without this the bound on `ask_question` is theatre: an owner
+               refused on a question can put the same paragraph in front of the same
+               person through this door, and it does not even end its turn to do it. */
+            if (message.length > PERSON_READS_LIMIT) {
+                throw new Error(`NOTHING WAS WRITTEN: that is ${message.length} characters and they read it on a card `
+                    + `three inches wide. The limit is ${PERSON_READS_LIMIT}. One or two sentences saying `
+                    + 'what you are about to do; what you found goes in the artifact or your report.');
+            }
+            const { data, error } = await client.rpc('panel3_say', {
+                p_run_id: runId,
+                p_body: message,
+                ...(processToken === undefined ? {} : { p_process_token: processToken }),
+            });
+            if (error)
+                throw new Error(`could not say that on this card: ${error.message}`);
+            /* ═══ REFUSED, AND THE AGENT IS TOLD SO RATHER THAN LEFT BELIEVING IT
+               SPOKE. ═══ Three reasons collapse to one sentence because the caller
+               cannot tell them apart and all three mean the same thing to it: this
+               conversation is not yours to speak on any more. An owner that thinks it
+               acknowledged and did not is the failure this tool exists to remove,
+               arrived at from the other side. */
+            if (data === null) {
+                throw new Error('NOTHING WAS WRITTEN: this conversation is not yours to speak on. It has been stopped, '
+                    + 'or somebody else owns it now. Do not tell anybody you said anything.');
+            }
+            return 'Said. They can read it now. Carry on.';
+        },
+    },
     // ── 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. '
+            + 'The line says what you are FINDING OUT or what you are CHANGING, not the steps you are '
+            + 'running to do it: "Checking for clock use, CI config, and running the test suite once" tells '
+            + 'a reader nothing, where "Working out whether the code can tell what happened this week" tells '
+            + 'them what turns on it. You do not need to have seen anybody\'s message to write one. '
             + '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) => {
+        input: {
+            activity: z.string().min(1).describe('One line, present tense, naming what you are finding out or changing. "Working out whether '
+                + 'the code can tell what happened this week".'),
+        },
+        handler: async ({ client, runId, processToken }, 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
@@ -1070,7 +1603,11 @@ const TOOLS = [
                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');
+            await whileRunning(client.rpc('panel3_report_activity', {
+                p_run_id: runId,
+                p_activity: activity,
+                ...(processToken === undefined ? {} : { p_process_token: processToken }),
+            }), runId, 'record what you are doing on');
             return 'Noted.';
         },
     },
@@ -1082,12 +1619,14 @@ const TOOLS = [
             + '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) => {
+        handler: async ({ client, runId, processToken }, 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');
+            await whileRunning(processToken === undefined
+                ? client.from('panel3_runs').update({ report }).eq('id', runId)
+                    .in('state', STILL_WRITING).is('ended_at', null).select('id')
+                : client.rpc('panel3_write_report', {
+                    p_run_id: runId, p_report: report, p_process_token: processToken,
+                }), runId, 'write the report on');
             return 'Report written.';
         },
     },
@@ -1134,6 +1673,9 @@ const TOOLS = [
                    question carried them, and absent rather than printed as empty. */
                 ...(a.category ? [`  ${a.category}`] : []),
                 ...(a.context ? [`  why  ${a.context}`] : []),
+                ...(a.related_artifact_id ? [
+                    `  artifact  ${a.related_artifact_id}  presented revision ${a.related_artifact_revision ?? 'not recorded'}`,
+                ] : []),
                 `  Q  ${a.question ?? '(this question could not be read)'}`,
                 ...(a.options ?? []).map((option) => `  -  ${option}`),
                 `  A  ${a.answer ?? 'not answered yet'}`,
@@ -1147,11 +1689,28 @@ const TOOLS = [
            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.',
+        description: 'Put a question to the person, and stop. A Level 1 launcher uses this only for a destination '
+            + 'or codebase it truly cannot choose; it launches the owner for every work or product '
+            + 'decision. A Level 2 owner MUST use this tool when work cannot continue '
+            + 'until the person answers, including when they must choose between options; an ordinary '
+            + 'reply is not a question path and completing the card with a question is wrong. Ask only '
+            + 'what you genuinely cannot settle from the '
+            + 'record, by dispatching someone to find out, or by answering it yourself. Use the shortest '
+            + 'question and context the person can answer safely. 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. For an artifact approval, name its Work Item and live artifact, '
+            + 'offer approve or request changes, and present one revision at a time. THE QUESTION LINE '
+            + 'ITSELF SAYS WHAT THEY ARE APPROVING, in plain words, never further down in the context: '
+            + 'approving a document that describes work is not the same as approving the work, and the '
+            + 'person cannot tell those apart from the title of an artifact. Write it the way these are '
+            + 'written: "Plan is written. Please read it and approve or ask for changes", "Ok to write a '
+            + 'spec.md and attach it to this work item?", "The work item has a detailed plan. Ok to start '
+            + 'building?". A question that names the artifact and leaves the reader to work out what '
+            + 'approving starts is the one this rule exists to stop. '
+            + 'After this call, stop immediately. '
+            + 'Do not repeat the question in '
+            + 'an ordinary reply or add a message saying that you asked it.',
         input: {
             question: z.string().min(1),
             ...DECIDING,
@@ -1162,8 +1721,11 @@ const TOOLS = [
                 + '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.'),
+            related_artifact_id: z.string().optional().describe('The live Analysis or Plan artifact on work_item_id that this decision presents for approval '
+                + 'or sends back for changes. Only the current Level 2 conversation owner may name it, and '
+                + 'its current process token is required. Leave it out for every ordinary question.'),
         },
-        handler: async ({ client, runId }, args) => asked(client, runId, args, true),
+        handler: async (caller, args) => asked(caller, args, true),
     },
     {
         name: 'escalate',
@@ -1176,7 +1738,7 @@ const TOOLS = [
             + '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),
+        handler: async (caller, args) => asked(caller, args, false),
     },
     {
         name: 'answer_escalation',
@@ -1189,7 +1751,7 @@ const TOOLS = [
             + '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) => {
+        handler: async ({ client, runId, processToken }, 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
@@ -1202,6 +1764,7 @@ const TOOLS = [
                 p_selected_options: [],
                 p_answer_note: answer,
                 p_by_run_id: runId,
+                ...(processToken === undefined ? {} : { p_process_token: processToken }),
             });
             if (error)
                 throw new Error(`could not answer question ${question_id}: ${error.message}`);
@@ -1245,7 +1808,8 @@ const TOOLS = [
             + '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.'),
+            codebase_id: z.string().uuid().optional().describe('The id of the registered project codebase this work belongs to. A launcher may omit this '
+                + 'for record-only work; an owner dispatching a worker must provide it.'),
             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.'),
@@ -1253,15 +1817,20 @@ const TOOLS = [
         },
         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.');
+            if (caller.level === 2 && !codebase_id) {
+                throw new Error('A worker must be attached to a registered project codebase.');
             }
-            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.');
+            let codebase = null;
+            if (codebase_id) {
+                const projectId = await projectOfCard(caller);
+                if (!projectId) {
+                    throw new Error('This conversation is not filed under a project, so it has no codebase to use.');
+                }
+                codebase = (await listCodebases(caller.client, projectId))
+                    .find((candidate) => candidate.id === codebase_id) ?? null;
+                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,
@@ -1277,11 +1846,9 @@ const TOOLS = [
                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);
+            const { runId } = await caller.dispatch(caller.runId, workBrief(childLevel, responsibility, boundary, work_item_id, attachments, codebase === null ? undefined : {
+                id: codebase.id, name: codebase.name, identity: codebase.gitRemoteUrl,
+            }), codebase, caller.processToken);
             /* ═══ 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
@@ -1293,8 +1860,8 @@ const TOOLS = [
             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.'
+                    ? 'That owner now has the conversation. Your launcher work is finished: write no reply, '
+                        + 'ask nothing else, and exit immediately.'
                     : '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.'));
@@ -1314,10 +1881,14 @@ const TOOLS = [
             + '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) => {
+        handler: async ({ client, runId, processToken }, args) => {
             const { run_id } = args;
             const { data, error } = await client
-                .rpc('panel3_stop_run', { p_by_run_id: runId, p_run_id: run_id });
+                .rpc('panel3_stop_run', {
+                p_by_run_id: runId,
+                p_run_id: run_id,
+                ...(processToken === undefined ? {} : { p_process_token: processToken }),
+            });
             if (error)
                 throw new Error(`could not stop run ${run_id}: ${error.message}`);
             const stopped = data;
@@ -1382,10 +1953,11 @@ async function receipt({ client, runId, cardId }, kind, refId, label) {
     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
+ *  the same reason `cs 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);
+export function toolNamesForLevel(level, isOwner = false) {
+    return TOOLS.filter((t) => t.levels.includes(level) && !(isOwner && t.name === 'escalate'))
+        .map((t) => t.name);
 }
 /**
  * One tool's handler, by name. Exported for the same reason `toolNamesForLevel`
@@ -1396,10 +1968,21 @@ export function toolNamesForLevel(level) {
  * standing up the MCP transport `buildServer` wraps it in.
  */
 export function toolHandler(name) {
+    return toolNamed(name).handler;
+}
+/** One tool's registered input schema and description, by name. Exported for
+ *  what a handler test cannot see: whether a bound lives in Zod, where it would
+ *  reject before `buildServer`'s try/catch and reach every level sharing the
+ *  schema, or in the handler, where it comes back as a correctable failure. */
+export function toolShape(name) {
+    const { description, input } = toolNamed(name);
+    return { description, input };
+}
+function toolNamed(name) {
     const tool = TOOLS.find((t) => t.name === name);
     if (!tool)
         throw new Error(`no tool named ${name}`);
-    return tool.handler;
+    return tool;
 }
 // ---------------------------------------------------------------------------
 /**
@@ -1416,7 +1999,7 @@ function buildServer(caller) {
             + 'hold rather than one that is missing.',
     });
     for (const tool of TOOLS) {
-        if (!tool.levels.includes(caller.level))
+        if (!tool.levels.includes(caller.level) || (caller.isOwner && tool.name === 'escalate'))
             continue;
         server.registerTool(tool.name, { description: tool.description, inputSchema: tool.input }, (async (args) => {
             try {
@@ -1426,7 +2009,7 @@ function buildServer(caller) {
                    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);
+                const safe = redactArgs(secretScope(caller), args);
                 return { content: [{ type: 'text', text: await tool.handler(caller, safe) }] };
             }
             catch (error) {
@@ -1447,6 +2030,18 @@ function buildServer(caller) {
     }
     return server;
 }
+export const toolsUrl = (port, runId, processToken) => `http://127.0.0.1:${port}/mcp/${runId}${processToken ? `/${processToken}` : ''}`;
+/** The per-request fence used by already-open MCP sessions. */
+export async function processActivationIsCurrent(client, runId, processToken) {
+    const current = await rows(client.from('panel3_runs')
+        .select('process_token, card:panel3_cards!panel3_runs_card_id_fkey!inner(conversation_run_id)')
+        .eq('id', runId)
+        .eq('process_token', processToken)
+        .in('state', ['running', 'asked'])
+        .is('ended_at', null)
+        .eq('card.conversation_run_id', runId), 'verify', `the current process activation for run ${runId}`);
+    return current.length > 0;
+}
 /**
  * Start the v3 tools server on loopback, for the signed-in user this client
  * carries.
@@ -1477,6 +2072,7 @@ export async function startToolsServer(client, dispatch) {
     /** 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();
+    const sessionTokens = new Map();
     /** Known once the socket is bound, which is before any request can arrive. */
     let port = 0;
     const fail = (res, status, why) => {
@@ -1484,7 +2080,11 @@ export async function startToolsServer(client, dispatch) {
     };
     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;
+        const parts = url.pathname.startsWith('/mcp/')
+            ? url.pathname.slice('/mcp/'.length).split('/').filter(Boolean)
+            : [];
+        const runId = parts[0] ?? null;
+        const processToken = parts[1];
         if (!runId) {
             fail(res, 404, 'Not found. The v3 tools server serves /mcp/<run-id> and nothing else.');
             return;
@@ -1501,6 +2101,17 @@ export async function startToolsServer(client, dispatch) {
                 fail(res, 400, 'Bad Request: this session belongs to a different run.');
                 return;
             }
+            const expected = sessionTokens.get(sessionId);
+            if (expected !== processToken) {
+                fail(res, 400, 'Bad Request: this session belongs to a different process activation.');
+                return;
+            }
+            if (expected !== undefined) {
+                if (!(await processActivationIsCurrent(client, runId, expected))) {
+                    fail(res, 403, `Run ${runId} belongs to a newer process activation.`);
+                    return;
+                }
+            }
             await existing.handleRequest(req, res);
             return;
         }
@@ -1517,7 +2128,9 @@ export async function startToolsServer(client, dispatch) {
            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 runs = await rows(client.from('panel3_runs')
+            .select('id, card_id, level, state, ended_at, process_token, card:panel3_cards!panel3_runs_card_id_fkey(conversation_run_id)')
+            .eq('id', runId), 'read', `run ${runId}`);
         const run = runs[0];
         if (!run) {
             fail(res, 404, `Not found: there is no run ${runId}.`);
@@ -1535,11 +2148,21 @@ export async function startToolsServer(client, dispatch) {
         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 isOwner = run.card?.conversation_run_id === run.id;
+        if (isOwner && (!processToken || processToken !== run.process_token)) {
+            fail(res, 403, `Run ${runId} belongs to a different process activation.`);
+            return;
+        }
+        if (!isOwner && processToken !== undefined) {
+            fail(res, 403, `Run ${runId} has no process activation token.`);
+            return;
+        }
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: () => crypto.randomUUID(),
             onsessioninitialized: (sid) => {
                 transports.set(sid, transport);
                 sessionRuns.set(sid, runId);
+                sessionTokens.set(sid, processToken);
             },
             // 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
@@ -1552,10 +2175,12 @@ export async function startToolsServer(client, dispatch) {
             if (sid) {
                 transports.delete(sid);
                 sessionRuns.delete(sid);
+                sessionTokens.delete(sid);
             }
         };
         const server = buildServer({
-            client, userId, runId, cardId: run.card_id, level: run.level, dispatch,
+            client, userId, runId, cardId: run.card_id, level: run.level,
+            processToken, isOwner, dispatch,
         });
         await server.connect(transport);
         await transport.handleRequest(req, res, body);
@@ -1581,11 +2206,12 @@ export async function startToolsServer(client, dispatch) {
     });
     port = http.address().port;
     return {
-        urlFor: (runId) => `http://127.0.0.1:${port}/mcp/${runId}`,
+        urlFor: (runId, processToken) => toolsUrl(port, runId, processToken),
         async close() {
             await Promise.all([...transports.values()].map((t) => t.close().catch(() => { })));
             transports.clear();
             sessionRuns.clear();
+            sessionTokens.clear();
             await new Promise((resolve, reject) => {
                 http.close((err) => (err ? reject(err) : resolve()));
             });