@oss-autopilot/core 3.1.0 → 3.3.0

package/dist/core/state.d.ts

@@ -26,6 +26,24 @@ export declare function maybeCheckpoint(stateManager: StateManager, callerModule
  * Retains lightweight CRUD operations for config, issues, shelving, dismissal,
  * and status overrides.
  */
+/**
+ * Surfaced when the in-memory cached state is no longer in sync with the
+ * canonical Gist — typically because `refreshFromGist()` failed (network
+ * blip, rate limit, expired token) or because the bootstrap fell back to
+ * the local cache file (#1193). Commands include this in their `--json`
+ * envelope so cron/dashboard consumers can react instead of silently
+ * operating on stale data.
+ */
+export interface StalenessInfo {
+    /** Why we're operating on cached data. Forward-compatible with future sources. */
+    source: 'cache';
+    /** Human-readable reason from the underlying error. */
+    reason: string;
+    /** ISO timestamp of the most recent successful refresh, or null if never. */
+    lastSuccessfulRefresh: string | null;
+    /** ISO timestamp when this staleness marker was first set. */
+    detectedAt: string;
+}
 export declare class StateManager {
     protected state: AgentState;
     protected inMemoryOnly: boolean;
@@ -34,6 +52,8 @@ export declare class StateManager {
     private _batchDirty;
     protected gistStore: GistStateStore | null;
     protected gistDegraded: boolean;
+    private staleness;
+    private lastSuccessfulRefreshAt;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -105,6 +125,29 @@ export declare class StateManager {
     isGistMode(): boolean;
     /** Whether the Gist is in degraded mode (using local cache fallback). */
     isGistDegraded(): boolean;
+    /**
+     * Whether per-repo guidelines (#867) are available. True iff the Gist store
+     * is initialized — in local-only mode, guidelines are unavailable and
+     * write operations would throw {@link GuidelinesNotAvailableError}.
+     */
+    isGuidelinesAvailable(): boolean;
+    /**
+     * Read the per-repo guidelines for `repo` (#867). Returns null when in
+     * local mode, when no file exists, or when the file is empty (tombstoned).
+     */
+    getGuidelines(repo: string): string | null;
+    /**
+     * Persist per-repo guidelines for `repo`. Throws when not in Gist mode or
+     * when content exceeds the byte budget.
+     */
+    setGuidelines(repo: string, content: string): void;
+    /**
+     * Tombstone the guidelines file for `repo` so subsequent reads return null.
+     * Throws when not in Gist mode.
+     */
+    deleteGuidelines(repo: string): void;
+    /** List repos with non-empty guidelines stored in the Gist. */
+    listGuidelinesRepos(): string[];
     /**
      * Get the current state as a read-only snapshot.
      */
@@ -119,6 +162,13 @@ export declare class StateManager {
      * Throttled to once per 30 seconds by GistStateStore. Returns true if state was refreshed.
      */
     refreshFromGist(): Promise<boolean>;
+    /**
+     * Returns a staleness marker when the in-memory state diverged from the
+     * canonical Gist (refresh failure or degraded bootstrap), or `null` when
+     * state is current. Commands surface this via their `--json` warnings
+     * envelope (#1193).
+     */
+    getStateStaleness(): StalenessInfo | null;
     /**
      * Store the latest daily digest and update the digest timestamp.
      * @param digest - The daily digest to store
@@ -176,6 +226,16 @@ export declare class StateManager {
     };
     /** Returns the most recent close date, used as a watermark for incremental fetching. */
     getClosedPRWatermark(): string | undefined;
+    /**
+     * Stamp `commentsFetchedAt` on the merged or closed PR matching `url` (#867).
+     * No-op when no PR with that URL is stored.
+     */
+    markPRCommentsFetched(url: string, fetchedAt: string): void;
+    /**
+     * Stamp `learningsExtractedAt` on the merged or closed PR matching `url` (#867).
+     * No-op when no PR with that URL is stored.
+     */
+    markPRLearningsExtracted(url: string, extractedAt: string): void;
     /**
      * Merge partial config updates into the current configuration.
      * @param config - Partial config object to merge

package/dist/core/state.js

@@ -3,13 +3,14 @@
  * Thin coordinator that delegates persistence to state-persistence.ts
  * and scoring logic to repo-score-manager.ts.
  */
-import * as fs from 'fs';
+import * as fs from 'node:fs';
 import { AgentStateSchema } from './state-schema.js';
 import { loadState, saveState, reloadStateIfChanged, createFreshState, atomicWriteFileSync, } from './state-persistence.js';
 import * as repoScoring from './repo-score-manager.js';
 import { debug, warn } from './logger.js';
-import { errorMessage, ConfigurationError, ConcurrencyError } from './errors.js';
+import { errorMessage, ConfigurationError, ConcurrencyError, isTransientNetworkError } from './errors.js';
 import { GistStateStore } from './gist-state-store.js';
+import * as guidelinesStoreModule from './guidelines-store.js';
 import { getStatePath, getStateCachePath } from './paths.js';
 import { parseGitHubUrl } from './urls.js';
 export { acquireLock, releaseLock, atomicWriteFileSync } from './state-persistence.js';
@@ -52,13 +53,6 @@ export async function maybeCheckpoint(stateManager, callerModule) {
         warn(callerModule, `Gist checkpoint failed (local mutation succeeded, will retry on next push): ${errorMessage(err)}`);
     }
 }
-/**
- * Singleton manager for persistent agent state stored in ~/.oss-autopilot/state.json.
- *
- * Delegates file I/O to state-persistence.ts and scoring logic to repo-score-manager.ts.
- * Retains lightweight CRUD operations for config, issues, shelving, dismissal,
- * and status overrides.
- */
 export class StateManager {
     state;
     inMemoryOnly;
@@ -67,6 +61,8 @@ export class StateManager {
     _batchDirty = false;
     gistStore = null;
     gistDegraded = false;
+    staleness = null;
+    lastSuccessfulRefreshAt = null;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -130,6 +126,16 @@ export class StateManager {
         manager.gistStore = gistStore;
         manager.gistDegraded = result.degraded ?? false;
         manager.inMemoryOnly = false; // re-enable persistence
+        // Seed the staleness marker if bootstrap fell back to the local cache —
+        // a `daily` running on a cron right after this start needs to know.
+        if (result.degraded) {
+            manager.staleness = {
+                source: 'cache',
+                reason: 'initial Gist bootstrap fell back to local cache',
+                lastSuccessfulRefresh: null,
+                detectedAt: new Date().toISOString(),
+            };
+        }
         return manager;
     }
     /**
@@ -274,6 +280,41 @@ export class StateManager {
     isGistDegraded() {
         return this.gistDegraded;
     }
+    /**
+     * Whether per-repo guidelines (#867) are available. True iff the Gist store
+     * is initialized — in local-only mode, guidelines are unavailable and
+     * write operations would throw {@link GuidelinesNotAvailableError}.
+     */
+    isGuidelinesAvailable() {
+        return this.gistStore !== null;
+    }
+    /**
+     * Read the per-repo guidelines for `repo` (#867). Returns null when in
+     * local mode, when no file exists, or when the file is empty (tombstoned).
+     */
+    getGuidelines(repo) {
+        return guidelinesStoreModule.getGuidelines(this.gistStore, repo);
+    }
+    /**
+     * Persist per-repo guidelines for `repo`. Throws when not in Gist mode or
+     * when content exceeds the byte budget.
+     */
+    setGuidelines(repo, content) {
+        guidelinesStoreModule.setGuidelines(this.gistStore, repo, content);
+        this.autoSave();
+    }
+    /**
+     * Tombstone the guidelines file for `repo` so subsequent reads return null.
+     * Throws when not in Gist mode.
+     */
+    deleteGuidelines(repo) {
+        guidelinesStoreModule.deleteGuidelines(this.gistStore, repo);
+        this.autoSave();
+    }
+    /** List repos with non-empty guidelines stored in the Gist. */
+    listGuidelinesRepos() {
+        return guidelinesStoreModule.listGuidelinesRepos(this.gistStore);
+    }
     /**
      * Get the current state as a read-only snapshot.
      */
@@ -309,6 +350,15 @@ export class StateManager {
             const raw = this.gistStore.cachedFiles.get('state.json');
             if (!raw) {
                 warn(MODULE, 'Gist refreshed but state.json missing from cache');
+                // HTTP fetch succeeded but the Gist body is missing state.json — we
+                // still have stale in-memory data, so surface a marker rather than
+                // silently returning false (#1193 review).
+                this.staleness = {
+                    source: 'cache',
+                    reason: 'Gist refresh returned no state.json file',
+                    lastSuccessfulRefresh: this.lastSuccessfulRefreshAt,
+                    detectedAt: new Date().toISOString(),
+                };
                 return false;
             }
             try {
@@ -317,11 +367,41 @@ export class StateManager {
             }
             catch (err) {
                 warn(MODULE, `Failed to parse refreshed Gist state: ${errorMessage(err)}`);
+                // Same reasoning as the missing-file branch: parse failure leaves us
+                // on stale in-memory state, so flag it.
+                this.staleness = {
+                    source: 'cache',
+                    reason: `Gist refresh succeeded but payload was invalid: ${errorMessage(err)}`,
+                    lastSuccessfulRefresh: this.lastSuccessfulRefreshAt,
+                    detectedAt: new Date().toISOString(),
+                };
                 return false;
             }
+            // Successful refresh clears any prior staleness (#1193).
+            this.lastSuccessfulRefreshAt = new Date().toISOString();
+            this.staleness = null;
+        }
+        else if (this.gistStore.lastRefreshError) {
+            // Distinguish "fetch failed" (set marker) from "throttled" (preserve
+            // any existing marker, set nothing new).
+            this.staleness = {
+                source: 'cache',
+                reason: errorMessage(this.gistStore.lastRefreshError),
+                lastSuccessfulRefresh: this.lastSuccessfulRefreshAt,
+                detectedAt: new Date().toISOString(),
+            };
         }
         return refreshed;
     }
+    /**
+     * Returns a staleness marker when the in-memory state diverged from the
+     * canonical Gist (refresh failure or degraded bootstrap), or `null` when
+     * state is current. Commands surface this via their `--json` warnings
+     * envelope (#1193).
+     */
+    getStateStaleness() {
+        return this.staleness;
+    }
     // === Dashboard Data Setters ===
     /**
      * Store the latest daily digest and update the digest timestamp.
@@ -434,6 +514,40 @@ export class StateManager {
     getClosedPRWatermark() {
         return this.state.closedPRs?.[0]?.closedAt || undefined;
     }
+    /**
+     * Stamp `commentsFetchedAt` on the merged or closed PR matching `url` (#867).
+     * No-op when no PR with that URL is stored.
+     */
+    markPRCommentsFetched(url, fetchedAt) {
+        const merged = this.state.mergedPRs?.find((pr) => pr.url === url);
+        if (merged) {
+            merged.commentsFetchedAt = fetchedAt;
+            this.autoSave();
+            return;
+        }
+        const closed = this.state.closedPRs?.find((pr) => pr.url === url);
+        if (closed) {
+            closed.commentsFetchedAt = fetchedAt;
+            this.autoSave();
+        }
+    }
+    /**
+     * Stamp `learningsExtractedAt` on the merged or closed PR matching `url` (#867).
+     * No-op when no PR with that URL is stored.
+     */
+    markPRLearningsExtracted(url, extractedAt) {
+        const merged = this.state.mergedPRs?.find((pr) => pr.url === url);
+        if (merged) {
+            merged.learningsExtractedAt = extractedAt;
+            this.autoSave();
+            return;
+        }
+        const closed = this.state.closedPRs?.find((pr) => pr.url === url);
+        if (closed) {
+            closed.learningsExtractedAt = extractedAt;
+            this.autoSave();
+        }
+    }
     // === Configuration ===
     /**
      * Merge partial config updates into the current configuration.
@@ -777,11 +891,20 @@ export async function getStateManagerAsync(token) {
         })
             .catch((err) => {
             asyncManagerPromise = null;
-            // Configuration errors (e.g. GistPermissionError) must surface to the user
+            // Configuration errors (e.g. GistPermissionError, GistCorruptError)
+            // must surface — falling back to local-only would silently split state
+            // across machines (#1202).
             if (err instanceof ConfigurationError)
                 throw err;
-            warn(MODULE, `Gist initialization failed, falling back to local-only mode: ${err}`);
-            return getStateManager(); // fall back to sync/local for transient errors
+            // Only fall back on actual network/server errors. Other failures
+            // (auth, schema, concurrency conflicts) indicate the Gist mode is
+            // broken in a way the user needs to address — silently falling back
+            // would write subsequent mutations to the local file while the Gist
+            // marker stays in config, causing permanent cross-machine divergence.
+            if (!isTransientNetworkError(err))
+                throw err;
+            warn(MODULE, `Gist initialization failed (transient network error), falling back to local-only mode: ${err}`);
+            return getStateManager();
         });
         return asyncManagerPromise;
     }
@@ -810,7 +933,7 @@ export async function ensureGistPersistence(token) {
         return;
     let persistence;
     try {
-        const raw = fs.readFileSync(getStatePath(), 'utf-8');
+        const raw = fs.readFileSync(getStatePath(), 'utf8');
         persistence = JSON.parse(raw)?.config?.persistence;
     }
     catch {

package/dist/core/types.d.ts

@@ -233,7 +233,7 @@ interface CommentedIssueWithoutResponse extends CommentedIssueBase {
 export type CommentedIssue = CommentedIssueWithResponse | CommentedIssueWithoutResponse;
 /** Default configuration applied to new state files. All fields can be overridden via `/setup-oss`. */
 export declare const DEFAULT_CONFIG: AgentConfig;
-/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v3 architecture. */
+/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v4 architecture. */
 export declare const INITIAL_STATE: AgentState;
 export declare const PROJECT_CATEGORIES: ("nonprofit" | "devtools" | "infrastructure" | "web-frameworks" | "data-ml" | "education")[];
 export declare const ISSUE_SCOPES: ("advanced" | "beginner" | "intermediate")[];

package/dist/core/types.js

@@ -12,8 +12,8 @@ export function isBelowMinStars(stargazersCount, minStars) {
 // ── Schema-derived constants ─────────────────────────────────────────
 /** Default configuration applied to new state files. All fields can be overridden via `/setup-oss`. */
 export const DEFAULT_CONFIG = AgentConfigSchema.parse({});
-/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v3 architecture. */
-export const INITIAL_STATE = AgentStateSchema.parse({ version: 3 });
+/** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v4 architecture. */
+export const INITIAL_STATE = AgentStateSchema.parse({ version: 4 });
 // ── Const arrays (derived from Zod schemas for runtime iteration) ────
 export const PROJECT_CATEGORIES = ProjectCategorySchema.options;
 export const ISSUE_SCOPES = IssueScopeSchema.options;

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

@@ -0,0 +1,48 @@
+/**
+ * Wrap GitHub-sourced text (PR titles, PR bodies, issue bodies, review
+ * comments) in a fenced delimiter so the LLM treats it as data, not
+ * instructions (#1192).
+ *
+ * The contract this module pins, exercised by `untrusted-content.test.ts`
+ * and the prompt-injection corpus:
+ *
+ *  1. Output starts with the open tag and ends with the close tag.
+ *  2. The close-tag literal NEVER appears inside the wrapped body — any
+ *     occurrence in the input is escaped to a sentinel so an attacker
+ *     cannot close the fence early and inject instructions after it.
+ *  3. `extractFromFence(wrapUntrustedContent(x, label))` returns `x`
+ *     unchanged for any input — the wrapping is lossless.
+ *
+ * Consumers should pair this with the agent-side guidance in
+ * `workflows/reference.md` ("Prompt Injection Awareness"), which tells
+ * the LLM to ignore instructions inside `<github-content>` blocks.
+ *
+ * Non-goals:
+ *  - This is NOT a content filter. We do not detect or strip prompt-
+ *    injection payloads; the human-in-the-loop gate on `post`/`claim`
+ *    remains the primary control.
+ */
+export declare const UNTRUSTED_OPEN_TAG_NAME = "github-content";
+export declare const UNTRUSTED_CLOSE_TAG = "</github-content>";
+export interface UntrustedContentMeta {
+    /** GitHub login of the content's author (e.g. PR comment author). */
+    author?: string;
+    /** GitHub author_association (OWNER, MEMBER, CONTRIBUTOR, NONE, ...). */
+    association?: string;
+    /** Free-form provenance label (e.g. "pr-body", "review-comment"). */
+    source?: string;
+}
+/**
+ * Wrap `text` in a `<github-content>` fence labeled with `label` and the
+ * optional metadata. Any occurrence of the close-tag literal inside `text`
+ * is replaced with a zero-width-joined sentinel that round-trips losslessly
+ * via {@link extractFromFence}.
+ */
+export declare function wrapUntrustedContent(text: string, label: string, meta?: UntrustedContentMeta): string;
+/**
+ * Reverse of {@link wrapUntrustedContent}. Extracts the original body text
+ * (un-escaping any sentinel-encoded close tags). Throws if the input is not
+ * a single well-formed fence — callers shouldn't be parsing arbitrary
+ * markdown with this; it's for tests + symmetric reasoning only.
+ */
+export declare function extractFromFence(fenced: string): string;

package/dist/core/untrusted-content.js

@@ -0,0 +1,106 @@
+/**
+ * Wrap GitHub-sourced text (PR titles, PR bodies, issue bodies, review
+ * comments) in a fenced delimiter so the LLM treats it as data, not
+ * instructions (#1192).
+ *
+ * The contract this module pins, exercised by `untrusted-content.test.ts`
+ * and the prompt-injection corpus:
+ *
+ *  1. Output starts with the open tag and ends with the close tag.
+ *  2. The close-tag literal NEVER appears inside the wrapped body — any
+ *     occurrence in the input is escaped to a sentinel so an attacker
+ *     cannot close the fence early and inject instructions after it.
+ *  3. `extractFromFence(wrapUntrustedContent(x, label))` returns `x`
+ *     unchanged for any input — the wrapping is lossless.
+ *
+ * Consumers should pair this with the agent-side guidance in
+ * `workflows/reference.md` ("Prompt Injection Awareness"), which tells
+ * the LLM to ignore instructions inside `<github-content>` blocks.
+ *
+ * Non-goals:
+ *  - This is NOT a content filter. We do not detect or strip prompt-
+ *    injection payloads; the human-in-the-loop gate on `post`/`claim`
+ *    remains the primary control.
+ */
+export const UNTRUSTED_OPEN_TAG_NAME = 'github-content';
+export const UNTRUSTED_CLOSE_TAG = `</${UNTRUSTED_OPEN_TAG_NAME}>`;
+/**
+ * Sentinels used to neutralize any literal open- or close-tag substring
+ * inside the wrapped body. We use HTML entity escapes (`&lt;` / `&gt;`) so
+ * the result is pure ASCII, lints cleanly, and round-trips losslessly. The
+ * `&` itself is escaped first so an input containing the literal text
+ * `&lt;/github-content&gt;` survives the wrap/unwrap round-trip without
+ * collision.
+ */
+const AMP_ESCAPE = '&amp;';
+const CLOSE_TAG_ESCAPE = `&lt;/${UNTRUSTED_OPEN_TAG_NAME}&gt;`;
+const OPEN_TAG_PATTERN = new RegExp(`<${UNTRUSTED_OPEN_TAG_NAME}\\b`, 'g');
+const OPEN_TAG_ESCAPE = `&lt;${UNTRUSTED_OPEN_TAG_NAME}`;
+function escapeAttr(value) {
+    // Newlines/carriage returns can't break out of a quoted attribute (no `"`)
+    // but they visually fragment the open tag in the prompt text the LLM
+    // reads, so encode them as numeric entities for defense-in-depth.
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/\n/g, '&#10;')
+        .replace(/\r/g, '&#13;');
+}
+/**
+ * Wrap `text` in a `<github-content>` fence labeled with `label` and the
+ * optional metadata. Any occurrence of the close-tag literal inside `text`
+ * is replaced with a zero-width-joined sentinel that round-trips losslessly
+ * via {@link extractFromFence}.
+ */
+export function wrapUntrustedContent(text, label, meta = {}) {
+    // Escape order matters for round-trip correctness:
+    //  1. `&` first — so any pre-existing entity in the input gets a literal
+    //     `&amp;` that survives the unwrap pass below.
+    //  2. Close-tag literals — replaced with the entity-escaped form.
+    //  3. Open-tag literals (matched only at boundaries via OPEN_TAG_PATTERN
+    //     so we don't accidentally rewrite the close-tag's `</github-content`).
+    const escapedBody = text
+        .split('&')
+        .join(AMP_ESCAPE)
+        .split(UNTRUSTED_CLOSE_TAG)
+        .join(CLOSE_TAG_ESCAPE)
+        .replace(OPEN_TAG_PATTERN, OPEN_TAG_ESCAPE);
+    const attrs = [`label="${escapeAttr(label)}"`];
+    if (meta.author !== undefined)
+        attrs.push(`author="${escapeAttr(meta.author)}"`);
+    if (meta.association !== undefined)
+        attrs.push(`association="${escapeAttr(meta.association)}"`);
+    if (meta.source !== undefined)
+        attrs.push(`source="${escapeAttr(meta.source)}"`);
+    return `<${UNTRUSTED_OPEN_TAG_NAME} ${attrs.join(' ')}>${escapedBody}${UNTRUSTED_CLOSE_TAG}`;
+}
+/**
+ * Reverse of {@link wrapUntrustedContent}. Extracts the original body text
+ * (un-escaping any sentinel-encoded close tags). Throws if the input is not
+ * a single well-formed fence — callers shouldn't be parsing arbitrary
+ * markdown with this; it's for tests + symmetric reasoning only.
+ */
+export function extractFromFence(fenced) {
+    const openMatch = fenced.match(new RegExp(`^<${UNTRUSTED_OPEN_TAG_NAME}\\b[^>]*>`));
+    if (!openMatch) {
+        throw new Error('extractFromFence: input does not start with a <github-content> open tag');
+    }
+    if (!fenced.endsWith(UNTRUSTED_CLOSE_TAG)) {
+        throw new Error('extractFromFence: input does not end with </github-content>');
+    }
+    const inner = fenced.slice(openMatch[0].length, fenced.length - UNTRUSTED_CLOSE_TAG.length);
+    if (inner.includes(UNTRUSTED_CLOSE_TAG)) {
+        throw new Error('extractFromFence: nested </github-content> found in body — fence escaping is broken');
+    }
+    // Reverse the escapes in opposite order: tag entities first (so an
+    // already-`&amp;`-prefixed entity survives), then unescape `&amp;`.
+    return inner
+        .split(CLOSE_TAG_ESCAPE)
+        .join(UNTRUSTED_CLOSE_TAG)
+        .split(OPEN_TAG_ESCAPE)
+        .join(`<${UNTRUSTED_OPEN_TAG_NAME}`)
+        .split(AMP_ESCAPE)
+        .join('&');
+}

package/dist/core/urls.js

@@ -5,8 +5,8 @@
  * owner/repo characters. Extracted from utils.ts under #1116.
  */
 // Validation patterns for GitHub owner and repo names
-const OWNER_PATTERN = /^[a-zA-Z0-9_-]+$/;
-const REPO_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+const OWNER_PATTERN = /^[\w-]+$/;
+const REPO_PATTERN = /^[\w.-]+$/;
 function isValidOwnerRepo(owner, repo) {
     return OWNER_PATTERN.test(owner) && REPO_PATTERN.test(repo);
 }

package/dist/formatters/json.d.ts

@@ -3,10 +3,9 @@
  * Provides structured output that can be consumed by scripts and plugins
  */
 import { z, type ZodType } from 'zod';
-import type { FetchedPR, DailyDigest, AgentState, RepoGroup, CommentedIssue, ShelvedPRRef } from '../core/types.js';
+import type { FetchedPR, DailyDigest, AgentState, RepoGroup, CommentedIssue, ShelvedPRRef, SearchPriority, CapacityAssessment, ActionableIssue, ActionableIssueType, CompactActionableIssue, ActionMenuItem, ActionMenu } from '../core/types.js';
 import type { ContributionStats } from '../core/stats.js';
 import type { PRCheckFailure } from '../core/pr-monitor.js';
-import type { SearchPriority, CapacityAssessment, ActionableIssue, ActionableIssueType, CompactActionableIssue, ActionMenuItem, ActionMenu } from '../core/types.js';
 import type { CIFormatterDiagnosis, FormatterDetectionResult } from '../core/formatter-detection.js';
 export type { CapacityAssessment, ActionableIssue, ActionableIssueType, CompactActionableIssue, ActionMenuItem, ActionMenu, };
 export type ErrorCode = 'AUTH_REQUIRED' | 'RATE_LIMITED' | 'VALIDATION' | 'CONFIGURATION' | 'NETWORK' | 'NOT_FOUND' | 'STATE_CORRUPTED' | 'CONCURRENCY' | 'UNKNOWN';
@@ -51,18 +50,37 @@ export interface CompactRepoGroup {
  * See `DailyWarning` and issue #1042 for the rationale — keeping this a
  * fixed union so downstream consumers can switch on it without drift.
  */
-export type DailyWarningPhase = 'fetch' | 'repo-scores' | 'analytics' | 'scout-sync' | 'partition' | 'dismiss-filter' | 'gist-checkpoint';
+export type DailyWarningPhase = 'fetch' | 'repo-scores' | 'analytics' | 'scout-sync' | 'partition' | 'dismiss-filter' | 'gist-checkpoint' | 'gist-staleness';
 /**
  * A single non-fatal failure surfaced from the `daily` pipeline. Unlike
  * `PRCheckFailure` (which is scoped to per-PR fetch errors), this covers
  * ancillary fetches that previously demoted to a log-only `warn()` — repo
  * metadata, monthly analytics, scout sync, Gist checkpoint, etc.
+ *
+ * `timestamp` and `details` are optional structured extensions added in
+ * #1193 so staleness warnings can carry `lastSuccessfulRefresh` /
+ * `detectedAt` without bespoke schemas. Existing producers don't need to
+ * supply them.
  */
 export interface DailyWarning {
     phase: DailyWarningPhase;
     operation: string;
     message: string;
+    timestamp?: string;
+    details?: Record<string, unknown>;
 }
+/**
+ * Build a warning entry from a {@link StalenessInfo} marker (#1193).
+ * Co-located with `DailyWarning` so every command (`daily`, `status`,
+ * `comments`) builds the same shape from the same source.
+ */
+export interface StalenessLike {
+    source: string;
+    reason: string;
+    lastSuccessfulRefresh: string | null;
+    detectedAt: string;
+}
+export declare function buildStalenessWarning(info: StalenessLike): DailyWarning;
 export interface DailyOutput {
     digest: DailyDigestCompact;
     capacity: CapacityAssessment;
@@ -139,6 +157,22 @@ export declare const StatusOutputSchema: z.ZodObject<{
     lastRunAt: z.ZodString;
     offline: z.ZodOptional<z.ZodBoolean>;
     lastUpdated: z.ZodOptional<z.ZodString>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            fetch: "fetch";
+            "repo-scores": "repo-scores";
+            analytics: "analytics";
+            "scout-sync": "scout-sync";
+            partition: "partition";
+            "dismiss-filter": "dismiss-filter";
+            "gist-checkpoint": "gist-checkpoint";
+            "gist-staleness": "gist-staleness";
+        }>;
+        operation: z.ZodString;
+        message: z.ZodString;
+        timestamp: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type StatusOutput = z.infer<typeof StatusOutputSchema>;
 export declare const DailyOutputSchema: z.ZodObject<{
@@ -234,9 +268,12 @@ export declare const DailyOutputSchema: z.ZodObject<{
             partition: "partition";
             "dismiss-filter": "dismiss-filter";
             "gist-checkpoint": "gist-checkpoint";
+            "gist-staleness": "gist-staleness";
         }>;
         operation: z.ZodString;
         message: z.ZodString;
+        timestamp: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const CompactDailyOutputSchema: z.ZodObject<{
@@ -327,9 +364,12 @@ export declare const CompactDailyOutputSchema: z.ZodObject<{
             partition: "partition";
             "dismiss-filter": "dismiss-filter";
             "gist-checkpoint": "gist-checkpoint";
+            "gist-staleness": "gist-staleness";
         }>;
         operation: z.ZodString;
         message: z.ZodString;
+        timestamp: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const SearchOutputSchema: z.ZodObject<{
@@ -426,6 +466,14 @@ export declare const InitOutputSchema: z.ZodObject<{
     username: z.ZodString;
     message: z.ZodString;
 }, z.core.$strip>;
+export declare const ManifestOutputSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    cliVersion: z.ZodString;
+    commands: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        localOnly: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const CheckSetupOutputSchema: z.ZodObject<{
     setupComplete: z.ZodBoolean;
     username: z.ZodString;
@@ -791,6 +839,8 @@ export interface CommentsOutput {
         inlineCommentCount: number;
         discussionCommentCount: number;
     };
+    /** Non-fatal warnings (e.g. stale-cache fallback, #1193). Always present; empty on clean runs. */
+    warnings?: DailyWarning[];
 }
 /** Output of the post command */
 export interface PostOutput {