botmux 3.9.0 → 3.9.2

package/dist/services/issue-board-store.js

@@ -0,0 +1,472 @@
+/**
+ * Issue Board 本地状态：binding（issue ↔ 本机会话锚点）与 outbox（状态回写发件箱）。
+ *
+ * 平台侧契约见 platform 仓 DESIGN-issue-board.md §六/§七。那份设计是按 Desktop 写的，
+ * Desktop 有 SQLite、能把「建本地任务」和「写 binding」放进**同一个事务**。botmux 没有
+ * SQLite（全仓都是 JSON + 原子写），所以这里换一套等价的崩溃安全约定。
+ *
+ * ## 时序：binding 只能在拿到 anchor 之后写
+ *
+ * binding 的主键 `anchorId` 是 `chatId` / `rootMessageId`——**建群/发 seed 之后才存在**，
+ * 所以不可能「先写 binding 再建群」。实际顺序是：
+ *
+ *   1. platform claim            → 拿到 claimId / claimEpoch / stateRev
+ *   2. 建群（或发无 @ 的 seed）  → 拿到 anchorId。**held**：不传 kickoffBot/kickoffPrompt
+ *   3. createBinding(anchorId…)  → 落盘，durable boundary（放在 createGroupWithBots 的
+ *                                  `onChatCreated` 同步钩子里写，函数返回前就已持久化）
+ *   4. platform bind(localTaskRef) → bindState 转 'bound'
+ *   5. kickoff（@bot）→ activate  → daemon 这时才真正起会话
+ *
+ * ## 崩溃语义：危险窗口在 2→3，靠「held」兜底
+ *
+ * 「群已建、binding 未写」= **孤儿群**。它比旧叙事里的「binding 有、群没有」难对账，但
+ * 危害被第 2 步的 held 挡住了：没发 kickoff 就没有任何 bot 被 @ 起来，daemon 不会创建
+ * 会话，**本机没有 agent 在跑**——与旧叙事想要的安全性质相同，只是换了达成方式。
+ *
+ * 对账要认出孤儿群，就必须留下 claimId→issue 的痕迹（否则 claimId 只活在内存里，崩了既
+ * 找不回 claim、也认不出哪个群是它的）。落点要钉在 **claim 成功之后、建群之前**——危险
+ * 窗口从 claim 返回的那一刻就开始了，写「建群前」不够精确：claim 已成功而意图未落盘时崩
+ * 溃，同样丢 claimId。held 只保证「没有 agent 在跑」，不保证「能对账续跑」，这两件事别混。
+ *
+ * ⚠️ 这份「claim 意图」存储**本刀还没有**——本模块只含 binding + outbox。拉群领取那一刀
+ * 必须补上（存 claimId / issueId / teamId / claimEpoch / stateRev），并把 claimId 同时写进
+ * 群名或 seed 正文，形成「本地意图 + 群侧标记」双通道反查。届时的对账策略：
+ *  - 有 claim 意图、无 binding → 按 claimId 反查群：找到就补写 binding 续跑，找不到就
+ *    释放 claim（或直接等平台 lease 到期由 sweeper 回收）
+ *  - 有 binding 且 `bindState==='pending'` → 重试 bind；被平台拒（issue 被回收/别人领走/
+ *    代次过期）则置 void 并解散那个 held 群，此刻同样没有 agent 在跑
+ *
+ * ## 写者不止一个，所以每次 RMW 都要拿锁
+ *
+ * 曾经这里写着「单写者假设：claim 流程与 outbox pump 都只跑在 dashboard 进程，故不加锁」。
+ * **那句话是错的**：`botmux report` 跑在 **agent 的 CLI 子进程**里（见 cli.ts 的 report
+ * issue 分支），它照样 enqueue/claim/settle 这两个文件，而发件箱 pump 跑在 **daemon 进程**。
+ *
+ * 危害不是"字段短暂回退"这么轻。两个文件都是**整份 map/数组重写**：进程 A 读到快照、进程 B
+ * 在这期间新建了一条 binding、A 再把自己的快照写回去 —— **B 那条 binding 直接消失**，那个群
+ * 与 issue 的关联凭空丢掉，而且全程无声。概率低（要求毫秒级交错），后果不可恢复。
+ *
+ * 所以所有 RMW 走 `withIssueLock`（[[utils/file-lock]] 的跨进程 advisory lock，与多 daemon
+ * 并发写 `bots.json` 同一套）。只读函数不加锁：原子写保证读者要么看到旧的完整文件、要么看到
+ * 新的完整文件，不存在半截状态。
+ *
+ * ⚠️ 锁**不可重入**：加锁的公开函数之间不能互相调用（`settleOutboxRow` 要改 binding，就用
+ * 下面的 `updateBindingUnlocked` 而不是 `updateBinding`）。
+ *
+ * 存储：`{dataDir}/issue-bindings.json`、`{dataDir}/issue-outbox.json`。
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { atomicWriteFileSync } from '../utils/atomic-write.js';
+import { withFileLockSync } from '../utils/file-lock.js';
+import { sessionKey } from '../core/types.js';
+/**
+ * 串行化对 issue board 本地状态的读-改-写。
+ *
+ * 一把锁覆盖 bindings / outbox / claim-intents 三个文件而不是各锁各的：`enqueueDesiredStatus`
+ * 本来就要跨两个文件写（bump 计数器 + 排行），分开锁等于没锁。
+ *
+ * 3s 上限：这些临界区都是一次读一次写的毫秒级操作，等到 3 秒基本就是持锁进程死了——
+ * file-lock 自己会 stale-break，这里超时抛错让调用方看见，好过无限等。
+ */
+function withIssueLock(dataDir, fn) {
+    return withFileLockSync(join(dataDir, 'issue-board'), fn, { maxWaitMs: 3_000 });
+}
+/**
+ * localTaskRef 的**唯一**构造入口，且 `createBinding` 会自己调它——`CreateBindingInput`
+ * 里没有 localTaskRef 字段，调用方**没有**手拼的机会。
+ *
+ * 之所以做成内生而不是「约定调用方用这个函数」：拼反了顺序不会当场报错，要等平台 bind
+ * 记下的 localTaskRef 与崩溃恢复时的重确认对不上，那条 held 会话被判 claim_mismatch 作废
+ * 才暴露——离出错点太远。直接复用 botmux 自己的 `sessionKey`，与 activeSessions 键同源。
+ */
+export function buildLocalTaskRef(anchorId, larkAppId) {
+    return sessionKey(anchorId, larkAppId);
+}
+function bindingsPath(dataDir) {
+    return join(dataDir, 'issue-bindings.json');
+}
+function outboxPath(dataDir) {
+    return join(dataDir, 'issue-outbox.json');
+}
+function readJson(fp, fallback) {
+    if (!existsSync(fp))
+        return fallback;
+    try {
+        const parsed = JSON.parse(readFileSync(fp, 'utf-8'));
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+    }
+    catch {
+        // 文件损坏 → fallback。binding 丢了会让在跑的会话失去 issue 关联（人工 force-detach
+        // 兜底），但绝不能因为一个坏文件让整个 daemon 起不来。
+    }
+    return fallback;
+}
+// ── bindings ────────────────────────────────────────────────────────────────
+export function listBindings(dataDir) {
+    return Object.values(readJson(bindingsPath(dataDir), {}));
+}
+export function getBinding(dataDir, anchorId) {
+    return readJson(bindingsPath(dataDir), {})[anchorId] ?? null;
+}
+/**
+ * 这条 binding 是否还代表「本机正持有这个 issue」。
+ *
+ * 抽成一个谓词而不是到处写 `!== 'void'`：终态从一个变成两个（`void` / `released`）时，
+ * 散落各处的判断只要漏改一处，就会出现「已释放的 issue 仍被当成已领取」——重领被拦、
+ * 回写继续发，而且全程不报错。加状态就改这一个地方。
+ */
+export function isActiveBindState(state) {
+    return state === 'pending' || state === 'bound';
+}
+/** 按 claimId 反查——崩溃恢复的入口（§六：不依赖平台「按 claimId 查 issue」的接口，那个接口不存在）。 */
+export function findBindingByClaimId(dataDir, claimId) {
+    return listBindings(dataDir).find((b) => b.claimId === claimId) ?? null;
+}
+/** 某 issue 当前在本机的活跃 binding（作废/已释放的不算）。用于「这个 issue 是不是我已经领了」。 */
+export function findActiveBindingByIssue(dataDir, issueId) {
+    return listBindings(dataDir).find((b) => b.issueId === issueId && isActiveBindState(b.bindState)) ?? null;
+}
+function writeBindings(dataDir, all) {
+    atomicWriteFileSync(bindingsPath(dataDir), JSON.stringify(all, null, 2) + '\n');
+}
+function claimIntentsPath(dataDir) {
+    return join(dataDir, 'issue-claims.json');
+}
+function writeClaimIntents(dataDir, all) {
+    atomicWriteFileSync(claimIntentsPath(dataDir), JSON.stringify(all, null, 2) + '\n');
+}
+export function listClaimIntents(dataDir) {
+    return Object.values(readJson(claimIntentsPath(dataDir), {}));
+}
+export function getClaimIntent(dataDir, claimId) {
+    return readJson(claimIntentsPath(dataDir), {})[claimId] ?? null;
+}
+/**
+ * 记下一次领取意图。**必须在 platform claim 返回成功后立刻调用，早于任何建群动作**。
+ *
+ * 同 claimId 重入返回既有记录（claim 本身幂等，重试不该产生第二条意图）。
+ */
+export function recordClaimIntent(dataDir, input, now = Date.now()) {
+    return withIssueLock(dataDir, () => {
+        const all = readJson(claimIntentsPath(dataDir), {});
+        const existing = all[input.claimId];
+        if (existing)
+            return existing;
+        const intent = { ...input, createdAt: now, updatedAt: now };
+        all[intent.claimId] = intent;
+        writeClaimIntents(dataDir, all);
+        return intent;
+    });
+}
+/** 回填 anchorId / chatId（建群成功后）。 */
+export function updateClaimIntent(dataDir, claimId, patch, now = Date.now()) {
+    return withIssueLock(dataDir, () => {
+        const all = readJson(claimIntentsPath(dataDir), {});
+        const cur = all[claimId];
+        if (!cur)
+            return null;
+        const next = { ...cur, ...patch, claimId: cur.claimId, createdAt: cur.createdAt, updatedAt: now };
+        all[claimId] = next;
+        writeClaimIntents(dataDir, all);
+        return next;
+    });
+}
+/**
+ * 领取流程走完（binding 已 bound）后清掉意图——此后 binding 自己就是完整证据。
+ *
+ * ⚠️ 清除必须**晚于** binding 落盘。反过来先清意图再写 binding，中间崩溃就同时丢掉了两份
+ * 证据，那个群彻底认不回来——这正是意图存在的意义。
+ */
+export function clearClaimIntent(dataDir, claimId) {
+    return withIssueLock(dataDir, () => {
+        const all = readJson(claimIntentsPath(dataDir), {});
+        if (!all[claimId])
+            return false;
+        delete all[claimId];
+        writeClaimIntents(dataDir, all);
+        return true;
+    });
+}
+/** 对账分类：意图还在、但没有对应 binding 的，就是需要人/流程接手的悬空领取。 */
+export function listDanglingClaimIntents(dataDir) {
+    const bound = new Set(listBindings(dataDir).map((b) => b.claimId));
+    return listClaimIntents(dataDir).filter((i) => !bound.has(i.claimId));
+}
+/**
+ * 写入一条 pending binding。**在建群/发 seed 拿到 anchorId 之后调用**——主键就是那个
+ * anchor，之前不可能有。放在 `createGroupWithBots` 的 `onChatCreated` 同步钩子里写，
+ * 让它成为「群已存在」到「群已归属某个 issue」之间的 durable boundary（见文件头时序）。
+ *
+ * 两条不变式都在这层强制，不指望调用方自觉：
+ *  - **claimId 唯一**：同 claimId 重入直接返回既有行（本地幂等，对应 Desktop 侧的
+ *    `UNIQUE(claim_id)`）——领取重试不会产生第二条 binding、也不会重复建群。
+ *  - **一 issue 一活跃 binding**：同 issue 已有非 void 的 binding 却拿着不同 claimId 进来，
+ *    是调用方漏查（比如没先 `findActiveBindingByIssue`）。此时**抛错**而不是照写——写下去
+ *    就是同一个 issue 两个群、两个 agent 同时开工，而平台侧只认最后一次 claim，另一个群
+ *    会变成谁也不管的孤儿。抛在这里离原因最近；释放后重领是安全的（旧 binding 已置 void）。
+ */
+export function createBinding(dataDir, input, now = Date.now()) {
+    return withIssueLock(dataDir, () => {
+        const all = readJson(bindingsPath(dataDir), {});
+        const existing = Object.values(all).find((b) => b.claimId === input.claimId);
+        if (existing)
+            return existing;
+        const activeSameIssue = Object.values(all).find((b) => b.issueId === input.issueId && isActiveBindState(b.bindState));
+        if (activeSameIssue) {
+            throw new Error(`issue ${input.issueId} 已有活跃 binding（anchor=${activeSameIssue.anchorId}, claimId=${activeSameIssue.claimId}）；`
+                + '重复领取前应先 findActiveBindingByIssue 复用，或释放后再领');
+        }
+        const binding = {
+            ...input,
+            localTaskRef: buildLocalTaskRef(input.anchorId, input.larkAppId),
+            bindState: input.bindState ?? 'pending',
+            nextSourceSeq: 1,
+            createdAt: now,
+            updatedAt: now,
+        };
+        all[binding.anchorId] = binding;
+        writeBindings(dataDir, all);
+        return binding;
+    });
+}
+/** 局部更新一条 binding（read-modify-write，保住并发写入的其它字段）。 */
+export function updateBinding(dataDir, anchorId, patch, now = Date.now()) {
+    return withIssueLock(dataDir, () => updateBindingUnlocked(dataDir, anchorId, patch, now));
+}
+/** 已经持有 issue 锁时用这个——锁不可重入，嵌套调 `updateBinding` 会自己等死自己。 */
+function updateBindingUnlocked(dataDir, anchorId, patch, now) {
+    const all = readJson(bindingsPath(dataDir), {});
+    const cur = all[anchorId];
+    if (!cur)
+        return null;
+    const next = { ...cur, ...patch, anchorId: cur.anchorId, createdAt: cur.createdAt, updatedAt: now };
+    all[anchorId] = next;
+    writeBindings(dataDir, all);
+    return next;
+}
+/** 删除一条 binding（会话彻底结束且 issue 已终态后清理）。返回是否删掉。 */
+export function removeBinding(dataDir, anchorId) {
+    return withIssueLock(dataDir, () => {
+        const all = readJson(bindingsPath(dataDir), {});
+        if (!(anchorId in all))
+            return false;
+        delete all[anchorId];
+        writeBindings(dataDir, all);
+        return true;
+    });
+}
+// ── outbox ──────────────────────────────────────────────────────────────────
+function readOutbox(dataDir) {
+    const raw = readJson(outboxPath(dataDir), []);
+    return Array.isArray(raw) ? raw : [];
+}
+function writeOutbox(dataDir, rows) {
+    atomicWriteFileSync(outboxPath(dataDir), JSON.stringify(rows, null, 2) + '\n');
+}
+export function listOutbox(dataDir, anchorId) {
+    const rows = readOutbox(dataDir);
+    return anchorId === undefined ? rows : rows.filter((r) => r.anchorId === anchorId);
+}
+/**
+ * 投影一次「本会话应达的 issue 状态」到发件箱（§七 去重合并）。
+ *
+ * 合并规则（**与最新未完成目标比，不是与 lastSyncedStatus 比**）：
+ *  - 该 binding 已有 `pending` 行 → **就地覆盖**它的 targetStatus 并重分配 sourceSeq，不新增行；
+ *  - 否则仅当 desired 与「最新目标 ∪ lastSyncedStatus」都不同才排一条新行。
+ *
+ * 为什么必须这样：离线期间 30s 一次的 tick 会反复投影，若每次都追加，恢复后会把一长串
+ * 早已过时的中间态依次发给平台——既刷无效自迁移，又让**最新**状态排在队尾迟迟到不了。
+ *
+ * 返回排出的行；无需回写时返回 null。
+ */
+export function enqueueDesiredStatus(dataDir, anchorId, desired, opts = {}, now = Date.now()) {
+    return withIssueLock(dataDir, () => {
+        const bindings = readJson(bindingsPath(dataDir), {});
+        const binding = bindings[anchorId];
+        // 终态（void/released）之后不再回写：那个 issue 已经不归本机管了，继续发只会被平台拒。
+        // 释放本身也走这里，但它是在 binding 还是 bound 的时候排的行——先排队再改状态，见
+        // [[issue-release]] 的「平台先行、本地后写」。
+        if (!binding || !isActiveBindState(binding.bindState))
+            return null;
+        const rows = readOutbox(dataDir);
+        const mine = rows.filter((r) => r.anchorId === anchorId);
+        const pendingIdx = rows.findIndex((r) => r.anchorId === anchorId && r.state === 'pending');
+        const latestUnsettled = mine
+            .filter((r) => r.state === 'pending' || r.state === 'inflight')
+            .sort((a, b) => b.sourceSeq - a.sourceSeq)[0];
+        // 已经在追同一个目标（或已经同步到位）→ 无事可做。
+        if (pendingIdx < 0) {
+            const latestTarget = latestUnsettled?.targetStatus;
+            if (desired === latestTarget || (latestTarget === undefined && desired === binding.lastSyncedStatus)) {
+                return null;
+            }
+        }
+        else if (rows[pendingIdx].targetStatus === desired && rows[pendingIdx].attentionReason === opts.attentionReason) {
+            return null;
+        }
+        // 分配序号时取「计数器」与「本 binding 在 outbox 里出现过的最大序号 + 1」的较大者。
+        //
+        // 写序（见下）已经保证正常路径不会复用序号；这一层是**自愈**：万一计数器因为任何原因
+        // 落后于已排出的行（历史遗留数据、外部改文件、未来重构把写序改回去），复用序号的后果是
+        // 平台按 `sourceSeq <= lastSourceSeq` 静默 no-op ——**新状态永远上不去且毫无报错**。
+        // 这种失败太安静，值得用两行把它变成不可能，而不是只靠写序的正确性来担保。
+        // prune 删掉旧的 done 行会让 max 变小，但计数器只增不减，取较大者天然安全。
+        const maxSeen = mine.reduce((m, r) => Math.max(m, r.sourceSeq), 0);
+        const sourceSeq = Math.max(binding.nextSourceSeq, maxSeen + 1);
+        const row = {
+            writeId: randomUUID(),
+            anchorId,
+            sourceSeq,
+            targetStatus: desired,
+            ...(opts.attentionReason ? { attentionReason: opts.attentionReason } : {}),
+            claimId: binding.claimId,
+            claimEpoch: binding.claimEpoch,
+            ...(opts.expectedStateRev !== undefined
+                ? { expectedStateRev: opts.expectedStateRev }
+                : binding.platformStateRev !== undefined
+                    ? { expectedStateRev: binding.platformStateRev }
+                    : {}),
+            state: 'pending',
+            attempts: 0,
+            createdAt: now,
+        };
+        // ⚠️ 写序不能反：**先 bump 计数器落盘，再写 outbox**。
+        //
+        // 这是两个文件的 RMW，单文件 atomicWrite 保不了跨文件原子性，中间必然存在崩溃窗口。
+        // 两种写序的崩溃后果完全不同：
+        //  - 先 outbox 后 binding（错）：outbox 已有 seq=N、计数器还停在 N。该行 settle 后
+        //    下一次投影会**复用 N**，平台见 `sourceSeq <= lastSourceSeq` 直接 no-op —— 新状态
+        //    **永远上不去**，而且一路静默，真机上极难查。
+        //  - 先 binding 后 outbox（对）：最坏是 outbox 那条没写成、序号 N 被跳过。平台只要求
+        //    单调、不要求连续，跳号无害；丢掉的投影下一拍 tick 会用更大的 seq 重新排出来。
+        bindings[anchorId] = { ...binding, nextSourceSeq: sourceSeq + 1, updatedAt: now };
+        writeBindings(dataDir, bindings);
+        if (pendingIdx >= 0)
+            rows[pendingIdx] = row; // 就地覆盖未发送行
+        else
+            rows.push(row);
+        writeOutbox(dataDir, rows);
+        return row;
+    });
+}
+/**
+ * 领取该 binding 的下一条待发行（`pending → inflight` 的 CAS）。
+ *
+ * **串行**：同一 binding 已有 inflight 行时返回 null——平台侧要求同一 issue 的 sourceSeq
+ * 单调到达，并发发送会让顺序乱掉。`nextRetryAt` 未到的行也不返回（退避）。
+ */
+export function claimNextOutboxRow(dataDir, anchorId, now = Date.now()) {
+    return withIssueLock(dataDir, () => {
+        const rows = readOutbox(dataDir);
+        const mine = rows.filter((r) => r.anchorId === anchorId);
+        if (mine.some((r) => r.state === 'inflight'))
+            return null;
+        // 按 sourceSeq 最小的先发，不依赖数组顺序。今天「追加保序 + 就地覆盖」恰好也对，但
+        // 一旦以后 prune/compaction 重排数组，按下标取就可能先发高序号再发低序号——平台按
+        // 单调判重，低序号那条会被静默丢弃。显式排序把这条契约钉在代码里而不是数组布局上。
+        const nextRow = mine
+            .filter((r) => r.state === 'pending' && (r.nextRetryAt ?? 0) <= now)
+            .sort((a, b) => a.sourceSeq - b.sourceSeq)[0];
+        if (!nextRow)
+            return null;
+        const idx = rows.findIndex((r) => r.writeId === nextRow.writeId);
+        if (idx < 0)
+            return null;
+        rows[idx] = { ...rows[idx], state: 'inflight', attempts: rows[idx].attempts + 1 };
+        writeOutbox(dataDir, rows);
+        return rows[idx];
+    });
+}
+/**
+ * 发送成功：标 done，并把平台返回的 stateRev / 已同步状态写回 binding。
+ *
+ * `applied: false` 用于「这条行不必再发了，但平台**没有**采纳它」——目前只有一种情况：
+ * 409 对账发现 claim 已易主。此时**绝不能**写 `lastSyncedStatus`：写了本地就以为
+ * "已经是 in_review 了"，下一次交付会走幂等分支直接回成功，而平台上那条压根没变。
+ */
+export function settleOutboxRow(dataDir, writeId, result, now = Date.now()) {
+    withIssueLock(dataDir, () => {
+        const rows = readOutbox(dataDir);
+        const idx = rows.findIndex((r) => r.writeId === writeId);
+        if (idx < 0)
+            return;
+        const row = rows[idx];
+        rows[idx] = { ...row, state: 'done' };
+        writeOutbox(dataDir, rows);
+        const binding = getBinding(dataDir, row.anchorId);
+        // 用平台回传的 `claim.lastSourceSeq` 校准本地计数器。
+        //
+        // 平台才是「已应用到哪一号」的权威：它按 `sourceSeq <= lastSourceSeq` 判重，本地计数器
+        // 一旦落后（dataDir 从旧快照恢复、文件被外部改、其它路径抢跑过序号），之后每一条回写都
+        // 会被静默丢弃——平台回 200、本地记成功、状态却永远上不去。真机 e2e 里就撞到过这一幕。
+        //
+        // 单写者假设下计数器本该恒领先，所以这只是兜底；但代价是一次 max()，而漏掉的代价是
+        // 无声的状态停更，值得。
+        const syncedSeq = result.platformLastSourceSeq !== undefined && binding
+            ? Math.max(binding.nextSourceSeq, result.platformLastSourceSeq + 1)
+            : undefined;
+        updateBindingUnlocked(dataDir, row.anchorId, {
+            ...(result.applied === false ? {} : { lastSyncedStatus: row.targetStatus }),
+            ...(result.platformStateRev !== undefined ? { platformStateRev: result.platformStateRev } : {}),
+            ...(syncedSeq !== undefined && syncedSeq !== binding?.nextSourceSeq ? { nextSourceSeq: syncedSeq } : {}),
+        }, now);
+    });
+}
+/** 发送失败：退回 pending + 指数退避（上限 5min）。`fatal` 用于平台明确拒绝、重试无意义的情况。 */
+export function failOutboxRow(dataDir, writeId, error, opts = {}, now = Date.now()) {
+    withIssueLock(dataDir, () => {
+        const rows = readOutbox(dataDir);
+        const idx = rows.findIndex((r) => r.writeId === writeId);
+        if (idx < 0)
+            return;
+        const row = rows[idx];
+        const backoff = Math.min(1_000 * 2 ** Math.max(0, row.attempts - 1), 5 * 60_000);
+        rows[idx] = {
+            ...row,
+            state: opts.fatal ? 'failed' : 'pending',
+            lastError: error.slice(0, 500),
+            ...(opts.fatal ? {} : { nextRetryAt: now + backoff }),
+        };
+        writeOutbox(dataDir, rows);
+    });
+}
+/**
+ * 启动对账：把本机所有 `inflight` 退回 `pending`。
+ *
+ * 进程在「标 inflight 后、记录响应前」崩溃时，那一行会永远停在 inflight 并**堵死该
+ * binding 的串行 pump**（claimNextOutboxRow 见到 inflight 就返回 null）。平台侧的
+ * sourceSeq 单调 + 终态幂等保证重复投递是安全的，所以无脑退回即可，不需要发送租约。
+ *
+ * 返回被退回的行数。
+ */
+export function resetInflightToPending(dataDir) {
+    return withIssueLock(dataDir, () => {
+        const rows = readOutbox(dataDir);
+        let n = 0;
+        const next = rows.map((r) => {
+            if (r.state !== 'inflight')
+                return r;
+            n += 1;
+            return { ...r, state: 'pending' };
+        });
+        if (n > 0)
+            writeOutbox(dataDir, next);
+        return n;
+    });
+}
+/** 清理已完成的发件箱行（保留最近 `keep` 条便于排查）。返回清掉的行数。 */
+export function pruneOutbox(dataDir, keep = 50) {
+    return withIssueLock(dataDir, () => {
+        const rows = readOutbox(dataDir);
+        const settled = rows.filter((r) => r.state === 'done');
+        if (settled.length <= keep)
+            return 0;
+        const drop = new Set(settled.sort((a, b) => a.createdAt - b.createdAt).slice(0, settled.length - keep).map((r) => r.writeId));
+        writeOutbox(dataDir, rows.filter((r) => !drop.has(r.writeId)));
+        return drop.size;
+    });
+}
+//# sourceMappingURL=issue-board-store.js.map

package/dist/services/issue-board-store.js.map

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

package/dist/services/issue-claim-flow.d.ts

@@ -0,0 +1,160 @@
+import type { CreateGroupOpts, CreateGroupResult } from './group-creator.js';
+import type { IssueClientResult, PlatformIssue } from '../platform/issue-client.js';
+import { type IssueBinding, type IssueStatus } from './issue-board-store.js';
+/**
+ * 群名里带的领取标记。对账时靠它把「平台上有 claim、本地没有 binding」的孤儿群认回来
+ * ——本地意图是一条腿，这个标记是另一条腿，少哪条都会留下认不出的群。
+ *
+ * 只取前 8 位十六进制（32 bit）：群名是给人看的，不该被一串 32 字符的随机数占满；
+ * 同时在手可数的候选群里，32 bit 足以唯一定位。
+ */
+export declare function claimMarker(claimId: string): string;
+export declare function matchesClaimMarker(groupName: string, claimId: string): boolean;
+/**
+ * 拼领取群名：`<标题> #<claimId 前 8 位>`，**标题被截、标记一定完整**。
+ *
+ * 不截的话飞书自己会截，而它从尾部截——先吃掉的正是尾部那个 `#claimId` 标记，也就是双通道
+ * 反查的一条腿。那条腿断了不会报错：对账时只是"这个群不像是任何一次领取的"，然后被当成
+ * 无主群跳过。宁可标题短一点。
+ *
+ * 标记放尾部而不是挪到前面：群列表里先看到的应该是任务在说什么，一串十六进制不配占开头。
+ * 长度自己控住了，位置就不再是风险。
+ */
+export declare function claimGroupName(title: string, claimId: string): string;
+/**
+ * 平台上这条 issue 的详情深链。
+ *
+ * 路由形状来自平台前端：tab 在 hash（`#issues`）、详情在 query（`?issue=<id>`），见
+ * platform 仓 `frontend/src/App.tsx` 的 Tabs 与 `IssueBoard.tsx` 的 `openDetail`。
+ * 拼不出来（平台地址为空/非法）就返回 undefined，卡片少一个按钮而已，不该因此报错。
+ */
+export declare function issueDetailUrl(platformBaseUrl: string, issueId: string): string | undefined;
+export interface ClaimFlowDeps {
+    dataDir: string;
+    platformBaseUrl: string;
+    claim: (issueId: string, args: {
+        claimId: string;
+        agent?: string;
+        repoLabel?: string;
+        expectedStateRev: number;
+    }) => Promise<IssueClientResult<{
+        claim: {
+            claimEpoch: number;
+        };
+        issue: PlatformIssue;
+    }>>;
+    bind: (issueId: string, args: {
+        claimId: string;
+        localTaskRef: string;
+        expectedStateRev: number;
+        localTaskLabel?: string;
+        localTaskUrl?: string;
+    }) => Promise<IssueClientResult<{
+        issue: PlatformIssue;
+    }>>;
+    createGroup: (opts: CreateGroupOpts) => Promise<CreateGroupResult>;
+    /**
+     * 往新群里发开工播报（[[issue-card]] 的 `buildIssueKickoffCard`）。
+     *
+     * **best-effort**：失败只记日志，绝不让领取失败——它是给人看的，不是协议的一环。
+     * 不传就不播报（单测里默认不传）。
+     */
+    announce?: (chatId: string, card: string) => Promise<void>;
+    /** 播报失败时的旁路（生产接 logger；不注入就静默）。 */
+    onAnnounceError?: (reason: string) => void;
+    /** in_progress 回写失败时的旁路（同上）。失败不推翻领取，但必须留下痕迹。 */
+    onStatusError?: (reason: string) => void;
+    /** 发 kickoff（@ 目标 bot）把会话激活。返回 messageId。 */
+    activate: (chatId: string, botLarkAppId: string, prompt: string) => Promise<string>;
+    /**
+     * 激活成功后把平台状态推到 `in_progress`。
+     *
+     * **必填，不是可选**：平台的 activation lease 只扫 `status=claimed`（5 分钟），不回写
+     * in_progress 的话 sweeper 会把任务打成 `needs_attention(claim_activate_timeout)`，而
+     * 那个状态**回不去**——平台只放行 `task_blocked` 恢复成 in_progress，超时的只能
+     * open/reopened（都清 claim），群里的活就废了。做成可选依赖的话，漏传不会有任何报错，
+     * 引信就这么静默装回去了；宁可编译期逼调用方给。
+     *
+     * 与 fetchIssue 一起构成 [[issue-status-writer]] 的 `StatusWriterDeps`，回写走那边的
+     * `projectStatus`——sourceSeq 分配、串行、409 对账、退避只实现一次。
+     */
+    writeStatus: (issueId: string, args: {
+        claimId: string;
+        claimEpoch: number;
+        sourceSeq: number;
+        status: IssueStatus;
+        expectedStateRev: number;
+    }) => Promise<IssueClientResult<{
+        issue: PlatformIssue;
+    }>>;
+    /** 撞 409 时判断「平台还认不认这个 claim」。见 issue-status-writer。 */
+    fetchIssue: (teamId: string, issueId: string) => Promise<PlatformIssue | null>;
+    newClaimId?: () => string;
+    now?: () => number;
+}
+export interface ClaimFlowArgs {
+    /** `body` 只进开工播报（平台侧允许为空），所以这里放宽成可选。 */
+    issue: Pick<PlatformIssue, '_id' | 'title' | 'stateRev' | 'targetRepoLabel'> & {
+        body?: string;
+    };
+    teamId: string;
+    /** 由哪个 bot 承接这个 issue —— 决定 localTaskRef 的 appId 段与 kickoff 目标。 */
+    larkAppId: string;
+    /**
+     * 上送平台 `claim.agent` 的展示名。平台把这个值原样渲染在 issue 详情里，所以必须是**人能
+     * 认出来的名字**（`claude-loopy`），不是 `cli_xxx` ——早先直接传 larkAppId，看板上只能看到
+     * 一串 appId，谁在干这活完全看不出来。缺省回落到 larkAppId，保证总有值。
+     */
+    agentLabel?: string;
+    /** 建群者（通常是 dashboard 所属的那个 bot）。 */
+    creatorLarkAppId: string;
+    /** 一并拉进群的其它 bot。 */
+    peerLarkAppIds?: string[];
+    /** 把人按 union_id 拉进群（open_id 是 app-scoped 的，跨 bot 不通用）。 */
+    ownerUnionIds?: string[];
+    /**
+     * agent 干活的目录。会作为 `bindWorkingDir` 绑到新群上（oncall 绑定），**必须传**——
+     * 不传的话人在卡片里选的仓库根本不会生效，会话会起在 bot 的默认目录里，
+     * 等于让 agent 在错误的仓库动手，而且没有任何报错。
+     */
+    workingDir: string;
+    kickoffPrompt: string;
+}
+export type ClaimFlowResult = {
+    ok: true;
+    binding: IssueBinding;
+    chatId: string;
+    kickoffMessageId: string;
+}
+/** 领取本身没成功，本地没有留下任何痕迹，重试是安全的。 */
+ | {
+    ok: false;
+    stage: 'claim';
+    reason: string;
+    alreadyLocal?: IssueBinding;
+}
+/** 已 claim 但群没建成：意图在盘上，对账会接手（释放 claim 或补建）。 */
+ | {
+    ok: false;
+    stage: 'group';
+    reason: string;
+    claimId: string;
+}
+/** 群建好了、binding 也落盘了，但 bind 被平台拒 → binding 置 void，群留给人处理。 */
+ | {
+    ok: false;
+    stage: 'bind';
+    reason: string;
+    binding: IssueBinding;
+    chatId: string;
+}
+/** 前面全成，只差 kickoff。binding 已 bound，重试 activate 即可，不必重建群。 */
+ | {
+    ok: false;
+    stage: 'activate';
+    reason: string;
+    binding: IssueBinding;
+    chatId: string;
+};
+export declare function claimIssueIntoGroup(deps: ClaimFlowDeps, args: ClaimFlowArgs): Promise<ClaimFlowResult>;
+//# sourceMappingURL=issue-claim-flow.d.ts.map