Merge commit '69c5e4ace81586c05dea6a9a3afd54dafa61a73b' as 'claude-templates'

1 files changed, 134 insertions, 0 deletions

diff --git a/claude-templates/.ai/scripts/cross-agent-comms/cross-agent-halt.md b/claude-templates/.ai/scripts/cross-agent-comms/cross-agent-halt.md
new file mode 100644
index 0000000..b817fbc
--- /dev/null
+++ b/claude-templates/.ai/scripts/cross-agent-comms/cross-agent-halt.md
@@ -0,0 +1,134 @@
+# cross-agent-halt
+
+**Purpose.** Failsafe stop for all cross-agent activity on the local machine
+(or, with `--tailnet`, across all configured peers). Creates the HALT file
+that every component in the protocol checks; within one polling cadence
+(~5 min) all polling, sending, watching, and receiving stops.
+
+This is the user's emergency brake. Use when something is misbehaving and
+visiting individual sessions is too slow.
+
+## Usage
+
+```
+cross-agent-halt [reason] [--tailnet] [--no-stop-watcher]
+```
+
+### Positional argument
+
+| Position | Meaning | Example |
+|---|---|---|
+| 1 | Optional human-readable reason for the halt. Written into the HALT file's body. Helps future-you remember why you stopped things. | `"investigating runaway poll loop, 2026-04-27"` |
+
+### Flags
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--tailnet` | local only | Propagate halt to every peer in `peers.toml` via SSH over Tailscale. |
+| `--no-stop-watcher` | (stops watcher) | Skip stopping the `cross-agent-watch.path` systemd unit. Useful if the watcher is intentionally separate from comms (rare). |
+
+## Behavior
+
+### Local halt (default)
+
+1. Write the HALT file: `~/.config/cross-agent-comms/HALT`. If a `[reason]` was
+   passed, write it as the file's body. Otherwise the file is empty (existence
+   alone triggers halt).
+2. Stop the watcher service: `systemctl --user stop cross-agent-watch.path`
+   (and the corresponding `.service` if running).
+3. Print a summary:
+   ```
+   ✓ HALT file written: ~/.config/cross-agent-comms/HALT
+   ✓ Watcher service stopped (cross-agent-watch.path)
+   - In-flight sends will complete their current rsync step (~seconds), then
+     stop. New sends are blocked.
+   - Active agent polling sessions stop within one cadence (~5 min).
+   - Use `cross-agent-resume` to clear HALT.
+     Per-session polling does NOT auto-resume — you re-engage each session by
+     telling its agent to resume polling.
+   ```
+4. Exit 0.
+
+### Cross-tailnet halt (`--tailnet`)
+
+1. Apply local halt steps 1-2 first.
+2. Read `peers.toml` for the list of remote machines.
+3. For each peer, SSH and write the HALT file:
+   ```
+   ssh <user>@<host> "echo '<reason>' > ~/.config/cross-agent-comms/HALT && \
+                       systemctl --user stop cross-agent-watch.path"
+   ```
+4. Track per-peer success/failure. Print results:
+   ```
+   Halting velox.local       ✓ (HALT file written)
+   Halting bastion.local     ✗ (ssh exit 255: no route to host)
+   Halting locally           ✓ (HALT file written)
+
+   PARTIAL HALT: 2/3 machines halted. bastion.local needs manual halt.
+   ```
+5. Exit 0 if all peers halted; exit 1 if any peer failed (so scripts can
+   detect partial halt). The local halt always succeeds — even on `--tailnet`,
+   if remote peers fail, local is still halted.
+
+## What "halt active" means for each component
+
+| Component | Behavior under HALT |
+|---|---|
+| `cross-agent-send` | Refuses to send. Exits 5 with "halt active; remove ~/.config/cross-agent-comms/HALT to resume." Checks HALT at start AND between each retry/rsync step, so an in-flight send completes its current step then stops. |
+| `cross-agent-recv` | Refuses to verify or dedup. Exits 5 with same message. Inbound files are **left in place** — not moved, not rejected — so resume picks them up cleanly via cold-start. |
+| `cross-agent-watch` | Continues running but suppresses notifications. Logs each event with `(suppressed by HALT)` so the operator can see what would have fired. |
+| `cross-agent-status` | Prints prominent `⚠ HALT ACTIVE` banner before normal output. Continues to enumerate (read-only). |
+| `cross-agent-discover` | Same banner. Continues (read-only). |
+| Agent polling loops | Check HALT on every wake. If set: write a final `progress` note to any active conversation ("HALT fired locally; pausing"), surface "(HALT active; cross-agent comms paused)" in every user response, and stop rescheduling. Polling decays naturally within one cadence. |
+| Conversation initiator | Refuses to write sequence 1 of any new conversation. Surfaces refusal to user. |
+| Startup workflow (Phase A) | Checks HALT at session boot. If set, surfaces immediately and skips cross-agent inbox checks. |
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `~/.config/cross-agent-comms/HALT` already exists | Halt was already active | OK — running halt again refreshes the reason text. Safe. |
+| `systemctl --user stop` fails | Watcher service not installed, or systemd not available | The HALT file is still written — components that check HALT will still stop. The systemctl failure surfaces as a non-fatal warning. |
+| `--tailnet` halts some peers but not others | One or more peers unreachable | Exit 1 with per-peer status. Manually halt the unreachable peers (visit each machine, `touch ~/.config/cross-agent-comms/HALT`), or fix the network and re-run. |
+| Permission denied writing the HALT file | `~/.config/cross-agent-comms/` doesn't exist or is owned by another user | `mkdir -p ~/.config/cross-agent-comms/`; check ownership. |
+
+## What halt does NOT do
+
+- Does not kill running Claude sessions. Polling stops within ~5 min, but the
+  session itself stays alive and can be re-engaged after resume.
+- Does not delete pending messages. Inbound files in `inbox/from-agents/`
+  remain; they get processed when polling resumes.
+- Does not abort in-flight rsync push mid-byte. Atomic-write semantics
+  guarantee in-flight messages either complete cleanly or leave only `.tmp.*`
+  files (which receivers ignore).
+
+## Examples
+
+```bash
+# Quick halt with no reason
+cross-agent-halt
+
+# Halt with a memo
+cross-agent-halt "runaway poll loop in homelab session, debugging"
+
+# Halt all tailnet peers + local
+cross-agent-halt --tailnet "shutting down for system update"
+
+# Halt protocol comms but leave the watcher service running
+cross-agent-halt --no-stop-watcher
+```
+
+## Recovery
+
+Always pair with `cross-agent-resume` when the situation is resolved:
+
+```bash
+cross-agent-resume                # local
+cross-agent-resume --tailnet      # all peers
+```
+
+## See also
+
+- `cross-agent-resume` — counterpart that clears HALT.
+- `cross-agent-status` — see HALT state at a glance.
+- `cross-agent-comms.org` — protocol spec, `* Halt mechanism` section.