sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

TUIOS runbook: the environment is not tmux, and how sessions start on .13/.27/.51

Browse Source 
The handover named TUIOS but never said plainly that it is not tmux, how a session is
created on each machine, that workspaces vanish when empty and renumber, that TUIOS keeps
h/j/k/l in window mode, or how to drive a pane from a script. All of it is now in
docs/TUIOS-RUNBOOK.md, referenced first in AGENTS.md and README.
This commit is contained in:
sam
2026-11-10 11:31:10 +11:00
parent d89479bcf1
commit 4e2eb5d2dd
4 changed files with 113 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
docs/TUIOS-RUNBOOK.md Normal file
View File

@@ -0,0 +1,100 @@
# How this runs: TUIOS, not tmux
Read this before writing any code or starting any session. Everything here was measured on
this setup; the commands are real.
## The environment is TUIOS
The terminal multiplexer on these machines is **TUIOS**, not tmux. There is no tmux session
to attach to, and a design that assumes tmux will not work. TUIOS calls its groupings
**workspaces**, and each split inside a workspace is a **pane**. A pane is a real terminal
(its own PTY) running a program.
Consequences that have already cost us two days:
1. **A workspace with no panes is deleted, and the rest are renumbered.** Never hold a
workspace number. Always resolve a workspace by name at the moment you use it.
2. **A page must keep one pane that never exits**, or the page vanishes. This is why every
screen in this project has a permanent pane.
3. **TUIOS owns part of the keyboard.** In window-management mode it keeps `h j k l`, `z`
and `n`. A program only receives keys in terminal mode, entered with `i` or `Enter`, and
you leave window mode with the prefix key then `Esc` (default prefix `Ctrl+B`).
4. **A resize reaches the program as a normal terminal resize** (SIGWINCH). Handle it. Do
not hardcode sizes.
## The machines
| Name | Address | Reachable how |
|---|---|---|
| `.13` `nixos-desktop` | `192.168.20.13` | headless, hosts the work and the Paperclip server; also reachable over the web |
| `.27` `sam-4screen-desktop` | `192.168.20.27` | local only |
| `.51` `sam-thinkpad` | `192.168.20.51` | local only |
`.13` is the machine that hosts work. `.27` and `.51` are where a person sits. Any machine
can drive any other over ssh, but ssh needs a key already installed
(`ssh-copy-id 192.168.20.13` once if it ever asks for a password).
## Starting a session
Session creation needs a real terminal. Measured: `tuios new` and `tuios attach` both fail
with "Standard output is not a terminal" when run from a script. So the person creates the
session, once, in a terminal:
```
# on .27, to create a session that lives on .13
tuios new --host nixos-desktop cookie
# on the machine that owns the folder, plainly
tuios new cookie
```
Then inside a pane of that session, on the host where the folder lives:
```
cd ~/src/cookie
```
Rules that follow from this:
- The session lives on one machine. The folder lives on one machine. Use the same one.
- Inside the session, on the host that owns the folder, nothing else is needed. No `--host`.
- `--host` is only for acting on a *different* machine from where you typed the command.
## Reading and driving a session from a script
```
tuios list-sessions
tuios list-workspaces -s cookie --json # number and name of each workspace
tuios list-windows -s cookie --json # panes, their workspace and their name
tuios new-window NAME -s cookie --workspace "<number>" --cwd <dir> --no-focus --keep-open -- <command...>
tuios capture-pane -s cookie -w <window-id> # what the pane shows now
tuios send-keys -s cookie -w <window-id> <Key> # drive a program in a pane
tuios close-window <window-id> -s cookie
```
The colour codes in `list-windows` output wrap the name, so match on the stripped text.
Anything matching a bare name must strip escape sequences first — a plain ` name ` match
fails and made a live session look absent.
## What this means for our four screens
Each screen is a pane in its own workspace, named for what it shows. The Go program draws
inside the pane it is given; it never owns the whole terminal. A screen that needs the
whole width is a pane that has been zoomed, not a separate mode.
When a screen is started, it is started with the project and the session in its
environment, so it knows what to read. When it is started twice, the second start must
adopt the existing pane rather than create a duplicate.
## Testing an interface change
A test in a plain terminal, or in tmux, proves only that the program draws. TUIOS owns part
of the keyboard and forwards mouse clicks relative to the pane, so the real check is:
```
tuios new-window harness-check -s "$TUIOS_SESSION" --no-focus --keep-open -- /tmp/harness-bin
tuios capture-pane -s "$TUIOS_SESSION" -w harness-check
tuios send-keys -s "$TUIOS_SESSION" -w harness-check Down --repeat 2
```
If the pane shows what you expect after the keys, it works where it will be used.