@oss-autopilot/core 1.16.2 → 1.17.1

package/dist/core/dashboard-data-schema.js

@@ -0,0 +1,80 @@
+/**
+ * Runtime schema for the dashboard server's `GET /api/data` response (#1050).
+ *
+ * The server (`commands/dashboard-data.ts`) and client (`packages/dashboard/`)
+ * run in different processes. TypeScript can't cross the process boundary —
+ * if the server removes or renames a field, the client hits runtime
+ * `undefined` with no diagnostic. This schema is the shared runtime contract:
+ * the server can optionally self-check outgoing payloads, and the dashboard
+ * validates every `/api/data` response before committing to state.
+ *
+ * Intentional scope: this schema validates **top-level presence and primitive
+ * shape** (required vs optional fields, container types like array/object),
+ * but uses `z.array(z.unknown())` for nested PR/issue arrays rather than
+ * pinning every field. The top-level surface is the only place drift tends
+ * to go silently undetected — nested fields already blow up loudly at the
+ * render site when they change. Exhaustive nested validation would turn the
+ * schema into a maintenance burden.
+ */
+import { z } from 'zod';
+export const DashboardStatsSchema = z.object({
+    activePRs: z.number(),
+    shelvedPRs: z.number(),
+    mergedPRs: z.number(),
+    closedPRs: z.number(),
+    mergeRate: z.string(),
+    availableIssues: z.number().optional(),
+});
+const RepoStatsEntrySchema = z.object({
+    active: z.number(),
+    merged: z.number(),
+    closed: z.number(),
+});
+const TopRepoSchema = z.object({
+    repo: z.string(),
+    active: z.number(),
+    merged: z.number(),
+    closed: z.number(),
+});
+export const DashboardDataSchema = z.object({
+    stats: DashboardStatsSchema,
+    prsByRepo: z.record(z.string(), RepoStatsEntrySchema),
+    topRepos: z.array(TopRepoSchema),
+    monthlyMerged: z.record(z.string(), z.number()),
+    monthlyOpened: z.record(z.string(), z.number()),
+    monthlyClosed: z.record(z.string(), z.number()),
+    // PR / issue arrays are validated loosely — the domain shapes are pinned by
+    // AgentStateSchema (state-schema.ts) on the server side. Use `z.unknown()`
+    // here so server-side additions to the nested shape don't break the
+    // dashboard's parse; the UI handles unknown extra fields gracefully.
+    activePRs: z.array(z.unknown()),
+    shelvedPRUrls: z.array(z.string()),
+    recentlyMergedPRs: z.array(z.unknown()),
+    recentlyClosedPRs: z.array(z.unknown()),
+    autoUnshelvedPRs: z.array(z.unknown()),
+    commentedIssues: z.array(z.unknown()),
+    issueResponses: z.array(z.unknown()),
+    allMergedPRs: z.array(z.unknown()),
+    allClosedPRs: z.array(z.unknown()),
+    repoMetadata: z.record(z.string(), z.unknown()).optional(),
+    vettedIssues: z.unknown().nullable().optional(),
+    offline: z.boolean().optional(),
+    lastUpdated: z.string().optional(),
+    partialFailures: z.array(z.string()).optional(),
+});
+/**
+ * Validate a raw `/api/data` payload. Returns `{ok: true, data}` on success or
+ * `{ok: false, message}` with a condensed Zod error string on failure. Never
+ * throws. The dashboard's `useDashboard` hook surfaces the message in the UI.
+ */
+export function validateDashboardData(raw) {
+    const result = DashboardDataSchema.safeParse(raw);
+    if (result.success)
+        return { ok: true, data: result.data };
+    const issues = result.error.issues
+        .slice(0, 3)
+        .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
+        .join('; ');
+    const more = result.error.issues.length > 3 ? ` (+${result.error.issues.length - 3} more)` : '';
+    return { ok: false, message: `Server response did not match expected shape — ${issues}${more}` };
+}

package/dist/core/errors.d.ts

@@ -32,6 +32,20 @@ export declare class ValidationError extends OssAutopilotError {
 export declare class GistPermissionError extends ConfigurationError {
     constructor(message?: string);
 }
+/**
+ * Thrown when an optimistic compare-and-swap on state.json detects that
+ * another process wrote the file between load and save. See issue #1030.
+ *
+ * Library consumers should call `stateManager.reloadIfChanged()` and
+ * re-apply their mutation. The runtime `message` is phrased for CLI
+ * end-users; the structured `expectedMtimeMs` / `actualMtimeMs` fields
+ * are for programmatic handling.
+ */
+export declare class ConcurrencyError extends OssAutopilotError {
+    readonly expectedMtimeMs: number;
+    readonly actualMtimeMs: number;
+    constructor(expectedMtimeMs: number, actualMtimeMs: number);
+}
 /**
  * Extract a human-readable message from an unknown error value.
  */

package/dist/core/errors.js

@@ -49,6 +49,26 @@ export class GistPermissionError extends ConfigurationError {
         this.name = 'GistPermissionError';
     }
 }
+/**
+ * Thrown when an optimistic compare-and-swap on state.json detects that
+ * another process wrote the file between load and save. See issue #1030.
+ *
+ * Library consumers should call `stateManager.reloadIfChanged()` and
+ * re-apply their mutation. The runtime `message` is phrased for CLI
+ * end-users; the structured `expectedMtimeMs` / `actualMtimeMs` fields
+ * are for programmatic handling.
+ */
+export class ConcurrencyError extends OssAutopilotError {
+    expectedMtimeMs;
+    actualMtimeMs;
+    constructor(expectedMtimeMs, actualMtimeMs) {
+        super('Another oss-autopilot process wrote state.json concurrently. ' +
+            'Re-run the command to retry — the last write wins and no data was lost from the other process.', 'CONCURRENCY_ERROR');
+        this.expectedMtimeMs = expectedMtimeMs;
+        this.actualMtimeMs = actualMtimeMs;
+        this.name = 'ConcurrencyError';
+    }
+}
 /**
  * Extract a human-readable message from an unknown error value.
  */
@@ -126,6 +146,8 @@ export function resolveErrorCode(err) {
         return 'CONFIGURATION';
     if (err instanceof ValidationError)
         return 'VALIDATION';
+    if (err instanceof ConcurrencyError)
+        return 'CONCURRENCY';
     // Check HTTP status codes (Octokit errors)
     const status = getHttpStatusCode(err);
     if (status === 401)

package/dist/core/http-cache.d.ts

@@ -25,9 +25,10 @@ export interface CacheEntry {
  */
 export declare class HttpCache {
     private readonly cacheDir;
+    private readonly maxEntries;
     /** In-flight request deduplication map: URL -> Promise<response>. */
     private readonly inflightRequests;
-    constructor(cacheDir?: string);
+    constructor(cacheDir?: string, maxEntries?: number);
     /** Derive a filesystem-safe cache key from a URL. */
     private keyFor;
     /** Full path to the cache file for a given URL. */
@@ -46,6 +47,12 @@ export declare class HttpCache {
      * Store a response with its ETag.
      */
     set(url: string, etag: string, body: unknown): void;
+    /**
+     * If the cache directory exceeds `maxEntries`, evict the oldest entries
+     * (by mtime) until it's at the cap. Best-effort — any I/O failure is
+     * swallowed so cache-bookkeeping never breaks the request path.
+     */
+    private evictIfExceeds;
     /**
      * Check whether a URL has an in-flight request.
      */

package/dist/core/http-cache.js

@@ -23,6 +23,15 @@ const MODULE = 'http-cache';
  * `evictStale()` will remove them.
  */
 const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Soft cap on the number of entries kept on disk (#1057 M27). `set()`
+ * opportunistically evicts the oldest entries when the directory grows past
+ * this ceiling. The cap is deliberately high (2000) so it doesn't thrash a
+ * normal day's traffic — it's a belt-and-suspenders guard against unbounded
+ * growth on long-running sessions that accumulate cache files between the
+ * daily `evictStale()` sweep.
+ */
+const DEFAULT_MAX_ENTRIES = 2000;
 /**
  * File-based HTTP cache backed by `~/.oss-autopilot/cache/`.
  *
@@ -32,10 +41,12 @@ const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
  */
 export class HttpCache {
     cacheDir;
+    maxEntries;
     /** In-flight request deduplication map: URL -> Promise<response>. */
     inflightRequests = new Map();
-    constructor(cacheDir) {
+    constructor(cacheDir, maxEntries = DEFAULT_MAX_ENTRIES) {
         this.cacheDir = cacheDir ?? getCacheDir();
+        this.maxEntries = maxEntries;
     }
     /** Derive a filesystem-safe cache key from a URL. */
     keyFor(url) {
@@ -91,12 +102,59 @@ export class HttpCache {
         try {
             fs.writeFileSync(this.pathFor(url), JSON.stringify(entry), { encoding: 'utf-8', mode: 0o600 });
             debug(MODULE, `Cached response for ${url}`);
+            // Best-effort size cap (#1057 M27). Runs after each write rather than on
+            // a schedule so long-lived sessions can't accumulate past the cap.
+            this.evictIfExceeds(this.maxEntries);
         }
         catch (err) {
             // Non-fatal: cache write failure should not break the request
             debug(MODULE, `Failed to write cache for ${url}`, err);
         }
     }
+    /**
+     * If the cache directory exceeds `maxEntries`, evict the oldest entries
+     * (by mtime) until it's at the cap. Best-effort — any I/O failure is
+     * swallowed so cache-bookkeeping never breaks the request path.
+     */
+    evictIfExceeds(maxEntries) {
+        if (maxEntries <= 0)
+            return;
+        try {
+            const entries = fs.readdirSync(this.cacheDir).filter((f) => f.endsWith('.json'));
+            if (entries.length <= maxEntries)
+                return;
+            // Stat once; sort oldest first so we evict the stalest files.
+            const withMtime = entries
+                .map((file) => {
+                const fullPath = path.join(this.cacheDir, file);
+                try {
+                    return { fullPath, mtimeMs: fs.statSync(fullPath).mtimeMs };
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((e) => e !== null)
+                .sort((a, b) => a.mtimeMs - b.mtimeMs);
+            const toEvict = withMtime.length - maxEntries;
+            let evicted = 0;
+            for (let i = 0; i < toEvict; i++) {
+                try {
+                    fs.unlinkSync(withMtime[i].fullPath);
+                    evicted++;
+                }
+                catch {
+                    // Another process may have raced us — ignore.
+                }
+            }
+            if (evicted > 0) {
+                debug(MODULE, `Capped cache at ${maxEntries} entries: evicted ${evicted} oldest`);
+            }
+        }
+        catch {
+            // Cache dir missing / unreadable — not fatal.
+        }
+    }
     /**
      * Check whether a URL has an in-flight request.
      */

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, resetStateManager, type Stats, } from './state.js';
+export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, maybeCheckpoint, 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';
@@ -18,4 +18,6 @@ export { fetchPRTemplate, type PRTemplateResult } from './pr-template.js';
 export { classifyLinkedPR, type LinkedPR, type LinkedPRClassification, type LinkedPRState, } from './linked-pr-classification.js';
 export { scanForAntiLLMPolicy, type AntiLLMCategory, type AntiLLMMatch, type AntiLLMScanResult, } from './anti-llm-policy.js';
 export { detectFormatters, diagnoseCIFormatterFailure, getPreferredFormatter, type DetectedFormatter, type FormatterDetectionResult, type CIFormatterDiagnosis, type FormatterName, } from './formatter-detection.js';
+export { CONFIG_KEY_REGISTRY, type ConfigKeyDef, type SettableVia, isKnownKey, getKeyDef, getSetupKeys, getConfigKeys, suggestKey, formatUnknownKeyError, } from './config-registry.js';
+export { DashboardDataSchema, DashboardStatsSchema, validateDashboardData, type DashboardDataParsed, } from './dashboard-data-schema.js';
 export * from './types.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, resetStateManager, } from './state.js';
+export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, maybeCheckpoint, 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
@@ -19,4 +19,6 @@ export { fetchPRTemplate } from './pr-template.js';
 export { classifyLinkedPR, } from './linked-pr-classification.js';
 export { scanForAntiLLMPolicy, } from './anti-llm-policy.js';
 export { detectFormatters, diagnoseCIFormatterFailure, getPreferredFormatter, } from './formatter-detection.js';
+export { CONFIG_KEY_REGISTRY, isKnownKey, getKeyDef, getSetupKeys, getConfigKeys, suggestKey, formatUnknownKeyError, } from './config-registry.js';
+export { DashboardDataSchema, DashboardStatsSchema, validateDashboardData, } from './dashboard-data-schema.js';
 export * from './types.js';

package/dist/core/maintainer-analysis.js

@@ -50,9 +50,15 @@ export function extractMaintainerActionHints(commentBody, reviewDecision) {
     if (docKeywords.some((kw) => lower.includes(kw))) {
         hints.push('docs_requested');
     }
-    // Rebase requests
-    const rebaseKeywords = ['rebase', 'merge conflict', 'out of date', 'behind main', 'behind master'];
-    if (rebaseKeywords.some((kw) => lower.includes(kw))) {
+    // Rebase requests.
+    //
+    // The `rebase` term uses a word-boundary regex so past-tense mentions like
+    // "after rebasing this was fine" or "I already rebased this" don't trigger
+    // a rebase_requested hint (#1057 M30). The other phrases are specific
+    // enough that plain substring matching is sufficient.
+    const rebasePhrases = ['merge conflict', 'out of date', 'behind main', 'behind master'];
+    const hasRebaseWord = /\brebase\b/i.test(commentBody);
+    if (hasRebaseWord || rebasePhrases.some((kw) => lower.includes(kw))) {
         hints.push('rebase_requested');
     }
     return hints;

package/dist/core/pr-monitor.d.ts

@@ -33,6 +33,13 @@ export interface PRCheckFailure {
 export interface FetchPRsResult {
     prs: FetchedPR[];
     failures: PRCheckFailure[];
+    /**
+     * Non-fatal warnings accumulated while fetching. Currently populated when
+     * the GitHub Search API's 1000-result ceiling truncates the user's PR
+     * list — callers (daily, dashboard) surface these so users know the data
+     * may be incomplete (#1057 M25).
+     */
+    warnings?: string[];
 }
 /**
  * Fetches and enriches open PRs from GitHub for the configured user.

package/dist/core/pr-monitor.js

@@ -17,7 +17,7 @@ import { getStateManager } from './state.js';
 import { daysBetween, parseGitHubUrl, extractOwnerRepo, isOwnRepo, DEFAULT_CONCURRENCY } from './utils.js';
 import { determineStatus } from './status-determination.js';
 import { runWorkerPool } from './concurrency.js';
-import { ConfigurationError, ValidationError, errorMessage, getHttpStatusCode } from './errors.js';
+import { ConfigurationError, ValidationError, errorMessage, getHttpStatusCode, isRateLimitOrAuthError, } from './errors.js';
 import { paginateAll } from './pagination.js';
 import { debug, warn, timed } from './logger.js';
 import { getHttpCache, cachedRequest } from './http-cache.js';
@@ -96,9 +96,50 @@ export class PRMonitor {
         });
         allItems.push(...firstPage.data.items);
         const totalCount = firstPage.data.total_count;
-        debug('pr-monitor', `Found ${totalCount} open PRs`);
+        debug(MODULE, `Found ${totalCount} open PRs`);
         // Fetch remaining pages if needed (GitHub search API returns max 1000 results)
-        const totalPages = Math.min(Math.ceil(totalCount / perPage), 10); // Cap at 1000 results
+        const SEARCH_API_RESULT_CAP = 1000;
+        const MAX_PAGES = Math.ceil(SEARCH_API_RESULT_CAP / perPage); // 10 pages at per_page=100
+        const totalPages = Math.min(Math.ceil(totalCount / perPage), MAX_PAGES);
+        // Non-fatal warnings threaded into the result (#1057 M25). When the
+        // Search API's hard 1000-result ceiling truncates the user's PR list we
+        // previously silently dropped the overflow; now the caller can surface
+        // it so the daily digest doesn't quietly report a partial view.
+        const warnings = [];
+        // Guardrail: if the Search API returned zero PRs, cross-check the
+        // configured username against the authenticated viewer. A real failure
+        // mode was a stale/placeholder username (e.g. "example-user") silently
+        // producing zero results with no error — the dashboard just showed
+        // "0 active PRs" and looked like a fresh install. getAuthenticated is
+        // advisory; a failure here never breaks the fetch.
+        if (totalCount === 0) {
+            try {
+                const { data: viewer } = await this.octokit.users.getAuthenticated();
+                if (viewer.login.toLowerCase() !== config.githubUsername.toLowerCase()) {
+                    const message = `Configured GitHub username @${config.githubUsername} does not match ` +
+                        `authenticated user @${viewer.login}. Did you mean to run ` +
+                        `\`oss-autopilot config username ${viewer.login}\`? Zero PRs returned.`;
+                    warnings.push(message);
+                    warn(MODULE, message);
+                }
+            }
+            catch (err) {
+                // Rate-limit/401/403 errors must abort the run just like every sibling
+                // fetch in this pipeline — swallowing them here would mask the exact
+                // class of failure the guardrail is meant to surface (e.g. revoked
+                // token returning 401 while the unauthenticated Search above still
+                // succeeds with zero results).
+                if (isRateLimitOrAuthError(err))
+                    throw err;
+                debug(MODULE, `Could not cross-check viewer login: ${errorMessage(err)}`);
+            }
+        }
+        if (totalCount > SEARCH_API_RESULT_CAP) {
+            warnings.push(`GitHub Search API returned ${totalCount} PRs for @${config.githubUsername}, ` +
+                `but results are capped at ${SEARCH_API_RESULT_CAP}. ` +
+                `Showing the ${SEARCH_API_RESULT_CAP} most recently updated PRs.`);
+            warn(MODULE, warnings[warnings.length - 1]);
+        }
         while (page < totalPages) {
             page++;
             const nextPage = await this.octokit.search.issuesAndPullRequests({
@@ -149,7 +190,7 @@ export class PRMonitor {
                 return 0;
             return a.status === 'needs_addressing' ? -1 : 1;
         });
-        return { prs, failures };
+        return warnings.length > 0 ? { prs, failures, warnings } : { prs, failures };
     }
     /**
      * Fetch detailed information for a single PR

package/dist/core/repo-score-manager.d.ts

@@ -3,12 +3,26 @@
  * Functions that operate on AgentState for scoring, querying,
  * and computing aggregate statistics. Mutation functions modify
  * the passed state object in place; query functions are pure.
+ *
+ * **User-facing reference:** `docs/repo-scoring.md` — plain-language
+ * explanation of the formula and what a given score means.
  */
 import { AgentState, RepoScore, RepoScoreUpdate, StoredMergedPR, StoredClosedPR } from './types.js';
 /**
- * Calculate the score based on the repo's metrics.
- * Base 5, logarithmic merge bonus (max +5), -1 per closed without merge (max -3),
- * +1 if recently merged (within 90 days), +1 if responsive, -2 if hostile. Clamp 1-10.
+ * Calculate a 1–10 score for a repo based on the user's PR history and the
+ * repo's maintainer-health signals.
+ *
+ * Formula (all constants named above with rationale):
+ *   BASE_SCORE
+ *     + min(round(log2(merged + 1) * MERGE_BONUS_COEFFICIENT), MERGE_BONUS_CAP)
+ *     − min(closedWithoutMergeCount, CLOSED_PENALTY_CAP)
+ *     + (lastMergedAt within RECENCY_WINDOW_DAYS ? RECENCY_BONUS : 0)
+ *     + (isResponsive ? RESPONSIVENESS_BONUS : 0)
+ *     − (hasHostileComments ? HOSTILITY_PENALTY : 0)
+ *   clamped to [SCORE_MIN, SCORE_MAX].
+ *
+ * See `docs/repo-scoring.md` for user-facing intent and what a given
+ * score means in practice.
  */
 export declare function calculateScore(repoScore: RepoScore): number;
 /**

package/dist/core/repo-score-manager.js

@@ -3,11 +3,36 @@
  * Functions that operate on AgentState for scoring, querying,
  * and computing aggregate statistics. Mutation functions modify
  * the passed state object in place; query functions are pure.
+ *
+ * **User-facing reference:** `docs/repo-scoring.md` — plain-language
+ * explanation of the formula and what a given score means.
  */
 import { isBelowMinStars } from './types.js';
 import { debug, warn } from './logger.js';
 import { parseGitHubUrl } from './utils.js';
 const MODULE = 'scoring';
+// ── Scoring constants (#1054) ─────────────────────────────────────────
+// Previously inlined as magic numbers in `calculateScore`. Extracted with
+// rationale comments so the formula is auditable without source spelunking.
+// Changing any of these is a behavior change — update docs/repo-scoring.md
+// and the tests below in lockstep.
+/** Starting point before any signals are applied. Deliberately optimistic so first-time repos aren't punished. */
+const BASE_SCORE = 5;
+/** Logarithmic merge bonus: 1 merge→+2, 2→+3, 3→+4, 4+→+5. Log instead of linear so a 20th merge doesn't dominate. */
+const MERGE_BONUS_COEFFICIENT = 2;
+const MERGE_BONUS_CAP = 5;
+/** −1 per closed-without-merge PR, capped so a few rejections don't zero out an otherwise-healthy repo. */
+const CLOSED_PENALTY_CAP = 3;
+/** Repos whose most-recent merge is within this window get a +1 freshness bonus. */
+const RECENCY_WINDOW_DAYS = 90;
+const RECENCY_BONUS = 1;
+/** +1 when the repo's signals say maintainers respond to PRs (per-PR computed; see issue-grading.ts). */
+const RESPONSIVENESS_BONUS = 1;
+/** −2 when hostile maintainer comments have been detected (e.g., explicit rejection of PRs without review). */
+const HOSTILITY_PENALTY = 2;
+/** Final clamp — scores always land in this inclusive range. */
+const SCORE_MIN = 1;
+const SCORE_MAX = 10;
 /** Repo scores older than this are considered stale and excluded from low-scoring lists. */
 const SCORE_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 /**
@@ -16,7 +41,7 @@ const SCORE_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 function createDefaultRepoScore(repo) {
     return {
         repo,
-        score: 5, // Base score
+        score: BASE_SCORE,
         mergedPRCount: 0,
         closedWithoutMergeCount: 0,
         avgResponseDays: null,
@@ -29,21 +54,28 @@ function createDefaultRepoScore(repo) {
     };
 }
 /**
- * Calculate the score based on the repo's metrics.
- * Base 5, logarithmic merge bonus (max +5), -1 per closed without merge (max -3),
- * +1 if recently merged (within 90 days), +1 if responsive, -2 if hostile. Clamp 1-10.
+ * Calculate a 1–10 score for a repo based on the user's PR history and the
+ * repo's maintainer-health signals.
+ *
+ * Formula (all constants named above with rationale):
+ *   BASE_SCORE
+ *     + min(round(log2(merged + 1) * MERGE_BONUS_COEFFICIENT), MERGE_BONUS_CAP)
+ *     − min(closedWithoutMergeCount, CLOSED_PENALTY_CAP)
+ *     + (lastMergedAt within RECENCY_WINDOW_DAYS ? RECENCY_BONUS : 0)
+ *     + (isResponsive ? RESPONSIVENESS_BONUS : 0)
+ *     − (hasHostileComments ? HOSTILITY_PENALTY : 0)
+ *   clamped to [SCORE_MIN, SCORE_MAX].
+ *
+ * See `docs/repo-scoring.md` for user-facing intent and what a given
+ * score means in practice.
  */
 export function calculateScore(repoScore) {
-    let score = 5; // Base score
-    // Logarithmic merge bonus (max +5): 1→+2, 2→+3, 3→+4, 4+→+5
+    let score = BASE_SCORE;
     if (repoScore.mergedPRCount > 0) {
-        const mergedBonus = Math.min(Math.round(Math.log2(repoScore.mergedPRCount + 1) * 2), 5);
+        const mergedBonus = Math.min(Math.round(Math.log2(repoScore.mergedPRCount + 1) * MERGE_BONUS_COEFFICIENT), MERGE_BONUS_CAP);
         score += mergedBonus;
     }
-    // -1 per closed without merge (max -3)
-    const closedPenalty = Math.min(repoScore.closedWithoutMergeCount, 3);
-    score -= closedPenalty;
-    // +1 if lastMergedAt is set and within 90 days (recency)
+    score -= Math.min(repoScore.closedWithoutMergeCount, CLOSED_PENALTY_CAP);
     if (repoScore.lastMergedAt) {
         const lastMergedDate = new Date(repoScore.lastMergedAt);
         if (isNaN(lastMergedDate.getTime())) {
@@ -52,21 +84,18 @@ export function calculateScore(repoScore) {
         else {
             const msPerDay = 1000 * 60 * 60 * 24;
             const daysSince = Math.floor((Date.now() - lastMergedDate.getTime()) / msPerDay);
-            if (daysSince <= 90) {
-                score += 1;
+            if (daysSince <= RECENCY_WINDOW_DAYS) {
+                score += RECENCY_BONUS;
             }
         }
     }
-    // +1 if responsive
     if (repoScore.signals.isResponsive) {
-        score += 1;
+        score += RESPONSIVENESS_BONUS;
     }
-    // -2 if hostile
     if (repoScore.signals.hasHostileComments) {
-        score -= 2;
+        score -= HOSTILITY_PENALTY;
     }
-    // Clamp to 1-10
-    return Math.max(1, Math.min(10, score));
+    return Math.max(SCORE_MIN, Math.min(SCORE_MAX, score));
 }
 /**
  * Get the score record for a repository.

package/dist/core/state-persistence.d.ts

@@ -52,9 +52,22 @@ export declare function loadState(): {
 /**
  * Persist state to disk, creating a timestamped backup of the previous
  * state file first. Retains at most 10 backup files.
+ *
+ * When `expectedMtimeMs` is provided (non-null, non-zero), implements
+ * optimistic compare-and-swap: if the on-disk file has been modified since
+ * the caller last loaded it, throws `ConcurrencyError` instead of
+ * overwriting. This prevents the classic read-modify-write lost-update
+ * race across processes (see issue #1030). Pass `null` / `0` to disable
+ * the check (first write, or when the caller has already reloaded).
+ *
+ * The check runs *inside* the advisory lock so the compare-and-swap is
+ * atomic with respect to the write.
+ *
  * @returns The file's mtime after writing (for change detection).
+ * @throws ConcurrencyError when `expectedMtimeMs` is provided and the
+ *   on-disk mtime no longer matches.
  */
-export declare function saveState(state: Readonly<AgentState>): number;
+export declare function saveState(state: Readonly<AgentState>, expectedMtimeMs?: number | null): number;
 /**
  * Re-read state from disk if the file has been modified since the last load/save.
  * Uses mtime comparison (single statSync call) to avoid unnecessary JSON parsing.

package/dist/core/state-persistence.js

@@ -7,7 +7,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { AgentStateSchema } from './state-schema.js';
 import { getStatePath, getBackupDir, getDataDir } from './utils.js';
-import { errorMessage } from './errors.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
@@ -439,15 +439,37 @@ function cleanupBackups() {
 /**
  * Persist state to disk, creating a timestamped backup of the previous
  * state file first. Retains at most 10 backup files.
+ *
+ * When `expectedMtimeMs` is provided (non-null, non-zero), implements
+ * optimistic compare-and-swap: if the on-disk file has been modified since
+ * the caller last loaded it, throws `ConcurrencyError` instead of
+ * overwriting. This prevents the classic read-modify-write lost-update
+ * race across processes (see issue #1030). Pass `null` / `0` to disable
+ * the check (first write, or when the caller has already reloaded).
+ *
+ * The check runs *inside* the advisory lock so the compare-and-swap is
+ * atomic with respect to the write.
+ *
  * @returns The file's mtime after writing (for change detection).
+ * @throws ConcurrencyError when `expectedMtimeMs` is provided and the
+ *   on-disk mtime no longer matches.
  */
-export function saveState(state) {
+export function saveState(state, expectedMtimeMs = null) {
     const statePath = getStatePath();
     const lockPath = statePath + '.lock';
     const backupDir = getBackupDir();
     // Acquire advisory lock to prevent concurrent writes
     acquireLock(lockPath);
     try {
+        // Compare-and-swap: reject the write if the file changed externally
+        // between the caller's last load and now. Zero/null bypasses the
+        // check for first writes and Gist-mode local-cache paths.
+        if (expectedMtimeMs !== null && expectedMtimeMs > 0 && fs.existsSync(statePath)) {
+            const currentMtimeMs = safeGetMtimeMs(statePath);
+            if (currentMtimeMs !== expectedMtimeMs) {
+                throw new ConcurrencyError(expectedMtimeMs, currentMtimeMs);
+            }
+        }
         // Create backup of existing state (best-effort, non-fatal)
         try {
             if (fs.existsSync(statePath)) {

package/dist/core/state-schema.d.ts

@@ -240,6 +240,7 @@ export declare const AgentConfigSchema: z.ZodObject<{
         vscode: "vscode";
     }>>;
     diffToolCustomCommand: z.ZodOptional<z.ZodString>;
+    autoFormatBeforePush: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const LocalRepoCacheSchema: z.ZodObject<{
     repos: z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -397,6 +398,7 @@ export declare const AgentStateSchema: z.ZodObject<{
             vscode: "vscode";
         }>>;
         diffToolCustomCommand: z.ZodOptional<z.ZodString>;
+        autoFormatBeforePush: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     lastRunAt: z.ZodDefault<z.ZodString>;
     lastDigestAt: z.ZodOptional<z.ZodString>;

package/dist/core/state-schema.js

@@ -146,6 +146,11 @@ export const AgentConfigSchema = z.object({
     preferredOrgs: z.array(z.string()).default([]),
     diffTool: DiffToolSchema.default('inline'),
     diffToolCustomCommand: z.string().optional(),
+    /**
+     * Opt-in gate for the auto-format-before-push hook (#1045). Default false:
+     * the hook does nothing on every push unless the user explicitly enables it.
+     */
+    autoFormatBeforePush: z.boolean().default(false),
 });
 // ── 6. Cache schemas ─────────────────────────────────────────────────
 export const LocalRepoCacheSchema = z.object({