@oss-autopilot/core 1.8.0 → 1.10.0

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

@@ -32,14 +32,6 @@ export declare const IssueScopeSchema: z.ZodEnum<{
     beginner: "beginner";
     intermediate: "intermediate";
 }>;
-export declare const StateEventTypeSchema: z.ZodEnum<{
-    pr_tracked: "pr_tracked";
-    pr_merged: "pr_merged";
-    pr_closed: "pr_closed";
-    pr_dormant: "pr_dormant";
-    daily_check: "daily_check";
-    comment_posted: "comment_posted";
-}>;
 export declare const RepoSignalsSchema: z.ZodObject<{
     hasActiveMaintainers: z.ZodBoolean;
     isResponsive: z.ZodBoolean;
@@ -61,28 +53,22 @@ export declare const RepoScoreSchema: z.ZodObject<{
     stargazersCount: z.ZodOptional<z.ZodNumber>;
     language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
-export declare const StateEventSchema: z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodEnum<{
-        pr_tracked: "pr_tracked";
-        pr_merged: "pr_merged";
-        pr_closed: "pr_closed";
-        pr_dormant: "pr_dormant";
-        daily_check: "daily_check";
-        comment_posted: "comment_posted";
-    }>;
-    at: z.ZodString;
-    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-}, z.core.$strip>;
 export declare const StoredMergedPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     mergedAt: z.ZodString;
+    learningsExtractedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const StoredClosedPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     closedAt: z.ZodString;
+    learningsExtractedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const AnalyzedIssueConversationSchema: z.ZodObject<{
+    url: z.ZodString;
+    repo: z.ZodString;
+    analyzedAt: z.ZodString;
 }, z.core.$strip>;
 export declare const ContributionGuidelinesSchema: z.ZodObject<{
     branchNamingConvention: z.ZodOptional<z.ZodString>;
@@ -209,10 +195,8 @@ export declare const AgentConfigSchema: z.ZodObject<{
     trustedProjects: z.ZodDefault<z.ZodArray<z.ZodString>>;
     githubUsername: z.ZodDefault<z.ZodString>;
     minRepoScoreThreshold: z.ZodDefault<z.ZodNumber>;
-    scoreThreshold: z.ZodDefault<z.ZodNumber>;
     starredRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
     starredReposLastFetched: z.ZodOptional<z.ZodString>;
-    showHealthCheck: z.ZodOptional<z.ZodBoolean>;
     squashByDefault: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"ask">]>>;
     localRepoScanPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     minStars: z.ZodDefault<z.ZodNumber>;
@@ -229,6 +213,7 @@ export declare const AgentConfigSchema: z.ZodObject<{
         lastActivityAt: z.ZodString;
     }, z.core.$strip>>>;
     issueListPath: z.ZodOptional<z.ZodString>;
+    skippedIssuesPath: z.ZodOptional<z.ZodString>;
     projectCategories: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         nonprofit: "nonprofit";
         devtools: "devtools";
@@ -319,7 +304,8 @@ export declare const DailyDigestSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const AgentStateSchema: z.ZodObject<{
-    version: z.ZodLiteral<2>;
+    version: z.ZodLiteral<3>;
+    gistId: z.ZodOptional<z.ZodString>;
     repoScores: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         repo: z.ZodString;
         score: z.ZodNumber;
@@ -355,10 +341,8 @@ export declare const AgentStateSchema: z.ZodObject<{
         trustedProjects: z.ZodDefault<z.ZodArray<z.ZodString>>;
         githubUsername: z.ZodDefault<z.ZodString>;
         minRepoScoreThreshold: z.ZodDefault<z.ZodNumber>;
-        scoreThreshold: z.ZodDefault<z.ZodNumber>;
         starredRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
         starredReposLastFetched: z.ZodOptional<z.ZodString>;
-        showHealthCheck: z.ZodOptional<z.ZodBoolean>;
         squashByDefault: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"ask">]>>;
         localRepoScanPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
         minStars: z.ZodDefault<z.ZodNumber>;
@@ -375,6 +359,7 @@ export declare const AgentStateSchema: z.ZodObject<{
             lastActivityAt: z.ZodString;
         }, z.core.$strip>>>;
         issueListPath: z.ZodOptional<z.ZodString>;
+        skippedIssuesPath: z.ZodOptional<z.ZodString>;
         projectCategories: z.ZodDefault<z.ZodArray<z.ZodEnum<{
             nonprofit: "nonprofit";
             devtools: "devtools";
@@ -385,19 +370,6 @@ export declare const AgentStateSchema: z.ZodObject<{
         }>>>;
         preferredOrgs: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
-    events: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        type: z.ZodEnum<{
-            pr_tracked: "pr_tracked";
-            pr_merged: "pr_merged";
-            pr_closed: "pr_closed";
-            pr_dormant: "pr_dormant";
-            daily_check: "daily_check";
-            comment_posted: "comment_posted";
-        }>;
-        at: z.ZodString;
-        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    }, z.core.$strip>>>;
     lastRunAt: z.ZodDefault<z.ZodString>;
     lastDigestAt: z.ZodOptional<z.ZodString>;
     lastDigest: z.ZodOptional<z.ZodObject<{
@@ -452,7 +424,6 @@ export declare const AgentStateSchema: z.ZodObject<{
     monthlyMergedCounts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     monthlyClosedCounts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     monthlyOpenedCounts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
-    dailyActivityCounts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     localRepoCache: z.ZodOptional<z.ZodObject<{
         repos: z.ZodRecord<z.ZodString, z.ZodObject<{
             path: z.ZodString;
@@ -466,11 +437,18 @@ export declare const AgentStateSchema: z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         mergedAt: z.ZodString;
+        learningsExtractedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     closedPRs: z.ZodOptional<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         closedAt: z.ZodString;
+        learningsExtractedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    analyzedIssueConversations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        repo: z.ZodString;
+        analyzedAt: z.ZodString;
     }, z.core.$strip>>>;
     activeIssues: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodNumber;
@@ -521,12 +499,11 @@ 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 StateEventType = z.infer<typeof StateEventTypeSchema>;
 export type RepoSignals = z.infer<typeof RepoSignalsSchema>;
 export type RepoScore = z.infer<typeof RepoScoreSchema>;
-export type StateEvent = z.infer<typeof StateEventSchema>;
 export type StoredMergedPR = z.infer<typeof StoredMergedPRSchema>;
 export type StoredClosedPR = z.infer<typeof StoredClosedPRSchema>;
+export type AnalyzedIssueConversation = z.infer<typeof AnalyzedIssueConversationSchema>;
 export type ContributionGuidelines = z.infer<typeof ContributionGuidelinesSchema>;
 export type IssueVettingResult = z.infer<typeof IssueVettingResultSchema>;
 export type TrackedIssue = z.infer<typeof TrackedIssueSchema>;

package/dist/core/state-schema.js

@@ -21,14 +21,6 @@ export const ProjectCategorySchema = z.enum([
     'education',
 ]);
 export const IssueScopeSchema = z.enum(['beginner', 'intermediate', 'advanced']);
-export const StateEventTypeSchema = z.enum([
-    'pr_tracked',
-    'pr_merged',
-    'pr_closed',
-    'pr_dormant',
-    'daily_check',
-    'comment_posted',
-]);
 // ── 2. Leaf schemas ──────────────────────────────────────────────────
 export const RepoSignalsSchema = z.object({
     hasActiveMaintainers: z.boolean(),
@@ -47,21 +39,22 @@ export const RepoScoreSchema = z.object({
     stargazersCount: z.number().optional(),
     language: z.string().nullable().optional(),
 });
-export const StateEventSchema = z.object({
-    id: z.string(),
-    type: StateEventTypeSchema,
-    at: z.string(),
-    data: z.record(z.string(), z.unknown()),
-});
 export const StoredMergedPRSchema = z.object({
     url: z.string(),
     title: z.string(),
     mergedAt: z.string(),
+    learningsExtractedAt: z.string().optional(),
 });
 export const StoredClosedPRSchema = z.object({
     url: z.string(),
     title: z.string(),
     closedAt: z.string(),
+    learningsExtractedAt: z.string().optional(),
+});
+export const AnalyzedIssueConversationSchema = z.object({
+    url: z.string(),
+    repo: z.string(),
+    analyzedAt: z.string(),
 });
 // ── 3. Contribution schemas ──────────────────────────────────────────
 export const ContributionGuidelinesSchema = z.object({
@@ -135,10 +128,8 @@ export const AgentConfigSchema = z.object({
     trustedProjects: z.array(z.string()).default([]),
     githubUsername: z.string().default(''),
     minRepoScoreThreshold: z.number().default(4),
-    scoreThreshold: z.number().int().min(1).max(10).default(6),
     starredRepos: z.array(z.string()).default([]),
     starredReposLastFetched: z.string().optional(),
-    showHealthCheck: z.boolean().optional(),
     squashByDefault: z.union([z.boolean(), z.literal('ask')]).default(true),
     localRepoScanPaths: z.array(z.string()).optional(),
     minStars: z.number().default(50),
@@ -148,6 +139,7 @@ export const AgentConfigSchema = z.object({
     dismissedIssues: z.record(z.string(), z.string()).default({}),
     statusOverrides: z.record(z.string(), StatusOverrideSchema).optional(),
     issueListPath: z.string().optional(),
+    skippedIssuesPath: z.string().optional(),
     projectCategories: z.array(ProjectCategorySchema).default([]),
     preferredOrgs: z.array(z.string()).default([]),
 });
@@ -197,19 +189,19 @@ export const DailyDigestSchema = z.object({
 });
 // ── 8. Root schema ───────────────────────────────────────────────────
 export const AgentStateSchema = z.object({
-    version: z.literal(2),
+    version: z.literal(3),
+    gistId: z.string().optional(),
     repoScores: z.record(z.string(), RepoScoreSchema).default({}),
     config: AgentConfigSchema.default(() => AgentConfigSchema.parse({})),
-    events: z.array(StateEventSchema).default([]),
     lastRunAt: z.string().default(() => new Date().toISOString()),
     lastDigestAt: z.string().optional(),
     lastDigest: DailyDigestSchema.optional(),
     monthlyMergedCounts: z.record(z.string(), z.number()).optional(),
     monthlyClosedCounts: z.record(z.string(), z.number()).optional(),
     monthlyOpenedCounts: z.record(z.string(), z.number()).optional(),
-    dailyActivityCounts: z.record(z.string(), z.number()).optional(),
     localRepoCache: LocalRepoCacheSchema.optional(),
     mergedPRs: z.array(StoredMergedPRSchema).optional(),
     closedPRs: z.array(StoredClosedPRSchema).optional(),
+    analyzedIssueConversations: z.array(AnalyzedIssueConversationSchema).optional(),
     activeIssues: z.array(TrackedIssueSchema).default([]),
 });

package/dist/core/state.d.ts

@@ -3,23 +3,26 @@
  * Thin coordinator that delegates persistence to state-persistence.ts
  * and scoring logic to repo-score-manager.ts.
  */
-import { AgentState, TrackedIssue, RepoScore, RepoScoreUpdate, StateEvent, StateEventType, DailyDigest, LocalRepoCache, StatusOverride, FetchedPRStatus, StoredMergedPR, StoredClosedPR } from './types.js';
+import { AgentState, TrackedIssue, RepoScore, RepoScoreUpdate, DailyDigest, LocalRepoCache, StatusOverride, FetchedPRStatus, StoredMergedPR, StoredClosedPR } from './types.js';
 import type { Stats } from './repo-score-manager.js';
+import { GistStateStore } from './gist-state-store.js';
 export { acquireLock, releaseLock, atomicWriteFileSync } from './state-persistence.js';
 export type { Stats } from './repo-score-manager.js';
 /**
  * Singleton manager for persistent agent state stored in ~/.oss-autopilot/state.json.
  *
  * Delegates file I/O to state-persistence.ts and scoring logic to repo-score-manager.ts.
- * Retains lightweight CRUD operations for config, events, issues, shelving, dismissal,
+ * Retains lightweight CRUD operations for config, issues, shelving, dismissal,
  * and status overrides.
  */
 export declare class StateManager {
-    private state;
-    private readonly inMemoryOnly;
+    protected state: AgentState;
+    protected inMemoryOnly: boolean;
     private lastLoadedMtimeMs;
     private _batching;
     private _batchDirty;
+    protected gistStore: GistStateStore | null;
+    protected gistDegraded: boolean;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -27,6 +30,15 @@ export declare class StateManager {
      *   Defaults to false (normal persistent mode).
      */
     constructor(inMemoryOnly?: boolean);
+    /**
+     * Async factory that creates a StateManager backed by a GitHub Gist.
+     *
+     * The regular constructor is synchronous (for backwards-compat), but Gist
+     * bootstrapping requires network calls, so this factory is async.
+     *
+     * @param token - GitHub personal access token with `gist` scope
+     */
+    static createWithGist(token: string): Promise<StateManager>;
     /**
      * Attempt PR count reconciliation, logging a warning on failure.
      * Called after every state load from disk.
@@ -58,8 +70,17 @@ export declare class StateManager {
     /**
      * Persist the current state to disk, creating a timestamped backup of the previous
      * state file first. In in-memory mode, only updates `lastRunAt` without any file I/O.
+     *
+     * In Gist mode, writes to a local cache file (not the main state file) so the Gist
+     * remains the source of truth. Use `checkpoint()` to push state to the Gist.
      */
     save(): void;
+    /** Push current state to Gist (async). Call at well-defined moments (end of daily, after claim). */
+    checkpoint(): Promise<boolean>;
+    /** Whether this StateManager is backed by a Gist. */
+    isGistMode(): boolean;
+    /** Whether the Gist is in degraded mode (using local cache fallback). */
+    isGistDegraded(): boolean;
     /**
      * Get the current state as a read-only snapshot.
      */
@@ -89,11 +110,6 @@ export declare class StateManager {
      * @param counts - Monthly opened PR counts keyed by YYYY-MM
      */
     setMonthlyOpenedCounts(counts: Record<string, number>): void;
-    /**
-     * Update daily activity counts for dashboard display.
-     * @param counts - Daily activity counts keyed by YYYY-MM-DD
-     */
-    setDailyActivityCounts(counts: Record<string, number>): void;
     /**
      * Update the local repository cache.
      * @param cache - Local repository cache mapping repo names to paths
@@ -122,26 +138,6 @@ export declare class StateManager {
      * @param config - Partial config object to merge
      */
     updateConfig(config: Partial<AgentState['config']>): void;
-    /**
-     * Append a new event to the event log and auto-persist.
-     * Events are capped at 1000 to prevent unbounded growth.
-     * @param type - The event type identifier
-     * @param data - Arbitrary event payload
-     */
-    appendEvent(type: StateEventType, data: Record<string, unknown>): void;
-    /**
-     * Filter events by type.
-     * @param type - The event type to filter by
-     * @returns Events matching the given type
-     */
-    getEventsByType(type: StateEventType): StateEvent[];
-    /**
-     * Filter events within a date range.
-     * @param since - Start of range (inclusive)
-     * @param until - End of range (inclusive), defaults to now
-     * @returns Events within the date range
-     */
-    getEventsInRange(since: Date, until?: Date): StateEvent[];
     /**
      * Track a new issue. No-op if the issue URL is already tracked.
      * @param issue - The issue to track
@@ -287,6 +283,19 @@ export declare class StateManager {
  * ```
  */
 export declare function getStateManager(): StateManager;
+/**
+ * Get or create a StateManager with Gist-backed persistence.
+ * If a StateManager already exists (from sync init), returns it.
+ * If a token is provided and no manager exists, creates one with Gist backing.
+ * Falls back to sync initialization if no token is provided.
+ *
+ * **Important:** This must be called (and awaited) before any command runs for
+ * Gist mode to be active. It pre-sets the singleton so that subsequent
+ * `getStateManager()` calls return the Gist-backed instance. If this is not
+ * called first, `getStateManager()` will lazily create a local-only
+ * StateManager and Gist checkpoints will be no-ops.
+ */
+export declare function getStateManagerAsync(token?: string): Promise<StateManager>;
 /**
  * Reset the singleton StateManager instance to null. Intended for test isolation.
  */

package/dist/core/state.js

@@ -3,19 +3,20 @@
  * Thin coordinator that delegates persistence to state-persistence.ts
  * and scoring logic to repo-score-manager.ts.
  */
-import { loadState, saveState, reloadStateIfChanged, createFreshState } from './state-persistence.js';
+import * as fs from 'fs';
+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 { GistStateStore } from './gist-state-store.js';
+import { getStatePath, getStateCachePath } from './utils.js';
 export { acquireLock, releaseLock, atomicWriteFileSync } from './state-persistence.js';
 const MODULE = 'state';
-// Maximum number of events to retain in the event log
-const MAX_EVENTS = 1000;
 /**
  * Singleton manager for persistent agent state stored in ~/.oss-autopilot/state.json.
  *
  * Delegates file I/O to state-persistence.ts and scoring logic to repo-score-manager.ts.
- * Retains lightweight CRUD operations for config, events, issues, shelving, dismissal,
+ * Retains lightweight CRUD operations for config, issues, shelving, dismissal,
  * and status overrides.
  */
 export class StateManager {
@@ -24,6 +25,8 @@ export class StateManager {
     lastLoadedMtimeMs = 0;
     _batching = false;
     _batchDirty = false;
+    gistStore = null;
+    gistDegraded = false;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -42,6 +45,53 @@ export class StateManager {
             this.tryReconcilePRCounts();
         }
     }
+    /**
+     * Async factory that creates a StateManager backed by a GitHub Gist.
+     *
+     * The regular constructor is synchronous (for backwards-compat), but Gist
+     * bootstrapping requires network calls, so this factory is async.
+     *
+     * @param token - GitHub personal access token with `gist` scope
+     */
+    static async createWithGist(token) {
+        // Dynamic import to avoid circular dependencies
+        const { getOctokit } = await import('./github.js');
+        const octokit = getOctokit(token);
+        const gistStore = new GistStateStore(octokit);
+        // Check if local state exists for migration
+        const statePath = getStatePath();
+        let result;
+        if (fs.existsSync(statePath)) {
+            // Existing user: load local state and migrate it into the Gist if no Gist exists yet.
+            const localStateResult = loadState();
+            const migrationResult = await gistStore.bootstrapWithMigration(localStateResult.state);
+            result = migrationResult;
+            // If a new Gist was just created from local state, rename the local file
+            // so it no longer competes as the source of truth on future startups.
+            if (migrationResult.migrated) {
+                try {
+                    const preGistPath = statePath + '.pre-gist-migration';
+                    fs.renameSync(statePath, preGistPath);
+                    debug(MODULE, `Renamed ${statePath} to ${preGistPath} after Gist migration`);
+                }
+                catch (err) {
+                    warn(MODULE, `Failed to rename state.json after Gist migration: ${err}`);
+                }
+            }
+        }
+        else {
+            result = await gistStore.bootstrap();
+        }
+        const manager = new StateManager(true); // start in-memory
+        manager.state = result.state;
+        if (result.gistId) {
+            manager.state.gistId = result.gistId;
+        }
+        manager.gistStore = gistStore;
+        manager.gistDegraded = result.degraded ?? false;
+        manager.inMemoryOnly = false; // re-enable persistence
+        return manager;
+    }
     /**
      * Attempt PR count reconciliation, logging a warning on failure.
      * Called after every state load from disk.
@@ -119,14 +169,44 @@ export class StateManager {
     /**
      * Persist the current state to disk, creating a timestamped backup of the previous
      * state file first. In in-memory mode, only updates `lastRunAt` without any file I/O.
+     *
+     * In Gist mode, writes to a local cache file (not the main state file) so the Gist
+     * remains the source of truth. Use `checkpoint()` to push state to the Gist.
      */
     save() {
         this.state.lastRunAt = new Date().toISOString();
         if (this.inMemoryOnly) {
             return;
         }
+        if (this.gistStore) {
+            // In Gist mode, write to local cache (not main state file).
+            // The Gist is the source of truth; local cache is for fallback.
+            try {
+                atomicWriteFileSync(getStateCachePath(), JSON.stringify(this.state, null, 2), 0o600);
+            }
+            catch {
+                // Best-effort cache write
+            }
+            return;
+        }
+        // Local file mode (existing behavior)
         this.lastLoadedMtimeMs = saveState(this.state);
     }
+    /** Push current state to Gist (async). Call at well-defined moments (end of daily, after claim). */
+    async checkpoint() {
+        if (!this.gistStore)
+            return true; // not in Gist mode
+        this.gistStore.setState(JSON.stringify(this.state, null, 2));
+        return this.gistStore.push();
+    }
+    /** Whether this StateManager is backed by a Gist. */
+    isGistMode() {
+        return this.gistStore !== null;
+    }
+    /** Whether the Gist is in degraded mode (using local cache fallback). */
+    isGistDegraded() {
+        return this.gistDegraded;
+    }
     /**
      * Get the current state as a read-only snapshot.
      */
@@ -140,6 +220,8 @@ export class StateManager {
     reloadIfChanged() {
         if (this.inMemoryOnly)
             return false;
+        if (this.gistStore)
+            return false; // Gist is the source of truth; skip local file reload
         const result = reloadStateIfChanged(this.lastLoadedMtimeMs);
         if (!result)
             return false;
@@ -182,14 +264,6 @@ export class StateManager {
         this.state.monthlyOpenedCounts = counts;
         this.autoSave();
     }
-    /**
-     * Update daily activity counts for dashboard display.
-     * @param counts - Daily activity counts keyed by YYYY-MM-DD
-     */
-    setDailyActivityCounts(counts) {
-        this.state.dailyActivityCounts = counts;
-        this.autoSave();
-    }
     /**
      * Update the local repository cache.
      * @param cache - Local repository cache mapping repo names to paths
@@ -261,47 +335,6 @@ export class StateManager {
         this.state.config = { ...this.state.config, ...config };
         this.autoSave();
     }
-    // === Event Logging ===
-    /**
-     * Append a new event to the event log and auto-persist.
-     * Events are capped at 1000 to prevent unbounded growth.
-     * @param type - The event type identifier
-     * @param data - Arbitrary event payload
-     */
-    appendEvent(type, data) {
-        const event = {
-            id: `evt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
-            type,
-            at: new Date().toISOString(),
-            data,
-        };
-        this.state.events.push(event);
-        // Cap the events array to prevent unbounded growth
-        if (this.state.events.length > MAX_EVENTS) {
-            this.state.events = this.state.events.slice(-MAX_EVENTS);
-        }
-        this.autoSave();
-    }
-    /**
-     * Filter events by type.
-     * @param type - The event type to filter by
-     * @returns Events matching the given type
-     */
-    getEventsByType(type) {
-        return this.state.events.filter((e) => e.type === type);
-    }
-    /**
-     * Filter events within a date range.
-     * @param since - Start of range (inclusive)
-     * @param until - End of range (inclusive), defaults to now
-     * @returns Events within the date range
-     */
-    getEventsInRange(since, until = new Date()) {
-        return this.state.events.filter((e) => {
-            const eventTime = new Date(e.at);
-            return eventTime >= since && eventTime <= until;
-        });
-    }
     // === Issue Management ===
     /**
      * Track a new issue. No-op if the issue URL is already tracked.
@@ -590,6 +623,7 @@ export class StateManager {
 }
 // Singleton instance
 let stateManager = null;
+let asyncManagerPromise = null;
 /**
  * Get the singleton StateManager instance, creating it on first call.
  * @returns The shared StateManager instance
@@ -609,9 +643,43 @@ export function getStateManager() {
     }
     return stateManager;
 }
+/**
+ * Get or create a StateManager with Gist-backed persistence.
+ * If a StateManager already exists (from sync init), returns it.
+ * If a token is provided and no manager exists, creates one with Gist backing.
+ * Falls back to sync initialization if no token is provided.
+ *
+ * **Important:** This must be called (and awaited) before any command runs for
+ * Gist mode to be active. It pre-sets the singleton so that subsequent
+ * `getStateManager()` calls return the Gist-backed instance. If this is not
+ * called first, `getStateManager()` will lazily create a local-only
+ * StateManager and Gist checkpoints will be no-ops.
+ */
+export async function getStateManagerAsync(token) {
+    if (stateManager)
+        return stateManager;
+    if (asyncManagerPromise)
+        return asyncManagerPromise;
+    if (token) {
+        asyncManagerPromise = StateManager.createWithGist(token)
+            .then((mgr) => {
+            stateManager = mgr;
+            asyncManagerPromise = null;
+            return mgr;
+        })
+            .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
+        });
+        return asyncManagerPromise;
+    }
+    return getStateManager();
+}
 /**
  * Reset the singleton StateManager instance to null. Intended for test isolation.
  */
 export function resetStateManager() {
     stateManager = null;
+    asyncManagerPromise = null;
 }

package/dist/core/types.d.ts

@@ -2,7 +2,7 @@
  * Core types for the Open Source Contribution Agent
  */
 import type { FetchedPRStatus, RepoSignals, TrackedIssue, IssueVettingResult, IssueScope, AgentConfig, AgentState } from './state-schema.js';
-export type { IssueStatus, FetchedPRStatus, ProjectCategory, IssueScope, StateEventType, RepoSignals, RepoScore, StateEvent, StoredMergedPR, StoredClosedPR, ContributionGuidelines, IssueVettingResult, TrackedIssue, ShelvedPRRef, StatusOverride, AgentConfig, LocalRepoCache, ClosedPR, MergedPR, DailyDigest, AgentState, } from './state-schema.js';
+export type { IssueStatus, FetchedPRStatus, ProjectCategory, IssueScope, RepoSignals, RepoScore, StoredMergedPR, StoredClosedPR, AnalyzedIssueConversation, ContributionGuidelines, IssueVettingResult, TrackedIssue, ShelvedPRRef, StatusOverride, AgentConfig, LocalRepoCache, ClosedPR, MergedPR, DailyDigest, AgentState, } from './state-schema.js';
 /** CI pipeline status for a PR's latest commit. */
 export type CIStatus = 'passing' | 'failing' | 'pending' | 'unknown';
 /**
@@ -233,7 +233,7 @@ interface CommentedIssueWithoutResponse extends CommentedIssueBase {
 export type CommentedIssue = CommentedIssueWithResponse | CommentedIssueWithoutResponse;
 /** Default configuration applied to new state files. All fields can be overridden via `/setup-oss`. */
 export declare const DEFAULT_CONFIG: AgentConfig;
-/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v2 architecture. */
+/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v3 architecture. */
 export declare const INITIAL_STATE: AgentState;
 export declare const PROJECT_CATEGORIES: ("nonprofit" | "devtools" | "infrastructure" | "web-frameworks" | "data-ml" | "education")[];
 export declare const ISSUE_SCOPES: ("advanced" | "beginner" | "intermediate")[];

package/dist/core/types.js

@@ -12,8 +12,8 @@ export function isBelowMinStars(stargazersCount, minStars) {
 // ── Schema-derived constants ─────────────────────────────────────────
 /** Default configuration applied to new state files. All fields can be overridden via `/setup-oss`. */
 export const DEFAULT_CONFIG = AgentConfigSchema.parse({});
-/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v2 architecture. */
-export const INITIAL_STATE = AgentStateSchema.parse({ version: 2 });
+/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v3 architecture. */
+export const INITIAL_STATE = AgentStateSchema.parse({ version: 3 });
 // ── Const arrays (derived from Zod schemas for runtime iteration) ────
 export const PROJECT_CATEGORIES = ProjectCategorySchema.options;
 export const ISSUE_SCOPES = IssueScopeSchema.options;