@ctrl-spc/cs 0.7.3 → 0.7.5

package/dist/panel3/tools.js

@@ -118,10 +118,32 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { returned } from './client.js';
+import { readableWriteError, FIREWALL_WRITING_RULE } from '../firewall.js';
 import { rememberSecret, redactArgs } from './secrets.js';
 import { workBrief } from './prompt.js';
+/* The harness this daemon spawns with, which is the process this server runs
+   in. It is what `panel3_runs.harness` is written from at spawn, so reading it
+   here is the same fact without a second round trip. */
+import { harness } from './spawn.js';
 import { listCodebases } from '../codebases.js';
-import { readWorkflow } from '../workflows.js';
+import { buildWorkflow, duplicateWorkflow, editWorkflow, readWorkflow, rewordStage } from '../workflows.js';
+/* ═══ 38-panel3-steps: THE FIFTH NEUTRAL MODULE, AND A DECISION LIKE THE OTHERS.
+   ═══ Stages and steps are the work item's own record, shared by both
+   generations and read by the web's Steps section. `steps.ts` owns the rows so
+   nothing here names a `cliv2_` table; conventions.md's enumeration and
+   `panel3-isolation.contract.test.mjs` were amended with it. */
+import { STEP_STATUSES, createStep, listSteps, stageById, startWorkflowOnItem, stepById, updateStep, } from '../steps.js';
+/* ═══ A THIRD GENERATION-NEUTRAL MODULE, AND IT IS A DECISION. ═══
+   conventions.md enumerates what `panel3/` may reach outside itself and says
+   "and nothing else", so this line amends that enumeration rather than slipping
+   past it, and `panel3-isolation.contract.test.mjs` fails until the list agrees.
+   `screenshots.ts` names no `cliv2_` table and no v1 or v2 concept: it is a PNG
+   parser and a byte bound. The alternative was copying 215 lines of chunk
+   walking into `panel3/` to avoid one entry in a list, which is the duplication
+   the guide forbids, and it would have left two answers to "is this a PNG". */
+import { readPngScreenshot, screenshotArtifactId, MAX_SCREENSHOT_BYTES } from '../screenshots.js';
+import { lstat } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
 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
@@ -218,6 +240,24 @@ const secretScope = ({ runId, processToken }) => processToken === undefined ? ru
  * child text is ever inherited by what the person reads.
  */
 const PERSON_READS_LIMIT = 700;
+/**
+ * ═══ HOW MANY WORDS MAY NAME THE WORK ON A CARD, AND WHY IT IS SIX. ═══
+ *
+ * The name is read on one line three inches wide, and the branch for the work
+ * is cut from the same words, so both want a name rather than a sentence. Six
+ * is room for one: "Fix the sign-out checklist bug" is five.
+ *
+ * ═══ AND IT REFUSES RATHER THAN CUTTING THE NAME DOWN. ═══ `say.ts` already
+ * owns the one rule for turning a long line into a title. A second cut here
+ * would be a second answer to that question inside one package, and it would be
+ * the answer nobody saw being given: half a name is written, the card carries
+ * it, and the branch is cut from it. Refusing puts it back to the one caller
+ * that can still say it shorter, and it comes back through `buildServer`'s
+ * catch as a correctable failure rather than a protocol error, which is the
+ * same reason `PERSON_READS_LIMIT` above is checked in a handler and not on the
+ * schema.
+ */
+const WORK_NAME_WORDS = 6;
 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;
@@ -434,6 +474,14 @@ function elapsed(startedAt, endedAt, resumedAt) {
  *  enforces it. Both copies are reading the same authority: the bucket the
  *  migration created (20260722180000_skills.sql). */
 const SKILL_BUNDLES_BUCKET = 'skill-bundles';
+/** Owner-scoped and private, the one `20260924090000_panel3_images.sql` created.
+ *  Never the org-scoped `artifacts` bucket: a `panel3_images` row is readable by
+ *  its owner alone, and a row that private pointing at a PNG the whole org can
+ *  read would make the privacy a claim rather than a fact. */
+/* Exported because the daemon downloads a card's pictures into the run's cwd
+   before it builds the prompt (33 Slice 6), and a second literal is a second
+   place for the bucket to be renamed wrong. */
+export const PANEL3_IMAGES_BUCKET = 'panel3-images';
 /**
  * ═══ A REMOVED SKILL IS NOT A MISSING ONE, AND AN AGENT TOLD OTHERWISE SAYS
  *     THE WRONG THING TO THE PERSON. ═══
@@ -524,6 +572,47 @@ async function skillDocument(client, storagePath, what) {
     }
     return await data.text();
 }
+/**
+ * ═══ WHY A FILE COULD NOT BE SHOWN, SAID WITHOUT NAMING IT. ═══
+ *
+ * `attach_image` is handed an absolute local path, and every failure below it
+ * carries that path in its message: `readPngScreenshot` interpolates it four
+ * times, and an `ENOENT` from Node restates it again in its own wording. A
+ * tool's thrown message is what the AGENT reads, and an agent that has just
+ * failed quotes its own error into a `say`, which lands in `panel3_turns.body` —
+ * a cloud column a browser renders. AGENTS.md's rule is that no absolute path
+ * reaches the cloud, so the leak has to be closed here, two hops before it.
+ *
+ * NOT BY EDITING THE MESSAGE FROM BELOW. Stripping the path out of a string that
+ * already contains it is a guess about wording that holds until some layer
+ * phrases it differently — and the layer most likely to is the operating system,
+ * which owes this codebase nothing. So the reason is re-derived here and the text
+ * from below is discarded entirely.
+ *
+ * The agent still gets an actionable sentence, which is the whole point of
+ * telling it anything: the four cases it can do something about are separated,
+ * and everything else says the one true thing left.
+ */
+async function whyNotAPicture(localPath) {
+    if (!isAbsolute(localPath)) {
+        return 'that is not an absolute path, and this needs one.';
+    }
+    let stat;
+    try {
+        stat = await lstat(localPath);
+    }
+    catch {
+        return 'there is no file at that path on this machine.';
+    }
+    if (!stat.isFile())
+        return 'that path is a folder or a link, not a file.';
+    if (stat.size === 0)
+        return 'that file is empty.';
+    if (stat.size > MAX_SCREENSHOT_BYTES) {
+        return `that file is larger than the ${MAX_SCREENSHOT_BYTES / (1024 * 1024)} MB limit.`;
+    }
+    return 'that file could not be read as a PNG. It must be a real, uncompressed-format PNG.';
+}
 /**
  * ═══ THE PATH A SKILL NAMED IS NOT TRUSTED. ═══
  *
@@ -585,6 +674,37 @@ const CREDENTIAL_INSTRUCTION = 'This is a SECRET, and it is yours to USE. Make t
     + 'itself into your report, your answer, a progress line, a question, a comment, an artifact or a '
     + 'file you commit, because all of those are shared and permanent. Name the credential you used '
     + 'instead. Never refuse the work to avoid touching the value.';
+/**
+ * The exit rules whose refusal carries a NUMBER, checked in the 1-based
+ * numbering the agent sent and returned in the 0-based one the RPC takes.
+ *
+ * SHARED BY `create_workflow` AND `edit_workflow`, because they are the same
+ * rules over the same list: `cliv2_build_workflow` and `cliv2_edit_workflow`
+ * both count stages from 0, a numbering neither tool ever showed the agent, so
+ * both refuse here in the numbering the agent used.
+ */
+function zeroBasedExits(exits, stageCount) {
+    for (const exit of exits) {
+        const where = `exit from stage ${exit.from_stage} to stage ${exit.to_stage}`;
+        const inRange = (n) => n >= 1 && n <= stageCount;
+        if (!inRange(exit.from_stage) || !inRange(exit.to_stage)) {
+            throw new Error(`${where} names a stage this workflow does not have (stages are 1..${stageCount}). `
+                + 'Nothing was written.');
+        }
+        if (exit.to_stage > exit.from_stage) {
+            throw new Error(`${where} jumps forward. to_stage must be earlier than from_stage, or the same stage. `
+                + 'Nothing was written.');
+        }
+        if (exit.condition.trim() === '') {
+            throw new Error(`the exit from stage ${exit.from_stage} needs a condition. Nothing was written.`);
+        }
+    }
+    return exits.map((exit) => ({
+        from: exit.from_stage - 1,
+        to: exit.to_stage - 1,
+        condition: exit.condition.trim(),
+    }));
+}
 // ---------------------------------------------------------------------------
 // THE TOOLS.
 //
@@ -592,6 +712,32 @@ const CREDENTIAL_INSTRUCTION = 'This is a SECRET, and it is yours to USE. Make t
 // read against the table it came from without hunting. `levels` on each entry is
 // the whole of the per-level rule; there is no second place where a level is
 // granted or taken away.
+/** 38-panel3-steps: the work item must be one this card carries. The person's
+ *  attachments are the authority on what a run may write to, exactly as
+ *  `attach_image_artifact` reads them before keeping a picture. */
+async function carriedWorkItem(caller, workItemId, consequence, attached) {
+    attached ??= await loadAttachments(caller.client, caller.cardId);
+    if (!attached.some((item) => item.kind === 'work_item' && item.ref_id === workItemId)) {
+        throw new Error(`NOTHING WAS WRITTEN: this card does not carry work item ${workItemId}, so ${consequence}. `
+            + 'get_my_brief_and_report and what was attached name the work item you are on.');
+    }
+}
+/** The stage a step write may land in: a real row, anchored to a work item this
+ *  card carries. A stage anchored to a panel request has no Steps section to
+ *  show it, so it is refused by name and the agent is pointed at the card. */
+async function stageForWriting(caller, stageId, consequence) {
+    const stage = await stageById(caller.client, stageId);
+    if (!stage) {
+        throw new Error(`NOTHING WAS WRITTEN: there is no stage ${stageId}, or it is not yours. list_steps names them.`);
+    }
+    if (!stage.workItemId) {
+        throw new Error(`NOTHING WAS WRITTEN: stage ${stageId} belongs to a panel request rather than a work item, and `
+            + 'steps are a WORK ITEM\'s record. What you are doing already goes on the card: call '
+            + 'report_activity. If this work deserves a work item of its own, ask for one.');
+    }
+    await carriedWorkItem(caller, stage.workItemId, consequence);
+    return stage;
+}
 const TOOLS = [
     // ── Read the record ──────────────────────────────────────────────────────
     {
@@ -837,6 +983,441 @@ const TOOLS = [
             ].join('\n');
         },
     },
+    {
+        name: 'create_workflow',
+        /* ═══ LEVEL 2 ALONE, FOR THE REASON `get_workflow` IS. ═══ The owner is the
+           agent talking to the person, so it is the one that hears a process
+           described and can write it down as it was described. A launcher writes one
+           line and exits; a worker owns one piece of somebody else's process. */
+        levels: [2],
+        description: "Write a new workflow into this organisation's library: a name, what it is about, and its "
+            + 'stages in order, each with a one-line description and the markdown document an agent '
+            + 'following it reads. Stages are numbered from 1, the way get_workflow prints them. exits '
+            + 'are the conditional ways back: from_stage N, if condition, go back to to_stage M, where M '
+            + 'is earlier than N or the same stage; a forward jump is refused and nothing is written. '
+            + 'Takes no organisation or project: the workflow goes into the organisation this '
+            + "conversation's project belongs to. It appears on /workflows at once. Never put an "
+            + 'absolute local path in any field.',
+        input: {
+            name: z.string(),
+            description: z.string().optional(),
+            stages: z.array(z.object({
+                name: z.string(),
+                description: z.string().optional(),
+                body: z.string().describe('the whole stage document, in markdown'),
+            })),
+            exits: z.array(z.object({
+                from_stage: z.number().int(),
+                to_stage: z.number().int(),
+                condition: z.string(),
+            })).optional(),
+        },
+        handler: async (caller, args) => {
+            const { name, description, stages, exits } = args;
+            /* ═══ CHECKED HERE IN THE NUMBERING THE AGENT SENT. ═══
+               `cliv2_build_workflow` enforces every one of these itself, and its
+               messages count stages from 0, a numbering this tool never showed the
+               agent, which would have it correcting the wrong stage. So the rules
+               whose refusal carries a NUMBER are pre-checked and worded in 1-based
+               terms; everything else (the grant, "at least one stage", anything
+               unforeseen) is left to the RPC and passed back as it came. */
+            const workflowName = name.trim();
+            if (workflowName === '')
+                throw new Error('a workflow needs a name. Nothing was written.');
+            /* THE RPC REFUSES THIS TOO, and its message carries no number, so it
+               would ordinarily be left to it. It is checked here because the exit
+               range below would otherwise read "stages are 1..0", which is not a
+               range and is not the thing that is actually wrong. */
+            if (stages.length === 0) {
+                throw new Error('a workflow needs at least one stage. Nothing was written.');
+            }
+            stages.forEach((stage, i) => {
+                if (stage.name.trim() === '')
+                    throw new Error(`stage ${i + 1} needs a name. Nothing was written.`);
+            });
+            const wanted = zeroBasedExits(exits ?? [], stages.length);
+            /* ═══ THE ORGANISATION IS THE CONVERSATION'S, NOT THE AGENT'S. ═══ There
+               is no org argument to get wrong, and a record-only card genuinely has
+               none, which is said rather than guessed at. */
+            const projectId = await projectOfCard(caller);
+            if (projectId === null) {
+                throw new Error('this conversation has no project, so there is no organisation to write the workflow into.');
+            }
+            const project = await only(caller.client.from('projects').select('id, org_id').eq('id', projectId).is('archived_at', null), 'read', `the project this conversation is in (${projectId})`);
+            const id = await buildWorkflow(caller.client, {
+                orgId: project.org_id,
+                name: workflowName,
+                description: description?.trim() ?? '',
+                stages: stages.map((stage) => ({
+                    name: stage.name.trim(),
+                    description: stage.description?.trim() ?? '',
+                    /* THE BODY IS NOT TRIMMED. It is a markdown document, and its leading
+                       blank lines are the author's own. */
+                    body: stage.body,
+                })),
+                exits: wanted,
+                fromAgent: harness(),
+            });
+            await receipt(caller, 'workflow', id, workflowName);
+            return `Created workflow ${workflowName}, id ${id}, with ${stages.length} stages. `
+                + 'It is now in the library.';
+        },
+    },
+    {
+        name: 'reword_stage',
+        /* ═══ LEVEL 2 ALONE, FOR `create_workflow`'s REASON. ═══ The owner is the
+           agent hearing the person say how a stage should read. */
+        levels: [2],
+        description: 'Reword one stage of the workflow attached to this conversation: its name, its one-line '
+            + 'description, or its whole markdown document. Name the stage by the number get_workflow '
+            + 'prints. Send only the fields to change; a field left out is left as it is. A stage is one '
+            + 'shared library row, so if other workflows hold it they change too, and the reply names them. '
+            + 'Never put an absolute local path in any field.',
+        input: {
+            workflow_id: z.string(),
+            stage: z.number().int().describe('the stage number, counted from 1 as get_workflow prints it'),
+            name: z.string().optional(),
+            description: z.string().optional(),
+            body: z.string().optional().describe('the whole stage document, in markdown; replaces the current one'),
+        },
+        handler: async (caller, args) => {
+            const { workflow_id, stage, name, description, body } = args;
+            if (name === undefined && description === undefined && body === undefined) {
+                throw new Error('send at least one of name, description or body. Nothing was written.');
+            }
+            const stageName = name?.trim();
+            if (stageName === '')
+                throw new Error('a stage needs a name. Nothing was written.');
+            const workflow = await readWorkflow(caller.client, workflow_id);
+            if (workflow.archivedAt !== null) {
+                throw new Error(`workflow ${workflow.name} is archived. Nothing was written.`);
+            }
+            /* ═══ THE NUMBER THE AGENT SAW, RESOLVED THROUGH THE READ THAT PRINTED IT.
+               ═══ No v3 tool at any level takes a stage uuid, so the numbering is
+               `get_workflow`'s presentation and the mapping stays here. `stage: 0`
+               indexes -1, is undefined, and is refused with the range. */
+            const target = workflow.stages[stage - 1];
+            if (!target) {
+                throw new Error(`stage ${stage} is not a stage of ${workflow.name} (stages are 1..${workflow.stages.length}). `
+                    + 'Nothing was written.');
+            }
+            const { alsoIn } = await rewordStage(caller.client, {
+                workflowId: workflow.id,
+                stageId: target.id,
+                name: stageName,
+                /* A WHITESPACE-ONLY DESCRIPTION CLEARS IT. An empty description is a
+                   real state (the column defaults to one); an empty name is not. */
+                description: description?.trim(),
+                /* THE BODY IS NOT TRIMMED, for `create_workflow`'s reason. */
+                body,
+            });
+            /* THE WORKFLOW IS WHAT THE PERSON OPENS, because no v3 surface shows a
+               stage on its own. */
+            await receiptOnce(caller, 'workflow', workflow.id, workflow.name);
+            const changed = [
+                name !== undefined && 'name',
+                description !== undefined && 'description',
+                body !== undefined && 'body',
+            ].filter(Boolean).join(', ');
+            return [
+                `Reworded stage ${stage} ${stageName ?? target.name} of ${workflow.name} (${changed}).`,
+                alsoIn.length === 0
+                    ? 'It is in no other live workflow.'
+                    : `That stage is shared, so these workflows changed too: ${alsoIn.join(', ')}.`,
+                /* ═══ A RENAME DOES NOT REACH A PLAN ALREADY RUNNING. ═══
+                   `cliv2_start_workflow` copies the stage NAME onto the work item's plan
+                   and keeps only a reference for the document, so a body change flows to
+                   a run in flight and a name change does not. Said when the name
+                   actually changed; naming the runs is not done, because the read that
+                   exists, `cliv2_workflow_runs`, names every run of a workflow rather
+                   than the runs carrying this stage. */
+                ...(stageName === undefined || stageName === target.name ? [] : [
+                    'Work items already running a workflow that holds it keep the old stage name on their plan.',
+                ]),
+            ].join(' ');
+        },
+    },
+    {
+        name: 'edit_workflow',
+        /* ═══ LEVEL 2 ALONE, FOR `create_workflow`'s REASON. ═══ The owner is the
+           agent hearing the person say the process has changed shape. */
+        levels: [2],
+        description: 'Change the shape of the workflow attached to this conversation: its name, what it is about, '
+            + 'which stages it has and in what order, and the conditional ways back. stages is the WHOLE '
+            + 'new list, in order: a stage left out is removed from the workflow (it stays in the library). '
+            + 'Each entry is either { keep: N } to keep stage N as get_workflow prints it, or { name, '
+            + 'description, body } to write a new stage. exits is the WHOLE new list of conditional ways '
+            + 'back too, and may be empty: from_stage and to_stage count from 1 in the NEW list, to_stage '
+            + 'must be earlier than from_stage or the same, and exits off one stage are tried in the order '
+            + 'sent. name and description left out are left as they are; an empty description clears it. '
+            + 'To change the wording of an '
+            + 'existing stage use reword_stage. Refused, with nothing written, while any work item is '
+            + 'running the workflow. Never put an absolute local path in any field.',
+        input: {
+            workflow_id: z.string(),
+            name: z.string().optional(),
+            description: z.string().optional(),
+            stages: z.array(z.union([
+                z.object({ keep: z.number().int().describe('the stage number as get_workflow prints it') }).strict(),
+                z.object({
+                    name: z.string(),
+                    description: z.string().optional(),
+                    body: z.string().describe('the whole stage document, in markdown'),
+                }).strict(),
+            ])),
+            exits: z.array(z.object({
+                from_stage: z.number().int(),
+                to_stage: z.number().int(),
+                condition: z.string(),
+            })).optional().describe('the whole new list of conditional ways back; send [] for none'),
+        },
+        handler: async (caller, args) => {
+            const { workflow_id, name, description, stages, exits } = args;
+            const workflowName = name?.trim();
+            if (workflowName === '')
+                throw new Error('a workflow needs a name. Nothing was written.');
+            if (stages.length === 0) {
+                throw new Error('a workflow needs at least one stage, and stages is its WHOLE new list. Nothing was written.');
+            }
+            /* ═══ AN ABSENT `exits` IS REFUSED IN WORDS, NEVER DEFAULTED TO `[]`. ═══
+               The RPC REPLACES the exits from what it is sent, so treating "left out"
+               as "none" would silently straighten a loop a person drew, on a call the
+               agent made to add one stage. */
+            if (exits === undefined) {
+                throw new Error('exits is the whole new list of conditional ways back and may be empty; send [] for none. '
+                    + 'Nothing was written.');
+            }
+            const workflow = await readWorkflow(caller.client, workflow_id);
+            if (workflow.archivedAt !== null) {
+                throw new Error(`workflow ${workflow.name} is archived. Nothing was written.`);
+            }
+            /* ═══ THE NUMBER THE AGENT SAW, RESOLVED THROUGH THE READ THAT PRINTED IT,
+               ═══ as `reword_stage` does it: no v3 tool at any level takes a stage
+               uuid, so `{ keep: N }` is `get_workflow`'s numbering and the mapping
+               stays here. */
+            const kept = new Set();
+            const entries = stages.map((stage, i) => {
+                if ('keep' in stage) {
+                    const target = workflow.stages[stage.keep - 1];
+                    if (!target) {
+                        throw new Error(`keep ${stage.keep} names a stage ${workflow.name} does not have (stages are `
+                            + `1..${workflow.stages.length}). Nothing was written.`);
+                    }
+                    if (kept.has(stage.keep)) {
+                        throw new Error(`stage ${stage.keep} is listed twice. A stage may appear once. Nothing was written.`);
+                    }
+                    kept.add(stage.keep);
+                    return { stage_id: target.id };
+                }
+                if (stage.name.trim() === '') {
+                    throw new Error(`the new stage at position ${i + 1} needs a name. Nothing was written.`);
+                }
+                /* THE BODY IS NOT TRIMMED, for `create_workflow`'s reason. */
+                return { name: stage.name.trim(), description: stage.description?.trim() ?? '', body: stage.body };
+            });
+            const count = await editWorkflow(caller.client, {
+                workflowId: workflow.id,
+                name: workflowName ?? null,
+                /* A WHITESPACE-ONLY DESCRIPTION CLEARS IT, as `reword_stage`'s does;
+                   left out, it is left as it is, which is what null means to the RPC. */
+                description: description?.trim() ?? null,
+                stages: entries,
+                exits: zeroBasedExits(exits, entries.length),
+                /* THE BRANCHES GO BACK AS THEY CAME. The RPC rewrites them from what it
+                   is sent and nothing in v3 sets one, so sending anything else would
+                   delete what a person set on `/workflows`. */
+                branches: workflow.branches,
+                fromAgent: harness(),
+            });
+            /* THE LABEL IS THE NAME THAT SURVIVED THE EDIT, which is the reply's own:
+               `name` is optional and is undefined whenever only the stages changed,
+               so the raw argument would put an empty label on the card. */
+            await receiptOnce(caller, 'workflow', workflow.id, workflowName ?? workflow.name);
+            /* THE COUNT IN THE REPLY IS THE LIST'S, NOT THE RPC'S. They agree when
+               the RPC did its job, and the RPC's is checked for being a number
+               above; the sentence claims what was sent, so it counts what was sent. */
+            return `Edited workflow ${workflowName ?? workflow.name}: it now has exactly the ${entries.length} stages you sent, `
+                + `in that order, and ${exits.length === 0 ? 'no exits back to an earlier stage' : 'exactly the exits back you sent'}. `
+                + `The database counts ${count}.`;
+        },
+    },
+    {
+        name: 'duplicate_workflow',
+        /* ═══ LEVEL 2 ALONE, FOR `create_workflow`'s REASON. ═══ It is the way past
+           the refusal `edit_workflow` gives, so it belongs to the level that was
+           refused. */
+        levels: [2],
+        description: 'Copy a workflow into a new one with no runs: the same stages in the same order, the same '
+            + 'exits, branch conditions and ending, under a new name (the original name plus " (copy)" '
+            + 'unless you give one). This is the way past a workflow edit_workflow refused because a work '
+            + 'item is running it: the original keeps its runs, the copy takes your change. Never put an '
+            + 'absolute local path in the name.',
+        input: {
+            workflow_id: z.string(),
+            name: z.string().optional().describe('the name for the copy; leave out for the original name plus " (copy)"'),
+        },
+        handler: async (caller, args) => {
+            const { workflow_id, name } = args;
+            const copyName = name?.trim();
+            if (copyName === '') {
+                throw new Error('a workflow needs a name; leave name out to take the original name plus " (copy)". '
+                    + 'Nothing was written.');
+            }
+            /* ═══ NOTHING IS READ FIRST. ═══ The RPC refuses an archived source, one
+               that is not the person's and a stageless one in its own words, which are
+               the words v2 agents already see; a pre-check here would be a second
+               owner of those rules saying them differently. `create_workflow`'s
+               pre-checks exist only because the RPC's numbers are 0-based, and nothing
+               here carries a number. */
+            const id = await duplicateWorkflow(caller.client, {
+                workflowId: workflow_id,
+                name: copyName ?? null,
+                fromAgent: harness(),
+            });
+            /* ═══ READ BACK, NOT GUESSED. ═══ The RPC chose the name (the default is
+               its rule, not this tool's) and copied the links, so the receipt label
+               and the reply say what is stored. */
+            const copy = await readWorkflow(caller.client, id);
+            await receipt(caller, 'workflow', copy.id, copy.name);
+            return `Copied the workflow as ${copy.name}, id ${copy.id}, with ${copy.stages.length} stages`
+                + `${copy.ending === 'next-in-backlog' ? ', restarting on the next backlog item' : ''}. `
+                + 'It has no runs, so edit_workflow can change its shape. It links the same stage documents '
+                + 'as the original, so reword_stage on either rewords both.';
+        },
+    },
+    // ── Steps: the work item's own record of a workflow run ──────────────────
+    /* ═══ 38-panel3-steps: A PANEL RUN THAT FOLLOWS A WORKFLOW WRITES THE WORK
+       ITEM'S STEPS. ═══ The Steps section, its tables, its live refresh and the
+       board card's progress chip all existed; what did not exist was a writer on
+       this side. v2's own step tools refuse anything but a v2 session and gate on
+       v2's scope contract, which a panel run never has, so these four are served
+       here over the neutral module.
+  
+       THE GATE IS THE CARD'S ATTACHMENTS, exactly as `attach_image_artifact`
+       gates a picture: the person pointed this conversation at a work item, and
+       that row is the authority on what a run may write to. A stage anchored to
+       a panel request rather than a work item is refused outright, because the
+       Steps section that would show it lives on a work item (decision 1 on the
+       work item's spec). Provenance is copied from the stage by the module, never
+       chosen here.
+  
+       WHO HOLDS WHAT. `start_workflow` is the owner's, like `get_workflow`: only
+       level 2 sees the attachment list and reads the process. The three that
+       write and read steps are levels 2 and 3, because a worker owns one stage
+       and the owner may work a record-only stage itself. Level 1 launches and
+       exits and holds none of them. */
+    {
+        name: 'start_workflow',
+        levels: [2],
+        description: 'Put the attached workflow\'s stages on the attached work item, once, before you send anybody '
+            + 'for the first stage. The person watches progress on the work item, so a workflow that is '
+            + 'not started there is a workflow they cannot see. Call it again and nothing is written twice.',
+        input: {
+            workflow_id: z.string().uuid().describe('The id printed beside the workflow in what was attached.'),
+            work_item_id: z.string().uuid().describe('The id printed beside the work item in what was attached.'),
+        },
+        handler: async (caller, args) => {
+            const { workflow_id, work_item_id } = args;
+            const attached = await loadAttachments(caller.client, caller.cardId);
+            if (!attached.some((item) => item.kind === 'workflow' && item.ref_id === workflow_id)) {
+                throw new Error(`NOTHING WAS WRITTEN: this card does not carry workflow ${workflow_id}. Use the id printed `
+                    + 'beside the workflow in what was attached.');
+            }
+            await carriedWorkItem(caller, work_item_id, 'a workflow cannot be started on it', attached);
+            const workflow = await readWorkflow(caller.client, workflow_id);
+            const result = await startWorkflowOnItem(caller.client, work_item_id, workflow_id);
+            return result.started
+                ? `The ${result.stages} stages of ${workflow.name} are on work item ${work_item_id}. Work them in `
+                    + 'order: send somebody for stage 1, and nobody for stage 2 until list_steps shows stage 1\'s '
+                    + 'steps are all done.'
+                : `${workflow.name} is already on work item ${work_item_id} (${result.stages} stages); nothing was `
+                    + 'written twice. Call list_steps to see where it is.';
+        },
+    },
+    {
+        name: 'list_steps',
+        levels: [2, 3],
+        description: 'The stages on a work item, the steps recorded inside each, and UP NEXT: the one thing that '
+            + 'should happen next, computed by the product and read by the person too. "decompose" means '
+            + 'the named stage has no steps yet and writing them is the next action; "step" names the one '
+            + 'to work; "none" means nothing is waiting. Read it before you record or send anything.',
+        input: {
+            work_item_id: z.string().uuid().describe('The work item, from what was attached or your brief.'),
+        },
+        handler: async (caller, args) => {
+            const { work_item_id } = args;
+            await carriedWorkItem(caller, work_item_id, 'its steps cannot be read from here');
+            const spine = await listSteps(caller.client, work_item_id);
+            if (spine.stages.length === 0) {
+                return `Work item ${work_item_id} has no stages. Nothing has been started on it.`;
+            }
+            return [
+                `STAGES  ${spine.stages.length} on work item ${work_item_id}`,
+                ...spine.stages.flatMap((stage, i) => {
+                    const done = stage.steps.filter((step) => step.status === 'done').length;
+                    const summary = stage.steps.length === 0 ? 'no steps yet' : `${done} of ${stage.steps.length} done`;
+                    return [
+                        '',
+                        `${i + 1}. ${stage.title}   id ${stage.id}   ${stage.sourceKind} · ${stage.sourceLabel}   ${summary}`,
+                        ...stage.steps.map((step, j) => `   ${i + 1}.${j + 1} ${step.title}   [${step.status}]   id ${step.id}\n`
+                            + `       next: ${step.nextAction}`),
+                    ];
+                }),
+                '',
+                'UP NEXT',
+                JSON.stringify(spine.upNext, null, 2),
+            ].join('\n');
+        },
+    },
+    {
+        name: 'create_step',
+        levels: [2, 3],
+        description: 'Record one step inside a stage of the work item, before you do it. A step is a resumable unit '
+            + 'of work: its charter says why it exists and what done looks like, its next action is the one '
+            + 'literal thing to do first, and its position orders it inside the stage. Record every step '
+            + 'of a stage before working the first; the person reads these as the run moves. '
+            + FIREWALL_WRITING_RULE,
+        input: {
+            stage_id: z.string().uuid().describe('The stage this step belongs to, from list_steps.'),
+            title: z.string().min(1).describe('A few words, as the person will read them in the list.'),
+            charter: z.string().min(1).describe('Why the step exists and how you would know it is done.'),
+            next_action: z.string().min(1).describe('The one literal thing to do first. Repo-relative paths only.'),
+            position: z.number().int().describe('Order inside the stage, from 1.'),
+        },
+        handler: async (caller, args) => {
+            const { stage_id, title, charter, next_action, position } = args;
+            const stage = await stageForWriting(caller, stage_id, 'a step cannot be recorded under it');
+            const { id } = await createStep(caller.client, stage, { title, charter, nextAction: next_action, position });
+            return `Recorded step ${position} "${title}" under ${stage.title}, id ${id}, status pending. Call `
+                + 'update_step with status in_progress when you pick it up.';
+        },
+    },
+    {
+        name: 'update_step',
+        levels: [2, 3],
+        description: 'Change a step you or somebody else recorded: in_progress when you pick it up, done when it is '
+            + 'finished, blocked with a next_action naming what you need when you cannot go on. Rewrite '
+            + 'next_action as it changes. Only done lets the next step start. A step\'s stage, position and '
+            + 'source cannot change; nothing is written when nothing would change. '
+            + FIREWALL_WRITING_RULE,
+        input: {
+            step_id: z.string().uuid().describe('The step, from list_steps or create_step.'),
+            title: z.string().optional(),
+            charter: z.string().optional(),
+            next_action: z.string().optional(),
+            status: z.enum(STEP_STATUSES).optional(),
+        },
+        handler: async (caller, args) => {
+            const { step_id, title, charter, next_action, status } = args;
+            const step = await stepById(caller.client, step_id);
+            if (!step) {
+                throw new Error(`NOTHING WAS WRITTEN: there is no step ${step_id}, or it is not yours. list_steps names them.`);
+            }
+            await stageForWriting(caller, step.stageId, 'its step cannot be changed');
+            const result = await updateStep(caller.client, step, { title, charter, nextAction: next_action, status });
+            return `Updated ${result.updated.join(', ')} on "${title ?? step.title}"; status is now ${status ?? step.status}.`;
+        },
+    },
     {
         name: 'get_credential',
         /* ═══ LEVELS 2 AND 3, AND THAT IS A CORRECTION TO ux.md's OWN TABLE. ═══
@@ -1316,7 +1897,8 @@ const TOOLS = [
         name: 'create_work_item',
         levels: [1],
         description: 'Create a work item on the board. Put what is to be done in the description: a name alone leaves '
-            + 'whoever picks it up guessing.',
+            + 'whoever picks it up guessing. '
+            + FIREWALL_WRITING_RULE,
         input: {
             project_id: z.string(),
             name: z.string().min(1),
@@ -1377,7 +1959,8 @@ const TOOLS = [
            work items, and an agent that cannot correct the item it just made in the
            same turn would have to make a second one beside it. */
         levels: ALL,
-        description: 'Change a work item. Pass only what changes; anything you leave out stays as it is.',
+        description: 'Change a work item. Pass only what changes; anything you leave out stays as it is. '
+            + FIREWALL_WRITING_RULE,
         input: {
             work_item_id: z.string(),
             name: z.string().min(1).optional(),
@@ -1387,7 +1970,7 @@ const TOOLS = [
             sprint_id: z.string().optional(),
             due_date: z.string().optional().describe('YYYY-MM-DD'),
         },
-        handler: async ({ client }, args) => {
+        handler: async (caller, args) => {
             const { work_item_id, ...rest } = args;
             const changes = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
             /* AN UPDATE WITH NOTHING IN IT IS REFUSED, not quietly treated as a
@@ -1396,7 +1979,8 @@ const TOOLS = [
             if (Object.keys(changes).length === 0) {
                 throw new Error('nothing to change: pass at least one field besides work_item_id');
             }
-            const item = await only(client.from('tasks').update(changes).eq('id', work_item_id).select('id, name'), 'update', `work item ${work_item_id}`);
+            const item = await only(caller.client.from('tasks').update(changes).eq('id', work_item_id).select('id, name'), 'update', `work item ${work_item_id}`);
+            await receiptOnce(caller, 'work_item', item.id, item.name);
             return `Updated ${item.name}: ${Object.keys(changes).join(', ')}.`;
         },
     },
@@ -1406,12 +1990,15 @@ const TOOLS = [
         // writes down what it learned so a later stage can read it.
         levels: ALL,
         description: 'Attach a document to a work item: a plan, a spec, an analysis. Artifacts are always on a work '
-            + 'item, so create the work item first if there is not one yet.',
+            + 'item, so create the work item first if there is not one yet. `format` defaults to md. Use '
+            + 'html for an interactive mock or wireframe, svg for a diagram, json for structured data. '
+            + FIREWALL_WRITING_RULE,
         input: {
             work_item_id: z.string(),
             title: z.string().min(1),
             content: z.string().min(1),
             type: z.enum(['plan', 'spec', 'analysis', 'diagram', 'mock', 'wireframe', 'user_story']).optional(),
+            format: z.enum(['md', 'html', 'json', 'svg']).optional(),
         },
         handler: async (caller, args) => {
             const a = args;
@@ -1420,7 +2007,7 @@ const TOOLS = [
                 title: a.title,
                 content: a.content,
                 type: a.type ?? 'plan',
-                format: 'md',
+                format: a.format ?? 'md',
                 // `not null`, no default, and the table's own policy requires it to be
                 // the caller. Stated rather than left to be defaulted somewhere else.
                 created_by: caller.userId,
@@ -1434,18 +2021,27 @@ const TOOLS = [
         // Everyone's, for the same reason `create_artifact` is: an object that can
         // be made and never corrected is an object that goes stale in the record.
         levels: ALL,
-        description: 'Replace an artifact\'s body. The whole body is replaced, so send it complete.',
-        input: { artifact_id: z.string(), content: z.string().min(1), title: z.string().min(1).optional() },
-        handler: async ({ client, userId }, args) => {
+        description: 'Replace an artifact\'s body. The whole body is replaced, so send it complete. '
+            + 'Pass `format` with the complete body to change how it renders. '
+            + FIREWALL_WRITING_RULE,
+        input: {
+            artifact_id: z.string(),
+            content: z.string().min(1),
+            title: z.string().min(1).optional(),
+            format: z.enum(['md', 'html', 'json', 'svg']).optional(),
+        },
+        handler: async (caller, args) => {
             const a = args;
-            const artifact = await only(client.from('artifacts')
+            const artifact = await only(caller.client.from('artifacts')
                 .update({
                 content: a.content,
                 ...(a.title ? { title: a.title } : {}),
+                ...(a.format ? { format: a.format } : {}),
                 updated_at: new Date().toISOString(),
-                updated_by: userId,
+                updated_by: caller.userId,
             })
                 .eq('id', a.artifact_id).select('id, title'), 'update', `artifact ${a.artifact_id}`);
+            await receiptOnce(caller, 'artifact', artifact.id, artifact.title);
             return `Updated artifact ${artifact.title ?? artifact.id}.`;
         },
     },
@@ -1471,7 +2067,8 @@ const TOOLS = [
             + '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.',
+            + 'to do — that goes in an artifact on the work item. '
+            + FIREWALL_WRITING_RULE,
         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.'),
@@ -1543,7 +2140,8 @@ const TOOLS = [
             + '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.',
+            + 'not use it for a running commentary, and do not use it to ask anything. '
+            + FIREWALL_WRITING_RULE,
         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."'),
@@ -1565,7 +2163,7 @@ const TOOLS = [
                 ...(processToken === undefined ? {} : { p_process_token: processToken }),
             });
             if (error)
-                throw new Error(`could not say that on this card: ${error.message}`);
+                throw new Error(`could not say that on this card: ${readableWriteError(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
@@ -1579,6 +2177,272 @@ const TOOLS = [
             return 'Said. They can read it now. Carry on.';
         },
     },
+    // ── Show them a picture ──────────────────────────────────────────────────
+    //
+    // ═══ LEVELS 2 AND 3, AND THEY REACH THE CARD BY DIFFERENT DOORS. ═══
+    //
+    // A level 2 owner SPEAKS: its picture goes into a turn through `panel3_say`,
+    // which refuses any run that is not the one `panel3_cards.conversation_run_id`
+    // names, so the fence is enforced in SQL rather than by this list.
+    //
+    // A level 3 worker CANNOT speak, and `panel3_say`'s own comment says why: it
+    // exists so "a dispatched worker can never reach the person through it".
+    // Widening that fence to carry a picture would change what a worker is. So a
+    // worker writes the `panel3_images` row with NO turn, and the panel reads a
+    // card's turn-less images as conversation events of their own.
+    //
+    // ═══ AN IMAGE DOES NOT NEED A TURN TO EXIST, WHICH IS WHAT MAKES THAT
+    // POSSIBLE. ═══ `panel3_images.turn_id` is nullable for exactly this case, and
+    // the two reads partition the table rather than overlapping it: the turn embed
+    // takes the rows that have a `turn_id`, the card read takes the rows that do
+    // not. Neither picture can render twice, by construction.
+    {
+        name: 'attach_image',
+        levels: [2, 3],
+        description: 'Show the person a picture on the card, with one or two sentences saying what they are '
+            + 'looking at. Use it when a picture is the answer and words are not: a screen you have just '
+            + 'changed, a diagram, a chart, something you were asked to look at. The picture must be a PNG '
+            + 'file that already exists on this machine, and you give its absolute path. It does NOT end '
+            + 'your turn: keep working after it. Do not use it for a picture they '
+            + 'already have, and do not use it in place of the reply you finish with.',
+        input: {
+            path: z.string().min(1).describe('The absolute path of a PNG file on this machine. "/Users/me/work/search-screen.png"'),
+            caption: z.string().min(1).max(PERSON_READS_LIMIT).describe('What they are looking at, in their words. "Here is the search screen with the new filter '
+                + 'row." One or two sentences: it is read on a card three inches wide.'),
+        },
+        handler: async ({ client, userId, cardId, runId, level, processToken }, args) => {
+            const { path, caption } = args;
+            /* ═══ THE PICTURE IS VALIDATED BEFORE ANYTHING IS WRITTEN, AND ITS
+               FAILURES ARE RE-THROWN PATH-FREE. ═══ `readPngScreenshot` interpolates
+               the absolute path into every one of its messages, and a tool's thrown
+               message is what the agent reads. An agent may quote its own error into a
+               `say`, which lands in `panel3_turns.body` — a cloud row a browser
+               renders. So the reason is kept and the path is not, in the shape
+               `checkout.ts` established for exactly this. */
+            let picture;
+            try {
+                picture = await readPngScreenshot(path);
+            }
+            catch (err) {
+                /* ═══ THE REASON IS KEPT, THE TEXT IS NOT. ═══ Every message from below
+                   may name the path, and not only where `readPngScreenshot` interpolated
+                   it: an `ENOENT` from Node restates the path in its own words, inside
+                   quotes, and a `replace(path, …)` over the string would miss any such
+                   restatement that differs by a byte. So nothing composed down there is
+                   forwarded. What the agent needs is which of these went wrong, and each
+                   of these sentences is written here. */
+                throw new Error(`NOTHING WAS WRITTEN: ${await whyNotAPicture(path)} Check the path and try once more.`);
+            }
+            /* ═══ THE ID IS MINTED HERE, BECAUSE THE STORAGE PATH IS DERIVED FROM IT.
+               ═══ `panel3_images_storage_path_shape` requires the object key to equal
+               `<user>/<card>/<id>.png`, so a server-defaulted id makes the key
+               uncomputable before the upload. */
+            const imageId = crypto.randomUUID();
+            const storagePath = `${userId}/${cardId}/${imageId}.png`;
+            const { error: uploadError } = await client.storage
+                .from(PANEL3_IMAGES_BUCKET)
+                .upload(storagePath, picture.bytes, { contentType: 'image/png', upsert: false });
+            if (uploadError) {
+                throw new Error(`NOTHING WAS WRITTEN: the picture could not be stored (${uploadError.message}).`);
+            }
+            /* ═══ A WORKER WRITES THE PICTURE AND NOTHING ELSE. ═══ It has no turn to
+               hang it on and must not acquire one: `panel3_say` would refuse it, and
+               it is right to. The row's null `turn_id` is what puts the picture on the
+               card as an event of its own, and the caption travels with it as the
+               row's own words rather than as a message the worker did not send. */
+            if (level === 3) {
+                /* ═══ AND IT ASKS FIRST WHETHER IT IS STILL RUNNING, WHICH LEVEL 2 GETS
+                   FOR FREE AND THIS DOES NOT. ═══ `panel3_say` refuses a stopped card
+                   and a superseded owner, so the level 2 path below cannot write a
+                   picture from a run that is over. A worker has no such gate: its row
+                   can be stamped `stopped` by the person's Stop button while its process
+                   lives on for another poll, and a bare insert here would put a picture
+                   on the card after they asked for it to end. */
+                if (!(await stillRunning(client, runId))) {
+                    throw new Error('NOTHING WAS WRITTEN: THIS RUN HAS ENDED, so nothing more of yours reaches the card. Stop.');
+                }
+                const { error } = await client.from('panel3_images').insert({
+                    id: imageId,
+                    card_id: cardId,
+                    turn_id: null,
+                    caption,
+                    storage_path: storagePath,
+                    width: picture.width,
+                    height: picture.height,
+                    size_bytes: picture.sizeBytes,
+                });
+                if (error) {
+                    throw new Error(`NOTHING WAS WRITTEN: the picture could not be recorded (${error.message}).`);
+                }
+                return 'Shown on the card. Carry on with your own work: this did not send anybody a message.';
+            }
+            /* ═══ SPEAK FIRST, THEN WRITE THE ROW. ═══ NOT the web send path's order,
+               and the difference is `panel3_say`'s: it returns NULL rather than
+               raising when the card is stopped or this owner has been superseded. An
+               image row written before that refusal would sit on the card with a null
+               `turn_id`, which is now a WORKER's picture and would be rendered as one.
+               Speaking first means a refusal happens before any row exists. The upload
+               still precedes both, so a refusal leaves bytes with no row, which is
+               invisible and is the honest way round: the alternative is a row pointing
+               at bytes that were never stored. */
+            const { data: turnId, error: sayError } = await client.rpc('panel3_say', {
+                p_run_id: runId,
+                p_body: caption,
+                ...(processToken === undefined ? {} : { p_process_token: processToken }),
+            });
+            if (sayError)
+                throw new Error(`could not show that on this card: ${sayError.message}`);
+            if (turnId === 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 showed them anything.');
+            }
+            const { error: rowError } = await client.from('panel3_images').insert({
+                id: imageId,
+                card_id: cardId,
+                turn_id: turnId,
+                /* ═══ NULL WHEN THERE IS A TURN, BECAUSE THE TURN IS ALREADY THE WORDS.
+                   ═══ Storing the caption twice would give the panel two places to read
+                   the same sentence from and a way for them to disagree. */
+                caption: null,
+                storage_path: storagePath,
+                width: picture.width,
+                height: picture.height,
+                size_bytes: picture.sizeBytes,
+            });
+            /* Truthful rather than tidy: the caption is already in front of the person,
+               so the failure says what they can see and what they cannot. */
+            if (rowError) {
+                throw new Error(`Your words reached them but the picture did not (${rowError.message}). They are looking `
+                    + 'at a message with nothing under it, so say what it was meant to show.');
+            }
+            return 'Shown. They can see the picture and read what you said about it. Carry on.';
+        },
+    },
+    // ── Keep a picture on the work item ──────────────────────────────────────
+    //
+    // ═══ A SECOND TOOL, NOT FIVE INPUTS ON THE FIRST. ═══ Anchoring a picture to
+    // a work item needs a title, a platform and a target that `attach_image` has
+    // no use for, and `attach_image` needs a caption this has no use for. Bolting
+    // them together makes five inputs, three of them conditional on each other,
+    // and a schema that cannot express its own rule. `attach_screenshot` is the
+    // shape followed here: every input required, one write path.
+    //
+    // ═══ AND THE ORG-SCOPED BUCKET IS RIGHT HERE, HAVING BEEN WRONG NEXT DOOR.
+    // ═══ `attach_image` writes to the private owner-scoped `panel3-images`,
+    // because a conversation is one person's. An artifact belongs to a work item
+    // the whole org can see, so it goes where every other artifact goes. Two
+    // visibility models, two buckets, both deliberate.
+    {
+        name: 'attach_image_artifact',
+        levels: [2, 3],
+        description: 'Keep a picture on the work item, where anybody can find it later. Use it when the picture is '
+            + 'part of what the work produced rather than something you are showing in passing: a screen '
+            + 'you have built, a diagram of what you changed, the state something is in. The picture must '
+            + 'be a PNG file that already exists on this machine, and you give its absolute path. It is '
+            + 'kept for good and cannot be replaced, so attach it when it is right. Use attach_image '
+            + 'instead for something the person only needs to see now.',
+        input: {
+            path: z.string().min(1).describe('The absolute path of a PNG file on this machine. "/Users/me/work/search-screen.png"'),
+            title: z.string().min(1).max(200).describe('What this picture is, as a person scanning the work item would want it named. '
+                + '"Search results with the new filter row."'),
+            work_item_id: z.string().uuid().describe('The work item to keep it on. It must be one this card carries: get_my_brief_and_report '
+                + 'names it.'),
+            platform: z.enum(['web', 'ios', 'android']).describe('Where the picture was taken.'),
+            target: z.string().min(1).max(200).describe('What was on screen, so somebody can find their way back to it. A URL, a route, or a screen '
+                + 'name. "/projects/search" or "Search results".'),
+        },
+        handler: async (caller, args) => {
+            const { path, title, work_item_id, platform, target } = args;
+            const { client, userId } = caller;
+            let picture;
+            try {
+                picture = await readPngScreenshot(path);
+            }
+            catch {
+                /* Path-free, for `attach_image`'s reason: a tool's thrown message is what
+                   the agent reads, and an agent quotes its own errors into a `say`. */
+                throw new Error(`NOTHING WAS WRITTEN: ${await whyNotAPicture(path)} Check the path and try once more.`);
+            }
+            /* ═══ THE WORK ITEM MUST BE ONE THIS CARD CARRIES. ═══ Validated once,
+               here, at the boundary. Without it an agent that names the wrong id
+               writes a picture onto an unrelated work item, which nothing downstream
+               would catch: the guard checks the artifact's SHAPE, and RLS lets this
+               person write to any item in their org. The card's attachments are what
+               the PERSON pointed this conversation at, so they are the authority on
+               what this run may anchor to. */
+            const attached = await loadAttachments(client, caller.cardId);
+            if (!attached.some((item) => item.kind === 'work_item' && item.ref_id === work_item_id)) {
+                throw new Error(`NOTHING WAS WRITTEN: this card does not carry work item ${work_item_id}, so a picture `
+                    + 'cannot be kept on it. get_my_brief_and_report names the work item you are on. If the '
+                    + 'picture belongs to the conversation rather than to an item, use attach_image.');
+            }
+            /* ═══ THE DATABASE DERIVES THE STORAGE PATH AND REFUSES ANY OTHER. ═══
+               `app.guard_agent_artifact_insert` computes
+               `<org>/<project>/<task>/<artifact id>.png` and raises on a mismatch, so
+               the org and project are resolved BEFORE the upload rather than after:
+               the key cannot be computed without them, and a server-defaulted artifact
+               id would make it uncomputable at all. */
+            const item = await only(client.from('tasks').select('id, project_id').eq('id', work_item_id).is('archived_at', null), 'read', `work item ${work_item_id}`);
+            if (item.project_id === null) {
+                throw new Error(`NOTHING WAS WRITTEN: work item ${work_item_id} is in no project, and a picture is kept `
+                    + 'under its project. Move it into one first.');
+            }
+            const project = await only(client.from('projects').select('id, org_id').eq('id', item.project_id).is('archived_at', null), 'read', `the project work item ${work_item_id} is in`);
+            /* ═══ CONTENT-ADDRESSED, NOT MINTED. ═══ The same picture under the same
+               anchor and title yields the same id, so a call interrupted between the
+               upload and the insert retries onto the same key and converges instead of
+               leaving one orphaned object per attempt. A random uuid would make every
+               retry a second artifact of the same picture. */
+            const artifactId = screenshotArtifactId(item.id, title, platform, target, picture.bytes);
+            const storagePath = `${project.org_id}/${item.project_id}/${item.id}/${artifactId}.png`;
+            /* ═══ EXACTLY THESE FIVE KEYS, BECAUSE THE GUARD DEMANDS EXACTLY THESE
+               FIVE. ═══ It rejects a `content` object with any other key set, so this
+               is not a place to add a field. */
+            const content = JSON.stringify({
+                platform,
+                target,
+                width: picture.width,
+                height: picture.height,
+                size_bytes: picture.sizeBytes,
+            });
+            const { error: uploadError } = await client.storage
+                .from('artifacts')
+                .upload(storagePath, picture.bytes, { contentType: 'image/png', upsert: false });
+            /* A duplicate key is the converging retry above, arriving: the bytes at
+               that key are this picture's, because the key is derived from them. */
+            if (uploadError && !/duplicate|already exists|resource exists/i.test(uploadError.message)) {
+                throw new Error(`NOTHING WAS WRITTEN: the picture could not be stored (${uploadError.message}).`);
+            }
+            const { error: insertError } = await client.from('artifacts').insert({
+                id: artifactId,
+                task_id: item.id,
+                type: 'image',
+                format: 'png',
+                title,
+                content,
+                storage_path: storagePath,
+                created_by: userId,
+                /* ═══ BOTH NULL, AND THE GUARD IS WHY. ═══ It refuses a non-null
+                   `from_agent` from an `authenticated` caller, and panel3's client is
+                   the person's own session. `create_artifact` leaves them null for the
+                   same reason. */
+                from_agent: null,
+                agent_run_id: null,
+            });
+            if (insertError) {
+                /* A retry that finds its own artifact already there has converged, which
+                   is the point of the derived id: say so rather than reporting a
+                   failure that would make the agent attach a second copy. */
+                if (/duplicate key|already exists/i.test(insertError.message)) {
+                    return `Already kept on the work item as "${title}". Nothing was written twice.`;
+                }
+                throw new Error(`the picture could not be kept on the work item (${insertError.message}).`);
+            }
+            await receipt(caller, 'artifact', artifactId, title);
+            return (`Kept on the work item as "${title}", and it shows on the card. It cannot be replaced, so `
+                + 'attach another if this one turns out to be wrong.');
+        },
+    },
     // ── Report ───────────────────────────────────────────────────────────────
     {
         name: 'report_activity',
@@ -1617,7 +2481,8 @@ const TOOLS = [
         description: 'Write down what is true NOW: what you have done, what you decided and why, and what is still '
             + 'open. It REPLACES your last report rather than adding to it, and it is what you are handed if '
             + 'you are respawned, so write it as the thing you would want to read to carry on. Write it as '
-            + 'you go, not only at the end.',
+            + 'you go, not only at the end. '
+            + FIREWALL_WRITING_RULE,
         input: { report: z.string().min(1) },
         handler: async ({ client, runId, processToken }, args) => {
             const { report } = args;
@@ -1767,7 +2632,7 @@ const TOOLS = [
                 ...(processToken === undefined ? {} : { p_process_token: processToken }),
             });
             if (error)
-                throw new Error(`could not answer question ${question_id}: ${error.message}`);
+                throw new Error(`could not answer question ${question_id}: ${readableWriteError(error.message)}`);
             if (data === null) {
                 /* REFUSED, AND THE THREE REASONS ARE ONE SENTENCE because the caller
                    cannot tell them apart and all three mean the same thing to it: this
@@ -1814,12 +2679,34 @@ const TOOLS = [
                 + 'context: what to find out or change, and in which part of the codebase.'),
             boundary: z.string().min(1).describe('What it must not touch, and where its work stops.'),
             work_item_id: z.string().optional().describe('The work item it is working, if there is one.'),
+            work_name: z.string().optional().describe(`A few words, ${WORK_NAME_WORDS} at most, naming the WORK this conversation is doing, such `
+                + 'as "Fix the sign-out checklist bug". Pass it when the conversation has NO work item '
+                + 'attached: the conversation is called this from now on, and the branch the work goes on is '
+                + 'cut from it, both at the moment you send somebody. Leave it out when a work item is '
+                + 'attached, because that item is already the name.'),
         },
         handler: async (caller, args) => {
-            const { codebase_id, responsibility, boundary, work_item_id } = args;
+            const { codebase_id, responsibility, boundary, work_item_id, work_name } = args;
             if (caller.level === 2 && !codebase_id) {
                 throw new Error('A worker must be attached to a registered project codebase.');
             }
+            /* ═══ THE NAME IS CHECKED BEFORE ANYTHING IS READ, WRITTEN OR STARTED.
+               ═══ It is the one argument here that changes something the person is
+               already looking at, so a refusal has to leave the card exactly as it
+               was and nobody running. */
+            const named = work_name === undefined ? null : work_name.trim();
+            if (named !== null) {
+                const words = named === '' ? [] : named.split(/\s+/);
+                if (words.length === 0) {
+                    throw new Error('NOTHING WAS WRITTEN and nobody was started: work_name is blank. Name the work in a few '
+                        + 'words, or leave it out and the conversation keeps the words they opened with.');
+                }
+                if (words.length > WORK_NAME_WORDS) {
+                    throw new Error(`NOTHING WAS WRITTEN and nobody was started: that is ${words.length} words, and it is `
+                        + `read on one line and cut into a branch name. The limit is ${WORK_NAME_WORDS}. Name `
+                        + 'the work, do not describe it.');
+                }
+            }
             let codebase = null;
             if (codebase_id) {
                 const projectId = await projectOfCard(caller);
@@ -1845,7 +2732,21 @@ const TOOLS = [
                three hops from level 1 still knows which item it is working, without
                asking. See `workBrief`'s own doc for why the two are different things
                carried the same way. */
-            const attachments = (await loadAttachments(caller.client, caller.cardId)).map(attachmentLine);
+            const attached = await loadAttachments(caller.client, caller.cardId);
+            /* ═══ THE CONVERSATION IS NAMED HERE OR IT IS NEVER NAMED. ═══ Sending
+               somebody resolves the working copy, and resolving it cuts the branch
+               from whatever the conversation is called at that moment and stamps it
+               for good. So the name is written BEFORE the call below, and there is no
+               second chance further on.
+      
+               AN ATTACHED WORK ITEM IS ALREADY THE NAME, so nothing is written over
+               it: the person chose that item and the conversation was called after it
+               the moment they did. */
+            if (named !== null && !attached.some((attachment) => attachment.kind === 'work_item')) {
+                await rows(caller.client.from('panel3_cards').update({ title: named }).eq('id', caller.cardId)
+                    .select('id'), 'name', `card ${caller.cardId}`);
+            }
+            const attachments = attached.map(attachmentLine);
             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);
@@ -1922,8 +2823,14 @@ const TOOLS = [
  * that produced nothing visible. So every `create_*` above writes its own
  * receipt, and `record_output` stays for what these tools did not create.
  *
- * UPDATES DELIBERATELY WRITE NOTHING. A receipt answers "what did this card
- * produce", and editing something twice did not produce it twice.
+ * AN EDIT RECORDS THE OBJECT TOO, ONCE. A person who asks for an artifact to be
+ * rewritten wants to open the thing that changed, and a card showing nothing
+ * leaves them nowhere to go; but editing something twice did not produce it
+ * twice. So the four editing tools go through `receiptOnce`, which calls
+ * `receipt` only when this card has no receipt for that object yet. `receipt`
+ * stays the only writer, and the check is deliberately NOT inside it: every
+ * create site hands it an id made a moment ago, which cannot already be there,
+ * and a read for each of them would buy nothing.
  *
  * ═══ AND AN ENDED RUN DOES NOT LEAVE RECEIPTS, WHICH IS THE ONE GUARD HERE
  *     THAT IS NOT ATOMIC. ═══
@@ -1940,18 +2847,50 @@ const TOOLS = [
  * is a duplicate of work another agent may redo, not an attribution to something
  * that never happened, which is why it does not earn an RPC of its own today.
  */
-async function receipt({ client, runId, cardId }, kind, refId, label) {
+/**
+ * Whether this run may still put something on the person's card.
+ *
+ * ═══ ONE OWNER, BECAUSE THERE IS ONE QUESTION. ═══ A run's process outlives its
+ * row: `panel3_stop_these` stamps `state` and `ended_at` across a whole subtree
+ * in one statement and the processes are killed within a poll, so between those
+ * two moments a child is alive and its row says it is finished. Every write that
+ * reaches the card asks this before it lands, and it is the same predicate for
+ * all of them, which is why it is a function rather than a clause repeated in
+ * each of them.
+ */
+async function stillRunning(client, runId) {
     const live = await rows(client.from('panel3_runs').select('id').eq('id', runId)
         .in('state', STILL_WRITING).is('ended_at', null), 'check', `whether run ${runId} is still running`);
-    if (live.length === 0) {
-        /* IT NAMES WHAT WAS MADE. The product row exists — it was created before
-           this was reached — so an error that only said "refused" would leave the
-           agent unable to say whether the thing is there. */
-        throw new Error(`the ${kind} ${refId} was created, but THIS RUN HAS ENDED so no receipt was written for it and `
-            + 'its card has been handed to another agent. Say what you made and stop.');
+    return live.length > 0;
+}
+async function receipt({ client, runId, cardId }, kind, refId, label) {
+    if (!(await stillRunning(client, runId))) {
+        /* IT NAMES WHAT LANDED. The product row exists — it was written before this
+           was reached — so an error that only said "refused" would leave the agent
+           unable to say whether the thing is there. IT COVERS BOTH CALLERS: the
+           creating tools and, through `receiptOnce`, the editing ones, so it must
+           not tell an agent it created what it changed. */
+        throw new Error(`the ${kind} ${refId} was written, but THIS RUN HAS ENDED so no receipt was written for it and `
+            + 'its card has been handed to another agent. Say what you did and stop.');
     }
     await only(client.from('panel3_outputs').insert({ card_id: cardId, run_id: runId, kind, ref_id: refId, label }).select('id'), 'record', `the ${kind} on the card`);
 }
+/**
+ * The same receipt, unless this card already carries one for that object.
+ *
+ * ═══ THIS IS NOT A RACE GUARD, AND IS NOT CLAIMED AS ONE. ═══ `panel3_outputs`
+ * has no unique key over card, kind and ref, so two edits of the same object
+ * landing in the same instant can both read nothing and both write. What that
+ * costs is one repeated card and nothing worse, which is why it does not earn a
+ * constraint or an RPC today.
+ */
+async function receiptOnce(caller, kind, refId, label) {
+    const already = await rows(caller.client.from('panel3_outputs').select('id')
+        .eq('card_id', caller.cardId).eq('kind', kind).eq('ref_id', refId), 'check', `whether the ${kind} ${refId} is already on the card`);
+    if (already.length > 0)
+        return;
+    await receipt(caller, kind, refId, label);
+}
 /** The names one level is served, in the order they are registered. Exported for
  *  the same reason `cs show` exists: a rule nobody can print is a rule nobody
  *  can check. */