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

package/dist/tunnel.js

@@ -1,64 +0,0 @@
-/** Cloudflared tunnel manager. Prefers token-from-env so a missing local credentials JSON does not block startup. */
-import { spawn, spawnSync } from 'node:child_process';
-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;
-    }
-}

package/dist/webhooks.js

@@ -1,41 +0,0 @@
-/** Webhook endpoint registry: persists `(id, label, secret?)` for each receive endpoint. */
-import { randomBytes } from 'node:crypto';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { STATE_DIR } from './paths.js';
-const 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 read() {
-    if (!existsSync(FILE))
-        return { endpoints: [] };
-    try {
-        return JSON.parse(readFileSync(FILE, 'utf8'));
-    }
-    catch {
-        return { endpoints: [] };
-    }
-}
-function write(s) { writeFileSync(FILE, JSON.stringify(s, null, 2)); }
-export const listEndpoints = () => read().endpoints;
-export const findEndpoint = (id) => read().endpoints.find(e => e.id === id);
-export function addEndpoint(label, secret) {
-    const s = read();
-    /** 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);
-    write(s);
-    return ep;
-}
-export function removeEndpoint(id) {
-    const s = read();
-    const before = s.endpoints.length;
-    s.endpoints = s.endpoints.filter(e => e.id !== id);
-    if (s.endpoints.length === before)
-        return false;
-    write(s);
-    return true;
-}

package/docs/broker.md

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

package/docs/monitor.md

@@ -1,163 +0,0 @@
-# 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/docs/uri-scheme.md

@@ -1,124 +0,0 @@
-# Metro URI scheme
-
-Universal identifier for every conversational scope in metro. Lines pass around as opaque strings; only the owning station parses its own paths.
-
-## Grammar
-
-```
-line       = "metro://" station "/" path
-station    = lowercase identifier (claude | codex | discord | telegram | webhook | …)
-path       = station-specific, "/"-separated segments
-```
-
-The URI parses cleanly with the WHATWG `URL` parser: `new URL(line)` gives `protocol="metro:"`, `host=<station>`, `pathname="/<path>"`.
-
-## Registered stations
-
-| Station    | Pattern                                      | Example                                                                |
-|------------|----------------------------------------------|------------------------------------------------------------------------|
-| `discord`  | `metro://discord/<channel-id>`               | `metro://discord/1234567890123456789`                                  |
-| `telegram` | `metro://telegram/<chat-id>[/<topic-id>]`    | `metro://telegram/-1001234567890/42`                                   |
-| `claude`   | `metro://claude/<user-id>/<session-id>`      | `metro://claude/9bfc7af0-…/50b00d11-…`                                 |
-| `codex`    | `metro://codex/<user-id>/<session-id>`       | `metro://codex/8119ecb1-…/01997d4b-…`                                  |
-| `webhook`  | `metro://webhook/<endpoint-id>`              | `metro://webhook/fwaCgTKJuLAjS2K0`                                     |
-
-Claude / Codex lines mirror the `<root>/<sub>` structure of `metro://telegram/<chat-id>/<topic-id>`: `<user-id>` (the stable account id — same across devices) plays the role of `<chat-id>`, and `<session-id>` (one conversation) plays the role of `<topic-id>`. Both segments are derived per station (see [participants](#participants) below).
-
-## Participants
-
-Every chat station also exposes participant URIs — used as `from` on inbound/outbound events and history rows.
-
-| Kind   | Pattern                          | Example                                                       |
-|--------|----------------------------------|---------------------------------------------------------------|
-| user    | `metro://<station>/user/<id>`    | `metro://discord/user/87654321`                               |
-| claude  | `metro://claude/user/<orgId>`    | `metro://claude/user/9bfc7af0-2117-44c5-baf2-d22ba382d065`    |
-| codex   | `metro://codex/user/<accountId>` | `metro://codex/user/8119ecb1-b05e-48db-aa80-434584439df9`     |
-| webhook | `metro://webhook/<endpointId>`   | `metro://webhook/fwaCgTKJuLAjS2K0` (line + `from` are the same — no HTTP-side user identity) |
-
-`from` and `to` on history entries are always participant URIs. Discord/Telegram inbounds set `from` to the user URI; the daemon sets `to` to the local user identity:
-
-- **Claude Code** (`$CLAUDECODE` set) — `metro://claude/user/<orgId>`. `<orgId>` is the stable Anthropic-account UUID, resolved by shelling out to `claude auth status --json`.
-- **Codex** (`$METRO_CODEX_RC` or `$CODEX_HOME` set) — `metro://codex/user/<accountId>`. `<accountId>` is the ChatGPT-account UUID, read from `$CODEX_HOME/auth.json` (default `~/.codex/auth.json`) at the `tokens.account_id` field. Requires `auth_mode=chatgpt`; API-key-only Codex sessions have no account id and metro will error.
-- **Neither** — `to` is the generic `metro://user`.
-
-Same account on any machine yields the same URI. Switching accounts via `claude auth login` / `codex login` flips the URI within ~5 s for the long-lived daemon (5 s TTL cache); one-shot CLI invocations re-resolve every run. On outbound, `from` = the same user identity; `to` = the original sender for replies/reacts (looked up from history), or the channel `line` for fresh group sends. A `fromName` field carries the display name (`@alice`, `bonustrack_`).
-
-Override with `--from=<uri>` on any write command, or set `$METRO_FROM` to pin a custom identity for the whole session.
-
-Chat lines identify a Discord channel / Telegram chat (with optional forum topic). Claude / Codex lines identify a *specific session* of a specific user (`<user-id>/<session-id>`) — posting to one re-emits the message on the daemon's stdout stream and (if configured) pushes it to the Codex app-server. They have no inherent "messages"; only events.
-
-### Session derivation per station
-
-| Station  | `<user-id>`                | `<session-id>`                                                  |
-|----------|----------------------------|-----------------------------------------------------------------|
-| `claude` | `orgId` from `claude auth status --json` | `$CLAUDE_CODE_SESSION_ID` (set by Claude Code; stable across `--resume`)|
-| `codex`  | `tokens.account_id` from `$CODEX_HOME/auth.json` | codex-rc thread id from the JSON-RPC handshake (`thread/loaded/list` → `thread/start`) |
-
-Override either segment with `METRO_USER_ID` / `METRO_USER_SESSION_ID` env vars.
-
-### User registry
-
-The daemon persists every `(station, user-id, session)` tuple it sees to `$METRO_STATE_DIR/user-registry.json`. `metro stations` prints the count of seen users and sessions per station. Run it to discover what's reachable rather than guessing topic names.
-
-## Webhook station
-
-Receive-only HTTP endpoint for third-party services (GitHub, Intercom, Fireflies, …). Each registered endpoint is one `metro://webhook/<endpoint-id>` line.
-
-- **Register:** `metro webhook add <label> [--secret=<shared-secret>]` mints a 16-char endpoint id (96 bits of entropy, persisted to `$METRO_STATE_DIR/webhooks.json`) and prints the receiving URL. `metro webhook list` / `remove <id>` for the obvious.
-- **Listener:** the dispatcher binds `127.0.0.1:8420` (override with `METRO_WEBHOOK_PORT`) when ≥1 endpoint is registered. Routes `POST /wh/<endpoint-id>` to an inbound event with `payload: { headers, body }` — `body` is parsed JSON when the request `Content-Type` is JSON, raw string otherwise. `GET /wh/<endpoint-id>` returns 200 (for provider ping checks).
-- **Envelope:** `messageId` falls back to `X-GitHub-Delivery` / `X-Request-ID` / a generated UUID for idempotency tracking. `text` is synthesized from `X-GitHub-Event` / `X-Intercom-Topic` plus method + path for at-a-glance routing; consumers narrow on `payload.body` for full event details.
-- **HMAC verification:** if `--secret` was set on `metro webhook add`, requests must include a matching `X-Hub-Signature-256: sha256=<hex>` (GitHub/Intercom format) — mismatches are rejected with 401 before reaching the stream.
-- **Public reachability:** provided by a Cloudflare named tunnel — see [Tunneling](#tunneling) below. Without one, the listener stays loopback-only (useful for `curl` testing).
-
-## Tunneling
-
-Webhook providers need a public URL. Metro integrates with **Cloudflare named tunnels** (free, stable, account-scoped):
-
-```bash
-cloudflared tunnel login                                   # one-time OAuth (browser)
-metro tunnel setup metro webhook.yourdomain.com            # creates the tunnel + DNS route
-metro                                                      # daemon spawns `cloudflared tunnel run`
-```
-
-After setup, `metro webhook list` prints `https://webhook.yourdomain.com/wh/<id>` for each endpoint. The URL is stable across restarts (bound to the tunnel UUID in `~/.cloudflared/<uuid>.json`, not the cloudflared process). Tunnel config persists at `$METRO_STATE_DIR/tunnel.json`. Without setup, endpoints fall back to `http://127.0.0.1:8420/wh/<id>` (local-only, useful for curl testing).
-
-## Message addressing
-
-Messages on chat lines are referenced by **line + message id** (two args), not as part of the URI. So:
-
-```bash
-metro reply  metro://discord/123…  4567  "ack"
-metro edit   metro://discord/123…  9876  "fixed typo"
-metro react  metro://telegram/-100…/42  4567  👍
-```
-
-## Properties
-
-- **Stable**: a Line is valid for the lifetime of the scope.
-- **Self-describing**: the station name is encoded; the dispatcher routes by station prefix.
-- **Persistable**: safe as a JSON key on disk (used by `lines.json`).
-- **Branded**: TypeScript type `Line` prevents mixing with arbitrary strings.
-
-## API
-
-```ts
-import { Line } from './stations/index.js';            // value namespace + type
-
-const l: Line = Line.discord('1234567890');     // typed Line
-Line.parse(l);                                   // { station: 'discord', path: ['1234567890'] } | null
-Line.station(l);                                 // 'discord'
-Line.claude(orgId, sessionId);                   // metro://claude/<orgId>/<sessionId>
-Line.codex(accountId, threadId);                 // metro://codex/<accountId>/<threadId>
-Line.parseClaude(l);                             // { userId, sessionId } | null
-Line.parseCodex(l);                              // { userId, sessionId } | null
-Line.webhook(endpointId);                        // metro://webhook/<endpointId>
-Line.parseWebhook(l);                            // string | null  (the endpoint id)
-Line.user(station, id);                          // metro://<station>/user/<id>
-Line.isLocal(l);                                 // true for any metro://{claude,codex}/...
-```
-
-## Adding a new station
-
-1. Pick a lowercase station name (`slack`, `matrix`, …).
-2. Add a `Line.<station>(...)` formatter and a parser that returns your typed payload.
-3. Document the path grammar in the table above.