@oss-autopilot/core 3.13.4 → 3.14.1

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

@@ -4,7 +4,7 @@
  * 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
+ * **User-facing reference:** `docs/repo-scores.md` — plain-language
  * explanation of the formula and what a given score means.
  */
 import { isBelowMinStars } from './types.js';
@@ -14,7 +14,7 @@ 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
+// Changing any of these is a behavior change — update docs/repo-scores.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;
@@ -66,7 +66,7 @@ function createDefaultRepoScore(repo) {
  *     − (hasHostileComments ? HOSTILITY_PENALTY : 0)
  *   clamped to [SCORE_MIN, SCORE_MAX].
  *
- * See `docs/repo-scoring.md` for user-facing intent and what a given
+ * See `docs/repo-scores.md` for user-facing intent and what a given
  * score means in practice.
  */
 export function calculateScore(repoScore) {

package/dist/core/repo-vet.d.ts

@@ -11,7 +11,7 @@
  * supply pre-fetched repo signals so the score is reproducible
  * against fixture data and offline replays.
  *
- * Rubric reference: docs/repo-rubric.md.
+ * Rubric reference: docs/repo-scores.md.
  */
 export interface RepoVetInput {
     /** Star count from the GitHub repo metadata. */
@@ -78,7 +78,7 @@ export interface RepoVetResult {
         prTemplate: boolean;
         codeOfConduct: boolean;
     };
-    /** Weighted 1-10 score per docs/repo-rubric.md. */
+    /** Weighted 1-10 score per docs/repo-scores.md. */
     rubricScore: number;
     /** Top-line verdict derived from the score and red-flag overrides. */
     rubricVerdict: RepoVetVerdict;

package/dist/core/repo-vet.js

@@ -11,7 +11,7 @@
  * supply pre-fetched repo signals so the score is reproducible
  * against fixture data and offline replays.
  *
- * Rubric reference: docs/repo-rubric.md.
+ * Rubric reference: docs/repo-scores.md.
  */
 const WEIGHTS = {
     activity: 0.25,

package/dist/core/review-analysis.d.ts

@@ -53,6 +53,25 @@ export declare function getInlineCommentBody(reviewId: number, reviewComments: R
  * that also posted inline comments (#829).
  */
 export declare function reviewHasInlineComments(reviewId: number, reviewComments: ReviewComment[]): boolean;
+/**
+ * Earliest maintainer response timestamp across issue comments and submitted
+ * reviews (#1461). A "response" is any comment or review by a non-bot
+ * account other than the contributor — acknowledgments and approvals count,
+ * since for latency purposes any human maintainer reply is a response.
+ * Computed from data fetchPRDetails already holds in memory (zero extra API
+ * calls). Returns undefined when no maintainer has responded yet.
+ */
+export declare function getFirstMaintainerResponseAt(comments: Array<{
+    user?: {
+        login?: string;
+    } | null;
+    created_at: string;
+}>, reviews: Array<{
+    user?: {
+        login?: string;
+    } | null;
+    submitted_at?: string | null;
+}>, username: string): string | undefined;
 /**
  * Check if there are unresponded comments from maintainers.
  * Combines issue comments and review comments into a timeline,

package/dist/core/review-analysis.js

@@ -97,6 +97,34 @@ export function getInlineCommentBody(reviewId, reviewComments) {
 export function reviewHasInlineComments(reviewId, reviewComments) {
     return reviewComments.some((c) => c.pull_request_review_id === reviewId);
 }
+/**
+ * Earliest maintainer response timestamp across issue comments and submitted
+ * reviews (#1461). A "response" is any comment or review by a non-bot
+ * account other than the contributor — acknowledgments and approvals count,
+ * since for latency purposes any human maintainer reply is a response.
+ * Computed from data fetchPRDetails already holds in memory (zero extra API
+ * calls). Returns undefined when no maintainer has responded yet.
+ */
+export function getFirstMaintainerResponseAt(comments, reviews, username) {
+    const usernameLower = username.toLowerCase();
+    let earliest;
+    const consider = (author, createdAt) => {
+        if (!author || !createdAt)
+            return;
+        if (author.toLowerCase() === usernameLower)
+            return;
+        if (isBotAuthor(author))
+            return;
+        if (!earliest || new Date(createdAt).getTime() < new Date(earliest).getTime()) {
+            earliest = createdAt;
+        }
+    };
+    for (const comment of comments)
+        consider(comment.user?.login, comment.created_at);
+    for (const review of reviews)
+        consider(review.user?.login, review.submitted_at);
+    return earliest;
+}
 /**
  * Check if there are unresponded comments from maintainers.
  * Combines issue comments and review comments into a timeline,

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

@@ -9,6 +9,7 @@
  * Unknown keys are stripped by default (Zod 4 behavior).
  */
 import { z } from 'zod';
+import type { FetchedPR } from './types.js';
 export declare const IssueStatusSchema: z.ZodEnum<{
     candidate: "candidate";
     claimed: "claimed";
@@ -63,6 +64,8 @@ export declare const StoredMergedPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     mergedAt: z.ZodString;
+    openedAt: z.ZodOptional<z.ZodString>;
+    firstMaintainerResponseAt: z.ZodOptional<z.ZodString>;
     commentsFetchedAt: z.ZodOptional<z.ZodString>;
     learningsExtractedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -70,6 +73,8 @@ export declare const StoredClosedPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     closedAt: z.ZodString;
+    openedAt: z.ZodOptional<z.ZodString>;
+    firstMaintainerResponseAt: z.ZodOptional<z.ZodString>;
     commentsFetchedAt: z.ZodOptional<z.ZodString>;
     learningsExtractedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -251,6 +256,8 @@ export declare const AgentConfigSchema: z.ZodObject<{
     }>>>;
     excludeRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
     excludeOrgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    avoidRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    boostIssueTypes: z.ZodDefault<z.ZodArray<z.ZodString>>;
     trustedProjects: z.ZodDefault<z.ZodArray<z.ZodString>>;
     githubUsername: z.ZodDefault<z.ZodString>;
     minRepoScoreThreshold: z.ZodDefault<z.ZodNumber>;
@@ -311,6 +318,7 @@ export declare const ClosedPRSchema: z.ZodObject<{
     title: z.ZodString;
     closedAt: z.ZodString;
     closedBy: z.ZodOptional<z.ZodString>;
+    openedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const MergedPRSchema: z.ZodObject<{
     url: z.ZodString;
@@ -318,6 +326,7 @@ export declare const MergedPRSchema: z.ZodObject<{
     number: z.ZodNumber;
     title: z.ZodString;
     mergedAt: z.ZodString;
+    openedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const DailyDigestSummarySchema: z.ZodObject<{
     totalActivePRs: z.ZodNumber;
@@ -325,11 +334,29 @@ export declare const DailyDigestSummarySchema: z.ZodObject<{
     totalMergedAllTime: z.ZodNumber;
     mergeRate: z.ZodNumber;
 }, z.core.$strip>;
+/**
+ * Minimal FetchedPR validation for persisted digest arrays (#1456). The
+ * persisted digest is rendered by the dashboard from cold start (before any
+ * refresh), so the fields it dereferences must be guaranteed present. Only
+ * the identity/status core is pinned — required on every real `FetchedPR`
+ * since the type's introduction — and `.passthrough()` keeps the dozens of
+ * volatile enrichment fields (CI, review, staleness) from rejecting digests
+ * persisted by older or newer producers.
+ */
+export declare const FetchedPRSchema: z.ZodObject<{
+    url: z.ZodString;
+    repo: z.ZodString;
+    number: z.ZodNumber;
+    status: z.ZodEnum<{
+        needs_addressing: "needs_addressing";
+        waiting_on_maintainer: "waiting_on_maintainer";
+    }>;
+}, z.core.$loose>;
 export declare const DailyDigestSchema: z.ZodObject<{
     generatedAt: z.ZodString;
-    openPRs: z.ZodArray<z.ZodAny>;
-    needsAddressingPRs: z.ZodArray<z.ZodAny>;
-    waitingOnMaintainerPRs: z.ZodArray<z.ZodAny>;
+    openPRs: z.ZodType<FetchedPR[], unknown, z.core.$ZodTypeInternals<FetchedPR[], unknown>>;
+    needsAddressingPRs: z.ZodType<FetchedPR[], unknown, z.core.$ZodTypeInternals<FetchedPR[], unknown>>;
+    waitingOnMaintainerPRs: z.ZodType<FetchedPR[], unknown, z.core.$ZodTypeInternals<FetchedPR[], unknown>>;
     recentlyClosedPRs: z.ZodArray<z.ZodObject<{
         url: z.ZodString;
         repo: z.ZodString;
@@ -337,6 +364,7 @@ export declare const DailyDigestSchema: z.ZodObject<{
         title: z.ZodString;
         closedAt: z.ZodString;
         closedBy: z.ZodOptional<z.ZodString>;
+        openedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     recentlyMergedPRs: z.ZodArray<z.ZodObject<{
         url: z.ZodString;
@@ -344,6 +372,7 @@ export declare const DailyDigestSchema: z.ZodObject<{
         number: z.ZodNumber;
         title: z.ZodString;
         mergedAt: z.ZodString;
+        openedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     shelvedPRs: z.ZodArray<z.ZodObject<{
         number: z.ZodNumber;
@@ -413,6 +442,8 @@ export declare const AgentStateSchema: z.ZodObject<{
         }>>>;
         excludeRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
         excludeOrgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        avoidRepos: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        boostIssueTypes: z.ZodDefault<z.ZodArray<z.ZodString>>;
         trustedProjects: z.ZodDefault<z.ZodArray<z.ZodString>>;
         githubUsername: z.ZodDefault<z.ZodString>;
         minRepoScoreThreshold: z.ZodDefault<z.ZodNumber>;
@@ -462,9 +493,9 @@ export declare const AgentStateSchema: z.ZodObject<{
     lastStrategyAt: z.ZodOptional<z.ZodString>;
     lastDigest: z.ZodOptional<z.ZodObject<{
         generatedAt: z.ZodString;
-        openPRs: z.ZodArray<z.ZodAny>;
-        needsAddressingPRs: z.ZodArray<z.ZodAny>;
-        waitingOnMaintainerPRs: z.ZodArray<z.ZodAny>;
+        openPRs: z.ZodType<FetchedPR[], unknown, z.core.$ZodTypeInternals<FetchedPR[], unknown>>;
+        needsAddressingPRs: z.ZodType<FetchedPR[], unknown, z.core.$ZodTypeInternals<FetchedPR[], unknown>>;
+        waitingOnMaintainerPRs: z.ZodType<FetchedPR[], unknown, z.core.$ZodTypeInternals<FetchedPR[], unknown>>;
         recentlyClosedPRs: z.ZodArray<z.ZodObject<{
             url: z.ZodString;
             repo: z.ZodString;
@@ -472,6 +503,7 @@ export declare const AgentStateSchema: z.ZodObject<{
             title: z.ZodString;
             closedAt: z.ZodString;
             closedBy: z.ZodOptional<z.ZodString>;
+            openedAt: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         recentlyMergedPRs: z.ZodArray<z.ZodObject<{
             url: z.ZodString;
@@ -479,6 +511,7 @@ export declare const AgentStateSchema: z.ZodObject<{
             number: z.ZodNumber;
             title: z.ZodString;
             mergedAt: z.ZodString;
+            openedAt: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         shelvedPRs: z.ZodArray<z.ZodObject<{
             number: z.ZodNumber;
@@ -525,6 +558,8 @@ export declare const AgentStateSchema: z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         mergedAt: z.ZodString;
+        openedAt: z.ZodOptional<z.ZodString>;
+        firstMaintainerResponseAt: z.ZodOptional<z.ZodString>;
         commentsFetchedAt: z.ZodOptional<z.ZodString>;
         learningsExtractedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
@@ -532,6 +567,8 @@ export declare const AgentStateSchema: z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         closedAt: z.ZodString;
+        openedAt: z.ZodOptional<z.ZodString>;
+        firstMaintainerResponseAt: z.ZodOptional<z.ZodString>;
         commentsFetchedAt: z.ZodOptional<z.ZodString>;
         learningsExtractedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;

package/dist/core/state-schema.js

@@ -44,6 +44,20 @@ export const StoredMergedPRSchema = z.object({
     url: z.string(),
     title: z.string(),
     mergedAt: z.string(),
+    /**
+     * When the PR was opened (#1461). Optional: entries persisted before the
+     * outcome ledger existed don't carry it. Sourced from the Search API's
+     * `created_at` at merge-detection time — zero extra API calls.
+     */
+    openedAt: z.string().optional(),
+    /**
+     * Earliest maintainer (non-bot, non-author) comment or review on the
+     * PR (#1461). Best-effort: only derivable when the PR was enriched while
+     * open (looked up from the previous run's persisted digest at detection
+     * time), so it is absent for PRs that merged before ever appearing in an
+     * enriched run.
+     */
+    firstMaintainerResponseAt: z.string().optional(),
     /** When the raw review-comment bundle for this PR was last fetched (#867). */
     // ISO-8601 datetime guards against `markPRCommentsFetched(url, "garbage")`
     // poisoning state through the stamping API (#1209 L4).
@@ -55,6 +69,13 @@ export const StoredClosedPRSchema = z.object({
     url: z.string(),
     title: z.string(),
     closedAt: z.string(),
+    /** When the PR was opened (#1461). See StoredMergedPRSchema.openedAt. */
+    openedAt: z.string().optional(),
+    /**
+     * Earliest maintainer response (#1461). See
+     * StoredMergedPRSchema.firstMaintainerResponseAt.
+     */
+    firstMaintainerResponseAt: z.string().optional(),
     /** When the raw review-comment bundle for this PR was last fetched (#867). */
     // ISO-8601 datetime guards against `markPRCommentsFetched(url, "garbage")`
     // poisoning state through the stamping API (#1209 L4).
@@ -176,6 +197,21 @@ export const AgentConfigSchema = z.object({
     scope: z.array(IssueScopeSchema).optional(),
     excludeRepos: z.array(z.string()).default([]),
     excludeOrgs: z.array(z.string()).optional(),
+    /**
+     * Repos (owner/repo) to softly downrank in discovery results (#1464).
+     * Milder than `excludeRepos`' hard filter: scout pushes matches below
+     * equally-recommended candidates but does not remove them, and a strong
+     * affinity boost can still outweigh the penalty (scout #168).
+     * Threaded to scout via `scout-bridge.ts`.
+     */
+    avoidRepos: z.array(z.string()).default([]),
+    /**
+     * Issue label types (e.g. "bug", "good first issue") to softly boost in
+     * discovery ranking, matched case-insensitively against issue labels
+     * (scout #168 / #1464). Does not filter results or change viability
+     * scores. Threaded to scout via `scout-bridge.ts`.
+     */
+    boostIssueTypes: z.array(z.string()).default([]),
     trustedProjects: z.array(z.string()).default([]),
     githubUsername: z.string().default(''),
     minRepoScoreThreshold: z.number().default(4),
@@ -251,6 +287,12 @@ export const ClosedPRSchema = z.object({
     title: z.string(),
     closedAt: z.string(),
     closedBy: z.string().optional(),
+    /**
+     * When the PR was opened (#1461). Carried from the Search API's
+     * `created_at` so close detection can persist it into the outcome ledger.
+     * Optional: digests persisted by older producers don't have it.
+     */
+    openedAt: z.string().optional(),
 });
 export const MergedPRSchema = z.object({
     url: z.string(),
@@ -258,6 +300,12 @@ export const MergedPRSchema = z.object({
     number: z.number(),
     title: z.string(),
     mergedAt: z.string(),
+    /**
+     * When the PR was opened (#1461). Carried from the Search API's
+     * `created_at` so merge detection can persist it into the outcome ledger.
+     * Optional: digests persisted by older producers don't have it.
+     */
+    openedAt: z.string().optional(),
 });
 export const DailyDigestSummarySchema = z.object({
     totalActivePRs: z.number(),
@@ -265,12 +313,41 @@ export const DailyDigestSummarySchema = z.object({
     totalMergedAllTime: z.number(),
     mergeRate: z.number(),
 });
+/**
+ * Minimal FetchedPR validation for persisted digest arrays (#1456). The
+ * persisted digest is rendered by the dashboard from cold start (before any
+ * refresh), so the fields it dereferences must be guaranteed present. Only
+ * the identity/status core is pinned — required on every real `FetchedPR`
+ * since the type's introduction — and `.passthrough()` keeps the dozens of
+ * volatile enrichment fields (CI, review, staleness) from rejecting digests
+ * persisted by older or newer producers.
+ */
+export const FetchedPRSchema = z
+    .object({
+    url: z.string(),
+    repo: z.string(),
+    number: z.number(),
+    status: FetchedPRStatusSchema,
+})
+    .passthrough();
+/**
+ * The digest arrays hold full `FetchedPR` objects at runtime; validation is
+ * intentionally limited to the identity/status core above (everything else
+ * is ephemeral enrichment that older/newer producers legitimately differ
+ * on), so the inferred type is widened back to `FetchedPR[]` for consumers.
+ * The cast is sound in both directions: every real `FetchedPR` satisfies the
+ * core schema, and `.passthrough()` preserves the enrichment fields on parse
+ * output. This mirrors the pre-#1456 `z.array(z.any())` static contract
+ * while actually validating the fields the dashboard dereferences.
+ */
+const FetchedPRArraySchema = z.array(FetchedPRSchema);
 export const DailyDigestSchema = z.object({
     generatedAt: z.string(),
-    // FetchedPR arrays — ephemeral, regenerated each run. Validated loosely.
-    openPRs: z.array(z.any()),
-    needsAddressingPRs: z.array(z.any()),
-    waitingOnMaintainerPRs: z.array(z.any()),
+    // FetchedPR arrays — ephemeral, regenerated each run. Validated for the
+    // identity/status core the dashboard dereferences; loose on the rest.
+    openPRs: FetchedPRArraySchema,
+    needsAddressingPRs: FetchedPRArraySchema,
+    waitingOnMaintainerPRs: FetchedPRArraySchema,
     recentlyClosedPRs: z.array(ClosedPRSchema),
     recentlyMergedPRs: z.array(MergedPRSchema),
     shelvedPRs: z.array(ShelvedPRRefSchema),

package/dist/core/state.d.ts

@@ -7,6 +7,7 @@ import { AgentState, TrackedIssue, RepoScore, RepoScoreUpdate, DailyDigest, Loca
 import { type LoadRecoveryInfo } from './state-persistence.js';
 import type { Stats } from './repo-score-manager.js';
 import { GistStateStore } from './gist-state-store.js';
+import { type GistHealth } from './gist-health.js';
 export { acquireLock, releaseLock, atomicWriteFileSync } from './state-persistence.js';
 export type { LoadRecoveryInfo } from './state-persistence.js';
 export type { Stats } from './repo-score-manager.js';
@@ -135,6 +136,20 @@ export declare class StateManager {
     isGistMode(): boolean;
     /** Whether the Gist is in degraded mode (using local cache fallback). */
     isGistDegraded(): boolean;
+    /**
+     * Single source of truth for gist persistence health (#1444). Surfaces
+     * that need "is this process reliably syncing to the Gist?" (daily
+     * warnings, dashboard banners/recovery gates) derive it from here instead
+     * of re-combining `config.persistence` / `isGistMode()` /
+     * `isGistDegraded()` at each call site.
+     *
+     * Composes the same primitive fields those accessors expose:
+     * - no gist store + config asks for gist → `configured-but-local`
+     * - gist store attached but disarmed (#1443) → `bootstrap-degraded`
+     *   (`since` comes from the staleness marker the degraded bootstrap seeds)
+     * - otherwise healthy (`degraded: null`)
+     */
+    getGistHealth(): GistHealth;
     /**
      * Whether per-repo guidelines (#867) are available. True iff the Gist store
      * is initialized — in local-only mode, guidelines are unavailable and
@@ -225,7 +240,15 @@ export declare class StateManager {
      * Entries with URLs that fail {@link parseGitHubUrl} are dropped before
      * persistence (read-side filters in dashboard-data already skip them, but
      * this prevents the bad data from reaching disk in the first place).
-     * @param prs - Merged PRs to add (duplicates by URL are ignored)
+     *
+     * Re-seen URLs are not re-added, but upgrade the stored entry in place
+     * (#1461): outcome-ledger fields (`openedAt`, `firstMaintainerResponseAt`)
+     * missing on the stored entry are filled from the richer incoming one.
+     * Existing values are never overwritten, so stamps that live only on the
+     * stored entry (commentsFetchedAt, learningsExtractedAt) and earlier
+     * enriched writes stay intact.
+     *
+     * @param prs - Merged PRs to add (duplicates by URL upgrade in place)
      * @returns count of entries added vs. dropped (invalid URL)
      */
     addMergedPRs(prs: StoredMergedPR[]): {
@@ -241,7 +264,11 @@ export declare class StateManager {
      * Entries with URLs that fail {@link parseGitHubUrl} are dropped before
      * persistence (read-side filters in dashboard-data already skip them, but
      * this prevents the bad data from reaching disk in the first place).
-     * @param prs - Closed PRs to add (duplicates by URL are ignored)
+     *
+     * Re-seen URLs upgrade the stored entry's missing ledger fields in place
+     * (#1461) — see {@link addMergedPRs} for the full semantics.
+     *
+     * @param prs - Closed PRs to add (duplicates by URL upgrade in place)
      * @returns count of entries added vs. dropped (invalid URL)
      */
     addClosedPRs(prs: StoredClosedPR[]): {
@@ -450,10 +477,14 @@ export type GistPersistenceStatus =
  | '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 mode active: the singleton is gist-backed AND the store is armed
+ * (the bootstrap actually verified its Gist — not a degraded fallback). */
  | '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. */
+/** Gist mode is configured and a token was available, but this process is
+ * not writing to the Gist: init either fell back to a local-only manager
+ * (transient network failure) or bootstrapped DEGRADED off the local
+ * cache (#1443 — gist-backed but disarmed, reads stale and pushes fail).
+ * A later call may recover. */
  | 'degraded';
 export declare function ensureGistPersistence(token: string | null): Promise<GistPersistenceStatus>;
 /**