@cluesmith/codev 3.3.2 → 3.3.4

package/dist/agent-farm/servers/message-write.js

@@ -1,17 +1,113 @@
 /**
- * Paced message writing for PTY sessions (Bugfix #584).
+ * Paced message writing for PTY sessions (Bugfix #584, Issue #1567).
  *
  * Extracted to a shared module to avoid circular imports between
  * tower-routes.ts and tower-cron.ts.
  */
 import { trySubmitToSession, watchBypasses } from './session-submit.js';
-// Messages longer than this threshold are written line-by-line with delays
-// to prevent the receiving terminal from classifying the input as a paste
-// and swallowing the final Enter.
-const PACED_WRITE_LINE_THRESHOLD = 4;
-const INTER_LINE_DELAY_MS = 10;
-const PACED_ENTER_DELAY_MS = 80;
 const SIMPLE_ENTER_DELAY_MS = 50;
+/**
+ * Issue #1567 — why long frames are no longer handed to the PTY in one write.
+ *
+ * The kernel splits a large master-side write at the slave's input-queue high-water mark
+ * (TTYHOG − 2 = 1022 bytes on macOS). The receiving TUI reads the first ~1 KB as one chunk,
+ * its paste heuristic classifies that chunk as a paste and DISCARDS it, then types the
+ * remainder and the Enter normally — so the agent saw a mid-sentence tail-only fragment
+ * while every `write()` reported success. Measured on claude 2.1.263 (harness in
+ * `scripts/bugfix-1567-head-loss-harness.mts`, evidence in `codev/evidence/1567-head-loss/`):
+ * a 1,172-byte 3-line frame lost its head 14/20 times on an IDLE composer; a 1,000-byte frame
+ * never did. Two independent changes each measured 0 losses, and both are applied:
+ *
+ *   1. **No single write exceeds {@link PASTE_CHUNK_BYTES}** — comfortably under the queue
+ *      limit, so the kernel never splits a read and the reader drains between writes.
+ *   2. **Long frames travel as ONE explicit bracketed paste** (`ESC[200~` … `ESC[201~`), so the
+ *      TUI's paste heuristic never runs on chunk boundaries and newlines inside the body can
+ *      never be read as Enter. The Enter is a separate write OUTSIDE the bracket, after a
+ *      settle. Inside the bracket newlines travel as `\r`, which is what a terminal emulator
+ *      emits on paste (xterm.js) and what claude's composer expects there — the same convention
+ *      `apps/vscode/src/review-queue/queue.ts` already uses to type a review into a builder.
+ *
+ * This replaces the #584-era per-line pacing for frames of {@link BRACKET_MIN_LINES} lines or
+ * more, which was tuned against an older TUI's heuristic. Short frames keep the pre-existing
+ * single write + delayed Enter, byte for byte, so `--raw` slash commands and short sends are
+ * untouched.
+ */
+export const PASTE_CHUNK_BYTES = 512;
+/** Gap between consecutive chunk writes; the reader drains a chunk in well under this. */
+export const PASTE_CHUNK_GAP_MS = 5;
+/** Settle between the paste's closing marker and the Enter that submits it (measured: 0/29 losses). */
+export const PASTE_ENTER_DELAY_MS = 80;
+/**
+ * Frames LONGER than this many bytes, or of {@link BRACKET_MIN_LINES} lines or more, are
+ * bracketed and chunked. Well under the 1,022-byte queue limit where the loss starts: the
+ * field's smallest confirmed truncations were ~500-byte bodies, and a bracketed short paste
+ * costs nothing on the measured harnesses.
+ */
+export const BRACKET_MIN_BYTES = 256;
+/** The #584 threshold, kept: any frame of this many lines or more is never typed line by line. */
+export const BRACKET_MIN_LINES = 4;
+/** Gap between line pieces on the non-bracketed (opt-out) strategy — the #584 pacing. */
+const INTER_LINE_DELAY_MS = 10;
+export const PASTE_BEGIN = '\x1b[200~';
+export const PASTE_END = '\x1b[201~';
+export const BRACKETED_PASTE = { bracketedPaste: true };
+export const PLAIN_CHUNKED = { bracketedPaste: false };
+/**
+ * The write strategy for a gate profile's `app`. agy is the one modeled harness whose paste
+ * handling was not measurable (unauthenticated), so it keeps the per-line shape; anything
+ * else is bracketed. Unknown apps never reach the write edge (the gate holds `no-profile`).
+ */
+export function writeStrategyForApp(app) {
+    return app === 'agy' ? PLAIN_CHUNKED : BRACKETED_PASTE;
+}
+/** Does this frame take the bracketed/chunked path rather than the single short write? */
+export function isLongFrame(message) {
+    return message.split('\n').length >= BRACKET_MIN_LINES || Buffer.byteLength(message, 'utf8') > BRACKET_MIN_BYTES;
+}
+/**
+ * Split `text` into pieces of at most `max` bytes, never inside a UTF-8 sequence (a split
+ * continuation byte would reach the TUI as two invalid characters).
+ */
+export function chunkForPty(text, max = PASTE_CHUNK_BYTES) {
+    const buf = Buffer.from(text, 'utf8');
+    const out = [];
+    for (let at = 0; at < buf.length;) {
+        let end = Math.min(buf.length, at + max);
+        while (end < buf.length && end > at && (buf[end] & 0xc0) === 0x80)
+            end--;
+        out.push(buf.subarray(at, end).toString('utf8'));
+        at = end;
+    }
+    return out;
+}
+/**
+ * The pieces of a long frame, in write order, for a strategy. Bracketed: the body (newlines
+ * as `\r`) chunked, with the opening marker on the first piece and the closing marker on the
+ * last — the markers are never split across writes, so no chunk boundary can land inside an
+ * escape sequence, and every piece INCLUDING its marker stays within {@link PASTE_CHUNK_BYTES}.
+ * Plain: one piece per line (`\n` kept, as #584 wrote it), with any line over
+ * the chunk size split further.
+ */
+export function framePieces(message, strategy) {
+    if (strategy.bracketedPaste) {
+        // A literal paste marker inside the body (a pasted terminal log, say) would end or restart
+        // the paste mid-frame and let the remainder be typed as keys; strip both so the bracket
+        // we add is the only one the TUI sees.
+        const body = message.replace(/\r?\n/g, '\r').split(PASTE_BEGIN).join('').split(PASTE_END).join('');
+        // Chunk with room for the markers so NO write — first or last piece included — exceeds
+        // PASTE_CHUNK_BYTES on the wire.
+        const pieces = chunkForPty(body, PASTE_CHUNK_BYTES - PASTE_BEGIN.length - PASTE_END.length);
+        // A body that was NOTHING but markers is empty after stripping; still emit one (empty) paste
+        // so the frame is a well-formed no-op rather than the literal text "undefined".
+        if (pieces.length === 0)
+            pieces.push('');
+        pieces[0] = PASTE_BEGIN + pieces[0];
+        pieces[pieces.length - 1] += PASTE_END;
+        return pieces;
+    }
+    const lines = message.split('\n');
+    return lines.flatMap((line, i) => chunkForPty(i < lines.length - 1 ? line + '\n' : line));
+}
 /** ESC keystroke — ends the agent's current turn (Spec 1273). */
 export const ESC = '\x1b';
 /**
@@ -43,21 +139,22 @@ export function writeEscapeToSession(session, noEnter) {
     return ESCAPE_ENTER_DELAY_MS;
 }
 /**
- * Write a message to a PTY session, pacing multi-line output to prevent
- * the terminal from treating it as a paste (Bugfix #584).
+ * Write a message to a PTY session (Bugfix #584, Issue #1567).
+ *
+ * Short frames (under {@link BRACKET_MIN_LINES} lines AND at most {@link BRACKET_MIN_BYTES}
+ * bytes): a single write, then Enter after 50 ms — unchanged since #584.
  *
- * Short messages (≤3 lines): single write + delayed Enter.
- * Long messages (>3 lines): line-by-line writes with 10ms gaps, then Enter
- * after all lines are delivered.
+ * Long frames: {@link framePieces} written {@link PASTE_CHUNK_GAP_MS} apart (bracketed by
+ * default; see {@link WriteStrategy}), then Enter as its own write
+ * {@link PASTE_ENTER_DELAY_MS} after the last piece. The Enter is always outside the paste
+ * bracket, so a TUI that collapses the paste into a placard still submits it.
  *
  * @param delayOffset  ms offset for all scheduled writes (used to serialize
  *                     multiple messages to the same session without interleaving)
  * @returns            ms timestamp (from call time) when all writes complete
  */
-export function writeMessageToSession(session, message, noEnter, delayOffset = 0) {
-    const lines = message.split('\n');
-    if (lines.length < PACED_WRITE_LINE_THRESHOLD) {
-        // Short messages: single write (existing behavior, works fine)
+export function writeMessageToSession(session, message, noEnter, delayOffset = 0, strategy = BRACKETED_PASTE) {
+    if (!isLongFrame(message)) {
         if (delayOffset === 0) {
             session.write(message);
         }
@@ -70,26 +167,23 @@ export function writeMessageToSession(session, message, noEnter, delayOffset = 0
         }
         return enterTime;
     }
-    // Multi-line: pace output line-by-line to avoid paste detection.
-    // Writing all lines in a single write() causes the terminal to treat it
-    // as a paste, swallowing the final Enter.
-    for (let i = 0; i < lines.length; i++) {
-        const text = i < lines.length - 1 ? lines[i] + '\n' : lines[i];
-        const lineDelay = delayOffset + i * INTER_LINE_DELAY_MS;
-        if (lineDelay === 0) {
-            session.write(text);
+    const pieces = framePieces(message, strategy);
+    const gap = strategy.bracketedPaste ? PASTE_CHUNK_GAP_MS : INTER_LINE_DELAY_MS;
+    for (let i = 0; i < pieces.length; i++) {
+        const at = delayOffset + i * gap;
+        if (at === 0) {
+            session.write(pieces[i]);
         }
         else {
-            setTimeout(() => session.write(text), lineDelay);
+            setTimeout(() => session.write(pieces[i]), at);
         }
     }
-    const lastLineTime = delayOffset + (lines.length - 1) * INTER_LINE_DELAY_MS;
-    if (!noEnter) {
-        const enterTime = lastLineTime + PACED_ENTER_DELAY_MS;
-        setTimeout(() => session.write('\r'), enterTime);
-        return enterTime;
-    }
-    return lastLineTime;
+    const lastPieceTime = delayOffset + (pieces.length - 1) * gap;
+    if (noEnter)
+        return lastPieceTime;
+    const enterTime = lastPieceTime + PASTE_ENTER_DELAY_MS;
+    setTimeout(() => session.write('\r'), enterTime);
+    return enterTime;
 }
 /**
  * Paced write of a message (text + trailing Enter unless `noEnter`) performed as ONE
@@ -117,7 +211,7 @@ export function writeMessageToSession(session, message, noEnter, delayOffset = 0
  * `submitToSession` schedules its own equal-offset sleep, so the Enter still executes
  * first — which is what makes the per-agent serializer's completion-chaining real.
  */
-export async function submitMessagePaced(session, message, noEnter, precheck, clock) {
+export async function submitMessagePaced(session, message, noEnter, precheck, clock, strategy = BRACKETED_PASTE) {
     // Fail LOUD on a missing id rather than keying the lock on `undefined`. Sessions reach
     // this through structurally-typed ports, so a double without an id compiles fine and
     // would silently collapse every per-terminal lock into one global lock — serialization
@@ -137,9 +231,17 @@ export async function submitMessagePaced(session, message, noEnter, precheck, cl
     try {
         let delivered = true;
         let abort = null;
+        // Sampled inside the lock, immediately before the first byte (below), so the comparison
+        // spans exactly the paced write and not the lock wait that preceded it.
+        let inputSeqBefore = session.inputSeq;
+        // The origin is HARD-CODED here rather than forwarded through a parameter (Issue #1473).
+        // A one-arg function is assignable to a two-arg function type, so a wrapper that forgot to
+        // pass the origin along would compile cleanly — and its failure mode is the delivery
+        // counting its own bytes as human input, i.e. "mail never delivers". Removing the parameter
+        // removes the opportunity.
         const tracked = {
             write: (data) => {
-                const ok = session.write(data);
+                const ok = session.write(data, 'delivery');
                 if (!ok)
                     delivered = false;
                 return ok;
@@ -149,7 +251,8 @@ export async function submitMessagePaced(session, message, noEnter, precheck, cl
             abort = precheck();
             if (abort !== null)
                 return 0; // refused in-lock: not one byte goes out
-            return writeMessageToSession(tracked, message, noEnter);
+            inputSeqBefore = session.inputSeq;
+            return writeMessageToSession(tracked, message, noEnter, 0, strategy);
         }, clock);
         if (!ran)
             return { status: 'contended' };
@@ -162,6 +265,12 @@ export async function submitMessagePaced(session, message, noEnter, precheck, cl
             return { status: 'dropped' };
         if (bypasses.raced())
             return { status: 'preempted' };
+        // The prechecks close everything up to the first byte; between the first byte and the
+        // trailing Enter there is still an 80 ms-to-seconds window, and by then the bytes are out.
+        // So this is a REPORTING signal — flag it and let the caller tell the operator, rather than
+        // hold and re-write a message that may well have landed (#1584). Omitted when false.
+        if (session.inputSeq !== inputSeqBefore)
+            return { status: 'written', racedByInput: true };
         return { status: 'written' };
     }
     finally {

package/dist/agent-farm/servers/message-write.js.map

@@ -1 +1 @@
-{"version":3,"file":"message-write.js","sourceRoot":"","sources":["../../../src/agent-farm/servers/message-write.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"message-write.js","sourceRoot":"","sources":["../../../src/agent-farm/servers/message-write.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/servers/overview.d.ts

@@ -7,6 +7,7 @@
  * mode when the `gh` CLI is unavailable.
  */
 import type { ForgeIssueListItem } from '../../lib/github.js';
+import { type RateLimitProbe } from '../../lib/forge-rate-limit.js';
 import type { PlanPhase, OverviewBuilder, OverviewBacklogItem, OverviewData } from '@cluesmith/codev-types';
 interface ParsedStatus {
     id: string;
@@ -161,15 +162,28 @@ export declare function readFeedbackMode(workspaceRoot: string): 'forward' | 'qu
  * Derive backlog from open GitHub issues cross-referenced with specs and builders.
  */
 export declare function deriveBacklog(issues: ForgeIssueListItem[], workspaceRoot: string, activeBuilderIssues: Set<string>, prLinkedIssues: Set<string>): OverviewBacklogItem[];
+export interface OverviewCacheOptions {
+    /** Clock, injectable for tests. */
+    now?: () => number;
+    /** Reset probe run once per fresh suspension (Tower passes the gh probe). */
+    probe?: RateLimitProbe;
+}
 export declare class OverviewCache {
     private prCache;
     private issueCache;
     private closedCache;
     private mergedPRCache;
     private currentUserCache;
+    /** Single-flight per `<workspace>:<concept>` (#1645). */
+    private inflight;
+    /** Escalating failure window per `<workspace>:<budget>`. */
+    private failureWindows;
+    /** Epoch of the last invalidate(); open-list entries fetched before it are stale once debounced. */
+    private invalidatedAt;
+    private readonly limiter;
+    private readonly now;
+    constructor(options?: OverviewCacheOptions);
     private resolvedEnrichment;
-    private readonly TTL;
-    private readonly USER_TTL;
     /**
      * Build the overview response. Aggregates builder state, PRs, and backlog.
      *
@@ -180,20 +194,22 @@ export declare class OverviewCache {
      */
     getOverview(workspaceRoot: string, activeBuilderRoleIds?: Set<string>): Promise<OverviewData>;
     /**
-     * Invalidate all cached data.
+     * Mark the open lists (PRs, issues) stale. Porch, cleanup and the VS Code
+     * review queue call this after every mutation, so it is not a human signal
+     * (#1645): it never clears a suspension or a cached failure, never touches
+     * the search or identity caches, and a list is refetched for it at most once
+     * per `INVALIDATE_DEBOUNCE_MS` per workspace.
      */
     invalidate(): void;
-    private fetchPRsCached;
-    private fetchIssuesCached;
     /**
-     * Resolve the current user's forge login via the `user-identity` concept.
-     * Long TTL — identity is stable for the lifetime of a Tower session.
-     * Only successful resolutions are cached, so a transient failure (gh
-     * logged out, offline) self-heals on the next overview poll.
+     * Serve `concept` for `cwd` from cache, or dispatch exactly one fetch.
+     * `listCache` entries additionally honour invalidate() (debounced).
      */
-    private fetchCurrentUserCached;
-    private fetchRecentlyClosedCached;
-    private fetchMergedPRsCached;
+    private cachedFetch;
+    /** Run the concept once and record the outcome. Never rejects. */
+    private dispatch;
+    /** Current failure window for a key; escalates once per elapsed window, not per failure. */
+    private failureWindow;
 }
 export {};
 //# sourceMappingURL=overview.d.ts.map

package/dist/agent-farm/servers/overview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/overview.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/overview.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/servers/overview.js

@@ -9,7 +9,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { UNCATEGORIZED_AREA } from '@cluesmith/codev-sdk/constants';
-import { fetchPRList, fetchIssueList, fetchRecentlyClosed, fetchRecentMergedPRs, fetchCurrentUser, parseLinkedIssue, parseLabelDefaults, parseArea, } from '../../lib/github.js';
+import { fetchForOverview, overviewBackend, parseLinkedIssue, parseLabelDefaults, parseArea, } from '../../lib/github.js';
+import { ForgeRateLimiter, budgetKeyFor } from '../../lib/forge-rate-limit.js';
 import { loadProtocol } from '../../commands/porch/protocol.js';
 import { ResolvedEnrichmentCache } from './resolved-enrichment-cache.js';
 import Database from 'better-sqlite3';
@@ -761,23 +762,41 @@ export function deriveBacklog(issues, workspaceRoot, activeBuilderIssues, prLink
         return item;
     });
 }
-// =============================================================================
-// OverviewCache
-// =============================================================================
+/** Open lists: what porch/VS Code invalidation refreshes. */
+const LIST_TTL_MS = 180_000;
+/** The two 24 h searches: invalidation never touches these. */
+const SEARCH_TTL_MS = 600_000;
+/** GitHub identity is session-stable. */
+const USER_TTL_MS = 3_600_000;
+/** A list refetches at most once per minute per workspace because of invalidation. */
+const INVALIDATE_DEBOUNCE_MS = 60_000;
+/** Failure window: 60 s, doubling per window (not per failed command) to 15 min. */
+const FAILURE_WINDOW_MIN_MS = 60_000;
+const FAILURE_WINDOW_MAX_MS = 15 * 60_000;
 export class OverviewCache {
     prCache = new Map();
     issueCache = new Map();
     closedCache = new Map();
     mergedPRCache = new Map();
     currentUserCache = new Map();
+    /** Single-flight per `<workspace>:<concept>` (#1645). */
+    inflight = new Map();
+    /** Escalating failure window per `<workspace>:<budget>`. */
+    failureWindows = new Map();
+    /** Epoch of the last invalidate(); open-list entries fetched before it are stale once debounced. */
+    invalidatedAt = 0;
+    limiter;
+    now;
+    constructor(options = {}) {
+        this.now = options.now ?? (() => Date.now());
+        this.limiter = new ForgeRateLimiter(options.probe);
+    }
     // Cache of issue-derived builder fields (today: `area`) keyed by worktreePath,
     // so they survive refreshes where the source issue is unreachable rather than
     // snapping back to their default while the builder is still listed (PIR #907).
     // Intentionally NOT cleared by invalidate(): surviving cache invalidation is
     // the whole point. See ResolvedEnrichmentCache.
     resolvedEnrichment = new ResolvedEnrichmentCache();
-    TTL = 30_000;
-    USER_TTL = 3_600_000; // 1h — GitHub identity is session-stable
     /**
      * Build the overview response. Aggregates builder state, PRs, and backlog.
      *
@@ -849,17 +868,29 @@ export class OverviewCache {
             .filter((id) => id !== null));
         // 2. Fetch PRs, issues, recently closed, merged PRs, and current user in
         //    parallel (each is independently cached)
-        const [prs, issues, closed, mergedPRs, currentUser] = await Promise.all([
-            this.fetchPRsCached(workspaceRoot),
-            this.fetchIssuesCached(workspaceRoot),
-            this.fetchRecentlyClosedCached(workspaceRoot),
-            this.fetchMergedPRsCached(workspaceRoot),
-            this.fetchCurrentUserCached(workspaceRoot),
+        const [prsOutcome, issuesOutcome, closedOutcome, mergedOutcome, userOutcome] = await Promise.all([
+            this.cachedFetch(this.prCache, workspaceRoot, 'pr-list', LIST_TTL_MS, true),
+            this.cachedFetch(this.issueCache, workspaceRoot, 'issue-list', LIST_TTL_MS, true),
+            this.cachedFetch(this.closedCache, workspaceRoot, 'recently-closed', SEARCH_TTL_MS, false),
+            this.cachedFetch(this.mergedPRCache, workspaceRoot, 'recently-merged', SEARCH_TTL_MS, false),
+            this.cachedFetch(this.currentUserCache, workspaceRoot, 'user-identity', USER_TTL_MS, false),
         ]);
+        const prs = prsOutcome.data;
+        const issues = issuesOutcome.data;
+        const closed = closedOutcome.data;
+        const mergedPRs = mergedOutcome.data;
+        const currentUser = userOutcome.data;
+        // Every forge-backed section counts, the two searches included (#1645).
+        const sections = [prsOutcome, issuesOutcome, closedOutcome, mergedOutcome];
+        const rateLimited = sections.find(o => o.rateLimitedUntil !== null);
+        const forgeStatus = rateLimited
+            ? 'rate-limited'
+            : sections.some(o => o.data === null) ? 'unavailable' : 'ok';
+        const forgeResetAt = rateLimited ? new Date(rateLimited.rateLimitedUntil).toISOString() : undefined;
         // 3. Process PRs
         let pendingPRs = [];
         if (prs === null) {
-            errors.prs = 'GitHub CLI unavailable — could not fetch PRs';
+            errors.prs = describeMissing(prsOutcome, 'PRs');
         }
         else {
             pendingPRs = prs.map(pr => ({
@@ -885,7 +916,7 @@ export class OverviewCache {
             ? new Map(issues.map(i => [String(i.number), parseArea(i.labels)]))
             : null;
         if (issues === null) {
-            errors.issues = 'GitHub CLI unavailable — could not fetch issues';
+            errors.issues = describeMissing(issuesOutcome, 'issues');
         }
         else {
             backlog = deriveBacklog(issues, workspaceRoot, activeBuilderIssues, prLinkedIssues);
@@ -978,7 +1009,10 @@ export class OverviewCache {
         // has no view of the live terminal sessions. `handleOverview` (tower-routes.ts)
         // injects the real architect list via `liveArchitects` before serialization,
         // mirroring how it enriches `lastDataAt`.
-        const result = { builders, pendingPRs, backlog, recentlyClosed, architects: [], heldCount, mailboxEscalated, queuedFeedback, feedbackMode };
+        const result = { builders, pendingPRs, backlog, recentlyClosed, architects: [], heldCount, mailboxEscalated, queuedFeedback, feedbackMode, forgeStatus };
+        if (forgeResetAt) {
+            result.forgeResetAt = forgeResetAt;
+        }
         if (currentUser) {
             result.currentUser = currentUser;
         }
@@ -988,87 +1022,104 @@ export class OverviewCache {
         return result;
     }
     /**
-     * Invalidate all cached data.
+     * Mark the open lists (PRs, issues) stale. Porch, cleanup and the VS Code
+     * review queue call this after every mutation, so it is not a human signal
+     * (#1645): it never clears a suspension or a cached failure, never touches
+     * the search or identity caches, and a list is refetched for it at most once
+     * per `INVALIDATE_DEBOUNCE_MS` per workspace.
      */
     invalidate() {
-        this.prCache.clear();
-        this.issueCache.clear();
-        this.closedCache.clear();
-        this.mergedPRCache.clear();
-        this.currentUserCache.clear();
+        this.invalidatedAt = this.now();
         // Note: resolvedEnrichment is deliberately NOT cleared here. It must survive
         // invalidation so a cleanup-triggered refresh (which calls invalidate()) can
         // still fall back to a builder's resolved area instead of UNCATEGORIZED
         // (PIR #907). It self-prunes in getOverview when a builder disappears.
     }
     // ===========================================================================
-    // Private cache helpers
+    // Private cache helpers (#1645)
     // ===========================================================================
-    async fetchPRsCached(cwd) {
-        const now = Date.now();
-        const cached = this.prCache.get(cwd);
-        if (cached && (now - cached.fetchedAt) < this.TTL) {
-            return cached.data;
-        }
-        const data = await fetchPRList(cwd);
-        if (data !== null) {
-            this.prCache.set(cwd, { data, fetchedAt: now });
-        }
-        return data;
-    }
-    async fetchIssuesCached(cwd) {
-        const now = Date.now();
-        const cached = this.issueCache.get(cwd);
-        if (cached && (now - cached.fetchedAt) < this.TTL) {
-            return cached.data;
-        }
-        const data = await fetchIssueList(cwd);
-        if (data !== null) {
-            this.issueCache.set(cwd, { data, fetchedAt: now });
-        }
-        return data;
-    }
     /**
-     * Resolve the current user's forge login via the `user-identity` concept.
-     * Long TTL — identity is stable for the lifetime of a Tower session.
-     * Only successful resolutions are cached, so a transient failure (gh
-     * logged out, offline) self-heals on the next overview poll.
+     * Serve `concept` for `cwd` from cache, or dispatch exactly one fetch.
+     * `listCache` entries additionally honour invalidate() (debounced).
      */
-    async fetchCurrentUserCached(cwd) {
-        const now = Date.now();
-        const cached = this.currentUserCache.get(cwd);
-        if (cached && (now - cached.fetchedAt) < this.USER_TTL) {
-            return cached.data;
-        }
-        const login = await fetchCurrentUser(cwd);
-        if (login !== null) {
-            this.currentUserCache.set(cwd, { data: login, fetchedAt: now });
+    cachedFetch(cache, cwd, concept, ttl, listCache) {
+        const now = this.now();
+        const backend = overviewBackend(concept, cwd);
+        const budget = backend === null ? null : budgetKeyFor(backend, concept);
+        const entry = cache.get(cwd);
+        const withinTtl = entry !== undefined && now < entry.expiresAt;
+        // Only a *positive* entry goes stale on invalidation: a refresh means "my
+        // data may be stale", never "the forge has recovered".
+        const invalidated = listCache && entry !== undefined && entry.data !== null
+            && entry.fetchedAt < this.invalidatedAt && now - entry.fetchedAt >= INVALIDATE_DEBOUNCE_MS;
+        const rateLimitedUntil = budget === null ? null : this.limiter.resetAt(budget, now);
+        if (withinTtl && !invalidated) {
+            return Promise.resolve({ data: entry.data, rateLimitedUntil, backend });
         }
-        return login;
-    }
-    async fetchRecentlyClosedCached(cwd) {
-        const now = Date.now();
-        const cached = this.closedCache.get(cwd);
-        if (cached && (now - cached.fetchedAt) < this.TTL) {
-            return cached.data;
+        if (rateLimitedUntil !== null) {
+            // Suspended: a list still inside its TTL is served stale; an expired one is empty.
+            return Promise.resolve({ data: withinTtl ? entry.data : null, rateLimitedUntil, backend });
         }
-        const data = await fetchRecentlyClosed(cwd);
-        if (data !== null) {
-            this.closedCache.set(cwd, { data, fetchedAt: now });
+        if (backend === null || budget === null) {
+            return Promise.resolve({ data: null, rateLimitedUntil: null, backend: null });
         }
-        return data;
+        const key = `${cwd}:${concept}`;
+        const existing = this.inflight.get(key);
+        if (existing)
+            return existing;
+        const flight = this.dispatch(cache, cwd, concept, ttl, backend, budget).finally(() => {
+            // Identity check: a settling flight must never unregister a newer one.
+            if (this.inflight.get(key) === flight)
+                this.inflight.delete(key);
+        });
+        this.inflight.set(key, flight);
+        return flight;
     }
-    async fetchMergedPRsCached(cwd) {
-        const now = Date.now();
-        const cached = this.mergedPRCache.get(cwd);
-        if (cached && (now - cached.fetchedAt) < this.TTL) {
-            return cached.data;
+    /** Run the concept once and record the outcome. Never rejects. */
+    async dispatch(cache, cwd, concept, ttl, backend, budget) {
+        const dispatchedAt = this.now();
+        let data = null;
+        let errorText = null;
+        try {
+            const result = await fetchForOverview(concept, cwd);
+            data = result.data;
+            if (result.error)
+                errorText = `${result.error.stderr}\n${result.error.message}`;
+            else if (data === null)
+                errorText = '';
         }
-        const data = await fetchRecentMergedPRs(cwd);
-        if (data !== null) {
-            this.mergedPRCache.set(cwd, { data, fetchedAt: now });
+        catch (err) {
+            errorText = err instanceof Error ? err.message : String(err);
         }
-        return data;
+        const now = this.now();
+        if (errorText !== null) {
+            const suspended = this.limiter.noteFailure(budget, backend, cwd, errorText, now);
+            cache.set(cwd, { data: null, fetchedAt: dispatchedAt, expiresAt: now + this.failureWindow(`${cwd}:${budget}`, now) });
+            return { data: null, rateLimitedUntil: suspended ? this.limiter.resetAt(budget, now) : null, backend };
+        }
+        this.limiter.noteSuccess(budget, dispatchedAt);
+        this.failureWindows.delete(`${cwd}:${budget}`);
+        cache.set(cwd, { data, fetchedAt: dispatchedAt, expiresAt: now + ttl });
+        return { data, rateLimitedUntil: null, backend };
+    }
+    /** Current failure window for a key; escalates once per elapsed window, not per failure. */
+    failureWindow(key, now) {
+        const w = this.failureWindows.get(key);
+        if (w && now < w.startedAt + w.ttl)
+            return w.ttl;
+        const level = w ? w.level + 1 : 0;
+        const ttl = Math.min(FAILURE_WINDOW_MIN_MS * 2 ** level, FAILURE_WINDOW_MAX_MS);
+        this.failureWindows.set(key, { level, startedAt: now, ttl });
+        return ttl;
+    }
+}
+/** Degraded-mode text naming the real reason and the real backend (never "GitHub" on GitLab). */
+function describeMissing(outcome, what) {
+    if (outcome.rateLimitedUntil !== null) {
+        return `${outcome.backend} rate limited until ${new Date(outcome.rateLimitedUntil).toISOString()} — ${what} unavailable`;
     }
+    if (outcome.backend === null)
+        return `forge concept disabled — ${what} unavailable`;
+    return `${outcome.backend} CLI unavailable — could not fetch ${what}`;
 }
 //# sourceMappingURL=overview.js.map