opensquid 0.5.395

package/dist/chat/daemon/worker.js

@@ -0,0 +1,313 @@
+/**
+ * Chat-daemon worker entrypoint (v0.7.1 Phase A).
+ *
+ * Spawned as a detached child by `lifecycle.startDaemon()`. Owns the
+ * single long-poll connection per chat platform. The MCP server side
+ * stays out of the polling business entirely — outbound RPC (Phase B)
+ * and inbox tailing (Phase C) replace the in-process gateway.
+ *
+ * Lifecycle inside the worker:
+ *   1. Write our PID to ~/.opensquid/chat-daemon.pid
+ *   2. Build the chat gateway from ~/.opensquid/config.json
+ *   3. Start every configured adapter (their long-poll loops run as
+ *      side effects of start())
+ *   4. Install SIGTERM / SIGINT handlers that stop the gateway and
+ *      remove the pidfile before exit
+ *   5. Park on process.stdin (which is /dev/null in detached mode)
+ *      so the event loop stays alive
+ *
+ * Crash behavior: any unhandled exception from gateway.start() prints
+ * to the (parent-redirected) log file and exits non-zero. The pidfile
+ * is cleaned up in the SIGTERM handler — if we crash before installing
+ * it, the pidfile may linger, and the next `status` call will report
+ * `stale_pid` (lifecycle.startDaemon cleans up stale pidfiles before
+ * spawning).
+ */
+import { promises as fs } from "node:fs";
+import { buildChatGateway } from "../factory.js";
+import { appendToInbox } from "./inbox.js";
+import { daemonPaths } from "./lifecycle.js";
+import { buildRoutingIndex, loadAllProjectChatRouting } from "./routing.js";
+import { RpcServer } from "./rpc-server.js";
+let gateway = null;
+let rpcServer = null;
+let routingIndex = new Map();
+let routingPollTimer = null;
+let pidFile = null;
+let shuttingDown = false;
+export async function runDaemonWorker(dataRoot) {
+    const paths = daemonPaths(dataRoot);
+    pidFile = paths.pidFile;
+    // Write pidfile FIRST so a status check after spawn sees the worker
+    // promptly. Truncate-write is the right semantic — any previous
+    // pidfile is stale by definition (we already verified no live daemon
+    // existed in lifecycle.startDaemon).
+    await fs.writeFile(pidFile, `${process.pid}\n`, "utf8");
+    log(`[chat-daemon] worker booted pid=${process.pid} cwd=${process.cwd()}`);
+    // Build + start the gateway. If config is empty, no adapters
+    // activate and the daemon parks idle — useful for testing the
+    // lifecycle without configuring a real bot token.
+    try {
+        // 0.7.5 (#148): log which source each platform's token came from
+        // (env / env-file / config-json) so operators can debug "which
+        // bot is this daemon actually using" without exposing the secret.
+        try {
+            const { loadChatConfigWithSources } = await import("../config.js");
+            const { sources } = await loadChatConfigWithSources(dataRoot);
+            const lines = [];
+            if (sources.telegram)
+                lines.push(`telegram=${sources.telegram}`);
+            if (sources.discord)
+                lines.push(`discord=${sources.discord}`);
+            if (sources.slack_bot)
+                lines.push(`slack_bot=${sources.slack_bot}`);
+            if (sources.slack_app)
+                lines.push(`slack_app=${sources.slack_app}`);
+            if (lines.length) {
+                log(`[chat-daemon] token sources: ${lines.join(" ")}${sources.env_file_path ? ` (env-file: ${sources.env_file_path})` : ""}`);
+            }
+        }
+        catch (logErr) {
+            log(`[chat-daemon] could not log token sources (non-fatal): ${logErr instanceof Error ? logErr.message : logErr}`);
+        }
+        const built = await buildChatGateway({ dataRoot });
+        gateway = built.gateway;
+        log(`[chat-daemon] activating platforms: ${built.activated.join(",") || "(none)"}`);
+        if (built.issues.length) {
+            for (const i of built.issues) {
+                log(`[chat-daemon] config issue ${i.platform}.${i.field}: ${i.problem}`);
+            }
+        }
+        // Phase C: load per-project chat-routing.json files and build the
+        // chat_id → project_uuid index BEFORE attaching the inbound
+        // handler. The handler uses this index to route messages to
+        // per-project inboxes.
+        routingIndex = await rebuildRoutingIndex(dataRoot);
+        log(`[chat-daemon] routing index built: ${routingIndex.size} inbound channels mapped`);
+        gateway.onMessage(async (msg) => {
+            // v0.5.94 (WAB.2 Part A / TG.1 (a)): DM-first routing.
+            //
+            // Key precedence:
+            //   1. DM key (`telegram:dm:<user_id>`) when the message is a DM —
+            //      defined as `msg.channel === "telegram:" + msg.senderId`.
+            //      The Telegram adapter formats DM chats as `telegram:<chat_id>`
+            //      where chat_id === from.id, so the equality check is the
+            //      canonical Telegram private-chat indicator. This also rejects
+            //      group-message-from-self spoofs (group chat.id is negative
+            //      for supergroups; senderId is positive; they cannot collide).
+            //   2. Topic-specific key (`<channel>:<threadId>`) when the message
+            //      is in a forum topic.
+            //   3. Channel-only key (`<channel>`).
+            //
+            // Strict topic whitelist preserved per TG.1 (d) — a message in a
+            // topic NOT listed by any project's `inbound_topic_ids` will not
+            // fall back to the chat-only key (because `collectInboundChannels`
+            // does not emit the chat-only key when `inbound_topic_ids` is set
+            // on that project). Such messages orphan, which is the documented
+            // security-correct default.
+            const isDm = msg.platform === 'telegram' && msg.channel === `telegram:${msg.senderId}`;
+            const dmKey = isDm ? `telegram:dm:${msg.senderId}` : null;
+            const topicKey = msg.threadId ? `${msg.channel}:${msg.threadId}` : null;
+            const projectUuid = (dmKey ? routingIndex.get(dmKey) : undefined) ??
+                (topicKey ? routingIndex.get(topicKey) : undefined) ??
+                routingIndex.get(msg.channel) ??
+                null;
+            try {
+                const r = await appendToInbox(msg, projectUuid, dataRoot);
+                log(`[chat-daemon] inbox ← ${msg.channel} (${msg.text.slice(0, 60).replace(/\n/g, " ")}…) → ${r.destination}${r.project_uuid ? "/" + r.project_uuid : ""}`);
+            }
+            catch (err) {
+                log(`[chat-daemon] inbox append failed for ${msg.channel}: ${err instanceof Error ? err.message : err}`);
+            }
+            // TPS.6 patch 2 (v0.5.126) — broadcast to long-lived UDS
+            // subscribers. The JSONL file write above is the durable record;
+            // this push is the low-latency delivery. We broadcast on a
+            // single key — the most-specific one available: topic-suffixed
+            // `<channel>:<threadId>` if present, else bare `<channel>`.
+            // This mirrors the routing-index key semantics from
+            // `collectInboundChannels`: a project that registers only
+            // `chat_id:thread_id` doesn't want to receive messages from
+            // other topics in the same supergroup. Wildcard subscribers
+            // (chat_ids=[]) see every message regardless of key shape.
+            // Fire-and-forget — subscriber write failures are handled by
+            // the registry's own socket lifecycle hooks.
+            if (rpcServer !== null) {
+                const broadcastKey = msg.threadId
+                    ? `${msg.channel}:${msg.threadId}`
+                    : msg.channel;
+                const notif = {
+                    jsonrpc: "2.0",
+                    method: "inbound_message",
+                    params: {
+                        delivery_id: `del-${Date.now().toString()}-${Math.random().toString(36).slice(2, 10)}`,
+                        message_id: msg.id,
+                        platform: msg.platform,
+                        channel: msg.channel,
+                        ...(msg.threadId !== undefined ? { thread_id: msg.threadId } : {}),
+                        sender: msg.sender,
+                        sender_id: msg.senderId,
+                        text: msg.text,
+                        received_at: msg.receivedAt.toISOString(),
+                        mentions_bot: msg.mentionsBot,
+                    },
+                };
+                rpcServer.subscribers.broadcast(broadcastKey, notif);
+            }
+        });
+        await gateway.start();
+        log(`[chat-daemon] gateway start complete`);
+        // v0.5.89 (TG.2) — startup reachability check against each
+        // unique inbound chat_id. Catches kicked-from-supergroup (403),
+        // stale chat_id (400), and network errors immediately at startup.
+        // Best-effort: failures don't block daemon startup, just log
+        // warnings so operators can see what's wrong without inspecting
+        // hours of empty log noise. The check is Telegram-only for now;
+        // Discord/Slack equivalents land in a follow-up if needed.
+        try {
+            const { verifyTelegramChats, formatReachabilityLine } = await import("./health-check.js");
+            const { loadChatConfig } = await import("../config.js");
+            const chatConfig = await loadChatConfig(dataRoot);
+            const tgToken = chatConfig.telegram?.bot_token;
+            // Collect unique chat_ids referenced across all projects' Telegram
+            // routing (skip dm: and topic-suffixed keys — getChat takes only
+            // the chat_id, no topic).
+            const chatIds = new Set();
+            const configs = await loadAllProjectChatRouting(dataRoot);
+            for (const cfg of configs.values()) {
+                for (const id of cfg.telegram?.inbound_chat_ids ?? [])
+                    chatIds.add(id);
+            }
+            if (chatIds.size > 0 && tgToken) {
+                const results = await verifyTelegramChats(tgToken, [...chatIds]);
+                for (const r of results)
+                    log(formatReachabilityLine(r));
+            }
+        }
+        catch (err) {
+            log(`[chat-daemon] chat-reachability check skipped (non-fatal): ${err instanceof Error ? err.message : err}`);
+        }
+        // RPC server listens for outbound send() calls from per-project
+        // MCP servers. Starting it AFTER gateway.start() means clients
+        // that connect successfully are guaranteed a fully-warmed gateway.
+        rpcServer = new RpcServer({ gateway, dataRoot, version: "v0.7.1-phase-c" });
+        await rpcServer.listen();
+        // Poll the routing files every 30s so operators can edit a
+        // chat-routing.json and have the daemon pick it up without a full
+        // restart. Polling is the most portable option (fs.watch behavior
+        // varies across macOS/Linux/Windows + recursive support).
+        routingPollTimer = setInterval(() => {
+            void (async () => {
+                try {
+                    const next = await rebuildRoutingIndex(dataRoot);
+                    if (!sameIndex(routingIndex, next)) {
+                        routingIndex = next;
+                        log(`[chat-daemon] routing reload: ${routingIndex.size} inbound channels mapped`);
+                    }
+                }
+                catch (err) {
+                    log(`[chat-daemon] routing reload failed (non-fatal): ${err instanceof Error ? err.message : err}`);
+                }
+            })();
+        }, 30_000);
+        log(`[chat-daemon] rpc server listening; entering park loop`);
+    }
+    catch (err) {
+        log(`[chat-daemon] FATAL: gateway start failed: ${err instanceof Error ? err.stack : err}`);
+        await cleanup();
+        process.exit(1);
+    }
+    // Signal handlers. SIGTERM = graceful, SIGINT = also graceful (for
+    // manual `kill` during dev). Each calls cleanup() exactly once.
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    // Park forever. process.stdin.resume() does NOT work here because
+    // the parent spawned us with `stdio: ['ignore', ...]` — there's no
+    // FD 0 to poll. An unresolved Promise alone won't hold the event
+    // loop either; Node exits when nothing's scheduled. The reliable
+    // pattern is a long-interval no-op timer (~12 days per tick); the
+    // tick is a microsecond of CPU and easily survives clock jitter.
+    // Signal handlers are independently registered above and still fire.
+    setInterval(() => {
+        /* keep-alive heartbeat */
+    }, 1 << 30);
+    // TypeScript demands a return path even though we never reach here.
+    return await new Promise(() => {
+        /* never resolves; held alive by the heartbeat interval */
+    });
+}
+async function shutdown(signal) {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    log(`[chat-daemon] ${signal} received, shutting down...`);
+    if (routingPollTimer)
+        clearInterval(routingPollTimer);
+    // TPS.6 patch 2 (v0.5.126) — tell subscribers we're going away
+    // BEFORE closing the RPC server. The shutdown notification gives
+    // MCP bridges a clean signal to back off their reconnect loop
+    // instead of treating the disconnect as transient and immediately
+    // retrying.
+    try {
+        if (rpcServer)
+            rpcServer.subscribers.shutdown(signal);
+    }
+    catch (err) {
+        log(`[chat-daemon] subscriber shutdown notify error (non-fatal): ${err instanceof Error ? err.message : err}`);
+    }
+    try {
+        if (rpcServer)
+            await rpcServer.close();
+    }
+    catch (err) {
+        log(`[chat-daemon] rpc close error (non-fatal): ${err instanceof Error ? err.message : err}`);
+    }
+    try {
+        if (gateway)
+            await gateway.shutdown();
+    }
+    catch (err) {
+        log(`[chat-daemon] gateway.shutdown error (non-fatal): ${err instanceof Error ? err.message : err}`);
+    }
+    await cleanup();
+    log(`[chat-daemon] clean exit`);
+    process.exit(0);
+}
+async function cleanup() {
+    if (pidFile) {
+        try {
+            await fs.unlink(pidFile);
+        }
+        catch {
+            /* race-tolerant */
+        }
+    }
+}
+function log(line) {
+    // stdio is already redirected to the log file by the parent's spawn
+    // options; plain console.log lands in the right place.
+    process.stdout.write(`${new Date().toISOString()} ${line}\n`);
+}
+async function rebuildRoutingIndex(dataRoot) {
+    const cfgs = await loadAllProjectChatRouting(dataRoot);
+    const { recordCollision } = await import("./collisions.js");
+    return buildRoutingIndex(cfgs, (info) => {
+        log(`[chat-daemon] routing collision: ${info.channel_key} existing=${info.existing_uuid} newcomer=${info.newcomer_uuid} (latter wins)`);
+        // Fire-and-forget: persist + notify happen async; the routing
+        // rebuild must not wait. recordCollision swallows its own errors
+        // (stderr-logged) so this `void` is intentional.
+        void recordCollision({
+            info,
+            dataRoot,
+            ...(gateway !== null ? { gateway } : {}),
+        });
+    });
+}
+function sameIndex(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [k, v] of a) {
+        if (b.get(k) !== v)
+            return false;
+    }
+    return true;
+}

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

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

package/dist/chat/daemon/workspace-topic.js

@@ -0,0 +1,324 @@
+/**
+ * workspace-topic.ts — workspace → forum-topic binding primitive
+ * (TPS.3 / v0.5.120+).
+ *
+ * Solves: given a workspace (cwd-resolved uuid + path) and a target
+ * supergroup chat_id, ensure the workspace has a bound forum topic +
+ * persist the binding to its `chat-routing.json`. Idempotent.
+ *
+ * Used by:
+ *   - TPS.4 — `opensquid setup chat` wizard step (mode: "wizard")
+ *   - TPS.6 — daemon auto-boot on MCP subscribe (mode: "auto-boot")
+ *
+ * Concurrency: protected by `proper-lockfile` on the per-project
+ * `chat-routing.json` so two concurrent invocations for the same
+ * workspace can't race-create two topics. The lock window covers
+ * (load existing config) → (call createTopic if missing) → (write
+ * updated config). Lock retries are bounded; if a stale lock from a
+ * crashed prior run blocks acquisition, an `LOCKED` error is thrown
+ * upward — callers (wizard, auto-boot) surface this to the user
+ * rather than papering over it.
+ *
+ * Error propagation: this module does NOT swallow errors. RPC failures
+ * (bot not admin, network), parse errors, and lock failures all
+ * propagate. Callers decide how to surface them (TPS.4 prints to the
+ * wizard, TPS.6 logs + falls back to general topic).
+ *
+ * Rebuild path: same as adapters/telegram.ts — see that file's header
+ * for the ad-hoc tsc invocation. `pnpm build` does NOT recompile this
+ * file; the chat-daemon worker loads dist/chat/daemon/workspace-topic.js
+ * at runtime.
+ */
+import { promises as fs } from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import * as lockfile from "proper-lockfile";
+// Need synchronous require() to construct the rpc-client lazily without
+// making resolveOrCreateTopic's signature async-on-import. ESM Node 20+
+// exposes createRequire for exactly this case.
+const requireCJS = createRequire(import.meta.url);
+import { loadAllProjectChatRouting, loadProjectChatRouting, projectChatRoutingPath, } from "./routing.js";
+// ---------------------------------------------------------------------
+// Main entrypoint
+// ---------------------------------------------------------------------
+export async function resolveOrCreateTopic(args) {
+    const routingPath = projectChatRoutingPath(args.workspaceUuid, args.dataRoot);
+    // Lockfile lives next to the routing file; proper-lockfile handles
+    // both lock acquisition and the necessary parent-dir creation logic
+    // as long as the target exists. Ensure the dir exists first.
+    await fs.mkdir(path.dirname(routingPath), { recursive: true });
+    // proper-lockfile requires the target file to exist; touch it
+    // (empty config) if it doesn't, so the lock can be acquired
+    // regardless of whether the workspace has ever had routing set up.
+    await ensureRoutingFileExists(routingPath);
+    // Retry tuning rationale (TPS.3 pre-research): typical createTopic
+    // round-trip is 200-600ms (UDS + HTTPS to api.telegram.org). 8
+    // retries with 1.5× backoff at 50ms-800ms gives ~2.4s headroom —
+    // plenty for one contender to finish while another waits. Stale is
+    // proper-lockfile's default (10s); not setting it explicitly.
+    const release = await lockfile.lock(routingPath, {
+        retries: { retries: 8, factor: 1.5, minTimeout: 50, maxTimeout: 800 },
+    });
+    try {
+        const existing = await loadProjectChatRouting(args.workspaceUuid, args.dataRoot);
+        assertAutoBoundInvariant(existing, routingPath);
+        const bound = existing?.telegram?.auto_bound;
+        if (bound && Number.isFinite(bound.topic_id) && bound.topic_id > 0) {
+            // Idempotent — already bound, return existing.
+            // Sanity check: if the auto_bound.workspace_uuid disagrees with
+            // the outer uuid (the directory name), log on stderr but trust
+            // the outer uuid as authoritative.
+            if (bound.workspace_uuid !== args.workspaceUuid) {
+                process.stderr.write(`[workspace-topic] auto_bound.workspace_uuid (${bound.workspace_uuid}) ≠ outer uuid (${args.workspaceUuid}) for ${routingPath}; using existing binding\n`);
+            }
+            return { topicId: bound.topic_id, topicName: bound.topic_name, created: false };
+        }
+        const name = deriveTopicName(args.workspacePath, args.workspaceUuid);
+        const client = args.rpcClient ?? defaultRpcClient(args.dataRoot);
+        const created = await client.createTopic({
+            platform: "telegram",
+            chat_id: args.chatId,
+            name,
+        });
+        const nextAutoBound = {
+            workspace_path: args.workspacePath,
+            workspace_uuid: args.workspaceUuid,
+            topic_id: created.message_thread_id,
+            topic_name: created.name,
+            created_at: new Date().toISOString(),
+            created_by: args.mode,
+        };
+        const merged = {
+            ...(existing ?? {}),
+            telegram: {
+                ...(existing?.telegram ?? {}),
+                // Persist both auto_bound metadata + the actual routing field
+                // (inbound_topic_ids) so the routing index picks up the new
+                // binding on its next ~30s hot-reload without separate writes.
+                inbound_topic_ids: mergeTopicIds(existing?.telegram?.inbound_topic_ids, created.message_thread_id),
+                inbound_chat_ids: mergeChatIds(existing?.telegram?.inbound_chat_ids, args.chatId),
+                auto_bound: nextAutoBound,
+            },
+        };
+        try {
+            await persistRoutingAtomic(routingPath, merged);
+        }
+        catch (persistErr) {
+            // TPS.3 pre-research, choice #6 partial-failure compensation:
+            // createTopic SUCCEEDED but persist FAILED — Telegram has a real
+            // topic we cannot reference. Log it to a recovery file so the
+            // user can clean up (delete the orphan topic manually) instead
+            // of accumulating ghost topics on every retry. Don't try to
+            // rollback (delete the topic) here — that requires a second
+            // RPC call that could also fail, compounding the problem.
+            // The user-facing surface lives in TPS.5 collision channel.
+            await recordOrphanTopic(args.dataRoot, {
+                chat_id: args.chatId,
+                topic_id: created.message_thread_id,
+                topic_name: created.name,
+                workspace_uuid: args.workspaceUuid,
+                workspace_path: args.workspacePath,
+                mode: args.mode,
+                persist_error: persistErr instanceof Error ? persistErr.message : String(persistErr),
+                occurred_at: new Date().toISOString(),
+            });
+            throw persistErr;
+        }
+        return {
+            topicId: created.message_thread_id,
+            topicName: created.name,
+            created: true,
+        };
+    }
+    finally {
+        await release();
+    }
+}
+// ---------------------------------------------------------------------
+// Helpers (exported for unit tests)
+// ---------------------------------------------------------------------
+/**
+ * Derive a deterministic, human-readable topic name from the workspace
+ * path + uuid. The basename of the path is the most user-recognisable
+ * part; the uuid prefix disambiguates two workspaces with the same
+ * basename. Examples:
+ *
+ *   deriveTopicName("/Users/slee/projects/loop", "da96385b-...") =
+ *     "loop · da96385b"
+ *   deriveTopicName("/", "abc12345-...") = "root · abc12345"
+ */
+export function deriveTopicName(workspacePath, workspaceUuid) {
+    const basenameRaw = path.basename(workspacePath) || "root";
+    // Telegram limit per [aiogram docs](https://docs.aiogram.dev/en/latest/api/methods/create_forum_topic.html)
+    // is 1-128 chars. Cap basename at 48 to leave headroom for the
+    // " · 12345678" suffix (11 chars) — total max output ~59 chars.
+    // 48 is conservative: Telegram client truncates topic-list display
+    // at ~30-35 chars anyway. Pre-research verdict #4.
+    const basename = basenameRaw.length > 48 ? `${basenameRaw.slice(0, 45)}...` : basenameRaw;
+    const uuidShort = workspaceUuid.slice(0, 8);
+    return `${basename} · ${uuidShort}`;
+}
+/**
+ * Merge a single new topic_id into an optional existing array. Avoids
+ * duplicates while preserving order (existing first, new last).
+ */
+export function mergeTopicIds(existing, newId) {
+    if (!existing || existing.length === 0)
+        return [newId];
+    if (existing.includes(newId))
+        return existing;
+    return [...existing, newId];
+}
+/**
+ * Same as mergeTopicIds for chat_ids (strings).
+ */
+export function mergeChatIds(existing, newId) {
+    if (!existing || existing.length === 0)
+        return [newId];
+    if (existing.includes(newId))
+        return existing;
+    return [...existing, newId];
+}
+/**
+ * Clear an existing auto_bound block (TPS.7 stale-topic lifecycle).
+ * Leaves `inbound_topic_ids` alone — caller decides whether to also
+ * scrub those (typically yes, since the stale topic_id no longer
+ * exists). Returns true if a binding was cleared, false if none.
+ */
+export async function clearBinding(args) {
+    const routingPath = projectChatRoutingPath(args.workspaceUuid, args.dataRoot);
+    await fs.mkdir(path.dirname(routingPath), { recursive: true });
+    await ensureRoutingFileExists(routingPath);
+    const release = await lockfile.lock(routingPath, {
+        retries: { retries: 8, factor: 1.5, minTimeout: 50, maxTimeout: 800 },
+        stale: 10_000,
+    });
+    try {
+        const existing = await loadProjectChatRouting(args.workspaceUuid, args.dataRoot);
+        if (!existing?.telegram?.auto_bound)
+            return false;
+        const staleTopicId = existing.telegram.auto_bound.topic_id;
+        const next = {
+            ...existing,
+            telegram: {
+                ...existing.telegram,
+                inbound_topic_ids: (existing.telegram.inbound_topic_ids ?? []).filter((t) => t !== staleTopicId),
+                auto_bound: undefined,
+            },
+        };
+        // Drop the auto_bound key entirely (don't leave `auto_bound: undefined`
+        // in the JSON output).
+        if (next.telegram)
+            delete next.telegram.auto_bound;
+        if (next.telegram?.inbound_topic_ids?.length === 0)
+            delete next.telegram.inbound_topic_ids;
+        await persistRoutingAtomic(routingPath, next);
+        return true;
+    }
+    finally {
+        await release();
+    }
+}
+/**
+ * Find the workspace whose `auto_bound` block claims the given
+ * (chat_id, topic_id) pair. Used by TPS.7 stale-topic recovery to
+ * locate which workspace owned a now-stale binding so we can
+ * `clearBinding` for the right uuid.
+ *
+ * Returns the workspace uuid on match, or null when:
+ *   - no project has an auto_bound block at all
+ *   - no auto_bound block matches BOTH chat_id and topic_id
+ *   - the matching project's routing config was already cleared by a
+ *     concurrent recovery (race-safe)
+ *
+ * Match rule: `auto_bound.topic_id === topicId` AND
+ *             `inbound_chat_ids.includes(chatId)`.
+ * The chat_id check guards against the (rare) case of identical topic_id
+ * numbers across two different supergroups; without it we could clear
+ * the wrong workspace's binding.
+ *
+ * Lock-free read: this just scans on-disk routing configs. The actual
+ * mutation (`clearBinding`) is lockfile-protected on the per-project
+ * routing file, so two concurrent recoveries racing to clear the same
+ * binding serialize cleanly — first wins, second sees no binding to
+ * clear and returns false.
+ */
+export async function findOwnerOfBinding(args) {
+    const all = await loadAllProjectChatRouting(args.dataRoot);
+    for (const [uuid, cfg] of all) {
+        const bound = cfg.telegram?.auto_bound;
+        if (!bound)
+            continue;
+        if (bound.topic_id !== args.topicId)
+            continue;
+        const inboundChats = cfg.telegram?.inbound_chat_ids ?? [];
+        if (!inboundChats.includes(args.chatId))
+            continue;
+        return uuid;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------
+async function ensureRoutingFileExists(routingPath) {
+    try {
+        await fs.access(routingPath);
+    }
+    catch {
+        await fs.writeFile(routingPath, "{}\n", { flag: "wx" }).catch((err) => {
+            // EEXIST is fine — another process touched it in the race window.
+            if (err.code !== "EEXIST")
+                throw err;
+        });
+    }
+}
+async function persistRoutingAtomic(routingPath, cfg) {
+    // Write to a sibling tmp + rename for atomicity (rename(2) is atomic
+    // on the same filesystem). Avoids partial-write reads from the daemon's
+    // 30s reload loop.
+    const tmp = `${routingPath}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    await fs.rename(tmp, routingPath);
+}
+function defaultRpcClient(dataRoot) {
+    // No cache: DaemonClient construction is cheap (just stores config)
+    // and caching it across calls broke tests that switch OPENSQUID_HOME
+    // per test. Construct fresh; pay the ~no-op cost. Pre-research
+    // verdict #7.
+    const { DaemonClient } = requireCJS("./rpc-client.js");
+    return new DaemonClient(dataRoot ? { dataRoot } : {});
+}
+/**
+ * Invariant check: if `auto_bound.topic_id` is set, it MUST appear in
+ * `inbound_topic_ids`. Pre-research verdict #9: log a warning on
+ * mismatch but do NOT auto-repair (preserves user-edited intent).
+ */
+function assertAutoBoundInvariant(cfg, routingPath) {
+    const bound = cfg?.telegram?.auto_bound;
+    if (!bound)
+        return;
+    const inboundTopics = cfg?.telegram?.inbound_topic_ids ?? [];
+    if (!inboundTopics.includes(bound.topic_id)) {
+        process.stderr.write(`[workspace-topic] invariant warning: auto_bound.topic_id=${bound.topic_id} not in inbound_topic_ids=${JSON.stringify(inboundTopics)} for ${routingPath}; not auto-repairing\n`);
+    }
+}
+async function recordOrphanTopic(dataRoot, record) {
+    // Pre-research verdict #6: log orphans to a recovery file so the
+    // user can clean up (delete the topic manually via Telegram client
+    // or via a future TPS.7 cleanup tool) instead of accumulating
+    // ghost topics on every retry. Doesn't try to delete the topic
+    // (that's a separate RPC call that could ALSO fail, compounding).
+    const root = dataRoot ?? process.env.OPENSQUID_HOME;
+    if (!root)
+        return; // best-effort: nowhere to write
+    const recoveryPath = path.join(root, "orphan-topics.jsonl");
+    try {
+        await fs.mkdir(path.dirname(recoveryPath), { recursive: true });
+        await fs.appendFile(recoveryPath, JSON.stringify(record) + "\n", "utf8");
+    }
+    catch {
+        // If even the recovery write fails, give up silently. The original
+        // persist error will propagate; that's the load-bearing surface.
+    }
+}