@oss-autopilot/core 1.15.1 → 1.16.0

package/dist/cli.js

@@ -50,22 +50,10 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
             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);
-        }
+        // Shared helper peeks at the state file and only pre-sets the singleton
+        // when Gist mode is the configured persistence (#1000).
+        const { ensureGistPersistence } = await import('./core/index.js');
+        await ensureGistPersistence(token);
     }
 });
 // First-run detection: if no subcommand was provided and no state file exists,

package/dist/commands/daily.d.ts

@@ -33,6 +33,15 @@ export interface DailyCheckResult {
     repoGroups: RepoGroup[];
     failures: PRCheckFailure[];
 }
+/**
+ * Convert a full DailyCheckResult to the compact DailyOutput for JSON serialization (#287).
+ * Deduplicates PR objects: category arrays become PR URL references,
+ * full objects live only in digest.openPRs. Reduces JSON payload size ~60-70%.
+ *
+ * Exported for the `daily --json` contract test (#986), which pins this
+ * shape transformation without spinning up the full fetch pipeline.
+ */
+export declare function toDailyOutput(result: DailyCheckResult): DailyOutput;
 /**
  * Core daily check logic, extracted for reuse by the startup command.
  * Fetches all open PRs, updates state, and returns structured output.

package/dist/commands/daily.js

@@ -370,8 +370,11 @@ function generateDigestOutput(digest, activePRs, shelvedPRs, commentedIssues, fa
  * Convert a full DailyCheckResult to the compact DailyOutput for JSON serialization (#287).
  * Deduplicates PR objects: category arrays become PR URL references,
  * full objects live only in digest.openPRs. Reduces JSON payload size ~60-70%.
+ *
+ * Exported for the `daily --json` contract test (#986), which pins this
+ * shape transformation without spinning up the full fetch pipeline.
  */
-function toDailyOutput(result) {
+export function toDailyOutput(result) {
     return {
         digest: deduplicateDigest(result.digest),
         capacity: result.capacity,

package/dist/commands/dashboard-data.d.ts

@@ -49,6 +49,15 @@ export interface DashboardJsonData {
     offline?: boolean;
     lastUpdated?: string;
 }
+/** Action types the dashboard can request via POST /api/action. */
+export type DashboardActionType = 'move' | 'dismiss_issue_response';
+/** Body shape for POST /api/action — single source for both server validation and SPA client (#998). */
+export interface ActionRequest {
+    action: DashboardActionType;
+    url: string;
+    /** Target state for move action. */
+    target?: 'attention' | 'waiting' | 'shelved' | 'auto';
+}
 export declare function buildDashboardStats(digest: DailyDigest, state: Readonly<AgentState>, storedMergedCount?: number, storedClosedCount?: number): DashboardStats;
 /**
  * Merge fresh API counts into existing stored counts.

package/dist/commands/dashboard-server.js

@@ -251,7 +251,9 @@ export async function startDashboardServer(options) {
                     }
                     catch (error) {
                         warn(MODULE, `Failed to rebuild dashboard data after state reload: ${errorMessage(error)}`);
-                        // Intentional: serve previous cachedJsonData rather than returning 500
+                        // Serve previous cachedJsonData rather than returning 500.
+                        // Signal staleness via response header so clients can detect the degraded mode (#994).
+                        res.setHeader('X-Dashboard-Stale', '1');
                     }
                 }
                 sendJson(res, 200, cachedJsonData);

package/dist/commands/index.d.ts

@@ -22,7 +22,7 @@ export { runStartup } from './startup.js';
 /** Return contribution statistics (merge rate, PR counts, repo breakdown) from local state. */
 export { runStatus } from './status.js';
 /** Search GitHub for contributable issues using multi-strategy discovery. */
-export { runSearch } from './search.js';
+export { runSearch, MAX_SEARCH_RESULTS } from './search.js';
 /** Vet a single GitHub issue for claimability (open, unassigned, no linked PRs, repo health). */
 export { runVet } from './vet.js';
 /** Re-vet all available issues in a curated issue list for freshness. */
@@ -71,6 +71,7 @@ export { runCheckIntegration } from './check-integration.js';
 export { runDetectFormatters } from './detect-formatters.js';
 /** Scan for locally cloned repos. */
 export { runLocalRepos } from './local-repos.js';
+export type { DashboardJsonData, DashboardStats, DashboardActionType, ActionRequest } from './dashboard-data.js';
 export type { ErrorCode } from '../formatters/json.js';
 export type { DailyOutput, SearchOutput, StartupOutput, StatusOutput, TrackOutput } from '../formatters/json.js';
 export type { VetOutput, CommentsOutput, PostOutput, ClaimOutput, VetListOutput, VetListItemStatus, } from '../formatters/json.js';

package/dist/commands/index.js

@@ -23,7 +23,7 @@ export { runStartup } from './startup.js';
 /** Return contribution statistics (merge rate, PR counts, repo breakdown) from local state. */
 export { runStatus } from './status.js';
 /** Search GitHub for contributable issues using multi-strategy discovery. */
-export { runSearch } from './search.js';
+export { runSearch, MAX_SEARCH_RESULTS } from './search.js';
 /** Vet a single GitHub issue for claimability (open, unassigned, no linked PRs, repo health). */
 export { runVet } from './vet.js';
 /** Re-vet all available issues in a curated issue list for freshness. */

package/dist/commands/scout-bridge.js

@@ -4,6 +4,7 @@
  */
 import { createScout } from '@oss-scout/core';
 import { getStateManager, requireGitHubToken } from '../core/index.js';
+import { loadSkippedIssues } from './skip-file-parser.js';
 /**
  * Build a ScoutState from the current AgentState.
  * Maps oss-autopilot's config and state fields to oss-scout's state format.
@@ -52,7 +53,7 @@ export function buildScoutState() {
             openedAt: pr.createdAt,
         })),
         savedResults: [],
-        skippedIssues: [],
+        skippedIssues: loadSkippedIssues(config.skippedIssuesPath),
         lastRunAt: state.lastRunAt,
     };
 }

package/dist/commands/search.d.ts

@@ -4,6 +4,12 @@
  */
 import { type SearchOutput } from '../formatters/json.js';
 export { type SearchOutput } from '../formatters/json.js';
+/**
+ * Hard cap on issue-search result count. Shared between CLI (`cli-registry.ts`),
+ * MCP tool (`tools.ts`), and MCP prompt (`prompts.ts`) so a future adjustment
+ * lands in one place instead of three (#1002).
+ */
+export declare const MAX_SEARCH_RESULTS = 100;
 interface SearchOptions {
     maxResults: number;
 }

package/dist/commands/search.js

@@ -4,6 +4,12 @@
  */
 import { createAutopilotScout } from './scout-bridge.js';
 import { getStateManager } from '../core/index.js';
+/**
+ * Hard cap on issue-search result count. Shared between CLI (`cli-registry.ts`),
+ * MCP tool (`tools.ts`), and MCP prompt (`prompts.ts`) so a future adjustment
+ * lands in one place instead of three (#1002).
+ */
+export const MAX_SEARCH_RESULTS = 100;
 /**
  * Search GitHub for contributable issues using multi-phase discovery.
  *

package/dist/commands/skip-add.d.ts

@@ -0,0 +1,25 @@
+export interface SkipAddOptions {
+    issueUrl: string;
+    /** Override the configured `skippedIssuesPath`. */
+    skipFilePath?: string;
+    /** Injected for deterministic tests. Defaults to `new Date()`. */
+    now?: Date;
+}
+export interface SkipAddOutput {
+    added: boolean;
+    alreadyPresent: boolean;
+    url: string;
+    path: string;
+    /** Populated only when an entry was appended. */
+    date?: string;
+}
+/**
+ * Append an issue URL to the skipped-issues file.
+ *
+ * Creates the file with the standard header if it doesn't exist. If the URL
+ * is already present (per the skip-file-parser's view of the file), this is
+ * a no-op and returns `alreadyPresent: true`.
+ *
+ * @throws when no path can be resolved or the URL isn't a GitHub issue/PR URL.
+ */
+export declare function runSkipAdd(options: SkipAddOptions): SkipAddOutput;

package/dist/commands/skip-add.js

@@ -0,0 +1,48 @@
+import * as fs from 'fs';
+import { loadSkippedIssues } from './skip-file-parser.js';
+import { getStateManager } from '../core/index.js';
+// Keep in sync with GITHUB_URL_RE in skip-file-parser.ts.
+const GITHUB_URL_RE = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/(?:issues|pull)\/(\d+)(?:[/?#].*)?$/;
+const FILE_HEADER = '# Skipped Issues — auto-culled after 90 days\n# Format: YYYY-MM-DD URL\n\n';
+function formatUtcDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * Append an issue URL to the skipped-issues file.
+ *
+ * Creates the file with the standard header if it doesn't exist. If the URL
+ * is already present (per the skip-file-parser's view of the file), this is
+ * a no-op and returns `alreadyPresent: true`.
+ *
+ * @throws when no path can be resolved or the URL isn't a GitHub issue/PR URL.
+ */
+export function runSkipAdd(options) {
+    const skipFilePath = options.skipFilePath ?? getStateManager().getState().config.skippedIssuesPath;
+    if (!skipFilePath) {
+        throw new Error('No skipped-issues path configured. Set one via `oss-autopilot config --set skippedIssuesPath=<path>` or pass --path.');
+    }
+    if (!GITHUB_URL_RE.test(options.issueUrl)) {
+        throw new Error(`Invalid GitHub issue or PR URL: ${options.issueUrl}`);
+    }
+    const existing = loadSkippedIssues(skipFilePath);
+    if (existing.some((entry) => entry.url === options.issueUrl)) {
+        return {
+            added: false,
+            alreadyPresent: true,
+            url: options.issueUrl,
+            path: skipFilePath,
+        };
+    }
+    if (!fs.existsSync(skipFilePath)) {
+        fs.writeFileSync(skipFilePath, FILE_HEADER);
+    }
+    const date = formatUtcDate(options.now ?? new Date());
+    fs.appendFileSync(skipFilePath, `${date} ${options.issueUrl}\n`);
+    return {
+        added: true,
+        alreadyPresent: false,
+        url: options.issueUrl,
+        path: skipFilePath,
+        date,
+    };
+}

package/dist/commands/skip-file-parser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Parser for the skipped-issues markdown file (#989).
+ *
+ * The file format is one entry per line:
+ *   2026-04-15 https://github.com/owner/repo/issues/123
+ * Lines starting with `#` and blank lines are ignored.
+ *
+ * Produces SkippedIssue entries that plug directly into oss-scout's ScoutState
+ * so the search engine filters already-skipped URLs out of results.
+ */
+import type { SkippedIssue } from '@oss-scout/core';
+/**
+ * Parse the raw text of a skipped-issues file into SkippedIssue entries.
+ * Pure function — no I/O. Malformed lines are warned and skipped; the rest
+ * pass through unchanged.
+ */
+export declare function parseSkippedIssuesContent(content: string): SkippedIssue[];
+/**
+ * Read the skipped-issues file from disk and parse it.
+ * Returns `[]` when:
+ *   - `path` is undefined or empty,
+ *   - the file does not exist,
+ *   - the file cannot be read (a warning is logged).
+ */
+export declare function loadSkippedIssues(path: string | undefined): SkippedIssue[];

package/dist/commands/skip-file-parser.js

@@ -0,0 +1,92 @@
+/**
+ * Parser for the skipped-issues markdown file (#989).
+ *
+ * The file format is one entry per line:
+ *   2026-04-15 https://github.com/owner/repo/issues/123
+ * Lines starting with `#` and blank lines are ignored.
+ *
+ * Produces SkippedIssue entries that plug directly into oss-scout's ScoutState
+ * so the search engine filters already-skipped URLs out of results.
+ */
+import * as fs from 'fs';
+import { warn } from '../core/logger.js';
+import { errorMessage } from '../core/errors.js';
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const GITHUB_URL_RE = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/(?:issues|pull)\/(\d+)(?:[/?#].*)?$/;
+/**
+ * Parse the raw text of a skipped-issues file into SkippedIssue entries.
+ * Pure function — no I/O. Malformed lines are warned and skipped; the rest
+ * pass through unchanged.
+ */
+export function parseSkippedIssuesContent(content) {
+    const results = [];
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const lineNumber = i + 1;
+        const line = lines[i].trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        // Split on first whitespace run: "YYYY-MM-DD <url>"
+        const match = line.match(/^(\S+)\s+(\S+)\s*$/);
+        if (!match) {
+            warn('skip-file-parser', `Line ${lineNumber}: malformed (expected "<date> <url>"): ${line}`);
+            continue;
+        }
+        const [, dateStr, url] = match;
+        if (!DATE_RE.test(dateStr)) {
+            warn('skip-file-parser', `Line ${lineNumber}: invalid date format (expected YYYY-MM-DD): ${line}`);
+            continue;
+        }
+        const dateMs = Date.parse(`${dateStr}T00:00:00.000Z`);
+        if (Number.isNaN(dateMs)) {
+            warn('skip-file-parser', `Line ${lineNumber}: unparseable date: ${line}`);
+            continue;
+        }
+        // Guard against JS Date normalization — Date.parse silently shifts
+        // invalid calendar dates (e.g. 2026-02-30 → 2026-03-02). Without this
+        // round-trip check the entry would be stored under the wrong date and
+        // scout's 90-day cull would run against a shifted value.
+        const roundTrip = new Date(dateMs).toISOString().slice(0, 10);
+        if (roundTrip !== dateStr) {
+            warn('skip-file-parser', `Line ${lineNumber}: invalid calendar date ${dateStr} (would be normalized to ${roundTrip}): ${line}`);
+            continue;
+        }
+        const urlMatch = url.match(GITHUB_URL_RE);
+        if (!urlMatch) {
+            warn('skip-file-parser', `Line ${lineNumber}: non-GitHub-issue URL: ${line}`);
+            continue;
+        }
+        const [, repo, numberStr] = urlMatch;
+        const number = Number.parseInt(numberStr, 10);
+        results.push({
+            url,
+            repo,
+            number,
+            title: '',
+            skippedAt: new Date(dateMs).toISOString(),
+        });
+    }
+    return results;
+}
+/**
+ * Read the skipped-issues file from disk and parse it.
+ * Returns `[]` when:
+ *   - `path` is undefined or empty,
+ *   - the file does not exist,
+ *   - the file cannot be read (a warning is logged).
+ */
+export function loadSkippedIssues(path) {
+    if (!path)
+        return [];
+    if (!fs.existsSync(path))
+        return [];
+    let content;
+    try {
+        content = fs.readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        warn('skip-file-parser', `Failed to read skipped-issues file at ${path}: ${errorMessage(err)}`);
+        return [];
+    }
+    return parseSkippedIssuesContent(content);
+}

package/dist/commands/startup.js

@@ -109,8 +109,11 @@ export function detectIssueList() {
             skippedIssuesPath = configuredSkipPath;
         }
     }
-    catch {
-        /* fall through */
+    catch (err) {
+        // State access can fail on a degraded state file (corrupt JSON, EACCES).
+        // Default-path probe below still runs; warn so the underlying cause is visible (#994).
+        // Matches the sibling warn at line 64 for `issueListPath` read failures.
+        warn('startup', `Could not read skippedIssuesPath from state: ${errorMessage(err)}`);
     }
     // Probe default path: same directory as issue list, named skipped-issues.md
     if (!skippedIssuesPath && issueListPath) {

package/dist/commands/track.d.ts

@@ -1,7 +1,16 @@
 /**
- * Track/Untrack commands
- * In v2, PRs are fetched fresh from GitHub on each `daily` run.
- * These commands are preserved for backward compatibility.
+ * Track/Untrack commands (v2 semantics — see #1001)
+ *
+ * **These commands do not mutate state.** In v2, PRs are discovered and
+ * enriched automatically on every `daily` run — there is no local tracking
+ * list to add to or remove from. The commands are preserved for backwards
+ * compatibility with v1 callers, but:
+ *
+ * - `runTrack` is an **informational lookup** that fetches PR metadata from
+ *   GitHub and returns it. Useful for inspecting a specific PR's shape
+ *   without waiting for the next `daily` run. Nothing is persisted.
+ * - `runUntrack` is **deprecated** and always a no-op. Use `shelve` to hide
+ *   a PR from the daily digest.
  */
 import type { TrackOutput } from '../formatters/json.js';
 export interface UntrackOutput {
@@ -10,7 +19,11 @@ export interface UntrackOutput {
     message: string;
 }
 /**
- * Validate and fetch metadata for a PR URL.
+ * Fetch metadata for a PR URL (informational — does not persist).
+ *
+ * In v2 this is a read-only lookup. PRs are discovered automatically on each
+ * `daily` run; this command exists for one-off inspection of a specific PR's
+ * shape (title, repo, number).
  *
  * @param options - Track options
  * @param options.prUrl - Full GitHub PR URL
@@ -21,11 +34,14 @@ export declare function runTrack(options: {
     prUrl: string;
 }): Promise<TrackOutput>;
 /**
- * No-op in v2 — PRs are fetched fresh on each daily run.
+ * @deprecated No-op in v2. Use `runShelve` to hide a PR from the daily digest.
+ *
+ * Kept for backwards compatibility with v1 callers. PRs are fetched fresh
+ * on each `daily` run, so there is no local tracking list to remove from.
  *
  * @param options - Untrack options
- * @param options.prUrl - Full GitHub PR URL
- * @returns Message explaining v2 behavior
+ * @param options.prUrl - Full GitHub PR URL (validated but not used)
+ * @returns Output object with `removed: false` and a message explaining v2 behavior
  * @throws {ValidationError} If the URL is not a valid GitHub PR URL
  */
 export declare function runUntrack(options: {

package/dist/commands/track.js

@@ -1,13 +1,26 @@
 /**
- * Track/Untrack commands
- * In v2, PRs are fetched fresh from GitHub on each `daily` run.
- * These commands are preserved for backward compatibility.
+ * Track/Untrack commands (v2 semantics — see #1001)
+ *
+ * **These commands do not mutate state.** In v2, PRs are discovered and
+ * enriched automatically on every `daily` run — there is no local tracking
+ * list to add to or remove from. The commands are preserved for backwards
+ * compatibility with v1 callers, but:
+ *
+ * - `runTrack` is an **informational lookup** that fetches PR metadata from
+ *   GitHub and returns it. Useful for inspecting a specific PR's shape
+ *   without waiting for the next `daily` run. Nothing is persisted.
+ * - `runUntrack` is **deprecated** and always a no-op. Use `shelve` to hide
+ *   a PR from the daily digest.
  */
 import { getOctokit, requireGitHubToken } from '../core/index.js';
 import { validateUrl, PR_URL_PATTERN, validateGitHubUrl } from './validation.js';
 import { parseGitHubUrl } from '../core/utils.js';
 /**
- * Validate and fetch metadata for a PR URL.
+ * Fetch metadata for a PR URL (informational — does not persist).
+ *
+ * In v2 this is a read-only lookup. PRs are discovered automatically on each
+ * `daily` run; this command exists for one-off inspection of a specific PR's
+ * shape (title, repo, number).
  *
  * @param options - Track options
  * @param options.prUrl - Full GitHub PR URL
@@ -35,11 +48,14 @@ export async function runTrack(options) {
     };
 }
 /**
- * No-op in v2 — PRs are fetched fresh on each daily run.
+ * @deprecated No-op in v2. Use `runShelve` to hide a PR from the daily digest.
+ *
+ * Kept for backwards compatibility with v1 callers. PRs are fetched fresh
+ * on each `daily` run, so there is no local tracking list to remove from.
  *
  * @param options - Untrack options
- * @param options.prUrl - Full GitHub PR URL
- * @returns Message explaining v2 behavior
+ * @param options.prUrl - Full GitHub PR URL (validated but not used)
+ * @returns Output object with `removed: false` and a message explaining v2 behavior
  * @throws {ValidationError} If the URL is not a valid GitHub PR URL
  */
 export async function runUntrack(options) {

package/dist/core/index.d.ts

@@ -2,7 +2,7 @@
  * Core module exports
  * Re-exports all core functionality for convenient imports
  */
-export { StateManager, getStateManager, getStateManagerAsync, resetStateManager, type Stats } from './state.js';
+export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, 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 { IssueConversationMonitor } from './issue-conversation.js';

package/dist/core/index.js

@@ -2,7 +2,7 @@
  * Core module exports
  * Re-exports all core functionality for convenient imports
  */
-export { StateManager, getStateManager, getStateManagerAsync, resetStateManager } from './state.js';
+export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, resetStateManager, } from './state.js';
 export { GistStateStore } from './gist-state-store.js';
 export { PRMonitor, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
 // Search/vetting now delegated to @oss-scout/core via commands/scout-bridge.ts

package/dist/core/state.d.ts

@@ -301,6 +301,25 @@ export declare function getStateManager(): StateManager;
  * StateManager and Gist checkpoints will be no-ops.
  */
 export declare function getStateManagerAsync(token?: string): Promise<StateManager>;
+/**
+ * Bootstrap helper for processes that may run in Gist persistence mode.
+ *
+ * Peeks at the state file to check if Gist mode is configured. If so and a
+ * valid token is provided, pre-sets the singleton via {@link getStateManagerAsync}
+ * so subsequent synchronous {@link getStateManager} calls return the Gist-backed
+ * instance. No-op when the state file is absent, unparseable, or not in Gist mode.
+ *
+ * Consolidates identical filesystem-peek + getStateManagerAsync logic that
+ * was duplicated between the CLI bootstrap (`cli.ts`) and MCP tool bootstrap
+ * (`mcp-server/src/tools.ts`) — #1000.
+ *
+ * @param token - GitHub token with `gist` scope, or `null` to skip activation
+ *
+ * @example
+ * // CLI bootstrap
+ * await ensureGistPersistence(token);
+ */
+export declare function ensureGistPersistence(token: string | null): Promise<void>;
 /**
  * Reset the singleton StateManager instance to null. Intended for test isolation.
  */

package/dist/core/state.js

@@ -185,8 +185,10 @@ export class StateManager {
             try {
                 atomicWriteFileSync(getStateCachePath(), JSON.stringify(this.state, null, 2), 0o600);
             }
-            catch {
-                // Best-effort cache write
+            catch (err) {
+                // Cache write failure is non-fatal (Gist remains source of truth), but
+                // silent failure masks degraded-mode risk on next offline bootstrap (#994).
+                warn(MODULE, `Failed to write Gist local cache: ${errorMessage(err)}`);
             }
             return;
         }
@@ -705,6 +707,40 @@ export async function getStateManagerAsync(token) {
     }
     return getStateManager();
 }
+/**
+ * Bootstrap helper for processes that may run in Gist persistence mode.
+ *
+ * Peeks at the state file to check if Gist mode is configured. If so and a
+ * valid token is provided, pre-sets the singleton via {@link getStateManagerAsync}
+ * so subsequent synchronous {@link getStateManager} calls return the Gist-backed
+ * instance. No-op when the state file is absent, unparseable, or not in Gist mode.
+ *
+ * Consolidates identical filesystem-peek + getStateManagerAsync logic that
+ * was duplicated between the CLI bootstrap (`cli.ts`) and MCP tool bootstrap
+ * (`mcp-server/src/tools.ts`) — #1000.
+ *
+ * @param token - GitHub token with `gist` scope, or `null` to skip activation
+ *
+ * @example
+ * // CLI bootstrap
+ * await ensureGistPersistence(token);
+ */
+export async function ensureGistPersistence(token) {
+    if (!token)
+        return;
+    let persistence;
+    try {
+        const raw = fs.readFileSync(getStatePath(), 'utf-8');
+        persistence = JSON.parse(raw)?.config?.persistence;
+    }
+    catch {
+        // No state file or unreadable — stay in local mode
+        return;
+    }
+    if (persistence === 'gist') {
+        await getStateManagerAsync(token);
+    }
+}
 /**
  * Reset the singleton StateManager instance to null. Intended for test isolation.
  */

package/dist/core/utils.d.ts

@@ -145,14 +145,14 @@ export declare function extractOwnerRepo(url: string): {
     repo: string;
 } | null;
 /**
- * Calculates the number of whole days between two dates, using floor rounding.
+ * Calculates the number of whole days between two dates, clamped to zero.
  *
- * Can return negative values if `from` is after `to`. Partial days are truncated
- * (e.g., 1.9 days returns 1).
+ * Returns `0` if `from` is after `to` — reversed ranges and clock-skew do not
+ * produce negative values. Partial days are truncated (e.g., 1.9 days -> 1).
  *
  * @param from - The start date
  * @param to - The end date (defaults to the current date/time)
- * @returns Number of whole days between the two dates (may be negative)
+ * @returns Number of whole days between the two dates, minimum `0`
  *
  * @example
  * daysBetween(new Date('2024-01-01'), new Date('2024-01-10'))
@@ -160,7 +160,7 @@ export declare function extractOwnerRepo(url: string): {
  *
  * @example
  * daysBetween(new Date('2024-01-10'), new Date('2024-01-01'))
- * // -9
+ * // 0 (clamped; reversed ranges are not signed)
  */
 export declare function daysBetween(from: Date, to?: Date): number;
 /**

package/dist/core/utils.js

@@ -220,14 +220,14 @@ export function extractOwnerRepo(url) {
     return { owner, repo };
 }
 /**
- * Calculates the number of whole days between two dates, using floor rounding.
+ * Calculates the number of whole days between two dates, clamped to zero.
  *
- * Can return negative values if `from` is after `to`. Partial days are truncated
- * (e.g., 1.9 days returns 1).
+ * Returns `0` if `from` is after `to` — reversed ranges and clock-skew do not
+ * produce negative values. Partial days are truncated (e.g., 1.9 days -> 1).
  *
  * @param from - The start date
  * @param to - The end date (defaults to the current date/time)
- * @returns Number of whole days between the two dates (may be negative)
+ * @returns Number of whole days between the two dates, minimum `0`
  *
  * @example
  * daysBetween(new Date('2024-01-01'), new Date('2024-01-10'))
@@ -235,7 +235,7 @@ export function extractOwnerRepo(url) {
  *
  * @example
  * daysBetween(new Date('2024-01-10'), new Date('2024-01-01'))
- * // -9
+ * // 0 (clamped; reversed ranges are not signed)
  */
 export function daysBetween(from, to = new Date()) {
     return Math.max(0, Math.floor((to.getTime() - from.getTime()) / (1000 * 60 * 60 * 24)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {