wicked-bus 1.0.0 → 1.1.0

package/README.md

@@ -125,6 +125,8 @@ Auto-detects installed CLIs and copies skills. Available skills:
 | `wicked-bus/subscribe` | Consume events |
 | `wicked-bus/naming` | Event naming conventions |
 | `wicked-bus/query` | Query and debug |
+| `wicked-bus/status` | Bus health and diagnostics |
+| `wicked-bus/update` | Check for and install updates |
 
 ## Why wicked-bus?
 

package/commands/cli.js

@@ -6,9 +6,11 @@
 
 import { WBError, EXIT_CODES } from '../lib/errors.js';
 
-// Argument parser
+// Argument parser. Returns flags + positional args (anything that isn't --flag
+// or its value). Positional args are needed for subcommands like `dlq list`.
 function parseArgs(argv) {
   const args = {};
+  const positional = [];
   for (let i = 0; i < argv.length; i++) {
     if (argv[i].startsWith('--')) {
       const key = argv[i].slice(2);
@@ -17,8 +19,11 @@ function parseArgs(argv) {
       } else {
         args[key] = argv[++i];
       }
+    } else {
+      positional.push(argv[i]);
     }
   }
+  args._positional = positional;
   return args;
 }
 
@@ -28,6 +33,7 @@ function printUsage() {
     commands: [
       'init', 'emit', 'subscribe', 'status', 'replay',
       'cleanup', 'register', 'deregister', 'list', 'ack',
+      'dlq',
     ],
     global_flags: ['--db-path <path>', '--json', '--log-level <level>'],
   };
@@ -117,6 +123,11 @@ async function main() {
         await cmdAck(args, globals);
         break;
       }
+      case 'dlq': {
+        const { cmdDlq } = await import('./cmd-dlq.js');
+        await cmdDlq(args, globals, args._positional || []);
+        break;
+      }
       default:
         printUsage();
         process.exit(command ? 1 : 0);

package/commands/cmd-dlq.js

@@ -0,0 +1,102 @@
+/**
+ * wicked-bus dlq command — list, replay, drop dead-lettered events.
+ */
+
+import { loadConfig } from '../lib/config.js';
+import { openDb } from '../lib/db.js';
+import { listDeadLetters, replayDeadLetter, dropDeadLetter } from '../lib/dlq.js';
+import { WBError } from '../lib/errors.js';
+
+export async function cmdDlq(args, globals, positional = []) {
+  const subcommand = positional[0];
+
+  if (!subcommand) {
+    throw new WBError('WB-001', 'INVALID_EVENT_SCHEMA', {
+      message: 'dlq requires a subcommand: list | replay | drop',
+      reason: 'missing dlq subcommand',
+    });
+  }
+
+  const configOverrides = {};
+  if (globals.db_path) configOverrides.db_path = globals.db_path;
+  if (globals.log_level) configOverrides.log_level = globals.log_level;
+
+  const config = loadConfig(configOverrides);
+  const db = openDb(config);
+
+  try {
+    switch (subcommand) {
+      case 'list': {
+        const opts = {};
+        if (args.plugin) opts.plugin = args.plugin;
+        if (args['cursor-id']) opts.cursorId = args['cursor-id'];
+        if (args.limit) opts.limit = parseInt(args.limit, 10);
+        const rows = listDeadLetters(db, opts);
+        process.stdout.write(JSON.stringify({ dead_letters: rows, count: rows.length }) + '\n');
+        return;
+      }
+
+      case 'replay': {
+        const dlId = parseDlId(args);
+        if (args['dry-run']) {
+          const row = db.prepare('SELECT * FROM dead_letters WHERE dl_id = ?').get(dlId);
+          if (!row) {
+            throw new WBError('WB-006', 'CURSOR_NOT_FOUND', {
+              message: `Dead letter not found: ${dlId}`,
+              dl_id: dlId,
+              reason: 'dead letter row not found',
+            });
+          }
+          process.stdout.write(JSON.stringify({
+            dry_run: true,
+            would_replay: {
+              dl_id: row.dl_id,
+              event_id: row.event_id,
+              event_type: row.event_type,
+              domain: row.domain,
+              attempts: row.attempts,
+              last_error: row.last_error,
+            },
+          }) + '\n');
+          return;
+        }
+        const result = replayDeadLetter(db, dlId);
+        process.stdout.write(JSON.stringify(result) + '\n');
+        return;
+      }
+
+      case 'drop': {
+        const dlId = parseDlId(args);
+        const result = dropDeadLetter(db, dlId);
+        process.stdout.write(JSON.stringify(result) + '\n');
+        return;
+      }
+
+      default:
+        throw new WBError('WB-001', 'INVALID_EVENT_SCHEMA', {
+          message: `Unknown dlq subcommand: ${subcommand}`,
+          reason: 'unknown dlq subcommand',
+        });
+    }
+  } finally {
+    db.close();
+  }
+}
+
+function parseDlId(args) {
+  const raw = args['dl-id'];
+  if (raw == null || raw === true) {
+    throw new WBError('WB-001', 'INVALID_EVENT_SCHEMA', {
+      message: '--dl-id <number> is required',
+      reason: 'missing --dl-id',
+    });
+  }
+  const dlId = parseInt(raw, 10);
+  if (!Number.isInteger(dlId) || dlId <= 0) {
+    throw new WBError('WB-001', 'INVALID_EVENT_SCHEMA', {
+      message: `--dl-id must be a positive integer, got: ${raw}`,
+      reason: 'invalid --dl-id',
+    });
+  }
+  return dlId;
+}

package/install.mjs

@@ -60,19 +60,24 @@ if (pathArg) {
 }
 
 // Copy skills to each target CLI
-const skillDirs = readdirSync(skillsSource).filter((d) => !d.startsWith("."));
+// Repo structure: skills/wicked-bus/{name}/SKILL.md (nested namespace)
+// Installed structure: {cli}/skills/wicked-bus-{name}/SKILL.md (flat, one level deep)
+// CLI skill discovery only scans one level deep under the skills directory.
+const namespace = "wicked-bus";
+const namespaceSrc = join(skillsSource, namespace);
+const subSkills = readdirSync(namespaceSrc).filter((d) => !d.startsWith("."));
 
 for (const target of targets) {
   console.log(`Installing to ${target.name} (${target.dir})...`);
   mkdirSync(target.dir, { recursive: true });
 
-  for (const skill of skillDirs) {
-    const src = join(skillsSource, skill);
-    const dest = join(target.dir, skill);
+  for (const skill of subSkills) {
+    const src = join(namespaceSrc, skill);
+    const dest = join(target.dir, `${namespace}-${skill}`);
     cpSync(src, dest, { recursive: true });
   }
 
-  console.log(`  ${skillDirs.length} skills installed`);
+  console.log(`  ${subSkills.length} skills installed`);
 }
 
 console.log(`\nwicked-bus skills installed! Available skills:`);
@@ -81,3 +86,5 @@ console.log(`  wicked-bus/emit      — Publish events`);
 console.log(`  wicked-bus/subscribe — Consume events`);
 console.log(`  wicked-bus/naming    — Event naming conventions`);
 console.log(`  wicked-bus/query     — Query and debug the bus`);
+console.log(`  wicked-bus/status    — Bus health and diagnostics`);
+console.log(`  wicked-bus/update    — Check for and install updates`);

package/lib/db.js

@@ -12,7 +12,7 @@ import { resolveDbPath, ensureDataDir } from './paths.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
 const SCHEMA_SQL_PATH = join(__dirname, 'schema.sql');
-const MAX_SUPPORTED_SCHEMA_VERSION = 1;
+const MAX_SUPPORTED_SCHEMA_VERSION = 2;
 
 /**
  * Open (or create) the SQLite database, apply PRAGMAs and schema.

package/lib/dlq.js

@@ -0,0 +1,144 @@
+/**
+ * Dead-letter queue inspection and operator controls.
+ * @module lib/dlq
+ *
+ * Read-only listing, replay request, and drop. The managed subscribe() helper
+ * in lib/subscribe.js owns the corresponding write paths (DLQ insertion on
+ * retry exhaustion, replay drain on each poll cycle).
+ */
+
+import { WBError } from './errors.js';
+
+/**
+ * List dead-lettered events, most recent first.
+ *
+ * Caveat: dead_letters rows are denormalized snapshots of the originating
+ * event taken at DLQ time. The original row in `events` may have been swept
+ * by `dedup_expires_at` (24h default) by the time the DLQ entry is read, so
+ * the returned `payload` / `event_type` / `domain` / `subdomain` reflect the
+ * event as it existed when it failed, not the current state of `events`.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {object} [opts]
+ * @param {string} [opts.plugin] - Filter to a single subscriber plugin
+ * @param {string} [opts.cursorId] - Filter to a single cursor
+ * @param {number} [opts.limit=100] - Max rows to return
+ * @returns {object[]} Dead letter rows with `payload` parsed from JSON
+ */
+export function listDeadLetters(db, opts = {}) {
+  const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 100;
+
+  const conditions = [];
+  const params = { limit };
+
+  if (opts.plugin) {
+    conditions.push(`dl.subscription_id IN (
+      SELECT subscription_id FROM subscriptions WHERE plugin = :plugin
+    )`);
+    params.plugin = opts.plugin;
+  }
+
+  if (opts.cursorId) {
+    conditions.push('dl.cursor_id = :cursor_id');
+    params.cursor_id = opts.cursorId;
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+  const sql = `
+    SELECT
+      dl.dl_id,
+      dl.cursor_id,
+      dl.subscription_id,
+      dl.event_id,
+      dl.event_type,
+      dl.domain,
+      dl.subdomain,
+      dl.payload,
+      dl.emitted_at,
+      dl.attempts,
+      dl.last_error,
+      dl.dead_lettered_at,
+      dl.replay_requested_at,
+      s.plugin
+    FROM dead_letters dl
+    LEFT JOIN subscriptions s ON s.subscription_id = dl.subscription_id
+    ${where}
+    ORDER BY dl.dead_lettered_at DESC, dl.dl_id DESC
+    LIMIT :limit
+  `;
+
+  const rows = db.prepare(sql).all(params);
+
+  return rows.map(row => ({
+    ...row,
+    payload: parsePayload(row.payload),
+  }));
+}
+
+/**
+ * Mark a dead-lettered event for replay. The next tick of the managed
+ * subscribe() loop for this cursor will drain pending replays before normal
+ * polling. Replay is a single attempt — no automatic retry. On success the
+ * DLQ row is deleted; on failure `replay_requested_at` is cleared and
+ * `attempts` / `last_error` are updated so the operator can re-inspect.
+ *
+ * Caveat: if the handler re-emits during replay, the original event's
+ * `idempotency_key` may already have been swept from `events` (24h
+ * `dedup_expires_at`), so the re-emission will not be deduped against the
+ * original. Replay is for recovery after fixing a bug, not transparent retry.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {number} dlId - dl_id of the dead_letters row to replay
+ * @returns {{ replayed: boolean, dl_id: number, replay_requested_at: number }}
+ */
+export function replayDeadLetter(db, dlId) {
+  const now = Date.now();
+  const result = db.prepare(`
+    UPDATE dead_letters
+    SET replay_requested_at = ?
+    WHERE dl_id = ?
+  `).run(now, dlId);
+
+  if (result.changes === 0) {
+    throw new WBError('WB-006', 'CURSOR_NOT_FOUND', {
+      message: `Dead letter not found: ${dlId}`,
+      dl_id: dlId,
+      reason: 'dead letter row not found',
+    });
+  }
+
+  return { replayed: true, dl_id: dlId, replay_requested_at: now };
+}
+
+/**
+ * Permanently drop a dead-lettered event. Use this when an event is
+ * unrecoverable and the operator does not want it consuming DLQ slots.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {number} dlId
+ * @returns {{ dropped: boolean, dl_id: number }}
+ */
+export function dropDeadLetter(db, dlId) {
+  const result = db.prepare('DELETE FROM dead_letters WHERE dl_id = ?').run(dlId);
+  if (result.changes === 0) {
+    throw new WBError('WB-006', 'CURSOR_NOT_FOUND', {
+      message: `Dead letter not found: ${dlId}`,
+      dl_id: dlId,
+      reason: 'dead letter row not found',
+    });
+  }
+  return { dropped: true, dl_id: dlId };
+}
+
+function parsePayload(raw) {
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new WBError('WB-001', 'INVALID_EVENT_SCHEMA', {
+      message: 'dead_letters row has malformed JSON payload',
+      reason: err.message,
+    });
+  }
+}

package/lib/index.js

@@ -10,4 +10,6 @@ export { openDb } from './db.js';
 export { loadConfig } from './config.js';
 export { resolveDataDir, ensureDataDir, resolveDbPath } from './paths.js';
 export { startSweep, runSweep } from './sweep.js';
+export { listDeadLetters, replayDeadLetter, dropDeadLetter } from './dlq.js';
+export { subscribe } from './subscribe.js';
 export { WBError, ERROR_CODES, EXIT_CODES } from './errors.js';

package/lib/schema.sql

@@ -57,6 +57,55 @@ CREATE INDEX IF NOT EXISTS idx_cursors_subscription_id ON cursors(subscription_i
 CREATE INDEX IF NOT EXISTS idx_cursors_active
     ON cursors(subscription_id) WHERE deregistered_at IS NULL;
 
+-- dead_letters: events that exhausted retries for a specific cursor.
+-- Physically separate from events so poll()'s WB-003 MIN(event_id) check stays
+-- correct. Denormalized so rows survive the 24h dedup_expires_at sweep of the
+-- originating event. No automatic TTL — operator-managed via dlq subcommands.
+CREATE TABLE IF NOT EXISTS dead_letters (
+    dl_id                 INTEGER PRIMARY KEY AUTOINCREMENT,
+    cursor_id             TEXT    NOT NULL
+                            REFERENCES cursors(cursor_id) ON DELETE RESTRICT,
+    subscription_id       TEXT    NOT NULL
+                            REFERENCES subscriptions(subscription_id) ON DELETE RESTRICT,
+    event_id              INTEGER NOT NULL,
+    event_type            TEXT    NOT NULL,
+    domain                TEXT    NOT NULL,
+    subdomain             TEXT    NOT NULL DEFAULT '',
+    payload               TEXT    NOT NULL,
+    emitted_at            INTEGER NOT NULL,
+    attempts              INTEGER NOT NULL,
+    last_error            TEXT,
+    dead_lettered_at      INTEGER NOT NULL,
+    -- Replay queue marker set by replayDeadLetter(). The managed subscribe
+    -- loop drains rows with non-null replay_requested_at before polling new
+    -- events. Cleared on replay success (row deleted) or failure (row
+    -- updated with new attempts/last_error so the operator can re-inspect).
+    replay_requested_at   INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_dead_letters_cursor_id        ON dead_letters(cursor_id);
+CREATE INDEX IF NOT EXISTS idx_dead_letters_subscription_id  ON dead_letters(subscription_id);
+CREATE INDEX IF NOT EXISTS idx_dead_letters_dead_lettered_at ON dead_letters(dead_lettered_at);
+CREATE INDEX IF NOT EXISTS idx_dead_letters_event_id         ON dead_letters(event_id);
+CREATE INDEX IF NOT EXISTS idx_dead_letters_replay_pending
+    ON dead_letters(cursor_id, replay_requested_at)
+    WHERE replay_requested_at IS NOT NULL;
+
+-- delivery_attempts: per-cursor retry state for events currently in flight.
+-- Created on first handler failure, deleted on successful ack or DLQ transition.
+-- Survives process restarts so the retry counter is restored on the next poll.
+CREATE TABLE IF NOT EXISTS delivery_attempts (
+    cursor_id        TEXT    NOT NULL
+                       REFERENCES cursors(cursor_id) ON DELETE CASCADE,
+    event_id         INTEGER NOT NULL,
+    attempts         INTEGER NOT NULL DEFAULT 1,
+    last_attempt_at  INTEGER NOT NULL,
+    last_error       TEXT,
+    PRIMARY KEY (cursor_id, event_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_delivery_attempts_cursor_id ON delivery_attempts(cursor_id);
+
 -- schema_migrations
 CREATE TABLE IF NOT EXISTS schema_migrations (
     version     INTEGER PRIMARY KEY,
@@ -66,3 +115,6 @@ CREATE TABLE IF NOT EXISTS schema_migrations (
 
 INSERT OR IGNORE INTO schema_migrations(version, applied_at, description)
 VALUES (1, unixepoch() * 1000, 'initial schema');
+
+INSERT OR IGNORE INTO schema_migrations(version, applied_at, description)
+VALUES (2, unixepoch() * 1000, 'add dead_letters and delivery_attempts tables');

package/lib/subscribe.js

@@ -0,0 +1,452 @@
+/**
+ * Managed long-running subscriber helper.
+ * @module lib/subscribe
+ *
+ * Layered on top of register/poll/ack — handles the poll loop, error
+ * isolation, retry/backoff, dead-lettering, lifecycle, lag introspection,
+ * and replay drain.
+ *
+ * Design notes:
+ * - Serial per subscription: events are processed one at a time in cursor
+ *   order. The next poll does not start until the current batch is drained.
+ * - Retry state lives in `delivery_attempts` so it survives process restarts.
+ *   On the next poll after a crash, the loop reads the existing attempt count
+ *   and resumes from where it left off.
+ * - On exhaustion, the event is copied (denormalized) into `dead_letters` and
+ *   the cursor is acked past it. The original `events` row may be swept by
+ *   the 24h `dedup_expires_at` later — the DLQ row is self-contained.
+ * - `stop()` cancels any in-flight backoff timer, dead-letters the sleeping
+ *   event, and acks the cursor. Cursor cleanliness beats avoiding an
+ *   unexpected DLQ entry the operator can replay.
+ * - `replayDeadLetter()` sets `replay_requested_at`. The loop drains pending
+ *   replays before each normal poll — success deletes the DLQ row, failure
+ *   clears `replay_requested_at` and updates `attempts` / `last_error`.
+ *
+ * Caveats:
+ * - At-least-once delivery + retries means the handler may be invoked more
+ *   than once for the same logical event. Handlers must be idempotent.
+ * - If a DLQ entry is replayed and the handler re-emits as part of recovery,
+ *   the original `idempotency_key` may already have been swept from `events`
+ *   (24h `dedup_expires_at`). The re-emission will not be deduped against
+ *   the original. Replay is for recovery, not for transparent retry.
+ */
+
+import { poll, ack } from './poll.js';
+import { register } from './register.js';
+
+const DEFAULTS = Object.freeze({
+  pollIntervalMs: 15000,
+  batchSize: 50,
+  maxRetries: 0,
+  backoffMs: 1000,
+  lagIntervalMs: 60000,
+  cursor_init: 'latest',
+});
+
+/**
+ * Resume an existing subscription by (plugin, filter), or register a new one.
+ * Internal — not exported. Direct callers of register() keep the original
+ * "always create a new UUID" semantics.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {object} opts
+ * @returns {{ subscription_id: string, cursor_id: string, created: boolean }}
+ */
+function registerOrResume(db, opts) {
+  const existing = db.prepare(`
+    SELECT s.subscription_id, c.cursor_id
+    FROM subscriptions s
+    INNER JOIN cursors c ON c.subscription_id = s.subscription_id
+    WHERE s.plugin = ?
+      AND s.role = 'subscriber'
+      AND s.event_type_filter = ?
+      AND s.deregistered_at IS NULL
+      AND c.deregistered_at IS NULL
+    ORDER BY s.registered_at DESC
+    LIMIT 1
+  `).get(opts.plugin, opts.filter);
+
+  if (existing) {
+    return {
+      subscription_id: existing.subscription_id,
+      cursor_id: existing.cursor_id,
+      created: false,
+    };
+  }
+
+  const fresh = register(db, {
+    plugin: opts.plugin,
+    role: 'subscriber',
+    filter: opts.filter,
+    cursor_init: opts.cursor_init,
+  });
+
+  return {
+    subscription_id: fresh.subscription_id,
+    cursor_id: fresh.cursor_id,
+    created: true,
+  };
+}
+
+/**
+ * Normalize backoffMs into an array of length maxRetries with last-element
+ * repeat semantics. A single number becomes a constant array.
+ */
+function normalizeBackoff(input, maxRetries) {
+  if (maxRetries <= 0) return [];
+  const source = Array.isArray(input) ? input : [input ?? DEFAULTS.backoffMs];
+  if (source.length === 0) return new Array(maxRetries).fill(DEFAULTS.backoffMs);
+  const out = new Array(maxRetries);
+  for (let i = 0; i < maxRetries; i++) {
+    out[i] = source[Math.min(i, source.length - 1)];
+  }
+  return out;
+}
+
+/**
+ * Read the current attempt count for an in-flight retry, or 0 if none.
+ */
+function getAttempts(db, cursorId, eventId) {
+  const row = db.prepare(
+    'SELECT attempts FROM delivery_attempts WHERE cursor_id = ? AND event_id = ?'
+  ).get(cursorId, eventId);
+  return row ? row.attempts : 0;
+}
+
+function upsertDeliveryAttempt(db, cursorId, eventId, attempts, lastError) {
+  db.prepare(`
+    INSERT INTO delivery_attempts (cursor_id, event_id, attempts, last_attempt_at, last_error)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(cursor_id, event_id) DO UPDATE SET
+      attempts = excluded.attempts,
+      last_attempt_at = excluded.last_attempt_at,
+      last_error = excluded.last_error
+  `).run(cursorId, eventId, attempts, Date.now(), lastError ?? null);
+}
+
+function deleteDeliveryAttempt(db, cursorId, eventId) {
+  db.prepare(
+    'DELETE FROM delivery_attempts WHERE cursor_id = ? AND event_id = ?'
+  ).run(cursorId, eventId);
+}
+
+function moveToDeadLetter(db, cursorId, subscriptionId, event, attempts, reason) {
+  db.prepare(`
+    INSERT INTO dead_letters (
+      cursor_id, subscription_id, event_id, event_type, domain, subdomain,
+      payload, emitted_at, attempts, last_error, dead_lettered_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    cursorId,
+    subscriptionId,
+    event.event_id,
+    event.event_type,
+    event.domain,
+    event.subdomain ?? '',
+    typeof event.payload === 'string' ? event.payload : JSON.stringify(event.payload),
+    event.emitted_at,
+    attempts,
+    reason ?? null,
+    Date.now()
+  );
+}
+
+function parseEvent(row) {
+  let payload = row.payload;
+  if (typeof payload === 'string') {
+    try { payload = JSON.parse(payload); } catch (_) { /* leave as string */ }
+  }
+  return { ...row, payload };
+}
+
+/**
+ * Compute lag for a cursor — how far behind the head of the matching stream.
+ * @returns {{ cursor_lag: number, oldest_unacked_age_ms: number|null, dlq_count: number }}
+ */
+function computeLag(db, cursorId) {
+  const cursor = db.prepare(
+    'SELECT * FROM cursors WHERE cursor_id = ?'
+  ).get(cursorId);
+  if (!cursor) {
+    return { cursor_lag: 0, oldest_unacked_age_ms: null, dlq_count: 0 };
+  }
+
+  const sub = db.prepare(
+    'SELECT * FROM subscriptions WHERE subscription_id = ?'
+  ).get(cursor.subscription_id);
+  if (!sub) {
+    return { cursor_lag: 0, oldest_unacked_age_ms: null, dlq_count: 0 };
+  }
+
+  // Reuse poll() filter compilation by counting matching events ahead of cursor.
+  // We approximate: count rows where event_id > last_event_id and not expired.
+  // Filter matching is handled in a sub-query below.
+  const head = db.prepare(
+    'SELECT MAX(event_id) as max_id FROM events'
+  ).get();
+  const maxId = head && head.max_id != null ? head.max_id : 0;
+  const cursorLag = Math.max(0, maxId - cursor.last_event_id);
+
+  // Oldest unacked age is best-effort: emitted_at of the lowest unacked event
+  // that the cursor would actually receive on next poll. We skip the filter
+  // join here for simplicity and use the same filtered poll() shape via
+  // event_id > last_event_id and expires_at > now.
+  const now = Date.now();
+  const oldest = db.prepare(`
+    SELECT MIN(emitted_at) as oldest
+    FROM events
+    WHERE event_id > ? AND expires_at > ?
+  `).get(cursor.last_event_id, now);
+  const oldestUnackedAgeMs = oldest && oldest.oldest != null ? now - oldest.oldest : null;
+
+  const dlq = db.prepare(
+    'SELECT COUNT(*) as c FROM dead_letters WHERE cursor_id = ?'
+  ).get(cursorId);
+  const dlqCount = dlq ? dlq.c : 0;
+
+  return {
+    cursor_lag: cursorLag,
+    oldest_unacked_age_ms: oldestUnackedAgeMs,
+    dlq_count: dlqCount,
+  };
+}
+
+/**
+ * Subscribe to events with a managed loop, retry, DLQ, and lifecycle.
+ *
+ * @param {object} opts
+ * @param {import('better-sqlite3').Database} opts.db - Open DB handle (required)
+ * @param {string} opts.plugin - Subscriber plugin identity
+ * @param {string} opts.filter - Event type filter (e.g. 'wicked.fact.extracted.*')
+ * @param {(event: object) => void|Promise<void>} opts.handler - Event handler; throws to retry
+ * @param {'latest'|'oldest'} [opts.cursor_init='latest'] - Only used on first registration
+ * @param {number} [opts.pollIntervalMs=15000]
+ * @param {number} [opts.batchSize=50]
+ * @param {number} [opts.maxRetries=0] - 0 = fail-fast (advance cursor on first failure)
+ * @param {number|number[]} [opts.backoffMs=1000] - Number = constant; array repeats last element
+ * @param {number} [opts.lagIntervalMs=60000] - onLag callback cadence (independent of poll)
+ * @param {(err: Error, event: object) => void} [opts.onError]
+ * @param {(event: object, reason: string) => void} [opts.onDeadLetter]
+ * @param {(lag: object) => void} [opts.onLag]
+ *
+ * @returns {{ stop: () => Promise<void>, getLag: () => object, cursor_id: string, subscription_id: string }}
+ */
+export function subscribe(opts) {
+  if (!opts || !opts.db) throw new TypeError('subscribe: opts.db is required');
+  if (!opts.plugin) throw new TypeError('subscribe: opts.plugin is required');
+  if (!opts.filter) throw new TypeError('subscribe: opts.filter is required');
+  if (typeof opts.handler !== 'function') {
+    throw new TypeError('subscribe: opts.handler must be a function');
+  }
+
+  const db = opts.db;
+  const pollIntervalMs = opts.pollIntervalMs ?? DEFAULTS.pollIntervalMs;
+  const batchSize = opts.batchSize ?? DEFAULTS.batchSize;
+  const maxRetries = opts.maxRetries ?? DEFAULTS.maxRetries;
+  const backoffMs = normalizeBackoff(opts.backoffMs, maxRetries);
+  const lagIntervalMs = opts.lagIntervalMs ?? DEFAULTS.lagIntervalMs;
+
+  const { subscription_id, cursor_id } = registerOrResume(db, {
+    plugin: opts.plugin,
+    filter: opts.filter,
+    cursor_init: opts.cursor_init || DEFAULTS.cursor_init,
+  });
+
+  // ── Loop state ────────────────────────────────────────────────────────────
+  let stopping = false;
+  let stopPromise = null;
+  let resolveStop = null;
+  let pollTimer = null;
+  let lagTimer = null;
+  let backoffTimer = null;
+  let cancelBackoff = null;
+  let loopActive = false;
+
+  function safeCallback(cb, ...args) {
+    if (typeof cb !== 'function') return;
+    try { cb(...args); } catch (_) { /* user callback errors are swallowed */ }
+  }
+
+  function sleepCancelable(ms) {
+    return new Promise(resolve => {
+      backoffTimer = setTimeout(() => {
+        backoffTimer = null;
+        cancelBackoff = null;
+        resolve(true);
+      }, ms);
+      cancelBackoff = () => {
+        if (backoffTimer) {
+          clearTimeout(backoffTimer);
+          backoffTimer = null;
+        }
+        cancelBackoff = null;
+        resolve(false);
+      };
+    });
+  }
+
+  /**
+   * Process a single event with retry/DLQ semantics.
+   * Returns true when the cursor was advanced (success or DLQ), false if the
+   * loop should bail without advancing (only on shutdown mid-handler).
+   */
+  async function processEvent(event) {
+    let attempts = getAttempts(db, cursor_id, event.event_id);
+    const parsed = parseEvent(event);
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      if (stopping && attempts > 0) {
+        // Mid-retry shutdown: DLQ and advance.
+        moveToDeadLetter(db, cursor_id, subscription_id, event, attempts, 'shutdown during backoff');
+        deleteDeliveryAttempt(db, cursor_id, event.event_id);
+        ack(db, cursor_id, event.event_id);
+        safeCallback(opts.onDeadLetter, parsed, 'shutdown during backoff');
+        return true;
+      }
+
+      try {
+        await opts.handler(parsed);
+        deleteDeliveryAttempt(db, cursor_id, event.event_id);
+        ack(db, cursor_id, event.event_id);
+        return true;
+      } catch (err) {
+        attempts += 1;
+        safeCallback(opts.onError, err, parsed);
+
+        if (attempts > maxRetries) {
+          moveToDeadLetter(db, cursor_id, subscription_id, event, attempts, err.message);
+          deleteDeliveryAttempt(db, cursor_id, event.event_id);
+          ack(db, cursor_id, event.event_id);
+          safeCallback(opts.onDeadLetter, parsed, err.message);
+          return true;
+        }
+
+        upsertDeliveryAttempt(db, cursor_id, event.event_id, attempts, err.message);
+        const sleepMs = backoffMs[Math.min(attempts - 1, backoffMs.length - 1)];
+        const completed = await sleepCancelable(sleepMs);
+        if (!completed) {
+          // stop() interrupted the backoff
+          moveToDeadLetter(db, cursor_id, subscription_id, event, attempts, 'shutdown during backoff');
+          deleteDeliveryAttempt(db, cursor_id, event.event_id);
+          ack(db, cursor_id, event.event_id);
+          safeCallback(opts.onDeadLetter, parsed, 'shutdown during backoff');
+          return true;
+        }
+        // loop again — retry handler
+      }
+    }
+  }
+
+  /**
+   * Drain pending replays for this cursor before normal polling.
+   * Each replay is a single attempt — no retry semantics. Success deletes the
+   * DLQ row; failure clears replay_requested_at and updates attempts / last_error.
+   */
+  async function drainReplays() {
+    while (!stopping) {
+      const row = db.prepare(`
+        SELECT * FROM dead_letters
+        WHERE cursor_id = ? AND replay_requested_at IS NOT NULL
+        ORDER BY dl_id ASC
+        LIMIT 1
+      `).get(cursor_id);
+      if (!row) return;
+
+      const parsed = parseEvent(row);
+      try {
+        await opts.handler(parsed);
+        db.prepare('DELETE FROM dead_letters WHERE dl_id = ?').run(row.dl_id);
+      } catch (err) {
+        safeCallback(opts.onError, err, parsed);
+        db.prepare(`
+          UPDATE dead_letters
+          SET replay_requested_at = NULL,
+              attempts = attempts + 1,
+              last_error = ?
+          WHERE dl_id = ?
+        `).run(err.message, row.dl_id);
+        // Stop draining on failure; operator can re-replay after fixing
+        return;
+      }
+    }
+  }
+
+  async function tick() {
+    if (stopping || loopActive) return;
+    loopActive = true;
+    try {
+      await drainReplays();
+      if (stopping) return;
+
+      const events = poll(db, cursor_id, { batchSize });
+      for (const event of events) {
+        if (stopping) break;
+        await processEvent(event);
+      }
+    } catch (err) {
+      // Polling errors (WB-003, WB-006) bubble through onError so operators
+      // see them. The loop continues — the next tick will retry.
+      safeCallback(opts.onError, err, null);
+    } finally {
+      loopActive = false;
+      if (!stopping) {
+        pollTimer = setTimeout(tick, pollIntervalMs);
+      } else if (resolveStop) {
+        finalizeStop();
+      }
+    }
+  }
+
+  function finalizeStop() {
+    if (pollTimer) { clearTimeout(pollTimer); pollTimer = null; }
+    if (lagTimer) { clearInterval(lagTimer); lagTimer = null; }
+    if (resolveStop) {
+      const r = resolveStop;
+      resolveStop = null;
+      r();
+    }
+  }
+
+  async function stop() {
+    if (stopPromise) return stopPromise;
+    stopping = true;
+    stopPromise = new Promise(resolve => { resolveStop = resolve; });
+
+    if (cancelBackoff) cancelBackoff();
+    if (pollTimer) { clearTimeout(pollTimer); pollTimer = null; }
+    if (lagTimer) { clearInterval(lagTimer); lagTimer = null; }
+
+    if (!loopActive) {
+      // Nothing in flight — resolve immediately
+      finalizeStop();
+    }
+    // Otherwise tick()'s finally block will resolve once the in-flight handler
+    // (or backoff cancellation) completes.
+
+    return stopPromise;
+  }
+
+  function getLag() {
+    return computeLag(db, cursor_id);
+  }
+
+  // ── Start the loop ────────────────────────────────────────────────────────
+  // First tick on next macrotask so the caller can attach handlers / store the
+  // returned handle before the loop begins.
+  pollTimer = setTimeout(tick, 0);
+
+  if (typeof opts.onLag === 'function') {
+    lagTimer = setInterval(() => {
+      safeCallback(opts.onLag, computeLag(db, cursor_id));
+    }, lagIntervalMs);
+    // Don't keep the event loop alive for lag callbacks alone
+    if (lagTimer.unref) lagTimer.unref();
+  }
+
+  return { stop, getLag, cursor_id, subscription_id };
+}
+
+// Internal export for testing / advanced callers that want resume semantics
+// without the full managed loop.
+export { registerOrResume };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-bus",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Lightweight, local-first SQLite event bus for AI agents and developer tools",
   "type": "module",
   "exports": {
@@ -52,5 +52,13 @@
     "cursor-poll",
     "at-least-once"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mikeparcewski/wicked-bus.git"
+  },
+  "homepage": "https://github.com/mikeparcewski/wicked-bus#readme",
+  "bugs": {
+    "url": "https://github.com/mikeparcewski/wicked-bus/issues"
+  }
 }

package/skills/wicked-bus/emit/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: wicked-bus:emit
 description: Emit events to the wicked-bus. Use when publishing events from a plugin, logging activity to the bus, or integrating a new system with the event bridge. Covers both programmatic (Node.js) and CLI usage.
 ---
 

package/skills/wicked-bus/init/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: wicked-bus:init
 description: Initialize wicked-bus or connect to an existing instance. Use when setting up the bus for the first time, checking if it's running, or configuring a project to use it. Auto-triggered when any wicked-bus skill detects no config.
 ---
 

package/skills/wicked-bus/naming/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: wicked-bus:naming
 description: Guide for naming wicked-bus events — helps choose event_type, domain, and subdomain when emitting events. Use when creating new events, integrating a plugin with the bus, or reviewing event naming for consistency.
 ---
 

package/skills/wicked-bus/query/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: wicked-bus:query
 description: Query and debug the wicked-bus. Use when checking bus health, inspecting events, debugging delivery issues, tracing event flow, or investigating why a subscriber isn't receiving events. Covers status, replay, and direct SQLite queries.
 ---
 

package/skills/wicked-bus/status/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: wicked-bus:status
+description: |
+  Show wicked-bus health, statistics, and diagnostics. Event counts,
+  subscriber lag, provider list, database size, and configuration.
+
+  Use when: "bus status", "is the bus healthy", "how many events",
+  "show bus stats", or when diagnosing delivery issues.
+---
+
+# wicked-bus:status
+
+Show the current state of the wicked-bus.
+
+## When to use
+
+- User asks about bus health or status
+- Before debugging delivery issues
+- Checking if the bus is initialized and has data
+- Monitoring subscriber lag
+
+## Process
+
+### Step 1: Check if bus is initialized
+
+```bash
+npx wicked-bus status 2>/dev/null
+```
+
+If this fails, the bus isn't initialized. Suggest running `wicked-bus/init`.
+
+### Step 2: Parse and display status
+
+The `status` command returns JSON. Display it in a readable format:
+
+```markdown
+## wicked-bus Status
+
+**Database**: {db_path}
+**Events**: {total_events} total, {active_events} active (not expired)
+**Providers**: {provider_count} registered
+**Subscribers**: {subscriber_count} active
+
+### Subscriber Lag
+| Plugin | Filter | Cursor | Latest | Lag |
+|--------|--------|--------|--------|-----|
+| {plugin} | {filter} | {last_event_id} | {max_event_id} | {lag} |
+```
+
+### Step 3: Extended diagnostics (if requested)
+
+If the user wants deeper diagnostics, query SQLite directly:
+
+**Event distribution by type:**
+```bash
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT event_type, COUNT(*) as count FROM events GROUP BY event_type ORDER BY count DESC LIMIT 20;"
+```
+
+**Event distribution by domain:**
+```bash
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT domain, COUNT(*) as count FROM events GROUP BY domain ORDER BY count DESC;"
+```
+
+**Database size:**
+```bash
+ls -lh ~/.something-wicked/wicked-bus/bus.db
+```
+
+**WAL size (if checkpointing is lagging):**
+```bash
+ls -lh ~/.something-wicked/wicked-bus/bus.db-wal 2>/dev/null
+```
+
+**Events per hour (last 24h):**
+```bash
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT strftime('%Y-%m-%d %H:00', emitted_at/1000, 'unixepoch') as hour, COUNT(*) as count FROM events WHERE emitted_at > (strftime('%s','now')-86400)*1000 GROUP BY hour ORDER BY hour;"
+```
+
+**Oldest and newest events:**
+```bash
+sqlite3 ~/.something-wicked/wicked-bus/bus.db \
+  "SELECT 'oldest' as which, event_id, event_type, datetime(emitted_at/1000, 'unixepoch') as time FROM events ORDER BY event_id ASC LIMIT 1 UNION ALL SELECT 'newest', event_id, event_type, datetime(emitted_at/1000, 'unixepoch') FROM events ORDER BY event_id DESC LIMIT 1;"
+```
+
+**Deregistered subscriptions:**
+```bash
+npx wicked-bus list --include-deregistered --json
+```
+
+**Configuration:**
+```bash
+cat ~/.something-wicked/wicked-bus/config.json
+```
+
+If `WICKED_BUS_DATA_DIR` is set, use that path instead of the default.
+
+### Step 4: Health warnings
+
+Flag these issues if detected:
+
+- **High lag** (cursor > 100 events behind): subscriber may be failing to poll
+- **No recent events** (nothing in last 24h): producers may have stopped
+- **Large WAL file** (> 10 MB): checkpointing may be blocked
+- **Deregistered subscribers with active cursors**: orphaned cursors consuming space
+- **Events near dedup_expires_at**: about to be swept — subscribers should poll soon

package/skills/wicked-bus/subscribe/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: wicked-bus:subscribe
 description: Subscribe to wicked-bus events. Use when consuming events from the bus, setting up event listeners, polling for new events, or integrating as a subscriber. Covers registration, polling, acknowledgment, and filter patterns.
 ---
 

package/skills/wicked-bus/update/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: wicked-bus:update
+description: |
+  Check for and install wicked-bus updates. Compares installed version against
+  npm registry, updates skills across all detected CLIs.
+
+  Use when: "update wicked-bus", "check for bus updates", "wicked-bus update",
+  or periodically to stay current.
+---
+
+# wicked-bus:update
+
+Check for and install updates to wicked-bus and its skills.
+
+## Cross-Platform Notes
+
+Commands work on macOS, Linux, and Windows. Use agent-native tools
+(Read, Write, Grep, Glob) over shell commands when possible.
+
+## When to use
+
+- User asks to update or check for updates
+- After encountering unexpected behavior that might be fixed in a newer version
+- Periodically (suggest checking monthly)
+
+## Process
+
+### Step 1: Check current installed version
+
+Check both global and local installations:
+
+```bash
+npm list -g wicked-bus --json 2>/dev/null | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    deps = d.get('dependencies', {})
+    v = deps.get('wicked-bus', {}).get('version', 'not installed')
+    print(v)
+except Exception:
+    print('not installed')
+" 2>/dev/null || python -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    deps = d.get('dependencies', {})
+    v = deps.get('wicked-bus', {}).get('version', 'not installed')
+    print(v)
+except Exception:
+    print('not installed')
+"
+```
+
+Also check local (project-level) install:
+```bash
+npm list wicked-bus --json 2>/dev/null
+```
+
+### Step 2: Check latest version on npm
+
+```bash
+npm view wicked-bus version 2>/dev/null
+```
+
+### Step 3: Compare versions
+
+If installed version matches latest:
+"wicked-bus is up to date (v{version})."
+
+If an update is available:
+"wicked-bus v{new} is available (you have v{current}). Update now?"
+
+### Step 4: Update (if user approves)
+
+For global install:
+```bash
+npm install -g wicked-bus@latest 2>&1
+```
+
+For local (project) install:
+```bash
+npm install wicked-bus@latest 2>&1
+```
+
+If `EACCES` / permission denied:
+- macOS/Linux: `sudo npm install -g wicked-bus@latest`
+- Windows: re-run shell as Administrator
+- Report the failure — do NOT silently skip
+
+### Step 5: Refresh skills in all CLIs
+
+After updating the package, run the installer to copy updated skills:
+
+```bash
+npx wicked-bus-install
+```
+
+Or with a specific CLI target:
+```bash
+npx wicked-bus-install --cli=claude
+```
+
+### Step 6: Verify
+
+Re-run the Step 1 version check. Confirm the version matches latest.
+
+If it still shows the old version:
+1. Check `which wicked-bus` (macOS/Linux) or `where wicked-bus` (Windows)
+2. Clear npm cache: `npm cache clean --force`
+3. Check if nvm/fnm/volta is pinning a stale copy
+
+### Step 7: Report
+
+```
+wicked-bus updated: v{old} → v{new}
+Skills refreshed in {N} CLIs: {list}
+```
+
+## Version check without updating
+
+If the user just wants to check, stop after Step 3 and report
+current vs. available version.