chamba 0.8.0 → 0.10.0

package/templates/webterm/public/app/main.js

@@ -35,8 +35,9 @@
 //   pane-shape.js   the shape a pane has beside one session, and the store that keeps one for each
 //   pane.js         the Pages tool: the chips bar and the page
 //   tool-host.js    a tool's frame, and the credentials the shell hands into it
-//   specs-host.js   the Specs tool: which tool it is, and its panel
-//   reviews-host.js the Code Reviews tool, the same way
+//   home-host.js    the Home tool: which tool it is, and its panel
+//   specs-host.js   the Specs tool, the same way
+//   reviews-host.js the Code Reviews tool, the same way again
 //   pane-frame.js   a published page in a sandboxed frame, and the answer that comes back out of it
 //   pane-arrival.js which page an incoming list opens by itself, and when none of them does
 //   status-strip.js the attached session's model, context, quota meters and version, above the composer
@@ -72,6 +73,7 @@ import "./dom.js";
 import "./palette.js";
 import "./drafts.js";
 import "./frames.js";
+import "./home-host.js";
 import "./new-session.js";
 import "./note.js";
 import "./pane.js";

package/templates/webterm/public/app/pane-shape.js

@@ -15,12 +15,14 @@ export const PANE_KEY = "webterm-pane";
 
 // The tools there are to open, which a shape holds one of. Their ids and nothing else about them: what a tool
 // is made of is the pane's business, and all this module asks is whether a stored id is one of them.
+export const HOME = "home";
 export const PAGES = "pages";
 export const SPECS = "specs";
 export const REVIEWS = "reviews";
-const SHAPE_TOOLS = [PAGES, SPECS, REVIEWS];
-// The tool a session opens on.
-const DEFAULT_TOOL = PAGES;
+const SHAPE_TOOLS = [HOME, PAGES, SPECS, REVIEWS];
+// The tool a session opens on. Home, because it is the reading of the repository a session starts in, and
+// because a stored shape naming another tool keeps that tool: this is what a session with no shape gets.
+const DEFAULT_TOOL = HOME;
 
 // Narrower than this and the pane is not a pane any more, so it becomes the spine instead. The mock's
 // threshold, and the width the spine itself takes.

package/templates/webterm/public/app/pane-shell.js

@@ -1,7 +1,7 @@
 // pane-shell.js - the pane itself: which tool is open in it, and how wide it is.
 //
-// The pane is furniture. What sits in it are tools - Pages (pane.js), Specs (specs-host.js) and Code Reviews
-// (reviews-host.js) - and the line between them is the whole point of this module: a tool draws inside its
+// The pane is furniture. What sits in it are tools - Home (home-host.js), Specs (specs-host.js), Code Reviews
+// (reviews-host.js) and Pages (pane.js) - and the line between them is the whole point of this module: a tool draws inside its
 // own panel and nothing else, while the tab bar that says which tool is open, and the controls that say how
 // wide the pane is, are drawn out here. A tool can therefore never move the pane, and never lie about which
 // tool the user is looking at.
@@ -31,6 +31,7 @@ import {
     paneHalf,
     spine,
     spineBadge,
+    toolHome,
     toolPages,
     toolReviews,
     toolSpecs,
@@ -40,6 +41,7 @@ import {
     DEFAULT_FRACTION,
     defaultShape,
     draggedTo,
+    HOME,
     isDefaultWidth,
     mergeShape,
     PAGES,
@@ -52,14 +54,17 @@ import {
 
 // The tools' ids come from the shape, which holds one of them. Re-exported here because this module is the
 // pane, and a tool that asks whether it is open is asking the pane rather than the store.
-export { PAGES, REVIEWS, SPECS };
+export { HOME, PAGES, REVIEWS, SPECS };
 
 // The tools, in the order their tabs are drawn. A tool is a tab, a panel, and a render function it hands over
 // when it loads; the pane knows nothing else about any of them.
 const TOOLS = [
-    { id: PAGES, label: "Pages", panel: toolPages },
+    { id: HOME, label: "Home", panel: toolHome },
     { id: SPECS, label: "Specs", panel: toolSpecs },
-    { id: REVIEWS, label: "Code Reviews", panel: toolReviews },
+    // "Reviews" on the tab and Code Reviews everywhere else: four tabs have to be readable at the width the
+    // pane reopens at, and the tab is the one place the tool's whole name does not fit.
+    { id: REVIEWS, label: "Reviews", panel: toolReviews },
+    { id: PAGES, label: "Pages", panel: toolPages },
 ];
 
 // The one shape this window is drawing, and the session it belongs to. One and not a map of them: the store
@@ -213,6 +218,14 @@ function drawTabs() {
             badge.className = mark.counted ? "tool-mark" : "tool-mark dot";
             if (mark.counted) badge.textContent = String(mark.unread);
             else badge.setAttribute("aria-label", "something new");
+            // The ring, for a tool something landed in a moment ago. This element is new on every redraw, so
+            // the ring would start from the beginning each time; a negative delay of what has already run
+            // puts it back where it was.
+            const ring = pulsing.get(tool.id);
+            if (ring) {
+                badge.classList.add("pulse");
+                badge.style.setProperty("--ring-delay", `-${Date.now() - ring.at}ms`);
+            }
             button.append(badge);
         }
         button.addEventListener("click", () => showTool(tool.id));
@@ -337,6 +350,33 @@ export function flashPane() {
     arrivalTimer = setTimeout(() => pane.classList.remove("arriving"), ARRIVAL_MS);
 }
 
+// Three turns of the ring in styles.css, which runs for 1.6s each. The two numbers have to agree: the
+// keyframes are there and what takes the ring off again is here.
+const TAB_PULSE_MS = 4_800;
+
+// id -> when that tool's ring started, and the timer that ends it. A tab is rebuilt on every redraw, so the
+// ring cannot be left on the element the way the pane's own flash is - what holds it is this map.
+const pulsing = new Map();
+
+/**
+ * Something landed in a tool the user is not looking at, so its tab draws a ring around its mark for three
+ * turns and then rests.
+ *
+ * A second arrival during those three turns starts them again, which is what the mark means: the tab says
+ * that something arrived just now, and the number beside it says how much is waiting.
+ */
+export function pulseTool(id) {
+    clearTimeout(pulsing.get(id)?.timer);
+    pulsing.set(id, {
+        at: Date.now(),
+        timer: setTimeout(() => {
+            pulsing.delete(id);
+            renderShell();
+        }, TAB_PULSE_MS),
+    });
+    renderShell();
+}
+
 // --- The divider -------------------------------------------------------------------------------------------------------------------------
 
 // Dragging sets a pixel width until it stops making sense, and below the threshold the pane becomes the

package/templates/webterm/public/app/pane.js

@@ -34,6 +34,7 @@ import {
     isToolOpen,
     noteTool,
     PAGES,
+    pulseTool,
     registerTool,
     rememberPageSize,
     setPaneCollapsed,
@@ -91,7 +92,10 @@ export function applyPages(msg) {
     // saying-so is held back while another tool has the pane.
     if (arrived !== null) {
         select(msg.sid, arrived.id, { user: false });
+        // The pane switches tools for nobody. With Pages open the pane's own edge says the page is here;
+        // with another tool open the Pages tab says it, and the tool the user is working in is left alone.
         if (isToolOpen(PAGES)) flashPane();
+        else pulseTool(PAGES);
     }
     // A pane someone put away comes back for a page, in the session the page was published in - which is
     // the session this frame is about, since the list only reaches the tool for the one it is driving.
@@ -264,8 +268,10 @@ function render() {
     // because a pane that only appears once an agent has used it is one nobody knows to ask for. What the
     // empty pane says is the tool's own intro; the tab's mark is the shell's, from what the tool says here.
     const bare = pages.length === 0 && !entry?.notice;
-    // A page that arrived is a thing to look at, not a thing to answer, so the tab says so without a number.
-    noteTool(PAGES, { unread, empty: bare, counted: false });
+    // How many pages nobody has opened, the way Specs counts its open asks. Three waiting is a different day
+    // from one, and the pages already read are not a number anyone acts on, so the tab counts the unopened
+    // ones alone and never the whole list.
+    noteTool(PAGES, { unread, empty: bare, counted: true });
 
     chips.replaceChildren(...pages.map((page) => chipFor(sid, page, page.id === entry?.selected)));
     const at = pages.findIndex((page) => page.id === entry?.selected);

package/templates/webterm/public/app/reviews-host.js

@@ -2,6 +2,10 @@
 //
 // As the Specs host beside it: the tool's own name, its panel and its opening sentence, and the frame around
 // them is `tool-host.js`.
+//
+// "Reviews" and not "Code Reviews", because this word is what the user reads on the tab and in the panel
+// while the tool opens, and four tabs have to fit at the width the pane reopens at. The tool's own name is
+// Code Reviews everywhere else, the server table included, so every refusal still names it in full.
 
 import { toolReviews } from "./dom.js";
 import { REVIEWS } from "./pane-shell.js";
@@ -9,7 +13,7 @@ import { createToolHost } from "./tool-host.js";
 
 createToolHost({
     id: REVIEWS,
-    label: "Code Reviews",
+    label: "Reviews",
     panel: toolReviews,
     opening: "Opening the reviews in this repository.",
 });

package/templates/webterm/public/app/state.js

@@ -17,6 +17,9 @@ export let workspaceName = "";
 // the screen: the panel marks this, so "nothing picked" stays tellable from "picked the colour the port
 // would have given anyway".
 export let workspaceColorId = "";
+// Whether the host is holding itself awake for this container. A fact about the machine the container runs
+// on, which the server reads off a file the host writes; nothing in here can see it any other way.
+export let hostAwake = false;
 // Where "+ New session" starts an agent, relative to the workspace root ("" is the root itself). The server
 // owns it - it follows the directory chamba was last run in - and the picker opens on it.
 export let defaultCwd = "";
@@ -31,6 +34,7 @@ export function adoptSessionsFrame(msg) {
     if (Array.isArray(msg.agents)) agents = msg.agents;
     workspaceName = msg.workspace || "";
     workspaceColorId = typeof msg.color === "string" ? msg.color : "";
+    hostAwake = msg.awake === true;
     defaultCwd = msg.defaultCwd ?? "";
 }
 

package/templates/webterm/public/app/tabs.js

@@ -15,7 +15,7 @@ import { closeCard, stopCard } from "./cards.js";
 import { sendFrame } from "./connection.js";
 import { SVG_NS, tabbar } from "./dom.js";
 import { repositionNewPop, toggleNewPop } from "./new-session.js";
-import { agents, attachedSid, defaultAgent, defaultCwd, maxSessions, sessions, workspaceName } from "./state.js";
+import { agents, attachedSid, defaultAgent, defaultCwd, hostAwake, maxSessions, sessions, workspaceName } from "./state.js";
 import { focusTerminal, term } from "./terminal.js";
 import { colorFor } from "./theme.js";
 import { repositionColorPop, workspaceColorButton } from "./workspace-color.js";
@@ -444,6 +444,37 @@ function stopButton() {
     return button;
 }
 
+// The host is holding itself awake for this container. A sign and not a button: there is nothing here for a
+// window to change - the setting is the machine's, and it is changed in the chamba menu on the host.
+function awakeIcon() {
+    const sign = document.createElement("span");
+    sign.id = "awakeicon";
+    sign.title = "The host stays awake while this container is up";
+    sign.setAttribute("role", "img");
+    sign.setAttribute("aria-label", "The host stays awake while this container is up");
+    const svg = document.createElementNS(SVG_NS, "svg");
+    svg.setAttribute("viewBox", "0 0 24 24");
+    svg.setAttribute("width", "14");
+    svg.setAttribute("height", "14");
+    svg.setAttribute("fill", "none");
+    svg.setAttribute("stroke", "currentColor");
+    svg.setAttribute("stroke-width", "2");
+    svg.setAttribute("stroke-linecap", "round");
+    // A sun: a small circle with eight rays, drawn as one dashed ring outside it so the rays cost one node.
+    const core = document.createElementNS(SVG_NS, "circle");
+    core.setAttribute("cx", "12");
+    core.setAttribute("cy", "12");
+    core.setAttribute("r", "4");
+    const rays = document.createElementNS(SVG_NS, "circle");
+    rays.setAttribute("cx", "12");
+    rays.setAttribute("cy", "12");
+    rays.setAttribute("r", "9");
+    rays.setAttribute("stroke-dasharray", "0.1 6.97");
+    svg.append(core, rays);
+    sign.append(svg);
+    return sign;
+}
+
 function chevronIcon() {
     const svg = document.createElementNS(SVG_NS, "svg");
     svg.setAttribute("viewBox", "0 0 24 24");
@@ -514,8 +545,11 @@ export function renderBar() {
         ws.textContent = workspaceName;
         right.append(ws);
     }
-    // The colour first: it is about this window's identity rather than about what the window does, so it sits
-    // next to the name it belongs with, on the far side of the bell from the button that ends everything.
+    // The awake sign first, before the buttons: it is the one thing here nobody presses, and it says
+    // something about the machine this container runs on rather than about this window or this session.
+    if (hostAwake) right.append(awakeIcon());
+    // The colour next: it is about this window's identity rather than about what the window does, so it sits
+    // at the near end of the buttons, on the far side of the bell from the one that ends everything.
     right.append(workspaceColorButton(), bellButton(), stopButton());
     tabbar.append(right);
 

package/templates/webterm/public/app/tool-host.js

@@ -47,6 +47,17 @@ export function toolsMovedToSession() {
     for (const host of hosts.values()) host.session();
 }
 
+// Whether the bell in the bar is on. It rides in the session message, so a tool that makes a sound obeys the one
+// control this window has rather than a mute of its own. Held here rather than read out of `alerts.js`, so the flow
+// is one way: the bell says it moved, and every frame hears it in the message it already reads.
+let toolSound = true;
+
+/** The bell moved. Every frame hears the new preference in its next session message, which is sent now. */
+export function toolsHearSound(on) {
+    toolSound = on;
+    toolsMovedToSession();
+}
+
 /**
  * Put one tool on the page.
  *
@@ -174,17 +185,22 @@ export function createToolHost({ id, label, panel, opening }) {
     }
 
     /**
-     * Tell one frame which session this window is driving, and how that session reads. `null` says there is none.
+     * Tell one frame which session this window is driving, how that session reads, and whether this window
+     * makes a sound. `null` says there is no session.
      *
      * The theme rides with the session because it belongs to it: the frame has an opaque origin and no storage
-     * of its own, so what it was set to last is the pane's to keep and the pane's to hand back.
+     * of its own, so what it was set to last is the pane's to keep and the pane's to hand back. The sound
+     * preference rides in the same message because it reaches a frame the same way and moves the same way.
      */
     function sendSession(target) {
         const sid = attachedSid ?? null;
         // Both fields say the same session or neither does: the pane is drawn in the session it opened with
         // before the first frame names one, and handing the frame that session's palette beside "there is no
         // session" would have it read in a theme it was never told the reason for.
-        target?.contentWindow?.postMessage({ t: named(SESSION), sid, theme: sid === null ? null : storedPaneTheme() }, "*");
+        target?.contentWindow?.postMessage(
+            { t: named(SESSION), sid, theme: sid === null ? null : storedPaneTheme(), sound: toolSound },
+            "*",
+        );
     }
 
     /**

package/templates/webterm/public/app/workspace-color.js

@@ -75,7 +75,7 @@ function cell(id, hex, label, stored) {
     button.addEventListener("click", () => {
         panel.close();
         // Sent, never held: the server decides, and every window is told on the frame that comes back. A pick
-        // kept to send later would be undone by the next sessions frame anyway (FR-17).
+        // kept to send later would be undone by the next sessions frame anyway.
         sendFrame({ t: "color", color: id });
     });
     return button;

package/templates/webterm/public/index.html

@@ -65,9 +65,13 @@
                 </span>
             </div>
 
+            <!-- Home: the pulse of the repository this workspace holds, in a frame of its own. The tool a
+                 session with no stored shape opens on, so it is the one panel without `hidden`. -->
+            <div id="tool-home" class="tool-panel"></div>
+
             <!-- Pages: the pages this session's agent published, with the chips bar and the counter drawn out
                  here by the interface, and the page itself inside a sandboxed frame. -->
-            <div id="tool-pages" class="tool-panel">
+            <div id="tool-pages" class="tool-panel" hidden>
                 <div id="pagebar">
                     <button type="button" id="pane-prev" class="pane-nav" title="Older pages" aria-label="Older pages" hidden>&#8249;</button>
                     <div id="chips"></div>

package/templates/webterm/public/styles.css

@@ -760,6 +760,44 @@ body.dragging {
     font-weight: 700;
 }
 
+/* Something landed in a tool the user is not looking at: a ring around its mark, three times, then rest.
+   TAB_PULSE_MS in app/pane-shell.js must match three turns of this - it is what takes the class off again,
+   since a tab, unlike the pane, is rebuilt from one frame to the next. The delay is how far a rebuilt tab is
+   already into the ring, so a redraw in the middle of a pulse resumes it. */
+.tool-mark.pulse {
+    position: relative;
+}
+
+.tool-mark.pulse::after {
+    content: "";
+    position: absolute;
+    inset: -4px;
+    border: 2px solid var(--accent);
+    border-radius: 12px;
+    animation: toolMarkRing 1.6s ease-out 3;
+    animation-delay: var(--ring-delay, 0s);
+}
+
+@keyframes toolMarkRing {
+    from {
+        opacity: 0.9;
+        transform: scale(0.8);
+    }
+    to {
+        opacity: 0;
+        transform: scale(1.5);
+    }
+}
+
+/* The same moment, held instead of pulsed, the way the pane's own arrival highlight is. Without this the
+   ring would never appear at all for someone who asked for less movement. */
+@media (prefers-reduced-motion: reduce) {
+    .tool-mark.pulse::after {
+        opacity: 0.9;
+        animation: none;
+    }
+}
+
 /* A tool that counts nothing says only that something arrived, so its mark carries no number and is drawn
    as the dot it means. */
 .tool-mark.dot {
@@ -1329,6 +1367,19 @@ body.offline #wscolorpop {
     pointer-events: none;
 }
 
+/* ---- The host is being kept awake ---- */
+
+/* A sign rather than a control: no border, no hover, no pointer. It sits among buttons, so it has to read as
+   the one thing here that nothing happens to when it is pressed. */
+#awakeicon {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 4px;
+    color: var(--muted);
+    opacity: 0.75;
+}
+
 /* ---- Sound, and stopping the container ---- */
 
 /* Both sit at the far right of the bar, away from the tabs: neither one is about a single session. */
@@ -1493,6 +1544,20 @@ body.offline #wscolorpop {
 /* Border carries the state (no separate status dot): lit in the workspace's colour when you can type into the
    attached session, plain grey while this window is between sessions or reconnecting. A dropped connection is
    not a failure here - the session on the other side kept running - so it goes quiet rather than warning. */
+/* The ruler autoGrow() measures the text in: out of the flow, out of sight, and of no height of its own, so
+   its scroll height is the height of the text and nothing about it moves the composer. */
+#input-mirror {
+    position: absolute;
+    top: 0;
+    left: 0;
+    height: 0;
+    min-height: 0;
+    overflow: hidden;
+    visibility: hidden;
+    pointer-events: none;
+    resize: none;
+}
+
 #input.online {
     border-color: var(--ws);
     box-shadow: 0 0 0 1px color-mix(in srgb, var(--ws) 25%, transparent);

package/templates/webterm/server.js

@@ -18,11 +18,14 @@ import { join, resolve, sep } from "node:path";
 import express from "express";
 import { WebSocketServer } from "ws";
 import { cleanLine, cleanSubmission, createPaneStore, isPageId } from "./artifacts.js";
+import { isHostAwake } from "./awake.js";
 import { readColor, storeColor } from "./color.js";
 import {
     AGENT_ARGS,
     AGENT_STORES,
     AGENTS,
+    AWAKE_FILE,
+    AWAKE_STALE_MS,
     agentSpawnArgv,
     CHECK_INTERVAL_MS,
     CLIENT_PING_INTERVAL_MS,
@@ -171,6 +174,10 @@ function sessionAgent(raw) {
 // nothing was picked, and the browser works one out from the published port.
 let chosenColor = readColor(COLOR_FILE);
 
+// Whether the host is being kept awake for this container. A fact about the machine out there rather than
+// anything this server does, read off the marker on the status timer below and carried on the sessions frame.
+let hostAwake = isHostAwake(AWAKE_FILE, AWAKE_STALE_MS);
+
 // The one-line file that names the default agent, for the `webterm` launcher to read back. Written when the
 // port is bound and again whenever the default moves, so a second `webterm <agent>` can say what is live.
 function publishAgent() {
@@ -501,6 +508,9 @@ function broadcastSessions() {
             // The accent colour, on the one frame that already reaches every window: a change has to travel
             // to all of them either way, so this closes the door rather than adding a second one.
             color: chosenColor,
+            // The same reasoning as the colour: window-wide, true for every session in here at once, and
+            // already travelling to all of them, so it rides this frame rather than opening a second door.
+            awake: hostAwake,
             max: MAX_SESSIONS,
             defaultCwd: workspaceLabel(defaultCwd),
             list,
@@ -691,6 +701,16 @@ function sweepStatus() {
     }
 }
 
+// The marker read, on the same pass. Nothing in the container hears a write the host made to the mount, so
+// looking again is the whole mechanism - and a frame goes out only when the answer changed, because every
+// window already has the last one.
+function sweepAwake() {
+    const awake = isHostAwake(AWAKE_FILE, AWAKE_STALE_MS);
+    if (awake === hostAwake) return;
+    hostAwake = awake;
+    broadcastSessions();
+}
+
 // What the host asks before it offers to stop the container. `sessions` is how many conversations are
 // alive (they all die with the container), `attached` how many a window is watching right now, `agent` the
 // one a new session gets and `agents` what is actually running, per agent. Counts and names only - nothing
@@ -1485,7 +1505,10 @@ setInterval(() => pane.sweep(), PANE_SCAN_MS).unref();
 
 // The strip's scan, for the same reason: a snapshot file is written by a shell script into a bind mount, so
 // the only way to know it moved is to look.
-setInterval(() => sweepStatus(), STATUS_SCAN_MS).unref();
+setInterval(() => {
+    sweepStatus();
+    sweepAwake();
+}, STATUS_SCAN_MS).unref();
 
 // Keepalive pass. A window that stops answering is terminated, which releases the session it was
 // driving so the window that comes back can pick it up without a takeover prompt. Sessions themselves

package/templates/webterm/tool-document.js

@@ -46,8 +46,8 @@ export function withNonce(html, nonce) {
  *
  * `default-src 'none'` is the floor, so anything not named below is refused. What runs is named by the nonce
  * alone. What is fetched is named by `origin` - the scheme and host the document was loaded from - because
- * the client's own assets, the tool's data routes and the jailed workspace files are all served from here,
- * and an opaque origin has no `'self'` to say that with. `base-uri` and `form-action` are named on their own,
+ * the client's own assets, its images and its clips, the tool's data routes and the jailed workspace files
+ * are all served from here, and an opaque origin has no `'self'` to say that with. `base-uri` and `form-action` are named on their own,
  * since neither one falls back to `default-src`.
  */
 export function documentPolicy(nonce, origin) {
@@ -56,6 +56,7 @@ export function documentPolicy(nonce, origin) {
         `script-src 'nonce-${nonce}'`,
         `style-src-elem 'nonce-${nonce}'`,
         `img-src ${origin}`,
+        `media-src ${origin}`,
         `connect-src ${origin}`,
         `frame-src ${origin}`,
         "base-uri 'none'",

package/templates/webterm/tools/home.js

@@ -0,0 +1,80 @@
+// =========================================================================================================================================
+// tools/home.js - What the Home tool is, as one table.
+//
+// The smallest table of the three, and the shape of a tool that only reads. There are no verbs, because Home has no helper and nothing
+// to say to an agent; no events, because it delivers nothing into a session; and no raw side, because it serves no file of the
+// workspace at all. What is left is three reads of the repository the workspace holds.
+//
+// The module is handed two directories rather than one: the workspace, which is the repository it draws, and the state directory
+// outside it, which is where its cache goes. The cache is derived from the repository and is nobody's record, so a file of it in the
+// workspace would show up in the `git status` of every repository Home opens. The module refuses a cache directory inside the
+// workspace, so the two can never be the same place.
+// =========================================================================================================================================
+
+import { createHomeModule, refuseRaw, statusFor } from "../../pane-apps/server/home.mjs";
+import {
+    HOME_CACHE_DIR,
+    HOME_KEY,
+    HOME_RAW_TOKEN,
+    MAX_HOME_BYTES,
+    REVIEWS_ROOT,
+    SPECS_ROOT,
+    WORKSPACE,
+    WORKSPACE_ROOT,
+} from "../config.js";
+
+// The module maker, re-exported so the path to the built dist is written once, as it is for every tool.
+export { createHomeModule };
+
+export const HOME_TABLE = {
+    id: "home",
+    /** What a refusal calls the tool. The word on the tab is the client's own, in `tool-host.js`. */
+    label: "Home",
+    key: HOME_KEY,
+    rawToken: HOME_RAW_TOKEN,
+    statusFor,
+
+    /**
+     * The repository this draws, the directory outside it that the cache goes in, the name to call it, and the two directories the
+     * other tools keep their work in.
+     *
+     * The name is chamba's own for this workspace, which is what the bar wears, so the header row of the page and the corner of the
+     * window say the same word. Without it the header would show the mount point, which is "workspace" in every container there is.
+     *
+     * The two roots are the ones the Specs tool and the Code Reviews tool are mounted with, and Home leaves what is inside them out of
+     * every count of lines and of files, with a switch on the page to put them back. Both tools write what they serve - a spec's forms
+     * and answers, a review's grouping and its baseline blobs - and counted as code they say a workspace is mostly JSON. They come from
+     * here rather than from inside Home for the same reason each tool takes its own root here: a repository that keeps either one
+     * elsewhere is served the same way, and Home holds no word about what they are called.
+     */
+    create: () =>
+        createHomeModule({
+            root: WORKSPACE_ROOT,
+            cacheDir: HOME_CACHE_DIR,
+            name: WORKSPACE,
+            toolPaths: [SPECS_ROOT, REVIEWS_ROOT],
+        }),
+
+    /** Home delivers nothing into a session, so there is no sentence for one to arrive as. */
+    events: {},
+
+    /**
+     * How much a request may carry. Every route is a GET with no body, so nothing reaches this; it is here because the door that
+     * gates a body reads it for every tool, and a tool with no number is a tool with no gate.
+     */
+    limits: { bytes: MAX_HOME_BYTES },
+
+    /** Home serves no workspace bytes at all, so every path is refused rather than resolved. */
+    raw: (_module, path) => refuseRaw(path),
+
+    // The three reads, each one a section of the page. Three and not one: each costs what its own question costs, and the page draws
+    // each section the moment that section's answer lands.
+    routes: (module) => ({
+        history: { GET: () => module.history() },
+        branches: { GET: () => module.branches() },
+        tree: { GET: () => module.tree() },
+    }),
+
+    /** No verbs. The helper door is registered for every tool and answers 400 for every name it is given. */
+    verbs: () => ({}),
+};

package/templates/webterm/tools/index.js

@@ -5,15 +5,16 @@
 // types and how much of the typing channel one session gets. server.js reads the list and never a tool's name, so a third tool is
 // a row here and a table beside it.
 //
-// The order is the order the tabs are drawn in, which is the pane's own list in `public/app/pane-shell.js`. The two lists are
-// checked against each other by the interface's tests rather than derived from one another, because the pane is drawn in the
-// browser and this file is read in the server.
+// The order is the order the tabs are drawn in, which is the pane's own list in `public/app/pane-shell.js`, less Pages: the
+// interface draws that one itself and it has no table here. The two lists are checked against each other by the interface's tests
+// rather than derived from one another, because the pane is drawn in the browser and this file is read in the server.
 // =========================================================================================================================================
 
+import { HOME_TABLE } from "./home.js";
 import { REVIEWS_TABLE } from "./reviews.js";
 import { SPECS_TABLE } from "./specs.js";
 
-export const TOOLS = [SPECS_TABLE, REVIEWS_TABLE];
+export const TOOLS = [HOME_TABLE, SPECS_TABLE, REVIEWS_TABLE];
 
 /** The table of one tool, or undefined. Asked with `find`, so a name that is not a tool's is not one. */
 export function toolTable(id) {

package/templates/webterm/tools/reviews.js

@@ -4,8 +4,9 @@
 // The same shape as the Specs table beside it, and the differences are the tool's own. A review is a directory with a slug, so its
 // routes name their subject in the path rather than in a query, and the acts of the screen are one route with the act as a segment.
 // Its raw files are two named locations rather than any workspace file, so a browser reaches a stored blob and a signature and
-// nothing else. And it is the one module in this container that runs a child process, which is why it is handed the workspace as
-// well as its own root: every git call it makes runs with the repository as its working directory.
+// nothing else. And it is one of the two modules in this container that run a child process, Home being the other, which is why it
+// is handed the workspace as well as its own root: every git call it makes runs with the repository as its working directory. The
+// runner itself is shared, in the pane-apps server library, and this module hands it a closed table of read-only operations of its own.
 //
 // The framed sentences are the three acts that keep the review with the reviewer. Sending feedback, syncing and filing a review all
 // hand it over, and each of those types the review's command instead: the act starts the agent, and the skill reads the review's
@@ -111,7 +112,7 @@ export const REVIEWS_TABLE = {
         "review/:slug/blob": {
             GET: ({ params, query }) => module.blobLines(params.slug, field(query.name), count(query.from), count(query.count)),
         },
-        // One route for every act of FR-22 to FR-49. The module holds the list of them and refuses a name that is not one, so what
+        // One route for every act of a review. The module holds the list of them and refuses a name that is not one, so what
         // an act is stays in one place rather than being a row here as well.
         "review/:slug/:act": { POST: ({ params, body }) => module.act(params.slug, params.act, body) },
     }),
@@ -125,6 +126,9 @@ export const REVIEWS_TABLE = {
         // A review filed from the terminal, which the tab shows with a note saying so.
         start: (_entry, payload) => module.start(payload, "terminal"),
         metadata: (entry, payload) => module.metadata(entry, payload),
+        // One group at a time, which several workers may post at once without treading on one another.
+        group: (entry, payload) => module.group(entry, payload),
+        ungroup: (entry, payload) => module.ungroup(entry, payload),
         reply: (entry, payload) => module.reply(entry, payload),
         activity: (entry, payload) => module.activity(entry, payload),
         done: (entry) => module.done(entry),