self-write: the seat's own identity writer, its fence, and a seat-local lock (#1152)

[fujibee]

Part of #1152. (#1137, the action hook's record lacking project and type, is handled separately; this path refuses to write a record without them and tests that.)

What this adds

The one path by which a seat writes its own identity cells, the lock that keeps two writers on one seat from interleaving, and the entry that reaches it: fix, which takes no arguments and writes only where the seat has proved itself to be.

scripts/lib/self-write.sh

agmsg_self_write <team> <agent> <ref> <owner> writes, for the calling seat only, in this order and each independently:

• record — the placement record, now with a fourth TAB field fence=<instance>:<terminal_id> (existing readers select columns with awk/cut, so the field is invisible to them). Required: it is the only cell a seat's reachability runs through.
• label + key — one terminal_name call, two separate readbacks through terminal_team_observe.
• session — <rename_cmd> <team>-<agent> typed once, unconditionally, when the pane's input is ready. There is no pre-read skip, stored mark or process flag: every one of those was a stale value keyed to skip a needed rename. The title before is a baseline for the delta only.

The pane arrives here already proved (by fix, below); the writer does not derive or verify it. team and agent come from the seat's own actas; no argument may name another seat. The library holds no search, no candidate generation and no other-seat resolution, and a test pins that by name.

Every fact is one output line (seat=… fence=… record attempt=… readback=… … policy=…), also written last and atomically to run/self-write-done.<team>__<agent>. policy is decided here only: accepted (record verified), accepted_unverified (record written, readback unavailable), otherwise repair_incomplete. Decorations never change it.

fix: scripts/fix.sh → scripts/lib/self-fix.sh

fix takes NO arguments — from a poke, a person, or the skill. A location handed in from outside is the defect this replaces: measured live, a seat whose label had been broken resolved itself through an inherited environment into another seat's pane and wrote that pane into its own mark. So the seat establishes where it is:

1. identity — the seats whose actas lock this session owns (a lock names a role, never a pane);
2. candidate — the pane the environment names, handed to the proof as a candidate only, never as an authority;
3. proof — agmsg_self_proof (process ancestry, feat(self-proof): prove a seat's process is bound to a pane, or say why not (#1152) #1154): proved / disproved / undetermined / unsupported;
4. fallback — when the proof did not say proved and the emit-and-observe locator agmsg_token_locate_self (feat(team): add the self-locate-by-token matching core (#1124) #1188) is present, it runs under the same four-state contract;
5. write — only on proved, through agmsg_self_write, with the proof's pane qualified by the instance the observation went through. Anything else is one line with state= and reason= and nothing written. Any argument is refused by name.

Exit 0 when every held seat was written, 2 when at least one was left unwritten, 1 on refusal. SKILL.md dispatches fix.

The fence: terminal_fence <id> (new optional driver op)

Pane ids repeat across terminal instances (two herdr sessions both have a w1:p2; tmux has one id space per socket), so a pane id alone can name a live pane in another instance — measured on 2026-09-11 when a repair resolved in one session landed in another's pane. Each generation reads <instance, terminal_id> once, stores it in the record, and re-reads it before every later mutation; a difference in either half refuses that mutation visibly (skipped:fence_mismatch:<field>).

• herdr: instance = the session the driver talks to, terminal_id = the pane's server-side id (unique across sessions, 52 panes / 0 crossings; changes across a restart, so a stored fence expires with the server and refuses instead of writing into whatever now sits at that id).
• tmux: instance = the socket, terminal_id = the pane's shell pid.
• plain: record-only by ruling, not by capability — label, key and session are reported as skipped:unsupported:plain_record_only even where an emulator adapter could name or type, because the emulator's identity is not evidence. The fence observes the tty of the seat's own CLI process (the pid in the owner token, via ps -o tty=), never the environment; it refuses by name when the process has no controlling tty, sits on a different tty than the locator names, or no pid was given, and the writer then writes nothing. The anchor is the tty plus the owning pid and its start time, so a recycled /dev/ttysNNN cannot pass as an old match; the emulator half is carried as delivered and is not evidence. Label, key and session are reported as unsupported in the driver's own words (feat(terminal): address measured plain emulators #1163).

This is best-effort safety, not an atomic fence. The read and the keystroke are separate calls, so a pane closed and reused between them is not caught; a real fence needs the terminal to compare-and-type. What it removes is the accident that actually happened.

scripts/lib/self-write-lock.sh and the shared lock core

The whole generation runs under a seat-local single-flight lock (run/self-write.<team>__<agent>.lock), separate by name, path and API from the leader/seat exchange lock so that deleting one never deletes the other. A second writer sees busy:<owner>, never a silent drop.

To avoid a second producer of the three-valued verdict, the actas lock's core (write, read back, hard-link publish; verdict; positive-dead-only reclaim) now takes a lock path and owner, and actas_lock_* are wrappers over it. Two defects surfaced while extracting it and are fixed for both locks:

• the reclaim mutex was a bare mkdir/rmdir with no owner, so a reclaimer dying between them left it forever and every later claim spun into unknown:reclaim_contended. It is now an owner-bearing lock of the same kind; a dead reclaimer's mutex is displaced by an atomic rename to a claimant-unique tombstone and settled there — removed only if its owner is still positively dead, linked back otherwise. A failed restore link is not read as "someone published into the gap": the destination is re-read, and only a mutex actually read there lets the tombstone go; otherwise the tombstone is kept and every later claim stops with a named unknown instead of treating the gap as free.
• the mutex helpers printed a verdict and also returned 1, so a set -e caller of the claim loop died inside it before any verdict was printed. They return 0 on every verdict; the line decides.

The spawn-time boot witness is carried

spawn records a plain window with the boot shell's pid and start time (boot=, boot_start=), and forced teardown needs them once the CLI's pid is gone. The first self-write generation carries exactly that pair into its own fence when the seat's existing record names the same emulator and tty and both keys are complete; unknown keys are never copied, and the fence re-reads compare against the driver's own anchor, not the carried one.

Placement-record readers take the fourth field

Eight readers split the record with read -r ref proj type; read puts everything after the third TAB into the last variable, so the fence field landed in type and despawn --force handed that to reset. Each reader now takes a fourth variable, a despawn control pins it, and a static test requires it of every placement-record read in scripts/ (it found the eighth reader, in watch.sh). The fence is re-read right after the record lands and before the record line is printed; a witness that moved is named on the record and the generation is not accepted.

Tests

• tests/test_self_write.bats (14): the real herdr driver against a fixture-driven fake herdr that logs every argv. Accepted path; already-named session gets one rename and reads matched_no_delta; decorations failing leave policy=accepted; missing record fields → repair_incomplete and no record (A placement record written by the action hook has no project or type, and arrange refuses it #1137); record written but unreadable → accepted_unverified; terminal_id changing after the record refuses label/key/session and keeps the record's fence; unreadable fence or no session → nothing written; bad ref / plain ref / empty owner refused; a live writer → none:busy; no pane other than the one handed is touched; no derivation/search by name.
• tests/test_self_write_lock.bats (32) + tests/test_actas_lock.bats (46): the six lock controls (other process, pid reuse, orphan temp, empty lock, crash mid-cell, exact-owner release), the reclaim-mutex controls (live holder, dead holder, a holder killed while holding via the real code, empty/unreadable/undecidable kept, pid reuse, a dead-then-undecidable flip restored), the tombstone controls (restore link failing with the destination absent / superseded / unreadable, a displacer dying between rename and settle), and an errexit control calling the claim loop as a bare statement in a bash -e child.
• The tmux "every id-taking op reaches the owning server" sweep now includes terminal_fence.
• tests/test_self_fix.bats (13): the proof, the fallback and the writer are spies, and the file pins what reaches the writer and what never does — any argument refused; no seat for the session; proved → the writer gets the seat, the socket-qualified locator and the lock's owner token; disproved/undetermined → nothing written and the reason named; the fallback runs only when the proof did not prove, its own undetermined is named, and its absence is fallback_absent; no candidate in the environment → the proof is not asked; two held seats each written and another session's lock ignored; herdr with no socket and tmux socket-in-ref locators; and a missing TMUX under a real set -u shell, where an unguarded read would have killed the substitution and produced a seat line with an empty state.

Mutations, one test each, run by hand: eight on fix (arguments accepted, write on any state, environment as authority, fallback ignored, another session's lock counted as ours, fallback state unchecked, fallback run even when proved; the eighth, dropping the instance, is equivalent because the locator grammar refuses an empty instance and the bare-ref test pins that path), eight on the writer (fence check removed, unavailable counted as accepted, readiness ignored, missing fields still written, ref grammar skipped, lock skipped, a pre-read match skip added, fence field dropped) and eleven on the locks. Each reddens only its own test; the clean tree is green.

Known gaps, stated: the tmux fence is exercised only by the sweep, not by a fake; the title readback reuses agmsg_cli_session_observed, whose screen-scraping form still takes the first matching line, so for a type whose name lives on screen the session cell should be read as undecided rather than trusted — that is the next change, not this one.