paperclip-harness/docs/SESSIONS.md

Sessions: the ones TUIOS holds, and the ones Pi writes

Two different things are called a session. Keeping them apart is most of the answer.

	TUIOS session	Pi session
what it is	a set of workspaces and panes, run by the TUIOS daemon	one conversation, written by Pi as JSONL
where it lives	inside the daemon; listed by tuios ls	~/.pi/paperclips/<timestamp>-<agentId>.jsonl
how it ends	you kill it, or it is resurrected after a restart	never; it is a file
who cleans up	nobody, automatically	nobody; files accumulate

Where to look for a Pi session — the only thing you need

~/.pi/paperclips/<timestamp>-<agentId>.jsonl      178 files on this machine

Every Paperclip run of a Pi agent writes one, named with the time it started and the agent's id. To find the one for a task, ask Paperclip rather than guess:

GET /api/agents/{agentId}/task-sessions
→ [{ taskKey, sessionParamsJson: { cwd, sessionId: "/home/sam/.pi/paperclips/…jsonl" } }]

To open one, three options, cheapest first:

1. pi --resume in any pane, and pick from Pi's own list.
2. pi --session /home/sam/.pi/paperclips/<file>.jsonl opens that exact conversation — the same flag Paperclip uses.
3. Open the folder in Yazi (~/.pi/paperclips), read or copy the file.

Two writers on one session file is the only risk, so open finished runs, or treat it as a deliberate hand-over.

The junk TUIOS sessions

Measured with tuios ls --all-hosts: 37 sessions, of which 21 are from the closed project's tests — harness-demo-card-* (18) and office-test-1* (3). The rest are yours and should stay: office, office-test-1's parent, tuios coding harness, paperclip-harness, factory, drone deeca ai, email_agent, nixos desktop 13 devops, Basketball-site, agents-tutorial, computer_hardware, computer_software, famil_home_lab, resume_projects_notes, thinkpad.

Nothing was killed: that is a destructive action and the list above is the evidence to decide on.

Proposed cleanup, in order

1. Kill the 21 test sessions, by name pattern, after printing the list:

   tuios ls --all-hosts | (parse names) | grep -E '^(harness-demo-card-|office-test-1)' \
     | xargs -n1 tuios kill-session
   

   Add a --dry-run that prints and does nothing, and require the pattern to be given explicitly, so no command can ever delete "everything that looks old".

2. A bin/prune command that lists sessions with their pane counts and last-active time, marks anything not seen for N days, and refuses to touch a session that is attached.

3. A rule for tests: every test that creates a session kills it in the same script. The previous project's tests left 21 behind precisely because creating was one command and cleaning up was not.

4. Do not prune paperclip-harness. Its nine panes are the layout; R in Repair rebuilds them. If a pane is stray, close it by name — the layout is rebuilt from bin/board, not from whatever happens to be open.

What is not junk, and looks like it

• office has 32 panes and is attached: it is the person's main session.
• factory, office-test-1 and the harness-demo-* sessions have one pane each and are detached — they are the junk, but they are indistinguishable from a deliberately parked session by age alone. Hence the pattern, and hence the confirmation.