@geoly-ai/social-hub-cli 0.3.4 → 0.3.6

package/dist/register-notify.js

@@ -0,0 +1,1148 @@
+import { renameSync, rmSync, writeFileSync } from "node:fs";
+import { SocialHubHttpError, compareNotificationSeqStrings, } from "@geoly-ai/social-hub-sdk";
+import { requireClient, resolveTeamId } from "./client.js";
+import { assertApplyOrDryRun } from "./dry-run.js";
+import { resolveJsonArg, JsonArgError } from "./lib/json-arg.js";
+/**
+ * `social-hub notify …` —— 事件订阅通知的消费面（设计见
+ * `docs/notification-event-subscription-design.md`，契约见
+ * `packages/contracts/src/notifications.ts`）。
+ *
+ * 使用场景：用户自己机器上的 agent 从 Hub 拉「帖子发布后 2h/6h/24h/2d/7d」这类节点事件，
+ * 拿到后自己去开浏览器截图、发飞书群。**Hub 只通知，完全不管执行**。因此本命令组的设计
+ * 目标是「AI agent 的工具调用」：机器友好 + 崩溃可恢复。
+ *
+ * ## 五条不可协商的形态约束
+ *
+ * 1. **默认 `--limit 1`**（不是 20）。没有 delivery 表，ack 是**连续 watermark** 而不是
+ *    单条确认：`cursorSeq = N` 表示该订阅所有匹配事件中 `seq ≤ N` 的**均已完成**。
+ *    一次拉 20 条、第 5 条失败，后面 15 条就再也无法安全 ack。
+ * 2. **`--follow` 的背压固定为 maxUnacked=1**：输出一条后轮询自己的 subscription，
+ *    等 `cursorSeq >= pendingSeq` 才拉下一条。`--follow` 是便利模式，**不是新的消费协议**。
+ * 3. **不提供 `--auto-ack`**。CLI 写完 stdout 不代表下游 agent 已经截完图、发完飞书；
+ *    此时崩溃事件就丢了。ack 必须由真正完成副作用的一方显式发起。
+ * 4. **只原样输出，绝不「补齐」缺失字段**。envelope 带四层版本 + `includedFields`，
+ *    形状随配置变化是设计不是 bug。
+ * 5. **`seq` 全程字符串**（bigint）。任何 `Number(seq)` 都是精度炸弹；比较走
+ *    {@link compareNotificationSeqStrings}（BigInt）。
+ *
+ * ## 退出码矩阵（脚本/supervisor 据此分流）
+ *
+ * | 码 | 含义 |
+ * | -- | ---- |
+ * | 0 | 成功（含「无消息」、`--follow` 被 SIGINT/SIGTERM 正常中断） |
+ * | 1 | 参数 / 鉴权 / 权限 / 协议错误，或服务端**非重试**错误（含 pull 的 410 stale） |
+ * | 2 | 可重试的网络 / 服务不可用；或 `--fail-if-empty` 且无消息 |
+ * | 3 | ack 的 cursor / receipt 冲突（409 CAS 冲突、410 游标过期） |
+ * | 4 | **保留**：未来批量操作部分成功。Phase 1 不产生该退出码 |
+ */
+export const NOTIFY_EXIT = {
+    OK: 0,
+    /** 参数/鉴权/权限/协议或服务端非重试错误。 */
+    FATAL: 1,
+    /** 可重试的网络/服务不可用，或 --fail-if-empty 且无消息。 */
+    RETRYABLE: 2,
+    /** ack 的 cursor/receipt 冲突（409/410）。 */
+    CURSOR_CONFLICT: 3,
+    /** 保留：批量操作部分成功（Phase 1 不产生）。 */
+    PARTIAL: 4,
+};
+const CURSOR_SEQ_RE = /^(0|[1-9][0-9]{0,18})$/;
+const EVENT_SEQ_RE = /^[1-9][0-9]{0,18}$/;
+/** 长轮询上限（契约 NOTIFICATION_PULL_WAIT_SECONDS_MAX）。 */
+const PULL_WAIT_SECONDS_MAX = 30;
+/** 单次 pull 上限（契约 NOTIFICATION_PULL_LIMIT_MAX）。 */
+const PULL_LIMIT_MAX = 50;
+/** `--follow` 未显式给 `--wait` 时的默认长轮询秒数（留 5s 余量给服务端）。 */
+const FOLLOW_DEFAULT_WAIT_SECONDS = 25;
+/** 网络/5xx 退避上限（秒）。 */
+const NETWORK_BACKOFF_MAX_SECONDS = 30;
+/** 尊重 `Retry-After` 但要封顶，避免异常响应让进程睡几天。 */
+const RETRY_AFTER_CAP_SECONDS = 300;
+/** 等待游标推进时的 stderr 心跳间隔（毫秒）。 */
+const HEARTBEAT_INTERVAL_MS = 30_000;
+// ---------------------------------------------------------------------------
+// 错误分类（纯函数，可单测）
+// ---------------------------------------------------------------------------
+/**
+ * 可重试的 HTTP 状态：超时/过早/限流/服务端故障。
+ * 4xx 里只有 408 / 425 / 429 是「等一会儿再来」，其余都是调用方自己的问题。
+ */
+export function isRetryableStatus(status) {
+    // 显式白名单而不是「所有 5xx」：501 Not Implemented / 505 不会自行恢复，
+    // 归成可重试会让 `--follow` 无限打同一个必然失败的请求。
+    return [408, 425, 429, 500, 502, 503, 504].includes(status);
+}
+/** 传输层失败（DNS / 连接拒绝 / socket 断开 / TLS）——一律当可重试。 */
+export function isNetworkError(e) {
+    if (e instanceof SocialHubHttpError)
+        return false;
+    if (!(e instanceof Error))
+        return false;
+    const text = `${e.message} ${String(e.cause ?? "")}`;
+    // 注意**不含 EPIPE**：那通常是本进程 stdout 的下游关了管道，不是 Hub 不可达。
+    // 归成「可重试」会让 supervisor 反复重启一个其实已经没人读输出的消费者。
+    return /fetch failed|ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|socket hang up|network|certificate|aborted/i.test(text);
+}
+/**
+ * 把任意错误映射成退出码。
+ *
+ * 关键取舍：
+ *   - **pull 的 410（`SUBSCRIPTION_CURSOR_EXPIRED`）判 1 而不是 2**。它需要人工确认后
+ *     `notify subscriptions reset`；若判成「可重试」，supervisor 会对同一个 stale 订阅
+ *     无限重启。
+ *   - **ack 的 409 与 410 都判 3**，方便调用方统一进入「游标恢复分支」；具体动作靠
+ *     stderr 里的 `code` 区分（409 → 重读订阅/重新 pull 拿新 receipt；410 → 人工 reset）。
+ *   - **`PULL_RECEIPT_INVALID` 判 1**：签名/epoch/filterVersion 已变，重试同一 receipt
+ *     永远不会成功，必须重新 pull。
+ */
+export function classifyNotifyError(e, phase) {
+    if (e instanceof SocialHubHttpError) {
+        const base = {
+            status: e.status,
+            code: e.code,
+            message: e.message,
+            details: e.details,
+            retryAfterSeconds: e.retryAfterSeconds,
+        };
+        if (isRetryableStatus(e.status)) {
+            return { ...base, exitCode: NOTIFY_EXIT.RETRYABLE, retryable: true };
+        }
+        if (phase === "ack" && (e.status === 409 || e.status === 410)) {
+            return {
+                ...base,
+                exitCode: NOTIFY_EXIT.CURSOR_CONFLICT,
+                retryable: false,
+                hint: e.status === 409
+                    ? "游标已被推进或 receipt 已失效：先 `notify subscriptions get` 看 cursorSeq；若 cursorSeq >= throughSeq 说明上次 ack 其实成功了（响应丢失），不要重放副作用；否则重新 pull 拿新 receipt。"
+                    : "游标已落后于保留 floor（订阅 stale）：人工确认丢事件风险后执行 `notify subscriptions reset --start earliest|now --apply`。",
+            };
+        }
+        if (phase === "pull" && e.status === 410) {
+            return {
+                ...base,
+                exitCode: NOTIFY_EXIT.FATAL,
+                retryable: false,
+                hint: "订阅已 stale（游标落后于保留 floor）。这不是临时错误，重试无用：人工确认丢事件风险后执行 `notify subscriptions reset --start earliest|now --apply`。",
+            };
+        }
+        return {
+            ...base,
+            exitCode: NOTIFY_EXIT.FATAL,
+            retryable: false,
+            hint: e.status === 401 || e.status === 403
+                ? "鉴权/权限问题：`social-hub auth whoami` 确认身份；字段权限不足会整个订阅 403（不做字段级脱敏）。"
+                : undefined,
+        };
+    }
+    if (isNetworkError(e)) {
+        return {
+            exitCode: NOTIFY_EXIT.RETRYABLE,
+            retryable: true,
+            message: e instanceof Error ? e.message : String(e),
+        };
+    }
+    return {
+        exitCode: NOTIFY_EXIT.FATAL,
+        retryable: false,
+        message: e instanceof Error ? e.message : String(e),
+    };
+}
+// ---------------------------------------------------------------------------
+// 输出（stdout 只出事件；一切日志走 stderr）
+// ---------------------------------------------------------------------------
+function logErr(obj) {
+    process.stderr.write(`${JSON.stringify(obj)}\n`);
+}
+function reportError(c, phase) {
+    logErr({
+        level: "error",
+        phase,
+        exitCode: c.exitCode,
+        status: c.status,
+        code: c.code,
+        message: c.message,
+        details: c.details,
+        hint: c.hint,
+    });
+}
+/**
+ * 写一行 JSON Lines 到 stdout，并在内核缓冲区满时**等 drain**。
+ * 直接 `console.log` 在下游管道慢时会让内存无上限增长。
+ *
+ * drain 等待必须同时监听 `error`/`close` 与 stop 信号：下游停止读取（比如 `head -1`
+ * 之后管道关闭）时，只等 `drain` 会永久挂住。
+ */
+async function writeStdoutLine(line, stop) {
+    if (process.stdout.write(`${line}\n`))
+        return;
+    await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            process.stdout.off("drain", onDrain);
+            process.stdout.off("error", onError);
+            process.stdout.off("close", onClose);
+            stop?.off(onStop);
+        };
+        // 🔴 只有 drain（真的写出去了）或 stop（人为中断）才算成功。
+        // 把 error/close 也当成功 = 下游其实没收到这条 envelope，CLI 却进入等 ack 态，
+        // 于是永久挂死在一条谁也不知道存在的事件上。
+        const onDrain = () => {
+            cleanup();
+            resolve();
+        };
+        const onStop = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (e) => {
+            cleanup();
+            reject(e instanceof Error ? e : new Error(`stdout write failed: ${String(e)}`));
+        };
+        const onClose = () => {
+            cleanup();
+            if (stop?.requested)
+                return resolve();
+            reject(new Error("stdout closed before the event line was flushed"));
+        };
+        process.stdout.once("drain", onDrain);
+        process.stdout.once("error", onError);
+        process.stdout.once("close", onClose);
+        stop?.on(onStop);
+    });
+}
+function printJson(data) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+}
+export function buildReceiptSidecar(res) {
+    const last = res.events.at(-1);
+    if (!last)
+        return null;
+    return {
+        subscriptionId: res.receipt.subscriptionId,
+        cursorSeq: res.cursorSeq,
+        throughSeq: last.seq,
+        eventIds: res.events.map((e) => e.eventId),
+        receipt: res.receipt,
+    };
+}
+let sidecarCounter = 0;
+/**
+ * 原子落盘：先写临时文件再 rename，避免 agent 读到半截 JSON。
+ * 权限 0600 —— receipt 是签名凭据，虽有 TTL 但不该对同机其它用户可读。
+ */
+export function writeReceiptSidecarAtomically(path, sidecar) {
+    const tmp = `${path}.tmp-${process.pid}-${++sidecarCounter}`;
+    writeFileSync(tmp, `${JSON.stringify(sidecar, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+// ---------------------------------------------------------------------------
+// 退避 / 睡眠
+// ---------------------------------------------------------------------------
+/** 指数退避 + ±20% 抖动，封顶 maxMs。 */
+export function nextBackoffMs(attempt, baseMs, maxMs, rand = Math.random) {
+    const raw = Math.min(maxMs, baseMs * 2 ** Math.max(0, attempt - 1));
+    const jitter = 1 + (rand() * 0.4 - 0.2);
+    return Math.max(0, Math.round(Math.min(maxMs, raw * jitter)));
+}
+/** 可被信号打断的 sleep（否则 Ctrl-C 后还要等满一个退避周期）。 */
+function sleep(ms, stop) {
+    return new Promise((resolve) => {
+        if (stop.requested)
+            return resolve();
+        const finish = () => {
+            clearTimeout(timer);
+            stop.off(onStop);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        function onStop() {
+            finish();
+        }
+        stop.on(onStop);
+    });
+}
+function createStopSignal() {
+    const listeners = new Set();
+    const controller = new AbortController();
+    const state = {
+        requested: false,
+        signal: controller.signal,
+        on(fn) {
+            listeners.add(fn);
+        },
+        off(fn) {
+            listeners.delete(fn);
+        },
+        dispose() {
+            process.off("SIGINT", trigger);
+            process.off("SIGTERM", trigger);
+        },
+    };
+    function trigger() {
+        if (state.requested)
+            return;
+        state.requested = true;
+        logErr({ level: "info", event: "shutdown", message: "signal received" });
+        // abort 在途的 long-poll fetch —— 只置布尔位的话，Ctrl-C 后还要等满 25 秒。
+        controller.abort();
+        for (const fn of [...listeners])
+            fn();
+    }
+    process.on("SIGINT", trigger);
+    process.on("SIGTERM", trigger);
+    return state;
+}
+/** 被 stop 信号 abort 掉的 fetch 不是错误，而是「正常收工」。 */
+function isAbortFromStop(e, stop) {
+    return (stop.requested &&
+        e instanceof Error &&
+        (e.name === "AbortError" || /abort/i.test(e.message)));
+}
+// ---------------------------------------------------------------------------
+// 订阅引用解析（name | uuid）
+// ---------------------------------------------------------------------------
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * `--subscription` 收 name 或 uuid。
+ *
+ * SDK 侧**只认 uuid**（pull/ack 是消费热路径，不该藏一次隐式 list）；name 解析是 CLI
+ * 的便利层，且 `--follow` 只在启动时解析一次。
+ */
+export async function resolveSubscription(client, teamId, ref, 
+/** `--follow` 启动期解析也必须能被 Ctrl-C 打断，否则要一直等到网络超时。 */
+signal) {
+    if (UUID_RE.test(ref)) {
+        try {
+            return await client.getNotificationSubscription(teamId, ref, signal ? { signal } : {});
+        }
+        catch (e) {
+            if (!(e instanceof SocialHubHttpError && e.status === 404))
+                throw e;
+            // uuid 形状但不存在 → 继续按 name 找（理论上 name 也可能长得像 uuid）。
+        }
+    }
+    const list = await client.listNotificationSubscriptions(teamId, signal ? { signal } : {});
+    const matches = (list.items ?? []).filter((s) => s.name === ref && s.status !== "deleted");
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length === 0) {
+        throw new Error(`找不到订阅 "${ref}"（team ${teamId}）。用 \`social-hub notify subscriptions list -t ${teamId}\` 查看。`);
+    }
+    throw new Error(`订阅名 "${ref}" 在 team ${teamId} 下匹配到 ${matches.length} 条，请改用 uuid。`);
+}
+/**
+ * `--follow` 每轮 GET subscription 后的判定。
+ *
+ * 只比 cursor 是不够的 —— 下列情形会让「等 cursor 推进」永久挂死，必须当场退出：
+ *   - `paused` / `stale` / `deleted`：这些状态下 ack 根本不会成功；
+ *   - `receiptEpoch` / `filterVersion` 变了而 cursor 还没越过 pendingSeq：
+ *     在途 receipt 已作废（reset / 改 filter / 权限变化），这条事件再也 ack 不上去。
+ *
+ * cursor 已越过 pendingSeq 视为**已被别处推进**，直接继续下一轮，**不重复输出**该事件。
+ */
+export function evaluateCursorWait(args) {
+    const s = args.subscription;
+    if (compareNotificationSeqStrings(s.cursorSeq, args.pendingSeq) >= 0) {
+        return { kind: "advanced" };
+    }
+    if (s.status === "paused") {
+        return {
+            kind: "abort",
+            reason: "subscription_paused",
+            hint: "订阅被 pause，暂停期间无法 ack。`notify subscriptions resume` 后重启 --follow。",
+        };
+    }
+    if (s.status === "stale") {
+        return {
+            kind: "abort",
+            reason: "subscription_stale",
+            hint: "订阅已 stale（游标落后于保留 floor）。人工确认后 `notify subscriptions reset --apply`。",
+        };
+    }
+    if (s.status === "deleted") {
+        return {
+            kind: "abort",
+            reason: "subscription_deleted",
+            hint: "订阅已删除。",
+        };
+    }
+    if (s.receiptEpoch !== args.receiptEpoch) {
+        return {
+            kind: "abort",
+            reason: "receipt_epoch_changed",
+            hint: "receiptEpoch 已变（reset / 权限或匹配面变化），在途 receipt 已作废：这条事件永远 ack 不上去。重启 --follow 会重新拉到它。",
+        };
+    }
+    if (s.filterVersion !== args.filterVersion) {
+        return {
+            kind: "abort",
+            reason: "filter_version_changed",
+            hint: "filterVersion 已变（sourceIds/filters/requiredFields 被改），在途 receipt 已作废。重启 --follow。",
+        };
+    }
+    return { kind: "wait" };
+}
+// ---------------------------------------------------------------------------
+// 参数解析小工具
+// ---------------------------------------------------------------------------
+/** 逗号分隔列表 → 去重 + ASCII 升序（契约要求 sourceIds / 字段路径升序去重）。 */
+export function parseSortedList(raw) {
+    if (raw === undefined)
+        return undefined;
+    const items = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (items.length === 0)
+        return undefined;
+    return [...new Set(items)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+function collectRepeatable(value, prev = []) {
+    return [...prev, value];
+}
+function parseIntOption(raw, label, min, max) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < min || n > max) {
+        fail(`${label} 须为 ${min}..${max} 的整数（收到 ${raw}）。`);
+    }
+    return n;
+}
+/**
+ * 参数错误。
+ *
+ * 抛而不是 `process.exit()`：stdout/stderr 走管道时是**异步**的，`process.exit()`
+ * 会把已排队但未 flush 的内容直接截断（空 pull 打完 JSON 紧接着 exit 2 就会得到半截 JSON）。
+ * 统一由 {@link runNotify} 设 `process.exitCode` 后正常返回，让 Node 自己 flush。
+ */
+class NotifyArgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NotifyArgError";
+    }
+}
+function fail(message) {
+    throw new NotifyArgError(message);
+}
+function assertSeq(value, label, allowZero) {
+    const re = allowZero ? CURSOR_SEQ_RE : EVENT_SEQ_RE;
+    if (!re.test(value)) {
+        fail(`${label} 须为十进制 seq 字符串${allowZero ? "（允许 0）" : "（正整数）"}，收到 "${value}"。seq 是 bigint，禁止科学计数/浮点。`);
+    }
+    return value;
+}
+/**
+ * 命令边界：把任何错误映射成退出码，且**只设 `process.exitCode`**（见 {@link fail}）。
+ * **不复用** `withCliErrorBoundary` —— 那个恒定退出 1，会抹掉 2/3 的分流价值。
+ *
+ * 也兜住本地 I/O 异常（sidecar 落盘失败、stdout 被下游关闭），否则 `--follow` 会变成
+ * unhandled rejection 而不是稳定的退出码 + 结构化 stderr。
+ */
+async function runNotify(phase, run) {
+    try {
+        await run();
+    }
+    catch (e) {
+        if (e instanceof JsonArgError || e instanceof NotifyArgError) {
+            logErr({
+                level: "error",
+                phase: "args",
+                exitCode: NOTIFY_EXIT.FATAL,
+                message: e.message,
+            });
+            process.exitCode = NOTIFY_EXIT.FATAL;
+            return;
+        }
+        const c = classifyNotifyError(e, phase);
+        reportError(c, phase);
+        process.exitCode = c.exitCode;
+    }
+}
+async function runPullOnce(client, teamId, subscriptionId, limit, waitSeconds, signal) {
+    return client.pullNotificationEvents(teamId, { subscriptionId, limit, waitSeconds }, signal ? { signal } : {});
+}
+async function pullOneShot(client, teamId, sub, opts) {
+    const res = await runPullOnce(client, teamId, sub.id, opts.limit, opts.waitSeconds);
+    const sidecar = buildReceiptSidecar(res);
+    if (opts.receiptFile) {
+        if (sidecar) {
+            // 先落 receipt 再出事件：反过来的话 agent 可能拿到一条永远 ack 不了的事件。
+            writeReceiptSidecarAtomically(opts.receiptFile, sidecar);
+        }
+        else {
+            // 空 pull 必须**清掉**上一轮的 sidecar：留着会让「以文件存在为信号」的 agent
+            // 拿旧 receipt 去 ack 一条它这轮根本没处理的事件。
+            rmSync(opts.receiptFile, { force: true });
+        }
+    }
+    if (opts.format === "jsonl") {
+        for (const event of res.events) {
+            await writeStdoutLine(JSON.stringify(event));
+        }
+    }
+    else {
+        printJson(res);
+    }
+    if (res.events.length === 0 && opts.failIfEmpty) {
+        logErr({
+            level: "error",
+            phase: "pull",
+            exitCode: NOTIFY_EXIT.RETRYABLE,
+            message: "no events (--fail-if-empty)",
+            cursorSeq: res.cursorSeq,
+            latestSeq: res.latestSeq,
+        });
+        process.exitCode = NOTIFY_EXIT.RETRYABLE;
+    }
+}
+/**
+ * `--follow`：常驻监听，**maxUnacked = 1**。
+ *
+ * 每轮：pull(limit=1) → 落 receipt sidecar → stdout 一行 envelope → 轮询自己的
+ * subscription 直到 `cursorSeq >= pendingSeq` → 再拉下一条。
+ *
+ * 为什么用「轮询 subscription」而不是「重复 pull 同一条直到 seq 变了」：pull 是幂等的
+ * （不推进游标），重复 pull 会不断签发新 receipt、刷 `lastPulledAt`，而且要么重复输出
+ * 同一 envelope（破坏 JSON Lines 语义），要么在 CLI 内部做去重（等于把 subscription
+ * 状态在客户端重建一遍）。GET subscription 才是游标的权威状态探针。
+ *
+ * **未知 payloadSchemaVersion 的 poison pill**：agent 拒绝处理且不 ack 时，本命令会
+ * 永久停在等待态（这是安全设计，不是 bug —— 跳过就等于静默丢事件）。stderr 心跳会一直
+ * 报 pendingSeq，人工介入后 SIGINT 退出 0。
+ */
+async function pullFollow(client, teamId, subscriptionRef, opts) {
+    // 🔴 信号处理器**先于**订阅解析安装：解析期间 Ctrl-C 否则会走 Node 默认信号退出码，
+    // 与「--follow 被正常中断 → 0」的约定矛盾。
+    const stop = createStopSignal();
+    try {
+        let sub;
+        try {
+            sub = await resolveSubscription(client, teamId, subscriptionRef, stop.signal);
+        }
+        catch (e) {
+            if (isAbortFromStop(e, stop))
+                return NOTIFY_EXIT.OK;
+            const c = classifyNotifyError(e, "pull");
+            reportError(c, "pull");
+            return c.exitCode;
+        }
+        if (stop.requested)
+            return NOTIFY_EXIT.OK;
+        let networkAttempt = 0;
+        while (!stop.requested) {
+            let res;
+            try {
+                res = await runPullOnce(client, teamId, sub.id, 1, opts.waitSeconds, stop.signal);
+                networkAttempt = 0;
+            }
+            catch (e) {
+                if (isAbortFromStop(e, stop))
+                    break;
+                const c = classifyNotifyError(e, "pull");
+                if (!c.retryable) {
+                    reportError(c, "pull");
+                    return c.exitCode;
+                }
+                networkAttempt += 1;
+                const retryAfterMs = c.retryAfterSeconds !== undefined
+                    ? Math.min(c.retryAfterSeconds, RETRY_AFTER_CAP_SECONDS) * 1000
+                    : undefined;
+                const delay = retryAfterMs ??
+                    nextBackoffMs(networkAttempt, 1000, NETWORK_BACKOFF_MAX_SECONDS * 1000);
+                logErr({
+                    level: "warn",
+                    phase: "pull",
+                    event: "retry",
+                    attempt: networkAttempt,
+                    delayMs: delay,
+                    status: c.status,
+                    message: c.message,
+                });
+                await sleep(delay, stop);
+                continue;
+            }
+            if (res.events.length === 0)
+                continue;
+            const sidecar = buildReceiptSidecar(res);
+            if (!sidecar)
+                continue;
+            writeReceiptSidecarAtomically(opts.receiptFile, sidecar);
+            const event = res.events[0];
+            await writeStdoutLine(JSON.stringify(event), stop);
+            const decision = await waitForCursorAdvance(client, teamId, sub.id, {
+                pendingSeq: event.seq,
+                receiptEpoch: res.receipt.receiptEpoch,
+                filterVersion: res.receipt.filterVersion,
+                pollIntervalMs: opts.pollIntervalMs,
+                maxPollIntervalMs: opts.maxPollIntervalMs,
+                stop,
+            });
+            if (decision.kind === "abort") {
+                logErr({
+                    level: "error",
+                    phase: "pull",
+                    exitCode: NOTIFY_EXIT.FATAL,
+                    event: "follow_abort",
+                    reason: decision.reason,
+                    pendingSeq: event.seq,
+                    hint: decision.hint,
+                });
+                return NOTIFY_EXIT.FATAL;
+            }
+            if (decision.kind === "fatal") {
+                reportError(decision.classification, "pull");
+                return decision.classification.exitCode;
+            }
+            // advanced / stopped → 继续下一轮（stopped 由 while 条件收口）。
+        }
+        return NOTIFY_EXIT.OK;
+    }
+    finally {
+        stop.dispose();
+    }
+}
+async function waitForCursorAdvance(client, teamId, subscriptionId, args) {
+    const startedAt = Date.now();
+    let lastHeartbeat = startedAt;
+    let attempt = 0;
+    let networkAttempt = 0;
+    while (!args.stop.requested) {
+        await sleep(networkAttempt > 0
+            ? nextBackoffMs(networkAttempt, 1000, NETWORK_BACKOFF_MAX_SECONDS * 1000)
+            : nextBackoffMs(attempt + 1, args.pollIntervalMs, args.maxPollIntervalMs), args.stop);
+        if (args.stop.requested)
+            break;
+        let subscription;
+        try {
+            subscription = await client.getNotificationSubscription(teamId, subscriptionId, { signal: args.stop.signal });
+            networkAttempt = 0;
+        }
+        catch (e) {
+            if (isAbortFromStop(e, args.stop))
+                return { kind: "stopped" };
+            if (e instanceof SocialHubHttpError && e.status === 404) {
+                return {
+                    kind: "abort",
+                    reason: "subscription_deleted",
+                    hint: "订阅已删除或不可见。",
+                };
+            }
+            const c = classifyNotifyError(e, "pull");
+            if (!c.retryable)
+                return { kind: "fatal", classification: c };
+            networkAttempt += 1;
+            logErr({
+                level: "warn",
+                phase: "pull",
+                event: "cursor_poll_retry",
+                attempt: networkAttempt,
+                status: c.status,
+                message: c.message,
+            });
+            continue;
+        }
+        const decision = evaluateCursorWait({
+            subscription,
+            pendingSeq: args.pendingSeq,
+            receiptEpoch: args.receiptEpoch,
+            filterVersion: args.filterVersion,
+        });
+        if (decision.kind === "advanced")
+            return { kind: "advanced" };
+        if (decision.kind === "abort")
+            return decision;
+        attempt += 1;
+        const now = Date.now();
+        if (now - lastHeartbeat >= HEARTBEAT_INTERVAL_MS) {
+            lastHeartbeat = now;
+            logErr({
+                level: "info",
+                phase: "pull",
+                event: "awaiting_ack",
+                subscriptionId,
+                pendingSeq: args.pendingSeq,
+                cursorSeq: subscription.cursorSeq,
+                waitedSeconds: Math.round((now - startedAt) / 1000),
+                hint: "CLI 不会自动 ack：完成副作用后调用 `social-hub notify ack --receipt-file <sidecar>`。",
+            });
+        }
+    }
+    return { kind: "stopped" };
+}
+// ---------------------------------------------------------------------------
+// 注册
+// ---------------------------------------------------------------------------
+export function registerNotifyCommands(program) {
+    const notify = program
+        .command("notify")
+        .description("事件订阅通知（Hub 只通知不管执行；agent 拉走后自己干活）：subscriptions / pull / ack / source-configs");
+    registerSubscriptionCommands(notify);
+    registerPullCommand(notify);
+    registerAckCommand(notify);
+    registerSourceConfigCommands(notify);
+}
+function registerSubscriptionCommands(notify) {
+    const subs = notify
+        .command("subscriptions")
+        .description("订阅管理（每台机器一个订阅、各自独立游标；订阅之间是广播）");
+    subs
+        .command("list")
+        .description("GET .../notification-subscriptions（非 manager/admin 只看得到自己的）")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .option("--status <status>", "active|paused|stale|deleted")
+        .option("--source-id <sourceId>", "只看订阅了该 source 的")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            printJson(await requireClient().listNotificationSubscriptions(teamId, {
+                status: opts.status,
+                sourceId: opts.sourceId,
+            }));
+        });
+    });
+    subs
+        .command("get")
+        .description("GET .../notification-subscriptions/:id（--subscription 接受 name 或 uuid）")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--subscription <nameOrId>", "订阅名或 uuid")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            const client = requireClient();
+            printJson(await resolveSubscription(client, teamId, opts.subscription));
+        });
+    });
+    subs
+        .command("create")
+        .description("POST .../notification-subscriptions — 新建订阅")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .option("--name <name>", "订阅名（team 内唯一；建议用机器名，如 my-mac-agent）")
+        .option("--source <sourceId>", "订阅的 sourceId，可重复（如 post-performance-node.v1）", collectRepeatable)
+        .option("--start <position>", "now|earliest（默认 now：避免新机器一上线被历史事件淹没）")
+        .option("--require-fields <csv>", "逗号分隔字段路径：没有这些字段就别发给我（如 subject.permalink,account.externalRef）")
+        .option("--filter-brand <csv>", "brandIds 过滤（逗号分隔 uuid）")
+        .option("--filter-account <csv>", "socialAccountIds 过滤（逗号分隔 uuid）")
+        .option("--filter-subreddit <csv>", "subreddits 过滤（逗号分隔，小写无 r/ 前缀）")
+        .option("-j, --json <json>", "整个请求体 JSON（也支持 @<file> 与 - 读 stdin）")
+        .option("--json-file <path>", "从文件/`-`(stdin) 读整个请求体 JSON")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            const body = buildCreateSubscriptionBody(opts);
+            printJson(await requireClient().createNotificationSubscription(teamId, body));
+        });
+    });
+    subs
+        .command("update")
+        .description("PATCH .../notification-subscriptions/:id — 改匹配面/名字（会 bump filterVersion + receiptEpoch）")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--subscription <nameOrId>", "订阅名或 uuid")
+        .option("-j, --json <json>", "patch JSON（也支持 @<file> 与 - 读 stdin）")
+        .option("--json-file <path>", "从文件/`-`(stdin) 读 patch JSON")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            const client = requireClient();
+            const patch = resolveJsonArg({
+                inline: opts.json,
+                file: opts.jsonFile,
+                label: "-j / --json",
+                required: true,
+            });
+            const sub = await resolveSubscription(client, teamId, opts.subscription);
+            // 未显式给 expectedRowVersion 时用刚读到的值：CAS 仍然生效（读→写之间被人改过就 409）。
+            const body = {
+                expectedRowVersion: sub.rowVersion,
+                ...patch,
+            };
+            printJson(await client.updateNotificationSubscription(teamId, sub.id, body));
+        });
+    });
+    const registerStatusToggle = (name, paused, description) => {
+        subs
+            .command(name)
+            .description(description)
+            .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+            .requiredOption("--subscription <nameOrId>", "订阅名或 uuid")
+            .option("--expected-row-version <n>", "乐观锁；缺省先 GET 一次取当前值")
+            .action(async (opts) => {
+            await runNotify("admin", async () => {
+                const teamId = resolveTeamId(opts.team);
+                const client = requireClient();
+                const sub = await resolveSubscription(client, teamId, opts.subscription);
+                const expected = parseIntOption(opts.expectedRowVersion, "--expected-row-version", 0, Number.MAX_SAFE_INTEGER) ?? sub.rowVersion;
+                printJson(await client.setNotificationSubscriptionPaused(teamId, sub.id, paused, { expectedRowVersion: expected }));
+            });
+        });
+    };
+    registerStatusToggle("pause", true, "POST .../:id/pause — 暂停消费（暂停期间 ack 不会成功）");
+    registerStatusToggle("resume", false, "POST .../:id/resume — 恢复消费（游标不动，从上次 watermark 继续）");
+    subs
+        .command("delete")
+        .description("DELETE .../notification-subscriptions/:id — 软删（保留审计，204 无响应体）")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--subscription <nameOrId>", "订阅名或 uuid")
+        .option("--apply", "确认执行")
+        .option("--dry-run", "只预览")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            const client = requireClient();
+            const sub = await resolveSubscription(client, teamId, opts.subscription);
+            if (!assertApplyOrDryRun(opts, {
+                command: "notify subscriptions delete",
+                danger: "软删订阅并作废全部在途 receipt（receiptEpoch bump）",
+                summary: { subscriptionId: sub.id, name: sub.name },
+            })) {
+                return;
+            }
+            await client.deleteNotificationSubscription(teamId, sub.id);
+            // API 返回 204 无响应体；给 agent 一个可解析的确认对象。
+            printJson({ deleted: true, subscriptionId: sub.id, name: sub.name });
+        });
+    });
+    subs
+        .command("reset")
+        .description("POST .../notification-subscriptions/:id/reset — 重设游标起点（stale 恢复的唯一出口）")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--subscription <nameOrId>", "订阅名或 uuid")
+        .option("--start <position>", "now|earliest（缺省沿用订阅自身的 startPosition）")
+        .option("--apply", "确认执行")
+        .option("--dry-run", "只预览")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            const start = opts.start;
+            if (start !== undefined && start !== "now" && start !== "earliest") {
+                fail("--start 只能是 now 或 earliest。");
+            }
+            const client = requireClient();
+            const sub = await resolveSubscription(client, teamId, opts.subscription);
+            if (!assertApplyOrDryRun(opts, {
+                command: "notify subscriptions reset",
+                danger: "重设游标：start=now 会**永久跳过**当前所有未处理事件；start=earliest 会重放全部保留期内事件（agent 须靠 dedupeKey 幂等）。同时 bump receiptEpoch，作废全部在途 receipt。",
+                summary: {
+                    subscriptionId: sub.id,
+                    name: sub.name,
+                    currentCursorSeq: sub.cursorSeq,
+                    startPosition: start ?? sub.startPosition,
+                    // reset 不会 resume：paused 保持 paused，只有 stale 会被恢复成 active。
+                    statusAfterReset: sub.status === "stale" ? "active" : sub.status,
+                    expectedRowVersion: sub.rowVersion,
+                },
+            })) {
+                return;
+            }
+            printJson(
+            // 真 CAS：rowVersion 取自上面刚读到的订阅，若期间被并发改过服务端会 409。
+            await client.resetNotificationSubscriptionCursor(teamId, sub.id, {
+                expectedRowVersion: sub.rowVersion,
+                ...(start ? { startPosition: start } : {}),
+            }));
+        });
+    });
+}
+/** 组装 create 请求体：`-j/--json` 整体覆盖，否则由扁平参数拼（并做升序去重规范化）。 */
+export function buildCreateSubscriptionBody(opts) {
+    if (opts.json !== undefined || opts.jsonFile !== undefined) {
+        return resolveJsonArg({
+            inline: opts.json,
+            file: opts.jsonFile,
+            label: "-j / --json",
+            required: true,
+        });
+    }
+    if (!opts.name)
+        fail("缺少 --name（或用 -j/--json/--json-file 给整个请求体）。");
+    const sourceIds = [...new Set(opts.source ?? [])].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+    if (sourceIds.length === 0) {
+        fail("至少需要一个 --source <sourceId>（如 --source post-performance-node.v1）。");
+    }
+    const start = opts.start ?? "now";
+    if (start !== "now" && start !== "earliest") {
+        fail("--start 只能是 now 或 earliest。");
+    }
+    const filters = {};
+    const brandIds = parseSortedList(opts.filterBrand);
+    if (brandIds)
+        filters.brandIds = brandIds;
+    const socialAccountIds = parseSortedList(opts.filterAccount);
+    if (socialAccountIds)
+        filters.socialAccountIds = socialAccountIds;
+    // 逐项、**锚定**去前缀（与契约 canonicalizeNotificationFilters 同则）。
+    // 对整串做全局替换会把中间的 `/r/` 也吃掉，把非法输入悄悄改成另一个合法 subreddit。
+    const subreddits = parseSortedList(opts.filterSubreddit
+        ?.split(",")
+        .map((v) => v
+        .trim()
+        .replace(/^\/?r\//i, "")
+        .toLowerCase())
+        .join(","));
+    if (subreddits)
+        filters.subreddits = subreddits;
+    const requiredFields = parseSortedList(opts.requireFields);
+    return {
+        name: opts.name,
+        sourceIds,
+        ...(Object.keys(filters).length > 0 ? { filters } : {}),
+        ...(requiredFields ? { requiredFields } : {}),
+        startPosition: start,
+    };
+}
+function registerPullCommand(notify) {
+    notify
+        .command("pull")
+        .description("POST .../notification-events/pull — 拉事件（幂等，不推进游标）。默认 --limit 1：游标是连续 watermark")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--subscription <nameOrId>", "订阅名或 uuid")
+        .option("--limit <n>", "1..50，默认 1（强烈建议保持 1）", "1")
+        .option("--wait <seconds>", `0..${PULL_WAIT_SECONDS_MAX} long-poll 秒数（默认 0；--follow 默认 ${FOLLOW_DEFAULT_WAIT_SECONDS}）`)
+        .option("--format <fmt>", "json（完整 pull 响应，含 receipt）| jsonl（stdout 每行一个 envelope，需配 --receipt-file）", "json")
+        .option("--receipt-file <path>", "把 ack 所需的 receipt 原子写入该文件（jsonl / --follow 必填）")
+        .option("--follow", "常驻监听：一次一条，等 cursor 推进后才拉下一条（maxUnacked=1）")
+        .option("--fail-if-empty", "无消息时退出 2（不可与 --follow 同用）")
+        .option("--poll-interval <seconds>", "--follow 等待 ack 的初始轮询间隔（默认 1）", "1")
+        .option("--max-poll-interval <seconds>", "--follow 轮询间隔上限（默认 10）", "10")
+        .action(async (opts) => {
+        await runNotify("pull", async () => {
+            const follow = opts.follow === true;
+            const format = opts.format === "jsonl" ? "jsonl" : "json";
+            if (opts.format !== undefined &&
+                !["json", "jsonl"].includes(opts.format)) {
+                fail("--format 只能是 json 或 jsonl。");
+            }
+            const limit = parseIntOption(opts.limit, "--limit", 1, PULL_LIMIT_MAX) ?? 1;
+            const waitSeconds = parseIntOption(opts.wait, "--wait", 0, PULL_WAIT_SECONDS_MAX) ??
+                (follow ? FOLLOW_DEFAULT_WAIT_SECONDS : 0);
+            const pollIntervalMs = (parseIntOption(opts.pollInterval, "--poll-interval", 1, 3600) ?? 1) *
+                1000;
+            const maxPollIntervalMs = (parseIntOption(opts.maxPollInterval, "--max-poll-interval", 1, 3600) ?? 10) * 1000;
+            if (maxPollIntervalMs < pollIntervalMs) {
+                fail("--max-poll-interval 不能小于 --poll-interval。");
+            }
+            if (follow && opts.failIfEmpty) {
+                fail("--follow 与 --fail-if-empty 互斥：--follow 本来就是等到有消息为止。");
+            }
+            if (follow && limit !== 1) {
+                fail("--follow 只支持 --limit 1：背压语义是 maxUnacked=1，一次多条就无法安全 ack。");
+            }
+            if (follow && format !== "jsonl") {
+                fail("--follow 必须配 --format jsonl（流式消费；stdout 每行一个 envelope）。");
+            }
+            // jsonl 的 stdout 里没有 receipt，而 ack 要求回传整个 receipt 对象。
+            // 没有 sidecar 就等于产出一批永远 ack 不了的死事件，故提前拒。
+            if (format === "jsonl" && !opts.receiptFile) {
+                fail("--format jsonl 必须配 --receipt-file <path>：envelope 里没有 receipt，而 ack 要回传整个 receipt 对象。");
+            }
+            const teamId = resolveTeamId(opts.team);
+            const client = requireClient();
+            if (follow) {
+                // pullFollow 自己管信号与已分类的 HTTP 错误并返回退出码；
+                // 意外的本地 I/O 异常（sidecar 落盘失败、stdout 关闭）冒泡给外层 runNotify。
+                process.exitCode = await pullFollow(client, teamId, opts.subscription, {
+                    waitSeconds,
+                    receiptFile: opts.receiptFile,
+                    pollIntervalMs,
+                    maxPollIntervalMs,
+                });
+                return;
+            }
+            const sub = await resolveSubscription(client, teamId, opts.subscription);
+            await pullOneShot(client, teamId, sub, {
+                limit,
+                waitSeconds,
+                format,
+                ...(opts.receiptFile ? { receiptFile: opts.receiptFile } : {}),
+                failIfEmpty: opts.failIfEmpty === true,
+            });
+        });
+    });
+}
+/**
+ * `--receipt` / `--receipt-file` 收两种形状：
+ *   - sidecar（`{subscriptionId, cursorSeq, throughSeq, receipt}`，`notify pull --receipt-file` 产出）
+ *   - 裸 receipt（`{subscriptionId, fromCursorSeq, …, signature}`）
+ * 两者都接受，agent 不必自己拆包。
+ */
+export function extractAckInput(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new JsonArgError("--receipt 须为 JSON 对象（sidecar 或裸 receipt）。");
+    }
+    const obj = raw;
+    const inner = obj.receipt;
+    if (inner && typeof inner === "object" && !Array.isArray(inner)) {
+        return {
+            receipt: inner,
+            cursorSeq: typeof obj.cursorSeq === "string" ? obj.cursorSeq : undefined,
+            throughSeq: typeof obj.throughSeq === "string" ? obj.throughSeq : undefined,
+        };
+    }
+    if (typeof obj.signature !== "string") {
+        throw new JsonArgError("--receipt 既不是 sidecar（缺 receipt 字段）也不是裸 receipt（缺 signature 字段）。");
+    }
+    return {
+        receipt: obj,
+        cursorSeq: typeof obj.fromCursorSeq === "string" ? obj.fromCursorSeq : undefined,
+        throughSeq: typeof obj.maxDeliveredSeq === "string" ? obj.maxDeliveredSeq : undefined,
+    };
+}
+function registerAckCommand(notify) {
+    notify
+        .command("ack")
+        .description("POST .../notification-events/ack — 推进连续 watermark（「seq ≤ throughSeq 的全部已完成」，不是执行回执）")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--subscription <nameOrId>", "订阅名或 uuid")
+        .option("--expected-cursor-seq <seq>", "CAS：ack 前的 cursorSeq（缺省取 receipt/sidecar 里的 fromCursorSeq）")
+        .option("--through-seq <seq>", "推进到哪一条（缺省取 sidecar 的 throughSeq / receipt 的 maxDeliveredSeq）")
+        .option("--receipt <json>", "pull 返回的 receipt 或 sidecar JSON（支持 @<file> 与 - 读 stdin）")
+        .option("--receipt-file <path>", "从文件/`-`(stdin) 读 receipt / sidecar JSON")
+        .action(async (opts) => {
+        await runNotify("ack", async () => {
+            const teamId = resolveTeamId(opts.team);
+            const parsed = resolveJsonArg({
+                inline: opts.receipt,
+                file: opts.receiptFile,
+                label: "--receipt",
+                required: true,
+            });
+            const { receipt, cursorSeq, throughSeq } = extractAckInput(parsed);
+            const expectedCursorSeq = assertSeq(opts.expectedCursorSeq ??
+                cursorSeq ??
+                fail("缺少 --expected-cursor-seq（receipt/sidecar 里也没有）。"), "--expected-cursor-seq", true);
+            const through = assertSeq(opts.throughSeq ??
+                throughSeq ??
+                fail("缺少 --through-seq（receipt/sidecar 里也没有）。"), "--through-seq", false);
+            const client = requireClient();
+            const sub = await resolveSubscription(client, teamId, opts.subscription);
+            printJson(await client.ackNotificationCursor(teamId, {
+                subscriptionId: sub.id,
+                expectedCursorSeq,
+                throughSeq: through,
+                receipt,
+            }));
+        });
+    });
+}
+function registerSourceConfigCommands(notify) {
+    const cfg = notify
+        .command("source-configs")
+        .description("后台侧 source 配置（数据，不发版）：节点档位/过滤/字段勾选/保留期 + 实时 kill switch");
+    cfg
+        .command("sources")
+        .description("GET .../notification-sources — registry 声明（可勾字段/默认档位）+ 本 team 的 active config")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            printJson(await requireClient().listNotificationSources(teamId));
+        });
+    });
+    cfg
+        .command("list")
+        .description("GET .../notification-sources/:sourceId/configs — 该 source 的历史 version（老版本只读留档）")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--source <sourceId>", "sourceId")
+        .option("--limit <n>", "1..200，默认 50")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            const limit = parseIntOption(opts.limit, "--limit", 1, 200);
+            printJson(await requireClient().listNotificationSourceConfigs(teamId, opts.source, limit === undefined ? {} : { limit }));
+        });
+    });
+    cfg
+        .command("get")
+        .description("GET .../notification-sources/:sourceId/configs/:configId")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--source <sourceId>", "sourceId")
+        .requiredOption("--id <uuid>", "config version 行 id")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            printJson(await requireClient().getNotificationSourceConfig(teamId, opts.source, opts.id));
+        });
+    });
+    cfg
+        .command("create")
+        .description("POST .../notification-sources/:sourceId/configs — 创建新的不可变 version（默认立即激活；只影响新物化的 schedule）")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--source <sourceId>", "sourceId（须与 body.sourceId 一致）")
+        .option("--no-activate", "只建 draft 不激活（默认建完即激活）")
+        .option("-j, --json <json>", "请求体 JSON（也支持 @<file> 与 - 读 stdin）")
+        .option("--json-file <path>", "从文件/`-`(stdin) 读请求体 JSON")
+        .option("--apply", "确认执行")
+        .option("--dry-run", "只预览")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            const body = resolveJsonArg({
+                inline: opts.json,
+                file: opts.jsonFile,
+                label: "-j / --json",
+                required: true,
+            });
+            const activate = opts.activate !== false;
+            if (!assertApplyOrDryRun(opts, {
+                command: "notify source-configs create",
+                danger: activate
+                    ? "新建并【立即激活】config version：若其 configuredFields 不含某个 active 订阅的 requiredFields，会被 409 拒绝激活"
+                    : "新建 draft config version（不激活）",
+                summary: { sourceId: opts.source, activate, body },
+            })) {
+                return;
+            }
+            printJson(await requireClient().createNotificationSourceConfig(teamId, opts.source, body, { activate }));
+        });
+    });
+    cfg
+        .command("activate")
+        .description("POST .../notification-sources/:sourceId/configs/:configId/activate — 激活某个已建 version")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--source <sourceId>", "sourceId")
+        .requiredOption("--id <uuid>", "config version 行 id")
+        .option("--apply", "确认执行")
+        .option("--dry-run", "只预览")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            if (!assertApplyOrDryRun(opts, {
+                command: "notify source-configs activate",
+                danger: "激活会做双向前置检查：打掉某个 active 订阅的 requiredFields 时 409 拒绝（Phase 1 无强制覆盖）",
+                summary: { sourceId: opts.source, configId: opts.id },
+            })) {
+                return;
+            }
+            printJson(await requireClient().activateNotificationSourceConfig(teamId, opts.source, opts.id));
+        });
+    });
+    cfg
+        .command("set-enabled")
+        .description("PUT .../notification-sources/:sourceId/enabled — 实时 kill switch（影响全部在途 schedule；不 bump sourceConfigVersion）")
+        .option("-t, --team <teamId>", "Team UUID（缺省用当前 context）")
+        .requiredOption("--source <sourceId>", "sourceId（身份级开关，改的是该 source 下全部历史 version 行）")
+        .requiredOption("--enabled <bool>", "true|false")
+        .option("--apply", "确认执行")
+        .option("--dry-run", "只预览")
+        .action(async (opts) => {
+        await runNotify("admin", async () => {
+            const teamId = resolveTeamId(opts.team);
+            const raw = String(opts.enabled).toLowerCase();
+            if (raw !== "true" && raw !== "false") {
+                fail("--enabled 只能是 true 或 false。");
+            }
+            const enabled = raw === "true";
+            if (!assertApplyOrDryRun(opts, {
+                command: "notify source-configs set-enabled",
+                danger: enabled
+                    ? "重新启用：**不会**补发 disabled 期间已标 missed 的节点"
+                    : "停用：disabled 期间到点的 schedule 一律不发事件、直接标 missed（不排队补发）",
+                summary: { sourceId: opts.source, enabled },
+            })) {
+                return;
+            }
+            printJson(await requireClient().setNotificationSourceEnabled(teamId, opts.source, enabled));
+        });
+    });
+}
+//# sourceMappingURL=register-notify.js.map