@oss-autopilot/core 1.9.0 → 1.11.0

package/dist/cli.js

@@ -49,6 +49,23 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
             console.error('Then run your command again.');
             process.exit(1);
         }
+        // Activate Gist persistence if configured, before any command runs.
+        // Peek at the config file directly to avoid creating a local-only singleton
+        // (getStateManager() would lock in local mode before getStateManagerAsync runs).
+        let persistence;
+        try {
+            const { getStatePath } = await import('./core/index.js');
+            const fs = await import('fs');
+            const raw = fs.readFileSync(getStatePath(), 'utf-8');
+            persistence = JSON.parse(raw)?.config?.persistence;
+        }
+        catch {
+            // No state file or unreadable — local mode, lazy init
+        }
+        if (persistence === 'gist' && token) {
+            const { getStateManagerAsync } = await import('./core/index.js');
+            await getStateManagerAsync(token);
+        }
     }
 });
 // First-run detection: if no subcommand was provided and no state file exists,

package/dist/commands/comments.js

@@ -185,6 +185,17 @@ export async function runClaim(options) {
             updatedAt: new Date().toISOString(),
             vetted: false,
         });
+        // Push state to Gist if in Gist mode.
+        // If getStateManagerAsync was not called before this command ran,
+        // isGistMode() will be false and checkpoint is correctly skipped.
+        try {
+            if (stateManager.isGistMode()) {
+                await stateManager.checkpoint();
+            }
+        }
+        catch {
+            /* best-effort */
+        }
     }
     catch (error) {
         console.error(`Warning: Comment posted on ${options.issueUrl} but failed to save to local state: ${error instanceof Error ? error.message : error}`);

package/dist/commands/config.js

@@ -3,8 +3,7 @@
  * Shows or updates configuration
  */
 import { getStateManager } from '../core/index.js';
-import { ValidationError } from '../core/errors.js';
-import { ISSUE_SCOPES } from '../core/types.js';
+import { ISSUE_SCOPES, DIFF_TOOLS } from '../core/types.js';
 import { validateGitHubUsername } from './validation.js';
 function validateScope(value) {
     if (!ISSUE_SCOPES.includes(value)) {
@@ -106,14 +105,18 @@ export async function runConfig(options) {
         case 'issueListPath':
             stateManager.updateConfig({ issueListPath: value || undefined });
             break;
-        case 'scoreThreshold': {
-            const threshold = Number(value);
-            if (!Number.isInteger(threshold) || threshold < 1 || threshold > 10) {
-                throw new ValidationError(`Invalid value for scoreThreshold: "${value}". Must be an integer between 1 and 10.`);
+        case 'diffTool': {
+            if (!DIFF_TOOLS.includes(value)) {
+                throw new Error(`Invalid diffTool "${value}". Valid options: ${DIFF_TOOLS.join(', ')}`);
             }
-            stateManager.updateConfig({ scoreThreshold: threshold });
+            stateManager.updateConfig({ diffTool: value });
             break;
         }
+        case 'diffToolCustomCommand':
+            stateManager.updateConfig({
+                diffToolCustomCommand: value || undefined,
+            });
+            break;
         default:
             throw new Error(`Unknown config key: ${options.key}`);
     }

package/dist/commands/daily.js

@@ -424,11 +424,21 @@ async function executeDailyCheckInternal(token) {
     const { prs, failures, mergedCounts, closedCounts, monthlyCounts, monthlyClosedCounts, openedFromMerged, openedFromClosed, recentlyClosedPRs, recentlyMergedPRs, commentedIssues, } = await fetchPRData(prMonitor, token);
     // Phase 2: Update repo scores (signals, star counts, trust sync)
     await updateRepoScores(prMonitor, prs, mergedCounts, closedCounts);
-    // Phase 3: Persist monthly analytics (batch the 3 monthly setter calls).
+    // Phase 3: Persist monthly analytics and store merged/closed PR history.
     // try-catch: analytics are supplementary — save failure should not crash the daily check.
     try {
         getStateManager().batch(() => {
             updateMonthlyAnalytics(prs, monthlyCounts, monthlyClosedCounts, openedFromMerged, openedFromClosed);
+            // Store recently merged/closed PRs in the persistent arrays.
+            // This ensures the mergedPRs/closedPRs ledger is populated even when
+            // the dashboard is never opened (which has its own fetch path).
+            // addMergedPRs/addClosedPRs deduplicate by URL, so overlaps are safe.
+            if (recentlyMergedPRs.length > 0) {
+                getStateManager().addMergedPRs(recentlyMergedPRs.map((pr) => ({ url: pr.url, title: pr.title, mergedAt: pr.mergedAt })));
+            }
+            if (recentlyClosedPRs.length > 0) {
+                getStateManager().addClosedPRs(recentlyClosedPRs.map((pr) => ({ url: pr.url, title: pr.title, closedAt: pr.closedAt })));
+            }
         });
     }
     catch (error) {
@@ -440,7 +450,20 @@ async function executeDailyCheckInternal(token) {
     // Phase 4: Partition PRs, generate and save digest
     const { activePRs, shelvedPRs, digest } = partitionPRs(prMonitor, prs, recentlyClosedPRs, recentlyMergedPRs);
     // Phase 5: Build structured output (capacity, dismiss filter, action menu)
-    return generateDigestOutput(digest, activePRs, shelvedPRs, commentedIssues, failures, previousLastDigestAt);
+    const result = generateDigestOutput(digest, activePRs, shelvedPRs, commentedIssues, failures, previousLastDigestAt);
+    // Checkpoint: push state to Gist if in Gist mode.
+    // If getStateManagerAsync was not called before this command ran,
+    // isGistMode() will be false and checkpoint is correctly skipped.
+    try {
+        const sm = getStateManager();
+        if (sm.isGistMode()) {
+            await sm.checkpoint();
+        }
+    }
+    catch (err) {
+        warn(MODULE, `Gist checkpoint failed: ${errorMessage(err)}`);
+    }
+    return result;
 }
 /**
  * Run the daily PR check and return a deduplicated digest.

package/dist/commands/dashboard-server.js

@@ -209,8 +209,15 @@ export async function startDashboardServer(options) {
                     sendError(res, 429, 'Too many requests');
                     return;
                 }
-                // Re-read state.json if CLI commands modified it externally
-                if (stateManager.reloadIfChanged()) {
+                // Re-read state if modified externally (file mtime for local, Gist API for Gist mode)
+                let stateChanged = false;
+                if (stateManager.isGistMode()) {
+                    stateChanged = await stateManager.refreshFromGist();
+                }
+                else {
+                    stateChanged = stateManager.reloadIfChanged();
+                }
+                if (stateChanged) {
                     try {
                         cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues);
                     }
@@ -268,7 +275,12 @@ export async function startDashboardServer(options) {
     // ── POST /api/action handler ─────────────────────────────────────────────
     async function handleAction(req, res) {
         // Reload state before mutating to avoid overwriting external CLI changes
-        stateManager.reloadIfChanged();
+        if (stateManager.isGistMode()) {
+            await stateManager.refreshFromGist();
+        }
+        else {
+            stateManager.reloadIfChanged();
+        }
         let body;
         try {
             const raw = await readBody(req);
@@ -334,7 +346,12 @@ export async function startDashboardServer(options) {
             return;
         }
         try {
-            stateManager.reloadIfChanged();
+            if (stateManager.isGistMode()) {
+                await stateManager.refreshFromGist();
+            }
+            else {
+                stateManager.reloadIfChanged();
+            }
             warn(MODULE, 'Refreshing dashboard data from GitHub...');
             const result = await fetchDashboardData(currentToken);
             cachedDigest = result.digest;
@@ -449,8 +466,13 @@ export async function startDashboardServer(options) {
     // so subsequent /api/data requests get live data instead of cached state.
     if (token) {
         fetchDashboardData(token)
-            .then((result) => {
-            stateManager.reloadIfChanged();
+            .then(async (result) => {
+            if (stateManager.isGistMode()) {
+                await stateManager.refreshFromGist();
+            }
+            else {
+                stateManager.reloadIfChanged();
+            }
             cachedDigest = result.digest;
             cachedCommentedIssues = result.commentedIssues;
             cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues, result.allMergedPRs, result.allClosedPRs);

package/dist/commands/index.d.ts

@@ -55,6 +55,12 @@ export { runInit } from './init.js';
 export { runSetup } from './setup.js';
 /** Check whether setup has been completed. */
 export { runCheckSetup } from './setup.js';
+/** Show current persistence mode, Gist ID, and sync status. */
+export { runStateShow } from './state-cmd.js';
+/** Force push state to the backing Gist (no-op in local mode). */
+export { runStateSync } from './state-cmd.js';
+/** Disconnect from Gist persistence and switch to local-only mode. */
+export { runStateUnlink } from './state-cmd.js';
 /** Parse a curated markdown issue list file into structured issue items. */
 export { runParseList, pruneIssueList } from './parse-list.js';
 /** Check if new files are properly referenced/integrated. */
@@ -76,3 +82,4 @@ export type { InitOutput } from './init.js';
 export type { ConfigSetOutput, ConfigCommandOutput } from './config.js';
 export type { SetupSetOutput, SetupCompleteOutput, SetupRequiredOutput, SetupOutput, CheckSetupOutput, } from './setup.js';
 export type { DailyCheckResult } from './daily.js';
+export type { StateShowOutput, StateSyncOutput, StateUnlinkOutput } from './state-cmd.js';

package/dist/commands/index.js

@@ -59,6 +59,13 @@ export { runInit } from './init.js';
 export { runSetup } from './setup.js';
 /** Check whether setup has been completed. */
 export { runCheckSetup } from './setup.js';
+// ── State Persistence ────────────────────────────────────────────────────────
+/** Show current persistence mode, Gist ID, and sync status. */
+export { runStateShow } from './state-cmd.js';
+/** Force push state to the backing Gist (no-op in local mode). */
+export { runStateSync } from './state-cmd.js';
+/** Disconnect from Gist persistence and switch to local-only mode. */
+export { runStateUnlink } from './state-cmd.js';
 // ── Utilities ───────────────────────────────────────────────────────────────
 /** Parse a curated markdown issue list file into structured issue items. */
 export { runParseList, pruneIssueList } from './parse-list.js';

package/dist/commands/setup.d.ts

@@ -24,7 +24,7 @@ export interface SetupCompleteOutput {
         projectCategories: ProjectCategory[];
         preferredOrgs: string[];
         scope: IssueScope[];
-        scoreThreshold: number;
+        persistence: 'local' | 'gist';
     };
 }
 export interface SetupPrompt {

package/dist/commands/setup.js

@@ -5,7 +5,7 @@
 import { getStateManager, DEFAULT_CONFIG } from '../core/index.js';
 import { ValidationError } from '../core/errors.js';
 import { validateGitHubUsername } from './validation.js';
-import { PROJECT_CATEGORIES, ISSUE_SCOPES } from '../core/types.js';
+import { PROJECT_CATEGORIES, ISSUE_SCOPES, DIFF_TOOLS, } from '../core/types.js';
 /** Parse and validate a positive integer setting value. */
 function parsePositiveInt(value, settingName) {
     const parsed = Number(value);
@@ -14,14 +14,6 @@ function parsePositiveInt(value, settingName) {
     }
     return parsed;
 }
-/** Parse and validate an integer within a specific range [min, max]. */
-function parseBoundedInt(value, settingName, min, max) {
-    const parsed = Number(value);
-    if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
-        throw new ValidationError(`Invalid value for ${settingName}: "${value}". Must be an integer between ${min} and ${max}.`);
-    }
-    return parsed;
-}
 /**
  * Interactive setup wizard or direct setting application.
  *
@@ -78,10 +70,6 @@ export async function runSetup(options) {
                         stateManager.updateConfig({ labels: value.split(',').map((l) => l.trim()) });
                         results[key] = value;
                         break;
-                    case 'showHealthCheck':
-                        stateManager.updateConfig({ showHealthCheck: value !== 'false' });
-                        results[key] = value !== 'false' ? 'true' : 'false';
-                        break;
                     case 'squashByDefault':
                         if (value === 'ask') {
                             stateManager.updateConfig({ squashByDefault: 'ask' });
@@ -92,12 +80,6 @@ export async function runSetup(options) {
                             results[key] = value !== 'false' ? 'true' : 'false';
                         }
                         break;
-                    case 'scoreThreshold': {
-                        const threshold = parseBoundedInt(value, 'scoreThreshold', 1, 10);
-                        stateManager.updateConfig({ scoreThreshold: threshold });
-                        results[key] = String(threshold);
-                        break;
-                    }
                     case 'minStars': {
                         const stars = Number(value);
                         if (!Number.isInteger(stars) || stars < 0) {
@@ -208,10 +190,30 @@ export async function runSetup(options) {
                         results[key] = dedupedScopes.length > 0 ? dedupedScopes.join(', ') : '(empty — using labels only)';
                         break;
                     }
+                    case 'persistence':
+                        if (value !== 'local' && value !== 'gist') {
+                            throw new ValidationError(`Invalid value for persistence: "${value}". Must be "local" or "gist".`);
+                        }
+                        stateManager.updateConfig({ persistence: value });
+                        results[key] = value;
+                        break;
                     case 'issueListPath':
                         stateManager.updateConfig({ issueListPath: value || undefined });
                         results[key] = value || '(cleared)';
                         break;
+                    case 'diffTool': {
+                        if (!DIFF_TOOLS.includes(value)) {
+                            warnings.push(`Invalid diffTool "${value}". Valid: ${DIFF_TOOLS.join(', ')}`);
+                            break;
+                        }
+                        stateManager.updateConfig({ diffTool: value });
+                        results[key] = value;
+                        break;
+                    }
+                    case 'diffToolCustomCommand':
+                        stateManager.updateConfig({ diffToolCustomCommand: value || undefined });
+                        results[key] = value || '(cleared)';
+                        break;
                     case 'complete':
                         if (value === 'true') {
                             stateManager.markSetupComplete();
@@ -239,7 +241,7 @@ export async function runSetup(options) {
                 projectCategories: config.projectCategories ?? [],
                 preferredOrgs: config.preferredOrgs ?? [],
                 scope: config.scope ?? [],
-                scoreThreshold: config.scoreThreshold,
+                persistence: config.persistence ?? 'local',
             },
         };
     }
@@ -296,13 +298,6 @@ export async function runSetup(options) {
                 default: [],
                 type: 'list',
             },
-            {
-                setting: 'scoreThreshold',
-                prompt: 'Minimum vet score (1-10) for issues to keep after vetting? Issues below this are auto-filtered.',
-                current: config.scoreThreshold,
-                default: 6,
-                type: 'number',
-            },
             {
                 setting: 'aiPolicyBlocklist',
                 prompt: 'Repos with anti-AI contribution policies to block (owner/repo, comma-separated)?',
@@ -324,6 +319,13 @@ export async function runSetup(options) {
                 default: [],
                 type: 'list',
             },
+            {
+                setting: 'persistence',
+                prompt: 'Where should state be stored? "local" for file only, "gist" for GitHub Gist (survives device loss)',
+                current: config.persistence ?? 'local',
+                default: 'local',
+                type: 'string',
+            },
         ],
     };
 }

package/dist/commands/state-cmd.d.ts

@@ -0,0 +1,22 @@
+/**
+ * State persistence management commands.
+ * Provides --show, --sync, and --unlink subcommands for the Gist persistence layer.
+ */
+export interface StateShowOutput {
+    persistence: 'local' | 'gist';
+    gistId: string | null;
+    gistDegraded: boolean;
+    lastRunAt: string | undefined;
+}
+export interface StateSyncOutput {
+    pushed: boolean;
+    gistId: string | null;
+}
+export interface StateUnlinkOutput {
+    unlinked: boolean;
+    localStatePath: string;
+    previousGistId: string | null;
+}
+export declare function runStateShow(): Promise<StateShowOutput>;
+export declare function runStateSync(): Promise<StateSyncOutput>;
+export declare function runStateUnlink(): Promise<StateUnlinkOutput>;

package/dist/commands/state-cmd.js

@@ -0,0 +1,64 @@
+/**
+ * State persistence management commands.
+ * Provides --show, --sync, and --unlink subcommands for the Gist persistence layer.
+ */
+import * as fs from 'fs';
+import { getStateManager, resetStateManager } from '../core/state.js';
+import { atomicWriteFileSync } from '../core/state-persistence.js';
+import { getStatePath, getGistIdPath } from '../core/utils.js';
+import { warn } from '../core/logger.js';
+const MODULE = 'state-cmd';
+export async function runStateShow() {
+    const sm = getStateManager();
+    const state = sm.getState();
+    return {
+        persistence: state.config.persistence ?? 'local',
+        gistId: state.gistId ?? null,
+        gistDegraded: sm.isGistDegraded(),
+        lastRunAt: state.lastRunAt,
+    };
+}
+export async function runStateSync() {
+    const sm = getStateManager();
+    if (!sm.isGistMode()) {
+        return { pushed: false, gistId: null };
+    }
+    const pushed = await sm.checkpoint();
+    if (!pushed) {
+        throw new Error('Failed to push state to Gist after retry. Check network connectivity and token permissions.');
+    }
+    return { pushed: true, gistId: sm.getState().gistId ?? null };
+}
+export async function runStateUnlink() {
+    const sm = getStateManager();
+    const state = sm.getState();
+    const previousGistId = state.gistId ?? null;
+    const statePath = getStatePath();
+    // Refresh from Gist to get the latest state before unlinking
+    if (sm.isGistMode()) {
+        await sm.refreshFromGist();
+    }
+    // Write current state to local state.json with persistence set to local
+    const localState = JSON.parse(JSON.stringify(sm.getState()));
+    delete localState.gistId;
+    localState.config.persistence = 'local';
+    atomicWriteFileSync(statePath, JSON.stringify(localState, null, 2), 0o600);
+    // Remove the gist-id file so future startups don't try to use the Gist
+    const gistIdPath = getGistIdPath();
+    try {
+        if (fs.existsSync(gistIdPath)) {
+            fs.unlinkSync(gistIdPath);
+        }
+    }
+    catch (err) {
+        warn(MODULE, `Failed to remove gist-id file: ${err}`);
+    }
+    // Do NOT delete the remote Gist — the user may want it as a backup
+    // Reset the singleton so subsequent calls in this process use local mode
+    resetStateManager();
+    return {
+        unlinked: true,
+        localStatePath: statePath,
+        previousGistId,
+    };
+}

package/dist/core/errors.d.ts

@@ -26,6 +26,12 @@ export declare class ConfigurationError extends OssAutopilotError {
 export declare class ValidationError extends OssAutopilotError {
     constructor(message: string);
 }
+/**
+ * Gist API scope error (token lacks the "gist" scope).
+ */
+export declare class GistPermissionError extends ConfigurationError {
+    constructor(message?: string);
+}
 /**
  * Extract a human-readable message from an unknown error value.
  */

package/dist/core/errors.js

@@ -36,6 +36,18 @@ export class ValidationError extends OssAutopilotError {
         this.name = 'ValidationError';
     }
 }
+/**
+ * Gist API scope error (token lacks the "gist" scope).
+ */
+export class GistPermissionError extends ConfigurationError {
+    constructor(message) {
+        super(message ??
+            'Your GitHub token does not have Gist permissions. ' +
+                'Run `gh auth refresh -s gist` to add the required scope, ' +
+                'or create a token with the "gist" scope.');
+        this.name = 'GistPermissionError';
+    }
+}
 /**
  * Extract a human-readable message from an unknown error value.
  */

package/dist/core/gist-state-store.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Gist-based persistence layer for oss-autopilot state.
+ *
+ * Manages a single private GitHub Gist that stores `state.json` (structured state)
+ * and potentially freeform markdown documents. Provides an in-memory file cache
+ * for session-scoped reads and a local cache write-through for degraded-mode fallback.
+ *
+ * Bootstrap flow:
+ *  1. Check for locally stored Gist ID file (`~/.oss-autopilot/gist-id`)
+ *  2. If found, fetch that Gist directly via `GET /gists/:id`
+ *  3. If not found locally, search the user's Gists for description `oss-autopilot-state`
+ *  4. If found via search, store the ID locally and fetch it
+ *  5. If not found anywhere, create a new private Gist with seed files and store the ID
+ *  6. Cache all Gist file contents in memory for session-scoped reads
+ *  7. Write state to a local cache file for fallback
+ */
+import { AgentState } from './types.js';
+/** Well-known Gist description used for search-based discovery. */
+export declare const GIST_DESCRIPTION = "oss-autopilot-state";
+/** Primary state file name inside the Gist. */
+export declare const STATE_FILE_NAME = "state.json";
+/** Result of a successful bootstrap. */
+export interface BootstrapResult {
+    gistId: string;
+    state: AgentState;
+    created: boolean;
+    /** True when state was loaded from local cache due to API failure. */
+    degraded?: boolean;
+}
+/**
+ * Minimal Octokit-shaped interface for the Gist API methods we use.
+ * Accepts the real ThrottledOctokit or a plain mock object in tests.
+ */
+export interface OctokitLike {
+    gists: {
+        get: (params: {
+            gist_id: string;
+        }) => Promise<{
+            data: GistResponseData;
+        }>;
+        list: (params: {
+            per_page: number;
+            page: number;
+        }) => Promise<{
+            data: GistListItem[];
+        }>;
+        create: (params: {
+            description: string;
+            public: boolean;
+            files: Record<string, {
+                content: string;
+            }>;
+        }) => Promise<{
+            data: GistResponseData;
+        }>;
+        update: (params: {
+            gist_id: string;
+            files: Record<string, {
+                content: string;
+            }>;
+        }) => Promise<{
+            data: GistResponseData;
+        }>;
+    };
+}
+/** Shape of a single Gist in a list response (subset). */
+interface GistListItem {
+    id: string;
+    description: string | null;
+}
+/** Shape of a full Gist response (subset). */
+interface GistResponseData {
+    id: string;
+    description: string | null;
+    files: Record<string, {
+        filename: string;
+        content?: string;
+    } | null>;
+}
+/**
+ * Gist-backed state store with in-memory file cache and local write-through.
+ */
+export declare class GistStateStore {
+    private gistId;
+    readonly cachedFiles: Map<string, string>;
+    readonly dirtyFiles: Set<string>;
+    private readonly octokit;
+    private lastRefreshAt;
+    private static readonly REFRESH_THROTTLE_MS;
+    constructor(octokit: OctokitLike);
+    /**
+     * Bootstrap the Gist store: locate or create the backing Gist,
+     * populate the in-memory cache, and write the local cache file.
+     */
+    bootstrap(): Promise<BootstrapResult>;
+    /**
+     * Bootstrap with migration from an existing local state.
+     * If a Gist already exists (found via local ID or search), uses it — no migration needed.
+     * If no Gist exists, creates one seeded with the provided existingState instead of a fresh state.
+     * @returns BootstrapResult extended with `migrated: true` if a new Gist was created from local state
+     */
+    bootstrapWithMigration(existingState: AgentState): Promise<BootstrapResult & {
+        migrated: boolean;
+    }>;
+    /** Return the resolved Gist ID (available after bootstrap). */
+    getGistId(): string | null;
+    /**
+     * Mark a file as dirty so it will be included in the next `push()` call.
+     */
+    markDirty(filename: string): void;
+    /**
+     * Read a freeform document from the in-memory cache.
+     * Returns null if the file has not been loaded (or does not exist in the Gist).
+     * Synchronous — all Gist contents are loaded into memory at bootstrap.
+     */
+    getDocument(filename: string): string | null;
+    /**
+     * Write a freeform document into the in-memory cache and mark it dirty
+     * so it will be included in the next `push()` call.
+     */
+    setDocument(filename: string, content: string): void;
+    /**
+     * Return all filenames in the in-memory cache whose names start with `prefix`.
+     * Useful for listing all guidelines files (e.g. prefix `guidelines--`).
+     */
+    listDocuments(prefix: string): string[];
+    /**
+     * Stage new state JSON for the next `push()`. Updates the in-memory cache
+     * for `state.json` and marks it dirty.
+     */
+    setState(stateJson: string): void;
+    /**
+     * Push all dirty files to the backing Gist. Retries once on failure.
+     *
+     * Returns `true` on success (or when there is nothing to push).
+     * Returns `false` if both attempts fail.
+     * Throws if the Gist ID has not been resolved yet (bootstrap not called).
+     */
+    push(): Promise<boolean>;
+    /**
+     * Re-fetch the Gist and update the in-memory cache.
+     * Throttled to at most once per 30 seconds.
+     */
+    refreshFromGist(): Promise<boolean>;
+    /**
+     * Preflight check: verify the token has Gist API scope.
+     * Costs one cheap API call; catches permission issues early with a clear message.
+     */
+    private checkGistScope;
+    /**
+     * Fetch a Gist by ID, populate the in-memory cache, parse state,
+     * and write the local cache file.
+     */
+    private fetchAndCache;
+    /**
+     * Parse `state.json` from the in-memory cache. Handles v2 migration
+     * by running through the Zod schema (which requires version: 3).
+     * Falls back to fresh state if the file is missing or unparseable.
+     */
+    private parseStateFromCache;
+    /**
+     * Search the authenticated user's Gists for one with the well-known description.
+     * Pages through up to 10 pages (100 Gists per page) to find it.
+     */
+    private searchForGist;
+    /**
+     * Create a new private Gist with seed files and store it in memory.
+     */
+    private createGist;
+    /**
+     * Create a new private Gist seeded with the provided state (for migration).
+     */
+    private createGistFromState;
+    /** Read the locally persisted Gist ID, or return null if not found. */
+    private readLocalGistId;
+    /** Persist the Gist ID locally for fast lookup on next session. */
+    private writeLocalGistId;
+    /** Write state to the local cache file for degraded-mode fallback. */
+    private writeLocalStateCache;
+}
+export {};