@oss-autopilot/core 3.10.0 → 3.11.0

package/dist/cli.js

@@ -10,7 +10,7 @@
  */
 import { Command } from 'commander';
 import { getGitHubTokenAsync, enableDebug, debug, getCLIVersion, stateFileExists } from './core/index.js';
-import { commands } from './cli-registry.js';
+import { commands, handleCommandError } from './cli-registry.js';
 const VERSION = getCLIVersion();
 const program = new Command();
 program
@@ -100,5 +100,13 @@ Run oss-autopilot --help for all commands.
 `);
     process.exit(0);
 }
-// Parse and execute
-program.parse();
+// Parse and execute. parseAsync, not parse: the preAction hook is async, so
+// with synchronous parse() a rejected hook promise (corrupt Gist, missing
+// gist scope, rate limit during bootstrap — all of which ensureGistPersistence
+// now propagates) became an UnhandledPromiseRejection and the user saw a raw
+// stack instead of the actionable message (#1386). Command actions already
+// route their errors through executeAction/handleCommandError, so this catch
+// covers exactly the hook path (plus any handler that escapes the wrapper).
+program.parseAsync().catch((err) => {
+    handleCommandError(err, process.argv.includes('--json'));
+});

package/dist/commands/comments.js

@@ -3,7 +3,8 @@
  * Handles GitHub comment interactions
  */
 import { getStateManager, getOctokit, parseGitHubUrl, requireGitHubToken, maybeCheckpoint } from '../core/index.js';
-import { ValidationError } from '../core/errors.js';
+import { wrapUntrustedContent } from '../core/untrusted-content.js';
+import { ValidationError, isRateLimitOrAuthError } from '../core/errors.js';
 import { warn } from '../core/logger.js';
 const MODULE = 'comments';
 import { paginateAll } from '../core/pagination.js';
@@ -77,6 +78,12 @@ export async function runComments(options) {
     const relevantReviews = reviews
         .filter((r) => filterComment(r) && r.body && r.body.trim())
         .sort((a, b) => new Date(b.submitted_at || 0).getTime() - new Date(a.submitted_at || 0).getTime());
+    // Fence every third-party body at this boundary: the output feeds agents
+    // directly (CLI --json, the MCP `comments` tool, and the `respond-to-pr`
+    // MCP prompt), so raw GitHub text must never reach a prompt unfenced
+    // (#1372). The CLI text display unwraps via safeExtractFromFence.
+    const fenceLabel = `${owner}/${repo}#${pull_number}`;
+    const fence = (body, source, author, association) => wrapUntrustedContent(body, fenceLabel, { author, association, source });
     const staleness = stateManager.getStateStaleness();
     return {
         pr: {
@@ -90,18 +97,18 @@ export async function runComments(options) {
         reviews: relevantReviews.map((r) => ({
             user: r.user?.login,
             state: r.state,
-            body: r.body ?? null,
+            body: r.body == null ? null : fence(r.body, 'pr-review', r.user?.login, r.author_association),
             submittedAt: r.submitted_at ?? null,
         })),
         reviewComments: relevantReviewComments.map((c) => ({
             user: c.user?.login,
-            body: c.body,
+            body: fence(c.body, 'pr-review-comment', c.user?.login, c.author_association),
             path: c.path,
             createdAt: c.created_at,
         })),
         issueComments: relevantIssueComments.map((c) => ({
             user: c.user?.login,
-            body: c.body,
+            body: c.body == null ? c.body : fence(c.body, 'pr-issue-comment', c.user?.login, c.author_association),
             createdAt: c.created_at,
         })),
         summary: {
@@ -170,16 +177,15 @@ export async function runClaim(options) {
     }
     const { owner, repo, number } = parsed;
     const octokit = getOctokit(token);
-    const { data: comment } = await octokit.issues.createComment({
-        owner,
-        repo,
-        issue_number: number,
-        body: message,
-    });
     // Fetch the real issue title + labels so the tracked entry has useful metadata
     // rather than a permanent "(claimed)" placeholder that never gets backfilled
     // (#1056 M24). Best-effort: if the fetch fails, fall back to the placeholder
     // so state still records the claim.
+    //
+    // Ordering matters: enrichment runs BEFORE the claim comment is posted
+    // (#1391). Rate-limit / auth failures rethrow here, and aborting after the
+    // comment landed would leave an orphaned claim on GitHub that local state
+    // never tracked — aborting before it means a clean no-op the user can retry.
     let issueTitle = '(claimed)';
     let issueLabels = [];
     let issueCreatedAt = new Date().toISOString();
@@ -194,9 +200,18 @@ export async function runClaim(options) {
             issueCreatedAt = issue.created_at;
     }
     catch (error) {
-        warn(MODULE, `Claimed ${options.issueUrl} but failed to enrich issue metadata (title/labels): ${error instanceof Error ? error.message : error}`);
+        if (isRateLimitOrAuthError(error))
+            throw error;
+        warn(MODULE, `Failed to enrich issue metadata (title/labels) for ${options.issueUrl}; claiming with placeholder: ${error instanceof Error ? error.message : error}`);
     }
+    const { data: comment } = await octokit.issues.createComment({
+        owner,
+        repo,
+        issue_number: number,
+        body: message,
+    });
     // Add to tracked issues — non-fatal if state save fails (comment already posted)
+    let gistSyncWarning = null;
     try {
         const stateManager = getStateManager();
         stateManager.addIssue({
@@ -211,10 +226,10 @@ export async function runClaim(options) {
             updatedAt: new Date().toISOString(),
             vetted: false,
         });
-        // Push state to Gist if in Gist mode. Best-effort — logs on failure
-        // rather than silently swallowing, so operators see the degraded-sync
-        // signal (#1036 audit H1).
-        await maybeCheckpoint(stateManager, MODULE);
+        // Push state to Gist if in Gist mode. Best-effort — the warning is
+        // threaded into the structured output so MCP/dashboard consumers see
+        // the degraded-sync signal, not just the stderr log (#1036 audit H1, #1370).
+        gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
     }
     catch (error) {
         // Structured warning instead of bare console.error so the breadcrumb shows
@@ -224,5 +239,6 @@ export async function runClaim(options) {
     return {
         commentUrl: comment.html_url,
         issueUrl: options.issueUrl,
+        ...(gistSyncWarning ? { gistSyncWarning } : {}),
     };
 }

package/dist/commands/compliance-score.js

@@ -11,15 +11,20 @@
  * mutation, runs against a public PR URL.
  */
 import { getOctokit, requireGitHubToken } from '../core/index.js';
-import { ValidationError } from '../core/errors.js';
+import { ValidationError, errorMessage, isRateLimitOrAuthError } from '../core/errors.js';
+import { warn } from '../core/logger.js';
 import { validateUrl, PR_URL_PATTERN, validateGitHubUrl } from './validation.js';
 import { parseGitHubUrl } from '../core/urls.js';
 import { computeComplianceScore, } from '../core/compliance-score.js';
+const MODULE = 'compliance-score';
 /**
  * Detect whether the target repo has visible test infrastructure. Looks
  * for the well-known directories at the repo root in a single contents
- * call. Failures (missing repo, rate limit, network) surface as
- * `undefined` so the score function falls back to its strict default.
+ * call. Non-fatal failures (missing repo, 5xx, network) surface as
+ * `undefined` so the score function falls back to its strict default,
+ * with a warning so "couldn't look" is distinguishable from "no test
+ * dir" in logs. Rate-limit / auth errors propagate — swallowing them
+ * here would mask a systemic problem affecting the whole run (#1373).
  */
 async function detectTestInfrastructure(octokit, owner, repo) {
     try {
@@ -29,7 +34,10 @@ async function detectTestInfrastructure(octokit, owner, repo) {
         const TEST_DIR = /^(?:tests?|__tests__|spec)$/i;
         return data.some((entry) => entry.type === 'dir' && TEST_DIR.test(entry.name));
     }
-    catch {
+    catch (err) {
+        if (isRateLimitOrAuthError(err))
+            throw err;
+        warn(MODULE, `test-infrastructure probe for ${owner}/${repo} failed: ${errorMessage(err)}`);
         return undefined;
     }
 }

package/dist/commands/daily.js

@@ -8,6 +8,7 @@
  */
 import { getStateManager, PRMonitor, IssueConversationMonitor, requireGitHubToken, CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatBriefSummary, formatSummary, } from '../core/index.js';
 import { errorMessage, isRateLimitOrAuthError } from '../core/errors.js';
+import { wrapUntrustedContent } from '../core/untrusted-content.js';
 import { computeStrategy, shouldComputeStrategy } from '../core/strategy.js';
 import { warn } from '../core/logger.js';
 import { emptyPRCountsResult } from '../core/github-stats.js';
@@ -457,6 +458,35 @@ function generateDigestOutput(digest, activePRs, shelvedPRs, commentedIssues, fa
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+/**
+ * Fence the GitHub-sourced comment excerpts in a CommentedIssue for
+ * agent-facing JSON (#1372). This happens HERE — not in
+ * `issue-conversation.ts` — because the producer's objects also feed the
+ * dashboard SPA and the CLI text renderers (`daily-render.ts`), which must
+ * not display raw fence tags, and the producer's internal classification
+ * (acknowledgment / @mention matching) string-matches on raw bodies.
+ *
+ * `userLastCommentBody` is fenced too: it is the user's own comment, but
+ * repo maintainers can edit any comment in their repos, so it is still
+ * GitHub-controlled text by the time we re-fetch it.
+ */
+function fenceCommentedIssue(issue) {
+    const label = `${issue.repo}#${issue.number}`;
+    if (issue.status === 'new_response') {
+        return {
+            ...issue,
+            userLastCommentBody: wrapUntrustedContent(issue.userLastCommentBody, label, { source: 'issue-comment' }),
+            lastResponseBody: wrapUntrustedContent(issue.lastResponseBody, label, {
+                author: issue.lastResponseAuthor,
+                source: 'issue-comment',
+            }),
+        };
+    }
+    return {
+        ...issue,
+        userLastCommentBody: wrapUntrustedContent(issue.userLastCommentBody, label, { source: 'issue-comment' }),
+    };
+}
 /**
  * Convert a full DailyCheckResult to the compact DailyOutput for JSON serialization (#287).
  * Deduplicates PR objects: category arrays become PR URL references,
@@ -473,7 +503,7 @@ export function toDailyOutput(result) {
         briefSummary: result.briefSummary,
         actionableIssues: compactActionableIssues(result.actionableIssues),
         actionMenu: result.actionMenu,
-        commentedIssues: result.commentedIssues,
+        commentedIssues: result.commentedIssues.map(fenceCommentedIssue),
         repoGroups: compactRepoGroups(result.repoGroups),
         failures: result.failures,
         warnings: result.warnings,
@@ -516,6 +546,13 @@ async function executeDailyCheckInternal(token) {
     if (staleness) {
         warnings.push(buildStalenessWarning(staleness));
     }
+    // Surface a state-load recovery (corrupt state.json restored from backup or
+    // replaced with fresh state) so it's machine-visible, not just stderr (#1371).
+    const loadRecovery = getStateManager().getLoadRecovery();
+    if (loadRecovery) {
+        recordWarning(warnings, 'state-load', 'State file recovery', new Error(`${loadRecovery.reason}; recovered from ${loadRecovery.source}` +
+            (loadRecovery.rejectedPath ? `; rejected file preserved at ${loadRecovery.rejectedPath}` : '')));
+    }
     // Phase 1: Fetch all PR data from GitHub
     const { prs, failures, mergedCounts, closedCounts, monthlyCounts, monthlyClosedCounts, openedFromMerged, openedFromClosed, recentlyClosedPRs, recentlyMergedPRs, commentedIssues, } = await fetchPRData(prMonitor, token, warnings);
     // Phase 2: Update repo scores (signals, star counts, trust sync)
@@ -566,10 +603,18 @@ async function executeDailyCheckInternal(token) {
     // Checkpoint: push state to Gist if in Gist mode.
     // If getStateManagerAsync was not called before this command ran,
     // isGistMode() will be false and checkpoint is correctly skipped.
+    // `warnings` is the same array referenced by `result`, so warnings
+    // recorded here still reach the structured output.
     try {
         const sm = getStateManager();
         if (sm.isGistMode()) {
-            await sm.checkpoint();
+            // checkpoint() resolves false (no throw) when the push failed after
+            // its retry — previously discarded, reporting clean success while
+            // cross-machine state silently drifted (#1370).
+            const pushed = await sm.checkpoint();
+            if (!pushed) {
+                recordWarning(warnings, 'gist-checkpoint', 'Gist checkpoint', new Error('push failed after retry; state not synced to Gist this run'));
+            }
         }
     }
     catch (err) {

package/dist/commands/dashboard-data.d.ts

@@ -67,6 +67,23 @@ export interface ActionRequest {
     target?: 'attention' | 'waiting' | 'shelved' | 'auto';
 }
 export declare function buildDashboardStats(digest: DailyDigest, state: Readonly<AgentState>, storedMergedCount?: number, storedClosedCount?: number): DashboardStats;
+/**
+ * Re-derive `digest.shelvedPRs` and `summary.totalActivePRs` from the CURRENT
+ * `state.config.shelvedPRUrls` so a shelve/unshelve issued from the dashboard
+ * SPA is reflected immediately.
+ *
+ * Why this exists: POST /api/action → runMove only mutates
+ * `state.config.shelvedPRUrls`; it never touches the cached digest.
+ * buildDashboardJson derives both `shelvedPRUrls` and `stats.shelvedPRs` from
+ * `digest.shelvedPRs`, so without this reconciliation a dashboard shelve/unshelve
+ * appears to do nothing until the next full /api/refresh rebuilds the digest.
+ *
+ * Baked shelved entries that are NOT among the current open PRs (the daily-check
+ * dormant partition, #981) are preserved as-is — the SPA cannot act on those —
+ * while explicit shelve/unshelve of open PRs and the dormant-auto-shelve rule
+ * are honored.
+ */
+export declare function reconcileShelvePartition(digest: DailyDigest, state: Readonly<AgentState>): void;
 /**
  * Merge fresh API counts into existing stored counts.
  * Months present in the fresh data are updated; months only in the existing data are preserved.

package/dist/commands/dashboard-data.js

@@ -35,6 +35,55 @@ export function buildDashboardStats(digest, state, storedMergedCount, storedClos
         mergeRate: `${(summary.mergeRate ?? 0).toFixed(1)}%`,
     };
 }
+/**
+ * A PR is shelved for display when the user explicitly shelved it, or the
+ * dormant-auto-shelve rule applies (dormant + not needing attention). Mirrors
+ * the partition built in fetchDashboardData (see the `freshShelved` filter).
+ */
+function isShelvedForDisplay(pr, explicitlyShelved) {
+    return explicitlyShelved.has(pr.url) || (pr.stalenessTier === 'dormant' && pr.status !== 'needs_addressing');
+}
+/**
+ * Re-derive `digest.shelvedPRs` and `summary.totalActivePRs` from the CURRENT
+ * `state.config.shelvedPRUrls` so a shelve/unshelve issued from the dashboard
+ * SPA is reflected immediately.
+ *
+ * Why this exists: POST /api/action → runMove only mutates
+ * `state.config.shelvedPRUrls`; it never touches the cached digest.
+ * buildDashboardJson derives both `shelvedPRUrls` and `stats.shelvedPRs` from
+ * `digest.shelvedPRs`, so without this reconciliation a dashboard shelve/unshelve
+ * appears to do nothing until the next full /api/refresh rebuilds the digest.
+ *
+ * Baked shelved entries that are NOT among the current open PRs (the daily-check
+ * dormant partition, #981) are preserved as-is — the SPA cannot act on those —
+ * while explicit shelve/unshelve of open PRs and the dormant-auto-shelve rule
+ * are honored.
+ */
+export function reconcileShelvePartition(digest, state) {
+    const openPRs = (digest.openPRs || []);
+    const openByUrl = new Map(openPRs.map((pr) => [pr.url, pr]));
+    const explicitlyShelved = new Set(state.config.shelvedPRUrls || []);
+    // Keep baked entries that are either off the open-PR list (daily dormant
+    // partition we can't recompute here) or still shelved under current state.
+    const reconciled = (digest.shelvedPRs || []).filter((ref) => {
+        const pr = openByUrl.get(ref.url);
+        return !pr || isShelvedForDisplay(pr, explicitlyShelved);
+    });
+    // Add open PRs that became shelved but aren't represented in the baked list yet.
+    const present = new Set(reconciled.map((ref) => ref.url));
+    for (const pr of openPRs) {
+        if (!present.has(pr.url) && isShelvedForDisplay(pr, explicitlyShelved)) {
+            reconciled.push(toShelvedPRRef(pr));
+        }
+    }
+    digest.shelvedPRs = reconciled;
+    // Only re-derive the active count when we actually have the open-PR list;
+    // some digests carry an authoritative summary with an empty openPRs fixture.
+    if (openPRs.length > 0) {
+        const shelvedOpen = reconciled.filter((ref) => openByUrl.has(ref.url)).length;
+        digest.summary.totalActivePRs = openPRs.length - shelvedOpen;
+    }
+}
 /**
  * Merge fresh API counts into existing stored counts.
  * Months present in the fresh data are updated; months only in the existing data are preserved.

package/dist/commands/dashboard-server.js

@@ -10,10 +10,10 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { getStateManager, getGitHubToken, getCLIVersion, applyStatusOverrides } from '../core/index.js';
-import { errorMessage, ValidationError } from '../core/errors.js';
+import { errorMessage, ValidationError, ConcurrencyError, GistConcurrencyError } from '../core/errors.js';
 import { warn } from '../core/logger.js';
 import { validateUrl, validateGitHubUrl, PR_URL_PATTERN, ISSUE_URL_PATTERN } from './validation.js';
-import { fetchDashboardData, computePRsByRepo, computeTopRepos, getMonthlyData, buildDashboardStats, storedToMergedPRs, storedToClosedPRs, } from './dashboard-data.js';
+import { fetchDashboardData, computePRsByRepo, computeTopRepos, getMonthlyData, buildDashboardStats, reconcileShelvePartition, storedToMergedPRs, storedToClosedPRs, } from './dashboard-data.js';
 import { openInBrowser, detectIssueList } from './startup.js';
 import { parseIssueList } from './parse-list.js';
 import { writeDashboardServerInfo, removeDashboardServerInfo } from './dashboard-process.js';
@@ -75,6 +75,11 @@ function getIssueListMtimeMs() {
  * start-up, so tests that need a specific digest should call this directly).
  */
 export function buildDashboardJson(digest, state, commentedIssues, allMergedPRs, allClosedPRs, partialFailures) {
+    // Re-derive the shelve partition from the CURRENT state before reading it.
+    // The POST /api/action path rebuilds with a cached digest whose shelvedPRs
+    // predates the shelve/unshelve, so without this the SPA action appears to do
+    // nothing until the next full /api/refresh.
+    reconcileShelvePartition(digest, state);
     const prsByRepo = computePRsByRepo(digest, state);
     const topRepos = computeTopRepos(prsByRepo);
     const { monthlyMerged, monthlyOpened, monthlyClosed } = getMonthlyData(state);
@@ -240,6 +245,27 @@ function sendJson(res, statusCode, data) {
 function sendError(res, statusCode, message) {
     sendJson(res, statusCode, { error: message });
 }
+/**
+ * True when an error is an optimistic-concurrency conflict on state.json
+ * (local mtime CAS) or the state Gist (ETag CAS). Both carry the
+ * CONCURRENCY_ERROR code and the same recovery contract: reload, re-apply,
+ * save. See state-concurrency.test.ts (#1378) and errors.ts.
+ */
+function isConcurrencyConflict(error) {
+    return error instanceof ConcurrencyError || error instanceof GistConcurrencyError;
+}
+/**
+ * Send the machine-readable 409 for a concurrency conflict (#1397).
+ * `retryable: true` tells the SPA it can re-prime via GET /api/data and
+ * retry the POST; `code` matches the structured code on ConcurrencyError.
+ */
+function sendConflict(res) {
+    sendJson(res, 409, {
+        error: 'Another process wrote state concurrently — retry the request',
+        code: 'CONCURRENCY_ERROR',
+        retryable: true,
+    });
+}
 // ── Server ─────────────────────────────────────────────────────────────────────
 export async function startDashboardServer(options) {
     const { port: requestedPort, assetsDir, token, open } = options;
@@ -398,14 +424,16 @@ export async function startDashboardServer(options) {
     });
     server.requestTimeout = REQUEST_TIMEOUT_MS;
     // ── POST /api/action handler ─────────────────────────────────────────────
-    async function handleAction(req, res) {
-        // Reload state before mutating to avoid overwriting external CLI changes
+    /** Re-read state written by external processes (CLI) before mutating. */
+    async function reloadState() {
         if (stateManager.isGistMode()) {
             await stateManager.refreshFromGist();
         }
         else {
             stateManager.reloadIfChanged();
         }
+    }
+    async function handleAction(req, res) {
         let body;
         try {
             const raw = await readBody(req);
@@ -440,24 +468,62 @@ export async function startDashboardServer(options) {
             }
             return;
         }
-        try {
-            if (body.action === 'move') {
-                const { VALID_TARGETS, runMove } = await import('./move.js');
-                if (!body.target || !VALID_TARGETS.includes(body.target)) {
-                    sendError(res, 400, `move requires a valid "target" field (${VALID_TARGETS.join(', ')})`);
-                    return;
-                }
-                await runMove({ prUrl: body.url, target: body.target });
+        // Resolve the mutation up-front so target validation happens before the
+        // state reload — keeps the reload-to-save freshness window minimal.
+        let applyMutation;
+        if (body.action === 'move') {
+            const { VALID_TARGETS, runMove } = await import('./move.js');
+            if (!body.target || !VALID_TARGETS.includes(body.target)) {
+                sendError(res, 400, `move requires a valid "target" field (${VALID_TARGETS.join(', ')})`);
+                return;
             }
-            else {
-                // dismiss_issue_response
+            const target = body.target;
+            applyMutation = async () => {
+                await runMove({ prUrl: body.url, target });
+            };
+        }
+        else {
+            // dismiss_issue_response
+            applyMutation = () => {
                 stateManager.dismissIssue(body.url, new Date().toISOString());
-            }
+            };
+        }
+        // Reload state before mutating to avoid overwriting external CLI changes.
+        // Runs AFTER body parsing/validation (which only inspects the request,
+        // never the loaded state) so the read-modify-write window excludes the
+        // body-streaming time (#1397).
+        await reloadState();
+        try {
+            await applyMutation();
         }
         catch (error) {
-            warn(MODULE, `Action failed: ${body.action} ${body.url} ${errorMessage(error)}`);
-            sendError(res, 500, 'Action failed');
-            return;
+            if (!isConcurrencyConflict(error)) {
+                warn(MODULE, `Action failed: ${body.action} ${body.url} ${errorMessage(error)}`);
+                sendError(res, 500, 'Action failed');
+                return;
+            }
+            // Concurrency conflict: an external write landed between our reload and
+            // save. Decision (#1397): retry ONCE server-side instead of bouncing the
+            // first conflict to the client. Both mutations (move targets, dismiss)
+            // are absolute set operations, so re-applying them on a freshly reloaded
+            // baseline is safe — exactly the reload-reapply recovery contract pinned
+            // in state-concurrency.test.ts. A second consecutive conflict means
+            // sustained contention; surface it as a retryable 409 and let the SPA
+            // re-prime and retry.
+            try {
+                await reloadState();
+                await applyMutation();
+            }
+            catch (retryError) {
+                if (isConcurrencyConflict(retryError)) {
+                    warn(MODULE, `Action conflicted twice: ${body.action} ${body.url} ${errorMessage(retryError)}`);
+                    sendConflict(res);
+                    return;
+                }
+                warn(MODULE, `Action failed on conflict retry: ${body.action} ${body.url} ${errorMessage(retryError)}`);
+                sendError(res, 500, 'Action failed');
+                return;
+            }
         }
         // Rebuild dashboard data from cached digest + updated state. Persist
         // the last-known partialFailures across action rebuilds (#1035) so the
@@ -475,12 +541,7 @@ export async function startDashboardServer(options) {
             return;
         }
         try {
-            if (stateManager.isGistMode()) {
-                await stateManager.refreshFromGist();
-            }
-            else {
-                stateManager.reloadIfChanged();
-            }
+            await reloadState();
             warn(MODULE, 'Refreshing dashboard data from GitHub...');
             const result = await fetchDashboardData(currentToken);
             cachedDigest = result.digest;
@@ -493,6 +554,14 @@ export async function startDashboardServer(options) {
             sendJson(res, 200, cachedJsonData);
         }
         catch (error) {
+            // No server-side retry here (unlike handleAction): a refresh re-run is a
+            // full GitHub fetch — expensive and rate-limited. The 409 is retryable
+            // by the client, which re-POSTs /api/refresh on its own schedule (#1397).
+            if (isConcurrencyConflict(error)) {
+                warn(MODULE, `Dashboard refresh hit a concurrent state write: ${errorMessage(error)}`);
+                sendConflict(res);
+                return;
+            }
             warn(MODULE, `Dashboard refresh failed: ${errorMessage(error)}`);
             sendError(res, 500, 'Refresh failed');
         }

package/dist/commands/dismiss.d.ts

@@ -6,10 +6,14 @@
 export interface DismissOutput {
     dismissed: boolean;
     url: string;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 export interface UndismissOutput {
     undismissed: boolean;
     url: string;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 /**
  * Dismiss an issue's reply notifications without posting a comment.

package/dist/commands/dismiss.js

@@ -20,8 +20,8 @@ export async function runDismiss(options) {
     validateGitHubUrl(options.url, ISSUE_URL_PATTERN, 'issue');
     const stateManager = getStateManager();
     const added = stateManager.dismissIssue(options.url, new Date().toISOString());
-    await maybeCheckpoint(stateManager, MODULE);
-    return { dismissed: added, url: options.url };
+    const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+    return { dismissed: added, url: options.url, ...(gistSyncWarning ? { gistSyncWarning } : {}) };
 }
 /**
  * Restore a dismissed issue to notifications.
@@ -36,6 +36,6 @@ export async function runUndismiss(options) {
     validateGitHubUrl(options.url, ISSUE_URL_PATTERN, 'issue');
     const stateManager = getStateManager();
     const removed = stateManager.undismissIssue(options.url);
-    await maybeCheckpoint(stateManager, MODULE);
-    return { undismissed: removed, url: options.url };
+    const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+    return { undismissed: removed, url: options.url, ...(gistSyncWarning ? { gistSyncWarning } : {}) };
 }

package/dist/commands/guidelines.d.ts

@@ -10,15 +10,26 @@ export interface GuidelinesViewOutput {
     /** Where the guidelines would be persisted if a write happened now. */
     storageMode: 'gist' | 'local-unavailable';
 }
+export interface GuidelinesListOutput {
+    /** Repos with non-empty guidelines stored, sorted alphabetically. Always empty in local mode. */
+    repos: string[];
+    count: number;
+    /** Where guidelines are persisted. `local-unavailable` always yields an empty list. */
+    storageMode: 'gist' | 'local-unavailable';
+}
 export interface GuidelinesStoreOutput {
     repo: string;
     byteSize: number;
     stored: boolean;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 export interface GuidelinesResetOutput {
     repo: string;
     /** True when an existing file was tombstoned, false when no file existed. */
     deleted: boolean;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 export interface FetchCorpusOutput {
     repo: string;
@@ -37,6 +48,8 @@ export interface FetchCorpusOutput {
         prUrl: string;
         error: string;
     }>;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 interface RepoOption {
     repo: string;
@@ -52,6 +65,12 @@ interface StoreOptions extends RepoOption {
 }
 /** Read the per-repo guidelines for `repo`. Returns a `local-unavailable` envelope in non-Gist mode. */
 export declare function runGuidelinesView(options: RepoOption): Promise<GuidelinesViewOutput>;
+/**
+ * List every repo with non-empty stored guidelines. Never throws in local
+ * mode — returns an empty list with `storageMode: 'local-unavailable'` so
+ * hosts can distinguish "nothing stored" from "storage not configured".
+ */
+export declare function runGuidelinesList(): Promise<GuidelinesListOutput>;
 /**
  * Persist per-repo guidelines for `repo`. Throws when not in Gist mode or
  * when content exceeds the byte budget — the CLI surface relies on the