@oss-autopilot/core 1.8.0 → 1.10.0

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

@@ -0,0 +1,424 @@
+/**
+ * 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 * as fs from 'fs';
+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';
+const MODULE = 'gist-store';
+/** Well-known Gist description used for search-based discovery. */
+export const GIST_DESCRIPTION = 'oss-autopilot-state';
+/** Primary state file name inside the Gist. */
+export const STATE_FILE_NAME = 'state.json';
+/**
+ * Gist-backed state store with in-memory file cache and local write-through.
+ */
+export class GistStateStore {
+    gistId = null;
+    cachedFiles = new Map();
+    dirtyFiles = new Set();
+    octokit;
+    constructor(octokit) {
+        this.octokit = octokit;
+    }
+    /**
+     * Bootstrap the Gist store: locate or create the backing Gist,
+     * populate the in-memory cache, and write the local cache file.
+     */
+    async bootstrap() {
+        try {
+            // Step 1: Try loading Gist ID from local file
+            const localId = this.readLocalGistId();
+            if (localId) {
+                debug(MODULE, `Found local Gist ID: ${localId}`);
+                try {
+                    this.gistId = localId;
+                    const state = await this.fetchAndCache(localId);
+                    return { gistId: localId, state, created: false };
+                }
+                catch (err) {
+                    warn(MODULE, `Failed to fetch Gist ${localId}, will search/create`, err);
+                    // Fall through to search
+                }
+            }
+            // Step 2: Search user's Gists by description
+            const foundId = await this.searchForGist();
+            if (foundId) {
+                debug(MODULE, `Found Gist via search: ${foundId}`);
+                this.gistId = foundId;
+                this.writeLocalGistId(foundId);
+                const state = await this.fetchAndCache(foundId);
+                return { gistId: foundId, state, created: false };
+            }
+            // Step 3: Create a new Gist
+            debug(MODULE, 'No existing Gist found, creating new one');
+            const { id, state } = await this.createGist();
+            this.writeLocalGistId(id);
+            return { gistId: id, state, created: true };
+        }
+        catch (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
+            try {
+                const cachePath = getStateCachePath();
+                if (fs.existsSync(cachePath)) {
+                    let obj = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+                    // Chain migrations
+                    if (typeof obj === 'object' && obj !== null) {
+                        const record = obj;
+                        if (record.version === 1)
+                            obj = migrateV1ToV2(record);
+                        if (obj.version === 2)
+                            obj = migrateV2ToV3(obj);
+                    }
+                    const cachedState = AgentStateSchema.parse(obj);
+                    debug(MODULE, 'Loaded state from local cache in degraded mode');
+                    return { gistId: '', state: cachedState, created: false, degraded: true };
+                }
+            }
+            catch (cacheErr) {
+                debug(MODULE, `Failed to read local cache in degraded mode: ${cacheErr}`);
+            }
+            // No cache either — return fresh state in degraded mode
+            debug(MODULE, 'No local cache found, returning fresh state in degraded mode');
+            return { gistId: '', state: createFreshState(), created: false, degraded: true };
+        }
+    }
+    /**
+     * 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
+     */
+    async bootstrapWithMigration(existingState) {
+        try {
+            // Step 1: Try loading Gist ID from local file
+            const localId = this.readLocalGistId();
+            if (localId) {
+                debug(MODULE, `bootstrapWithMigration: found local Gist ID: ${localId}`);
+                try {
+                    this.gistId = localId;
+                    const state = await this.fetchAndCache(localId);
+                    return { gistId: localId, state, created: false, migrated: false };
+                }
+                catch (err) {
+                    warn(MODULE, `bootstrapWithMigration: failed to fetch Gist ${localId}, will search/create`, err);
+                    // Fall through to search
+                }
+            }
+            // Step 2: Search user's Gists by description
+            const foundId = await this.searchForGist();
+            if (foundId) {
+                debug(MODULE, `bootstrapWithMigration: found Gist via search: ${foundId}`);
+                this.gistId = foundId;
+                this.writeLocalGistId(foundId);
+                const state = await this.fetchAndCache(foundId);
+                return { gistId: foundId, state, created: false, migrated: false };
+            }
+            // Step 3: No existing Gist found — create one seeded with the provided state
+            debug(MODULE, 'bootstrapWithMigration: no existing Gist found, creating one seeded with local state');
+            const { id, state } = await this.createGistFromState(existingState);
+            this.writeLocalGistId(id);
+            return { gistId: id, state, created: true, migrated: true };
+        }
+        catch (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
+            try {
+                const cachePath = getStateCachePath();
+                if (fs.existsSync(cachePath)) {
+                    let obj = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+                    // Chain migrations
+                    if (typeof obj === 'object' && obj !== null) {
+                        const record = obj;
+                        if (record.version === 1)
+                            obj = migrateV1ToV2(record);
+                        if (obj.version === 2)
+                            obj = migrateV2ToV3(obj);
+                    }
+                    const cachedState = AgentStateSchema.parse(obj);
+                    debug(MODULE, 'bootstrapWithMigration: loaded state from local cache in degraded mode');
+                    return { gistId: '', state: cachedState, created: false, degraded: true, migrated: false };
+                }
+            }
+            catch (cacheErr) {
+                debug(MODULE, `bootstrapWithMigration: failed to read local cache in degraded mode: ${cacheErr}`);
+            }
+            // No cache either — use the provided existingState in degraded mode
+            debug(MODULE, 'bootstrapWithMigration: no local cache found, returning existing state in degraded mode');
+            return { gistId: '', state: existingState, created: false, degraded: true, migrated: false };
+        }
+    }
+    /** Return the resolved Gist ID (available after bootstrap). */
+    getGistId() {
+        return this.gistId;
+    }
+    /**
+     * Mark a file as dirty so it will be included in the next `push()` call.
+     */
+    markDirty(filename) {
+        this.dirtyFiles.add(filename);
+    }
+    /**
+     * 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) {
+        return this.cachedFiles.get(filename) ?? 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, content) {
+        this.cachedFiles.set(filename, content);
+        this.markDirty(filename);
+    }
+    /**
+     * 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) {
+        const results = [];
+        for (const filename of this.cachedFiles.keys()) {
+            if (filename.startsWith(prefix)) {
+                results.push(filename);
+            }
+        }
+        return results;
+    }
+    /**
+     * Stage new state JSON for the next `push()`. Updates the in-memory cache
+     * for `state.json` and marks it dirty.
+     */
+    setState(stateJson) {
+        this.cachedFiles.set(STATE_FILE_NAME, stateJson);
+        this.markDirty(STATE_FILE_NAME);
+    }
+    /**
+     * 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).
+     */
+    async push() {
+        if (this.dirtyFiles.size === 0) {
+            return true;
+        }
+        if (this.gistId === null) {
+            throw new Error('GistStateStore: cannot push before bootstrap — gistId is null');
+        }
+        // Build PATCH payload from the dirty set
+        const files = {};
+        for (const filename of this.dirtyFiles) {
+            const content = this.cachedFiles.get(filename);
+            if (content !== undefined) {
+                files[filename] = { content };
+            }
+        }
+        const attempt = async () => {
+            await this.octokit.gists.update({ gist_id: this.gistId, files });
+            return true;
+        };
+        try {
+            await attempt();
+        }
+        catch (firstErr) {
+            debug(MODULE, `push failed on first attempt, retrying: ${firstErr}`);
+            try {
+                await attempt();
+            }
+            catch (secondErr) {
+                warn(MODULE, `push failed after retry, giving up: ${secondErr}`);
+                return false;
+            }
+        }
+        // Success: flush dirty set and write local cache
+        this.dirtyFiles.clear();
+        const raw = this.cachedFiles.get(STATE_FILE_NAME);
+        if (raw) {
+            try {
+                const state = this.parseStateFromCache();
+                this.writeLocalStateCache(state);
+            }
+            catch (err) {
+                debug(MODULE, `push succeeded but local cache write failed: ${err}`);
+            }
+        }
+        return true;
+    }
+    // ── Private helpers ─────────────────────────────────────────────────
+    /**
+     * Fetch a Gist by ID, populate the in-memory cache, parse state,
+     * and write the local cache file.
+     */
+    async fetchAndCache(gistId) {
+        const { data } = await this.octokit.gists.get({ gist_id: gistId });
+        this.gistId = gistId;
+        // Populate in-memory cache with ALL files from the Gist
+        this.cachedFiles.clear();
+        for (const [filename, file] of Object.entries(data.files)) {
+            if (file && file.content != null) {
+                this.cachedFiles.set(filename, file.content);
+            }
+        }
+        // Parse state.json
+        const state = this.parseStateFromCache();
+        // Write-through to local cache for degraded-mode fallback
+        this.writeLocalStateCache(state);
+        return state;
+    }
+    /**
+     * 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.
+     */
+    parseStateFromCache() {
+        const raw = this.cachedFiles.get(STATE_FILE_NAME);
+        if (!raw) {
+            debug(MODULE, 'No state.json found in Gist, using fresh state');
+            return createFreshState();
+        }
+        try {
+            let obj = JSON.parse(raw);
+            // Chain migrations using shared helpers from state-persistence
+            if (typeof obj === 'object' && obj !== null) {
+                const record = obj;
+                if (record.version === 1)
+                    obj = migrateV1ToV2(record);
+                if (obj.version === 2)
+                    obj = migrateV2ToV3(obj);
+            }
+            return AgentStateSchema.parse(obj);
+        }
+        catch (err) {
+            warn(MODULE, `Failed to parse state.json from Gist: ${err}`);
+            return createFreshState();
+        }
+    }
+    /**
+     * 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.
+     */
+    async searchForGist() {
+        try {
+            const maxPages = 10;
+            for (let page = 1; page <= maxPages; page++) {
+                const { data: gists } = await this.octokit.gists.list({ per_page: 100, page });
+                if (gists.length === 0)
+                    break;
+                const match = gists.find((g) => g.description === GIST_DESCRIPTION);
+                if (match) {
+                    return match.id;
+                }
+            }
+        }
+        catch (err) {
+            warn(MODULE, 'Failed to search Gists by description', err);
+        }
+        return null;
+    }
+    /**
+     * Create a new private Gist with seed files and store it in memory.
+     */
+    async createGist() {
+        const freshState = createFreshState();
+        const stateContent = JSON.stringify(freshState, null, 2);
+        const { data } = await this.octokit.gists.create({
+            description: GIST_DESCRIPTION,
+            public: false,
+            files: {
+                [STATE_FILE_NAME]: { content: stateContent },
+            },
+        });
+        this.gistId = data.id;
+        // Populate in-memory cache
+        this.cachedFiles.clear();
+        for (const [filename, file] of Object.entries(data.files)) {
+            if (file && file.content != null) {
+                this.cachedFiles.set(filename, file.content);
+            }
+        }
+        // Write-through to local cache
+        this.writeLocalStateCache(freshState);
+        return { id: data.id, state: freshState };
+    }
+    /**
+     * Create a new private Gist seeded with the provided state (for migration).
+     */
+    async createGistFromState(seedState) {
+        const stateContent = JSON.stringify(seedState, null, 2);
+        const { data } = await this.octokit.gists.create({
+            description: GIST_DESCRIPTION,
+            public: false,
+            files: {
+                [STATE_FILE_NAME]: { content: stateContent },
+            },
+        });
+        this.gistId = data.id;
+        // Populate in-memory cache
+        this.cachedFiles.clear();
+        for (const [filename, file] of Object.entries(data.files)) {
+            if (file && file.content != null) {
+                this.cachedFiles.set(filename, file.content);
+            }
+        }
+        // Write-through to local cache
+        this.writeLocalStateCache(seedState);
+        return { id: data.id, state: seedState };
+    }
+    /** Read the locally persisted Gist ID, or return null if not found. */
+    readLocalGistId() {
+        try {
+            const gistIdPath = getGistIdPath();
+            if (fs.existsSync(gistIdPath)) {
+                const id = fs.readFileSync(gistIdPath, 'utf-8').trim();
+                return id || null;
+            }
+        }
+        catch (err) {
+            debug(MODULE, 'Could not read local Gist ID file', err);
+        }
+        return null;
+    }
+    /** Persist the Gist ID locally for fast lookup on next session. */
+    writeLocalGistId(gistId) {
+        try {
+            const gistIdPath = getGistIdPath();
+            atomicWriteFileSync(gistIdPath, gistId, 0o600);
+            debug(MODULE, `Wrote Gist ID to ${gistIdPath}`);
+        }
+        catch (err) {
+            warn(MODULE, `Failed to write local Gist ID file: ${err}`);
+        }
+    }
+    /** Write state to the local cache file for degraded-mode fallback. */
+    writeLocalStateCache(state) {
+        try {
+            const cachePath = getStateCachePath();
+            atomicWriteFileSync(cachePath, JSON.stringify(state, null, 2), 0o600);
+            debug(MODULE, `Wrote state cache to ${cachePath}`);
+        }
+        catch (err) {
+            warn(MODULE, `Failed to write local state cache: ${err}`);
+        }
+    }
+}

package/dist/core/index.d.ts

@@ -2,7 +2,8 @@
  * Core module exports
  * Re-exports all core functionality for convenient imports
  */
-export { StateManager, getStateManager, resetStateManager, type Stats } from './state.js';
+export { StateManager, getStateManager, getStateManagerAsync, resetStateManager, type Stats } from './state.js';
+export { GistStateStore } from './gist-state-store.js';
 export { PRMonitor, type PRCheckFailure, type FetchPRsResult, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
 export { IssueDiscovery } from './issue-discovery.js';
 export { isDocOnlyIssue, applyPerRepoCap, DOC_ONLY_LABELS } from './issue-filtering.js';
@@ -10,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, } from './errors.js';
+export { OssAutopilotError, ConfigurationError, ValidationError, 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

@@ -2,7 +2,8 @@
  * Core module exports
  * Re-exports all core functionality for convenient imports
  */
-export { StateManager, getStateManager, resetStateManager } from './state.js';
+export { StateManager, getStateManager, getStateManagerAsync, resetStateManager } from './state.js';
+export { GistStateStore } from './gist-state-store.js';
 export { PRMonitor, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
 export { IssueDiscovery } from './issue-discovery.js';
 export { isDocOnlyIssue, applyPerRepoCap, DOC_ONLY_LABELS } from './issue-filtering.js';
@@ -10,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, } from './errors.js';
+export { OssAutopilotError, ConfigurationError, ValidationError, 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-persistence.d.ts

@@ -1,6 +1,6 @@
 /**
  * State persistence layer for the OSS Contribution Agent.
- * Handles file I/O, locking, backup/restore, and v1-to-v2 migration.
+ * Handles file I/O, locking, backup/restore, and schema migration (v1→v2→v3).
  * No module-level mutable state — functions accept/return AgentState objects.
  */
 import { AgentState } from './types.js';
@@ -23,7 +23,19 @@ export declare function releaseLock(lockPath: string): void;
  */
 export declare function atomicWriteFileSync(filePath: string, data: string, mode?: number): void;
 /**
- * Create a fresh state (v2: fresh GitHub fetching).
+ * Migrate state from v1 (local PR tracking) to v2 (fresh GitHub fetching).
+ * Preserves repoScores and config; drops the legacy PR arrays.
+ */
+export declare function migrateV1ToV2(rawState: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Migrate state from v2 to v3.
+ * Drops: events, dailyActivityCounts, config.showHealthCheck, config.scoreThreshold.
+ * Adds: analyzedIssueConversations, learningsExtractedAt on StoredMergedPR/StoredClosedPR.
+ * New optional fields are handled by Zod defaults (undefined/optional).
+ */
+export declare function migrateV2ToV3(rawState: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Create a fresh state (v3).
  * Leverages Zod schema defaults to produce a complete state.
  */
 export declare function createFreshState(): AgentState;

package/dist/core/state-persistence.js

@@ -1,6 +1,6 @@
 /**
  * State persistence layer for the OSS Contribution Agent.
- * Handles file I/O, locking, backup/restore, and v1-to-v2 migration.
+ * Handles file I/O, locking, backup/restore, and schema migration (v1→v2→v3).
  * No module-level mutable state — functions accept/return AgentState objects.
  */
 import * as fs from 'fs';
@@ -101,7 +101,7 @@ export function atomicWriteFileSync(filePath, data, mode) {
  * Migrate state from v1 (local PR tracking) to v2 (fresh GitHub fetching).
  * Preserves repoScores and config; drops the legacy PR arrays.
  */
-function migrateV1ToV2(rawState) {
+export function migrateV1ToV2(rawState) {
     debug(MODULE, 'Migrating state from v1 to v2 (fresh GitHub fetching)...');
     // Extract merged/closed PR arrays from v1 state to seed repo scores.
     // Don't increment counts here as the score may already reflect these PRs.
@@ -131,18 +131,39 @@ function migrateV1ToV2(rawState) {
         activeIssues: rawState.activeIssues || [],
         repoScores,
         config: rawState.config,
-        events: rawState.events || [],
         lastRunAt: new Date().toISOString(),
     };
     debug(MODULE, `Migration complete. Preserved ${Object.keys(repoScores).length} repo scores.`);
     return migratedState;
 }
 /**
- * Create a fresh state (v2: fresh GitHub fetching).
+ * Migrate state from v2 to v3.
+ * Drops: events, dailyActivityCounts, config.showHealthCheck, config.scoreThreshold.
+ * Adds: analyzedIssueConversations, learningsExtractedAt on StoredMergedPR/StoredClosedPR.
+ * New optional fields are handled by Zod defaults (undefined/optional).
+ */
+export function migrateV2ToV3(rawState) {
+    debug(MODULE, 'Migrating state from v2 to v3 (drop dead fields, add learnings tracking)...');
+    // Remove dead fields from root
+    delete rawState.events;
+    delete rawState.dailyActivityCounts;
+    // Remove dead fields from config
+    const config = rawState.config;
+    if (config) {
+        delete config.showHealthCheck;
+        delete config.scoreThreshold;
+    }
+    // Bump version
+    rawState.version = 3;
+    debug(MODULE, 'v2 to v3 migration complete.');
+    return rawState;
+}
+/**
+ * Create a fresh state (v3).
  * Leverages Zod schema defaults to produce a complete state.
  */
 export function createFreshState() {
-    return AgentStateSchema.parse({ version: 2 });
+    return AgentStateSchema.parse({ version: 3 });
 }
 /**
  * Migrate state from legacy ./data/ location to ~/.oss-autopilot/.
@@ -243,9 +264,15 @@ function tryRestoreFromBackup() {
         try {
             const data = fs.readFileSync(backupPath, 'utf-8');
             let raw = JSON.parse(data);
-            // Migrate from v1 to v2 if needed (before schema validation)
-            if (typeof raw === 'object' && raw !== null && raw.version === 1) {
-                raw = migrateV1ToV2(raw);
+            // Chain migrations: v1 → v2 → v3
+            if (typeof raw === 'object' && raw !== null) {
+                const rawObj = raw;
+                if (rawObj.version === 1) {
+                    raw = migrateV1ToV2(rawObj);
+                }
+                if (raw.version === 2) {
+                    raw = migrateV2ToV3(raw);
+                }
             }
             const parsed = AgentStateSchema.safeParse(raw);
             if (parsed.success) {
@@ -286,11 +313,18 @@ export function loadState() {
         if (fs.existsSync(statePath)) {
             const data = fs.readFileSync(statePath, 'utf-8');
             let raw = JSON.parse(data);
-            // Migrate from v1 to v2 if needed (before schema validation)
+            // Chain migrations: v1 → v2 → v3
             let wasMigrated = false;
-            if (typeof raw === 'object' && raw !== null && raw.version === 1) {
-                raw = migrateV1ToV2(raw);
-                wasMigrated = true;
+            if (typeof raw === 'object' && raw !== null) {
+                const rawObj = raw;
+                if (rawObj.version === 1) {
+                    raw = migrateV1ToV2(rawObj);
+                    wasMigrated = true;
+                }
+                if (raw.version === 2) {
+                    raw = migrateV2ToV3(raw);
+                    wasMigrated = true;
+                }
             }
             // Validate through Zod schema (strips unknown keys in memory; stale keys persist on disk until next save)
             const parsed = AgentStateSchema.safeParse(raw);