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

Corrected: Mouse-1 is a hosted API, not software to install. MOUSE_API_KEY is present; what is missing is a client call from our side. The old project's policy stands: triage only, never a gate, never a permit — it could order Board>needs, never decide a merge.

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.