@oss-autopilot/core 3.13.4 → 3.14.1

package/dist/commands/scout-bridge.js

@@ -4,7 +4,20 @@
  */
 import { createScout } from '@oss-scout/core';
 import { getStateManager, isLinkedPRStalled, requireGitHubToken } from '../core/index.js';
-import { loadSkippedIssues } from './skip-file-parser.js';
+import { computeStrategy } from '../core/strategy.js';
+import { loadSkippedIssuesDetailed } from './skip-file-parser.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 const SEARCH_DIVERSITY_RATIO = 0.2;
 /**
  * Convert scout 0.6.0's `LinkedPR` (separate `state` + `merged`) into the
  * shape `classifyLinkedPR` expects (`state` already folded with `merged`).
@@ -56,10 +69,30 @@ export function buildCandidateLinkedPR(scoutLinkedPR) {
 /**
  * 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 function buildScoutState() {
+export function buildScoutState(diagnostics) {
     const state = getStateManager().getState();
     const { config } = state;
+    // Read failure (not absence) of the skip file means scout will see an empty
+    // skip list and may resurface explicitly-skipped issues — flag it so the
+    // search envelope can carry the signal instead of only stderr (#1448).
+    const skippedIssuesLoad = loadSkippedIssuesDetailed(config.skippedIssuesPath);
+    if (skippedIssuesLoad.readError !== undefined && diagnostics) {
+        diagnostics.skipListUnavailable = true;
+    }
+    // Strategy-derived personalization (#1464). `computeStrategy` returns null
+    // below the merged-PR floor — empty lists then read as "no bias" on scout's
+    // side. Baking the bias into the preferences (rather than only per-call
+    // search options, #1244) makes every scout surface share it: `search()`
+    // falls back to these when no per-call override is passed, and `features()`
+    // exposes no per-call bias knobs at all (scout 1.1.0 accepts only
+    // count/anchorThreshold/splitRatio/broad), so preferences are the only
+    // channel by which bias can reach the features path.
+    const strategy = computeStrategy(state);
     return {
         version: 1,
         preferences: {
@@ -90,15 +123,31 @@ export function buildScoutState() {
             // `--split-ratio` flags for overrides.
             featuresAnchorThreshold: 3,
             featuresSplitRatio: 0.6,
-            // Personalization-bias prefs, likewise required on the inferred type
-            // (scout #1244 / #168). Autopilot doesn't surface these as settings yet,
-            // so we pass scout's documented "no bias" defaults.
-            preferLanguages: [],
-            preferRepos: [],
-            diversityRatio: 0,
-            avoidRepos: [],
-            boostIssueTypes: [],
+            // Personalization-bias prefs (scout #1244 / #168 / #1464).
+            // preferLanguages/preferRepos mirror the strategy derivation the search
+            // command uses per-call; avoidRepos/boostIssueTypes are user settings
+            // (config-registry keys); diversityRatio matches the search policy.
+            preferLanguages: strategy?.recommendations.languages ?? [],
+            preferRepos: strategy?.recommendations.repos ?? [],
+            diversityRatio: SEARCH_DIVERSITY_RATIO,
+            avoidRepos: config.avoidRepos ?? [],
+            boostIssueTypes: config.boostIssueTypes ?? [],
         },
+        // CONTRACT (#1458): repoScores is passed BY REFERENCE, not copied. Scout's
+        // updateRepoScore mutates entries of this shared object in place, so scout
+        // calls that touch scores (e.g. search's hasActiveMaintainers feedback,
+        // scout #167) write straight into the in-memory AgentState. Those writes
+        // reach disk only if a later StateManager mutation triggers a save —
+        // scout's own checkpoint() persists nothing under persistence:'provided'.
+        // Nothing may RELY on this alias for persistence: daily's former Phase 3.5
+        // did, and was deleted in #1458 (its record* calls were also dedup no-ops
+        // against the ledger Phase 3 had just written; see
+        // scout-bridge.repo-scores.test.ts for the pinning tests). Also note scout
+        // recalculates `score` with its own formula (linear merge bonus, no
+        // recency term), which differs from autopilot's repo-score-manager
+        // formula; daily Phase 2 recomputes every repo it touches with the
+        // autopilot formula each run, so the persisted history scores reflect
+        // autopilot's model.
         repoScores: state.repoScores,
         // Scout #117 added tombstones (deletion records for gist merge). Autopilot
         // synthesizes a fresh ScoutState per operation and tracks no deletions, so
@@ -124,19 +173,22 @@ export function buildScoutState() {
             openedAt: pr.createdAt,
         })),
         savedResults: [],
-        skippedIssues: loadSkippedIssues(config.skippedIssuesPath),
+        skippedIssues: skippedIssuesLoad.issues,
         lastRunAt: state.lastRunAt,
     };
 }
 /**
  * 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 async function createAutopilotScout() {
+export async function createAutopilotScout(diagnostics) {
     const token = requireGitHubToken();
     return createScout({
         githubToken: token,
         persistence: 'provided',
-        initialState: buildScoutState(),
+        initialState: buildScoutState(diagnostics),
     });
 }

package/dist/commands/search.d.ts

@@ -11,13 +11,11 @@ export { type SearchOutput } from '../formatters/json.js';
  */
 export declare const MAX_SEARCH_RESULTS = 100;
 /**
- * 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.
+ * Diversity-counterweight ratio (#1244). Moved to `scout-bridge.ts` in #1464
+ * (it is now also baked into the bridge-built `ScoutPreferences`); re-exported
+ * here so existing importers keep working.
  */
-export declare const SEARCH_DIVERSITY_RATIO = 0.2;
+export { SEARCH_DIVERSITY_RATIO } from './scout-bridge.js';
 interface SearchOptions {
     maxResults: number;
 }

package/dist/commands/search.js

@@ -2,7 +2,7 @@
  * Search command
  * Searches for new issues to work on via @oss-scout/core
  */
-import { adaptScoutLinkedPR, buildCandidateLinkedPR, createAutopilotScout } from './scout-bridge.js';
+import { adaptScoutLinkedPR, buildCandidateLinkedPR, createAutopilotScout, SEARCH_DIVERSITY_RATIO, } from './scout-bridge.js';
 import { classifyLinkedPR, getStateManager } from '../core/index.js';
 import { gradeFromCandidate } from '../core/issue-grading.js';
 import { computeStrategy } from '../core/strategy.js';
@@ -15,13 +15,11 @@ const MODULE = 'search';
  */
 export const MAX_SEARCH_RESULTS = 100;
 /**
- * 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.
+ * Diversity-counterweight ratio (#1244). Moved to `scout-bridge.ts` in #1464
+ * (it is now also baked into the bridge-built `ScoutPreferences`); re-exported
+ * here so existing importers keep working.
  */
-export const SEARCH_DIVERSITY_RATIO = 0.2;
+export { SEARCH_DIVERSITY_RATIO } from './scout-bridge.js';
 /**
  * Search GitHub for contributable issues using multi-phase discovery.
  *
@@ -53,25 +51,66 @@ function sanitizeViabilityScore(raw) {
     }
     return raw;
 }
+/**
+ * Read a non-negative integer scout-delay override from an env var.
+ *
+ * Scout spaces its multi-phase `/search/issues` calls with an inter-phase
+ * delay (default 30s) and a broad-phase delay (default 90s) to stay under
+ * GitHub's secondary rate limit (see `buildScoutState`). Those delays make a
+ * single `search` invocation take ~100s, which is fine in normal use but makes
+ * the live-API e2e suite (`search.e2e.test.ts`, run only in the nightly
+ * workflow — see #1452) impractically slow. These env vars let that suite
+ * collapse the delays so the test completes in a realistic CI window.
+ *
+ * Returns `undefined` when the var is unset/empty or not a parseable
+ * non-negative integer, so scout falls back to its preference value and
+ * production behavior is unchanged. Only the live test/nightly run sets them.
+ */
+function readScoutDelayOverride(envVar) {
+    const raw = process.env[envVar];
+    if (raw === undefined || raw === '') {
+        return undefined;
+    }
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        warn(MODULE, `Ignoring invalid ${envVar}="${raw}" (expected a non-negative integer); using scout's default delay`);
+        return undefined;
+    }
+    return parsed;
+}
 export async function runSearch(options) {
-    const scout = await createAutopilotScout();
+    // Collect bridge-level degradation signals (#1448): an unreadable skip file
+    // means scout searched with an empty skip list, so explicitly-skipped
+    // issues may resurface — the envelope must say so, not just stderr.
+    const bridgeDiagnostics = {};
+    const scout = await createAutopilotScout(bridgeDiagnostics);
     const stateManager = getStateManager();
     // Derive personalization from local history (#1244). `computeStrategy`
     // returns null below the merged-PR floor — in that case we pass nothing
-    // and scout's sort behaves exactly as before. Once strategy data is
-    // available, scout boosts language/repo matches into a separate sort
-    // tier (still no filtering).
+    // and scout falls back to the bridge-built preferences, which derive the
+    // same values from the same state (#1464), so the sort is identical either
+    // way. The explicit per-call pass is kept for self-documentation. Once
+    // strategy data is available, scout boosts language/repo matches into a
+    // separate sort tier (still no filtering). avoidRepos/boostIssueTypes are
+    // not passed per-call: scout reads them from the bridge-built preferences.
     const strategy = computeStrategy(stateManager.getState());
     const preferLanguages = strategy?.recommendations.languages ?? undefined;
     const preferRepos = strategy?.recommendations.repos ?? undefined;
     if (preferLanguages?.length || preferRepos?.length) {
         debug(MODULE, `Applying strategy bias to search: preferLanguages=${JSON.stringify(preferLanguages ?? [])}, preferRepos=${JSON.stringify(preferRepos ?? [])}`);
     }
+    // Live-API test/nightly affordance (#1452): collapse scout's inter-phase
+    // delays so the e2e suite finishes in a realistic window. Unset in normal
+    // use → undefined → scout falls back to the 30s/90s preference defaults.
+    const interPhaseDelayMs = readScoutDelayOverride('OSS_AUTOPILOT_SCOUT_INTER_PHASE_DELAY_MS');
+    const broadPhaseDelayMs = readScoutDelayOverride('OSS_AUTOPILOT_SCOUT_BROAD_PHASE_DELAY_MS');
     const result = await scout.search({
         maxResults: options.maxResults,
         preferLanguages,
         preferRepos,
         diversityRatio: SEARCH_DIVERSITY_RATIO,
+        ...(interPhaseDelayMs !== undefined ? { interPhaseDelayMs } : {}),
+        ...(broadPhaseDelayMs !== undefined ? { broadPhaseDelayMs } : {}),
     });
     // #1354: never surface issues the user already has an open PR for. Uses
     // scout's structured linked-PR metadata when present; candidates without it
@@ -95,6 +134,11 @@ export async function runSearch(options) {
             // the autopilot-tracked repoScore. Candidates without a repoScore
             // receive 'F' — that's an honest signal for "we haven't seen this repo
             // before" rather than a fabricated score.
+            //
+            // Note (#1465): repoScore here is the cached HISTORY score (the user's
+            // own merge outcomes — docs/repo-scores.md §History score), so this
+            // grade reflects history only; `vet` later re-grades the same issue
+            // with freshly fetched repo health and can legitimately disagree.
             const grade = gradeFromCandidate({
                 repo: c.issue.repo,
                 projectHealth: {
@@ -156,5 +200,8 @@ export async function runSearch(options) {
     if (result.rateLimitWarning) {
         searchOutput.rateLimitWarning = result.rateLimitWarning;
     }
+    if (bridgeDiagnostics.skipListUnavailable) {
+        searchOutput.skipListUnavailable = true;
+    }
     return searchOutput;
 }

package/dist/commands/setup.d.ts

@@ -11,6 +11,8 @@ export interface SetupSetOutput {
     success: true;
     settings: Record<string, string>;
     warnings?: string[];
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1440). */
+    gistSyncWarning?: string;
 }
 export interface SetupCompleteOutput {
     setupComplete: true;

package/dist/commands/setup.js

@@ -2,10 +2,11 @@
  * Setup command
  * Interactive setup / configuration
  */
-import { getStateManager, DEFAULT_CONFIG, formatUnknownKeyError, getSetupKeys } from '../core/index.js';
+import { getStateManager, DEFAULT_CONFIG, formatUnknownKeyError, getSetupKeys, maybeCheckpoint, } from '../core/index.js';
 import { ValidationError } from '../core/errors.js';
 import { validateGitHubUsername } from './validation.js';
 import { PROJECT_CATEGORIES, ISSUE_SCOPES, DIFF_TOOLS, } from '../core/types.js';
+const MODULE = 'setup';
 /** Parse and validate a positive integer setting value. */
 function parsePositiveInt(value, settingName) {
     const parsed = Number(value);
@@ -168,6 +169,50 @@ export async function runSetup(options) {
                         results[key] = valid.length > 0 ? valid.join(', ') : '(empty)';
                         break;
                     }
+                    case 'avoidRepos': {
+                        // Same owner/repo validation as aiPolicyBlocklist: skip (and warn
+                        // about) malformed entries instead of failing the whole set.
+                        const entries = value
+                            .split(',')
+                            .map((r) => r.trim())
+                            .filter(Boolean);
+                        const valid = [];
+                        const invalid = [];
+                        for (const entry of entries) {
+                            const normalized = entry.replace(/\s+/g, '');
+                            if (/^[\w.-]+\/[\w.-]+$/.test(normalized)) {
+                                valid.push(normalized);
+                            }
+                            else {
+                                invalid.push(entry);
+                            }
+                        }
+                        if (invalid.length > 0) {
+                            warnings.push(`Warning: Skipping invalid entries (expected "owner/repo" format): ${invalid.join(', ')}`);
+                        }
+                        if (valid.length === 0 && entries.length > 0) {
+                            warnings.push('Warning: All entries were invalid. avoidRepos not updated.');
+                            results[key] = '(all entries invalid)';
+                            break;
+                        }
+                        const dedupedRepos = [...new Set(valid)];
+                        stateManager.updateConfig({ avoidRepos: dedupedRepos });
+                        results[key] = dedupedRepos.length > 0 ? dedupedRepos.join(', ') : '(empty)';
+                        break;
+                    }
+                    case 'boostIssueTypes': {
+                        // Free-form issue labels (scout matches them case-insensitively);
+                        // an empty value clears the list.
+                        const types = [
+                            ...new Set(value
+                                .split(',')
+                                .map((t) => t.trim())
+                                .filter(Boolean)),
+                        ];
+                        stateManager.updateConfig({ boostIssueTypes: types });
+                        results[key] = types.length > 0 ? types.join(', ') : '(empty)';
+                        break;
+                    }
                     case 'projectCategories': {
                         const categories = value
                             .split(',')
@@ -276,7 +321,16 @@ export async function runSetup(options) {
                 }
             }
         });
-        return { success: true, settings: results, warnings: warnings.length > 0 ? warnings : undefined };
+        // Push the settings 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 {
+            success: true,
+            settings: results,
+            warnings: warnings.length > 0 ? warnings : undefined,
+            ...(gistSyncWarning ? { gistSyncWarning } : {}),
+        };
     }
     // Show setup status
     if (config.setupComplete && !options.reset) {

package/dist/commands/skip-file-parser.d.ts

@@ -15,11 +15,34 @@ import type { SkippedIssue } from '@oss-scout/core';
  * pass through unchanged.
  */
 export declare function parseSkippedIssuesContent(content: string): SkippedIssue[];
+/** Result of {@link loadSkippedIssuesDetailed}: parsed entries plus read-failure signal (#1448). */
+export interface SkippedIssuesLoadResult {
+    issues: SkippedIssue[];
+    /**
+     * Set when the file exists but could not be read (`issues` is `[]` in that
+     * case). Distinguishes "no skips configured" from "skip list unavailable" —
+     * without it, a read failure silently resurfaces explicitly-skipped issues
+     * in search results. Absent when the path is unset, the file does not
+     * exist, or the read succeeded.
+     */
+    readError?: string;
+}
+/**
+ * Read the skipped-issues file from disk and parse it, surfacing read
+ * failures to the caller (#1448).
+ * Returns `{ issues: [] }` (no `readError`) when `path` is undefined/empty or
+ * the file does not exist; `{ issues: [], readError }` when the read throws
+ * (a warning is also logged).
+ */
+export declare function loadSkippedIssuesDetailed(path: string | undefined): SkippedIssuesLoadResult;
 /**
  * Read the skipped-issues file from disk and parse it.
  * Returns `[]` when:
  *   - `path` is undefined or empty,
  *   - the file does not exist,
  *   - the file cannot be read (a warning is logged).
+ *
+ * Callers that need to distinguish "unreadable" from "no skips" should use
+ * {@link loadSkippedIssuesDetailed} instead.
  */
 export declare function loadSkippedIssues(path: string | undefined): SkippedIssue[];

package/dist/commands/skip-file-parser.js

@@ -69,24 +69,37 @@ export function parseSkippedIssuesContent(content) {
     return results;
 }
 /**
- * Read the skipped-issues file from disk and parse it.
- * Returns `[]` when:
- *   - `path` is undefined or empty,
- *   - the file does not exist,
- *   - the file cannot be read (a warning is logged).
+ * Read the skipped-issues file from disk and parse it, surfacing read
+ * failures to the caller (#1448).
+ * Returns `{ issues: [] }` (no `readError`) when `path` is undefined/empty or
+ * the file does not exist; `{ issues: [], readError }` when the read throws
+ * (a warning is also logged).
  */
-export function loadSkippedIssues(path) {
+export function loadSkippedIssuesDetailed(path) {
     if (!path)
-        return [];
+        return { issues: [] };
     if (!fs.existsSync(path))
-        return [];
+        return { issues: [] };
     let content;
     try {
         content = fs.readFileSync(path, 'utf8');
     }
     catch (err) {
         warn('skip-file-parser', `Failed to read skipped-issues file at ${path}: ${errorMessage(err)}`);
-        return [];
+        return { issues: [], readError: errorMessage(err) };
     }
-    return parseSkippedIssuesContent(content);
+    return { issues: parseSkippedIssuesContent(content) };
+}
+/**
+ * Read the skipped-issues file from disk and parse it.
+ * Returns `[]` when:
+ *   - `path` is undefined or empty,
+ *   - the file does not exist,
+ *   - the file cannot be read (a warning is logged).
+ *
+ * Callers that need to distinguish "unreadable" from "no skips" should use
+ * {@link loadSkippedIssuesDetailed} instead.
+ */
+export function loadSkippedIssues(path) {
+    return loadSkippedIssuesDetailed(path).issues;
 }

package/dist/commands/startup.d.ts

@@ -7,12 +7,7 @@
  * `node cli.bundle.cjs startup --json` call, reducing UI noise in Claude Code.
  */
 import { type StartupOutput, type IssueListInfo } from '../formatters/json.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 declare function parseIssueListPathFromConfig(configContent: string): string | undefined;
+export { parseIssueListPathFromConfig } from './locate-issue-list.js';
 /**
  * Count available and completed items in an issue list file.
  * Available items exclude any vetting status that moves an item out of the

package/dist/commands/startup.js

@@ -16,19 +16,11 @@ import { executeDailyCheck } from './daily.js';
 import { launchDashboardServer } from './dashboard-lifecycle.js';
 import { recordBrowserOpened } from './dashboard-process.js';
 import { parseIssueList } from './parse-list.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;
-}
+import { detectIssueListPath } from './locate-issue-list.js';
+// Path detection moved to locate-issue-list.ts (#1463) so the daily
+// merge-loop can use it without an import cycle through this module.
+// Re-exported here for back-compat with existing consumers/tests.
+export { parseIssueListPathFromConfig } from './locate-issue-list.js';
 /**
  * Count available and completed items in an issue list file.
  * Available items exclude any vetting status that moves an item out of the
@@ -45,60 +37,27 @@ export function countIssueListItems(content) {
  * @returns Issue list info with path and item counts, or undefined if not found
  */
 export function detectIssueList() {
-    let issueListPath = '';
-    let source = 'auto-detected';
-    // 1. Check state.json config (primary)
-    try {
-        const stateManager = getStateManager();
-        const configuredPath = stateManager.getState().config.issueListPath;
-        if (configuredPath && fs.existsSync(configuredPath)) {
-            issueListPath = 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)
-    if (!issueListPath) {
-        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)) {
-                    issueListPath = configuredPath;
-                    source = 'configured';
-                }
-            }
-            catch (error) {
-                console.error('[STARTUP] Failed to read config:', errorMessage(error));
-            }
-        }
-    }
-    // 3. Probe known paths
-    if (!issueListPath) {
-        const probes = ['open-source/potential-issue-list.md', 'oss/issue-list.md', 'issues.md'];
-        for (const probe of probes) {
-            if (fs.existsSync(probe)) {
-                issueListPath = probe;
-                source = 'auto-detected';
-                break;
-            }
-        }
-    }
-    if (!issueListPath)
+    // Steps 1-3 (state config → legacy config.md → known-path probes) live in
+    // locate-issue-list.ts (#1463), shared with the daily merge-loop.
+    const located = detectIssueListPath();
+    if (!located)
         return undefined;
+    const issueListPath = located.path;
+    const source = located.source;
     // 4. Count available/completed items
     let availableCount = 0;
     let completedCount = 0;
+    let readError;
     try {
         const content = fs.readFileSync(issueListPath, 'utf8');
         ({ availableCount, completedCount } = countIssueListItems(content));
     }
     catch (error) {
-        console.error(`[STARTUP] Failed to read issue list at ${issueListPath}:`, errorMessage(error));
+        // Surface the failure in the envelope (#1448): a 0/0 count from an
+        // unreadable list is indistinguishable from a genuinely empty list, and
+        // an agent seeing 0 available may trigger a redundant fresh search.
+        readError = errorMessage(error);
+        console.error(`[STARTUP] Failed to read issue list at ${issueListPath}:`, readError);
     }
     // 5. Detect skipped issues file
     let skippedIssuesPath;
@@ -145,7 +104,14 @@ export function detectIssueList() {
             }
         }
     }
-    return { path: issueListPath, source, availableCount, completedCount, skippedIssuesPath };
+    return {
+        path: issueListPath,
+        source,
+        availableCount,
+        completedCount,
+        skippedIssuesPath,
+        ...(readError !== undefined ? { readError } : {}),
+    };
 }
 /**
  * Open a URL in the default system browser.

package/dist/commands/track.d.ts

@@ -7,8 +7,8 @@
  * metadata from GitHub and returns it; useful for inspecting a specific
  * PR's shape without waiting for the next `daily` run. Nothing is persisted.
  *
- * The `runUntrack` v1→v2 stub was removed in v4 (#1133). Use `shelve`/
- * `unshelve` to hide a PR from the daily digest.
+ * The `runUntrack` v1→v2 stub was removed in v4 (#1133). Use `move`
+ * (target `shelved`/`auto`) to hide/restore a PR in the daily digest.
  */
 import type { TrackOutput } from '../formatters/json.js';
 /**

package/dist/commands/track.js

@@ -7,8 +7,8 @@
  * metadata from GitHub and returns it; useful for inspecting a specific
  * PR's shape without waiting for the next `daily` run. Nothing is persisted.
  *
- * The `runUntrack` v1→v2 stub was removed in v4 (#1133). Use `shelve`/
- * `unshelve` to hide a PR from the daily digest.
+ * The `runUntrack` v1→v2 stub was removed in v4 (#1133). Use `move`
+ * (target `shelved`/`auto`) to hide/restore a PR in the daily digest.
  */
 import { getOctokit, requireGitHubToken } from '../core/index.js';
 import { ValidationError } from '../core/errors.js';

package/dist/commands/vet-list.d.ts

@@ -3,6 +3,7 @@
  * Re-vets all available issues in a curated issue list file via @oss-scout/core.
  */
 import { type VetListOutput, type VetOutput, type VetListItemStatus } from '../formatters/json.js';
+import { type IssueAvailabilityVerdict } from '../core/index.js';
 interface VetListOptions {
     issueListPath?: string;
     concurrency?: number;
@@ -35,12 +36,11 @@ export declare function extractSkipReason(candidate: unknown): ScoutSkipReason |
  */
 export declare function classifyListStatus(vetResult: VetOutput, skipReason?: ScoutSkipReason): VetListItemStatus;
 /**
- * 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 declare function listStatusFromVerdict(verdict: IssueAvailabilityVerdict): VetListItemStatus;
 export declare function runVetList(options?: VetListOptions): Promise<VetListOutput>;
 export {};