chamba 0.6.1 → 0.8.0

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

@@ -0,0 +1,437 @@
+---
+name: dx-spec-execute
+description: Run the execution plan of a spec the Specs tab holds, phase by phase, with the run's progress on that tab as it goes. User-invoked only.
+disable-model-invocation: true
+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 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
+
+This family runs inside a chamba web session, where the Specs tab holds the work.
+Check for one before anything else:
+
+```
+specs stages
+```
+
+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 ask for this skill there.
+
+Say the command in the spelling of the session's own agent.
+
+Start no flow, and offer no substitute.
+
+## Asking and telling
+
+**Everything you ask the user goes on the Specs tab**, through `specs await`.
+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, 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:
+
+```
+echo '{"kind":"status","status":"executing"}' | specs post <spec>
+echo '{"kind":"phase","phase":"phase-02-the-consuming-skills","title":"The consuming skills","status":"running"}' | specs post <spec>
+echo '{"kind":"activity","said":"Running the verify steps"}' | specs post <spec>
+echo '{"kind":"phase","phase":"phase-02-the-consuming-skills","title":"The consuming skills","status":"done"}' | specs post <spec>
+echo '{"round":1,"verdict":"holds, one for you","findings":6,"judgments":1}' | specs review <spec>
+```
+
+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`.
+**Never edit either one.**
+The status, the phase list, the review rounds and the dated log are the tool's, and the verbs above are how they move.
+
+`plan/PLAN.md` and the phase files are yours, and you write them by hand as always.
+
+## A page you make during the run
+
+A page that explains this piece of work belongs to the work, so save it into the spec directory under a lowercase name.
+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 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.
+Build the work to match it, and never return it quietly to the principle it excepts.
+A principle the plan does not except stays binding.
+
+Your own limits do not justify a change to the plan.
+When you cannot do what the plan asks, that is a stop condition, and the **Stop and ask** section says how to raise it.
+Never replace the plan's instruction with a weaker one and carry on.
+
+Two things fall outside this rule.
+A choice of your own that changes nothing - which of two equal ways to read a file - is yours.
+An instruction from the user in this conversation overrides the plan.
+The plan loses to the user, and never to you.
+
+## 0. Bootstrap
+
+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
+
+A candidate is a piece of work under the root, outside `archive/`, whose plan still holds an unticked phase.
+
+The user may name one.
+A name that matches one spec exactly is an instruction, not a guess.
+Start on it, and ask nothing.
+
+In three cases the spec is a guess of yours:
+
+- A name that matches no spec exactly.
+- A spec you infer from the conversation.
+- The one candidate, when there is only one.
+
+Confirm a guess in a round before you do any work, even when one candidate exists.
+Give the round one option per candidate, carrying how many phases are done and what comes next, and one option that means none of these.
+Declare the round on the likeliest candidate, because every asking verb names a spec and it has to be one that is there.
+Change nothing until the user answers.
+
+With no candidate at all, ask nothing.
+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 three states before anything else:
+
+- 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 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.**
+
+- A phase ticked in `PLAN.md` is done.
+- The first unticked phase is next.
+- A phase file that exists carries a `Status:` line: `in progress` or `done`.
+- A file at `in progress` under an unticked phase means an earlier session stopped mid-phase. Treat it as suspect: check `git status` for half-done work, re-run the verify steps of the ticked tasks, and carry on from where the evidence points.
+- 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.**
+`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.
+- `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 `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.
+Do not stop, and do not follow a fixed rule.
+
+## 3. The loop
+
+Every phase goes through the same steps, and you carry out every one yourself.
+
+1. **The phase file.**
+
+   Check for a phase file an interrupted run left, and never rewrite one.
+   Check it against the actual code before you change anything.
+   Keep its ticked tasks: they show what got done.
+   Adapt a small change and note it. Treat a design change as a stop condition.
+
+   With no such file, write `plan/phase-NN-<slug>.md` right before you build the phase, against the code as it stands after the earlier phases.
+   Take the goal and the definition of done from `PLAN.md`:
+
+   ```markdown
+   # Phase 02 - <name>
+
+   Status: in progress
+
+   ## Tasks
+
+   - [ ] <task>
+   - [ ] <task>
+
+   ## Verify
+
+   - <command or check that proves the definition of done>
+   ```
+
+   Do not give much weight to development cost when you write it.
+   Prefer quality, simplicity, robustness, scalability and long-term maintainability.
+   When something grows too large, restructure it by judgment: refactor, split, or extract.
+   Never restructure by a number set in advance.
+
+   Post the phase as `running`.
+
+2. **Build.** Keep the changes scoped to this phase, and tick each task as it completes.
+
+3. **Verify.** Run the Verify section, and make it pass.
+
+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, 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.
+
+   Finish the whole record before the next phase starts, so an interrupted session loses nothing.
+
+Then, in this order:
+
+- 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, 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 branch that was decided.
+
+Never merge, and never push. Merging the work back is the user's job.
+
+**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** 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 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
+
+`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 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.
+
+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:
+
+- Its focus, and to check the work against what was asked.
+- Which files to read: `spec/SPEC.md`, `plan/PLAN.md`, the phase files written so far, and the principles file.
+- That the plan's principles check records deviations as approved exceptions, not as findings.
+- How to see the changes: name the commit the work started from, so it can diff against that, and point at the working tree when nothing is committed.
+
+Each reviewer returns a verdict with concrete findings, each pointing at a file and a line.
+
+Then, yourself:
+
+- Merge the findings, and remove the duplicates.
+- Dismiss what you judge wrong, and say why in the report.
+- Fix the rest 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, 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
+
+`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.
+Point the gate at the artifact the phase produced, where one exists, so the user reads it and answers in the same place.
+
+On "carry on": start the next phase in this session.
+On "stop": end the run with the report below.
+A later run finds from disk where this one stopped, resumes at the next unfinished phase, and pauses only at the pauses ahead of it.
+
+A pause after the last phase has nothing to carry on to.
+Run the final checkpoint, and give the end-of-run report instead of asking.
+
+## 4. Stop and ask
+
+Stop and ask when one of these three holds. Otherwise keep going on your own.
+
+1. **The work deviates significantly from the spec.**
+   - What you build contradicts `spec/SPEC.md`.
+   - A fact you found makes the approved shape no longer fit.
+   - The solution departs noticeably from an approved solution sketch.
+
+2. **A blocker only the user can resolve.**
+   - A scope or design decision with no single right answer.
+   - An action that is destructive or hard to reverse: a data migration, a deletion, a call to an external service.
+   - Missing access only the user can grant.
+
+3. **The run cannot carry on for technical reasons.**
+   - A verify step that still fails after a real attempt to fix it.
+   - A tool the plan needs, and your environment refuses to give.
+
+For the third one, declare a gate saying what the plan asks for and why you cannot do it here.
+Offer stopping and carrying on without it, and say plainly that the report will name what never happened.
+
+**Everything else is yours to settle**: a review finding, a wording call, an unclear task, which of two fixes reads better.
+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. 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.
+
+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 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.
+- 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