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

package/README.md

@@ -1,8 +1,11 @@
 # Metro
 
-> **A live JSON stream of Telegram, Discord, webhooks, and cross-agent messages for your local Claude Code / Codex session.**
+[![npm](https://img.shields.io/npm/v/@stage-labs/metro/beta?label=npm&color=cb3837)](https://www.npmjs.com/package/@stage-labs/metro)
+[![lines of code](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.codetabs.com%2Fv1%2Floc%2F%3Fgithub%3Dbonustrack%2Fmetro&query=%24%5B0%5D.linesOfCode&label=lines%20of%20TypeScript&color=blue)](https://github.com/bonustrack/metro)
 
-Metro is a small daemon you launch from inside your agent. It connects to Discord, Telegram, and any third-party service that can POST a webhook (GitHub, Intercom, Fireflies, …), emits each inbound as one JSON line on stdout (which Claude Code's `Monitor` consumes natively, and Codex picks up via an app-server WebSocket push), and exposes a tiny CLI — `metro reply`, `metro send`, `metro edit`, `metro react`, `metro download`, `metro fetch` — for posting back. Cross-agent: any agent can ping any other via `metro send metro://claude/<agent-id>/<session-id>` and the daemon re-emits it on the stream.
+> **A live JSON stream of Telegram, Discord, webhooks, and cross-user messages for your local Claude Code / Codex session.**
+
+Metro is a small daemon you launch from inside your session. It connects to Discord, Telegram, and any third-party service that can POST a webhook (GitHub, Intercom, Fireflies, …), emits each inbound as one JSON line on stdout (which Claude Code's `Monitor` consumes natively, and Codex picks up via an app-server WebSocket push), and exposes a tiny CLI — `metro reply`, `metro send`, `metro edit`, `metro react`, `metro download`, `metro fetch` — for posting back. Cross-user: any user can ping any other via `metro send metro://claude/<user-id>/<session-id>` and the daemon re-emits it on the stream.
 
 ```
 [Claude Code session]
@@ -11,7 +14,7 @@ $ metro &                              # backgrounded
 $ Monitor( … metro's stdout … )
 
 >>> {"kind":"inbound","station":"discord","line":"metro://discord/123…","messageId":"9876",
-     "text":"@bot we got a 5xx spike from /v1/sync. Look?",
+     "text":"@metro we got a 5xx spike from /v1/sync. Look?",
      "payload":{"channelId":"123…","guildId":"456…","content":"<@…> we got a 5xx spike…",
                 "mentions":{"users":["<bot-id>"],"roles":[],"everyone":false},…}}
 
@@ -19,7 +22,7 @@ $ Monitor( … metro's stdout … )
   Bash: metro reply metro://discord/123… 9876 "three deploys in the last 24h…"
 ```
 
-The agent owns its own streaming, tool calls, and reply timing. Metro is the wire.
+You own your own streaming, tool calls, and reply timing. Metro is the wire.
 
 ---
 
@@ -34,7 +37,7 @@ metro doctor                             # verify
 metro                                    # run the daemon
 ```
 
-Requires **Node ≥ 22 or Bun ≥ 1.3**. Metro doesn't launch Claude or Codex — you do, and the agent launches metro. See [`docs/agents.md`](docs/agents.md).
+Requires **Node ≥ 22 or Bun ≥ 1.3**. Metro doesn't launch Claude or Codex — you do, and the user launches metro. See [`docs/users.md`](docs/users.md).
 
 In **Discord**: DM the bot, or `@<bot>` in any channel. In **Telegram**: DM, or `@<bot>` in a forum supergroup. Every inbound becomes one JSON line on `metro`'s stdout.
 
@@ -49,16 +52,16 @@ Cloudflare tunnel   ──┤ ── HTTP webhooks (GitHub, Intercom, …)
                       │
                       ├─▶ metro daemon ───▶ stdout (JSON events; Claude Code's Monitor reads here)
                       │                ───▶ codex-rc WebSocket (Codex turn/start; opt-in)
-                      │                ◀── IPC Unix socket  (metro send to agent lines)
+                      │                ◀── IPC Unix socket  (metro send to Claude / Codex lines)
                       │
-agent CLI calls   ────┴── REST → Discord / Telegram   (metro reply / send / edit / react / download / fetch)
+local CLI calls   ────┴── REST → Discord / Telegram   (metro reply / send / edit / react / download / fetch)
 ```
 
-- **Inversion of control.** The agent (Claude Code, Codex) launches `metro`, not the other way around. Metro never spawns an agent process.
+- **Inversion of control.** Claude Code / Codex launches `metro`, not the other way around. Metro never spawns a Claude / Codex process.
 - **Single daemon per machine.** Lockfile at `$METRO_STATE_DIR/.tail-lock` enforces singleton.
 - **Account-tied identity.** `to` on inbound and `from` on outbound resolve to a stable account-scoped URI per runtime: `metro://claude/user/<orgId>` (from `claude auth status --json`) or `metro://codex/user/<accountId>` (from `$CODEX_HOME/auth.json`). Same on any device for the same logged-in account.
 - **Codex push (opt-in).** Set `METRO_CODEX_RC=ws://127.0.0.1:8421` and metro pushes each event via JSON-RPC `turn/start` to the Codex app-server. Codex's TUI must be attached with `--remote` to the same URL.
-- **Cross-agent notification.** `metro send metro://claude/<agent-id>/<session-id>` (or `metro://codex/<agent-id>/<session-id>`) routes through the daemon's IPC socket; the daemon re-emits on its stdout (and pushes to codex-rc), so the peer agent sees it. Discover reachable agents/sessions via `metro stations` or `$METRO_STATE_DIR/agent-registry.json`.
+- **Cross-user notification.** `metro send metro://claude/<user-id>/<session-id>` (or `metro://codex/<user-id>/<session-id>`) routes through the daemon's IPC socket; the daemon re-emits on its stdout (and pushes to codex-rc), so the peer sees it. Discover reachable users/sessions via `metro stations` or `$METRO_STATE_DIR/user-registry.json`.
 - **Webhooks (opt-in).** `metro webhook add <label>` registers an HTTP receive endpoint; the daemon binds `127.0.0.1:8420` (override with `$METRO_WEBHOOK_PORT`). If you've run `metro tunnel setup`, a Cloudflare named tunnel exposes it publicly. Each POST is re-emitted on stdout as an inbound event.
 
 ---
@@ -67,20 +70,20 @@ agent CLI calls   ────┴── REST → Discord / Telegram   (metro rep
 
 Each endpoint is a **station** with declared capabilities:
 
-| Station    | Kind    | Modalities    | Features                                              | Config                                                                                  |
-|------------|---------|---------------|-------------------------------------------------------|-----------------------------------------------------------------------------------------|
-| `discord`  | chat    | text + image  | reply, send, edit, react, download, fetch             | `DISCORD_BOT_TOKEN` + Message Content Intent                                            |
-| `telegram` | chat    | text + image  | reply, send, edit, react, download                    | `TELEGRAM_BOT_TOKEN`                                                                    |
-| `claude`   | agent   | text          | send, notify                                          | auto-detected from `$CLAUDECODE`; identity via `claude auth status --json`              |
-| `codex`    | agent   | text          | send, notify                                          | auto-detected from `$METRO_CODEX_RC` / `$CODEX_HOME`; identity via `$CODEX_HOME/auth.json` |
-| `webhook`  | service | text          | (receive-only; optional HMAC verify)                  | `metro webhook add <label>` + `metro tunnel setup` (Cloudflare named tunnel)            |
+| Station    | Modalities    | Features                                              | Config                                                                                  |
+|------------|---------------|-------------------------------------------------------|-----------------------------------------------------------------------------------------|
+| `discord`  | text + image  | reply, send, edit, react, download, fetch             | `DISCORD_BOT_TOKEN` + Message Content Intent                                            |
+| `telegram` | text + image  | reply, send, edit, react, download                    | `TELEGRAM_BOT_TOKEN`                                                                    |
+| `claude`   | text          | send                                                  | auto-detected from `$CLAUDECODE`; identity via `claude auth status --json`              |
+| `codex`    | text          | send                                                  | auto-detected from `$METRO_CODEX_RC` / `$CODEX_HOME`; identity via `$CODEX_HOME/auth.json` |
+| `webhook`  | text          | (receive-only; optional HMAC verify)                  | `metro webhook add <label>` + `metro tunnel setup` (Cloudflare named tunnel)            |
 
 Run `metro stations` to see live config status (`✓` configured, `✗` not, `·` informational).
 
 Behaviors worth knowing:
-- **No streaming / no edit machinery in metro.** The agent runs the show; metro is one-shot REST.
+- **No streaming / no edit machinery in metro.** The local CLI runs the show; metro is one-shot REST.
 - **No link previews.** Outgoing messages set `link_preview_options.is_disabled` on Telegram and `SUPPRESS_EMBEDS` on Discord.
-- **Image attachments inbound** — `[image]` placeholders surface inline in `text`; the agent calls `metro download` to materialize them. 20 MB cap.
+- **Image attachments inbound** — `[image]` placeholders surface inline in `text`; the user calls `metro download` to materialize them. 20 MB cap.
 - **Rich content outbound.** `metro send` / `reply` accept `--image=<path>` (repeatable: albums of up to 10), `--document=<path>` (repeatable), `--voice=<path>` (single voice message — Telegram renders the voice bubble), and `--buttons='[[{"text":"…","url":"…"}]]'` for inline URL-button keyboards. `metro edit` accepts `--buttons` (pass `'[]'` to clear). 20 MB / file. URL buttons only for now — no callback/interactive components.
 - **Telegram non-forum groups are skipped.** No thread boundary to scope on.
 - **Webhook signature verification.** Pass `--secret=<shared-secret>` to `metro webhook add` and the daemon verifies `X-Hub-Signature-256` (GitHub/Intercom format) on every POST. Mismatches return 401 and never reach the stream.
@@ -115,7 +118,7 @@ Paste the URL into the provider's webhook settings (for GitHub: **Content type m
 | One-time tunnel setup | `metro tunnel setup <tunnel-name> <hostname>` |
 | Tunnel status | `metro tunnel status` |
 
-The tunnel is optional — without it the listener binds `127.0.0.1:8420` only (good for local testing or your own loopback tools). With Cloudflare named tunnels, the URL stays stable across daemon restarts and machines. See [docs/uri-scheme.md](docs/uri-scheme.md) and [docs/agents.md](docs/agents.md) for the full event shape.
+The tunnel is optional — without it the listener binds `127.0.0.1:8420` only (good for local testing or your own loopback tools). With Cloudflare named tunnels, the URL stays stable across daemon restarts and machines. See [docs/uri-scheme.md](docs/uri-scheme.md) and [docs/users.md](docs/users.md) for the full event shape.
 
 ---
 
@@ -127,12 +130,12 @@ Every conversational scope is identified by a **Line** — a URI in the form `me
 metro://discord/1234567890123456789
 metro://telegram/-1001234567890                 # main chat / DM
 metro://telegram/-1001234567890/42              # forum topic 42
-metro://claude/9bfc7af0-…/50b00d11-…            # claude agent session
-metro://codex/8119ecb1-…/01997d4b-…             # codex agent session
+metro://claude/9bfc7af0-…/50b00d11-…            # claude user session
+metro://codex/8119ecb1-…/01997d4b-…             # codex user session
 metro://webhook/fwaCgTKJuLAjS2K0                # HTTP webhook endpoint
 ```
 
-Anyone can post to a line via [`metro send`](#cli) — daemon required only for agent lines. Full grammar in [`docs/uri-scheme.md`](docs/uri-scheme.md).
+Anyone can post to a line via [`metro send`](#cli) — daemon required only for Claude / Codex lines. Full grammar in [`docs/uri-scheme.md`](docs/uri-scheme.md).
 
 ---
 
@@ -167,12 +170,12 @@ metro update                                Upgrade in place.
 All commands accept `--json`. `reply` / `send` / `edit` read multi-line `<text>` from stdin if no positional is given.
 
 **State files** in `$METRO_STATE_DIR` (default `~/.cache/metro`):
-- `AGENTS.md` — agent skill copied from the package on every start (so the path is stable across upgrades)
-- `history.jsonl` — universal message log (one JSON object per line; append-only). Read with `metro history`. Each entry carries `from` and `to` as universal participant URIs (`metro://<station>/user/<id>`, `metro://claude/user/<orgId>`, `metro://codex/user/<accountId>`) plus a `fromName` display field. The dispatcher auto-detects the consuming agent for `to` on inbound (`$CLAUDECODE` → `metro://claude/user/<orgId>` from `claude auth status --json`; `$METRO_CODEX_RC`/`$CODEX_HOME` → `metro://codex/user/<accountId>` from `$CODEX_HOME/auth.json`).
-- `bot-ids.json` — `{discord: "<botUserId>", telegram: "<botUserId>"}` written by the daemon on startup (cached for the few historical lookups that still need a bot identity).
+- `USERS.md` — user skill copied from the package on every start (so the path is stable across upgrades)
+- `history.jsonl` — universal message log (one JSON object per line; append-only). Read with `metro history`. Each entry carries `from` and `to` as universal participant URIs (`metro://<station>/user/<id>`, `metro://claude/user/<orgId>`, `metro://codex/user/<accountId>`) plus a `fromName` display field. The dispatcher auto-detects the local user for `to` on inbound (`$CLAUDECODE` → `metro://claude/user/<orgId>` from `claude auth status --json`; `$METRO_CODEX_RC`/`$CODEX_HOME` → `metro://codex/user/<accountId>` from `$CODEX_HOME/auth.json`).
+- `bot-ids.json` — `{discord: "<botUserId>", telegram: "<botUserId>"}` written by the daemon on startup (cached for the few historical lookups that still need a platform-side bot identity).
 - `lines.json` — line → last-seen / name cache (read by `metro lines`)
-- `agent-registry.json` — every `(station, agent-id, sessions[])` tuple metro has seen; surfaced under each agent row in `metro stations`
-- `stations/codex/session-id` — current codex-rc thread id (daemon writes on handshake; CLI processes read for `metro://codex/<agent-id>/<session>`)
+- `user-registry.json` — every `(station, user-id, sessions[])` tuple metro has seen; surfaced under each Claude / Codex row in `metro stations`
+- `stations/codex/session-id` — current codex-rc thread id (daemon writes on handshake; CLI processes read for `metro://codex/<user-id>/<session>`)
 - `webhooks.json` — registered HTTP receive endpoints (id, label, optional shared secret)
 - `tunnel.json` — Cloudflare named-tunnel config (`{name, hostname}`); when present, the daemon spawns `cloudflared tunnel run`. The token is resolved via `cloudflared tunnel token <name>` and passed through as `TUNNEL_TOKEN`, so the per-tunnel credentials JSON at `~/.cloudflared/<id>.json` is not required (the named-form spawn is the fallback when the token call fails)
 - `.tail-lock` — dispatcher pid
@@ -188,8 +191,8 @@ All commands accept `--json`. `reply` / `send` / `edit` read multi-line `<text>`
 | `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN` | — | Bot tokens. `metro setup` writes them here. |
 | `METRO_CODEX_RC` | — | Codex app-server URL (`ws://…`, `wss://…`, `unix:///…`). When set, the daemon pushes each event via JSON-RPC `turn/start`. |
 | `METRO_WEBHOOK_PORT` | `8420` | Local port the HTTP webhook listener binds to (always `127.0.0.1`; expose publicly via Cloudflare tunnel). |
-| `METRO_AGENT_ID` | — | Override the resolved agent id (orgId / accountId) used in `metro://<station>/user/<id>` and `metro://<station>/<id>/<session>`. Useful for testing. |
-| `METRO_AGENT_SESSION_ID` | — | Override the resolved session id (Claude session / Codex thread). |
+| `METRO_USER_ID` | — | Override the resolved user id (orgId / accountId) used in `metro://<station>/user/<id>` and `metro://<station>/<id>/<session>`. Useful for testing. |
+| `METRO_USER_SESSION_ID` | — | Override the resolved session id (Claude session / Codex thread). |
 | `METRO_FROM` | — | Pin a custom `from` URI for all writes (overrides runtime detection). |
 | `METRO_CONFIG_DIR` | `~/.config/metro` | Where the global `.env` lives. |
 | `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, line cache, IPC socket, telegram offset, registries, tunnel config. |
@@ -215,15 +218,15 @@ Source map:
 
 - [`src/cli/`](src/cli/) — `metro` binary entry ([`index.ts`](src/cli/index.ts)) + admin commands ([`config.ts`](src/cli/config.ts): setup/doctor/update), action handlers ([`actions.ts`](src/cli/actions.ts): send/reply/edit/react/download/fetch), webhook + tunnel commands ([`webhook.ts`](src/cli/webhook.ts)), and shared CLI primitives ([`util.ts`](src/cli/util.ts)).
 - [`src/dispatcher.ts`](src/dispatcher.ts) — the daemon: starts each station, emits events on stdout, listens on the IPC socket, optionally pushes to codex-rc, supervises the Cloudflare tunnel.
-- [`src/stations/`](src/stations/) — Line URI scheme + ChatStation interface + listing ([`index.ts`](src/stations/index.ts)). Chat impls: [`discord.ts`](src/stations/discord.ts), [`telegram.ts`](src/stations/telegram.ts) (+ [`telegram-md.ts`](src/stations/telegram-md.ts) markdown helper). Agent identity resolvers: [`claude.ts`](src/stations/claude.ts) (orgId via `claude auth status --json`), [`codex.ts`](src/stations/codex.ts) (account_id via `auth.json`). HTTP receive: [`webhook.ts`](src/stations/webhook.ts).
+- [`src/stations/`](src/stations/) — Line URI scheme + ChatStation interface + listing ([`index.ts`](src/stations/index.ts)). Chat impls: [`discord.ts`](src/stations/discord.ts), [`telegram.ts`](src/stations/telegram.ts) (+ [`telegram-md.ts`](src/stations/telegram-md.ts) markdown helper). User identity resolvers: [`claude.ts`](src/stations/claude.ts) (orgId via `claude auth status --json`), [`codex.ts`](src/stations/codex.ts) (account_id via `auth.json`). HTTP receive: [`webhook.ts`](src/stations/webhook.ts).
 - [`src/codex-rc.ts`](src/codex-rc.ts) — Codex app-server WebSocket push client (also exposes the rc thread id used as Codex session-id).
 - [`src/tunnel.ts`](src/tunnel.ts) — Cloudflared named-tunnel supervisor.
 - [`src/webhooks.ts`](src/webhooks.ts) — webhook endpoint store (`webhooks.json` CRUD).
-- [`src/registry.ts`](src/registry.ts) — agent registry: `(station, agent-id, sessions[])` tracking.
-- [`src/history.ts`](src/history.ts) — universal message log + `agentSelf()` / `selfLine()` identity helpers.
+- [`src/registry.ts`](src/registry.ts) — user registry: `(station, user-id, sessions[])` tracking.
+- [`src/history.ts`](src/history.ts) — universal message log + `userSelf()` / `selfLine()` identity helpers.
 - [`src/ipc.ts`](src/ipc.ts) — Unix-socket IPC between the daemon and one-shot CLI commands.
 - [`src/cache.ts`](src/cache.ts) — in-memory line cache with debounced flush to `lines.json`, plus bot-id cache.
-- [`docs/uri-scheme.md`](docs/uri-scheme.md) specs the Line format; [`docs/agents.md`](docs/agents.md) is the in-context skill for agents.
+- [`docs/uri-scheme.md`](docs/uri-scheme.md) specs the Line format; [`docs/users.md`](docs/users.md) is the in-context skill for users.
 
 CI runs typecheck + lint + build on every PR via [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
 

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/cache.js

@@ -3,7 +3,6 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { errMsg, log } from './log.js';
 import { STATE_DIR } from './paths.js';
-import { Line } from './stations/index.js';
 const cacheFile = join(STATE_DIR, 'lines.json');
 const FLUSH_DELAY_MS = 5_000;
 let cache = null;
@@ -68,8 +67,3 @@ export function saveBotId(station, id) {
         log.warn({ err: errMsg(err) }, 'bot-ids cache write failed');
     }
 }
-/** Resolve the bot's URI for a station. Returns `metro://<station>/bot/<id>` or the placeholder. */
-export function botLine(station) {
-    const id = readBotIds()[station];
-    return id ? Line.bot(station, id) : `metro://${station}/bot`;
-}

package/dist/cli/actions.js

@@ -6,9 +6,10 @@ import { errMsg } from '../log.js';
 import { DiscordStation } from '../stations/discord.js';
 import { TelegramStation } from '../stations/telegram.js';
 import { ipcCall } from '../ipc.js';
-import { agentSelf, appendHistory, lookupEntry, mintId, resolvePlatformId, } from '../history.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);
@@ -45,29 +46,55 @@ function richOpts(f) {
         opts.buttons = buttons;
     return opts;
 }
-/** Append an outbound action to history.jsonl; `to` = the original sender when replying/reacting. */
+/** Mirror the original entry's destination: group → `line`; DM → the other-party user URI. */
+function destinationFor(orig, line) {
+    if (!orig || !orig.to || orig.to === orig.line)
+        return line;
+    return orig.from;
+}
+/** Append an outbound action to history.jsonl; `to` mirrors the destination per `destinationFor`. */
 function logOutbound(f, e) {
     const id = mintId();
     const fromOverride = flagOne(f, 'from');
+    const from = fromOverride ? asLine(fromOverride) : userSelf();
     appendHistory({
         id, ts: new Date().toISOString(), station: Line.station(e.line) ?? '?',
-        from: fromOverride ? asLine(fromOverride) : agentSelf(), 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.isAgent(line)) {
-        const from = flagOne(f, 'from');
-        const resp = await ipcCall({ op: 'notify', line, from, text });
+    if (Line.isLocal(line)) {
+        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));
-    const id = logOutbound(f, { kind: 'outbound', line, text, messageId });
+    /** Inherit destination from the most recent inbound on this line so DM sends address the user. */
+    const to = destinationFor(readHistory({ line, kind: 'inbound', limit: 1 })[0], line);
+    const id = logOutbound(f, { kind: 'outbound', line, text, messageId, to });
     emit(f, `sent ${id} (${messageId}) to ${line}`, { ok: true, line, id, messageId });
 }
 export async function cmdReply(p, f) {
@@ -76,7 +103,7 @@ export async function cmdReply(p, f) {
     const [to, replyToArg] = p, text = await resolveText(p, 2), line = asLine(to);
     const replyTo = resolvePlatformId(replyToArg);
     const messageId = await chatStationOf(line).send(line, text, { ...richOpts(f), replyTo });
-    const id = logOutbound(f, { kind: 'outbound', line, text, messageId, replyTo: replyToArg, to: lookupEntry(replyToArg)?.from });
+    const id = logOutbound(f, { kind: 'outbound', line, text, messageId, replyTo: replyToArg, to: destinationFor(lookupEntry(replyToArg), line) });
     emit(f, `replied ${id} (${messageId}) to ${line}#${replyTo}`, { ok: true, line, id, replyTo: replyToArg, messageId });
 }
 export async function cmdEdit(p, f) {
@@ -96,7 +123,7 @@ export async function cmdReact(p, f) {
     const [to, msgArg, emoji = ''] = p, line = asLine(to);
     const platformId = resolvePlatformId(msgArg);
     await chatStationOf(line).react(line, platformId, emoji);
-    const id = logOutbound(f, { kind: 'react', line, messageId: platformId, emoji, to: lookupEntry(msgArg)?.from });
+    const id = logOutbound(f, { kind: 'react', line, messageId: platformId, emoji, to: destinationFor(lookupEntry(msgArg), line) });
     const human = emoji ? `reacted ${emoji} on ${line}#${platformId}` : `cleared reaction on ${line}#${platformId}`;
     emit(f, human, { ok: true, line, id, messageId: platformId, emoji });
 }

package/dist/cli/index.js

@@ -4,14 +4,15 @@ import pkg from '../../package.json' with { type: 'json' };
 import { errMsg } from '../log.js';
 import { listLines } from '../cache.js';
 import { fmtCapabilities, listStations } from '../stations/index.js';
-import { listAgents } from '../registry.js';
+import { listUsers } from '../registry.js';
 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 agent
+const USAGE = `metro — Telegram + Discord stream for your Claude Code / Codex user
 
 Usage:
   metro                                       Run the dispatcher (emits JSON events on stdout).
@@ -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).
@@ -47,22 +57,20 @@ Exit codes: 0 success · 1 usage · 2 config · 3 upstream
 async function cmdStations(_, f) {
     loadMetroEnv();
     const rows = listStations();
-    const agentsByStation = {
-        claude: listAgents('claude'),
-        codex: listAgents('codex'),
+    const usersByStation = {
+        claude: listUsers('claude'),
+        codex: listUsers('codex'),
     };
     if (isJson(f))
-        return writeJson({ stations: rows, agents: agentsByStation });
+        return writeJson({ stations: rows, users: usersByStation });
     process.stdout.write('metro stations\n\n');
     for (const s of rows) {
         const mark = s.configured === true ? '✓' : s.configured === false ? '✗' : '·';
-        process.stdout.write(`  ${mark} ${s.name.padEnd(10)} ${s.kind.padEnd(6)} ${fmtCapabilities(s.capabilities)}\n        ${s.detail}\n`);
-        if (s.kind === 'agent') {
-            const seen = agentsByStation[s.name] ?? [];
-            for (const inst of seen) {
-                const sessionsTxt = inst.sessions.length ? ` · sessions: ${inst.sessions.length}` : '';
-                process.stdout.write(`          seen: ${inst.agentId}${sessionsTxt}\n`);
-            }
+        process.stdout.write(`  ${mark} ${s.name.padEnd(10)} ${fmtCapabilities(s.capabilities)}\n        ${s.detail}\n`);
+        const seen = usersByStation[s.name] ?? [];
+        for (const inst of seen) {
+            const sessionsTxt = inst.sessions.length ? ` · sessions: ${inst.sessions.length}` : '';
+            process.stdout.write(`          seen: ${inst.userId}${sessionsTxt}\n`);
         }
     }
     process.stdout.write('\n');
@@ -123,16 +131,14 @@ async function cmdHistory(_, f) {
         process.stdout.write(`${ts}  ${e.id.padEnd(12)}  ${e.kind.padEnd(12)}  ${from} → ${to}  ${text}\n`);
     }
 }
-/** Compact display: fromName if known; else `station:@<id>` (user), `station:bot`, or `station:<id>`. */
+/** Compact display: fromName if known; else `station:@<id>` (user) or `station:<id>`. */
 function fmtActor(uri, name) {
     if (name)
         return name;
-    const m = uri.match(/^metro:\/\/([^/]+)(?:\/(?:(user|bot)\/)?(.*))?$/);
+    const m = uri.match(/^metro:\/\/([^/]+)(?:\/(?:(user)\/)?(.*))?$/);
     if (!m)
         return uri;
     const [, station, kind, rest] = m;
-    if (kind === 'bot')
-        return `${station}:bot`;
     if (kind === 'user')
         return `${station}:@${shortId(rest ?? '')}`;
     return rest ? `${station}:${shortId(rest)}` : station;
@@ -144,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/skill.js

@@ -1,4 +1,4 @@
-/** `metro setup skill` — install the bundled SKILL.md into each detected agent runtime. */
+/** `metro setup skill` — install the bundled SKILL.md into each detected user runtime. */
 import { copyFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -42,7 +42,7 @@ function install(f) {
         }
     }
     if (!installed.length) {
-        throw exitErr('no agent runtime detected (~/.claude or ~/.codex). Install one and rerun.', 2);
+        throw exitErr('no user runtime detected (~/.claude or ~/.codex). Install one and rerun.', 2);
     }
     emit(f, `installed metro skill → ${installed.join(', ')}`, { ok: true, installed });
 }