@oss-autopilot/core 1.16.2 → 1.17.1

package/dist/commands/doctor.js

@@ -0,0 +1,358 @@
+/**
+ * Doctor command — a real system-health audit.
+ *
+ * Runs independent checks against the local environment and reports an
+ * aggregate `DoctorOutput` so users can diagnose common failure modes
+ * (missing token, unauthenticated gh CLI, stale bundle, corrupted state,
+ * unresolvable scout dependency, low rate-limit budget) in one go.
+ *
+ * Each `check*` function is exported individually so tests can mock its
+ * external dependencies in isolation.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { getGitHubTokenAsync, getOctokit, getStatePath } from '../core/index.js';
+import { AgentStateSchema } from '../core/state-schema.js';
+import { errorMessage } from '../core/errors.js';
+const execFileAsync = promisify(execFile);
+const GH_CMD_TIMEOUT_MS = 3000;
+// ── Individual checks ───────────────────────────────────────────────────
+/** Extract a Node errno-style code from an unknown thrown value. */
+function errCode(err) {
+    if (err && typeof err === 'object' && 'code' in err) {
+        const code = err.code;
+        if (typeof code === 'string')
+            return code;
+    }
+    return undefined;
+}
+export async function checkGhCli() {
+    try {
+        const { stdout } = await execFileAsync('gh', ['--version'], { timeout: GH_CMD_TIMEOUT_MS });
+        const versionLine = stdout.split('\n')[0]?.trim() || 'gh present';
+        return { name: 'gh CLI installed', status: 'ok', message: versionLine };
+    }
+    catch (err) {
+        // Distinguish "not on PATH" (ENOENT) from "present but broken" (anything
+        // else — spawn errors, timeouts, permission denied, non-zero exit). Telling
+        // users to "install gh" when gh is already installed is actively misleading.
+        const code = errCode(err);
+        if (code === 'ENOENT') {
+            return {
+                name: 'gh CLI installed',
+                status: 'warning',
+                message: 'gh CLI not found on PATH',
+                remediation: 'Install the GitHub CLI from https://cli.github.com/',
+            };
+        }
+        return {
+            name: 'gh CLI installed',
+            status: 'warning',
+            message: `gh CLI present but failed to run: ${errorMessage(err)}`,
+            remediation: 'Check that `gh --version` works in your shell; a timeout or permission error may indicate a broken install',
+        };
+    }
+}
+export async function checkGhAuth() {
+    try {
+        await execFileAsync('gh', ['auth', 'status'], { timeout: GH_CMD_TIMEOUT_MS });
+        return { name: 'gh CLI authenticated', status: 'ok', message: 'Signed in to github.com' };
+    }
+    catch (err) {
+        // `gh auth status` also exits non-zero on network/proxy failures and TLS
+        // issues reaching github.com — not only when the user isn't logged in.
+        // Mentioning both paths in the remediation avoids misleading users whose
+        // problem is connectivity, not auth.
+        return {
+            name: 'gh CLI authenticated',
+            status: 'warning',
+            message: `gh auth status failed: ${errorMessage(err)}`,
+            remediation: 'Run `gh auth login` to authenticate, or check network/proxy connectivity if the error looks network-related',
+        };
+    }
+}
+export async function checkGitHubToken(preloadedToken) {
+    const token = preloadedToken !== undefined ? preloadedToken : await getGitHubTokenAsync();
+    if (!token) {
+        return {
+            name: 'GitHub token resolvable',
+            status: 'warning',
+            message: 'No GitHub token available via $GITHUB_TOKEN or `gh auth token`',
+            remediation: 'Set $GITHUB_TOKEN or run `gh auth login`',
+        };
+    }
+    try {
+        const octokit = getOctokit(token);
+        const { data } = await octokit.users.getAuthenticated();
+        return {
+            name: 'GitHub token resolvable',
+            status: 'ok',
+            message: `Authenticated as @${data.login}`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'GitHub token resolvable',
+            status: 'error',
+            message: `Token present but API auth failed: ${errorMessage(err)}`,
+            remediation: 'Token may be expired or revoked — run `gh auth refresh` or set a fresh $GITHUB_TOKEN',
+        };
+    }
+}
+/**
+ * Locate `packages/core/dist/cli.bundle.cjs` across the two runtime contexts
+ * this code can run in:
+ *
+ *   - Dev (tsx): `__dirname` = `.../packages/core/src/commands`, bundle sits
+ *     two levels up in `../../dist/cli.bundle.cjs`.
+ *   - Bundled (cjs): `__dirname` = `.../packages/core/dist`, bundle sits at
+ *     `./cli.bundle.cjs` in that same directory.
+ */
+function resolveBundlePaths() {
+    const devBundle = path.resolve(__dirname, '../../dist/cli.bundle.cjs');
+    const coDirBundle = path.resolve(__dirname, 'cli.bundle.cjs');
+    const devSource = path.resolve(__dirname, '../cli.ts');
+    const coDirSource = path.resolve(__dirname, '../src/cli.ts');
+    // Prefer whichever resolves an existing file; fall back to dev paths so the
+    // "missing" branches in checkBundleUpToDate still have a sensible path to
+    // report.
+    const bundlePath = fs.existsSync(devBundle) ? devBundle : fs.existsSync(coDirBundle) ? coDirBundle : devBundle;
+    const sourcePath = fs.existsSync(devSource) ? devSource : fs.existsSync(coDirSource) ? coDirSource : devSource;
+    return { bundlePath, sourcePath };
+}
+/**
+ * Try `fs.statSync`; if the file is merely missing (ENOENT), return null.
+ * For other fs errors (EACCES, ELOOP, ENOTDIR, …) surface the error so the
+ * caller can report it instead of misdiagnosing it as "file missing."
+ */
+function tryStat(p) {
+    try {
+        return { stat: fs.statSync(p) };
+    }
+    catch (err) {
+        if (errCode(err) === 'ENOENT')
+            return { stat: null };
+        return { stat: null, error: err };
+    }
+}
+/**
+ * Bundle-freshness check only fires when the *source* file is present — that's
+ * the dev-repo workflow. npm consumers install the pre-built bundle with no
+ * source, so we just confirm the bundle exists.
+ */
+export function checkBundleUpToDate(options) {
+    const resolved = resolveBundlePaths();
+    const bundlePath = options?.bundlePath ?? resolved.bundlePath;
+    const sourcePath = options?.sourcePath ?? resolved.sourcePath;
+    const bundleResult = tryStat(bundlePath);
+    const sourceResult = tryStat(sourcePath);
+    if (bundleResult.error || sourceResult.error) {
+        const err = bundleResult.error ?? sourceResult.error;
+        return {
+            name: 'CLI bundle',
+            status: 'error',
+            message: `Bundle freshness check failed: ${errorMessage(err)}`,
+            remediation: 'Check filesystem permissions on packages/core/dist/',
+        };
+    }
+    const bundleStat = bundleResult.stat;
+    const sourceStat = sourceResult.stat;
+    if (!bundleStat && !sourceStat) {
+        return {
+            name: 'CLI bundle',
+            status: 'warning',
+            message: 'Neither cli.ts nor cli.bundle.cjs could be located',
+            remediation: 'Reinstall the package or check your install location',
+        };
+    }
+    if (!bundleStat) {
+        return {
+            name: 'CLI bundle',
+            status: 'warning',
+            message: 'dist/cli.bundle.cjs not built yet',
+            remediation: 'Run `pnpm run bundle` to build the CLI bundle',
+        };
+    }
+    if (sourceStat && sourceStat.mtimeMs > bundleStat.mtimeMs) {
+        return {
+            name: 'CLI bundle',
+            status: 'warning',
+            message: 'Source files are newer than dist/cli.bundle.cjs',
+            remediation: 'Run `pnpm run bundle` to rebuild',
+        };
+    }
+    return { name: 'CLI bundle', status: 'ok', message: 'Bundle present and up-to-date' };
+}
+export function checkStateFile(options) {
+    const statePath = options?.statePathOverride ?? getStatePath();
+    if (!fs.existsSync(statePath)) {
+        return {
+            name: 'state.json valid',
+            status: 'ok',
+            message: 'No state.json yet (first run — nothing to validate)',
+        };
+    }
+    try {
+        const raw = fs.readFileSync(statePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const result = AgentStateSchema.safeParse(parsed);
+        if (!result.success) {
+            const snippet = result.error.issues
+                .slice(0, 3)
+                .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
+                .join('; ');
+            return {
+                name: 'state.json valid',
+                status: 'error',
+                message: `state.json failed schema validation — ${snippet}`,
+                remediation: 'Restore from a backup in `~/.oss-autopilot/backups/` or re-run `oss-autopilot init`',
+            };
+        }
+        const version = typeof parsed?.version === 'number' ? parsed.version : '?';
+        return { name: 'state.json valid', status: 'ok', message: `state v${version} parses and validates` };
+    }
+    catch (err) {
+        return {
+            name: 'state.json valid',
+            status: 'error',
+            message: `Failed to read/parse state.json: ${errorMessage(err)}`,
+            remediation: 'Restore from a backup in `~/.oss-autopilot/backups/`',
+        };
+    }
+}
+const defaultScoutImporter = () => import('@oss-scout/core');
+export async function checkScoutResolvable(importer = defaultScoutImporter) {
+    // The scout package is ESM-exports-only, so `require.resolve` fails even
+    // when it's installed. `import()` goes through the ESM resolver, which
+    // honors `exports` maps correctly. Dynamic import only loads the package
+    // on demand (not at doctor module load) and is cheap — no auth side effects.
+    try {
+        await importer();
+        return { name: '@oss-scout/core resolvable', status: 'ok', message: 'Found on module path' };
+    }
+    catch (err) {
+        // Three outcomes we want to distinguish:
+        //   - "Package simply isn't installed" (missing from node_modules)
+        //   - "Package is present but the install is corrupt" (bad exports map,
+        //     unparseable source, missing internal file) — reinstall is the fix
+        //   - "Package loaded but threw during init" — this is a scout bug
+        const code = errCode(err);
+        const isNotFound = code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND';
+        const isCorruptInstall = code === 'ERR_PACKAGE_PATH_NOT_EXPORTED' ||
+            code === 'ERR_PACKAGE_IMPORT_NOT_DEFINED' ||
+            code === 'ERR_INVALID_PACKAGE_CONFIG' ||
+            err instanceof SyntaxError;
+        const reinstallRequired = isNotFound || isCorruptInstall;
+        return {
+            name: '@oss-scout/core resolvable',
+            status: 'error',
+            message: reinstallRequired
+                ? `@oss-scout/core cannot be loaded (install issue): ${errorMessage(err)}`
+                : `@oss-scout/core failed to load: ${errorMessage(err)}`,
+            remediation: reinstallRequired
+                ? 'Reinstall dependencies (`pnpm install` or `npm install`)'
+                : 'Scout loaded but threw during initialization — report this as a bug in oss-scout with the error above',
+        };
+    }
+}
+export async function checkGitHubRateLimit(preloadedToken) {
+    const token = preloadedToken !== undefined ? preloadedToken : await getGitHubTokenAsync();
+    if (!token) {
+        return {
+            name: 'GitHub rate limit',
+            status: 'warning',
+            message: 'Cannot check — no token available',
+            remediation: 'Set $GITHUB_TOKEN or run `gh auth login` to enable API-backed checks',
+        };
+    }
+    try {
+        const octokit = getOctokit(token);
+        const { data } = await octokit.rateLimit.get();
+        const core = data.resources.core;
+        const resetAt = new Date(core.reset * 1000).toISOString();
+        if (core.remaining < 100) {
+            return {
+                name: 'GitHub rate limit',
+                status: 'warning',
+                message: `Only ${core.remaining}/${core.limit} core requests remaining (resets at ${resetAt})`,
+                remediation: 'Wait for the window to reset or use a token with a higher limit',
+            };
+        }
+        return {
+            name: 'GitHub rate limit',
+            status: 'ok',
+            message: `${core.remaining}/${core.limit} core requests remaining`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'GitHub rate limit',
+            status: 'error',
+            message: `Failed to check rate limit: ${errorMessage(err)}`,
+        };
+    }
+}
+// ── Orchestrator ────────────────────────────────────────────────────────
+/**
+ * Run all diagnostic checks and return a structured report.
+ *
+ * Checks are run concurrently where possible. None of the checks throw — each
+ * returns a `DoctorCheck` with its own status so a single failing check does
+ * not abort the rest of the audit.
+ */
+/**
+ * Run a check defensively. If it rejects or the run itself throws, convert the
+ * failure into a synthetic `DoctorCheck` with status 'error' — `doctor` is the
+ * tool users reach for when things are already broken, so it must never abort
+ * itself because one individual check crashed.
+ */
+async function runCheckSafely(name, runner) {
+    try {
+        return await runner();
+    }
+    catch (err) {
+        return {
+            name,
+            status: 'error',
+            message: `Check crashed unexpectedly: ${errorMessage(err)}`,
+            remediation: 'This is a bug in the doctor command — please report it with the error above',
+        };
+    }
+}
+export async function runDoctor() {
+    // Pre-resolve the token once and pass it to the token-dependent checks.
+    // Without this, the first call enters the async `gh auth token` branch
+    // (setting `tokenFetchAttempted = true` synchronously, then yielding at the
+    // `execFile` await). A second concurrent caller sees the flag set and the
+    // cache still empty, and returns `null` immediately — producing a spurious
+    // "no token available" warning while the first caller later resolves a valid
+    // token. Empirically reproduced before this fix.
+    // Best-effort token fetch — if it throws (sync or async), downstream
+    // token-dependent checks still run and will report "no token available" on
+    // their own. `try/catch` covers the sync-throw case; `.catch` alone would
+    // not.
+    let token = null;
+    try {
+        token = await getGitHubTokenAsync();
+    }
+    catch {
+        token = null;
+    }
+    const checks = await Promise.all([
+        runCheckSafely('gh CLI installed', () => checkGhCli()),
+        runCheckSafely('gh CLI authenticated', () => checkGhAuth()),
+        runCheckSafely('GitHub token resolvable', () => checkGitHubToken(token)),
+        runCheckSafely('GitHub rate limit', () => checkGitHubRateLimit(token)),
+        runCheckSafely('@oss-scout/core resolvable', () => checkScoutResolvable()),
+        runCheckSafely('CLI bundle', () => checkBundleUpToDate()),
+        runCheckSafely('state.json valid', () => checkStateFile()),
+    ]);
+    const summary = {
+        ok: checks.filter((c) => c.status === 'ok').length,
+        warnings: checks.filter((c) => c.status === 'warning').length,
+        errors: checks.filter((c) => c.status === 'error').length,
+    };
+    return { checks, summary };
+}

package/dist/commands/index.d.ts

@@ -67,6 +67,8 @@ export { runStateUnlink } from './state-cmd.js';
 export { runParseList, pruneIssueList } from './parse-list.js';
 /** Check if new files are properly referenced/integrated. */
 export { runCheckIntegration } from './check-integration.js';
+/** System-health diagnostic — verifies tokens, bundle, state, scout, rate limit. */
+export { runDoctor, type DoctorCheck, type DoctorCheckStatus, type DoctorOutput } from './doctor.js';
 /** Detect formatters/linters configured in a local repository (#703). */
 export { runDetectFormatters } from './detect-formatters.js';
 /** Scan for locally cloned repos. */

package/dist/commands/index.js

@@ -73,6 +73,8 @@ export { runStateUnlink } from './state-cmd.js';
 export { runParseList, pruneIssueList } from './parse-list.js';
 /** Check if new files are properly referenced/integrated. */
 export { runCheckIntegration } from './check-integration.js';
+/** System-health diagnostic — verifies tokens, bundle, state, scout, rate limit. */
+export { runDoctor } from './doctor.js';
 /** Detect formatters/linters configured in a local repository (#703). */
 export { runDetectFormatters } from './detect-formatters.js';
 /** Scan for locally cloned repos. */

package/dist/commands/move.d.ts

@@ -17,8 +17,7 @@ export interface MoveOutput {
  * @param options.prUrl - Full GitHub PR URL
  * @param options.target - Target state: 'attention' | 'waiting' | 'shelved' | 'auto'
  * @returns The move result with a human-readable description
- * @throws {ValidationError} If the URL is not a valid GitHub PR URL
- * @throws {Error} If the target is invalid
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL or the target is invalid
  */
 export declare function runMove(options: {
     prUrl: string;

package/dist/commands/move.js

@@ -2,8 +2,10 @@
  * Move command — transition a PR between states:
  * attention, waiting, shelved, or auto (reset to computed status).
  */
-import { getStateManager } from '../core/index.js';
+import { getStateManager, maybeCheckpoint } from '../core/index.js';
+import { ValidationError } from '../core/errors.js';
 import { PR_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
+const MODULE = 'move';
 export const VALID_TARGETS = ['attention', 'waiting', 'shelved', 'auto'];
 /**
  * Move a PR between states: attention, waiting, shelved, or auto (computed).
@@ -12,15 +14,14 @@ export const VALID_TARGETS = ['attention', 'waiting', 'shelved', 'auto'];
  * @param options.prUrl - Full GitHub PR URL
  * @param options.target - Target state: 'attention' | 'waiting' | 'shelved' | 'auto'
  * @returns The move result with a human-readable description
- * @throws {ValidationError} If the URL is not a valid GitHub PR URL
- * @throws {Error} If the target is invalid
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL or the target is invalid
  */
 export async function runMove(options) {
     validateUrl(options.prUrl);
     validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR');
     const target = options.target;
     if (!VALID_TARGETS.includes(target)) {
-        throw new Error(`Invalid target "${options.target}". Must be one of: ${VALID_TARGETS.join(', ')}`);
+        throw new ValidationError(`Invalid target "${options.target}". Must be one of: ${VALID_TARGETS.join(', ')}`);
     }
     const stateManager = getStateManager();
     switch (target) {
@@ -35,6 +36,7 @@ export async function runMove(options) {
                 stateManager.setStatusOverride(options.prUrl, status, lastActivityAt);
                 stateManager.unshelvePR(options.prUrl);
             });
+            await maybeCheckpoint(stateManager, MODULE);
             return { url: options.prUrl, target, description: `Moved to ${label}` };
         }
         case 'shelved': {
@@ -42,6 +44,7 @@ export async function runMove(options) {
                 stateManager.shelvePR(options.prUrl);
                 stateManager.clearStatusOverride(options.prUrl);
             });
+            await maybeCheckpoint(stateManager, MODULE);
             return {
                 url: options.prUrl,
                 target,
@@ -53,6 +56,7 @@ export async function runMove(options) {
                 stateManager.clearStatusOverride(options.prUrl);
                 stateManager.unshelvePR(options.prUrl);
             });
+            await maybeCheckpoint(stateManager, MODULE);
             return {
                 url: options.prUrl,
                 target,

package/dist/commands/read.js

@@ -3,10 +3,11 @@
  * In v2, PR read/unread state is not tracked locally.
  * This command is a no-op preserved for backward compatibility.
  */
+import { ValidationError } from '../core/errors.js';
 import { validateUrl } from './validation.js';
 export async function runRead(options) {
     if (!options.all && !options.prUrl) {
-        throw new Error('PR URL or --all flag required');
+        throw new ValidationError('PR URL or --all flag required');
     }
     if (options.prUrl) {
         validateUrl(options.prUrl);

package/dist/commands/search.d.ts

@@ -13,22 +13,4 @@ export declare const MAX_SEARCH_RESULTS = 100;
 interface SearchOptions {
     maxResults: number;
 }
-/**
- * Search GitHub for contributable issues using multi-phase discovery.
- *
- * @param options - Search configuration
- * @param options.maxResults - Maximum number of candidates to return
- * @returns Search results with scored candidates and exclusion lists
- * @throws {ConfigurationError} If no GitHub token is available
- *
- * @example
- * ```typescript
- * import { runSearch } from '@oss-autopilot/core/commands';
- *
- * const results = await runSearch({ maxResults: 10 });
- * for (const c of results.candidates) {
- *   console.log(`${c.issue.repo}#${c.issue.number} — ${c.viabilityScore}/100`);
- * }
- * ```
- */
 export declare function runSearch(options: SearchOptions): Promise<SearchOutput>;

package/dist/commands/search.js

@@ -4,6 +4,9 @@
  */
 import { createAutopilotScout } from './scout-bridge.js';
 import { getStateManager } from '../core/index.js';
+import { gradeFromCandidate } from '../core/issue-grading.js';
+import { warn } from '../core/logger.js';
+const MODULE = 'search';
 /**
  * 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
@@ -28,6 +31,19 @@ export const MAX_SEARCH_RESULTS = 100;
  * }
  * ```
  */
+/**
+ * Coerce scout's raw `viabilityScore` into a trustworthy 0–100 number.
+ * Scout is supposed to emit a finite integer in range, but out-of-contract
+ * values (NaN, Infinity, negative, >100, non-number) would otherwise flow
+ * straight through to consumers. Defend at the boundary — see #1043.
+ */
+function sanitizeViabilityScore(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0 || raw > 100) {
+        warn(MODULE, `Ignoring out-of-contract viabilityScore from scout: ${JSON.stringify(raw)}`);
+        return 0;
+    }
+    return raw;
+}
 export async function runSearch(options) {
     const scout = await createAutopilotScout();
     const result = await scout.search({ maxResults: options.maxResults });
@@ -35,6 +51,26 @@ export async function runSearch(options) {
     const searchOutput = {
         candidates: result.candidates.map((c) => {
             const repoScoreRecord = stateManager.getRepoScore(c.issue.repo);
+            // Scout's `search` does not emit per-candidate projectHealth (only
+            // `vetIssue` does). Pass a sentinel `checkFailed: true` so the grader
+            // correctly treats scout-side signals as unknown and grades purely from
+            // the autopilot-tracked repoScore. Candidates without a repoScore
+            // receive 'F' — that's an honest signal for "we haven't seen this repo
+            // before" rather than a fabricated score.
+            const grade = gradeFromCandidate({
+                repo: c.issue.repo,
+                projectHealth: { avgIssueResponseDays: null, daysSinceLastCommit: null, checkFailed: true },
+                getRepoScore: (repo) => {
+                    const score = stateManager.getRepoScore(repo);
+                    return score
+                        ? {
+                            mergedPRCount: score.mergedPRCount,
+                            closedWithoutMergeCount: score.closedWithoutMergeCount,
+                            avgResponseDays: score.avgResponseDays ?? null,
+                        }
+                        : undefined;
+                },
+            });
             return {
                 issue: {
                     repo: c.issue.repo,
@@ -48,7 +84,8 @@ export async function runSearch(options) {
                 reasonsToApprove: c.reasonsToApprove,
                 reasonsToSkip: c.reasonsToSkip,
                 searchPriority: c.searchPriority,
-                viabilityScore: c.viabilityScore,
+                viabilityScore: sanitizeViabilityScore(c.viabilityScore),
+                grade,
                 repoScore: repoScoreRecord
                     ? {
                         score: repoScoreRecord.score,

package/dist/commands/setup.js

@@ -2,7 +2,7 @@
  * Setup command
  * Interactive setup / configuration
  */
-import { getStateManager, DEFAULT_CONFIG } from '../core/index.js';
+import { getStateManager, DEFAULT_CONFIG, formatUnknownKeyError, getSetupKeys } from '../core/index.js';
 import { ValidationError } from '../core/errors.js';
 import { validateGitHubUsername } from './validation.js';
 import { PROJECT_CATEGORIES, ISSUE_SCOPES, DIFF_TOOLS, } from '../core/types.js';
@@ -34,6 +34,18 @@ export async function runSetup(options) {
     if (options.set && options.set.length > 0) {
         const results = {};
         const warnings = [];
+        // Pre-validate every key before mutating state. `stateManager.batch()` only
+        // defers the disk write — it does not snapshot in-memory state, so throwing
+        // mid-loop would leave earlier successful updates applied in memory (a real
+        // issue for long-running consumers like the MCP server and dashboard that
+        // share the StateManager singleton across requests).
+        const knownKeys = new Set(getSetupKeys());
+        for (const setting of options.set) {
+            const [key] = setting.split('=');
+            if (!knownKeys.has(key)) {
+                throw new ValidationError(formatUnknownKeyError(key, 'setup'));
+            }
+        }
         stateManager.batch(() => {
             for (const setting of options.set) {
                 const [key, ...valueParts] = setting.split('=');
@@ -89,6 +101,34 @@ export async function runSetup(options) {
                         results[key] = String(stars);
                         break;
                     }
+                    case 'maxIssueAgeDays': {
+                        const days = parsePositiveInt(value, 'maxIssueAgeDays');
+                        stateManager.updateConfig({ maxIssueAgeDays: days });
+                        results[key] = String(days);
+                        break;
+                    }
+                    case 'minRepoScoreThreshold': {
+                        const threshold = Number(value);
+                        if (!Number.isInteger(threshold) || threshold < 0) {
+                            throw new ValidationError(`Invalid value for minRepoScoreThreshold: "${value}". Must be a non-negative integer.`);
+                        }
+                        stateManager.updateConfig({ minRepoScoreThreshold: threshold });
+                        results[key] = String(threshold);
+                        break;
+                    }
+                    case 'skippedIssuesPath':
+                        stateManager.updateConfig({ skippedIssuesPath: value || undefined });
+                        results[key] = value || '(cleared)';
+                        break;
+                    case 'autoFormatBeforePush': {
+                        if (value !== 'true' && value !== 'false') {
+                            throw new ValidationError(`Invalid value for autoFormatBeforePush: "${value}". Must be "true" or "false".`);
+                        }
+                        const enabled = value === 'true';
+                        stateManager.updateConfig({ autoFormatBeforePush: enabled });
+                        results[key] = String(enabled);
+                        break;
+                    }
                     case 'includeDocIssues':
                         stateManager.updateConfig({ includeDocIssues: value === 'true' });
                         results[key] = value === 'true' ? 'true' : 'false';
@@ -221,7 +261,7 @@ export async function runSetup(options) {
                         }
                         break;
                     default:
-                        warnings.push(`Unknown setting: ${key}`);
+                        throw new ValidationError(formatUnknownKeyError(key, 'setup'));
                 }
             }
         });

package/dist/commands/shelve.js

@@ -7,8 +7,9 @@
  * which also clears status overrides. These functions match that behavior
  * to keep the library API consistent.
  */
-import { getStateManager } from '../core/index.js';
+import { getStateManager, maybeCheckpoint } from '../core/index.js';
 import { PR_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
+const MODULE = 'shelve';
 // Re-export for backward compatibility with tests
 export { PR_URL_PATTERN };
 /**
@@ -28,6 +29,7 @@ export async function runShelve(options) {
         added = stateManager.shelvePR(options.prUrl);
         stateManager.clearStatusOverride(options.prUrl);
     });
+    await maybeCheckpoint(stateManager, MODULE);
     return { shelved: added, url: options.prUrl };
 }
 /**
@@ -47,5 +49,6 @@ export async function runUnshelve(options) {
         removed = stateManager.unshelvePR(options.prUrl);
         stateManager.clearStatusOverride(options.prUrl);
     });
+    await maybeCheckpoint(stateManager, MODULE);
     return { unshelved: removed, url: options.prUrl };
 }

package/dist/commands/skip-add.js

@@ -19,7 +19,7 @@ function formatUtcDate(d) {
 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.');
+        throw new Error('No skipped-issues path configured. Set one via `oss-autopilot setup --set skippedIssuesPath=<path>` or pass --path.');
     }
     if (!GITHUB_URL_RE.test(options.issueUrl)) {
         throw new Error(`Invalid GitHub issue or PR URL: ${options.issueUrl}`);