paperclip-harness/docs/PLAN-INTERFACE.md

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.