@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/slack/announce.js

@@ -0,0 +1,725 @@
+// The daemon-templated announcer.
+//
+// Everything the daemon says in Slack on its own initiative is assembled HERE,
+// in deterministic TypeScript, from state the daemon already holds: no model
+// call, no overseer turn, nothing a prompt can reword. src/slack/messages.ts
+// owns the wording; this module owns *whether*, *where* and *exactly once*.
+//
+// Three rules shape the whole file:
+//
+//  1. **Root-on-first-event.** Whichever event reaches a PR
+//     first — the pickup at dispatch, or a `pr.not_picked_up` notice while it
+//     still waits — posts the top-level message and writes `slack_threads`.
+//     Every later post targets that recorded `root_ts`, never a reply's own ts.
+//     A reply for a PR with no root is PROMOTED to a root rather than dropped
+//     into the channel unthreaded.
+//  2. **Never block the daemon.** Slack is a side channel: every failure is
+//     recorded (`ok = 0`) and swallowed. No path here throws into dispatch or
+//     the verdict watcher, and none of them can delay a label, a verdict or a
+//     round.
+//  3. **Caps are daemon code.** Announcements bypass the model-turn caps (they
+//     cost nothing) but still pass `decideAnnouncement` — per-cause switch,
+//     cooldown with fold, one escalation bypass a day, rolling-hour ceiling —
+//     and the `slack_posts` idem_key ledger, claimed BEFORE the API call so a
+//     restart mid-post cannot double-post.
+//
+// Thread-lifecycle posts (pickup / verdict / re-round /
+// superseded) are deliberately NOT cooldown-gated: they answer a real event on
+// one PR and folding them would silently drop a verdict. They honour their
+// cause's `enabled` switch (never hardcoded) and the idem ledger, nothing else.
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { opsDay } from "../eod.js";
+import { snapshotHeartbeat, } from "../state.js";
+import { causeMessage, formatGap, heartbeatMessage, isoSeconds, pickupMessage, reRoundMessage, supersededMessage, verdictMessage, } from "./messages.js";
+import { announcementKey, causePolicy, decideAnnouncement, hourlyCeiling } from "./policy.js";
+/** Cause keys for the thread-lifecycle posts. They live in the same namespace
+ * as the unprompted causes so `[slack.policy.causes]` can silence any of them
+ * without a code change (none of them is hardcoded-on). */
+export const LIFECYCLE_CAUSES = {
+    pickup: "pr.pickup",
+    verdict: "pr.verdict",
+    reRound: "round.restarted",
+    superseded: "review.superseded",
+};
+/** Fixed ledger key for the pinned heartbeat: one message, updated forever. */
+export const HEARTBEAT_IDEM_KEY = "daemon.heartbeat";
+/** How long after a recovery the pinned heartbeat still names it. */
+const RECOVERY_BANNER_WINDOW_MS = 10 * 60_000;
+/** How long a recovered incident's message correction is retried for. */
+const RECOVERY_CORRECTION_WINDOW_MS = 24 * 60 * 60_000;
+/** Node timers are unref-able; an injected fake usually is not. */
+function unref(handle) {
+    handle?.unref?.();
+}
+/**
+ * PRs that have waited past `pickup_grace_min` without a round: queued, not
+ * paused, triggered, and with no round started since that trigger. Pure over
+ * the store — the caller drives it on a timer.
+ */
+export function scanNotPickedUp(store, cfg, now = new Date()) {
+    const graceMs = cfg.slack.policy.pickup_grace_min * 60_000;
+    const queued = store.allPrs().filter((p) => p.state === "queued" && !p.paused && p.trigger_ts);
+    const running = store.runningRounds().length;
+    const waiting = queued.filter((p) => {
+        const triggered = Date.parse(p.trigger_ts);
+        if (!Number.isFinite(triggered))
+            return false;
+        if (now.getTime() - triggered <= graceMs)
+            return false;
+        // A round already answering this trigger means the PR was picked up.
+        return !store.roundsFor(p.number).some((r) => Date.parse(r.started_at) >= triggered);
+    });
+    return waiting.map((p) => ({
+        pr: p.number,
+        age_min: Math.round((now.getTime() - Date.parse(p.trigger_ts)) / 60_000),
+        queue_depth: queued.length,
+        running,
+        max_concurrent: cfg.daemon.max_concurrent_rounds,
+    }));
+}
+export class SlackAnnouncer {
+    deps;
+    heartbeatTimer = null;
+    lastConnections = 1;
+    /** Recoveries (`incident_id@recovered_at`) whose correction Slack has
+     * ACCEPTED in this process. A refused edit stays out and is retried on the
+     * next tick; a restart forgets the set and re-applies the (identical) edit
+     * once. Keyed on the recovery, not the incident: a reopened-then-recovered
+     * incident is a new recovery and owes its own correction. */
+    correctedIncidents = new Set();
+    /** Ledger keys this process claimed — an unsettled claim it did not make
+     * is a previous run's, interrupted mid-post. */
+    /** Idem keys whose post request is awaiting Slack's answer in this process. */
+    inFlight = new Set();
+    /** Tail of each posting lane (one per PR, else one per idem key). */
+    lanes = new Map();
+    /** Corrections to one incident execute in order, including recovery edits. */
+    incidentEdits = new Map();
+    setTimeoutFn;
+    clearTimeoutFn;
+    setIntervalFn;
+    clearIntervalFn;
+    constructor(deps) {
+        this.deps = deps;
+        this.setTimeoutFn = deps.setTimeoutFn ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimeoutFn =
+            deps.clearTimeoutFn ?? ((h) => clearTimeout(h));
+        this.setIntervalFn = deps.setIntervalFn ?? ((fn, ms) => setInterval(fn, ms));
+        this.clearIntervalFn =
+            deps.clearIntervalFn ?? ((h) => clearInterval(h));
+    }
+    /** Inert when `[slack] enabled = false`: zero posts, zero state writes. */
+    get enabled() {
+        return this.deps.cfg.slack.enabled;
+    }
+    now() {
+        return (this.deps.now ?? (() => new Date()))();
+    }
+    log(msg, extra) {
+        (this.deps.log ?? (() => { }))(msg, extra);
+    }
+    // ---- the one posting path ---------------------------------------------
+    /**
+     * Claim, post, settle. Returns the message ts on success, undefined on any
+     * refusal or failure. Every NEW message goes through here; the only other
+     * Slack calls are edits and a pin of messages already posted: the
+     * heartbeat's own, and an incident's (its recovery, and its reopening).
+     */
+    async post(req) {
+        if (!this.deps.cfg.slack.enabled)
+            return undefined;
+        // Posts on one lane run one at a time, so each reads the thread root and
+        // the idem row only after the previous one settled: two causes racing on
+        // a threadless PR cannot both open a root, and two retries of one failed
+        // row (heartbeat ticks are unawaited) cannot both deliver. Every Slack call
+        // is bounded (api.ts), so a lane cannot wedge.
+        const lane = req.pr === undefined ? `key:${req.idemKey}` : `pr:${req.pr}`;
+        const prev = this.lanes.get(lane) ?? Promise.resolve();
+        const run = prev.then(() => this.postNow(req));
+        const tail = run.catch(() => undefined);
+        this.lanes.set(lane, tail);
+        void tail.then(() => {
+            if (this.lanes.get(lane) === tail)
+                this.lanes.delete(lane);
+        });
+        return run;
+    }
+    async postNow(req) {
+        const { cfg, store, slack } = this.deps;
+        const thread = req.pr === undefined ? undefined : store.slackThreadForPr(req.pr);
+        // Root-on-first-event: with no recorded root, this post BECOMES the root.
+        const threadTs = thread?.channel === cfg.slack.channel ? thread.root_ts : undefined;
+        if (req.hourCapped && store.slackPost(req.idemKey)?.ok !== 1) {
+            const ceiling = hourlyCeiling(store, cfg, this.now());
+            if (ceiling.reached) {
+                this.log(`slack: announcement suppressed at claim (${req.idemKey}) — ${ceiling.reason}`);
+                store.restoreSlackCooldown(req.hourCapped.key, req.hourCapped.prior);
+                return undefined;
+            }
+        }
+        // A previously FAILED attempt may be retried, claimed afresh like a new
+        // one (so the rolling-hour ceiling counts it); a delivered one, or one
+        // claimed and not yet settled, may not.
+        const claimed = store.recordSlackPost({
+            idem_key: req.idemKey,
+            kind: req.kind,
+            pr: req.pr ?? null,
+            thread_ts: threadTs ?? null,
+            chars: req.text.length,
+        }) ||
+            store.reclaimSlackPost(req.idemKey, { thread_ts: threadTs ?? null, chars: req.text.length });
+        if (!claimed) {
+            this.log(`slack: skipping duplicate post (${req.idemKey})`);
+            return undefined;
+        }
+        this.inFlight.add(req.idemKey);
+        let result;
+        try {
+            result = await slack.postMessage({
+                channel: cfg.slack.channel,
+                text: req.text,
+                thread_ts: threadTs,
+            });
+        }
+        catch (err) {
+            result = { ok: false, error: String(err), ambiguous: true };
+        }
+        finally {
+            this.inFlight.delete(req.idemKey);
+        }
+        if (!result.ok || !result.ts) {
+            if (result.ambiguous || result.ok) {
+                // Keep the existing reservation: Slack may have accepted this create.
+                store.noteSlackPostUnknown(req.idemKey, result.error ?? "no ts returned");
+                this.log(`slack: delivery unknown (${req.idemKey})`, result.error ?? "no ts returned");
+                return undefined;
+            }
+            store.settleSlackPost(req.idemKey, { ok: false, error: result.error ?? "no ts returned" });
+            this.log(`slack: post failed (${req.idemKey})`, result.error);
+            return undefined;
+        }
+        const ts = result.ts;
+        store.db.transaction(() => {
+            store.settleSlackPost(req.idemKey, { ok: true, ts });
+            if (req.pr !== undefined) {
+                if (threadTs === undefined)
+                    store.upsertSlackThread({ pr: req.pr, channel: cfg.slack.channel, root_ts: ts });
+                else
+                    store.touchSlackThread(req.pr);
+            }
+        })();
+        return result.ts;
+    }
+    /** Lifecycle gate: the cause's own switch, nothing more (see header). */
+    lifecycleEnabled(cause) {
+        if (!this.enabled)
+            return false;
+        if (causePolicy(this.deps.cfg, cause).enabled)
+            return true;
+        this.log(`slack: lifecycle cause '${cause}' is disabled`);
+        return false;
+    }
+    /** Unprompted-cause gate: switch + cooldown + fold + rolling-hour ceiling.
+     * Mutates on decide, exactly like AlertPolicy — so a caller can never fire
+     * without paying the cooldown. */
+    announcementAllowed(cause, pr, escalated) {
+        if (!this.enabled)
+            return undefined;
+        const prior = this.deps.store.slackCooldown(announcementKey(cause, pr));
+        const d = decideAnnouncement(this.deps.store, this.deps.cfg, { cause, pr, escalated }, this.now());
+        if (!d.allow) {
+            this.log(`slack: announcement '${d.key}' suppressed — ${d.reason ?? d.block}`);
+            return undefined;
+        }
+        return { key: d.key, prior };
+    }
+    /** The policy-timezone day token — the shared opsDay (src/eod.ts) over
+     * this section's zone; no private day-naming copy. */
+    policyDay() {
+        return opsDay(this.deps.cfg.slack.policy.timezone, this.now());
+    }
+    /** Coarse buckets keep a repeatable cause idempotent across a restart while
+     * still letting it speak again later (the cooldown decides when). */
+    hourBucket() {
+        return this.now().toISOString().slice(0, 13);
+    }
+    /** The ledger key of a PR's not-picked-up notice this hour. */
+    notPickedUpKey(pr) {
+        return `pr.not_picked_up:${pr}:${this.hourBucket()}`;
+    }
+    minuteBucket() {
+        return this.now().toISOString().slice(0, 16);
+    }
+    // ---- thread lifecycle --------------------------------------------------
+    /**
+     * A round was created. Says the pickup message the first time — as the
+     * thread ROOT when nothing has spoken for this PR yet, or as the first REPLY
+     * when a `pr.not_picked_up` notice already opened the thread (the rule is
+     * root-on-first-event, NOT pickup-only-if-first) — and the 🔄 line in-thread
+     * on every genuinely later round.
+     *
+     * The branch is on the PICKUP POST, never on thread existence: a thread the
+     * 🐢 notice opened must still receive the pickup template, and a 🔄 line
+     * ("you pushed new commits") about a PR that was merely queued would be a
+     * lie. `round_no` is MAX+1 per PR (StateStore.startRound), so round 1 can
+     * never be a re-round — that guard keeps a replayed first round silent
+     * instead of inventing a 🔄 line for it.
+     */
+    async roundStarted(a) {
+        if (!this.enabled)
+            return;
+        const { store, cfg } = this.deps;
+        // A previously FAILED pickup (ok = 0) is retried by `post`, so it does not
+        // count as said.
+        // With pickup switched off nothing is owed before a later round, so the
+        // re-round line keeps its own switch.
+        const pickupSaid = store.slackPost(`pickup:${a.pr}`)?.ok === 1;
+        if (!pickupSaid && this.lifecycleEnabled(LIFECYCLE_CAUSES.pickup)) {
+            await this.post({
+                idemKey: `pickup:${a.pr}`,
+                kind: "pickup",
+                pr: a.pr,
+                text: pickupMessage(cfg, {
+                    pr: a.pr,
+                    title: a.title,
+                    author: a.author,
+                    round_no: a.round_no,
+                    round_type: a.round_type,
+                    changed_files: a.changed_files,
+                    additions: a.additions,
+                    deletions: a.deletions,
+                    lenses: a.lenses,
+                }),
+            });
+        }
+        else if (a.round_no > 1 && this.lifecycleEnabled(LIFECYCLE_CAUSES.reRound)) {
+            const reason = a.reason ?? (a.round_type === "staleness" ? { kind: "base_moved" } : { kind: "pushed" });
+            await this.post({
+                idemKey: `reround:${a.pr}:${a.round_no}`,
+                kind: "announce",
+                pr: a.pr,
+                text: reRoundMessage({ round_no: a.round_no, reason, head_sha: a.head_sha }),
+            });
+        }
+    }
+    /** The verdict, in-thread. Never `reply_broadcast`, whatever
+     * `broadcast_verdicts` says — the seam has no broadcast parameter at all. */
+    async verdict(a) {
+        if (!this.lifecycleEnabled(LIFECYCLE_CAUSES.verdict))
+            return;
+        const author = a.author ?? this.deps.store.getPr(a.pr)?.author ?? "";
+        await this.post({
+            idemKey: `verdict:${a.pr}:${a.round_no}`,
+            kind: "verdict",
+            pr: a.pr,
+            text: verdictMessage(this.deps.cfg, {
+                pr: a.pr,
+                author,
+                round_no: a.round_no,
+                verdict: a.verdict,
+                ...(a.approval_withheld ? { approval_withheld: true } : {}),
+                summary: a.summary,
+                duration_min: Math.max(0, Math.round((a.duration_s ?? 0) / 60)),
+            }),
+        });
+    }
+    /** A round outlived by a newer one. Wording per AGENTS.md invariant 2. */
+    async superseded(a) {
+        if (!this.lifecycleEnabled(LIFECYCLE_CAUSES.superseded))
+            return;
+        await this.post({
+            idemKey: `superseded:${a.pr}:${a.old_round_no}`,
+            kind: "announce",
+            pr: a.pr,
+            text: supersededMessage(a),
+        });
+    }
+    // ---- unprompted causes -------------------------------------------------
+    /** Overdue / malformed: both return the PR to its standing-verdict state
+     * (never a park) and neither implies an approval. A
+     * round-less anomaly has nothing to say and stays silent. */
+    async anomaly(a) {
+        if (a.round_no === null || !this.enabled)
+            return;
+        const { cause, text } = this.anomalyMessage({ ...a, round_no: a.round_no });
+        if (!causePolicy(this.deps.cfg, cause).enabled)
+            return;
+        // An incident already announced is announced again when it reopens (or
+        // fails again before it recovered): its one message — which a recovery
+        // corrected to "recovered" — is edited to say work is owed again, where a
+        // second post would be refused by the ledger and leave it claiming
+        // recovery.
+        const prior = a.incident_id ? this.deps.store.slackPost(a.incident_id) : undefined;
+        if (a.incident_id && prior?.ok === 1 && prior.ts) {
+            const failure = this.deps.store.openReviewFailure(a.pr);
+            if (failure?.incident_id !== a.incident_id)
+                return;
+            const owed = {
+                incident_id: a.incident_id,
+                generation: randomUUID(),
+                pr: a.pr,
+                episode: String(failure.reopen_epoch ?? 0),
+                cause,
+                text,
+                ts: prior.ts,
+                channel: this.deps.cfg.slack.channel,
+            };
+            this.deps.store.queueSlackReopening(owed);
+            await this.retryReopening(owed);
+            return;
+        }
+        // An anomaly is a genuine escalation: it may spend the day's one bypass.
+        const admitted = this.announcementAllowed(cause, a.pr, true);
+        if (!admitted)
+            return;
+        await this.post({
+            idemKey: a.incident_id ?? `${cause}:${a.pr}:${a.round_no}`,
+            kind: "announce",
+            hourCapped: admitted,
+            pr: a.pr,
+            text,
+        });
+    }
+    async retryReopening(owed) {
+        const { store, cfg } = this.deps;
+        const current = () => {
+            const failure = store.openReviewFailure(owed.pr);
+            return (failure?.incident_id === owed.incident_id &&
+                String(failure.reopen_epoch ?? 0) === owed.episode);
+        };
+        if (!current()) {
+            store.clearSlackReopening(owed.incident_id, owed.generation);
+            return;
+        }
+        if (!this.enabled || !causePolicy(cfg, owed.cause).enabled)
+            return;
+        const edited = await this.editIncident(owed.incident_id, owed.ts, owed.text, "reopening", () => current() && causePolicy(cfg, owed.cause).enabled, owed.channel);
+        if (edited)
+            store.clearSlackReopening(owed.incident_id, owed.generation);
+    }
+    /** An anomaly's policy cause and its message, chosen once by its kind. */
+    anomalyMessage(a) {
+        const { cfg } = this.deps;
+        switch (a.kind) {
+            case "overdue":
+                return {
+                    cause: "round.overdue",
+                    text: causeMessage(cfg, {
+                        cause: "round.overdue",
+                        pr: a.pr,
+                        round_no: a.round_no,
+                        deadline_min: a.deadline_min,
+                    }),
+                };
+            case "failed_loud":
+                return {
+                    cause: "review.failed_loud",
+                    text: `⛔ #${a.pr} round ${a.round_no} exhausted automatic recovery — review work is still owed. Use u on the board to recover.`,
+                };
+            case "malformed":
+                return {
+                    cause: "round.malformed_verdict",
+                    text: causeMessage(cfg, {
+                        cause: "round.malformed_verdict",
+                        pr: a.pr,
+                        round_no: a.round_no,
+                    }),
+                };
+        }
+    }
+    /** Edit an incident's message; true when Slack accepted the edit. A refusal
+     * is logged with the incident and the message, and owed to the caller. */
+    async editIncident(incidentId, ts, text, what, isCurrent, channel) {
+        const prior = this.incidentEdits.get(incidentId) ?? Promise.resolve();
+        const run = prior.then(async () => {
+            // State can change while an earlier Slack request is in flight. An
+            // obsolete correction must not overwrite the current episode's message.
+            if (!this.enabled || !isCurrent())
+                return false;
+            const { cfg, slack } = this.deps;
+            try {
+                const res = await slack.updateMessage({ channel: channel ?? cfg.slack.channel, ts, text });
+                if (!res.ok)
+                    this.log(`slack: failure ${what} update failed (${incidentId}, ts ${ts})`, res.error);
+                return res.ok;
+            }
+            catch (err) {
+                this.log(`slack: failure ${what} update threw (${incidentId}, ts ${ts})`, err);
+                return false;
+            }
+        });
+        const tail = run.catch(() => undefined);
+        this.incidentEdits.set(incidentId, tail);
+        void tail.then(() => {
+            if (this.incidentEdits.get(incidentId) === tail)
+                this.incidentEdits.delete(incidentId);
+        });
+        return run;
+    }
+    /** A PR still waiting for a slot. This may be the FIRST event on the PR, in
+     * which case it opens the thread (root-on-first-event). */
+    async notPickedUp(item) {
+        const admitted = this.announcementAllowed("pr.not_picked_up", item.pr);
+        if (!admitted)
+            return;
+        await this.post({
+            idemKey: this.notPickedUpKey(item.pr),
+            kind: "announce",
+            hourCapped: admitted,
+            pr: item.pr,
+            text: causeMessage(this.deps.cfg, { cause: "pr.not_picked_up", ...item }),
+        });
+    }
+    /** Run the scan and announce every hit. Returns what it announced. */
+    async announceNotPickedUp() {
+        if (!this.enabled)
+            return [];
+        const announced = [];
+        for (const item of scanNotPickedUp(this.deps.store, this.deps.cfg, this.now())) {
+            const key = this.notPickedUpKey(item.pr);
+            const before = this.deps.store.slackPost(key);
+            await this.notPickedUp(item);
+            const after = this.deps.store.slackPost(key);
+            if (!before && after?.ok === 1)
+                announced.push(item.pr);
+        }
+        return announced;
+    }
+    /** The Slack answer budget ran out — said once a day, never per refusal. */
+    async capReached(cap) {
+        const admitted = this.announcementAllowed("slack.cap_reached");
+        if (!admitted)
+            return;
+        await this.post({
+            idemKey: `slack.cap_reached:${this.policyDay()}`,
+            kind: "announce",
+            hourCapped: admitted,
+            text: causeMessage(this.deps.cfg, { cause: "slack.cap_reached", cap }),
+        });
+    }
+    // ---- daemon lifecycle --------------------------------------------------
+    /** Previous run's liveness instant from state/status.json (see AnnouncerDeps
+     * .statusPath for why that file is the source). */
+    lastHeartbeatIso() {
+        const raw = this.readStatusRaw();
+        if (raw === undefined)
+            return undefined;
+        try {
+            const snap = JSON.parse(raw);
+            const value = snapshotHeartbeat(snap);
+            return value !== null && Number.isFinite(Date.parse(value)) ? value : undefined;
+        }
+        catch (err) {
+            this.log("slack: status.json unreadable for downtime measurement", err);
+            return undefined;
+        }
+    }
+    readStatusRaw() {
+        if (this.deps.readStatus)
+            return this.deps.readStatus();
+        const path = this.deps.statusPath;
+        if (!path || !existsSync(path))
+            return undefined;
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch (err) {
+            this.log("slack: status.json read failed", err);
+            return undefined;
+        }
+    }
+    /**
+     * Announce a restart ONLY when the measured gap exceeds
+     * `downtime_notice_min`. Shorter gaps are deploy noise: the socket overlaps,
+     * nothing is lost, and a line about it would be pure spam. The gap that IS
+     * reported is the measured one — never rounded into a reassuring shape.
+     */
+    async daemonUp() {
+        if (!this.enabled)
+            return false;
+        const last = this.lastHeartbeatIso();
+        if (last === undefined)
+            return false; // first ever boot: nothing was missed
+        const gapMs = this.now().getTime() - Date.parse(last);
+        if (gapMs <= this.deps.cfg.slack.policy.downtime_notice_min * 60_000)
+            return false;
+        const admitted = this.announcementAllowed("daemon.up");
+        if (!admitted)
+            return false;
+        const ts = await this.post({
+            idemKey: `daemon.up:${this.minuteBucket()}`,
+            kind: "announce",
+            hourCapped: admitted,
+            text: causeMessage(this.deps.cfg, {
+                cause: "daemon.up",
+                version: this.deps.version ?? "unknown",
+                gap: formatGap(gapMs),
+                last_heartbeat: isoSeconds(last),
+            }),
+        });
+        return ts !== undefined;
+    }
+    /** Best-effort goodbye, bounded so shutdown can never wait on Slack. */
+    async daemonStopping(reason) {
+        const admitted = this.announcementAllowed("daemon.stopping");
+        if (!admitted)
+            return;
+        const budget = this.deps.stopTimeoutMs ?? 3000;
+        const post = this.post({
+            idemKey: `daemon.stopping:${this.minuteBucket()}`,
+            kind: "announce",
+            hourCapped: admitted,
+            text: causeMessage(this.deps.cfg, { cause: "daemon.stopping", reason }),
+        });
+        let timer;
+        try {
+            await Promise.race([
+                post,
+                new Promise((resolve) => {
+                    timer = this.setTimeoutFn(() => resolve(), budget);
+                    unref(timer);
+                }),
+            ]);
+        }
+        catch (err) {
+            this.log("slack: stopping announcement failed", err);
+        }
+        finally {
+            if (timer !== undefined)
+                this.clearTimeoutFn(timer);
+        }
+    }
+    // ---- pinned heartbeat --------------------------------------------------
+    /**
+     * One message, posted once and edited forever: its staleness is what shows
+     * the current gap. The ts lives in the post ledger under a fixed idem key, so
+     * a restart updates the same message instead of littering the channel.
+     */
+    async heartbeat() {
+        if (!this.enabled)
+            return undefined;
+        const { store, cfg, slack } = this.deps;
+        for (const owed of store.owedSlackReopenings())
+            await this.retryReopening(owed);
+        const refreshedAt = this.now();
+        // The banner names only a JUST-recovered incident; the incident message's
+        // correction is owed until Slack accepts it, whatever the tick cadence —
+        // so it reads a day-long window and retries a refusal.
+        const recoveries = store.recentReviewRecoveries(new Date(refreshedAt.getTime() - RECOVERY_BANNER_WINDOW_MS).toISOString());
+        const owed = store.recentReviewRecoveries(new Date(refreshedAt.getTime() - RECOVERY_CORRECTION_WINDOW_MS).toISOString());
+        const recoveryKey = (r) => `${r.incident_id}@${r.recovered_at ?? ""}`;
+        const stillOwed = new Set(owed.map(recoveryKey));
+        for (const key of this.correctedIncidents)
+            if (!stillOwed.has(key))
+                this.correctedIncidents.delete(key);
+        for (const recovered of owed) {
+            if (this.correctedIncidents.has(recoveryKey(recovered)))
+                continue;
+            const incidentPost = store.slackPost(recovered.incident_id);
+            if (!incidentPost?.ts)
+                continue;
+            const edited = await this.editIncident(recovered.incident_id, incidentPost.ts, `✓ #${recovered.pr} review failure recovered via ${recovered.recovery ?? "operator action"} — ${recovered.incident_id}`, "recovery", () => store
+                .recentReviewRecoveries(recovered.recovered_at)
+                .some((current) => current.incident_id === recovered.incident_id &&
+                current.recovered_at === recovered.recovered_at));
+            if (edited)
+                this.correctedIncidents.add(recoveryKey(recovered));
+        }
+        const recovered = recoveries[0];
+        const text = heartbeatMessage({
+            refreshed_at: refreshedAt.toISOString(),
+            running: store.runningRounds().length,
+            max_concurrent: cfg.daemon.max_concurrent_rounds,
+            queued: store.allPrs().filter((p) => p.state === "queued" && !p.paused).length,
+            failed_loud: store.openReviewFailures().length,
+            ...(recovered ? { recovered_incident: recovered.incident_id } : {}),
+            dry_run: cfg.dry_run,
+        });
+        let existing = store.slackPost(HEARTBEAT_IDEM_KEY);
+        // A claim with no message and no outcome whose request is not awaiting
+        // Slack in this process is a previous run's (killed mid-post) or this
+        // run's own ambiguous attempt: settle it failed so the post is retried — a heartbeat lost for good is worse than one duplicate line.
+        if (existing && existing.ok === 1 && !existing.ts && !this.inFlight.has(HEARTBEAT_IDEM_KEY)) {
+            store.settleSlackPost(HEARTBEAT_IDEM_KEY, {
+                ok: false,
+                error: "claimed by an earlier run that never settled it",
+            });
+            existing = store.slackPost(HEARTBEAT_IDEM_KEY);
+        }
+        if (existing?.ts) {
+            let missing = false;
+            try {
+                const res = await slack.updateMessage({
+                    channel: cfg.slack.channel,
+                    ts: existing.ts,
+                    text,
+                });
+                if (!res.ok) {
+                    this.log("slack: heartbeat update failed", res.error);
+                    missing = res.error === "message_not_found" && !res.ambiguous;
+                }
+            }
+            catch (err) {
+                this.log("slack: heartbeat update threw", err);
+            }
+            if (!missing)
+                return existing.ts;
+            if (!store.forgetMissingSlackMessage(HEARTBEAT_IDEM_KEY, existing.ts))
+                return store.slackPost(HEARTBEAT_IDEM_KEY)?.ts ?? undefined;
+        }
+        const ts = await this.post({ idemKey: HEARTBEAT_IDEM_KEY, kind: "announce", text });
+        if (ts) {
+            // Pinning may be refused (`no_permission`) — the operator can pin by hand.
+            try {
+                const pin = await slack.pinsAdd({ channel: cfg.slack.channel, ts });
+                if (!pin.ok)
+                    this.log(`slack: heartbeat pin skipped (${pin.error ?? "unknown"})`);
+            }
+            catch (err) {
+                this.log("slack: heartbeat pin threw", err);
+            }
+        }
+        return ts;
+    }
+    /** Drive the heartbeat on `heartbeat_interval_min`. Idempotent. */
+    startHeartbeat() {
+        if (!this.enabled || this.heartbeatTimer)
+            return;
+        const tick = () => void this.heartbeat().catch((err) => this.log("slack: heartbeat tick failed", err));
+        tick();
+        const every = Math.max(1, this.deps.cfg.slack.policy.heartbeat_interval_min) * 60_000;
+        this.heartbeatTimer = this.setIntervalFn(tick, every);
+        unref(this.heartbeatTimer);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer)
+            this.clearIntervalFn(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+    }
+    // ---- ops signal (NOT a channel post) -----------------------------------
+    /**
+     * `hello.num_connections > 1` outside a deploy window means a second consumer
+     * is eating our events. Ops signals are off for the channel, so this
+     * surfaces as an anomaly callback (the overseer-inject path) only, and only
+     * when the count changes — a duplicate consumer is one event, not a stream.
+     */
+    noteConnections(numConnections, opts = {}) {
+        const previous = this.lastConnections;
+        this.lastConnections = numConnections;
+        if (opts.deployWindow)
+            return;
+        if (numConnections <= 1 || numConnections === previous)
+            return;
+        const message = `Slack socket reports ${numConnections} connections outside a deploy window — ` +
+            `a second consumer is receiving (and acking) our events. Check for a stray daemon or a duplicate container.`;
+        this.log(`slack: ${message}`);
+        void Promise.resolve(this.deps.onAnomalySignal?.(message)).catch((err) => this.log("slack: anomaly signal failed", err));
+    }
+}
+/** Convenience for wiring: an announcer that is only built when
+ * Slack is on, so callers can pass `undefined` straight through. */
+export function makeAnnouncer(deps) {
+    return deps.cfg.slack.enabled ? new SlackAnnouncer(deps) : undefined;
+}
+//# sourceMappingURL=announce.js.map