# cross-agent-status

**Purpose.** Point-in-time snapshot of pending cross-agent messages across
every project on this machine. Run from any terminal. No daemon required.

This is the user-pull layer of the cold-start story — `cross-agent-watch`
pushes notifications, `cross-agent-status` lets the user query.

## Usage

```
cross-agent-status [--json] [--projects-glob <glob>]
```

No args required.

### Flags

| Flag | Default | Purpose |
|---|---|---|
| `--json` | off (table) | Output as JSON for scripting. |
| `--projects-glob <glob>` | `~/projects/*/inbox/from-agents/` | Override which directories to scan. |

## Output

### Default (table)

```
$ cross-agent-status
project           pending  most-recent
career            0        —
claude-templates  0        —
clipper           0        —
homelab           1        20260427T085611Z-from-career-question.org (3 min ago)
finances          0        —
... (other 9 projects)
```

Sort: pending-first, then alphabetical.

### `--json`

```json
{
  "scanned_at": "2026-04-27T04:13:00-05:00",
  "projects": [
    {
      "name": "homelab",
      "pending_count": 1,
      "most_recent": {
        "filename": "20260427T085611Z-from-career-question.org",
        "age_seconds": 180
      }
    },
    ...
  ]
}
```

## Pending semantics

A message is "pending" if it sits in `inbox/from-agents/` AND no
`MESSAGE_TYPE: release` exists for the same `CONVERSATION_ID` after it.

Concretely:

1. Scan each project's `inbox/from-agents/` for `.org` files.
2. Group by `CONVERSATION_ID` from frontmatter.
3. For each conversation, find the highest-`#+TIMESTAMP` message with
   `MESSAGE_TYPE: release`.
4. Messages with `#+TIMESTAMP` after that release (or in conversations with no
   release) count as pending.

Files without parseable frontmatter are counted as pending and noted in the
output (single warning row per project).

## Failure modes

| Symptom | Likely cause | Fix |
|---|---|---|
| Project missing from output | Project's `.ai/` directory exists but `inbox/from-agents/` does not | Created lazily on first cross-agent message; `mkdir -p` to surface in output. |
| All projects show "0 pending" but you know one has messages | Glob misresolved, OR all messages are post-release | `cross-agent-status --projects-glob` with explicit path to confirm. |
| Warning row "N files unparseable in <project>" | Message file has invalid frontmatter | Open the file, fix or move out. |

## Performance

Scans every `.org` file in every watched directory. For Craig's setup (14
projects, single-digit messages each), runs in <100ms. If a project
accumulates hundreds of post-release messages, archive them per the persistence
guidance in the protocol spec.

## HALT awareness

Checks `~/.config/cross-agent-comms/HALT` at start. If HALT exists, prints a
prominent banner before normal output:

```
$ cross-agent-status
⚠ HALT ACTIVE — cross-agent comms paused
  Reason: investigating runaway poll loop, 2026-04-27
  HALT file: ~/.config/cross-agent-comms/HALT
  Resume with: cross-agent-resume

(snapshot continues normally — HALT does not suppress visibility)

project           pending  most-recent
career            0        —
homelab           1        20260427T085611Z-from-career-question.org (3 min ago)
...
```

Status is read-only, so it always runs. The banner ensures the user can't
miss that halt is active when checking inbox state. Reason text comes from
the HALT file's body; if empty, omit the reason line.

If the HALT file exists but is unreadable, print a warning banner ("HALT
file present but unreadable; treat as halted") and continue with normal
output.

See `cross-agent-halt.md` for the full halt mechanism.

## Examples

```bash
# Snapshot
cross-agent-status

# JSON for piping
cross-agent-status --json | jq '.projects[] | select(.pending_count > 0)'

# Single-project query
cross-agent-status --projects-glob ~/projects/work/inbox/from-agents/
```

## See also

- `cross-agent-watch` — push notifications on new arrivals.
- `cross-agent-discover` — enumerate available agents (cross-machine).
- `cross-agent-comms.org` — protocol spec.