@oss-autopilot/core 1.15.2 → 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/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/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/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.2",
+  "version": "1.16.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {