chamba 0.8.0 → 0.9.0

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

@@ -60,11 +60,25 @@ 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>
+echo '{"verdict":"holds, one for you","findings":6,"judgments":1}' | specs review <spec>
 ```
 
+The number and the source are the tool's own.
+It reads where the work stands when the round lands, decides which review the round belongs to - the spec's own review, the checkpoint the run is at, or the execution with no place, which is where a round posted at no checkpoint lands - and numbers the round within that review, so the spec's round 1 and a checkpoint's round 1 are two rounds.
+Carry a `round` in the payload for one purpose only: to replace a round of the same review that you posted before, which is how a round is corrected.
+
 A phase's id is its file's name without the extension, which is what you already write and tick.
 
+**A phase report names a phase the plan holds, and the tool refuses one that does not.**
+The refusal names the phases the plan does hold, so a report the tool would not take says in its own words what to do.
+Where the plan changed while the run was going - a phase renamed, split in two, or added - post the whole phase list first, in plan order, and report the phase after that:
+
+```
+echo '{"kind":"plan","phases":[{"phase":"phase-01-the-state","title":"The state"},{"phase":"phase-02-the-rail","title":"The rail"}]}' | specs post <spec>
+```
+
+The list is the plan's own: a phase it drops leaves the board, and a phase that survives keeps the status it had, so a finished phase is never set back to waiting.
+
 ## The run does not stop on its own
 
 The `pauses` decision is the only thing that stops this run for the user.
@@ -203,7 +217,7 @@ The user then knows from the start where this run stops and where it gets review
 - 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.
+- Each round in the state carries the review it belongs to. A chosen checkpoint whose phases are all done, and which no stored round names, has not run. Run it before you move on.
 
 **The commits.**
 `commits` is `per-phase`, `single` or `none`.
@@ -257,6 +271,10 @@ Every phase goes through the same steps, and you carry out every one yourself.
 
 2. **Build.** Keep the changes scoped to this phase, and tick each task as it completes.
 
+   Write the rule in the comment's own words.
+   Never name a requirement id, a phase or a spec in a comment.
+   The user can delete the spec directory, and a comment that names it then points at nothing.
+
 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`.
@@ -351,6 +369,7 @@ Then, yourself:
 - 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.
+Post it before you report the next phase as running: the tool reads where the run stands to work out which review a round belongs to, so a round that lands after the next phase has started belongs to the execution and to no checkpoint.
 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**.
@@ -366,7 +385,7 @@ 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.
+On "stop": end the turn with the message of **section 6**, and write no report file - the run has not reached its end.
 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.
@@ -409,24 +428,70 @@ 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 write the run report to `<root>/<spec>/run-report.md`.
+**Section 6** holds its title, its headings and what goes under each one.
+Write it here, before the closing commit, so the commit carries it.
+A later run of the same spec writes the file again, over the report of the run before it.
+A run that stops before its end writes no report at all: the message of **section 6** is the whole of what such a run gives.
+
 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.
+This one commit covers the phase files, the ticked plan, the spec the run kept true, the report 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.
+Then give the message of section 6, which is what ends the turn and says what the closing commit did.
 
 ## 6. Report
 
-This report is what ends a turn.
+A run that reaches its end has two homes for its report, and they hold the same run.
+A run that stops before its end has one: the message.
+
+`run-report.md` at the top of the spec directory is the whole of the report.
+The closing step of section 5 writes it, the Specs tab lists it beside the other artifacts and renders it, and it stays with the work for whoever reads the spec later.
+It is written at the end of the run and nowhere else, so a pause and a stop condition write no file at all.
+
+The message in this terminal is the short form.
+It is what ends the turn, and the user reads it now rather than later.
+
+### The file
+
+Write it as Markdown, with this title and these headings, in this order:
+
+```markdown
+# <spec name> - run report
+
+## Bottom line
+
+## Must know
+
+## The details
+```
+
+The title names the spec.
+The title and the three headings are fixed word for word.
+Nothing else about the report is fixed.
+The text under each heading is yours to write, so two reports share the headings and differ in their words alone.
+
+- **Bottom line**: a few sentences on what landed, and whether the run is complete.
+- **Must know**: the decisions that carry weight, the departures from the plan and from the mocks, and the critical issues a checkpoint found.
+  Write this section only where the run holds something the user must know.
+  Where it holds none, leave the heading out, and never write the section to fill it.
+- **The details**: the phases finished and the overall progress, every checkpoint with what it found, what was fixed and what was dismissed with the reason, what you settled on your own, the branch and the commits of the run, and the commit mode.
+  Say that the report rides in the closing commit, or, with `"commits": "none"`, that it sits uncommitted in the tree.
+
+Bottom line and The details are in every report.
+
+### The message
+
+The message 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:
+Say it in normal message text:
 
 - 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.
@@ -435,3 +500,4 @@ Report in a normal message:
 - 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.
+- Where the run reached its end, that `run-report.md` in the spec directory holds the whole of the report.

package/templates/startup.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // =============================================================================
-// startup.mjs -- Container startup: AI CLI updates + readiness checks
+// startup.mjs -- Container startup: agent CLI updates + readiness checks
 // Baked into the container image at /home/devuser/startup.mjs
 // Must run as root (npm global install requires root).
 // Must use only Node.js built-ins -- no external packages available in container.
@@ -45,15 +45,15 @@ const fail = (label, detail) => {
 };
 // Non-fatal notice: always prints (even in summary), but does NOT increment errors, so it never aborts
 // the session. Used for things the user should know about but that must not block connecting (e.g. a
-// transient AI CLI update failure -- the existing versions still work).
+// transient agent CLI update failure -- the existing versions still work).
 const warn = (label, detail) => console.log(`${yellow("!")} ${label.padEnd(24)}${detail ? yellow(detail) : ""}`);
 const section = summary ? () => {} : (title) => console.log(`\n${bold(title)}`);
 
 // -- Header -------------------------------------------------------------------
 if (!summary) console.log(`\n${bold("chamba - Sandbox for AI Agents")}\n`);
 
-// -- AI CLI update (requires root - skipped when run via 'status' alias as devuser) -
-section("AI CLI update");
+// -- Agent CLI update (requires root - skipped when run via 'status' alias as devuser) -
+section("Agent CLI update");
 
 const isRoot = process.getuid?.() === 0;
 const TIMESTAMP_FILE = "/home/devuser/.ai-cli-updated";
@@ -148,7 +148,7 @@ const doUpdate = (label) =>
         child.on("error", (err) => {
             finish(() => {
                 printIndented(String(err?.message ?? err));
-                warn("AI CLIs", "update failed -- continuing with existing versions");
+                warn("agent CLIs", "update failed -- continuing with existing versions");
             });
         });
         child.on("close", (code) => {
@@ -156,10 +156,10 @@ const doUpdate = (label) =>
                 if (code === 0) {
                     printIndented(out);
                     writeFileSync(TIMESTAMP_FILE, `${new Date().toISOString()}\n`);
-                    ok("AI CLIs", "updated");
+                    ok("agent CLIs", "updated");
                 } else {
                     printIndented(`${out}${errOut}`);
-                    warn("AI CLIs", "update failed -- continuing with existing versions");
+                    warn("agent CLIs", "update failed -- continuing with existing versions");
                 }
             });
         });
@@ -176,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... SPACE to skip, ENTER to update now`)}`;
+        const line = (s) => `\r\x1b[K${blue("●")} ${dim(`Updating agent CLIs in ${s}s... SPACE to skip, ENTER to update now`)}`;
         const cleanup = () => {
             clearInterval(tick);
             clearTimeout(timer);
@@ -218,19 +218,19 @@ const promptSkipUpdate = (seconds) =>
     });
 
 if (Number.isFinite(lastUpdate) && Date.now() - lastUpdate < THROTTLE_MS) {
-    ok("AI CLIs", "up to date");
+    ok("agent CLIs", "up to date");
 } else if (!isRoot) {
-    skip("AI CLIs", "update skipped (requires root)");
+    skip("agent CLIs", "update skipped (requires root)");
 } else {
     // About to show update activity (the skip prompt and/or install/update output). In summary mode that is the
     // first thing after the host's "Starting dev container...", so add a blank line to separate it.
     if (summary) console.log("");
     if (!timestampFileExists) {
-        await doUpdate("Installing AI CLIs...");
+        await doUpdate("Installing agent CLIs...");
     } else if (await promptSkipUpdate(5)) {
-        skip("AI CLIs", "update skipped by user");
+        skip("agent CLIs", "update skipped by user");
     } else {
-        await doUpdate("Updating AI CLIs to latest...");
+        await doUpdate("Updating agent CLIs to latest...");
     }
 }
 

package/templates/tool-helper.sh

@@ -38,7 +38,7 @@ Verbs:
   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 }
+  review   <spec>        Post a round of review. { verdict, findings, judgments }, and { round } to replace one already posted
   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.
@@ -53,7 +53,9 @@ 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 }
+  metadata <review>      Post the whole grouping and its notes, replacing what is there. { fingerprint, groups, notes }
+  group    <review>      Add or replace one group, and the notes on its hunks. { fingerprint, group, notes }
+  ungroup  <review>      Remove one group; the notes on its hunks stay. { fingerprint, id }
   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.

package/templates/webterm/README.md

@@ -61,7 +61,14 @@ That is why a session showing as working never also shows as waiting for you.
 - **A tab flashes and then stays lit** when its agent finishes. Every ending, whoever is watching: it costs nothing to say a thing twice on screen, and one rule for every session is easier to trust than one for the tab you have open and another for the rest. Touching the session, or arriving at it, is what puts it out.
 - **A tab takes its session's colour and grows a small page** beside its age when a page is published into that session's pane while you are looking at another one, and flashes once as it arrives. It holds until you get to that session, where the newest page opens itself; anything older that piled up behind it keeps its chip badge, so the tab marks itself again - without a second flash - once you leave. Its own state, not the one above: that one is an agent finishing, and this one is a page waiting to be read.
 - **The browser tab speaks too**, because that is all a window behind something else can do. The title counts the sessions waiting for you, and the favicon carries one mark: a white bar across its bottom edge, with a lit segment moving along it, while an agent is working, and a green dot in its top corner - pulsing until you go and look - when one is waiting. Two shapes at opposite ends of the icon rather than two colours in one place, because at 16px a hue is the first thing to go. White for working because every hue here belongs to a workspace or a session, and the frame around the icon is one of them.
+- **And it goes grey when the window cannot reach the container.** Three seconds after the socket drops - long enough that a wifi blip or a closed lid passes without it - the spark and the frame drain to one flat grey, both marks go, and nothing in the icon moves again until the socket is back.
+  The title drops its count with them and keeps the workspace name alone.
+  Everything else the tab says comes from the last frame the server sent, and while the socket is down that frame only gets older, so a green dot would call you back to a session this window can no longer see.
+  The icon is the same grey for every kind of disconnect: a container that is stopped, a key that is spent, and a container that has gone.
+  It says whether this window can reach the container, not why - the curtain on the page is where the reason is.
 - **And ten seconds later it says so out loud** - one soft chime, once, for an ending nobody came back to. A sound cannot be taken back and it reaches you in the next room, so it is the one thing here that asks whether you were there. Several sessions finishing together are one chime, and so are two windows open on the same container. The bell beside the power button mutes it, and remembers.
+  A grey tab is a silent one: a finish that comes due while the icon is grey is spent without a sound, and the reconnect does not play it late.
+  By then the chime would be calling you to a session this window could not see when the finish came due, and a sound is the one thing here that cannot be taken back.
 
 Whether you were there is answered by whether that session gets touched - a keystroke, a click, a scroll - in the ten seconds after it finishes, not by whether the browser had focus.
 Focus was the first answer and the wrong one: it varies by browser and platform, it has to be re-reported on every reconnect, and every hole in it fails towards silence, which is the one direction a notification must not fail in.
@@ -110,7 +117,8 @@ webterm is baked into the chamba image with its dependencies preinstalled, and t
    The agent is always explicit; `webterm` on its own prints usage and the URL, and never picks one for you.
    The choice is written to `~/.chamba-webterm/agent`, and the host reads it back at the next container start - so it holds across restarts.
    chamba bind-mounts that directory from the workspace cache, and three files live in it: `agent`, the resume stamp `resumed-at`, and `color`, which holds the workspace colour.
-   A rebuild replaces the container and leaves all three where they are.
+   Home's cache directory `.home/` sits beside them, for the same reason: what outlives the container goes here.
+   A rebuild replaces the container and leaves all of it where it is.
 
 The first session after a container start reopens the most recent conversation; later sessions start fresh.
 The server decides that itself, in `resume.js`, by reading the same agent stores the pane reads - the host is not involved and plants nothing.
@@ -123,20 +131,32 @@ Sessions already open keep running the agent they were started with.
 
 ## The web pane
 
-Beside the terminal is a pane, and the pane holds tools. **Pages** is the first of them: the pages this session's agent published - a plan, a table, a diagram, a question with more structure than a terminal prompt can hold. **Specs** and **Code Reviews** sit beside it, and each has a section of its own below.
+Beside the terminal is a pane, and the pane holds tools. **Home** is the first of them, and the tool a pane with no shape of its own opens on: the pulse of the workspace repository, read from git. **Pages** is the interface's own: the pages this session's agent published - a plan, a table, a diagram, a question with more structure than a terminal prompt can hold. **Specs** and **Code Reviews** sit beside them, and Home, Specs and Code Reviews each have a section of their own below.
 
-- **The pane's own chrome.** One tab per tool, drawn as a flat label with a line under the open one in the workspace's own colour, and the width controls beside them. Everything in that bar is the pane's, never a tool's, so no tool can resize the pane or say which tool you are looking at - the same reason the chips bar is drawn outside the page it lists. Width has three states and only one of them is a width: the divider drags anything between the two ends, full width takes the whole row and squeezes the terminal out, and collapse folds the pane into the vertical "Web pane" spine. Between those two buttons is a third for half the window, which is the width the pane opens at - half itself rather than the pixels half came to, so the pane stays at half when the window is resized, and the button is lit exactly while it is there. The grip stays on the screen in every one of them, so dragging it is always the way back, and a second press of the full-width button is the other. The spine carries what every tool is waiting on, whichever tool is open. The pane's shape belongs to the session it is beside - which tool is open, how wide it is, which of the three states it is in, how big a page is drawn and which palette the reading is in - so switching sessions gives each one the pane it was left with, and a reload gives them all back. A session nobody has shaped opens at half the window, on Pages, whether or not the agent has published anything yet. The browser keeps this, one shape per session, and a session that leaves the bar takes its shape with it.
+- **The pane's own chrome.** One tab per tool, drawn as a flat label with a line under the open one in the workspace's own colour, and the width controls beside them. Everything in that bar is the pane's, never a tool's, so no tool can resize the pane or say which tool you are looking at - the same reason the chips bar is drawn outside the page it lists. Width has three states and only one of them is a width: the divider drags anything between the two ends, full width takes the whole row and squeezes the terminal out, and collapse folds the pane into the vertical "Web pane" spine. Between those two buttons is a third for half the window, which is the width the pane opens at - half itself rather than the pixels half came to, so the pane stays at half when the window is resized, and the button is lit exactly while it is there. The grip stays on the screen in every one of them, so dragging it is always the way back, and a second press of the full-width button is the other. The spine carries what every tool is waiting on, whichever tool is open. The pane's shape belongs to the session it is beside - which tool is open, how wide it is, which of the three states it is in, how big a page is drawn and which palette the reading is in - so switching sessions gives each one the pane it was left with, and a reload gives them all back. A session nobody has shaped opens at half the window, on Home. The browser keeps this, one shape per session, and a session that leaves the bar takes its shape with it.
 - **Publishing.** `webpane <file.html> [--title "..."]` inside a session, from an agent or by hand. Anything in the session's process tree may publish: the helper sends only its own pid, and the server walks up the process tree to a session it started, so no caller ever names a directory.
 - **The files.** `~/.webpane/<conversation-id>/<NN>-<slug>.html`, bind-mounted from the host workspace cache. A page is a plain standalone HTML file, and a file copied into the directory by hand shows up in the pane within a second or two, exactly like a published one.
 - **Per conversation, not per session.** The directory is named after the agent's own conversation id, so resuming a conversation - after a container restart, or by hand with `claude --resume <id>` - opens with its pages again. A session whose agent has not written its id down yet publishes into a `pending-...` directory, which is renamed the moment the id appears. Two live sessions never share a directory: a conversation already open elsewhere is refused, and the second session gets its own empty pane with a notice.
 - **Feedback.** A page may carry `<form data-feedback>`. Submitting it writes `~/.webpane/<conversation-id>/feedback/<page>-<epoch-ms>.json` - `{ page, submittedAt, fields, text }`, where a field named `text` becomes the free-text box - and types one line into the agent's terminal saying where to read it. An agent that has already exited still gets the file; only the line is skipped.
-- **What you see.** The pane is beside the terminal from the start, open at half the window in a session that has published nothing - a pane that only appears once an agent has used it is one nobody knows to ask for. The empty pane says what it is for and gives three things to say to get a page. Once there are pages, the history is the chips bar above them: one chip per page with its title and age, newest at the end. A page that arrives opens itself and pulses the pane's edge once, and takes nothing else: the caret stays where it was mid-sentence, so you keep typing and click into the page when you want it. "Arrives" is the server's own unread flag rather than "new to this window", so a reload opens nothing that was already read, and a page waiting in a session you have not visited still opens when you get there. A pane you put away comes back for it, at no less than a readable width - the one place this interface overrides a choice you made. A pane a session was never put away in is open already, so nothing has to arrive for it to be there. A page published in a session you are *not* looking at changes nothing where you are: its tab takes that session's colour and a small page beside its age, flashes once, and holds until you get there. A page that lands while the pane is open on another tool changes nothing on the screen either: it is selected, ready for when you come back, and the number on the Pages tab is what says so. The minus and plus beside the counter step the shown page through five text sizes, 80% to 150% with 100% the default, and nothing reloads on a press, so a scroll position and a half-filled form both survive it. That control is the browser's own furniture: the size is applied from outside the frame, no page has to account for it, and nothing an agent reads mentions it. The collapse button in the pane's own bar puts the pane away into the spine, which reopens on a click, and dragging the divider past the collapse threshold does the same. Reopening gives back the width the pane had, but never less than a third of the window - a pane that comes back as a sliver may as well have stayed shut. The width, the collapse, the text size and the open tool belong to the session, the way the pages, the selection and the badges do, so switching sessions gives each one the pane it was left with.
+- **What you see.** The pane is beside the terminal from the start, open at half the window in a session that has published nothing - a pane that only appears once an agent has used it is one nobody knows to ask for. The empty pane says what it is for and gives three things to say to get a page. Once there are pages, the history is the chips bar above them: one chip per page with its title and age, newest at the end. A page that arrives opens itself and pulses the pane's edge once, and takes nothing else: the caret stays where it was mid-sentence, so you keep typing and click into the page when you want it. "Arrives" is the server's own unread flag rather than "new to this window", so a reload opens nothing that was already read, and a page waiting in a session you have not visited still opens when you get there. A pane you put away comes back for it where Pages is the tool it was put away on, at no less than a readable width - the one place this interface overrides a choice you made. A pane put away on another tool stays away, and its Pages tab carries the page until you get there. A pane a session was never put away in is open already, so nothing has to arrive for it to be there. A page published in a session you are *not* looking at changes nothing where you are: its tab takes that session's colour and a small page beside its age, flashes once, and holds until you get there. A page that lands while the pane is open on another tool changes nothing on the screen either: it is selected, ready for when you come back, and the number on the Pages tab is what says so. The minus and plus beside the counter step the shown page through five text sizes, 80% to 150% with 100% the default, and nothing reloads on a press, so a scroll position and a half-filled form both survive it. That control is the browser's own furniture: the size is applied from outside the frame, no page has to account for it, and nothing an agent reads mentions it. The collapse button in the pane's own bar puts the pane away into the spine, which reopens on a click, and dragging the divider past the collapse threshold does the same. Reopening gives back the width the pane had, but never less than a third of the window - a pane that comes back as a sliver may as well have stayed shut. The width, the collapse, the text size and the open tool belong to the session, the way the pages, the selection and the badges do, so switching sessions gives each one the pane it was left with.
 - **How an agent comes to use it.** Two layers, so it happens without being asked each time. Every agent's injected context carries the standing rule - prefer a page when the answer is longer or more structured than a terminal reply carries well, and when a question has more options or structure than the agent's own question tooling holds - plus the palette to match and the form contract. Every agent also gets the craft in full - a standalone dark page, inline everything, how to ask with a form, and what a submitted form does and does not prove - through one channel: the `web-pane` skill, whose body is `templates/context/web-pane-craft.md` and whose description is the phrases a user actually says ("show me", "as a page", "in the pane", "publish"). All three read it that way, from the skills home their own CLI reads. The craft is long and it is needed on the turns that write a page, so it arrives when the skill loader shows its description and the model opens it, rather than in context on every turn. The standing rule above is what makes that safe: reaching for a page does not wait on the skill loading. The session greeting names the pane too, so a user who has never heard of it learns it exists in the first sentence.
 - **Nothing is deleted.** No removal by age, nothing removed when a session closes. Growth is bounded instead: a page over the per-page limit is refused, and once the whole directory reaches its total - in bytes or in number of files - new publishes are refused and what is there stays. Advanced > Clear agent memory in chamba is what clears it.
 
+## The Home tool
+
+**Home** is the pane's first tab, and the tool a session with no stored shape opens on.
+It reads the workspace repository through git and draws the pulse of it, so the first thing the pane shows is the work itself rather than an empty panel.
+
+- **What it serves.** The workspace as a repository, and nothing else. A directory that is no repository is a state Home draws - one plain line - rather than a failure, and so is a repository with no commit yet.
+- **The child process.** git, through the same shared runner Code Reviews uses, as a closed list of read-only operations of Home's own. A branch name never reaches a `--format=` string as text: where a branch is the subject, Home passes its object id.
+- **When it reads.** When its tab is first given a width, and when the user presses Refresh. Nothing watches the repository and nothing polls it, so a commit made in the terminal beside the tab shows on the next opening or the next refresh. The row says how long ago the page read the repository.
+- **The cache.** Derived numbers alone - a walk of the history and a verdict per branch - kept in `.home/` under the bind-mounted state directory. The module refuses a cache directory inside the workspace, because a file there would show up in the `git status` of every repository Home opens, and a file in the container would die with it.
+- **No door for the agent.** Three routes, each a GET the page calls: the history, the branches and the tree. No verb, no helper on PATH, no framed sentence and no workspace file served raw. Home is the one tool an agent cannot reach at all.
+- **The bee.** A bee crosses the page about once a minute, and a click on it plays one of two short clips and shows a quote. It is one animated image and two sound files, built into the Home client. Its sound is the bell in the bar: the pane hands that preference to every tool frame in the session message, so Home has no mute of its own. Under reduced motion the bee parks beside the header row and stays there.
+
 ## The Specs tool
 
-**Specs** is the pane's second tab, and the first thing in it that is not the interface's own: a separate application - its own client, its own server side - that webterm hosts rather than contains.
+**Specs** is the pane's second tab: a separate application - its own client, its own server side - that webterm hosts rather than contains, built and mounted the way Home is.
 It reads the specs the workspace holds, and it is where the spec workflow grows.
 
 - **Where it comes from.** The private `pane-apps` package builds one dist - a client per tool, and one bundled server module per tool - which chamba's build stages into its templates and the image bakes at `/usr/local/share/chamba/pane-apps/`, beside this directory. Nothing is installed for it: the module imports node builtins and nothing else.
@@ -148,7 +168,7 @@ It reads the specs the workspace holds, and it is where the spec workflow grows.
 - **Where a link goes.** A link inside a document is never followed by the frame, which has to stay the document the shell put in it. One inside the spec opens in place at the section it named; one out of the repository is asked of the shell, which opens it as a window of its own.
 - **Where a piece of work stands.** One `state.json` inside each spec's `.specs/`, written by the tool alone: the confirmed protocol stage by stage, the mode flags, what the agent is doing right now, what is waiting for the user, and the dated log. `README.md` beside it is rendered from that file every time it moves, so the board in the pane and the file in git are the same facts rather than two copies somebody keeps in step.
 - **Starting one.** `New spec` at the top of the rail is one form - a working name, one box for everything you have to say, and files by drop or paste. The name says what the work will be saved as as you type it, and one quiet line at the foot asks for imagination mode: a wish the agent shapes its recommendation around, and not a decision, because the steps are where the mode is confirmed. Sending it creates the directory, saves what you wrote as `intake.md`, starts the state file, and types the spec command with the fresh directory's name into the terminal - filing the form is the user's own act, so the line is the command the user would type. Each agent spells that command its own way, and the line is spelled for the session it goes to: `/dx-spec` for claude and for opencode, `$dx-spec` for codex. An agent that hears the idea in conversation files the same intake through the helper, and gets the same directory.
-- **Choosing the steps.** The agent reads the intake and posts a recommendation; the pane renders it as a form with every stage of the catalog in it, recommended or not, each with the agent's one line. One stage brings a question of its own, asked beside that stage and only while it is ticked: how wide to cast under research. Confirming writes the protocol into the state file in catalog order. Imagination mode is offered exactly when the run includes exploration or the mocks, and opens ticked where the intake asked for it, and `Ask the agent first` sends the question to the terminal instead of answering it here.
+- **Choosing the steps.** The agent reads the intake and posts a recommendation; the pane renders it as a form with every stage of the catalog in it, recommended or not, each with the agent's one line. One stage brings a question of its own, asked beside that stage and only while it is ticked: how wide to cast under research. Confirming writes the protocol into the state file in catalog order. Imagination mode is offered exactly when the run includes exploration or the mocks, and opens ticked where the intake asked for it, and `Ask` sends the question to the terminal instead of answering it here.
 - **Changing them later.** `change` beside the board's Protocol heading reopens the same form over what was confirmed. A stage that is done or running is locked, because a step already taken is not untaken by unticking a box; a stage still waiting can go. Confirming writes the amended protocol through the same act that wrote the first one - there is no second writer - and types one line into the terminal saying what moved, so the agent in the middle of the work hears about it. `Quality review` in the rail is that same act in one press, for the one change that is asked for most.
 - **The helper.** `specs <verb>` on PATH inside any session, gated the way `webpane` is - the key from the key file, the caller as its own pid, refused for a process that is not in a session. The verbs are `stages` (the catalog, as data rather than something an agent remembers), `state`, `intake`, `propose`, `recommend`, `await`, `withdraw`, `post`, `review` and `answers`. A payload is JSON on stdin and the answer is JSON on stdout. The agent moves the work only through these: nothing hand-edits the state file.
 - **Annotating.** Select text in a document, or point at an image or the artifact itself, and there are two actions and no others: say something about it, or ask for it to be removed. A removal is complete by pointing, so it joins the queue in the right pane at once. A comment is written where it is about, in a small box that opens at the point, and nothing joins the queue until it is submitted - an empty box leaves nothing behind. What is queued reads back as what was said, with the acts to change it, send it on its own or drop it, and nobody has been told until it is sent. The queue is the piece of work's own: it is kept in that work's `.specs/` directory, so it survives a page reload, a session that ends and a container that is rebuilt, and every window open on the same spec draws the same list. Nothing an agent reads has changed until a round is sent.
@@ -156,7 +176,7 @@ It reads the specs the workspace holds, and it is where the spec workflow grows.
 - **Setting the run up.** One form carries every decision that shapes a run: how the work is saved, which branch it lands on, where it stops for you, and who reviews it, with a panel of one focus per reviewer. A reviewer on that panel is a chip of plain text with a button to drop it, because a focus is a sentence and a field cannot show one whole. One box at the end of the panel is where a reviewer is written: Enter or its own `add` button puts what is in it on the panel and empties it, a box left with words in it becomes a reviewer at submit, and clicking a chip's words puts them back in that box, which is how a reviewer is changed. It opens on the agent's own recommendation, marked as such, and on the built-in defaults where there is none - and on the decisions the run started with, once it has started, because a second execute is the same run carrying on. Submitting records the decisions in the state file and only then types the command that starts the run, so the agent reads what you decided rather than what the last run did. A pause or a checkpoint naming a phase the plan no longer holds is marked, and the form waits for you to re-place it.
 - **One view for each session.** The pane is one frame for the whole window, and the window drives one session at a time, so what is open follows the session rather than the window: two pieces of work in two sessions are two readers. Moving between sessions gives each one back the spec it was reading, where it was, the answer form it was in the middle of, and the New-spec form with what was typed into it. The queued annotations are not on that list: the queue belongs to the piece of work rather than to the reader of it, so it is the same list in every session and in every window open on that spec. A window with no session shows the overview, because a screen whose send actions have nowhere to go is not worth keeping. The one exception is the session that starts from the tool's own offer: it arrives at a window that was driving none, and takes over the spec the reader was looking at when they asked for it.
 - **What the run asks you.** Three things, and one mechanism under all of them. A gate judges one artifact: it opens that artifact and stands under it, and it takes an approval or a change request with the words that say what to change. A round asks questions: each one carries its options, whether one answer or several are allowed, a marked recommendation, and a box of its own for anything the options missed. A decision card is one question of that same kind, plus a pointer to the passage it is about: it names the artifact and the section, the tab opens that artifact at that section and draws the card beneath it, and the ways out are the agent's own options rather than two fixed buttons - what was found and what each way costs are in the question's own words. Each of the three is one file the agent declared under the spec's `.specs/rounds/`, and answering writes the answer into that same file.
-- **Not answering yet.** Every one of the three offers two ways out that settle nothing. `Ask about this` sends what you typed to the terminal as a question and answers nothing: the ask stays on the list, the form stays open, and the agent's answer comes back beside it. `Later` closes the form and leaves the ask waiting, with what you wrote still in it when you open it again. Neither one writes anything into the round file, and neither one is a decision.
+- **Not answering yet.** Every one of the three offers two ways out that settle nothing. `Ask` sends what you typed to the terminal as a question and answers nothing: the ask stays on the list, the form stays open, and the agent's answer comes back beside it. `Later` closes the form and leaves the ask waiting, with what you wrote still in it when you open it again. Neither one writes anything into the round file, and neither one is a decision.
 - **Answering.** A round goes with whatever you answered: a question you left alone is written as unanswered rather than left out, so the agent can tell a "no" from a question you skipped. The first answer wins - two windows can be looking at one gate, and the second is told it was already answered instead of overwriting the first. The outcome becomes a dated line in the state file, the item stops waiting, and one framed line goes to the terminal naming the file the answer went into.
 - **What is waiting for you.** Everything the run is waiting on is a card in the right pane, each naming the artifact it is about and each opening it. They sit at the top of the board, above the protocol, the run and the review rounds: all of those are a record of what has happened, and that record grows for as long as the work runs, so anything under it leaves the pane. The count is on the Specs tab itself, so it is visible from Pages and from the collapsed spine, and it goes when the last item is answered.
 - **The board.** Under the protocol heading, one line per confirmed stage with a mark saying where it stands - green for done, the accent blue for running, muted for waiting. A stage's name is the way into what it produced: one artifact opens from the name itself, several fold out under it on a click and fold away on the next, and a stage that produced nothing is plain text. No list is drawn until it is asked for, because the same paths under stage after stage bury the shape of the work in its own filenames. What the agent is doing at this moment is under its own **Now** heading with a pulsing dot, which is the one line on the board that is not a record of what has happened. It is there while it is current, and the heading goes with it: an activity is over the moment anything else is posted, and one that nothing follows is held for half an hour, because a quiet step is still a step. So a run that ends mid-activity - a container rebuilt, a session closed - takes its line off the board by itself, and the board never says an agent is working when none is. Under **Execution**, once there is an execution plan, the phases and where each one stands; under **Review**, each round of quality review with its verdict and how many findings it made. A pause in the run is a gate like any other: the document explaining it opens, and the gate to carry on stands beside it.
@@ -164,16 +184,17 @@ It reads the specs the workspace holds, and it is where the spec workflow grows.
 
 ## The Code Reviews tool
 
-**Code Reviews** is the pane's third tab, built and mounted the same way Specs is, and it is the one tool that reads the repository itself.
+**Code Reviews** is the pane's third tab, built and mounted the same way Specs is, and it is the tool that reads the repository as a change.
 A review is a changeset the reviewer reads hunk by hunk, with the agent on the other side of it.
 
 - **What it serves.** One directory of the workspace, `WEBTERM_REVIEWS_ROOT`, which is `reviews/` unless it is set, and the workspace itself as the repository the reviews are of. Every git call runs with the repository as its working directory, and every diff the tool computes excludes the reviews root by pathspec, so a review is never a review of itself.
-- **The one child process.** git, and nothing else. It is run by an absolute path, with no shell, as a closed list of read-only operations with fixed arguments, and with limits on time and output. An argument outside the list is refused rather than passed on. The interface never writes to the workspace from a review: no checkout, no staging and no commit, so the commit at approval and a checkout from the "Different branch" banner are asked of the agent instead.
-- **What a review holds.** One directory each, under the reviews root, with the review's own files in a `.reviews/` inside it: the state, the baseline of the changeset with its raw diff and the blobs it needs, the reader's marks, the threads, the pending feedback, the agent's metadata and the approval. The tool is the single writer, every write is atomic, and `README.md` beside the state is rendered from it, so what the pane draws and what git holds are the same facts.
+- **The child process.** git, and nothing else, which is the one program Home runs too. It is run by an absolute path, with no shell, as a closed list of read-only operations with fixed arguments, and with limits on time and output. An argument outside the list is refused rather than passed on. The interface never writes to the workspace from a review: no checkout, no staging and no commit, so the commit at approval and a checkout from the "Different branch" banner are asked of the agent instead.
+- **What it shows.** A rail of the agent's groups on the left, one row each with what is left in it, and All groups as the last row. The group in view is a section in the middle, under a header that sticks to the top of the feed and holds the group's name, its counts, the agent's narrative and facts, the acts on the whole group, and four controls that walk the group hunk by hunk - the next unseen hunk, the next issue, the next attention note and the next unread reply. A hunk is a card of the diff, coloured by its own language, and the agent's notes are rows inside that diff, each one directly above the lines it is about. Under both columns runs one status bar with what is left of the review, the activity log and the way to approve.
+- **What a review holds.** One directory each, under the reviews root, with the review's own files in a `.reviews/` inside it: the state, the baseline of the changeset with its raw diff and the blobs it needs, the reader's marks, the threads the comments made, what the reader put aside, the pending feedback, where the reader has read to, the agent's metadata and the approval. The tool is the single writer, every write is atomic, and `README.md` beside the state is rendered from it, so what the pane draws and what git holds are the same facts.
 - **Live.** Every change under the root reaches every open window, coalesced per review: a recompute writes hundreds of files and a window that re-reads the review has no use for hundreds of events.
 - **In a frame of its own.** As Specs: an opaque origin, two scoped credentials of its own, and nothing of the shell reachable from inside - see Security below.
 - **What a browser may load from a review.** Two locations and no others: a stored blob, addressed by its own object name, and the signature image of an approval. Both come back through the tool's own reader, jailed like every other workspace byte. Nothing else under a review, and nothing of the repository, is served that way.
-- **The helper.** `reviews <verb>` on PATH inside any session, the same script as `specs` under its other name and gated the same way. The verbs are `stages`, `state`, `start`, `metadata`, `reply`, `activity`, `done` and `log`. Nothing in that list marks a hunk seen, closes a thread, approves, or changes the baseline of its own accord: those are the reviewer's acts, through the tab.
+- **The helper.** `reviews <verb>` on PATH inside any session, the same script as `specs` under its other name and gated the same way. The verbs are `stages`, `state`, `start`, `metadata`, `group`, `ungroup`, `reply`, `activity`, `done` and `log`. Nothing in that list marks a hunk seen, closes a thread, approves, or changes the baseline of its own accord: those are the reviewer's acts, through the tab.
 - **How an agent comes to use it.** The `dx-review` skill, shipped in the image and injected like every other skill. Every act that hands a review to the agent types that skill's command into the reviewer's session - `/dx-review` on claude and opencode, `$dx-review` on codex - and the skill reads the review's state to know which of its acts is being asked for. The three events that keep the review with the reviewer type a framed sentence instead, tagged `[reviews]`.
 
 ## The status strip
@@ -224,8 +245,8 @@ A window the account does not have takes its whole meter off the strip rather th
 
 ## Config
 
-`config.js` holds the knobs (port, agent list and default agent, key and key file, upload dir, size limit, cleanup age/interval, paste framing, resume stamp, state file, colour file, session limit, keepalive interval, stop timings, claude context file, workspace root and directory-scan limits, the pane's directory, limits, scan interval, feedback bounds and agent stores, the status strip's scan interval, the root and the two scoped credentials each pane tool is mounted with, and the bounds on a delivery, per tool).
-Env overrides: `WEBTERM_PORT`, `WEBTERM_CWD`, `WEBTERM_AGENT`, `WEBTERM_AGENT_ARGS`, `WEBTERM_KEY`, `WEBTERM_KEY_FILE`, `WEBTERM_RESUME_STAMP`, `WEBTERM_STATE_FILE`, `WEBTERM_COLOR_FILE`, `WEBTERM_MAX_SESSIONS`, `WEBTERM_PING_INTERVAL_MS`, `WEBTERM_WORKSPACE`, `WEBTERM_CONTEXT_FILE`, `WEBTERM_PANE_DIR`, `WEBTERM_MAX_PAGE_BYTES`, `WEBTERM_MAX_PANE_BYTES`, `WEBTERM_MAX_PANE_FILES`, `WEBTERM_PANE_SCAN_MS`, `WEBTERM_FEEDBACK_MIN_INTERVAL_MS`, `WEBTERM_MAX_FEEDBACK_PER_PAGE`, `WEBTERM_STATUS_SCAN_MS`, `WEBTERM_SUBMIT_DELAY_MS`, `WEBTERM_SPECS_ROOT`, `WEBTERM_SPECS_KEY`, `WEBTERM_SPECS_RAW_TOKEN`, `WEBTERM_MAX_SPECS_LINE_LENGTH`, `WEBTERM_SPECS_LINE_MIN_INTERVAL_MS`, `WEBTERM_MAX_SPECS_LINES_PER_SESSION`, `WEBTERM_SPECS_NEW_SESSION_DELAY_MS`, the same seven for the Code Reviews tool - `WEBTERM_REVIEWS_ROOT`, `WEBTERM_REVIEWS_KEY`, `WEBTERM_REVIEWS_RAW_TOKEN`, `WEBTERM_MAX_REVIEWS_LINE_LENGTH`, `WEBTERM_REVIEWS_LINE_MIN_INTERVAL_MS`, `WEBTERM_MAX_REVIEWS_LINES_PER_SESSION` and `WEBTERM_REVIEWS_NEW_SESSION_DELAY_MS` - and the four `WEBTERM_*_DIR` agent-store paths, plus `WEBTERM_PROC_ROOT`, which belongs to `proc.js` rather than to `config.js`.
+`config.js` holds the knobs (port, agent list and default agent, key and key file, upload dir, size limit, cleanup age/interval, paste framing, resume stamp, state file, colour file, session limit, keepalive interval, stop timings, claude context file, workspace root and directory-scan limits, the pane's directory, limits, scan interval, feedback bounds and agent stores, the status strip's scan interval, the root and the two scoped credentials each pane tool is mounted with, Home's cache directory, and the bounds on a delivery, per tool).
+Env overrides: `WEBTERM_PORT`, `WEBTERM_CWD`, `WEBTERM_AGENT`, `WEBTERM_AGENT_ARGS`, `WEBTERM_KEY`, `WEBTERM_KEY_FILE`, `WEBTERM_RESUME_STAMP`, `WEBTERM_STATE_FILE`, `WEBTERM_COLOR_FILE`, `WEBTERM_MAX_SESSIONS`, `WEBTERM_PING_INTERVAL_MS`, `WEBTERM_WORKSPACE`, `WEBTERM_CONTEXT_FILE`, `WEBTERM_PANE_DIR`, `WEBTERM_MAX_PAGE_BYTES`, `WEBTERM_MAX_PANE_BYTES`, `WEBTERM_MAX_PANE_FILES`, `WEBTERM_PANE_SCAN_MS`, `WEBTERM_FEEDBACK_MIN_INTERVAL_MS`, `WEBTERM_MAX_FEEDBACK_PER_PAGE`, `WEBTERM_STATUS_SCAN_MS`, `WEBTERM_SUBMIT_DELAY_MS`, `WEBTERM_SPECS_ROOT`, `WEBTERM_SPECS_KEY`, `WEBTERM_SPECS_RAW_TOKEN`, `WEBTERM_MAX_SPECS_LINE_LENGTH`, `WEBTERM_SPECS_LINE_MIN_INTERVAL_MS`, `WEBTERM_MAX_SPECS_LINES_PER_SESSION`, `WEBTERM_SPECS_NEW_SESSION_DELAY_MS`, the same seven for the Code Reviews tool - `WEBTERM_REVIEWS_ROOT`, `WEBTERM_REVIEWS_KEY`, `WEBTERM_REVIEWS_RAW_TOKEN`, `WEBTERM_MAX_REVIEWS_LINE_LENGTH`, `WEBTERM_REVIEWS_LINE_MIN_INTERVAL_MS`, `WEBTERM_MAX_REVIEWS_LINES_PER_SESSION` and `WEBTERM_REVIEWS_NEW_SESSION_DELAY_MS` - `WEBTERM_HOME_CACHE_DIR`, `WEBTERM_HOME_KEY` and `WEBTERM_HOME_RAW_TOKEN`, which are the whole of Home's own set, and the four `WEBTERM_*_DIR` agent-store paths, plus `WEBTERM_PROC_ROOT`, which belongs to `proc.js` rather than to `config.js`.
 `WEBTERM_KEY` pins the key instead of creating one, and each tool's two scoped credentials the same way, which is for tests and hand-run debugging - there is no way to turn any of those gates off.
 `WEBTERM_CWD` is where new sessions start, not where they must stay: the browser can name another directory per session, and `POST /cwd` moves the default.
 `WEBTERM_AGENT` is the same shape: the agent new sessions start with, which the browser can override per session and `POST /agent` moves. A value that is not one of the three falls back to the first, so nothing arbitrary can be spawned through it.

package/templates/webterm/config.js

@@ -149,6 +149,26 @@ export const MAX_REVIEWS_LINES_PER_SESSION = Number(process.env.WEBTERM_MAX_REVI
 // And the wait for a session this delivery had to start, which is about the agent CLI rather than the tool.
 export const REVIEWS_NEW_SESSION_DELAY_MS = Number(process.env.WEBTERM_REVIEWS_NEW_SESSION_DELAY_MS) || 3_000;
 
+// --- Home --------------------------------------------------------------------------------------------------------------------------------
+
+// Where the Home tool keeps what it worked out about the repository. Its numbers are all derived and belong
+// to nobody, so they are not the work: a file of them in the workspace would show up in the `git status` of
+// every repository Home opens, and a file of them in the container would die with it. This directory is bind-
+// mounted from the host workspace cache, beside STATE_FILE, so the cache outlives a rebuild. The module
+// refuses a directory inside the workspace, so the two can never be the same place.
+export const HOME_CACHE_DIR = process.env.WEBTERM_HOME_CACHE_DIR || "/home/devuser/.chamba-webterm";
+
+// This tool's own two credentials, made the same way and opening nothing of the other tools'. Home serves no
+// workspace file at all, so the raw token opens nothing; it is issued all the same, because the raw door is
+// registered for every tool and a tool with no token would be a tool with no door to refuse at.
+export const HOME_KEY = process.env.WEBTERM_HOME_KEY || randomBytes(16).toString("hex");
+export const HOME_RAW_TOKEN = process.env.WEBTERM_HOME_RAW_TOKEN || randomBytes(16).toString("hex");
+
+// The largest body a Home data route accepts. Every route is a GET with no body, so this is the size of the
+// nothing they carry; the door that gates a body reads it for every tool, and a tool with no number is a tool
+// with no gate.
+export const MAX_HOME_BYTES = 64 * 1024;
+
 // --- The status strip --------------------------------------------------------------------------------------------------------------------
 
 // How often a session's snapshot file is looked at again for the strip above the composer. A poll for the