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

package/dist/broker.js

@@ -0,0 +1,166 @@
+/** 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';
+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 };
+    });
+}
+export function tryAutoClaim(line, owner) {
+    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, '-');
+}
+const cursorPath = (uri) => join(CURSORS_DIR, userSlug(uri));
+export function readCursor(uri) {
+    const p = cursorPath(uri);
+    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) {
+    mkdirSync(CURSORS_DIR, { recursive: true });
+    const p = cursorPath(uri);
+    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/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);
@@ -55,21 +56,39 @@ function destinationFor(orig, line) {
 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 or METRO_NO_AUTO_CLAIM=1; never overwrites a foreign owner. */
+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);
+    if (result.status === 'skipped') {
+        process.stderr.write(`auto-claim skipped: line owned by ${result.existing}\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,27 @@ 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]
                                               Post a fresh message; repeat --image/--document for multi-file albums.
-  metro reply <line> <message_id> <text> [--image=… --document=… --voice=… --buttons=…]
+                                              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]
                                               Threaded reply (same flags as send).
-  metro edit <line> <message_id> <text> [--buttons=<json>]
+  metro edit <line> <message_id> <text> [--buttons=<json>] [--no-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]
+                                              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 +150,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,161 @@
+/** 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 { 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, self) {
+    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 self ? readCursor(self) : 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 startOffset = resolveStartOffset(f, self);
+    const json = isJson(f);
+    const includeWebhooks = f['include-webhooks'] === true;
+    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 (self)
+                writeCursor(self, 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/docs/broker.md

@@ -0,0 +1,173 @@
+# 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-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.                   |
+
+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 (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]
+# 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.
+
+- 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.
+- Opt-out per command with `--no-claim`, or globally with the env var `METRO_NO_AUTO_CLAIM=1`.
+- 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.
+
+### `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).
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.11",
+  "version": "0.1.0-beta.12",
   "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 +31,8 @@
     "prepublishOnly": "tsc",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "bun test test/"
   },
   "dependencies": {
     "discord.js": "^14.14.0",