@oss-autopilot/core 3.13.1 → 3.13.3

package/dist/cli.js

@@ -81,6 +81,20 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
         const { ensureGistPersistence } = await import('./core/index.js');
         await ensureGistPersistence(token);
     }
+    else {
+        // #1431: localOnly skips the AUTH GATE, not gist persistence. Mutating
+        // localOnly commands (shelve/move/dismiss/override/...) already call
+        // maybeCheckpoint, which silently no-ops when the singleton never
+        // bootstrapped — so a gist-configured user's CLI mutations were written
+        // local-only with no warning and never reached the Gist. Best-effort
+        // bootstrap; the warning semantics live (and are unit-tested) in
+        // bootstrapGistBestEffort.
+        const { bootstrapGistBestEffort } = await import('./core/index.js');
+        const localOnlyWarning = await bootstrapGistBestEffort(getGitHubTokenAsync);
+        if (localOnlyWarning) {
+            console.error(`Warning: ${localOnlyWarning}`);
+        }
+    }
 });
 // First-run detection: if no subcommand was provided and no state file exists,
 // show a quick-start guide and exit before Commander displays generic help.

package/dist/commands/daily.js

@@ -546,6 +546,15 @@ async function executeDailyCheckInternal(token) {
     // One collector shared by every phase — threaded through explicitly so the
     // callgraph documents which phases can produce non-fatal warnings. See #1042.
     const warnings = [];
+    // Surface gist-mode degradation in the machine-readable envelope (#1431):
+    // a process whose config says `persistence: gist` but whose manager is
+    // local-only (transient init fallback, or a localOnly entry point that
+    // never bootstrapped) writes mutations that will not sync. Previously the
+    // only signal was a stderr warn, invisible to --json consumers.
+    const smForGistCheck = getStateManager();
+    if (smForGistCheck.getState().config.persistence === 'gist' && !smForGistCheck.isGistMode()) {
+        recordWarning(warnings, 'gist-init', 'Gist persistence degraded', new Error('configured for Gist but running local-only in this process; mutations will not sync until Gist init succeeds'));
+    }
     // Surface Gist staleness up-front so consumers see it even if Phase 1 fails (#1193).
     const staleness = getStateManager().getStateStaleness();
     if (staleness) {

package/dist/commands/dashboard-data.js

@@ -283,7 +283,10 @@ export async function fetchDashboardData(token) {
             // Partitioned over overriddenPRs (#1416): the shelve decision must use
             // the same post-override status the CLI partitions on.
             const shelvedUrls = new Set(stateManager.getState().config.shelvedPRUrls || []);
-            const freshShelved = overriddenPRs.filter((pr) => !CRITICAL_STATUSES.has(pr.status) && (shelvedUrls.has(pr.url) || pr.stalenessTier === 'dormant'));
+            // Single copy of the shelve predicate (#1421): isShelvedForDisplay is
+            // the same rule reconcileShelvePartition applies on rebuilds, so its
+            // regression tests now guard this line too.
+            const freshShelved = overriddenPRs.filter((pr) => isShelvedForDisplay(pr, shelvedUrls));
             digest.shelvedPRs = freshShelved.map(toShelvedPRRef);
             digest.autoUnshelvedPRs = [];
             digest.summary.totalActivePRs = overriddenPRs.length - freshShelved.length;

package/dist/commands/list-move-tier.js

@@ -184,10 +184,20 @@ export async function runListMoveTier(options) {
             'Add the entry to the list first, then re-run list-move-tier.');
     }
     if (result.moved) {
+        // tmp+rename so a crash mid-write can't truncate the curated list —
+        // same atomic pattern as list-mark-done (#1421).
+        const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
         try {
-            fs.writeFileSync(filePath, result.content, 'utf8');
+            fs.writeFileSync(tmp, result.content, 'utf8');
+            fs.renameSync(tmp, filePath);
         }
         catch (error) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch {
+                // best-effort cleanup
+            }
             throw new Error(`Failed to write file: ${errorMessage(error)}`, { cause: error });
         }
     }

package/dist/core/auth.js

@@ -13,6 +13,22 @@ const MODULE = 'auth';
 // Cached GitHub token (fetched once per session)
 let cachedGitHubToken = null;
 let tokenFetchAttempted = false;
+/**
+ * A `gh auth token` spawn that timed out is transient (#1415): the CLI is
+ * installed and may answer on the next call (slow disk, machine waking,
+ * momentary load). Everything else is definitive for the process lifetime —
+ * ENOENT (gh not installed) and a non-zero exit (not authenticated) will not
+ * change without user action, so those still latch `tokenFetchAttempted`.
+ * The async execFile timeout surfaces as `killed: true` (signal SIGTERM);
+ * the sync execFileSync timeout surfaces as `code: 'ETIMEDOUT'` (no
+ * `killed` property) — both arms are load-bearing, one per path.
+ */
+function isTransientTokenFetchError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    return e.killed === true || e.code === 'ETIMEDOUT';
+}
 /**
  * Retrieves a GitHub authentication token, checking sources in priority order.
  *
@@ -29,7 +45,6 @@ export function getGitHubToken() {
     if (tokenFetchAttempted) {
         return null;
     }
-    tokenFetchAttempted = true;
     if (process.env.GITHUB_TOKEN) {
         cachedGitHubToken = process.env.GITHUB_TOKEN;
         return cachedGitHubToken;
@@ -40,6 +55,8 @@ export function getGitHubToken() {
             stdio: ['pipe', 'pipe', 'pipe'],
             timeout: 2000,
         }).trim();
+        // Definitive outcome (a token, or authoritatively none) — latch.
+        tokenFetchAttempted = true;
         if (token && token.length > 0) {
             cachedGitHubToken = token;
             debug(MODULE, 'Using GitHub token from gh CLI');
@@ -47,9 +64,14 @@ export function getGitHubToken() {
         }
     }
     catch (err) {
-        // Promote to warn-once-per-session so a slow `gh` (2s timeout) or a
-        // misconfigured CLI is visible without DEBUG=1 (#1209 L6). The
-        // tokenFetchAttempted cache means subsequent calls don't re-warn.
+        // Latch only on definitive failures (#1415): a timeout must not
+        // permanently disable token fetch for a long-lived process (the MCP
+        // server), or gist-mode mutations silently degrade to local-only for
+        // the process lifetime. Promote to warn so a slow `gh` (2s timeout) or
+        // a misconfigured CLI is visible without DEBUG=1 (#1209 L6).
+        if (!isTransientTokenFetchError(err)) {
+            tokenFetchAttempted = true;
+        }
         warn(MODULE, `gh auth token failed (CLI unavailable or not authenticated): ${err instanceof Error ? err.message : String(err)}`);
     }
     return null;
@@ -97,7 +119,6 @@ export async function getGitHubTokenAsync() {
     if (tokenFetchAttempted) {
         return null;
     }
-    tokenFetchAttempted = true;
     if (process.env.GITHUB_TOKEN) {
         cachedGitHubToken = process.env.GITHUB_TOKEN;
         return cachedGitHubToken;
@@ -113,6 +134,8 @@ export async function getGitHubTokenAsync() {
                 }
             });
         });
+        // Definitive outcome (a token, or authoritatively none) — latch.
+        tokenFetchAttempted = true;
         if (token && token.length > 0) {
             cachedGitHubToken = token;
             debug(MODULE, 'Using GitHub token from gh CLI (async)');
@@ -120,7 +143,11 @@ export async function getGitHubTokenAsync() {
         }
     }
     catch (err) {
-        // Same warn-once promotion as the sync version (#1209 L6).
+        // Same transient/definitive split and warn promotion as the sync
+        // version (#1415, #1209 L6).
+        if (!isTransientTokenFetchError(err)) {
+            tokenFetchAttempted = true;
+        }
         warn(MODULE, `gh auth token failed (CLI unavailable or not authenticated): ${err instanceof Error ? err.message : String(err)}`);
     }
     return null;

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, ensureGistPersistence, maybeCheckpoint, resetStateManager, type Stats, } from './state.js';
+export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, bootstrapGistBestEffort, type GistPersistenceStatus, maybeCheckpoint, resetStateManager, type Stats, } from './state.js';
 export { GistStateStore } from './gist-state-store.js';
 export { guidelinesFilename, repoFromGuidelinesFilename, GUIDELINES_FILE_PREFIX, GUIDELINES_MAX_BYTES, GuidelinesNotAvailableError, GuidelinesTooLargeError, } from './guidelines-store.js';
 export { PRMonitor, type PRCheckFailure, type FetchPRsResult, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.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, ensureGistPersistence, maybeCheckpoint, resetStateManager, } from './state.js';
+export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, bootstrapGistBestEffort, maybeCheckpoint, resetStateManager, } from './state.js';
 export { GistStateStore } from './gist-state-store.js';
 export { guidelinesFilename, repoFromGuidelinesFilename, GUIDELINES_FILE_PREFIX, GUIDELINES_MAX_BYTES, GuidelinesNotAvailableError, GuidelinesTooLargeError, } from './guidelines-store.js';
 export { PRMonitor, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';

package/dist/core/state.d.ts

@@ -441,7 +441,40 @@ export declare function getStateManagerAsync(token?: string): Promise<StateManag
  * // CLI bootstrap
  * await ensureGistPersistence(token);
  */
-export declare function ensureGistPersistence(token: string | null): Promise<void>;
+export type GistPersistenceStatus = 
+/** No state file yet, or config does not request gist mode. */
+'local-mode'
+/** The state file exists but could not be read/parsed for this attempt
+ * (permissions, transient FS error, corrupt JSON). Callers must NOT
+ * memoize this as "local mode chosen" — a later attempt may succeed. */
+ | 'state-unreadable'
+/** Gist mode is configured but no token was available for this attempt. */
+ | 'no-token'
+/** Gist mode active: the singleton is gist-backed. */
+ | 'gist'
+/** Gist mode is configured and a token was available, but init fell back
+ * to local-only (transient network failure). A later call may recover. */
+ | 'degraded';
+export declare function ensureGistPersistence(token: string | null): Promise<GistPersistenceStatus>;
+/**
+ * Best-effort gist bootstrap for entry points WITHOUT the auth gate (#1431):
+ * the CLI's localOnly commands (shelve/move/dismiss/override/config/setup/...)
+ * skip token enforcement, but a gist-configured user's mutations must still
+ * reach the Gist — their maybeCheckpoint calls silently no-op when the
+ * singleton never bootstrapped.
+ *
+ * Returns a human-readable LOCAL-ONLY warning when the process will write
+ * local-only despite a gist config, or null when no warning is needed
+ * (local mode, or gist mode successfully activated).
+ *
+ * Ordering: peek first with no token (zero spawn cost for genuinely-local
+ * users), fetch a token only when the config asks for gist. Hard
+ * ConfigurationErrors are converted to a warning instead of thrown — the
+ * localOnly set includes config/setup, the very commands needed to REPAIR a
+ * broken gist setup, so they must not be bricked by it. (The auth-gated
+ * path keeps throwing per #1202.)
+ */
+export declare function bootstrapGistBestEffort(fetchToken: () => Promise<string | null>): Promise<string | null>;
 /**
  * Reset the singleton StateManager instance to null. Intended for test isolation.
  */

package/dist/core/state.js

@@ -924,13 +924,27 @@ export function getStateManager() {
  * StateManager and Gist checkpoints will be no-ops.
  */
 export async function getStateManagerAsync(token) {
-    if (stateManager)
+    // #1415: a LOCAL-mode singleton does not short-circuit when a token is
+    // provided. The only token-bearing caller is ensureGistPersistence, which
+    // already verified the config says `persistence: gist` — so a local
+    // singleton here means a previous transient init failure fell back (or a
+    // tool body lazily created the local manager before auth resolved), and
+    // this call is the retry that must be allowed to upgrade it. The old
+    // unconditional early return made every retry a dead no-op, permanently
+    // latching gist-configured processes into silent local-only writes.
+    if (stateManager && (!token || stateManager.isGistMode()))
         return stateManager;
     if (asyncManagerPromise)
         return asyncManagerPromise;
     if (token) {
         asyncManagerPromise = StateManager.createWithGist(token)
             .then((mgr) => {
+            // Upgrade note: replacing a transient-fallback local singleton fixes
+            // FUTURE operations. Mutations made during the degraded window stay
+            // in the local state.json only — when a Gist already exists they are
+            // NOT merged into it by this upgrade (bootstrapWithMigration seeds a
+            // Gist from local state only on first creation). The per-call MCP
+            // warning is the signal that those writes were at risk.
             stateManager = mgr;
             asyncManagerPromise = null;
             return mgr;
@@ -949,6 +963,9 @@ export async function getStateManagerAsync(token) {
             // marker stays in config, causing permanent cross-machine divergence.
             if (!isTransientNetworkError(err))
                 throw err;
+            // Intentional CLI semantics: a one-shot process warns and proceeds
+            // local-only. Long-lived callers (MCP) detect this via the
+            // ensureGistPersistence return status and retry on later calls.
             warn(MODULE, `Gist initialization failed (transient network error), falling back to local-only mode: ${err}`);
             return getStateManager();
         });
@@ -956,39 +973,75 @@ 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(), 'utf8');
         persistence = JSON.parse(raw)?.config?.persistence;
     }
-    catch {
-        // No state file or unreadable — stay in local mode
-        return;
+    catch (err) {
+        // A missing file is the genuine "fresh local-mode user" case. Anything
+        // else (EACCES, EMFILE, corrupt JSON) must not be silently classified
+        // as a local-mode CHOICE — that would re-create the #1415 latch through
+        // a third door when the caller memoizes the answer.
+        if (err.code === 'ENOENT')
+            return 'local-mode';
+        warn(MODULE, `State file unreadable during gist-persistence check (will retry): ${errorMessage(err)}`);
+        return 'state-unreadable';
+    }
+    if (persistence !== 'gist')
+        return 'local-mode';
+    // #1415: report the distinction the MCP layer needs — "gist configured but
+    // token missing" and "init fell back to local" both mean the process is
+    // NOT writing to the Gist despite the config saying it should, and a
+    // long-lived caller must keep retrying instead of memoizing the outcome.
+    if (!token)
+        return 'no-token';
+    const mgr = await getStateManagerAsync(token);
+    return mgr.isGistMode() ? 'gist' : 'degraded';
+}
+/**
+ * Best-effort gist bootstrap for entry points WITHOUT the auth gate (#1431):
+ * the CLI's localOnly commands (shelve/move/dismiss/override/config/setup/...)
+ * skip token enforcement, but a gist-configured user's mutations must still
+ * reach the Gist — their maybeCheckpoint calls silently no-op when the
+ * singleton never bootstrapped.
+ *
+ * Returns a human-readable LOCAL-ONLY warning when the process will write
+ * local-only despite a gist config, or null when no warning is needed
+ * (local mode, or gist mode successfully activated).
+ *
+ * Ordering: peek first with no token (zero spawn cost for genuinely-local
+ * users), fetch a token only when the config asks for gist. Hard
+ * ConfigurationErrors are converted to a warning instead of thrown — the
+ * localOnly set includes config/setup, the very commands needed to REPAIR a
+ * broken gist setup, so they must not be bricked by it. (The auth-gated
+ * path keeps throwing per #1202.)
+ */
+export async function bootstrapGistBestEffort(fetchToken) {
+    let reason = null;
+    try {
+        let status = await ensureGistPersistence(null);
+        if (status === 'no-token') {
+            status = await ensureGistPersistence(await fetchToken());
+        }
+        if (status === 'no-token')
+            reason = 'no GitHub token is available';
+        else if (status === 'state-unreadable')
+            reason = 'the state file could not be read';
+        else if (status === 'degraded')
+            reason = 'Gist initialization hit a transient network failure';
     }
-    if (persistence === 'gist') {
-        await getStateManagerAsync(token);
+    catch (err) {
+        reason =
+            err instanceof ConfigurationError
+                ? `Gist initialization failed (${errorMessage(err)}) — fix the Gist setup (check the token's gist scope, or run state-show / setup) before relying on sync`
+                : `Gist initialization failed: ${errorMessage(err)}`;
     }
+    if (reason === null)
+        return null;
+    return (`Gist persistence is configured but ${reason} — changes made by this command are ` +
+        'LOCAL-ONLY and may be overwritten by the next successful Gist sync.');
 }
 /**
  * Reset the singleton StateManager instance to null. Intended for test isolation.

package/dist/formatters/json.d.ts

@@ -51,7 +51,7 @@ export interface CompactRepoGroup {
  * See `DailyWarning` and issue #1042 for the rationale — keeping this a
  * fixed union so downstream consumers can switch on it without drift.
  */
-export type DailyWarningPhase = 'fetch' | 'repo-scores' | 'analytics' | 'scout-sync' | 'partition' | 'dismiss-filter' | 'gist-checkpoint' | 'gist-staleness' | 'state-load';
+export type DailyWarningPhase = 'fetch' | 'repo-scores' | 'analytics' | 'scout-sync' | 'partition' | 'dismiss-filter' | 'gist-init' | 'gist-checkpoint' | 'gist-staleness' | 'state-load';
 /**
  * A single non-fatal failure surfaced from the `daily` pipeline. Unlike
  * `PRCheckFailure` (which is scoped to per-PR fetch errors), this covers
@@ -179,6 +179,7 @@ export declare const StatusOutputSchema: z.ZodObject<{
             "scout-sync": "scout-sync";
             partition: "partition";
             "dismiss-filter": "dismiss-filter";
+            "gist-init": "gist-init";
             "gist-checkpoint": "gist-checkpoint";
             "gist-staleness": "gist-staleness";
             "state-load": "state-load";
@@ -394,6 +395,7 @@ export declare const DailyOutputSchema: z.ZodObject<{
             "scout-sync": "scout-sync";
             partition: "partition";
             "dismiss-filter": "dismiss-filter";
+            "gist-init": "gist-init";
             "gist-checkpoint": "gist-checkpoint";
             "gist-staleness": "gist-staleness";
             "state-load": "state-load";
@@ -541,6 +543,7 @@ export declare const CompactDailyOutputSchema: z.ZodObject<{
             "scout-sync": "scout-sync";
             partition: "partition";
             "dismiss-filter": "dismiss-filter";
+            "gist-init": "gist-init";
             "gist-checkpoint": "gist-checkpoint";
             "gist-staleness": "gist-staleness";
             "state-load": "state-load";

package/dist/formatters/json.js

@@ -90,6 +90,7 @@ const DailyWarningPhaseSchema = z.enum([
     'scout-sync',
     'partition',
     'dismiss-filter',
+    'gist-init',
     'gist-checkpoint',
     'gist-staleness',
     'state-load',

package/package.json

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