Merge commit '69c5e4ace81586c05dea6a9a3afd54dafa61a73b' as 'claude-templates'

1 files changed, 139 insertions, 0 deletions

diff --git a/claude-templates/.ai/scripts/cross-agent-comms/cross-agent-status.md b/claude-templates/.ai/scripts/cross-agent-comms/cross-agent-status.md
new file mode 100644
index 0000000..070330c
--- /dev/null
+++ b/claude-templates/.ai/scripts/cross-agent-comms/cross-agent-status.md
@@ -0,0 +1,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.