paperclip-harness/HANDOVER.md

Handover — where this is, and why

Written 2026-11-11. This file is the one to read first after AGENTS.md. It says what exists, what was decided, what is unproven, and where everything lives. The earlier attempts are recorded at the end, on purpose: they are the evidence for why this one is shaped as it is.

The one-line version

Paperclip owns tasks, blockers, comments, runs, cost and the git worktree for every task. On top of it is one small Go program with eight screens, running as panes in TUIOS, and a set of small commands for the parts a screen should not do (merge, review, adopt a folder).

What is running now

Session paperclip-harness on the daemon at .13, eight workspaces, one pane each:

Workspace>pane	what it shows
Shell>shell	a prompt in the project folder, preceded by a box saying where everything is
Board>board	tasks by group, the chosen task, what needs you; a assign, u unblock, c cancel, / filter, t tools
Work>work	runs, change, facts, review, log, merge; n/p walk tasks, enter opens a run's log, m merges after asking, v reviews
Agents>agents	roster, runs, log, settings, skills, extensions; p/P/w pause, resume, wake; space toggles a skill or extension for that agent
Reply>reply	the task, the thread, a reply box that can also set the status
New task>new	the five-field form, what each field means, and exactly what the agent will be sent
Project>project	overview (dashboard), facts, costs with bars, settings and limits, adopted projects
Repair>repair	health checks, the live layout, the rebuild log, and session cleanup

R in any of them rebuilds the whole layout. r re-reads the data. ? lists the keys.

Commands beside the panes: bin/office <folder> (adopt, create the session, build the panes), bin/board (build or repair), bin/merge <task> (rebase, check, review, merge, re-check), bin/review <task> (the review alone), bin/triage <task> (ask Mouse-1 one question), bin/project-reset, bin/shell-banner.

The decisions that matter, and why

1. Paperclip owns the facts. Tasks, blockers, comments, approvals, runs, cost and worktrees are read from it every time and never copied. Two screens cannot disagree because there is only one record.
2. One project is one folder on one machine, remembered in <folder>/.harness/harness.toml with its session, machine and the task being watched. That file is all we store.
3. Choosing a task is one act. enter on the board writes the choice into that file and the other panes follow within a second. No messages between programs.
4. A task is finished when the agent says so; a review stage or ocr can refuse the change; a project's check.sh is a regression check at merge time, not the definition of done.
5. The merge is a decision, so it asks. m, then a dialog naming the branch and the base branch, then y. It takes a lock, so two merges cannot overlap.
6. Keys follow TUIOS's rules. TUIOS keeps h j k l z n and also [ ] tab , . = ; and the digits. Tabs are switched with ( and ); movement is arrows or j k; a bare Esc closes a box and never quits.
7. Nothing hardcodes a size. Every pane re-asks the terminal for its size on each refresh, because TUIOS can re-tile panes without the program hearing about it, and a stale size is what "broken border" always turned out to be.

What is proven, with the measurement

• Assignment wakes Pi within 0.1 s; a task went todo → in progress → done in 28 s; the comment named the commit; cost 1 cent. (docs/PAPERCLIP-API-NOTES.md)
• Worktrees are Paperclip's, once enableIsolatedWorkspaces is on: branch AUD-160-milestone-1-t2-read-hello-txt at …/.paperclip/worktrees/….
• The review gate refuses a real problem: ocr found rm -rf "$HOME/tmp" deleting /tmp when HOME is empty, and the merge was refused.
• A task with two runs shows two: AUD-166 has assignment then automation (Paperclip's corrective wake).
• Per-agent skills work: adding archify to Builder changed that agent's list and no other.
• A new project was adopted end to end today: bin/office /tmp/fresh-project-2026-11-11 created the session and built all eight panes without a person running tuios new.
• Mouse-1 answers in ~0.5 s warm; the cold start is real (503 after 30.5 s, then 200 in 21.7 s).

What is unproven

• Opening a project whose session is on another daemon (switch-session with host), because a pane is refused the right to move the person's client at all.
• Clicking a task row with the mouse: the zones are wired, nobody has clicked.
• A task whose blocker is still open: does the agent stay away until it closes?
• Headroom in front of any agent: its backend is Anthropic and this machine has no Anthropic credential, so the provider entry was removed after testing. See docs/PLAN-INTERFACE.md.

Machines, measured 2026-11-11

	.13 nixos-desktop	.27 sam-4screen	.51 sam-thinkpad
Go	1.26.5	1.26.2	missing
Nerd Fonts	384 files	98	98
Pi	0.82.1	0.82.1	0.87.1
TUIOS	0.12.1	0.12.1	0.12.1

.51 needs Go added; Pi differs between machines and is worth aligning before agents run there.

The earlier attempts, kept on purpose

Two attempts came before this one and both are still on disk, deliberately:

• ~/paseo/projects/tuios_coding_harness — plans, notes and history.
• ~/paseo/harness — the code.

They are read-only reference. When this project is finished and you are comfortable, they can be archived into a single tarball and the trees deleted. Until then they are the record of what went wrong, and you want them for your own account of the work: attempt one built an interface before anything ran, attempt two measured instead of building, and this one runs a task end to end before styling a screen. Nothing in this project was copied from them except understanding.

Where each document lives

docs/DOCMAP.md is the index. The ones worth knowing: PLAN-INTERFACE.md (the plan and the findings), WORKSPACES.md (every workspace and pane), RUNS-AND-MERGE.md (task, run, merge), TEST-PLAN.md (every key and expected result), SESSIONS.md (TUIOS sessions, Pi conversations, cleanup), NEXT.md (what is left), OPERATING-RULES.md, TUIOS-RUNBOOK.md, PAPERCLIP-API-NOTES.md, ENVIRONMENT-FACTS.md.