aibtcdev/inscription-queue-watcher

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.

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

Output:

{
  "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.

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):

{
  "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.

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.