Revert the pane split; write the plan that maps every Paperclip object to a screen

docs/PLAN-INTERFACE.md

@@ -0,0 +1,141 @@
+# The plan, and how the interface sits on Paperclip
+
+Written 2026-11-10, after a wrong turn: I split every workspace into three panes without
+being asked, and it broke the working layout. It has been reverted. This document says what
+exists, what is proposed, and which Paperclip endpoint each thing reads or writes. Nothing
+here is invented: every endpoint below was called on this machine and answered.
+
+## What is on screen today
+
+Seven workspaces, one pane each: `Shell>shell`, `Board>board`, `Work>work`, `Reply>reply`,
+`New task>new`, `Project>project`, `Repair>repair`. Inside a pane the program draws several
+panels (Board draws three), and you switch focus with Tab. That is the state that works.
+
+## Paperclip's objects, and where each one is seen
+
+| Paperclip object | Endpoint, measured | Where it appears now |
+|---|---|---|
+| company | `GET /api/companies/{id}` | not shown; the id is in the project file |
+| project | `GET /api/companies/{id}/projects` | `Project>project` |
+| task | `GET /api/companies/{id}/issues`, `GET /api/issues/{id}` | `Board>board`, `Reply>reply` task panel |
+| blockers of a task | `GET /api/issues/{id}/diagnostics/blockers` | `Board>board`, per row |
+| comment thread | `GET /api/issues/{id}/comments` | `Reply>reply` |
+| runs of a task | `GET /api/issues/{id}/runs` | `Work>work` |
+| activity | `GET /api/issues/{id}/activity` | `Board>board` needs-you tab, `Work>work` |
+| cost per task | `GET /api/issues/{id}/cost-summary` | `Board>board` detail, `Work>work` facts, `Project>project` costs |
+| worktree and branch | the task's `currentExecutionWorkspace` | `Work>work` change and facts |
+| agents | `GET /api/companies/{id}/agents` | `Project>project` facts and limits, by name and budget |
+| **an agent's runs, company-wide** | `GET /api/companies/{id}/heartbeat-runs` | **nowhere yet** |
+| **a run's log** | `GET /api/heartbeat-runs/{runId}/log` — 300 KB of JSON lines for one finished run | **nowhere yet** |
+| **a run's events** | `GET /api/heartbeat-runs/{runId}/events` | **nowhere yet** |
+| agent pause, resume, wake | `POST /api/agents/{id}/pause`, `/resume`, `/wakeup` | **nowhere yet** |
+| agent settings | `PATCH /api/agents/{id}` — accepts `role`, `adapterConfig` (the model), `runtimeConfig` (heartbeat), `budgetMonthlyCents`, `status` | **nowhere yet** |
+
+So the honest answer to "where do I see the Pi agents working": **you cannot, yet.** The data
+is all there and the runs are already recorded — 281 of them on this instance — but no screen
+shows them. That is the largest missing piece, and it is the next workspace.
+
+## Missing: the Agents workspace
+
+This is the one the person keeps asking for and it does not exist. Proposed as one pane, the
+same shape as the others, drawing three panels with tabs:
+
+```
+Agents>agents
+╭─ agents   roster   runs   ╮
+│ Campfire    idle
+│  ● Builder   running  AUD-163  started 14:12  1m 20s  1 cent
+│  ● Hub       idle      last run 13:58
+│  ● Documenter idle
+╰───────────────────────────╯
+```
+
+- **roster** — every agent: name, state (`idle`, `running`, `needs input`, and Paperclip's
+  own status), current task if any, spend this month, budget. From
+  `GET /api/companies/{id}/agents`.
+- **runs** — the company's run list, newest first: agent, task, state, what woke it, start,
+  duration, cost. From `GET /api/companies/{id}/heartbeat-runs` (281 today).
+- **log** — the tail of the chosen run, from `GET /api/heartbeat-runs/{runId}/log`. This is
+  the closest thing to "watching Pi work": the log grows while the run is live, and
+  `lastOutputAt`/`lastOutputBytes` on the run say how fresh it is.
+
+Actions, all with the user key, all reversible:
+- `enter` on a run → its log in the log tab.
+- `p` pause, `P` resume an agent (`POST /api/agents/{id}/pause|resume`).
+- `w` wake an agent (`POST /api/agents/{id}/wakeup`).
+- `e` open its settings (see below).
+
+## Missing: working on an agent — role, model, cost
+
+Paperclip owns these, so the interface edits Paperclip, never a local file. One more panel,
+`Agents>settings`, or a tab inside `Agents>agents`:
+
+| Field | Paperclip field | Endpoint |
+|---|---|---|
+| name and job title | `name`, `title` | `PATCH /api/agents/{id}` |
+| role | `role` | same |
+| who it reports to | `reportsTo` | same |
+| model (the LLM) | `adapterConfig.model` | same, with `replaceAdapterConfig` care |
+| heartbeat on/off, concurrency | `runtimeConfig.heartbeat` | same |
+| monthly budget | `budgetMonthlyCents` | same |
+| pause / resume | `POST /api/agents/{id}/pause`, `/resume` | separate calls |
+
+Two rules that fall out of this and are not negotiable: a change to a model applies to that
+agent's **next** run, never to one in flight; and a budget change is recorded with who
+changed it, because Paperclip's audit trail is the only record we have.
+
+## Tool panels: Lazygit, Hunk, a shell, the review
+
+Both are installed on this machine and I verified the paths:
+`/run/current-system/sw/bin/lazygit` and `/etc/profiles/per-user/sam/bin/hunk`.
+
+They are **not** to be reimplemented. The proposal is one key in `Work>work`:
+
+- `t` opens a chooser: `shell · lazygit · hunk · git log · ocr`.
+- The chosen tool opens as a pane **in the current workspace**, beside the panel you were
+  reading, and takes focus.
+- `q` or `esc` closes it and focus returns exactly where it was.
+- Nothing is created until you ask, so the layout stays as it is today.
+
+This is the answer to "I thought we had Lazygit and Hunk": they are installed, they are not
+wired in, and wiring them in is one pane-opener plus a key.
+
+## The review: ocr is installed and has already run
+
+`ocr` is at `/home/sam/.local/bin/ocr`, version `open-code-review v1.13.6`. It is in the
+project's `bin/merge` and `bin/review`, and it has blocked a real merge: on `AUD-165` it
+reported a critical finding (`rm -rf "$HOME/tmp"` deleting `/tmp` when `HOME` is empty) and
+the merge was refused. The Repair screen once said "not on the path" because a pane started
+by TUIOS gets a smaller PATH than a shell; that was fixed by looking in the usual places.
+
+Where it belongs in the interface: a **review panel inside `Work>work`**, showing the last
+verdict for the chosen task, its findings, and the blocking ones in red. The merge stays a
+command (`bin/merge`), because a merge is a decision with a lock, not a keystroke.
+
+## Mouse-1 and Switch
+
+Measured just now: **not installed** — no `mouse`, `mouse1` or `switch` binary on this
+machine, and nothing obviously serving them locally. So nothing can be built on them yet
+without adding software first.
+
+Where they would fit if added: Mouse-1 is a small probability model that answers typed
+questions; Switch turns a state into those questions. The honest use in this factory is
+**routing and judgement that must be cheap and repeatable** — "is this task ready", "does
+this comment answer the question", "which agent should take this" — rather than prose
+generation. That is a later milestone, after agents and the review panel, and it needs a
+decision about installing both, plus a measurement of whether they are better than the
+existing cheap model already configured for agents (`omni/deepseek/deepseek-v4-flash`).
+
+## The order I propose
+
+1. **Agents workspace** — roster, runs, log. This is the missing view of Pi working, and it
+   is read-only, so it cannot break anything.
+2. **Agent settings** — role, model, budget, pause/resume. First write surface aimed at
+   agents rather than tasks.
+3. **Tool panels** — `t` opens Lazygit, Hunk, a shell, `ocr` in the current workspace.
+4. **Review panel** in `Work>work` — the last verdict and its findings, beside the diff.
+5. **Mouse-1 / Switch** — only after the above, and only after they are installed and
+   measured.
+
+Each of the first four is one pane, one program, no change to the working layout. Nothing in
+this list requires splitting workspaces again.