paperclip-harness/docs/STARTUP-COMMANDS.md

The startup commands: how the system is opened, and why they look like this

The previous attempt produced four commands. They work. This explains what each does, the decisions behind them, and the traps — so a new session does not redesign them from scratch.

The four commands

office <folder>                     open a project on this machine
office <folder> --host nixos-desktop   open a project that lives on another machine
project-reset <folder>              start a project again from nothing
board                               create any missing screen in the current session

They live in ~/paseo/harness/bin and are installed as small wrappers in ~/.local/bin, so they work from any directory. They are wrappers, not symlinks: a symlink made the scripts think they lived in ~/.local/bin, which broke every sibling command they call.

What office decides, in order

1. The folder. Made absolute, ~ expanded, created if missing. Everything else hangs off this.
2. The session name. --session if given, otherwise the folder's own name. One project, one session. Not one session with many projects.
3. Which machine. In this order:
   • --host NAME if given;
   • otherwise the host remembered in <folder>/.harness/host;
   • otherwise this machine.
4. Is that machine this one? If the name resolves to this machine's hostname or one of its own addresses, it runs locally and says host: nixos-desktop (this machine). This check exists because the first version tried to ssh to the machine it was already running on, which is refused, and looked like a login problem.
5. If it really is another machine, it tests the login first (`ssh -o BatchMode=yes true`) and, only if that works, runs the same command there, then prints the attach lines for both a graphical and a terminal client.

Host names map to addresses that ssh can actually reach:

Name you type	Address used
nixos-desktop, .13	192.168.20.13
sam-4screen-desktop, .27	192.168.20.27
sam-thinkpad, .51	192.168.20.51

The first version mapped names to the literal strings .13, .27, .51, which ssh cannot resolve. That is why office used to fail with "Could not resolve hostname .13".

The host is only remembered when it is genuinely remote. A local project never gets a .harness/host file, because a stale "remote" entry is how a project starts rebuilding itself on the wrong machine.

The rule that matters for the person

The session and the folder live on the same machine. If you are typing inside the session, on the machine that owns the folder, you type office <folder> and nothing else.

--host exists for one case only: the folder is on a different machine from the one your shell is on. It is stated once, then remembered.

Why --host is stated twice when starting from scratch

Because two separate things are being created, by two different tools:

1. tuios new --host nixos-desktop cookie — TUIOS creates the session on that machine.
2. office ~/src/cookie --host nixos-desktop — the harness prepares the folder there.

Neither tool can do the other's job. TUIOS cannot create a folder project; office cannot create a session (measured: tuios new fails with "Standard output is not a terminal" when run from anything but a real terminal). Once the folder has been prepared there, office remembers the host and the second flag is never needed again.

What happens after the host is settled

1. Adopt the folder. new-project writes only what is missing: the project settings, the role files, one page note per screen, a to-do list, the verify command, the plan stubs. It never overwrites a file that exists, so running it twice is safe.
2. Check the session exists. The session table is colour-coded, so names are matched after stripping escape sequences. A plain name match fails on a live session and made a running session look absent.
3. Build the screens. Pages are created in a fixed order, and each pane is claimed in a workspace by name, never by number. TUIOS deletes a workspace whose last pane closes and renumbers the rest, so a remembered number is always wrong eventually.
4. Every page keeps one pane that never exits (its notes pane). Without it, a page disappears when its work finishes, which is exactly what made the factory seem to restart.

The three rebuild levels

board              create what is missing; close nothing
board --replace    rebuild every page, in order
board --reset      empty the session first, then rebuild     (~20 s for 26 panes)

--reset lists the panes, closes each by id, waits until the session reports zero panes, clears every workspace name, then builds. It exists because --replace on a half-built session ran out of workspace slots and left pages short.

In a running panel, R repairs every page (it runs board) and then restarts itself with the code on disk. q exits and leaves the pane.

Traps, in short

• A pane's own command must carry the project, or board rebuilds the wrong one.
• Compare host names against the machine's own addresses before ssh, or you will try to log in to yourself.
• Strip colour codes before matching anything TUIOS prints.
• Never store a workspace number.
• A page with no permanent pane will vanish.
• A repair that does not carry the project name silently does nothing.

Relationship to the new project

The four screens in docs/PLAN.md replace most of what office builds today. What survives and must be kept: the host resolution above, the "same machine for folder and session" rule, the wrapper-not-symlink detail, resolve-by-name, and the permanent notes pane per page.