@ctrl-spc/cs 0.7.0 → 0.7.1

package/dist/panel3/tools.js

@@ -121,6 +121,7 @@ import { returned } from './client.js';
 import { rememberSecret, redactArgs } from './secrets.js';
 import { workBrief } from './prompt.js';
 import { listCodebases } from '../codebases.js';
+import { readWorkflow } from '../workflows.js';
 import { ASK_CONTENT_COLUMNS, attachmentLine, loadAttachments, withAskContent, } from './show.js';
 // ---------------------------------------------------------------------------
 // READING AND WRITING. Every query goes through the same guard every other v3
@@ -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
@@ -651,6 +709,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 +819,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 +855,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 +890,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
@@ -1053,15 +1198,81 @@ const TOOLS = [
             return `Updated artifact ${artifact.title ?? artifact.id}.`;
         },
     },
+    // ── 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 +1281,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 +1297,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 +1351,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 +1367,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 +1399,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 +1416,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 +1429,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 +1442,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 +1486,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 +1495,21 @@ 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 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.');
+                }
+                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 +1525,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 +1539,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 +1560,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;
@@ -1384,8 +1634,9 @@ async function receipt({ client, runId, cardId }, kind, refId, label) {
 /** 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);
+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 +1647,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 +1678,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 +1688,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 +1709,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 +1751,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 +1759,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 +1780,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 +1807,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 +1827,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 +1854,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 +1885,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()));
             });