@oss-autopilot/core 1.10.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/config.js

@@ -3,7 +3,7 @@
  * Shows or updates configuration
  */
 import { getStateManager } from '../core/index.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)) {
@@ -105,6 +105,18 @@ export async function runConfig(options) {
         case 'issueListPath':
             stateManager.updateConfig({ issueListPath: value || undefined });
             break;
+        case 'diffTool': {
+            if (!DIFF_TOOLS.includes(value)) {
+                throw new Error(`Invalid diffTool "${value}". Valid options: ${DIFF_TOOLS.join(', ')}`);
+            }
+            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/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,6 +24,7 @@ export interface SetupCompleteOutput {
         projectCategories: ProjectCategory[];
         preferredOrgs: string[];
         scope: IssueScope[];
+        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);
@@ -190,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();
@@ -221,6 +241,7 @@ export async function runSetup(options) {
                 projectCategories: config.projectCategories ?? [],
                 preferredOrgs: config.preferredOrgs ?? [],
                 scope: config.scope ?? [],
+                persistence: config.persistence ?? 'local',
             },
         };
     }
@@ -298,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

@@ -85,6 +85,8 @@ export declare class GistStateStore {
     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,
@@ -135,6 +137,16 @@ export declare class GistStateStore {
      * 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.

package/dist/core/gist-state-store.js

@@ -19,6 +19,7 @@ import { AgentStateSchema } from './state-schema.js';
 import { atomicWriteFileSync, createFreshState, migrateV1ToV2, migrateV2ToV3 } from './state-persistence.js';
 import { getGistIdPath, getStateCachePath } from './utils.js';
 import { debug, warn } from './logger.js';
+import { GistPermissionError, isRateLimitError } from './errors.js';
 const MODULE = 'gist-store';
 /** Well-known Gist description used for search-based discovery. */
 export const GIST_DESCRIPTION = 'oss-autopilot-state';
@@ -32,6 +33,8 @@ export class GistStateStore {
     cachedFiles = new Map();
     dirtyFiles = new Set();
     octokit;
+    lastRefreshAt = 0;
+    static REFRESH_THROTTLE_MS = 30_000;
     constructor(octokit) {
         this.octokit = octokit;
     }
@@ -41,6 +44,7 @@ export class GistStateStore {
      */
     async bootstrap() {
         try {
+            await this.checkGistScope();
             // Step 1: Try loading Gist ID from local file
             const localId = this.readLocalGistId();
             if (localId) {
@@ -71,6 +75,9 @@ export class GistStateStore {
             return { gistId: id, state, created: true };
         }
         catch (err) {
+            // Configuration errors (e.g. GistPermissionError) must surface, not degrade
+            if (err instanceof GistPermissionError)
+                throw err;
             // All API paths failed — enter degraded mode
             warn(MODULE, 'All Gist API paths failed, entering degraded mode', err);
             // Try reading from local cache file
@@ -107,6 +114,7 @@ export class GistStateStore {
      */
     async bootstrapWithMigration(existingState) {
         try {
+            await this.checkGistScope();
             // Step 1: Try loading Gist ID from local file
             const localId = this.readLocalGistId();
             if (localId) {
@@ -137,6 +145,9 @@ export class GistStateStore {
             return { gistId: id, state, created: true, migrated: true };
         }
         catch (err) {
+            // Configuration errors (e.g. GistPermissionError) must surface, not degrade
+            if (err instanceof GistPermissionError)
+                throw err;
             // All API paths failed — enter degraded mode
             warn(MODULE, 'bootstrapWithMigration: all Gist API paths failed, entering degraded mode', err);
             // Try reading from local cache file
@@ -265,7 +276,45 @@ export class GistStateStore {
         }
         return true;
     }
+    /**
+     * Re-fetch the Gist and update the in-memory cache.
+     * Throttled to at most once per 30 seconds.
+     */
+    async refreshFromGist() {
+        if (!this.gistId)
+            return false;
+        const now = Date.now();
+        if (now - this.lastRefreshAt < GistStateStore.REFRESH_THROTTLE_MS)
+            return false;
+        try {
+            await this.fetchAndCache(this.gistId);
+            this.lastRefreshAt = now;
+            return true;
+        }
+        catch (err) {
+            warn(MODULE, `refreshFromGist failed: ${err}`);
+            return false;
+        }
+    }
     // ── Private helpers ─────────────────────────────────────────────────
+    /**
+     * Preflight check: verify the token has Gist API scope.
+     * Costs one cheap API call; catches permission issues early with a clear message.
+     */
+    async checkGistScope() {
+        try {
+            await this.octokit.gists.list({ per_page: 1, page: 1 });
+        }
+        catch (err) {
+            if (isRateLimitError(err))
+                throw err;
+            const status = err.status;
+            if (status === 401 || status === 403) {
+                throw new GistPermissionError();
+            }
+            throw err;
+        }
+    }
     /**
      * Fetch a Gist by ID, populate the in-memory cache, parse state,
      * and write the local cache file.

package/dist/core/index.d.ts

@@ -11,7 +11,7 @@ export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
 export { getOctokit, checkRateLimit, type RateLimitInfo } from './github.js';
 export { parseGitHubUrl, daysBetween, splitRepo, isOwnRepo, getCLIVersion, getDataDir, getStatePath, getBackupDir, getCacheDir, formatRelativeTime, byDateDescending, getGitHubToken, getGitHubTokenAsync, requireGitHubToken, resetGitHubTokenCache, detectGitHubUsername, stateFileExists, DEFAULT_CONCURRENCY, } from './utils.js';
-export { OssAutopilotError, ConfigurationError, ValidationError, errorMessage, getHttpStatusCode, isRateLimitError, isRateLimitOrAuthError, resolveErrorCode, } from './errors.js';
+export { OssAutopilotError, ConfigurationError, ValidationError, GistPermissionError, errorMessage, getHttpStatusCode, isRateLimitError, isRateLimitOrAuthError, resolveErrorCode, } from './errors.js';
 export { enableDebug, isDebugEnabled, debug, info, warn, timed } from './logger.js';
 export { HttpCache, getHttpCache, cachedRequest, type CacheEntry } from './http-cache.js';
 export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatActionHint, formatBriefSummary, formatSummary, printDigest, } from './daily-logic.js';

package/dist/core/index.js

@@ -11,7 +11,7 @@ export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
 export { getOctokit, checkRateLimit } from './github.js';
 export { parseGitHubUrl, daysBetween, splitRepo, isOwnRepo, getCLIVersion, getDataDir, getStatePath, getBackupDir, getCacheDir, formatRelativeTime, byDateDescending, getGitHubToken, getGitHubTokenAsync, requireGitHubToken, resetGitHubTokenCache, detectGitHubUsername, stateFileExists, DEFAULT_CONCURRENCY, } from './utils.js';
-export { OssAutopilotError, ConfigurationError, ValidationError, errorMessage, getHttpStatusCode, isRateLimitError, isRateLimitOrAuthError, resolveErrorCode, } from './errors.js';
+export { OssAutopilotError, ConfigurationError, ValidationError, GistPermissionError, errorMessage, getHttpStatusCode, isRateLimitError, isRateLimitOrAuthError, resolveErrorCode, } from './errors.js';
 export { enableDebug, isDebugEnabled, debug, info, warn, timed } from './logger.js';
 export { HttpCache, getHttpCache, cachedRequest } from './http-cache.js';
 export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatActionHint, formatBriefSummary, formatSummary, printDigest, } from './daily-logic.js';

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

@@ -32,6 +32,12 @@ export declare const IssueScopeSchema: z.ZodEnum<{
     beginner: "beginner";
     intermediate: "intermediate";
 }>;
+export declare const DiffToolSchema: z.ZodEnum<{
+    inline: "inline";
+    custom: "custom";
+    sourcetree: "sourcetree";
+    vscode: "vscode";
+}>;
 export declare const RepoSignalsSchema: z.ZodObject<{
     hasActiveMaintainers: z.ZodBoolean;
     isResponsive: z.ZodBoolean;
@@ -179,6 +185,10 @@ export declare const StatusOverrideSchema: z.ZodObject<{
 export declare const AgentConfigSchema: z.ZodObject<{
     setupComplete: z.ZodDefault<z.ZodBoolean>;
     setupCompletedAt: z.ZodOptional<z.ZodString>;
+    persistence: z.ZodDefault<z.ZodEnum<{
+        local: "local";
+        gist: "gist";
+    }>>;
     maxActivePRs: z.ZodDefault<z.ZodNumber>;
     dormantThresholdDays: z.ZodDefault<z.ZodNumber>;
     approachingDormantDays: z.ZodDefault<z.ZodNumber>;
@@ -223,6 +233,13 @@ export declare const AgentConfigSchema: z.ZodObject<{
         education: "education";
     }>>>;
     preferredOrgs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    diffTool: z.ZodDefault<z.ZodEnum<{
+        inline: "inline";
+        custom: "custom";
+        sourcetree: "sourcetree";
+        vscode: "vscode";
+    }>>;
+    diffToolCustomCommand: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const LocalRepoCacheSchema: z.ZodObject<{
     repos: z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -325,6 +342,10 @@ export declare const AgentStateSchema: z.ZodObject<{
     config: z.ZodDefault<z.ZodObject<{
         setupComplete: z.ZodDefault<z.ZodBoolean>;
         setupCompletedAt: z.ZodOptional<z.ZodString>;
+        persistence: z.ZodDefault<z.ZodEnum<{
+            local: "local";
+            gist: "gist";
+        }>>;
         maxActivePRs: z.ZodDefault<z.ZodNumber>;
         dormantThresholdDays: z.ZodDefault<z.ZodNumber>;
         approachingDormantDays: z.ZodDefault<z.ZodNumber>;
@@ -369,6 +390,13 @@ export declare const AgentStateSchema: z.ZodObject<{
             education: "education";
         }>>>;
         preferredOrgs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        diffTool: z.ZodDefault<z.ZodEnum<{
+            inline: "inline";
+            custom: "custom";
+            sourcetree: "sourcetree";
+            vscode: "vscode";
+        }>>;
+        diffToolCustomCommand: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     lastRunAt: z.ZodDefault<z.ZodString>;
     lastDigestAt: z.ZodOptional<z.ZodString>;
@@ -499,6 +527,7 @@ export type IssueStatus = z.infer<typeof IssueStatusSchema>;
 export type FetchedPRStatus = z.infer<typeof FetchedPRStatusSchema>;
 export type ProjectCategory = z.infer<typeof ProjectCategorySchema>;
 export type IssueScope = z.infer<typeof IssueScopeSchema>;
+export type DiffTool = z.infer<typeof DiffToolSchema>;
 export type RepoSignals = z.infer<typeof RepoSignalsSchema>;
 export type RepoScore = z.infer<typeof RepoScoreSchema>;
 export type StoredMergedPR = z.infer<typeof StoredMergedPRSchema>;

package/dist/core/state-schema.js

@@ -21,6 +21,7 @@ export const ProjectCategorySchema = z.enum([
     'education',
 ]);
 export const IssueScopeSchema = z.enum(['beginner', 'intermediate', 'advanced']);
+export const DiffToolSchema = z.enum(['inline', 'sourcetree', 'vscode', 'custom']);
 // ── 2. Leaf schemas ──────────────────────────────────────────────────
 export const RepoSignalsSchema = z.object({
     hasActiveMaintainers: z.boolean(),
@@ -116,6 +117,7 @@ export const StatusOverrideSchema = z.object({
 export const AgentConfigSchema = z.object({
     setupComplete: z.boolean().default(false),
     setupCompletedAt: z.string().optional(),
+    persistence: z.enum(['local', 'gist']).default('local'),
     maxActivePRs: z.number().default(10),
     dormantThresholdDays: z.number().default(30),
     approachingDormantDays: z.number().default(25),
@@ -142,6 +144,8 @@ export const AgentConfigSchema = z.object({
     skippedIssuesPath: z.string().optional(),
     projectCategories: z.array(ProjectCategorySchema).default([]),
     preferredOrgs: z.array(z.string()).default([]),
+    diffTool: DiffToolSchema.default('inline'),
+    diffToolCustomCommand: z.string().optional(),
 });
 // ── 6. Cache schemas ─────────────────────────────────────────────────
 export const LocalRepoCacheSchema = z.object({

package/dist/core/state.d.ts

@@ -90,6 +90,11 @@ export declare class StateManager {
      * Returns true if state was reloaded, false if unchanged or in-memory mode.
      */
     reloadIfChanged(): boolean;
+    /**
+     * Re-fetch state from the backing Gist (if in Gist mode).
+     * Throttled to once per 30 seconds by GistStateStore. Returns true if state was refreshed.
+     */
+    refreshFromGist(): Promise<boolean>;
     /**
      * Store the latest daily digest and update the digest timestamp.
      * @param digest - The daily digest to store

package/dist/core/state.js

@@ -4,10 +4,11 @@
  * and scoring logic to repo-score-manager.ts.
  */
 import * as fs from 'fs';
+import { AgentStateSchema } from './state-schema.js';
 import { loadState, saveState, reloadStateIfChanged, createFreshState, atomicWriteFileSync, } from './state-persistence.js';
 import * as repoScoring from './repo-score-manager.js';
 import { debug, warn } from './logger.js';
-import { errorMessage } from './errors.js';
+import { errorMessage, ConfigurationError } from './errors.js';
 import { GistStateStore } from './gist-state-store.js';
 import { getStatePath, getStateCachePath } from './utils.js';
 export { acquireLock, releaseLock, atomicWriteFileSync } from './state-persistence.js';
@@ -230,6 +231,31 @@ export class StateManager {
         this.tryReconcilePRCounts();
         return true;
     }
+    /**
+     * Re-fetch state from the backing Gist (if in Gist mode).
+     * Throttled to once per 30 seconds by GistStateStore. Returns true if state was refreshed.
+     */
+    async refreshFromGist() {
+        if (!this.gistStore)
+            return false;
+        const refreshed = await this.gistStore.refreshFromGist();
+        if (refreshed) {
+            const raw = this.gistStore.cachedFiles.get('state.json');
+            if (!raw) {
+                warn(MODULE, 'Gist refreshed but state.json missing from cache');
+                return false;
+            }
+            try {
+                this.state = AgentStateSchema.parse(JSON.parse(raw));
+                this.tryReconcilePRCounts();
+            }
+            catch (err) {
+                warn(MODULE, `Failed to parse refreshed Gist state: ${errorMessage(err)}`);
+                return false;
+            }
+        }
+        return refreshed;
+    }
     // === Dashboard Data Setters ===
     /**
      * Store the latest daily digest and update the digest timestamp.
@@ -669,8 +695,11 @@ export async function getStateManagerAsync(token) {
         })
             .catch((err) => {
             asyncManagerPromise = null;
-            warn(MODULE, `Unhandled Gist initialization error, falling back to local-only mode (not a normal degraded bootstrap): ${err}`);
-            return getStateManager(); // fall back to sync/local
+            // Configuration errors (e.g. GistPermissionError) must surface to the user
+            if (err instanceof ConfigurationError)
+                throw err;
+            warn(MODULE, `Gist initialization failed, falling back to local-only mode: ${err}`);
+            return getStateManager(); // fall back to sync/local for transient errors
         });
         return asyncManagerPromise;
     }