@stage-labs/metro 0.1.0-beta.15 → 0.1.0-beta.151

package/dist/trains/protocol.js

@@ -1,99 +0,0 @@
-/** Train stdin/stdout protocol: line buffering + JSON envelope + outbound call bookkeeping. */
-import { readdirSync, statSync } from 'node:fs';
-import { join, parse as parsePath } from 'node:path';
-import { errMsg, log } from '../log.js';
-export const CALL_TIMEOUT_MS = 60_000;
-export const STDOUT_LINE_MAX = 4 * 1024 * 1024; // 4 MiB safeguard per line
-/** Classify a single parsed stdout line from a train. */
-export function parseTrainLine(name, line) {
-    let msg;
-    try {
-        msg = JSON.parse(line);
-    }
-    catch (err) {
-        log.warn({ name, err: errMsg(err), line: line.slice(0, 200) }, 'train: bad JSON');
-        return null;
-    }
-    if (msg.op === 'response') {
-        if (typeof msg.id !== 'string')
-            return { op: 'ignore' };
-        return { op: 'response', id: msg.id, result: msg.result, error: msg.error };
-    }
-    if (msg.op === 'log')
-        return { op: 'log', text: msg.text };
-    /** Anything without an `op` (or with `op:"event"`) is an inbound event. */
-    /** Defensive shape check: every event needs `line` (string). Log + drop if missing. */
-    if (typeof msg.line !== 'string') {
-        log.warn({ name, line: line.slice(0, 200) }, 'train: event missing `line` (string) — dropped');
-        return { op: 'ignore' };
-    }
-    return { op: 'event', event: msg };
-}
-/** Consume complete `\n`-terminated lines from a rolling buffer; invoke `onLine` for each. */
-/** Returns the leftover (incomplete) buffer to keep accumulating. */
-export function drainLines(name, buf, onLine) {
-    if (buf.length > STDOUT_LINE_MAX && !buf.includes('\n')) {
-        log.warn({ name, bytes: buf.length }, 'train: dropping oversized stdout line');
-        return '';
-    }
-    let nl;
-    while ((nl = buf.indexOf('\n')) !== -1) {
-        const line = buf.slice(0, nl).trim();
-        buf = buf.slice(nl + 1);
-        if (!line)
-            continue;
-        onLine(line);
-    }
-    return buf;
-}
-export function encodeCall(id, action, args) {
-    return JSON.stringify({ op: 'call', id, action, args }) + '\n';
-}
-function isTrainFile(name) {
-    return /\.(ts|js|mjs)$/.test(name) && !name.startsWith('_') && !name.startsWith('.');
-}
-/** Discover trains under `dir`: regular files with allowed extensions, no `_` / `.` prefix. */
-export function listTrainFiles(dir) {
-    return readdirSync(dir).filter(isTrainFile)
-        .map(f => ({ name: parsePath(f).name, path: join(dir, f) }))
-        .filter(t => { try {
-        return statSync(t.path).isFile();
-    }
-    catch {
-        return false;
-    } });
-}
-/* ──────────── outbound call bookkeeping (per-train pending map + timeout) ──────────── */
-export function mintCallId(seq) {
-    return `req_${seq}_${Math.random().toString(36).slice(2, 8)}`;
-}
-/** Reject + clear all pending calls on a train (used on shutdown/exit). */
-export function failAllPending(pending, reason) {
-    for (const p of pending.values()) {
-        clearTimeout(p.timer);
-        p.reject(new Error(reason));
-    }
-    pending.clear();
-}
-/** Dispatch `action` to a train's stdin and register a pending entry; returns the awaitable. */
-export function sendCall(t, id, action, args) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            t.pending.delete(id);
-            reject(new Error(`train '${t.name}' call '${action}' timed out after ${CALL_TIMEOUT_MS}ms`));
-        }, CALL_TIMEOUT_MS);
-        t.pending.set(id, { resolve, reject, timer });
-        try {
-            const stdin = t.proc?.stdin;
-            if (!stdin || typeof stdin === 'number')
-                throw new Error('stdin not piped');
-            stdin.write(encodeCall(id, action, args));
-            stdin.flush();
-        }
-        catch (err) {
-            clearTimeout(timer);
-            t.pending.delete(id);
-            reject(new Error(`train '${t.name}' stdin write failed: ${errMsg(err)}`));
-        }
-    });
-}

package/dist/trains/supervisor.js

@@ -1,210 +0,0 @@
-/** Train supervisor: spawn `~/.metro/trains/*.{ts,js,mjs}` under `bun run`, multiplex their */
-/** stdout (events + call-responses), route outbound calls to their stdin. Pure transport. */
-import { mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { errMsg, log } from '../log.js';
-import { userSelf } from '../history.js';
-import { drainLines, failAllPending, listTrainFiles, mintCallId, parseTrainLine, sendCall, } from './protocol.js';
-const RESTART_BACKOFFS_MS = [1_000, 5_000, 30_000];
-const MAX_CONSECUTIVE_FAILS = 5;
-export const TRAINS_DIR = process.env.METRO_TRAINS_DIR ?? join(homedir(), '.metro', 'trains');
-export class TrainSupervisor {
-    dir;
-    trains = new Map();
-    onEvent = null;
-    nextCallId = 1;
-    constructor(dir = TRAINS_DIR) {
-        this.dir = dir;
-    }
-    onTrainEvent(handler) { this.onEvent = handler; }
-    /** Discover trains under `dir` and spawn one subprocess per file. Creates the dir if missing. */
-    start() {
-        mkdirSync(this.dir, { recursive: true });
-        for (const t of listTrainFiles(this.dir))
-            this.startTrain(t.name, t.path);
-        log.info({ dir: this.dir, count: this.trains.size }, 'train supervisor: started');
-    }
-    /** Shut everything down (graceful: send SIGTERM, then SIGKILL after grace period). */
-    async stop() {
-        const tasks = [];
-        for (const t of this.trains.values()) {
-            t.stopped = true;
-            if (t.restartTimer) {
-                clearTimeout(t.restartTimer);
-                t.restartTimer = null;
-            }
-            failAllPending(t.pending, 'train shutting down');
-            const wait = killGracefully(t.proc);
-            if (wait)
-                tasks.push(wait);
-        }
-        await Promise.all(tasks);
-    }
-    list() {
-        return [...this.trains.values()].map(t => ({
-            name: t.name, path: t.path, running: !!(t.proc && t.proc.exitCode === null),
-            pid: t.proc?.pid ?? null, startedAt: t.startedAt, failCount: t.failCount,
-        }));
-    }
-    /** Kill + respawn a named train; resets fail counter so backoff starts fresh. */
-    async restart(name) {
-        const t = this.trains.get(name);
-        if (!t)
-            throw new Error(`no train named '${name}'`);
-        if (t.restartTimer) {
-            clearTimeout(t.restartTimer);
-            t.restartTimer = null;
-        }
-        failAllPending(t.pending, `train '${name}' restarting`);
-        t.stopped = true;
-        const wait = killGracefully(t.proc);
-        if (wait)
-            await wait;
-        t.stopped = false;
-        t.failCount = 0;
-        t.proc = null;
-        this.spawn(t);
-    }
-    /** Send a call to a named train and await the matching response. */
-    async call(name, action, args) {
-        const t = this.trains.get(name);
-        if (!t)
-            throw new Error(`no train named '${name}' (have: ${[...this.trains.keys()].join(', ') || '(none)'})`);
-        if (!t.proc || t.proc.exitCode !== null)
-            throw new Error(`train '${name}' is not running`);
-        return sendCall(t, mintCallId(this.nextCallId++), action, args);
-    }
-    startTrain(name, path) {
-        if (this.trains.has(name)) {
-            log.warn({ name }, 'train supervisor: duplicate name, skipping');
-            return;
-        }
-        const state = {
-            name, path, proc: null, pending: new Map(), buf: '', errBuf: '',
-            failCount: 0, restartTimer: null, startedAt: null, stopped: false,
-        };
-        this.trains.set(name, state);
-        this.spawn(state);
-    }
-    spawn(state) {
-        if (state.stopped)
-            return;
-        try {
-            const proc = Bun.spawn(['bun', 'run', state.path], {
-                stdin: 'pipe', stdout: 'pipe', stderr: 'pipe',
-                env: { ...process.env, METRO_TRAIN_NAME: state.name, METRO_SELF_URI: userSelf() },
-            });
-            state.proc = proc;
-            state.startedAt = new Date().toISOString();
-            state.buf = '';
-            state.errBuf = '';
-            log.info({ name: state.name, pid: proc.pid }, 'train: spawned');
-            void this.pumpStdout(state);
-            void this.pumpStderr(state);
-            void proc.exited.then(code => this.onExit(state, code ?? 0));
-        }
-        catch (err) {
-            log.warn({ name: state.name, err: errMsg(err) }, 'train: spawn failed');
-            this.scheduleRestart(state);
-        }
-    }
-    pumpStdout(state) {
-        return pumpStream(state.proc?.stdout, state.name, 'stdout', chunk => {
-            state.buf += chunk;
-            state.buf = drainLines(state.name, state.buf, line => this.handleLine(state, line));
-        });
-    }
-    /** Stream train stderr line-by-line into the daemon's logger so users see crashes/warnings. */
-    pumpStderr(state) {
-        return pumpStream(state.proc?.stderr, state.name, 'stderr', chunk => {
-            state.errBuf += chunk;
-            let nl;
-            while ((nl = state.errBuf.indexOf('\n')) !== -1) {
-                const line = state.errBuf.slice(0, nl).trimEnd();
-                state.errBuf = state.errBuf.slice(nl + 1);
-                if (line)
-                    log.warn({ train: state.name }, line);
-            }
-        });
-    }
-    handleLine(state, line) {
-        const msg = parseTrainLine(state.name, line);
-        if (!msg || msg.op === 'ignore')
-            return;
-        if (msg.op === 'response') {
-            const pending = state.pending.get(msg.id);
-            if (!pending) {
-                log.debug({ name: state.name, id: msg.id }, 'train: stale response');
-                return;
-            }
-            state.pending.delete(msg.id);
-            clearTimeout(pending.timer);
-            pending.resolve({ result: msg.result, error: msg.error });
-            return;
-        }
-        if (msg.op === 'log') {
-            log.info({ name: state.name, msg: msg.text }, 'train log');
-            return;
-        }
-        this.onEvent?.(msg.event, state.name);
-    }
-    onExit(state, code) {
-        log.warn({ name: state.name, code }, 'train: exited');
-        state.proc = null;
-        state.startedAt = null;
-        failAllPending(state.pending, `train '${state.name}' exited (code=${code}) before responding`);
-        if (state.stopped)
-            return;
-        state.failCount++;
-        if (state.failCount >= MAX_CONSECUTIVE_FAILS) {
-            log.error({ name: state.name, fails: state.failCount }, 'train: too many consecutive failures, giving up (restart metro to retry)');
-            return;
-        }
-        this.scheduleRestart(state);
-    }
-    scheduleRestart(state) {
-        if (state.stopped)
-            return;
-        const idx = Math.min(state.failCount, RESTART_BACKOFFS_MS.length - 1);
-        const delay = RESTART_BACKOFFS_MS[idx];
-        log.info({ name: state.name, delay, attempt: state.failCount }, 'train: restart scheduled');
-        state.restartTimer = setTimeout(() => {
-            state.restartTimer = null;
-            /** Any subprocess that survives 30s resets its consecutive-fail counter. */
-            this.spawn(state);
-            setTimeout(() => { if (state.proc && state.proc.exitCode === null)
-                state.failCount = 0; }, 30_000);
-        }, delay);
-    }
-}
-function killGracefully(proc) {
-    if (!proc || proc.exitCode !== null)
-        return null;
-    try {
-        proc.kill('SIGTERM');
-    }
-    catch { /* ignore */ }
-    const grace = setTimeout(() => { try {
-        proc.kill('SIGKILL');
-    }
-    catch { /* ignore */ } }, 2_000);
-    return proc.exited.finally(() => clearTimeout(grace));
-}
-async function pumpStream(stream, name, kind, onChunk) {
-    if (!stream || typeof stream === 'number')
-        return;
-    const reader = stream.getReader();
-    const dec = new TextDecoder();
-    try {
-        while (true) {
-            const { value, done } = await reader.read();
-            if (done)
-                break;
-            onChunk(dec.decode(value, { stream: true }));
-        }
-    }
-    catch (err) {
-        log.debug({ name, err: errMsg(err) }, `train: ${kind} pump ended`);
-    }
-}

package/dist/tunnel.js

@@ -1,102 +0,0 @@
-/** Cloudflared tunnel manager + webhook endpoint registry. Both persist tiny JSON files in STATE_DIR. */
-import { spawn, spawnSync } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { STATE_DIR } from './paths.js';
-import { errMsg, log } from './log.js';
-const FILE = join(STATE_DIR, 'tunnel.json');
-const RESTART_DELAY_MS = 2_000;
-export const loadTunnelConfig = () => existsSync(FILE)
-    ? JSON.parse(readFileSync(FILE, 'utf8'))
-    : null;
-export function saveTunnelConfig(c) { writeFileSync(FILE, JSON.stringify(c, null, 2)); }
-/** Fetch the tunnel's auth token. Null when CLI is unavailable, not logged in, or no such tunnel. */
-function fetchTunnelToken(name) {
-    const r = spawnSync('cloudflared', ['tunnel', 'token', name], { encoding: 'utf8' });
-    if (r.status !== 0)
-        return null;
-    const token = r.stdout.trim();
-    return token.length > 0 ? token : null;
-}
-export class Tunnel {
-    cfg;
-    port;
-    child = null;
-    closed = false;
-    /** `undefined` = unresolved; `null` = resolved but unavailable (CLI missing / not logged in / no tunnel). */
-    token = undefined;
-    constructor(cfg, port) {
-        this.cfg = cfg;
-        this.port = port;
-    }
-    get hostname() { return this.cfg.hostname; }
-    start() {
-        if (this.closed)
-            return;
-        if (this.token === undefined)
-            this.token = fetchTunnelToken(this.cfg.name);
-        const mode = this.token ? 'token' : 'named';
-        log.info({ name: this.cfg.name, hostname: this.cfg.hostname, port: this.port, mode }, 'cloudflared tunnel starting');
-        /** `--no-autoupdate` is a global cloudflared flag — must come before the `tunnel` subcommand. */
-        const args = ['--no-autoupdate', 'tunnel', 'run', '--url', `http://127.0.0.1:${this.port}`];
-        /** Token form resolves the tunnel from TUNNEL_TOKEN so the trailing name arg must be omitted. */
-        if (!this.token)
-            args.push(this.cfg.name);
-        const env = this.token
-            ? { ...process.env, TUNNEL_TOKEN: this.token }
-            : process.env;
-        this.child = spawn('cloudflared', args, { stdio: ['ignore', 'pipe', 'pipe'], env });
-        this.child.stderr?.on('data', d => log.debug({ cloudflared: d.toString().trim() }, 'cloudflared'));
-        this.child.on('exit', code => {
-            this.child = null;
-            if (this.closed)
-                return;
-            log.warn({ code }, 'cloudflared exited; restarting');
-            setTimeout(() => this.start(), RESTART_DELAY_MS);
-        });
-        this.child.on('error', err => log.warn({ err: errMsg(err) }, 'cloudflared spawn error'));
-    }
-    stop() {
-        this.closed = true;
-        this.child?.kill();
-        this.child = null;
-    }
-}
-/* ──────────── webhook endpoint registry (id, label, optional secret) ──────────── */
-const WEBHOOKS_FILE = join(STATE_DIR, 'webhooks.json');
-/** Local listener port — `127.0.0.1` only; expose publicly via Cloudflare tunnel. */
-export const webhookPort = () => Number(process.env.METRO_WEBHOOK_PORT) || 8420;
-function readWebhooks() {
-    if (!existsSync(WEBHOOKS_FILE))
-        return { endpoints: [] };
-    try {
-        return JSON.parse(readFileSync(WEBHOOKS_FILE, 'utf8'));
-    }
-    catch {
-        return { endpoints: [] };
-    }
-}
-const writeWebhooks = (s) => writeFileSync(WEBHOOKS_FILE, JSON.stringify(s, null, 2));
-export const listEndpoints = () => readWebhooks().endpoints;
-export const findEndpoint = (id) => readWebhooks().endpoints.find(e => e.id === id);
-export function addEndpoint(label, secret) {
-    const s = readWebhooks();
-    /** 16-char URL-safe id (~96 bits — collision-proof for any reasonable count). */
-    const ep = {
-        id: randomBytes(12).toString('base64url'), label, createdAt: new Date().toISOString(),
-        ...(secret ? { secret } : {}),
-    };
-    s.endpoints.push(ep);
-    writeWebhooks(s);
-    return ep;
-}
-export function removeEndpoint(id) {
-    const s = readWebhooks();
-    const before = s.endpoints.length;
-    s.endpoints = s.endpoints.filter(e => e.id !== id);
-    if (s.endpoints.length === before)
-        return false;
-    writeWebhooks(s);
-    return true;
-}

package/docs/broker.md

@@ -1,166 +0,0 @@
-# Metro broker
-
-Multi-user event routing on top of the event log. Turns "one daemon → one stdout consumer"
-into "one daemon → N independently-subscribed users (Claude Code, Codex, anything) with
-durable, replayable delivery".
-
-## 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 event (chat messages, webhooks, reactions, transcripts, …). 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.      |
-| Per-mode cursor      | `$METRO_STATE_DIR/cursors/<key>`        | Byte offset into `history.jsonl` — last-emitted position for one tail mode. 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. `--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.
-
-```
-                                ┌──────────────────────────┐
-   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
-```
-
-`--as <user-id>` defaults to `userSelf()` ([history.ts](../src/history.ts)) — 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
-subscriber, a router, and a human observer. Each maps to one mutually-exclusive flag:
-
-| 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 subscriber that won't race on unclaimed events.|
-| **Unclaimed only** | `--unclaimed`              | `line ∉ claims`                                                                 | Router/first-responder pattern 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`.
-
-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
-
-Outbound paths call `tryAutoClaim` ([broker/claims.ts](../src/broker/claims.ts)) to claim the target `<line>`
-for the actor (`userSelf()`) the first time it's touched, atomically — same lockfile as
-`metro claim`. Auto-claim only fires when **the line topology is 1:1** (DM, or a
-Claude/Codex cross-user line). Shared lines are skipped:
-
-| Line                                            | Classification | Auto-claim? | 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         | 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 a stream, not a conversation               |
-
-- If the line is already claimed by someone else (and topology check passed), the action
-  still proceeds but the claim is **not overwritten**.
-- Auto-claim writes happen after the action succeeds, so a failed call never writes to `claims.json`.
-
-### `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.
-- Maintains a per-mode cursor (byte offset) at `cursors/<key>`. On startup, resumes from cursor;
-  on each emitted line, the offset is advanced *after* the write succeeds. O(1) resume.
-- `--since <offset>` overrides the cursor; `--since=tail` starts from EOF, ignoring backlog.
-- Claim lookups read `claims.json` once per emitted event. Small (~KB), OS-cached; sub-microsecond cost.
-
-### `metro claim` semantics
-
-- Pure metadata edit on `claims.json`. Does **not** notify the daemon — claims are read by
-  tails, not the dispatcher.
-- Re-claiming a line re-assigns it (last writer wins). `metro claims` prints the current map.
-- 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 writes
-  on the same host.
-
-## Dispatcher
-
-The dispatcher stays dumb. `emit()` appends to history, pushes to codex-rc, and writes to
-stdout. All routing intelligence lives in `metro tail`'s filter, which reads two small files
-(`claims.json` + its own cursor) per event. No new sockets, no fan-out bookkeeping, no
-coupling between subscriber count and daemon state.
-
-## Concurrency
-
-Multiple processes write `history.jsonl`: the daemon's `emit()` and short-lived auto-claim
-writers. `appendFileSync` opens with `O_APPEND`; POSIX guarantees atomic seek-to-end-and-write
-per `write(2)`. Concurrent writers produce whole lines in some order, never interleaved halves.
-Node issues one `write(2)` per `appendFileSync` call, and history entries stay well under
-per-syscall atomicity limits (~2GB on Linux, `INT_MAX` on macOS).
-
-`claims.json` is read on every event by every tail; writes are infrequent. An `O_EXCL`
-lockfile around writes is enough; tails do an unlocked read with a malformed-JSON retry.
-
-## 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 — those are owned by the train and read from `~/.metro/.env`.
-
-## Failure modes
-
-| 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.                                               |
-| `history.jsonl` grows unboundedly   | Out of scope here. (Rotate by date, prune by age.)                                                |
-
-## Non-goals
-
-- **Strict ordering across chats**: events within one `line` are ordered by JSONL append order; cross-chat ordering is best-effort.
-- **Exactly-once delivery**: at-least-once via cursor + redelivery. Idempotency is the subscriber's problem (the daemon mints stable `msg_*` ids).
-- **Authn between users**: any process with filesystem access to `$METRO_STATE_DIR` can tail and claim. Same trust model as the host.
-- **Remote users**: broker is local-only. Cross-host fan-out is solved by running metro on each host and bridging at the chat layer.