chamba 0.6.1 → 0.7.0

package/templates/specs.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# specs - move a piece of work through the Specs tool in this session's web pane.
+# Baked into the image at /usr/local/share/chamba/specs.sh, on PATH as `specs`.
+#
+# The agent's half of the coordination channel. The pane writes a file and types one line into this terminal;
+# these verbs are how the work moves the other way. Everything they change is a file in the spec 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}"
+
+usage() {
+    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 }
+  propose  <spec>        Recommend a protocol. { stages: [{ id, recommended, why }], note }
+  await    <spec>        Declare a gate or a round. { id, kind, title, file, payload }
+  post     <spec>        Say what is happening. { kind: activity | stage | phase | 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
+}
+
+VERB="${1:-}"
+SPEC="${2:-}"
+
+case "$VERB" in
+    "" | -h | --help)
+        usage
+        exit 0
+        ;;
+esac
+
+if [ ! -r "$KEY_FILE" ]; then
+    echo "specs: the web interface is not running in this container, so there is no pane to tell." >&2
+    exit 1
+fi
+
+# A payload only where one was piped in. A verb that takes none is called with nothing on stdin, and waiting
+# for a terminal to close would hang the agent rather than answer it.
+PAYLOAD="null"
+if [ ! -t 0 ]; then
+    PIPED="$(cat)"
+    if [ -n "$PIPED" ]; then
+        PAYLOAD="$PIPED"
+    fi
+fi
+
+BODY_FILE="$(mktemp)"
+REQUEST_FILE="$(mktemp)"
+trap 'rm -f "$BODY_FILE" "$REQUEST_FILE"' EXIT
+
+# 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 "specs: jq is not in this container, and the request cannot be composed without it." >&2
+    exit 1
+fi
+
+if ! jq -n --arg verb "$VERB" --arg spec "$SPEC" --argjson payload "$PAYLOAD" \
+    '{ verb: $verb, spec: $spec, payload: $payload }' >"$REQUEST_FILE" 2>/dev/null; then
+    echo "specs: the payload on stdin is not JSON." >&2
+    exit 1
+fi
+
+# $$ 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 30 \
+        -X POST \
+        -H "Content-Type: application/json" \
+        -H "X-Webterm-Key: $(head -n 1 "$KEY_FILE")" \
+        -H "X-Specs-Pid: $$" \
+        --data-binary "@${REQUEST_FILE}" \
+        "http://127.0.0.1:${CONTAINER_PORT}${WEBTERM_SPECS_AGENT_PATH:-/specs/agent}" 2>/dev/null
+)" || {
+    echo "specs: 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 "specs: nothing was done - ${REASON}." >&2
+exit 1

package/templates/webterm/README.md

@@ -34,7 +34,7 @@ The page is mission control for the container: the tab bar at the top is every a
 - **A tab is named after what it runs** - `claude 3`, `codex 4` - so a bar with two agents in it reads without a legend. **Rename** by double-clicking the name, so a long-lived conversation reads by what it is about instead; the name shows in every window and clearing it brings the default back. Names last as long as the session; nothing is saved to disk.
 - **Drag a tab to reorder the bar.** The order is the registry's, not the window's, so it moves in every window at once, and the number in `claude 3` stays with the session rather than with the position. Mouse and trackpad only - this is the browser's own drag and drop, which touch does not fire.
 - **The composer belongs to the session you are in.** A half-written message stays with its conversation: switch tabs and the box holds the next session's draft, switch back and yours is as you left it, image attachments included. Ending a session throws its draft away with it. Drafts are per browser window - they survive a switch, a reload and a sleep, but they do not follow a session into another window, and nothing is saved to disk.
-- **One button asks for a page.** The fourth button in the composer, above Send, sends `Put your last answer in the web pane as a page.` in one click - the one message that would otherwise be typed again every day. It goes through the same paste path as anything typed, so the agent cannot tell the two apart, and it does nothing else: a half-written message stays in the box, the draft is kept, the caret does not move, and the sentence is not added to the Up-arrow history, which is what *you* typed. It is in every session whatever agent it runs, and it is unavailable exactly when Send is - with no connection, or with no session attached.
+- **One button asks for a page.** The fourth button in the composer, above Send, sends `Put your last answer on a page.` in one click - the one message that would otherwise be typed again every day. It goes through the same paste path as anything typed, so the agent cannot tell the two apart, and it does nothing else: a half-written message stays in the box, the draft is kept, the caret does not move, and the sentence is not added to the Up-arrow history, which is what *you* typed. It names no pane, because where a page belongs follows what the session is doing: a page made during spec work is an artifact of that work and is saved beside it, and anything else goes to Pages - the skills carry that rule. It is in every session whatever agent it runs, and it is unavailable exactly when Send is - with no connection, or with no session attached.
 - **Shift+Enter is a newline in both boxes.** It always was in the composer; in the terminal above it, Shift+Enter now sends the same ESC-then-Return that Alt+Enter does, which is what the agents read as "a newline, not send". A terminal has no Shift+Enter of its own - Enter is a carriage return whatever else is held - so this is a second key onto a sequence the agent already understands. Alt+Enter still works.
 - **Up recalls what you already sent.** From an empty composer, Up brings back the last message sent to that session and keeps stepping back; Down comes forward, and past the newest is the empty box you started from. Once a message is showing the arrows only step on from its first and last line, so they still move the caret around a long one, and typing anything ends the walk. What is stored is what the agent actually received, image tokens already expanded, so sending a recalled message again means the same thing. History is per session and per browser window, it holds what went through the composer rather than what was typed straight into the terminal, and it goes when the session does.
 - **One window drives a session at a time**, because a PTY has one size and two drivers would fight over it. Opening a session another window is watching offers to switch it to this one; the window that loses it can take it back.
@@ -107,16 +107,41 @@ Sessions already open keep running the agent they were started with.
 
 ## The web pane
 
-Beside the terminal, each session has a pane of pages the agent published - a plan, a table, a diagram, a question with more structure than a terminal prompt can hold.
+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** sits beside it, and has a section of its own below.
 
+- **The pane's own chrome.** One tab per tool, 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. 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. Which tool is open, how wide it is and which of the three states it is in all belong to the window and survive a reload.
 - **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, as the vertical "Web pane" spine in a session that has published nothing - a pane that only appeared once an agent had used it was one nobody knew to ask for. Opening that 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 nobody has touched yet opens the same way, since collapsed has three answers (yes, no, and nobody has said) and only a click or a drag makes it one of the first two. 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. Drag the divider to set the width. 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 button at the end of the chips bar puts the pane away into the vertical "Web pane" spine, which carries the unread count and 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 and the text size belong to the window and survive switching tabs; the pages, the selection and the badges belong to the session and switch with it.
+- **What you see.** The pane is beside the terminal from the start, as the vertical "Web pane" spine in a session that has published nothing - a pane that only appeared once an agent had used it was one nobody knew to ask for. Opening that 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 nobody has touched yet opens the same way, since collapsed has three answers (yes, no, and nobody has said) and only a click or a drag makes it one of the first two. 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 and the text size belong to the window and survive switching tabs; the pages, the selection and the badges belong to the session and switch with it.
 - **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 - from one file, `templates/context/web-pane-craft.md`: claude reads it as the body of a `web-pane` skill, whose description is the phrases a user actually says ("show me", "as a page", "in the pane", "publish"), and codex and opencode read it as a section of the `AGENTS.md` chamba writes them, since a skill is a Claude Code mechanism and neither has one. The frontmatter and the title are claude's alone; the advice is written once. 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 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.
+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.
+- **How it is mounted.** `specs.js` is the mount. It hands the module the directory to serve and an `onChange`, registers its answers behind gates the module does not hold itself, and turns its changes into socket frames - the same shape the pane store is mounted with. There is no second process and no second port. A failure inside the module is one request answered with a status: every terminal in the container carries on, and the tab recovers on the next thing you do.
+- **What it serves.** One directory of the workspace, `WEBTERM_SPECS_ROOT`, which is `specs/` unless it is set. The directory is a mount parameter rather than a name inside the tool, so the tool serves whatever a repository calls its specs.
+- **Live.** Every change under that root reaches every open window, not one: a spec belongs to the repository rather than to a session, so two windows reading the same spec both hear it.
+- **In a frame of its own.** The client is not part of this page. It is loaded into an iframe with an opaque origin, and what it may ask the server for is decided by two scoped credentials the shell hands in - see Security below.
+- **What it shows.** Three panes: the specs and their artifacts on the left, one artifact read as one continuous document in the middle, and the state of the work on the right. A section carries a read mark, and a section that changed since it was read says so. A page or a diagram beside a spec renders in a frame of the jailed route, an image renders as an image, and anything else is named rather than drawn.
+- **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` in the navigator is one form - a working name, one box for everything you have to say, and files by drop or paste. Sending it creates the directory, saves what you wrote as `intake.md`, starts the state file, and tells the agent. 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. 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 `Ask the agent first` sends the question to the terminal instead of answering it here.
+- **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`, `await`, `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. Each one joins a queue in the right pane, where it can be written, edited or dropped, and nothing is on disk and nobody has been told until it is sent. A request to remove something is complete by pointing; a comment with nothing written in it does not go.
+- **Telling the agent.** Sending writes one round into the spec's own `.specs/user-feedback.json` and then types one line into the terminal beside the pane, naming the file rather than carrying what is in it. The line goes to the session that window is driving - the tool names no session, and there is none for it to name. With no session running, the tool asks first, and starts one only if you say so; the line then waits a moment for the agent to be there to read it. `Continue this spec` is the same channel with no file: it asks the session to pick the spec up.
+- **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 carries what was found and what each way costs, and its two answers are apply it and dismiss it. 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.
+- **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. 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 run.** Once there is an execution plan, the board draws its phases and where each one stands, and 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.
+- **How an agent comes to use it.** The `dx-spec` family of skills, shipped in the image and injected like every other skill: `/dx-spec` builds a spec, `/dx-spec-execute` runs its plan, and `/dx-spec-config` keeps the settings and principles beside them. They carry the craft alone - how to interview, what goes in a spec, how to review it, how to run a plan - and they ask through the tab, because the forms are the product's half. None of them starts a flow in a terminal with no web session: they say how to open one and stop, since there is one flow and it needs the tab.
+
 ## The status strip
 
 Between the terminal and the composer, a claude session shows its own numbers, live: the model and its effort, the context it is holding against the window it fits in, what is left of each rate-limit window - the five-hour one and the seven-day one, tagged `5h` and `7d` - with the time until each recharges, and the installed Claude Code version.
@@ -145,6 +170,17 @@ A window the account does not have takes its whole meter off the strip rather th
 - **A page bigger than a page is never read whole.** Anything can write into the pane directory, so a file there is not held to the publish limit. Listing a page reads only the first few kilobytes, looking for its title, and serving one is refused outright past the per-page limit - one huge file cannot stall the interface for every session in the container. The conversation-id discovery reads its stores the same way.
 - **Pages are read without leaving the pane directory.** Keys and filenames are checked against a narrow pattern before they become a path, symlinks and anything that is not a regular file are refused rather than followed, and the resolved path is checked to still be inside the root. A file over the per-page limit is refused rather than read into memory.
 - **Feedback is bounded and bound.** The body has a size limit, a page accepts one submission per second and only so many in its life (past that the page is refused, and no line is typed into the agent's terminal - answers are small, so a byte limit alone would let a page in a loop drive an agent for days), the answers count against the directory's total and its file count like pages do (past either, they are refused, and nothing is removed), and the directory, the page and the filename all come from the artifact the pane is showing - the request body contributes nothing but the answers, which are themselves limited in count and length. The line typed into the agent's terminal is built only from text the server controls: a title reduced to a single clean line, and a path the server generated.
+- **The Specs tool never holds this interface's key.** Its client renders in a frame with `sandbox="allow-scripts allow-forms"` and no `allow-same-origin`, exactly like a published page, so it has an opaque origin and nothing of the shell - the DOM, storage, the URL the key is in - is reachable from inside it. It gets two credentials of its own instead, both made fresh at server start and neither one the master key: a Specs key that opens the tool's data routes, presented as a header, and a raw-route token that opens workspace files, carried as a path segment because a frame and an image send no headers. Neither opens any other route, and presenting either one to anything else is refused. So one bug in spec rendering leaks spec reading at worst, never the key that types into terminals.
+- **The key is handed over once, and never on request.** The shell posts it into the frame on the load of the document it put there, unprompted. A frame's window object survives a navigation, so a document that navigated itself in would ask with the same identity as the one that was loaded; a second load is therefore read as a navigation, and the frame is thrown away and built again rather than handed anything.
+- **A workspace file is served jailed, whatever it is.** Every answer from the raw route carries `Content-Security-Policy: sandbox allow-scripts allow-forms` and `X-Content-Type-Options: nosniff`, on every media type and on refusals too - a list of scriptable types would be one enumeration away from being wrong. The route is frame-and-subresource only: the jail's second mechanism is the sandbox of whatever embeds the file, and a top-level document has no embedder, so a request that says it is one is refused - and so is a request that will not say, since reading silence as "not a document" would hand the refusal to whoever leaves the header off. The cost of that is a browser with no Fetch Metadata, where workspace files do not render at all.
+- **No other origin may read a workspace file.** A jailed document can read its own URL, and that URL carries the raw token; if the files that token opens were readable across origins, one bad render would be every spec in the repository, posted anywhere. So nothing on that route says anything may be read - a frame and an image need no permission - and what the tool itself reads as text comes back through the data routes instead, where a header is what opens it.
+- **Only the Specs data routes answer a cross-origin preflight.** The tool's key is a header, which is what makes its requests ask permission first; nothing else on this origin gives that permission. The tool's own client and assets are served open and readable, which is a plain GET rather than an answer to a preflight, and they hold nothing secret and drive nothing. They do carry `frame-ancestors 'self'`, so a page elsewhere cannot frame a tool's document without the sandbox this interface puts around it.
+- **A workspace document is walked before it is put on the page.** Markdown from the workspace is rendered, and then every node of what came out is walked, element by element and attribute by attribute, against written-out lists: anything not on them is removed, and a URL is decided by parsing it rather than by matching its text. What survives is moved into the page node by node, so no HTML string exists after the walk - a serialize-and-reparse is the shape most sanitizer bypasses take, and there is not one here. See `packages/pane-apps/src/lib/sanitize.ts`.
+- **A tool's own document names no origin in what decides execution.** It is served ahead of the open statics, under a policy of its own: `default-src 'none'`, a per-response nonce for its one script and its one stylesheet, and the origin it was loaded from named only where bytes are fetched. `'self'` is not usable here and would not be safe if it were - the document has an opaque origin, where `'self'` matches nothing, and this origin also serves workspace bytes through the raw route, so a host source in `script-src` would be a way to load a workspace file as code. This is the second mechanism over workspace markdown, and it is tested against the same payload list the walk is. See `tool-document.js`.
+- **A delivery is a pointer and a sentence the server owns.** What the tool sends is a kind of event, one line of detail, and a file it wrote. The sentence is picked from a table in `server.js` by that event key, so a tool chooses which of a few sentences is typed and never what it says. The path has to resolve to one of the tool's own files - inside a `.specs/`, or one of the two artifacts the tool renders into a spec directory, `intake.md` and `README.md` - or the line names none. The detail is the one part that came from somewhere else, and it is reduced before it reaches a terminal: everything that is not a visible character becomes a space, invisible padding and tag characters are dropped, and the quote characters that would close the frame become plain ones. So a document read in the pane cannot write a line that reads as a second voice, and cannot hide a tail behind the width of the row. See `typed-line.js`.
+- **A delivery is bounded, and refuses out loud.** The detail has a length limit checked on the text as it arrived, so an over-limit message is refused with a reason rather than cut into half a sentence. A session takes one delivery per second and only so many for as long as the container runs - a tool in a loop would otherwise drive an agent for days at one line a second. Every refusal is a sentence the tool shows the reader, so nothing is quietly dropped.
+- **The helper's door is not the pane's.** `POST /specs/agent` takes the master key like every other helper route, and the caller has to be a process inside a session, found by walking up the process tree from the pid it sends. It takes no session name from the caller - a name would be a value the server has to trust, and everything in this container could send one. The Specs key opens the pane's data routes and not this door, and this door opens none of those.
+- **A delivery cannot choose a terminal.** The message rides the window's own socket and the server resolves the session from it, exactly as the pane's own routes do. Two locks stand in front of that: the shell forwards a delivery only from the frame's own window, and only when it carries the Specs key, so a workspace document nested inside the tool has neither, and one that navigated the frame has the window and not the key.
 - **The key gate confines the browser, not the container.** `/tmp/webterm.key` is readable by `devuser`, because the `webpane` helper has to read it, and everything in the container is `devuser`. So a script an agent writes can do anything a browser window can: attach to another session, type into it, publish into its pane. That is the same boundary the container has always had - one agent session can already reach another's files - and it is why the isolation that matters is the container's, not the key's.
 - Runs as the non-root `devuser`; the agent inherits the same sandbox and auth it has in the terminal.
 
@@ -154,9 +190,9 @@ 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, 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, and the status strip's scan interval).
-Env overrides: `WEBTERM_PORT`, `WEBTERM_CWD`, `WEBTERM_AGENT`, `WEBTERM_AGENT_ARGS`, `WEBTERM_KEY`, `WEBTERM_KEY_FILE`, `WEBTERM_RESUME_STAMP`, `WEBTERM_STATE_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`, 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, which is for tests and hand-run debugging - there is no way to turn the gate off.
+`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, 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, where the pane's tools sit with the root and the two scoped credentials the Specs tool is mounted with, and the bounds on a delivery).
+Env overrides: `WEBTERM_PORT`, `WEBTERM_CWD`, `WEBTERM_AGENT`, `WEBTERM_AGENT_ARGS`, `WEBTERM_KEY`, `WEBTERM_KEY_FILE`, `WEBTERM_RESUME_STAMP`, `WEBTERM_STATE_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`, 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 the two `WEBTERM_SPECS_*` credentials the same way, which is for tests and hand-run debugging - there is no way to turn any of the three 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.
 `WEBTERM_AGENT_ARGS` belongs to `WEBTERM_AGENT` alone - it comes from the same launcher run - so any other agent is spawned bare.

package/templates/webterm/config.js

@@ -75,6 +75,49 @@ export const MAX_PANE_FILES = Number(process.env.WEBTERM_MAX_PANE_FILES) || 5_00
 // every host.
 export const PANE_SCAN_MS = Number(process.env.WEBTERM_PANE_SCAN_MS) || 1_500;
 
+// --- The Specs tool ----------------------------------------------------------------------------------------------------------------------
+//
+// The first of the pane's tools. Its client and its server module are built from the pane-apps package and
+// baked beside webterm, so this side names where they sit, what they are pointed at, and the two scoped
+// credentials that open them.
+
+// Where the built tool clients and server modules sit: a sibling of this directory, which is true both of the
+// image's bake and of a checkout, where chamba's build stages the same dist.
+export const PANE_APPS_DIR = join(import.meta.dirname, "..", "pane-apps");
+export const PANE_APPS_CLIENT_DIR = join(PANE_APPS_DIR, "client");
+
+// The directory of specs the tool serves. A mount parameter rather than a name inside the tool, so a
+// repository is served whatever it calls its specs directory.
+export const SPECS_ROOT = process.env.WEBTERM_SPECS_ROOT || join(WORKSPACE_ROOT, "specs");
+
+// The two scoped credentials, fresh every time this server starts, like the master key and for the same
+// reason: nothing has to store them, and one never outlives the process that issued it. The key opens the
+// data routes and travels in a header; the token opens workspace files and rides as a path segment, because a
+// frame and an image send no headers. Neither opens any other route, and neither is the master key.
+// The env overrides exist for tests and hand-run debugging, exactly as WEBTERM_KEY does.
+export const SPECS_KEY = process.env.WEBTERM_SPECS_KEY || randomBytes(16).toString("hex");
+export const SPECS_RAW_TOKEN = process.env.WEBTERM_SPECS_RAW_TOKEN || randomBytes(16).toString("hex");
+
+// The largest body a Specs data route accepts. A round of feedback carries its images inside it, which is
+// what makes this a file size rather than a form size; the tool writes those images out as real files.
+export const MAX_SPECS_BYTES = 64 * 1024 * 1024;
+
+// What a Specs delivery may be - one line typed into the agent's terminal saying that something arrived and
+// where to read it. The three bounds mirror the pane's feedback limits and are here for the same reasons.
+//
+// The length is of the source text, checked before the line is reduced, so an over-limit message is refused
+// with a reason rather than cut into half a sentence. The gap is what a person delivering things looks like:
+// anything faster is a stuck button or a script. And the total is what the gap alone cannot stop - a tool in
+// a loop would otherwise drive an agent for days at one line a second, so a session accepts only so many
+// deliveries for as long as this container runs.
+export const MAX_SPECS_LINE_LENGTH = Number(process.env.WEBTERM_MAX_SPECS_LINE_LENGTH) || 600;
+export const SPECS_LINE_MIN_INTERVAL_MS = Number(process.env.WEBTERM_SPECS_LINE_MIN_INTERVAL_MS) || 1_000;
+export const MAX_SPECS_LINES_PER_SESSION = Number(process.env.WEBTERM_MAX_SPECS_LINES_PER_SESSION) || 500;
+
+// How long a delivery waits when it had to start the session it is for. An agent CLI takes a moment to draw
+// its prompt, and a paste that arrives before it does is read by the terminal rather than by the agent.
+export const SPECS_NEW_SESSION_DELAY_MS = Number(process.env.WEBTERM_SPECS_NEW_SESSION_DELAY_MS) || 3_000;
+
 // --- The status strip --------------------------------------------------------------------------------------------------------------------
 
 // How often a session's snapshot file is looked at again for the strip above the composer. A poll for the

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

@@ -161,7 +161,10 @@ sendBtn.addEventListener("click", send);
 // draft is not dropped, the Up-arrow history is what you typed and does not gain this, and the terminal is not
 // given the focus. Preventing the default on mousedown is what keeps the caret where it was: a button takes the
 // focus when it is clicked, and this one has no use for it.
-const PANE_REQUEST = "Put your last answer in the web pane as a page.";
+// It names no pane on purpose. Where a page belongs follows what the session is doing: a page made during
+// spec work is an artifact of that work and is saved beside it, and anything else goes to Pages. The skills
+// carry that rule, so the sentence asks for the page and leaves the destination to them.
+const PANE_REQUEST = "Put your last answer on a page.";
 
 askPageBtn.addEventListener("mousedown", (e) => e.preventDefault());
 askPageBtn.addEventListener("click", () => {

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

@@ -17,10 +17,21 @@ export const askPageBtn = document.getElementById("ask-page");
 export const fileInput = document.getElementById("file-input");
 export const note = document.getElementById("note");
 
-// The web pane. Every one of these is chrome the interface draws around a published page - the page itself
-// lives in a frame built by app/pane-frame.js and is never queried back.
+// The pane's own chrome: the bar that says which tool is open and how wide the pane is, and the panel each
+// tool draws into. None of it belongs to a tool, which is what keeps a tool from moving the pane.
 export const grip = document.getElementById("grip");
 export const pane = document.getElementById("pane");
+export const panebar = document.getElementById("panebar");
+export const toolTabs = document.getElementById("tool-tabs");
+export const paneFull = document.getElementById("pane-full");
+export const paneCollapse = document.getElementById("pane-collapse");
+export const spine = document.getElementById("spine");
+export const spineBadge = document.getElementById("spine-badge");
+export const toolPages = document.getElementById("tool-pages");
+export const toolSpecs = document.getElementById("tool-specs");
+
+// The Pages tool. Every one of these is chrome the interface draws around a published page - the page itself
+// lives in a frame built by app/pane-frame.js and is never queried back.
 export const pagebar = document.getElementById("pagebar");
 export const panePrev = document.getElementById("pane-prev");
 export const paneNext = document.getElementById("pane-next");
@@ -29,10 +40,7 @@ export const pageCount = document.getElementById("page-count");
 export const pageSmaller = document.getElementById("page-smaller");
 export const pageBigger = document.getElementById("page-bigger");
 export const pageSizeVal = document.getElementById("page-size-val");
-export const paneCollapse = document.getElementById("pane-collapse");
 export const pageDoc = document.getElementById("page-doc");
-export const spine = document.getElementById("spine");
-export const spineBadge = document.getElementById("spine-badge");
 
 // The status strip. One element: everything in it is built per frame from the attached session's snapshot.
 export const strip = document.getElementById("strip");

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

@@ -13,6 +13,7 @@ import { stopDictation } from "./dictation.js";
 import { captureDraft, dropDraft, dropHistory, persistDrafts, pruneDrafts, pruneHistory, restoreDraft } from "./drafts.js";
 import { noteMsg } from "./note.js";
 import { applyPages, prunePanes, refreshPane } from "./pane.js";
+import { applySpecs, applySpecsDelivery } from "./specs-host.js";
 import { adoptSessionsFrame, attachedSid, defaultAgent, sessions, setAttachedSid } from "./state.js";
 import { applySnapshot, pruneStatuses, refreshStrip } from "./status-strip.js";
 import { noteArrivals, notePageArrivals, renderBar } from "./tabs.js";
@@ -64,6 +65,12 @@ export function onFrame(msg) {
         refreshStrip();
     } else if (msg.t === "pages") {
         applyPages(msg);
+    } else if (msg.t === "specs") {
+        // Every window gets these: a spec belongs to the repository rather than to a session.
+        applySpecs(msg);
+    } else if (msg.t === "specs:delivered") {
+        // What the server made of this window's own delivery, on its way back to the frame that asked.
+        applySpecsDelivery(msg);
     } else if (msg.t === "snapshot") {
         applySnapshot(msg);
     } else if (msg.t === "out") {

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

@@ -28,7 +28,9 @@
 //   cards.js        the overlay cards
 //   connection.js   the socket, the reconnect loop, and the curtain
 //   frames.js       what to do with each frame the server sends
-//   pane.js         the web pane: the chips bar, the drag and the spine
+//   pane-shell.js   the pane itself: the tool tabs, the three widths, the drag and the spine
+//   pane.js         the Pages tool: the chips bar and the page
+//   specs-host.js   the Specs tool: its frame, and the credentials the shell hands into it
 //   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
@@ -67,10 +69,12 @@ import "./note.js";
 import "./pane.js";
 import "./pane-arrival.js";
 import "./pane-frame.js";
+import "./specs-host.js";
 import "./state.js";
 import "./status-strip.js";
 import "./strip-format.js";
 import "./theme.js";
+import { mountPane } from "./pane-shell.js";
 import { renderBar } from "./tabs.js";
 import { mountTerminal, term } from "./terminal.js";
 
@@ -79,6 +83,8 @@ import { mountTerminal, term } from "./terminal.js";
 mountTerminal();
 installClipboard();
 refreshComposer();
+// After every tool has registered, which is what makes the pane something to draw.
+mountPane();
 renderBar();
 // Before the first frame arrives, so the icon carries this workspace's frame from the moment the page loads.
 refreshBrowserTab();