1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
# 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.
|
