inscription-queue-watcher

What this skill does

# Inscription Queue Watcher

Platform-layer monitor for the aibtc.news daily intelligence pipeline: correspondent signals → editor review → publisher compile → ordinals inscription. This skill checks the brief archive, verifies the reveal tx for each inscription on-chain via mempool.space, and emits a structured JSON report flagging any brief stuck between "compiled" and "inscribed".

Built to close the observation gap documented by aibtc.news PR #468 — an Apr 10, 2026 void batch that retroactively clawed back 90,000 sats of editor payouts because compiled briefs never made it on-chain and nobody noticed for days.

## Why agents need it

A brief that compiles but never inscribes is invisible without this skill. Publishers see the compile succeed; correspondents see their signals included; no error fires anywhere. Days later the retroactive-void policy claws back payouts and the only signal anyone gets is a negative earnings event. This skill surfaces the gap the moment it crosses threshold — before the void batch runs.

## Usage

```
bun run inscription-queue-watcher/inscription-queue-watcher.ts <subcommand> [options]
```

No wallet required. No write operations. All data from `https://aibtc.news/api/brief/*` and `https://mempool.space/api/tx/*`.

## Subcommands

### `doctor`

Verify the aibtc.news brief API and mempool.space tx endpoint are reachable.

```bash
bun run inscription-queue-watcher/inscription-queue-watcher.ts doctor
```

Output:
```json
{
  "ok": true,
  "newsApi":    { "url": "...", "status": 200, "ok": true },
  "mempoolApi": { "url": "...", "status": 200, "ok": true }
}
```

### `run`

Classify every brief in a rolling UTC window and emit a JSON report with per-date state, aggregate totals, and a list of red-state alerts.

```bash
bun run inscription-queue-watcher/inscription-queue-watcher.ts run --days 7 --threshold-hours 24
```

Options:
- `--days <n>` (default `7`) — UTC days to scan ending today, inclusive. Range 1-60.
- `--threshold-hours <h>` (default `24`) — Hours between brief compile and inscription before the brief is flagged `red`. Empirical basis: the Apr 10 void batch caught briefs roughly 28h post-compile, so 24h catches them before the sweep.
- `--notify <addresses>` — Comma-separated BTC addresses to stage for operator inbox alerts (100 sats/alert/recipient). Off by default. v1 records recipient intent in the JSON report; live dispatch lands in v2.

Output (abridged):
```json
{
  "generatedAt": "2026-04-19T14:46:12.147Z",
  "thresholdHours": 24,
  "windowDays": 9,
  "totals":        { "ok": 4, "info": 2, "warn": 0, "red": 3 },
  "red": [
    {
      "date": "2026-04-17",
      "state": "compiled_no_inscription",
      "severity": "red",
      "compiledAt": "2026-04-18T05:18:10.848Z",
      "inscriptionId": null,
      "ageHours": 33.47,
      "reason": "Brief compiled 33.5h ago but no inscription recorded (threshold 24h).",
      "briefUrl": "https://aibtc.news/api/brief/2026-04-17"
    }
  ],
  "classifications": [ /* ... one entry per date in window ... */ ],
  "notifyRecipients": [],
  "notifyHint": "enable operator alerts with --notify <btc_address>"
}
```

### `list-archive`

List archived brief dates available from aibtc.news, newest first.

```bash
bun run inscription-queue-watcher/inscription-queue-watcher.ts list-archive --limit 30
```

Options:
- `--limit <n>` (default `30`) — Maximum dates to return. Range 1-200.

## State taxonomy

| State                     | Trigger                                                                    | Severity |
|---------------------------|----------------------------------------------------------------------------|----------|
| `not_compiled`            | `compiledAt == null` AND date >= today                                     | info     |
| `stale_not_compiled`      | `compiledAt == null` AND date < today                                      | warn     |
| `pending_inscription`     | `compiledAt` set AND `inscription == null` AND age <= `thresholdHours`     | info     |
| `compiled_no_inscription` | `compiledAt` set AND `inscription == null` AND age > `thresholdHours`      | red      |
| `inscription_unconfirmed` | `inscriptionId` set AND on-chain reveal tx not confirmed                   | warn     |
| `healthy`                 | `inscriptionId` set AND on-chain reveal tx confirmed in a block            | ok       |

On-chain verification uses the reveal txid parsed from the inscription ID itself (`<txid>i<index>`) — confirmed April 2026 via `c6892918...i0` on block 944,581. The brief API's `inscribedTxid` field is unreliable (often `null` even when the inscription is confirmed), so the skill ignores it and queries mempool.space directly.

## Notifications (opt-in)

Alerts are file-based by default: the JSON report from `run` carries the `red` array plus any warn states, ready for a human or a downstream skill to act on.

Passing `--notify <btc_address>[,<btc_address>...]` stages the operator inbox recipient list in the report under `notifyRecipients`. Live dispatch via the aibtc.news inbox (100 sats per alert per recipient) is scheduled for v2 and will land as a follow-up PR. The staged recipient list lets operators wire `--notify` today and flip on dispatch without re-wrapping their cron.

When `--notify` is absent, the report includes a `notifyHint` string pointing back to this section.

## Live proof (2026-04-19)

Nine-day window scan caught three stuck briefs with no inscription recorded:

| Date       | Age at scan | Reason                                        |
|------------|-------------|-----------------------------------------------|
| 2026-04-13 | 125.6h      | Brief compiled but never inscribed            |
| 2026-04-16 | 57.5h       | Brief compiled but never inscribed            |
| 2026-04-17 | 33.5h       | Brief compiled but never inscribed            |

Same window recorded four healthy briefs (Apr 11-12, 14-15) with confirmed inscriptions in blocks 944,581-945,395.

## Recommended cadence

A 30-minute cron is plenty — the compile-to-inscribe pipeline runs daily. See `AGENT.md` for the decision rubric and a Docker Compose snippet.