@oss-autopilot/core 3.13.4 → 3.14.1

package/dist/commands/vet-list.js

@@ -7,7 +7,8 @@ import { adaptScoutLinkedPR, buildCandidateLinkedPR, createAutopilotScout } from
 import { runParseList, pruneIssueList } from './parse-list.js';
 import { detectIssueList } from './startup.js';
 import { computeSuccessGrade, gradeFromCandidate } from '../core/issue-grading.js';
-import { getStateManager, classifyLinkedPR } from '../core/index.js';
+import { ValidationError } from '../core/errors.js';
+import { getStateManager, classifyLinkedPR, getOctokit, requireGitHubToken, parseGitHubUrl, verifyIssuesBatch, } from '../core/index.js';
 const UNKNOWN_GRADE = computeSuccessGrade({ avgResponseDays: null, mergeRate: null, daysSinceLastCommit: null });
 const KNOWN_SKIP_REASONS = new Set([
     'issue_closed',
@@ -93,13 +94,64 @@ export function classifyListStatus(vetResult, skipReason) {
     return 'still_available';
 }
 /**
- * Re-vet all available issues in a curated issue list.
- * Reads the list file, extracts available (non-done) issues,
- * and vets each in parallel with concurrency control.
- *
- * @param options - Vet-list options
- * @returns Consolidated vetting results with list status for each issue
+ * Map a deterministic verify-issue verdict onto the vet-list status taxonomy
+ * (#1494). This is the authoritative path: the GraphQL verdict knows the
+ * closing-vs-mention distinction (#1353) that scout's substring heuristic
+ * cannot, so `at_risk` (mention only) no longer collapses into `claimed`.
+ */
+export function listStatusFromVerdict(verdict) {
+    switch (verdict) {
+        case 'closed': {
+            return 'closed';
+        }
+        case 'own-open-pr': {
+            return 'own_open_pr';
+        }
+        case 'taken': {
+            return 'claimed';
+        }
+        case 'at-risk': {
+            return 'at_risk';
+        }
+        case 'available': {
+            return 'still_available';
+        }
+    }
+}
+/**
+ * Verdicts that conclusively rule an issue out as a new opportunity. For these
+ * we skip scout's grade/health vet entirely — there is nothing to grade — and
+ * build the result row straight from the verification.
  */
+const RULED_OUT_VERDICTS = new Set(['closed', 'taken', 'own-open-pr']);
+/** The per-row `verification` sub-object: the authoritative facts behind the
+ * status, projected from the full {@link IssueVerification}. */
+function toVerificationSummary(v) {
+    return {
+        verdict: v.verdict,
+        verdictReason: v.verdictReason,
+        state: v.state,
+        stateReason: v.stateReason,
+        assignees: v.assignees,
+        linkedPRs: v.linkedPRs,
+    };
+}
+/** Minimal VetOutput for a ruled-out issue (no scout vet was run). The
+ * verification carries the real reason; scout-derived fields are left empty. */
+function ruledOutVetOutput(v) {
+    return {
+        issue: { repo: `${v.owner}/${v.repo}`, number: v.number, title: v.title, url: v.url, labels: [] },
+        recommendation: 'skip',
+        reasonsToApprove: [],
+        reasonsToSkip: [v.verdictReason],
+        projectHealth: {},
+        vettingResult: {},
+        grade: UNKNOWN_GRADE,
+    };
+}
+function toMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 export async function runVetList(options = {}) {
     const concurrency = options.concurrency ?? 5;
     // 1. Find and parse the issue list
@@ -115,75 +167,146 @@ export async function runVetList(options = {}) {
     if (parsed.available.length === 0) {
         return {
             results: [],
-            summary: { total: 0, stillAvailable: 0, claimed: 0, closed: 0, hasPR: 0, hasStalledPR: 0, errors: 0 },
+            summary: {
+                total: 0,
+                stillAvailable: 0,
+                claimed: 0,
+                closed: 0,
+                hasPR: 0,
+                hasStalledPR: 0,
+                atRisk: 0,
+                ownOpenPr: 0,
+                errors: 0,
+            },
         };
     }
-    // 2. Vet each available issue in parallel with concurrency limit
-    const scout = await createAutopilotScout();
-    const results = [];
-    // Simple concurrency limiter
     const items = parsed.available;
-    let index = 0;
-    async function processNext() {
-        while (index < items.length) {
-            const item = items[index++];
+    // 2. Verify FIRST (#1494): one deterministic GraphQL check per entry, in a
+    //    bounded batch. The verdict is closing-vs-mention aware, so it carries
+    //    the authoritative status — and ruling issues out here means we skip
+    //    scout's search-driven vet (a net REDUCTION in /search/issues calls).
+    const octokit = getOctokit(requireGitHubToken());
+    const verifyTargets = [];
+    items.forEach((item, i) => {
+        const ghUrl = parseGitHubUrl(item.url);
+        if (ghUrl && ghUrl.type === 'issues') {
+            verifyTargets.push({ index: i, params: { owner: ghUrl.owner, repo: ghUrl.repo, number: ghUrl.number } });
+        }
+    });
+    const batch = await verifyIssuesBatch(octokit, verifyTargets.map((t) => t.params), { concurrency });
+    const verificationByIndex = new Map();
+    verifyTargets.forEach((t, k) => verificationByIndex.set(t.index, batch[k]));
+    // 3. Vet only the issues still in play; build each row.
+    const scout = await createAutopilotScout();
+    /** Run scout's grade/health vet for an issue (the search-driven path). */
+    async function runScoutVet(item) {
+        const candidate = await scout.vetIssue(item.url);
+        const grade = gradeFromCandidate({
+            repo: candidate.issue.repo,
+            projectHealth: candidate.projectHealth,
+            getRepoScore: (repo) => getStateManager().getRepoScore(repo),
+        });
+        const userLogin = getStateManager().getState().config.githubUsername;
+        const linkedPRClassification = classifyLinkedPR({
+            linkedPR: adaptScoutLinkedPR(candidate.vettingResult.linkedPR),
+            userLogin,
+        });
+        const linkedPR = buildCandidateLinkedPR(candidate.vettingResult.linkedPR);
+        const vetResult = {
+            issue: {
+                repo: candidate.issue.repo,
+                number: candidate.issue.number,
+                title: candidate.issue.title,
+                url: candidate.issue.url,
+                labels: candidate.issue.labels,
+            },
+            recommendation: candidate.recommendation,
+            reasonsToApprove: candidate.reasonsToApprove,
+            reasonsToSkip: candidate.reasonsToSkip,
+            projectHealth: candidate.projectHealth,
+            vettingResult: candidate.vettingResult,
+            antiLLMPolicy: candidate.antiLLMPolicy,
+            linkedPRClassification,
+            ...(linkedPR ? { linkedPR } : {}),
+            slmTriage: candidate.slmTriage ?? null,
+            grade,
+        };
+        return { vetResult, skipReason: extractSkipReason(candidate) };
+    }
+    function errorRow(item, error) {
+        const message = toMessage(error);
+        return {
+            issue: { repo: item.repo, number: item.number, title: item.title, url: item.url, labels: [] },
+            recommendation: 'skip',
+            reasonsToApprove: [],
+            reasonsToSkip: [`Error: ${message}`],
+            projectHealth: {},
+            vettingResult: {},
+            grade: UNKNOWN_GRADE,
+            listStatus: 'error',
+            errorMessage: message,
+        };
+    }
+    async function processItem(item, verification) {
+        // No authoritative verdict for this row: either verify errored, or the URL
+        // was never enrolled (parse-list also accepts PR URLs, which `verify-issue`
+        // can't classify). Either way `listStatus` falls back to scout's heuristic,
+        // so we ALWAYS tag the row with `verifyError` — the explicit signal that the
+        // status is not authoritative and must be re-verified before acting.
+        if (!verification || verification.verification === undefined) {
+            const verifyError = verification?.error;
+            // A ValidationError means the issue definitively doesn't exist (deleted,
+            // private, or the URL points at a PR). Don't re-grade it via scout — that
+            // could mislabel a dead issue as available. Report it as an error row.
+            if (verifyError instanceof ValidationError) {
+                return { ...errorRow(item, verifyError), verifyError: toMessage(verifyError) };
+            }
+            // Transient verify failure (rate limit, network, truncated timeline), or a
+            // non-issue URL that was never sent to verify. Fall back to scout's
+            // heuristic, tagged so the row is re-verified later.
+            const verifyErrorTag = {
+                verifyError: verifyError === undefined
+                    ? `not verified: ${item.url} is not a verifiable issue URL`
+                    : toMessage(verifyError),
+            };
             try {
-                const candidate = await scout.vetIssue(item.url);
-                const grade = gradeFromCandidate({
-                    repo: candidate.issue.repo,
-                    projectHealth: candidate.projectHealth,
-                    getRepoScore: (repo) => getStateManager().getRepoScore(repo),
-                });
-                const userLogin = getStateManager().getState().config.githubUsername;
-                const linkedPRClassification = classifyLinkedPR({
-                    linkedPR: adaptScoutLinkedPR(candidate.vettingResult.linkedPR),
-                    userLogin,
-                });
-                const linkedPR = buildCandidateLinkedPR(candidate.vettingResult.linkedPR);
-                const vetResult = {
-                    issue: {
-                        repo: candidate.issue.repo,
-                        number: candidate.issue.number,
-                        title: candidate.issue.title,
-                        url: candidate.issue.url,
-                        labels: candidate.issue.labels,
-                    },
-                    recommendation: candidate.recommendation,
-                    reasonsToApprove: candidate.reasonsToApprove,
-                    reasonsToSkip: candidate.reasonsToSkip,
-                    projectHealth: candidate.projectHealth,
-                    vettingResult: candidate.vettingResult,
-                    antiLLMPolicy: candidate.antiLLMPolicy,
-                    linkedPRClassification,
-                    ...(linkedPR ? { linkedPR } : {}),
-                    slmTriage: candidate.slmTriage ?? null,
-                    grade,
-                };
-                results.push({
-                    ...vetResult,
-                    listStatus: classifyListStatus(vetResult, extractSkipReason(candidate)),
-                });
+                const { vetResult, skipReason } = await runScoutVet(item);
+                return { ...vetResult, listStatus: classifyListStatus(vetResult, skipReason), ...verifyErrorTag };
             }
             catch (error) {
-                // Per-issue errors don't fail the batch
-                results.push({
-                    issue: { repo: item.repo, number: item.number, title: item.title, url: item.url, labels: [] },
-                    recommendation: 'skip',
-                    reasonsToApprove: [],
-                    reasonsToSkip: [`Error: ${error instanceof Error ? error.message : String(error)}`],
-                    projectHealth: {},
-                    vettingResult: {},
-                    grade: UNKNOWN_GRADE,
-                    listStatus: 'error',
-                    errorMessage: error instanceof Error ? error.message : String(error),
-                });
+                return { ...errorRow(item, error), ...verifyErrorTag };
             }
         }
+        const v = verification.verification;
+        const summary = toVerificationSummary(v);
+        const listStatus = listStatusFromVerdict(v.verdict);
+        // Conclusively ruled out — skip the scout vet entirely.
+        if (RULED_OUT_VERDICTS.has(v.verdict)) {
+            return { ...ruledOutVetOutput(v), listStatus, verification: summary };
+        }
+        // available / at-risk: still worth grading. The verdict stays authoritative
+        // for listStatus; scout only supplies grade/health/recommendation.
+        try {
+            const { vetResult } = await runScoutVet(item);
+            return { ...vetResult, listStatus, verification: summary };
+        }
+        catch (error) {
+            // Verify succeeded, so keep its verdict facts even though grading failed.
+            return { ...errorRow(item, error), verification: summary };
+        }
+    }
+    const results = new Array(items.length);
+    let index = 0;
+    async function processNext() {
+        while (index < items.length) {
+            const i = index++;
+            results[i] = await processItem(items[i], verificationByIndex.get(i));
+        }
     }
-    // Start `concurrency` workers
+    // Start `concurrency` workers (bounds the scout-vet fan-out).
     const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => processNext());
     await Promise.all(workers);
-    // 3. Compute summary
+    // 4. Compute summary
     const summary = {
         total: results.length,
         stillAvailable: results.filter((r) => r.listStatus === 'still_available').length,
@@ -191,6 +314,8 @@ export async function runVetList(options = {}) {
         closed: results.filter((r) => r.listStatus === 'closed').length,
         hasPR: results.filter((r) => r.listStatus === 'has_pr').length,
         hasStalledPR: results.filter((r) => r.listStatus === 'has_stalled_pr').length,
+        atRisk: results.filter((r) => r.listStatus === 'at_risk').length,
+        ownOpenPr: results.filter((r) => r.listStatus === 'own_open_pr').length,
         errors: results.filter((r) => r.listStatus === 'error').length,
     };
     // 4. Prune the file if requested — remove completed/skipped/low-score items
@@ -207,6 +332,10 @@ export async function runVetList(options = {}) {
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
             console.error(`Warning: Failed to prune ${issueListPath}: ${msg}`);
+            // Surface the failure in the envelope (#1448): without this, a failed
+            // prune returned a plain success with pruneResult simply absent — the
+            // same shape as "prune not requested".
+            pruneResult = { removedCount: 0, error: msg };
         }
     }
     return { results, summary, pruneResult };

package/dist/core/config-registry.js

@@ -104,6 +104,18 @@ export const CONFIG_KEY_REGISTRY = [
         settableVia: 'setup',
         valueHint: 'comma-separated list of owner/repo',
     },
+    {
+        key: 'avoidRepos',
+        description: 'Repos (owner/repo) to softly downrank in discovery results — milder than excludeRepos (whole-list replace).',
+        settableVia: 'setup',
+        valueHint: 'comma-separated list of owner/repo',
+    },
+    {
+        key: 'boostIssueTypes',
+        description: 'Issue label types to softly boost in discovery ranking (whole-list replace).',
+        settableVia: 'setup',
+        valueHint: 'comma-separated list (e.g. bug,good first issue)',
+    },
     // ── Exclusion list mutators (config-only) ────────────────────────────
     {
         key: 'add-language',
@@ -147,6 +159,30 @@ export const CONFIG_KEY_REGISTRY = [
         settableVia: 'config',
         valueHint: 'org name (no slash)',
     },
+    {
+        key: 'add-avoid-repo',
+        description: 'Append a repo (owner/repo) to the soft-downrank avoid list.',
+        settableVia: 'config',
+        valueHint: 'owner/repo',
+    },
+    {
+        key: 'remove-avoid-repo',
+        description: 'Remove a repo from the soft-downrank avoid list.',
+        settableVia: 'config',
+        valueHint: 'owner/repo (must already be present)',
+    },
+    {
+        key: 'add-boost-issue-type',
+        description: 'Append an issue label type to the discovery ranking boost list.',
+        settableVia: 'config',
+        valueHint: 'issue label (e.g. bug)',
+    },
+    {
+        key: 'remove-boost-issue-type',
+        description: 'Remove an issue label type from the discovery ranking boost list.',
+        settableVia: 'config',
+        valueHint: 'issue label (must already be present)',
+    },
     // ── Tooling ──────────────────────────────────────────────────────────
     {
         key: 'issueListPath',

package/dist/core/daily-logic.d.ts

@@ -14,6 +14,7 @@
  * re-exports them at the bottom so existing imports keep working without
  * a sweep.
  */
+import type { AttentionSummary } from './pr-attention.js';
 import type { FetchedPR, FetchedPRStatus, StalenessTier, ActionReason, AgentState, ShelvedPRRef, ComputedRepoSignals, RepoGroup, CommentedIssue, CapacityAssessment, ActionableIssue, ActionMenu, StarFilter } from './types.js';
 /**
  * Statuses indicating action needed from the contributor.
@@ -38,9 +39,13 @@ export declare const STALE_STATUSES: ReadonlySet<StalenessTier>;
  *
  * @param prs - The fetched PR list to apply overrides to
  * @param state - Current agent state containing status overrides
+ * @param failures - Optional collector (#1448): a message is pushed for each
+ *   PR whose override lookup threw (that PR keeps its un-overridden status).
+ *   Call sites surface these in warnings[]/partialFailures so the silently
+ *   wrong status is visible in the envelope, not just stderr.
  * @returns New PR array with overrides applied (original array is not mutated)
  */
-export declare function applyStatusOverrides(prs: FetchedPR[], state: Readonly<AgentState>): FetchedPR[];
+export declare function applyStatusOverrides(prs: FetchedPR[], state: Readonly<AgentState>, failures?: string[]): FetchedPR[];
 /**
  * Project a PR to a lightweight ShelvedPRRef for digest output.
  * Only the fields needed for display are retained, reducing JSON payload size.
@@ -61,6 +66,22 @@ export declare function toShelvedPRRef(pr: ShelvedPRRef): ShelvedPRRef;
  * @returns Star filter with minimum threshold and known counts, or undefined on first run
  */
 export declare function buildStarFilter(state: Readonly<AgentState>): StarFilter | undefined;
+/**
+ * Look up a just-merged/closed PR's `firstMaintainerResponseAt` from the
+ * previous run's persisted digest (#1461). At detection time the PR is no
+ * longer open, so it cannot be enriched without new API calls — but if it
+ * was open during a prior enriched run, the persisted digest's openPRs carry
+ * the timestamp. Best-effort: returns undefined when the PR never appeared
+ * in a persisted digest (e.g. opened and merged between runs, or the digest
+ * predates the field).
+ *
+ * Lives in core/daily-logic.ts so both ledger writers (daily Phase 3 and
+ * dashboard-data) share one lookup. Callers must read `state.lastDigest`
+ * BEFORE the current run overwrites it via setLastDigest.
+ */
+export declare function firstMaintainerResponseFromDigest(digest: {
+    openPRs: FetchedPR[];
+} | undefined, url: string): string | undefined;
 /**
  * Group PRs by repository (#80).
  * Ensures one agent per repo during parallel dispatch, preventing branch checkout conflicts.
@@ -108,7 +129,9 @@ export declare function collectActionableIssues(prs: FetchedPR[], lastDigestAt?:
  * @param actionableIssues - Issues requiring attention
  * @param capacity - Current capacity assessment
  * @param commentedIssues - Issues with comment activity
+ * @param attention - Attention bucket counts; non-zero stuck-CI / dormant-followup buckets add a follow_up item
+ * @param unextractedMergeCount - Recently merged PRs whose learnings have not been extracted yet (#1463); non-zero adds an extract_learnings item
  * @returns Action menu with context flags for orchestration
  */
-export declare function computeActionMenu(actionableIssues: ActionableIssue[], capacity: CapacityAssessment, commentedIssues?: CommentedIssue[]): ActionMenu;
+export declare function computeActionMenu(actionableIssues: ActionableIssue[], capacity: CapacityAssessment, commentedIssues?: CommentedIssue[], attention?: Pick<AttentionSummary, 'stuckCI' | 'dormantFollowup'>, unextractedMergeCount?: number): ActionMenu;
 export { formatActionHint, formatBriefSummary, formatSummary, printDigest } from '../commands/daily-render.js';

package/dist/core/daily-logic.js

@@ -52,9 +52,13 @@ const VALID_OVERRIDE_STATUSES = new Set(['needs_addressing', 'waiting_on_maintai
  *
  * @param prs - The fetched PR list to apply overrides to
  * @param state - Current agent state containing status overrides
+ * @param failures - Optional collector (#1448): a message is pushed for each
+ *   PR whose override lookup threw (that PR keeps its un-overridden status).
+ *   Call sites surface these in warnings[]/partialFailures so the silently
+ *   wrong status is visible in the envelope, not just stderr.
  * @returns New PR array with overrides applied (original array is not mutated)
  */
-export function applyStatusOverrides(prs, state) {
+export function applyStatusOverrides(prs, state, failures) {
     const overrides = state.config.statusOverrides;
     if (!overrides || Object.keys(overrides).length === 0)
         return prs;
@@ -82,7 +86,9 @@ export function applyStatusOverrides(prs, state) {
                 return { ...pr, status: override.status, waitReason: undefined, actionReason: 'needs_response' };
             }
             catch (err) {
-                warn('daily-logic', `Failed to apply status override for ${pr.url}: ${errorMessage(err)}`);
+                const message = `Failed to apply status override for ${pr.url}: ${errorMessage(err)}`;
+                warn('daily-logic', message);
+                failures?.push(message);
                 return pr;
             }
         });
@@ -152,6 +158,22 @@ export function buildStarFilter(state) {
         return undefined;
     return { minStars, knownStarCounts };
 }
+/**
+ * Look up a just-merged/closed PR's `firstMaintainerResponseAt` from the
+ * previous run's persisted digest (#1461). At detection time the PR is no
+ * longer open, so it cannot be enriched without new API calls — but if it
+ * was open during a prior enriched run, the persisted digest's openPRs carry
+ * the timestamp. Best-effort: returns undefined when the PR never appeared
+ * in a persisted digest (e.g. opened and merged between runs, or the digest
+ * predates the field).
+ *
+ * Lives in core/daily-logic.ts so both ledger writers (daily Phase 3 and
+ * dashboard-data) share one lookup. Callers must read `state.lastDigest`
+ * BEFORE the current run overwrites it via setLastDigest.
+ */
+export function firstMaintainerResponseFromDigest(digest, url) {
+    return digest?.openPRs.find((pr) => pr.url === url)?.firstMaintainerResponseAt;
+}
 /**
  * Group PRs by repository (#80).
  * Ensures one agent per repo during parallel dispatch, preventing branch checkout conflicts.
@@ -328,9 +350,11 @@ export function collectActionableIssues(prs, lastDigestAt) {
  * @param actionableIssues - Issues requiring attention
  * @param capacity - Current capacity assessment
  * @param commentedIssues - Issues with comment activity
+ * @param attention - Attention bucket counts; non-zero stuck-CI / dormant-followup buckets add a follow_up item
+ * @param unextractedMergeCount - Recently merged PRs whose learnings have not been extracted yet (#1463); non-zero adds an extract_learnings item
  * @returns Action menu with context flags for orchestration
  */
-export function computeActionMenu(actionableIssues, capacity, commentedIssues = []) {
+export function computeActionMenu(actionableIssues, capacity, commentedIssues = [], attention, unextractedMergeCount) {
     const issueResponses = commentedIssues.filter((i) => i.status === 'new_response');
     const items = [];
     const hasActionableIssues = actionableIssues.length > 0;
@@ -355,6 +379,37 @@ export function computeActionMenu(actionableIssues, capacity, commentedIssues =
             description: 'Maintainers responded to your comments on issues',
         });
     }
+    // Follow-up nudges (#1462) — the stuck_ci / dormant_followup buckets from
+    // summarizeAttentionBuckets get a menu path to workflows/dormant-pr-follow-up.md
+    // instead of only a headline count. Emitted only when a bucket is non-zero,
+    // so menus without stuck/dormant PRs are unchanged.
+    const stuckCI = attention?.stuckCI ?? 0;
+    const dormantFollowup = attention?.dormantFollowup ?? 0;
+    if (stuckCI > 0 || dormantFollowup > 0) {
+        const parts = [];
+        if (stuckCI > 0)
+            parts.push(`${stuckCI} stuck-CI`);
+        if (dormantFollowup > 0)
+            parts.push(`${dormantFollowup} dormant`);
+        const total = stuckCI + dormantFollowup;
+        items.push({
+            key: 'follow_up',
+            label: `Follow up on ${parts.join(' and ')} PR${total === 1 ? '' : 's'}`,
+            description: 'Waiting PRs that may need a nudge (pending CI or no review activity)',
+        });
+    }
+    // Extract-learnings nudge (#1463) — recently merged PRs whose ledger
+    // entries carry no learningsExtractedAt stamp get a menu path to
+    // workflows/extract-learnings.md. The nudge persists across runs for the
+    // recently-merged window until the extraction runs, then self-clears.
+    const unextracted = unextractedMergeCount ?? 0;
+    if (unextracted > 0) {
+        items.push({
+            key: 'extract_learnings',
+            label: `Extract learnings from ${unextracted} recently merged PR${unextracted === 1 ? '' : 's'}`,
+            description: 'Distill maintainer review feedback into per-repo contribution guidelines',
+        });
+    }
     // The orchestration layer (commands/oss.md Action Menu section) may insert issue-list
     // options before the search item when a curated list is available.
     const searchItem = {

package/dist/core/gist-health.d.ts

@@ -0,0 +1,81 @@
+/**
+ * One health source and one warning renderer for gist persistence (#1444).
+ *
+ * "Are we degraded?" used to be answered by three independent predicates
+ * (`config.persistence === 'gist' && !isGistMode()`, the
+ * `GistPersistenceStatus` union, `isGistMode() && isGistDegraded()`), each
+ * re-rendering its own warning prose. `StateManager.getGistHealth()` is now
+ * the single predicate for live-manager surfaces (daily warnings, dashboard
+ * probes), and {@link renderGistWarning} is the single prose renderer for
+ * every surface (CLI envelope, MCP injection, bootstrapGistBestEffort,
+ * daily warnings).
+ */
+/**
+ * Degradation causes a live StateManager can attest to from its own fields
+ * (see `StateManager.getGistHealth()`):
+ *
+ * - `configured-but-local`: config says `persistence: 'gist'` but this
+ *   process's manager has no gist store — init never ran here, or fell back
+ *   to a local-only manager. Mutations save locally and will not sync.
+ * - `bootstrap-degraded`: the manager IS gist-backed, but the bootstrap fell
+ *   back to the local cache and the store is disarmed (#1443) — reads may be
+ *   stale and pushes fail.
+ */
+export type GistHealthDegradedCause = 'configured-but-local' | 'bootstrap-degraded';
+/**
+ * Causes {@link renderGistWarning} can name. Superset of
+ * {@link GistHealthDegradedCause}: the process-level bootstrap outcomes are
+ * observed by config-peek paths (`ensureGistPersistence`, the MCP init memo)
+ * that run before or around manager creation, where there is no
+ * StateManager to ask:
+ *
+ * - `no-token`: gist is configured but no GitHub token was available.
+ * - `state-unreadable`: the state file could not be read for this attempt.
+ * - `init-fallback`: init resolved degraded — `ensureGistPersistence`
+ *   reported `'degraded'` (transient network fallback, or a #1443 degraded
+ *   bootstrap, which it deliberately conflates at that layer).
+ */
+export type GistWarningCause = GistHealthDegradedCause | 'no-token' | 'state-unreadable' | 'init-fallback';
+/**
+ * Snapshot of gist persistence health from the one source of truth
+ * (`StateManager.getGistHealth()`), shaped per #1444.
+ */
+export interface GistHealth {
+    /** `'gist'` when the manager is gist-backed (a GistStateStore is attached),
+     * `'local'` otherwise — regardless of what the config asks for. */
+    mode: 'local' | 'gist';
+    /** `null` when healthy: either genuinely local (config agrees) or
+     * gist-backed with an armed store. Non-null when this process is not
+     * reliably syncing to the Gist. */
+    degraded: null | {
+        cause: GistHealthDegradedCause;
+        /** ISO timestamp when the degradation was first observed, when known
+         * (a degraded bootstrap seeds the staleness marker; a
+         * configured-but-local manager has no marker to date it by). */
+        since?: string;
+        /** Whether a later init/recovery attempt can heal this without user
+         * action. Both manager-level causes are recoverable by re-running
+         * `ensureGistPersistence` with a token (#1415/#1443); a PERMANENT halt
+         * (e.g. token lacking the gist scope) surfaces as a thrown
+         * ConfigurationError at the surface that attempted recovery — the
+         * manager itself cannot observe it, so it never reports false here. */
+        recoverable: boolean;
+    };
+}
+/**
+ * Render the one gist-degradation warning shown by every surface (#1444).
+ *
+ * Accepts either a known {@link GistWarningCause} or `{ reason }` for the
+ * hard-error paths (ConfigurationError repair carve-outs) whose reason text
+ * is built from the underlying error.
+ *
+ * @param cause - Known cause, or a free-form reason for hard init errors.
+ * @param opts.retryHint - Optional trailing sentence describing the
+ *   surface-specific retry behavior (e.g. the MCP's "Will retry on the next
+ *   tool call.").
+ */
+export declare function renderGistWarning(cause: GistWarningCause | {
+    reason: string;
+}, opts?: {
+    retryHint?: string;
+}): string;

package/dist/core/gist-health.js

@@ -0,0 +1,39 @@
+/**
+ * One health source and one warning renderer for gist persistence (#1444).
+ *
+ * "Are we degraded?" used to be answered by three independent predicates
+ * (`config.persistence === 'gist' && !isGistMode()`, the
+ * `GistPersistenceStatus` union, `isGistMode() && isGistDegraded()`), each
+ * re-rendering its own warning prose. `StateManager.getGistHealth()` is now
+ * the single predicate for live-manager surfaces (daily warnings, dashboard
+ * probes), and {@link renderGistWarning} is the single prose renderer for
+ * every surface (CLI envelope, MCP injection, bootstrapGistBestEffort,
+ * daily warnings).
+ */
+/** Cause → human reason, the MCP's former `gistWarningText` mapping promoted
+ * to core (#1444). Keep these one-line and append-only: surfaces interpolate
+ * them mid-sentence. */
+const GIST_DEGRADED_REASON = {
+    'no-token': 'no GitHub token was available',
+    'state-unreadable': 'the state file could not be read',
+    'init-fallback': 'initialization hit a transient network failure',
+    'configured-but-local': 'this process is running local-only (Gist init has not succeeded)',
+    'bootstrap-degraded': 'the Gist bootstrap fell back to the local cache (reads may be stale and pushes are failing)',
+};
+/**
+ * Render the one gist-degradation warning shown by every surface (#1444).
+ *
+ * Accepts either a known {@link GistWarningCause} or `{ reason }` for the
+ * hard-error paths (ConfigurationError repair carve-outs) whose reason text
+ * is built from the underlying error.
+ *
+ * @param cause - Known cause, or a free-form reason for hard init errors.
+ * @param opts.retryHint - Optional trailing sentence describing the
+ *   surface-specific retry behavior (e.g. the MCP's "Will retry on the next
+ *   tool call.").
+ */
+export function renderGistWarning(cause, opts = {}) {
+    const reason = typeof cause === 'string' ? GIST_DEGRADED_REASON[cause] : cause.reason;
+    return (`Gist persistence is configured but ${reason}; writes are LOCAL-ONLY and may be ` +
+        `overwritten by the next successful Gist sync.${opts.retryHint ? ` ${opts.retryHint}` : ''}`);
+}

package/dist/core/gist-state-store.d.ts

@@ -232,7 +232,9 @@ export declare class GistStateStore {
     push(): Promise<boolean>;
     /**
      * Re-fetch the Gist and update the in-memory cache.
-     * Throttled to at most once per 30 seconds.
+     * Throttled to at most once per 30 seconds — ATTEMPTS, not just successes:
+     * a failed fetch stamps the throttle too (#1443), so an outage does not
+     * turn every SPA poll into an immediate full re-fetch.
      *
      * Returns a discriminated union so callers can tell apart the four
      * outcomes that previously collapsed into a single boolean (#1209 L9):