@oss-scout/core 0.11.0 → 1.1.0

package/dist/core/roadmap.js

@@ -10,9 +10,7 @@
  * Auth (401) and rate-limit errors propagate, matching the rest of the
  * codebase's error strategy. Other errors degrade gracefully (warn + empty).
  */
-import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
-import { warn } from "./logger.js";
-const MODULE = "roadmap";
+import { probeRepoFile } from "./probe-repo-file.js";
 /** TTL for roadmap fetch results (1 hour). */
 const CACHE_TTL_MS = 60 * 60 * 1000;
 /** Paths probed in priority order. First success wins. */
@@ -97,26 +95,32 @@ export async function fetchRoadmapIssueRefs(octokit, owner, repo) {
     if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
         return cached.refs;
     }
+    // Concurrent feature vets of issues from one repo share a probe (#124)
+    const inflight = roadmapInflight.get(cacheKey);
+    if (inflight)
+        return inflight;
+    const promise = fetchRoadmapIssueRefsUncached(octokit, owner, repo, cacheKey);
+    roadmapInflight.set(cacheKey, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        roadmapInflight.delete(cacheKey);
+    }
+}
+const roadmapInflight = new Map();
+async function fetchRoadmapIssueRefsUncached(octokit, owner, repo, cacheKey) {
     for (const path of ROADMAP_PATHS) {
-        try {
-            const { data } = await octokit.repos.getContent({ owner, repo, path });
-            if (!("content" in data))
-                continue;
-            const content = Buffer.from(data.content, "base64").toString("utf-8");
-            const refs = parseRoadmapIssueRefs(content, owner, repo);
-            roadmapCache.set(cacheKey, { refs, fetchedAt: Date.now() });
-            pruneCache();
-            return refs;
-        }
-        catch (err) {
-            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-                throw err;
-            const status = getHttpStatusCode(err);
-            if (status === 404)
-                continue; // path missing — try next
-            warn(MODULE, `Unexpected error fetching ${path} from ${owner}/${repo}: ${errorMessage(err)}`);
-            // Fall through and try next path.
-        }
+        // probeRepoFile rethrows 401/rate-limit, treats 404 and non-content
+        // payloads as a null text, and warns on 5xx — all of which we degrade past
+        // by trying the next path.
+        const { text } = await probeRepoFile(octokit, owner, repo, path);
+        if (!text)
+            continue;
+        const refs = parseRoadmapIssueRefs(text, owner, repo);
+        roadmapCache.set(cacheKey, { refs, fetchedAt: Date.now() });
+        pruneCache();
+        return refs;
     }
     // No roadmap found (or all probes errored softly). Cache the empty result
     // so we don't re-probe every run.

package/dist/core/schemas.d.ts

@@ -7,9 +7,6 @@
 import { z } from "zod";
 export declare const IssueStatusSchema: z.ZodEnum<{
     candidate: "candidate";
-    claimed: "claimed";
-    in_progress: "in_progress";
-    pr_submitted: "pr_submitted";
 }>;
 export declare const ProjectCategorySchema: z.ZodEnum<{
     nonprofit: "nonprofit";
@@ -37,7 +34,7 @@ export declare const RepoSignalsSchema: z.ZodObject<{
     hasActiveMaintainers: z.ZodBoolean;
     isResponsive: z.ZodBoolean;
     hasHostileComments: z.ZodBoolean;
-}, z.core.$strip>;
+}, z.core.$loose>;
 export declare const RepoScoreSchema: z.ZodObject<{
     repo: z.ZodString;
     score: z.ZodNumber;
@@ -50,25 +47,25 @@ export declare const RepoScoreSchema: z.ZodObject<{
         hasActiveMaintainers: z.ZodBoolean;
         isResponsive: z.ZodBoolean;
         hasHostileComments: z.ZodBoolean;
-    }, z.core.$strip>;
+    }, z.core.$loose>;
     stargazersCount: z.ZodOptional<z.ZodNumber>;
     language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, z.core.$strip>;
+}, z.core.$loose>;
 export declare const StoredMergedPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     mergedAt: z.ZodString;
-}, z.core.$strip>;
+}, z.core.$loose>;
 export declare const StoredClosedPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     closedAt: z.ZodString;
-}, z.core.$strip>;
+}, z.core.$loose>;
 export declare const StoredOpenPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     openedAt: z.ZodString;
-}, z.core.$strip>;
+}, z.core.$loose>;
 export declare const ContributionGuidelinesSchema: z.ZodObject<{
     branchNamingConvention: z.ZodOptional<z.ZodString>;
     commitMessageFormat: z.ZodOptional<z.ZodString>;
@@ -142,9 +139,6 @@ export declare const TrackedIssueSchema: z.ZodObject<{
     title: z.ZodString;
     status: z.ZodEnum<{
         candidate: "candidate";
-        claimed: "claimed";
-        in_progress: "in_progress";
-        pr_submitted: "pr_submitted";
     }>;
     labels: z.ZodArray<z.ZodString>;
     createdAt: z.ZodString;
@@ -195,7 +189,7 @@ export declare const SkippedIssueSchema: z.ZodObject<{
     number: z.ZodNumber;
     title: z.ZodString;
     skippedAt: z.ZodString;
-}, z.core.$strip>;
+}, z.core.$loose>;
 export declare const HorizonSchema: z.ZodEnum<{
     "quick-win": "quick-win";
     "bigger-bet": "bigger-bet";
@@ -212,7 +206,11 @@ export declare const SavedCandidateSchema: z.ZodObject<{
         needs_review: "needs_review";
     }>;
     viabilityScore: z.ZodNumber;
-    searchPriority: z.ZodString;
+    searchPriority: z.ZodCatch<z.ZodEnum<{
+        normal: "normal";
+        starred: "starred";
+        merged_pr: "merged_pr";
+    }>>;
     firstSeenAt: z.ZodString;
     lastSeenAt: z.ZodString;
     lastScore: z.ZodNumber;
@@ -220,7 +218,18 @@ export declare const SavedCandidateSchema: z.ZodObject<{
         "quick-win": "quick-win";
         "bigger-bet": "bigger-bet";
     }>>;
-}, z.core.$strip>;
+    /**
+     * Availability status recorded by the previous `vet-list` run, so the next
+     * run can report transitions ("was available, now claimed") instead of
+     * re-diffing full snapshots (#165). "error" is never stored.
+     */
+    lastStatus: z.ZodOptional<z.ZodEnum<{
+        closed: "closed";
+        still_available: "still_available";
+        claimed: "claimed";
+        has_pr: "has_pr";
+    }>>;
+}, z.core.$loose>;
 export declare const PersistenceModeSchema: z.ZodEnum<{
     local: "local";
     gist: "gist";
@@ -261,13 +270,50 @@ export declare const ScoutPreferencesSchema: z.ZodObject<{
         broad: "broad";
         maintained: "maintained";
     }>>>;
+    /**
+     * Persisted personalization defaults (#168). The `--prefer-languages`,
+     * `--prefer-repos`, and `--diversity-ratio` search flags override these when
+     * passed, so a stored preference removes the need to retype the boost every
+     * search. Empty / 0 disables the corresponding signal (same as the flags).
+     */
+    preferLanguages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    preferRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    diversityRatio: z.ZodDefault<z.ZodNumber>;
+    avoidRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    boostIssueTypes: z.ZodDefault<z.ZodArray<z.ZodString>>;
     broadPhaseDelayMs: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Skip the expensive broad phase once this many candidates were found by
+     * the cheaper phases. Clamped at runtime to maxResults - 1 so it stays
+     * satisfiable; 0 disables skipping entirely.
+     */
     skipBroadWhenSufficientResults: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Optional Ollama model id used for SLM pre-triage during vetting
+     * (oss-autopilot#1122). Empty disables the feature. Recommended values:
+     * `gemma4:e4b` (default for capable hardware) or `gemma4:e2b` /
+     * `qwen3:1.7b` for low-RAM machines.
+     */
     slmTriageModel: z.ZodDefault<z.ZodString>;
+    /**
+     * Override the Ollama HTTP host. Defaults to `http://127.0.0.1:11434`
+     * when empty. Useful when Ollama runs on a different machine on the
+     * local network.
+     */
     slmTriageHost: z.ZodDefault<z.ZodString>;
+    /**
+     * Minimum merged-PR count for a repo to qualify as an anchor in
+     * `scout features` (#98). Lowering surfaces more anchors at the cost
+     * of weaker prior engagement signal.
+     */
     featuresAnchorThreshold: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Quick-wins / bigger-bets split ratio for `scout features` (#99).
+     * 0.6 means 60% quick wins, 40% bigger bets when both pools are
+     * abundant. Deficits redirect to the other bucket.
+     */
     featuresSplitRatio: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
+}, z.core.$loose>;
 export declare const ScoutStateSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     preferences: z.ZodDefault<z.ZodObject<{
@@ -306,13 +352,50 @@ export declare const ScoutStateSchema: z.ZodObject<{
             broad: "broad";
             maintained: "maintained";
         }>>>;
+        /**
+         * Persisted personalization defaults (#168). The `--prefer-languages`,
+         * `--prefer-repos`, and `--diversity-ratio` search flags override these when
+         * passed, so a stored preference removes the need to retype the boost every
+         * search. Empty / 0 disables the corresponding signal (same as the flags).
+         */
+        preferLanguages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        preferRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        diversityRatio: z.ZodDefault<z.ZodNumber>;
+        avoidRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        boostIssueTypes: z.ZodDefault<z.ZodArray<z.ZodString>>;
         broadPhaseDelayMs: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Skip the expensive broad phase once this many candidates were found by
+         * the cheaper phases. Clamped at runtime to maxResults - 1 so it stays
+         * satisfiable; 0 disables skipping entirely.
+         */
         skipBroadWhenSufficientResults: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Optional Ollama model id used for SLM pre-triage during vetting
+         * (oss-autopilot#1122). Empty disables the feature. Recommended values:
+         * `gemma4:e4b` (default for capable hardware) or `gemma4:e2b` /
+         * `qwen3:1.7b` for low-RAM machines.
+         */
         slmTriageModel: z.ZodDefault<z.ZodString>;
+        /**
+         * Override the Ollama HTTP host. Defaults to `http://127.0.0.1:11434`
+         * when empty. Useful when Ollama runs on a different machine on the
+         * local network.
+         */
         slmTriageHost: z.ZodDefault<z.ZodString>;
+        /**
+         * Minimum merged-PR count for a repo to qualify as an anchor in
+         * `scout features` (#98). Lowering surfaces more anchors at the cost
+         * of weaker prior engagement signal.
+         */
         featuresAnchorThreshold: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Quick-wins / bigger-bets split ratio for `scout features` (#99).
+         * 0.6 means 60% quick wins, 40% bigger bets when both pools are
+         * abundant. Deficits redirect to the other bucket.
+         */
         featuresSplitRatio: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>>;
+    }, z.core.$loose>>;
     repoScores: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         repo: z.ZodString;
         score: z.ZodNumber;
@@ -325,27 +408,27 @@ export declare const ScoutStateSchema: z.ZodObject<{
             hasActiveMaintainers: z.ZodBoolean;
             isResponsive: z.ZodBoolean;
             hasHostileComments: z.ZodBoolean;
-        }, z.core.$strip>;
+        }, z.core.$loose>;
         stargazersCount: z.ZodOptional<z.ZodNumber>;
         language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, z.core.$strip>>>;
+    }, z.core.$loose>>>;
     starredRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
     starredReposLastFetched: z.ZodOptional<z.ZodString>;
     mergedPRs: z.ZodDefault<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         mergedAt: z.ZodString;
-    }, z.core.$strip>>>;
+    }, z.core.$loose>>>;
     closedPRs: z.ZodDefault<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         closedAt: z.ZodString;
-    }, z.core.$strip>>>;
+    }, z.core.$loose>>>;
     openPRs: z.ZodDefault<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         openedAt: z.ZodString;
-    }, z.core.$strip>>>;
+    }, z.core.$loose>>>;
     savedResults: z.ZodDefault<z.ZodArray<z.ZodObject<{
         issueUrl: z.ZodString;
         repo: z.ZodString;
@@ -358,7 +441,11 @@ export declare const ScoutStateSchema: z.ZodObject<{
             needs_review: "needs_review";
         }>;
         viabilityScore: z.ZodNumber;
-        searchPriority: z.ZodString;
+        searchPriority: z.ZodCatch<z.ZodEnum<{
+            normal: "normal";
+            starred: "starred";
+            merged_pr: "merged_pr";
+        }>>;
         firstSeenAt: z.ZodString;
         lastSeenAt: z.ZodString;
         lastScore: z.ZodNumber;
@@ -366,18 +453,53 @@ export declare const ScoutStateSchema: z.ZodObject<{
             "quick-win": "quick-win";
             "bigger-bet": "bigger-bet";
         }>>;
-    }, z.core.$strip>>>;
+        /**
+         * Availability status recorded by the previous `vet-list` run, so the next
+         * run can report transitions ("was available, now claimed") instead of
+         * re-diffing full snapshots (#165). "error" is never stored.
+         */
+        lastStatus: z.ZodOptional<z.ZodEnum<{
+            closed: "closed";
+            still_available: "still_available";
+            claimed: "claimed";
+            has_pr: "has_pr";
+        }>>;
+    }, z.core.$loose>>>;
     skippedIssues: z.ZodDefault<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
         repo: z.ZodString;
         number: z.ZodNumber;
         title: z.ZodString;
         skippedAt: z.ZodString;
-    }, z.core.$strip>>>;
+    }, z.core.$loose>>>;
+    /**
+     * Deletion tombstones (#117). Without these, the gist union-merge would
+     * resurrect any saved result or skipped issue removed on one machine the
+     * next time it merged against another machine's copy that still had it.
+     * A tombstone suppresses an item across a merge until the item is
+     * re-added with a newer timestamp. Pruned after 90 days.
+     */
+    tombstones: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        removedAt: z.ZodString;
+    }, z.core.$loose>>>;
+    /**
+     * When preferences were last changed (#117). The gist merge previously
+     * always took the remote preferences, silently reverting a local edit;
+     * the side with the fresher timestamp now wins.
+     */
+    preferencesUpdatedAt: z.ZodOptional<z.ZodString>;
     lastSearchAt: z.ZodOptional<z.ZodString>;
     lastRunAt: z.ZodDefault<z.ZodString>;
     gistId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+}, z.core.$loose>;
+/**
+ * Single entry point for parsing persisted state (local file, gist, gist
+ * cache). Version migrations belong here: when a version 2 ships, transform
+ * older raw shapes before validation so no load site ever sees unmigrated
+ * data. Unknown keys round-trip via the loose schemas above.
+ */
+export declare function parseScoutState(raw: unknown): ScoutState;
 export type ProjectCategory = z.infer<typeof ProjectCategorySchema>;
 export type IssueScope = z.infer<typeof IssueScopeSchema>;
 export type SearchStrategy = z.infer<typeof SearchStrategySchema>;

package/dist/core/schemas.js

@@ -6,12 +6,12 @@
  */
 import { z } from "zod";
 // ── Enum schemas ────────────────────────────────────────────────────
-export const IssueStatusSchema = z.enum([
-    "candidate",
-    "claimed",
-    "in_progress",
-    "pr_submitted",
-]);
+// Only "candidate" is ever assigned (TrackedIssue.status is hardcoded in
+// issue-vetting). The "claimed" / "in_progress" / "pr_submitted" values were
+// vestigial from the autopilot extraction and never set; TrackedIssue is an
+// in-memory type, not part of persisted ScoutState, so trimming them carries
+// no migration risk (#155).
+export const IssueStatusSchema = z.enum(["candidate"]);
 export const ProjectCategorySchema = z.enum([
     "nonprofit",
     "devtools",
@@ -40,12 +40,15 @@ export const CONCRETE_STRATEGIES = [
     "maintained",
 ];
 // ── Leaf schemas ────────────────────────────────────────────────────
-export const RepoSignalsSchema = z.object({
+export const RepoSignalsSchema = z.looseObject({
     hasActiveMaintainers: z.boolean(),
+    // Retained for backward compatibility but no longer affects the repo score
+    // (#167): nothing computes it, and hasActiveMaintainers is the live activity
+    // proxy. Kept so old persisted state and the search JSON output still parse.
     isResponsive: z.boolean(),
     hasHostileComments: z.boolean(),
 });
-export const RepoScoreSchema = z.object({
+export const RepoScoreSchema = z.looseObject({
     repo: z.string(),
     score: z.number(),
     mergedPRCount: z.number(),
@@ -57,17 +60,17 @@ export const RepoScoreSchema = z.object({
     stargazersCount: z.number().optional(),
     language: z.string().nullable().optional(),
 });
-export const StoredMergedPRSchema = z.object({
+export const StoredMergedPRSchema = z.looseObject({
     url: z.string(),
     title: z.string(),
     mergedAt: z.string(),
 });
-export const StoredClosedPRSchema = z.object({
+export const StoredClosedPRSchema = z.looseObject({
     url: z.string(),
     title: z.string(),
     closedAt: z.string(),
 });
-export const StoredOpenPRSchema = z.object({
+export const StoredOpenPRSchema = z.looseObject({
     url: z.string(),
     title: z.string(),
     openedAt: z.string(),
@@ -129,7 +132,7 @@ export const TrackedIssueSchema = z.object({
     vettingResult: IssueVettingResultSchema.optional(),
 });
 // ── Skipped issue schema ──────────────────────────────────────────
-export const SkippedIssueSchema = z.object({
+export const SkippedIssueSchema = z.looseObject({
     url: z.string(),
     repo: z.string(),
     number: z.number(),
@@ -138,7 +141,7 @@ export const SkippedIssueSchema = z.object({
 });
 // ── Saved candidate schema ─────────────────────────────────────────
 export const HorizonSchema = z.enum(["quick-win", "bigger-bet"]);
-export const SavedCandidateSchema = z.object({
+export const SavedCandidateSchema = z.looseObject({
     issueUrl: z.string(),
     repo: z.string(),
     number: z.number(),
@@ -146,15 +149,26 @@ export const SavedCandidateSchema = z.object({
     labels: z.array(z.string()),
     recommendation: z.enum(["approve", "skip", "needs_review"]),
     viabilityScore: z.number(),
-    searchPriority: z.string(),
+    // Tightened from z.string() to the actual 3-value union (#158). `.catch`
+    // keeps old persisted state loadable: any unrecognized stored value (or a
+    // future-version value) decodes to "normal" instead of failing the parse.
+    searchPriority: z.enum(["merged_pr", "starred", "normal"]).catch("normal"),
     firstSeenAt: z.string(),
     lastSeenAt: z.string(),
     lastScore: z.number(),
     horizon: HorizonSchema.optional(),
+    /**
+     * Availability status recorded by the previous `vet-list` run, so the next
+     * run can report transitions ("was available, now claimed") instead of
+     * re-diffing full snapshots (#165). "error" is never stored.
+     */
+    lastStatus: z
+        .enum(["still_available", "claimed", "closed", "has_pr"])
+        .optional(),
 });
 // ── Scout preferences schema ────────────────────────────────────────
 export const PersistenceModeSchema = z.enum(["local", "gist"]);
-export const ScoutPreferencesSchema = z.object({
+export const ScoutPreferencesSchema = z.looseObject({
     githubUsername: z.string().default(""),
     languages: z.array(z.string()).default(["any"]),
     labels: z.array(z.string()).default(["good first issue", "help wanted"]),
@@ -170,8 +184,28 @@ export const ScoutPreferencesSchema = z.object({
     interPhaseDelayMs: z.number().min(0).max(120000).default(30000),
     persistence: PersistenceModeSchema.default("local"),
     defaultStrategy: z.array(SearchStrategySchema).optional(),
+    /**
+     * Persisted personalization defaults (#168). The `--prefer-languages`,
+     * `--prefer-repos`, and `--diversity-ratio` search flags override these when
+     * passed, so a stored preference removes the need to retype the boost every
+     * search. Empty / 0 disables the corresponding signal (same as the flags).
+     */
+    preferLanguages: z.array(z.string()).default([]),
+    preferRepos: z.array(z.string()).default([]),
+    diversityRatio: z.number().min(0).max(1).default(0),
+    // Soft penalty (milder than the hard excludeRepos filter): candidates in
+    // these `owner/repo` slugs are pushed down the ranking but not removed (#168).
+    avoidRepos: z.array(z.string()).default([]),
+    // Soft boost for candidates whose issue labels match one of these types,
+    // case-insensitive (e.g. "bug", "good first issue") (#168).
+    boostIssueTypes: z.array(z.string()).default([]),
     broadPhaseDelayMs: z.number().min(0).max(300000).default(90000),
-    skipBroadWhenSufficientResults: z.number().int().min(0).max(100).default(15),
+    /**
+     * Skip the expensive broad phase once this many candidates were found by
+     * the cheaper phases. Clamped at runtime to maxResults - 1 so it stays
+     * satisfiable; 0 disables skipping entirely.
+     */
+    skipBroadWhenSufficientResults: z.number().int().min(0).max(100).default(8),
     /**
      * Optional Ollama model id used for SLM pre-triage during vetting
      * (oss-autopilot#1122). Empty disables the feature. Recommended values:
@@ -199,7 +233,10 @@ export const ScoutPreferencesSchema = z.object({
     featuresSplitRatio: z.number().min(0).max(1).default(0.6),
 });
 // ── Root state schema ───────────────────────────────────────────────
-export const ScoutStateSchema = z.object({
+// Persisted schemas are loose (unknown keys round-trip) so an older binary
+// loading state written by a newer one cannot silently strip and then
+// persist away the newer fields (#137).
+export const ScoutStateSchema = z.looseObject({
     version: z.literal(1),
     preferences: ScoutPreferencesSchema.default(() => ScoutPreferencesSchema.parse({})),
     repoScores: z.record(z.string(), RepoScoreSchema).default({}),
@@ -210,7 +247,36 @@ export const ScoutStateSchema = z.object({
     openPRs: z.array(StoredOpenPRSchema).default([]),
     savedResults: z.array(SavedCandidateSchema).default([]),
     skippedIssues: z.array(SkippedIssueSchema).default([]),
+    /**
+     * Deletion tombstones (#117). Without these, the gist union-merge would
+     * resurrect any saved result or skipped issue removed on one machine the
+     * next time it merged against another machine's copy that still had it.
+     * A tombstone suppresses an item across a merge until the item is
+     * re-added with a newer timestamp. Pruned after 90 days.
+     */
+    tombstones: z
+        .array(z.looseObject({
+        url: z.string(),
+        removedAt: z.string(),
+    }))
+        .default([]),
+    /**
+     * When preferences were last changed (#117). The gist merge previously
+     * always took the remote preferences, silently reverting a local edit;
+     * the side with the fresher timestamp now wins.
+     */
+    preferencesUpdatedAt: z.string().optional(),
     lastSearchAt: z.string().optional(),
     lastRunAt: z.string().default(() => new Date().toISOString()),
     gistId: z.string().optional(),
 });
+/**
+ * Single entry point for parsing persisted state (local file, gist, gist
+ * cache). Version migrations belong here: when a version 2 ships, transform
+ * older raw shapes before validation so no load site ever sees unmigrated
+ * data. Unknown keys round-trip via the loose schemas above.
+ */
+export function parseScoutState(raw) {
+    // No migrations yet; version 1 is current.
+    return ScoutStateSchema.parse(raw);
+}

package/dist/core/search-budget.d.ts

@@ -20,6 +20,8 @@ export declare class SearchBudgetTracker {
     private resetAt;
     /** Total calls recorded since init (for diagnostics). */
     private totalCalls;
+    /** Calls made since the last known quota reset (external accounting). */
+    private callsSinceReset;
     /**
      * Initialize with pre-flight rate limit data from GitHub.
      */
@@ -28,6 +30,13 @@ export declare class SearchBudgetTracker {
      * Record that a Search API call was just made.
      */
     recordCall(): void;
+    /**
+     * Replenish the external budget once GitHub's quota window has reset.
+     * Without this, the pre-flight remaining acted as a never-replenishing
+     * run-lifetime total, throttling long multi-phase runs to ~1 call/min
+     * even though GitHub fully resets every 60 seconds (#119).
+     */
+    private refreshExternalBudget;
     /**
      * Remove timestamps older than the sliding window.
      */

package/dist/core/search-budget.js

@@ -30,6 +30,8 @@ export class SearchBudgetTracker {
     resetAt = 0;
     /** Total calls recorded since init (for diagnostics). */
     totalCalls = 0;
+    /** Calls made since the last known quota reset (external accounting). */
+    callsSinceReset = 0;
     /**
      * Initialize with pre-flight rate limit data from GitHub.
      */
@@ -38,6 +40,7 @@ export class SearchBudgetTracker {
         this.resetAt = new Date(resetAt).getTime();
         this.callTimestamps = [];
         this.totalCalls = 0;
+        this.callsSinceReset = 0;
         debug(MODULE, `Initialized: ${remaining} remaining, resets at ${new Date(this.resetAt).toLocaleTimeString()}`);
     }
     /**
@@ -46,8 +49,28 @@ export class SearchBudgetTracker {
     recordCall() {
         this.callTimestamps.push(Date.now());
         this.totalCalls++;
+        this.callsSinceReset++;
         this.pruneOldTimestamps();
     }
+    /**
+     * Replenish the external budget once GitHub's quota window has reset.
+     * Without this, the pre-flight remaining acted as a never-replenishing
+     * run-lifetime total, throttling long multi-phase runs to ~1 call/min
+     * even though GitHub fully resets every 60 seconds (#119).
+     */
+    refreshExternalBudget() {
+        if (this.resetAt <= 0)
+            return;
+        const now = Date.now();
+        if (now < this.resetAt)
+            return;
+        this.knownRemaining = SEARCH_RATE_LIMIT;
+        this.callsSinceReset = 0;
+        while (this.resetAt <= now) {
+            this.resetAt += SEARCH_WINDOW_MS;
+        }
+        debug(MODULE, "Quota window reset; external search budget replenished");
+    }
     /**
      * Remove timestamps older than the sliding window.
      */
@@ -69,9 +92,11 @@ export class SearchBudgetTracker {
      * and the pre-flight remaining quota from GitHub.
      */
     getEffectiveBudget() {
-        // Use the stricter of: local window limit vs. pre-flight remaining minus calls made
+        this.refreshExternalBudget();
+        // Use the stricter of: local window limit vs. known remaining quota
+        // minus calls made since the last reset
         const localBudget = EFFECTIVE_BUDGET - this.callTimestamps.length;
-        const externalBudget = this.knownRemaining - this.totalCalls;
+        const externalBudget = this.knownRemaining - this.callsSinceReset;
         return Math.max(0, Math.min(localBudget, externalBudget));
     }
     /**
@@ -97,7 +122,15 @@ export class SearchBudgetTracker {
             // Wait until the oldest call in the window ages out
             const oldestInWindow = this.callTimestamps[0];
             if (!oldestInWindow) {
-                return; // No calls in window — budget exhausted by external consumption, can't wait it out
+                // No calls in window — the external quota is exhausted. Wait for
+                // GitHub's reset when we know it, otherwise proceed (#119).
+                const untilReset = this.resetAt - Date.now();
+                if (this.resetAt > 0 && untilReset > 0) {
+                    debug(MODULE, `External quota exhausted, waiting ${untilReset}ms for reset`);
+                    await sleep(untilReset + 100);
+                    continue;
+                }
+                return;
             }
             const waitUntil = oldestInWindow + SEARCH_WINDOW_MS;
             const waitMs = waitUntil - Date.now();