@morehao/dsh-github-trending 0.1.4 → 0.3.0

package/lib/internal.d.ts

@@ -1,60 +1,8 @@
+import { ErrorCode, FileArtifact, ErrorInfo, RunRequest, RunResult, State, StateRun } from '@morehao/trendradar-contract';
 import http from 'node:http';
 
 /**
- * 由 scripts/gen-ipc-types.mjs 从 contract/schema/ipc.v1.json 生成，**不要手改**。
- * 上游：https://github.com/morehao/trendradar.git@d3bf720a869732e7a2ee04fa39d32dd50868fd61
- * aggregate：eb7f1ac9e117a709d15d87de89cf30e309c479e62dfa3d320cb8f154d3f1dc1e
- * 重新生成：npm run gen:ipc
- */
-type ErrorCode = "INTERNAL" | "CONFIG_INVALID" | "PAYLOAD_TOO_LARGE" | "FETCH_FAILED" | "FETCH_RATE_LIMITED" | "PARSE_FAILED" | "MODEL_UNAUTHORIZED" | "MODEL_RATE_LIMITED" | "MODEL_TIMEOUT" | "MODEL_FAILED" | "MODEL_BAD_OUTPUT" | "GIT_NOT_INSTALLED" | "REPO_NOT_GIT" | "REPO_DIRTY" | "GIT_OPERATION_FAILED" | "PR_FAILED" | "NOT_MERGEABLE";
-interface ErrorInfo {
-    code: ErrorCode;
-    message: string;
-    retriable: boolean;
-    details?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-interface FileArtifact {
-    path: string;
-    bytes: number;
-    sha256: string;
-    [key: string]: unknown;
-}
-interface RunRequest {
-    ipcSchema: 1;
-    command: "run" | "serve" | "config" | "version";
-    configPath?: string;
-    date?: string;
-    dryRun?: boolean;
-    outputDir?: string;
-}
-interface RunResult {
-    ipcSchema: 1;
-    ok: boolean;
-    command: "run" | "serve" | "config" | "version";
-    startedAt: string;
-    finishedAt: string;
-    skipped: boolean;
-    files: FileArtifact[];
-    error?: ErrorInfo;
-    warnings?: string[];
-    [key: string]: unknown;
-}
-interface StateRun {
-    date: string;
-    contentHash: string;
-    runAt: string;
-    [key: string]: unknown;
-}
-interface State {
-    ipcSchema: 1;
-    lastRun?: StateRun;
-    [key: string]: unknown;
-}
-declare const IPC_SCHEMA_VERSION: 1;
-
-/**
- * 错误码：核心码（`ipc.v1` 的 17 个）+ 插件自己的码。
+ * 错误码：核心码（契约包 `ipc.v2` / `errors.v2` 的 17 个）+ 插件自己的码。
  *
  * 核心当前只在 stderr 打 `error: <CODE>: <message>`，模型/抓取的失败甚至没有码，
  * 所以这里承担两件事：
@@ -78,13 +26,22 @@ declare function isRetriable(code: string): boolean;
 /** 错误码 → 界面落点。UI 用这个决定红字出现在哪个区块。 */
 type ErrorArea = 'core' | 'model' | 'repo' | 'auth' | 'run';
 declare function areaOf(code: string): ErrorArea;
+/**
+ * push 失败的细分原因。核心新版本会在 `details.reason` 里给出；旧核心只有
+ * stderr 时按文本兜底。`stale-lease` 必须排在 `non-fast-forward` 之前：
+ * 前者是 lease 基线过期，后者是历史分叉，下一步完全不同。
+ */
+type GitReason = 'stale-lease' | 'non-fast-forward' | 'auth' | 'protected' | 'hook' | 'pathspec' | 'unknown';
+declare function reasonOf(code: string, message?: string, details?: Record<string, unknown>): string | undefined;
 /** 每种码一句「下一步怎么做」，避免界面只给码不给路。 */
-declare function hintOf(code: string): string;
+declare function hintOf(code: string, message?: string, reason?: string): string;
 /**
  * 从核心的 stderr 里解出一个结构化错误。
  *
  * 优先级：`error: <CODE>: ...` 的显式码 > 文本归类 > INTERNAL。
- * message 只取最后一条非空行（核心把根因打在最外层，前面的行多是上下文）。
+ * 显式码命中的那一行往往只是首行（如 `error: GIT_OPERATION_FAILED: To github.com:...`），
+ * 真正的根因在其后的多行里（`! [rejected] ... (non-fast-forward)`、`hint: ...`），
+ * 因此把这些诊断行一并保留进 message，避免界面只看到半句。
  */
 declare function classifyStderr(stderr: string): ClassifiedError;
 /**
@@ -96,38 +53,32 @@ declare function redact(input: string, secrets?: Array<string | undefined>): str
 type errors_AnyCode = AnyCode;
 type errors_ClassifiedError = ClassifiedError;
 type errors_ErrorArea = ErrorArea;
+type errors_GitReason = GitReason;
 declare const errors_PLUGIN_CODES: typeof PLUGIN_CODES;
 type errors_PluginCode = PluginCode;
 declare const errors_areaOf: typeof areaOf;
 declare const errors_classifyStderr: typeof classifyStderr;
 declare const errors_hintOf: typeof hintOf;
 declare const errors_isRetriable: typeof isRetriable;
+declare const errors_reasonOf: typeof reasonOf;
 declare const errors_redact: typeof redact;
 declare namespace errors {
-  export { type errors_AnyCode as AnyCode, type errors_ClassifiedError as ClassifiedError, type errors_ErrorArea as ErrorArea, errors_PLUGIN_CODES as PLUGIN_CODES, type errors_PluginCode as PluginCode, errors_areaOf as areaOf, errors_classifyStderr as classifyStderr, errors_hintOf as hintOf, errors_isRetriable as isRetriable, errors_redact as redact };
+  export { type errors_AnyCode as AnyCode, type errors_ClassifiedError as ClassifiedError, type errors_ErrorArea as ErrorArea, type errors_GitReason as GitReason, errors_PLUGIN_CODES as PLUGIN_CODES, type errors_PluginCode as PluginCode, errors_areaOf as areaOf, errors_classifyStderr as classifyStderr, errors_hintOf as hintOf, errors_isRetriable as isRetriable, errors_reasonOf as reasonOf, errors_redact as redact };
 }
 
-/**
- * 契约类型与运行时守卫。
- *
- * 类型来自 `contract/schema/ipc.v1.json` 的生成物（`ipc.gen.ts`）；本文件只放
- * 契约没有、但插件必须理解的东西：核心 `version --json` 的握手形状、核心 `run --json`
- * 的输出形状，以及把两种结果形状归一化成 `RunOutcome` 的解析器。
- *
- * 为什么同时接受两种形状：`contract/schema/ipc.v1.json` 定义的是 `RunResult`
- * （`ok`/`startedAt`/`error.code`），而当前核心的 `run --json` 输出的是一份更小的
- * `runOutput`（`files`/`skipped`/`branch`/`prUrl`/`digest.contentHash`），错误只走
- * stderr 文本。核心补上信封后，`parseRunResult` 无需改动即可接住。
- */
-
+/** 插件实现所对应的 IPC 契约版本（契约包 `ipc.v2.json` 的 wire 整数）。 */
+declare const IPC_SCHEMA_VERSION: 2;
 /** 插件能接受的 digest 契约版本（与核心 `version --json` 的 digestSchema 比对）。 */
-declare const SUPPORTED_DIGEST_SCHEMA = 1;
+declare const SUPPORTED_DIGEST_SCHEMA: 2;
+/** 契约包 `contractVersion` 的主版本；0.x 期间同主版本即视为同一契约线。 */
+declare const SUPPORTED_CONTRACT_MAJOR = 0;
 /** 核心 `version --json` 的输出。 */
 interface VersionInfo {
     version: string;
     commit?: string;
     ipcSchema: number;
     digestSchema: number;
+    contractVersion?: string;
     supportedProviders?: string[];
 }
 /** 插件侧的错误信息：`code` 可能是核心码，也可能是插件码（`CORE_*` 等）。 */
@@ -147,6 +98,8 @@ interface RunOutcome {
     branch?: string;
     commit?: string;
     prUrl?: string;
+    /** 核心给出的跳过原因：merged | pr-closed | unchanged（可选，旧核心没有）。 */
+    skipReason?: string;
     error?: RunError;
     warnings: string[];
     startedAt: string;
@@ -165,6 +118,7 @@ declare class IpcError extends Error {
 declare function parseJsonObject(text: string): Record<string, unknown>;
 declare function isVersionInfo(value: unknown): value is VersionInfo;
 declare function parseVersionInfo(text: string): VersionInfo;
+/** 契约包 `RunResult` → 插件内部 `RunOutcome` 的唯一映射。 */
 interface ParseRunOptions {
     coreVersion: string;
     startedAt: string;
@@ -175,38 +129,40 @@ interface ParseRunOptions {
 /**
  * 把核心 `run --json` 的 stdout 归一化成 `RunOutcome`。
  *
- * 两种形状的判别：有 `ipcSchema` 且 `command === 'run'` 就是契约 `RunResult`；
- * 否则按当前核心的 `runOutput` 处理。两者都不像就直接 `IPC_INVALID`，
- * 绝不「猜字段」——结果信封读错会把失败当成功写进状态。
+ * 唯一接受的形状是契约 `RunResult`（`ipcSchema=2` / `command=run`），并用契约包
+ * 自带的 ajv 校验器校验。任何其它形状直接 `IPC_INVALID`——结果信封读错会把失败
+ * 当成功写进状态。
  */
 declare function parseRunResult(text: string, options: ParseRunOptions): RunOutcome;
 
-type ipc_ErrorCode = ErrorCode;
-type ipc_ErrorInfo = ErrorInfo;
-type ipc_FileArtifact = FileArtifact;
+declare const ipc_ErrorCode: typeof ErrorCode;
+declare const ipc_ErrorInfo: typeof ErrorInfo;
+declare const ipc_FileArtifact: typeof FileArtifact;
 declare const ipc_IPC_SCHEMA_VERSION: typeof IPC_SCHEMA_VERSION;
 type ipc_IpcError = IpcError;
 declare const ipc_IpcError: typeof IpcError;
 type ipc_ParseRunOptions = ParseRunOptions;
 type ipc_RunError = RunError;
 type ipc_RunOutcome = RunOutcome;
-type ipc_RunRequest = RunRequest;
-type ipc_RunResult = RunResult;
+declare const ipc_RunRequest: typeof RunRequest;
+declare const ipc_RunResult: typeof RunResult;
+declare const ipc_SUPPORTED_CONTRACT_MAJOR: typeof SUPPORTED_CONTRACT_MAJOR;
 declare const ipc_SUPPORTED_DIGEST_SCHEMA: typeof SUPPORTED_DIGEST_SCHEMA;
-type ipc_State = State;
-type ipc_StateRun = StateRun;
+declare const ipc_State: typeof State;
+declare const ipc_StateRun: typeof StateRun;
 type ipc_VersionInfo = VersionInfo;
 declare const ipc_isVersionInfo: typeof isVersionInfo;
 declare const ipc_parseJsonObject: typeof parseJsonObject;
 declare const ipc_parseRunResult: typeof parseRunResult;
 declare const ipc_parseVersionInfo: typeof parseVersionInfo;
 declare namespace ipc {
-  export { type ipc_ErrorCode as ErrorCode, type ipc_ErrorInfo as ErrorInfo, type ipc_FileArtifact as FileArtifact, ipc_IPC_SCHEMA_VERSION as IPC_SCHEMA_VERSION, ipc_IpcError as IpcError, type ipc_ParseRunOptions as ParseRunOptions, type ipc_RunError as RunError, type ipc_RunOutcome as RunOutcome, type ipc_RunRequest as RunRequest, type ipc_RunResult as RunResult, ipc_SUPPORTED_DIGEST_SCHEMA as SUPPORTED_DIGEST_SCHEMA, type ipc_State as State, type ipc_StateRun as StateRun, type ipc_VersionInfo as VersionInfo, ipc_isVersionInfo as isVersionInfo, ipc_parseJsonObject as parseJsonObject, ipc_parseRunResult as parseRunResult, ipc_parseVersionInfo as parseVersionInfo };
+  export { ipc_ErrorCode as ErrorCode, ipc_ErrorInfo as ErrorInfo, ipc_FileArtifact as FileArtifact, ipc_IPC_SCHEMA_VERSION as IPC_SCHEMA_VERSION, ipc_IpcError as IpcError, type ipc_ParseRunOptions as ParseRunOptions, type ipc_RunError as RunError, type ipc_RunOutcome as RunOutcome, ipc_RunRequest as RunRequest, ipc_RunResult as RunResult, ipc_SUPPORTED_CONTRACT_MAJOR as SUPPORTED_CONTRACT_MAJOR, ipc_SUPPORTED_DIGEST_SCHEMA as SUPPORTED_DIGEST_SCHEMA, ipc_State as State, ipc_StateRun as StateRun, type ipc_VersionInfo as VersionInfo, ipc_isVersionInfo as isVersionInfo, ipc_parseJsonObject as parseJsonObject, ipc_parseRunResult as parseRunResult, ipc_parseVersionInfo as parseVersionInfo };
 }
 
 type Provider = string;
 type CommitMode = 'branch' | 'direct';
-type AuthMode = 'device' | 'pat' | 'gh';
+/** 只保留两种真正可用的方式：本机 `gh` 登录态、手动 PAT。历史的 `device` 在归一化时迁移为 `gh`。 */
+type AuthMode = 'pat' | 'gh';
 type Since = 'daily' | 'weekly';
 interface ModelSettings {
     provider: Provider;
@@ -271,6 +227,16 @@ declare const DEFAULT_SETTINGS: Settings;
 /** 核心支持的 provider 默认端点（空字符串 = 必须由用户填）。 */
 declare const PROVIDER_BASE_URLS: Record<string, string>;
 declare const CORE_PROVIDERS: readonly ["deepseek", "openai-compatible"];
+/** 设置页分区；分段保存时只提交并校验对应分区，互不牵连。 */
+declare const SETTINGS_SECTIONS: readonly ["source", "model", "repo", "auth", "scope", "schedule"];
+type SettingsSection = (typeof SETTINGS_SECTIONS)[number];
+/** 校验问题字段 → 所属分区（用于分段保存时只把本分区的问题回给界面）。 */
+declare function sectionOfField(field: string): SettingsSection | undefined;
+/**
+ * 分段保存：只把 `incoming` 里 `section` 的字段合并进 `stored`，其余分区保持已保存值。
+ * 这样一个 tab 的保存不会顺带提交或覆盖其它 tab 里尚未保存的改动。
+ */
+declare function mergeSettingsSection(stored: Settings, incoming: Settings, section: SettingsSection): Settings;
 /**
  * 把任意来源的对象（磁盘上的旧版本、HTTP 请求体、CLI 导入）收敛成完整设置。
  * 未知字段一律丢弃：settings.json 只有以下形状，避免旧版本字段悄悄生效。
@@ -349,18 +315,22 @@ type config_PRSettings = PRSettings;
 type config_Problem = Problem;
 type config_Provider = Provider;
 type config_RepoSettings = RepoSettings;
+declare const config_SETTINGS_SECTIONS: typeof SETTINGS_SECTIONS;
 type config_ScheduleSettings = ScheduleSettings;
 type config_Settings = Settings;
+type config_SettingsSection = SettingsSection;
 type config_Since = Since;
 type config_TrendingSettings = TrendingSettings;
 declare const config_effectiveBaseURL: typeof effectiveBaseURL;
 declare const config_isValidTimezone: typeof isValidTimezone;
+declare const config_mergeSettingsSection: typeof mergeSettingsSection;
 declare const config_normalizeSettings: typeof normalizeSettings;
+declare const config_sectionOfField: typeof sectionOfField;
 declare const config_toCoreConfig: typeof toCoreConfig;
 declare const config_toYaml: typeof toYaml;
 declare const config_validateSettings: typeof validateSettings;
 declare namespace config {
-  export { type config_AuthMode as AuthMode, config_CORE_PROVIDERS as CORE_PROVIDERS, type config_CommitMode as CommitMode, type config_CoreConfig as CoreConfig, config_DEFAULT_SETTINGS as DEFAULT_SETTINGS, type config_GithubSettings as GithubSettings, type config_ModelSettings as ModelSettings, type config_OutputSettings as OutputSettings, config_PROVIDER_BASE_URLS as PROVIDER_BASE_URLS, type config_PRSettings as PRSettings, type config_Problem as Problem, type config_Provider as Provider, type config_RepoSettings as RepoSettings, type config_ScheduleSettings as ScheduleSettings, type config_Settings as Settings, type config_Since as Since, type config_TrendingSettings as TrendingSettings, config_effectiveBaseURL as effectiveBaseURL, config_isValidTimezone as isValidTimezone, config_normalizeSettings as normalizeSettings, config_toCoreConfig as toCoreConfig, config_toYaml as toYaml, config_validateSettings as validateSettings };
+  export { type config_AuthMode as AuthMode, config_CORE_PROVIDERS as CORE_PROVIDERS, type config_CommitMode as CommitMode, type config_CoreConfig as CoreConfig, config_DEFAULT_SETTINGS as DEFAULT_SETTINGS, type config_GithubSettings as GithubSettings, type config_ModelSettings as ModelSettings, type config_OutputSettings as OutputSettings, config_PROVIDER_BASE_URLS as PROVIDER_BASE_URLS, type config_PRSettings as PRSettings, type config_Problem as Problem, type config_Provider as Provider, type config_RepoSettings as RepoSettings, config_SETTINGS_SECTIONS as SETTINGS_SECTIONS, type config_ScheduleSettings as ScheduleSettings, type config_Settings as Settings, type config_SettingsSection as SettingsSection, type config_Since as Since, type config_TrendingSettings as TrendingSettings, config_effectiveBaseURL as effectiveBaseURL, config_isValidTimezone as isValidTimezone, config_mergeSettingsSection as mergeSettingsSection, config_normalizeSettings as normalizeSettings, config_sectionOfField as sectionOfField, config_toCoreConfig as toCoreConfig, config_toYaml as toYaml, config_validateSettings as validateSettings };
 }
 
 declare const PLUGIN_DIR_NAME = "github-trending";
@@ -385,11 +355,30 @@ declare namespace paths {
 }
 
 declare const HISTORY_LIMIT = 30;
+/** 预览副本上限：最多保留 30 份，和 history 的 30 天窗口对齐。 */
+declare const PREVIEW_LIMIT = 30;
+/** 一次预览只读这么多字节；超过的不复制，避免把大文件塞进状态目录。 */
+declare const PREVIEW_MAX_BYTES: number;
+/** 契约 v2 的固定内容哈希算法；旧版状态没有这个字段，据此识别 legacy。 */
+declare const CONTENT_HASH_ALGO_V2 = "jcs-sha256-v1";
 interface DigestIdentity {
     date: string;
     contentHash: string;
+    /** 产出该 hash 的算法；v2 新写的一律是 jcs-sha256-v1。 */
+    contentHashAlgo: string;
     coreVersion: string;
 }
+/**
+ * 预览副本的元数据：只记「哪份文件、多大、内容 sha256」，正文进 previews/。
+ * `file` 是仓库内相对路径，不落绝对路径（避免把用户目录写进状态）。
+ */
+interface PreviewMeta {
+    file: string;
+    bytes: number;
+    sha256: string;
+    /** 只读接口截断时为 true；当前 512 KB 上限下正常不会出现。 */
+    truncated?: boolean;
+}
 interface RunRecord {
     id: string;
     at: string;
@@ -399,12 +388,19 @@ interface RunRecord {
     /** `null` 表示没有错误。 */
     errorCode?: string;
     errorMessage?: string;
+    /** push 等失败的机器可判定原因（stale-lease / non-fast-forward / auth ...）。 */
+    errorReason?: string;
+    /** 跳过原因：merged / pr-closed / unchanged。 */
+    skipReason?: string;
     durationMs: number;
     files: number;
+    /** 运行所属的调度时区日期（YYYY-MM-DD）；旧记录可能没有。 */
+    date?: string;
     contentHash?: string;
     branch?: string;
     commit?: string;
     prUrl?: string;
+    preview?: PreviewMeta;
     coreVersion: string;
     model: {
         provider: string;
@@ -413,13 +409,19 @@ interface RunRecord {
     languages: string[];
     warnings: string[];
     logFile?: string;
+    /** true = 契约 v1 时代留下的旧记录（contentHash 算法不同，不可与 v2 比较）。 */
+    legacy?: boolean;
 }
 interface PendingPr {
     url: string;
     createdAt: string;
+    /** 该 PR 对应的 digest 日期（YYYY-MM-DD）；用于判断「同日重跑」是否真的会撞分支。 */
+    date?: string;
 }
 interface PluginState {
     lastRunAt?: string;
+    /** 最近一次成功（ok=true，含 skipped）的运行时间；调度用它锁当天。 */
+    lastSuccessAt?: string;
     lastDigest?: DigestIdentity;
     lastResult?: RunRecord;
     pendingPr?: PendingPr;
@@ -427,6 +429,12 @@ interface PluginState {
 interface HistoryFile {
     records: RunRecord[];
 }
+interface LegacyMigrationResult {
+    stateChanged: boolean;
+    clearedDigest: boolean;
+    clearedPendingPr: boolean;
+    historyMarked: number;
+}
 /** 原子写：同目录临时文件写完再 rename，权限 0600。 */
 declare function writeJsonAtomic(file: string, value: unknown): void;
 interface StoreOptions {
@@ -442,26 +450,50 @@ declare class Store {
     get statePath(): string;
     get historyPath(): string;
     get logsPath(): string;
+    get previewsPath(): string;
     readSettings(): Settings;
     writeSettings(settings: Settings): void;
     readState(): PluginState;
     writeState(state: PluginState): void;
+    /**
+     * 把 v1 时代遗留的 state / history 一次性清洗落盘：清掉不可信的 lastDigest 与
+     * 与之绑定的 pendingPr，并给旧历史记录打 legacy 标。插件启动时调用一次。
+     */
+    migrateLegacyState(): LegacyMigrationResult;
     readHistory(): RunRecord[];
+    /** 原始历史（不做 legacy 标注）：写入路径用它，避免把「读时标注」持久化。 */
+    private readHistoryRaw;
     /** 记录一次运行：历史裁剪到 30 条，state 同步更新。 */
     recordRun(record: RunRecord, next?: Partial<PluginState>): void;
     newLogPath(id: string): string;
     appendLog(file: string, line: string): void;
     hasLog(file: string): boolean;
     readLog(file: string, maxBytes?: number): string;
+    /** 预览副本路径；写入前才建目录，读接口不会凭空创建目录。 */
+    previewPath(id: string): string;
+    /** 写预览副本：同目录临时文件 + rename、0600；写完裁到 30 份。 */
+    writePreview(id: string, text: string): void;
+    /** 读预览副本；不存在/不可读返回 undefined，超过上限时截断。 */
+    readPreview(id: string, maxBytes?: number): {
+        text: string;
+        truncated: boolean;
+    } | undefined;
+    /** 只保留最近 `keep` 份预览副本；按 mtime 倒序，任何错误都忽略。 */
+    prunePreviews(keep?: number): void;
 }
 /** 运行 id：时间前缀便于按时间排序，随机后缀避免同毫秒撞车。 */
 declare function newRunId(now?: Date): string;
 
+declare const state_CONTENT_HASH_ALGO_V2: typeof CONTENT_HASH_ALGO_V2;
 type state_DigestIdentity = DigestIdentity;
 declare const state_HISTORY_LIMIT: typeof HISTORY_LIMIT;
 type state_HistoryFile = HistoryFile;
+type state_LegacyMigrationResult = LegacyMigrationResult;
+declare const state_PREVIEW_LIMIT: typeof PREVIEW_LIMIT;
+declare const state_PREVIEW_MAX_BYTES: typeof PREVIEW_MAX_BYTES;
 type state_PendingPr = PendingPr;
 type state_PluginState = PluginState;
+type state_PreviewMeta = PreviewMeta;
 type state_RunRecord = RunRecord;
 type state_Store = Store;
 declare const state_Store: typeof Store;
@@ -469,7 +501,7 @@ type state_StoreOptions = StoreOptions;
 declare const state_newRunId: typeof newRunId;
 declare const state_writeJsonAtomic: typeof writeJsonAtomic;
 declare namespace state {
-  export { type state_DigestIdentity as DigestIdentity, state_HISTORY_LIMIT as HISTORY_LIMIT, type state_HistoryFile as HistoryFile, type state_PendingPr as PendingPr, type state_PluginState as PluginState, type state_RunRecord as RunRecord, state_Store as Store, type state_StoreOptions as StoreOptions, state_newRunId as newRunId, state_writeJsonAtomic as writeJsonAtomic };
+  export { state_CONTENT_HASH_ALGO_V2 as CONTENT_HASH_ALGO_V2, type state_DigestIdentity as DigestIdentity, state_HISTORY_LIMIT as HISTORY_LIMIT, type state_HistoryFile as HistoryFile, type state_LegacyMigrationResult as LegacyMigrationResult, state_PREVIEW_LIMIT as PREVIEW_LIMIT, state_PREVIEW_MAX_BYTES as PREVIEW_MAX_BYTES, type state_PendingPr as PendingPr, type state_PluginState as PluginState, type state_PreviewMeta as PreviewMeta, type state_RunRecord as RunRecord, state_Store as Store, type state_StoreOptions as StoreOptions, state_newRunId as newRunId, state_writeJsonAtomic as writeJsonAtomic };
 }
 
 interface CoreRelease {
@@ -489,7 +521,7 @@ interface ReleaseDescriptor extends CoreRelease {
     binaryPath: string;
     cached: boolean;
 }
-/** 从本包的 package.json 读核心版本（`sync-contract --ref vX` 会同时更新它）。 */
+/** 从本包的 package.json 读核心版本（`scripts/set-core-version.mjs` 会更新它）。 */
 declare function readCoreRelease(pkg?: {
     dsh?: {
         core?: {
@@ -697,6 +729,8 @@ interface RunCoreOptions {
     token?: string;
     date?: string;
     dryRun: boolean;
+    /** 谁触发的运行：核心用它在定时运行时尊重「人工关闭的 PR」。 */
+    trigger?: 'manual' | 'schedule';
     /** 回环代理地址：覆盖配置里的 model.baseURL（代理模式专用）。 */
     baseURLOverride?: string;
     signal?: AbortSignal;
@@ -820,10 +854,11 @@ interface CredentialServices {
 declare function credentialServices(get: (name: string) => unknown): CredentialServices | undefined;
 declare function describeRef(services: CredentialServices | undefined, ref: string, env?: NodeJS.ProcessEnv): Promise<CredentialDescription>;
 declare function resolveRef(services: CredentialServices | undefined, ref: string, env?: NodeJS.ProcessEnv): Promise<ResolvedSecret>;
-/** GitHub token：按 authMode 取，`gh` 模式读本机 gh 的登录态。 */
-declare function resolveGithubToken(services: CredentialServices | undefined, authMode: 'device' | 'pat' | 'gh', tokenRef: string, deps?: {
+/** GitHub token：按 authMode 取，`gh` 模式读本机 gh 的登录态，`pat` 读凭据/环境变量。 */
+declare function resolveGithubToken(services: CredentialServices | undefined, authMode: 'pat' | 'gh', tokenRef: string, deps?: {
     env?: NodeJS.ProcessEnv;
     execGh?: () => Promise<string | undefined>;
+    freshGh?: boolean;
 }): Promise<{
     token?: string;
     source: string;
@@ -840,6 +875,57 @@ declare namespace credentials {
   export { type credentials_CredentialDescription as CredentialDescription, type credentials_CredentialServices as CredentialServices, type credentials_ResolvedSecret as ResolvedSecret, credentials_credentialServices as credentialServices, credentials_describeRef as describeRef, credentials_resolveGithubToken as resolveGithubToken, credentials_resolveRef as resolveRef };
 }
 
+/**
+ * GitHub 认证探测：供设置页「测试认证」按钮调用。
+ *
+ * 只做一次 `GET https://api.github.com/user`，把「有没有 token、token 是否有效」
+ * 一次性验证清楚并回显登录账号；token 不进日志、不进响应明文。
+ */
+
+interface GithubProbeResult {
+    ok: boolean;
+    login?: string;
+    /** token 来源（gh / env / credentials）。 */
+    source?: string;
+    code?: string;
+    message?: string;
+}
+declare function probeGithubAuth(options: {
+    credentials: CredentialServices | undefined;
+    authMode: 'pat' | 'gh';
+    tokenRef: string;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+}): Promise<GithubProbeResult>;
+
+type github_GithubProbeResult = GithubProbeResult;
+declare const github_probeGithubAuth: typeof probeGithubAuth;
+declare namespace github {
+  export { type github_GithubProbeResult as GithubProbeResult, github_probeGithubAuth as probeGithubAuth };
+}
+
+interface DefaultBranchResult {
+    branch?: string;
+    /** `origin-head` = 远端默认分支；`head` = 本地当前分支兜底；`none` = 读不到。 */
+    source: 'origin-head' | 'head' | 'none';
+    message?: string;
+}
+/**
+ * 读取仓库默认分支：
+ *   1. `refs/remotes/origin/HEAD` → 远端默认分支（最准确）；
+ *   2. 回退到本地当前分支 `HEAD`（空仓库/未 fetch 时仍能给个值）；
+ *   3. 都失败返回 `none`，由界面提示。
+ */
+declare function readDefaultBranch(repoPath: string, options?: {
+    env?: NodeJS.ProcessEnv;
+}): Promise<DefaultBranchResult>;
+
+type repo_DefaultBranchResult = DefaultBranchResult;
+declare const repo_readDefaultBranch: typeof readDefaultBranch;
+declare namespace repo {
+  export { type repo_DefaultBranchResult as DefaultBranchResult, repo_readDefaultBranch as readDefaultBranch };
+}
+
 /**
  * 从宿主的 provider 目录快速填充模型配置（FR-P-03 / AC-P-03）。
  *
@@ -910,6 +996,18 @@ interface CandidateOptions {
     env?: NodeJS.ProcessEnv;
 }
 declare function listProviderCandidates(options: CandidateOptions): Promise<LlmProviderCandidate[]>;
+/** 宿主当前的默认模型选择（`ctx.agentDefaultModel`）；没有该服务或读取失败时返回 undefined。 */
+interface DefaultSelection {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+declare function readDefaultSelection(get: (name: string) => unknown): DefaultSelection | undefined;
+/**
+ * 把「DSH 默认模型」落成模型设置：能匹配到已生效路由就复用其认证形态，
+ * 否则按代理模式（hostProvider = 该路由 id）交给宿主转发。
+ */
+declare function applyDefaultSelection(settings: Settings, selection: DefaultSelection, candidate?: LlmProviderCandidate): Settings;
 /**
  * 把候选落成模型设置。`mode: 'proxy'` 时清空 baseURL 与 apiKeyRef——
  * 端点由插件在运行时注入回环代理地址，留存旧值只会误导。
@@ -923,17 +1021,20 @@ declare function resolveModelKey(settings: Settings, credentials: CredentialServ
 }>;
 
 type quickfill_CandidateOptions = CandidateOptions;
+type quickfill_DefaultSelection = DefaultSelection;
 type quickfill_LlmModelCandidate = LlmModelCandidate;
 type quickfill_LlmProviderCandidate = LlmProviderCandidate;
 type quickfill_LlmServices = LlmServices;
 declare const quickfill_applyCandidate: typeof applyCandidate;
+declare const quickfill_applyDefaultSelection: typeof applyDefaultSelection;
 declare const quickfill_coreProviderFor: typeof coreProviderFor;
 declare const quickfill_credentialServices: typeof credentialServices;
 declare const quickfill_listProviderCandidates: typeof listProviderCandidates;
 declare const quickfill_llmServices: typeof llmServices;
+declare const quickfill_readDefaultSelection: typeof readDefaultSelection;
 declare const quickfill_resolveModelKey: typeof resolveModelKey;
 declare namespace quickfill {
-  export { type quickfill_CandidateOptions as CandidateOptions, type quickfill_LlmModelCandidate as LlmModelCandidate, type quickfill_LlmProviderCandidate as LlmProviderCandidate, type quickfill_LlmServices as LlmServices, quickfill_applyCandidate as applyCandidate, quickfill_coreProviderFor as coreProviderFor, quickfill_credentialServices as credentialServices, quickfill_listProviderCandidates as listProviderCandidates, quickfill_llmServices as llmServices, quickfill_resolveModelKey as resolveModelKey };
+  export { type quickfill_CandidateOptions as CandidateOptions, type quickfill_DefaultSelection as DefaultSelection, type quickfill_LlmModelCandidate as LlmModelCandidate, type quickfill_LlmProviderCandidate as LlmProviderCandidate, type quickfill_LlmServices as LlmServices, quickfill_applyCandidate as applyCandidate, quickfill_applyDefaultSelection as applyDefaultSelection, quickfill_coreProviderFor as coreProviderFor, quickfill_credentialServices as credentialServices, quickfill_listProviderCandidates as listProviderCandidates, quickfill_llmServices as llmServices, quickfill_readDefaultSelection as readDefaultSelection, quickfill_resolveModelKey as resolveModelKey };
 }
 
 /**
@@ -1026,6 +1127,59 @@ declare namespace proxy {
   export { type proxy_LlmLike as LlmLike, type proxy_ProxyHandle as ProxyHandle, type proxy_ProxyOptions as ProxyOptions, proxy_foldMessages as foldMessages, proxy_startProxy as startProxy };
 }
 
+/**
+ * 未合并 PR 的「对账」：把 `state.pendingPr` 和 GitHub 上的真实状态对齐。
+ *
+ * 背景：插件把「上次成功创建的 PR」记在 `pendingPr`，但它不会感知这个 PR 之后
+ * 在 GitHub 上被**合并或关闭**——于是界面/工具会一直显示「未合并」，而且在同日
+ * 重跑时给出误导性的判断。这里做一次只读核对（GET /pulls/{n}）：
+ *
+ *   - open    → 仍是未合并 PR，保留；
+ *   - merged  → 已完成，清掉陈旧记录；
+ *   - closed  → 已放弃，清掉陈旧记录；
+ *   - unknown → 无 token / 解析失败 / 网络异常，先不动（下次再试）。
+ *
+ * 只读、可注入 `fetchImpl`，并对同一 URL 做 60 s 缓存，避免 `/state` 5 s 轮询
+ * 每次都打 GitHub。任何失败都降级为 `unknown`，绝不让对账影响主流程。
+ */
+type PullState = 'open' | 'closed' | 'merged' | 'unknown';
+interface PendingPrStatus {
+    state: PullState;
+    url: string;
+    number?: number;
+    title?: string;
+    reason?: string;
+}
+interface ParsedPullUrl {
+    owner: string;
+    repo: string;
+    number: number;
+}
+/** 只认标准的 `https://github.com/<owner>/<repo>/pull/<n>` 形态。 */
+declare function parsePullUrl(url: string): ParsedPullUrl | undefined;
+/** 清空缓存（测试与「强制刷新」用）。 */
+declare function clearPendingPrCache(): void;
+interface CheckPendingPrOptions {
+    url: string;
+    token?: string;
+    fetchImpl?: typeof fetch;
+    now?: number;
+    /** false = 跳过缓存，强制请求。 */
+    cache?: boolean;
+}
+declare function checkPendingPr(options: CheckPendingPrOptions): Promise<PendingPrStatus>;
+
+type pendingPr_CheckPendingPrOptions = CheckPendingPrOptions;
+type pendingPr_ParsedPullUrl = ParsedPullUrl;
+type pendingPr_PendingPrStatus = PendingPrStatus;
+type pendingPr_PullState = PullState;
+declare const pendingPr_checkPendingPr: typeof checkPendingPr;
+declare const pendingPr_clearPendingPrCache: typeof clearPendingPrCache;
+declare const pendingPr_parsePullUrl: typeof parsePullUrl;
+declare namespace pendingPr {
+  export { type pendingPr_CheckPendingPrOptions as CheckPendingPrOptions, type pendingPr_ParsedPullUrl as ParsedPullUrl, type pendingPr_PendingPrStatus as PendingPrStatus, type pendingPr_PullState as PullState, pendingPr_checkPendingPr as checkPendingPr, pendingPr_clearPendingPrCache as clearPendingPrCache, pendingPr_parsePullUrl as parsePullUrl };
+}
+
 interface RunSummary {
     id: string;
     ok: boolean;
@@ -1037,7 +1191,11 @@ interface RunSummary {
     files: number;
     contentHash?: string;
     branch?: string;
+    commit?: string;
     prUrl?: string;
+    preview?: PreviewMeta;
+    /** 核心给出的跳过原因（merged / pr-closed / unchanged）。 */
+    skipReason?: string;
     error?: {
         code: string;
         message: string;
@@ -1045,6 +1203,8 @@ interface RunSummary {
         area: string;
         retriable: boolean;
         inferred?: boolean;
+        /** 机器可判定的细分原因（push 失败时由核心给出）。 */
+        reason?: string;
     };
     warnings: string[];
     logFile?: string;
@@ -1065,6 +1225,8 @@ interface RunnerDeps {
     env?: NodeJS.ProcessEnv;
     /** 运行结束（成功或失败）后回调，用于刷新调度/界面缓存。 */
     onFinished?: (summary: RunSummary) => void;
+    /** 预览副本这类「可失败但不阻断运行」的事件走这里，不写进 warnings。 */
+    logger?: (event: string, data?: Record<string, unknown>) => void;
 }
 declare class Runner {
     private active;
@@ -1078,6 +1240,15 @@ declare class Runner {
     run(options: RunRequestOptions): Promise<RunSummary>;
     private summarize;
     private failureSummary;
+    /**
+     * 从本次核心返回的 artifact 清单里选当天的 `.md`，只读复制到 previews/。
+     *
+     * 这是插件**唯一**读取用户仓库的场景，而且只读核心自己刚写出的那一份：
+     * - 路径必须在 `repo.path` 内（词法 + realpath 各判一次，挡 `..`/绝对路径/符号链接）；
+     * - 上限 512 KB、拒绝 NUL、sha256 必须与契约声明一致；
+     * - 任何一步失败都只记日志，返回 undefined；运行结果不受影响。
+     */
+    private capturePreview;
     /** 写历史与状态；同一天的 skipped 运行不覆盖 lastDigest。 */
     private record;
     /** 给设置页/工具用的「核心现在什么状态」。 */
@@ -1093,6 +1264,22 @@ declare namespace runner {
   export { type runner_RunRequestOptions as RunRequestOptions, type runner_RunSummary as RunSummary, runner_Runner as Runner, type runner_RunnerDeps as RunnerDeps };
 }
 
+interface PluginInfo {
+    name: string;
+    version: string;
+    repository?: string;
+}
+/** 只放行 GitHub 的 http(s) 地址；ssh / git+ 前缀先归一化。 */
+declare function normalizeRepositoryUrl(value: unknown): string | undefined;
+declare function readPluginInfo(): PluginInfo;
+
+type pluginInfo_PluginInfo = PluginInfo;
+declare const pluginInfo_normalizeRepositoryUrl: typeof normalizeRepositoryUrl;
+declare const pluginInfo_readPluginInfo: typeof readPluginInfo;
+declare namespace pluginInfo {
+  export { type pluginInfo_PluginInfo as PluginInfo, pluginInfo_normalizeRepositoryUrl as normalizeRepositoryUrl, pluginInfo_readPluginInfo as readPluginInfo };
+}
+
 /**
  * 调度（FR-P-08 / 规格 §9）。
  *
@@ -1136,7 +1323,8 @@ declare class Scheduler {
     private readonly deps;
     private timerHandle;
     private stopped;
-    private lastFiredFor;
+    /** 当天已尝试次数与时间；只在内存里，进程重启后重新计数。 */
+    private readonly attempts;
     constructor(deps: SchedulerDeps);
     start(): void;
     stop(): void;
@@ -1186,7 +1374,12 @@ interface RouteDeps {
     scheduler: Scheduler;
     get: (name: string) => unknown;
     env?: NodeJS.ProcessEnv;
+    /** 注入用：pendingPr 对账的 fetch 实现（测试不联网）。 */
+    fetchImpl?: typeof fetch;
     version: string;
+    /** 包名与仓库地址都来自 package.json，由 src/index.ts 传入。 */
+    pluginName?: string;
+    repository?: string;
     logger?: (event: string, data?: Record<string, unknown>) => void;
 }
 declare function createRoutes(deps: RouteDeps): (request: http.IncomingMessage, response: http.ServerResponse) => Promise<void>;
@@ -1440,4 +1633,4 @@ declare namespace tools {
   export { tools_createTrendingHistoryTool as createTrendingHistoryTool, tools_createTrendingRunTool as createTrendingRunTool };
 }
 
-export { channel, config, core, credentials, errors, exec, handshake$1 as handshake, importCli, ipc, locate, paths, preflight, proxy, quickfill, release, routes, run, runner, schedule, state, tools };
+export { channel, config, core, credentials, errors, exec, github, handshake$1 as handshake, importCli, ipc, locate, paths, pendingPr, pluginInfo, preflight, proxy, quickfill, release, repo, routes, run, runner, schedule, state, tools };