@oss-autopilot/core 3.10.0 → 3.12.0

package/dist/core/issue-verification.js

@@ -0,0 +1,270 @@
+/**
+ * Deterministic issue verification (#1353, #1354).
+ *
+ * One GraphQL round-trip answers the two questions the issue-scout agent
+ * historically hallucinated: "is this issue actually open?" and "is it
+ * actually taken?". The query fetches the issue's `state`/`stateReason`,
+ * its assignees, every cross-referenced PR with `closingIssuesReferences`,
+ * and `viewer.login` — so "is this my PR?" is derived from the same token
+ * that fetched the data instead of a cached username.
+ *
+ * Classification is a pure function (`classifyIssueAvailability`) so the
+ * verdict rules are unit-testable without network access. The distinction
+ * that matters (#1353): a PR whose `closingIssuesReferences` includes this
+ * issue is a real claim (`closing`); a PR that merely mentions the issue in
+ * its timeline is just a mention (`cross-referenced`) and must not drive a
+ * "Taken" verdict.
+ */
+import { ValidationError } from './errors.js';
+function isSameLogin(a, b) {
+    return a !== null && a !== '' && b !== '' && a.toLowerCase() === b.toLowerCase();
+}
+/**
+ * Compute the availability verdict from fetched facts. Rules in priority
+ * order; the first match wins.
+ */
+export function classifyIssueAvailability(input) {
+    const { state, stateReason, assignees, linkedPRs, userLogin } = input;
+    if (state === 'closed') {
+        const reason = stateReason ?? 'unknown';
+        return {
+            verdict: 'closed',
+            verdictReason: reason === 'not_planned'
+                ? 'issue closed as not planned — drop it permanently'
+                : `issue closed (${reason}) — mark it done upstream`,
+        };
+    }
+    const closingPRs = linkedPRs.filter((pr) => pr.linkType === 'closing');
+    const ownOpenClaim = closingPRs.find((pr) => pr.state === 'open' && pr.isOwn);
+    if (ownOpenClaim) {
+        return {
+            verdict: 'own-open-pr',
+            verdictReason: `you already have an open PR for this issue: ${ownOpenClaim.url}`,
+        };
+    }
+    const otherOpenClaim = closingPRs.find((pr) => pr.state === 'open' && !pr.isOwn);
+    if (otherOpenClaim) {
+        return {
+            verdict: 'taken',
+            verdictReason: `open PR by ${otherOpenClaim.author ?? 'unknown author'} closes this issue: ${otherOpenClaim.url}`,
+        };
+    }
+    const otherAssignees = assignees.filter((login) => !isSameLogin(login, userLogin));
+    if (otherAssignees.length > 0) {
+        return {
+            verdict: 'taken',
+            verdictReason: `assigned to ${otherAssignees.join(', ')}`,
+        };
+    }
+    const mergedClaim = closingPRs.find((pr) => pr.state === 'merged');
+    if (mergedClaim) {
+        return {
+            verdict: 'at-risk',
+            verdictReason: `a merged PR closes this issue (${mergedClaim.url}) — likely resolved, awaiting issue close`,
+        };
+    }
+    const openMention = linkedPRs.find((pr) => pr.linkType === 'cross-referenced' && pr.state === 'open');
+    if (openMention) {
+        return {
+            verdict: 'at-risk',
+            verdictReason: `open PR ${openMention.url} cross-references this issue (mention only, not a claim) — ` +
+                'risk of being superseded by broader work',
+        };
+    }
+    // Self-assignment was filtered out above — don't claim "unassigned" then.
+    const selfAssigned = assignees.length > 0;
+    return {
+        verdict: 'available',
+        verdictReason: selfAssigned ? 'open, assigned to you, no claiming PRs' : 'open, unassigned, no claiming PRs',
+    };
+}
+// ── GraphQL fetch ──────────────────────────────────────────────────────
+const VERIFY_ISSUE_QUERY = /* GraphQL */ `
+  query VerifyIssue($owner: String!, $repo: String!, $number: Int!, $after: String) {
+    viewer {
+      login
+    }
+    repository(owner: $owner, name: $repo) {
+      issue(number: $number) {
+        number
+        title
+        url
+        state
+        stateReason
+        closedAt
+        assignees(first: 10) {
+          nodes {
+            login
+          }
+        }
+        timelineItems(itemTypes: [CROSS_REFERENCED_EVENT], first: 100, after: $after) {
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+          nodes {
+            ... on CrossReferencedEvent {
+              source {
+                ... on PullRequest {
+                  number
+                  url
+                  title
+                  state
+                  isDraft
+                  updatedAt
+                  author {
+                    login
+                  }
+                  closingIssuesReferences(first: 50) {
+                    nodes {
+                      number
+                      repository {
+                        nameWithOwner
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+/**
+ * Fetch + classify in one GraphQL round-trip.
+ *
+ * Throws `ValidationError` when the issue does not exist (or the URL points
+ * at a PR — GitHub's `issue()` resolver returns null for PR numbers).
+ * GraphQL/network/rate-limit errors propagate to the caller; nothing is
+ * swallowed into a degraded verdict.
+ */
+/** True when a GraphQL error response is purely "the repo/issue we asked for
+ * doesn't exist" — a caller-input problem, not an API failure. Requires every
+ * error to be NOT_FOUND *and* rooted at the repository/issue path: a nested
+ * NOT_FOUND (e.g. a cross-referenced source in a deleted repo) must not be
+ * misdiagnosed as "issue not found". Duck-typed so we don't import octokit's
+ * GraphqlResponseError class just for instanceof. */
+function isGraphqlNotFound(error) {
+    const errors = error?.errors;
+    if (!Array.isArray(errors) || errors.length === 0)
+        return false;
+    return errors.every((e) => {
+        if (e?.type !== 'NOT_FOUND')
+            return false;
+        const path = Array.isArray(e.path) ? e.path : [];
+        return path.length <= 2 && (path.length === 0 || (path[0] === 'repository' && (path[1] ?? 'issue') === 'issue'));
+    });
+}
+/**
+ * Hard ceiling on timeline pages (100 events each). Timeline events arrive
+ * oldest-first, so silently stopping early would drop the NEWEST events —
+ * exactly the ones most likely to be the active claiming PR. Past the cap we
+ * fail loudly instead of returning a possibly-false `available`.
+ */
+const MAX_TIMELINE_PAGES = 20;
+export async function fetchIssueVerification(octokit, params) {
+    const { owner, repo, number } = params;
+    let issue;
+    let userLogin;
+    const timelineNodes = [];
+    let after = null;
+    for (let page = 0;; page++) {
+        if (page >= MAX_TIMELINE_PAGES) {
+            throw new Error(`Issue ${owner}/${repo}#${number} has more than ${MAX_TIMELINE_PAGES * 100} cross-reference events; ` +
+                'refusing to verify on a truncated timeline. Check the issue manually.');
+        }
+        let response;
+        try {
+            response = await octokit.graphql(VERIFY_ISSUE_QUERY, {
+                owner,
+                repo,
+                number,
+                after,
+            });
+        }
+        catch (error) {
+            // GitHub reports a missing repo/issue as a NOT_FOUND GraphQL error (the
+            // client throws before our null check below can run). Surface it as the
+            // same ValidationError; everything else (rate limits, network, auth)
+            // propagates untouched.
+            if (isGraphqlNotFound(error)) {
+                throw new ValidationError(`Issue not found: ${owner}/${repo}#${number}. ` +
+                    'Check the URL — it may point at a pull request or a deleted/private issue.');
+            }
+            throw error;
+        }
+        const pageIssue = response.repository?.issue;
+        if (!pageIssue) {
+            throw new ValidationError(`Issue not found: ${owner}/${repo}#${number}. ` +
+                'Check the URL — it may point at a pull request or a deleted/private issue.');
+        }
+        issue ??= pageIssue;
+        userLogin = response.viewer.login;
+        timelineNodes.push(...pageIssue.timelineItems.nodes);
+        const pageInfo = pageIssue.timelineItems.pageInfo;
+        if (!pageInfo?.hasNextPage)
+            break;
+        after = pageInfo.endCursor;
+    }
+    // The loop above either assigns both then breaks, or throws.
+    if (!issue || userLogin === undefined) {
+        throw new Error('unreachable: timeline pagination exited without an issue');
+    }
+    const issueRepo = `${owner}/${repo}`.toLowerCase();
+    const linkedPRs = [];
+    const seenUrls = new Set();
+    for (const node of timelineNodes) {
+        const source = node?.source;
+        // CrossReferencedEvent sources can be issues too; PRs are the ones that
+        // carry a `state` from the inline fragment. Skip everything else.
+        if (!source || typeof source.number !== 'number' || !source.url || !source.state)
+            continue;
+        if (seenUrls.has(source.url))
+            continue;
+        seenUrls.add(source.url);
+        // A "closing" link must name THIS issue in THIS repo — closing references
+        // to same-numbered issues in other repos don't count. Deliberate cap:
+        // `closingIssuesReferences(first: 50)` — a PR closing 50+ issues is
+        // pathological; its claim on this one would downgrade to a mention.
+        const closesThisIssue = (source.closingIssuesReferences?.nodes ?? []).some((ref) => ref !== null && ref.number === number && ref.repository.nameWithOwner.toLowerCase() === issueRepo);
+        const author = source.author?.login ?? null;
+        linkedPRs.push({
+            number: source.number,
+            url: source.url,
+            title: source.title ?? '',
+            state: source.state.toLowerCase(),
+            isDraft: source.isDraft ?? false,
+            author,
+            isOwn: isSameLogin(author, userLogin),
+            linkType: closesThisIssue ? 'closing' : 'cross-referenced',
+            updatedAt: source.updatedAt ?? null,
+        });
+    }
+    const state = issue.state.toLowerCase();
+    const stateReason = (issue.stateReason?.toLowerCase() ?? null);
+    const assignees = issue.assignees.nodes.flatMap((n) => (n ? [n.login] : []));
+    const { verdict, verdictReason } = classifyIssueAvailability({
+        state,
+        stateReason,
+        assignees,
+        linkedPRs,
+        userLogin,
+    });
+    return {
+        url: issue.url,
+        owner,
+        repo,
+        number: issue.number,
+        title: issue.title,
+        state,
+        stateReason,
+        closedAt: issue.closedAt,
+        assignees,
+        linkedPRs,
+        verdict,
+        verdictReason,
+        userLogin,
+    };
+}

package/dist/core/paths.d.ts

@@ -25,6 +25,18 @@ export declare function getDataDir(): string;
  * Implicitly creates the data directory via {@link getDataDir} if it does not exist.
  */
 export declare function getStatePath(): string;
+/**
+ * Returns the legacy (pre-`~/.oss-autopilot`) state file path: `./data/state.json`
+ * relative to the working directory.
+ *
+ * Functions rather than module constants so tests can mock them per-file:
+ * as constants in state-persistence.ts they resolved to the one shared
+ * `packages/core/data/` during vitest, and the migration tests racing
+ * parallel workers on that real directory caused CI flakes (#1382).
+ */
+export declare function getLegacyStatePath(): string;
+/** Legacy backup directory (`./data/backups`); see {@link getLegacyStatePath}. */
+export declare function getLegacyBackupDir(): string;
 /**
  * Returns the backup directory path, creating it if it does not exist.
  *

package/dist/core/paths.js

@@ -36,6 +36,22 @@ export function getDataDir() {
 export function getStatePath() {
     return path.join(getDataDir(), 'state.json');
 }
+/**
+ * Returns the legacy (pre-`~/.oss-autopilot`) state file path: `./data/state.json`
+ * relative to the working directory.
+ *
+ * Functions rather than module constants so tests can mock them per-file:
+ * as constants in state-persistence.ts they resolved to the one shared
+ * `packages/core/data/` during vitest, and the migration tests racing
+ * parallel workers on that real directory caused CI flakes (#1382).
+ */
+export function getLegacyStatePath() {
+    return path.join(process.cwd(), 'data', 'state.json');
+}
+/** Legacy backup directory (`./data/backups`); see {@link getLegacyStatePath}. */
+export function getLegacyBackupDir() {
+    return path.join(process.cwd(), 'data', 'backups');
+}
 /**
  * Returns the backup directory path, creating it if it does not exist.
  *

package/dist/core/pr-attention.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Unified PR attention taxonomy (#1352).
+ *
+ * The headline "needs attention" number used to be computed twice — the CLI
+ * brief counted `collectActionableIssues()` output while the dashboard
+ * counted raw `status === 'needs_addressing'` — and the cases the CLI
+ * deliberately excludes (stuck CI, dormant maintainer waits) sat
+ * undifferentiated inside `waiting_on_maintainer`. This module is the single
+ * classifier both surfaces consume.
+ *
+ * Buckets (mutually exclusive, first match wins):
+ * - `needs_attention` — the contributor has a concrete code-related next
+ *   step today (`status === 'needs_addressing'`: response, changes, CI fix,
+ *   conflict, checklist). This is the headline count on BOTH surfaces.
+ * - `stuck_ci` — waiting PRs whose CI has been `pending` long past any
+ *   normal run time. A "ping / investigate" workflow, not a coding one.
+ * - `dormant_followup` — waiting PRs with `review_required` and no activity
+ *   past the follow-up threshold. A "draft a nudge" workflow.
+ * - `waiting` — everything else that's healthy to leave alone.
+ */
+import type { AttentionBucket, FetchedPR } from './types.js';
+export type { AttentionBucket } from './types.js';
+/**
+ * Days of inactivity after which a `pending` CI status reads as stuck rather
+ * than in-flight. Real CI runs finish in minutes-to-hours; multiple days of
+ * `pending` means a webhook was lost, a runner died, or a required check
+ * never started.
+ */
+export declare const STUCK_CI_THRESHOLD_DAYS = 3;
+/**
+ * Days of inactivity after which a `review_required` PR becomes a follow-up
+ * candidate. Matches the middle step of the 7/14/30 dormant-PR follow-up
+ * cadence — early enough to nudge before the PR goes fully dormant
+ * (default `dormantThresholdDays` is 30).
+ */
+export declare const DORMANT_FOLLOWUP_THRESHOLD_DAYS = 14;
+/** The minimal slice of {@link FetchedPR} the classifier reads. */
+export type AttentionInput = Pick<FetchedPR, 'status' | 'ciStatus' | 'reviewDecision' | 'daysSinceActivity'>;
+/**
+ * Classify one PR into its attention bucket. Pure — both the CLI daily path
+ * and the dashboard `/api/data` path call this, so the two surfaces cannot
+ * diverge on what a count means.
+ */
+export declare function classifyAttentionBucket(pr: AttentionInput): AttentionBucket;
+export interface AttentionSummary {
+    needsAttention: number;
+    stuckCI: number;
+    dormantFollowup: number;
+    waiting: number;
+}
+/** Count PRs per bucket — the shape both headline surfaces render from. */
+export declare function summarizeAttentionBuckets(prs: readonly AttentionInput[]): AttentionSummary;

package/dist/core/pr-attention.js

@@ -0,0 +1,76 @@
+/**
+ * Unified PR attention taxonomy (#1352).
+ *
+ * The headline "needs attention" number used to be computed twice — the CLI
+ * brief counted `collectActionableIssues()` output while the dashboard
+ * counted raw `status === 'needs_addressing'` — and the cases the CLI
+ * deliberately excludes (stuck CI, dormant maintainer waits) sat
+ * undifferentiated inside `waiting_on_maintainer`. This module is the single
+ * classifier both surfaces consume.
+ *
+ * Buckets (mutually exclusive, first match wins):
+ * - `needs_attention` — the contributor has a concrete code-related next
+ *   step today (`status === 'needs_addressing'`: response, changes, CI fix,
+ *   conflict, checklist). This is the headline count on BOTH surfaces.
+ * - `stuck_ci` — waiting PRs whose CI has been `pending` long past any
+ *   normal run time. A "ping / investigate" workflow, not a coding one.
+ * - `dormant_followup` — waiting PRs with `review_required` and no activity
+ *   past the follow-up threshold. A "draft a nudge" workflow.
+ * - `waiting` — everything else that's healthy to leave alone.
+ */
+/**
+ * Days of inactivity after which a `pending` CI status reads as stuck rather
+ * than in-flight. Real CI runs finish in minutes-to-hours; multiple days of
+ * `pending` means a webhook was lost, a runner died, or a required check
+ * never started.
+ */
+export const STUCK_CI_THRESHOLD_DAYS = 3;
+/**
+ * Days of inactivity after which a `review_required` PR becomes a follow-up
+ * candidate. Matches the middle step of the 7/14/30 dormant-PR follow-up
+ * cadence — early enough to nudge before the PR goes fully dormant
+ * (default `dormantThresholdDays` is 30).
+ */
+export const DORMANT_FOLLOWUP_THRESHOLD_DAYS = 14;
+/**
+ * Classify one PR into its attention bucket. Pure — both the CLI daily path
+ * and the dashboard `/api/data` path call this, so the two surfaces cannot
+ * diverge on what a count means.
+ */
+export function classifyAttentionBucket(pr) {
+    if (pr.status === 'needs_addressing')
+        return 'needs_attention';
+    // From here on the PR is waiting_on_maintainer — subdivide the wait.
+    if (pr.ciStatus === 'pending' && pr.daysSinceActivity >= STUCK_CI_THRESHOLD_DAYS) {
+        return 'stuck_ci';
+    }
+    if (pr.reviewDecision === 'review_required' && pr.daysSinceActivity >= DORMANT_FOLLOWUP_THRESHOLD_DAYS) {
+        return 'dormant_followup';
+    }
+    return 'waiting';
+}
+/** Count PRs per bucket — the shape both headline surfaces render from. */
+export function summarizeAttentionBuckets(prs) {
+    const summary = { needsAttention: 0, stuckCI: 0, dormantFollowup: 0, waiting: 0 };
+    for (const pr of prs) {
+        switch (classifyAttentionBucket(pr)) {
+            case 'needs_attention': {
+                summary.needsAttention++;
+                break;
+            }
+            case 'stuck_ci': {
+                summary.stuckCI++;
+                break;
+            }
+            case 'dormant_followup': {
+                summary.dormantFollowup++;
+                break;
+            }
+            case 'waiting': {
+                summary.waiting++;
+                break;
+            }
+        }
+    }
+    return summary;
+}

package/dist/core/pr-comments-fetcher.d.ts

@@ -16,6 +16,7 @@ import type { Octokit } from '@octokit/rest';
 export interface PRReviewEntry {
     author: string;
     authorAssociation: string;
+    /** `<github-content>`-fenced review body (#1372). */
     body: string;
     submittedAt: string;
 }
@@ -23,6 +24,7 @@ export interface PRReviewEntry {
 export interface PRReviewCommentEntry {
     author: string;
     authorAssociation: string;
+    /** `<github-content>`-fenced comment body (#1372). */
     body: string;
     path: string;
     createdAt: string;
@@ -31,6 +33,7 @@ export interface PRReviewCommentEntry {
 export interface PRIssueCommentEntry {
     author: string;
     authorAssociation: string;
+    /** `<github-content>`-fenced comment body (#1372). */
     body: string;
     createdAt: string;
 }
@@ -62,8 +65,13 @@ export declare function fetchPRCommentBundle(octokit: Octokit, prUrl: string, gi
  * `{ bundles, failures }` so the caller can decide whether to retry, surface
  * a partial-data banner, or proceed. Rationale: extraction quality is already
  * a partial-information problem (users contribute to many repos and many PRs),
- * so a single 404 / rate limit on one PR should not deny the host the corpus
- * from the other 4 — but the failure should still be visible (#1209 L8).
+ * so a single 404 / transient failure on one PR should not deny the host the
+ * corpus from the other 4 — but the failure should still be visible (#1209 L8).
+ *
+ * Rate-limit / auth errors are the exception: they reject the whole batch
+ * (#1391). Under throttling every remaining PR would fail the same way, so
+ * degrading to "skipped N PRs" silently masks a systemic failure the caller
+ * needs to surface (the CLI/MCP error envelope on `guidelines fetch-corpus`).
  */
 export interface PRCommentBundlesBatchResult {
     bundles: PRCommentBundle[];

package/dist/core/pr-comments-fetcher.js

@@ -1,7 +1,8 @@
 import { paginateAll } from './pagination.js';
+import { wrapUntrustedContent } from './untrusted-content.js';
 import { isBotAuthor } from './comment-utils.js';
 import { parseGitHubUrl } from './urls.js';
-import { ValidationError, errorMessage } from './errors.js';
+import { ValidationError, errorMessage, isRateLimitOrAuthError } from './errors.js';
 import { debug, warn } from './logger.js';
 const MODULE = 'pr-comments-fetcher';
 /** Default concurrency for {@link fetchPRCommentBundlesBatch}. */
@@ -60,6 +61,12 @@ export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
         return true;
     };
     const mergedAt = pr.merged_at ?? pr.closed_at ?? '';
+    // Fence every body at fetch time (#1372): the bundle's only consumer is
+    // `guidelines fetch-corpus`, whose output goes straight into the host's
+    // extract-learnings prompt — there is no human-display or string-matching
+    // consumer downstream, so fetch-time wrapping is safe here.
+    const fenceLabel = `${repoFull}#${pull_number}`;
+    const fence = (body, source, author, association) => wrapUntrustedContent(body, fenceLabel, { author, association, source });
     return {
         prUrl,
         prTitle: pr.title,
@@ -70,7 +77,7 @@ export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
             .map((r) => ({
             author: r.user?.login ?? '',
             authorAssociation: r.author_association ?? 'NONE',
-            body: r.body ?? '',
+            body: fence(r.body ?? '', 'pr-review', r.user?.login ?? '', r.author_association ?? 'NONE'),
             submittedAt: r.submitted_at ?? '',
         })),
         reviewComments: reviewComments
@@ -78,7 +85,7 @@ export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
             .map((c) => ({
             author: c.user?.login ?? '',
             authorAssociation: c.author_association ?? 'NONE',
-            body: c.body ?? '',
+            body: fence(c.body ?? '', 'pr-review-comment', c.user?.login ?? '', c.author_association ?? 'NONE'),
             path: c.path ?? '',
             createdAt: c.created_at ?? '',
         })),
@@ -87,7 +94,7 @@ export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
             .map((c) => ({
             author: c.user?.login ?? '',
             authorAssociation: c.author_association ?? 'NONE',
-            body: c.body ?? '',
+            body: fence(c.body ?? '', 'pr-issue-comment', c.user?.login ?? '', c.author_association ?? 'NONE'),
             createdAt: c.created_at ?? '',
         })),
     };
@@ -96,8 +103,11 @@ export async function fetchPRCommentBundlesBatch(octokit, prUrls, githubUsername
     const bundles = [];
     const failures = [];
     const queue = [...prUrls];
+    let aborted = false;
     async function worker() {
         while (queue.length > 0) {
+            if (aborted)
+                return;
             const url = queue.shift();
             if (!url)
                 return;
@@ -106,6 +116,14 @@ export async function fetchPRCommentBundlesBatch(octokit, prUrls, githubUsername
                 bundles.push(bundle);
             }
             catch (err) {
+                // Rate-limit / auth failures abort the batch instead of degrading to
+                // a per-PR skip — see the doc comment above (#1391). The abort flag
+                // stops sibling workers from burning more rate-limited requests on
+                // results that will be discarded when Promise.all rejects.
+                if (isRateLimitOrAuthError(err)) {
+                    aborted = true;
+                    throw err;
+                }
                 const errorMsg = errorMessage(err);
                 failures.push({ prUrl: url, error: errorMsg });
                 warn(MODULE, `Skipping ${url}: ${errorMsg}`);

package/dist/core/state-persistence.d.ts

@@ -45,16 +45,41 @@ export declare function migrateV3ToV4(rawState: Record<string, unknown>): Record
  * Leverages Zod schema defaults to produce a complete state.
  */
 export declare function createFreshState(): AgentState;
+/**
+ * Details about a recovery that happened during {@link loadState} — set when
+ * the main state file was unreadable (JSON parse error) or structurally
+ * invalid (Zod rejection) and the loader fell back to a backup or fresh state.
+ * Surfaced through StateManager.getLoadRecovery() so commands can include the
+ * event in structured output instead of only stderr warn() lines (#1371).
+ */
+export interface LoadRecoveryInfo {
+    /** Where the loaded state came from after the original file was rejected. */
+    source: 'backup' | 'fresh';
+    /** Path of the preserved `.rejected-<ts>` copy, or null if preservation failed. */
+    rejectedPath: string | null;
+    /** Short summary of why the original state file was rejected. */
+    reason: string;
+}
+/**
+ * Result of {@link loadState}: the loaded state, the file's mtime for change
+ * detection, and (only when the main file was rejected) recovery details.
+ */
+export interface LoadStateResult {
+    state: AgentState;
+    mtimeMs: number;
+    recovery?: LoadRecoveryInfo;
+}
 /**
  * Load state from file, or create initial state if none exists.
  * If the main state file is corrupted, attempts to restore from the most recent backup.
  * Performs migration from legacy ./data/ location if needed.
- * @returns Object with the loaded state and the file's mtime (for change detection).
+ * @returns Object with the loaded state, the file's mtime (for change detection),
+ *   and recovery details when the main file was rejected.
+ * @throws Error when the state file exists but cannot be read due to a
+ *   permission error (EACCES/EPERM) — that is an environment problem, not
+ *   corruption, so restore-or-fresh would mask it and risk clobbering data.
  */
-export declare function loadState(): {
-    state: AgentState;
-    mtimeMs: number;
-};
+export declare function loadState(): LoadStateResult;
 /**
  * Persist state to disk, creating a timestamped backup of the previous
  * state file first. Retains at most 10 backup files.
@@ -79,7 +104,4 @@ export declare function saveState(state: Readonly<AgentState>, expectedMtimeMs?:
  * Uses mtime comparison (single statSync call) to avoid unnecessary JSON parsing.
  * @returns The new state and mtime if reloaded, or null if no change detected.
  */
-export declare function reloadStateIfChanged(lastLoadedMtimeMs: number): {
-    state: AgentState;
-    mtimeMs: number;
-} | null;
+export declare function reloadStateIfChanged(lastLoadedMtimeMs: number): LoadStateResult | null;