aboutsummaryrefslogtreecommitdiff
path: root/.ai/scripts/cross-agent-comms/cross-agent-discover.md
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-06-16 23:40:42 -0500
committerCraig Jennings <c@cjennings.net>2026-06-16 23:40:42 -0500
commite1933fe685a3e15d001552537df90e33ba00b83a (patch)
tree4b6435152b6605a96c0cc7a3f3b1dcadd4fc6a02 /.ai/scripts/cross-agent-comms/cross-agent-discover.md
parent4e2db8f20a259d43d2198b120ac32660298d0d63 (diff)
downloadrulesets-e1933fe685a3e15d001552537df90e33ba00b83a.tar.gz
rulesets-e1933fe685a3e15d001552537df90e33ba00b83a.zip
refactor: remove unused cross-agent-comms subsystem
Nothing used the cross-agent message system (send/recv/watch/status/discover/halt/resume over the inbox/from-agents/ file-IPC protocol). Every cross-project handoff goes through inbox-send instead. I removed the scripts, READMEs, workflow, tests, INDEX entry, the three startup.org wirings, and the legacy bin symlinks, then repointed helper-mode's escalation to inbox-send and noted the removal in the generic-agent-runtime spec.
Diffstat (limited to '.ai/scripts/cross-agent-comms/cross-agent-discover.md')
-rw-r--r--.ai/scripts/cross-agent-comms/cross-agent-discover.md155
1 files changed, 0 insertions, 155 deletions
diff --git a/.ai/scripts/cross-agent-comms/cross-agent-discover.md b/.ai/scripts/cross-agent-comms/cross-agent-discover.md
deleted file mode 100644
index 95134bb..0000000
--- a/.ai/scripts/cross-agent-comms/cross-agent-discover.md
+++ /dev/null
@@ -1,155 +0,0 @@
-# cross-agent-discover
-
-**Purpose.** Enumerate available cross-agent destinations — local projects on
-this machine and remote projects on tailnet peers. Validates SSH reachability
-for cross-machine destinations before reporting them as usable.
-
-## Usage
-
-```
-cross-agent-discover [--enumerate-remote] [--no-cache] [--peer <name>]
-```
-
-No args required for the common case (local enumeration + peer reachability).
-
-### Flags
-
-| Flag | Default | Purpose |
-|---|---|---|
-| `--enumerate-remote` | off | SSH into each peer and list projects under `~/projects/*/.ai/`. Off by default because SSH adds latency; turn on when you want to see what's available on a remote machine you haven't fully configured. |
-| `--no-cache` | off | Skip the 5-minute cache; force fresh discovery. |
-| `--peer <name>` | (all) | Limit to a single peer from `peers.toml`. |
-| `--json` | off | Machine-readable output. |
-
-## Output
-
-### Default
-
-```
-$ cross-agent-discover
-Local (ratio):
- career, claude-templates, clipper, danneel, documents, elibrary,
- finances, health, homelab, jr-estate, kit, little-elisper,
- philosophy, website [14 projects]
-
-Peers (from ~/.config/cross-agent-comms/peers.toml):
- velox.local reachable (last seen 2 sec ago)
- bastion.local UNREACHABLE (ssh exit 255: connection refused)
-```
-
-### With `--enumerate-remote`
-
-```
-$ cross-agent-discover --enumerate-remote
-Local (ratio):
- ... (as above)
-
-velox.local (reachable):
- career, homelab [2 projects]
-```
-
-## Configuration
-
-Reads `~/.config/cross-agent-comms/peers.toml`:
-
-```toml
-# Each peer is a remote machine reachable via SSH (typically over Tailscale).
-
-[peers.velox]
-host = "velox.local"
-ssh_user = "cjennings"
-
-[peers.bastion]
-host = "bastion.local"
-ssh_user = "cjennings"
-```
-
-Peers entries describe machines, NOT projects. Projects are enumerated
-on-demand under `~/projects/*/.ai/` either locally or via SSH.
-
-## Cache
-
-Successful discovery results are cached at
-`~/.cache/cross-agent-comms/discovery.json` for 5 minutes. Repeated invocations
-within the window read from cache.
-
-`--no-cache` forces a fresh probe. Useful when adding a new peer or after a
-network change.
-
-## SSH reachability check
-
-For each peer, runs:
-
-```
-ssh -o ConnectTimeout=2 -o BatchMode=yes <user>@<host> true
-```
-
-`BatchMode=yes` prevents interactive password prompts — peers that don't have
-key-based auth set up are reported as UNREACHABLE.
-
-If `--enumerate-remote` is set, on success runs:
-
-```
-ssh <user>@<host> 'ls -d ~/projects/*/.ai/ 2>/dev/null'
-```
-
-## Failure modes
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Peer reported UNREACHABLE | Tailscale not connected, SSH key not authorized, host firewalled | `tailscale status`; `ssh -v <peer>` to debug. |
-| Local list is empty | Glob misresolved, or `~/projects/` doesn't exist | Check `ls -d ~/projects/*/.ai/`. |
-| `--enumerate-remote` slow | Cold cache, slow tailnet, many peers | First run is slow, subsequent runs hit cache. Use `--peer <name>` to scope. |
-| Peer unexpectedly missing from output | Not in `peers.toml`, or `peers.toml` malformed | `cat ~/.config/cross-agent-comms/peers.toml` and validate. |
-
-## HALT awareness
-
-Checks `~/.config/cross-agent-comms/HALT` at start. If HALT exists, prints a
-prominent banner before normal output:
-
-```
-$ cross-agent-discover
-⚠ HALT ACTIVE — cross-agent comms paused
- Reason: <reason from HALT file body, if any>
- Resume with: cross-agent-resume
-
-(enumeration continues normally — HALT does not suppress visibility)
-
-Local (ratio):
- career, claude-templates, ...
-
-Peers:
- velox.local reachable
-```
-
-Discover is read-only. Like `cross-agent-status`, it always runs so the user
-keeps visibility into what destinations exist regardless of halt state. The
-banner makes the halt state impossible to miss.
-
-If the HALT file exists but is unreadable, print a warning banner and
-continue.
-
-See `cross-agent-halt.md` for the full halt mechanism.
-
-## Examples
-
-```bash
-# Common: see what's available
-cross-agent-discover
-
-# Force fresh probe after network change
-cross-agent-discover --no-cache
-
-# What's on velox specifically
-cross-agent-discover --peer velox --enumerate-remote
-
-# Pipe to grep
-cross-agent-discover --json | jq '.peers[] | select(.reachable)'
-```
-
-## See also
-
-- `cross-agent-send` — uses `peers.toml` for routing destinations.
-- `cross-agent-status` — local pending messages.
-- `cross-agent-comms.org` — protocol spec, `* Limitations` section
- explains the cross-machine model.