opensquid 0.5.395

package/dist/chat/daemon/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src.legacy/chat/daemon/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkD1F;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,KAAK,CAAC,CAE1D"}

package/dist/chat/daemon/cli.js

@@ -0,0 +1,71 @@
+/**
+ * Chat-daemon CLI dispatch (v0.7.1 Phase A).
+ *
+ * Two entry shapes:
+ *   `opensquid chat-daemon {start|stop|status}` — user-facing
+ *   `opensquid chat-daemon-worker`              — internal, never type
+ *
+ * `start` spawns the worker as a detached child and exits. The worker
+ * subcommand IS the long-running daemon — never invoke it manually
+ * unless you want to inspect logs in the foreground.
+ */
+import { runDaemonWorker } from "./worker.js";
+import { startDaemon, status, stopDaemon } from "./lifecycle.js";
+export async function runChatDaemonCli(subcommand, argv) {
+    switch (subcommand) {
+        case "start": {
+            const res = await startDaemon();
+            if (res.already_running) {
+                process.stdout.write(`[chat-daemon] already running (pid ${res.pid})\n`);
+            }
+            else {
+                process.stdout.write(`[chat-daemon] started (pid ${res.pid})\n`);
+            }
+            return 0;
+        }
+        case "stop": {
+            const res = await stopDaemon();
+            if (res.stopped) {
+                process.stdout.write(`[chat-daemon] stopped (pid ${res.pid})\n`);
+            }
+            else {
+                process.stdout.write(`[chat-daemon] not running\n`);
+            }
+            return 0;
+        }
+        case "status": {
+            const s = await status();
+            if (s.running) {
+                const upMin = s.uptime_ms !== null ? (s.uptime_ms / 60000).toFixed(1) : "?";
+                process.stdout.write(`[chat-daemon] running (pid ${s.pid}, up ${upMin}m)\n`);
+                return 0;
+            }
+            if (s.stale_pid !== undefined) {
+                process.stdout.write(`[chat-daemon] not running (stale pidfile points at ${s.stale_pid})\n`);
+                return 1;
+            }
+            process.stdout.write(`[chat-daemon] not running\n`);
+            return 1;
+        }
+        case "restart": {
+            const wasRunning = await status();
+            if (wasRunning.running)
+                await stopDaemon();
+            const res = await startDaemon();
+            process.stdout.write(`[chat-daemon] restarted (pid ${res.pid})\n`);
+            return 0;
+        }
+        default:
+            process.stderr.write(`[chat-daemon] usage: opensquid chat-daemon {start|stop|status|restart}\n` +
+                `  argv received: ${JSON.stringify([subcommand, ...argv])}\n`);
+            return 1;
+    }
+}
+/**
+ * Internal worker entrypoint — not for direct user invocation.
+ * Called by the detached child spawned by lifecycle.startDaemon().
+ */
+export async function runChatDaemonWorker() {
+    return runDaemonWorker();
+}
+//# sourceMappingURL=cli.js.map

package/dist/chat/daemon/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../src.legacy/chat/daemon/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjE,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,UAAkB,EAAE,IAAc;IACvE,QAAQ,UAAU,EAAE,CAAC;QACnB,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,GAAG,GAAG,MAAM,WAAW,EAAE,CAAC;YAChC,IAAI,GAAG,CAAC,eAAe,EAAE,CAAC;gBACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sCAAsC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;YAC3E,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;YACnE,CAAC;YACD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;YAC/B,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;YACnE,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;YACtD,CAAC;YACD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,CAAC,GAAG,MAAM,MAAM,EAAE,CAAC;YACzB,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;gBACd,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;gBAC5E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC;gBAC7E,OAAO,CAAC,CAAC;YACX,CAAC;YACD,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,sDAAsD,CAAC,CAAC,SAAS,KAAK,CACvE,CAAC;gBACF,OAAO,CAAC,CAAC;YACX,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;YACpD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,UAAU,GAAG,MAAM,MAAM,EAAE,CAAC;YAClC,IAAI,UAAU,CAAC,OAAO;gBAAE,MAAM,UAAU,EAAE,CAAC;YAC3C,MAAM,GAAG,GAAG,MAAM,WAAW,EAAE,CAAC;YAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;YACnE,OAAO,CAAC,CAAC;QACX,CAAC;QACD;YACE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0EAA0E;gBACxE,oBAAoB,IAAI,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAChE,CAAC;YACF,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,OAAO,eAAe,EAAE,CAAC;AAC3B,CAAC"}

package/dist/chat/daemon/collisions.js

@@ -0,0 +1,384 @@
+/**
+ * collisions.ts — TPS.5 (v0.5.124).
+ *
+ * Surfaces `buildRoutingIndex` collisions through three durable channels
+ * instead of the one (daemon log) v0.5.x had. Replaces the "warning lost
+ * in a log nobody tails" failure mode with:
+ *
+ *   1. `~/.opensquid/collisions.jsonl` — append-only audit trail.
+ *   2. Telegram general-topic notification — debounced 60min per key
+ *      so a long-standing collision pings the operator once an hour,
+ *      not every routing reload.
+ *   3. MCP `chat_poll_inbox` — prepends warning lines to the poll
+ *      response when an unresolved collision affects the active
+ *      workspace (read path lives in `src/mcp/chat-bridge-server.ts`).
+ *
+ * Source of truth is the JSONL file: write-once-on-every-collision +
+ * read-tail-on-every-poll. Debounce state is derived from the records
+ * themselves (last `notified_via_telegram=true` timestamp for the same
+ * channel_key) so daemon restarts don't reset the cooldown.
+ *
+ * Concurrency: single writer (the chat-daemon worker), many readers
+ * (per-project MCP bridge subprocesses). POSIX O_APPEND keeps
+ * sub-PIPE_BUF writes atomic. Malformed lines are skipped on read.
+ *
+ * Failure isolation: NEVER block the routing rebuild. Disk full →
+ * stderr log + continue. Telegram send failure → log + the JSONL line
+ * (which already wrote) still surfaces the collision on next MCP poll.
+ *
+ * Rebuild path: same ad-hoc tsc invocation as the other src.legacy/
+ * modules — see `src.legacy/chat/adapters/telegram.ts` header.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { loadAllProjectChatRouting } from "./routing.js";
+export const DEBOUNCE_WINDOW_MS = 60 * 60 * 1000;
+// ---------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------
+export function collisionsPath(dataRoot) {
+    const root = dataRoot ?? process.env.OPENSQUID_HOME;
+    if (!root || root.length === 0) {
+        throw new Error("collisionsPath: dataRoot not provided and OPENSQUID_HOME unset");
+    }
+    return path.join(root, "collisions.jsonl");
+}
+// ---------------------------------------------------------------------
+// Read / debounce
+// ---------------------------------------------------------------------
+/**
+ * Read the full discriminated union from `collisions.jsonl`, dropping
+ * malformed lines and unknown-shape records. Returns [] on missing
+ * file. TPS.7 (v0.5.130) — supersedes pre-TPS.7 single-type readers.
+ *
+ * Records without an explicit `kind` are treated as `CollisionEntry`
+ * (back-compat with TPS.5 writes).
+ */
+export async function loadAllCollisionsLines(dataRoot) {
+    const p = collisionsPath(dataRoot);
+    let raw;
+    try {
+        raw = await fs.readFile(p, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (line.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed.v !== 1 || typeof parsed.channel_key !== "string")
+                continue;
+            const kind = parsed.kind;
+            if (kind === "topic_gone") {
+                const ev = parsed;
+                if (typeof ev.workspace_uuid === "string" &&
+                    typeof ev.chat_id === "string" &&
+                    typeof ev.topic_id === "number") {
+                    out.push(ev);
+                }
+            }
+            else {
+                // kind missing OR explicitly "collision" — treat as CollisionEntry.
+                const ent = parsed;
+                if (Array.isArray(ent.claimants) && typeof ent.winner_uuid === "string") {
+                    out.push(ent);
+                }
+            }
+        }
+        catch {
+            /* skip malformed line */
+        }
+    }
+    return out;
+}
+/**
+ * TPS.5 back-compat reader — filters `loadAllCollisionsLines` to just
+ * `CollisionEntry` records (drops TPS.7 `TopicGoneEvent` lines). Used
+ * by the debounce scan in `recordCollision` so a recent topic-gone
+ * event doesn't suppress a fresh collision notification.
+ */
+export async function loadAllCollisions(dataRoot) {
+    const all = await loadAllCollisionsLines(dataRoot);
+    return all.filter((line) => {
+        const kind = line.kind;
+        return kind === undefined || kind === "collision";
+    });
+}
+/**
+ * TPS.7 (v0.5.130) — read `TopicGoneEvent` records only. Used by the
+ * debounce scan in `recordTopicGoneEvent` and by MCP `chat_poll_inbox`
+ * for stale-topic warnings.
+ */
+export async function loadAllTopicGoneEvents(dataRoot) {
+    const all = await loadAllCollisionsLines(dataRoot);
+    return all.filter((line) => {
+        return line.kind === "topic_gone";
+    });
+}
+/**
+ * MCP-side helper: return collisions whose `occurred_at` is within
+ * `maxAgeMinutes`. Used by `chat_poll_inbox` to prepend warnings
+ * about ACTIVE (still-recent) collisions to its response.
+ *
+ * Default window is 24 hours — long enough that the user sees the
+ * warning across a typical work session without surfacing ancient
+ * collisions that the user already fixed.
+ */
+export async function getRecentCollisions(maxAgeMinutes = 24 * 60, dataRoot) {
+    const cutoff = Date.now() - maxAgeMinutes * 60 * 1000;
+    const all = await loadAllCollisions(dataRoot);
+    return all.filter((e) => {
+        const t = Date.parse(e.occurred_at);
+        return Number.isFinite(t) && t >= cutoff;
+    });
+}
+/**
+ * TPS.7 (v0.5.130) — same default window as `getRecentCollisions` but
+ * for `TopicGoneEvent` records. Surfaced through MCP `chat_poll_inbox`
+ * so the agent learns "your topic was deleted; daemon cleared the
+ * binding; next session will rebind automatically" within the same
+ * 24h window.
+ */
+export async function getRecentTopicGoneEvents(maxAgeMinutes = 24 * 60, dataRoot) {
+    const cutoff = Date.now() - maxAgeMinutes * 60 * 1000;
+    const all = await loadAllTopicGoneEvents(dataRoot);
+    return all.filter((e) => {
+        const t = Date.parse(e.occurred_at);
+        return Number.isFinite(t) && t >= cutoff;
+    });
+}
+/**
+ * Find the most recent record (if any) that fired a Telegram
+ * notification for the same channel_key. Used to decide whether a
+ * new collision is within the debounce window.
+ */
+function lastNotifiedAt(entries, channelKey) {
+    let best = null;
+    for (const e of entries) {
+        if (e.channel_key !== channelKey)
+            continue;
+        if (!e.notified_via_telegram)
+            continue;
+        const t = Date.parse(e.occurred_at);
+        if (!Number.isFinite(t))
+            continue;
+        if (best === null || t > best)
+            best = t;
+    }
+    return best;
+}
+/**
+ * Record a collision: append a structured JSONL entry, and (if outside
+ * the debounce window + a Telegram report_channel exists) fire a
+ * one-shot notification to the supergroup's general topic. Returns
+ * the entry that was appended.
+ *
+ * NEVER throws past the caller: persist failures log to stderr; send
+ * failures log + flip the `notified_via_telegram` flag back to false
+ * for the persisted record. The routing rebuild that triggered this
+ * call must always complete.
+ */
+export async function recordCollision(args) {
+    const now = (args.nowMs ?? Date.now)();
+    const existing = await loadAllCollisions(args.dataRoot).catch(() => []);
+    const lastNotified = lastNotifiedAt(existing, args.info.channel_key);
+    const withinDebounce = lastNotified !== null && now - lastNotified < DEBOUNCE_WINDOW_MS;
+    // Decide whether we WILL notify this time. The final
+    // `notified_via_telegram` value reflects the send result (see below).
+    const shouldNotify = !withinDebounce && args.gateway !== undefined;
+    // Try Telegram notification BEFORE appending so the persisted flag
+    // reflects reality. If gateway send fails (rate limit, bot kicked),
+    // we still record the collision with notified=false so the next
+    // routing reload may retry past the debounce window.
+    let didNotify = false;
+    if (shouldNotify && args.gateway) {
+        try {
+            didNotify = await notifyCollisionViaTelegram({
+                gateway: args.gateway,
+                info: args.info,
+                dataRoot: args.dataRoot,
+            });
+        }
+        catch (err) {
+            process.stderr.write(`[collisions] telegram notify failed for ${args.info.channel_key}: ${err instanceof Error ? err.message : String(err)}\n`);
+            didNotify = false;
+        }
+    }
+    const entry = {
+        v: 1,
+        occurred_at: new Date(now).toISOString(),
+        channel_key: args.info.channel_key,
+        claimants: [args.info.existing_uuid, args.info.newcomer_uuid],
+        winner_uuid: args.info.newcomer_uuid,
+        notified_via_telegram: didNotify,
+    };
+    try {
+        await appendCollisionsLine(entry, args.dataRoot);
+    }
+    catch (err) {
+        process.stderr.write(`[collisions] persist failed for ${args.info.channel_key}: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    return entry;
+}
+/**
+ * Find ANY project with a Telegram `report_channel` configured and
+ * send the collision notification to its general topic. Picks the
+ * first match deterministically (Map insertion order, which is
+ * filename-sorted in `loadAllProjectChatRouting`) so notifications
+ * are stable across daemon restarts.
+ *
+ * Returns true iff the send succeeded. Catches everything — caller
+ * folds the failure into the JSONL record via `notified_via_telegram`.
+ */
+async function notifyCollisionViaTelegram(args) {
+    const configs = await loadAllProjectChatRouting(args.dataRoot);
+    const target = pickNotificationTarget(configs);
+    if (target === null)
+        return false;
+    const text = formatCollisionMessage(args.info, target.workspaceLabel);
+    try {
+        // Force the general topic — collisions are admin-tier notifications,
+        // not workspace-scoped chatter. Telegram represents the general
+        // topic as the chat itself with NO threadId, so we intentionally
+        // omit it (don't pass report_topic_id even if set).
+        await args.gateway.send({ channel: target.channel, text });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pickNotificationTarget(configs) {
+    for (const [uuid, cfg] of configs) {
+        const ch = cfg.telegram?.report_channel;
+        if (ch && ch.length > 0) {
+            return { channel: ch, workspaceLabel: uuid };
+        }
+    }
+    return null;
+}
+function formatCollisionMessage(info, sourceLabel) {
+    return [
+        "⚠️ opensquid routing collision detected",
+        "",
+        `  channel: ${info.channel_key}`,
+        `  existing: ${info.existing_uuid}`,
+        `  newcomer: ${info.newcomer_uuid} (will win)`,
+        "",
+        `Two workspaces claim the same inbound channel. Inbound messages route to`,
+        `the newer claimant; the older one will see nothing. Edit one of the`,
+        `chat-routing.json files under ~/.opensquid/projects/ to resolve.`,
+        "",
+        `(notified by ${sourceLabel})`,
+    ].join("\n");
+}
+/**
+ * Record a topic-gone event: append a structured JSONL entry to
+ * collisions.jsonl, and (if outside the debounce window + a Telegram
+ * report_channel exists) fire a one-shot notification to the
+ * supergroup's general topic. Returns the entry that was appended.
+ *
+ * Mirrors `recordCollision` semantics — NEVER throws past the caller.
+ * Persist failures log to stderr; send failures flip the
+ * `notified_via_telegram` flag to false. The async caller in
+ * `rpc-server.ts:handleTopicGone` doesn't await any user-visible work.
+ *
+ * Debounce key: the same `channel_key` shape used by collisions
+ * (`telegram:<chat_id>:<topic_id>`). Within `DEBOUNCE_WINDOW_MS`,
+ * additional topic-gone events for the same channel record to JSONL
+ * but skip the Telegram ping — the user already got the alert.
+ */
+export async function recordTopicGoneEvent(args) {
+    const now = (args.nowMs ?? Date.now)();
+    const channelKey = `telegram:${args.chatId}:${args.topicId}`;
+    const existing = await loadAllTopicGoneEvents(args.dataRoot).catch(() => []);
+    const lastNotified = lastTopicGoneNotifiedAt(existing, channelKey);
+    const withinDebounce = lastNotified !== null && now - lastNotified < DEBOUNCE_WINDOW_MS;
+    const shouldNotify = !withinDebounce && args.gateway !== undefined;
+    let didNotify = false;
+    if (shouldNotify && args.gateway) {
+        try {
+            didNotify = await notifyTopicGoneViaTelegram({
+                gateway: args.gateway,
+                workspaceUuid: args.workspaceUuid,
+                chatId: args.chatId,
+                topicId: args.topicId,
+                dataRoot: args.dataRoot,
+            });
+        }
+        catch (err) {
+            process.stderr.write(`[collisions] topic-gone telegram notify failed for ${channelKey}: ${err instanceof Error ? err.message : String(err)}\n`);
+            didNotify = false;
+        }
+    }
+    const entry = {
+        v: 1,
+        kind: "topic_gone",
+        occurred_at: new Date(now).toISOString(),
+        channel_key: channelKey,
+        workspace_uuid: args.workspaceUuid,
+        chat_id: args.chatId,
+        topic_id: args.topicId,
+        underlying_description: args.underlyingDescription,
+        notified_via_telegram: didNotify,
+    };
+    try {
+        await appendCollisionsLine(entry, args.dataRoot);
+    }
+    catch (err) {
+        process.stderr.write(`[collisions] topic-gone persist failed for ${channelKey}: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    return entry;
+}
+function lastTopicGoneNotifiedAt(events, channelKey) {
+    let best = null;
+    for (const e of events) {
+        if (e.channel_key !== channelKey)
+            continue;
+        if (!e.notified_via_telegram)
+            continue;
+        const t = Date.parse(e.occurred_at);
+        if (!Number.isFinite(t))
+            continue;
+        if (best === null || t > best)
+            best = t;
+    }
+    return best;
+}
+async function appendCollisionsLine(line, dataRoot) {
+    const p = collisionsPath(dataRoot);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.appendFile(p, JSON.stringify(line) + "\n", "utf8");
+}
+async function notifyTopicGoneViaTelegram(args) {
+    const configs = await loadAllProjectChatRouting(args.dataRoot);
+    const target = pickNotificationTarget(configs);
+    if (target === null)
+        return false;
+    const text = formatTopicGoneMessage(args);
+    try {
+        await args.gateway.send({ channel: target.channel, text });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function formatTopicGoneMessage(args) {
+    return [
+        "🧹 opensquid topic binding cleared (topic was deleted)",
+        "",
+        `  workspace: ${args.workspaceUuid}`,
+        `  chat_id: ${args.chatId}`,
+        `  topic_id: ${args.topicId} (no longer exists)`,
+        "",
+        `The bound forum topic was deleted from the supergroup. The daemon`,
+        `cleared the stale binding; the next MCP-bridge subscribe for this`,
+        `workspace will auto-rebind to a fresh topic (TPS.6 auto-boot).`,
+    ].join("\n");
+}

package/dist/chat/daemon/health-check.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Startup health checks for chat-daemon's configured inbound channels
+ * (v0.5.89 / TG.2).
+ *
+ * Why this exists: the daemon's inbound path silently accepts whatever
+ * Telegram delivers via long-poll. If the bot has been kicked from a
+ * supergroup, or the supergroup_id in chat-routing.json is stale, or
+ * the bot doesn't have read permission, the symptom is identical:
+ * "no inbound messages from that chat ever arrive". The daemon log
+ * looks healthy. The user assumes their routing is broken.
+ *
+ * This module adds one round-trip per unique inbound chat_id at
+ * daemon startup, calling Telegram's `getChat` HTTPS endpoint, and
+ * logs a clear reachability verdict per chat_id. Catches:
+ *
+ *   - 403 Forbidden ("bot was kicked from the supergroup chat") — the
+ *     load-bearing case this module was written to catch.
+ *   - 400 Bad Request (chat_id doesn't exist or bot can't see it) —
+ *     surfaces typo'd or stale chat_ids.
+ *   - Network failures — distinguishes config error from connectivity
+ *     issues.
+ *
+ * Scope discipline:
+ *   - Telegram-only. Discord + Slack health checks deferred (their
+ *     SDKs require different shapes; one-platform-at-a-time).
+ *   - Best-effort. Health-check failures DO NOT block daemon startup;
+ *     they log warnings and let the daemon continue. A bot that's
+ *     kicked from one chat may still be fine for outbound to others.
+ *   - No grammy dependency. Uses native fetch so this module can run
+ *     even if grammy isn't loaded yet (it's a dynamic import elsewhere).
+ *
+ * Imports from: nothing (fetch is global in Node 20+).
+ * Imported by: src.legacy/chat/daemon/worker.ts (post-gateway-start).
+ */
+export interface ChatReachability {
+    /** The chat_id we tested, in raw string form (e.g. `-1001234567890` for a supergroup). */
+    chatId: string;
+    /** True iff Telegram returned `ok: true` on getChat. */
+    ok: boolean;
+    /** Chat title when known (supergroups + channels carry it). */
+    title?: string;
+    /** Chat type when known (`supergroup`, `group`, `channel`, `private`). */
+    chatType?: string;
+    /** Telegram error_code when not ok (typically 403 or 400). */
+    errorCode?: number;
+    /** Telegram description string when not ok. */
+    errorDescription?: string;
+    /** Set when the round-trip itself failed (DNS, TLS, timeout). */
+    networkError?: string;
+}
+/**
+ * Call Telegram getChat for each chat_id and return per-chat
+ * reachability. Sequential because the call count is small (typically
+ * 1–3 chats per project, 1–10 projects per host) and Telegram's bot
+ * API rate limits favor sequential calls over bursts. Per-call
+ * timeout is 5s — enough for legitimate latency, short enough that
+ * a hung API doesn't block daemon startup forever.
+ *
+ * `botToken` is the loaded Telegram bot token. If absent or empty,
+ * returns an empty array (no point health-checking without a token).
+ */
+export declare function verifyTelegramChats(botToken: string | undefined, chatIds: readonly string[]): Promise<ChatReachability[]>;
+/**
+ * Render a single reachability verdict as a one-line log message.
+ * Stays formatting-stable so operators can grep daemon logs for
+ * `[chat-daemon] chat-reachability` to find all verdicts in one pass.
+ */
+export declare function formatReachabilityLine(r: ChatReachability): string;
+//# sourceMappingURL=health-check.d.ts.map

package/dist/chat/daemon/health-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-check.d.ts","sourceRoot":"","sources":["../../../src.legacy/chat/daemon/health-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,EAAE,EAAE,OAAO,CAAC;IACZ,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAaD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAU7B;AAiCD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAclE"}

package/dist/chat/daemon/health-check.js

@@ -0,0 +1,112 @@
+/**
+ * Startup health checks for chat-daemon's configured inbound channels
+ * (v0.5.89 / TG.2).
+ *
+ * Why this exists: the daemon's inbound path silently accepts whatever
+ * Telegram delivers via long-poll. If the bot has been kicked from a
+ * supergroup, or the supergroup_id in chat-routing.json is stale, or
+ * the bot doesn't have read permission, the symptom is identical:
+ * "no inbound messages from that chat ever arrive". The daemon log
+ * looks healthy. The user assumes their routing is broken.
+ *
+ * This module adds one round-trip per unique inbound chat_id at
+ * daemon startup, calling Telegram's `getChat` HTTPS endpoint, and
+ * logs a clear reachability verdict per chat_id. Catches:
+ *
+ *   - 403 Forbidden ("bot was kicked from the supergroup chat") — the
+ *     load-bearing case this module was written to catch.
+ *   - 400 Bad Request (chat_id doesn't exist or bot can't see it) —
+ *     surfaces typo'd or stale chat_ids.
+ *   - Network failures — distinguishes config error from connectivity
+ *     issues.
+ *
+ * Scope discipline:
+ *   - Telegram-only. Discord + Slack health checks deferred (their
+ *     SDKs require different shapes; one-platform-at-a-time).
+ *   - Best-effort. Health-check failures DO NOT block daemon startup;
+ *     they log warnings and let the daemon continue. A bot that's
+ *     kicked from one chat may still be fine for outbound to others.
+ *   - No grammy dependency. Uses native fetch so this module can run
+ *     even if grammy isn't loaded yet (it's a dynamic import elsewhere).
+ *
+ * Imports from: nothing (fetch is global in Node 20+).
+ * Imported by: src.legacy/chat/daemon/worker.ts (post-gateway-start).
+ */
+/**
+ * Call Telegram getChat for each chat_id and return per-chat
+ * reachability. Sequential because the call count is small (typically
+ * 1–3 chats per project, 1–10 projects per host) and Telegram's bot
+ * API rate limits favor sequential calls over bursts. Per-call
+ * timeout is 5s — enough for legitimate latency, short enough that
+ * a hung API doesn't block daemon startup forever.
+ *
+ * `botToken` is the loaded Telegram bot token. If absent or empty,
+ * returns an empty array (no point health-checking without a token).
+ */
+export async function verifyTelegramChats(botToken, chatIds) {
+    if (!botToken || botToken.trim().length === 0)
+        return [];
+    if (chatIds.length === 0)
+        return [];
+    const unique = Array.from(new Set(chatIds));
+    const results = [];
+    for (const chatId of unique) {
+        results.push(await checkOne(botToken, chatId));
+    }
+    return results;
+}
+async function checkOne(token, chatId) {
+    // 5s timeout via AbortController — keeps a hung Telegram API from
+    // wedging daemon startup indefinitely. The daemon doesn't actually
+    // need health-check results to be useful; if all calls time out, we
+    // just log "skipped due to timeouts" and continue.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5_000);
+    try {
+        const url = `https://api.telegram.org/bot${token}/getChat?chat_id=${encodeURIComponent(chatId)}`;
+        const res = await fetch(url, { method: "GET", signal: controller.signal });
+        const body = (await res.json());
+        if (body.ok && body.result) {
+            const r = { chatId, ok: true, chatType: body.result.type };
+            if (body.result.title)
+                r.title = body.result.title;
+            return r;
+        }
+        const r = { chatId, ok: false };
+        if (body.error_code !== undefined)
+            r.errorCode = body.error_code;
+        if (body.description)
+            r.errorDescription = body.description;
+        return r;
+    }
+    catch (err) {
+        return {
+            chatId,
+            ok: false,
+            networkError: err instanceof Error ? err.message : String(err),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Render a single reachability verdict as a one-line log message.
+ * Stays formatting-stable so operators can grep daemon logs for
+ * `[chat-daemon] chat-reachability` to find all verdicts in one pass.
+ */
+export function formatReachabilityLine(r) {
+    if (r.ok) {
+        const title = r.title ? ` "${r.title}"` : "";
+        const type = r.chatType ? ` (${r.chatType})` : "";
+        return `[chat-daemon] chat-reachability ${r.chatId}${title}${type}: OK`;
+    }
+    if (r.networkError) {
+        return `[chat-daemon] chat-reachability ${r.chatId}: NETWORK_ERROR ${r.networkError}`;
+    }
+    // Common 403 = "Forbidden: bot was kicked from the supergroup chat"
+    // Common 400 = "Bad Request: chat not found" (typo'd or stale id)
+    const code = r.errorCode !== undefined ? `${r.errorCode}` : "?";
+    const desc = r.errorDescription ?? "(no description)";
+    return `[chat-daemon] chat-reachability ${r.chatId}: ERROR ${code} ${desc}`;
+}

package/dist/chat/daemon/health-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-check.js","sourceRoot":"","sources":["../../../src.legacy/chat/daemon/health-check.ts"],"names":[],"mappings":"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"}