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