one attempt per release, and the rule is code rather than a paragraph

The first watcher had an unbounded retry in it. A release whose deploy failed left no .done file, so the
next poll two minutes later spawned a fresh headless agent, and the one after that, all night, each one
costing money. The loop was careful and its logging was honest; the defect was structural.

It is structural because the loop is written FRESH by an agent every time one arms. A rule that lives only
in the prompt gets re-implemented from scratch each time, and the wrong implementation is the one that
looks right: test the .done file. That file only exists on success, so testing it is exactly the retry
storm.

So scripts/deploy-claim.sh owns it. `claim <version>` exits 0 once and 1 for ever after, whatever became
of the attempt that held it — a failed release is not retried, it is looked at. Handing the claim back is
`rm -rf` by a person, on purpose; a loop cannot undo its own claim, which is what makes the storm
impossible rather than unlikely.

Three choices in it worth keeping:

- `mkdir` is the claim. One atomic syscall that both tests and takes, with no window between checking and
  acting — two pollers a second apart is not hypothetical when a watcher gets restarted.
- Bash, not bun. The thing that stops a retry storm must not need a healthy checkout; a deploy that dies
  on `bun install` is precisely when it has to work.
- A version is digits and dots or it is refused. It arrives off a git tag and is concatenated into a path.

A pre-existing .done with no claim beside it still counts as deployed, so deploy/2026.08.21.01 — rolled
out by hand before any of this existed — is not re-attempted.

docs/servers.md corrected from the commander's own report, which was right and specific: on macbookpro
APPEND /opt/homebrew/bin for bun rather than replacing the PATH (this file said "do not help the PATH",
which is right for pm2 and is what made plugins:update fail there), `ls` is aliased to an eza that is not
installed, plugins:update bounces every sidecar before the plan's own restart step, and fofos cannot
publish affordances for what is probably the same ownership problem as its capabilities sync.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/servers.md

@@ -60,13 +60,27 @@ All verified, none cosmetic.
   _login_ shell does not read. Use `ssh <host> '$SHELL -ic "pm2 jlist"'`. `-lc` is **not** enough — it
   reports "command not found" on machines where pm2 is plainly running, which cost two wrong conclusions
   on 2026-08-21.
-- **On `macbookpro`, do not help the PATH.** Exporting one to reach `bun` breaks `pm2`, which is only on
-  the interactive shell's. `$SHELL -ic` and nothing else.
+- **On `macbookpro`, APPEND to the PATH for `bun`. Never replace it.** This said "do not help the PATH"
+  until 2026-08-21, and that was half right in a way that cost a deploy step: `pm2` is only on the
+  interactive shell's PATH, so replacing it breaks `pm2` — but `bun` is at `/opt/homebrew/bin/bun` and
+  `.zshrc` does not put that directory on the interactive PATH either, so `bun run plugins:update` fails
+  `command not found` before it runs a line. `export PATH=$PATH:/opt/homebrew/bin` for that one command
+  shadows nothing: `pm2` stays at `~/.local/bin/pm2` and `node` at `node@22`. Run `pm2` as a separate
+  command.
+- **`$SHELL -ic` on `macbookpro` aliases `ls` to `eza`, which is not installed.** A probe using `ls`
+  reports a missing file that is plainly there. Use `command ls`, or a non-interactive shell for file tests.
 - **The git remotes differ.** `fofos` pulls over HTTPS; the others over SSH. Never assume a URL — pull in
   place.
 - **A "dirty tree" means TRACKED changes.** `git status --porcelain` counts untracked files, and a stray
   script a fast-forward could never touch is not a reason to skip a host. Use `--untracked-files=no`.
 - **`macbookpro` is a laptop.** It may be asleep. Unreachable is a skip with a note, not a failed deploy.
+- **`bun run plugins:update` restarts sidecars itself**, printing `sidecar: started` per plugin — on
+  `alpha` that is twelve processes bouncing during the plugins step, before any restart the plan asked for.
+  Not a fault, but a deploy report that lists only `officer` under "restarted" is understating what moved.
+- **`fofos` cannot sync its capabilities**, and could not publish gitea affordances on 2026-08-21:
+  `dubious ownership` from git and `EACCES … mkdir '…/capabilities/affordances/officerdev'`. Both point at
+  that capabilities checkout being owned by somebody other than `pastilhas`. Deliberately not papered over
+  with a `safe.directory` entry until somebody has run one `stat` on it. **Unexplained.**
 
 ## Not platforms — ignore for now