@oss-autopilot/core 3.1.0 → 3.3.0

package/dist/core/guidelines-store.js

@@ -0,0 +1,130 @@
+import { OssAutopilotError } from './errors.js';
+/** Filename prefix shared by every guidelines file in the Gist. */
+export const GUIDELINES_FILE_PREFIX = 'guidelines--';
+/** Hard byte budget for a single guidelines file (#867 design log §1). */
+export const GUIDELINES_MAX_BYTES = 8192;
+/** Suffix appended to the filename so it renders as markdown in Gist. */
+const GUIDELINES_FILE_SUFFIX = '.md';
+/**
+ * Convert an `owner/repo` pair into the filename used inside the Gist.
+ * Slashes are escaped as `--` so the filename is filesystem-safe and
+ * unambiguous when parsing back to a repo string.
+ */
+export function guidelinesFilename(repo) {
+    if (!repo.includes('/')) {
+        throw new OssAutopilotError(`Invalid repo identifier "${repo}". Expected "owner/repo" format.`, 'INVALID_REPO_ID');
+    }
+    // GitHub forbids `/` in owner and repo, so the only `/` is the separator.
+    const [owner, name] = repo.split('/');
+    return `${GUIDELINES_FILE_PREFIX}${owner}--${name}${GUIDELINES_FILE_SUFFIX}`;
+}
+/**
+ * Inverse of {@link guidelinesFilename}. Returns null when the filename
+ * doesn't match the guidelines convention.
+ */
+export function repoFromGuidelinesFilename(filename) {
+    if (!filename.startsWith(GUIDELINES_FILE_PREFIX))
+        return null;
+    if (!filename.endsWith(GUIDELINES_FILE_SUFFIX))
+        return null;
+    const middle = filename.slice(GUIDELINES_FILE_PREFIX.length, filename.length - GUIDELINES_FILE_SUFFIX.length);
+    // Only split on the FIRST `--` separator. Repo names with `--` are rare
+    // but legal; owner names cannot contain `--` per GitHub username rules.
+    const sep = middle.indexOf('--');
+    if (sep === -1)
+        return null;
+    const owner = middle.slice(0, sep);
+    const name = middle.slice(sep + 2);
+    if (!owner || !name)
+        return null;
+    return `${owner}/${name}`;
+}
+/**
+ * Thrown by {@link setGuidelines} / {@link deleteGuidelines} when the
+ * StateManager is not in Gist mode. Catch + degrade gracefully when surfacing
+ * to user-facing flows: per-repo guidelines simply aren't available without a
+ * Gist to store them in.
+ */
+export class GuidelinesNotAvailableError extends OssAutopilotError {
+    constructor(message) {
+        super(message ??
+            'Per-repo guidelines require Gist persistence. Run `oss-autopilot setup` to enable Gist sync, then retry.', 'GUIDELINES_NOT_AVAILABLE');
+        this.name = 'GuidelinesNotAvailableError';
+    }
+}
+/**
+ * Thrown by {@link setGuidelines} when content exceeds {@link GUIDELINES_MAX_BYTES}.
+ * Surfaced separately from generic validation errors so consumers can prompt the
+ * user with a "trim or split" UX rather than a generic shape rejection.
+ */
+export class GuidelinesTooLargeError extends OssAutopilotError {
+    constructor(byteSize, max = GUIDELINES_MAX_BYTES) {
+        super(`Guidelines content is ${byteSize} bytes, exceeding the ${max}-byte cap. ` + `Trim or split across categories.`, 'GUIDELINES_TOO_LARGE');
+        this.name = 'GuidelinesTooLargeError';
+    }
+}
+/**
+ * Read the guidelines file for a repo from the Gist cache. Returns null when
+ * the store is not in Gist mode, the file does not exist, or the file is
+ * present but empty (treated as a tombstone left by {@link deleteGuidelines}).
+ */
+export function getGuidelines(store, repo) {
+    if (!store)
+        return null;
+    const content = store.getDocument(guidelinesFilename(repo));
+    if (content === null || content === '')
+        return null;
+    return content;
+}
+/**
+ * Write or replace the guidelines file for a repo. Throws if the store is not
+ * in Gist mode or the content exceeds the byte budget.
+ */
+export function setGuidelines(store, repo, content) {
+    if (!store)
+        throw new GuidelinesNotAvailableError();
+    const byteSize = Buffer.byteLength(content, 'utf8');
+    if (byteSize > GUIDELINES_MAX_BYTES) {
+        throw new GuidelinesTooLargeError(byteSize);
+    }
+    store.setDocument(guidelinesFilename(repo), content);
+}
+/**
+ * Delete the guidelines file for a repo. No-op if the file doesn't exist.
+ * Implementation: write an empty string. The Gist API treats files with
+ * empty content as deletions on the next push, matching the existing
+ * single-source-of-truth model.
+ */
+export function deleteGuidelines(store, repo) {
+    if (!store)
+        throw new GuidelinesNotAvailableError();
+    // setDocument('') is interpreted as deletion; the GistStateStore push path
+    // already strips empty-content files before sending to the Gist API.
+    store.setDocument(guidelinesFilename(repo), '');
+}
+/**
+ * List every repo (as `owner/repo`) that has a non-empty guidelines file in
+ * the cache. Tombstoned (empty-content) files are excluded so the result
+ * matches what {@link getGuidelines} would actually return.
+ *
+ * Returns an empty array when the store is null or no files exist.
+ */
+export function listGuidelinesRepos(store) {
+    if (!store)
+        return [];
+    const filenames = store.listDocuments(GUIDELINES_FILE_PREFIX);
+    const repos = [];
+    for (const filename of filenames) {
+        const repo = repoFromGuidelinesFilename(filename);
+        // Skip files we can't decode (e.g. older formats, hand-edited) — better
+        // than throwing and breaking listGuidelinesRepos for everyone.
+        if (!repo)
+            continue;
+        // Skip tombstones — empty content means the user deleted these guidelines.
+        const content = store.getDocument(filename);
+        if (content === null || content === '')
+            continue;
+        repos.push(repo);
+    }
+    return repos.sort();
+}

package/dist/core/http-cache.js

@@ -9,9 +9,9 @@
  * for the same endpoint (e.g., star counts for two PRs in the same repo)
  * share a single HTTP round-trip.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as crypto from 'crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
 import { getCacheDir } from './paths.js';
 import { debug } from './logger.js';
 import { getHttpStatusCode } from './errors.js';
@@ -76,7 +76,7 @@ export class HttpCache {
     get(url) {
         const filePath = this.pathFor(url);
         try {
-            const raw = fs.readFileSync(filePath, 'utf-8');
+            const raw = fs.readFileSync(filePath, 'utf8');
             const entry = JSON.parse(raw);
             // Sanity-check: the file should contain the URL we asked for
             if (entry.url !== url) {
@@ -100,7 +100,7 @@ export class HttpCache {
             cachedAt: new Date().toISOString(),
         };
         try {
-            fs.writeFileSync(this.pathFor(url), JSON.stringify(entry), { encoding: 'utf-8', mode: 0o600 });
+            fs.writeFileSync(this.pathFor(url), JSON.stringify(entry), { encoding: 'utf8', 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.
@@ -191,7 +191,7 @@ export class HttpCache {
                     continue;
                 const filePath = path.join(this.cacheDir, file);
                 try {
-                    const raw = fs.readFileSync(filePath, 'utf-8');
+                    const raw = fs.readFileSync(filePath, 'utf8');
                     const entry = JSON.parse(raw);
                     const age = now - new Date(entry.cachedAt).getTime();
                     if (age > maxAgeMs) {

package/dist/core/index.d.ts

@@ -4,9 +4,11 @@
  */
 export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, maybeCheckpoint, resetStateManager, type Stats, } from './state.js';
 export { GistStateStore } from './gist-state-store.js';
+export { guidelinesFilename, repoFromGuidelinesFilename, GUIDELINES_FILE_PREFIX, GUIDELINES_MAX_BYTES, GuidelinesNotAvailableError, GuidelinesTooLargeError, } from './guidelines-store.js';
 export { PRMonitor, type PRCheckFailure, type FetchPRsResult, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
 export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
+export { wrapUntrustedContent, extractFromFence, UNTRUSTED_OPEN_TAG_NAME, UNTRUSTED_CLOSE_TAG, type UntrustedContentMeta, } from './untrusted-content.js';
 export { getOctokit, checkRateLimit, type RateLimitInfo } from './github.js';
 export { parseGitHubUrl, splitRepo, isOwnRepo } from './urls.js';
 export { daysBetween, formatRelativeTime, byDateDescending } from './dates.js';

package/dist/core/index.js

@@ -4,10 +4,12 @@
  */
 export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, maybeCheckpoint, resetStateManager, } from './state.js';
 export { GistStateStore } from './gist-state-store.js';
+export { guidelinesFilename, repoFromGuidelinesFilename, GUIDELINES_FILE_PREFIX, GUIDELINES_MAX_BYTES, GuidelinesNotAvailableError, GuidelinesTooLargeError, } from './guidelines-store.js';
 export { PRMonitor, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
 // Search/vetting now delegated to @oss-scout/core via commands/scout-bridge.ts
 export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
+export { wrapUntrustedContent, extractFromFence, UNTRUSTED_OPEN_TAG_NAME, UNTRUSTED_CLOSE_TAG, } from './untrusted-content.js';
 export { getOctokit, checkRateLimit } from './github.js';
 export { parseGitHubUrl, splitRepo, isOwnRepo } from './urls.js';
 export { daysBetween, formatRelativeTime, byDateDescending } from './dates.js';

package/dist/core/issue-conversation.js

@@ -151,7 +151,9 @@ export class IssueConversationMonitor {
                 body: comment.body || '',
                 createdAt: comment.created_at,
                 isUser: author.toLowerCase() === username.toLowerCase(),
-                authorAssociation: String(comment.author_association ?? ''),
+                authorAssociation: typeof comment.author_association === 'string'
+                    ? comment.author_association
+                    : '',
             });
         }
         timeline.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());

package/dist/core/paths.js

@@ -6,9 +6,9 @@
  *
  * Extracted from utils.ts under #1116.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
 /**
  * Returns the oss-autopilot data directory path, creating it if it does not exist.
  *
@@ -98,7 +98,7 @@ export function stateFileExists() {
 export function getCLIVersion() {
     try {
         const pkgPath = path.join(path.dirname(process.argv[1]), '..', 'package.json');
-        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+        return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version;
     }
     catch {
         return '0.0.0';

package/dist/core/pr-comments-fetcher.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Fetch the raw review-comment bundle for a PR (#867 PR 3).
+ *
+ * Returns reviews, inline review comments, and issue-level comments for a
+ * single PR with the contributor's own comments + bots filtered out. The
+ * `authorAssociation` field is preserved on every entry so the host's
+ * extraction prompt can weight maintainer voices (OWNER/MEMBER/COLLABORATOR)
+ * differently from community feedback (CONTRIBUTOR/NONE).
+ *
+ * No LLM calls happen here — this is the data layer feeding the host's
+ * `extract-learnings` prompt. The bundle structure is the contract; the
+ * extraction is the host's responsibility.
+ */
+import type { Octokit } from '@octokit/rest';
+/** A single review (top-level) on a PR. */
+export interface PRReviewEntry {
+    author: string;
+    authorAssociation: string;
+    body: string;
+    submittedAt: string;
+}
+/** An inline review comment (anchored to a file/line) on a PR. */
+export interface PRReviewCommentEntry {
+    author: string;
+    authorAssociation: string;
+    body: string;
+    path: string;
+    createdAt: string;
+}
+/** An issue-level comment posted on the PR thread. */
+export interface PRIssueCommentEntry {
+    author: string;
+    authorAssociation: string;
+    body: string;
+    createdAt: string;
+}
+/**
+ * The full comment bundle returned for a single PR. Field order matches
+ * the typical narrative arc of a PR review (top-level reviews → inline
+ * comments → general thread chatter), so the host's extraction prompt can
+ * walk the bundle linearly.
+ */
+export interface PRCommentBundle {
+    prUrl: string;
+    prTitle: string;
+    repo: string;
+    /** ISO-8601 timestamp the PR was merged or closed; whichever applies. */
+    mergedAt: string;
+    reviews: PRReviewEntry[];
+    reviewComments: PRReviewCommentEntry[];
+    issueComments: PRIssueCommentEntry[];
+}
+/**
+ * Fetch a single PR's comment bundle. Filters out the authenticated user's
+ * own comments and bots. Throws {@link ValidationError} on a non-PR URL.
+ */
+export declare function fetchPRCommentBundle(octokit: Octokit, prUrl: string, githubUsername: string): Promise<PRCommentBundle>;
+/**
+ * Fetch comment bundles for many PRs with a small concurrency cap (default 3).
+ *
+ * Failures on individual PRs are logged and skipped — the batch returns a
+ * shorter array rather than aborting. Rationale: extraction quality is
+ * already a partial-information problem (users contribute to many repos and
+ * many PRs), so a single 404 / rate limit on one PR should not deny the
+ * host the corpus from the other 4.
+ */
+export declare function fetchPRCommentBundlesBatch(octokit: Octokit, prUrls: string[], githubUsername: string, concurrency?: number): Promise<PRCommentBundle[]>;

package/dist/core/pr-comments-fetcher.js

@@ -0,0 +1,125 @@
+import { paginateAll } from './pagination.js';
+import { isBotAuthor } from './comment-utils.js';
+import { parseGitHubUrl } from './urls.js';
+import { ValidationError, errorMessage } from './errors.js';
+import { debug, warn } from './logger.js';
+const MODULE = 'pr-comments-fetcher';
+/** Default concurrency for {@link fetchPRCommentBundlesBatch}. */
+const DEFAULT_BATCH_CONCURRENCY = 3;
+/**
+ * Fetch a single PR's comment bundle. Filters out the authenticated user's
+ * own comments and bots. Throws {@link ValidationError} on a non-PR URL.
+ */
+export async function fetchPRCommentBundle(octokit, prUrl, githubUsername) {
+    const parsed = parseGitHubUrl(prUrl);
+    if (!parsed || parsed.type !== 'pull') {
+        throw new ValidationError(`Invalid PR URL: ${prUrl}`);
+    }
+    const { owner, repo, number: pull_number } = parsed;
+    const repoFull = `${owner}/${repo}`;
+    // Fetch the PR + all three comment streams in parallel. We always fetch
+    // every page — corpus quality depends on having every reviewer voice, not
+    // just the first 100 comments.
+    const [{ data: pr }, reviews, reviewComments, issueComments] = await Promise.all([
+        octokit.pulls.get({ owner, repo, pull_number }),
+        paginateAll((page) => octokit.pulls.listReviews({
+            owner,
+            repo,
+            pull_number,
+            per_page: 100,
+            page,
+        })),
+        paginateAll((page) => octokit.pulls.listReviewComments({
+            owner,
+            repo,
+            pull_number,
+            per_page: 100,
+            page,
+        })),
+        paginateAll((page) => octokit.issues.listComments({
+            owner,
+            repo,
+            issue_number: pull_number,
+            per_page: 100,
+            page,
+        })),
+    ]);
+    const ownLogin = githubUsername.toLowerCase();
+    /**
+     * Drop entries that aren't useful corpus: the user's own comments, bots,
+     * and entries with no author at all (deleted accounts surface as null
+     * user from GitHub's REST API).
+     */
+    const isWorthKeeping = (login) => {
+        if (!login)
+            return false;
+        if (login.toLowerCase() === ownLogin)
+            return false;
+        if (isBotAuthor(login))
+            return false;
+        return true;
+    };
+    const mergedAt = pr.merged_at ?? pr.closed_at ?? '';
+    return {
+        prUrl,
+        prTitle: pr.title,
+        repo: repoFull,
+        mergedAt,
+        reviews: reviews
+            .filter((r) => isWorthKeeping(r.user?.login))
+            .map((r) => ({
+            author: r.user?.login ?? '',
+            authorAssociation: r.author_association ?? 'NONE',
+            body: r.body ?? '',
+            submittedAt: r.submitted_at ?? '',
+        })),
+        reviewComments: reviewComments
+            .filter((c) => isWorthKeeping(c.user?.login))
+            .map((c) => ({
+            author: c.user?.login ?? '',
+            authorAssociation: c.author_association ?? 'NONE',
+            body: c.body ?? '',
+            path: c.path ?? '',
+            createdAt: c.created_at ?? '',
+        })),
+        issueComments: issueComments
+            .filter((c) => isWorthKeeping(c.user?.login))
+            .map((c) => ({
+            author: c.user?.login ?? '',
+            authorAssociation: c.author_association ?? 'NONE',
+            body: c.body ?? '',
+            createdAt: c.created_at ?? '',
+        })),
+    };
+}
+/**
+ * Fetch comment bundles for many PRs with a small concurrency cap (default 3).
+ *
+ * Failures on individual PRs are logged and skipped — the batch returns a
+ * shorter array rather than aborting. Rationale: extraction quality is
+ * already a partial-information problem (users contribute to many repos and
+ * many PRs), so a single 404 / rate limit on one PR should not deny the
+ * host the corpus from the other 4.
+ */
+export async function fetchPRCommentBundlesBatch(octokit, prUrls, githubUsername, concurrency = DEFAULT_BATCH_CONCURRENCY) {
+    const results = [];
+    const queue = [...prUrls];
+    async function worker() {
+        while (queue.length > 0) {
+            const url = queue.shift();
+            if (!url)
+                return;
+            try {
+                const bundle = await fetchPRCommentBundle(octokit, url, githubUsername);
+                results.push(bundle);
+            }
+            catch (err) {
+                warn(MODULE, `Skipping ${url}: ${errorMessage(err)}`);
+            }
+        }
+    }
+    const workers = Array.from({ length: Math.min(concurrency, prUrls.length) }, worker);
+    await Promise.all(workers);
+    debug(MODULE, `Fetched ${results.length}/${prUrls.length} comment bundles`);
+    return results;
+}

package/dist/core/pr-monitor.js

@@ -16,9 +16,8 @@ import { getOctokit } from './github.js';
 import { getStateManager } from './state.js';
 import { daysBetween } from './dates.js';
 import { parseGitHubUrl, extractOwnerRepo, isOwnRepo } from './urls.js';
-import { DEFAULT_CONCURRENCY } from './concurrency.js';
+import { DEFAULT_CONCURRENCY, runWorkerPool } from './concurrency.js';
 import { determineStatus } from './status-determination.js';
-import { runWorkerPool } from './concurrency.js';
 import { ConfigurationError, ValidationError, errorMessage, getHttpStatusCode, isRateLimitOrAuthError, } from './errors.js';
 import { paginateAll } from './pagination.js';
 import { debug, warn, timed } from './logger.js';

package/dist/core/pr-template.js

@@ -43,7 +43,7 @@ export async function fetchPRTemplate(octokit, owner, repo) {
                 debug(MODULE, `${path} has no content, skipping`);
                 continue;
             }
-            const template = Buffer.from(data.content, 'base64').toString('utf-8');
+            const template = Buffer.from(data.content, 'base64').toString('utf8');
             debug(MODULE, `Found PR template at ${path} (${template.length} chars)`);
             return { template, source: path };
         }

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

@@ -34,6 +34,12 @@ export declare function migrateV1ToV2(rawState: Record<string, unknown>): Record
  * New optional fields are handled by Zod defaults (undefined/optional).
  */
 export declare function migrateV2ToV3(rawState: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Migrate state from v3 to v4 (#867).
+ * Adds: commentsFetchedAt on StoredMergedPR / StoredClosedPR. The new field is
+ * optional, so no data transformation is needed — only the version bump.
+ */
+export declare function migrateV3ToV4(rawState: Record<string, unknown>): Record<string, unknown>;
 /**
  * Create a fresh state (v3).
  * Leverages Zod schema defaults to produce a complete state.

package/dist/core/state-persistence.js

@@ -3,8 +3,8 @@
  * Handles file I/O, locking, backup/restore, and schema migration (v1→v2→v3).
  * No module-level mutable state — functions accept/return AgentState objects.
  */
-import * as fs from 'fs';
-import * as path from 'path';
+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 { errorMessage, ConcurrencyError } from './errors.js';
@@ -21,7 +21,7 @@ const LEGACY_BACKUP_DIR = path.join(process.cwd(), 'data', 'backups');
  */
 function isLockStale(lockPath) {
     try {
-        const existing = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+        const existing = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
         return Date.now() - existing.timestamp > LOCK_TIMEOUT_MS;
     }
     catch (err) {
@@ -72,7 +72,7 @@ export function acquireLock(lockPath) {
  */
 export function releaseLock(lockPath) {
     try {
-        const data = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+        const data = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
         if (data.pid === process.pid) {
             fs.unlinkSync(lockPath);
         }
@@ -158,12 +158,23 @@ export function migrateV2ToV3(rawState) {
     debug(MODULE, 'v2 to v3 migration complete.');
     return rawState;
 }
+/**
+ * Migrate state from v3 to v4 (#867).
+ * Adds: commentsFetchedAt on StoredMergedPR / StoredClosedPR. The new field is
+ * optional, so no data transformation is needed — only the version bump.
+ */
+export function migrateV3ToV4(rawState) {
+    debug(MODULE, 'Migrating state from v3 to v4 (add commentsFetchedAt to stored PR records)...');
+    rawState.version = 4;
+    debug(MODULE, 'v3 to v4 migration complete (no data transformation required).');
+    return rawState;
+}
 /**
  * Create a fresh state (v3).
  * Leverages Zod schema defaults to produce a complete state.
  */
 export function createFreshState() {
-    return AgentStateSchema.parse({ version: 3 });
+    return AgentStateSchema.parse({ version: 4 });
 }
 /**
  * Migrate state from legacy ./data/ location to ~/.oss-autopilot/.
@@ -262,7 +273,7 @@ function tryRestoreFromBackup() {
     for (const backupFile of backupFiles) {
         const backupPath = path.join(backupDir, backupFile);
         try {
-            const data = fs.readFileSync(backupPath, 'utf-8');
+            const data = fs.readFileSync(backupPath, 'utf8');
             let raw = JSON.parse(data);
             // Chain migrations: v1 → v2 → v3
             if (typeof raw === 'object' && raw !== null) {
@@ -273,6 +284,9 @@ function tryRestoreFromBackup() {
                 if (raw.version === 2) {
                     raw = migrateV2ToV3(raw);
                 }
+                if (raw.version === 3) {
+                    raw = migrateV3ToV4(raw);
+                }
             }
             const parsed = AgentStateSchema.safeParse(raw);
             if (parsed.success) {
@@ -311,9 +325,9 @@ export function loadState() {
     const statePath = getStatePath();
     try {
         if (fs.existsSync(statePath)) {
-            const data = fs.readFileSync(statePath, 'utf-8');
+            const data = fs.readFileSync(statePath, 'utf8');
             let raw = JSON.parse(data);
-            // Chain migrations: v1 → v2 → v3
+            // Chain migrations: v1 → v2 → v3 → v4
             let wasMigrated = false;
             if (typeof raw === 'object' && raw !== null) {
                 const rawObj = raw;
@@ -325,6 +339,10 @@ export function loadState() {
                     raw = migrateV2ToV3(raw);
                     wasMigrated = true;
                 }
+                if (raw.version === 3) {
+                    raw = migrateV3ToV4(raw);
+                    wasMigrated = true;
+                }
             }
             // Validate through Zod schema (strips unknown keys in memory; stale keys persist on disk until next save)
             const parsed = AgentStateSchema.safeParse(raw);
@@ -473,7 +491,7 @@ export function saveState(state, expectedMtimeMs = null) {
         // Create backup of existing state (best-effort, non-fatal)
         try {
             if (fs.existsSync(statePath)) {
-                const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const timestamp = new Date().toISOString().replace(/[.:]/g, '-');
                 const randomSuffix = Math.random().toString(36).slice(2, 8).padEnd(6, '0');
                 const backupFile = path.join(backupDir, `state-${timestamp}-${randomSuffix}.json`);
                 fs.copyFileSync(statePath, backupFile);

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

@@ -63,12 +63,14 @@ export declare const StoredMergedPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     mergedAt: z.ZodString;
+    commentsFetchedAt: z.ZodOptional<z.ZodString>;
     learningsExtractedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const StoredClosedPRSchema: z.ZodObject<{
     url: z.ZodString;
     title: z.ZodString;
     closedAt: z.ZodString;
+    commentsFetchedAt: z.ZodOptional<z.ZodString>;
     learningsExtractedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const AnalyzedIssueConversationSchema: z.ZodObject<{
@@ -324,7 +326,7 @@ export declare const DailyDigestSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const AgentStateSchema: z.ZodObject<{
-    version: z.ZodLiteral<3>;
+    version: z.ZodLiteral<4>;
     gistId: z.ZodOptional<z.ZodString>;
     repoScores: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         repo: z.ZodString;
@@ -471,12 +473,14 @@ export declare const AgentStateSchema: z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         mergedAt: z.ZodString;
+        commentsFetchedAt: z.ZodOptional<z.ZodString>;
         learningsExtractedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     closedPRs: z.ZodOptional<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
         title: z.ZodString;
         closedAt: z.ZodString;
+        commentsFetchedAt: z.ZodOptional<z.ZodString>;
         learningsExtractedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     analyzedIssueConversations: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/core/state-schema.js

@@ -44,12 +44,18 @@ export const StoredMergedPRSchema = z.object({
     url: z.string(),
     title: z.string(),
     mergedAt: z.string(),
+    /** When the raw review-comment bundle for this PR was last fetched (#867). */
+    commentsFetchedAt: z.string().optional(),
+    /** When the host last ran LLM extraction over this PR's comment bundle (#867). */
     learningsExtractedAt: z.string().optional(),
 });
 export const StoredClosedPRSchema = z.object({
     url: z.string(),
     title: z.string(),
     closedAt: z.string(),
+    /** When the raw review-comment bundle for this PR was last fetched (#867). */
+    commentsFetchedAt: z.string().optional(),
+    /** When the host last ran LLM extraction over this PR's comment bundle (#867). */
     learningsExtractedAt: z.string().optional(),
 });
 export const AnalyzedIssueConversationSchema = z.object({
@@ -211,7 +217,7 @@ export const DailyDigestSchema = z.object({
 });
 // ── 8. Root schema ───────────────────────────────────────────────────
 export const AgentStateSchema = z.object({
-    version: z.literal(3),
+    version: z.literal(4),
     gistId: z.string().optional(),
     repoScores: z.record(z.string(), RepoScoreSchema).default({}),
     config: AgentConfigSchema.default(() => AgentConfigSchema.parse({})),