@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.2

package/dist/channels/supervisor.js

@@ -1,8 +1,28 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 import { randomUUID } from "node:crypto";
+import { CHANNEL_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { secretValues } from "../config/fields.js";
 import { enabledExtensionsByOrg } from "../extensions/enabled.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { ReplicaStatusStore } from "../extensions/sources.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { KERNEL_BUS, KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
 import { createRedactor } from "../log.js";
-import { CHANNEL_CHANGED_TOPIC, channelBackoffKey, channelFailsKey, } from "./connections.service.js";
+import { CHANNEL_CHANGED_TOPIC, ChannelConnections, channelBackoffKey, channelFailsKey, } from "./connections.service.js";
+import { ChannelInbound } from "./inbound.js";
+import { GATEWAY_CHECK_JOB } from "./job-ids.js";
 /** 长连接租约键（内核锁）：值为持有方的随机 token。 */
 export const channelLeaseKey = (connectionId) => `capk:channel-lease:${connectionId}`;
 /**
@@ -43,12 +63,6 @@ const FAILS_TTL_SECONDS = 3600;
 const SETTLE_MS = 5_000;
 /** `last_error` 的最大长度。 */
 const MAX_ERROR_CHARS = 1000;
-const RENEW = `
-if redis.call('GET', KEYS[1]) == ARGV[1] then
-  return redis.call('PEXPIRE', KEYS[1], ARGV[2])
-end
-return 0
-`;
 /**
  * Heartbeat with the Redis server clock (replica wall clocks may drift): for each key, ZADD the
  * member, trim members older than one TTL and refresh the key's expiry. KEYS = heartbeat keys to
@@ -92,39 +106,42 @@ export async function liveGateways(redis, plugins, ttlMs) {
     });
     return out;
 }
-const RELEASE = `
-if redis.call('GET', KEYS[1]) == ARGV[1] then
-  return redis.call('DEL', KEYS[1])
-end
-return 0
-`;
 const errMsg = (e) => (e instanceof Error ? e.message : String(e));
 /**
- * 渠道长连接选主（runs only on the gateway role）。每个副本两个各自独立的循环，周期都是 `channels.scanIntervalMs`（默认 10s）：
- * - 续租循环：为本进程持有的连接续租（`capk:channel-lease:<id>`，TTL `channels.leaseTtlMs` 默认 30s）。
- *   它不做任何可能慢的事（不等交还、不查库），一个插件迟迟不退出不会拖慢其他连接的续租。
+ * 渠道长连接选主（runs only on the gateway role: a provider of `GatewayModule`, started and stopped by
+ * `KernelLifecycle` through `GatewayRole` after the extension load）。每个副本两个各自独立的循环，周期都是 `channels.scanIntervalMs`（默认 10s）：
+ * - 心跳循环：写本副本的 gateway 心跳，再为本进程持有的连接续一次租。它不做任何可能慢的事（不等交还、不查库），
+ *   一个插件迟迟不退出不会拖慢其他连接的续租。
  * - 扫描循环：复核持有的连接仍为 active、未删除且插件在该组织启用（不满足就交还，交还不阻塞本轮），
- *   再扫描无人持有的这类连接，`SET NX PX` 取到租约的副本调用插件 `connect`（传 `signal`）。
- * 续租失败（租约已丢）→ 立即中止，不释放（已不是自己的）；Redis 出错时，自上次续租成功起满 `TTL - 扫描周期`
- * 仍续不上就按丢失处理（赶在租约可能被别的副本拿走之前断开）。连接被停用 / 删除 / 改配置（内核 bus `channel.changed`，
- * 或扫描时复核发现）→ 中止、等 `connect` 返回后释放租约，下一轮任一副本按新配置重连；取得租约到 `connect` 开始之间
+ *   再扫描无人持有的这类连接，取到租约（`LockService.hold`）的副本调用插件 `connect`（传 `signal`）。
+ * The lease `capk:channel-lease:<id>` (value: this replica's random token, TTL
+ * `channels.leaseTtlMs`, default 30 s) is renewed by `LockService` (every TTL/3, plus once in the
+ * heartbeat loop). A lost lease (overwritten or expired, or no successful renewal by the renewal
+ * deadline) aborts at once and is not released (it is no longer ours).
+ * 连接被停用 / 删除 / 改配置（内核 bus `channel.changed`，或扫描时复核发现）→ 中止、等 `connect` 返回后释放租约，下一轮任一副本按新配置重连；取得租约到 `connect` 开始之间
  * 收到的重连广播会被记下，开始后立即交还。
  * `connect` 抛错或提前返回 → 记 `last_error`，在 Redis 写退避标记（指数退避，上限 5 分钟），释放租约后由任一副本重试。
- * Fair share (E11-B): the renewal loop also writes this replica's heartbeat into `capk:gateway-replicas`;
+ * Fair share (E11-B): the heartbeat loop writes this replica's heartbeat into `capk:gateway-replicas`;
  * each scan computes this replica's target from the runnable count and the live replicas
  * (`shareTarget`), stops claiming at the target and, when above it, gives back one connection per
  * round (the most recently connected) with a handoff marker. Exactly one holder per connection is
  * still guaranteed by the lease alone; the share only decides who claims.
- * 停机时中止全部长连接并释放租约，并等进行中的 `onEvent`（入队）结束。持有的长连接、租约 token 与定时器都是「本进程持有的资源」，
+ * 停机时中止全部长连接并释放租约，并等进行中的 `onEvent`（入队）结束。持有的长连接、租约与定时器都是「本进程持有的资源」，
  * 跨副本的状态（租约、退避、失败计数）都在 Redis。
  */
-export class ChannelSupervisor {
-    deps;
+let ChannelSupervisor = class ChannelSupervisor {
+    db;
+    redis;
+    bus;
+    locks;
+    connections;
+    registry;
+    inbound;
+    config;
+    log;
     held = new Map();
     /** 已取得租约、正在读配置准备 `connect` 的连接；值为期间是否收到了重连广播。 */
     connecting = new Map();
-    /** 正在交还（已中止、等 `connect` 返回）的连接 → 租约 token：等待期间照常续租，交还完成才释放。 */
-    settling = new Map();
     /** 进行中的交还（`stop()` 要等它们全部结束）。 */
     releasing = new Set();
     /** 进行中的 `onEvent`（去重 + 入队，很快）：`stop()` 等它们结束，插件才不会在内核关闭队列之后才拿到结果。 */
@@ -139,11 +156,38 @@ export class ChannelSupervisor {
     heartbeated = new Set();
     /** A claim-only scan is queued and has not started yet: further nudges until then are dropped. */
     claimQueued = false;
-    constructor(deps) {
-        this.deps = deps;
+    /**
+     * This process's replica id (`ReplicaStatusStore.replicaId`), the member of the gateway heartbeat
+     * ZSET. Not `http.replicaId`, which is optional and may repeat across replicas.
+     */
+    replicaId;
+    /** Called at the start of every scan round (`claimOnly` for handoff nudges); for tests / metrics. */
+    onScan;
+    constructor(db, redis, bus, locks, connections, 
+    /** The channel extensions loaded in this process (`channel@1` providers). */
+    registry, 
+    /** Events from a plugin's `connect` (dedupe and enqueue; ack after it resolves). */
+    inbound, config, log, replicaStatus) {
+        this.db = db;
+        this.redis = redis;
+        this.bus = bus;
+        this.locks = locks;
+        this.connections = connections;
+        this.registry = registry;
+        this.inbound = inbound;
+        this.config = config;
+        this.log = log;
+        this.replicaId = replicaStatus.replicaId;
+    }
+    /** 本进程已加载、提供 `channel@1` 的插件名。 */
+    localPlugins() {
+        return this.registry
+            .list("channel")
+            .filter((e) => e.capability === CHANNEL_EXTENSION_POINT)
+            .map((e) => e.plugin);
     }
     async start() {
-        this.unsubscribe = await this.deps.bus.subscribe(CHANNEL_CHANGED_TOPIC, (payload) => {
+        this.unsubscribe = await this.bus.subscribe(CHANNEL_CHANGED_TOPIC, (payload) => {
             const m = payload;
             const id = m?.connectionId;
             if (m?.reconnect !== true || typeof id !== "string")
@@ -160,20 +204,20 @@ export class ChannelSupervisor {
         // round. Claim only (no hand-back), so hand-backs stay at one per plugin per scan round.
         // Nudges coalesce: at most one claim-only scan waits behind the one running; nudges for a
         // plugin not loaded here are ignored.
-        this.unsubscribeHandoff = await this.deps.bus.subscribe(CHANNEL_HANDOFF_TOPIC, (payload) => {
+        this.unsubscribeHandoff = await this.bus.subscribe(CHANNEL_HANDOFF_TOPIC, (payload) => {
             const m = payload;
-            if (this.stopped || m?.replicaId === this.deps.replicaId || this.claimQueued)
+            if (this.stopped || m?.replicaId === this.replicaId || this.claimQueued)
                 return;
-            if (typeof m?.plugin !== "string" || !this.deps.localPlugins().includes(m.plugin))
+            if (typeof m?.plugin !== "string" || !this.localPlugins().includes(m.plugin))
                 return;
             this.claimQueued = true;
             const run = this.exclusive(() => {
                 this.claimQueued = false;
                 return this.scan(true);
             });
-            this.track(run).catch((err) => this.deps.log.error("channel supervisor scan failed", { err }));
+            this.track(run).catch((err) => this.log.error("channel supervisor scan failed", { err }));
         });
-        this.loop("renew", () => this.renewAll());
+        this.loop("heartbeat", () => this.heartbeatRound());
         this.loop("scan", () => this.exclusive(async () => {
             await this.recheckHeld();
             if (!this.stopped)
@@ -195,40 +239,34 @@ export class ChannelSupervisor {
                 return;
             st.timer = setTimeout(() => {
                 st.running = fn()
-                    .catch((err) => this.deps.log.error(`channel supervisor ${name} failed`, { err }))
+                    .catch((err) => this.log.error(`channel supervisor ${name} failed`, { err }))
                     .finally(() => {
                     st.running = undefined;
-                    run(this.deps.config().channels.scanIntervalMs);
+                    run(this.config.get().channels.scanIntervalMs);
                 });
             }, ms);
             st.timer.unref?.();
         };
         run(0);
     }
-    async renewAll() {
-        const { leaseTtlMs: ttl, scanIntervalMs } = this.deps.config().channels;
-        // Heartbeat before renewing: a crashed replica's heartbeat then goes stale no later than its
-        // leases expire, so the survivors' share already excludes it when those connections free up
+    /**
+     * One heartbeat round: the heartbeat first, then one renewal of every lease held (on top of
+     * `LockService`'s own), so a crashed replica's heartbeat goes stale no later than its leases
+     * expire and the survivors' share already excludes it when those connections free up.
+     */
+    async heartbeatRound() {
+        const ttl = this.config.get().channels.leaseTtlMs;
         await this.heartbeat(ttl);
         await Promise.all([...this.held].map(async ([id, h]) => {
-            let ok;
-            try {
-                ok =
-                    Number(await this.deps.redis.eval(RENEW, 1, channelLeaseKey(id), h.token, ttl)) === 1;
-            }
-            catch (err) {
-                // Redis 暂时不可用：再等一轮就可能超过 TTL（租约在别的副本眼里已过期），提前按丢失处理
-                this.deps.log.warn("channel lease renew failed", { connectionId: id, err });
-                ok = Date.now() - h.renewedAt < ttl - scanIntervalMs;
-                if (ok)
-                    return;
-            }
-            await this.afterRenew(id, h, ok, ttl);
+            // false marks the lease lost (`lost` aborts, the connection drops); a Redis error is the
+            // watchdog's to log and judge (lost at the renewal deadline)
+            const ok = await h.lease.renew().catch(() => undefined);
+            if (ok === true)
+                await this.afterRenew(id, h, ttl);
+            // false: the key is gone or taken, or the lease was already lost (`drop` is idempotent)
+            else if (ok === false)
+                this.drop(id, h);
         }));
-        // 交还中的连接：插件还没退出，租约不能在别的副本眼里过期（否则两边同时在线）；续不上就算了（已不是自己的）
-        await Promise.all([...this.settling].map(([id, token]) => this.deps.redis.eval(RENEW, 1, channelLeaseKey(id), token, ttl).catch((err) => {
-            this.deps.log.warn("channel lease renew failed", { connectionId: id, err });
-        })));
     }
     /**
      * Writes this replica's heartbeat into the ZSET of every channel plugin loaded here (trimming
@@ -238,16 +276,16 @@ export class ChannelSupervisor {
     async heartbeat(ttl) {
         if (this.stopped)
             return;
-        const plugins = [...new Set(this.deps.localPlugins())];
+        const plugins = [...new Set(this.localPlugins())];
         const gone = [...this.heartbeated].filter((p) => !plugins.includes(p));
         if (plugins.length === 0 && gone.length === 0)
             return;
         try {
-            await this.deps.redis.eval(HEARTBEAT, plugins.length, ...plugins.map(gatewayReplicasKey), this.deps.replicaId, ttl, ...gone.map(gatewayReplicasKey));
+            await this.redis.eval(HEARTBEAT, plugins.length, ...plugins.map(gatewayReplicasKey), this.replicaId, ttl, ...gone.map(gatewayReplicasKey));
             this.heartbeated = new Set(plugins);
         }
         catch (err) {
-            this.deps.log.warn("gateway heartbeat failed", { err });
+            this.log.warn("gateway heartbeat failed", { err });
         }
     }
     /**
@@ -256,13 +294,13 @@ export class ChannelSupervisor {
      * written yet on the first round).
      */
     async targets(runnable) {
-        const { leaseTtlMs: ttl, shareSlack } = this.deps.config().channels;
+        const { leaseTtlMs: ttl, shareSlack } = this.config.get().channels;
         const plugins = [...runnable.keys()];
-        const live = await liveGateways(this.deps.redis, plugins, ttl);
+        const live = await liveGateways(this.redis, plugins, ttl);
         const out = new Map();
         for (const p of plugins) {
-            const members = [...new Set([...(live.get(p) ?? []), this.deps.replicaId])].sort();
-            const rank = members.indexOf(this.deps.replicaId);
+            const members = [...new Set([...(live.get(p) ?? []), this.replicaId])].sort();
+            const rank = members.indexOf(this.replicaId);
             out.set(p, shareTarget(runnable.get(p) ?? 0, members.length, shareSlack, rank));
         }
         return out;
@@ -289,26 +327,22 @@ export class ChannelSupervisor {
         if (!latest)
             return;
         const [id] = latest;
-        const px = this.deps.config().channels.scanIntervalMs * 2;
-        await this.deps.redis.set(channelHandoffKey(id), this.deps.replicaId, "PX", px);
+        const px = this.config.get().channels.scanIntervalMs * 2;
+        await this.redis.set(channelHandoffKey(id), this.replicaId, "PX", px);
         this.releaseInBackground(id, this.nudge(plugin));
     }
     /** After-release callback: tells the other replicas a connection of `plugin` is free to claim. */
     nudge(plugin) {
-        return () => this.deps.bus
-            .publish(CHANNEL_HANDOFF_TOPIC, { plugin, replicaId: this.deps.replicaId })
-            .catch((err) => this.deps.log.warn("cannot publish channel handoff", { err }));
+        return () => this.bus
+            .publish(CHANNEL_HANDOFF_TOPIC, { plugin, replicaId: this.replicaId })
+            .catch((err) => this.log.warn("cannot publish channel handoff", { err }));
     }
-    async afterRenew(id, h, ok, ttl) {
-        if (!ok) {
-            this.deps.log.warn("channel lease lost; disconnecting", { connectionId: id });
-            this.drop(id, h);
-            return;
-        }
+    /** A renewal succeeded: one lease period connected in a row clears the failure count. */
+    async afterRenew(id, h, ttl) {
         h.renewedAt = Date.now();
         if (!h.stable && Date.now() - h.startedAt >= ttl) {
             h.stable = true;
-            await this.deps.redis.del(channelFailsKey(id)).catch(() => { });
+            await this.redis.del(channelFailsKey(id)).catch(() => { });
         }
     }
     /**
@@ -316,10 +350,11 @@ export class ChannelSupervisor {
      * 且插件在本进程已加载——滚动升级期间还没有该插件的副本根本不考虑它（不取租约、不记失败），留给有插件的副本。
      */
     runnable(plugins) {
-        return (this.deps.db
+        const db = this.db.db;
+        return (db
             .selectFrom("channel_connections")
             .innerJoin("orgs", "orgs.id", "channel_connections.org_id")
-            .innerJoin(enabledExtensionsByOrg(this.deps.db).as("en"), (j) => j
+            .innerJoin(enabledExtensionsByOrg(db).as("en"), (j) => j
             .onRef("en.plugin", "=", "channel_connections.plugin")
             .onRef("en.org_id", "=", "channel_connections.org_id"))
             .select(["channel_connections.id", "channel_connections.plugin"])
@@ -338,7 +373,7 @@ export class ChannelSupervisor {
         const ids = [...this.held.keys()];
         if (ids.length === 0)
             return;
-        const plugins = this.deps.localPlugins();
+        const plugins = this.localPlugins();
         const live = new Set(plugins.length === 0
             ? []
             : (await this.runnable(plugins).where("channel_connections.id", "in", ids).execute()).map((r) => r.id));
@@ -356,8 +391,8 @@ export class ChannelSupervisor {
     async scan(claimOnly) {
         if (this.stopped)
             return;
-        this.deps.onScan?.(claimOnly);
-        const plugins = this.deps.localPlugins();
+        this.onScan?.(claimOnly);
+        const plugins = this.localPlugins();
         if (plugins.length === 0)
             return;
         const rows = await this.runnable(plugins).execute();
@@ -384,34 +419,40 @@ export class ChannelSupervisor {
             }
             if (this.held.has(id))
                 continue;
-            if ((await this.deps.redis.exists(channelBackoffKey(id))) === 1)
+            if ((await this.redis.exists(channelBackoffKey(id))) === 1)
                 continue;
-            if ((await this.deps.redis.get(channelHandoffKey(id))) === this.deps.replicaId)
+            if ((await this.redis.get(channelHandoffKey(id))) === this.replicaId)
                 continue;
-            const token = randomUUID();
-            const ttl = this.deps.config().channels.leaseTtlMs;
-            const ok = await this.deps.redis.set(channelLeaseKey(id), token, "PX", ttl, "NX");
-            if (ok !== "OK")
+            const ttl = this.config.get().channels.leaseTtlMs;
+            const lease = await this.locks.hold(channelLeaseKey(id), randomUUID(), ttl);
+            if (!lease)
                 continue;
             if (this.stopped) {
-                await this.releaseLease(id, token);
+                await lease.release();
                 return;
             }
-            await this.connect(id, token);
+            await this.connect(id, lease);
         }
     }
     /** 已取得租约：读配置并在后台跑插件的 `connect`。 */
-    async connect(id, token) {
+    async connect(id, lease) {
         const pending = { reconnect: false };
         this.connecting.set(id, pending);
         let rt;
         try {
-            rt = await this.deps.connections.runtime(id);
+            rt = await this.connections.runtime(id);
         }
         catch (err) {
             this.connecting.delete(id);
             await this.failed(id, err);
-            await this.releaseLease(id, token);
+            await lease.release();
+            return;
+        }
+        // The lease was lost while the config was read (an aborted signal never fires a listener
+        // added later): not ours any more, so no connect and no release
+        if (lease.lost.aborted) {
+            this.connecting.delete(id);
+            lease.abandon();
             return;
         }
         // 插件异常信息可能带上凭据：写进 last_error / 日志前按该连接的密钥打码
@@ -420,7 +461,7 @@ export class ChannelSupervisor {
         const now = Date.now();
         const h = {
             plugin: rt.row.plugin,
-            token,
+            lease,
             abort,
             done: Promise.resolve(),
             startedAt: now,
@@ -429,12 +470,14 @@ export class ChannelSupervisor {
         };
         this.held.set(id, h);
         this.connecting.delete(id);
+        // 租约丢失（LockService 记一行 `lock lost`）：中止，不释放（已不是自己的）
+        lease.lost.addEventListener("abort", () => this.drop(id, h), { once: true });
         h.done = (async () => {
             try {
                 await rt.channel.connect({
                     connectionId: id,
                     config: rt.config,
-                    onEvent: (e) => this.track(this.deps.onEvent(id, e)),
+                    onEvent: (e) => this.track(this.inbound.onEvent(id, e)),
                     signal: abort.signal,
                 });
                 if (!abort.signal.aborted)
@@ -449,7 +492,7 @@ export class ChannelSupervisor {
                 // 自己结束（出错 / 提前返回）：交还租约，退避后由任一副本重试
                 if (!abort.signal.aborted && this.held.get(id) === h) {
                     this.held.delete(id);
-                    await this.releaseLease(id, token);
+                    await lease.release();
                 }
             }
         })();
@@ -468,26 +511,28 @@ export class ChannelSupervisor {
     async failed(id, err, redact) {
         const raw = errMsg(err);
         const message = (redact ? redact(raw) : raw).slice(0, MAX_ERROR_CHARS);
-        this.deps.log.warn("channel connection failed", { connectionId: id, error: message });
+        this.log.warn("channel connection failed", { connectionId: id, error: message });
         try {
-            const fails = await this.deps.redis.incr(channelFailsKey(id));
-            await this.deps.redis.expire(channelFailsKey(id), FAILS_TTL_SECONDS);
-            const delay = Math.min(MAX_BACKOFF_MS, this.deps.config().channels.retryBaseMs * 2 ** Math.min(fails - 1, 20));
-            await this.deps.redis.set(channelBackoffKey(id), "1", "PX", delay);
-            await this.deps.db
+            const fails = await this.redis.incr(channelFailsKey(id));
+            await this.redis.expire(channelFailsKey(id), FAILS_TTL_SECONDS);
+            const delay = Math.min(MAX_BACKOFF_MS, this.config.get().channels.retryBaseMs * 2 ** Math.min(fails - 1, 20));
+            await this.redis.set(channelBackoffKey(id), "1", "PX", delay);
+            await this.db
                 .updateTable("channel_connections")
                 .set({ last_error: message })
                 .where("id", "=", id)
                 .execute();
         }
         catch (e) {
-            this.deps.log.warn("cannot record channel failure", { connectionId: id, err: e });
+            this.log.warn("cannot record channel failure", { connectionId: id, err: e });
         }
     }
-    /** 租约已丢：中止，不释放（已不是自己的）。 */
+    /** 租约已丢：中止，不释放（已不是自己的；续租已停）。 */
     drop(id, h) {
-        if (this.held.get(id) === h)
-            this.held.delete(id);
+        if (this.held.get(id) !== h)
+            return;
+        this.held.delete(id);
+        h.lease.abandon();
         h.abort.abort();
     }
     /** 后台交还，记入 `releasing` 供 `stop()` 等待；`after` runs once the lease is released. */
@@ -500,13 +545,15 @@ export class ChannelSupervisor {
             .finally(() => this.releasing.delete(p));
         this.releasing.add(p);
     }
-    /** 主动交还：中止，等 `connect` 返回（至多 SETTLE_MS）后释放租约；超时则让租约自然过期，避免两边同时在线。 */
+    /**
+     * 主动交还：中止，等 `connect` 返回（至多 SETTLE_MS，期间租约照常续着，不会在别的副本眼里提前过期）后释放租约；
+     * 超时则停止续租、让租约自然过期，避免两边同时在线。
+     */
     async release(id) {
         const h = this.held.get(id);
         if (!h)
             return false;
         this.held.delete(id);
-        this.settling.set(id, h.token);
         h.abort.abort();
         let timer;
         const settled = await Promise.race([
@@ -517,23 +564,15 @@ export class ChannelSupervisor {
             }),
         ]);
         clearTimeout(timer);
-        if (this.settling.get(id) === h.token)
-            this.settling.delete(id);
         if (settled)
-            await this.releaseLease(id, h.token);
-        else
-            this.deps.log.warn("channel connect did not stop in time; lease left to expire", {
+            await h.lease.release();
+        else {
+            h.lease.abandon();
+            this.log.warn("channel connect did not stop in time; lease left to expire", {
                 connectionId: id,
             });
-        return settled;
-    }
-    async releaseLease(id, token) {
-        try {
-            await this.deps.redis.eval(RELEASE, 1, channelLeaseKey(id), token);
-        }
-        catch (err) {
-            this.deps.log.warn("cannot release channel lease", { connectionId: id, err });
         }
+        return settled;
     }
     /**
      * 本进程的插件实例变了（撤销、替换为新实例；内核接 `host.onChange`，C17）：交还该插件持有的全部长连接
@@ -561,8 +600,8 @@ export class ChannelSupervisor {
         // A nudged scan may still be claiming: let it finish so its leases are released below
         await this.scanChain;
         // Leave the share first so the other gateways count one replica fewer right away
-        await Promise.all([...this.heartbeated].map((p) => this.deps.redis.zrem(gatewayReplicasKey(p), this.deps.replicaId).catch((err) => {
-            this.deps.log.warn("cannot remove gateway heartbeat", { plugin: p, err });
+        await Promise.all([...this.heartbeated].map((p) => this.redis.zrem(gatewayReplicasKey(p), this.replicaId).catch((err) => {
+            this.log.warn("cannot remove gateway heartbeat", { plugin: p, err });
         })));
         this.heartbeated.clear();
         await Promise.all([...this.held.keys()].map((id) => this.release(id)));
@@ -571,19 +610,78 @@ export class ChannelSupervisor {
         // 插件交来的事件已在入队途中：等它们结束（之后内核才关闭队列）
         await Promise.all([...this.inflight]);
     }
-}
-/** Maintenance job that warns when channel connections need a gateway and none is live (Ruling R1). */
-export const GATEWAY_CHECK_JOB = "channel-gateway-check";
-export const GATEWAY_CHECK_SCHEDULER_ID = "channel-gateway-check-every";
+};
+ChannelSupervisor = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(REDIS)),
+    __param(2, Inject(KERNEL_BUS)),
+    __param(3, Inject(LockService)),
+    __param(4, Inject(ChannelConnections)),
+    __param(5, Inject(ExtensionRegistry)),
+    __param(6, Inject(ChannelInbound)),
+    __param(7, Inject(KernelConfigService)),
+    __param(8, Inject(KERNEL_LOGGER)),
+    __param(9, Inject(ReplicaStatusStore))
+], ChannelSupervisor);
+export { ChannelSupervisor };
+export { GATEWAY_CHECK_JOB, GATEWAY_CHECK_SCHEDULER_ID } from "./job-ids.js";
+/** The period of the gateway check (`@LockedCron` every minute). */
 export const GATEWAY_CHECK_EVERY_MS = 60_000;
 /**
- * Runs on the worker role (maintenance queue), per channel plugin (Ruling R3): when a plugin has
+ * Warns when channel connections need a gateway and none is live (Ruling R1 / R3 / R4):
+ * {@link checkGatewayPresence}, every minute, once across replicas; a worker-role job
+ * (`WorkerModule`), as the maintenance job it replaces was. Silent for one lease TTL after this
+ * worker process built its providers (the gateways' first heartbeats; the old handler's grace also
+ * started at the worker's kernel construction). Replaces the maintenance scheduler
+ * `channel-gateway-check-every` (retired at worker start).
+ */
+let GatewayCheckJob = class GatewayCheckJob {
+    db;
+    redis;
+    config;
+    lockService;
+    log;
+    /** The start of the grace period: when this process built its providers. */
+    graceFrom = Date.now();
+    constructor(db, redis, config, lockService, log) {
+        this.db = db;
+        this.redis = redis;
+        this.config = config;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async run() {
+        await checkGatewayPresence({
+            db: this.db.db,
+            redis: this.redis,
+            locks: this.lockService,
+            config: this.config,
+            log: this.log,
+            graceUntil: this.graceFrom + this.config.get().channels.leaseTtlMs,
+        });
+    }
+};
+__decorate([
+    LockedCron("* * * * *", { name: GATEWAY_CHECK_JOB })
+], GatewayCheckJob.prototype, "run", null);
+GatewayCheckJob = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(REDIS)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(LockService)),
+    __param(4, Inject(KERNEL_LOGGER))
+], GatewayCheckJob);
+export { GatewayCheckJob };
+/**
+ * Runs once a minute across replicas ({@link GatewayCheckJob}), per channel plugin (Ruling R3): when a plugin has
  * active connections (not deleted, org not deleted, plugin enabled for the org; long connection or
  * webhook mode, Ruling R4) but no gateway replica with that plugin loaded has a heartbeat newer than
  * one lease TTL (Redis server clock), nobody holds those long connections or answers their webhooks.
  * - Logs one `warn` (naming the plugins) per interval at most across the cluster: a Redis
- *   `SET NX PX` rate limit a little shorter than the job period, so a duplicated job or several
- *   worker replicas do not repeat it while each period still gets its line.
+ *   marker (`LockService.lease`, a `SET NX PX`) a little shorter than the job period, so a
+ *   duplicated job or several replicas do not repeat it while each period still gets its line.
  * - Silent before `graceUntil` (this process's start + one lease TTL), so a fresh cluster does not
  *   warn before the gateways' first heartbeat.
  * Returns whether it warned.
@@ -609,13 +707,13 @@ export async function checkGatewayPresence(deps) {
     const plugins = [...counts.keys()].filter((p) => (counts.get(p) ?? 0) > 0).sort();
     if (plugins.length === 0)
         return false;
-    const live = await liveGateways(deps.redis, plugins, deps.config().channels.leaseTtlMs);
+    const live = await liveGateways(deps.redis, plugins, deps.config.get().channels.leaseTtlMs);
     const missing = plugins.filter((p) => (live.get(p) ?? []).length === 0);
     if (missing.length === 0)
         return false;
     const everyMs = deps.everyMs ?? GATEWAY_CHECK_EVERY_MS;
-    const first = await deps.redis.set(gatewayMissingWarnedKey, "1", "PX", Math.max(Math.ceil(everyMs / 2), everyMs - 5_000), "NX");
-    if (first !== "OK")
+    const first = await deps.locks.lease(gatewayMissingWarnedKey, "1", Math.max(Math.ceil(everyMs / 2), everyMs - 5_000));
+    if (!first)
         return false;
     deps.log.warn("active channel connections have no live gateway replica with their plugin loaded; add the gateway role to a process (CAPYBARA_ROLES) that can load the plugin, or they receive no messages", {
         plugins: missing,