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

Startup commands: how office, project-reset and board decide the machine and the session

Browse Source 
Host resolution order, the local-machine check, the address table, when the host is
remembered, why --host appears twice when starting from scratch, the three rebuild levels,
and the six traps that produced every startup fault so far.
This commit is contained in:
sam
2026-11-12 11:25:43 +11:00
parent 9631cdda48
commit e02b04196f
8 changed files with 762 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
docs/STARTUP-COMMANDS.md Normal file
View File

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