Add expose_port previews with a Preview tab; leave setup to AGENTS.md

docs/operations.md

@@ -10,6 +10,7 @@
 - `internal/agents`: the agent session manager. It owns the running Claude processes, task agents and lead agents alike (see "Lead agent"), and records their activity as events.
 - `internal/claude`: the Claude Code stream-json client (see `docs/claude-protocol.md`).
 - `internal/push`: web push notifications for new inbox items (see "Notifications").
+- `internal/tailscale`: `tailscale serve` for task previews (see "Previews").
 - `web/`: the SPA, frameworkless TypeScript compiled file-by-file to ES modules (no bundler). `web/src/*.ts` is the source; `web/src/api.gen.ts` holds types generated from `api/openapi.yaml`, and `web/src/api.ts` is the typed client over them. `go generate ./web` runs `npm ci`, regenerates the types and compiles `web/dist/`, which is committed so `go install` needs no Node. The binary embeds `index.html`, `style.css`, `dist/`, `src/` (for source maps), `fonts/` and `vendor/` (Mermaid, see "Inbox"; xterm.js, see "Terminals"). `byre serve --dev` serves `./web` from disk instead (run from the repo root); pair it with `npm --prefix web exec tsc -- --watch`.
 
 ## Data
@@ -22,10 +23,8 @@ Schema changes are the `migrations` slice in `internal/store/store.go`: named en
 
 Every task worktree is made by `createTask` (`internal/agents/tasks.go`): new tasks, `create_task`, `start_todo` and forks alike.
 
-- **Ports.** Each active task holds a block of `store.PortBlock` ports starting at `tasks.port_base` (`port_base` on the Task). `Store.CreateTask` gives a new task the lowest block from `byre serve --ports` (default `store.DefaultPortFirst`) up that no active task holds, so a merged or discarded task's block is reused. The agent's `claude` process gets `PORT` (the first port, which most dev servers read on their own), and the session guidance names the range and says to run dev servers on it. `sqlite3 byre.db "SELECT id, port_base FROM tasks WHERE status = 'active'"` lists the blocks in use.
-- **Setup script.** If the new worktree has an executable `script/setup` (`setupScript` in `internal/agents/setup.go`), byre runs it in the background, in the worktree, with `PORT` added to byre's environment. Nothing in its interface is byre-specific: a script that copies untracked files such as `.env` from the project's checkout finds it as the parent of `git rev-parse --path-format=absolute --git-common-dir`. It is the project's own file, so a branch that changes it changes the setup of tasks started or forked from that branch. It is killed after `setupTimeout`. The task's transcript shows a `setup.started` note and a `setup.ended` note holding the last `setupOutputBytes` of its combined output (`output`), how long it took (`duration_ms`) and `error` when it failed.
-- **Waiting.** While setup runs, the task's turns are queued as if the caps were full (`Manager.settingUp`, checked in `turn` and `drain`), so the session shows `queued`; when setup ends, byre drains the queue. Task creation itself doesn't wait.
-- **Failure.** A failed setup doesn't stop the agent. The next prompt its session submits gets the failure and the output appended to the `UserPromptSubmit` guidance (`remindTaskGuidance`), and at that moment byre files the same text as a `session_error` inbox item. The setup state and failure live in memory, so a byre restart during setup leaves the queued turn to start without it and nothing reruns the script.
+- **Ports.** Each active task holds a block of `store.PortBlock` ports starting at `tasks.port_base` (`port_base` on the Task). `Store.CreateTask` gives a new task the lowest block from `byre serve --ports` (default `store.DefaultPortFirst`) up that no active task holds, so a merged or discarded task's block is reused. The agent's `claude` process gets `PORT` (the first port, which most dev servers read on their own), and the session guidance names the range, says to run dev servers on it listening on `127.0.0.1`, and points at `expose_port` (see "Previews"). `sqlite3 byre.db "SELECT id, port_base FROM tasks WHERE status = 'active'"` lists the blocks in use.
+- **Setup.** byre runs nothing in a new worktree. The session guidance says the worktree starts with only what git tracks and tells the agent to do any setup the project's AGENTS.md describes before other work, so installing dependencies or copying untracked files such as `.env` is the project's own instruction, carried out by the agent with its own tools. A project's checkout is the parent of `git rev-parse --path-format=absolute --git-common-dir` in the worktree.
 
 ## Closing a task
 
@@ -60,16 +59,21 @@ After rebuilding: `go install ./cmd/byre && launchctl kickstart -k gui/$(id -u)/
 
 Clients reach `tailscale serve` over HTTP/2; it proxies to byre over HTTP/1.1 and passes SSE through unbuffered.
 
+## Previews
+
+An agent shows the human a server it runs with the `expose_port` MCP tool (`internal/agents/preview.go`): `name` labels it, `port` is where it listens. The agent starts the server itself, usually as a background command; byre doesn't supervise it, so it dies with the agent's `claude` process (a byre restart, compaction, the task closing) and the agent starts it again when asked. The call is refused when `port` is outside the task's block or nothing accepts a connection on `127.0.0.1:<port>`. Otherwise byre runs `tailscale serve --bg --https=<port> http://127.0.0.1:<port>` (`internal/tailscale`, which runs the macOS CLI at `/Applications/Tailscale.app/Contents/MacOS/Tailscale`, since byre's environment has no `tailscale` on its `PATH`), so the server is at `https://<byre's ts.net name>:<port>/` with Tailscale's identity headers, and records a row in the `previews` table (task, name, port, time) with a `preview.exposed` event, which the transcript shows as a note linking the URL. Each port gets its own HTTPS port rather than a path under byre's, since path-prefix proxying breaks apps that use absolute paths. Exposing a name or port the task already has replaces that row, and a port it no longer uses is turned off with `tailscale serve --https=<port> off`. A server must listen on `127.0.0.1`: while `tailscale serve` holds a port, binding `0.0.0.0` on it fails with "address already in use". When the task is merged or discarded, byre turns off each of its ports (`Manager.Unexpose`); the rows stay. `GET /api/tasks/{taskId}/previews` lists a task's rows by name, and `tailscale serve status` shows what is served.
+
+The **Preview** tab (`web/src/preview.ts`) lists the task's previews by name and port, shows the selected one (the first by default; the choice is kept per task in memory) in an iframe, and links it in a new tab. It fetches the list when it opens, when the selected task changes, and on each `preview.exposed` in the task's stream, which also reloads the iframe.
+
 ## Previewing byre
 
-A task's build of byre runs alongside the service with its own empty state, from the worktree root, on the task's port:
+A task's build of byre runs alongside the service with its own empty state, from the worktree root, on the task's port, and the agent exposes it with `expose_port`:
 
 ```
 go run ./cmd/byre serve --dev --data "$PWD/.preview" --listen 127.0.0.1:$PORT --ports 51000
-tailscale serve --bg --https=$PORT http://127.0.0.1:$PORT
 ```
 
-It must never share the service's data directory: nothing locks the database, and startup resumes every session marked `running` in its recorded worktree. `--ports` puts the preview's own tasks' port blocks in a range the service's tasks don't use; each instance only knows its own tasks, so with the default both would hand out blocks from the same first port, starting with the one the preview listens on. `.preview/` is gitignored, so the end-of-turn commit leaves it out. The preview starts with no users, projects or sessions; set a git identity with `PUT /api/me` and add a project to try things. A project's Merge pushes to its checkout's `origin`, so a preview project should be a clone whose `origin` is a local bare repository (`git clone --bare <checkout> .preview/origin.git`, then clone that), never the real checkout. `tailscale serve --https=$PORT off` removes the preview's port; `tailscale serve status` lists what is served. byre's own environment doesn't have `tailscale` on its `PATH`; on macOS the CLI is `/Applications/Tailscale.app/Contents/MacOS/Tailscale`.
+It must never share the service's data directory: nothing locks the database, and startup resumes every session marked `running` in its recorded worktree. `--ports` puts the preview's own tasks' port blocks in a range the service's tasks don't use; each instance only knows its own tasks, so with the default both would hand out blocks from the same first port, starting with the one the preview listens on. `.preview/` is gitignored, so the end-of-turn commit leaves it out. The preview starts with no users, projects or sessions; set a git identity with `PUT /api/me` and add a project to try things. A project's Merge pushes to its checkout's `origin`, so a preview project should be a clone whose `origin` is a local bare repository (`git clone --bare <checkout> .preview/origin.git`, then clone that), never the real checkout.
 
 ## Identity
 
@@ -95,7 +99,7 @@ Agents don't commit; byre does. Each `user.message` event that starts a turn rec
 
 byre chooses the Claude session ID (`vendor_session_id`) up front, so every session can be resumed. Processes start on demand: the first message after a restart resumes the session with `--resume`. Sessions are `running` from the moment a turn is sent until its `result` arrives; on startup, every session still marked `running` was cut off mid-turn, and byre resumes it and sends a message telling the agent to re-check the working tree. Stopping the server kills all agent processes. Merging or discarding a task kills its sessions and marks them `completed`.
 
-Every session gets byre's guidance (`guidance` in `internal/agents/guidance.go`): ask questions with `ask_human`, end each turn with a final message that summarizes it (including every departure from the plan), put everything the human needs in a blocking question's context since that turn files no report, don't commit (byre commits each turn), and don't push, touch other branches or run git maintenance. A task agent's guidance also names its port range (see "Worktree setup and ports"). A task started from a `TODO.md` item gets one more line naming the item and telling the agent to remove it from `TODO.md` in its worktree when the work is done (`taskGuidance`; see "TODO"). It is passed as `--append-system-prompt`, which Claude Code records on a session's first request and reuses on resume, so a running session keeps the text it started with; a `UserPromptSubmit` hook also attaches it as `additionalContext` to every user turn, which reaches existing sessions too.
+Every session gets byre's guidance (`guidance` in `internal/agents/guidance.go`): ask questions with `ask_human`, end each turn with a final message that summarizes it (including every departure from the plan), put everything the human needs in a blocking question's context since that turn files no report, don't commit (byre commits each turn), and don't push, touch other branches or run git maintenance. A task agent's guidance also names its port range and tells it to do the setup AGENTS.md describes in a new worktree (see "Worktree setup and ports"). A task started from a `TODO.md` item gets one more line naming the item and telling the agent to remove it from `TODO.md` in its worktree when the work is done (`taskGuidance`; see "TODO"). It is passed as `--append-system-prompt`, which Claude Code records on a session's first request and reuses on resume, so a running session keeps the text it started with; a `UserPromptSubmit` hook also attaches it as `additionalContext` to every user turn, which reaches existing sessions too.
 
 A Stop hook (`bounceProseQuestion` in `internal/agents/guidance.go`) bounces a turn whose final message asks the human something in prose: if `ask_human` wasn't called during the turn and the final message (`last_assistant_message`) has a sentence ending in `?` outside code spans, code blocks, quotes and blockquotes, the stop is blocked once with an instruction to ask through `ask_human`. The per-turn flags reset when the next user message is sent. Claude Code reports the block as a "Stop hook error" notification; that is expected. An agent told explicitly to ask in plain text will refuse the bounce.
 
@@ -137,7 +141,7 @@ Each user has one long-running lead agent, shown in the left pane. It is not tie
 - **Compaction.** The pane's **Compact** button asks the lead for a handoff (`leadHandoffPrompt`). The lead can also call `compact_self` at a logical point; when that turn ends normally, byre sends the same request. The handoff turn ends the session, and a new lead session starts from `leadHandoffPreamble` plus the handoff; held input follows once that turn ends.
 - **Restarts.** On shutdown, byre marks each running lead session idle with "byre stopped mid-turn" and holds a restart notice for it, so a lead is never left `running` for a build without lead support to find. After a crash, startup resumes a running lead like a task session. Startup then delivers any held input.
 
-The UI is two panes: the left is the lead's transcript and composer (the same view as a task transcript, with only the Compact button in its header), the right shows the focused task, or project with no task, with the Transcript, Changes, Files, Terminal, Inbox and Project tabs, the lead's `tabs` first. ⌘P (Ctrl+P elsewhere) selects the Project tab, keeping the right pane's task, and replaces the browser's print shortcut. ⌘S (Ctrl+S elsewhere) opens the right pane's task's Merge confirmation, from any tab, when the Merge button would be enabled, and replaces the browser's save shortcut.
+The UI is two panes: the left is the lead's transcript and composer (the same view as a task transcript, with only the Compact button in its header), the right shows the focused task, or project with no task, with the Transcript, Changes, Files, Terminal, Preview, Inbox and Project tabs, the lead's `tabs` first. ⌘P (Ctrl+P elsewhere) selects the Project tab, keeping the right pane's task, and replaces the browser's print shortcut. ⌘S (Ctrl+S elsewhere) opens the right pane's task's Merge confirmation, from any tab, when the Merge button would be enabled, and replaces the browser's save shortcut.
 
 ## TODO