paperclip-harness/docs/NEXT.md

What is left to build

Written 2026-11-11. The interface has eight workspaces and 23 panels; the work below is what is still missing or unproven. Order is by usefulness, not by size.

Done since this list was written

• Repair>cleanup — session list with pane count and last use, space ticks, x closes after asking, protected and attached sessions refused, and a line on screen saying that ~/.pi/paperclips is not touched.
• t → pi sessions (Yazi) and t → pi resume — the two cheapest ways into the history.
• v in Work>review — starts bin/review <task> --post and the tab follows its log.
• Project>projects — the registry bin/office writes, listed with folder, machine and session; a project on another machine is shown and not offered.
• Board>needs → enter now also switches to the Reply workspace.

1. Repair>cleanup — the pane you asked for

A fourth tab in Repair>repair that lists TUIOS sessions with their pane count and last-active time, marks the ones that are attached, and kills only what you tick. Two rules it must keep:

• never touch ~/.pi/paperclips/ — those are the Pi conversations, and they are the history;
• refuse any session that is attached, and refuse paperclip-harness by name.

Measured today: 37 sessions, 21 of them from the closed project's tests (harness-demo-card-*, office-test-1*). Nothing has been killed.

2. A Pi session browser

The cheap version first: a t entry that opens ~/.pi/paperclips in Yazi, and one that runs pi --resume. Then, if that feels like a detour after a week, a read-only transcript tab in Agents>agents that reads the JSONL directly. GET /api/agents/{id}/task-sessions maps a task to its session file, so neither version has to guess.

Done: Project>projects — switching project

bin/office records each adopted project; the tab lists session, machine and folder; enter asks once and switches the client with tuios call switch-session, including to a session on another machine when that machine is in the client's [hosts] table. See docs/SESSIONS.md.

3. Project>projects — switching project

A tab listing every adopted project from a small local registry (~/.config/paperclip-harness/projects.toml: id, folder, host, session), filled by bin/office, with a key to switch. A project on another machine is shown as on .27 and not offered, because this terminal cannot open a folder that is not here.

4. Run a review from the interface

Work>review shows the verdicts already recorded. It should also be able to start one: v runs bin/review <task> --post in the background and the tab follows its log, the way Work>merge already does.

5. The old office scaffold

bin/office writes .harness/harness.toml and builds the panes. The previous project also wrote a scaffold: settings.toml, one file per role, verify.sh, the per-page notes — writing only what is missing. That is the cheapest remaining gap in the project layer.

6. Board>needs: act on a card

The needs-you panel lists what is waiting but the action still happens elsewhere. Each card should carry its own key: unblock, assign, open in Reply.

Done: costs as a chart

Project>costs draws each task's spend as a bar against the largest, so the shape of the month is visible without reading numbers. No extra API calls: the figures were already loaded.

task       state       cents  runs  share of the largest
AUD-163    done            3     3  ████████████████████████
AUD-164    done            2     2  ████████████████
AUD-159    done            1     1  ████████

Done: the office scaffold

bin/office now also writes what is missing, never overwriting: .harness/verify.sh with a comment explaining how to replace it, and .harness/NOTES.md for the person. Adopting a folder no longer leaves it without a place to say what "finished" means.

Done: memory per agent, read-only

Agents>settings ends with a line read from the agent's command and the global Pi settings:

memory and extensions
  extensions: the global set  ·  memory: pi-memctx

It claims only what it has read. A switch is a later decision, after one agent has run both ways.

7. Costs as a chart

Project>overview already draws a sparkline of runs in Go. Spend-per-day, using the same block characters or tuios.dev/plot, is the natural second chart — no TML, no web view.

8. Memory per agent

engram is installed and headroom is running as a compression proxy, but nothing in the interface shows which agent uses which. A read-only row in Agents>settings is the honest first step; a switch is only worth adding after one agent has been run both ways and measured.

9. MOUSE-1

It is a hosted API, not software: POST https://api.mouse.dev/v1/decisions with the key already in the environment. Measured facts are in docs/MOUSE-1-NOTES.md and summarised in docs/PLAN-INTERFACE.md: cold start of minutes, ~490 ms warm, stable answers at high confidence, and four proven uses — failure routing first among them.

The one place it would earn its keep here: a failed run in Agents>agents offers f, which asks "what does this failure need" with four options and records the answer, the confidence and the options on the task. A person still decides, and it never decides a merge.

Headroom: measured facts

• The tool path works: headroom-ai is now installed for Pi on .13, .27 and .51, and compress() answers from http://192.168.20.13:8787 (measured: 2809 tokens before and after for a single long user message, which headroom protects from compression).
• The provider path fails, and not for the reason first given: docker logs headroom shows LiteLLM rejecting the router's model ids, so a completion returns 502. The router answers the same request in 1.1 s. Fixing it means teaching headroom's LiteLLM the router's models.

Headroom: a tool, not a provider

The headroom-bridge extension gives an agent two tools (compress_for_agent, check_headroom). The endpoint answers (POST /v1/compress → 200). It needs the headroom-ai npm package for Pi to resolve, which is not installed; then the extensions picker can give it to one agent. As a provider it does not work here: 502 on OpenAI requests, 401 on Anthropic ones.

Headroom: blocked as a provider

A provider entry was added, tested and removed. Headroom answers 502 proxy_error to OpenAI chat requests and 401 invalid x-api-key to Anthropic ones: its backend is Anthropic and this machine has no Anthropic credential. It cannot sit in front of the agents until either headroom accepts the omni router's key, or the agents move to an Anthropic-shaped provider. The detail is in docs/PLAN-INTERFACE.md.

Done: Mouse-1 triage

bin/triage <task> [--ask next|failure] asks Mouse-1 one four-option question about a task and writes the answer, the confidence and the option meanings onto the task as a comment. Measured on AUD-162: 0.5 s warm, answer person at 0.97 confidence. The cold start reproduces: 503 after 30.5 s, then 200 in 21.7 s, so the command retries exactly once and says so.

Unproven, and worth a test

• opening a project on another machine (bin/office --host): written, never exercised;
• clicking a task row with the mouse in Board>board: the zones are wired, nobody has clicked;
• R with a pane that is not at its expected size;
• a task whose blocker is still open: does the agent stay away until it closes?

Open Paperclip tasks in this project

One: AUD-162, a leftover test task in todo from the first day. Everything else is done.