slack-term 1.46.0 → 1.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slack-term",
-  "version": "1.46.0",
+  "version": "1.48.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/slack-term.git"
@@ -25,6 +25,10 @@
   "bin": {
     "slack": "./ts/cli.ts"
   },
+  "exports": {
+    "./worker": "./worker/src/index.ts",
+    "./package.json": "./package.json"
+  },
   "description": "Slack CLI — read activity/news/mentions, search, send messages with a confirm-hash safety gate.",
   "engines": {
     "node": ">=18"
@@ -32,6 +36,7 @@
   "files": [
     "ts/",
     "dist/",
+    "worker/src/",
     "README.md",
     "SKILL.md",
     "LICENSE"
@@ -75,5 +80,13 @@
   "type": "module",
   "dependencies": {
     "yargs": "^18.0.0"
+  },
+  "peerDependencies": {
+    "@cloudflare/workers-types": "^4"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/workers-types": {
+      "optional": true
+    }
   }
 }

package/ts/cli.ts

@@ -14,7 +14,8 @@ import { diagnoseBotMessaging, formatDiagnosis } from "./botdoctor.ts";
 import { cmdAuthLogin, cmdAuthLoginChrome, cmdAuthChrome, cmdAuthFirefox, cmdAuthToken, cmdAuthApp, cmdAuthSave, cmdAuthTokens } from "./auth.ts";
 import { cmdTail, parseSince as parseDuration } from "./tail.ts";
 import { runStream, webClient } from "./stream.ts";
-import { relaySubscriber } from "./relay.ts";
+import { relaySubscriber, relayTransport } from "./relay.ts";
+import { DEFAULT_DIR, initRelay, initReport, relayHealth } from "./relayInit.ts";
 import { agentCommands } from "./agent.ts";
 
 import {
@@ -5558,8 +5559,9 @@ async function main(): Promise<void> {
     .option("workspace", { alias: "w", type: "string", describe: "Workspace name" })
     .middleware(async (argv) => {
       const cmd = String((argv._ ?? [])[0] ?? "");
-      // `sent` reads only the local log — no token, no network.
-      if (!cmd || cmd === "auth" || cmd === "login" || cmd === "agent" || cmd === "sent") return;
+      // `sent` reads only the local log — no token, no network. `relay` writes
+      // local files (init) or talks to the user's own relay (health): no Slack token.
+      if (!cmd || cmd === "auth" || cmd === "login" || cmd === "agent" || cmd === "sent" || cmd === "relay") return;
       try {
         const active = resolveToken((argv as W).workspace);
         const bot = resolveBotToken();
@@ -7638,6 +7640,46 @@ async function main(): Promise<void> {
         )
         .command("$0", false as unknown as string, () => {}, () => { y.showHelp(); process.exit(0); }),
     )
+    .command(
+      "relay",
+      "Set up / check the real-time relay for `slack stream` (a Cloudflare Worker)",
+      (y) => y
+        .command(
+          "init [dir]",
+          "Scaffold a deployable relay Worker folder (local files only; prints a fresh RELAY_TOKEN and the next steps)",
+          (y2) => y2
+            .positional("dir", { type: "string", default: DEFAULT_DIR, describe: "Folder to create" })
+            .option("name", { type: "string", describe: "Worker name (default: the folder's name)" })
+            .option("force", { type: "boolean", default: false, describe: "Overwrite files that already exist" })
+            .option("slack-term", { type: "string", describe: "slack-term dependency spec (default: this CLI's version), e.g. latest or file:../slack-term" }),
+          (argv) => {
+            const r = initRelay(argv.dir, {
+              force: argv.force,
+              ...(argv.name !== undefined ? { name: argv.name } : {}),
+              ...(argv["slack-term"] !== undefined ? { slackTerm: argv["slack-term"] } : {}),
+            });
+            if (!r.ok) {
+              console.error(`slack relay init: ${r.error}`);
+              for (const f of r.existing ?? []) console.error(`  exists: ${f}`);
+              process.exit(2);
+            }
+            console.log(initReport(r));
+          },
+        )
+        .command(
+          "health",
+          "GET /health on the relay (SLACK_RELAY_URL / SLACK_RELAY_TOKEN); exit 0 = ok",
+          (y2) => y2
+            .option("url", { type: "string", describe: "Relay URL (default: $SLACK_RELAY_URL)" })
+            .option("token", { type: "string", describe: "Relay token (default: $SLACK_RELAY_TOKEN)" }),
+          async (argv) => {
+            const r = await relayHealth(argv.url ?? process.env.SLACK_RELAY_URL, argv.token ?? process.env.SLACK_RELAY_TOKEN);
+            (r.code === 0 ? console.log : console.error)(r.out);
+            process.exit(r.code);
+          },
+        )
+        .demandCommand(1, "Specify a relay subcommand (init, health)"),
+    )
     .command(
       "stream",
       "Print every new message matching --grep, across all channels the identity is in (threads included); resumable",
@@ -7655,7 +7697,7 @@ async function main(): Promise<void> {
         .option("calls-per-min", { type: "number", default: 40, describe: "Polling: pace conversations.history/replies to this many calls per minute (0 = unpaced)" })
         .option("state", { type: "string", describe: "Cursor file (default: one per identity+grep+channels under $XDG_STATE_HOME/slack-term/stream/)" })
         .option("as-user", { type: "boolean", default: false, describe: "Stream as the user identity (sees the user's DMs) instead of the bot" })
-        .option("relay", { type: "boolean", default: true, describe: "Use the doorbell relay (worker/) when SLACK_RELAY_URL and SLACK_RELAY_TOKEN are set; --no-relay polls only" })
+        .option("relay", { type: "boolean", default: true, describe: "Use the doorbell relay (`slack relay init`) when SLACK_RELAY_URL and SLACK_RELAY_TOKEN are set; --no-relay polls only" })
         .option("reconcile", { type: "string", default: "5m", describe: "While the relay is connected, poll this rarely as a safety net" }),
       async (argv) => {
         let re: RegExp;
@@ -7753,7 +7795,7 @@ async function main(): Promise<void> {
         const relayUrl = process.env.SLACK_RELAY_URL;
         const relayToken = process.env.SLACK_RELAY_TOKEN;
         const relay = argv.relay && !asUser && !argv.once && relayUrl && relayToken
-          ? { url: relayUrl, subscribe: relaySubscriber(relayUrl, relayToken), reconcileMs }
+          ? { url: relayUrl, subscribe: relaySubscriber(relayUrl, relayToken, undefined, { transport: relayTransport(process.env.SLACK_RELAY_TRANSPORT) }), reconcileMs }
           : undefined;
         if (argv.relay && asUser && relayUrl) console.error("slack stream: relay not used with --as-user (it only sees the bot's channels)");
         const pollReason = !argv.relay ? "--no-relay"

package/ts/relay.ts

@@ -1,11 +1,17 @@
 // Client for the slack-term relay (worker/): a Cloudflare Worker that receives
 // Slack's Events API and serves "doorbells" — {channel, ts, thread_ts}, never
-// message text — as a resumable Server-Sent Events stream. `slack stream` uses
-// it to scan the one channel a bell names within a second of the post, instead
-// of waiting for its next poll.
+// message text — as a resumable stream. `slack stream` uses it to scan the one
+// channel a bell names within a second of the post, instead of waiting for its
+// next poll.
 //
-// SSE over fetch (not WebSocket) so the bearer token travels in a header on
-// both bun and node, and never in a URL.
+// Transport: a WebSocket to /ws first. The relay accepts it as a hibernatable
+// socket, so its Durable Object is not kept awake (and billed) while we sit
+// connected, and our 25 s "ping" is answered without waking it. The bearer
+// token never goes in a URL: it rides in the Sec-WebSocket-Protocol header as
+// `bearer.<base64url(token)>` — Node's WebSocket cannot set other headers.
+// If the socket cannot be opened at all (a relay from before /ws, a proxy
+// that strips upgrades, a runtime without WebSocket), the same connection
+// falls back to the old Server-Sent Events endpoint, /stream, over fetch.
 
 /** A bell: where a message just appeared. */
 export type Doorbell = {
@@ -18,7 +24,13 @@ export type Doorbell = {
  *  starts from; `gap` means bells after the requested seq are gone (expired,
  *  or the relay was reset), so the client must catch up by polling. `epoch`
  *  names the relay's storage: a new one means its numbering restarted. */
-export type Hello = { seq: number; gap: boolean; retention_sec: number; epoch?: string };
+export type Hello = {
+  seq: number; gap: boolean; retention_sec: number; epoch?: string;
+  /** Client-side: which transport this connection uses. */
+  via?: Transport;
+};
+
+export type Transport = "websocket" | "sse";
 
 /** Where to resume: the last seq taken, in the numbering of `epoch`. */
 export type Cursor = { seq: number; epoch?: string };
@@ -58,8 +70,158 @@ export function parseSse(buf: string, emit: (event: string, data: string, id: st
   return buf;
 }
 
-export function relaySubscriber(baseUrl: string, token: string, idleMs = 70_000): Subscribe {
+/** The subprotocol the relay's /ws speaks; it echoes this one back. */
+export const WS_PROTOCOL = "slack-term-relay.v1";
+
+/** The subprotocol that carries the bearer token: subprotocols must be HTTP
+ *  tokens, so the token is base64url-encoded. */
+export function bearerProtocol(token: string): string {
+  return `bearer.${Buffer.from(token, "utf8").toString("base64url")}`;
+}
+
+/** The slice of the WHATWG WebSocket this client uses (bun's and node's). */
+export type WebSocketLike = {
+  readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: ((ev: unknown) => void) | null;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+  onclose: ((ev: { code: number; reason: string }) => void) | null;
+};
+export type WebSocketCtor = new (url: string, protocols: string[]) => WebSocketLike;
+
+export type RelayOptions = {
+  /** "auto" (default): WebSocket, falling back to SSE when it cannot open. */
+  transport?: "auto" | Transport;
+  /** Defaults to the runtime's global WebSocket; null means none. */
+  WebSocket?: WebSocketCtor | null;
+  /** Keepalive ping interval; the relay answers without waking up. */
+  pingMs?: number;
+  /** How long a received bell may wait for its ack (acks are batched). */
+  ackDelayMs?: number;
+};
+
+/** SLACK_RELAY_TRANSPORT: "websocket" or "sse" pins one; anything else is "auto". */
+export function relayTransport(v: string | undefined): "auto" | Transport {
+  return v === "websocket" || v === "sse" ? v : "auto";
+}
+
+/** Received-but-unacked bells that trigger an ack at once. The relay cuts a
+ *  client off at 64 unacked live bells, and replays its backlog one batch
+ *  per ack. */
+const ACK_EVERY = 32;
+
+function resumeQuery(after: Cursor | undefined): string {
+  return after === undefined ? "" : `?after=${after.seq}${after.epoch ? `&epoch=${encodeURIComponent(after.epoch)}` : ""}`;
+}
+
+export function relaySubscriber(baseUrl: string, token: string, idleMs = 70_000, opts: RelayOptions = {}): Subscribe {
   const base = baseUrl.replace(/\/+$/, "");
+  const transport = opts.transport ?? "auto";
+  const sse = sseSubscriber(base, token, idleMs);
+  return async (after, signal, on) => {
+    const WS = opts.WebSocket === undefined ? (globalThis as { WebSocket?: WebSocketCtor }).WebSocket : opts.WebSocket;
+    if (transport !== "sse") {
+      if (!WS) {
+        if (transport === "websocket") throw new Error("relay: this runtime has no WebSocket");
+      } else {
+        const opened = await wsSubscribe(WS, base, token, idleMs, opts.pingMs ?? 25_000, opts.ackDelayMs ?? 100, after, signal, on);
+        if (opened || signal.aborted) return;
+        // Never opened: an old relay, or something in between refusing the
+        // upgrade. SSE says which — a 401 from it is a RelayAuthError.
+        if (transport === "websocket") throw new Error("relay: WebSocket connection failed");
+      }
+    }
+    return sse(after, signal, on);
+  };
+}
+
+/** One WebSocket connection. Resolves true once it has been open (closed by
+ *  the server normally, or aborted), false if it never opened — the caller
+ *  then falls back to SSE. Rejects on an abnormal close or silence. */
+function wsSubscribe(
+  WS: WebSocketCtor, base: string, token: string, idleMs: number, pingMs: number, ackDelayMs: number,
+  after: Cursor | undefined, signal: AbortSignal, on: RelayHandlers,
+): Promise<boolean> {
+  return new Promise<boolean>((resolve, reject) => {
+    if (signal.aborted) return resolve(true);
+    let ws: WebSocketLike;
+    try {
+      ws = new WS(`${base.replace(/^http/i, "ws")}/ws${resumeQuery(after)}`, [WS_PROTOCOL, bearerProtocol(token)]);
+    } catch {
+      return resolve(false);
+    }
+    let opened = false;
+    let done = false;
+    let idle: ReturnType<typeof setTimeout> | undefined;
+    let ackTimer: ReturnType<typeof setTimeout> | undefined;
+    let ping: ReturnType<typeof setInterval> | undefined;
+    let last = 0; // highest seq received
+    let acked = 0; // highest seq acked
+    const finish = (err?: Error): void => {
+      if (done) return;
+      done = true;
+      clearTimeout(idle);
+      clearTimeout(ackTimer);
+      clearInterval(ping);
+      signal.removeEventListener("abort", onAbort);
+      ws.onopen = ws.onmessage = ws.onerror = ws.onclose = null;
+      try { ws.close(1000); } catch { /* already closing */ }
+      if (err) reject(err);
+      else resolve(opened || signal.aborted);
+    };
+    const onAbort = (): void => finish();
+    signal.addEventListener("abort", onAbort, { once: true });
+    const arm = (): void => {
+      clearTimeout(idle);
+      // Silence before the open is a handshake that hangs: fall back.
+      idle = setTimeout(() => finish(opened ? new Error(`relay: no data for ${Math.round(idleMs / 1000)}s`) : undefined), idleMs);
+    };
+    const ack = (): void => {
+      clearTimeout(ackTimer);
+      ackTimer = undefined;
+      if (last <= acked) return;
+      acked = last;
+      try { ws.send(JSON.stringify({ type: "ack", seq: last })); } catch { /* the close event reports it */ }
+    };
+    arm();
+    ws.onopen = () => {
+      opened = true;
+      arm();
+      ping = setInterval(() => { try { ws.send("ping"); } catch { /* the close event reports it */ } }, pingMs);
+    };
+    ws.onmessage = (ev) => {
+      arm();
+      if (typeof ev.data !== "string" || ev.data === "pong") return;
+      let m: { type?: unknown; seq?: unknown; bell?: unknown };
+      try {
+        m = JSON.parse(ev.data) as typeof m;
+      } catch (e) {
+        return finish(e as Error);
+      }
+      if (m.type === "hello") {
+        const { type: _, ...h } = m as Hello & { type: string };
+        last = acked = h.seq;
+        on.hello({ ...h, via: "websocket" });
+      } else if (m.type === "bell" && typeof m.seq === "number") {
+        on.bell(m.seq, m.bell as Doorbell);
+        if (done) return; // the handler hung up
+        last = Math.max(last, m.seq);
+        if (last - acked >= ACK_EVERY) ack();
+        else ackTimer ??= setTimeout(ack, ackDelayMs);
+      }
+    };
+    ws.onerror = () => { /* a close event follows */ };
+    ws.onclose = (ev) => {
+      if (!opened || ev.code === 1000) return finish();
+      finish(new Error(`relay: WebSocket closed (${ev.code}${ev.reason ? ` ${ev.reason}` : ""})`));
+    };
+  });
+}
+
+/** The Server-Sent Events transport (GET /stream). */
+function sseSubscriber(base: string, token: string, idleMs: number): Subscribe {
   return async (after, signal, on) => {
     const ac = new AbortController();
     const stop = (): void => ac.abort();
@@ -72,8 +234,7 @@ export function relaySubscriber(baseUrl: string, token: string, idleMs = 70_000)
     };
     try {
       arm();
-      const q = after === undefined ? "" : `?after=${after.seq}${after.epoch ? `&epoch=${encodeURIComponent(after.epoch)}` : ""}`;
-      const res = await fetch(`${base}/stream${q}`, {
+      const res = await fetch(`${base}/stream${resumeQuery(after)}`, {
         headers: { authorization: `Bearer ${token}`, accept: "text/event-stream" },
         signal: ac.signal,
       });
@@ -89,7 +250,7 @@ export function relaySubscriber(baseUrl: string, token: string, idleMs = 70_000)
         // CRLF is normalised on the whole buffer: a \r\n pair can straddle chunks.
         buf = parseSse((buf + dec.decode(value, { stream: true })).replace(/\r\n/g, "\n"), (event, data, id) => {
           const j = JSON.parse(data) as unknown;
-          if (event === "hello") on.hello(j as Hello);
+          if (event === "hello") on.hello({ ...j as Hello, via: "sse" });
           else if (event === "bell" && id !== undefined) on.bell(Number(id), j as Doorbell);
         });
       }

package/ts/relayInit.ts

@@ -0,0 +1,209 @@
+// `slack relay init` / `slack relay health`: set up and check the doorbell
+// relay without cloning this repo.
+//
+// The relay's code ships in the npm package as `slack-term/worker`
+// (worker/src/), so a deployable Worker is a two-line re-export plus a
+// wrangler.jsonc. `init` writes that folder — local files only, no network,
+// nothing that touches Slack — and prints a fresh RELAY_TOKEN with the next
+// steps. The token is deliberately NOT written into the folder: it is a secret,
+// and the folder is meant to be committed.
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import pkg from "../package.json" with { type: "json" };
+
+/** The wrangler the repo deploys worker/ with (worker/package.json). */
+export const WRANGLER_VERSION = "4.105.0";
+/** worker/wrangler.jsonc's compatibility_date. */
+export const COMPATIBILITY_DATE = "2026-07-01";
+export const DEFAULT_DIR = "slack-term-relay";
+export const RELAY_DOCS_URL = "https://github.com/snomiao/slack-term/blob/main/worker/README.md";
+
+/** A Workers script name: lowercase letters, digits and dashes, 1–63 chars,
+ *  no leading or trailing dash. */
+export function validWorkerName(name: string): boolean {
+  return /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(name);
+}
+
+/** A directory name turned into a valid Worker name. */
+export function workerNameFrom(dir: string): string {
+  const n = basename(resolve(dir)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63).replace(/-+$/, "");
+  return n || DEFAULT_DIR;
+}
+
+export type ScaffoldOptions = {
+  /** Worker name; default: the directory's basename. */
+  name?: string;
+  /** The `slack-term` dependency spec; default: `^` this CLI's version (a source
+   *  checkout carries a stale placeholder version; the range still resolves). */
+  slackTerm?: string;
+};
+
+/** The scaffold's files, relative path → content. */
+export function relayFiles(name: string, opts: { slackTerm?: string } = {}): Record<string, string> {
+  const packageJson = {
+    name,
+    private: true,
+    type: "module",
+    scripts: { deploy: "wrangler deploy", dev: "wrangler dev --local" },
+    dependencies: { "slack-term": opts.slackTerm ?? `^${pkg.version}` },
+    devDependencies: { wrangler: WRANGLER_VERSION },
+    engines: { node: ">=22" },
+  };
+  return {
+    "package.json": `${JSON.stringify(packageJson, null, 2)}\n`,
+    "wrangler.jsonc": `// slack-term relay: Slack Events API -> doorbells for \`slack stream\`.
+// Secrets (not in this file): wrangler secret put SLACK_SIGNING_SECRET / RELAY_TOKEN / SLACK_TEAM_ID (optional)
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": ${JSON.stringify(name)},
+  "main": "src/index.ts",
+  "compatibility_date": "${COMPATIBILITY_DATE}",
+  "durable_objects": {
+    "bindings": [{ "name": "RELAY", "class_name": "Relay" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Relay"] }],
+  // Request bodies are message events from possibly customer-facing channels:
+  // keep Workers Logs off so nothing about them is persisted by the platform.
+  "observability": { "enabled": false }
+}
+`,
+    "src/index.ts": `// The relay lives in the slack-term package. Relay (the Durable Object class)
+// must be exported from this main module for the RELAY binding to find it.
+export { default, Relay } from "slack-term/worker";
+`,
+    ".gitignore": "node_modules/\n.wrangler/\n.dev.vars*\n.env*\n",
+    "README.md": readme(name),
+  };
+}
+
+/** The steps after `init`, shared by the README and the printed output.
+ *  `token` is only ever printed, never written to a file. */
+export function nextSteps(name: string, token?: string): string {
+  const tok = token ?? "<RELAY_TOKEN>";
+  return `1. Node >= 22 (wrangler 4 needs it), then install:
+     npm install
+2. Log in to Cloudflare:
+     npx wrangler login
+   or set CLOUDFLARE_API_TOKEN (Workers Scripts: Edit) and CLOUDFLARE_ACCOUNT_ID.
+3. Deploy, then set the secrets:
+     npx wrangler deploy
+     npx wrangler secret put SLACK_SIGNING_SECRET   # Slack app -> Basic Information -> Signing Secret
+     npx wrangler secret put RELAY_TOKEN            # paste: ${tok}
+     npx wrangler secret put SLACK_TEAM_ID          # optional: accept one workspace only (T...)
+4. In the Slack app -> Event Subscriptions: Enable Events, Request URL
+     https://${name}.<your-subdomain>.workers.dev/slack/events
+   and subscribe to bot events: message.channels, message.groups, message.im,
+   app_mention (and message.mpim if the bot has mpim:history). Save; reinstall if asked.
+5. Where \`slack stream\` runs:
+     export SLACK_RELAY_URL=https://${name}.<your-subdomain>.workers.dev
+     export SLACK_RELAY_TOKEN=${tok}
+6. Check it:
+     slack relay health        # or: curl -H "Authorization: Bearer $SLACK_RELAY_TOKEN" $SLACK_RELAY_URL/health
+     slack stream -e .         # stderr says: relay connected (websocket)
+`;
+}
+
+function readme(name: string): string {
+  return `# ${name}
+
+A [slack-term](https://github.com/snomiao/slack-term) relay: a Cloudflare Worker
+that turns Slack's Events API into a resumable doorbell stream for
+\`slack stream\`. The code is the \`slack-term/worker\` export; this folder only
+configures and deploys it. Created by \`slack relay init\`.
+
+## Set up
+
+${nextSteps(name)}
+\`RELAY_TOKEN\` is any long random string (\`openssl rand -hex 32\`); \`slack relay init\`
+printed one. Keep it out of this folder: anyone holding it can watch when and
+where messages are posted.
+
+## Update
+
+Bump \`slack-term\` in package.json, \`npm install\`, \`npx wrangler deploy\`.
+Storage survives redeploys; clients reconnect and resume.
+
+Details (endpoints, privacy, protocol): ${RELAY_DOCS_URL}
+`;
+}
+
+export type InitResult =
+  | { ok: true; dir: string; name: string; written: string[]; token: string }
+  | { ok: false; error: string; existing?: string[] };
+
+/** Write the scaffold into `dir`. Refuses to overwrite any existing file
+ *  unless `force`. Returns the generated RELAY_TOKEN for the caller to print. */
+export function initRelay(
+  dir: string,
+  opts: ScaffoldOptions & { force?: boolean } = {},
+  rand: (n: number) => Buffer = randomBytes,
+): InitResult {
+  const name = opts.name ?? workerNameFrom(dir);
+  if (!validWorkerName(name)) {
+    return { ok: false, error: `invalid worker name "${name}": use lowercase letters, digits and dashes (1-63 chars, no leading/trailing dash)` };
+  }
+  const files = relayFiles(name, opts.slackTerm !== undefined ? { slackTerm: opts.slackTerm } : {});
+  const root = resolve(dir);
+  const existing = Object.keys(files).filter((f) => existsSync(join(root, f)));
+  if (existing.length && !opts.force) {
+    return { ok: false, error: `refusing to overwrite existing files in ${root} (pass --force to replace them)`, existing };
+  }
+  for (const [rel, content] of Object.entries(files)) {
+    const p = join(root, rel);
+    mkdirSync(join(p, ".."), { recursive: true });
+    writeFileSync(p, content);
+  }
+  return { ok: true, dir: root, name, written: Object.keys(files), token: rand(32).toString("hex") };
+}
+
+/** What `slack relay init` prints on success. */
+export function initReport(r: Extract<InitResult, { ok: true }>, cwd: string = process.cwd()): string {
+  const rel = r.dir.startsWith(`${cwd}/`) ? r.dir.slice(cwd.length + 1) : r.dir;
+  return [
+    `Created ${r.dir} (worker "${r.name}"):`,
+    ...r.written.map((f) => `  ${f}`),
+    "",
+    `RELAY_TOKEN (generated now, not saved anywhere — copy it):`,
+    `  ${r.token}`,
+    "",
+    "Next steps:",
+    `0. cd ${rel}`,
+    nextSteps(r.name, r.token),
+  ].join("\n");
+}
+
+export type HealthResult = { code: 0 | 1 | 2; out: string };
+
+/** GET /health on the relay (read-only). 0 = ok, 1 = unhealthy/unreachable,
+ *  2 = not configured. */
+export async function relayHealth(
+  url: string | undefined,
+  token: string | undefined,
+  fetchImpl: typeof fetch = fetch,
+  timeoutMs = 10_000,
+): Promise<HealthResult> {
+  if (!url || !token) {
+    return { code: 2, out: "slack relay health: set SLACK_RELAY_URL and SLACK_RELAY_TOKEN (or pass --url / --token)" };
+  }
+  const target = `${url.replace(/\/+$/, "")}/health`;
+  try {
+    const res = await fetchImpl(target, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const body = await res.text();
+    if (res.status === 401) return { code: 1, out: `slack relay health: 401 unauthorized — SLACK_RELAY_TOKEN does not match the relay's RELAY_TOKEN secret` };
+    if (!res.ok) return { code: 1, out: `slack relay health: HTTP ${res.status} from ${target}${body ? `: ${body.slice(0, 200)}` : ""}` };
+    let json: { ok?: unknown };
+    try {
+      json = JSON.parse(body) as typeof json;
+    } catch {
+      return { code: 1, out: `slack relay health: not a slack-term relay (non-JSON reply from ${target})` };
+    }
+    return { code: json.ok === true ? 0 : 1, out: JSON.stringify(json, null, 2) };
+  } catch (e) {
+    return { code: 1, out: `slack relay health: cannot reach ${target}: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}

package/ts/stream.ts

@@ -643,7 +643,7 @@ export async function runStream(client: StreamClient, opts: StreamOpts): Promise
       `slack stream: WARNING: polling mode (${opts.pollReason ?? "no relay configured"}) — this is the fallback, ` +
       `not the intended setup: matches arrive up to ${Math.round(opts.intervalMs / 1000)}s late (replies under older ` +
       `parents up to ${Math.round(Math.max(opts.threadScanSec ?? 180, opts.intervalMs / 1000))}s) and every cycle spends ` +
-      `Slack API calls. For real time, deploy the relay and set SLACK_RELAY_URL + SLACK_RELAY_TOKEN: ${RELAY_DOCS}`,
+      `Slack API calls. For real time, set up the relay (slack relay init) and set SLACK_RELAY_URL + SLACK_RELAY_TOKEN: ${RELAY_DOCS}`,
     );
   }
   client = paced(client, opts.callsPerMin ?? 40, opts.signal);
@@ -733,7 +733,7 @@ export async function runStream(client: StreamClient, opts: StreamOpts): Promise
       if (bus.live === live) return;
       bus.live = live;
       _internals.err(live
-        ? `slack stream: relay connected — polling every ${Math.round(Math.max(opts.intervalMs, relay!.reconcileMs) / 1000)}s as a safety net`
+        ? `slack stream: relay connected${why ? ` (${why})` : ""} — polling every ${Math.round(Math.max(opts.intervalMs, relay!.reconcileMs) / 1000)}s as a safety net`
         : `slack stream: relay unavailable${why ? ` (${why})` : ""} — polling every ${Math.round(opts.intervalMs / 1000)}s`);
       ring();
     };
@@ -777,7 +777,7 @@ export async function runStream(client: StreamClient, opts: StreamOpts): Promise
                 for (const p of [...bus.queue, ...bus.retry, ...(bus.inflight ? [bus.inflight] : [])]) p.seq = Math.min(p.seq, h.seq);
               }
               after = { seq: h.seq, ...(h.epoch ? { epoch: h.epoch } : {}) };
-              setLive(true);
+              setLive(true, h.via);
             },
             bell: (seq, bell) => {
               if (paused) return;