chamba 0.3.1 → 0.4.0

package/templates/webterm/README.md

@@ -0,0 +1,157 @@
+# webterm
+
+A browser front-end for the interactive AI agents (`claude`, `opencode`, `codex`) running inside a chamba container.
+One server runs all three, one agent per session, so a single bar can hold a claude tab and a codex tab at once.
+
+It relays the real agent TUI over a PTY (not the Agent SDK, not headless mode), so it uses your subscription through the container's config dir (e.g. `~/.claude`) - no API key - and stays inside the chamba sandbox.
+On top of the terminal it adds a rich composer so you can paste images, drop or upload attachments, and dictate - things the container terminal alone cannot do.
+
+## How it works
+
+- `server.js` serves the page, exposes `POST /upload`, and runs a WebSocket relay at `/ws`.
+- The URL carries a key (`/?k=<key>`) and every route that carries the relay demands it. The server mints a new one at each start, so the key lives exactly as long as the process that issued it.
+- `sessions.js` is the session registry: what a session is, who drives it, and what ends it. The PTY is injected, so the rules are unit-tested without `node-pty`.
+- A session is one `node-pty` process running its own agent in a directory inside `/workspace`. Both are fixed for the life of the session - they are the process. Sessions belong to the container, not to the browser.
+- The page (`public/`) lists every live session as a tab, renders the attached one's TUI with xterm.js, and forwards keystrokes.
+- The page is plain ES modules under `public/app/`, one per subject (the bar, the composer, the socket and curtain, the frame router, the clipboard, and so on), loaded through `app/main.js`. No build step: what the browser runs is what is in the file. `main.js` lists the modules and holds the boot order, and it is the only place that calls into a module while the page is starting - the graph has cycles, so nothing else may.
+- The composer sends its message (text plus any image paths) as one bracketed paste, so a multi-line message is submitted once.
+- Tab order is registry state (`reorder`), so a drag is a frame and the new bar comes back as an ordinary broadcast - a locally sorted bar would be undone by the next one. The bar holds still while a drag is in flight, because rebuilding it would replace the element being dragged and cancel the drag.
+- Composer drafts are the client's, kept per session id in `sessionStorage` and swapped on every attach. The text, the `[Image #N]` tokens and the counter behind them move together: a token only means something next to the map that expands it, so one shared map would let `[Image #1]` in one session resolve to another session's file.
+- Pasted/dropped/uploaded images are POSTed to the server, saved under `/tmp/uploads/`, and their in-container paths are injected into the message. The agent reads the images from those paths.
+- When a session's agent is `claude`, a short note (`context/claude.md`) is appended to its system prompt via `--append-system-prompt-file`, so it knows it is reached through the browser rather than a terminal. Decided per spawn, since the next session may be a different agent. Only claude has this per-launch hook; the shared managed `CLAUDE.md` (which the terminal reads too) is untouched. `WEBTERM_CONTEXT_FILE` overrides the file.
+- The page owns the clipboard, because a TUI can own the mouse. claude turns on mouse tracking, so xterm hands drags to the agent and has no selection of its own; the agent then pushes the selected text out with **OSC 52**, which the page decodes (base64 to UTF-8, not bare `atob`) and writes to the clipboard. A clipboard *read* request (`OSC 52` with `?`) is never answered, so nothing in the container can pull the host clipboard out through the relay. Where the terminal does own the selection, `Cmd+C` / `Ctrl+Shift+C` and the terminal's right-click menu copy it; `Ctrl+C` is always an interrupt.
+- There is one clipboard - the machine's - and only a copy made in the window in front may write it. A replayed screen is the session's own past output, so it still contains the OSC 52 of any copy made in that session earlier: replays go through `writeReplay`, which makes the OSC 52 handler ignore them. Without that, every attach (a session switch, a reload, a reconnect after sleep) put that session's stale text back on the clipboard, so each session tab looked like it carried a clipboard of its own. An unfocused window does not write either - its text waits for the copy shortcut rather than replacing what was copied in another app.
+- When this window cannot do anything at all, one curtain covers the whole page and says why - the container is gone, this URL's key is spent, or the container is being stopped. Stopping is the one that is a wait rather than a report, so it shows as one (dots, and no advice about a container that has not gone yet) and the closing socket turns it into "the container is stopped" - nothing else takes the relay down at that moment, and a wait left up for good is indistinguishable from a page that hung. It replaces disabling each control on its own, which is what used to leave a dead page looking alive: tabs that still hovered, and an X that opened an end-session prompt nothing would answer. A dropped socket makes the page inert at once but waits 3s before drawing the curtain, so a sleeping laptop or a wifi blip heals without one appearing.
+- Clicking in the session bar blurs the terminal (a tab is a plain div; `+ New session` is a button), and a blurred terminal receives neither keystrokes nor `Cmd+V`, so a tab click and every attach hand focus back to it. The composer, a rename editor and an open card keep focus.
+
+## Sessions
+
+The page is mission control for the container: the tab bar at the top is every agent session running in it, however long ago you started it.
+
+- **Nothing is ended for you.** A closed browser, dropped wifi and a slept laptop are indistinguishable from the server, so none of them ends a session. Close the lid on an unanswered question, open it a day later, and the question is still there. A session ends only when you close it, when the agent exits on its own, or when the container stops.
+- **A session is picked up, not recreated.** Reconnecting replays the session's screen and carries on. Open the same URL in another browser and every session is listed there too.
+- **Closing the session you are in lands you on its neighbour** - the tab to its right, else the one to its left - rather than on a dead screen. Closing a session you were not in leaves you where you are. When every session that is left is open in another window, nothing is taken from it: this window says so instead of leaving the closed session's screen up looking live.
+- **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.
+- **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.
+- **Opening the URL always lands you somewhere:** the session you were last looking at, or - when nothing is running - one freshly started session, which is what resumes the most recent conversation.
+  Reconnecting is not the same as opening, and starts nothing: a wifi blip or a slept laptop puts you back on exactly what you left, an empty bar included.
+- **A session starts where you did, and stays there.** `+ New session` opens the agent in the directory `npx chamba` ran in, the same directory a terminal session lands in - so `npx chamba` inside `apps/api` gets you an agent working on `apps/api`.
+  The directory belongs to the session for its whole life, so several sessions can work in different parts of the workspace at once.
+  A path has to name a directory that exists inside the workspace, or nothing is started - the container is the sandbox boundary either way, this is what keeps the picker honest.
+- **And with the agent you asked for**, because one server runs every agent it knows, one per session: claude and codex can be two tabs of the same bar, each in its own directory.
+  Which agent and which directory are the only two things that make a session, and neither can be changed later, so the chevron beside `+ New session` asks both in one panel - anchored under the button, since it opens on the way to something routine.
+  Choosing there starts that one session and nothing else: the default stays where the container put it, and `webterm <agent>` in the container is what moves it.
+  A name that is not one of the agents starts nothing: the browser names it, and it ends up as a process.
+- **Up to 8 sessions** (`WEBTERM_MAX_SESSIONS`). The limit is memory: each one is a full agent process.
+- **Call it a day with the power button** at the right of the bar: it stops the container, and with it every session in it - browser and terminal alike. It always asks first, naming what ends. The container stops itself by signalling PID 1, which only works because chamba gives the keep-alive a TERM trap; a container created before that says so instead of hanging, and points at the host.
+
+## What the tabs are telling you
+
+Whether an agent is working is read off the rhythm of its output - a sustained stretch means working, going quiet means it stopped - so it is the same for every agent and does not depend on reading anyone's TUI.
+Going quiet is not the end of a turn on its own, though: an agent pauses mid-turn (a slow first token, a tool that prints nothing while it runs) and carries straight on.
+So the light goes out with the output, but the stop has to hold for a few seconds before anything says the agent finished - and work that resumes is never reported as finished at all.
+That is why a session showing as working never also shows as waiting for you.
+
+- **A light travels round a tab** while that session's agent is working.
+- **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.
+- **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 sweeping 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 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.
+
+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.
+Nothing before the ending counts, the prompt that started the turn included - sitting and watching a reply arrive is not using the session, and counting the prompt is what once made a short turn silent for good.
+What it costs is the user who reads a long reply without touching anything: they get one chime for something they were looking at. A redundant sound you can mute is the cheaper mistake.
+
+`GET /dirs?k=<key>` answers with the default directory and the ones the picker suggests: `{"default":"apps/api","dirs":["apps","apps/api",...],"truncated":false}`.
+The walk is bounded (3 levels deep, 400 entries, no dot directories and no `node_modules`), and says when the list is partial - anything deeper can still be typed in.
+
+`POST /cwd?k=<key>` with `{"cwd":"/workspace/apps/api"}` moves where new sessions start.
+chamba calls it at every session start that finds the interface already running: the launcher only passes the directory once per container start, so without this the browser would keep opening sessions in the directory of whichever session first started the container.
+Existing sessions are untouched - a session's directory never changes under it.
+
+`POST /agent?k=<key>` with `{"agent":"codex"}` moves which agent new sessions start with, and nothing else - live sessions keep the agent they were started with.
+`webterm <agent>` in the container calls it when it finds the interface already running, which is what replaced killing the server to change agents.
+
+`GET /status?k=<key>` reports the agent new sessions get, what is actually running, how many sessions are alive, and how many of them a browser is watching: `{"agent":"claude","agents":{"claude":2},"sessions":2,"attached":1}`.
+chamba asks it when the last terminal session closes, so `exit` in the terminal warns before it stops a container with live browser sessions in it.
+A window whose socket dropped asks it too: an answer means the relay is fine, a `403` means this window's key is spent, and no answer at all means the container is gone - three different things to say, and this is what tells them apart.
+
+## Run
+
+webterm is baked into the chamba image with its dependencies preinstalled, and there is nothing to turn on.
+
+1. Open a session with `npx chamba`.
+   Every workspace gets its own sticky host port from the configured range (default `3900-3999`), stored host-side and never in `chamba.yaml`.
+   A port that cannot be used moves the workspace to the next free one in the range, and it stays there.
+2. chamba starts the server on every container start and opens the URL in your browser, e.g. `http://127.0.0.1:3900/?k=9f2c41ae8b...`.
+   On a host that cannot open a browser, the same URL is printed by chamba and again in the container greeting.
+   The key on the end is what the relay checks, and it changes every time the server starts.
+3. In the container, `webterm <agent>` (`claude`, `opencode`, or `codex`) moves which agent new browser sessions start with.
+   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`, a directory chamba bind-mounts from the workspace cache, and the host reads it back at the next container start - so it holds across restarts.
+
+The first session after a container start resumes the most recent conversation; later sessions start fresh.
+Only a session running that same agent may claim the resume - the marker holds a command for it, and any other agent would consume the conversation without being able to open it.
+
+Running `webterm <other-agent>` while the server is up starts nothing and ends nothing: it moves what `+ New session` will start, and prints the URL.
+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.
+
+- **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 never takes the screen - its chip gets a `new` badge and waits for a click - except in a pane that is still empty, where the first page opens on arrival - which is also what opens a pane nobody has touched yet, 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. Drag the divider to set the width. 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 and the collapse 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. claude also gets a `web-pane` skill whose description is the phrases a user actually says ("show me", "as a page", "in the pane", "publish"), and whose body is the craft: a standalone dark page, inline everything, how to ask with a form, and what a submitted form does and does not prove. 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 age sweep, nothing removed when a session closes. Growth is bounded instead: a page over the per-page cap 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 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 the five-hour quota with the time until it recharges, and the installed Claude Code version.
+
+- **Where the numbers come from.** The status line script chamba installs (`claude-statusline.sh`, baked into the image) prints nothing at all - in a browser a status line would scroll away with the output and cost a terminal row every prompt. What it does instead is write `~/.claude/context-usage/<session-id>.json` on every prompt render, and the strip is drawn from that file. The same file is what the `context-usage` helper reads, so an agent asking about its own context and the strip above it always agree.
+- **Whose numbers they are.** A snapshot records the pid of the claude process that wrote it, and the server matches it to a session by walking up the process tree from that pid to the session's PTY leader - not by assuming the two are equal, since a wrapper or a shell may sit between them. The start time recorded beside the pid is the tiebreak: the snapshot directory is a chamba mount, so it holds files written by containers that are gone, and their pids can be live again as something else.
+- **Only claude has one.** The snapshot is a Claude Code side effect, so a codex or opencode tab has no strip - the server sends no frame for one rather than an empty one. A claude session that has not rendered a prompt yet has no strip either, and gets one within a second or two of its first.
+- **Live, and only when it moved.** The file is polled (`WEBTERM_STATUS_SCAN_MS`, 2s) rather than watched - it is written by a shell script into a bind mount - and a frame goes out only when something the strip shows actually changed. It is pushed to the one window watching that session, never broadcast.
+
+## Security
+
+- The server binds container port **3899**; chamba publishes it loopback-only (`127.0.0.1:<port>:3899`), so nothing on the LAN can reach it.
+  That container port is reserved: a `chamba.yaml` entry publishing it is rejected, so nothing else can front the web URL.
+- Inside the container it listens on all interfaces - required for a published port to reach it. So any process on the host, and any container on the same Docker network, can open the port. Reaching the port is not the same as getting in: the key is.
+- **The URL carries a key, and the relay refuses anything without it.** A new one (16 random bytes, hex) is minted at every server start and published to `/tmp/webterm.key` the moment the port is bound; the launcher and the container greeting read it back, which is how the printed URL is always the live one. Gated: the page itself, `POST /upload`, `GET /status`, `GET /dirs`, `POST /cwd`, `POST /agent`, the three `/pane/*` routes, and the WebSocket handshake. Not gated: the page's modules under `/app/`, the stylesheet, the icon and the xterm files under `/vendor` - they hold nothing secret and drive nothing, and a window that never got the page opens no socket.
+- The key stays in the URL rather than in a cookie on purpose. Cookies on `localhost` are shared across ports, so a page served by any other local port could ride this workspace's; a key in the URL is scoped to the window that was handed it.
+- Comparison is constant time, so a caller cannot learn the key one character at a time from how long a refusal takes.
+- The WebSocket handshake also rejects any non-loopback `Origin`, checked alongside the key. On its own that is a browser-behavior gate - a non-browser client sets any Origin it likes - so it is the second lock, not the first.
+- A key dies with the server that issued it. Restarting the interface (or the container) invalidates every open window, which is why a spent URL gets a page that says where the current one is rather than a silent refusal.
+- Uploads are images only, size-capped, and written only under `/tmp/uploads/`.
+- **A published page never runs as part of this app.** The pane fetches its content over the key-gated route and renders it into an iframe with `sandbox="allow-scripts allow-forms"` and no `allow-same-origin`, so the page has an opaque origin: its scripts run, and there is nothing of the interface for them to reach. A form talks to the pane by `postMessage`, and only the pane - which is interface code - holds the key and calls the endpoint.
+- **A page cannot read the window's URL, which is where the key is.** A frame rendered from `srcdoc` has no URL of its own and falls back to the base URL of the document holding it, which a script inside the page can read as `document.baseURI` - an opaque origin does not cover this, because `baseURI` is a plain string on the page's own document rather than a cross-origin read. Two things close it. The shell declares `<base href="/">`, so the value a frame falls back to is the bare origin instead of a URL with a key on it; that is the half a page cannot affect. The rendered document is also given `<base href="about:srcdoc">` as its first element, so nothing is inherited in the first place; a page can delete that one, which is why the first exists. The frame is `referrerpolicy="no-referrer"` as well, since a srcdoc document otherwise inherits the parent's referrer and sends it with everything it loads.
+- **A feedback file says a page was submitted, not that a person answered.** The pane cannot tell a form a user filled in from a script in the same page posting the message the form would have. The file and the nudge are the channel, and the answers are bounded and filed either way; an agent should read one as data from its page, not as proof of consent.
+- **The pane's routes take their key in a header** (`X-Webterm-Key`) and refuse it in the URL. A script inside a page can read the URL of the document it is in, so no URL that carries a page's content may carry the key; there is nothing to open by hand and nothing to leak. The refusal is the server's, not a habit of the client's, so a second caller written later cannot reopen it. Every other route keeps `?k=`, which is what makes the interface openable from a link.
+- **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 cap. Listing a page reads only the first few kilobytes, looking for its title, and serving one is refused outright past the per-page cap - 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 cap is refused rather than read into memory.
+- **Feedback is bounded and bound.** The body has a size cap, 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 cap 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 capped 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 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.
+
+## Cleanup
+
+`/tmp/uploads/` is swept on startup and once a week: files older than 7 days are deleted, and only files strictly inside `/tmp/uploads/` are ever touched.
+
+## Config
+
+`config.js` holds the knobs (port, agent list and default agent, key and key file, upload dir, size cap, sweep age/interval, paste framing, resume marker, state file, session limit, keepalive interval, stop timings, claude context file, workspace root and directory-scan limits, the pane's directory, caps, 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_MARKER`, `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 minting one, which is for tests and hand-run debugging - there is no way to turn the gate 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.
+The `webterm` launcher on PATH sets these from the container's chamba-injected environment, and falls back to its own `$PWD` for the session directory - so a hand-run `webterm claude` starts sessions where that shell is.