Skill and extension picker for Paperclip agents; session notes and cleanup plan

docs/SESSIONS.md

@@ -0,0 +1,73 @@
+# 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.