See the whole herdr session, not just its agents

[lntvan166]

What and why

paddock could only ever see agents. Any herdr pane without a coding-agent harness was dropped by toAgent and was invisible — and so was any space containing only such panes. This adds the read half of spaces-and-tabs management: the session tree, a screen to browse it, and the ability to open a pane that has no agent.

Design: docs/design/2026-08-25-spaces-and-tabs-management-design.md. Plan: docs/plans/2026-08-25-spaces-and-tabs-read.md. Phases 1–3 of six; rename, create, spawn and close are a second plan.

Four measurements shaped it, all against a live herdr 0.8.2 (§14 of the design records them):

• An agent's name is a stored override, not a derivation. herdr writes it once at agent start from the workspace label, then leaves it alone. Clearing it does not restore a herdr name — the key disappears. So space rename and agent rename are independent, and a "reset to default" control would be a lie.
• pane.read is a superset of agent.read — byte-identical content, indistinguishable speed, and it works on a pane with no harness where agent.read returns agent_not_found. So a shell and an agent are one pane at two moments, not two renderers. Agents deliberately stay on agent.read anyway: it refuses recent_unwrapped on a non-idle agent, a herdr-side guard against scrolling a live pane that we would otherwise have to maintain ourselves.
• Shell panes keep real scrollback; agent panes do not. 400 lines in 2 ms for a shell on the normal screen, against ~35 ms/line for an agent on the alternate screen. The cheap source for one is the ruinous one for the other, and state === null is the discriminator.
• session.snapshot returns the whole tree in one ~15 ms call, and its shapes are already in herdr's schema — so the feature sits inside the drift guarantee instead of outside it.

The load-bearing constraint: agents stay in AgentStore; panes with no agent live only in the tree and the terminal view. Widening Agent into Pane would drag stateless panes through the delta path and the notifier — the call site docs/roadmap.md flags as unguarded, where a mistake silently kills notifications. tests/shell-panes-stay-out.test.ts guards that line.

The tree is read on demand and invalidated by structural herdr events only (workspace.created/closed/renamed, tab.created/closed/renamed), never by workspace.updated, whose rollup status moves on every agent state change. Verified live: tree-stale arrived ~400 ms after a tab was created, and a 55-second window containing a real agent state change produced zero. Subscribe/deliver name pairs were measured before anything subscribed to them — docs/probes/2026-08-25-structural-events.md — because matching the wrong spelling fails silently and forever.

AgentTerminal.tsx splits 1050 → 608 lines, with the transcript and read loop moving to a reusable PaneTerminal. Not cosmetic: that is the seam the shell case falls on. No pre-existing terminal test was edited, which is the evidence the split moved code rather than changed behaviour.

Old #/agent/<id> links keep parsing forever — Telegram messages already sent still resolve.

Known gaps, recorded not discovered

• The Spaces screen cannot render in --demo, so it is currently un-screenshottable under this repo's own README rule. Needs a synthetic demo tree.
• docs/architecture.md and docs/decisions.md have no entry for this feature yet; the design doc carries the reasoning meanwhile.
• Design §9.1 carries a dated correction: a probe on this branch measured that tab.create does return the new pane id, on the envelope's root_pane. §14.8 is accurate — TabInfo the type genuinely has none; only §9.1's inference was wrong.

Checklist

• make check && make check-clean && make test pass — 1255 tests, 0 failures
• If this adds a test: I broke the thing it guards and watched it fail — the invariant guard was rejected on the first attempt for exactly this reason: deleting if (!rawAgent.agent) return null left it green, because the fixture's agent list never contained the shell pane. It now supplies that row inline in all three falsy shapes and goes red without the guard. Same red-then-green done for the structural-subscription assertion, which previously allowed the whole subscription list to be deleted with a green suite.
• If this touches measurement or performance claims: the number is in the commit message
• No hostnames, home paths, usernames, employer terms or real agent names — check-clean clean; fixtures use the invented names only

🤖 Generated with Claude Code

[lntvan166]

Round 2 — the six review findings, fixed

Driving the shipped screen against a real herd produced six complaints. All six are fixed on this branch (13 commits, fed0d76..3c12ad3). Suite 1307 passing, make check and make check-clean clean.

Two of the six were defects in this design's own reasoning, and are recorded as such in §16 rather than quietly patched.

1 & 6 — the screen said the wrong things. §14.7 measured that herdr initialises an agent's name to the slug of its workspace label; §6's merged row then compared the two strings for exact equality, so every row printed its own title twice, once de-spaced. The comparison is now slug-normalised. A tab label was rendering as a bare <h3> between pane rows, reading as a section header for the whole list — it is now a caption on the pane it labels, and a space's children are bracketed so a space is visibly a container. The Spaces control was stranded at the exact centre of the header by a justify-between row with three children; it is now grouped with Settings, and Settings gained a drawn icon so the two adjacent controls stop resting on opposite principles.

2 — shell panes were read-only. §8 promised them text input and no route was ever built. Now POST /api/panes/:id/{text,key} on the same closed isNavKey allowlist the agent path uses, with text refused rather than truncated at the ceiling — a silently shortened command is a different command.

xterm.js was refused, and the reasoning is recorded as decision 20. It buys cursor addressing, resize, and full-screen programs; it costs roughly 80 KB gzipped on top of a measured 102.45 KB bundle, in a repo that rejected a 76 KB webfont because it would be the largest payload on a slow link. Typing claude or ls needs none of it.

3 — back went to the wrong place, in the wrong clothes. Two defects behind one report: an agent pane always returned to the dashboard, discarding where you opened it from, and the shell branch hard-coded #/spaces, so a shell opened from a notification tap returned you to a screen you had never visited. One origin-aware rule now serves both, and a pane with no origin lands on the dashboard. The Spaces back control also adopted the shared ‹ treatment it was the only screen not using.

Also fixed: a shell's label put a hostname on screen. It was labelled by its terminal title, which for a pane at a prompt is the prompt. It is now labelled by its folder — and cwd is tilde-ised server-side, so the username never crosses the wire rather than being hidden by whichever client renders it.

The one that mattered most

A whole-round review caught a Critical that three earlier reviews missed: the shell's Send typed a command and never ran it. pane.send_text does not submit, the input is single-line, and the only Enter was the keypad's — which defaults to hidden. So the shipped first-run flow was: type ls, tap Send, nothing happens.

Every test passed because the tests called localStorage.setItem("paddock.term.keypad", "compact") first. That setup line was the defect, written down.

POST /api/panes/:id/text now takes {text, submit} and issues send_text then send_keys(["enter"]) — one operator act, one round trip — and reports a half-landed command distinctly ("typed, but not run: …"), because a command that was typed but not executed must never read as success. There is now a test that asserts localStorage is empty before proving Send works, so it tests the shipped product rather than an arranged one.

Verified end-to-end in a browser against a throwaway pane in the default configuration: the command executed, keypad untouched, tab closed afterwards.

Known gaps, named rather than discovered

• The Spaces screen cannot render in --demo, so it is still un-screenshottable under this repo's own README rule. The control is now hidden there rather than offering a button that always errors — but a synthetic demo tree is deliberately deferred, and README screenshots of this screen wait on it.
• The Spaces control derives from a capability signal carried on the WebSocket snapshot, so it appears a beat after connect, and would not appear at all if the socket were blocked while /api/spaces worked. Accepted cost of not gating it on a demo flag.
• After a half-landed submit the note tells you to press Enter, but in the default configuration the only Enter is behind the Keys toggle. Narrow — it needs a herdr failure between the two calls.
• docs/architecture.md and docs/decisions.md are now current (the tree module, the dependency edge, all eleven routes, and decision 21 for "the tree is read on demand and never replicated").

Create, rename and close for spaces and tabs is the next branch, designed in §7/§9/§10 with §16.7's control placement.

🤖 Generated with Claude Code