privateer-agent 0.3.6 → 0.4.0

package/src/channels/run.ts

@@ -0,0 +1,383 @@
+// Headless entry for the messaging channels — `npm run channels` (or
+// `node --env-file=.env --import tsx src/channels/run.ts`). Boots the Pi stack the
+// same way the routines daemon does, then bridges any configured chat platform
+// (Telegram, Slack) to per-conversation agent sessions.
+//
+// AUTHORIZATION MODEL (per channel):
+//   - admins  — governed by the channel `posture`; the ONLY users whose yes/no
+//               resolves an approval prompt.
+//   - members — may chat, but every turn runs read-only (writes/bash denied) and
+//               they cannot answer approvals.
+//   (Legacy `allowFrom` is treated as `admins` for back-compat.)
+//
+// POSTURE (config + restart only — deliberately no in-chat toggle; a restart is the
+// fail-safe reset). Applies to ADMIN turns; members are always read-only:
+//   - readonly — deny every write/edit/bash/fetch
+//   - approve  — each risky action prompts an admin in-chat for yes/no  (default)
+//   - auto     — non-dangerous actions run unattended; dangerous shell + destructive
+//                actions still prompt
+//   `tools` is the hard tool CEILING an admin can reach (default: read-only).
+//
+// MAINTENANCE: sessions are in-memory, per conversation, and evicted after 30 min
+// idle or at a 500-session cap. A restart resets all live state to config (roles,
+// posture). Every prompt/approval is appended to ~/.privateer/channels-audit.log.
+// Tokens live in config.json in plaintext — protect that file's permissions.
+//
+// Config lives in ~/.privateer/config.json (the same file the daemon reads):
+//   {
+//     "defaultModel": "openrouter/openai/gpt-4o-mini",
+//     "channels": {
+//       "model":   "openrouter/openai/gpt-4o-mini", // optional shared override
+//       "tools":   ["read","grep","find","ls"],      // optional shared ceiling
+//       "posture": "approve",                         // optional shared default
+//       "cwd":     "/path/to/project",                // optional (else process.cwd())
+//       "telegram": { "botToken": "…", "admins": ["<tg-id>"], "members": ["<tg-id>"],
+//                     "posture": "approve", "tools": ["read","grep","find","ls","edit","write","bash"] },
+//       "slack":    { "appToken": "xapp-…", "botToken": "xoxb-…", "admins": ["<slack-id>"] },
+//       "discord":  { "botToken": "…", "admins": ["<discord-id>"], "intents": 37376 },
+//       "whatsapp": { "phoneNumberId": "…", "accessToken": "…", "verifyToken": "…",
+//                     "appSecret": "…?", "port": 8787, "admins": ["<phone-number>"] }
+//     }
+//   }
+// Each platform block is optional — only the configured ones start. Approvals are
+// text-reply based (universal across all five platforms); mapping them to native
+// buttons (Slack blocks / Discord components / Telegram inline keyboards) is a
+// per-adapter enhancement.
+
+import "../boot.ts"; // env + attestation dispatcher, before any Pi import
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// Read-only default toolset — same rationale as the routines daemon's SAFE_TOOLS:
+// a turn nobody is watching can't mutate the filesystem or shell out. Now that the
+// gate routes approvals into the chat (see below), a user can safely widen this per
+// channel via `channels.tools` — e.g. add "edit","write","bash" and each risky call
+// prompts in-chat for a yes/no.
+const SAFE_TOOLS = ["read", "grep", "find", "ls"];
+
+// A channel's posture governs how an ADMIN's risky actions are handled (members are
+// always capped to read-only — see effectivePosture). Config + restart only; there
+// is deliberately no in-chat toggle.
+//   readonly — deny every write/edit/bash/fetch (reads still run)
+//   approve  — each risky action prompts in-chat for a yes/no (default)
+//   auto     — non-dangerous actions run unattended; dangerous shell + destructive
+//              actions still prompt
+type Posture = "readonly" | "approve" | "auto";
+const POSTURES: Posture[] = ["readonly", "approve", "auto"];
+
+// Bound the live session map so a long-running daemon can't grow without limit or
+// hold stale context forever.
+const MAX_SESSIONS = 500;
+const SESSION_IDLE_MS = 30 * 60 * 1000; // evict a conversation unused for 30 min
+const SESSION_SWEEP_MS = 5 * 60 * 1000;
+
+// Per-turn context. AsyncLocalStorage carries it across the async tool-call hooks so
+// the SHARED gate knows which conversation to prompt and the EFFECTIVE posture for
+// this turn (which already folds in the triggering user's role), even with several
+// chats running concurrently.
+interface ApprovalContext {
+  bridge: { requestApproval(chatId: string, req: any, signal?: AbortSignal): Promise<"allow" | "deny"> };
+  chatId: string;
+  posture: Posture;
+}
+const approvalCtx = new AsyncLocalStorage<ApprovalContext>();
+
+function parseSpec(spec: string): { provider: string; modelId: string } {
+  const i = spec.indexOf(":");
+  const j = spec.indexOf("/");
+  const sep = i === -1 ? j : j === -1 ? i : Math.min(i, j);
+  if (sep <= 0) return { provider: spec, modelId: "" };
+  return { provider: spec.slice(0, sep), modelId: spec.slice(sep + 1) };
+}
+
+function log(msg: string): void {
+  process.stdout.write(`[${new Date().toISOString()}] ${msg}\n`);
+}
+
+function normalizePosture(v: unknown): Posture | undefined {
+  return typeof v === "string" && (POSTURES as string[]).includes(v) ? (v as Posture) : undefined;
+}
+
+async function main() {
+  const { readFileSync, appendFileSync } = await import("node:fs");
+  const { join } = await import("node:path");
+  const {
+    createAgentSessionServices,
+    createAgentSessionFromServices,
+    SessionManager,
+  } = await import("@earendil-works/pi-coding-agent");
+  const { createEngineEventAdapter } = await import("../bridge/engineAdapter.ts");
+  const { makePermissionGate } = await import("../ext/permissionGate.ts");
+  type GateController = import("../ext/permissionGate.ts").GateController;
+  const { makePiPrivacyExtension } = await import("pi-privacy");
+  const { makeAccountProvider } = await import("../providers/account.ts");
+  const { agentDir, configPath, globalDir } = await import("../config/paths.ts");
+  const { redactText, collectSecrets } = await import("../util/redact.ts");
+  const { MessagingBridge } = await import("./bridge.ts");
+  type TurnRunner = import("./bridge.ts").TurnRunner;
+  const { TelegramAdapter } = await import("./telegram.ts");
+  const { SlackAdapter } = await import("./slack.ts");
+  const { DiscordAdapter } = await import("./discord.ts");
+  const { WhatsAppAdapter } = await import("./whatsapp.ts");
+  const { writeChannelsStatus, HEARTBEAT_MS } = await import("./status.ts");
+  type ChannelAdapter = import("./types.ts").ChannelAdapter;
+
+  // ── config ──────────────────────────────────────────────────────────────────
+  let cfg: any = {};
+  try {
+    cfg = JSON.parse(readFileSync(configPath(), "utf8"));
+  } catch {
+    log(`no config at ${configPath()} — add a channels block (see run.ts header).`);
+    process.exit(1);
+  }
+  const ch = cfg.channels ?? {};
+  const defaultModel: string = ch.model ?? cfg.defaultModel ?? "openrouter/openai/gpt-4o-mini";
+  const defaultTools: string[] = Array.isArray(ch.tools) && ch.tools.length ? ch.tools : SAFE_TOOLS;
+  const defaultPosture: Posture = normalizePosture(ch.posture) ?? "approve";
+  const cwd: string = ch.cwd ?? process.cwd();
+  const secrets = collectSecrets(cfg.providers);
+  const redact = (t: string) => redactText(t, secrets);
+
+  // Append-only security audit log — every prompt, approval request/decision, and
+  // refused non-admin approval, one JSON object per line.
+  const auditPath = join(globalDir(), "channels-audit.log");
+  const onAudit = (e: any) => {
+    try {
+      appendFileSync(auditPath, JSON.stringify(e) + "\n");
+    } catch {
+      /* best effort — never let auditing break a turn */
+    }
+  };
+
+  // ── shared Pi session services (one registry/auth; sessions created per chat) ─
+  //
+  // The gate reads the EFFECTIVE posture for the current turn from the ALS store
+  // (which already folded in the triggering user's role): a member always resolves
+  // to "readonly". Mode "default" makes every write/edit/bash/fetch classify as
+  // "ask"; "plan" (readonly) hard-denies them. getRemote() is always true so asks
+  // route to the in-chat approver rather than a (non-existent) terminal. localAsk
+  // stays deny as a fail-closed backstop.
+  const posture = () => approvalCtx.getStore()?.posture;
+  const gate: GateController = {
+    getMode: () => (posture() === "readonly" ? "plan" : "default"),
+    setMode: () => {},
+    allowlist: [],
+    allowedOutsideRoots: [],
+    cwd,
+    confineToCwd: true,
+    getRemote: () => true,
+    getNoQuarter: () => posture() === "auto",
+    async localAsk() {
+      return "deny";
+    },
+    async remoteAsk(req, signal) {
+      const store = approvalCtx.getStore();
+      if (!store) return "deny"; // no chat context → fail closed
+      if (store.posture === "readonly") return "deny"; // read-only: deny, don't prompt
+      return store.bridge.requestApproval(store.chatId, req, signal);
+    },
+  };
+  const services = await createAgentSessionServices({
+    cwd,
+    agentDir: agentDir(),
+    resourceLoaderOptions: {
+      extensionFactories: [makePermissionGate(gate), makePiPrivacyExtension(), makeAccountProvider()] as any,
+    },
+  });
+
+  const modelCache = new Map<string, any>();
+  function resolveModel(spec: string): any {
+    let m = modelCache.get(spec);
+    if (m === undefined) {
+      const { provider, modelId } = parseSpec(spec);
+      m = (services.modelRegistry as any).find(provider, modelId) ?? null;
+      modelCache.set(spec, m);
+    }
+    return m;
+  }
+
+  // One persistent session per conversation, keyed "<platform>:<chatId>" so chat
+  // ids can't collide across platforms. A single subscription per session routes
+  // streamed text to whichever turn is running (safe: the bridge serializes turns
+  // per chat).
+  interface SessionEntry {
+    session: any;
+    holder: { onText: (t: string) => void; error?: string };
+    lastUsed: number;
+  }
+  const sessions = new Map<string, SessionEntry>();
+
+  async function sessionFor(key: string, model: any, tools: string[]): Promise<SessionEntry> {
+    let entry = sessions.get(key);
+    if (!entry) {
+      const { session } = await createAgentSessionFromServices({
+        services,
+        sessionManager: SessionManager.inMemory(cwd),
+        model,
+        tools,
+      } as any);
+      const adapter = createEngineEventAdapter();
+      const holder: SessionEntry["holder"] = { onText: () => {}, error: undefined };
+      session.subscribe((ev: any) => {
+        for (const ee of adapter.toEngineEvents(ev)) {
+          if (ee.type === "text") holder.onText(ee.text);
+          else if (ee.type === "error") holder.error = ee.error;
+        }
+      });
+      entry = { session, holder, lastUsed: Date.now() };
+      sessions.set(key, entry);
+      // Hard cap: evict the least-recently-used conversation if we're over budget.
+      if (sessions.size > MAX_SESSIONS) {
+        let oldestKey: string | undefined;
+        let oldest = Infinity;
+        for (const [k, e] of sessions) {
+          if (e.lastUsed < oldest) {
+            oldest = e.lastUsed;
+            oldestKey = k;
+          }
+        }
+        if (oldestKey && oldestKey !== key) sessions.delete(oldestKey);
+      }
+    }
+    entry.lastUsed = Date.now();
+    return entry;
+  }
+
+  // Idle sweep: drop conversations untouched for SESSION_IDLE_MS. A dropped chat's
+  // next message just starts a fresh session (memory reset), so this is safe — turns
+  // are serialized, so an in-flight turn keeps its session recently-used.
+  const sweep = setInterval(() => {
+    const cutoff = Date.now() - SESSION_IDLE_MS;
+    for (const [k, e] of sessions) if (e.lastUsed < cutoff) sessions.delete(k);
+  }, SESSION_SWEEP_MS);
+  sweep.unref?.();
+
+  // ── build a bridge per configured platform ───────────────────────────────────
+  const bridges: { stop(): void }[] = [];
+  // Platforms with a live bridge — written to the heartbeat file so the app's
+  // channels manager (running on the daemon's relay, a separate process) can show
+  // a live/offline badge without talking to this process.
+  const startedPlatforms: string[] = [];
+
+  async function startChannel(platform: string, adapter: ChannelAdapter, block: any) {
+    // Roles. Legacy `allowFrom` is treated as admins (its prior meaning: the sole
+    // fully-capable users). Members are chat-only + read-only and can't approve.
+    const admins = new Set<string>((block.admins ?? block.allowFrom ?? []).map(String));
+    const members = new Set<string>((block.members ?? []).map(String));
+    if (admins.size === 0 && members.size === 0) {
+      log(`${platform}: no admins/members configured — skipping (fail-closed).`);
+      return;
+    }
+
+    const modelSpec: string = block.model ?? defaultModel;
+    const model = resolveModel(modelSpec);
+    if (!model) {
+      log(`${platform}: model "${modelSpec}" not found — skipping. Check the spec / provider keys.`);
+      return;
+    }
+    // Per-channel tool ceiling + posture. The ceiling is what admins CAN reach; the
+    // gate caps members to read-only regardless.
+    const chTools: string[] = Array.isArray(block.tools) && block.tools.length ? block.tools : defaultTools;
+    const chPosture: Posture = normalizePosture(block.posture) ?? defaultPosture;
+
+    // The runner references its own bridge (for approval routing via ALS), so the
+    // bridge is declared first and assigned just below.
+    let bridge: InstanceType<typeof MessagingBridge>;
+    const runTurn: TurnRunner = async (chatId, text, onText, _signal, meta) => {
+      const { session, holder } = await sessionFor(`${platform}:${chatId}`, model, chTools);
+      holder.onText = onText;
+      holder.error = undefined;
+      // A member's turn is always read-only, whatever the channel posture.
+      const effectivePosture: Posture = meta.isAdmin ? chPosture : "readonly";
+      try {
+        await approvalCtx.run({ bridge, chatId, posture: effectivePosture }, () => session.prompt(text));
+      } catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+      } finally {
+        holder.onText = () => {};
+      }
+      return holder.error ? { ok: false, error: holder.error } : { ok: true };
+    };
+
+    bridge = new MessagingBridge({
+      adapter,
+      runTurn,
+      isAllowed: (m) => admins.has(m.userId) || members.has(m.userId),
+      isAdmin: (m) => admins.has(m.userId),
+      redact,
+      onLog: log,
+      onAudit: (e) => onAudit({ ...e, platform }),
+    });
+    await bridge.start();
+    bridges.push(bridge);
+    startedPlatforms.push(platform);
+    log(
+      `${platform} up — model ${modelSpec}, ceiling [${chTools.join(", ")}], posture ${chPosture}, ` +
+        `${admins.size} admin(s)/${members.size} member(s), cwd ${cwd}.`,
+    );
+  }
+
+  if (ch.telegram?.botToken) {
+    await startChannel(
+      "telegram",
+      new TelegramAdapter({ botToken: ch.telegram.botToken, onLog: log }),
+      ch.telegram,
+    );
+  }
+  if (ch.slack?.appToken && ch.slack?.botToken) {
+    await startChannel(
+      "slack",
+      new SlackAdapter({ appToken: ch.slack.appToken, botToken: ch.slack.botToken, onLog: log }),
+      ch.slack,
+    );
+  }
+  if (ch.discord?.botToken) {
+    await startChannel(
+      "discord",
+      new DiscordAdapter({ botToken: ch.discord.botToken, intents: ch.discord.intents, onLog: log }),
+      ch.discord,
+    );
+  }
+  if (ch.whatsapp?.phoneNumberId && ch.whatsapp?.accessToken && ch.whatsapp?.verifyToken) {
+    await startChannel(
+      "whatsapp",
+      new WhatsAppAdapter({
+        phoneNumberId: ch.whatsapp.phoneNumberId,
+        accessToken: ch.whatsapp.accessToken,
+        verifyToken: ch.whatsapp.verifyToken,
+        appSecret: ch.whatsapp.appSecret,
+        port: ch.whatsapp.port,
+        path: ch.whatsapp.path,
+        onLog: log,
+      }),
+      ch.whatsapp,
+    );
+  }
+
+  if (bridges.length === 0) {
+    log("no channels started — configure a channels.<platform> block in config.json.");
+    process.exit(1);
+  }
+
+  // Heartbeat: announce the live platforms now and refresh on a cadence so the app's
+  // channels manager can tell running from merely-configured. A stale/absent file
+  // reads as offline (see channels/status.ts).
+  writeChannelsStatus(startedPlatforms);
+  const heartbeat = setInterval(() => writeChannelsStatus(startedPlatforms), HEARTBEAT_MS);
+  heartbeat.unref?.();
+
+  const shutdown = () => {
+    log("shutting down");
+    clearInterval(sweep);
+    clearInterval(heartbeat);
+    writeChannelsStatus([]); // clear presence immediately, don't wait for staleness
+    for (const b of bridges) b.stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack ?? err}\n`);
+  process.exit(1);
+});

package/src/channels/slack.ts

@@ -0,0 +1,176 @@
+// Slack channel adapter — templated off the Telegram one against the same
+// ChannelAdapter interface. Uses Socket Mode (an outbound WebSocket), so like
+// Telegram long-poll it needs NO public inbound endpoint: it works from a laptop
+// behind NAT. Zero new dependencies — `ws` is already a dep (see relayClient.ts)
+// and the rest is the Slack Web API over fetch.
+//
+// Slack app setup (one-time):
+//   - Enable Socket Mode → generate an app-level token `xapp-…` (scope
+//     connections:write). That's `appToken`.
+//   - Bot token `xoxb-…` with scope `chat:write`. That's `botToken`.
+//   - Event Subscriptions → subscribe the bot to `message.im` (DMs). Then DM the bot.
+//
+// Everything above the adapter (allowlist, serialization, redaction, chunking) is
+// MessagingBridge, reused verbatim.
+
+import WebSocket from "ws";
+import type { ChannelAdapter, InboundMessage } from "./types.ts";
+
+const API = "https://slack.com/api";
+const RECONNECT_MS = 3000;
+const HTTP_TIMEOUT_MS = 15_000;
+
+// The Events-API payload we read (Socket Mode wraps this in an envelope).
+interface SlackEventPayload {
+  event?: {
+    type?: string;
+    subtype?: string;
+    bot_id?: string;
+    user?: string;
+    text?: string;
+    channel?: string;
+  };
+}
+
+// Pure mapping: an Events-API payload → normalized InboundMessage, or null for
+// anything we shouldn't treat as a user prompt. Critically filters out our own
+// bot's messages (`bot_id`) and non-plain events (`subtype`: edits, joins, etc.)
+// so the agent never talks to itself. Extracted so it's unit-testable.
+export function messageFromSlackEvent(payload: SlackEventPayload): InboundMessage | null {
+  const ev = payload.event;
+  if (!ev || ev.type !== "message") return null;
+  if (ev.bot_id || ev.subtype) return null; // bot echoes / edits / system messages
+  if (typeof ev.text !== "string" || !ev.channel || !ev.user) return null;
+  return { chatId: ev.channel, userId: ev.user, text: ev.text };
+}
+
+export interface SlackOptions {
+  appToken: string; // xapp-… (Socket Mode connection)
+  botToken: string; // xoxb-… (chat:write)
+  fetchImpl?: typeof fetch;
+  onLog?: (msg: string) => void;
+}
+
+export class SlackAdapter implements ChannelAdapter {
+  readonly name = "slack";
+  private readonly appToken: string;
+  private readonly botToken: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly onLog?: (msg: string) => void;
+  private ws?: WebSocket;
+  private running = false;
+  private reconnectTimer?: ReturnType<typeof setTimeout>;
+  private onMessage?: (m: InboundMessage) => void;
+
+  constructor(opts: SlackOptions) {
+    this.appToken = opts.appToken;
+    this.botToken = opts.botToken;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.onLog = opts.onLog;
+  }
+
+  async start(onMessage: (m: InboundMessage) => void): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+    this.onMessage = onMessage;
+    await this.connect();
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    try {
+      this.ws?.close();
+    } catch {
+      /* ignore */
+    }
+    this.ws = undefined;
+  }
+
+  async sendText(chatId: string, text: string): Promise<void> {
+    if (!text) return;
+    const res = await this.web("chat.postMessage", { channel: chatId, text });
+    const data = (await res.json().catch(() => ({}))) as { ok?: boolean; error?: string };
+    if (!data.ok) this.log(`chat.postMessage failed: ${data.error ?? "unknown"}`);
+  }
+
+  // Slack has no bot "typing" over the Web API, so sendTyping is intentionally
+  // absent — the bridge guards `sendTyping?.()`.
+
+  private log(msg: string): void {
+    this.onLog?.(`slack: ${msg}`);
+  }
+
+  // Mint a fresh Socket Mode WSS URL and connect. Slack rotates the URL, sending a
+  // `disconnect` frame before it does; we just reconnect (re-minting) each time.
+  private async connect(): Promise<void> {
+    if (!this.running) return;
+    let url: string;
+    try {
+      const res = await this.web("apps.connections.open", {}, this.appToken);
+      const data = (await res.json()) as { ok?: boolean; url?: string; error?: string };
+      if (!data.ok || !data.url) throw new Error(data.error ?? "no url");
+      url = data.url;
+    } catch (e) {
+      this.log(`apps.connections.open failed: ${e instanceof Error ? e.message : String(e)} — retrying`);
+      return this.scheduleReconnect();
+    }
+
+    const ws = new WebSocket(url);
+    this.ws = ws;
+    ws.on("message", (raw) => this.handleFrame(ws, raw));
+    ws.on("close", () => {
+      if (this.ws === ws) this.ws = undefined;
+      if (this.running) this.scheduleReconnect();
+    });
+    ws.on("error", (err: Error) => this.log(`ws error: ${err?.message ?? err}`));
+  }
+
+  private scheduleReconnect(): void {
+    if (!this.running || this.reconnectTimer) return;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      void this.connect();
+    }, RECONNECT_MS);
+  }
+
+  private handleFrame(ws: WebSocket, raw: WebSocket.RawData): void {
+    let frame: { type?: string; envelope_id?: string; payload?: SlackEventPayload };
+    try {
+      frame = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    // Ack EVERY envelope immediately (Slack retries if not acked within 3s), before
+    // doing any work — onMessage only queues an async turn.
+    if (frame.envelope_id) {
+      try {
+        ws.send(JSON.stringify({ envelope_id: frame.envelope_id }));
+      } catch {
+        /* socket dying */
+      }
+    }
+    if (frame.type === "disconnect") {
+      // URL refresh / server drain — drop this socket; `close` reconnects.
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+      return;
+    }
+    if (frame.type === "events_api" && frame.payload) {
+      const m = messageFromSlackEvent(frame.payload);
+      if (m) this.onMessage?.(m);
+    }
+  }
+
+  private async web(method: string, body: Record<string, unknown>, token = this.botToken): Promise<Response> {
+    return this.fetchImpl(`${API}/${method}`, {
+      method: "POST",
+      headers: { "content-type": "application/json; charset=utf-8", authorization: `Bearer ${token}` },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    });
+  }
+}

package/src/channels/status.ts

@@ -0,0 +1,54 @@
+// Channels daemon heartbeat — the one bit of shared state between the channels
+// daemon (channels/run.ts, the WRITER) and the always-on management relay
+// (daemon/index.ts → channelsControl, the READER).
+//
+// The two run as SEPARATE processes, so the manager can't ask the channels
+// daemon directly whether it's live. Instead the channels daemon writes a small
+// heartbeat file with the platforms it's currently serving; the reader treats a
+// FRESH heartbeat as "running" and a stale/absent one as "not running". This is
+// best-effort presence, never a dependency: a missing file just means the app
+// shows the platform as configured-but-offline.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "../config/paths.ts";
+
+// Heartbeat cadence + freshness window. The channels daemon rewrites the file
+// every HEARTBEAT_MS; a heartbeat older than STALE_MS is treated as dead (the
+// process exited without clearing it, or wedged).
+export const HEARTBEAT_MS = 30_000;
+const STALE_MS = 90_000; // 3 missed beats
+
+interface ChannelsStatus {
+  pid: number;
+  at: string; // ISO timestamp of the last heartbeat
+  platforms: string[]; // platforms with a live bridge this beat
+}
+
+function statusPath(): string {
+  return join(globalDir(), "channels-status.json");
+}
+
+// WRITER: record which platforms have a live bridge right now. Called on start
+// and on each heartbeat tick. Best-effort — a failed write never breaks a turn.
+export function writeChannelsStatus(platforms: string[]): void {
+  try {
+    const status: ChannelsStatus = { pid: process.pid, at: new Date().toISOString(), platforms };
+    writeFileSync(statusPath(), JSON.stringify(status));
+  } catch {
+    /* best effort */
+  }
+}
+
+// READER: the set of platforms the channels daemon is currently serving, or an
+// empty set when the daemon is down / the heartbeat is stale. Never throws.
+export function readRunningPlatforms(): Set<string> {
+  try {
+    const status = JSON.parse(readFileSync(statusPath(), "utf8")) as ChannelsStatus;
+    const age = Date.now() - Date.parse(status.at);
+    if (!Number.isFinite(age) || age > STALE_MS) return new Set();
+    return new Set(Array.isArray(status.platforms) ? status.platforms.map(String) : []);
+  } catch {
+    return new Set();
+  }
+}