slack-term 1.47.0 → 1.49.0

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/scope.ts

@@ -0,0 +1,472 @@
+// `.slack-term/` — per-directory state, found like `.git`: the nearest one
+// walking up from the cwd is the scope, so each lane's tree (or repo) owns its
+// own aliases and settings without a pid, an env var or a daemon. No
+// `.slack-term/` anywhere up the tree falls back to ~/.config/slack-term/.
+//
+//   .slack-term/
+//     README.md            what this is (written on init)
+//     .gitignore           "*" — nothing in here is ever committed
+//     settings.yml         written by people: prefix, channel, as_bot, subscriptions
+//     settings.local.yml   written by `slack alias`; overrides settings.yml
+//     inbox/ archived/     incoming messages, one file each; handled ones move to archived/
+//     outbox/ sent/        outgoing messages, one file each; sent ones move to sent/
+//
+// Every write is tmp + rename (a reader never sees half a file), and the
+// read-modify-write of settings.local.yml holds a lock file, so two `slack
+// alias set` at once cannot drop each other's entry.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+export const SCOPE_DIR = ".slack-term";
+export const SCOPE_SUBDIRS = ["inbox", "archived", "outbox", "sent"] as const;
+
+export type Scope = { dir: string; global: boolean };
+
+/** The global fallback: ~/.config/slack-term (SLACK_TERM_HOME overrides, for tests). */
+export function globalScopeDir(): string {
+  return process.env.SLACK_TERM_HOME ?? join(homedir(), ".config", "slack-term");
+}
+
+/** The nearest `.slack-term/` at or above `cwd`, else the global one. */
+export function findScope(cwd = process.cwd()): Scope {
+  let d = resolve(cwd);
+  for (;;) {
+    const c = join(d, SCOPE_DIR);
+    try {
+      if (statSync(c).isDirectory()) return { dir: c, global: false };
+    } catch { /* not here */ }
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return { dir: globalScopeDir(), global: true };
+}
+
+const README = `# .slack-term/
+
+State for [slack-term](https://github.com/snomiao/slack-term) in this directory.
+\`slack\` uses the nearest \`.slack-term/\` walking up from where it runs (like
+\`.git\`), so everything below this directory shares it. Without one it uses
+~/.config/slack-term/.
+
+Nothing here is committed: \`.gitignore\` holds \`*\`.
+
+| Path | What |
+|---|---|
+| \`settings.yml\` | yours to edit: \`prefix\` (put in front of every \`slack reply\`, e.g. \`"[design]"\`), \`channel\` (default), \`as_bot\`, \`subscriptions\` |
+| \`settings.local.yml\` | written by \`slack alias set/unset\`; same keys, wins over \`settings.yml\` |
+| \`inbox/\` → \`archived/\` | one file per incoming message (\`slack stream --inbox\`): who, where, the text with secrets redacted, a files count, the permalink. Handled = moved to \`archived/\`, by \`slack done\` or by a sent outbox reply with \`in_reply_to\` |
+| \`outbox/\` → \`sent/\` | one file per queued reply (\`slack outbox add\`, redacted); \`slack outbox flush\` sends them and moves each to \`sent/\` with its ts and permalink. A failure stays, with \`error\` and \`attempts\` |
+
+\`restrict_to_subscriptions\`, \`auto_subscribe\` and \`nudge_after_min\` count only in
+\`settings.yml\`. With \`restrict_to_subscriptions: true\`, only \`settings.yml\`'s
+subscriptions count, \`slack alias set\` refuses (the owner uses \`--shared\`), and
+\`reply\` / \`outbox flush\` refuse any other thread.
+
+\`subscriptions\` maps an alias to a place:
+
+    subscriptions:
+      board:
+        channel: C00000001
+        thread_ts: "1700000000.000100"
+
+## Commands
+
+    slack alias ls                         # the aliases here
+    slack alias set <name> <permalink>     # name a thread (a reply's permalink names its root)
+    slack alias unset <name>
+    slack read <name>                      # read the thread
+    slack reply <name> '<text>'            # reply in it, with the prefix, behind the --code gate
+    slack reply --to <permalink> '<text>'  # reply in the thread where that message is
+    slack reply <name> --to <permalink> …  # refused when that message is in another thread
+    slack inbox ls | listen | nudge        # what was routed here
+    slack done <file|ts>                   # handled without a reply
+    slack outbox add <name> '<text>' --in-reply-to <ts>
+    slack outbox flush                     # send the queue (one --code for the batch)
+    slack alias who <channel> <ts>         # which dirs subscribe a thread
+`;
+
+const SETTINGS = `# slack-term settings for this directory. settings.local.yml (written by
+# \`slack alias\`) has the same keys and wins over this file.
+#
+# prefix: "[lane]"      # put in front of every \`slack reply\`; never doubled
+# channel: C00000001    # default channel
+# as_bot: false         # reply as the bot (SLACK_BOT_TOKEN)
+# subscriptions:        # alias -> place (\`slack alias set\` writes settings.local.yml)
+#   board:
+#     channel: C00000001
+#     thread_ts: "1700000000.000100"
+#
+# Only here, never in settings.local.yml:
+# restrict_to_subscriptions: true  # the subscriptions above are the whole allowlist,
+#                                  # and prefix / as_bot / channel come from here only
+# owner: ~/ws/x/tree/shr           # with restrict: --shared writes run only from under it
+# auto_subscribe: [D00000001]      # new top-level messages there are subscribed here
+# nudge_after_min: 30              # \`slack inbox nudge\` reports what waits longer
+`;
+
+export type Subscription = { channel: string; thread_ts?: string; added?: string; note?: string };
+export type Settings = {
+  prefix?: string; channel?: string; as_bot?: boolean; subscriptions?: Record<string, Subscription>;
+  /** settings.yml only: `subscriptions` there are the whole allowlist —
+   *  settings.local.yml can neither add one nor switch this off, and `reply`
+   *  refuses a thread that is not in it. */
+  restrict_to_subscriptions?: boolean;
+  /** settings.yml only: channels whose NEW top-level messages are subscribed
+   *  here automatically (as `t-<ts>`), so a fresh DM thread has an owner. */
+  auto_subscribe?: string[];
+  /** Minutes an inbox entry may wait before `slack inbox nudge` reports it. */
+  nudge_after_min?: number;
+  /** settings.yml only: the directory whose lane owns this allowlist (e.g. the
+   *  coordinator's tree). In a restricted scope, `--shared` writes are refused
+   *  unless they run from under it — every lane is the same uid, so the CLI is
+   *  the only thing that can tell them apart. */
+  owner?: string;
+};
+
+/** Create (or complete) `<parent>/.slack-term/`. Idempotent: existing files are kept. */
+export function initScope(parent: string, settings: Omit<Settings, "subscriptions"> = {}): { dir: string; created: string[] } {
+  const dir = join(resolve(parent), SCOPE_DIR);
+  const created: string[] = [];
+  mkdirSync(dir, { recursive: true });
+  for (const sub of SCOPE_SUBDIRS) {
+    const d = join(dir, sub);
+    if (!existsSync(d)) { mkdirSync(d, { recursive: true }); created.push(`${sub}/`); }
+  }
+  const put = (name: string, body: string): void => {
+    const p = join(dir, name);
+    if (existsSync(p)) return;
+    atomicWrite(p, body);
+    created.push(name);
+  };
+  put(".gitignore", "*\n");
+  put("README.md", README);
+  const given = Object.fromEntries(Object.entries(settings).filter(([, v]) => v !== undefined));
+  put("settings.yml", SETTINGS + (Object.keys(given).length ? "\n" + Bun.YAML.stringify(given, null, 2) + "\n" : ""));
+  if (dir !== globalScopeDir()) registerScope(dir);
+  return { dir, created };
+}
+
+export function atomicWrite(path: string, body: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, body, { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/** Hold `<path>.lock` (O_EXCL) around `fn`. A lock older than `staleMs` is a
+ *  crashed writer's and is taken over. */
+export function withFileLock<T>(path: string, fn: () => T, staleMs = 10_000, waitMs = 5_000): T {
+  const lock = `${path}.lock`;
+  mkdirSync(dirname(lock), { recursive: true });
+  const until = Date.now() + waitMs;
+  for (;;) {
+    try {
+      closeSync(openSync(lock, "wx"));
+      break;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > staleMs) { unlinkSync(lock); continue; }
+      } catch { continue; }
+      if (Date.now() > until) throw new Error(`${lock} is held by another writer`);
+      Bun.sleepSync(25);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try { unlinkSync(lock); } catch { /* already gone */ }
+  }
+}
+
+function asSubscription(v: unknown): Subscription | undefined {
+  if (!v || typeof v !== "object") return undefined;
+  const o = v as Record<string, unknown>;
+  if (typeof o.channel !== "string" || !o.channel) return undefined;
+  const s: Subscription = { channel: o.channel };
+  // A ts written unquoted parses as a number and loses its trailing zeros.
+  if (typeof o.thread_ts === "string" && /^\d{10}\.\d{6}$/.test(o.thread_ts)) s.thread_ts = o.thread_ts;
+  if (typeof o.added === "string") s.added = o.added;
+  if (typeof o.note === "string") s.note = o.note;
+  return s;
+}
+
+/** One settings file, validated; unknown keys and malformed entries are dropped. */
+export function readSettingsFile(path: string): Settings {
+  let raw: unknown;
+  try {
+    raw = Bun.YAML.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw new Error(`${path}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!raw || typeof raw !== "object") return {};
+  const o = raw as Record<string, unknown>;
+  const s: Settings = {};
+  if (typeof o.prefix === "string" && o.prefix.trim()) s.prefix = o.prefix.trim();
+  // `prefix: [lane]` unquoted is a YAML list: take the one-element form as meant.
+  else if (Array.isArray(o.prefix) && o.prefix.length === 1 && typeof o.prefix[0] === "string") s.prefix = `[${o.prefix[0]}]`;
+  if (typeof o.channel === "string" && o.channel) s.channel = o.channel;
+  if (typeof o.as_bot === "boolean") s.as_bot = o.as_bot;
+  if (o.restrict_to_subscriptions === true) s.restrict_to_subscriptions = true;
+  if (Array.isArray(o.auto_subscribe)) s.auto_subscribe = o.auto_subscribe.filter((c): c is string => typeof c === "string");
+  if (typeof o.nudge_after_min === "number" && o.nudge_after_min > 0) s.nudge_after_min = o.nudge_after_min;
+  if (typeof o.owner === "string" && o.owner) s.owner = o.owner;
+  if (o.subscriptions && typeof o.subscriptions === "object") {
+    const subs: Record<string, Subscription> = {};
+    for (const [k, v] of Object.entries(o.subscriptions as Record<string, unknown>)) {
+      const sub = asSubscription(v);
+      if (sub && validAliasName(k)) subs[k] = sub;
+    }
+    s.subscriptions = subs;
+  }
+  return s;
+}
+
+/** settings.yml with settings.local.yml over it (subscriptions merge by name). */
+export function readSettings(scope: Scope): Settings {
+  const base = readSettingsFile(join(scope.dir, "settings.yml"));
+  const local = readSettingsFile(join(scope.dir, "settings.local.yml"));
+  // What only settings.yml may say.
+  delete local.restrict_to_subscriptions;
+  delete local.auto_subscribe;
+  delete local.owner;
+  if (base.restrict_to_subscriptions) {
+    // Who the lane posts as is the owner's call too: a local prefix `[shr]`
+    // would let any lane speak as another.
+    delete local.subscriptions;
+    delete local.prefix;
+    delete local.as_bot;
+    delete local.channel;
+  }
+  const subs = { ...base.subscriptions, ...local.subscriptions };
+  const out: Settings = { ...base, ...local };
+  if (Object.keys(subs).length) out.subscriptions = subs;
+  else delete out.subscriptions;
+  return out;
+}
+
+// --- aliases ---
+
+export type Alias = Subscription & { name: string; scope: Scope; file: "settings.yml" | "settings.local.yml" };
+
+const ALIAS_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+/** Lowercase letters, digits, `.` `_` `-`; never a bare ts or a Slack id. */
+export function validAliasName(name: string): boolean {
+  return ALIAS_RE.test(name) && !/^\d{10}\.\d{6}$/.test(name);
+}
+
+export function listAliases(scope: Scope): Alias[] {
+  const baseFile = readSettingsFile(join(scope.dir, "settings.yml"));
+  const base = baseFile.subscriptions ?? {};
+  const local = baseFile.restrict_to_subscriptions ? {} : readSettingsFile(join(scope.dir, "settings.local.yml")).subscriptions ?? {};
+  const out: Alias[] = [];
+  for (const [name, s] of Object.entries(base)) if (!local[name]) out.push({ ...s, name, scope, file: "settings.yml" });
+  for (const [name, s] of Object.entries(local)) out.push({ ...s, name, scope, file: "settings.local.yml" });
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** A bare alias name, in the nearest scope, then the global one. */
+export function lookupAlias(name: string, cwd = process.cwd()): Alias | undefined {
+  if (!validAliasName(name)) return undefined;
+  const near = findScope(cwd);
+  const scopes = near.global ? [near] : [near, { dir: globalScopeDir(), global: true }];
+  for (const s of scopes) {
+    const a = listAliases(s).find((x) => x.name === name);
+    if (a) return a;
+  }
+  return undefined;
+}
+
+const LOCAL_HEADER = "# Written by `slack alias set/unset`; wins over settings.yml. Safe to edit by hand.\n";
+
+/** The comment block a settings file starts with: kept when the file is rewritten. */
+function leadingComments(path: string): string {
+  try {
+    const lines = readFileSync(path, "utf8").split("\n");
+    const head: string[] = [];
+    for (const l of lines) { if (l.startsWith("#") || (!l.trim() && head.length)) head.push(l); else break; }
+    return head.length ? head.join("\n").replace(/\n*$/, "\n") : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Read-modify-write one settings file under its lock. `shared` = settings.yml
+ *  (the allowlist owner's file: the relay or the coordinator, never the lane). */
+function updateSettings(scope: Scope, shared: boolean, fn: (s: Record<string, unknown>) => void): void {
+  const path = join(scope.dir, shared ? "settings.yml" : "settings.local.yml");
+  withFileLock(path, () => {
+    const header = shared ? leadingComments(path) : LOCAL_HEADER;
+    let raw: Record<string, unknown> = {};
+    try {
+      const v = Bun.YAML.parse(readFileSync(path, "utf8"));
+      if (v && typeof v === "object" && !Array.isArray(v)) raw = v as Record<string, unknown>;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw new Error(`${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    fn(raw);
+    atomicWrite(path, header + Bun.YAML.stringify(raw, null, 2) + "\n");
+  });
+}
+
+/** Is this scope's allowlist locked to settings.yml? */
+export function isRestricted(scope: Scope): boolean {
+  return readSettingsFile(join(scope.dir, "settings.yml")).restrict_to_subscriptions === true;
+}
+
+/** May the process at `cwd` write `scope`'s settings.yml? Always when the
+ *  scope is not restricted; otherwise only from under its `owner` dir (and
+ *  never when no owner is named). */
+export function sharedWriteRefusal(scope: Scope, cwd = process.cwd()): string | undefined {
+  if (!isRestricted(scope)) return undefined;
+  const owner = readSettingsFile(join(scope.dir, "settings.yml")).owner;
+  if (!owner) return `${scope.dir} is restricted and names no \`owner\` in settings.yml: nobody may write it with --shared (edit the file)`;
+  const real = (p: string): string => { try { return realpathSync(resolve(p)); } catch { return resolve(p); } };
+  const o = real(owner.replace(/^~(?=\/|$)/, homedir()));
+  const c = real(cwd);
+  if (c === o || c.startsWith(o.endsWith("/") ? o : o + "/")) return undefined;
+  return `${scope.dir} is owned by ${owner}: --shared writes run only from under that directory`;
+}
+
+export type SetAliasOpts = {
+  /** Write settings.yml instead of settings.local.yml. */
+  shared?: boolean;
+  /** The owner's own rule (auto_subscribe) writing: skips the owner/cwd check. */
+  asOwner?: boolean;
+  cwd?: string;
+};
+
+/** Add or replace an alias — in settings.local.yml, or with `shared` in
+ *  settings.yml — and return the one it replaced. A restricted scope refuses
+ *  the local write (its allowlist is not the lane's to extend), and a shared
+ *  write from outside its owner dir. */
+export function setAlias(scope: Scope, name: string, sub: Subscription, opts: SetAliasOpts | boolean = {}): Subscription | undefined {
+  const o: SetAliasOpts = typeof opts === "boolean" ? { shared: opts } : opts;
+  const shared = o.shared === true;
+  if (!validAliasName(name)) throw new Error(`invalid alias name "${name}" (a-z 0-9 . _ -, at most 64, not a bare ts)`);
+  if (!shared && isRestricted(scope)) throw new RestrictedError(scope);
+  if (shared && !o.asOwner) {
+    const why = sharedWriteRefusal(scope, o.cwd);
+    if (why) throw new RestrictedError(scope, why);
+  }
+  const before = listAliases(scope).find((a) => a.name === name);
+  updateSettings(scope, shared, (raw) => {
+    const subs = (raw.subscriptions && typeof raw.subscriptions === "object" ? raw.subscriptions : {}) as Record<string, unknown>;
+    subs[name] = { channel: sub.channel, ...(sub.thread_ts ? { thread_ts: sub.thread_ts } : {}), added: sub.added ?? new Date().toISOString(), ...(sub.note ? { note: sub.note } : {}) };
+    raw.subscriptions = subs;
+  });
+  return before;
+}
+
+/** Remove an alias from settings.local.yml. One defined in settings.yml is
+ *  refused: that file belongs to whoever wrote it. */
+export function unsetAlias(scope: Scope, name: string, shared = false, cwd?: string): "removed" | "absent" | "in-settings.yml" {
+  const a = listAliases(scope).find((x) => x.name === name);
+  if (!a) return "absent";
+  if (a.file === "settings.yml" && !shared) return "in-settings.yml";
+  if (a.file === "settings.yml") {
+    const why = sharedWriteRefusal(scope, cwd);
+    if (why) throw new RestrictedError(scope, why);
+  }
+  updateSettings(scope, a.file === "settings.yml", (raw) => {
+    const subs = raw.subscriptions as Record<string, unknown> | undefined;
+    if (subs) delete subs[name];
+    if (subs && !Object.keys(subs).length) delete raw.subscriptions;
+  });
+  return "removed";
+}
+
+export class RestrictedError extends Error {
+  constructor(scope: Scope, why?: string) {
+    super(why ?? `${scope.dir} is restricted (restrict_to_subscriptions in settings.yml): only its owner adds subscriptions, with \`slack alias set --shared\` run from the owner's directory`);
+  }
+}
+
+// --- the registry: every .slack-term/ on this machine, for the relay fan-out ---
+
+function registryPath(): string {
+  return join(globalScopeDir(), "scopes");
+}
+
+/** Remember `dir` (a .slack-term/ path) so a stream can deliver into it. */
+export function registerScope(dir: string): void {
+  const p = registryPath();
+  withFileLock(p, () => {
+    const have = registeredDirs();
+    if (have.includes(dir)) return;
+    atomicWrite(p, [...have, dir].join("\n") + "\n");
+  });
+}
+
+function registeredDirs(): string[] {
+  try {
+    return readFileSync(registryPath(), "utf8").split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+  } catch {
+    return [];
+  }
+}
+
+/** Registered scopes that still exist, plus the global one. */
+export function registeredScopes(): Scope[] {
+  const out: Scope[] = [];
+  for (const d of registeredDirs()) {
+    try { if (statSync(d).isDirectory()) out.push({ dir: d, global: false }); } catch { /* moved or removed */ }
+  }
+  const g = globalScopeDir();
+  // The global dir always exists once anything registered; it is a scope only
+  // when it has settings of its own.
+  const hasSettings = existsSync(join(g, "settings.yml")) || existsSync(join(g, "settings.local.yml"));
+  if (hasSettings && !out.some((s) => s.dir === g)) out.push({ dir: g, global: true });
+  return out;
+}
+
+/** Which scopes subscribe a message: a thread subscription matches its thread
+ *  (the message's thread_ts, or its own ts for a root); a channel-only one
+ *  matches everything in the channel. */
+export function whoSubscribes(channel: string, threadOrTs: string, scopes = registeredScopes()): Alias[] {
+  const out: Alias[] = [];
+  for (const s of scopes) {
+    for (const a of listAliases(s)) {
+      if (a.channel === channel && (a.thread_ts === undefined || a.thread_ts === threadOrTs)) out.push(a);
+    }
+  }
+  return out;
+}
+
+// --- reply text ---
+
+/** Put `prefix` in front of `text`, never twice: a caller that already wrote
+ *  `[lane] ` (or `[lane@machine] `) keeps one (owner request 11-02:
+ *  "[shr] [shr]"). Only the exact lane is stripped — `[lanex]` or another
+ *  lane's tag is the caller's text. Returns "" when nothing is left. */
+export function applyPrefix(text: string, prefix: string | undefined): string {
+  const p = prefix?.trim();
+  if (!p) return text;
+  const m = /^\[([^\]@\s]+)\]$/.exec(p);
+  let body = text;
+  if (m) {
+    const lane = m[1]!.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    body = text.replace(new RegExp(`^\\s*\\[${lane}(?:@[a-z0-9-]{1,16})?\\][ \\t]*`), "");
+  } else if (text.trimStart().startsWith(p)) {
+    body = text.trimStart().slice(p.length).replace(/^[ \t]+/, "");
+  }
+  return body.trim() ? `${p} ${body}` : "";
+}
+
+/** Where a message sits: its channel and its thread root (its own ts at top level). */
+export type MessagePlace = { channel: string; ts: string; root: string };
+
+/** Why an explicit destination is not where the answered message lives (the
+ *  11-02 "replied in the wrong thread"), or undefined when it is. */
+export function threadMismatch(dest: { channel: string; threadTs?: string }, answered: MessagePlace): string | undefined {
+  if (dest.channel === answered.channel && dest.threadTs === answered.root) return undefined;
+  const where = (c: string, t?: string): string => (t ? `${c} thread ${t}` : `${c} (top level)`);
+  return `the message you are answering (${answered.ts}) is in ${where(answered.channel, answered.root)}, ` +
+    `but the destination is ${where(dest.channel, dest.threadTs)}.\n` +
+    `  Drop the destination to reply where the message is:  slack reply --to <permalink> '…'\n` +
+    `  Or pass --any-thread if the other thread is really meant.`;
+}