# 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.

## Switching sessions, and what "on another machine" means

A session lives on a daemon, and a daemon runs on one machine. Where you *sit* does not matter:
a client on `.27` can drive a session whose daemon is on `.13`, and that is exactly what happens
here. So the phrase "a project on another machine" really means "a session on another daemon".

TUIOS has a verb for moving an attached client:

```
tuios call switch-session '{"name":"office","host":"nixos-desktop"}'
```

- `name` is the session to show.
- `host` may be omitted for the local daemon, or named for a machine in the client's `[hosts]`
  table. A machine that is not in that table cannot be reached this way; attach by hand then.

`Project>project` → **projects** now uses this. Every adopted project is listed with its
session, machine and folder; `enter` asks once and then switches the client in place. A
project whose session is on a daemon your client does not know is still listed, and the
confirmation says which machine it needs.