@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.5

package/README.md

@@ -1,15 +1,24 @@
 # Metro
 
-Run a long-lived daemon that bridges Discord and Telegram to your Codex + Claude Code agents. Each chat thread/topic gets its own agent session with streaming responses and live tool-call status. Both agents run side-by-side — pick per-message with a `with claude` / `with codex` suffix.
+> **Bridge Discord, Telegram, and GitHub to Claude Code + Codex.**
 
-## Prereqs
+Metro is a small daemon that turns any chat thread, forum topic, or GitHub issue into a live conversation with your local coding agents. Each thread is its own agent session — Claude and Codex run side-by-side, replies stream in real time with tool calls visible inline, and you can stop a turn with one click.
 
-- **Node ≥ 22** (or Bun ≥ 1.3).
-- **One or both agent CLIs** installed and authenticated:
-  - **Claude Code** — run `claude` once interactively to log in. Metro shells out per turn and inherits your auth, plugins, settings.
-  - **Codex** — run `codex` once interactively to log in. Metro spawns `codex app-server` and inherits your auth, MCPs, sandboxing.
-- **Discord bot** (optional) with **Message Content Intent** enabled (Developer Portal → Bot → Privileged Gateway Intents).
-- **Telegram bot** (optional). In supergroup forums, the bot also needs the **Manage Topics** admin permission so it can auto-create topics on @-mention.
+```
+[Discord — #infra]
+
+less        @bot we got a 5xx spike from /v1/sync. Look?
+sandboxbot  > 🛠 Bash  git log --since=24h --oneline
+            > 🛠 Read  services/sync.ts
+
+            Three deploys in the last 24h. The 14:02 one swallows a
+            timeout into a 500 on line 47 instead of retrying. Want
+            me to open a PR?
+
+            [ ⏹ Stop ]
+```
+
+---
 
 ## Quickstart
 
@@ -18,97 +27,251 @@ 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 orchestrator
+metro                                    # run the dispatcher
 ```
 
-Metro starts both agents at boot and listens on whichever platforms are configured. Each scope defaults to **Claude** for the first turn; once you've used an agent there, follow-up messages stick with it. Switch per-message by suffixing `with claude` or `with codex` (any casing):
+Requires **Node ≥ 22 or Bun ≥ 1.3** and at least one of [Claude Code](https://claude.com/claude-code) or [Codex](https://github.com/openai/codex) installed and logged in (run them once interactively first; metro inherits your auth).
+
+In **Discord**: DM the bot, or `@<bot>` in any channel. In **Telegram**: DM, or `@<bot>` in a forum's General topic. In **GitHub**: see [Testing GitHub](#testing-github).
+
+---
+
+## Stations
+
+Everything in metro is a **station** with declared capabilities:
+
+| Station    | Kind  | Modalities    | Features                            | Config                                                            |
+|------------|-------|---------------|-------------------------------------|-------------------------------------------------------------------|
+| `claude`   | agent | text + image  | stream, tools, cancel, attachments  | `claude` CLI on PATH, logged in                                   |
+| `codex`    | agent | text + image  | stream, tools, cancel, attachments  | `codex` CLI on PATH, logged in                                    |
+| `discord`  | chat  | text + image  | stream, edit, attachments           | `DISCORD_BOT_TOKEN` + Message Content Intent                      |
+| `telegram` | chat  | text + image  | stream, edit, attachments           | `TELEGRAM_BOT_TOKEN` + Manage Topics admin (for forums)           |
+| `github`   | chat  | text          | edit                                | `GITHUB_WEBHOOK_SECRET` + `GITHUB_BOT_USERNAME` + `GITHUB_TOKEN`  |
+
+Run `metro stations` to see the same matrix with live config status (`✓` configured, `✗` not).
+
+Each chat platform behaves slightly differently — what's universal is captured by the capabilities; the rest is in [Conversations](#conversations).
+
+---
+
+## Lines
+
+Every conversational scope is identified by a **Line** — a URI in the form `metro://<station>/<path>`:
 
 ```
-@Metro draft a release note
-   → uses Claude (default for a new scope)
+metro://discord/1234567890123456789
+metro://telegram/-1001234567890                 # main chat / DM
+metro://telegram/-1001234567890/42              # forum topic 42
+metro://github/bonustrack/metro/issues/123      # GitHub issue
+metro://github/bonustrack/metro/pull/456        # GitHub PR
+```
+
+Lines map 1:1 to agent sessions in `scopes.json`. Anyone can post to a line via [`metro send`](#cli) — daemon optional. Full grammar in [`docs/uri-scheme.md`](docs/uri-scheme.md).
+
+---
+
+## Conversations
+
+### Discord
+
+- **DM the bot** — every message is implicit; one line per DM.
+- **`@<bot>` in any guild channel** — metro creates a thread from your message, allocates an agent session, and streams the reply. Follow-ups in the thread route automatically.
+- **Tool calls** — render as `🛠 <tool>` headers plus two fenced code blocks (input → output). Outputs cap at 50 lines / 1500 chars with a `_(N more lines)_` note when truncated. Parallel tool calls are paired by id and don't collide.
+- **Stop button** — every in-flight turn carries an `⏹ Stop` button that aborts the underlying subprocess (Claude via `SIGTERM`, Codex via `turn/interrupt`).
+- **Catchup on restart** — Discord uses a per-line `lastSeenMessageId` watermark; metro REST-fetches anything newer when it comes back up.
+
+### Telegram
+
+- **DM the bot** — implicit; one line per chat.
+- **`@<bot>` in a forum supergroup's General topic** — metro creates a new forum topic for the conversation and posts a deep link back in General so it's one tap away. Follow-ups in that topic route automatically.
+- **Inside an existing custom topic** — routes to that topic's line on every message.
+- **Markdown → Telegram HTML** — agent markdown (`**bold**`, `*italic*`, `` `code` ``, fences, `[link](url)`, blockquotes) is converted on the way out. Plain-text fallback if Telegram rejects the HTML.
+
+Regular (non-forum) groups are skipped — without a per-thread boundary the routing model breaks down.
+
+### GitHub
+
+`@<bot-user>` in an **issue body, issue comment, PR body, or PR comment** allocates a per-issue agent session and the bot replies as a comment on the same issue/PR. Streaming is simulated via `PATCH /issues/comments` edits to the bot's own comment. Each issue/PR holds its own session across follow-ups.
+
+Setup:
+
+```
+GITHUB_WEBHOOK_SECRET=<random>     # any high-entropy string
+GITHUB_BOT_USERNAME=<github user>  # whose @-mentions trigger the bot
+GITHUB_TOKEN=<PAT>                 # issues:write (+ pull_requests:write for PRs)
+METRO_GITHUB_PORT=4321             # optional, default 4321
+```
+
+In your repo's *Settings → Webhooks*: payload URL `https://<your-public-url>/webhook`, content type `application/json`, the secret matches `GITHUB_WEBHOOK_SECRET`, events: **Issues** + **Issue comments**. For local development tunnel with [smee.io](https://smee.io), [cloudflared](https://github.com/cloudflare/cloudflared), or [ngrok](https://ngrok.com).
+
+End-to-end recipe: [Testing GitHub](#testing-github).
+
+---
+
+## Agents
+
+Both agents run side-by-side at boot. Each line defaults to **Claude** for the first turn; once you've used an agent in a line, it sticks. Switch per-message with a `with claude` / `with codex` suffix:
+
+```
+@bot draft a release note
+   → uses Claude (default for a new line)
 
 How would Codex have done this? with codex
-   → routes this turn to Codex; stays Codex on subsequent turns
+   → routes this turn to Codex; the line stays Codex on follow-ups
 ```
 
-### Discord
+A line can hold one session per agent — independent histories — so switching back later resumes where that agent left off. If only one agent is installed, metro still starts and asks-for-the-missing-one error inline.
 
-@-mention the bot in any channel:
-1. Metro creates a thread anchored on your message (named after the message).
-2. Spins up an agent session for that thread.
-3. Streams the agent's reply with tool-call status (`Running: <command>`, `Editing 3 files`, `Thinking…`).
+---
 
-Follow-ups in the thread route automatically — no @-mention needed.
+## Cross-station relay
 
-### Telegram
+Agents can post to any line through the CLI:
+
+```bash
+metro send metro://telegram/-1001234567890/42 "patch deployed"
+metro send metro://github/bonustrack/metro/issues/1 "all clear"
+```
 
-- **DM the bot** — every message is implicitly addressed to it; one scope per chat.
-- **@-mention the bot in a forum supergroup's General topic** — metro auto-creates a new topic for the conversation (Discord-style "thread from message"). Subsequent messages in that topic route automatically.
-- **Inside an existing custom topic** — routes to that topic's scope on every message.
+`metro send` uses the same env tokens as the dispatcher and doesn't require the daemon — useful when an agent in one place needs to relay to another.
 
-Regular (non-forum) groups are not routed — they have no thread boundary.
+---
 
-## How it works
+## Architecture
 
 ```
-Discord gateway ──┐                       ┌─▶ codex app-server   (long-lived subprocess, UDS JSON-RPC)
-                  ├─▶ metro orchestrator ─┤
-Telegram poller ──┘                       └─▶ claude -p ...      (per-turn subprocess, stream-json)
-                            │
-                            └──── scope map (scopes.json)
+Discord gateway ──┐
+Telegram poller ──┤                          ┌─▶ codex station   (long-lived `codex app-server`, UDS JSON-RPC)
+GitHub webhook ───┼─▶ metro dispatcher ──────┤
+                  │                          └─▶ claude station  (per-turn `claude -p`, stream-json)
+                  └─── line → agent-thread map (`scopes.json`)
 ```
 
-- **One metro = one daemon.** Lockfile at `$METRO_STATE_DIR/.tail-lock` keeps things singleton.
-- **Both agents side-by-side.** A scope can have up to one session per agent — independent histories. Routing is per-message: explicit `with claude` / `with codex` suffix, otherwise the scope's last-used agent, otherwise Claude.
-- **Streaming.** Replies edit one message every ~1500 ms while deltas stream in (leading-edge first flush for fast initial feedback). Tool calls show as a status line; long replies split past ~1900 chars onto a follow-up message.
-- **Queueing.** Messages that arrive while a turn is running are buffered per-scope and answered together in the next reply.
-- **Catchup-on-restart.** Discord uses a per-scope `lastSeenMessageId` watermark and REST-fetches anything newer when metro comes back up. Telegram leans on its own update-id queue (persisted offset in `telegram-offset.json`).
+The codebase is built on a small protocol in [`src/stations/types.ts`](src/stations/types.ts):
 
-## Config
+- **`Station`** — name, capabilities, `start`/`stop` lifecycle.
+  - **`AgentStation`** — `createThread()`, `sendTurn(req)` returns an `AsyncIterable<TurnEvent>` of `delta` / `tool-start` / `tool-end`. Cancellation via `AbortSignal`.
+  - **`ChatStation<TMeta>`** — `onMessage`/`onStop` event hooks, `send`/`edit` for posting back. Typed meta carries platform extras (`inGuild`, `inForum`, `isPR`, …).
+- **`Line`** — branded URI string. Each station owns its parse/format helpers in [`src/stations/line.ts`](src/stations/line.ts).
+
+Adding a backend (Slack, Matrix, SMS, another LLM) = `class XStation implements ChatStation` + a `Line.x(...)` helper. The dispatcher picks it up polymorphically.
+
+Behaviors worth knowing:
+- **One daemon per machine.** Lockfile at `$METRO_STATE_DIR/.tail-lock` enforces singleton.
+- **Streaming.** Replies edit one message every ~1500 ms while deltas arrive (leading-edge first flush so feedback feels instant). Long replies split past ~1900 chars onto follow-up messages.
+- **No link previews.** Outgoing messages set `link_preview_options.is_disabled` on Telegram and `SUPPRESS_EMBEDS` on Discord so URLs don't unfurl.
+- **Image attachments.** Discord and Telegram image uploads are forwarded as vision inputs (Anthropic `image/base64` for Claude; `image_url` data URI for Codex). 20 MB cap; non-images surface as `[file: name]` text.
+- **In-flight queueing.** Messages arriving during a turn are buffered per-line and answered as one combined follow-up.
+
+---
+
+## Configuration
 
 | Variable | Default | Description |
 |---|---|---|
 | `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN` | — | Bot tokens. `metro setup` writes them here. |
+| `GITHUB_WEBHOOK_SECRET`, `GITHUB_BOT_USERNAME`, `GITHUB_TOKEN` | — | Enables GitHub. Token needs `issues:write` (+ `pull_requests:write` for PR comments). Webhook listens on `METRO_GITHUB_PORT` (default `4321`). |
 | `METRO_CONFIG_DIR` | `~/.config/metro` | Where the global `.env` lives. |
-| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, scope cache, codex socket, telegram offset, claude session set. |
+| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, line cache, codex socket, telegram offset, claude session set. |
 | `METRO_LOG_LEVEL` | `info` | `trace` / `debug` / `info` / `warn` / `error` / `fatal`. |
 
-Token precedence: process env → `./.env` → `$METRO_CONFIG_DIR/.env`. Logs to stderr.
+Precedence: process env → `./.env` → `$METRO_CONFIG_DIR/.env`. Logs go to stderr.
+
+---
+
+## CLI
+
+```
+metro                                       Run the dispatcher daemon.
+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 active conversations (sorted by recency, with names).
+metro send <line> <text>                    Post to any metro:// line.
+metro update                                Upgrade in place.
+```
+
+All commands accept `--json` for machine-readable output.
+
+**State files** in `$METRO_STATE_DIR`:
+- `scopes.json` — Line → agent-session map
+- `AGENTS.md` — skill doc copied from the package on every dispatcher start; surfaced into each agent's per-turn context so it knows about `metro lines` / `metro send` / `metro stations`
+- `.tail-lock` — dispatcher pid
+- `codex-app-server.sock` — codex Unix socket
+- `telegram-offset.json` — last processed update id
+- `claude-sessions.json` — known Claude session uuids (so restarts use `--resume`)
+
+---
 
-## Develop locally
+## 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
 ```
 
-## Reference
+Source map:
+
+- [`src/cli/`](src/cli/) — the `metro` binary entry ([`cli/index.ts`](src/cli/index.ts)) plus subcommand handlers (`lines.ts`, `update.ts`).
+- [`src/dispatcher.ts`](src/dispatcher.ts) — the daemon: wires stations together, routes inbounds, installs `AGENTS.md` into state on each start.
+- [`src/stations/`](src/stations/) — one folder per station (`claude/`, `codex/`, `discord/`, `github/`, `telegram/`) plus the shared `types.ts`, `line.ts`, `listing.ts`, `send.ts`.
+- [`src/helpers/`](src/helpers/) — `streaming.ts`, `turn.ts`, `scope-cache.ts`, `async-queue.ts`.
+- [`docs/uri-scheme.md`](docs/uri-scheme.md) specs the Line format; [`docs/agents.md`](docs/agents.md) is the in-context skill copied to `$METRO_STATE_DIR/AGENTS.md`.
+
+CI runs typecheck + lint + build on every PR via [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+---
+
+## Testing GitHub
+
+1. **Pick a GitHub user** the bot acts as (your own account works for testing) and generate a token. Two options:
+   - **Fine-grained PAT** at `github.com/settings/tokens?type=beta` — scoped to a test repo with **Issues: Read & write** (+ **Pull requests: Read & write** for PR comments). Works for *your* repos. For org repos, an org admin must enable fine-grained PATs in *Organization settings → Personal access tokens*.
+   - **Classic PAT** at `github.com/settings/tokens?type=classic` — pick the `repo` scope. Works for any repo you have access to, no org opt-in needed.
+2. **Set env vars**:
+   ```bash
+   export GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
+   export GITHUB_BOT_USERNAME="metrobot"   # see solo-testing note below
+   export GITHUB_TOKEN="ghp_..."
+   ```
+3. **Tunnel** your local webhook port to the internet:
+   ```bash
+   npx smee-client --target http://localhost:4321/webhook --url <https://smee.io/your-channel>
+   ```
+4. **Add a webhook** on the test repo (*Settings → Webhooks*): payload URL = the smee channel, content type `application/json`, the same secret, events **Issues** + **Issue comments**.
+5. **Run metro**: `METRO_LOG_LEVEL=debug metro` — you should see `github station: listening`.
+6. **Open an issue** with body `@metrobot hello, what's this repo?` — the bot comments back (as the token's owner).
 
-- `metro --help` — command surface
-- `metro doctor` — health check (tokens + gateway/poller reachability + orchestrator status)
-- State files (`$METRO_STATE_DIR`, defaults to `~/.cache/metro/`):
-  - `scopes.json` — Discord-thread / Telegram-topic ↔ agent-session map
-  - `.tail-lock` — orchestrator pid
-  - `codex-app-server.sock` — codex's UDS
-  - `telegram-offset.json` — last processed update id (used for catchup on restart)
-  - `claude-sessions.json` — set of started Claude session uuids (so restarts use `--resume` instead of `--session-id`)
+**Solo testing note.** Metro filters out self-mentions (`sender === bot`) to prevent reply loops. If you set `GITHUB_BOT_USERNAME` to your *own* username and then try to `@<yourself>` on an issue, the filter drops it — you can't trigger the bot alone. Workaround: use a pseudo-name like `metrobot` (doesn't need to be a real GitHub user — it's just a string match). The bot still replies as the token owner, but the filter passes because `your-username ≠ metrobot`.
+
+**Common gotchas:**
+- Webhook 401 → secret mismatch between `.env` and the webhook config.
+- Webhook 200 but no reply → token lacks `issues:write`, or `GITHUB_BOT_USERNAME` doesn't appear in the body verbatim (case-sensitive).
+- Bot replies in a loop → the bot's own comment somehow includes `@<bot-username>`; rare with the default prompt, but check `AGENTS.md` if it happens.
+
+---
+
+## Caveats
+
+- **No allowlist.** Anyone who can DM/`@`-mention your bot can spawn a session. Run against bots you own.
+- **Per-agent histories are separate.** `with codex` mid-line starts a fresh Codex session; it doesn't see what Claude saw, and vice versa.
+- **Telegram non-forum groups are skipped.** No thread boundary to scope on. DMs and forum topics work normally.
+- **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.
+- **GitHub needs a public URL.** Webhooks are HMAC-verified, so a leaked URL only lets attackers spam rejected POSTs — but use a high-entropy `GITHUB_WEBHOOK_SECRET`.
+- **Pre-1.0 line URIs aren't migrated.** Older `discord:ID` / `telegram:CHAT:TOPIC` keys in `scopes.json` are ignored after upgrade.
+
+---
 
 ## Uninstall
 
 ```bash
 metro setup clear
-rm -rf ~/.cache/metro/
+rm -rf ~/.cache/metro
 npm uninstall -g @stage-labs/metro
 ```
-
-## Caveats
-
-- **No allowlist.** Anyone who can DM/@-mention your bot can spawn an agent session. Run against bots you own.
-- **Per-agent histories are separate.** Switching with `with codex` mid-scope spins up a fresh Codex session — it has no idea what you discussed with Claude in the same scope. Each agent only sees what was sent to it.
-- **One agent missing is OK.** If only `claude` or only `codex` is installed/authenticated, metro still starts; messages asking for the missing one surface an error in chat.
-- **Telegram non-forum groups are skipped.** Without a per-topic thread boundary the routing model breaks down. DMs and forum topics (incl. auto-created ones from General) work normally.
-- **Telegram bot privacy.** Default Telegram bot privacy is *enabled*, which can block group messages even with @-mentions. Disable in [@BotFather](https://t.me/BotFather) → Bot Settings → Group Privacy → Turn off, then kick + re-invite the bot.

package/dist/cli/index.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import pkg from '../../package.json' with { type: 'json' };
+import { cmdLines } from './lines.js';
+import { cmdUpdate } from './update.js';
+import { DiscordStation } from '../stations/discord/index.js';
+import { TelegramStation } from '../stations/telegram/index.js';
+import { fmtCapabilities, listStations } from '../stations/listing.js';
+import { sendToLine } from '../stations/send.js';
+import { errMsg } from '../log.js';
+import { CONFIG_ENV_FILE, configuredPlatforms, loadMetroEnv, readDotenv, STATE_DIR, writeDotenv } from '../paths.js';
+const USAGE = `metro — Telegram + Discord bridge for your Claude Code / Codex agent
+
+Usage:
+  metro                                       Run the dispatcher daemon.
+  metro setup [telegram|discord <token>]      Save token, or show status with no args.
+  metro setup clear [telegram|discord|all]    Remove tokens.
+  metro doctor                                Health check.
+  metro stations                              List stations + capabilities.
+  metro lines                                 List active conversations (sorted by recency).
+  metro send <line> <text>                    Post a message to a metro:// line.
+  metro update                                Upgrade in place.
+  metro --version | --help
+Exit codes: 0 success · 1 usage · 2 config · 3 upstream
+`;
+const exitErr = (msg, code) => Object.assign(new Error(msg), { code });
+const isJson = (f) => f.json === true;
+const emit = (f, human, structured) => void process.stdout.write(isJson(f) ? JSON.stringify(structured) + '\n' : human + '\n');
+const maskToken = (t) => !t ? '' : t.length <= 8 ? '••••' : `${t.slice(0, 6)}…${t.slice(-2)}`;
+const TOKEN_KEYS = { telegram: 'TELEGRAM_BOT_TOKEN', discord: 'DISCORD_BOT_TOKEN' };
+function parseArgs(argv) {
+    const positional = [], flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--')) {
+            positional.push(a);
+            continue;
+        }
+        const eq = a.indexOf('=');
+        if (eq !== -1) {
+            flags[a.slice(2, eq)] = a.slice(eq + 1);
+            continue;
+        }
+        const key = a.slice(2), next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            flags[key] = next;
+            i++;
+        }
+        else
+            flags[key] = true;
+    }
+    return { positional, flags };
+}
+/** Apply a token across CONFIG_ENV_FILE (always set/cleared) AND cwd/.env (only if it exists). Returns paths touched. */
+function applyTokenToAllEnvs(key, value) {
+    const out = [];
+    for (const path of [CONFIG_ENV_FILE, join(process.cwd(), '.env')]) {
+        if (path !== CONFIG_ENV_FILE && !existsSync(path))
+            continue;
+        const env = readDotenv(path);
+        if (value === null) {
+            if (!(key in env))
+                continue;
+            delete env[key];
+        }
+        else
+            env[key] = value;
+        writeDotenv(path, env);
+        out.push(path);
+    }
+    return out;
+}
+async function cmdSetup(positional, flags) {
+    const [sub, value] = positional;
+    if (!sub)
+        return cmdSetupStatus(flags);
+    if (sub === 'telegram' || sub === 'discord') {
+        if (!value)
+            throw new Error(`metro setup ${sub} <token> — token is required`);
+        const trimmed = value.trim();
+        let identity;
+        if (!flags['no-validate']) {
+            process.env[TOKEN_KEYS[sub]] = trimmed;
+            try {
+                identity = sub === 'telegram' ? `@${(await new TelegramStation().getMe()).username}` : (await new DiscordStation().getMe()).username;
+            }
+            catch (err) {
+                delete process.env[TOKEN_KEYS[sub]];
+                throw exitErr(`token rejected by ${sub}: ${errMsg(err)} (use --no-validate to save anyway)`, 3);
+            }
+        }
+        const paths = applyTokenToAllEnvs(TOKEN_KEYS[sub], trimmed);
+        emit(flags, `saved ${TOKEN_KEYS[sub]}${identity ? ` (verified as ${identity})` : ''} to ${paths.join(', ')}\nrestart metro for the new token to take effect.`, { ok: true, saved: TOKEN_KEYS[sub], paths, verified_as: identity ?? null });
+        return;
+    }
+    if (sub === 'clear') {
+        const target = value ?? 'all';
+        if (target !== 'all' && target !== 'telegram' && target !== 'discord')
+            throw new Error(`metro setup clear <telegram|discord|all> — got '${target}'`);
+        const keys = target === 'all' ? ['TELEGRAM_BOT_TOKEN', 'DISCORD_BOT_TOKEN'] : [TOKEN_KEYS[target]];
+        const paths = new Set();
+        for (const k of keys)
+            for (const p of applyTokenToAllEnvs(k, null))
+                paths.add(p);
+        const label = target === 'all' ? 'all metro tokens' : TOKEN_KEYS[target];
+        return void emit(flags, `cleared ${label} from ${[...paths].join(', ') || '(no files had it)'}\nrestart metro for changes to take effect.`, { ok: true, cleared: target, paths: [...paths] });
+    }
+    throw new Error(`unknown setup subcommand '${sub}' (try: telegram, discord, clear)`);
+}
+async function cmdSetupStatus(flags) {
+    loadMetroEnv();
+    const tg = process.env.TELEGRAM_BOT_TOKEN ?? '', dc = process.env.DISCORD_BOT_TOKEN ?? '';
+    if (isJson(flags))
+        return void process.stdout.write(JSON.stringify({ version: pkg.version, config_env_file: CONFIG_ENV_FILE,
+            tokens: { telegram: { set: !!tg, masked: maskToken(tg) }, discord: { set: !!dc, masked: maskToken(dc) } } }) + '\n');
+    const cfgState = existsSync(CONFIG_ENV_FILE) ? '' : ' (not yet written)';
+    process.stdout.write(`metro ${pkg.version}\n\nconfig:  ${CONFIG_ENV_FILE}${cfgState}\n\n  TELEGRAM_BOT_TOKEN  ${tg ? `set (${maskToken(tg)})` : 'not set'}\n  DISCORD_BOT_TOKEN   ${dc ? `set (${maskToken(dc)})` : 'not set'}\n\n${!tg && !dc
+        ? 'Get started:\n  1. metro setup telegram <token>   # https://t.me/BotFather\n     metro setup discord <token>     # https://discord.com/developers/applications\n  2. metro doctor\n  3. metro\n'
+        : 'Run `metro` to start the dispatcher, or `metro doctor` to verify.\n'}`);
+}
+/** Find which file (or process env) supplied the currently-loaded token, so doctor can name the real source. */
+function tokenSource(key) {
+    const val = process.env[key];
+    if (!val)
+        return '';
+    for (const path of [join(process.cwd(), '.env'), CONFIG_ENV_FILE])
+        if (existsSync(path) && readDotenv(path)[key] === val)
+            return path;
+    return 'process env';
+}
+async function cmdDoctor(flags) {
+    loadMetroEnv();
+    const cfg = configuredPlatforms();
+    const sources = [['telegram', 'TELEGRAM_BOT_TOKEN'], ['discord', 'DISCORD_BOT_TOKEN']].filter(([p]) => cfg[p]).map(([p, k]) => `${p}←${tokenSource(k)}`).join(', ');
+    const checks = [{ name: 'tokens', ok: cfg.telegram || cfg.discord,
+            detail: cfg.telegram || cfg.discord ? sources : 'no platform configured — run `metro setup telegram|discord <token>`',
+        }];
+    const getMeFns = { telegram: () => new TelegramStation().getMe(), discord: () => new DiscordStation().getMe() };
+    for (const p of ['telegram', 'discord']) {
+        if (!cfg[p]) {
+            checks.push({ name: p, ok: null, detail: 'not configured' });
+            continue;
+        }
+        try {
+            const me = await getMeFns[p]();
+            checks.push({ name: p, ok: true, detail: `getMe → ${p === 'telegram' ? '@' : ''}${me.username}` });
+        }
+        catch (err) {
+            checks.push({ name: p, ok: false, detail: errMsg(err) });
+        }
+    }
+    checks.push(dispatcherCheck());
+    if (isJson(flags))
+        process.stdout.write(JSON.stringify({ checks }) + '\n');
+    else {
+        process.stdout.write('metro doctor\n\n');
+        for (const c of checks)
+            process.stdout.write(`  ${c.ok === true ? '✓' : c.ok === false ? '✗' : '–'} ${c.name.padEnd(15)} ${c.detail}\n`);
+        process.stdout.write('\n');
+    }
+    if (checks.some(c => c.ok === false))
+        throw exitErr('one or more checks failed', 3);
+}
+function dispatcherCheck() {
+    const lockFile = join(STATE_DIR, '.tail-lock');
+    if (!existsSync(lockFile))
+        return { name: 'dispatcher', ok: null, detail: 'not running' };
+    try {
+        const pid = Number(readFileSync(lockFile, 'utf8').trim());
+        if (!Number.isInteger(pid) || pid <= 0)
+            throw new Error('invalid pid');
+        process.kill(pid, 0);
+        return { name: 'dispatcher', ok: true, detail: `running (pid ${pid})` };
+    }
+    catch {
+        return { name: 'dispatcher', ok: null, detail: 'stale lockfile (will auto-reclaim on next start)' };
+    }
+}
+async function cmdSend(positional, flags) {
+    const [to, ...rest] = positional;
+    if (!to || !rest.length)
+        throw exitErr('usage: metro send <line> <text>', 1);
+    loadMetroEnv();
+    const { line, messageId } = await sendToLine(to, rest.join(' '));
+    emit(flags, `sent ${messageId} to ${line}`, { ok: true, line, messageId });
+}
+async function cmdStations(flags) {
+    loadMetroEnv();
+    const rows = listStations();
+    if (isJson(flags))
+        return void process.stdout.write(JSON.stringify({ stations: rows }) + '\n');
+    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`);
+    }
+    process.stdout.write('\n');
+}
+const COMMANDS = {
+    setup: cmdSetup,
+    doctor: (_, f) => cmdDoctor(f),
+    stations: (_, f) => cmdStations(f),
+    lines: (_, f) => cmdLines(isJson(f)),
+    send: cmdSend,
+    update: (_, f) => cmdUpdate(isJson(f)),
+};
+async function main() {
+    const cmd = process.argv[2];
+    if (cmd === '--version' || cmd === '-v')
+        return void process.stdout.write(`${pkg.version}\n`);
+    if (cmd === '--help' || cmd === '-h')
+        return void process.stdout.write(USAGE);
+    if (!cmd) {
+        await import('../dispatcher.js');
+        return;
+    }
+    const handler = COMMANDS[cmd];
+    if (!handler) {
+        process.stderr.write(`unknown command '${cmd}'\n\n${USAGE}`);
+        process.exit(1);
+    }
+    const { positional, flags } = parseArgs(process.argv.slice(3));
+    try {
+        await handler(positional, flags);
+    }
+    catch (err) {
+        const code = err.code;
+        if (isJson(flags))
+            process.stdout.write(JSON.stringify({ ok: false, error: errMsg(err), code: code ?? 1 }) + '\n');
+        else
+            process.stderr.write(`error: ${errMsg(err)}\n`);
+        process.exit(typeof code === 'number' ? code : 1);
+    }
+}
+await main();

package/dist/cli/lines.js

@@ -0,0 +1,40 @@
+/** `metro lines` — list active lines from scopes.json, sorted by recency. */
+import { listLines } from '../helpers/scope-cache.js';
+import { loadMetroEnv } from '../paths.js';
+export async function cmdLines(json) {
+    loadMetroEnv();
+    const rows = listLines()
+        /** Drop pre-URI legacy keys (e.g. `discord:ID`) — they're not routable and just clutter the listing. */
+        .filter(({ line }) => line.startsWith('metro://'))
+        .map(({ line, entry }) => ({
+        line, name: entry.name ?? null,
+        lastSeenAt: entry.lastSeenAt ?? null,
+        lastAgent: entry.lastAgent ?? null,
+        agents: Object.keys(entry.agents ?? {}),
+    }))
+        .sort((a, b) => (b.lastSeenAt ?? '').localeCompare(a.lastSeenAt ?? ''));
+    if (json)
+        return void process.stdout.write(JSON.stringify({ lines: rows }) + '\n');
+    if (!rows.length)
+        return void process.stdout.write('metro lines\n\n  (none yet — start a conversation to populate)\n\n');
+    const widest = Math.max(...rows.map(r => r.line.length));
+    process.stdout.write('metro lines\n\n');
+    for (const r of rows) {
+        const when = r.lastSeenAt ? humanAgo(r.lastSeenAt) : '—';
+        const agent = r.lastAgent ?? r.agents.join('+') ?? '—';
+        const tag = r.name ? `  ${truncate(r.name, 40)}` : '';
+        process.stdout.write(`  ${when.padEnd(10)} ${agent.padEnd(8)} ${r.line.padEnd(widest)}${tag}\n`);
+    }
+    process.stdout.write('\n');
+}
+const humanAgo = (iso) => {
+    const sec = Math.max(0, Math.floor((Date.now() - new Date(iso).getTime()) / 1000));
+    if (sec < 60)
+        return `${sec}s ago`;
+    if (sec < 3600)
+        return `${Math.floor(sec / 60)}m ago`;
+    if (sec < 86400)
+        return `${Math.floor(sec / 3600)}h ago`;
+    return `${Math.floor(sec / 86400)}d ago`;
+};
+const truncate = (s, n) => s.length <= n ? s : s.slice(0, n - 1) + '…';

package/dist/cli/update.js

@@ -0,0 +1,27 @@
+/** `metro update` — npm registry lookup + in-place global install. */
+import { spawn } from 'node:child_process';
+import pkg from '../../package.json' with { type: 'json' };
+const emit = (json, human, structured) => {
+    process.stdout.write(json ? JSON.stringify(structured) + '\n' : human + '\n');
+};
+export async function cmdUpdate(json) {
+    const tag = pkg.version.includes('-') ? 'beta' : 'latest';
+    const res = await fetch('https://registry.npmjs.org/@stage-labs/metro', { signal: AbortSignal.timeout(15_000) });
+    if (!res.ok)
+        throw new Error(`npm registry: ${res.status}`);
+    const latest = (await res.json())['dist-tags']?.[tag];
+    if (!latest)
+        throw new Error(`no '${tag}' dist-tag for @stage-labs/metro`);
+    if (latest === pkg.version)
+        return emit(json, `already on ${pkg.version} (latest ${tag})`, { ok: true, current: pkg.version, latest, upgraded: false });
+    const argv1 = process.argv[1] ?? '', spec = `@stage-labs/metro@${tag}`;
+    const argv = argv1.includes('/.bun/') || argv1.includes('\\bun\\') ? ['bun', 'add', '-g', spec]
+        : argv1.includes('/pnpm/') || argv1.includes('\\pnpm\\') ? ['pnpm', 'add', '-g', spec]
+            : ['npm', 'install', '-g', spec];
+    emit(json, `metro ${pkg.version} → ${latest}\n$ ${argv.join(' ')}`, { ok: true, current: pkg.version, latest, command: argv.join(' ') });
+    await new Promise((resolve, reject) => {
+        const child = spawn(argv[0], argv.slice(1), { stdio: json ? 'ignore' : 'inherit' });
+        child.on('exit', code => code === 0 ? resolve() : reject(new Error(`${argv[0]} exited ${code}`)));
+        child.on('error', reject);
+    });
+}