AGENTS.md

1# AGENTS.md — Terminal Daemon
2 
3## Endpoint Ownership: Who May Touch the Socket Path
4 
5Two invariants govern the daemon's canonical socket path. Read this before changing anything that
6links, renames, unlinks or stats it — or that treats its existence as evidence a daemon is running.
7 
8> **Only a daemon publishing itself onto the canonical endpoint may mutate that directory entry,
9> and only by replacing an entry it has itself just proven dead.**
10>
11> **No actor removes a name it did not create.**
12 
13**Why it exists.** `net.Server.close()` unlinks the pathname it bound with no ownership check, so a
14departing daemon deleted whichever socket then sat at the canonical path — including a live
15replacement's. The replacement stayed alive hosting PTYs no client could reach, which reads to the
16user as terminals that accept keystrokes and never run them. Seven review rounds against the older
17"launcher reclaims a dead process's name" shape produced twenty-three defects, all the same
18interleaving: a third party observing liveness at T and acting on the directory entry at T+1.
19 
20**The protocol** (`daemon-endpoint-ownership.ts`): bind a private `.p<hex>` name → try an exclusive
21`link` → on `EEXIST` prove the incumbent dead by connecting → re-check the entry hasn't changed
22hands → probe once more → `rename` in one syscall → verify we kept it.
23 
24## Traps That Already Cost Us
25 
26- **Never collapse "can't tell" into "dead."** Only `connected` means occupied; only
27  `refused`/`missing` prove death. A timeout or `EPERM` proves nothing and must decline — treating
28  it as death deletes an endpoint still serving every terminal on the host.
29- **`link` first, never an unconditional `rename`.** `rename` replaces whatever it finds, so it
30  would let a starting daemon destroy a healthy one. `link` fails loudly and forces the liveness
31  question.
32- **`rename`, never `unlink`-then-`link`.** The latter leaves the name absent between two calls;
33  measured across a live handover it gapped on essentially every observation, where `rename` gapped
34  on none in ~14,500 probes.
35- **Do not identify an entry by `birthtimeMs`.** Node documents it as sometimes holding the ctime,
36  filesystems without a birth time report the epoch, and its granularity is often coarser than the
37  events it must separate. Three attempts to patch around this produced three more defects; inode
38  recycling is now settled by asking whether anything is _serving_.
39- **Do not add a sweeper.** Deciding whether someone else's leftover is safe to delete is the
40  question this design retired; the last one produced five defects, including deleting a live
41  listener's only pathname. Every actor removes its own scratch name on each non-crash path.
42- **Scratch namespaces must stay out of released builds' patterns.** Shipped versions sweep
43  `^\.b[0-9a-f]{10}$` on age alone with no liveness check, which is why the bind name is `.p`.
44  Deleting our sweeper does not un-ship theirs.
45- **Never remove the endpoint on shutdown.** A departing daemon leaves a dead entry; the next
46  publisher replaces it in one rename.
47 
48**Residual risk.** The final probe and the `rename` are two syscalls, and POSIX has no
49rename-if-target-is-inode-X. The harm is separately unreachable: a daemon never creates a session
50on an endpoint it no longer holds (`daemon-server.ts`), and it drains rather than serving on.
51