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

package/dist/broker.js

@@ -4,6 +4,7 @@ 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');
@@ -62,7 +63,25 @@ export function releaseLine(line) {
         return { released, claims: m };
     });
 }
-export function tryAutoClaim(line, owner) {
+/** 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];
@@ -82,17 +101,34 @@ export function tryAutoClaim(line, owner) {
 export function userSlug(uri) {
     return uri.replace(/^metro:\/+/, '').replace(/[^A-Za-z0-9_.-]/g, '-');
 }
-const cursorPath = (uri) => join(CURSORS_DIR, userSlug(uri));
-export function readCursor(uri) {
-    const p = cursorPath(uri);
+/** 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(uri, offset) {
+export function writeCursor(key, offset) {
     mkdirSync(CURSORS_DIR, { recursive: true });
-    const p = cursorPath(uri);
+    const p = cursorPath(key);
     const tmp = `${p}.tmp.${process.pid}`;
     writeFileSync(tmp, String(offset));
     renameSync(tmp, p);

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

@@ -52,6 +52,37 @@ 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();
@@ -64,16 +95,25 @@ function logOutbound(f, e) {
     maybeAutoClaim(f, e.line, from);
     return id;
 }
-/** Auto-claim on outbound — skips when --no-claim or METRO_NO_AUTO_CLAIM=1; never overwrites a foreign owner. */
+/** 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 result = tryAutoClaim(line, owner);
+    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`);
     }

package/dist/cli/index.js

@@ -22,14 +22,17 @@ 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>] [--no-claim]
+  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.
-                                              First outbound auto-claims the line; --no-claim or METRO_NO_AUTO_CLAIM=1 opts out.
-  metro reply <line> <message_id> <text> [--image=… --document=… --voice=… --buttons=…] [--no-claim]
+                                              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>] [--no-claim]
+  metro edit <line> <message_id> <text> [--buttons=<json>] [--no-claim] [--claim]
                                               Edit a previously-sent message (text + buttons).
-  metro react <line> <message_id> <emoji> [--no-claim]
+  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.

package/dist/cli/tail.js

@@ -1,6 +1,6 @@
 /** CLI subcommands: `metro tail` (claim-aware log subscriber) + `metro claim|release|claims`. */
 import { existsSync, watch } from 'node:fs';
-import { CLAIMS_FILE, HISTORY_FILE, claimLine, historySize, passesMode, readClaims, readCursor, readEntriesFrom, releaseLine, writeCursor, } from '../broker.js';
+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';
@@ -30,7 +30,7 @@ function resolveSelf(f) {
     const auto = userSelf();
     return auto === GENERIC_USER ? null : auto;
 }
-function resolveStartOffset(f, self) {
+function resolveStartOffset(f, key) {
     const since = flagOne(f, 'since');
     if (since === 'tail')
         return historySize();
@@ -40,7 +40,7 @@ function resolveStartOffset(f, self) {
             throw exitErr(`--since must be a byte offset or 'tail' (got '${since}')`, 1);
         return n;
     }
-    return self ? readCursor(self) : 0;
+    return key ? readCursor(key) : 0;
 }
 export async function cmdTail(_, f) {
     loadMetroEnv();
@@ -50,9 +50,12 @@ export async function cmdTail(_, f) {
     const chatFilter = flagOne(f, 'chat');
     const stationFilter = flagOne(f, 'station');
     const limit = Number(flagOne(f, 'limit')) || 0;
-    const startOffset = resolveStartOffset(f, self);
     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 = () => {
@@ -70,8 +73,8 @@ export async function cmdTail(_, f) {
                 process.stdout.write(JSON.stringify(entry) + '\n');
             else
                 process.stdout.write(fmtRow(entry) + '\n');
-            if (self)
-                writeCursor(self, offset);
+            if (key)
+                writeCursor(key, offset);
             emitted++;
             if (limit && emitted >= limit)
                 return true;

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

@@ -21,7 +21,21 @@ One concept — a **claim** — and three on-disk files you can `cat`:
 |----------------------|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
 | 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-user cursor      | `$METRO_STATE_DIR/cursors/<user-id>`    | Byte offset into `history.jsonl` — last-emitted position for one user. New. Updated atomically after each emit.                   |
+| 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:
 
@@ -56,11 +70,12 @@ 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 (so subsequent inbounds route to you).
-metro send  <line> <text>          [--no-claim]    # skip auto-claim for this call
-metro reply <line> <msg-id> <text> [--no-claim]
-metro edit  <line> <msg-id> <text> [--no-claim]
-metro react <line> <msg-id> <emoji> [--no-claim]
+# 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
@@ -97,11 +112,25 @@ Direct messages between users (`event.to == user-line`) always pass the filter r
 
 `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.
 
-- If the line is already claimed by **someone else**, 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.
+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 is why webhooks are excluded from personal modes (above): a webhook flowing into `--as <id>` mode that triggered a reply would auto-claim the webhook line for the responder, silently locking out other workers from future events on that endpoint. Keeping webhooks in `--unclaimed`/`--all` only ensures the router pattern explicitly decides who picks up each event.
+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
 
@@ -140,6 +169,18 @@ Multiple processes already write `history.jsonl` today: the daemon's `emit()` an
 
 `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                                                                                          |

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.12",
+  "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": {
@@ -32,7 +33,7 @@
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "typecheck": "tsc --noEmit",
-    "test": "bun test test/"
+    "test": "METRO_STATE_DIR=\"$(mktemp -d /tmp/metro-test.XXXXXX)\" bun test test/"
   },
   "dependencies": {
     "discord.js": "^14.14.0",