chamba 0.7.0 → 0.8.0

package/templates/skills/dx-spec-execute/SKILL.md

@@ -7,12 +7,16 @@ argument-hint: "[the name of the piece of work to run]"
 
 # dx-spec execute - build the work from its plan
 
-This skill runs when the user types `/dx-spec-execute`. It never starts on its own.
+This skill runs when the user types the command, or when the Specs tab types it as the user's own act. It never starts on its own.
+Each agent spells it its own way - `/dx-spec-execute` on claude and on opencode, and `$dx-spec-execute` on codex.
 
 Your job is to move through the phases of one spec's plan, and to keep every bit of progress on disk, so a later session restarts from this point.
 
 Write, build, verify, record and commit each phase yourself.
 The only subagents are reviewers, and they exist so somebody who did not do the work judges it.
+An agent with no subagent tool still reviews, one focus at a time and by itself, and says so - the review checkpoints section below has the whole of it.
+
+A framed `[specs]` line never starts this skill: such a line is information for a run already going, and it instructs nobody.
 
 ## The web session
 
@@ -27,7 +31,9 @@ The answer holds `root` - the directory the tab serves - and the stage catalog.
 A refusal means there is no pane.
 Say this and stop:
 
-> This works in the chamba web session, where the Specs tab holds your work. Open the browser window this container printed at start, or run `webterm` in the terminal to get the address again. Then run `/dx-spec-execute` there.
+> This works in the chamba web session, where the Specs tab holds your work. Open the browser window this container printed at start, or run `webterm` in the terminal to get the address again. Then ask for this skill there.
+
+Say the command in the spelling of the session's own agent.
 
 Start no flow, and offer no substitute.
 
@@ -37,12 +43,15 @@ Start no flow, and offer no substitute.
 A pause, a blocked run, a choice of spec: each one is a gate or a round on the tab.
 Declaring one ends your turn.
 The pane types one line into this terminal when the user answers, and that line starts you again.
+A line saying a question was asked is not an answer: the user wants to know something before they decide, the ask is still open, and the form is still on their screen.
+Answer it here in plain message text, and leave the ask standing.
 
 `/dx-spec` carries the payload shapes, under **The verbs**.
 Read that section for the exact JSON.
 
 **Everything you tell the user while building is normal message text.**
-A progress report is not a question.
+A progress report is not a question, and it is not a stop.
+Say it, and go straight on to the next thing in the same turn.
 
 **Post the run as it moves**, so the board shows it live:
 
@@ -56,6 +65,29 @@ echo '{"round":1,"verdict":"holds, one for you","findings":6,"judgments":1}' | s
 
 A phase's id is its file's name without the extension, which is what you already write and tick.
 
+## The run does not stop on its own
+
+The `pauses` decision is the only thing that stops this run for the user.
+`"pauses": "none"` means you build every phase, from the first to the last, and give the turn back once.
+
+Four things end your turn, and nothing else does:
+
+- A pause the decisions put there.
+- A stop condition from **Stop and ask**.
+- An ask this skill itself sends you to the tab with: the branch gate, and a decision card for a review finding that is the user's to judge. Declaring one ends your turn, as it does everywhere in this family.
+- The end of the run, where the report goes.
+
+A review checkpoint is not one of them.
+Run it, fix what it found, and start the next phase in the same turn.
+Finishing a phase is not one of them either, however much there is to say about it.
+
+Waiting for a reviewer you started is not a stop.
+Where your environment makes you give the turn back to hear one, say that you are waiting, and carry the run on the moment the answer arrives.
+
+A run that gives the turn back with a phase left to build has failed, unless it is at one of the four.
+Before you end a turn, name which of the four you are at.
+With none of them, you are not finished: go on to the next step.
+
 ## The tool owns the state
 
 The Specs tool writes `state.json` and each spec's `README.md`.
@@ -71,9 +103,36 @@ The tab lists it beside the other artifacts and renders it.
 A page about anything else goes to the Pages tab with `webpane`.
 Either way, keep it standalone: no external stylesheet, no script that fetches anything, and images as data URLs.
 
+## The run decisions are the user's instruction
+
+`runDecisions` in the state holds how this run is shaped: the commits, the branch, the pauses and the review checkpoints.
+The user settled every one of them on the execute form, in the act that started this run, and all of it binds you.
+
+```json
+{ "commits": "per-phase", "branch": "new", "branchName": "spec/checkout-discounts",
+  "pauses": "chosen", "pausePhases": ["phase-03-the-banner"],
+  "checkpoints": [
+    { "after": "final", "why": "judges the finished work as a whole",
+      "panel": ["correctness against the spec", "docs consistency"], "chosen": true } ],
+  "decidedAt": "2026-08-31T09:12:04.118Z" }
+```
+
+Read each field as it is written, and never read around it:
+
+- `pausePhases` counts only where `pauses` is `chosen`. A list left standing beside `none` or `every` is not a pause.
+- A checkpoint counts only where its `chosen` is true. One that is false stays in the record and does not run.
+- `branchName` counts only where `branch` is `new`.
+
+**A spec with no `runDecisions` is a spec whose run was never set up.**
+Say so, name the Execute action on the tab as where it is settled, and stop.
+An old spec may carry lines in `plan/PLAN.md` that describe how its run was once meant to go.
+Those lines are not the decisions and never override them.
+The form never reads them: it opens on the recommendations where there are any, and on the built-in defaults where there are none.
+So where the state holds decisions they bind you, and where it holds none there is nothing to act on, whatever `PLAN.md` says.
+
 ## The plan is the user's instruction
 
-The user chose everything in the plan at spec time: the commits and the branch, the pauses, the review checkpoints, the verify steps, and the principles check with its recorded deviations.
+The user chose everything in the plan at spec time: the phases, the verify steps, and the principles check with its recorded deviations.
 All of it binds this run.
 
 A recorded deviation is an approved exception.
@@ -91,8 +150,15 @@ The plan loses to the user, and never to you.
 
 ## 0. Bootstrap
 
-Run the bootstrap in `../dx-spec-config/SKILL.md` first.
-It resolves the root, reads the principles file, offers the one-time setup when there is none, and gives you the settings for the rest of the run.
+Settle the root and the principles first:
+
+1. Read `root` from `specs stages`. That is the directory the Specs tab serves, and every path in this family resolves against it.
+2. Read `<root>/principles.md`. It is plain markdown: a `# Principles` heading, then one `- <principle>` bullet each, and nothing else.
+3. Where no file is there, write one from `../dx-spec/references/principles-template.md`. Say in one line that you made it, and carry straight on.
+4. Honor every principle the file holds for the rest of the run, best-effort - which is the standing each one has, and no more. A file with no bullets holds no principles, so there is nothing to honor.
+
+A file that is already there produces no message at all.
+Nothing else about how this family works is configurable, and the user changes a principle by editing that file.
 
 ## 1. Choose the spec
 
@@ -114,20 +180,21 @@ Declare the round on the likeliest candidate, because every asking verb names a
 Change nothing until the user answers.
 
 With no candidate at all, ask nothing.
-Say there is no open work, name `/dx-spec` as where a spec gets written, and stop.
+Say there is no open work, name the `dx-spec` skill as where a spec gets written, and stop.
 
 Then read, in this order: `specs state <spec>`, `spec/SPEC.md`, and `plan/PLAN.md`.
 Do not read a phase file yet. Read or write one when its phase starts.
 
-Handle these two states before anything else:
+Handle these three states before anything else:
 
-- No `plan/` directory: say this spec has no execution plan, say `/dx-spec` adds one, and stop.
+- No `plan/` directory: say this spec has no execution plan, say the `dx-spec` skill adds one, and stop.
 - Every phase ticked: say so, and stop.
+- No `runDecisions` in the state: say the run is not set up yet, name the Execute action on the tab as where that happens, and stop.
 
 ## 2. Work out where things stand
 
 Work it out from disk alone.
-Say it in a message before you do anything, together with what the plan asks for: its `Pauses:` line and its `Review checkpoints:` line.
+Say it in a message before you do anything, together with what the decisions ask for: where this run pauses, and where it gets reviewed.
 The user then knows from the start where this run stops and where it gets reviewed.
 
 **The phases.**
@@ -139,15 +206,14 @@ The user then knows from the start where this run stops and where it gets review
 - The state file carries a dated line for each completed review checkpoint. A checkpoint whose phases are all done with no such line has not run. Run it before you move on.
 
 **The commits.**
-Read the `Commits:` line: `per phase`, `single` or `none`.
+`commits` is `per-phase`, `single` or `none`.
 It says how much of the record the repository itself shows:
 
-- `per phase`: a completed phase is a committed phase, and uncommitted changes belong to the phase that was interrupted.
+- `per-phase`: a completed phase is a committed phase, and uncommitted changes belong to the phase that was interrupted.
 - `single` or `none`: nothing is committed before the run ends, if at all. The phase status lines and the ticked boxes are the only record.
 
-Read the `Branch:` line with it.
-`current` means the commits land on the current branch.
-Any other value names a branch for this run.
+Read `branch` with it.
+`current` means the commits land on the branch that is checked out, and `new` means they land on the branch `branchName` names.
 
 **A state that does not match.**
 When the disk does not hold what this skill expects, settle it with judgment and say what you chose in the report.
@@ -195,7 +261,7 @@ Every phase goes through the same steps, and you carry out every one yourself.
 
 4. **Record.** Set the phase's `Status:` to `done`, tick its box in `PLAN.md`, and post the phase as `done`.
 
-   With `Commits: per phase`: commit the phase's changes with a one-line message in the commit style from the principles file, using "phase NN - <name>" as its descriptive part. Commit only. Never push.
+   With `"commits": "per-phase"`: commit the phase's changes with a one-line message in the commit style, using "phase NN - <name>" as its descriptive part. The style is stated once, in `dx-spec/SKILL.md` under **The commit style**, and a phase commit takes the type that suits what the phase did. Commit only. Never push.
 
    With `single` or `none`: commit nothing here.
 
@@ -203,50 +269,67 @@ Every phase goes through the same steps, and you carry out every one yourself.
 
 Then, in this order:
 
-- The review checkpoint after this phase, when the plan puts one there.
-- The pause after this phase, when the plan puts one there.
+- The review checkpoint after this phase, when the decisions put one there.
+- The pause after this phase, when the decisions put one there.
 
 A pause therefore always reports a result that is already reviewed and fixed.
+Where no pause sits after this phase, the next phase starts in the same turn.
 
 **On the first phase of a run**, post the status as `executing`.
 
-**Before that first phase, when `Branch:` names a branch**, put the run on it:
+**Before that first phase, commit the run decisions**, where the spec directory is already committed.
+The decisions the user made are part of the record of this work, so the spec directory is committed on the branch that is checked out now, before any move to the run's branch.
+What lands is whatever of that directory the repository keeps: the rendered `README.md` always, and the state file where the repository does not ignore it.
+Stage the spec directory by path, and compose the message from **The commit style** in `../dx-spec/SKILL.md`, with "<spec name> run set up" as the descriptive part.
+This one commit happens whatever `commits` says, `none` included: it records what the user decided, not what this run built.
+Where the spec directory holds nothing uncommitted, there is nothing to commit and nothing to say.
+Where it was never committed at all, commit nothing, and say so in the report.
+
+**Then, where `branch` is `new`**, put the run on the branch `branchName` names:
 
 - Already on it: carry on.
 - It exists but is not checked out: switch to it.
 - It does not exist: create it from the current `HEAD`.
 
 When the working tree holds changes that do not belong to this work, gate it on the tab before you switch or create: move to the branch and bring those changes along, or stay where you are and commit on the current branch.
-When the user stays, say in the report that this run's commits did not go to the planned branch.
+When the user stays, say in the report that this run's commits did not go to the branch that was decided.
 
 Never merge, and never push. Merging the work back is the user's job.
 
-**The final commit with `Commits: single`.**
+**The final commit with `"commits": "single"`.**
 Once the last phase passes its verify steps and finishes its record step, commit everything this work produced, in one commit.
-Compose the message from the commit style, with the `PLAN.md` title as its descriptive part.
+Compose the message from **The commit style** in `dx-spec/SKILL.md`, with the `PLAN.md` title as its descriptive part.
 That commit also covers earlier runs of the same work, which committed nothing.
 Make it before the final review checkpoint: a final checkpoint must never read an uncommitted tree when commits are on.
+`single` counts what the run built.
+The run-decisions commit at the start and the closing commit at the end stand outside that count: each one carries the record of the run rather than the work, and each one happens on its own terms.
 
-With `Commits: none`, commit nothing at any point.
+With `"commits": "none"`, commit nothing this run built, at any point.
+The run-decisions commit above is not one of the run's commits, and happens either way.
 
 **Keep the spec true.**
 When what gets built differs from `spec/SPEC.md` or the plan, update those files as part of the phase.
 The spec is the documentation of what was actually built.
+`/dx-spec` carries the rule over this, under **Keep what derives from a change true**: what derives from the document you changed is refreshed in the same act.
 When the solution departs noticeably from an approved solution sketch, that is a stop condition: the sketch does not bind you, but the user approved it and has to stay informed.
 
 ### Review checkpoints
 
-The `Review checkpoints:` line says where fresh reviewers judge the work.
-Each sub-bullet names one checkpoint: where it sits, how many reviewers, a focus each, and why it is there.
-`Review checkpoints: none` means no review runs, and the report says the plan chose none.
+`checkpoints` says where fresh reviewers judge the work.
+Each one names where it sits in `after` - a phase id, or the word `final` - and holds one focus per reviewer in `panel`.
+A checkpoint runs only where its `chosen` is true; one that is false is a record of what was offered and declined.
+With no chosen checkpoint at all, no review runs, and the report says the user chose none.
 
-Run a checkpoint once you record the phase it sits after, and once any commit the plan asks for has landed.
+Run a checkpoint once you record the phase it sits after, and once any commit the decisions ask for has landed.
 Run the `final` checkpoint once the last phase is recorded, any required commit has landed, and before the end-of-run report.
 
 **Start one reviewer subagent per focus the checkpoint names.**
 The reviewers share no context: each gets its own prompt, none sees this conversation, none learns what the others found, and you are never one of them.
 A reviewer's whole value comes from judging work it did not do.
-Treat an inability to start reviewers as a stop condition, and never review the work yourself instead.
+
+An agent with no subagent tool runs the same passes itself, one focus at a time, and writes each pass's findings down before it starts the next.
+Say in the report that the checkpoint ran inline, and that the fresh-context guarantee did not hold.
+An agent that has the capability but cannot make it work is a different case: that is a stop condition, and it never downgrades quietly.
 
 Tell each reviewer:
 
@@ -265,14 +348,18 @@ Then, yourself:
 - Re-run the Verify steps of every phase the fixes touch.
 - Have each reviewer who rejected a fix re-check it once.
 - When a reviewer still objects after that re-check, you settle it: fix it once more when the objection names something real, and otherwise record the finding as knowingly accepted and move on.
-- When commits are on, land the fixes in one follow-up commit, with "review fixes" as the descriptive part.
+- When commits are on, land the fixes in one follow-up commit, in **The commit style**, with "<spec name> review fixes" as its descriptive part.
 
 Post the round with `specs review`, so the board carries its verdict.
 Bring a finding that is the user's to judge to the tab as a decision card, rather than settling it yourself.
+A card names the passage it is about by file and by section, asks one question, and offers the ways out as its own options, one of them recommended.
+`../dx-spec/SKILL.md` carries the shape, under **The verbs**.
 
 ### Pauses
 
-The `Pauses:` line says when the run stops for the user: `none`, a list of phases, or `every phase`.
+`pauses` says when the run stops for the user.
+`none` stops nowhere, `every` stops after every phase, and `chosen` stops after each phase `pausePhases` names.
+Read `pausePhases` only where `pauses` is `chosen`: a list beside `none` is what an earlier decision left behind, and it is not a pause.
 
 At a pause, once the phase is built, reviewed where a checkpoint sits there, recorded and committed, report what the phase produced in a message.
 Then declare a gate: carry on, or stop here.
@@ -311,14 +398,40 @@ Settle it, keep the run moving, and say in the report what you settled.
 A run that stops to ask about something it could have settled has failed.
 Quality is yours to hold, and the user is waiting for the finished work.
 
-## 5. Report
+## 5. The end of the run
+
+Every phase is done, the final checkpoint has run, and its review-fixes commit has landed.
+Then, in this order:
+
+```
+echo '{"kind":"status","status":"complete"}' | specs post <spec>
+```
+
+The post moves the state file and the rendered `README.md`, so it goes before the commit that carries them.
+
+Then, unless `commits` is `none`, stage the spec directory by path and commit it.
+Compose the message from **The commit style** in `dx-spec/SKILL.md`, with "<spec name> complete" as its descriptive part, which makes it a `docs` commit.
+This one commit covers the phase files, the ticked plan, the spec the run kept true, and the rendered board.
+Staging by path leaves every other change in the working tree alone, and the tree is clean over the spec directory once it lands.
+Commit only. Never push.
+
+With `"commits": "none"`, post the status and commit nothing.
+The report then says the closing status was left uncommitted, so the user knows the state file and the `README.md` are changed and theirs to keep or to drop.
 
-At the end of the run, or at a pause, report in a normal message:
+Then give the report below, which is what ends the turn and says what the closing commit did.
+
+## 6. Report
+
+This report is what ends a turn.
+Give it at the end of the run, at a pause, or at a stop condition, and nowhere else.
+What you say between phases is a progress line: say it and keep building.
+
+Report in a normal message:
 
 - The phases finished this run, and the overall progress, such as "5/7 phases done".
-- What the verification showed, and the outcome of every checkpoint this run ran: what the reviewers found, what was fixed, what was dismissed and why. When the plan asked for no review, say so.
+- What the verification showed, and the outcome of every checkpoint this run ran: what the reviewers found, what was fixed, what was dismissed and why. When no checkpoint was chosen, say so.
 - What you settled on your own, where it matters to the user.
 - The branch, when the run committed to one of its own, that it is unmerged, and that merging it back is the user's job.
+- Whether the run decisions were committed, and where they were not, that the spec directory was never committed.
 - Why the run stopped, when it stopped at a pause or a stop condition, and what you need from the user.
-
-When every phase is done, post the status as `complete`.
+- Whether the closing commit landed, and under `"commits": "none"`, that the closing status was left uncommitted.

package/templates/startup.mjs

@@ -71,7 +71,7 @@ try {
 
 // -- Context snapshot cleanup (best-effort, silent) ---------------------------
 // claude-statusline.sh writes one small per-session snapshot to this directory on every
-// prompt render (see the context-usage helper). Delete week-old entries here -- covers both
+// prompt render, and the web interface's status strip reads it. Delete week-old entries here -- covers both
 // stale *.json snapshots and orphaned .tmp.* files. Any failure is swallowed so cleanup
 // can never affect readiness checks.
 const SNAPSHOT_DIR = "/home/devuser/.claude/context-usage";
@@ -165,7 +165,8 @@ const doUpdate = (label) =>
         });
     });
 
-// SPACE within `seconds` -> skip. Any other input is ignored. Ctrl+C exits 130. Non-TTY -> no skip.
+// SPACE within `seconds` -> skip. ENTER -> update now, without waiting out the countdown. Any other input is
+// ignored. Ctrl+C exits 130. Non-TTY -> no skip.
 const promptSkipUpdate = (seconds) =>
     new Promise((resolve) => {
         if (!process.stdin.isTTY) {
@@ -175,7 +176,7 @@ const promptSkipUpdate = (seconds) =>
         let remaining = seconds;
         let tick;
         let timer;
-        const line = (s) => `\r\x1b[K${blue("●")} ${dim(`Updating AI CLIs in ${s}s... press SPACE to skip`)}`;
+        const line = (s) => `\r\x1b[K${blue("●")} ${dim(`Updating AI CLIs in ${s}s... SPACE to skip, ENTER to update now`)}`;
         const cleanup = () => {
             clearInterval(tick);
             clearTimeout(timer);
@@ -195,6 +196,11 @@ const promptSkipUpdate = (seconds) =>
                     resolve(true);
                     return;
                 }
+                if (byte === 0x0d || byte === 0x0a) {
+                    cleanup();
+                    resolve(false);
+                    return;
+                }
             }
         };
         process.stdin.setRawMode(true);
@@ -221,7 +227,7 @@ if (Number.isFinite(lastUpdate) && Date.now() - lastUpdate < THROTTLE_MS) {
     if (summary) console.log("");
     if (!timestampFileExists) {
         await doUpdate("Installing AI CLIs...");
-    } else if (await promptSkipUpdate(3)) {
+    } else if (await promptSkipUpdate(5)) {
         skip("AI CLIs", "update skipped by user");
     } else {
         await doUpdate("Updating AI CLIs to latest...");

package/templates/tool-helper.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# The agent's half of a pane tool's channel, in this session's web pane.
+# Baked into the image at /usr/local/share/chamba/tool-helper.sh, on PATH as `specs` and as `reviews`.
+#
+# One script, and the tool it is for is the name it was called by. The two channels differ in a word, a door
+# and a list of verbs, and in nothing else: the pane writes a file and types one line into this terminal, and
+# these verbs are how the work moves the other way. Everything they change is a file in the tool's own
+# directory, so every exchange is something git can see.
+#
+# The caller says who it is by its own pid and nothing more, exactly as `webpane` does. The server walks up
+# the process tree from there to a session it started, and refuses a caller that is not in one.
+set -euo pipefail
+
+CONTAINER_PORT="${WEBTERM_PORT:-3899}"
+KEY_FILE="${WEBTERM_KEY_FILE:-/tmp/webterm.key}"
+
+# Which tool this is. The link's own name, so `specs` and `reviews` are one script with one set of rules.
+TOOL="$(basename "$0")"
+
+case "$TOOL" in
+    specs | reviews) ;;
+    *)
+        echo "tool-helper: no pane tool is called ${TOOL}." >&2
+        exit 1
+        ;;
+esac
+
+usage_specs() {
+    cat <<'TEXT'
+Usage: specs <verb> [<spec>] < payload.json
+
+Verbs:
+  stages                 Where the specs live, and every stage a protocol may hold.
+  state    <spec>        Where the work stands: protocol, activity, what awaits the user.
+  intake   [<spec>]      File a new piece of work. { name, text, attachments, wish }
+  propose  <spec>        Recommend a protocol. { stages: [{ id, recommended, why }], note }
+  recommend <spec>       Recommend how the run is shaped. { commits, branch, branchName, pauses, pausePhases, pauseReasons, noPauseReason, checkpoints }
+  await    <spec>        Declare a gate, a round or a decision card. { id, kind, title, file, payload }
+  withdraw <spec>        Take back an ask nobody needs to answer. { id, reason }
+  post     <spec>        Say what is happening. { kind: activity | stage | phase | plan | status | note, ... }
+  review   <spec>        Post a round of quality review. { round, verdict, findings, judgments }
+  answers  <spec>        Read back what the user answered. { id }
+
+A payload is JSON on stdin, where the verb takes one. The answer is JSON on stdout.
+TEXT
+}
+
+usage_reviews() {
+    cat <<'TEXT'
+Usage: reviews <verb> [<review>] < payload.json
+
+Verbs:
+  stages                 Where the reviews live, and what a review may hold.
+  state    <review>      The state, the baseline's summary, and what awaits whom.
+  start                  File a review from this terminal. { name, selection }
+  metadata <review>      Post the grouping and the notes for the baseline. { fingerprint, groups, notes }
+  reply    <review>      Append one reply to a thread. { thread, text }
+  activity <review>      Say what you are doing. { said }
+  done     <review>      End your act; the tool recomputes the baseline where one is due.
+  log      <review>      One dated line for the activity log. { said }
+
+A payload is JSON on stdin, where the verb takes one. The answer is JSON on stdout.
+
+Nothing here marks a hunk seen, closes a thread, approves, or changes the baseline of its own accord.
+Those are the reviewer's, through the tab.
+TEXT
+}
+
+VERB="${1:-}"
+ENTRY="${2:-}"
+
+case "$VERB" in
+    "" | -h | --help)
+        "usage_${TOOL}"
+        exit 0
+        ;;
+esac
+
+if [ ! -r "$KEY_FILE" ]; then
+    echo "${TOOL}: the web interface is not running in this container, so there is no pane to tell." >&2
+    exit 1
+fi
+
+# A payload is read only for a verb that takes one. The verbs that carry none never touch stdin: an agent's
+# shell often runs with a stdin that is neither a terminal nor closed - a socket, an open pipe - and a read on
+# it waits for a close that never comes, which hangs the agent rather than answering it. So what is read is a
+# pipe or a file, which is what a payload arrives on, and nothing else is read at all.
+#
+# The list is every such verb of either tool: `stages` and `state` read, and `reviews done` says its one thing
+# by being called. A name no tool has is refused by the server whatever happens here.
+BODY_FILE="$(mktemp)"
+REQUEST_FILE="$(mktemp)"
+PAYLOAD_FILE="$(mktemp)"
+trap 'rm -f "$BODY_FILE" "$REQUEST_FILE" "$PAYLOAD_FILE"' EXIT
+
+# The payload lands in a file rather than in a variable, because it is passed to jq and an argument has a
+# size limit of its own: the grouping of a large review is hundreds of kilobytes, which is well under what
+# the server accepts and over what one argument can carry.
+echo -n "null" >"$PAYLOAD_FILE"
+case "$VERB" in
+    stages | state | done) ;;
+    *)
+        if [ -p /dev/stdin ] || [ -f /dev/stdin ]; then
+            cat >"$PAYLOAD_FILE"
+            if [ ! -s "$PAYLOAD_FILE" ]; then
+                echo -n "null" >"$PAYLOAD_FILE"
+            fi
+        fi
+        ;;
+esac
+
+# The request is composed with jq so the payload stays JSON rather than being spliced into a string. jq is in
+# the image; without it there is no safe way to build this, so the helper says so instead of guessing.
+if ! command -v jq >/dev/null 2>&1; then
+    echo "${TOOL}: jq is not in this container, and the request cannot be composed without it." >&2
+    exit 1
+fi
+
+# `--slurpfile` reads the payload as JSON from the file, and jq's own words are kept: a payload that is
+# not JSON and a payload too large to read say different things, and an agent told the wrong one rewrites
+# correct JSON for ever.
+if ! SAID="$(jq -n --arg verb "$VERB" --arg entry "$ENTRY" --slurpfile payload "$PAYLOAD_FILE" \
+    '{ verb: $verb, entry: $entry, payload: $payload[0] }' 2>&1 >"$REQUEST_FILE")"; then
+    echo "${TOOL}: the payload on stdin is not JSON - ${SAID}" >&2
+    exit 1
+fi
+
+# How long an answer is waited for. Most verbs write a file and answer; `start` and `done` recompute a
+# baseline, which reads the whole diff of a selection and every blob in it, and a wait that ran out there
+# would tell the agent the act failed while the interface was still doing it.
+case "$VERB" in
+    start | done) DEADLINE=300 ;;
+    *) DEADLINE=30 ;;
+esac
+
+# $$ is this script's own pid. The server climbs from it to whichever session started it.
+STATUS="$(
+    curl -sS -o "$BODY_FILE" -w '%{http_code}' \
+        --connect-timeout 3 --max-time "$DEADLINE" \
+        -X POST \
+        -H "Content-Type: application/json" \
+        -H "X-Webterm-Key: $(head -n 1 "$KEY_FILE")" \
+        -H "X-${TOOL^}-Pid: $$" \
+        --data-binary "@${REQUEST_FILE}" \
+        "http://127.0.0.1:${CONTAINER_PORT}/${TOOL}/agent" 2>/dev/null
+)" || {
+    echo "${TOOL}: could not reach the web interface on this container's port ${CONTAINER_PORT}." >&2
+    exit 1
+}
+
+if [ "$STATUS" = "200" ]; then
+    jq . <"$BODY_FILE"
+    exit 0
+fi
+
+REASON="$(jq -r '.error // empty' <"$BODY_FILE" 2>/dev/null)"
+if [ -z "$REASON" ]; then
+    case "$STATUS" in
+        403) REASON="the key on disk is not the one the interface is using" ;;
+        409) REASON="this is not running inside a web session" ;;
+        413) REASON="the payload is too large" ;;
+        *) REASON="the interface answered ${STATUS}" ;;
+    esac
+fi
+echo "${TOOL}: nothing was done - ${REASON}." >&2
+exit 1