@stage-labs/metro 0.1.0-beta.11 → 0.1.0-beta.13

package/dist/broker.js

@@ -0,0 +1,202 @@
+/** Broker primitives: claims map + per-user byte-offset cursors over history.jsonl. */
+import { closeSync, existsSync, openSync, readFileSync, readSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { errMsg, log } from './log.js';
+import { STATE_DIR } from './paths.js';
+import { Line } from './stations/index.js';
+export const CLAIMS_FILE = join(STATE_DIR, 'claims.json');
+const CLAIMS_LOCK = join(STATE_DIR, 'claims.json.lock');
+const CURSORS_DIR = join(STATE_DIR, 'cursors');
+export const HISTORY_FILE = join(STATE_DIR, 'history.jsonl');
+/** Read claims.json. Returns empty map if missing or malformed (retries once on race). */
+export function readClaims() {
+    if (!existsSync(CLAIMS_FILE))
+        return {};
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            return JSON.parse(readFileSync(CLAIMS_FILE, 'utf8'));
+        }
+        catch { /* race with writer — retry once */ }
+    }
+    log.warn({ path: CLAIMS_FILE }, 'claims: malformed, treating as empty');
+    return {};
+}
+/** Mutate claims under an O_EXCL lockfile. Throws if another writer holds the lock past timeout. */
+function withClaimsLock(fn) {
+    const deadline = Date.now() + 2_000;
+    while (true) {
+        try {
+            closeSync(openSync(CLAIMS_LOCK, 'wx'));
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            if (Date.now() > deadline)
+                throw new Error('claims.json: lock contention (held >2s)');
+        }
+    }
+    try {
+        const next = readClaims();
+        const result = fn(next);
+        /** atomic publish: tmpfile + rename so readers never see a half-written file */
+        const tmp = `${CLAIMS_FILE}.tmp.${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
+        renameSync(tmp, CLAIMS_FILE);
+        return result;
+    }
+    finally {
+        try {
+            unlinkSync(CLAIMS_LOCK);
+        }
+        catch { /* ignore */ }
+    }
+}
+export function claimLine(line, owner) {
+    return withClaimsLock(m => { m[line] = owner; return m; });
+}
+export function releaseLine(line) {
+    return withClaimsLock(m => {
+        const released = line in m;
+        delete m[line];
+        return { released, claims: m };
+    });
+}
+/** Per-line decision: should auto-claim run on a successful outbound? */
+function shouldAutoClaim(line, kind) {
+    const station = Line.station(line);
+    /** Webhook lines are a broadcast stream — claiming one is a footgun. */
+    if (station === 'webhook')
+        return { ok: false, reason: 'webhook' };
+    /** Claude/Codex cross-user lines are 1:1 by construction — always safe. */
+    if (station === 'claude' || station === 'codex')
+        return { ok: true };
+    if (kind === 'group')
+        return { ok: false, reason: 'group' };
+    return { ok: true };
+}
+export function tryAutoClaim(line, owner, opts = {}) {
+    if (!opts.force) {
+        const decision = shouldAutoClaim(line, opts.lineKind ?? 'unknown');
+        if (!decision.ok)
+            return { status: decision.reason, line };
+    }
+    try {
+        return withClaimsLock(m => {
+            const existing = m[line];
+            if (existing && existing !== owner)
+                return { status: 'skipped', existing };
+            if (existing === owner)
+                return { status: 'kept', owner };
+            m[line] = owner;
+            return { status: 'claimed', owner };
+        });
+    }
+    catch (err) {
+        return { status: 'error', error: err.message };
+    }
+}
+/** Filename-safe slug for a participant URI. `metro://claude/user/9bfc…` → `claude-user-9bfc…`. */
+export function userSlug(uri) {
+    return uri.replace(/^metro:\/+/, '').replace(/[^A-Za-z0-9_.-]/g, '-');
+}
+/** Cursor key for a tail invocation. Derived from the *effective mode*, NOT from `userSelf()`. */
+/** Keeps `--all` / `--unclaimed` from trampling a `--as=<id>` cursor in a CLAUDECODE shell. */
+/** Keys: `--as=<id>`→slug(id); `+--strict`→slug+`--strict`; `--unclaimed`→`_unclaimed`; `--all`→`_all`. */
+/** The `_` prefix can't collide with a userSlug (always has a station prefix like `claude-user-…`). */
+/** `--include-webhooks` adds `--with-webhooks` so toggling mid-stream doesn't re-emit/skip events. */
+export function cursorKey(mode, self, opts = {}) {
+    if (mode === 'all')
+        return '_all';
+    if (mode === 'unclaimed')
+        return '_unclaimed';
+    if (!self)
+        return null;
+    const base = userSlug(self);
+    const suffix = mode === 'mine-only' ? '--strict' : '';
+    const webhooks = opts.includeWebhooks ? '--with-webhooks' : '';
+    return `${base}${suffix}${webhooks}`;
+}
+const cursorPath = (key) => join(CURSORS_DIR, key);
+export function readCursor(key) {
+    const p = cursorPath(key);
+    if (!existsSync(p))
+        return 0;
+    const n = Number(readFileSync(p, 'utf8').trim());
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+export function writeCursor(key, offset) {
+    mkdirSync(CURSORS_DIR, { recursive: true });
+    const p = cursorPath(key);
+    const tmp = `${p}.tmp.${process.pid}`;
+    writeFileSync(tmp, String(offset));
+    renameSync(tmp, p);
+}
+/** Byte size of history.jsonl right now (for `--since=tail`). */
+export function historySize() {
+    if (!existsSync(HISTORY_FILE))
+        return 0;
+    try {
+        return readFileSync(HISTORY_FILE).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Yield each complete JSONL line from `offset` to EOF; the returned offset is the position right after the `\n`. */
+export function* readEntriesFrom(offset) {
+    if (!existsSync(HISTORY_FILE))
+        return;
+    const fd = openSync(HISTORY_FILE, 'r');
+    try {
+        const chunk = Buffer.alloc(64 * 1024);
+        let pending = Buffer.alloc(0);
+        let pos = offset;
+        while (true) {
+            const n = readSync(fd, chunk, 0, chunk.length, pos);
+            if (n === 0)
+                break;
+            pending = Buffer.concat([pending, chunk.subarray(0, n)]);
+            pos += n;
+            let nl;
+            while ((nl = pending.indexOf(0x0a)) !== -1) {
+                const raw = pending.subarray(0, nl).toString('utf8').trim();
+                pending = pending.subarray(nl + 1);
+                if (!raw)
+                    continue;
+                try {
+                    const entry = JSON.parse(raw);
+                    /** offsetAfter = read-cursor in file - bytes still in pending buffer */
+                    yield { entry, offset: pos - pending.length };
+                }
+                catch (err) {
+                    log.warn({ err: errMsg(err) }, 'broker: skipped malformed history line');
+                }
+            }
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Claim-aware filter. Webhooks excluded from personal modes unless `includeWebhooks`.
+ */
+export function passesMode(event, mode, self, claims, opts = {}) {
+    if (self && event.to === self)
+        return true;
+    if (mode === 'all')
+        return true;
+    const isWebhook = event.station === 'webhook';
+    if (mode === 'unclaimed')
+        return !claims[event.line];
+    /** webhooks are filtered out of personal modes unless opted in */
+    if (isWebhook && !opts.includeWebhooks)
+        return false;
+    const owner = claims[event.line];
+    if (mode === 'mine-only')
+        return owner === self;
+    /** mode === 'mine-or-unclaimed' */
+    return !owner || owner === self;
+}

package/dist/cache.js

@@ -47,7 +47,7 @@ export function noteSeen(line, name) {
 export const listLines = () => Object.entries(read()).map(([line, entry]) => ({ line: line, entry }));
 /** Bot identity cache: `{discord: "<userId>", telegram: "<userId>"}`. Daemon writes after getMe(). */
 const botIdsFile = join(STATE_DIR, 'bot-ids.json');
-const readBotIds = () => {
+export const readBotIds = () => {
     try {
         return existsSync(botIdsFile) ? JSON.parse(readFileSync(botIdsFile, 'utf8')) : {};
     }

package/dist/cli/actions.js

@@ -9,6 +9,7 @@ import { ipcCall } from '../ipc.js';
 import { userSelf, appendHistory, lookupEntry, mintId, readHistory, resolvePlatformId, } from '../history.js';
 import { asLine, Line } from '../stations/index.js';
 import { loadMetroEnv } from '../paths.js';
+import { tryAutoClaim } from '../broker.js';
 import { emit, flagList, flagOne, isJson, need, resolveText, writeJson, } from './util.js';
 export function chatStationOf(line) {
     const s = Line.station(line);
@@ -51,25 +52,83 @@ function destinationFor(orig, line) {
         return line;
     return orig.from;
 }
+/** Classify a chat line as DM/group/unknown for the auto-claim group-skip rule. */
+/** Telegram: chat-id sign is authoritative (id < 0 ⇒ group). Discord: peek payload.guildId on */
+/** the most-recent inbound (null ⇒ DM, set ⇒ group, none seen ⇒ unknown). Claude/Codex ⇒ dm. */
+export function classifyLine(line) {
+    const station = Line.station(line);
+    if (station === 'telegram') {
+        const parsed = Line.parseTelegram(line);
+        if (!parsed)
+            return 'unknown';
+        return parsed.chatId < 0 ? 'group' : 'dm';
+    }
+    if (station === 'claude' || station === 'codex')
+        return 'dm';
+    if (station === 'webhook')
+        return 'group';
+    if (station === 'discord') {
+        /** Look at the most recent inbound on this line; the daemon stored the raw message in `payload`. */
+        const recent = readHistory({ line, kind: 'inbound', limit: 1 })[0];
+        if (!recent)
+            return 'unknown';
+        const payload = recent.payload;
+        if (!payload || !('guildId' in payload)) {
+            /** Older entries may not have a guildId — fall back to the `to` field: DMs route to a user URI. */
+            if (recent.to && recent.to !== recent.line)
+                return 'dm';
+            return 'unknown';
+        }
+        return payload.guildId == null ? 'dm' : 'group';
+    }
+    return 'unknown';
+}
 /** Append an outbound action to history.jsonl; `to` mirrors the destination per `destinationFor`. */
 function logOutbound(f, e) {
     const id = mintId();
     const fromOverride = flagOne(f, 'from');
+    const from = fromOverride ? asLine(fromOverride) : userSelf();
     appendHistory({
         id, ts: new Date().toISOString(), station: Line.station(e.line) ?? '?',
-        from: fromOverride ? asLine(fromOverride) : userSelf(), to: e.to ?? e.line, ...e,
+        from, to: e.to ?? e.line, ...e,
     });
+    maybeAutoClaim(f, e.line, from);
     return id;
 }
+/** Auto-claim on outbound — skips when `--no-claim` / `METRO_NO_AUTO_CLAIM=1`, when the line is */
+/** a group/webhook, or when already owned by someone else. `--claim` forces a group-line claim. */
+function maybeAutoClaim(f, line, owner) {
+    if (f['no-claim'] === true)
+        return;
+    if (process.env.METRO_NO_AUTO_CLAIM === '1')
+        return;
+    const force = f['claim'] === true;
+    const lineKind = classifyLine(line);
+    const result = tryAutoClaim(line, owner, { lineKind, force });
+    if (result.status === 'skipped') {
+        process.stderr.write(`auto-claim skipped: line owned by ${result.existing}\n`);
+    }
+    else if (result.status === 'group') {
+        process.stderr.write(`auto-claim skipped: ${line} is a group/public line; pass --claim to take it explicitly\n`);
+    }
+    else if (result.status === 'webhook') {
+        process.stderr.write(`auto-claim skipped: ${line} is a webhook line (broadcast stream)\n`);
+    }
+    else if (result.status === 'error') {
+        process.stderr.write(`auto-claim failed: ${result.error}\n`);
+    }
+}
 export async function cmdSend(p, f) {
     need(p, 1, 'metro send <line> <text> [--image=<path>]… [--document=<path>]… [--voice=<path>] [--buttons=<json>]');
     loadMetroEnv();
     const text = await resolveText(p, 1), line = asLine(p[0]);
     if (Line.isLocal(line)) {
-        const from = flagOne(f, 'from');
-        const resp = await ipcCall({ op: 'notify', line, from, text });
+        const fromFlag = flagOne(f, 'from');
+        const resp = await ipcCall({ op: 'notify', line, from: fromFlag, text });
         if (!resp.ok)
             throw new Error(resp.error);
+        /** cross-user notify still counts as the sender taking the line: auto-claim if unclaimed */
+        maybeAutoClaim(f, line, fromFlag ? asLine(fromFlag) : userSelf());
         return emit(f, `notified ${line}`, { ok: true, line, id: null, messageId: null });
     }
     const messageId = await chatStationOf(line).send(line, text, richOpts(f));

package/dist/cli/index.js

@@ -9,6 +9,7 @@ import { loadMetroEnv } from '../paths.js';
 import { readHistory } from '../history.js';
 import { cmdDoctor, cmdSetup, cmdUpdate } from './config.js';
 import { cmdDownload, cmdEdit, cmdFetch, cmdReact, cmdReply, cmdSend, } from './actions.js';
+import { cmdClaim, cmdClaims, cmdRelease, cmdTail } from './tail.js';
 import { cmdTunnel, cmdWebhook } from './webhook.js';
 import { flagOne, isJson, parseArgs, writeJson, } from './util.js';
 const USAGE = `metro — Telegram + Discord stream for your Claude Code / Codex user
@@ -21,18 +22,30 @@ Usage:
   metro doctor                                Health check.
   metro stations                              List stations + capabilities.
   metro lines                                 List recently-seen conversations.
-  metro send <line> <text> [--image=<path>]… [--document=<path>]… [--voice=<path>] [--buttons=<json>]
+  metro send <line> <text> [--image=<path>]… [--document=<path>]… [--voice=<path>] [--buttons=<json>] [--no-claim] [--claim]
                                               Post a fresh message; repeat --image/--document for multi-file albums.
-  metro reply <line> <message_id> <text> [--image=… --document=… --voice=… --buttons=…]
+                                              First outbound on a DM auto-claims; --no-claim or METRO_NO_AUTO_CLAIM=1 opts out;
+                                              --claim forces auto-claim even on group/public lines.
+                                              Note: send/reply/edit/react read bot tokens from ~/.config/metro/.env and post
+                                              directly to the platform — METRO_STATE_DIR isolates claims/history but NOT creds.
+  metro reply <line> <message_id> <text> [--image=… --document=… --voice=… --buttons=…] [--no-claim] [--claim]
                                               Threaded reply (same flags as send).
-  metro edit <line> <message_id> <text> [--buttons=<json>]
+  metro edit <line> <message_id> <text> [--buttons=<json>] [--no-claim] [--claim]
                                               Edit a previously-sent message (text + buttons).
-  metro react <line> <message_id> <emoji>     Set or clear ('') a reaction.
+  metro react <line> <message_id> <emoji> [--no-claim] [--claim]
+                                              Set or clear ('') a reaction.
   metro download <line> <message_id> [--out=<dir>]
                                               Download image attachments to disk.
   metro fetch <line> [--limit=N]              Recent-message lookback (Discord only).
   metro history [--limit=N] [--line=…] [--station=…] [--kind=…] [--from=…] [--text=…] [--since=…]
                                               Read the universal message log (newest first).
+  metro tail [--as=<user-uri>] [--follow] [--strict | --unclaimed | --all] [--include-webhooks]
+             [--chat=<line>] [--station=…] [--since=<offset|tail>] [--limit=N]
+                                              Subscribe to the event log; claim-aware by default. See docs/broker.md.
+                                              Webhooks are hidden in personal modes unless --include-webhooks is set.
+  metro claim <line> [--as=<user-uri>]        Take exclusive ownership of a line (so only you receive its events).
+  metro release <line>                        Release a line (it returns to broadcast).
+  metro claims                                Print the current claims map.
   metro webhook add <label> [--secret=…]      Register an HTTP receive endpoint (GitHub, Intercom, …).
   metro webhook list | remove <id>            List or remove webhook endpoints.
   metro tunnel setup <name> <hostname>        Configure a Cloudflare named tunnel (run cloudflared tunnel login first).
@@ -140,7 +153,9 @@ const COMMANDS = {
     send: cmdSend, reply: cmdReply, edit: cmdEdit, react: cmdReact,
     download: cmdDownload, fetch: cmdFetch,
     webhook: cmdWebhook, tunnel: cmdTunnel,
-    history: cmdHistory, update: cmdUpdate,
+    history: cmdHistory, tail: cmdTail,
+    claim: cmdClaim, release: cmdRelease, claims: cmdClaims,
+    update: cmdUpdate,
 };
 async function main() {
     const cmd = process.argv[2];

package/dist/cli/tail.js

@@ -0,0 +1,164 @@
+/** CLI subcommands: `metro tail` (claim-aware log subscriber) + `metro claim|release|claims`. */
+import { existsSync, watch } from 'node:fs';
+import { CLAIMS_FILE, HISTORY_FILE, claimLine, cursorKey, historySize, passesMode, readClaims, readCursor, readEntriesFrom, releaseLine, writeCursor, } from '../broker.js';
+import { userSelf } from '../history.js';
+import { asLine } from '../stations/index.js';
+import { loadMetroEnv } from '../paths.js';
+import { emit, exitErr, flagOne, isJson, need, writeJson } from './util.js';
+function resolveMode(f, self) {
+    const strict = f.strict === true, unclaimed = f.unclaimed === true, all = f.all === true;
+    if ([strict, unclaimed, all].filter(Boolean).length > 1) {
+        throw exitErr('--strict, --unclaimed, --all are mutually exclusive', 1);
+    }
+    if (strict) {
+        if (!self)
+            throw exitErr('--strict requires --as <user-uri>', 1);
+        return 'mine-only';
+    }
+    if (unclaimed)
+        return 'unclaimed';
+    if (all || !self)
+        return 'all';
+    return 'mine-or-unclaimed';
+}
+/** Generic fallback returned by `userSelf()` when there's no Claude/Codex env — treat as "no identity". */
+const GENERIC_USER = 'metro://user';
+function resolveSelf(f) {
+    const raw = flagOne(f, 'as');
+    if (raw !== undefined)
+        return asLine(raw);
+    const auto = userSelf();
+    return auto === GENERIC_USER ? null : auto;
+}
+function resolveStartOffset(f, key) {
+    const since = flagOne(f, 'since');
+    if (since === 'tail')
+        return historySize();
+    if (since !== undefined) {
+        const n = Number(since);
+        if (!Number.isFinite(n) || n < 0)
+            throw exitErr(`--since must be a byte offset or 'tail' (got '${since}')`, 1);
+        return n;
+    }
+    return key ? readCursor(key) : 0;
+}
+export async function cmdTail(_, f) {
+    loadMetroEnv();
+    const self = resolveSelf(f);
+    const mode = resolveMode(f, self);
+    const follow = f.follow === true;
+    const chatFilter = flagOne(f, 'chat');
+    const stationFilter = flagOne(f, 'station');
+    const limit = Number(flagOne(f, 'limit')) || 0;
+    const json = isJson(f);
+    const includeWebhooks = f['include-webhooks'] === true;
+    /** Cursor key derives from the effective mode (not userSelf), so `--all` / `--unclaimed` */
+    /** don't trample the personal `--as=<me>` cursor in a CLAUDECODE shell. */
+    const key = cursorKey(mode, self, { includeWebhooks });
+    const startOffset = resolveStartOffset(f, key);
+    let emitted = 0;
+    let offset = startOffset;
+    const drain = () => {
+        /** read claims once per drain so a burst of events shares a snapshot */
+        const claims = readClaims();
+        for (const { entry, offset: next } of readEntriesFrom(offset)) {
+            offset = next;
+            if (chatFilter && entry.line !== chatFilter)
+                continue;
+            if (stationFilter && entry.station !== stationFilter)
+                continue;
+            if (!passesMode(entry, mode, self, claims, { includeWebhooks }))
+                continue;
+            if (json)
+                process.stdout.write(JSON.stringify(entry) + '\n');
+            else
+                process.stdout.write(fmtRow(entry) + '\n');
+            if (key)
+                writeCursor(key, offset);
+            emitted++;
+            if (limit && emitted >= limit)
+                return true;
+        }
+        return false;
+    };
+    if (drain() && !follow)
+        return;
+    if (!follow)
+        return;
+    /** fs.watch on macOS sometimes coalesces or drops events — poll every 500ms as a backstop. */
+    await new Promise(resolve => {
+        let watcher = null;
+        const trigger = () => { if (drain())
+            cleanup(); };
+        const cleanup = () => {
+            if (watcher) {
+                try {
+                    watcher.close();
+                }
+                catch { /* ignore */ }
+                watcher = null;
+            }
+            clearInterval(poll);
+            resolve();
+        };
+        const poll = setInterval(trigger, 500);
+        const startWatcher = () => {
+            if (!existsSync(HISTORY_FILE))
+                return;
+            try {
+                watcher = watch(HISTORY_FILE, () => trigger());
+            }
+            catch { /* ignore — poll will catch */ }
+        };
+        startWatcher();
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+        process.stdin.on('end', cleanup).on('close', cleanup);
+    });
+}
+function fmtRow(e) {
+    const ts = e.ts.slice(11, 19);
+    const body = e.text ?? (e.emoji ? `[react ${e.emoji}]` : '');
+    const text = body.length > 80 ? body.slice(0, 79) + '…' : body;
+    const who = (e.fromName ?? e.from).padEnd(28).slice(0, 28);
+    const where = e.line.padEnd(40).slice(0, 40);
+    return `${ts}  ${e.id.padEnd(12)}  ${e.kind.padEnd(8)}  ${who}  ${where}  ${text}`;
+}
+export async function cmdClaim(p, f) {
+    loadMetroEnv();
+    need(p, 1, 'metro claim <line> [--as <user-uri>]');
+    const line = asLine(p[0]);
+    const asRaw = flagOne(f, 'as');
+    const owner = asRaw ? asLine(asRaw) : userSelf();
+    const claims = claimLine(line, owner);
+    emit(f, `claimed ${line} → ${owner}`, { ok: true, line, owner, claims });
+}
+export async function cmdRelease(p, f) {
+    loadMetroEnv();
+    need(p, 1, 'metro release <line>');
+    const line = asLine(p[0]);
+    const { released, claims } = releaseLine(line);
+    if (!released) {
+        emit(f, `${line} was not claimed`, { ok: true, released: false, line, claims });
+        return;
+    }
+    emit(f, `released ${line}`, { ok: true, released: true, line, claims });
+}
+export async function cmdClaims(_, f) {
+    loadMetroEnv();
+    const claims = readClaims();
+    const entries = Object.entries(claims);
+    if (isJson(f))
+        return writeJson({ claims });
+    if (!entries.length) {
+        process.stdout.write('(no claims — every tail with matching filters receives every event)\n');
+        process.stdout.write(`file: ${CLAIMS_FILE}${existsSync(CLAIMS_FILE) ? '' : ' (not created yet)'}\n`);
+        return;
+    }
+    const widest = Math.max(...entries.map(([l]) => l.length));
+    process.stdout.write('metro claims\n\n');
+    for (const [line, owner] of entries) {
+        process.stdout.write(`  ${line.padEnd(widest)}  →  ${owner}\n`);
+    }
+    process.stdout.write(`\n${entries.length} claim${entries.length === 1 ? '' : 's'} · ${CLAIMS_FILE}\n`);
+}

package/dist/history.js

@@ -35,12 +35,14 @@ export function appendHistory(entry) {
         log.warn({ err: errMsg(err), path: FILE }, 'history append failed');
     }
 }
-/** Read JSONL, parse, filter (most-recent-first), apply `limit`. Empty array if file is missing. */
+/** Read JSONL, parse, filter (most-recent-first), apply `skip` then `limit`. Empty array if file is missing. */
 export function readHistory(filter = {}) {
     if (!existsSync(FILE))
         return [];
     const lines = readFileSync(FILE, 'utf8').split('\n');
     const out = [];
+    const skip = filter.skip ?? 0;
+    let skipped = 0;
     /** Walk backwards so `limit` clamps without scanning the whole file body twice. */
     for (let i = lines.length - 1; i >= 0; i--) {
         const raw = lines[i].trim();
@@ -55,6 +57,10 @@ export function readHistory(filter = {}) {
         }
         if (!matches(e, filter))
             continue;
+        if (skipped < skip) {
+            skipped++;
+            continue;
+        }
         out.push(e);
         if (filter.limit && out.length >= filter.limit)
             break;

package/dist/monitor.js

@@ -0,0 +1,194 @@
+/** Read-only HTTP monitor endpoints. `/api/state` (snapshot) + `/api/tail` (SSE). */
+/** Mounted on the webhook server. Bearer auth via METRO_MONITOR_TOKEN (503 when unset). */
+import { timingSafeEqual } from 'node:crypto';
+import { watch } from 'node:fs';
+import pkg from '../package.json' with { type: 'json' };
+import { errMsg, log } from './log.js';
+import { HISTORY_FILE, historySize, passesMode, readClaims, readEntriesFrom, } from './broker.js';
+import { readBotIds } from './cache.js';
+import { readHistory } from './history.js';
+import { asLine } from './stations/index.js';
+const HISTORY_LIMIT = 100;
+function authorized(req) {
+    const token = process.env.METRO_MONITOR_TOKEN;
+    if (!token)
+        return { ok: false, status: 503, msg: 'monitor endpoints not configured (METRO_MONITOR_TOKEN unset)' };
+    const header = req.headers['authorization'];
+    const value = Array.isArray(header) ? header[0] : header;
+    if (!value || !value.startsWith('Bearer '))
+        return { ok: false, status: 401, msg: 'unauthorized' };
+    const given = Buffer.from(value.slice('Bearer '.length));
+    const want = Buffer.from(token);
+    if (given.length !== want.length || !timingSafeEqual(given, want)) {
+        return { ok: false, status: 401, msg: 'unauthorized' };
+    }
+    return { ok: true };
+}
+/** Hosts that serve `/api/*`. webhook.metro.box stays scoped to /wh/*. */
+const MONITOR_HOSTS = new Set(['monitor.metro.box', 'localhost', '127.0.0.1']);
+function monitorHostAllowed(req) {
+    const raw = req.headers[':authority'] ?? req.headers.host;
+    if (!raw)
+        return true;
+    return MONITOR_HOSTS.has(raw.split(':')[0].toLowerCase());
+}
+export function handleMonitorRequest(req, res) {
+    const url = req.url ?? '';
+    if (!url.startsWith('/api/'))
+        return false;
+    if (!monitorHostAllowed(req))
+        return false; // let outer router 404 it
+    const [pathOnly, queryString = ''] = url.split('?', 2);
+    if (req.method !== 'GET') {
+        res.writeHead(405, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'method not allowed' }));
+        return true;
+    }
+    const auth = authorized(req);
+    if (!auth.ok) {
+        res.writeHead(auth.status, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: auth.msg }));
+        return true;
+    }
+    const query = new URLSearchParams(queryString);
+    if (pathOnly === '/api/state') {
+        handleState(res, query);
+        return true;
+    }
+    if (pathOnly === '/api/tail') {
+        handleTail(req, res, query).catch(err => {
+            log.warn({ err: errMsg(err) }, 'monitor: tail handler error');
+            try {
+                if (!res.headersSent)
+                    res.writeHead(500).end();
+                else
+                    res.end();
+            }
+            catch { /* ignore */ }
+        });
+        return true;
+    }
+    res.writeHead(404, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: 'not found' }));
+    return true;
+}
+function parseNonNegInt(raw) {
+    if (raw === null)
+        return null;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n))
+        return null;
+    return n;
+}
+function handleState(res, query) {
+    const before = parseNonNegInt(query.get('before'));
+    const limitRaw = parseNonNegInt(query.get('limit'));
+    /** Page mode: skip `before` newest entries, return next `limit` (default HISTORY_LIMIT, capped at 500). */
+    if (before !== null) {
+        const limit = Math.min(limitRaw ?? HISTORY_LIMIT, 500);
+        const page = readHistory({ limit, skip: before });
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ recent_history: page }));
+        return;
+    }
+    /** `readHistory` is newest-first — what the activity feed expects. */
+    const limit = Math.min(limitRaw ?? HISTORY_LIMIT, 500);
+    const recent = readHistory({ limit });
+    const claims = readClaims();
+    const linesSet = new Set();
+    for (const e of recent)
+        linesSet.add(e.line);
+    for (const line of Object.keys(claims))
+        linesSet.add(line);
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({
+        claims,
+        lines: [...linesSet],
+        recent_history: recent,
+        bot_ids: readBotIds(),
+        version: pkg.version,
+    }));
+}
+/** Mirrors `cli/tail.ts:resolveMode` but operates on URLSearchParams. */
+function resolveQueryMode(query, self) {
+    const strict = query.get('strict') === 'true' || query.get('mode') === 'strict';
+    const unclaimed = query.get('unclaimed') === 'true' || query.get('mode') === 'unclaimed';
+    const all = query.get('all') === 'true' || query.get('mode') === 'all';
+    if ([strict, unclaimed, all].filter(Boolean).length > 1)
+        return 'all';
+    if (strict && self)
+        return 'mine-only';
+    if (unclaimed)
+        return 'unclaimed';
+    if (all || !self)
+        return 'all';
+    return 'mine-or-unclaimed';
+}
+async function handleTail(req, res, query) {
+    const asParam = query.get('as');
+    const self = asParam ? asLine(asParam) : null;
+    const mode = resolveQueryMode(query, self);
+    const chatFilter = query.get('chat');
+    const stationFilter = query.get('station');
+    const includeWebhooks = query.get('include_webhooks') === 'true';
+    res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache, no-transform',
+        'connection': 'keep-alive',
+        /** Bearer auth already gates us; CORS can be permissive. */
+        'access-control-allow-origin': '*',
+        /** Cloudflare/proxies buffer SSE without this hint. */
+        'x-accel-buffering': 'no',
+    });
+    /** `since=tail` (default) starts at EOF; `since=0` replays the full file. */
+    const since = query.get('since');
+    let offset = since === '0' ? 0 : historySize();
+    if (since && since !== '0' && since !== 'tail') {
+        const n = Number(since);
+        if (Number.isFinite(n) && n >= 0)
+            offset = n;
+    }
+    /** 4 KiB padding so Cloudflare's HTTP/2 buffer flushes (else holds 30+ s on free tier). */
+    res.write(`: metro monitor tail (mode=${mode}${self ? `, as=${self}` : ''})\n`);
+    res.write(`: ${'-'.repeat(4096)}\n\n`);
+    const drain = () => {
+        const claims = readClaims();
+        for (const { entry, offset: next } of readEntriesFrom(offset)) {
+            offset = next;
+            if (chatFilter && entry.line !== chatFilter)
+                continue;
+            if (stationFilter && entry.station !== stationFilter)
+                continue;
+            if (!passesMode(entry, mode, self, claims, { includeWebhooks }))
+                continue;
+            res.write(`id: ${entry.id}\n`);
+            res.write('event: history\n');
+            res.write(`data: ${JSON.stringify(entry)}\n\n`);
+        }
+    };
+    drain();
+    /** fs.watch coalesces on macOS — poll every 1s as a backstop. */
+    let watcher = null;
+    try {
+        watcher = watch(HISTORY_FILE, () => drain());
+    }
+    catch { /* file may not exist yet */ }
+    const poll = setInterval(drain, 1_000);
+    const keepalive = setInterval(() => res.write(': keepalive\n\n'), 25_000);
+    const cleanup = () => {
+        clearInterval(poll);
+        clearInterval(keepalive);
+        if (watcher) {
+            try {
+                watcher.close();
+            }
+            catch { /* ignore */ }
+        }
+        try {
+            res.end();
+        }
+        catch { /* ignore */ }
+    };
+    req.on('close', cleanup);
+    req.on('error', cleanup);
+}

package/dist/stations/webhook.js

@@ -3,6 +3,7 @@ import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
 import { errMsg, log } from '../log.js';
 import { mintId } from '../history.js';
+import { handleMonitorRequest } from '../monitor.js';
 import { findEndpoint, listEndpoints, webhookPort } from '../webhooks.js';
 import { Line } from './index.js';
 /** Synthesize an `event` tag from common provider-specific headers (GitHub, Intercom). */
@@ -51,6 +52,9 @@ export class WebhookStation {
         this.server = null;
     }
     async handle(req, res) {
+        /** Read-only monitor endpoints (`/api/state`, `/api/tail`) share this port. */
+        if (handleMonitorRequest(req, res))
+            return;
         const m = req.url?.match(/^\/wh\/([A-Za-z0-9_-]+)/);
         if (!m) {
             res.writeHead(404).end();

package/docs/broker.md

@@ -0,0 +1,214 @@
+# Metro broker
+
+Multi-user event routing. Turns metro from "one daemon → one stdout consumer" into "one daemon → N independently-subscribed users (Claude Code, Codex, anything) with durable, replayable delivery".
+
+## Why
+
+Today the dispatcher writes every inbound event to **its own stdout**, which only the parent process (one Claude Code, monitoring the daemon via `Monitor`) can read. Consequences:
+
+- **Throughput bottleneck**: bursts of inbound messages serialize behind whatever the single user is currently doing.
+- **No real sub-users**: `Agent`-tool sub-users can call `metro send` (IPC works from anywhere), but they cannot *receive* events — they have no stdout subscription.
+- **No multi-instance**: a second `claude` window or a separate `codex` process can't join in; the stream has one reader.
+- **No durability**: a user crashes mid-conversation → events emitted during the gap are lost; on restart it starts deaf.
+
+The fix is to treat metro as a tiny **durable message broker** over the event log that already exists ([history.ts](../src/history.ts), [user-registry.json](../src/registry.ts)).
+
+## Core idea
+
+One concept — a **claim** — and three on-disk files you can `cat`:
+
+| Concern              | File                                    | Role                                                                                                                              |
+|----------------------|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| Event log            | `$METRO_STATE_DIR/history.jsonl`        | Append-only JSONL — every inbound/outbound/edit/react. Already exists. The single source of truth.                                |
+| Claims               | `$METRO_STATE_DIR/claims.json`          | `{ <line>: <user-id> }` — flat map. A line in here is *exclusively* owned by that user. Absence = broadcast. New.                 |
+| Per-mode cursor      | `$METRO_STATE_DIR/cursors/<key>`        | Byte offset into `history.jsonl` — last-emitted position for one tail mode. New. Updated atomically after each emit.              |
+
+Cursor keys are derived from the *effective mode* (not from `userSelf()`), so `--all` and `--unclaimed` don't collide with a personal `--as=<id>` tail:
+
+| Tail invocation                  | Cursor key                         |
+|----------------------------------|------------------------------------|
+| `metro tail --as=<id>`           | `<userSlug(id)>`                   |
+| `metro tail --as=<id> --strict`  | `<userSlug(id)>--strict`           |
+| `metro tail --as=<id> --include-webhooks` | `<userSlug(id)>--with-webhooks` (or `…--strict--with-webhooks`) |
+| `metro tail --unclaimed`         | `_unclaimed`                       |
+| `metro tail --all`               | `_all`                             |
+
+The `_` prefix on the mode-keys can't collide with a real `userSelf()` slug (which always contains a station name like `claude-user-…`). Switching modes mid-stream keeps each cursor independent — a `tail --all` from a `CLAUDECODE=1` shell does **not** advance the personal `--as=<me>` cursor.
+
+`--chat=<line>` and `--station=<name>` are post-filters applied **after** cursor advancement, so they don't need their own cursor keys.
+
+Subscribers do not register with the daemon. They tail the log; the broker semantics emerge from one filtering rule applied at read time:
+
+> An event is delivered to a user when its `line` is **claimed by that user** *or* **claimed by no one**.
+
+That single rule covers every case the design needs to handle:
+
+- **Chat with one responder** — user claims the chat; other tailing users stop receiving it. No race.
+- **Webhook fan-out** — nobody claims; every user tailing a matching filter sees it.
+- **Operator observability** — `metro tail` with no `--as` (or `--all`) shows everything regardless of claims; doesn't take ownership.
+- **Sub-user onboarding** — sub-user claims its assigned chat before reading; parent stops receiving that chat without any coordination.
+
+There is no separate concept for "subscription" or "fan-out mode" — claims and their absence cover both. The dispatcher writes; tails filter; claims gate exclusivity. Three primitives, one rule.
+
+```
+                                ┌──────────────────────────┐
+   inbound (Discord/TG/web) ──► │  dispatcher              │ ──► history.jsonl  ◄── metro tail --as claude-A
+                                │  (writes log, no routing)│                    ◄── metro tail --as codex-B
+                                └──────────────────────────┘                    ◄── metro tail --as claude-sub-1
+                                                                                       (each holds its own cursor)
+```
+
+## CLI surface
+
+```bash
+# Tail the event log. --follow streams new entries via fs.watch.
+metro tail [--as <user-id>] [--follow] [--strict | --unclaimed | --all] [--include-webhooks]
+           [--chat <line>] [--station <name>] [--since <offset|tail>] [--limit <n>]
+
+# Claims: assert/release exclusive ownership of a line. Updates claims.json.
+metro claim   <line> [--as <user-id>]      # add/overwrite — last writer wins
+metro release <line>                       # remove (line returns to broadcast)
+metro claims                               # print current claims.json
+
+# Outbound actions auto-claim the line on first contact when topology is 1:1 (DM, claude/codex line).
+# Group / public / webhook lines are skipped by default — pass --claim to force.
+metro send  <line> <text>          [--no-claim] [--claim]
+metro reply <line> <msg-id> <text> [--no-claim] [--claim]
+metro edit  <line> <msg-id> <text> [--no-claim] [--claim]
+metro react <line> <msg-id> <emoji> [--no-claim] [--claim]
+# Or disable globally: METRO_NO_AUTO_CLAIM=1
+
+# Lease/ack — optional, v2. When enabled, an event is "in flight" with the
+# claimant; if no ack in N seconds the cursor isn't advanced and the next
+# `metro tail` re-emits.
+metro ack <event-id> --as <user-id>
+```
+
+`--as <user-id>` defaults to `userSelf()` ([history.ts:121](../src/history.ts#L121)) — the same stable identity already used in routing-aware code.
+
+### Subscription modes
+
+The same `metro tail` command serves four distinct callers — a working user, a strict worker, a router, and a human observer. Each maps to one mutually-exclusive flag controlling the claim-aware filter:
+
+| Mode               | Flag                       | Predicate                                                                       | Who uses it                                                |
+|--------------------|----------------------------|---------------------------------------------------------------------------------|------------------------------------------------------------|
+| **Mine + free**     | `--as <id>` (default)      | `(claims[line] == <id> ∨ line ∉ claims) ∧ station ≠ 'webhook'`                  | Default working user. Zero-config single-user setup.       |
+| **Mine only**       | `--as <id> --strict`        | `claims[line] == <id> ∧ station ≠ 'webhook'`                                    | Disciplined worker that won't race on unclaimed events.    |
+| **Unclaimed only**  | `--unclaimed`              | `line ∉ claims`                                                                 | Router/first-responder user that finds work to claim.      |
+| **All**             | (no `--as`) or `--all`     | `true`                                                                          | Operator/auditor/debugger; never takes ownership.          |
+
+Webhooks (`station == 'webhook'`) are excluded from the personal modes by default — they're broadcast traffic (GitHub pushes, Intercom pings, etc.) that should flow to the *router* (`--unclaimed`) or *operator* (`--all`) feed, not firehose into every `--as <id>` tail. Opt back in with `metro tail --as <id> --include-webhooks` when you genuinely want a worker to see them.
+
+Two UX defaults worth being explicit about:
+
+1. **`--as <id>` with no mode flag = "mine + free".** Single-user setups (the common case) get zero-config metro: nothing claimed yet, so the only tail sees everything. Adding a second user means claiming first — surfaced in docs, not enforced by the daemon. `--strict` is the opt-in for setups that want stricter separation.
+2. **No `--as` = "all".** Matches the unix `tail -f` mental model. Operators just want to read the log without registering an identity or accidentally taking ownership of anything.
+
+`--unclaimed` is the genuinely new primitive: it enables a "router" user pattern where one process watches for ownerless events and either responds directly or claims and delegates. It works with or without `--as` — with `--as`, outbound replies are still attributed correctly.
+
+Direct messages between users (`event.to == user-line`) always pass the filter regardless of mode — they're inherently 1:1 and can't be "claimed" by someone else.
+
+### Auto-claim on outbound
+
+`metro send`, `reply`, `edit`, and `react` claim the target `<line>` for the actor (`userSelf()`) the first time they touch it, atomically — same lockfile as `metro claim`. The intent: when a user picks up a conversation by replying, subsequent inbound events on that line route to them without any explicit `metro claim` call.
+
+Auto-claim only fires when **the line topology is 1:1** (DM, or a Claude/Codex cross-user line). Shared lines — group chats, public channels, webhook streams — would lock out other workers, so they're skipped by default:
+
+| Line                                            | Classification | Auto-claim default? | How                                                          |
+|-------------------------------------------------|----------------|---------------------|--------------------------------------------------------------|
+| `metro://telegram/<positive-id>` (incl. topics) | DM             | Yes                 | Telegram chat-id > 0 ⇒ private chat                          |
+| `metro://telegram/<negative-id>` / `-100…`      | group          | **No**              | Telegram chat-id < 0 ⇒ group/supergroup                      |
+| `metro://discord/<channel-id>` (no guild)       | DM             | Yes                 | Recent inbound payload `guildId == null`                     |
+| `metro://discord/<channel-id>` (in guild)       | group          | **No**              | Recent inbound payload `guildId != null`                     |
+| `metro://discord/<channel-id>` (no inbound)     | unknown        | Yes (conservative)  | No metadata cached — treat as DM-eligible until proven group |
+| `metro://claude/...` / `metro://codex/...`      | 1:1            | Yes                 | Cross-user notify is inherently 1:1 by construction          |
+| `metro://webhook/<id>`                          | broadcast      | **Never**           | Webhook lines are conceptually a stream, not a conversation  |
+
+- If the line is already claimed by **someone else** (and topology check passed), the action still proceeds (sending doesn't require ownership) but the claim is **not overwritten**. A single-line stderr note (`auto-claim skipped: line owned by <other-id>`) signals the no-op.
+- On a group-line skip you'll see `auto-claim skipped: <line> is a group/public line; pass --claim to take it explicitly` on stderr.
+- Opt-out per command with `--no-claim`, or globally with the env var `METRO_NO_AUTO_CLAIM=1`.
+- Opt-IN for groups: `--claim` forces auto-claim even on a group/public line (operator explicitly takes responsibility).
+- Cross-user sends (`metro send metro://claude/... ...` from a different user) auto-claim the target line too — the sender is taking ownership of the conversation.
+
+This default plus the webhook-exclusion above means: a webhook or a busy group channel flowing through the daemon won't auto-claim under any worker, so the router pattern (`--unclaimed`) can still see them.
+
+### `metro tail` mechanics
+
+- Reads `history.jsonl`, applies the mode predicate + any `--chat`/`--station` filters (AND), prints one JSONL line per event to stdout.
+- With `--follow`: stays open, watches the file via `fs.watch`, emits new matching lines as they're appended.
+- Maintains a per-user cursor (byte offset) at `cursors/<user-id>`. On startup, resumes from cursor; on each emitted line, the offset is advanced *after* the write succeeds. Byte offsets give O(1) resume — no file scan.
+- `--since <offset>` overrides the cursor; `--since=tail` starts from EOF, ignoring backlog. Useful for fresh-start without losing the persisted cursor.
+- Claim lookups read `claims.json` once per emitted event. The file is small (a few KB) and OS-cached; cost is sub-microsecond per event.
+
+### `metro claim` semantics
+
+- Pure metadata edit on `claims.json`. Does **not** notify the daemon — claims are read by tails, not the dispatcher (see "Dispatcher changes" below).
+- Re-claiming a line re-assigns it (last writer wins). `metro claims` prints the current map so a human can audit.
+- Releasing a line returns it to broadcast — every matching tail picks it up again.
+- Writes to `claims.json` are wrapped in an `O_EXCL` lockfile to serialize concurrent `metro claim` invocations on the same host.
+
+## Dispatcher changes
+
+Almost none. `emit()` still appends to history, pushes to codex-rc, and writes to stdout. The broker model lives entirely on the read side — claims and cursors are consulted by `metro tail`, not by the dispatcher. The dispatcher doesn't need to know who's listening or who's claimed what.
+
+This is the design's key simplification: **the daemon stays dumb**. It's still a single-writer to a JSONL file. All the routing intelligence is in `metro tail`'s filter, which reads two small files (`claims.json` and its own cursor) on each event.
+
+No new sockets. No fan-out bookkeeping. No coupling between subscriber count and daemon state.
+
+## What this enables
+
+- **Sub-users that actually receive events**: `Agent` spawns a sub-user whose first action is `metro tail --as <its-id> --chat <line> --follow &` — it then `Monitor`s that background process and gets *only* its assigned chat's events.
+- **Two manual Claude Code windows**: each runs `metro tail --as claude-A` / `claude-B`, claims disjoint chats. No coordination beyond `metro claim`.
+- **Codex alongside Claude**: same model — `metro tail --as codex-1 --station telegram` etc. The codex-rc push becomes optional: a Codex worker can subscribe via `metro tail` directly and bypass the rc file.
+- **Crash recovery**: process dies → restarts → `metro tail` resumes from cursor → backlog replays in order. No double-replies (the cursor is advanced on emit, not on reply).
+- **Replay for new joiners**: `metro tail --as new-user --since <offset-from-5-min-ago>` lets a freshly-spawned process backfill recent history before going live.
+
+## Concurrency
+
+Multiple processes already write `history.jsonl` today: the daemon's `emit()` and every short-lived CLI invocation (`metro send`/`reply`/`react` — see [actions.ts](../src/cli/actions.ts)). It works because `appendFileSync` opens with `O_APPEND`, and POSIX guarantees that `O_APPEND` writes atomically seek-to-end-and-write in one operation — concurrent writers produce whole lines in some order, never interleaved halves. Node issues one `write(2)` per `appendFileSync` call, and our entries (even fat webhook payloads) stay well under per-syscall atomicity limits on both Linux (~2GB) and macOS (`INT_MAX`). The broker model adds **only readers**, so the existing safety property is preserved.
+
+`claims.json` is read on every event by every tail, but writes are infrequent (`metro claim`/`release`). An `O_EXCL` lockfile around writes is enough; tails do an unlocked read with a malformed-JSON retry (one read can race with one write; the retry resolves it).
+
+## Isolation
+
+`METRO_STATE_DIR` isolates state-dir-scoped artifacts (`history.jsonl`, `claims.json`, `cursors/`, `lines.json`, `bot-ids.json`, the daemon socket, the webhook port). It does **not** isolate platform credentials: `metro send`, `reply`, `edit`, and `react` always read bot tokens from `$XDG_CONFIG_HOME/metro/.env` (defaulting to `~/.config/metro/.env`) and post directly to Discord/Telegram regardless of where `METRO_STATE_DIR` points.
+
+This means a test invocation with `METRO_STATE_DIR=/tmp/metro-test metro send …` will hit the **production** Discord/Telegram bot with production tokens. To avoid leaking real messages from a test/sandbox:
+
+- Use lines whose channel/chat IDs you know don't exist (the platform will 4xx before any side-effect).
+- Or unset/move `~/.config/metro/.env` for the test process — `metro send` will fail fast with a missing-token error.
+- Or use `metro tail` + manual `history.jsonl` seeding to exercise the read path without any platform contact.
+
+The auto-claim write happens **after** platform-API success, so a failed `metro send` never writes to `claims.json`. (Tests can rely on this: a failing send leaves the test state dir unchanged apart from the `history.jsonl` line the daemon would emit, if one were running.)
+
+## Failure modes & guardrails
+
+| Failure                             | Behavior                                                                                          |
+|-------------------------------------|---------------------------------------------------------------------------------------------------|
+| Process crashes mid-event           | Cursor not advanced → event redelivered on next `metro tail`. At-least-once.                      |
+| Two users claim same line           | `claims.json` last-write-wins. `metro claims` shows current owner; humans resolve.                |
+| No user claims a chat               | Event broadcasts to every tail whose filters match. Two tails without filters → both reply (operator error — claim should have been set first). |
+| User silently slow (no ack)         | v1: not detected. v2: `metro ack` + lease TTL — cursor doesn't advance, next `metro tail` re-emits, can surface "X went dark on chat Y" via an inbound event from another user. |
+| `history.jsonl` grows unboundedly   | Existing concern; out of scope for this doc. (Rotate by date, prune by age.)                      |
+
+## Migration
+
+All changes are additive. With no subscribers, the dispatcher behaves exactly as today (parent reads stdout, single-user throughput, no routing). The broker model layers on top:
+
+1. Ship `metro tail` (read-only, no daemon changes, no claim file). Users can subscribe and filter; multi-cast works for everything.
+2. Ship `metro claim`/`release`/`claims` + claim-aware filtering in `metro tail`. Exclusivity works.
+3. Optional v2: lease/ack — only if silent drops become a real problem.
+
+Each step is independently shippable.
+
+## Open questions
+
+- **Routing-key granularity**: claims map to `user-id` (orgId-level — same across sessions/devices) rather than `user-line` (`<user-id>/<session-id>`). This means two Claude Code windows logged into the same account share claims. The session-scoped alternative is more flexible but requires the claimant to write its current `selfLine()` into `claims.json` and refresh it when the session changes. **Default: user-id.** Override per-claim with `metro claim <line> --as <full-line>` if needed.
+- **codex-rc deprecation**: today the dispatcher mirrors every event into a codex-rc file so Codex sees them. Once `metro tail` exists, Codex workers could subscribe directly. The rc-push stays for compatibility; the next major version can drop it.
+
+## Non-goals
+
+- **Strict ordering across chats**: events within one `line` are ordered by JSONL append order; cross-chat ordering is best-effort. Subscribers shouldn't rely on it.
+- **Exactly-once delivery**: at-least-once via cursor + redelivery. Idempotency is the subscriber's problem (the daemon already mints stable `msg_*` ids).
+- **Authn between users**: any process with filesystem access to `$METRO_STATE_DIR` can tail and claim. Same trust model as today.
+- **Remote users**: broker is local-only. Cross-host fan-out is a separate problem (likely solved by running metro on each host and bridging at the chat layer).

package/docs/monitor.md

@@ -0,0 +1,163 @@
+# Metro monitor endpoints
+
+Read-only HTTP endpoints for an external observer (the `apps/app` mobile app, an admin
+dashboard, a curl one-liner) to view live daemon state without touching the JSONL files
+directly.
+
+These endpoints mount on the **existing** webhook HTTP server (default port `8420`).
+There is no separate daemon, no separate port, no extra process to launch.
+
+## Routes
+
+| Method | Path         | Returns                                                                                  |
+|--------|--------------|------------------------------------------------------------------------------------------|
+| GET    | `/api/state` | JSON snapshot — `{ claims, lines, recent_history (last 100), bot_ids }`.                 |
+| GET    | `/api/tail`  | Server-Sent Events stream — `history.jsonl` entries, claim-aware filtered.                |
+
+Both routes are **read-only**. The daemon never mutates state on receipt. The handlers
+read the same files the broker reads (`history.jsonl`, `claims.json`, `bot-ids.json`)
+under whatever `METRO_STATE_DIR` resolves to.
+
+## Authentication
+
+Bearer token in env: `METRO_MONITOR_TOKEN`.
+
+- If unset, both routes respond **503** with `{"error":"monitor endpoints not configured (METRO_MONITOR_TOKEN unset)"}`. Anonymous access is never allowed by accident.
+- If set, requests **must** carry `Authorization: Bearer <token>`. Missing/wrong/malformed → **401**. The comparison is constant-time (`crypto.timingSafeEqual`).
+
+Set in `~/.config/metro/.env`:
+
+```
+METRO_MONITOR_TOKEN=<a long random string — `openssl rand -base64 32`>
+```
+
+The daemon picks up the env var on next start.
+
+## `GET /api/state`
+
+Returns a one-shot JSON snapshot:
+
+```jsonc
+{
+  "claims": {
+    "metro://discord/123456789": "metro://claude/user/abc"
+  },
+  "lines": [
+    "metro://discord/123456789",
+    "metro://telegram/-100…"
+  ],
+  "recent_history": [/* most-recent-first, up to 100 HistoryEntry objects */],
+  "bot_ids": { "discord": "1234567890", "telegram": "987654321" }
+}
+```
+
+- `claims` — verbatim contents of `claims.json`.
+- `lines` — the set of conversation URIs seen across recent history and current claims (good-enough proxy for "what lines exist right now"). Subject to refinement; not authoritative.
+- `recent_history` — same shape as `HistoryEntry` in `src/history.ts`, ordered most-recent-first, capped at 100 entries.
+- `bot_ids` — verbatim contents of `bot-ids.json`.
+
+### Example
+
+```bash
+curl -H "Authorization: Bearer $METRO_MONITOR_TOKEN" \
+  https://monitor.metro.box/api/state | jq
+```
+
+## `GET /api/tail` (SSE)
+
+Server-Sent Events stream of new `history.jsonl` entries. Each event has:
+
+```
+id: <metro-msg-id>
+event: history
+data: <one HistoryEntry as JSON>
+
+```
+
+The stream stays open until the client disconnects. A `: keepalive` comment is emitted
+every 25 seconds to keep proxies happy.
+
+### Query parameters
+
+All optional. Mirror the `metro tail` CLI flags.
+
+| Param              | Default     | Effect                                                                  |
+|--------------------|-------------|-------------------------------------------------------------------------|
+| `as=<line>`        | (none)      | Self URI — enables "mine + free" claim-aware filtering.                  |
+| `mode=strict\|unclaimed\|all` | derived | Override the mode (`strict` needs `as=`).                            |
+| `chat=<line>`      | (none)      | Only emit events matching this exact `line`.                            |
+| `station=<name>`   | (none)      | Only emit events matching this station (`discord`, `telegram`, …).      |
+| `include_webhooks=true` | `false`  | Include webhook-station events in personal modes.                       |
+| `since=tail\|0\|<offset>` | `tail` | Where to start in `history.jsonl`. `tail` = EOF; `0` = full replay; or a byte offset. |
+
+### Filter rule
+
+Same predicate as `metro tail --as=<id> [--strict|--unclaimed|--all] [--include-webhooks]`:
+
+> An event is delivered when its `line` is **claimed by `as=`** *or* **claimed by no one**,
+> minus webhooks (unless `include_webhooks=true`), minus anything failing `chat=`/`station=`.
+
+See [broker.md](./broker.md) for the underlying broker semantics.
+
+### Example: live tail for a claude user
+
+```bash
+curl -N \
+  -H "Authorization: Bearer $METRO_MONITOR_TOKEN" \
+  "https://monitor.metro.box/api/tail?as=metro://claude/user/abc&include_webhooks=true"
+```
+
+The `-N` flag disables curl's output buffering so SSE frames appear as they arrive.
+
+### Example: full backlog replay for debugging
+
+```bash
+curl -N \
+  -H "Authorization: Bearer $METRO_MONITOR_TOKEN" \
+  "https://monitor.metro.box/api/tail?since=0"
+```
+
+## Exposing publicly via Cloudflare tunnel
+
+The daemon listens on `127.0.0.1:8420` only. To reach `/api/*` from a phone or a
+remote machine, route a public hostname through the existing `webhook.metro.box`
+cloudflared tunnel.
+
+Add a second hostname route to your `cloudflared` config (typically
+`~/.cloudflared/config.yml`):
+
+```yaml
+ingress:
+  - hostname: webhook.metro.box
+    service: http://127.0.0.1:8420
+  - hostname: monitor.metro.box     # new — same backing service
+    service: http://127.0.0.1:8420
+  - service: http_status:404
+```
+
+Then create the DNS record:
+
+```bash
+cloudflared tunnel route dns <tunnel-name> monitor.metro.box
+```
+
+Restart the tunnel; both hostnames now reach the same metro daemon. `webhook.metro.box`
+keeps serving inbound webhooks; `monitor.metro.box` serves the bearer-token-gated
+monitor routes.
+
+There's no harm in serving `/api/*` from `webhook.metro.box` too — the bearer-token
+gate is the same either way. The separate hostname is purely a routing convenience
+(and lets you put different access policies in front of each, e.g., Cloudflare Access
+on `monitor.metro.box` only).
+
+## Failure modes
+
+| Condition                          | Response                                                          |
+|------------------------------------|-------------------------------------------------------------------|
+| `METRO_MONITOR_TOKEN` not set      | 503 `{"error":"monitor endpoints not configured (...)"}`         |
+| Missing `Authorization` header     | 401 `{"error":"unauthorized"}`                                    |
+| Wrong / malformed token            | 401 `{"error":"unauthorized"}`                                    |
+| Unknown `/api/*` path              | 404 `{"error":"not found"}`                                       |
+| `POST` (or any non-`GET`) to `/api/*` | 405 `{"error":"method not allowed"}`                            |
+| `history.jsonl` doesn't exist yet  | 200 with empty `recent_history` / SSE stream w/ no events.       |
+| Client disconnects mid-SSE         | Handler clears its interval + closes the file watcher cleanly.   |

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.11",
+  "version": "0.1.0-beta.13",
+  "private": false,
   "description": "Live JSON stream of Telegram + Discord messages for your local Claude Code / Codex session. The user launches metro; metro emits inbounds on stdout and accepts replies via CLI subcommands.",
   "license": "MIT",
   "repository": {
@@ -31,7 +32,8 @@
     "prepublishOnly": "tsc",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "METRO_STATE_DIR=\"$(mktemp -d /tmp/metro-test.XXXXXX)\" bun test test/"
   },
   "dependencies": {
     "discord.js": "^14.14.0",