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

package/README.md

@@ -1,11 +1,14 @@
 # Metro
 
 [![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)
+[![lines of code](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.codetabs.com%2Fv1%2Floc%2F%3Fgithub%3Dbonustrack%2Fmetro%26ignored%3Dapps%2Ctest&query=%24%5B0%5D.linesOfCode&label=lines%20of%20TypeScript&color=blue)](https://github.com/bonustrack/metro)
 
-> **A live JSON stream of Telegram, Discord, webhooks, and cross-user messages for your local Claude Code / Codex session.**
+> **Event-interception wire. Supervises train subprocesses, multiplexes their stdout into one
+> JSON event stream, routes outbound action calls back via stdin. Per-platform code lives in
+> train scripts under `~/.metro/trains/` — outside this repo — written by the user (or agent)
+> on demand.**
 
-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.
+Metro is not a framework with platform connectors. Metro is the wire.
 
 ```
 [Claude Code session]
@@ -13,16 +16,16 @@ Metro is a small daemon you launch from inside your session. It connects to Disc
 $ metro &                              # backgrounded
 $ Monitor( … metro's stdout … )
 
->>> {"kind":"inbound","station":"discord","line":"metro://discord/123…","messageId":"9876",
-     "text":"@metro we got a 5xx spike from /v1/sync. Look?",
-     "payload":{"channelId":"123…","guildId":"456…","content":"<@…> we got a 5xx spike…",
+>>> {"kind":"inbound","station":"discord","line":"metro://discord/123…","message_id":"9876",
+     "text":"@metro 5xx spike on /v1/sync — look?",
+     "payload":{"channelId":"123…","guildId":"456…","content":"<@…> 5xx spike…",
                 "mentions":{"users":["<bot-id>"],"roles":[],"everyone":false},…}}
 
-  [I'd run git log + read services/sync.ts, then…]
-  Bash: metro reply metro://discord/123… 9876 "three deploys in the last 24h…"
+  [I'd grep services/sync.ts, then…]
+  Bash: metro call discord send '{"line":"metro://discord/123…","text":"three deploys in the last 24h…","replyTo":"9876"}'
 ```
 
-You own your own streaming, tool calls, and reply timing. Metro is the wire.
+You own streaming, tool calls, and reply timing. Metro is the wire.
 
 ---
 
@@ -31,222 +34,106 @@ You own your own streaming, tool calls, and reply timing. Metro is the wire.
 ```bash
 npm install -g @stage-labs/metro@beta    # or: bun add -g @stage-labs/metro@beta
 
-metro setup discord <token>              # https://discord.com/developers/applications
-metro setup telegram <token>             # https://t.me/BotFather
-metro doctor                             # verify
-metro                                    # run the daemon
+# One-time train setup (Telegram — no npm deps needed; uses native fetch)
+mkdir -p ~/.metro && cd ~/.metro && bun init -y
+cp $(npm root -g)/@stage-labs/metro/examples/telegram.ts ~/.metro/trains/
+echo 'TELEGRAM_BOT_TOKEN=your-token' >> ~/.metro/.env
+
+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 user launches metro. See [`docs/users.md`](docs/users.md).
+For Discord, copy the same `telegram.ts` and port it — swap the API base for
+`https://discord.com/api/v10` with `Authorization: Bot $TOKEN`, install
+`discord.js` for the gateway (`cd ~/.metro && bun add discord.js`), and keep
+the same envelope + `op:"call"` ↔ `op:"response"` protocol. See
+[`examples/README.md`](./examples/README.md) for the wire-format reference.
 
-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.
+Requires **Bun ≥ 1.3** (trains run under `bun run`). Metro core itself works under Node ≥ 22.
 
 ---
 
 ## Architecture
 
 ```
-Discord gateway     ──┐
-Telegram poller     ──┤
-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 Claude / Codex lines)
-                      │
-local CLI calls   ────┴── REST → Discord / Telegram   (metro reply / send / edit / react / download / fetch)
+~/.metro/trains/discord.ts ──> stdout JSON ──┐
+~/.metro/trains/telegram.ts ─> stdout JSON ──┤
+~/.metro/trains/<anything>.ts ─> stdout ─────┼──>  metro daemon ──>  stdout (Monitor / Codex push)
+                                             │                       history.jsonl
+HTTP /wh/<id>  (builtin webhook receiver) ───┤
+IPC `notify`   (builtin cross-user channel) ─┘
+
+metro call discord send {…}  ──>  IPC ──>  daemon  ──>  train stdin  ──>  response  ──> CLI stdout
 ```
 
-- **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-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.
+Every event metro emits is a `HistoryEntry`. Trains produce the full envelope; metro
+enriches `id`/`display` and appends to `history.jsonl`. Outbound action calls are
+train-defined — metro core knows the protocol (`{op:"call", id, action, args}` → `{op:"response", id, result|error}`),
+not what any specific action does.
 
 ---
 
-## Stations
-
-Each endpoint is a **station** with declared capabilities:
-
-| 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)            |
+## Train protocol
 
-Run `metro stations` to see live config status (`✓` configured, `✗` not, `·` informational).
+**Inbound (train → metro stdout)** — one JSON line per event (wire fields are `snake_case`):
 
-Behaviors worth knowing:
-- **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 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.
-
----
-
-## Webhooks
-
-Receive HTTP events from third parties (GitHub, Intercom, Fireflies, anything that POSTs) as standard metro inbound events. Each registered endpoint is one Line.
-
-```bash
-# One-time per machine — bring your own Cloudflare domain (free Registrar at-cost):
-brew install cloudflared
-cloudflared tunnel login                       # browser OAuth, pick your domain
-metro tunnel setup metro webhook.example.com   # creates tunnel + DNS CNAME
-
-# Per endpoint — repeat for each provider:
-metro webhook add github --secret=$(openssl rand -hex 32)
-# → https://webhook.example.com/wh/<id>
-# (without `metro tunnel setup`, falls back to http://127.0.0.1:8420/wh/<id> — local-only)
-
-metro                                          # daemon binds 8420 + spawns cloudflared automatically
+```json
+{"kind":"inbound","station":"discord","line":"metro://discord/123","from":"metro://discord/user/456","from_name":"alice","message_id":"789","text":"hi","is_private":false,"ts":"2026-05-17T18:00:00Z","payload":{...}}
 ```
 
-Paste the URL into the provider's webhook settings (for GitHub: **Content type must be `application/json`** — form-encoded won't parse). Every POST becomes an inbound event with `station: "webhook"`, `line: metro://webhook/<id>`, `payload: { headers, body }`. If you set `--secret`, metro verifies the `X-Hub-Signature-256` header (GitHub/Intercom format) and rejects mismatches with 401.
-
-| Action | Command |
-|---|---|
-| Register an endpoint | `metro webhook add <label> [--secret=<shared-secret>]` |
-| List endpoints + URLs | `metro webhook list` |
-| Remove an endpoint | `metro webhook remove <id>` |
-| 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/users.md](docs/users.md) for the full event shape.
+**Outbound (metro → train stdin)** — one JSON line per action call:
 
----
-
-## Lines
+```json
+{"op":"call","id":"req_abc","action":"send","args":{"line":"metro://discord/123","text":"hi"}}
+```
 
-Every conversational scope is identified by a **Line** — a URI in the form `metro://<station>/<path>`:
+Train responds on stdout:
 
-```
-metro://discord/1234567890123456789
-metro://telegram/-1001234567890                 # main chat / DM
-metro://telegram/-1001234567890/42              # forum topic 42
-metro://claude/9bfc7af0-…/50b00d11-…            # claude user session
-metro://codex/8119ecb1-…/01997d4b-…             # codex user session
-metro://webhook/fwaCgTKJuLAjS2K0                # HTTP webhook endpoint
+```json
+{"op":"response","id":"req_abc","result":{"messageId":"999"}}
 ```
 
-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).
+See [`examples/telegram.ts`](./examples/telegram.ts) (a self-contained ~110 LOC reference train) and [`examples/README.md`](./examples/README.md) for the full protocol + Discord port notes.
 
 ---
 
 ## CLI
 
 ```
-metro                                       Run the daemon (emits JSON events on stdout).
-metro setup [telegram|discord <token>]      Save token, or show status.
-metro setup clear [telegram|discord|all]    Remove tokens.
-metro doctor                                Health check.
-metro stations                              List stations + capabilities.
-metro lines                                 List recently-seen conversations.
-metro send <line> <text> [--image=…]… [--document=…]… [--voice=…] [--buttons=…]
-                                            Post a fresh message; --image/--document repeat for albums.
-metro reply <line> <message_id> <text> [--image|--document|--voice|--buttons]
-                                            Threaded reply (same flags as send).
-metro edit <line> <message_id> <text> [--buttons=<json>]
-                                            Edit a previously-sent message (text + URL-button keyboard).
-metro react <line> <message_id> <emoji>     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=…]
-                                            Universal message log (every inbound + outbound), newest first.
-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 for public webhook URLs.
-metro tunnel status                         Show current tunnel config.
-metro update                                Upgrade in place.
+metro                                    # start the daemon (foreground)
+metro trains list                        # supervised trains + state
+metro trains new <name>                  # scaffold ~/.metro/trains/<name>.ts from the example
+metro trains restart <name>              # kill + respawn a train (resets backoff)
+metro call <train> <action> <args>       # forward an action call; args = JSON / @file / - / string
+metro tail [--as=<user-uri>] [--follow]  # subscribe to the event log; claim-aware
+metro history [--limit=50] [--line=…]    # recent history (newest first), filterable
+metro lines                              # recently-seen conversations
+metro claim <line>                       # take exclusive ownership of a line
+metro release <line>                     # release
+metro claims                             # print the claims map
+metro webhook add <label> [--secret=…]   # add an HTTP receive endpoint
+metro webhook list | remove <id>         # manage endpoints
+metro tunnel setup <name> <hostname>     # configure a Cloudflare named tunnel
+metro tunnel status                      # show current tunnel config
+metro setup [skill [clear]]              # status; or install/remove the skill into ~/.claude / ~/.codex
+metro doctor                             # health check (trains, deps, tunnel, webhooks, env vars)
+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`):
-- `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`)
-- `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
-- `metro.sock` — daemon IPC socket
-- `telegram-offset.json` — last processed update id
+No more `metro send / reply / edit / react / download / fetch` — outbound is always
+`metro call <train> <action> <args>`, with action names defined by the train.
 
 ---
 
-## Configuration
+## State
 
-| Variable | Default | Description |
-|---|---|---|
-| `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_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. |
-| `METRO_LOG_LEVEL` | `info` | `trace` / `debug` / `info` / `warn` / `error` / `fatal`. |
-
-Precedence: process env → `./.env` → `$METRO_CONFIG_DIR/.env`. Logs go to stderr.
+- `~/.metro/trains/` — your train scripts
+- `~/.metro/.env` — your credentials (trains read these)
+- `~/.metro/package.json` — `bun add` here for train deps
+- `$METRO_STATE_DIR` (default `~/.cache/metro/`) — history, claims, cursors, monitor data
 
 ---
 
-## Develop
-
-```bash
-git clone https://github.com/bonustrack/metro && cd metro
-bun install && bun run build
-bun link                                 # makes `metro` resolve to this checkout
-METRO_LOG_LEVEL=debug metro
-
-bun run typecheck                        # ts
-bun run lint                             # eslint
-```
+## License
 
-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). 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) — 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/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).
-
----
-
-## Caveats
-
-- **No allowlist on chat stations.** Anyone who can DM/`@`-mention your bot can produce events. Run against bots you own.
-- **Webhook secrets are optional but recommended.** Without `--secret`, anyone who learns the endpoint URL can POST events. With it, metro verifies `X-Hub-Signature-256` and rejects mismatches.
-- **Telegram bot privacy is on by default**, which can block `@`-mentions in groups. Disable via [@BotFather](https://t.me/BotFather) → Bot Settings → Group Privacy, then kick + re-invite.
-- **Telegram non-forum groups are skipped.** No thread boundary to scope on. DMs and forum topics work normally.
-- **Telegram fetch isn't supported** (bot API doesn't expose history); `metro fetch` returns `[]` on Telegram lines.
-- **Cloudflared is your responsibility.** `metro tunnel setup` records the named tunnel; you still install `cloudflared` (`brew install cloudflared`) and run `cloudflared tunnel login` once.
-
----
-
-## Uninstall
-
-```bash
-metro setup clear
-rm -rf ~/.cache/metro
-npm uninstall -g @stage-labs/metro
-```
+MIT

package/dist/broker/claims.js

@@ -0,0 +1,144 @@
+/** Claims map: per-line owner registry under an O_EXCL lockfile. */
+import { closeSync, existsSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { log } from '../log.js';
+import { STATE_DIR } from '../paths.js';
+import { Line } from '../lines.js';
+export const CLAIMS_FILE = join(STATE_DIR, 'claims.json');
+const CLAIMS_LOCK = join(STATE_DIR, 'claims.json.lock');
+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 };
+    });
+}
+/** Classify a chat line as DM/group/unknown for the auto-claim group-skip rule. */
+/** TG: chatId<0⇒group. Discord: peek payload.guildId on most-recent inbound. Claude/Codex⇒dm. */
+export function classifyLine(line) {
+    const station = Line.station(line);
+    if (station === 'telegram') {
+        const parsed = Line.parseTelegram(line);
+        if (!parsed)
+            return 'unknown';
+        return parsed.chatId < 0 ? 'group' : 'dm';
+    }
+    if (station === 'claude' || station === 'codex')
+        return 'dm';
+    if (station === 'webhook')
+        return 'group';
+    if (station === 'discord') {
+        /** Lazy tail-scan of history.jsonl to avoid a static dep on the history filter helpers. */
+        const recent = readRecentInbound(line);
+        if (!recent)
+            return 'unknown';
+        const payload = recent.payload;
+        if (!payload || !('guildId' in payload)) {
+            /** Older entries may not have a guildId — fall back to the `to` field: DMs route to a user URI. */
+            if (recent.to && recent.to !== recent.line)
+                return 'dm';
+            return 'unknown';
+        }
+        return payload.guildId == null ? 'dm' : 'group';
+    }
+    return 'unknown';
+}
+/** Most-recent inbound on `line`. Walks `history.jsonl` from the tail; returns undefined if missing. */
+function readRecentInbound(line) {
+    if (!existsSync(HISTORY_FILE))
+        return undefined;
+    const lines = readFileSync(HISTORY_FILE, 'utf8').split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (!lines[i].trim())
+            continue;
+        try {
+            const e = JSON.parse(lines[i]);
+            if (e.line === line && e.kind === 'inbound')
+                return e;
+        }
+        catch { /* skip */ }
+    }
+    return undefined;
+}
+/** Per-line decision: should auto-claim run on a successful outbound? */
+function shouldAutoClaim(line, kind) {
+    const station = Line.station(line);
+    /** Webhook lines are a broadcast stream — claiming one is a footgun. */
+    if (station === 'webhook')
+        return { ok: false, reason: 'webhook' };
+    /** Claude/Codex cross-user lines are 1:1 by construction — always safe. */
+    if (station === 'claude' || station === 'codex')
+        return { ok: true };
+    if (kind === 'group')
+        return { ok: false, reason: 'group' };
+    return { ok: true };
+}
+export function tryAutoClaim(line, owner, opts = {}) {
+    if (!opts.force) {
+        const decision = shouldAutoClaim(line, opts.lineKind ?? 'unknown');
+        if (!decision.ok)
+            return { status: decision.reason, line };
+    }
+    try {
+        return withClaimsLock(m => {
+            const existing = m[line];
+            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 };
+    }
+}

package/dist/broker/history-stream.js

@@ -0,0 +1,147 @@
+/** Per-user byte-offset cursors over history.jsonl + claim-aware mode filter. */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, renameSync, watch, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { errMsg, log } from '../log.js';
+import { STATE_DIR } from '../paths.js';
+import { HISTORY_FILE, readClaims } from './claims.js';
+const CURSORS_DIR = join(STATE_DIR, 'cursors');
+/** 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, '-');
+}
+/** Cursor key for a tail invocation. Derived from the *effective mode*, NOT from `userSelf()`. */
+/** Keeps `--all` / `--unclaimed` from trampling a `--as=<id>` cursor in a CLAUDECODE shell. */
+/** Keys: `--as=<id>`→slug(id); `+--strict`→slug+`--strict`; `--unclaimed`→`_unclaimed`; `--all`→`_all`. */
+/** The `_` prefix can't collide with a userSlug (always has a station prefix like `claude-user-…`). */
+/** `--include-webhooks` adds `--with-webhooks` so toggling mid-stream doesn't re-emit/skip events. */
+export function cursorKey(mode, self, opts = {}) {
+    if (mode === 'all')
+        return '_all';
+    if (mode === 'unclaimed')
+        return '_unclaimed';
+    if (!self)
+        return null;
+    const base = userSlug(self);
+    const suffix = mode === 'mine-only' ? '--strict' : '';
+    const webhooks = opts.includeWebhooks ? '--with-webhooks' : '';
+    return `${base}${suffix}${webhooks}`;
+}
+const cursorPath = (key) => join(CURSORS_DIR, key);
+export function readCursor(key) {
+    const p = cursorPath(key);
+    if (!existsSync(p))
+        return 0;
+    const n = Number(readFileSync(p, 'utf8').trim());
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+export function writeCursor(key, offset) {
+    mkdirSync(CURSORS_DIR, { recursive: true });
+    const p = cursorPath(key);
+    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;
+    return !owner || owner === self; /** mode === 'mine-or-unclaimed' */
+}
+/** Drain matching entries from `offset` to EOF, returning the new offset. */
+/** Caller `onEntry` may return `true` to stop draining early (e.g. tail --limit). */
+export function drainTail(offset, opts, onEntry) {
+    const claims = readClaims();
+    for (const { entry, offset: next } of readEntriesFrom(offset)) {
+        offset = next;
+        if (opts.chatFilter && entry.line !== opts.chatFilter)
+            continue;
+        if (opts.stationFilter && entry.station !== opts.stationFilter)
+            continue;
+        if (!passesMode(entry, opts.mode, opts.self, claims, { includeWebhooks: opts.includeWebhooks }))
+            continue;
+        if (onEntry(entry) === true)
+            return offset;
+    }
+    return offset;
+}
+/** Follow history.jsonl: drain on change + poll backstop (macOS fs.watch coalesces). */
+/** Caller invokes the returned `stop()` to clean up the watcher/timer. */
+export function followTail(startOffset, opts, onEntry, pollMs) {
+    let offset = startOffset;
+    const tick = () => { offset = drainTail(offset, opts, onEntry); };
+    let watcher = null;
+    try {
+        watcher = watch(HISTORY_FILE, () => tick());
+    }
+    catch { /* file may not exist yet */ }
+    const poll = setInterval(tick, pollMs);
+    return () => {
+        clearInterval(poll);
+        if (watcher) {
+            try {
+                watcher.close();
+            }
+            catch { /* ignore */ }
+        }
+    };
+}