instar 1.3.499 → 1.3.501

package/dist/monitoring/ReapNoticeDrain.js

@@ -0,0 +1,231 @@
+/**
+ * ReapNoticeDrain — the ALWAYS-ON delivery loop for reap notices
+ * (reap-notify spec R1.3, tier0 supervision — deterministic delivery of
+ * pre-authored template content, declared per P7).
+ *
+ * Why it exists: the durable layer's existing drain (DeliveryFailureSentinel)
+ * is default-OFF fleet-wide, so "DFS will retry it" is false on a default
+ * agent — the round-2 foundation audit's central finding. The R1 guarantee
+ * ("every non-silent reap produces a durable, retried, recorded notice")
+ * therefore ships its OWN small always-on drain, independent of the DFS flag.
+ *
+ * Contract:
+ *  - Claims ONLY rows inside the `reap-notify:` PK range (index-compatible
+ *    range predicate; DFS claims the complement). The claim itself is a CAS
+ *    UPDATE — two drains can never double-claim a row.
+ *  - 30s tick; idle cost is one indexed claim query (~zero on an empty store).
+ *  - Per-pass send cap (15) keeps a 500-topic storm under Telegram's
+ *    per-group rate: 500 durable rows drain over ~17 minutes (R1.5's global
+ *    release throttle); the remainder is picked up next tick.
+ *  - Delivery is the DIRECT adapter send (`sendToTopic`) — NOT the
+ *    /telegram/reply relay — so the relay's tone gate, whoami check, and
+ *    duplicate-suppression are structurally off this path (notices carry
+ *    per-notice distinct content anyway).
+ *  - Bounded retries: store-backed exponential backoff on the existing
+ *    attempts/next_attempt_at columns; at `maxAttempts` (8) the row is
+ *    escalated terminally into ONE aggregated attention item (updated in
+ *    place — never per-row items; P17).
+ *  - Outcome records (R1.3 pairs): the terminal record (`sent` /
+ *    `send-failed-escalated`) is appended HERE, event-driven from the drain
+ *    that owns the terminal transition.
+ *  - Loop brakes (P19, declared): backoff + maxAttempts + per-pass cap +
+ *    terminal escalation; plus a bounded terminal-row cleanup so the
+ *    always-on lane cannot grow the store unboundedly while DFS's retention
+ *    pass is off.
+ */
+import { parseReapNotifyDeliveryId } from '../messaging/reap-notice-delivery-id.js';
+export const DEFAULT_REAP_NOTICE_DRAIN_OPTIONS = {
+    tickIntervalMs: 30_000,
+    perPassSendCap: 15,
+    maxAttempts: 8,
+    leaseDurationMs: 120_000,
+    backoffBaseMs: 30_000,
+    backoffMaxMs: 30 * 60_000,
+    terminalRetentionMs: 24 * 3600_000,
+};
+const ESCALATION_ATTENTION_ID = 'reap-notice-drain:escalations';
+export class ReapNoticeDrain {
+    deps;
+    opts;
+    now;
+    timer = null;
+    ticking = false;
+    /** Rolling escalation aggregate since boot (feeds the ONE attention item). */
+    escalations = [];
+    lastCleanupAt = 0;
+    constructor(deps, opts) {
+        this.deps = deps;
+        this.opts = { ...DEFAULT_REAP_NOTICE_DRAIN_OPTIONS, ...(opts ?? {}) };
+        this.now = deps.now ?? (() => Date.now());
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.tick().catch(() => {
+                /* @silent-fallback-ok — last-resort belt: tick() already guards and
+                   records every per-row failure durably (attempts/backoff/escalation);
+                   a throw here would only kill the interval timer. */
+            });
+        }, this.opts.tickIntervalMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** One drain pass. Public so tests (and a manual flush) can drive it. */
+    async tick() {
+        const counters = { sent: 0, retried: 0, escalated: 0 };
+        if (this.ticking)
+            return counters; // re-entrancy guard
+        this.ticking = true;
+        try {
+            const nowMs = this.now();
+            const nowIso = new Date(nowMs).toISOString();
+            let candidates = [];
+            try {
+                candidates = this.deps.store
+                    .selectClaimableReapNotices(nowIso, this.opts.perPassSendCap * 2)
+                    .filter((row) => row.state === 'queued' || this.isLeaseStale(row, nowMs));
+            }
+            catch (err) {
+                console.warn('[reap-notice-drain] select raised:', err);
+                return counters;
+            }
+            let processed = 0;
+            for (const row of candidates) {
+                if (processed >= this.opts.perPassSendCap)
+                    break;
+                const leaseUntil = new Date(nowMs + this.opts.leaseDurationMs).toISOString();
+                const claimedBy = `${this.deps.bootId}:${process.pid}:${leaseUntil}`;
+                let won = false;
+                try {
+                    won = this.deps.store.claimCas(row.delivery_id, claimedBy, {
+                        state: row.state,
+                        claimed_by: row.claimed_by,
+                    });
+                }
+                catch {
+                    won = false;
+                }
+                if (!won)
+                    continue; // lost the race (or the row moved) — next tick re-selects
+                processed++;
+                const noticeId = parseReapNotifyDeliveryId(row.delivery_id) ?? row.delivery_id;
+                const text = Buffer.isBuffer(row.text) ? row.text.toString('utf-8') : String(row.text ?? '');
+                try {
+                    await this.deps.sendToTopic(row.topic_id, text);
+                    this.safeTransition(row.delivery_id, 'delivered-recovered', { claimed_by: null });
+                    this.safeRecord({ noticeId, topicId: row.topic_id, outcome: 'sent' });
+                    counters.sent++;
+                }
+                catch (err) {
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    const attempts = (row.attempts ?? 1) + 1;
+                    if (attempts >= this.opts.maxAttempts) {
+                        this.safeTransition(row.delivery_id, 'escalated', {
+                            attempts,
+                            claimed_by: null,
+                            error_body: errMsg.slice(0, 512),
+                        });
+                        this.safeRecord({
+                            noticeId,
+                            topicId: row.topic_id,
+                            outcome: 'send-failed-escalated',
+                            detail: `after ${attempts} attempts: ${errMsg.slice(0, 200)}`,
+                        });
+                        counters.escalated++;
+                        await this.escalate(noticeId, row.topic_id, nowIso);
+                    }
+                    else {
+                        const backoff = Math.min(this.opts.backoffBaseMs * 2 ** Math.max(0, attempts - 1), this.opts.backoffMaxMs);
+                        this.safeTransition(row.delivery_id, 'queued', {
+                            attempts,
+                            claimed_by: null,
+                            next_attempt_at: new Date(nowMs + backoff).toISOString(),
+                            error_body: errMsg.slice(0, 512),
+                        });
+                        counters.retried++;
+                    }
+                }
+            }
+            // Bounded terminal-row cleanup (≤ once/hour).
+            if (nowMs - this.lastCleanupAt > 3600_000) {
+                this.lastCleanupAt = nowMs;
+                try {
+                    this.deps.store.purgeTerminalReapNotices(new Date(nowMs - this.opts.terminalRetentionMs).toISOString());
+                }
+                catch {
+                    /* cleanup is best-effort */
+                }
+            }
+            return counters;
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+    /** Lease format mirrors DFS: `<bootId>:<pid>:<leaseUntilIso>`. */
+    isLeaseStale(row, nowMs) {
+        if (!row.claimed_by)
+            return true;
+        const parts = row.claimed_by.split(':');
+        if (parts.length < 3)
+            return true;
+        const bootId = parts[0];
+        const leaseUntilIso = parts.slice(2).join(':');
+        if (bootId !== this.deps.bootId)
+            return true; // prior boot — reclaimable
+        const lease = Date.parse(leaseUntilIso);
+        if (Number.isNaN(lease))
+            return true;
+        return lease < nowMs;
+    }
+    safeTransition(deliveryId, state, fields) {
+        try {
+            this.deps.store.transition(deliveryId, state, fields);
+        }
+        catch (err) {
+            console.warn(`[reap-notice-drain] transition(${deliveryId}, ${state}) raised:`, err);
+        }
+    }
+    safeRecord(e) {
+        try {
+            this.deps.recordNotify(e);
+        }
+        catch {
+            /* the audit sink never endangers delivery */
+        }
+    }
+    /** ONE rolling deduped attention item, updated in place (P17). */
+    async escalate(noticeId, topicId, atIso) {
+        this.escalations.push({ noticeId, topicId, at: atIso });
+        if (this.escalations.length > 50)
+            this.escalations.shift();
+        if (!this.deps.emitAttention)
+            return;
+        const topics = [...new Set(this.escalations.map((e) => e.topicId))];
+        try {
+            await this.deps.emitAttention({
+                id: ESCALATION_ATTENTION_ID,
+                title: `Reap notices could not be delivered (${this.escalations.length} since startup)`,
+                summary: `Delivery of session-shutdown notices failed after all retries for topic(s) ${topics.join(', ')}.`,
+                description: `I tried to tell the affected conversation(s) that sessions were shut down, but the messages ` +
+                    `could not be delivered after repeated attempts. The shutdowns themselves are all recorded — ` +
+                    `ask me "what happened to my sessions?" and I can reconstruct it. Most recent failure: notice ` +
+                    `${noticeId} for topic ${topicId} at ${atIso}.`,
+                category: 'delivery',
+                priority: 'medium',
+                sourceContext: 'reap-notice-drain',
+            });
+        }
+        catch (err) {
+            console.warn('[reap-notice-drain] attention emit failed:', err);
+        }
+    }
+}
+//# sourceMappingURL=ReapNoticeDrain.js.map

package/dist/monitoring/ReapNoticeDrain.js.map

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

package/dist/monitoring/ReapNotifier.d.ts

@@ -1,50 +1,103 @@
 /**
  * ReapNotifier — the single coalescing listener for `sessionReaped`
- * (UNIFIED-SESSION-LIFECYCLE §P3).
+ * (UNIFIED-SESSION-LIFECYCLE §P3; v2 per reap-notify spec R1.1–R1.5).
  *
  * `SessionManager.terminateSession` emits `sessionReaped` exactly once per kill
- * at the one chokepoint. This listener turns a TERMINAL reap of a user-facing
- * session into a "your session was shut down" notice so a session never silently
- * vanishes (the 2026-05-27 incident). It stays SILENT for:
+ * at the one chokepoint. This listener turns TERMINAL reaps of user-facing
+ * sessions into "your session was shut down" notices so a session never
+ * silently vanishes (the 2026-05-27 incident). It stays SILENT for:
  *   - `recovery-bounce` reaps (a kill-to-respawn is a bounce, not a disappearance),
  *   - `origin:'operator'` reaps (the user clicked kill — telling them is noise).
  *
- * Coalescing (SE-7): terminal reaps within a short rolling window collapse onto a
- * single shared timer. On flush:
- *   - exactly ONE reap in the window → a per-session notice routed to its bound
- *     topic (or the lifeline topic if unbound),
- *   - MORE than one → ONE consolidated lifeline message stating the TOTAL count,
- *     so a mass-reap burst that overflows the bounded buffer is never
- *     under-reported (the reap-log P4 has the complete record regardless).
+ * v2 (perTopic: true, the shipped default):
+ *   - Per-topic coalescing (R1.1): every topic that lost a session gets ONE
+ *     notice in THAT topic; the lifeline gets unbound sessions plus — when >1
+ *     topic is affected — a one-line cross-topic index. Never creates topics.
+ *   - Affected-set tracking is SEPARATE from the bounded detail buffer, so in
+ *     a storm larger than the buffer every affected topic still gets at least
+ *     a correct count (count-only notice when its detail was dropped).
+ *   - Durable delivery (R1.3): notices become PendingRelayStore rows keyed
+ *     `reap-notify:<noticeId>` with the release hold riding `next_attempt_at`;
+ *     the always-on ReapNoticeDrain delivers them. Outcome records land in
+ *     the reap-log as append-only pairs. Enqueue failure degrades LOUDLY to
+ *     one direct send attempt, recorded `enqueue-failed`.
+ *   - Release tiers (decision 1 + R1.5): a mid-work reap with a QUEUED resume
+ *     releases IMMEDIATE outside quiet hours (quiet-hours end inside them —
+ *     never wakes the user; a queued resume means the system is already
+ *     handling it); everything else releases on the SUMMARY window. At most
+ *     `maxImmediatePerFlush` immediate releases per flush.
+ *   - Plain English (R1.2): reason slugs map to human sentences (unknown slug
+ *     ⇒ generic sentence with the slug parenthesized); no curl/API pointers
+ *     in any user-facing body.
+ *
+ * Legacy (perTopic: false — the rollback lever): byte-compatible with the
+ * pre-v2 behavior (single buffer; burst ⇒ ONE consolidated lifeline message).
  *
  * Sanitization: session names follow user-controlled topic renames, so the
- * dynamic fields (name, reason) are wrapped as inline-code spans — the downstream
- * Telegram formatter renders code spans as literal, HTML-escaped text, never
- * markup. The notifier never emits raw markup around user-controlled values.
+ * dynamic fields (name, reason) are wrapped as inline-code spans — the
+ * downstream Telegram formatter renders code spans as literal, HTML-escaped
+ * text, never markup. The notifier never emits raw markup around
+ * user-controlled values.
  */
 import type { Session } from '../core/types.js';
+import type { ReapNotifyOutcome } from './ReapLog.js';
 export interface ReapEvent {
     session: Pick<Session, 'name' | 'tmuxSession'>;
     reason: string;
     disposition?: 'terminal' | 'recovery-bounce';
     origin?: 'operator' | 'autonomous';
+    /** Mid-work stamp from the kill chokepoint (reap-notify spec R2.1). */
+    midWork?: boolean;
+    /** Clamped work-evidence names behind midWork. */
+    workEvidence?: string[];
 }
 export interface ReapNotifierDeps {
     /** Bound messaging topic for a session, or null if unbound. */
     resolveTopic: (tmuxSession: string) => number | null;
     /** The always-on system/lifeline topic, or null if none is configured. */
     lifelineTopic: () => number | null;
-    /** Deliver a (GFM) notice to a topic. Wiring decides the transport/tier. */
+    /** Legacy delivery (perTopic:false and drainEnabled:false modes). */
     send: (topicId: number, text: string) => void | Promise<void>;
+    /** Durable store enqueue (v2). Returns false on PK-dedupe no-op. */
+    enqueueNotice?: (input: {
+        delivery_id: string;
+        topic_id: number;
+        text: string;
+        next_attempt_at: string;
+    }) => boolean;
+    /** Append a notify outcome record to the reap-log (R1.3 pairs). */
+    recordNotify?: (e: {
+        noticeId: string;
+        topicId: number | null;
+        outcome: ReapNotifyOutcome;
+        detail?: string;
+    }) => void;
+    /** Epoch ms when the current quiet-hours window ends; null = not in quiet hours. */
+    quietHoursEndAt?: (nowMs: number) => number | null;
+    /** Epoch ms of the next SUMMARY-window release (≤30 min out — R1.5). */
+    summaryReleaseAt?: (nowMs: number) => number;
+    /** True when a resume-queue entry is QUEUED for this session AND the queue is
+     *  LIVE (not dry-run) — gates the "resume queued" line (R1.2). */
+    resumeQueuedFor?: (tmuxSession: string) => boolean;
+    /** Loud degradation surface for enqueue failures (aggregated upstream). */
+    reportDegradation?: (reason: string, impact: string) => void;
     now?: () => number;
 }
 export interface ReapNotifierOptions {
     enabled: boolean;
     coalesceWindowMs: number;
-    /** Max reaps retained for the consolidated-message detail list (count is exact regardless). */
+    /** Max reaps retained for detail lists (counts stay exact regardless). */
     maxBuffer: number;
+    /** v2 per-topic grouping (R1.1). false = legacy single-buffer behavior. */
+    perTopic: boolean;
+    /** Max notices released IMMEDIATE in one flush (R1.5). */
+    maxImmediatePerFlush: number;
+    /** Durable delivery via store + drain (R1.3). false = legacy direct send
+     *  (grouping unaffected; the durability guarantee lapses — stated rollback). */
+    drainEnabled: boolean;
 }
 export declare const DEFAULT_REAP_NOTIFIER_OPTIONS: ReapNotifierOptions;
+export declare function plainEnglishReason(slug: string): string;
 export declare class ReapNotifier {
     private readonly deps;
     private readonly opts;
@@ -52,15 +105,33 @@ export declare class ReapNotifier {
     private timer;
     private buffer;
     private windowCount;
+    /** v2 affected-set (R1.1) — tracked separately from the detail buffer. */
+    private affected;
+    private affectedOverflow;
+    private unbound;
+    private noticeSeq;
     constructor(deps: ReapNotifierDeps, opts?: Partial<ReapNotifierOptions>);
     /** The `sessionReaped` event handler. */
     onReaped(event: ReapEvent): void;
+    private trackAffected;
+    /** Remove a buffer-evicted event from its topic's detail list (count stays). */
+    private dropDetail;
+    private safeResolveTopic;
+    private safeResumeQueued;
     /**
      * Emit the coalesced notice(s) for the closed window and reset. Public so the
      * lifecycle (and tests) can drive it deterministically.
      */
     flush(): Promise<void>;
-    private formatSingle;
-    private formatBurst;
+    /** Legacy (pre-v2) flush — byte-compatible single-buffer behavior. */
+    private flushLegacy;
+    private nextNoticeId;
+    private releaseAt;
+    private deliver;
+    private formatTopicNotice;
+    private formatUnboundNotice;
+    private formatCrossTopicIndex;
+    private formatSingleLegacy;
+    private formatBurstLegacy;
 }
 //# sourceMappingURL=ReapNotifier.d.ts.map

package/dist/monitoring/ReapNotifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReapNotifier.d.ts","sourceRoot":"","sources":["../../src/monitoring/ReapNotifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,UAAU,GAAG,iBAAiB,CAAC;IAC7C,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,YAAY,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACrD,0EAA0E;IAC1E,aAAa,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACnC,4EAA4E;IAC5E,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,6BAA6B,EAAE,mBAI3C,CAAC;AAQF,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsB;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,WAAW,CAAK;gBAEZ,IAAI,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC;IAMvE,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAiBhC;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB5B,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,WAAW;CAWpB"}
+{"version":3,"file":"ReapNotifier.d.ts","sourceRoot":"","sources":["../../src/monitoring/ReapNotifier.ts"],"names":[],"mappings":"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"}