# 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.