@0xmaxma/claude-gateway 1.7.10 → 1.8.0

package/dist/telegram/receiver.d.ts

@@ -13,7 +13,12 @@ export declare class TelegramReceiver {
     start(): void;
     private spawnProcess;
     private scheduleRestart;
-    stop(): void;
+    /**
+     * Stop the receiver and resolve only once the child has actually exited.
+     * Escalates SIGTERM → SIGKILL so a wedged child cannot outlive the gateway's
+     * shutdown. See issue #405.
+     */
+    stop(): Promise<void>;
     isRunning(): boolean;
 }
 //# sourceMappingURL=receiver.d.ts.map

package/dist/telegram/receiver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"receiver.d.ts","sourceRoot":"","sources":["../../src/telegram/receiver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AASvC,qBAAa,gBAAgB;IASzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAVzB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;gBAGtC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM;IAKjC,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,YAAY;IAgCpB,OAAO,CAAC,eAAe;IAuBvB,IAAI,IAAI,IAAI;IASZ,SAAS,IAAI,OAAO;CAGrB"}
+{"version":3,"file":"receiver.d.ts","sourceRoot":"","sources":["../../src/telegram/receiver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAUvC,qBAAa,gBAAgB;IASzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAVzB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;gBAGtC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM;IAKjC,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,YAAY;IAgCpB,OAAO,CAAC,eAAe;IAuBvB;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBrB,SAAS,IAAI,OAAO;CAGrB"}

package/dist/telegram/receiver.js

@@ -37,6 +37,7 @@ exports.TelegramReceiver = void 0;
 const child_process_1 = require("child_process");
 const path = __importStar(require("path"));
 const logger_1 = require("../logger");
+const stop_child_1 = require("../utils/stop-child");
 const AUTO_RESTART_DELAY_MS = 5000;
 const MAX_RESTARTS = 3;
 // After MAX_RESTARTS fast attempts, fall back to a slow indefinite retry
@@ -106,13 +107,20 @@ class TelegramReceiver {
                 this.spawnProcess();
         }, delay);
     }
+    /**
+     * Stop the receiver and resolve only once the child has actually exited.
+     * Escalates SIGTERM → SIGKILL so a wedged child cannot outlive the gateway's
+     * shutdown. See issue #405.
+     */
     stop() {
         this.stopping = true;
         if (this.restartTimer) {
             clearTimeout(this.restartTimer);
             this.restartTimer = null;
         }
-        this.process?.kill('SIGTERM');
+        return (0, stop_child_1.stopChildProcess)(this.process, {
+            onEscalate: (pid) => this.logger.warn(`TelegramReceiver did not exit within ${stop_child_1.STOP_GRACE_MS}ms of SIGTERM; sending SIGKILL`, { pid }),
+        });
     }
     isRunning() {
         return this.process !== null && !this.process.killed;

package/dist/telegram/receiver.js.map

@@ -1 +1 @@
-{"version":3,"file":"receiver.js","sourceRoot":"","sources":["../../src/telegram/receiver.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,iDAAoD;AACpD,2CAA6B;AAE7B,sCAAyC;AAEzC,MAAM,qBAAqB,GAAG,IAAK,CAAC;AACpC,MAAM,YAAY,GAAG,CAAC,CAAC;AACvB,yEAAyE;AACzE,kEAAkE;AAClE,MAAM,qBAAqB,GAAG,CAAC,GAAG,KAAM,CAAC;AAEzC,MAAa,gBAAgB;IAQ3B,YACmB,WAAwB,EACxB,YAAoB,EACpB,MAAc;QAFd,gBAAW,GAAX,WAAW,CAAa;QACxB,iBAAY,GAAZ,YAAY,CAAQ;QACpB,WAAM,GAAN,MAAM,CAAQ;QAVzB,YAAO,GAAwB,IAAI,CAAC;QACpC,aAAQ,GAAG,KAAK,CAAC;QACjB,iBAAY,GAAG,CAAC,CAAC;QACjB,uBAAkB,GAAG,KAAK,CAAC;QAC3B,iBAAY,GAAyC,IAAI,CAAC;QAQhE,IAAI,CAAC,MAAM,GAAG,IAAA,qBAAY,EAAC,GAAG,WAAW,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IACnE,CAAC;IAED,KAAK;QACH,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC;QAChC,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;IAEO,YAAY;QAClB,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,oBAAoB,CAAC,CAAC;QAC3G,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC;QAE1E,IAAI,CAAC,OAAO,GAAG,IAAA,qBAAK,EAAC,KAAK,EAAE,CAAC,YAAY,CAAC,EAAE;YAC1C,GAAG,EAAE;gBACH,GAAG,OAAO,CAAC,GAAG;gBACd,sBAAsB,EAAE,MAAM;gBAC9B,kBAAkB,EAAE,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,IAAI,EAAE;gBAC7D,kBAAkB,EAAE,QAAQ;gBAC5B,uBAAuB,EAAE,oBAAoB,IAAI,CAAC,YAAY,UAAU;aACzE;YACD,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAC5C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CACpE,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAC5C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAC5D,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YACvC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAC9D,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,QAAQ;gBAAE,IAAI,CAAC,eAAe,EAAE,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CACpE,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAC/C,CAAC;IAEO,eAAe;QACrB,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC;QACpD,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,qBAAqB,CAAC;QACxE,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,YAAY,EAAE,CAAC;QACpC,6EAA6E;QAC7E,6EAA6E;QAC7E,oDAAoD;QACpD,IAAI,SAAS,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC1C,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,2BAA2B,YAAY,iDAAiD,qBAAqB,0BAA0B,CACxI,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kCAAkC,KAAK,IAAI,EAAE;YAC5D,OAAO,EAAE,IAAI,CAAC,YAAY;YAC1B,SAAS;SACV,CAAC,CAAC;QACH,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC,GAAG,EAAE;YAClC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ;gBAAE,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1C,CAAC,EAAE,KAAK,CAAC,CAAC;IACZ,CAAC;IAED,IAAI;QACF,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAChC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IACvD,CAAC;CACF;AA1FD,4CA0FC"}
+{"version":3,"file":"receiver.js","sourceRoot":"","sources":["../../src/telegram/receiver.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,iDAAoD;AACpD,2CAA6B;AAE7B,sCAAyC;AACzC,oDAAsE;AAEtE,MAAM,qBAAqB,GAAG,IAAK,CAAC;AACpC,MAAM,YAAY,GAAG,CAAC,CAAC;AACvB,yEAAyE;AACzE,kEAAkE;AAClE,MAAM,qBAAqB,GAAG,CAAC,GAAG,KAAM,CAAC;AAEzC,MAAa,gBAAgB;IAQ3B,YACmB,WAAwB,EACxB,YAAoB,EACpB,MAAc;QAFd,gBAAW,GAAX,WAAW,CAAa;QACxB,iBAAY,GAAZ,YAAY,CAAQ;QACpB,WAAM,GAAN,MAAM,CAAQ;QAVzB,YAAO,GAAwB,IAAI,CAAC;QACpC,aAAQ,GAAG,KAAK,CAAC;QACjB,iBAAY,GAAG,CAAC,CAAC;QACjB,uBAAkB,GAAG,KAAK,CAAC;QAC3B,iBAAY,GAAyC,IAAI,CAAC;QAQhE,IAAI,CAAC,MAAM,GAAG,IAAA,qBAAY,EAAC,GAAG,WAAW,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IACnE,CAAC;IAED,KAAK;QACH,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC;QAChC,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;IAEO,YAAY;QAClB,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,oBAAoB,CAAC,CAAC;QAC3G,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC;QAE1E,IAAI,CAAC,OAAO,GAAG,IAAA,qBAAK,EAAC,KAAK,EAAE,CAAC,YAAY,CAAC,EAAE;YAC1C,GAAG,EAAE;gBACH,GAAG,OAAO,CAAC,GAAG;gBACd,sBAAsB,EAAE,MAAM;gBAC9B,kBAAkB,EAAE,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,IAAI,EAAE;gBAC7D,kBAAkB,EAAE,QAAQ;gBAC5B,uBAAuB,EAAE,oBAAoB,IAAI,CAAC,YAAY,UAAU;aACzE;YACD,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAC5C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CACpE,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAC5C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAC5D,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YACvC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAC9D,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,QAAQ;gBAAE,IAAI,CAAC,eAAe,EAAE,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CACpE,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAC/C,CAAC;IAEO,eAAe;QACrB,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC;QACpD,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,qBAAqB,CAAC;QACxE,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,YAAY,EAAE,CAAC;QACpC,6EAA6E;QAC7E,6EAA6E;QAC7E,oDAAoD;QACpD,IAAI,SAAS,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC1C,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,2BAA2B,YAAY,iDAAiD,qBAAqB,0BAA0B,CACxI,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kCAAkC,KAAK,IAAI,EAAE;YAC5D,OAAO,EAAE,IAAI,CAAC,YAAY;YAC1B,SAAS;SACV,CAAC,CAAC;QACH,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC,GAAG,EAAE;YAClC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ;gBAAE,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1C,CAAC,EAAE,KAAK,CAAC,CAAC;IACZ,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAChC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QAED,OAAO,IAAA,6BAAgB,EAAC,IAAI,CAAC,OAAO,EAAE;YACpC,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAClB,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,wCAAwC,0BAAa,gCAAgC,EACrF,EAAE,GAAG,EAAE,CACR;SACJ,CAAC,CAAC;IACL,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IACvD,CAAC;CACF;AAtGD,4CAsGC"}

package/dist/utils/orphan-receivers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Reclaim channel receiver processes left behind by a previous gateway.
+ *
+ * The gateway spawns one `bun .../mcp/tools/<channel>/receiver-server.ts` child
+ * per channel per agent. Those children only die if the gateway runs its
+ * shutdown path. Any exit that bypasses it — SIGKILL, the OOM killer, or (until
+ * issue #405) a SIGHUP — reparents them to init, where they keep polling with no
+ * supervisor to hand messages to and survive every subsequent restart.
+ *
+ * Handling more signals cannot fix SIGKILL or OOM, so a boot-time sweep is the
+ * only mechanism that can recover from those. See issue #405.
+ */
+export interface OrphanedReceiver {
+    pid: number;
+    /** Full argv of the orphan, for logging. */
+    command: string;
+}
+/** Injectable so tests can drive the sweep without real processes. */
+export interface SweepDeps {
+    listProcesses?: () => Promise<string>;
+    kill?: (pid: number, signal: NodeJS.Signals) => void;
+    wait?: (ms: number) => Promise<void>;
+}
+export interface SweepResult {
+    /** Orphans that are gone as a result of this sweep. */
+    reclaimed: OrphanedReceiver[];
+    /** Orphans that ignored SIGTERM and had to be SIGKILLed. */
+    forced: number[];
+    /**
+     * Orphans that could NOT be terminated — most realistically EPERM, when a
+     * previous gateway ran under a different account or under sudo. Reported
+     * separately so the boot log never claims to have reclaimed a process that is
+     * still alive and still polling its bot token.
+     */
+    failed: Array<{
+        pid: number;
+        reason: string;
+    }>;
+}
+/**
+ * Grace period between SIGTERM and SIGKILL for an orphan.
+ *
+ * Must stay comfortably above the receivers' own exit deadline — both
+ * `mcp/tools/discord/receiver-server.ts` and `mcp/tools/telegram/receiver-server.ts`
+ * force-exit on a 2000ms timer after SIGTERM, and Discord's is unconditional. A
+ * 2000ms grace would be a dead heat, so healthy receivers would routinely be
+ * SIGKILLed and counted as wedged, making the "needed SIGKILL" figure useless as
+ * a signal.
+ */
+export declare const ORPHAN_SIGKILL_GRACE_MS = 5000;
+/**
+ * Find receiver processes spawned from `receiverToolsDir` that have been
+ * reparented to init.
+ *
+ * Both conditions are load-bearing:
+ *
+ * - `ppid === 1` proves the supervising gateway is *gone*. A receiver owned by a
+ *   live gateway always has that gateway's pid as its parent, including when the
+ *   gateway itself is a systemd service whose own ppid is 1. So this never
+ *   matches a receiver another running gateway still owns.
+ *
+ *   Caveat: on a host where an ancestor has called `prctl(PR_SET_CHILD_SUBREAPER)`
+ *   — `systemd --user` for user services, `docker run --init` / tini, s6 —
+ *   orphans reparent to that subreaper rather than to pid 1, and this sweep finds
+ *   nothing. The gateway still shuts down cleanly there (gap 1 covers the signal
+ *   paths); what is lost is the SIGKILL/OOM recovery, and such a host has a
+ *   supervisor that generally reaps the process group itself.
+ *
+ * - The argv must *execute* the receiver from this installation's own tools
+ *   directory. Matching is on argv tokens in the exact shape the receivers are
+ *   spawned with (`bun <toolsDir>/<channel>/receiver-server.ts`) rather than a
+ *   substring test, so a detached `grep -r receiver-server.ts <toolsDir>/`, an
+ *   editor, or a `bun test` over the same file is not mistaken for a receiver and
+ *   killed. `tests/unit/receiver-stop-teardown.test.ts` pins this shape against
+ *   the receivers' real spawn arguments.
+ */
+export declare function findOrphanedReceivers(psOutput: string, receiverToolsDir: string): OrphanedReceiver[];
+/**
+ * Terminate every orphaned receiver spawned from `receiverToolsDir`.
+ *
+ * Escalates SIGTERM → SIGKILL so a receiver wedged in an in-flight long-poll
+ * cannot survive the sweep.
+ *
+ * Rejects if the process list cannot be read at all — the caller must decide
+ * whether that is fatal (it is not: boot continues, loudly). Once the sweep is
+ * under way it stops throwing, and anything it could not terminate is reported
+ * in `failed` rather than silently counted as reclaimed.
+ */
+export declare function sweepOrphanedReceivers(receiverToolsDir: string, deps?: SweepDeps): Promise<SweepResult>;
+//# sourceMappingURL=orphan-receivers.d.ts.map

package/dist/utils/orphan-receivers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphan-receivers.d.ts","sourceRoot":"","sources":["../../src/utils/orphan-receivers.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;IACrD,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,4DAA4D;IAC5D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;OAKG;IACH,MAAM,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AA+B7C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAqBpG;AAqBD;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,gBAAgB,EAAE,MAAM,EACxB,IAAI,GAAE,SAAc,GACnB,OAAO,CAAC,WAAW,CAAC,CAwDtB"}

package/dist/utils/orphan-receivers.js

@@ -0,0 +1,218 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORPHAN_SIGKILL_GRACE_MS = void 0;
+exports.findOrphanedReceivers = findOrphanedReceivers;
+exports.sweepOrphanedReceivers = sweepOrphanedReceivers;
+const child_process_1 = require("child_process");
+const path = __importStar(require("path"));
+/**
+ * Grace period between SIGTERM and SIGKILL for an orphan.
+ *
+ * Must stay comfortably above the receivers' own exit deadline — both
+ * `mcp/tools/discord/receiver-server.ts` and `mcp/tools/telegram/receiver-server.ts`
+ * force-exit on a 2000ms timer after SIGTERM, and Discord's is unconditional. A
+ * 2000ms grace would be a dead heat, so healthy receivers would routinely be
+ * SIGKILLed and counted as wedged, making the "needed SIGKILL" figure useless as
+ * a signal.
+ */
+exports.ORPHAN_SIGKILL_GRACE_MS = 5000;
+const defaultListProcesses = () => new Promise((resolve, reject) => {
+    // `pid=,ppid=,args=` suppresses the header, so every line is a record.
+    // `-ww` disables width truncation: a clipped argv would silently stop
+    // matching the tools-directory prefix and reclaim nothing.
+    (0, child_process_1.execFile)('ps', ['-ww', '-eo', 'pid=,ppid=,args='], { maxBuffer: 8 * 1024 * 1024 }, (err, stdout) => {
+        if (err)
+            reject(err);
+        else
+            resolve(stdout);
+    });
+});
+const defaultKill = (pid, signal) => {
+    process.kill(pid, signal);
+};
+const defaultWait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** ESRCH means the process is already gone — the one "failure" that is a success. */
+function isAlreadyGone(err) {
+    return err?.code === 'ESRCH';
+}
+function describeKillError(err) {
+    const e = err;
+    if (e?.code === 'EPERM')
+        return 'EPERM (owned by another user)';
+    return e?.code ?? (e instanceof Error ? e.message : String(err));
+}
+/**
+ * Find receiver processes spawned from `receiverToolsDir` that have been
+ * reparented to init.
+ *
+ * Both conditions are load-bearing:
+ *
+ * - `ppid === 1` proves the supervising gateway is *gone*. A receiver owned by a
+ *   live gateway always has that gateway's pid as its parent, including when the
+ *   gateway itself is a systemd service whose own ppid is 1. So this never
+ *   matches a receiver another running gateway still owns.
+ *
+ *   Caveat: on a host where an ancestor has called `prctl(PR_SET_CHILD_SUBREAPER)`
+ *   — `systemd --user` for user services, `docker run --init` / tini, s6 —
+ *   orphans reparent to that subreaper rather than to pid 1, and this sweep finds
+ *   nothing. The gateway still shuts down cleanly there (gap 1 covers the signal
+ *   paths); what is lost is the SIGKILL/OOM recovery, and such a host has a
+ *   supervisor that generally reaps the process group itself.
+ *
+ * - The argv must *execute* the receiver from this installation's own tools
+ *   directory. Matching is on argv tokens in the exact shape the receivers are
+ *   spawned with (`bun <toolsDir>/<channel>/receiver-server.ts`) rather than a
+ *   substring test, so a detached `grep -r receiver-server.ts <toolsDir>/`, an
+ *   editor, or a `bun test` over the same file is not mistaken for a receiver and
+ *   killed. `tests/unit/receiver-stop-teardown.test.ts` pins this shape against
+ *   the receivers' real spawn arguments.
+ */
+function findOrphanedReceivers(psOutput, receiverToolsDir) {
+    const toolsDir = path.resolve(receiverToolsDir);
+    const found = [];
+    for (const line of psOutput.split('\n')) {
+        // `pid ppid args...` — args may contain spaces, so split off only the first two.
+        const match = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        const ppid = Number(match[2]);
+        const command = match[3].trim();
+        if (ppid !== 1)
+            continue;
+        if (pid === process.pid)
+            continue;
+        if (!isReceiverInvocation(command, toolsDir))
+            continue;
+        found.push({ pid, command });
+    }
+    return found;
+}
+/**
+ * True when `command` is the gateway spawning a receiver of its own — i.e.
+ * `bun <toolsDir>/<channel>/receiver-server.ts`, the script as the runtime's
+ * first argument, with exactly one directory level for the channel.
+ */
+function isReceiverInvocation(command, toolsDir) {
+    const tokens = command.split(/\s+/);
+    if (tokens.length < 2)
+        return false;
+    if (path.basename(tokens[0]) !== 'bun')
+        return false;
+    const script = tokens[1];
+    const relative = path.relative(toolsDir, script);
+    // Outside the tools directory (`..`) or on another root (absolute) — not ours.
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        return false;
+    const segments = relative.split(path.sep);
+    return segments.length === 2 && segments[1] === 'receiver-server.ts';
+}
+/**
+ * Terminate every orphaned receiver spawned from `receiverToolsDir`.
+ *
+ * Escalates SIGTERM → SIGKILL so a receiver wedged in an in-flight long-poll
+ * cannot survive the sweep.
+ *
+ * Rejects if the process list cannot be read at all — the caller must decide
+ * whether that is fatal (it is not: boot continues, loudly). Once the sweep is
+ * under way it stops throwing, and anything it could not terminate is reported
+ * in `failed` rather than silently counted as reclaimed.
+ */
+async function sweepOrphanedReceivers(receiverToolsDir, deps = {}) {
+    const listProcesses = deps.listProcesses ?? defaultListProcesses;
+    const kill = deps.kill ?? defaultKill;
+    const wait = deps.wait ?? defaultWait;
+    const orphans = findOrphanedReceivers(await listProcesses(), receiverToolsDir);
+    if (orphans.length === 0)
+        return { reclaimed: [], forced: [], failed: [] };
+    const failed = new Map();
+    for (const orphan of orphans) {
+        try {
+            kill(orphan.pid, 'SIGTERM');
+        }
+        catch (err) {
+            // ESRCH: it exited between the listing and now — already reclaimed.
+            // Anything else (EPERM in practice) means we cannot touch it at all.
+            if (!isAlreadyGone(err))
+                failed.set(orphan.pid, describeKillError(err));
+        }
+    }
+    await wait(exports.ORPHAN_SIGKILL_GRACE_MS);
+    // Re-list before escalating. A pid freed by SIGTERM can be recycled by an
+    // unrelated process within the grace period, and SIGKILLing that would be a
+    // far worse bug than the one being fixed — so only pids that are STILL a
+    // matching orphan are escalated, not merely pids that still exist.
+    let survivors;
+    try {
+        survivors = new Set(findOrphanedReceivers(await listProcesses(), receiverToolsDir).map((o) => o.pid));
+    }
+    catch (err) {
+        // The second listing failed even though the first succeeded. Skipping
+        // escalation leaves a wedged receiver alive, which the next boot will retry;
+        // guessing from stale pids could kill an unrelated process. Prefer the
+        // recoverable failure — but report the survivors as unreclaimed, not as won.
+        const reason = `escalation skipped: ${err.message}`;
+        for (const orphan of orphans) {
+            if (!failed.has(orphan.pid))
+                failed.set(orphan.pid, reason);
+        }
+        return finish(orphans, [], failed);
+    }
+    const forced = [];
+    for (const orphan of orphans) {
+        if (failed.has(orphan.pid))
+            continue; // could not be signalled at all
+        if (!survivors.has(orphan.pid))
+            continue; // exited on SIGTERM, as expected
+        try {
+            kill(orphan.pid, 'SIGKILL');
+            forced.push(orphan.pid);
+        }
+        catch (err) {
+            if (!isAlreadyGone(err))
+                failed.set(orphan.pid, describeKillError(err));
+        }
+    }
+    return finish(orphans, forced, failed);
+}
+function finish(orphans, forced, failed) {
+    return {
+        reclaimed: orphans.filter((o) => !failed.has(o.pid)),
+        forced,
+        failed: [...failed].map(([pid, reason]) => ({ pid, reason })),
+    };
+}
+//# sourceMappingURL=orphan-receivers.js.map

package/dist/utils/orphan-receivers.js.map

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

package/dist/utils/paths.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Expand a leading `~` to the home directory.
+ *
+ * A `~` reaches the gateway unexpanded whenever a path is not read through a
+ * shell: config files (`gateway.logDir` is written as `~/.claude-gateway/logs`
+ * by the shipped template), environment variables set in a unit file or a
+ * Dockerfile, and `--flag` values. Leaving it literal turns into an ENOENT that
+ * reads like "the directory is empty" rather than "the path was never
+ * resolved" — the shape of the `debug-bundle` bug found in review.
+ *
+ * There were four copies of this, on both the server and the CLI side. This
+ * module has no imports beyond `os`/`path` precisely so the server entry point
+ * can use it without pulling in the CLI.
+ */
+export declare function expandHome(p: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/utils/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI5C"}

package/dist/utils/paths.js

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandHome = expandHome;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * Expand a leading `~` to the home directory.
+ *
+ * A `~` reaches the gateway unexpanded whenever a path is not read through a
+ * shell: config files (`gateway.logDir` is written as `~/.claude-gateway/logs`
+ * by the shipped template), environment variables set in a unit file or a
+ * Dockerfile, and `--flag` values. Leaving it literal turns into an ENOENT that
+ * reads like "the directory is empty" rather than "the path was never
+ * resolved" — the shape of the `debug-bundle` bug found in review.
+ *
+ * There were four copies of this, on both the server and the CLI side. This
+ * module has no imports beyond `os`/`path` precisely so the server entry point
+ * can use it without pulling in the CLI.
+ */
+function expandHome(p) {
+    if (p === '~')
+        return os.homedir();
+    if (p.startsWith('~/'))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+//# sourceMappingURL=paths.js.map

package/dist/utils/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBA,gCAIC;AArBD,uCAAyB;AACzB,2CAA6B;AAE7B;;;;;;;;;;;;;GAaG;AACH,SAAgB,UAAU,CAAC,CAAS;IAClC,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACnC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/utils/stop-child.d.ts

@@ -0,0 +1,21 @@
+import { ChildProcess } from 'child_process';
+/** How long a supervised child gets to exit on SIGTERM before it is SIGKILLed. */
+export declare const STOP_GRACE_MS = 5000;
+export interface StopChildOptions {
+    /** Milliseconds to wait for a clean exit before escalating. */
+    graceMs?: number;
+    /** Called just before SIGKILL, so the caller can log with its own identity. */
+    onEscalate?: (pid: number | undefined) => void;
+}
+/**
+ * Terminate a supervised child and resolve only once it has actually exited.
+ *
+ * A bare `kill('SIGTERM')` is not enough: a receiver blocked in an in-flight
+ * long-poll can sit in its own handler indefinitely, and the caller had no way to
+ * know. Escalating to SIGKILL after a bounded grace period guarantees the child
+ * cannot outlive the gateway's shutdown. See issue #405.
+ *
+ * Never rejects — a shutdown path must not be derailed by a teardown failure.
+ */
+export declare function stopChildProcess(proc: ChildProcess | null, opts?: StopChildOptions): Promise<void>;
+//# sourceMappingURL=stop-child.d.ts.map

package/dist/utils/stop-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-child.d.ts","sourceRoot":"","sources":["../../src/utils/stop-child.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,kFAAkF;AAClF,eAAO,MAAM,aAAa,OAAQ,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;CAChD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,YAAY,GAAG,IAAI,EACzB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Cf"}

package/dist/utils/stop-child.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOP_GRACE_MS = void 0;
+exports.stopChildProcess = stopChildProcess;
+/** How long a supervised child gets to exit on SIGTERM before it is SIGKILLed. */
+exports.STOP_GRACE_MS = 5000;
+/**
+ * Terminate a supervised child and resolve only once it has actually exited.
+ *
+ * A bare `kill('SIGTERM')` is not enough: a receiver blocked in an in-flight
+ * long-poll can sit in its own handler indefinitely, and the caller had no way to
+ * know. Escalating to SIGKILL after a bounded grace period guarantees the child
+ * cannot outlive the gateway's shutdown. See issue #405.
+ *
+ * Never rejects — a shutdown path must not be derailed by a teardown failure.
+ */
+function stopChildProcess(proc, opts = {}) {
+    if (!proc)
+        return Promise.resolve();
+    const graceMs = opts.graceMs ?? exports.STOP_GRACE_MS;
+    return new Promise((resolve) => {
+        // An already-exited child never emits another 'exit', and `kill()` on it
+        // returns false *without throwing* (Node has cleared its handle) — so the
+        // catch below would not fire and the promise would idle for the whole grace
+        // period before "escalating" with a SIGKILL that does nothing.
+        //
+        // Loose `!= null` is deliberate: a real ChildProcess always exposes both
+        // fields as null while running, but anything that does not expose them at
+        // all must be treated as ALIVE and signalled, never assumed dead and
+        // silently skipped. Failing safe here means attempting the kill.
+        if (proc.exitCode != null || proc.signalCode != null) {
+            resolve();
+            return;
+        }
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(killTimer);
+            resolve();
+        };
+        const killTimer = setTimeout(() => {
+            opts.onEscalate?.(proc.pid);
+            // SIGKILL is delivered by the kernel whether or not we stay alive to
+            // observe the exit, so resolving here cannot leave the child running.
+            try {
+                proc.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+            finish();
+        }, graceMs);
+        proc.once('exit', finish);
+        // Returns false rather than throwing if the child died in the moment before
+        // this line; the exit event that clears the handle also settles us.
+        try {
+            proc.kill('SIGTERM');
+        }
+        catch {
+            finish();
+        }
+    });
+}
+//# sourceMappingURL=stop-child.js.map

package/dist/utils/stop-child.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-child.js","sourceRoot":"","sources":["../../src/utils/stop-child.ts"],"names":[],"mappings":";;;AAsBA,4CAgDC;AApED,kFAAkF;AACrE,QAAA,aAAa,GAAG,IAAK,CAAC;AASnC;;;;;;;;;GASG;AACH,SAAgB,gBAAgB,CAC9B,IAAyB,EACzB,OAAyB,EAAE;IAE3B,IAAI,CAAC,IAAI;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,qBAAa,CAAC;IAE9C,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,yEAAyE;QACzE,0EAA0E;QAC1E,4EAA4E;QAC5E,+DAA+D;QAC/D,EAAE;QACF,yEAAyE;QACzE,0EAA0E;QAC1E,qEAAqE;QACrE,iEAAiE;QACjE,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC;YACrD,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QAED,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,GAAG,EAAE;YAClB,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,SAAS,CAAC,CAAC;YACxB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QAEF,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;YAChC,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5B,qEAAqE;YACrE,sEAAsE;YACtE,IAAI,CAAC;gBAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;YAC1D,MAAM,EAAE,CAAC;QACX,CAAC,EAAE,OAAO,CAAC,CAAC;QAEZ,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC1B,4EAA4E;QAC5E,oEAAoE;QACpE,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,EAAE,CAAC;QACX,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/lib/pairing.ts

@@ -1,5 +1,5 @@
 /**
- * Shared pairing primitives for both scripts/create-agent.ts and mcp/tools/agent/handlers.ts.
+ * Shared pairing primitives for mcp/tools/agent/handlers.ts.
  * Uses fetch (available in Node 18+ and Bun) — no https module dependency.
  */
 

package/mcp/tools/agent/handlers.ts

@@ -26,7 +26,7 @@ const FENCE_CLOSE_REGEX = /^```$/;
 const STANDARD_STUB_FILES = ['HEARTBEAT.md', 'MEMORY.md', 'SOUL.md', 'USER.md'];
 
 // ---------------------------------------------------------------------------
-// Path helpers (local copies — same as scripts/create-agent.ts)
+// Path helpers
 // ---------------------------------------------------------------------------
 
 export function expandHome(p: string): string {

package/mcp/tools/discord/receiver-server.ts

@@ -21,6 +21,10 @@ async function postCallback(inbound: InboundMessage): Promise<void> {
     user: inbound.senderId,
     message_id: inbound.messageId ?? '',
     ts: new Date(inbound.ts).toISOString(),
+    // 'direct' | 'group'. The gateway gates agent-global commands on this:
+    // Discord's guild gate checks guild/channel/mention but never the user, so
+    // a command that changes state for every chat must be DM-only.
+    chat_type: inbound.chatType,
   };
 
   if (inbound.attachmentFileId) {

package/mcp/tools/telegram/receiver-server.ts

@@ -878,10 +878,12 @@ const BOT_COMMANDS = [
   { command: 'help', description: 'What this bot can do' },
 ]
 
-// Available AI models for /models command. Fallback only — the picker normally
-// uses the live list from the gateway (get_models); this is shown if that call
-// fails. Keep in sync with DEFAULT_MODELS (src/agent/runner.ts) and
-// config.template.json gateway.models.
+// Available AI models for /models command. Last-resort fallback: the picker
+// normally uses get_models, which itself resolves the live catalog and only
+// then falls back to config.json's gateway.models (issue #409). This copy is
+// reached only when the gateway call itself fails, so it is two fallbacks deep
+// and will drift — keep it roughly in step with DEFAULT_MODELS
+// (src/agent/runner.ts) and config.template.json gateway.models.
 const AVAILABLE_MODELS = [
   { id: 'claude-fable-5[1m]',        label: 'Fable 5 (1M)',     alias: 'fable[1m]' },
   { id: 'claude-opus-5[1m]',         label: 'Opus 5 (1M)',      alias: 'opus[1m]' },