@oss-autopilot/core 3.10.0 → 3.11.0

package/dist/core/state-persistence.js

@@ -6,15 +6,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { AgentStateSchema } from './state-schema.js';
-import { getStatePath, getBackupDir, getDataDir } from './paths.js';
+import { getStatePath, getBackupDir, getDataDir, getLegacyStatePath, getLegacyBackupDir } from './paths.js';
 import { errorMessage, ConcurrencyError } from './errors.js';
 import { debug, warn } from './logger.js';
 const MODULE = 'state';
 // Lock file timeout: if a lock is older than this, it is considered stale
 const LOCK_TIMEOUT_MS = 30_000; // 30 seconds
-// Legacy path for migration
-const LEGACY_STATE_FILE = path.join(process.cwd(), 'data', 'state.json');
-const LEGACY_BACKUP_DIR = path.join(process.cwd(), 'data', 'backups');
 /**
  * Check whether an existing lock file is stale (expired or corrupt).
  * Returns true if the lock should be considered stale and can be removed.
@@ -182,6 +179,10 @@ export function createFreshState() {
  */
 function migrateFromLegacyLocation() {
     const newStatePath = getStatePath();
+    // Resolved via paths.js (not module constants) so tests can mock the
+    // legacy location into per-test temp dirs — see #1382.
+    const LEGACY_STATE_FILE = getLegacyStatePath();
+    const LEGACY_BACKUP_DIR = getLegacyBackupDir();
     // If new state already exists, no migration needed
     if (fs.existsSync(newStatePath)) {
         return false;
@@ -316,11 +317,33 @@ function tryRestoreFromBackup() {
     }
     return null;
 }
+/**
+ * Copy a rejected state file to `<statePath>.rejected-<timestamp>` so the
+ * user can recover data manually before the file is overwritten by a backup
+ * restore or fresh state. Returns the preserved path, or null if the copy
+ * failed (preservation is best-effort and never throws).
+ */
+function preserveRejectedStateFile(statePath) {
+    try {
+        const rejectedPath = statePath + '.rejected-' + Date.now();
+        fs.copyFileSync(statePath, rejectedPath);
+        warn(MODULE, `Previous state preserved at: ${rejectedPath}`);
+        return rejectedPath;
+    }
+    catch (preserveErr) {
+        warn(MODULE, `Could not preserve rejected state file: ${errorMessage(preserveErr)}`);
+        return null;
+    }
+}
 /**
  * Load state from file, or create initial state if none exists.
  * If the main state file is corrupted, attempts to restore from the most recent backup.
  * Performs migration from legacy ./data/ location if needed.
- * @returns Object with the loaded state and the file's mtime (for change detection).
+ * @returns Object with the loaded state, the file's mtime (for change detection),
+ *   and recovery details when the main file was rejected.
+ * @throws Error when the state file exists but cannot be read due to a
+ *   permission error (EACCES/EPERM) — that is an environment problem, not
+ *   corruption, so restore-or-fresh would mask it and risk clobbering data.
  */
 export function loadState() {
     // Try to migrate from legacy location first
@@ -355,21 +378,16 @@ export function loadState() {
                 warn(MODULE, 'Attempting to restore from backup...');
                 debug(MODULE, 'Full validation errors:', parsed.error.issues);
                 // Preserve the rejected state file so the user can recover
-                try {
-                    const rejectedPath = statePath + '.rejected-' + Date.now();
-                    fs.copyFileSync(statePath, rejectedPath);
-                    warn(MODULE, `Previous state preserved at: ${rejectedPath}`);
-                }
-                catch (preserveErr) {
-                    warn(MODULE, `Could not preserve rejected state file: ${errorMessage(preserveErr)}`);
-                }
+                const rejectedPath = preserveRejectedStateFile(statePath);
+                const reason = `Invalid state file structure: ${summary}`;
                 const restoredState = tryRestoreFromBackup();
                 if (restoredState) {
                     const mtimeMs = safeGetMtimeMs(statePath);
-                    return { state: restoredState, mtimeMs };
+                    const recovery = { source: 'backup', rejectedPath, reason };
+                    return { state: restoredState, mtimeMs, recovery };
                 }
                 warn(MODULE, 'No valid backup found, starting fresh');
-                return { state: createFreshState(), mtimeMs: 0 };
+                return { state: createFreshState(), mtimeMs: 0, recovery: { source: 'fresh', rejectedPath, reason } };
             }
             // Save migrated state only after validation succeeds
             if (wasMigrated) {
@@ -408,14 +426,31 @@ export function loadState() {
         }
     }
     catch (error) {
+        // Permission errors are environmental, not corruption — restoring a
+        // backup or starting fresh here would mask the real problem and risk
+        // clobbering a perfectly valid state file. Rethrow with guidance (#1371).
+        const code = error?.code;
+        if (code === 'EACCES' || code === 'EPERM') {
+            throw new Error(`Permission denied reading state file (${code}): ${errorMessage(error)}. ` +
+                'This is an environment problem, not state corruption. Check the ownership and ' +
+                'permissions of ~/.oss-autopilot/state.json (e.g. run `ls -l ~/.oss-autopilot/state.json` ' +
+                'and fix with chown/chmod), then retry.', { cause: error });
+        }
         warn(MODULE, 'Error loading state:', error);
         warn(MODULE, 'Attempting to restore from backup...');
+        // Preserve the unparseable file before tryRestoreFromBackup() overwrites
+        // it with restored backup contents (#1371). Only attempt when the file
+        // actually exists — the error may have come from elsewhere in the block.
+        const rejectedPath = fs.existsSync(statePath) ? preserveRejectedStateFile(statePath) : null;
+        const reason = `Error loading state: ${errorMessage(error)}`;
         const restoredState = tryRestoreFromBackup();
         if (restoredState) {
             const mtimeMs = safeGetMtimeMs(statePath);
-            return { state: restoredState, mtimeMs };
+            const recovery = { source: 'backup', rejectedPath, reason };
+            return { state: restoredState, mtimeMs, recovery };
         }
         warn(MODULE, 'No valid backup found, starting fresh');
+        return { state: createFreshState(), mtimeMs: 0, recovery: { source: 'fresh', rejectedPath, reason } };
     }
     debug(MODULE, 'No existing state found, initializing...');
     return { state: createFreshState(), mtimeMs: 0 };

package/dist/core/state.d.ts

@@ -4,9 +4,11 @@
  * and scoring logic to repo-score-manager.ts.
  */
 import { AgentState, TrackedIssue, RepoScore, RepoScoreUpdate, DailyDigest, LocalRepoCache, StatusOverride, FetchedPRStatus, StoredMergedPR, StoredClosedPR } from './types.js';
+import { type LoadRecoveryInfo } from './state-persistence.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 { LoadRecoveryInfo } from './state-persistence.js';
 export type { Stats } from './repo-score-manager.js';
 /**
  * Push state to the backing Gist when Gist mode is active. Best-effort:
@@ -17,8 +19,15 @@ export type { Stats } from './repo-score-manager.js';
  * Intended for state-mutating PR-flow commands (shelve / unshelve / move /
  * dismiss / undismiss / claim) so Gist-sync users don't see day-long drift
  * between machines waiting for the next `daily` checkpoint. See issue #1036.
+ *
+ * @returns `null` when the push succeeded (or Gist mode is off); otherwise a
+ * human-readable warning the caller should surface in its structured output.
+ * `checkpoint()` resolves `false` without throwing when the push failed
+ * after its retry — previously that was discarded everywhere except
+ * `state --sync`, so a failed cross-machine sync reported clean success
+ * (#1370). stderr `warn()` alone is invisible to MCP/dashboard consumers.
  */
-export declare function maybeCheckpoint(stateManager: StateManager, callerModule: string): Promise<void>;
+export declare function maybeCheckpoint(stateManager: StateManager, callerModule: string): Promise<string | null>;
 /**
  * Singleton manager for persistent agent state stored in ~/.oss-autopilot/state.json.
  *
@@ -54,6 +63,7 @@ export declare class StateManager {
     protected gistDegraded: boolean;
     private staleness;
     private lastSuccessfulRefreshAt;
+    private loadRecovery;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -157,6 +167,13 @@ export declare class StateManager {
      * Returns true if state was reloaded, false if unchanged or in-memory mode.
      */
     reloadIfChanged(): boolean;
+    /**
+     * Recovery details from the most recent state load, or null when the last
+     * load read the state file cleanly (or no load from disk has happened,
+     * e.g. in-memory mode). Set when loadState() fell back to a backup or
+     * fresh state because the main file was corrupt or invalid (#1371).
+     */
+    getLoadRecovery(): LoadRecoveryInfo | null;
     /**
      * Re-fetch state from the backing Gist (if in Gist mode).
      * Throttled to once per 30 seconds by GistStateStore. Returns true if state was refreshed.

package/dist/core/state.js

@@ -42,15 +42,30 @@ function filterValidUrlEntries(entries, kind) {
  * Intended for state-mutating PR-flow commands (shelve / unshelve / move /
  * dismiss / undismiss / claim) so Gist-sync users don't see day-long drift
  * between machines waiting for the next `daily` checkpoint. See issue #1036.
+ *
+ * @returns `null` when the push succeeded (or Gist mode is off); otherwise a
+ * human-readable warning the caller should surface in its structured output.
+ * `checkpoint()` resolves `false` without throwing when the push failed
+ * after its retry — previously that was discarded everywhere except
+ * `state --sync`, so a failed cross-machine sync reported clean success
+ * (#1370). stderr `warn()` alone is invisible to MCP/dashboard consumers.
  */
 export async function maybeCheckpoint(stateManager, callerModule) {
     if (!stateManager.isGistMode())
-        return;
+        return null;
     try {
-        await stateManager.checkpoint();
+        const pushed = await stateManager.checkpoint();
+        if (!pushed) {
+            const msg = 'Gist checkpoint push failed after retry; the local mutation is saved and will sync on the next successful push';
+            warn(callerModule, msg);
+            return msg;
+        }
+        return null;
     }
     catch (err) {
-        warn(callerModule, `Gist checkpoint failed (local mutation succeeded, will retry on next push): ${errorMessage(err)}`);
+        const msg = `Gist checkpoint failed (local mutation succeeded, will retry on next push): ${errorMessage(err)}`;
+        warn(callerModule, msg);
+        return msg;
     }
 }
 export class StateManager {
@@ -63,6 +78,7 @@ export class StateManager {
     gistDegraded = false;
     staleness = null;
     lastSuccessfulRefreshAt = null;
+    loadRecovery = null;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -78,6 +94,7 @@ export class StateManager {
             const result = loadState();
             this.state = result.state;
             this.lastLoadedMtimeMs = result.mtimeMs;
+            this.loadRecovery = result.recovery ?? null;
             this.tryReconcilePRCounts();
         }
     }
@@ -97,9 +114,11 @@ export class StateManager {
         // Check if local state exists for migration
         const statePath = getStatePath();
         let result;
+        let localRecovery = null;
         if (fs.existsSync(statePath)) {
             // Existing user: load local state and migrate it into the Gist if no Gist exists yet.
             const localStateResult = loadState();
+            localRecovery = localStateResult.recovery ?? null;
             const migrationResult = await gistStore.bootstrapWithMigration(localStateResult.state);
             result = migrationResult;
             // If a new Gist was just created from local state, rename the local file
@@ -126,6 +145,9 @@ export class StateManager {
         manager.gistStore = gistStore;
         manager.gistDegraded = result.degraded ?? false;
         manager.inMemoryOnly = false; // re-enable persistence
+        // Surface a recovery that happened while loading the local file for Gist
+        // migration — the recovered (or fresh) state is what got migrated.
+        manager.loadRecovery = localRecovery;
         // Seed the staleness marker if bootstrap fell back to the local cache —
         // a `daily` running on a cron right after this start needs to know.
         if (result.degraded) {
@@ -335,9 +357,19 @@ export class StateManager {
             return false;
         this.state = result.state;
         this.lastLoadedMtimeMs = result.mtimeMs;
+        this.loadRecovery = result.recovery ?? null;
         this.tryReconcilePRCounts();
         return true;
     }
+    /**
+     * Recovery details from the most recent state load, or null when the last
+     * load read the state file cleanly (or no load from disk has happened,
+     * e.g. in-memory mode). Set when loadState() fell back to a backup or
+     * fresh state because the main file was corrupt or invalid (#1371).
+     */
+    getLoadRecovery() {
+        return this.loadRecovery;
+    }
     /**
      * Re-fetch state from the backing Gist (if in Gist mode).
      * Throttled to once per 30 seconds by GistStateStore. Returns true if state was refreshed.

package/dist/core/untrusted-content.d.ts

@@ -13,9 +13,22 @@
  *  3. `extractFromFence(wrapUntrustedContent(x, label))` returns `x`
  *     unchanged for any input — the wrapping is lossless.
  *
- * Consumers should pair this with the agent-side guidance in
- * `workflows/reference.md` ("Prompt Injection Awareness"), which tells
- * the LLM to ignore instructions inside `<github-content>` blocks.
+ * Runtime wiring (#1372) — body fields are fenced at the last serialization
+ * boundary into agent-facing output:
+ *
+ *  - `runComments` (commands/comments.ts): review / inline / discussion
+ *    comment bodies in the `comments` CLI `--json` + MCP tool output.
+ *  - `fetchPRCommentBundle` (core/pr-comments-fetcher.ts): bundle bodies
+ *    feeding `guidelines fetch-corpus` (agent-only consumer).
+ *  - `toDailyOutput` (commands/daily.ts): `commentedIssues[].lastResponseBody`
+ *    / `userLastCommentBody` in the daily/startup JSON. The producer
+ *    (`issue-conversation.ts`) stays raw because the dashboard SPA and the
+ *    CLI text renderers consume the same objects.
+ *
+ * Human-facing display paths unwrap with {@link safeExtractFromFence}.
+ * This pairs with the agent-side guidance in `workflows/reference.md`
+ * ("Prompt Injection Awareness"), which tells the LLM to treat anything
+ * inside `<github-content>` blocks as data, not instructions.
  *
  * Non-goals:
  *  - This is NOT a content filter. We do not detect or strip prompt-
@@ -46,3 +59,11 @@ export declare function wrapUntrustedContent(text: string, label: string, meta?:
  * markdown with this; it's for tests + symmetric reasoning only.
  */
 export declare function extractFromFence(fenced: string): string;
+/**
+ * Tolerant unwrap for human-facing display paths (CLI text mode). Returns
+ * the original body when `text` is a well-formed fence, and `text` unchanged
+ * otherwise. Display code must not crash on unfenced input (older state,
+ * fields that were never wrapped), so unlike {@link extractFromFence} this
+ * never throws.
+ */
+export declare function safeExtractFromFence(text: string): string;

package/dist/core/untrusted-content.js

@@ -13,9 +13,22 @@
  *  3. `extractFromFence(wrapUntrustedContent(x, label))` returns `x`
  *     unchanged for any input — the wrapping is lossless.
  *
- * Consumers should pair this with the agent-side guidance in
- * `workflows/reference.md` ("Prompt Injection Awareness"), which tells
- * the LLM to ignore instructions inside `<github-content>` blocks.
+ * Runtime wiring (#1372) — body fields are fenced at the last serialization
+ * boundary into agent-facing output:
+ *
+ *  - `runComments` (commands/comments.ts): review / inline / discussion
+ *    comment bodies in the `comments` CLI `--json` + MCP tool output.
+ *  - `fetchPRCommentBundle` (core/pr-comments-fetcher.ts): bundle bodies
+ *    feeding `guidelines fetch-corpus` (agent-only consumer).
+ *  - `toDailyOutput` (commands/daily.ts): `commentedIssues[].lastResponseBody`
+ *    / `userLastCommentBody` in the daily/startup JSON. The producer
+ *    (`issue-conversation.ts`) stays raw because the dashboard SPA and the
+ *    CLI text renderers consume the same objects.
+ *
+ * Human-facing display paths unwrap with {@link safeExtractFromFence}.
+ * This pairs with the agent-side guidance in `workflows/reference.md`
+ * ("Prompt Injection Awareness"), which tells the LLM to treat anything
+ * inside `<github-content>` blocks as data, not instructions.
  *
  * Non-goals:
  *  - This is NOT a content filter. We do not detect or strip prompt-
@@ -104,3 +117,18 @@ export function extractFromFence(fenced) {
         .split(AMP_ESCAPE)
         .join('&');
 }
+/**
+ * Tolerant unwrap for human-facing display paths (CLI text mode). Returns
+ * the original body when `text` is a well-formed fence, and `text` unchanged
+ * otherwise. Display code must not crash on unfenced input (older state,
+ * fields that were never wrapped), so unlike {@link extractFromFence} this
+ * never throws.
+ */
+export function safeExtractFromFence(text) {
+    try {
+        return extractFromFence(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/formatters/json.d.ts

@@ -50,7 +50,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';
+export type DailyWarningPhase = 'fetch' | 'repo-scores' | 'analytics' | 'scout-sync' | 'partition' | 'dismiss-filter' | '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
@@ -176,6 +176,7 @@ export declare const StatusOutputSchema: z.ZodObject<{
             "dismiss-filter": "dismiss-filter";
             "gist-checkpoint": "gist-checkpoint";
             "gist-staleness": "gist-staleness";
+            "state-load": "state-load";
         }>;
         operation: z.ZodString;
         message: z.ZodString;
@@ -378,6 +379,7 @@ export declare const DailyOutputSchema: z.ZodObject<{
             "dismiss-filter": "dismiss-filter";
             "gist-checkpoint": "gist-checkpoint";
             "gist-staleness": "gist-staleness";
+            "state-load": "state-load";
         }>;
         operation: z.ZodString;
         message: z.ZodString;
@@ -518,6 +520,7 @@ export declare const CompactDailyOutputSchema: z.ZodObject<{
             "dismiss-filter": "dismiss-filter";
             "gist-checkpoint": "gist-checkpoint";
             "gist-staleness": "gist-staleness";
+            "state-load": "state-load";
         }>;
         operation: z.ZodString;
         message: z.ZodString;
@@ -798,6 +801,7 @@ export declare const PostOutputSchema: z.ZodObject<{
 export declare const ClaimOutputSchema: z.ZodObject<{
     commentUrl: z.ZodString;
     issueUrl: z.ZodString;
+    gistSyncWarning: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const InitOutputSchema: z.ZodObject<{
     username: z.ZodString;
@@ -865,6 +869,7 @@ export declare const MoveOutputSchema: z.ZodObject<{
         shelved: "shelved";
     }>;
     description: z.ZodString;
+    gistSyncWarning: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const PRTemplateOutputSchema: z.ZodObject<{
     template: z.ZodNullable<z.ZodString>;
@@ -899,6 +904,7 @@ export declare const RepoVetOutputSchema: z.ZodObject<{
         lastCommitISO: z.ZodNullable<z.ZodString>;
         contributorsLast90d: z.ZodNumber;
         lastReleaseISO: z.ZodNullable<z.ZodString>;
+        releasesIncomplete: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     communityHealth: z.ZodObject<{
         contributing: z.ZodBoolean;
@@ -1398,6 +1404,8 @@ export interface PostOutput {
 export interface ClaimOutput {
     commentUrl: string;
     issueUrl: string;
+    /** Set when the post-mutation Gist checkpoint failed; the local mutation succeeded (#1370). */
+    gistSyncWarning?: string;
 }
 /** Info about a local git clone (#84) */
 export interface LocalRepoInfo {

package/dist/formatters/json.js

@@ -87,6 +87,7 @@ const DailyWarningPhaseSchema = z.enum([
     'dismiss-filter',
     'gist-checkpoint',
     'gist-staleness',
+    'state-load',
 ]);
 const DailyWarningSchema = z.object({
     phase: DailyWarningPhaseSchema,
@@ -417,6 +418,8 @@ export const PostOutputSchema = z.object({
 export const ClaimOutputSchema = z.object({
     commentUrl: z.string(),
     issueUrl: z.string(),
+    // Post-mutation Gist checkpoint failure (#1370). Optional: absent on clean runs.
+    gistSyncWarning: z.string().optional(),
 });
 export const InitOutputSchema = z.object({
     username: z.string(),
@@ -492,6 +495,8 @@ export const MoveOutputSchema = z.object({
     url: z.string(),
     target: z.enum(['attention', 'waiting', 'shelved', 'auto']),
     description: z.string(),
+    // Post-mutation Gist checkpoint failure (#1370). Optional: absent on clean runs.
+    gistSyncWarning: z.string().optional(),
 });
 export const PRTemplateOutputSchema = z.object({
     template: z.string().nullable(),
@@ -535,6 +540,13 @@ export const RepoVetOutputSchema = z.object({
         lastCommitISO: z.string().nullable(),
         contributorsLast90d: z.number().int().nonnegative(),
         lastReleaseISO: z.string().nullable(),
+        /**
+         * True when the release listing failed for a non-404 reason (5xx,
+         * network), so a `null` lastReleaseISO means "could not determine"
+         * rather than "confirmed no releases". The release-list analogue of
+         * `communityHealth.incomplete` (#1373).
+         */
+        releasesIncomplete: z.boolean().optional(),
     }),
     communityHealth: z.object({
         contributing: z.boolean(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {
@@ -54,18 +54,18 @@
   "dependencies": {
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/rest": "^22.0.1",
-    "@oss-scout/core": "^0.10.0",
-    "commander": "^14.0.3",
+    "@oss-scout/core": "^0.11.0",
+    "commander": "^15.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.7.0",
-    "@vitest/coverage-v8": "^4.1.6",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "^0.28.0",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.8"
   },
   "scripts": {
     "build": "tsc",