@oss-autopilot/core 3.13.3 → 3.14.0

package/dist/commands/init.js

@@ -2,8 +2,9 @@
  * Init command
  * Initialize with GitHub username. In v2, PRs are fetched fresh on each daily run.
  */
-import { getStateManager } from '../core/index.js';
+import { getStateManager, maybeCheckpoint } from '../core/index.js';
 import { validateGitHubUsername } from './validation.js';
+const MODULE = 'init';
 /**
  * Initialize with a GitHub username.
  *
@@ -17,8 +18,13 @@ export async function runInit(options) {
     const stateManager = getStateManager();
     // Set username in config
     stateManager.updateConfig({ githubUsername: options.username });
+    // Push the config mutation to the Gist in gist mode (no-op locally).
+    // Without this the change only hits the local cache and the next
+    // bootstrap reverts it from the Gist (#1440).
+    const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
     return {
         username: options.username,
         message: 'Username saved. Run `daily` to fetch your open PRs from GitHub.',
+        ...(gistSyncWarning ? { gistSyncWarning } : {}),
     };
 }

package/dist/commands/list-mark-done.js

@@ -17,9 +17,9 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { errorMessage, ValidationError } from '../core/errors.js';
+import { ENTRY_LINE_RE, ENTRY_MARKER_RE, lineMentionsUrl } from './curated-list.js';
 const STRIKE = '~~';
 const DONE_PREFIX = '  - **Done**';
-const ISSUE_LINE_RE = /^[*+-]\s/;
 const REPO_HEADING_RE = /^###\s/;
 const SECTION_BREAK_RE = /^#{1,3}\s/;
 const PR_NUMBER_RE = /\/(?:pull|issues)\/(\d+)(?:[/?#]|$)/;
@@ -31,7 +31,7 @@ function prNumberLabel(prUrl) {
 /** Wrap a line in `~~...~~` if it isn't already. Returns the input unchanged when already wrapped. */
 function strikeLine(line) {
     // Strip the leading list marker so we wrap the content, not the bullet.
-    const markerMatch = line.match(/^(?:[*+-]\s+|#{1,6}\s+)/);
+    const markerMatch = line.match(/^(?:[*+-]\s+|\d+\.\s+|#{1,6}\s+)/);
     const prefix = markerMatch ? markerMatch[0] : '';
     const body = line.slice(prefix.length);
     if (body.startsWith(STRIKE) && body.endsWith(STRIKE) && body.length >= 4) {
@@ -39,26 +39,11 @@ function strikeLine(line) {
     }
     return { line: `${prefix}${STRIKE}${body}${STRIKE}`, alreadyStruck: false };
 }
-/**
- * Match the URL only when followed by a non-digit, non-word character (or
- * end of line). A bare `includes(issueUrl)` would match `issues/1` against
- * a line containing `issues/10`, so finding/marking issue 1 would mark
- * whichever number-prefix line appears first.
- */
-function lineMentionsUrl(line, issueUrl) {
-    const idx = line.indexOf(issueUrl);
-    if (idx === -1)
-        return false;
-    const next = line.charCodeAt(idx + issueUrl.length);
-    // NaN (end of string) → digit boundary OK. Otherwise reject any digit
-    // immediately after the URL so 'issues/1' doesn't match 'issues/10'.
-    return Number.isNaN(next) || next < 48 /* '0' */ || next > 57; /* '9' */
-}
 /** Find the issue block (issue line plus any indented sub-bullets) that mentions the URL. */
 function findIssueBlock(lines, issueUrl) {
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
-        if (!ISSUE_LINE_RE.test(line))
+        if (!ENTRY_LINE_RE.test(line))
             continue;
         if (!lineMentionsUrl(line, issueUrl))
             continue;
@@ -96,9 +81,9 @@ function countOpenIssues(lines, section) {
     let open = 0;
     for (let i = section.headingIndex + 1; i < section.end; i++) {
         const line = lines[i];
-        if (!ISSUE_LINE_RE.test(line))
+        if (!ENTRY_LINE_RE.test(line))
             continue;
-        const body = line.replace(/^[*+-]\s+/, '');
+        const body = line.replace(ENTRY_MARKER_RE, '');
         if (!(body.startsWith(STRIKE) && body.endsWith(STRIKE)))
             open++;
     }
@@ -120,7 +105,7 @@ export function markIssueAsDone(content, opts) {
         };
     }
     const issueLine = lines[block.start];
-    const issueBody = issueLine.replace(/^[*+-]\s+/, '');
+    const issueBody = issueLine.replace(ENTRY_MARKER_RE, '');
     const alreadyMarked = issueBody.startsWith(STRIKE) && issueBody.endsWith(STRIKE);
     if (alreadyMarked) {
         const section = findRepoSection(lines, block.start);

package/dist/commands/list-move-tier.js

@@ -15,6 +15,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { errorMessage, ValidationError } from '../core/errors.js';
+import { ENTRY_LINE_RE, lineMentionsUrl } from './curated-list.js';
 const TIER_HEADERS = {
     pursue: '## Pursue',
     maybe: '## Maybe',
@@ -44,13 +45,10 @@ function tierForLine(lines, lineIndex) {
 /** Locate every issue block (issue line + any sub-bullets) that mentions the URL. */
 function findIssueBlocks(lines, issueUrl) {
     const blocks = [];
-    // Use exact substring match on the URL — no regex escaping pitfalls and
-    // the URL itself contains no markdown delimiters that would split a line.
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
-        // Top-level list item — `- `, `* `, `+ `, or `1.` at the start (with no leading whitespace).
-        const isTopLevelListItem = /^[*+-]\s|^\d+\.\s/.test(line);
-        if (!isTopLevelListItem || !line.includes(issueUrl))
+        // lineMentionsUrl (not a bare includes) so issues/1 can't match issues/10 (#1442).
+        if (!ENTRY_LINE_RE.test(line) || !lineMentionsUrl(line, issueUrl))
             continue;
         // Capture indented sub-bullets that follow this line.
         let end = i + 1;

package/dist/commands/locate-issue-list.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Curated-list path detection (#1463).
+ *
+ * Extracted from `startup.ts` so the daily merge-loop reconciliation can
+ * locate the list without importing `startup.ts` — that would close an
+ * import cycle (startup → daily → merge-loop → startup). `startup.ts`
+ * re-exports `parseIssueListPathFromConfig` for back-compat and layers item
+ * counts / skipped-issues detection on top of `detectIssueListPath`.
+ */
+/**
+ * Parse issueListPath from a config file's YAML frontmatter.
+ * @param configContent - Raw content of the config.md file
+ * @returns The path string or undefined if not found
+ */
+export declare function parseIssueListPathFromConfig(configContent: string): string | undefined;
+export interface IssueListLocation {
+    path: string;
+    source: 'configured' | 'auto-detected';
+}
+/**
+ * Locate the curated issue-list file: state config first, then the legacy
+ * config.md frontmatter, then known default paths. Returns undefined when
+ * no list exists — callers treat that as "user has no curated list".
+ */
+export declare function detectIssueListPath(): IssueListLocation | undefined;

package/dist/commands/locate-issue-list.js

@@ -0,0 +1,67 @@
+/**
+ * Curated-list path detection (#1463).
+ *
+ * Extracted from `startup.ts` so the daily merge-loop reconciliation can
+ * locate the list without importing `startup.ts` — that would close an
+ * import cycle (startup → daily → merge-loop → startup). `startup.ts`
+ * re-exports `parseIssueListPathFromConfig` for back-compat and layers item
+ * counts / skipped-issues detection on top of `detectIssueListPath`.
+ */
+import * as fs from 'node:fs';
+import { getStateManager } from '../core/index.js';
+import { errorMessage } from '../core/errors.js';
+import { warn } from '../core/logger.js';
+/**
+ * Parse issueListPath from a config file's YAML frontmatter.
+ * @param configContent - Raw content of the config.md file
+ * @returns The path string or undefined if not found
+ */
+export function parseIssueListPathFromConfig(configContent) {
+    const match = configContent.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return undefined;
+    const frontmatter = match[1];
+    const pathMatch = frontmatter.match(/issueListPath:\s*["']?([^"'\n]+)["']?/);
+    return pathMatch ? pathMatch[1].trim() : undefined;
+}
+/**
+ * Locate the curated issue-list file: state config first, then the legacy
+ * config.md frontmatter, then known default paths. Returns undefined when
+ * no list exists — callers treat that as "user has no curated list".
+ */
+export function detectIssueListPath() {
+    // 1. Check state.json config (primary)
+    try {
+        const stateManager = getStateManager();
+        const configuredPath = stateManager.getState().config.issueListPath;
+        if (configuredPath && fs.existsSync(configuredPath)) {
+            return { path: configuredPath, source: 'configured' };
+        }
+    }
+    catch (error) {
+        // State manager may not be initialized yet — fall through to legacy config.md
+        warn('startup', `Could not read issueListPath from state: ${errorMessage(error)}`);
+    }
+    // 2. Fallback: config.md (legacy — will be removed in future)
+    const configPath = '.claude/oss-autopilot/config.md';
+    if (fs.existsSync(configPath)) {
+        try {
+            const configContent = fs.readFileSync(configPath, 'utf8');
+            const configuredPath = parseIssueListPathFromConfig(configContent);
+            if (configuredPath && fs.existsSync(configuredPath)) {
+                return { path: configuredPath, source: 'configured' };
+            }
+        }
+        catch (error) {
+            console.error('[STARTUP] Failed to read config:', errorMessage(error));
+        }
+    }
+    // 3. Probe known paths
+    const probes = ['open-source/potential-issue-list.md', 'oss/issue-list.md', 'issues.md'];
+    for (const probe of probes) {
+        if (fs.existsSync(probe)) {
+            return { path: probe, source: 'auto-detected' };
+        }
+    }
+    return undefined;
+}

package/dist/commands/merge-loop.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Close the merge loop (#1463).
+ *
+ * When the daily check detects recently merged PRs, nothing previously
+ * connected the merge back to the curated issue list — `list-mark-done` is
+ * only offered interactively at PR-creation time (draft-first-workflow
+ * Step 10), so a skipped prompt left the entry open forever.
+ *
+ * The join: neither the merged-PR search result (url/repo/number/title/
+ * mergedAt) nor `state.activeIssues` (TrackedIssue — issue URL only, no PR
+ * URL) carries a deterministic PR→issue link. The only deterministic
+ * linkage lives in the curated list itself: workflows record the PR URL in
+ * an entry's sub-bullets (`**Done**` at Step 10, or in-progress markers
+ * like `**In Progress** — PR [#N](url)`). So the reconciliation traverses
+ * the list file's entry blocks for the merged PR URL, recovers the entry's
+ * own URL from its entry line, and marks it done via the exact transform
+ * `list-mark-done` uses. Repo-level guessing (matching a merged PR to "some
+ * claimed issue in the same repo") is deliberately avoided — it could
+ * strike the wrong entry when a repo has several listed issues.
+ *
+ * Auto vs offer: marking a list entry done for a PR that GitHub reports as
+ * MERGED is safe and idempotent (already-marked entries are quiet no-ops),
+ * so it runs automatically. The extract-learnings nudge stays an offer —
+ * it costs API calls and an LLM pass — surfaced via the action menu's
+ * `extract_learnings` item (see computeActionMenu in core/daily-logic.ts).
+ *
+ * Failures never crash the daily run: they land in `warnings[]` under the
+ * `merge-loop` phase.
+ */
+import type { DailyWarning, MergedPRListUpdate } from '../formatters/json.js';
+/**
+ * Find the curated-list entry whose block (entry line plus indented
+ * sub-bullets) mentions `prUrl` on a STATUS-marked line, and return the
+ * entry line's own GitHub URL — the URL `markIssueAsDone` needs to locate
+ * the block again.
+ *
+ * Returns undefined when no entry block mentions the PR URL on a marked
+ * line, or when the mentioning block's entry line carries no GitHub URL
+ * (nothing for the mark-done transform to anchor on).
+ */
+export declare function findListEntryUrlByPrUrl(content: string, prUrl: string): string | undefined;
+export interface ReconcileMergedPRsInput {
+    /** Recently merged PRs from the daily fetch (Phase 1). */
+    mergedPRs: Array<{
+        url: string;
+        mergedAt?: string;
+    }>;
+    /** Shared daily warnings collector — failures land here, never throw. */
+    warnings: DailyWarning[];
+}
+/**
+ * Auto-mark curated-list entries done for recently merged PRs.
+ *
+ * Silent no-op cases (by design — these are normal, not failures):
+ *   - no merged PRs this run
+ *   - no curated list configured/detected
+ *   - no list entry mentions a merged PR's URL
+ *   - the matching entry is already marked done (idempotent re-run)
+ *
+ * Returns the entries actually struck this run, or undefined when nothing
+ * changed — callers omit the field from output rather than emitting `[]`.
+ */
+export declare function reconcileMergedPRsWithList(input: ReconcileMergedPRsInput): MergedPRListUpdate[] | undefined;

package/dist/commands/merge-loop.js

@@ -0,0 +1,157 @@
+/**
+ * Close the merge loop (#1463).
+ *
+ * When the daily check detects recently merged PRs, nothing previously
+ * connected the merge back to the curated issue list — `list-mark-done` is
+ * only offered interactively at PR-creation time (draft-first-workflow
+ * Step 10), so a skipped prompt left the entry open forever.
+ *
+ * The join: neither the merged-PR search result (url/repo/number/title/
+ * mergedAt) nor `state.activeIssues` (TrackedIssue — issue URL only, no PR
+ * URL) carries a deterministic PR→issue link. The only deterministic
+ * linkage lives in the curated list itself: workflows record the PR URL in
+ * an entry's sub-bullets (`**Done**` at Step 10, or in-progress markers
+ * like `**In Progress** — PR [#N](url)`). So the reconciliation traverses
+ * the list file's entry blocks for the merged PR URL, recovers the entry's
+ * own URL from its entry line, and marks it done via the exact transform
+ * `list-mark-done` uses. Repo-level guessing (matching a merged PR to "some
+ * claimed issue in the same repo") is deliberately avoided — it could
+ * strike the wrong entry when a repo has several listed issues.
+ *
+ * Auto vs offer: marking a list entry done for a PR that GitHub reports as
+ * MERGED is safe and idempotent (already-marked entries are quiet no-ops),
+ * so it runs automatically. The extract-learnings nudge stays an offer —
+ * it costs API calls and an LLM pass — surfaced via the action menu's
+ * `extract_learnings` item (see computeActionMenu in core/daily-logic.ts).
+ *
+ * Failures never crash the daily run: they land in `warnings[]` under the
+ * `merge-loop` phase.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { errorMessage } from '../core/errors.js';
+import { warn } from '../core/logger.js';
+import { ENTRY_LINE_RE, lineMentionsUrl } from './curated-list.js';
+import { markIssueAsDone } from './list-mark-done.js';
+import { detectIssueListPath } from './locate-issue-list.js';
+const MODULE = 'merge-loop';
+/** First GitHub issue-or-PR URL on a line, without trailing punctuation. */
+const GITHUB_URL_RE = /https:\/\/github\.com\/[^/\s]+\/[^/\s]+\/(?:issues|pull)\/\d+/;
+/**
+ * A line counts as a STATUS sub-bullet only when it carries one of the
+ * markers the workflows write next to an entry's own PR (`**Done**`,
+ * `**In Progress**`, or a `PR [#N](...)` reference). A bare URL mention
+ * (e.g. a hand-written "blocked by <pr-url>" note under a DIFFERENT
+ * entry) must not auto-strike that entry (#1463 review).
+ */
+const STATUS_MARKER_RE = /\*\*(?:Done|In Progress)\*\*|PR \[#?\d/;
+/**
+ * Find the curated-list entry whose block (entry line plus indented
+ * sub-bullets) mentions `prUrl` on a STATUS-marked line, and return the
+ * entry line's own GitHub URL — the URL `markIssueAsDone` needs to locate
+ * the block again.
+ *
+ * Returns undefined when no entry block mentions the PR URL on a marked
+ * line, or when the mentioning block's entry line carries no GitHub URL
+ * (nothing for the mark-done transform to anchor on).
+ */
+export function findListEntryUrlByPrUrl(content, prUrl) {
+    const lines = content.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        if (!ENTRY_LINE_RE.test(lines[i])) {
+            i++;
+            continue;
+        }
+        // Block = entry line + following indented sub-bullets (same shape as
+        // list-mark-done's findIssueBlock).
+        let end = i + 1;
+        while (end < lines.length && /^\s{2,}/.test(lines[end]))
+            end++;
+        // The entry line mentioning the PR itself is self-anchored (no
+        // cross-entry ambiguity); sub-bullets must carry a status marker.
+        const entryMentions = lineMentionsUrl(lines[i], prUrl);
+        const markedSubBulletMentions = lines
+            .slice(i + 1, end)
+            .some((line) => lineMentionsUrl(line, prUrl) && STATUS_MARKER_RE.test(line));
+        if (entryMentions || markedSubBulletMentions) {
+            const match = GITHUB_URL_RE.exec(lines[i]);
+            if (match)
+                return match[0];
+            // Entry line has no URL to anchor a mark-done on — keep scanning in
+            // case a later block also mentions the PR (e.g. duplicate sections).
+        }
+        i = end;
+    }
+    return undefined;
+}
+/**
+ * Auto-mark curated-list entries done for recently merged PRs.
+ *
+ * Silent no-op cases (by design — these are normal, not failures):
+ *   - no merged PRs this run
+ *   - no curated list configured/detected
+ *   - no list entry mentions a merged PR's URL
+ *   - the matching entry is already marked done (idempotent re-run)
+ *
+ * Returns the entries actually struck this run, or undefined when nothing
+ * changed — callers omit the field from output rather than emitting `[]`.
+ */
+export function reconcileMergedPRsWithList(input) {
+    const { mergedPRs, warnings } = input;
+    if (mergedPRs.length === 0)
+        return undefined;
+    const located = detectIssueListPath();
+    if (!located)
+        return undefined;
+    const listPath = path.resolve(located.path);
+    let content;
+    try {
+        content = fs.readFileSync(listPath, 'utf8');
+    }
+    catch (error) {
+        const message = `read issue list at ${listPath}: ${errorMessage(error)}`;
+        warnings.push({ phase: 'merge-loop', operation: 'auto-mark merged list entries', message });
+        warn(MODULE, message);
+        return undefined;
+    }
+    const updates = [];
+    for (const pr of mergedPRs) {
+        const entryUrl = findListEntryUrlByPrUrl(content, pr.url);
+        if (!entryUrl)
+            continue;
+        const prStatus = pr.mergedAt ? `merged ${pr.mergedAt.slice(0, 10)}` : 'merged';
+        const result = markIssueAsDone(content, { issueUrl: entryUrl, prUrl: pr.url, prStatus });
+        if (!result.marked)
+            continue; // already-marked (or not-found race) — quiet no-op
+        content = result.content;
+        updates.push({
+            prUrl: pr.url,
+            issueUrl: entryUrl,
+            repoHeadingStruck: result.repoHeadingStruck,
+            listPath,
+        });
+    }
+    if (updates.length === 0)
+        return undefined;
+    // Atomic write (tmp + rename), mirroring runMarkIssueListItemDone.
+    const tmp = `${listPath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        fs.writeFileSync(tmp, content, 'utf8');
+        fs.renameSync(tmp, listPath);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            // best-effort cleanup
+        }
+        const message = `write issue list at ${listPath}: ${errorMessage(error)}`;
+        warnings.push({ phase: 'merge-loop', operation: 'auto-mark merged list entries', message });
+        warn(MODULE, message);
+        // Nothing persisted — do not report updates that are not on disk.
+        return undefined;
+    }
+    return updates;
+}

package/dist/commands/repo-vet.js

@@ -10,7 +10,7 @@
  * Same architectural shape as `compliance-score`: read-only API calls,
  * no state mutation, runs against a public `owner/repo` slug.
  */
-import { getOctokit, requireGitHubToken } from '../core/index.js';
+import { getOctokit, getStateManager, requireGitHubToken } from '../core/index.js';
 import { errorMessage, getHttpStatusCode, isRateLimitOrAuthError } from '../core/errors.js';
 import { warn } from '../core/logger.js';
 import { validateRepoIdentifier } from './validation.js';
@@ -102,6 +102,39 @@ async function checkCommunityHealth(octokit, owner, repo) {
         incomplete,
     };
 }
+/**
+ * Look up the user's cached HISTORY score for a repo slug (#1465).
+ *
+ * This is the relationship score from `state.repoScores` (the user's own
+ * merge outcomes, computed by `repo-score-manager.ts`) — a different number
+ * from the fresh `rubricScore` this command computes. Surfacing both in one
+ * envelope, under distinct names, is the point: agents must never quote one
+ * as the other. See docs/repo-scores.md.
+ *
+ * State keys come from parsed GitHub URLs and preserve their original case,
+ * while the user types the slug by hand — GitHub slugs are case-insensitive,
+ * so fall back to a case-insensitive scan before reporting "no history".
+ * Returns `undefined` (field omitted from output) when the user has no
+ * cached score for the repo.
+ */
+function lookupHistoryScore(repoSlug) {
+    // Best-effort by design: repo-vet ran for years without touching local
+    // state, and an unreadable state file (EACCES rethrows from loadState)
+    // must degrade to "no history", not abort the vet (#1465 review).
+    try {
+        const stateManager = getStateManager();
+        const exact = stateManager.getRepoScore(repoSlug);
+        if (exact)
+            return exact.score;
+        const lower = repoSlug.toLowerCase();
+        const match = Object.values(stateManager.getState().repoScores).find((rs) => rs.repo.toLowerCase() === lower);
+        return match?.score;
+    }
+    catch (error) {
+        warn(MODULE, `History-score lookup skipped (state unavailable): ${errorMessage(error)}`);
+        return undefined;
+    }
+}
 function summarizePRMerges(prs, windowDays, now) {
     const cutoff = now.getTime() - windowDays * DAY_MS;
     const prMergeTimesDays = [];
@@ -226,6 +259,11 @@ export async function runRepoVet(options) {
     // rubric score — the score reflects the fetched signals as-is and the
     // flag tells consumers which signal was unverified.
     const { repo: repoMeta, communityHealth, maintainerActivity, ...rest } = result;
+    // #1465: name both repo scores in one envelope. `rubricScore` is the fresh
+    // health score computed above; `historyScore` is the user's cached
+    // relationship score when one exists. Optional so the output is unchanged
+    // for repos the user has no history with (back-compat).
+    const historyScore = lookupHistoryScore(options.repo);
     return {
         repoSlug: options.repo,
         fetchedAt: now.toISOString(),
@@ -233,5 +271,6 @@ export async function runRepoVet(options) {
         communityHealth: { ...communityHealth, incomplete: communityHealthSummary.incomplete },
         maintainerActivity: { ...maintainerActivity, releasesIncomplete },
         ...rest,
+        ...(historyScore !== undefined ? { historyScore } : {}),
     };
 }

package/dist/commands/scout-bridge.d.ts

@@ -5,6 +5,32 @@
 import { type LinkedPR as ScoutLinkedPR, type OssScout, type ScoutState } from '@oss-scout/core';
 import type { LinkedPR } from '../core/linked-pr-classification.js';
 import type { CandidateLinkedPR } from '../formatters/json.js';
+/**
+ * Fraction of search slots reserved for candidates that matched neither
+ * strategy-preferred languages nor repos (#1244). Counterweight against
+ * echo-chamber bias: without it, strategy-boosted searches return more of
+ * what already merged, which merges more of the same, and the profile
+ * narrows over time. Scout clamps to [0, 1]; 0.2 is the issue's proposal.
+ *
+ * Lives here (not `search.ts`, which re-exports it) since #1464: the same
+ * ratio is baked into the `ScoutPreferences` built by {@link buildScoutState}
+ * so every scout surface shares one policy.
+ */
+export declare const SEARCH_DIVERSITY_RATIO = 0.2;
+/**
+ * Degradation signals collected while building a scout state (#1448).
+ * Callers pass an empty object and inspect it after the build — threading an
+ * out-param keeps `buildScoutState`/`createAutopilotScout` return types
+ * unchanged for the five command call sites.
+ */
+export interface ScoutBridgeDiagnostics {
+    /**
+     * Set when a configured skipped-issues file exists but could not be read.
+     * The scout state was built with an EMPTY skip list, so explicitly-skipped
+     * issues may resurface in results.
+     */
+    skipListUnavailable?: boolean;
+}
 /**
  * Convert scout 0.6.0's `LinkedPR` (separate `state` + `merged`) into the
  * shape `classifyLinkedPR` expects (`state` already folded with `merged`).
@@ -29,10 +55,17 @@ export declare function buildCandidateLinkedPR(scoutLinkedPR: ScoutLinkedPR | nu
 /**
  * Build a ScoutState from the current AgentState.
  * Maps oss-autopilot's config and state fields to oss-scout's state format.
+ *
+ * @param diagnostics - Optional collector for degradation signals (#1448);
+ *   `skipListUnavailable` is set when the skipped-issues file exists but
+ *   could not be read.
  */
-export declare function buildScoutState(): ScoutState;
+export declare function buildScoutState(diagnostics?: ScoutBridgeDiagnostics): ScoutState;
 /**
  * Create an OssScout instance backed by the current AgentState.
  * Uses 'provided' persistence so scout reads from oss-autopilot's state.
+ *
+ * @param diagnostics - Optional collector for degradation signals (#1448),
+ *   forwarded to {@link buildScoutState}.
  */
-export declare function createAutopilotScout(): Promise<OssScout>;
+export declare function createAutopilotScout(diagnostics?: ScoutBridgeDiagnostics): Promise<OssScout>;