@oss-autopilot/core 3.10.0 → 3.12.0

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

package/dist/commands/guidelines.js

@@ -1,6 +1,7 @@
 /**
  * Guidelines CLI commands (#867 PR 4).
  *
+ * `guidelines list`        — list repos with stored guidelines.
  * `guidelines view`        — read the per-repo guidelines file from the Gist.
  * `guidelines store`       — overwrite the per-repo guidelines file.
  * `guidelines reset`       — tombstone the file so subsequent reads return null.
@@ -41,6 +42,20 @@ export async function runGuidelinesView(options) {
         storageMode: sm.isGuidelinesAvailable() ? 'gist' : 'local-unavailable',
     };
 }
+/**
+ * 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 async function runGuidelinesList() {
+    const sm = getStateManager();
+    const repos = sm.listGuidelinesRepos();
+    return {
+        repos,
+        count: repos.length,
+        storageMode: sm.isGuidelinesAvailable() ? 'gist' : 'local-unavailable',
+    };
+}
 /**
  * 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
@@ -57,11 +72,12 @@ export async function runGuidelinesStore(options) {
     // Push to Gist — autoSave only writes the local state-cache mirror in Gist
     // mode, so without this checkpoint the change never propagates across
     // machines (#1200).
-    await maybeCheckpoint(sm, MODULE);
+    const gistSyncWarning = await maybeCheckpoint(sm, MODULE);
     return {
         repo: options.repo,
         byteSize: Buffer.byteLength(options.content, 'utf8'),
         stored: true,
+        ...(gistSyncWarning ? { gistSyncWarning } : {}),
     };
 }
 /** Tombstone the guidelines file for `repo`. */
@@ -72,12 +88,13 @@ export async function runGuidelinesReset(options) {
         throw new GuidelinesNotAvailableError();
     }
     const existed = sm.getGuidelines(options.repo) !== null;
+    let gistSyncWarning = null;
     if (existed) {
         sm.deleteGuidelines(options.repo);
         // Push to Gist — see runGuidelinesStore note (#1200).
-        await maybeCheckpoint(sm, MODULE);
+        gistSyncWarning = await maybeCheckpoint(sm, MODULE);
     }
-    return { repo: options.repo, deleted: existed };
+    return { repo: options.repo, deleted: existed, ...(gistSyncWarning ? { gistSyncWarning } : {}) };
 }
 /**
  * Fetch raw PR comment bundles for the most recent merged/closed PRs in `repo`
@@ -146,8 +163,9 @@ export async function runFetchCorpus(options) {
     // Push commentsFetchedAt stamps to Gist so other machines don't re-fetch
     // the same PRs forever. autoSave only writes the local mirror in Gist
     // mode (#1200).
+    let gistSyncWarning = null;
     if (bundles.length > 0) {
-        await maybeCheckpoint(sm, MODULE);
+        gistSyncWarning = await maybeCheckpoint(sm, MODULE);
     }
     return {
         repo: options.repo,
@@ -155,6 +173,7 @@ export async function runFetchCorpus(options) {
         prCount: bundles.length,
         skipped,
         failures,
+        ...(gistSyncWarning ? { gistSyncWarning } : {}),
     };
 }
 function clampLimit(limit) {

package/dist/commands/index.d.ts

@@ -29,6 +29,8 @@ export { runSearch, MAX_SEARCH_RESULTS } from './search.js';
 export { runFeatures, MAX_FEATURES_RESULTS } from './features.js';
 /** Vet a single GitHub issue for claimability (open, unassigned, no linked PRs, repo health). */
 export { runVet } from './vet.js';
+/** Deterministic availability check: state/stateReason + linked-PR classification (#1353, #1354). */
+export { runVerifyIssue, type VerifyIssueOptions } from './verify-issue.js';
 /** Re-vet all available issues in a curated issue list for freshness. */
 export { runVetList } from './vet-list.js';
 /** Fetch PR metadata from GitHub (informational; nothing is persisted). */
@@ -61,6 +63,8 @@ export { runInit } from './init.js';
 export { runSetup } from './setup.js';
 /** Check whether setup has been completed. */
 export { runCheckSetup } from './setup.js';
+/** List repos with stored guidelines (empty in local mode). */
+export { runGuidelinesList } from './guidelines.js';
 /** Read the guidelines file for a repo. */
 export { runGuidelinesView } from './guidelines.js';
 /** Persist a guidelines file for a repo (overwrites on subsequent calls). */
@@ -96,7 +100,7 @@ export type { VetOutput, CommentsOutput, PostOutput, ClaimOutput, VetListOutput,
 export type { ConfigOutput, DetectFormattersOutput, ParseIssueListOutput, ParsedIssueItem, CheckIntegrationOutput, LocalReposOutput, } from '../formatters/json.js';
 export type { ShelveOutput, UnshelveOutput } from './shelve.js';
 export type { MoveOutput, MoveTarget } from './move.js';
-export type { GuidelinesViewOutput, GuidelinesStoreOutput, GuidelinesResetOutput, FetchCorpusOutput, } from './guidelines.js';
+export type { GuidelinesListOutput, GuidelinesViewOutput, GuidelinesStoreOutput, GuidelinesResetOutput, FetchCorpusOutput, } from './guidelines.js';
 export type { DismissOutput, UndismissOutput } from './dismiss.js';
 export type { InitOutput } from './init.js';
 export type { ConfigSetOutput, ConfigCommandOutput } from './config.js';

package/dist/commands/index.js

@@ -30,6 +30,8 @@ export { runSearch, MAX_SEARCH_RESULTS } from './search.js';
 export { runFeatures, MAX_FEATURES_RESULTS } from './features.js';
 /** Vet a single GitHub issue for claimability (open, unassigned, no linked PRs, repo health). */
 export { runVet } from './vet.js';
+/** Deterministic availability check: state/stateReason + linked-PR classification (#1353, #1354). */
+export { runVerifyIssue } from './verify-issue.js';
 /** Re-vet all available issues in a curated issue list for freshness. */
 export { runVetList } from './vet-list.js';
 // ── PR Management ───────────────────────────────────────────────────────────
@@ -66,6 +68,8 @@ export { runSetup } from './setup.js';
 /** Check whether setup has been completed. */
 export { runCheckSetup } from './setup.js';
 // ── Per-Repo Guidelines (#867) ──────────────────────────────────────────────
+/** List repos with stored guidelines (empty in local mode). */
+export { runGuidelinesList } from './guidelines.js';
 /** Read the guidelines file for a repo. */
 export { runGuidelinesView } from './guidelines.js';
 /** Persist a guidelines file for a repo (overwrites on subsequent calls). */

package/dist/commands/list-move-tier.d.ts

@@ -6,7 +6,9 @@
  * issue-list markdown file. Replaces the model-driven prose rewrite that
  * lived in /oss-search with a deterministic file manipulation.
  *
- * Idempotent: re-running with the same target tier is a no-op.
+ * Idempotent: re-running with the same target tier is a no-op. A URL that is
+ * not in the list at all is an error (#1355) — the command does not create
+ * entries, and callers must add the entry before moving it.
  *
  * No GitHub calls — pure read/transform/write of a local file.
  */
@@ -17,7 +19,8 @@ export interface ListMoveTierOptions {
     listPath: string;
 }
 export interface ListMoveTierOutput {
-    /** Whether anything moved (false when the URL isn't in the list, or it was already in the target tier). */
+    /** Whether anything moved (false only when the entry was already in the
+     * target tier — a URL missing from the list entirely throws instead, #1355). */
     moved: boolean;
     /** Fully-resolved file path that was inspected. */
     filePath: string;
@@ -25,7 +28,8 @@ export interface ListMoveTierOutput {
     url: string;
     /** The target tier (always normalized to one of pursue/maybe/skip). */
     toTier: Tier;
-    /** The tier the issue was moved out of, if it had one. Absent when not found or already in target. */
+    /** The tier the issue was moved out of, if it had one. Also populated on the
+     * already-in-target no-op; absent when the source block sat under no tier header. */
     fromTier?: string;
     /** Number of matching entries moved. Should normally be 1; >1 means the list contained duplicate entries (all moved). */
     count: number;
@@ -36,11 +40,15 @@ export interface ListMoveTierOutput {
  * Pure transform — accepts the file content and returns the rewritten content
  * plus a summary of what changed. Exported for unit testing.
  */
+/** Discriminates the two `moved: false` outcomes of {@link moveIssueToTier}. */
+export type MoveNoOpReason = 'not-found' | 'already-in-target';
 export declare function moveIssueToTier(content: string, issueUrl: string, targetTier: Tier): {
     content: string;
     moved: boolean;
     fromTier?: string;
     count: number;
     reason?: string;
+    /** Set only when `moved` is false — why nothing changed. */
+    reasonCode?: MoveNoOpReason;
 };
 export declare function runListMoveTier(options: ListMoveTierOptions): Promise<ListMoveTierOutput>;

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

@@ -6,13 +6,15 @@
  * issue-list markdown file. Replaces the model-driven prose rewrite that
  * lived in /oss-search with a deterministic file manipulation.
  *
- * Idempotent: re-running with the same target tier is a no-op.
+ * Idempotent: re-running with the same target tier is a no-op. A URL that is
+ * not in the list at all is an error (#1355) — the command does not create
+ * entries, and callers must add the entry before moving it.
  *
  * No GitHub calls — pure read/transform/write of a local file.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { errorMessage } from '../core/errors.js';
+import { errorMessage, ValidationError } from '../core/errors.js';
 const TIER_HEADERS = {
     pursue: '## Pursue',
     maybe: '## Maybe',
@@ -82,17 +84,19 @@ function findTierInsertionIndex(lines, headerIndex) {
     }
     return lines.length;
 }
-/**
- * Pure transform — accepts the file content and returns the rewritten content
- * plus a summary of what changed. Exported for unit testing.
- */
 export function moveIssueToTier(content, issueUrl, targetTier) {
     // Preserve the trailing newline if present so we don't accidentally strip it.
     const hadTrailingNewline = content.endsWith('\n');
     const lines = (hadTrailingNewline ? content.slice(0, -1) : content).split('\n');
     const blocks = findIssueBlocks(lines, issueUrl);
     if (blocks.length === 0) {
-        return { content, moved: false, count: 0, reason: 'issue URL not found in the list' };
+        return {
+            content,
+            moved: false,
+            count: 0,
+            reason: 'issue URL not found in the list',
+            reasonCode: 'not-found',
+        };
     }
     const targetHeader = TIER_HEADERS[targetTier];
     // If every match is already in the target tier, no-op (idempotent).
@@ -103,6 +107,7 @@ export function moveIssueToTier(content, issueUrl, targetTier) {
             fromTier: blocks[0].tier,
             count: blocks.length,
             reason: 'already in target tier',
+            reasonCode: 'already-in-target',
         };
     }
     // Extract the blocks (highest start index first so earlier indices stay
@@ -172,6 +177,12 @@ export async function runListMoveTier(options) {
         throw new Error(`Failed to read file: ${errorMessage(error)}`, { cause: error });
     }
     const result = moveIssueToTier(content, options.issueUrl, options.tier);
+    // #1355: a missing entry is a caller error, not a quiet success. Idempotent
+    // re-runs (already-in-target) still resolve normally.
+    if (result.reasonCode === 'not-found') {
+        throw new ValidationError(`Issue URL not found in the list: ${options.issueUrl} (${filePath}). ` +
+            'Add the entry to the list first, then re-run list-move-tier.');
+    }
     if (result.moved) {
         try {
             fs.writeFileSync(filePath, result.content, 'utf8');

package/dist/commands/move.d.ts

@@ -9,6 +9,8 @@ export interface MoveOutput {
     target: MoveTarget;
     /** Human-readable description of what happened. */
     description: string;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 /**
  * Move a PR between states: attention, waiting, shelved, or auto (computed).

package/dist/commands/move.js

@@ -7,6 +7,10 @@ import { ValidationError } from '../core/errors.js';
 import { PR_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
 const MODULE = 'move';
 export const VALID_TARGETS = ['attention', 'waiting', 'shelved', 'auto'];
+/** Attach the checkpoint warning only when present, keeping the key off the wire on clean runs (#1370). */
+function withGistSyncWarning(output, gistSyncWarning) {
+    return gistSyncWarning ? { ...output, gistSyncWarning } : output;
+}
 /**
  * Move a PR between states: attention, waiting, shelved, or auto (computed).
  *
@@ -36,32 +40,32 @@ export async function runMove(options) {
                 stateManager.setStatusOverride(options.prUrl, status, lastActivityAt);
                 stateManager.unshelvePR(options.prUrl);
             });
-            await maybeCheckpoint(stateManager, MODULE);
-            return { url: options.prUrl, target, description: `Moved to ${label}` };
+            const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+            return withGistSyncWarning({ url: options.prUrl, target, description: `Moved to ${label}` }, gistSyncWarning);
         }
         case 'shelved': {
             stateManager.batch(() => {
                 stateManager.shelvePR(options.prUrl);
                 stateManager.clearStatusOverride(options.prUrl);
             });
-            await maybeCheckpoint(stateManager, MODULE);
-            return {
+            const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+            return withGistSyncWarning({
                 url: options.prUrl,
                 target,
                 description: 'Shelved — excluded from capacity and actionable items',
-            };
+            }, gistSyncWarning);
         }
         case 'auto': {
             stateManager.batch(() => {
                 stateManager.clearStatusOverride(options.prUrl);
                 stateManager.unshelvePR(options.prUrl);
             });
-            await maybeCheckpoint(stateManager, MODULE);
-            return {
+            const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+            return withGistSyncWarning({
                 url: options.prUrl,
                 target,
                 description: 'Reset to computed status',
-            };
+            }, gistSyncWarning);
         }
         default: {
             const _exhaustive = target;

package/dist/commands/repo-vet.js

@@ -11,7 +11,7 @@
  * no state mutation, runs against a public `owner/repo` slug.
  */
 import { getOctokit, requireGitHubToken } from '../core/index.js';
-import { errorMessage } from '../core/errors.js';
+import { errorMessage, getHttpStatusCode, isRateLimitOrAuthError } from '../core/errors.js';
 import { warn } from '../core/logger.js';
 import { validateRepoIdentifier } from './validation.js';
 import { computeRepoVet } from '../core/repo-vet.js';
@@ -160,13 +160,30 @@ export async function runRepoVet(options) {
     const token = requireGitHubToken();
     const octokit = getOctokit(token);
     const now = new Date();
+    // Tracks the release-list analogue of communityHealth's `incomplete`:
+    // set when the listReleases call failed for a reason that does NOT
+    // prove absence (5xx, network), so the caller can distinguish "repo
+    // has no releases" from "couldn't check releases" (#1373).
+    let releasesIncomplete = false;
     const [repoMetaResp, closedPRsResp, commitsResp, releasesResp, communityHealthSummary] = await Promise.all([
         octokit.repos.get({ owner, repo }),
         octokit.pulls.list({ owner, repo, state: 'closed', sort: 'updated', direction: 'desc', per_page: 100 }),
         octokit.repos.listCommits({ owner, repo, per_page: 100 }),
-        octokit.repos
-            .listReleases({ owner, repo, per_page: 1 })
-            .catch(() => ({ data: [] })),
+        octokit.repos.listReleases({ owner, repo, per_page: 1 }).catch((err) => {
+            // Rate-limit / auth failures must abort the run, same as every
+            // sibling fetch — under throttling, a blanket catch here would
+            // silently report "no releases" for the whole vet batch (#1373).
+            if (isRateLimitOrAuthError(err))
+                throw err;
+            const empty = { data: [] };
+            // 404 is a definitive "nothing there" — genuine absence, not a gap.
+            if (getHttpStatusCode(err) === 404)
+                return empty;
+            // 5xx / network: absence is unproven. Degrade gracefully but flag it.
+            releasesIncomplete = true;
+            warn(MODULE, `release listing for ${owner}/${repo} failed: ${errorMessage(err)} — release-recency signal is incomplete`);
+            return empty;
+        }),
         checkCommunityHealth(octokit, owner, repo),
     ]);
     const prs = closedPRsResp.data.map((p) => ({
@@ -201,15 +218,20 @@ export async function runRepoVet(options) {
     const result = computeRepoVet(input);
     // The core function names its metadata object `repo`. Rename to `repoMeta`
     // at the CLI boundary so the top-level slug doesn't collide with it.
-    // Also overlay the community-health `incomplete` flag the wrapper
-    // tracks (the core type doesn't carry it because computeRepoVet is
-    // pure — only the wrapper makes the API calls that can fail mid-probe).
-    const { repo: repoMeta, communityHealth, ...rest } = result;
+    // Also overlay the community-health `incomplete` and the
+    // `releasesIncomplete` flags the wrapper tracks (the core type doesn't
+    // carry them because computeRepoVet is pure — only the wrapper makes
+    // the API calls that can fail mid-probe). Like communityHealth's
+    // incomplete flag, releasesIncomplete deliberately does NOT alter the
+    // 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;
     return {
         repoSlug: options.repo,
         fetchedAt: now.toISOString(),
         repoMeta,
         communityHealth: { ...communityHealth, incomplete: communityHealthSummary.incomplete },
+        maintainerActivity: { ...maintainerActivity, releasesIncomplete },
         ...rest,
     };
 }

package/dist/commands/search.js

@@ -2,8 +2,8 @@
  * Search command
  * Searches for new issues to work on via @oss-scout/core
  */
-import { buildCandidateLinkedPR, createAutopilotScout } from './scout-bridge.js';
-import { getStateManager } from '../core/index.js';
+import { adaptScoutLinkedPR, buildCandidateLinkedPR, createAutopilotScout } from './scout-bridge.js';
+import { classifyLinkedPR, getStateManager } from '../core/index.js';
 import { gradeFromCandidate } from '../core/issue-grading.js';
 import { computeStrategy } from '../core/strategy.js';
 import { debug, warn } from '../core/logger.js';
@@ -64,8 +64,21 @@ export async function runSearch(options) {
         preferLanguages,
         preferRepos,
     });
+    // #1354: never surface issues the user already has an open PR for. Uses
+    // scout's structured linked-PR metadata when present; candidates without it
+    // pass through (the issue-scout agent re-checks via verify-issue anyway).
+    // Empty login means "can't prove any PR is the user's own" — nothing hidden.
+    const userLogin = stateManager.getState().config?.githubUsername ?? '';
+    if (userLogin === '') {
+        warn(MODULE, 'githubUsername not configured — the own-PR filter (#1354) cannot run; hiddenOwnPRCount will be 0');
+    }
+    const visibleCandidates = result.candidates.filter((c) => classifyLinkedPR({ linkedPR: adaptScoutLinkedPR(c.vettingResult?.linkedPR), userLogin }) !== 'user_open');
+    const hiddenOwnPRCount = result.candidates.length - visibleCandidates.length;
+    if (hiddenOwnPRCount > 0) {
+        debug(MODULE, `Hid ${hiddenOwnPRCount} candidate(s) with the user's own open PR (#1354)`);
+    }
     const searchOutput = {
-        candidates: result.candidates.map((c) => {
+        candidates: visibleCandidates.map((c) => {
             const repoScoreRecord = stateManager.getRepoScore(c.issue.repo);
             // Scout's `search` does not emit per-candidate projectHealth (only
             // `vetIssue` does). Pass a sentinel `checkFailed: true` so the grader
@@ -119,6 +132,7 @@ export async function runSearch(options) {
         }),
         excludedRepos: result.excludedRepos,
         aiPolicyBlocklist: result.aiPolicyBlocklist,
+        hiddenOwnPRCount,
     };
     if (result.rateLimitWarning) {
         searchOutput.rateLimitWarning = result.rateLimitWarning;

package/dist/commands/shelve.d.ts

@@ -11,10 +11,14 @@ import { PR_URL_PATTERN } from './validation.js';
 export interface ShelveOutput {
     shelved: boolean;
     url: string;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 export interface UnshelveOutput {
     unshelved: boolean;
     url: string;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 export { PR_URL_PATTERN };
 /**

package/dist/commands/shelve.js

@@ -29,8 +29,8 @@ export async function runShelve(options) {
         added = stateManager.shelvePR(options.prUrl);
         stateManager.clearStatusOverride(options.prUrl);
     });
-    await maybeCheckpoint(stateManager, MODULE);
-    return { shelved: added, url: options.prUrl };
+    const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+    return { shelved: added, url: options.prUrl, ...(gistSyncWarning ? { gistSyncWarning } : {}) };
 }
 /**
  * Unshelve a PR, restoring it to the daily digest.
@@ -49,6 +49,6 @@ export async function runUnshelve(options) {
         removed = stateManager.unshelvePR(options.prUrl);
         stateManager.clearStatusOverride(options.prUrl);
     });
-    await maybeCheckpoint(stateManager, MODULE);
-    return { unshelved: removed, url: options.prUrl };
+    const gistSyncWarning = await maybeCheckpoint(stateManager, MODULE);
+    return { unshelved: removed, url: options.prUrl, ...(gistSyncWarning ? { gistSyncWarning } : {}) };
 }

package/dist/commands/verify-issue.d.ts

@@ -0,0 +1,20 @@
+/**
+ * verify-issue command (#1353, #1354).
+ *
+ * Deterministic availability check for one GitHub issue: state/stateReason,
+ * assignees, and linked PRs classified as `closing` vs `cross-referenced`,
+ * with the authenticated user's own PRs flagged. One GraphQL round-trip,
+ * no scoring, no scout heuristics — this is the ground truth the
+ * issue-scout agent consumes BEFORE any judgment-based vetting.
+ */
+import { type IssueVerification } from '../core/index.js';
+export interface VerifyIssueOptions {
+    issueUrl: string;
+}
+/**
+ * Verify a GitHub issue's real availability.
+ *
+ * @throws {ValidationError} If the URL is not a valid GitHub issue URL or
+ *   the issue does not exist.
+ */
+export declare function runVerifyIssue(options: VerifyIssueOptions): Promise<IssueVerification>;

package/dist/commands/verify-issue.js

@@ -0,0 +1,32 @@
+/**
+ * verify-issue command (#1353, #1354).
+ *
+ * Deterministic availability check for one GitHub issue: state/stateReason,
+ * assignees, and linked PRs classified as `closing` vs `cross-referenced`,
+ * with the authenticated user's own PRs flagged. One GraphQL round-trip,
+ * no scoring, no scout heuristics — this is the ground truth the
+ * issue-scout agent consumes BEFORE any judgment-based vetting.
+ */
+import { fetchIssueVerification, getOctokit, parseGitHubUrl, requireGitHubToken, } from '../core/index.js';
+import { ValidationError } from '../core/errors.js';
+import { ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
+/**
+ * Verify a GitHub issue's real availability.
+ *
+ * @throws {ValidationError} If the URL is not a valid GitHub issue URL or
+ *   the issue does not exist.
+ */
+export async function runVerifyIssue(options) {
+    validateUrl(options.issueUrl);
+    validateGitHubUrl(options.issueUrl, ISSUE_URL_PATTERN, 'issue');
+    const parsed = parseGitHubUrl(options.issueUrl);
+    if (!parsed || parsed.type !== 'issues') {
+        throw new ValidationError(`Not a parseable GitHub issue URL: ${options.issueUrl}`);
+    }
+    const octokit = getOctokit(requireGitHubToken());
+    return fetchIssueVerification(octokit, {
+        owner: parsed.owner,
+        repo: parsed.repo,
+        number: parsed.number,
+    });
+}