@dependfix/engine 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -1,8 +1,7 @@
-import { i as FromPatParams, n as AuthProviderOptions, r as FromAppParams, t as AuthProvider } from "./auth-provider.mjs";
+import { c as FromAppParams, l as FromPatParams, o as AuthProvider, s as AuthProviderOptions } from "./chunks/index.mjs";
 import { Octokit } from "@octokit/rest";
-import { AlertClass, AlertSeverity, AlertSourceKind, AppError, FixAction, FixError, Logger, NormalizedSecurityAlert, RepositoryResult, RunResult, RunSummary, SeverityThreshold, createEmptyRunSummary } from "@dependfix/core";
+import { AlertClass, AlertFixOutcome, AlertSeverity, AlertSourceKind, AlertsDisabledRecord, AppError, BaselineRedDelivery, CheckAttribution, CheckConclusion, CiAlignmentRecord, CiAlignmentStatus, CiDefaultBranchHealth, CiMirrorSkipped, CiWorkflowEvidence, DeliverySkipRecord, FixAction, FixError, Logger, NormalizedSecurityAlert, PrCheckFailureSummary, PrCheckWatchReport, PrCheckWatchState, RepeatedAttemptRecord, RepositoryResult, RunResult, RunSummary, SeverityThreshold, VerifyCommandCategory, createEmptyRunSummary } from "@dependfix/core";
 import { z } from "zod";
-//#region src/github/client.d.ts
 export interface RetryPolicyOptions {
   /** 最大重试次数（默认 3；0 = 不重试） */
   maxRetries?: number;
@@ -30,7 +29,7 @@ export interface OctokitClientOptions {
    *
    * 保留作为低层入口；`token` 路径与 `auth: fromPat(token)` 行为等价
    * （共享同一 retry policy 与限流重试 hook）。
-   * 计划在 M19+ 评估移除。
+   * 计划在后续阶段评估移除。
    */
   token?: string;
   /**
@@ -62,7 +61,7 @@ export interface OctokitClientOptions {
  *
  * @example
  * ```typescript
- * // 推荐：使用 auth 抽象层（M18.1 实施后）
+ * // 推荐：使用 auth 抽象层（已实施）
  * import { fromPat } from '@dependfix/engine/auth'
  * const octokit = createGitHubClient({ auth: fromPat('ghp_xxxx') })
  *
@@ -100,8 +99,277 @@ export declare function createGitHubClient(options: OctokitClientOptions): Octok
  * - 其他状态码
  */
 export declare function computeRetryDelayMs(error: unknown, attempt: number, baseDelayMs?: number, maxBackoffMs?: number): number | null;
-//#endregion
-//#region src/github/code-quality-fetcher.d.ts
+/** 修复策略（尝试键的策略维度；策略变化即视为不同尝试）。 */
+export type PlanStrategy = 'direct-upgrade' | 'override' | 'member-upgrade' | 'family-lockstep';
+/** 尝试键输入。 */
+export interface AttemptKeyInput {
+  /** 告警源（dependabot / pnpm-audit；Code Scanning / Code Quality 不参与尝试计数） */
+  source: string;
+  /** 包名（同一告警族的稳定标识） */
+  packageName: string;
+  /** 目标版本（本次修复计划的推荐版本） */
+  targetVersion: string;
+  /** 修复策略（见 PlanStrategy） */
+  planStrategy: PlanStrategy;
+}
+/** 尝试键长度（hex 字符数）。 */
+export declare const ATTEMPT_KEY_LENGTH = 16;
+/** 失败签名归一化输入上限（字符数；失败命令 + 错误文本各截断到该长度）。 */
+export declare const FAILURE_SIGNATURE_INPUT_LIMIT = 2048;
+/**
+ * 计算同告警尝试键。
+ *
+ * 同一输入恒等；目标版本或修复策略变化 → 键变化（自然失效，不继承尝试计数）。
+ */
+export declare function computeAttemptKey(input: AttemptKeyInput): string;
+/**
+ * 计算 CI 失败签名（8 位 hex）。
+ *
+ * 归一化：命令与错误文本各自折叠空白 + 截断到 2KB，再取 sha256 前 8 位。
+ * 签名只增强证据（失败是否同因），**不改变尝试计数口径**。
+ */
+export declare function computeFailureSignature(command: string, error: string): string;
+/** PR 正文里的尝试标记（一个 PR 可携带多条：一次修复通常覆盖多条告警）。 */
+export interface AttemptMarker {
+  /** 尝试键（16 位 hex） */
+  key: string;
+  /** 尝试序号（1 起） */
+  n: number;
+  /** CI 失败签名（可选；仅回写阶段存在） */
+  failureSignature?: string;
+  /** CI 结果（`0` 成功 / `1` 失败；缺省 = 未知） */
+  failed?: 0 | 1;
+}
+/**
+ * 生成尝试标记（HTML 注释，渲染后不可见；置于正文头部以避免尾部截断丢失）。
+ *
+ * `n` 由调用方按「同键已关闭 PR 数 + 1」给出；解析侧只接受 1-9999（查询窗口 50 条 ⇒ 实际上界 51），
+ * 超出会被丢弃（fail-open）。
+ */
+export declare function formatAttemptMarker(marker: AttemptMarker): string;
+/**
+ * 解析 PR 正文中的尝试标记（支持多条）。
+ *
+ * 容错口径：键格式非法 / 序数非正整数（仅接受 1-9999 的十进制）/ 签名或结果格式非法 →
+ * 丢弃该条（fail-open）。同一标记内重复属性按 **last-wins**（后写覆盖）。
+ */
+export declare function parseAttemptMarkers(body: string | null | undefined): AttemptMarker[];
+/**
+ * 把本次运行的尝试记录折算为 PR 标记。
+ *
+ * - 跳过（`skipped`）不写标记：该告警本次未进入修复，写入会虚增后续计数
+ * - 传入 `executed`（本次实际产出的动作）时，只写「确实执行过」的键：pristine 安装基线失败 /
+ *   验证门禁回滚 / 无交付物等分支下，计划阶段已记录的键不会被执行，写标记会白白消耗一次额度
+ * - 同键去重取最大序号（多仓 / 同包多 GHSA 会产出重复键）
+ */
+export declare function collectAttemptMarkers(records: readonly RepeatedAttemptRecord[], executed?: ReadonlyArray<Pick<FixAction, 'type' | 'repository' | 'target' | 'noOp'>>): AttemptMarker[];
+/** 默认查询条数（设计稿 §6.2：最近 50 条关闭 PR）。 */
+export declare const CLOSED_ATTEMPT_QUERY_LIMIT = 50;
+/** 一条已关闭的 dependfix PR（仅保留尝试计数所需字段）。 */
+export interface ClosedAttemptPR {
+  number: number;
+  /** PR 链接（证据 / 后续报告展示用） */
+  htmlUrl: string;
+  /** head 分支名（后续 PR 创建后 CI 回环按分支定位 PR 时使用） */
+  headRef: string;
+  markers: AttemptMarker[];
+}
+export interface ClosedAttemptIndexOptions {
+  /** 单仓库查询条数（默认 `CLOSED_ATTEMPT_QUERY_LIMIT`；仅用于测试与调优） */
+  limit?: number;
+  /** 失败告警输出（缺省静默；由调用方决定是否可见） */
+  logger?: Pick<Logger, 'warn'>;
+}
+/**
+ * 运行级「已关闭 PR 尝试索引」。
+ *
+ * 缓存按 `owner/repo` 存 **Promise**：同仓库并发告警共享同一次请求（也缓存失败结果，
+ * 避免一次限流把后续每条告警都变成一次重试）。
+ */
+export declare class ClosedAttemptIndex {
+  private readonly cache;
+  private readonly limit;
+  private readonly logger?;
+  constructor(options?: ClosedAttemptIndexOptions);
+  /** 读取仓库最近关闭的 dependfix PR（运行级缓存；失败返回空数组）。 */
+  closedPRs(octokit: Octokit, owner: string, repo: string): Promise<ClosedAttemptPR[]>;
+  /** 同键已关闭（未合并）PR 数。 */
+  closedAttemptCount(octokit: Octokit, owner: string, repo: string, key: string): Promise<number>;
+  private load;
+}
+/** 单次解析的文件数上限（防超大仓库 / 恶意仓库拖慢运行）。 */
+export declare const MAX_WORKFLOW_FILES = 20;
+/** 单文件字节上限（超出按「未能读取」降级，不解析半截 YAML）。 */
+export declare const MAX_WORKFLOW_BYTES: number;
+/** 默认分支健康预检的 workflow 数上限（每个一次 API 调用，控制配额）。 */
+export declare const CI_HEALTH_MAX_WORKFLOWS = 3;
+/** 单次健康预检的请求超时（限流重试也被 signal 约束，避免拖住交付）。 */
+export declare const CI_HEALTH_TIMEOUT_MS = 5000;
+/** 单个 workflow 保留的结构化命令片段上限（仅镜像计划需要；超出即整体降级，不截断执行源）。 */
+export declare const MAX_RUN_FRAGMENTS = 2000;
+type FragmentClassification = {
+  kind: 'category';
+  category: VerifyCommandCategory;
+} | {
+  kind: 'install';
+} | {
+  kind: 'ignore';
+} | {
+  kind: 'unrecognized';
+  command: string;
+};
+/** 识别单个命令片段（导出以便单测锁定口径）。 */
+export declare function classifyCommandFragment(fragment: string): FragmentClassification;
+/** workflow 解析结果（失败时给出可渲染的原因，不抛错）。 */
+export type WorkflowParseResult = {
+  ok: true;
+  evidence: CiWorkflowEvidence;
+  runFragments: CiRunFragment[];
+  /** 片段数超上限（仅在收集时可能出现）：调用方须整体降级，不得用截断后的片段做执行计划 */
+  runFragmentsTruncated?: boolean;
+} | {
+  ok: false;
+  reason: string;
+};
+/** 结构化命令片段的收集选项（默认不收集：口径比对不需要执行源，避免大幅工作流占用内存）。 */
+export interface RunFragmentOptions {
+  collectRunFragments?: boolean;
+  maxRunFragments?: number;
+}
+/**
+ * 结构化命令片段（执行源，**原始命令未截断**）。
+ *
+ * 与 `CiWorkflowEvidence.unrecognized` 的分工：后者是 PR 正文展示用途（截断 120 字符、
+ * 反引号替换、每文件上限 5 条），不能作为执行源；本结构保留全部片段与所属 workflow。
+ *
+ * - `recognized`：默认链已覆盖的语义项（lint / build / typecheck / test）与 install
+ * - `unrecognized`：其余可执行片段（未知脚本、`docker` / `gh` / 任意 shell、包管理器非脚本子命令）
+ */
+export interface CiRunFragment {
+  command: string;
+  kind: 'recognized' | 'unrecognized';
+  workflow: string;
+}
+/**
+ * 解析单个 workflow 文件：只读 `jobs.*.steps[].run`，产出语义项与未识别命令。
+ *
+ * 非 GitHub Actions（缺少 `jobs` 映射）与非法 YAML 均返回失败结果，
+ * 由调用方降级为「未能读取 CI 配置」。
+ */
+export declare function parseWorkflowCommands(path: string, content: string, options?: RunFragmentOptions): WorkflowParseResult;
+/** workflow 文件源（相对路径 + 文本）。 */
+export interface WorkflowSource {
+  path: string;
+  content: string;
+}
+/** 读取结果：失败时给出可渲染原因（无目录 / 无文件 / 读取失败 / 超限）。 */
+export type WorkflowSourceResult = {
+  ok: true;
+  sources: WorkflowSource[];
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * 读取工作目录下 `.github/workflows/*.yml|yaml`（只读、有界）。
+ *
+ * 读取的是**工作区检出**的内容（引擎在默认分支检出上修复，修复链不改 workflow），
+ * 因此等价于「默认分支的 CI 配置」；多仓共享同一工作目录时的粒度局限见设计文档。
+ */
+export declare function readWorkflowSources(workDir: string): WorkflowSourceResult;
+/** 单次运行最多镜像执行的脚本条数（执行成本受控；超限部分记 `over-limit` 披露）。 */
+export declare const MAX_MIRROR_COMMANDS = 3;
+/** CI 脚本镜像计划（纯计算，不执行）。 */
+export interface CiMirrorPlan {
+  /** 可执行命令（规范化为 `<包管理器> run <script>`，按 workflow 顺序去重，≤ maxCommands） */
+  runnable: string[];
+  /** 被跳过的片段与原因（已按命令 + 原因去重） */
+  skipped: CiMirrorSkipped[];
+  /** workflow 无法读取 / 解析失败的原因（此时不做任何镜像） */
+  unreadableReason?: string;
+}
+/**
+ * 计算 CI 脚本镜像计划：读取 workflow → 结构化片段 → 归一化 → 脚本存在性校验 → 去重 / 上限。
+ *
+ * 只消费 `kind === 'unrecognized'` 的片段（默认链已覆盖的语义项与 install 不重复执行）；
+ * 不能归一化为受支持脚本形态的片段、脚本不存在的片段分别记 `unsupported-command` /
+ * `script-not-found`，超出上限的可执行候选记 `over-limit`——全部披露，不静默丢弃。
+ *
+ * 本函数不执行任何命令；执行、超时、取消与基线归因由验证链统一承担。
+ */
+export declare function planCiMirrorCommands(workDir: string, options?: {
+  maxCommands?: number;
+}): CiMirrorPlan;
+/** 比对结果（`CiAlignmentRecord` 的可计算子集）。 */
+export interface CiChainComparison {
+  status: CiAlignmentStatus;
+  ciCategories: VerifyCommandCategory[];
+  extraInExecution: VerifyCommandCategory[];
+  missingInExecution: VerifyCommandCategory[];
+  comparisonNote?: string;
+}
+/**
+ * 比对「本次实际执行的命令集」与「CI 可识别命令类别」。
+ *
+ * 判定口径：
+ * - CI 无可识别类别 → `inconclusive`（不能凭「没识别到」宣称一致）；
+ * - 本次无可识别类别（自定义命令链）→ `inconclusive`（不按类别硬判不一致）；
+ * - CI 有而本次无 → `differs`（口径缺口）；
+ * - 本次有而 CI 无 → `aligned` + `extraInExecution`（本次更严格，披露不判不一致）。
+ */
+export declare function compareVerificationChains(executedCommands: readonly string[], workflows: readonly CiWorkflowEvidence[]): CiChainComparison;
+/** 最小 logger 接口（引擎 Logger 与测试桩均满足）。 */
+export interface CiAlignmentLogger {
+  warn(message: string): void;
+}
+export interface WorkflowHealthParams {
+  client: Pick<Octokit, 'rest'>;
+  owner: string;
+  repo: string;
+  defaultBranch: string;
+  timeoutMs?: number;
+  maxWorkflows?: number;
+  logger?: CiAlignmentLogger;
+}
+/**
+ * 只读「口径比对所依据的 workflow」在默认分支的最近一次运行结论。
+ *
+ * 单次调用 + 请求级超时（限流重试同受 signal 约束）；任一调用失败只记日志并返回
+ * `unavailableReason`，调用方不得据此标注「默认分支失败」。
+ */
+export declare function fetchDefaultBranchWorkflowHealth(workflowPaths: readonly string[], params: WorkflowHealthParams): Promise<{
+  health: CiDefaultBranchHealth[];
+  unavailableReason?: string;
+}>;
+export interface CiAlignmentInput {
+  repository: string;
+  workDir: string;
+  /** 本次实际执行的验证命令（跳过 `package.json` 中不存在的脚本；首失败短路时只含已执行前缀） */
+  commands: string[];
+  /** GitHub 客户端（pnpm-audit / 无 token 时为 null ⇒ 只做本地解析，不做健康预检） */
+  client: Pick<Octokit, 'rest'> | null;
+  /** 默认分支（未知时不发起健康预检） */
+  defaultBranch?: string;
+  logger?: CiAlignmentLogger;
+  healthTimeoutMs?: number;
+  /** 跳过默认分支健康预检（复用上一轮结果时使用） */
+  skipHealth?: boolean;
+  /**
+   * CI 脚本镜像记录（`--mirror-ci-scripts` 开启时提供）。
+   * `mirrored` 只含实际执行的命令；`skipped` 为计划期跳过项。两者均为「披露」，不参与比对判定。
+   */
+  mirror?: {
+    mirrored: string[];
+    skipped: CiMirrorSkipped[];
+  };
+}
+/**
+ * 构建单仓库口径记录：本地解析 → 类别比对 → （可选）默认分支健康预检。
+ *
+ * 本函数不抛错：任何解析 / 网络问题都降级为 `unreadable` / `inconclusive` /
+ * `healthUnavailableReason`，调用方据此记录但不得阻断修复与交付。
+ */
+export declare function buildCiAlignmentRecord(input: CiAlignmentInput): Promise<CiAlignmentRecord>;
 export interface FetchCodeQualityFindingsParams {
   /** 仓库所属组织或用户 */
   owner: string;
@@ -142,8 +410,6 @@ export declare function fetchCodeQualityFindings(client: Octokit, params: FetchC
  * 映射口径与 `mapCodeScanningSeverity` 对齐（避免新源不一致）。
  */
 export declare function mapCodeQualitySeverity(severity: string | null | undefined): AlertSeverity;
-//#endregion
-//#region src/github/code-scanning-fetcher.d.ts
 export interface FetchCodeScanningAlertsParams {
   /** 仓库所属组织或用户 */
   owner: string;
@@ -174,8 +440,115 @@ export interface FetchCodeScanningAlertsParams {
  * @returns 标准化告警列表
  */
 export declare function fetchCodeScanningAlerts(client: Octokit, params: FetchCodeScanningAlertsParams): Promise<NormalizedSecurityAlert[]>;
-//#endregion
-//#region src/github/dependabot-fetcher.d.ts
+/** 提交集合判定失败的两类信号（写入 `FixError.category`）。 */
+export type CommitScopeErrorCode = 'UNEXPECTED_CHANGES' | 'NO_CHANGES';
+export declare class CommitScopeError extends Error {
+  readonly category: CommitScopeErrorCode;
+  readonly paths: readonly string[];
+  constructor(category: CommitScopeErrorCode, message: string, paths?: readonly string[]);
+}
+/** 一条工作区改动（workDir 相对、POSIX 分隔符）。 */
+export interface ChangedPath {
+  path: string;
+  untracked: boolean;
+  deleted: boolean;
+  /** 索引区已有改动（已暂存）：`git commit` 会连带提交，必须纳入提交集合判定 */
+  staged: boolean;
+  /** 未合并冲突（`UU` / `AA` / `DD` 等）：`git add` 会按工作树一侧静默「解决」，必须拒绝 */
+  conflicted: boolean;
+  /** 位于 workDir 之外（workDir 为仓库子目录时）：索引区改动仍会被 commit 带入 */
+  outside: boolean;
+}
+/** 被拒绝的声明路径。 */
+export interface PathRejection {
+  path: string;
+  reason: string;
+}
+/** 提交集合判定结果。 */
+export interface CommitScope {
+  /** 需要暂存的路径（已排序，便于确定性提交） */
+  paths: string[];
+  /** 未声明的已跟踪改动（非空即拒绝提交） */
+  unexpected: string[];
+  /** 生成物 / 未声明的新文件（不提交；仅留痕） */
+  ignored: string[];
+  /** 声明路径不合法（拒绝提交） */
+  rejected: PathRejection[];
+  /** 声明了但工作区没有对应改动（仅留痕，不阻断） */
+  missing: string[];
+  /** 索引区已有的改动（已暂存） */
+  staged: string[];
+  /** 未合并冲突路径 */
+  conflicts: string[];
+}
+/**
+ * 路径是否在白名单内。
+ *
+ * `package.json` 允许任意层级（monorepo 成员 manifest 由成员级修复写盘）；lockfile /
+ * workspace 配置 / `.npmrc` / `.gitignore` 只允许仓库根（引擎不会写嵌套位置的这些文件）。
+ */
+export declare function isCommitWhitelisted(path: string): boolean;
+/** 是否为构建 / 安装生成物（一律不提交，也不触发未声明告警）。 */
+export declare function isGeneratedPath(path: string): boolean;
+/**
+ * 校验并归一化 fixer / AI patch 声明路径。
+ *
+ * 拒绝：绝对路径（含 Windows 盘符）、`..` 段、pathspec magic（`:(` 开头）、控制字符、空路径。
+ * 归一化：`\` → `/`、去掉 `./` 与重复分隔符（Windows 上 `path.relative` 产出 `\`）。
+ */
+export declare function normalizeCommitPath(raw: string): {
+  ok: true;
+  path: string;
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * 列出工作区改动（`git status` 单一事实源）。
+ *
+ * - `--untracked-files=all`：展开未跟踪目录，避免把整目录当一项
+ * - `--no-renames`：重命名拆成「删除 + 新增」，删除因此不会绕过未声明检测
+ * - 输出路径相对**仓库根**：按 `--show-prefix` 折算为 workDir 相对路径（workDir 可为子目录）
+ */
+export declare function listChangedPaths(workDir: string): Promise<ChangedPath[]>;
+/** 从修复动作收集声明路径（仅成功且非 noOp 的动作）。 */
+export declare function collectDeclaredPaths(actions: readonly FixAction[]): string[];
+/** `stageAndCommit` 的可选声明路径。 */
+export interface StageAndCommitOptions {
+  /** fixer / AI patch 声明的相对路径（与固定白名单取并集） */
+  declaredPaths?: readonly string[];
+}
+/** 暂存结果（留痕 / 断言用）。 */
+export interface StageAndCommitResult {
+  /** 实际暂存的路径 */
+  staged: string[];
+  /** 因生成物 / 未跟踪而跳过的路径 */
+  ignored: string[];
+  /** 声明了但工作区没有对应改动 */
+  missing: string[];
+}
+/**
+ * 判定并暂存提交集合。
+ *
+ * 拒绝：非法声明路径 / 未声明的已跟踪改动（`UNEXPECTED_CHANGES`）、空集合（`NO_CHANGES`）、
+ * 索引区越界暂存内容（`UNEXPECTED_CHANGES`）。暂存用 `git add -- <paths>`（分批；`--` 阻断选项解析，
+ * 每条路径加 `:(literal)` 终止通配，文件名含 `*` / `?` / `[` 时也只暂存字面路径）。
+ */
+export declare function stageScopedChanges(workDir: string, declaredPaths?: readonly string[]): Promise<StageAndCommitResult>;
+/**
+ * 提交已暂存内容（不动提交集合）。
+ *
+ * author / 签名 / hooks 三条隔离：显式 `-c user.name` / `-c user.email` 覆盖 host 全局，
+ * `-c commit.gpgsign=false` 阻断宿主签名，`--no-verify` 跳过目标仓库钩子（详见 ./git-signing.ts）。
+ */
+export declare function commitStaged(message: string, workDir: string, author: {
+  name: string;
+  email: string;
+}): Promise<void>;
+/** 判定本次提交集合（不写盘、不暂存）。 */
+export declare function computeCommitScope(workDir: string, declaredPaths?: readonly string[]): Promise<CommitScope>;
+/** 按固定大小切分路径（`git add` 的 argv 上限防护）。 */
+export declare function chunkPaths(paths: readonly string[], size?: number): string[][];
 export interface FetchDependabotAlertsParams {
   /** 仓库所属组织或用户 */
   owner: string;
@@ -203,7 +576,7 @@ export interface FetchDependabotAlertsParams {
  *
  * @example
  * ```typescript
- * // 推荐：使用 auth 抽象层（M18.1 实施后）
+ * // 推荐：使用 auth 抽象层（已实施）
  * import { fromPat } from '@dependfix/engine/auth'
  * const octokit = createGitHubClient({ auth: fromPat('ghp_xxxx') })
  * const alerts = await fetchDependabotAlerts(octokit, { owner: 'foo', repo: 'bar' })
@@ -213,8 +586,6 @@ export interface FetchDependabotAlertsParams {
  * ```
  */
 export declare function fetchDependabotAlerts(client: Octokit, params: FetchDependabotAlertsParams): Promise<NormalizedSecurityAlert[]>;
-//#endregion
-//#region src/github/errors.d.ts
 /**
  * 将 Octokit 请求错误映射为 `AppError`。
  *
@@ -222,8 +593,200 @@ export declare function fetchDependabotAlerts(client: Octokit, params: FetchDepe
  * @param context - 调用上下文描述（如 `'fetch repo info for foo/bar'`），会附加到错误消息中
  */
 export declare function mapGitHubError(error: unknown, context: string): AppError;
-//#endregion
-//#region src/github/pr-creator.d.ts
+/**
+ * git 执行语义隔离参数（单一事实源，engine 与平台侧共用）。
+ *
+ * 两类隔离：
+ * 1. **签名语义**：宿主 `commit.gpgsign=true` / `push.gpgSign=true` 会让 dependfix 的 commit 带上宿主个人签名
+ *    （或直接失败）、push 带上 `--signed`（服务端 `receive-pack` 不支持时报
+ *    `the receiving end does not support --signed push`）。以 `-c <key>=false` 形式仅作用于该次调用
+ *    即可隔离，且不写回任何配置文件；`-c` 的优先级高于 repo local / worktree / host global / system。
+ *    背景与取证口径见 docs/standards/git.md §3.8。
+ * 2. **hooks 语义**：被修复仓库若安装 husky / lint-staged（或自定义 `core.hooksPath`），其 `pre-commit` /
+ *    `commit-msg` 钩子会在 dependfix 的自动 commit 时执行，`pre-push` 会在推送修复分支时执行。这类钩子依赖
+ *    `npx` 与目标仓库完整 `node_modules`，在隔离执行环境下通常不可用——生产实证会以 `npx: not found`（exit 127）
+ *    中断 commit，进而触发 `COMMIT_FAILED` 与修复回滚（push 侧同类失效会触发 `push_failed`）。自动提交 / 推送
+ *    不应受目标仓库本地开发钩子约束，故在本次 commit / push 调用内分别跳过 commit 侧与 push 侧钩子。
+ *
+ * 策略：**不提供签名 / hooks opt-in**。
+ */
+/** commit 侧签名隔离参数。 */
+export declare const GIT_COMMIT_SIGNING_ISOLATION_ARGS: readonly ["-c", "commit.gpgsign=false"];
+/**
+ * commit 侧 hooks 隔离参数——须置于 `commit` 子命令**之后**（`--no-verify` 是 commit 的子命令选项，
+ * 而 `-c` 是 git 全局选项，二者位置不可互换）。
+ *
+ * 选型 `--no-verify` 而非 `-c core.hooksPath=<空目录>`：跨平台无需构造/保证目录存在，且同样覆盖
+ * husky 的 `core.hooksPath` 重定向场景（实测对 `pre-commit` 非 0 退出与 `core.hooksPath` 两者等效，
+ * 见 pr-creator.test.ts 的 hooks 隔离回归）。
+ *
+ * 边界：`--no-verify` 跳过 `pre-commit` / `commit-msg` / `prepare-commit-msg`，但**不跳过** `post-commit`
+ * （git 语义：`post-commit` 在 commit 完成后运行且不能改变结果，其失败不影响 commit 成败）。
+ */
+export declare const GIT_COMMIT_HOOKS_ISOLATION_ARGS: readonly ["--no-verify"];
+/** push 侧签名隔离参数——覆盖 push / push --delete 等全部推送调用点。 */
+export declare const GIT_PUSH_SIGNING_ISOLATION_ARGS: readonly ["-c", "push.gpgSign=false"];
+/**
+ * push 侧 hooks 隔离参数——须置于 `push` 子命令**之后**（`--no-verify` 是 push 的子命令选项，
+ * 而 `-c` 是 git 全局选项，二者位置不可互换）。
+ *
+ * 覆盖 `pre-push`：被修复仓库的 `pre-push`（husky / 自定义 `core.hooksPath`）会在 dependfix 推送
+ * 修复分支时执行；隔离环境无 `npx` / 目标仓库 `node_modules` 不完整 → hook 非 0 退出 → `push_failed`
+ * → 交付链中断（与 commit 侧 `pre-commit` / `commit-msg` 同一类失效）。生产日志当前无 `pre-push`
+ * 实例，属预防性收口（口径见 docs/standards/git.md §3.8）。
+ *
+ * 边界：仅跳过 `pre-push`；同时适用于 `push --delete`（`cleanupRemoteBranch`）。
+ * 选型 `--no-verify` 与 commit 侧一致——无需构造/保证空 `core.hooksPath` 目录，且对
+ * `core.hooksPath` 重定向场景等效。
+ */
+export declare const GIT_PUSH_HOOKS_ISOLATION_ARGS: readonly ["--no-verify"];
+/** 首次轮询间隔。 */
+export declare const PR_CHECK_POLL_INITIAL_MS = 15000;
+/** 轮询间隔退避上限。 */
+export declare const PR_CHECK_POLL_MAX_MS = 60000;
+/** 宽限期：创建后至少等这么久、且至少两轮轮询才允许判定 `no_ci_detected`。 */
+export declare const PR_CHECK_GRACE_MS = 60000;
+/** 单 PR 等待上限默认值（15 分钟）。 */
+export declare const DEFAULT_PR_CHECK_TIMEOUT_MS = 900000;
+/** 运行级等待总预算默认值（20 分钟）。 */
+export declare const DEFAULT_PR_CHECK_RUN_BUDGET_MS = 1200000;
+/** GitHub Actions job 预算基线（与 `security-auto-fix.yml` 的 `timeout-minutes: 25` 对齐）。 */
+export declare const DEFAULT_JOB_BUDGET_MS: number;
+/** 等待最多占用「剩余 job 预算」的比例（给 install / 验证 / 收尾留余量）。 */
+export declare const JOB_BUDGET_MAX_SHARE = 0.7;
+/** 报告与评论中保留的失败 job 数上限。 */
+export declare const FAILED_CHECK_SUMMARY_LIMIT = 5;
+/** 单 PR 轮询次数上限（按 15s→60s 退避，15 分钟预算约 20 轮；上限防注入时钟不前进导致空转）。 */
+export declare const PR_CHECK_MAX_POLLS = 200;
+/** 归一化观测到的一条 check（check run 或 commit status）。 */
+export interface ObservedCheck {
+  /** 来源：check run / commit status（同名多轮组键的一部分） */
+  kind: 'check' | 'status';
+  /** provider 归因（check `app.slug` / status `context` 前缀；与平台同源） */
+  provider: string;
+  name: string;
+  conclusion: CheckConclusion;
+  /** 详情页 URL（check 用它提取 Actions run id 作为重跑血缘） */
+  url?: string;
+  /** 失败详情文本（用于 external_noise 文本签名） */
+  detail?: string;
+  /** 源侧 id（同名多轮收敛的确定性兜底，见 {@link dedupeObservedChecksByLatestRound}） */
+  id?: string | null;
+  /** 轮次时间戳（check `started_at ?? completed_at` / status `updated_at ?? created_at`） */
+  roundAt?: string | null;
+}
+export interface WatchPrChecksParams {
+  octokit: Octokit;
+  owner: string;
+  repo: string;
+  pr: {
+    number: number;
+    htmlUrl: string;
+  };
+  /** PR head 分支（作为 check 查询 ref 的兜底） */
+  headBranch: string;
+  /** PR head 提交 SHA（用于精确查询与父提交比对；缺省回退分支名） */
+  headSha?: string;
+  /** 本次 PR 携带的尝试标记（写进失败评论，便于后续计数追溯） */
+  attempts?: readonly AttemptMarker[];
+  /** 单 PR 等待上限（毫秒） */
+  timeoutMs: number;
+  /** 运行级等待总预算（毫秒） */
+  runBudgetMs: number;
+  /** 剩余 job 预算（毫秒）；缺省不参与折算 */
+  jobBudgetRemainingMs?: number;
+  dryRun: boolean;
+  closeFailedPr: boolean;
+  logger: Pick<Logger, 'info' | 'warn' | 'error'>;
+  /** 注入时钟 / 休眠（测试用；缺省真实实现） */
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}
+export interface WatchPrChecksResult {
+  state: PrCheckWatchState;
+  attribution?: CheckAttribution;
+  closed: boolean;
+  commented: boolean;
+  polls: number;
+  durationMs: number;
+  failedChecks?: PrCheckFailureSummary[];
+  reason?: string;
+  commentError?: string;
+  closeError?: string;
+  /** `timeout` 时绑定到哪一层预算 */
+  budgetLimit?: BudgetLimit;
+}
+/** 预算绑定来源（超时时用于报告 / 评论归因）。 */
+export type BudgetLimit = 'pr' | 'run' | 'job';
+/**
+ * 有效等待上限 = min(per-PR 上限, per-run 预算, 剩余 job 预算 × 70%)，并回传绑定来源。
+ *
+ * 剩余 job 预算为负 / 0 时立即超时（不再占用 job 时间）。非有限值（NaN / Infinity）按耗尽处理，
+ * 避免 `sleep(NaN)` 造成空转。
+ */
+export declare function resolveEffectiveTimeout(params: {
+  timeoutMs: number;
+  runBudgetMs: number;
+  jobBudgetRemainingMs?: number;
+}): {
+  timeoutMs: number;
+  limit: BudgetLimit;
+};
+/** check run 结论 → 归一化结论（未完成统一 `pending`）。 */
+export declare function normalizeCheckRunConclusion(status: string | null | undefined, conclusion: string | null | undefined): CheckConclusion;
+/** commit status state → 归一化结论（`error` 归一为 `failure`）。 */
+export declare function normalizeCommitStatusConclusion(state: string | null | undefined): CheckConclusion;
+/**
+ * 清洗来自目标仓库的 check / status URL（不可信文本）。
+ *
+ * 只接受 `http(s)`；剥离控制字符与空白（防换行截断），并把括号与竖线百分号编码（防 Markdown 链接结构与表格单元格被劫持）。
+ */
+export declare function sanitizeCheckUrl(value: string | null | undefined): string | undefined;
+/** 清洗来自目标仓库的 check / job 名（不可信文本）：去控制字符与换行、压缩空白、截断。 */
+export declare function sanitizeCheckName(value: string | null | undefined): string;
+interface TerminalEvaluation {
+  state: PrCheckWatchState;
+  attribution?: CheckAttribution;
+  failedChecks?: PrCheckFailureSummary[];
+}
+/**
+ * 同名多轮收敛：同一「组键」只保留**最新一轮**（与平台 `dedupeSignalsByLatestRound` 同源，
+ * 组键与排序均由 `@dependfix/core` 的 `checkRoundKey` / `dedupeByLatestRound` 提供）。
+ *
+ * 触发场景：check run re-run（同一 workflow run 的同名新尝试）、同一 commit status context 的后发状态。
+ * 组键含 `kind` / `provider`：check run 与 commit status 同名、或同名 job 由不同 App 上报时**不合并**；
+ * check 还要求能证明同一条 workflow run（`details_url` 里的 run id），否则各自成组——
+ * 「push 触发」与「pull_request 触发」是同名不同 run，合并会掩蔽另一方的失败。
+ * 口径见 docs/design/governance/pr-build-deploy-signals.md §3.10。
+ */
+export declare function dedupeObservedChecksByLatestRound(checks: readonly ObservedCheck[]): ObservedCheck[];
+/**
+ * 判定终态；未到终态返回 `undefined`（继续轮询）。
+ *
+ * 终态条件：已观测到至少一条 check，且全部 check 已完成（无 `pending`）。
+ * `completed + conclusion=null` 归一为 `unknown` 结论（`isFailedConclusion` 判失败，fail-closed），
+ * 与平台侧 `resolveCheckRunState` 同口径（docs/design/governance/pr-build-deploy-signals.md §3.10）。
+ * - 存在失败 → `failed`（逐条归因后聚合；混合归因 → `unknown`）
+ * - 无失败且有成功 → `passed`
+ * - 无失败且无成功（全是 cancelled / skipped / neutral）→ `cancelled`
+ */
+export declare function evaluateCheckTerminal(params: WatchPrChecksParams, observedChecks: readonly ObservedCheck[]): Promise<TerminalEvaluation | undefined>;
+/** 构造失败评论正文（job 名 + URL + 归因 + 尝试标记）。 */
+export declare function buildCheckFailureComment(params: {
+  prNumber: number;
+  state: PrCheckWatchState;
+  attribution?: CheckAttribution;
+  failedChecks?: readonly PrCheckFailureSummary[];
+  reason?: string;
+  attempts?: readonly AttemptMarker[];
+  closed?: boolean;
+}): string;
+/**
+ * 等待 PR check 终态并按归因处置。
+ *
+ * 任何 API / 评论 / 关闭失败都只降级记录，不抛错（调用方不因等待失败改变运行结论）。
+ */
+export declare function watchPullRequestChecks(params: WatchPrChecksParams): Promise<WatchPrChecksResult>;
 export interface CreatePullRequestParams {
   /** 已认证的 Octokit 实例 */
   octokit: Octokit;
@@ -239,12 +802,21 @@ export interface CreatePullRequestParams {
   title: string;
   /** PR 内容（Markdown） */
   body: string;
+  /**
+   * 创建为草稿 PR（基线红的交付降级 `draft` 档使用）。
+   *
+   * 草稿态让目标仓库 CI 仍会按既有失败为红，但不会触发人工 review 队列；
+   * 缺省 / `false` 时请求体不带 `draft`，与既有行为逐字一致。
+   */
+  draft?: boolean;
 }
 export interface PullRequestResult {
   /** PR 编号 */
   number: number;
   /** PR HTML URL */
   htmlUrl: string;
+  /** PR head 提交 SHA（check 回环用它精确查询；响应缺省时 undefined） */
+  headSha?: string;
 }
 export interface FixBranchResult {
   /** 分支名 */
@@ -261,6 +833,8 @@ export interface DependfixOpenPR {
   /** PR head 分支名 */
   headRef: string;
 }
+/** 自动修复分支统一前缀（分支名 = 前缀 + 内容指纹 8 位） */
+export declare const DEPENDFIX_BRANCH_PREFIX = "dependfix/auto-fix-";
 /**
  * 计算修复内容指纹（sha256 前 8 位）。
  *
@@ -306,27 +880,33 @@ export declare function computeFixAndPrPlan(existingPRs: DependfixOpenPR[], fing
  *
  * @returns 分支名和是否为新创建
  */
-export declare function createFixBranch(branchName: string, workDir: string): FixBranchResult;
+export declare function createFixBranch(branchName: string, workDir: string): Promise<FixBranchResult>;
 /**
- * 暂存所有变更并提交。
- * 自动设置 git user.name / user.email（如未设置）。
- * 使用 `execFileSync` 参数数组形式（不经 shell），保证多行 commit message
- * 与 UTF-8 字符（如 →）在 Windows/Linux 双平台传递一致。
- *
- * W3 修复（M18.4 audit round 2）：显式传 `-c user.name=X -c user.email=Y` 强制 commit author
- * 使用传入值，不受 host 全局 `user.name`（如 CaoMeiYouRen）污染——`git commit` 走 lookup order
- * (env → `-c` config → local → global → system)，显式 `-c` 在 lookup order 中最高优先。
+ * 暂存修复相关文件并提交。
  *
- * @param author - 可选 commit author 信息；不传时使用 PAT 默认值（保持现有 PAT 路径行为零变化）。
- *   M18.2 之后 GitHub App 路径会传入动态生成的 `{app_id}+{bot_login}[bot]` author。
+ * 提交集合由 [stageScopedChanges] 判定（固定白名单 ∪ fixer 声明路径，生成物剔除）：
+ * 未声明的已跟踪改动抛 `UNEXPECTED_CHANGES`，空集合抛 `NO_CHANGES`——不再通配暂存，
+ * 避免把目标仓库的生成物与用户未提交改动带进 PR。author / 签名 / hooks 三条隔离见
+ * [commitStaged] 与 ./git-signing.ts。
  *
- * @see [C22 PAT 无感升级评估 §5.1 兼容性](../../../../docs/design/governance/c22-pat-backward-compat.md)
+ * @param author - 可选 commit author；不传时使用 PAT 默认值（GitHub App 路径传动态 author）
+ * @throws {CommitScopeError} 提交集合含未声明改动 / 非法声明路径 / 为空
+ * @see [M48.4 提交面白名单 §7](../../../../docs/design/governance/pr-delivery-closure.md#7-m484-提交面白名单与-yaml-定点编辑)
  */
 export declare function stageAndCommit(message: string, workDir: string, author?: {
   name: string;
   email: string;
-}): void;
-export declare function pushBranch(branchName: string, workDir: string): void;
+}, options?: StageAndCommitOptions): Promise<StageAndCommitResult>;
+/**
+ * 推送分支到 origin。
+ *
+ * 隔离（单一事实源见 ./git-signing.ts）：
+ * - **签名**：显式传 `-c push.gpgSign=false`，避免宿主 `push.gpgSign=true` 让 push 带上
+ *   `--signed`（服务端不支持时直接 `the receiving end does not support --signed push` 失败）
+ * - **hooks**：`push --no-verify` 跳过被修复仓库的 `pre-push`（隔离环境无 `npx` / 目标仓库
+ *   `node_modules` 不完整时该 hook 会以非 0 退出，把交付链打断为 `push_failed`）
+ */
+export declare function pushBranch(branchName: string, workDir: string): Promise<void>;
 /**
  * 查找目标仓库中所有 open 状态的 dependfix 自动修复 PR。
  *
@@ -358,7 +938,7 @@ export declare function commentOnPullRequest(octokit: Octokit, owner: string, re
  */
 export declare function addLabelToPullRequest(octokit: Octokit, owner: string, repo: string, pullNumber: number, labels: string[]): Promise<void>;
 /**
- * 通过 GitHub API 创建 Pull Request。
+ * 通过 GitHub API 创建 Pull Request（`draft: true` 创建草稿 PR：基线红的交付降级档）。
  */
 export declare function createPullRequest(params: CreatePullRequestParams): Promise<PullRequestResult>;
 /** 分支清理状态（用于 cleanup-branches 清单分类） */
@@ -398,10 +978,9 @@ export declare function isConfirmAnswer(answer: string): boolean;
  * 明细表在尾部被截断），并附加截断说明——避免大仓库 PR 创建 422。
  *
  * @param supersededNumbers 被本 PR 取代并已关闭的旧 PR 编号列表（用于 Supersedes 声明）
+ * @param attemptMarkers 同告警尝试标记（HTML 注释；必须置于正文头部——正文超 64KB 时从尾部截断，尾置标记会丢失）
  */
-export declare function generatePRBody(result: RunResult, supersededNumbers?: number[]): string;
-//#endregion
-//#region src/github/repo-policy.d.ts
+export declare function generatePRBody(result: RunResult, supersededNumbers?: number[], attemptMarkers?: readonly AttemptMarker[]): string;
 /** 单条 glob 模式长度上限（加固：防止超长模式引入匹配开销；受信配置 + 短输入） */
 export declare const MAX_GLOB_PATTERN_LENGTH = 200;
 /**
@@ -427,9 +1006,52 @@ export interface RepoPolicy {
   exclude?: string[];
   /** topic 黑名单（仅作用于发现结果：排除含任一指定 topic 的仓库） */
   topicsExclude?: string[];
+  /**
+   * overrides 保护名单（显式维护）：仓库 glob → 不得自动写入 override 的包名列表。
+   *
+   * 命中时 dependfix 跳过该包的 override 写入并记审计（`OVERRIDE_PROTECTED`），
+   * 防止历史上被人工移除的破坏性 override 复发（实证见
+   * [override-protect-policy.md](../../../../docs/design/governance/override-protect-policy.md)）。
+   *
+   * **必须按仓库粒度**：同一 override 对不同仓库的破坏性不同（如纯 ESM 依赖只破坏 CJS 消费方），
+   * 全局包名黑名单会误伤真正需要该升级的仓库。键支持与 include / exclude 相同的 glob 语义
+   * （`owner/*`、`owner/pkg-*`）；全局兜底需写两段通配（owner 段与 repo 段各一个星号），因单星号不跨 `/`。
+   */
+  overrideProtect?: Record<string, string[]>;
 }
 /** 是否命中任一 exclude 模式（黑名单）。 */
 export declare function matchesRepoExclude(policy: RepoPolicy, fullName: string): boolean;
+/**
+ * 该仓库是否保护指定包的 override 写入。
+ *
+ * 命中条件：存在键 glob 匹配 `fullName` **且** 该键的包名列表包含 `packageName`。
+ * 返回命中的模式（用于报告展示判定依据）；未命中时 `protected=false`。
+ */
+export declare function matchesOverrideProtect(policy: RepoPolicy, fullName: string, packageName: string): {
+  protected: boolean;
+  matchedPattern?: string;
+};
+/**
+ * 是否为可安全用作对象键的名称（非原型链风险键）。
+ *
+ * 原型链风险键（`__proto__` / `constructor` / `prototype`）在「以外部输入为键写入对象」时
+ * 可能造成原型污染或语义歧义；overrideProtect 的两个入口（env / CLI 解析、目标仓库配置文件）
+ * 共用本谓词，避免两处口径漂移。
+ */
+export declare function isSafePrototypeKey(key: string): boolean;
+/**
+ * 解析 overrides 保护名单入口值（与 `--upgrade-groups` 同格式、同口径）：
+ * `name1:pkg1,pkg2;name2:pkg3`（`;` 分隔条目，`:` 分隔仓库 glob 与包列表，`,` 分隔包名）。
+ *
+ * 与 `normalizeUpgradeGroups` / `parseUpgradeGroupsFlag` 保持一致的 fail-fast 语义：
+ * 空 entry 忽略；非空但缺冒号 / 仓库 glob 为空 / 包列表为空 → 抛错（不静默降级）；
+ * 原型链风险键名（`__proto__` / `constructor` / `prototype`）忽略。
+ *
+ * @param value - 原始入口值（CLI 单值 / env 单值）
+ * @param errorFactory - 抛错工厂（config 侧抛 CONFIG_VALIDATION_ERROR、CLI 侧抛 ARGUMENT_PARSE_ERROR）
+ * @param label - 报错中展示的入口名（如 `--override-protect` / `DEPENDFIX_OVERRIDE_PROTECT`）
+ */
+export declare function parseOverrideProtectEntries(value: string, errorFactory: (message: string) => Error, label: string): Record<string, string[]>;
 /** 是否通过 include 白名单（include 为空 = 不限制；非空 = 必须命中任一模式）。 */
 export declare function matchesRepoInclude(policy: RepoPolicy, fullName: string): boolean;
 /** topic 黑名单：仓库 topics 含任一指定 topic 即排除（大小写归一化后比较）。 */
@@ -439,8 +1061,6 @@ export declare function matchesTopicsExclude(policy: RepoPolicy, topics: string[
  * 设计要点：显式优先，用户显式指定的仓库不应被 include 静默剔除）。
  */
 export declare function filterExplicitRepositories(policy: RepoPolicy, repositories: string[]): string[];
-//#endregion
-//#region src/github/repo-selector.d.ts
 /**
  * 从文件读取仓库列表（每行一个 `owner/repo`）。
  * 空行和 `#` 开头的注释行会被跳过。
@@ -450,8 +1070,6 @@ export declare function readReposFile(filePath: string): string[];
  * 合并 CLI 传入仓库列表与文件中的仓库列表，去重并校验。
  */
 export declare function resolveRepoList(cliRepos: string[], reposFilePath?: string): string[];
-//#endregion
-//#region src/github/repository-discovery.d.ts
 export interface RepositoryDiscoveryOptions {
   /** 已认证的 Octokit 实例 */
   client: Octokit;
@@ -478,7 +1096,7 @@ export interface RepositoryDiscoveryOptions {
   probeConcurrency?: number;
   /**
    * 发现规模上限：最多保留的仓库数（按 fullName 字典序排序后截断）。
-   * 默认 100；设为 0 或负数表示不限制。
+   * 默认 100；设为 0 表示不限制（负数会被拒绝）。
    * 大 org 场景下防止一次性全量发现导致 API 配额不可控消耗和超时。
    */
   maxRepos?: number;
@@ -514,8 +1132,6 @@ export declare function discoverRepositories(options: RepositoryDiscoveryOptions
  *   显式 `Owner/Repo` 与发现 `owner/repo` 视为同一仓库）
  */
 export declare function mergeRepositories(explicit: string[], discovered: string[]): string[];
-//#endregion
-//#region src/github/token-scope.d.ts
 /**
  * 凭据权限面启动检查（安全治理：超权限 token 启动即警告）。
  *
@@ -565,8 +1181,6 @@ export declare function analyzeTokenScope(scopeHeader: string | undefined, accep
 export declare function checkTokenPermissions(client: Octokit, options?: {
   codeScanningEnabled?: boolean;
 }): Promise<TokenScopeCheckResult>;
-//#endregion
-//#region src/code-scanning/rule-classifier.d.ts
 /**
  * A 类自动修复白名单默认集合（默认值常量；测试 disjointness 不变量用）。
  *
@@ -618,8 +1232,6 @@ export declare function classifyRule(ruleId: string | null | undefined): AlertCl
  * 读取自当前生效配置（`getActiveRulesConfig().suggested`）；未收录规则返回通用建议（C 类兜底，不静默）。
  */
 export declare function suggestionFor(ruleId: string | null | undefined): string;
-//#endregion
-//#region src/code-scanning/rule-config.d.ts
 export type RuleClass = 'auto-fixable' | 'suggested' | 'report-only';
 export interface RuleConfigEntry {
   /** 规则 id（如 `js/sql-injection`，trim 后用于匹配；空串非法） */
@@ -677,8 +1289,6 @@ export declare function getActiveRulesConfig(): CompiledRulesConfig;
 export declare function setActiveRulesConfig(config: CompiledRulesConfig): void;
 /** 重置为默认配置（测试 cleanup + 运行时 fallback） */
 export declare function resetActiveRulesConfig(): void;
-//#endregion
-//#region src/code-scanning/templates.d.ts
 export interface TemplateApplyResult {
   /** 修改后的文件内容 */
   content: string;
@@ -699,8 +1309,155 @@ export interface CodeScanningFixTemplate {
 }
 /** 获取规则对应的修复模板；无模板返回 undefined（调用方回退建议模式）。 */
 export declare function getCodeScanningFixTemplate(ruleId: string): CodeScanningFixTemplate | undefined;
-//#endregion
-//#region src/fixers/dependency/index.d.ts
+/** `package.json` 的最小结构视图（只声明本模块读写的字段）。 */
+interface PackageJson {
+  name?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  pnpm?: {
+    overrides?: Record<string, string>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+/** 依赖所在的安装组与原始声明。 */
+interface DependencyInfo {
+  group: 'dependencies' | 'devDependencies' | 'optionalDependencies';
+  version: string;
+}
+/**
+ * 在 `package.json` 的 `dependencies` / `devDependencies` / `optionalDependencies` 中按顺序查找包。
+ */
+export declare function findDependencyVersion(pkg: PackageJson, packageName: string): DependencyInfo | null;
+/**
+ * 从版本声明中提取前缀（^ / ~ / 空）。
+ *
+ * @example
+ * extractPrefix('^4.17.20')  // '^'
+ * extractPrefix('~4.17.0')   // '~'
+ * extractPrefix('4.17.20')   // ''
+ * extractPrefix('*')         // '^'  (默认)
+ */
+export declare function extractPrefix(version: string): string;
+/**
+ * 确保 `package.json` 中存在 `pnpm.overrides` 对象，若不存在则创建。
+ * 返回 `overrides` 对象的引用，调用方可直接写入。
+ */
+export declare function ensurePnpmOverrides(pkg: PackageJson): Record<string, string>;
+/** 版本化 overrides 批量应用条目（一条 = 一个包的多 key overrides）。 */
+interface VersionedOverridesPlan {
+  packageName: string;
+  overrides: Record<string, string>;
+}
+/** 批量应用结果（不抛错：失败经 `error` 文本暴露，成功可带 `warning`）。 */
+interface VersionedOverridesApplyResult {
+  success: boolean;
+  warning?: string;
+  error?: string;
+  /**
+   * 失败阶段：`precheck`（未写盘）/ `install`（已写盘且安装失败）/
+   * `verify`（安装成功但回读 lockfile 仍有低于目标的实例，已回滚）——供单包包装保持既有 `toVersion` 口径。
+   */
+  failurePhase?: 'precheck' | 'install' | 'verify';
+  /** 安装失败是否由安装环境问题导致（信号终止 / 超时 / 无 stderr 诊断）；调用方据此停止逐包重试 */
+  environmental?: boolean;
+}
+/** 单条写盘结果（版本声明保留原前缀）。 */
+interface ManifestUpgradeApplied {
+  packageName: string;
+  fromVersion: string;
+  toVersion: string;
+  isMajor: boolean;
+}
+/**
+ * 归一化单个 selector。
+ *
+ * 等价类：`1` / `^1` / `1.x` / `1.*` / `^1.x` → `major:1`。
+ * 其余（`~1`、`^1.2`、`1.1.21`、`>=1 <2` 等）原样返回（trim 后）。
+ */
+export declare function normalizeOverrideSelector(selector: string): string;
+/** 归一化整条 override key（含 scoped 包名与 `parent>child` 路径）。 */
+export declare function normalizeOverrideKey(key: string): string;
+/** upsert 结果：实际写入的 key（优先复用已有等价写法）与写入前旧值。 */
+interface OverrideUpsert {
+  /** 实际写入的 key；命中已有语义等价 key 时为其原写法 */
+  key: string;
+  /** 写入前的旧值（`undefined` = 新增） */
+  oldValue: string | undefined;
+}
+/**
+ * 写入 / 更新一条 override。命中已有语义等价 key（如已有 `pkg@^1` 而写入 `pkg@1`）
+ * 时复用已有写法，保证同一 selector 只保留一种写法。
+ */
+export declare function upsertOverride(overrides: Record<string, string | undefined>, key: string, value: string): OverrideUpsert;
+/**
+ * 从版本声明中提取主版本号（major）。
+ * 去除前缀后匹配第一个 semver 段。
+ *
+ * @example
+ * parseMajorVersion('^4.17.20')   // 4
+ * parseMajorVersion('~2.0.0')     // 2
+ * parseMajorVersion('1.2.3')      // 1
+ * parseMajorVersion('*')          // -1
+ */
+export declare function parseMajorVersion(version: string): number;
+/**
+ * 比较两个语义化版本（`x.y.z`，可选 pre-release 后缀）。
+ *
+ * `a > b` 返回正数，`a < b` 返回负数，相等返回 0；非 semver 字符串按 0 处理
+ * （保守：不参与大小比较）。pre-release 后缀忽略（如 `1.0.0-beta` 视为 `1.0.0`）。
+ *
+ * @example
+ * compareSemver('4.18.0', '4.17.21')  // 1
+ * compareSemver('5.4.20', '6.4.3')    // -1
+ * compareSemver('1.2.3', '1.2.3')     // 0
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * 检测版本声明是否包含包管理器协议前缀
+ * （`workspace:` / `catalog:` / `link:` / `file:` / `npm:` / `github:` /
+ * `gitlab:` / `bitbucket:` / `gist:` / `git:` / `git+ssh:` / `git+https:` /
+ * `git+http:` / `git+file:` / `https:` / `ssh:` 等）。
+ *
+ * 这类声明不是 semver range，`extractPrefix` 会将其误归为 `^` 导致声明被
+ * 不可逆改写（如 `catalog:` → `^x.y.z`、`git+ssh:` 来源从 fork/私有源静默
+ * 切回 registry），升级前必须拒绝。
+ *
+ * @example
+ * isNonSemverDeclaration('^4.17.20')      // false
+ * isNonSemverDeclaration('workspace:*')   // true
+ * isNonSemverDeclaration('catalog:')      // true
+ * isNonSemverDeclaration('link:../pkg')   // true
+ * isNonSemverDeclaration('git+ssh://...') // true
+ * isNonSemverDeclaration('gitlab:...')    // true
+ * isNonSemverDeclaration('https://...tgz') // true
+ */
+export declare function isNonSemverDeclaration(version: string): boolean;
+/**
+ * 从 `pnpm-lock.yaml` 中读取指定包的**所有**锁定版本实例。
+ *
+ * 支持两种 lockfile 键格式：
+ * 1. v9 早期格式（lockfileVersion 9.0 起）：`/package-name/version:`
+ * 2. pnpm v10+/v11 snapshot 格式：`package-name@version:` 或
+ *    `package-name@version(peer@x)(peer2@y):`（peer 后缀条目）
+ *
+ * 同一包在 lockfile 中可能共存多个版本（如 vite@5.4.14 与 vite@8.2.0），
+ * 多版本共存是「版本化 overrides（pkg@version: ^target）」修复策略的前提。
+ *
+ * @returns 去重后的版本列表（如 `['5.4.14', '8.2.0']`），未找到返回 `[]`
+ */
+export declare function readLockfileVersions(lockfilePath: string, packageName: string): string[];
+/**
+ * 从 `pnpm-lock.yaml` 中读取指定包的当前锁定版本。
+ *
+ * 多版本并存时（如同一包同时被根与子目录 manifest 引用），取**最高版本**
+ * （保守：不降级保护依赖此语义，如根 vite@8.2.0 与 docs vite@5.4.14 并存）。
+ *
+ * @returns 锁定版本字符串（如 `'5.0.0'`），未找到返回 `null`
+ */
+export declare function readLockfileVersion(lockfilePath: string, packageName: string): string | null;
 export interface UpgradeDependencyParams {
   /** 包名（如 `'lodash'`, `'@babel/traverse'`） */
   packageName: string;
@@ -730,22 +1487,18 @@ export interface DependencyFixResult {
   error?: string;
   /** 成功但存在需要用户注意的附加信息（如 overrides 写入位置可能被 pnpm 忽略） */
   warning?: string;
+  /**
+   * 失败是否由安装环境问题导致（信号终止 / 超时 / 无 stderr 诊断）。
+   * 调用方据此停止后续安装尝试——同一环境下逐包重试只会重复失败并耗尽运行预算。
+   */
+  environmental?: boolean;
 }
-export interface PackageJson {
-  name?: string;
-  dependencies?: Record<string, string>;
-  devDependencies?: Record<string, string>;
-  optionalDependencies?: Record<string, string>;
-  peerDependencies?: Record<string, string>;
-  pnpm?: {
-    overrides?: Record<string, string>;
-    [key: string]: unknown;
-  };
-  [key: string]: unknown;
-}
-interface DependencyInfo {
-  group: 'dependencies' | 'devDependencies' | 'optionalDependencies';
-  version: string;
+/** 家族锁步升级结果：`updates` 在安装失败时也保留已尝试的声明，便于报告展示。 */
+export interface FamilyUpgradeDependenciesResult {
+  success: boolean;
+  updates: ManifestUpgradeApplied[];
+  error?: string;
+  environmental?: boolean;
 }
 /**
  * 升级单个依赖到指定版本。
@@ -763,6 +1516,23 @@ interface DependencyInfo {
  * @returns 修复结果
  */
 export declare function upgradeDependency(params: UpgradeDependencyParams): Promise<DependencyFixResult>;
+/**
+ * 家族锁步升级：一次写盘 + 一次安装，失败整体回滚（含 lockfile）。
+ *
+ * 与 [upgradeDependency] 的区别只有写盘条数：族成员的 manifest 声明全部改完再执行
+ * 一次 `pnpm install`，任一成员校验失败 / 安装失败 / 回滚失败都按「整族失败」返回，
+ * 不产生半族状态。成员清单由 [planFamilyUpgrade] 决定（含触发包）。
+ *
+ * @param params - 工作目录、可选成员目录、待写盘成员（包名 + 目标版本）
+ */
+export declare function upgradeFamilyDependencies(params: {
+  workDir: string;
+  manifestDir?: string;
+  updates: ReadonlyArray<{
+    packageName: string;
+    targetVersion: string;
+  }>;
+}): Promise<FamilyUpgradeDependenciesResult>;
 /**
  * 通过 pnpm `overrides` 升级间接（transitive）依赖。
  *
@@ -800,97 +1570,25 @@ export declare function overrideTransitiveDependency(params: UpgradeDependencyPa
  * @param params - 包名、overrides 映射（`pkg@major` 或 `pkg` → `^target`）、工作目录
  * @returns 修复结果（fromVersion 为空字符串，表示多实例无单一来源版本）
  */
+/**
+ * 批量应用版本化 overrides：**一次写盘 + 一次安装**，失败整体回滚（含 lockfile）。
+ * 动机：逐包应用使单仓安装次数 = 可修包数（实测大仓 7–8 次），是资源受限主机 OOM 的放大器之一；
+ * [applyVersionedOverrides] 为单包薄包装，与本函数共用实现。调用方应过滤 `overrides` 为空的条目。
+ */
+export declare function applyVersionedOverridesBatch(params: {
+  workDir: string;
+  plans: VersionedOverridesPlan[];
+}): Promise<VersionedOverridesApplyResult>;
+/**
+ * 应用单个包的版本化 overrides（内部委托 [applyVersionedOverridesBatch]）。
+ * 写入位置：有 `pnpm-workspace.yaml` 时写其 `overrides`，否则写 `package.json#pnpm.overrides`；
+ * 失败自动回滚（含 lockfile），不执行验证（由上层负责）。
+ */
 export declare function applyVersionedOverrides(params: {
   packageName: string;
   versionedOverrides: Record<string, string>;
   workDir: string;
 }): Promise<DependencyFixResult>;
-/**
- * 从版本声明中提取前缀（^ / ~ / 空）。
- *
- * @example
- * extractPrefix('^4.17.20')  // '^'
- * extractPrefix('~4.17.0')   // '~'
- * extractPrefix('4.17.20')   // ''
- * extractPrefix('*')         // '^'  (默认)
- */
-export declare function extractPrefix(version: string): string;
-/**
- * 检测版本声明是否包含包管理器协议前缀
- * （`workspace:` / `catalog:` / `link:` / `file:` / `npm:` / `github:` /
- * `gitlab:` / `bitbucket:` / `gist:` / `git:` / `git+ssh:` / `git+https:` /
- * `git+http:` / `git+file:` / `https:` / `ssh:` 等）。
- *
- * 这类声明不是 semver range，`extractPrefix` 会将其误归为 `^` 导致声明被
- * 不可逆改写（如 `catalog:` → `^x.y.z`、`git+ssh:` 来源从 fork/私有源静默
- * 切回 registry），升级前必须拒绝。
- *
- * @example
- * isNonSemverDeclaration('^4.17.20')      // false
- * isNonSemverDeclaration('workspace:*')   // true
- * isNonSemverDeclaration('catalog:')      // true
- * isNonSemverDeclaration('link:../pkg')   // true
- * isNonSemverDeclaration('git+ssh://...') // true
- * isNonSemverDeclaration('gitlab:...')    // true
- * isNonSemverDeclaration('https://...tgz') // true
- */
-export declare function isNonSemverDeclaration(version: string): boolean;
-/**
- * 从版本声明中提取主版本号（major）。
- * 去除前缀后匹配第一个 semver 段。
- *
- * @example
- * parseMajorVersion('^4.17.20')   // 4
- * parseMajorVersion('~2.0.0')     // 2
- * parseMajorVersion('1.2.3')      // 1
- * parseMajorVersion('*')          // -1
- */
-export declare function parseMajorVersion(version: string): number;
-/**
- * 比较两个语义化版本（`x.y.z`，可选 pre-release 后缀）。
- *
- * - `a > b` 返回正数，`a < b` 返回负数，相等返回 0
- * - 非 semver 字符串按 0 处理（保守：不参与大小比较）
- * - 仅比较主/次/补丁段，pre-release 后缀忽略（如 `1.0.0-beta` 视为 `1.0.0`）
- *
- * @example
- * compareSemver('4.18.0', '4.17.21')  // 1
- * compareSemver('5.4.20', '6.4.3')    // -1
- * compareSemver('1.2.3', '1.2.3')     // 0
- */
-export declare function compareSemver(a: string, b: string): number;
-/**
- * 在 `package.json` 的 `dependencies` / `devDependencies` / `optionalDependencies` 中按顺序查找包。
- */
-export declare function findDependencyVersion(pkg: PackageJson, packageName: string): DependencyInfo | null;
-/**
- * 确保 `package.json` 中存在 `pnpm.overrides` 对象，若不存在则创建。
- * 返回 `overrides` 对象的引用，调用方可直接写入。
- */
-export declare function ensurePnpmOverrides(pkg: PackageJson): Record<string, string>;
-/**
- * 从 `pnpm-lock.yaml` 中读取指定包的**所有**锁定版本实例。
- *
- * 支持两种 lockfile 键格式：
- * 1. v9 早期格式（lockfileVersion 9.0 起）：`/package-name/version:`
- * 2. pnpm v10+/v11 snapshot 格式：`package-name@version:` 或
- *    `package-name@version(peer@x)(peer2@y):`（peer 后缀条目）
- *
- * 同一包在 lockfile 中可能共存多个版本（如 vite@5.4.14 与 vite@8.2.0），
- * 多版本共存是「版本化 overrides（pkg@version: ^target）」修复策略的前提。
- *
- * @returns 去重后的版本列表（如 `['5.4.14', '8.2.0']`），未找到返回 `[]`
- */
-export declare function readLockfileVersions(lockfilePath: string, packageName: string): string[];
-/**
- * 从 `pnpm-lock.yaml` 中读取指定包的当前锁定版本。
- *
- * 多版本并存时（如同一包同时被根与子目录 manifest 引用），取**最高版本**
- * （保守：不降级保护依赖此语义，如根 vite@8.2.0 与 docs vite@5.4.14 并存）。
- *
- * @returns 锁定版本字符串（如 `'5.0.0'`），未找到返回 `null`
- */
-export declare function readLockfileVersion(lockfilePath: string, packageName: string): string | null;
 /**
  * 读取当前已生效的 pnpm overrides 映射（与写入位置保持一致）：
  * - 存在 `pnpm-workspace.yaml` → 读取其中 `overrides` 字段（pnpm v10+ 推荐位置）
@@ -900,7 +1598,7 @@ export declare function readLockfileVersion(lockfilePath: string, packageName: s
  * 条目取 max 合并，不丢不改写已有条目（2026-08-09 复盘：此前生成侧不感知
  * 已有条目，导致 `pkg: ^x` 与 `pkg@major: ^y` 并存分裂）。
  *
- * @returns 已有 overrides 映射（key → 版本声明）；无配置或解析失败返回 {}
+ * @returns 已有 overrides 映射（key → 版本声明）；无配置、解析失败或 `overrides` 形态非法返回 {}
  */
 export declare function readExistingOverrides(workDir: string): Record<string, string>;
 /**
@@ -923,9 +1621,7 @@ export declare function detectPnpmMajor(workDir: string): number | null;
  * partitionSubmanifestAlerts 的常规跳过逻辑处理，避免重复计数。
  */
 export declare function isCrossMajorFixRequired(lockfilePath: string, alert: NormalizedSecurityAlert): boolean;
-//#endregion
-//#region src/fixers/pnpm/index.d.ts
-export type LockfileFailureCategory = 'LOCKFILE_NOT_FOUND' | 'MANIFEST_MISMATCH' | 'LOCKFILE_VERSION_MISMATCH' | 'CORRUPTED_LOCKFILE' | 'CREDENTIAL_ERROR' | 'RESOLVE_ERROR' | 'MINIMUM_RELEASE_AGE' | 'UNKNOWN';
+export type LockfileFailureCategory = 'LOCKFILE_NOT_FOUND' | 'MANIFEST_MISMATCH' | 'LOCKFILE_VERSION_MISMATCH' | 'CORRUPTED_LOCKFILE' | 'CREDENTIAL_ERROR' | 'RESOLVE_ERROR' | 'MINIMUM_RELEASE_AGE' | 'ENVIRONMENT_ERROR' | 'ABORTED' | 'UNKNOWN';
 export type RepairStrategy = 'REGENERATE' | 'FIX_ENTRIES' | 'PIN_TOOLCHAIN' | 'REINSTALL' | 'SKIP';
 export interface RepairLockfileParams {
   /** 工作目录（必须包含 package.json 和 pnpm-lock.yaml） */
@@ -949,6 +1645,10 @@ export interface RepairAttempt {
   success: boolean;
   error?: string;
   durationMs: number;
+  /** 进程退出码（非零退出时；被信号杀死 / spawn 失败时为 null） */
+  exitCode?: number | null;
+  /** 终止进程的信号（如 `SIGKILL` / `SIGTERM`）；非信号终止时为 null */
+  signal?: string | null;
 }
 export interface LockfileRepairResult {
   success: boolean;
@@ -956,22 +1656,50 @@ export interface LockfileRepairResult {
   failureDetail?: string;
   strategy?: RepairStrategy;
   diff?: LockfileDiff | null;
+  /** 修复后 lockfile **内容**是否实际改变（不同于行数 / 包数摘要；已合规时为 false）。 */
+  changed?: boolean;
   attemptHistory: RepairAttempt[];
   /** 修复后 lockfile 的 lockfileVersion（提取自 pnpm-lock.yaml） */
   lockfileVersion?: string;
   /** 修复前后 lockfileVersion 是否变化（格式漂移检测，wisdom: pnpm v11 overrides 迁移教训） */
   lockfileVersionChanged?: boolean;
+  /**
+   * 环境性安装失败（诊断步 `pnpm install --frozen-lockfile` 无 stderr 诊断 / 被信号杀死 / 超时）。
+   * 调用方据此**不归因目标仓库**（不计入「本次改动引入的失败」，与既有失败基线同族口径）。
+   */
+  environmental?: boolean;
 }
 interface ClassificationResult {
   ok: boolean;
   category?: LockfileFailureCategory;
+  /** 原始 stderr（保留供测试 / 来源区分；生产证据统一走 `diagnostics`） */
   stderr?: string;
+  /** 原始 stdout（pnpm 11 的安装脚本错误常写在这里；生产证据统一走 `diagnostics`） */
+  stdout?: string;
+  /** stderr + stdout 的合并诊断文本（分类与失败详情使用） */
+  diagnostics?: string;
+  /** 进程退出码（非零退出时；被信号杀死 / spawn 失败时为 null） */
+  exitCode: number | null;
+  /** 终止进程的信号；非信号终止时为 null */
+  signal: string | null;
+  /** 是否因超时被终止（execFileSync timeout） */
+  timedOut: boolean;
+  /** spawn 级 errno（如 `ENOENT`——工具链缺失）；无时为 null */
+  errno: string | null;
+  /** 合并诊断是否为空（无任何可用诊断信息） */
+  noDiagnostics: boolean;
+  /** 是否环境性失败（信号 / 超时 / 无 stderr 诊断） */
+  environmental: boolean;
 }
 /**
  * 执行 `pnpm i --frozen-lockfile` 并解析失败分类。
- * 成功时返回 { ok: true }。
+ * 成功时返回 `{ ok: true }`。
+ *
+ * 失败时保留进程级信号（退出码 / 信号 / 超时 / spawn errno）：无 stderr 诊断（被信号杀死 /
+ * 超时 / 静默非零退出）时归 `ENVIRONMENT_ERROR` + `environmental: true`——外部不再只看到
+ * `Command failed: pnpm install --no-frozen-lockfile` 这类无定位信息的结果。
  */
-export declare function classifyLockfileFailure(workDir: string): ClassificationResult;
+export declare function classifyLockfileFailure(workDir: string): Promise<ClassificationResult>;
 /** 从 lockfile 内容提取 `lockfileVersion` 字段值（如 `9.0`）；缺失返回 null。 */
 export declare function extractLockfileVersion(content: string): string | null;
 /**
@@ -1000,10 +1728,12 @@ export declare function resolvePnpmVersion(workDir: string, toolchain?: {
  *    - 验证通过 → 记录 diff、返回 success
  *    - 验证失败 → 继续下一个策略
  * 5. 所有策略失败 → 回滚 lockfile、返回失败结果
+ *
+ * 2026-10-17：本函数为**异步**（诊断 / frozen 校验 / 策略执行改为受管异步 `spawn`，
+ * 见 `runners/process-control.ts`）——同步实现会阻塞事件循环（引擎与平台同进程），
+ * 使平台的执行超时定时器一起停摆，且无法在取消时终止子进程树。
  */
-export declare function repairLockfile(params: RepairLockfileParams): LockfileRepairResult;
-//#endregion
-//#region src/fixers/code-scanning/index.d.ts
+export declare function repairLockfile(params: RepairLockfileParams): Promise<LockfileRepairResult>;
 export interface ApplyCodeScanningFixParams {
   /** 工作目录（告警 manifestPath 为相对路径，resolve 后读取） */
   workDir: string;
@@ -1047,11 +1777,24 @@ export declare function restoreSourceFile(workDir: string, snapshot: SourceFileS
  * 返回**真实路径**（后续读写走真实路径，避免再次经过 symlink）。
  */
 export declare function resolveWithinWorkDir(workDir: string, relativePath: string): string | null;
-//#endregion
-//#region src/config/index.d.ts
 export declare const RUNTIME_MODES: readonly ["report-only", "fix", "fix-and-pr", "cleanup-branches"];
 export declare const SEVERITY_THRESHOLDS: readonly ["critical", "high", "medium", "all"];
 export declare const ALERT_SOURCES: readonly AlertSourceKind[];
+/**
+ * GitHub App 认证配置。
+ * 通过 GitHub App installation token 认证时使用，用于生成真实 bot 身份的 commit author。
+ * 仅在 fix / fix-and-pr 模式下创建 commit 时生效；PAT 路径保持不变。
+ */
+export interface GitHubAppConfig {
+  /** GitHub App ID */
+  appId: string;
+  /** PEM 格式私钥 */
+  privateKey: string;
+  /** Installation ID */
+  installationId: string;
+  /** Bot 用户名（用于 commit author 动态生成；缺省 fallback `dependfix[bot]`） */
+  botLogin?: string;
+}
 /**
  * 环境变量统一前缀（v0.2 起替代旧项目名遗留的 `AUTO_FIX_GITHUB_SECURITY_`）。
  * 所有环境变量读取必须经由 {@link readEnv}，禁止散落硬编码，防止改名漏网。
@@ -1064,6 +1807,7 @@ export declare const ENV_PREFIX = "DEPENDFIX_";
  */
 export declare function readEnv(env: NodeJS.ProcessEnv, name: string): string | undefined;
 export type RuntimeMode = typeof RUNTIME_MODES[number];
+export type RollbackGranularity = 'unit' | 'repo';
 export interface RuntimeConfig {
   mode: RuntimeMode;
   severityThreshold: SeverityThreshold;
@@ -1094,6 +1838,12 @@ export interface RuntimeConfig {
    * 排除含任一指定 topic 的仓库。仅作用于发现结果（显式列表无 topics 元数据）。
    */
   repoTopicsExclude?: string[];
+  /**
+   * overrides 保护名单（`--override-protect` / `DEPENDFIX_OVERRIDE_PROTECT`）：
+   * 仓库 glob（`owner/*` / `owner/pkg-*`；全局兜底需写两段通配，因单星号不跨斜杠）→ 不得自动写入 override 的包名列表。
+   * 命中时跳过该包的 override 写入并记 `OVERRIDE_PROTECTED` 审计（防历史上被人工移除的破坏性 override 复发）。
+   */
+  overrideProtect?: Record<string, string[]>;
   dryRun: boolean;
   createPullRequest: boolean;
   /** 修复完成后是否在本地当前分支直接提交（不推送、不创建 PR） */
@@ -1103,6 +1853,11 @@ export interface RuntimeConfig {
   /** fix-and-pr 模式下结束后是否自动删除已合并/已关闭的 dependfix 分支（非交互） */
   cleanupBranchesAuto: boolean;
   githubToken: string;
+  /**
+   * GitHub App 认证配置（用于 commit author 真实 bot 身份）。
+   * 仅 fix-and-pr / fix 模式下创建 commit 时使用；PAT 路径保持不变。
+   */
+  githubApp?: GitHubAppConfig;
   /**
    * 告警数据源。默认 `github-dependabot`（GitHub Dependabot alerts API）；
    * `pnpm-audit` 为本地无 token 回退（`pnpm audit --json`），repository 解析
@@ -1132,10 +1887,60 @@ export interface RuntimeConfig {
    *
    * 开启后仅对「根 package.json 直接依赖（workspace 成员独占声明维持人工）
    * + lockfile 单版本」的跨线告警自动升级，升级后复核脆弱实例消除、
-   * 强制完整验证（install + lint + build），失败自动回滚；
+   * 强制完整验证（install + lint + build + typecheck + test），失败自动回滚；
    * 间接依赖 / 多版本共存跨线告警维持人工处理（skipped + warn）。
    */
   allowMajorUpgrade: boolean;
+  /**
+   * 验证失败回滚粒度：`unit`（默认）回退最近一个已通过 probe 的变更单元并重验一次；
+   * `repo` 保持既有整仓 `git reset --hard` 逃生语义。
+   */
+  rollbackGranularity?: RollbackGranularity;
+  /**
+   * 把目标仓库 CI 独有的 `pnpm/npm/yarn run` 脚本追加到验证链（`--mirror-ci-scripts` /
+   * `DEPENDFIX_MIRROR_CI_SCRIPTS`，默认 `false`）。
+   *
+   * 开启后在默认链**之后**执行（≤3 条、首失败即停），与默认链共用同一超时 / 取消面，
+   * 并同样纳入修复前基线采样（基线已红 → `preExisting`，不回滚、不改 exit code）。
+   * `docker` / `gh` / 任意 shell 与非脚本片段只记 `mirrorSkipped`，不执行。
+   * 显式自定义链（`--commands` / Action `commands` / 平台 `verifyCommands`）整链替换默认链，
+   * **不与 mirror 叠加**。
+   */
+  mirrorCiScripts?: boolean;
+  /**
+   * 忽略同告警尝试上限，强制再试一次（`--retry-failed` / `DEPENDFIX_RETRY_FAILED`，默认 `false`）。
+   *
+   * 仅 fix-and-pr 生效：同一告警 / 目标版本 / 修复策略连续两次关闭后，第 3 次起默认跳过
+   * （`alertsSkippedByReason['repeated-failure']`）；开启后仍执行并在报告标注「人工强制」。
+   * 尝试计数载体为 PR 正文 HTML 注释，计数口径见
+   * [pr-delivery-closure.md §6](../../../../docs/design/governance/pr-delivery-closure.md)。
+   */
+  retryFailed?: boolean;
+  /**
+   * 基线红（修复后安装仍既有失败）时的交付降级档位（`DEPENDFIX_ON_BASELINE_RED`，默认 `skip`）：
+   * `skip` 回滚并留痕 / `issue` 按失败指纹开 issue / `draft` 不回滚、创建**草稿** PR（仅 fix-and-pr；
+   * 平台只记录 summary）。口径见 [§16](../../../../docs/design/governance/pr-delivery-closure.md)。
+   */
+  onBaselineRed?: BaselineRedDelivery;
+  /** PR 创建后等待 check 终态（`--wait-pr-checks` / `DEPENDFIX_WAIT_PR_CHECKS`，默认 false；仅 fix-and-pr，口径见 [§8](../../../../docs/design/governance/pr-delivery-closure.md)） */
+  waitPrChecks?: boolean;
+  /** check 失败且归因 self_caused 时关闭 PR 并删分支（`--close-failed-pr`，默认 false；需同时等待，其余归因只评论） */
+  closeFailedPr?: boolean;
+  /** 单个 PR 的 check 等待上限（毫秒；默认 900000，60000-1800000） */
+  prCheckTimeoutMs?: number;
+  /** 运行内 check 等待总预算（毫秒；默认 1200000，60000-1800000，且 ≤ 剩余 job 预算 70%） */
+  prCheckRunBudgetMs?: number;
+  /** job 总预算基线（毫秒；`DEPENDFIX_JOB_BUDGET_MS`）。缺省仅在 `GITHUB_ACTIONS=true` 按 25 分钟套用 */
+  jobBudgetMs?: number;
+  /** 运行截止时间（epoch ms；平台计算、引擎消费）：预算不足时停止启动新工作并写 `BUDGET_EXHAUSTED` 审计。 */
+  deadlineAt?: number;
+  /** 执行宿主的构建版本回执（平台注入；缺省回退引擎包版本，最终 `unknown`；与 `/api/health` 同源）。 */
+  buildVersion?: string;
+  /**
+   * 执行宿主的构建 commit（平台容器注入）。只有宿主构建期能提供；
+   * 本地执行场景固定回退 `unknown`，不参与任何判定。
+   */
+  buildCommit?: string;
   /**
    * Dependabot alerts 专用 token（可选）。
    * 提供时仅用于拉取 Dependabot alerts（GITHUB_TOKEN 无法读取该 API，
@@ -1176,7 +1981,7 @@ export interface RuntimeConfig {
   toolchainPnpmVersion?: string;
   /**
    * 发现规模上限（`--max-repos` / `DEPENDFIX_MAX_REPOS`）：最多保留的仓库数。
-   * 默认 100；设为 0 或负数表示不限制。大 org 场景下防止一次性全量发现。
+   * 默认 100；设为 0 表示不限制（负数会被拒绝）。大 org 场景下防止一次性全量发现。
    */
   maxRepos: number;
   /**
@@ -1234,6 +2039,8 @@ export interface CliConfigOverrides {
   repoExclude?: string[];
   /** 发现结果 topic 黑名单（排除含任一指定 topic 的仓库） */
   repoTopicsExclude?: string[];
+  /** overrides 保护名单（仓库 glob → 包名列表；命中则跳过 override 写入） */
+  overrideProtect?: Record<string, string[]>;
   dryRun?: boolean;
   createPullRequest?: boolean;
   /** 修复完成后是否在本地当前分支直接提交 */
@@ -1254,6 +2061,24 @@ export interface CliConfigOverrides {
    * 无 env 通道；Action 不支持）。详见 RuntimeConfig.allowMajorUpgrade。
    */
   allowMajorUpgrade?: boolean;
+  /** 验证失败回滚粒度（unit / repo；默认 unit） */
+  rollbackGranularity?: RollbackGranularity;
+  /** 把目标仓库 CI 独有的包管理器脚本追加到验证链（`--mirror-ci-scripts`；默认关闭） */
+  mirrorCiScripts?: boolean;
+  /** 忽略同告警尝试上限并强制再试（`--retry-failed`；默认关闭，仅 fix-and-pr 生效） */
+  retryFailed?: boolean;
+  /** 基线红的交付降级档位（`DEPENDFIX_ON_BASELINE_RED`；默认 `skip`，仅 fix-and-pr 生效） */
+  onBaselineRed?: BaselineRedDelivery;
+  /** 等待本次 PR 的 check 终态（`--wait-pr-checks`；默认关闭，仅 fix-and-pr 生效） */
+  waitPrChecks?: boolean;
+  /** check 失败且归因 self_caused 时关闭 PR（`--close-failed-pr`；默认关闭，需同时等待） */
+  closeFailedPr?: boolean;
+  /** 单 PR check 等待上限（毫秒） */
+  prCheckTimeoutMs?: number;
+  /** 运行级 check 等待总预算（毫秒） */
+  prCheckRunBudgetMs?: number;
+  /** job 总预算基线（毫秒；缺省按 Actions 25 分钟兜底） */
+  jobBudgetMs?: number;
   /** Dependabot alerts 专用 token（可选，最小权限；缺省回退 githubToken） */
   alertsToken?: string;
   maxAlertsPerRepository?: number;
@@ -1269,7 +2094,7 @@ export interface CliConfigOverrides {
   toolchainPnpmVersion?: string;
   /**
    * 发现规模上限（`--max-repos` / `DEPENDFIX_MAX_REPOS`）：最多保留的仓库数。
-   * 默认 100；设为 0 或负数表示不限制。大 org 场景下防止一次性全量发现。
+   * 默认 100；设为 0 表示不限制（负数会被拒绝）。大 org 场景下防止一次性全量发现。
    */
   maxRepos?: number;
   /** AI 研判总开关（`--ai`） */
@@ -1282,19 +2107,24 @@ export interface CliConfigOverrides {
   aiBaseUrl?: string;
   /** AI Anthropic 兼容端点（`--ai-api-url`，仅 provider=anthropic 生效） */
   aiApiUrl?: string;
-  /** AI API Key（`--ai-api-key`；优先 DEPENDFIX_AI_API_KEY env） */
+  /** AI API Key（`--ai-api-key`；CLI 参数优先，DEPENDFIX_AI_API_KEY 环境变量兜底） */
   aiApiKey?: string;
   /** AI 触发范围（`--ai-trigger`：failure / major / both） */
   aiTrigger?: AiTriggerKind;
   /** 是否输出详细日志 */
   verbose?: boolean;
-  /** 自定义验证命令（覆盖默认的 `pnpm install --frozen-lockfile` / `pnpm lint` / `pnpm build`） */
+  /** 自定义验证命令（覆盖默认的 `pnpm install --frozen-lockfile` / `pnpm lint` / `pnpm build` / `pnpm typecheck` / `pnpm test`） */
   commands?: string[];
   /**
    * 历史查询（仅 CLI `--history`）：读取归档索引列出仓库历史运行摘要，
    * 不进入运行配置（resolveRuntimeConfig 不消费），由 CLI 层直接处理。
    */
   history?: string;
+  /**
+   * GitHub App 认证配置（用于 commit author 真实 bot 身份）。
+   * 仅 fix / fix-and-pr 模式下创建 commit 时使用；PAT 路径保持不变。
+   */
+  githubApp?: GitHubAppConfig;
 }
 export interface ResolveRuntimeConfigOptions {
   env?: NodeJS.ProcessEnv;
@@ -1316,8 +2146,6 @@ export declare function resolveRuntimeConfig(options?: ResolveRuntimeConfigOptio
  * @returns `owner/repo` 或 `null`（非 GitHub / 无 origin）
  */
 export declare function inferRepoFromGitRemote(workDir: string): string | null;
-//#endregion
-//#region src/report/archiver.d.ts
 export interface ArchiveRepoStats {
   repository: string;
   alertsCount: number;
@@ -1369,8 +2197,6 @@ export declare function readArchiveIndex(outputDir?: string): ArchiveIndex;
  * 仅返回包含该仓库的运行；无结果返回 []。
  */
 export declare function queryRepoHistory(repo: string, outputDir?: string): ArchiveRunEntry[];
-//#endregion
-//#region src/report/history.d.ts
 /**
  * 将某仓库的历史运行摘要格式化为多行文本（倒序时间：最新在前）。
  *
@@ -1381,8 +2207,6 @@ export declare function queryRepoHistory(repo: string, outputDir?: string): Arch
  * 无历史时返回提示行（非空，调用方直接打印）。
  */
 export declare function formatHistory(entries: ArchiveRunEntry[], repo: string): string;
-//#endregion
-//#region src/multirepo/scheduler.d.ts
 /** 并发上限（1-16，配置校验范围） */
 export declare const MAX_CONCURRENCY_LIMIT = 16;
 /** 默认并发（保守：行为与现状一致，逐仓库串行） */
@@ -1412,15 +2236,11 @@ export interface ConcurrencySchedulerOptions<T> {
 export declare function runWithConcurrency<T>(options: ConcurrencySchedulerOptions<T>): Promise<void>;
 /** 校验并发值是否在 1-16 范围内（config 层调用，抛 AppError）。 */
 export declare function isValidConcurrency(value: number): boolean;
-//#endregion
-//#region src/app/branch-cleanup.d.ts
 /**
  * 关闭被取代的旧 PR 并回收其 head 分支（supersede 流程）。
  * 关闭失败记录错误；分支删除失败仅 warn（家务活 best-effort，不触发非零退出）。
  */
 export declare function closeSupersededPRs(ctx: Pick<AppContext, 'logger' | 'allErrors'>, client: Octokit, owner: string, repo: string, supersedePRs: DependfixOpenPR[]): Promise<void>;
-//#endregion
-//#region src/ai/usage.d.ts
 interface AiUsage {
   /** 调用次数 */
   calls: number;
@@ -1451,8 +2271,6 @@ export declare class AiUsageTracker {
   record(inputTokens: number, outputTokens: number): void;
   snapshot(): AiUsage;
 }
-//#endregion
-//#region src/app/helpers.d.ts
 /** DependfixApp 提供给辅助方法的最小状态切片。 */
 interface AppContext {
   config: RuntimeConfig;
@@ -1463,10 +2281,61 @@ interface AppContext {
   allAlerts: NormalizedSecurityAlert[];
   allActions: FixAction[];
   allErrors: FixError[];
+  /** alerts 功能未启用记录（方案 A：未启用 ≠ 失败，不计入 allErrors） */
+  alertsDisabled: AlertsDisabledRecord[];
   repoResults: RepositoryResult[];
   summary: RunSummary;
   startedAt: string;
   finishedAt: string;
+  /** GitHub App 认证提供者（用于 commit author 真实 bot 身份） */
+  authProvider?: AuthProvider;
+  /**
+   * 验证链口径记录（run 级累积；`verifyProject` 写入，报告与 PR 正文消费）。
+   *
+   * 缺省（测试直接构造 ctx）⇒ 不记录；同一仓库多次验证取命令并集（按首次出现顺序），
+   * 并集未增长时复用既有记录与首轮健康预检结果，避免重复发起 API 调用。
+   */
+  ciAlignment?: CiAlignmentRecord[];
+  /**
+   * 同告警尝试记录（run 级累积；`repo-fix` 的计划阶段写入，报告与 PR 正文标记消费）。
+   * 缺省（测试直接构造 ctx）⇒ 不记录。
+   */
+  attemptTracking?: RepeatedAttemptRecord[];
+  /**
+   * 最近关闭 dependfix PR 的尝试索引（运行级缓存；仅 fix-and-pr 模式注入）。
+   * 缺省 ⇒ 不做同告警尝试判定（行为与引入前一致）。
+   */
+  attemptIndex?: ClosedAttemptIndex;
+  /**
+   * PR 落点仓库（`owner/repo`，= 本次运行的第一个仓库）。
+   *
+   * 尝试标记只能写进该仓库的 PR，故只有该仓库的告警参与尝试计数；多仓运行其余仓库
+   * 不做跳过判定（避免「在 A 仓计 B 仓的尝试」造成永久跳过）。
+   */
+  attemptRepo?: string;
+  /**
+   * 告警级修复结果收集器（run 级；修复管线在无法由 actions 反推的判定点写入，
+   * 报告 `alertOutcomes` 与平台 `ScanResult.fixStatus` 回写消费）。
+   * 缺省（测试直接构造 ctx）⇒ 报告只按 actions 与告警属性推导，不含收敛 / 跳过等显式判定。
+   */
+  alertOutcomes?: Map<string, AlertFixOutcome>;
+  /**
+   * PR check 回环结果（仅 `--wait-pr-checks` 且实际创建 PR 时存在）。
+   * 缺省 ⇒ 不等待（行为与引入前一致）。
+   */
+  prCheckWatch?: PrCheckWatchReport;
+  /**
+   * 交付跳过记录（修复后安装仍为既有失败 → 有修复但不交付）。
+   * 缺省（测试直接构造 ctx）⇒ 不记录，summary 计数保持 0。
+   */
+  deliverySkips?: DeliverySkipRecord[];
+  /**
+   * 运行截止时间（epoch ms；来自 `RuntimeConfig.deadlineAt`）。
+   * 缺省 ⇒ 不限预算（CLI 本地运行），所有预算检查放行。
+   */
+  deadlineAt?: number;
+  /** 已记录的预算跳过（`stage:work`；避免同一跳过来回刷审计）。缺省 ⇒ 不去重。 */
+  budgetSkips?: Set<string>;
 }
 /**
  * 按动作构成生成 PR 标题（收尾审查遗留修复：cs-only 修复不再误标 "N upgrades"，
@@ -1476,8 +2345,6 @@ interface AppContext {
  *   codeFixes 过滤条件一致（均 success && !noOp）；任一侧口径变更必须同步。
  */
 export declare function buildPrTitle(summary: Pick<RunSummary, 'alertsFixed'>, actions: FixAction[]): string;
-//#endregion
-//#region src/helpers/index.d.ts
 /**
  * 对可修复告警按包名去重（同包收敛）。
  *
@@ -1505,7 +2372,7 @@ export declare function restoreTrackedFiles(workDir: string, snapshot: Record<st
 /**
  * 快速验证（逐包）：运行验证命令序列。
  *
- * 有自定义命令时执行完整序列（含 install + setup + lint + build），
+ * 有自定义命令时执行完整序列（命令以自定义链为准，典型形态含 install + setup + lint + build + typecheck + test），
  * 否则仅运行 `pnpm lint`（脚本存在时）。
  *
  * 设计决策（run 33946113272 复盘）：旧版仅跑 `pnpm lint`，但 Nuxt 等框架
@@ -1567,8 +2434,6 @@ export declare function partitionSubmanifestAlerts(alerts: NormalizedSecurityAle
  * 进入跨线链路必然失败，维持人工处理。
  */
 export declare function isRootDirectDependency(workDir: string, packageName: string): boolean;
-//#endregion
-//#region src/grouping/index.d.ts
 /** 分组来源（决定分组优先级与命名语义） */
 export type GroupSource = 'explicit' | 'dependabot' | 'types' | 'scope' | 'prefix' | 'single';
 export interface DependencyGroup {
@@ -1659,8 +2524,6 @@ export declare function isMainPackagePresent(pkg: PackageJsonLike, lockfilePath:
  * 5. @types 归并（主包有告警并入其组）/ 独立组 / 清理候选（主包已不存在）
  */
 export declare function buildUpgradeGroups(alerts: NormalizedSecurityAlert[], options: GroupingOptions): GroupingResult;
-//#endregion
-//#region src/runners/network-audit.d.ts
 /**
  * 执行期网络外联审计 + 出站白名单拦截（安全治理：恶意脚本外联回传/下载 payload 的事故溯源与阻断）。
  *
@@ -1690,8 +2553,8 @@ interface NetworkAuditEntry {
   /** deny-by-default 拦截的违规外联标记（白名单校验失败的外联为 true） */
   violation?: boolean;
 }
-//#endregion
-//#region src/runners/verification-runner.d.ts
+/** 对子进程输出做敏感信息脱敏（可安全写入日志 / 报告）。 */
+export declare function sanitizeOutput(output: string): string;
 /**
  * 单条命令的执行结果
  */
@@ -1704,6 +2567,8 @@ export interface CommandResult {
   durationMs: number;
   /** 是否因超时被中止（默认 false） */
   timedOut?: boolean;
+  /** 超时兜底落定时是否未能确认直接子进程已退出 */
+  terminationUnconfirmed?: boolean;
   /** stdout 摘要（截断到 200 行，已脱敏） */
   stdout: string;
   /** stderr 摘要（截断到 200 行，已脱敏） */
@@ -1717,12 +2582,13 @@ export interface VerificationParams {
   workDir: string;
   /**
    * 要执行的命令序列。
-   * 默认: `pnpm install --frozen-lockfile` → `pnpm lint` → `pnpm build`
+   * 默认: `pnpm install --frozen-lockfile` → `pnpm lint` → `pnpm build` → `pnpm typecheck` → `pnpm test`
    */
   commands?: string[];
   /**
    * 单命令超时（毫秒），超时中止该命令并终止其进程树。
-   * 默认 10 分钟（恶意死循环脚本超时中止，防长时间占用）。
+   * 默认 10 分钟（恶意死循环脚本超时中止，防长时间占用）；
+   * 未显式提供时读取 `DEPENDFIX_VERIFY_TIMEOUT_MS`（10s-30min，越界回退默认）。
    */
   commandTimeoutMs?: number;
   /**
@@ -1731,6 +2597,12 @@ export interface VerificationParams {
    * 仅当环境无既有代理时注入（覆盖用户代理会破坏其网络行为）。
    */
   networkAuditDisabled?: boolean;
+  /**
+   * 遇首个失败命令后是否立即停止（默认 true，保持修复后验证的短路语义）。
+   * 修复前基线采样传 false：完整执行整条链并逐段记录，避免 install 失败遮蔽
+   * test 的既有失败（nest-template 形态）。
+   */
+  stopOnFailure?: boolean;
 }
 /**
  * 验证执行结果
@@ -1749,6 +2621,59 @@ export interface VerificationResult {
   /** 非白名单外联违规（deny-by-default 拦截记录；空数组 = 无违规或审计关闭） */
   networkViolations?: NetworkAuditEntry[];
 }
+/**
+ * 默认验证命令链（**唯一事实源**——app 层经此导入，消除此前的双副本漂移）。
+ *
+ * **顺序** install → lint → build → typecheck → test：
+ * - 便宜且失败信息明确的命令靠前，先失败可快速短路；test 置于最后（通常是链中最慢一步）。
+ * - typecheck 必须排在 build 之后：workspace 包的 `tsc` 依赖前置包已发射的 `dist` 声明
+ *   （实测移出 `packages/{core,engine,cli}/dist` 后 `pnpm --filter @dependfix/platform typecheck`
+ *   报大量 `TS2307 Cannot find module`）。
+ * - typecheck 排在 test 之前：类型错误优先于测试运行短路；修复前基线使用
+ *   完整链（`stopOnFailure:false`），不再受首失败前缀覆盖。
+ *
+ * **为何纳入 typecheck**：改动前的四条命令互不重叠地都不做类型检查——lint 只跑规则
+ * （类型解析失败通常降级为规则告警而非错误）、tsdown 的 `dts` 只发射声明、vitest 走 esbuild
+ * 转译。实证：消费方 `nodemailer.Transporter` 在依赖升到 10.x 后不再存在（TS2503），
+ * 而 install / lint / build / test 四条全绿——类型面破坏被判 `verificationPassed = true`
+ * 并交付成 PR，直到目标仓库 CI 才红。**边界**：`"build": "tsc"` 形态的仓库 build 本身即
+ * 类型检查，此时本命令为冗余（只增耗时，无害），并非新增防线。
+ *
+ * **为何纳入 test**：仅 install/lint/build 的矩阵无法捕获「lint/build 通过但测试无法运行或失败」
+ * 的破坏。实证：目标仓库把 `decode-uri-component` 升到纯 ESM 版本后，CJS 消费方
+ * `query-string@7.1.3` 在 Jest 下无法加载该模块（`SyntaxError: Unexpected token 'export'`），
+ * 而 install / lint / build 三条全绿——坏修复被交付成 PR。
+ *
+ * 无 `typecheck` / `test` 脚本的仓库由 `validateVerifyCommands` 跳过并记 `SCRIPT_NOT_FOUND` 审计，
+ * 不会误伤未配置对应脚本的仓库。
+ *
+ * **已知边界**：脚本语义不实（如 `"typecheck": "tsc --noEmit || true"`）无法机检；
+ * 「typecheck / test 长期为红」的仓库由命令级既有失败基线豁免；基线完整链采样全部命令
+ * （`sampleVerificationBaseline` 传 `stopOnFailure:false`），修复后验证仍首失败即停；
+ * 需 `nuxt prepare` 之类前置步骤的仓库默认链不成立，走 `--commands` / 平台 `verifyCommands` /
+ * action `commands` 逃生舱。
+ */
+export declare const DEFAULT_VERIFY_COMMANDS: string[];
+/**
+ * 单命令超时（10 分钟）：与纳入 test 前保持一致，不因命令数增加而调整。
+ * 注意：test 通常是链中最慢一步，大型测试套件超 10 分钟会被判超时 → 该命令计为失败。
+ * 修复前即红的既有失败不归因本次改动（命令级基线判定，见 `sampleVerificationBaseline`），
+ * 但超时本身仍按失败记录（不作独立超时豁免）。
+ *
+ * CI 镜像脚本（`--mirror-ci-scripts`）与默认链共用本超时——镜像不引入第二个计时器。
+ */
+export declare const DEFAULT_COMMAND_TIMEOUT_MS: number;
+/** 验证命令超时覆盖 env（运维面；默认链与 CI 镜像脚本同源）。 */
+export declare const VERIFY_TIMEOUT_ENV = "DEPENDFIX_VERIFY_TIMEOUT_MS";
+/** 允许的最小单命令超时（低于 10s 无实际意义，按配置错误回退默认）。 */
+export declare const MIN_COMMAND_TIMEOUT_MS = 10000;
+/** 允许的最大单命令超时（30 分钟，与平台单仓执行上限同量级）。 */
+export declare const MAX_COMMAND_TIMEOUT_MS: number;
+/**
+ * 解析单命令超时（毫秒）：合法正整数且落在 [10s, 30min] 内才采纳，否则回退默认。
+ * 与安装类超时（`fixers/install-timeouts.ts`）同族口径，但两者刻意不同源、互不覆盖。
+ */
+export declare function resolveCommandTimeoutMs(env?: NodeJS.ProcessEnv, fallback?: number): number;
 /**
  * 压缩验证命令输出为报告可读的摘要（首尾各取若干行，超长中间省略）。
  * 完整输出由日志承载；报告保持紧凑，避免 error 字段失控膨胀。
@@ -1772,12 +2697,6 @@ export declare function formatVerificationError(cr: CommandResult): string;
  * ```
  */
 export declare function runVerification(params: VerificationParams): Promise<VerificationResult>;
-/**
- * 对外暴露以支持单独测试
- */
-export declare function sanitizeOutput(output: string): string;
-//#endregion
-//#region src/alerts/pnpm-audit-fetcher.d.ts
 /**
  * pnpm audit 本地回退数据源（无 GitHub token 场景）。
  *
@@ -1811,6 +2730,8 @@ interface RiskRecord {
   ghsaId?: string;
   /** CVE ID 列表（pnpm audit `advisory.cves[]` 字符串数组） */
   cveIds?: string[];
+  /** 依赖链路径（`advisories[].findings[].paths[]` 合并去重，每项一条完整链） */
+  dependencyPaths?: string[];
 }
 /**
  * 解析 pnpm audit 报告（legacy + modern 双格式），按
@@ -1818,17 +2739,15 @@ interface RiskRecord {
  */
 export declare function parseAuditReport(report: unknown): RiskRecord[];
 /**
- * advisoryId 的稳定数字哈希（M20 之前使用，M20 后保留以维持向后兼容 `NormalizedSecurityAlert.id: number`）。
+ * advisoryId 的稳定数字哈希（保留以维持向后兼容 `NormalizedSecurityAlert.id: number`）。
  *
  * 取 sha256 前 4 字节完整 uint32（非设计稿的 `% 2^31`：uint32 语义更自然，
  * 碰撞概率 ~2^-32/对，12 条告警场景生日界 ~1.6e-8，可忽略）。
  *
- * M20 弃用：唯一去重键改为 `upstreamId`，详见 [`normalizeUpstreamId`](../../../core/src/alerts/upstream-id.ts)。
+ * 已弃用：唯一去重键改为 `upstreamId`，详见 [`normalizeUpstreamId`](../../../core/src/alerts/upstream-id.ts)。
  * 本函数保留仅为兼容现有 `NormalizedSecurityAlert.id: number` 字段，**不是**平台去重键。
  */
 export declare function hashAdvisoryId(packageName: string, advisoryId: string): number;
-//#endregion
-//#region src/ai/provider.d.ts
 interface AiConfig {
   /** 提供商类型：openai-compatible（默认）/ anthropic */
   provider: 'openai-compatible' | 'anthropic';
@@ -1863,8 +2782,6 @@ interface AiChatResult {
   text: string;
   usage: AiChatUsage;
 }
-//#endregion
-//#region src/ai/schema.d.ts
 declare const replaceBlockSchema: z.ZodObject<{
   search: z.ZodString;
   replace: z.ZodString;
@@ -1897,8 +2814,6 @@ declare const assessmentSchema: z.ZodObject<{
 type AiAssessment = z.infer<typeof assessmentSchema>;
 type AiFileChange = z.infer<typeof fileChangeSchema>;
 type AiReplaceBlock = z.infer<typeof replaceBlockSchema>;
-//#endregion
-//#region src/ai/changelog-fetcher.d.ts
 interface ChangelogEntry {
   /** release 版本号（tag_name 原样保留，可能为 `v1.2.3` 形态） */
   version: string;
@@ -1909,8 +2824,6 @@ interface ChangelogEntry {
   /** release 页面地址 */
   htmlUrl: string;
 }
-//#endregion
-//#region src/ai/prompt.d.ts
 interface AssessmentContextInput {
   packageName: string;
   fromVersion: string;
@@ -1922,8 +2835,6 @@ interface AssessmentContextInput {
   /** 受影响文件路径列表（可选） */
   affectedFiles?: string[];
 }
-//#endregion
-//#region src/ai/secrets.d.ts
 /**
  * 对文本中的敏感值做脱敏替换（保留首 4 尾 4 字符便于定位）。
  *
@@ -1935,8 +2846,6 @@ interface AssessmentContextInput {
  * // → 'call failed with key sk-a****yz'
  */
 export declare function maskSecrets(text: string, secrets: string[]): string;
-//#endregion
-//#region src/ai/index.d.ts
 export interface AssessResult {
   /** 结构化研判（降级时为 null，走建议模式） */
   assessment: AiAssessment | null;
@@ -1970,16 +2879,25 @@ export interface AssessOptions {
  * 降级语义：调用方走建议模式（报告输出人工建议），不静默、可审计。
  */
 export declare function assessBreakingChange(options: AssessOptions): Promise<AssessResult>;
-//#endregion
-//#region src/app/repo-alerts.d.ts
 /**
  * 获取仓库的默认分支。
  * pnpm-audit 模式 client 为 null → 返回 ''（报告显示 local）。
  * 失败时返回 `'unknown'`（不阻塞主流程）。
  */
 export declare function fetchDefaultBranch(client: Octokit | null, owner: string, repo: string): Promise<string>;
-//#endregion
-//#region src/app/index.d.ts
+/**
+ * 输出「部分源拉取失败」汇总（per-source 错误隔离：单源失败不阻断其余源的结果）。
+ *
+ * 触发条件（必须全部满足，避免与"仓库失败"（无任何成功源）语义重叠）：
+ * 1. allErrors 至少包含一个 `stage='fetch' + category='FETCH_FAILED'` 错误（per-source 失败）
+ * 2. **至少一个仓库成功拉取了部分告警**（isAnyRepoSuccessful = true）——
+ *    否则该仓库已按失败处理（无任何成功源），由 processRepoForReport catch + logger.error 单独处理，
+ *    本函数聚焦"warn + 保留成功源"场景的汇总输出，避免重复提示。
+ *
+ * 汇总按 source 分组（'dependabot' / 'code-scanning' / 'code-quality' / 'pnpm-audit'），
+ * 列出每个源失败的仓库数 + 示例错误消息，便于用户快速定位是 token 权限还是网络问题。
+ */
+export declare function logPartialSourceFailureSummary(allErrors: FixError[], logger: Logger, isAnyRepoSuccessful: boolean): void;
 export interface DependfixAppOptions {
   /** 已解析的运行时配置 */
   config: RuntimeConfig;
@@ -2009,20 +2927,8 @@ export interface DependfixRunResult {
   /** 进程退出码：0=全部成功, 1=部分失败, 2=全部失败 */
   exitCode: number;
 }
-/**
- * 输出"部分源拉取失败"汇总（todo.md §M19.5 C8 per-source 错误隔离）。
- *
- * 触发条件（必须全部满足，避免与"全部源失败"语义重叠）：
- * 1. allErrors 至少包含一个 `stage='fetch' + category='FETCH_FAILED'` 错误（per-source 失败）
- * 2. **至少一个仓库成功拉取了部分告警**（isAnyRepoSuccessful = true）——
- *    否则就是"全部源失败"语义，已由 processRepoForReport catch + logger.error 单独处理，
- *    本函数聚焦"warn + 保留成功源"场景的汇总输出，避免重复提示。
- *
- * 汇总按 source 分组（'dependabot' / 'code-scanning' / 'code-quality' / 'pnpm-audit'），
- * 列出每个源失败的仓库数 + 示例错误消息，便于用户快速定位是 token 权限还是网络问题。
- */
-export declare function logPartialSourceFailureSummary(allErrors: FixError[], logger: Logger, isAnyRepoSuccessful: boolean): void;
 export declare class DependfixApp {
+  /** 运行时配置；构造期按「中央配置优先」合并目标仓库专属配置后单次赋值（见 applyRepoConfig） */
   private readonly config;
   private readonly workDir;
   private readonly reportOutputDir;
@@ -2031,9 +2937,15 @@ export declare class DependfixApp {
   private readonly customCommands?;
   private readonly executionEnvironment;
   private readonly runId;
+  /** GitHub App 认证提供者（用于 commit author 真实 bot 身份；仅 fix/fix-and-pr 模式生效） */
+  private readonly githubAppAuth?;
+  /** 运行构建版本回执（`[build]` 启动行；平台注入优先，CLI 回退包版本） */
+  private readonly buildInfo;
   private readonly allAlerts;
   private readonly allActions;
   private readonly allErrors;
+  /** alerts 功能未启用记录（未启用 ≠ 失败，不计入 allErrors / exitCode） */
+  private readonly alertsDisabled;
   private readonly repoResults;
   private readonly summary;
   /** run 级 AI 用量聚合（--ai 实际调用时填充；报告 aiUsage 段数据源；由 repo-fix 管线步骤回写） */
@@ -2042,7 +2954,36 @@ export declare class DependfixApp {
   private finishedAt;
   /** 运行前工作区是否已有未提交改动（验证门禁回滚保护：避免销毁用户本地工作） */
   private preExistingDirty;
+  /** 运行级修复前基线（跨仓库复用；惰性首采，零告警不采样）。 */
+  private verificationBaseline;
+  /** 单元回滚 checkpoint（单元 probe 开始前记录，跨仓库传递）。 */
+  private readonly verificationCheckpoints;
+  /** 验证链口径记录（run 级；`verifyProject` 写入，报告与 PR 正文消费） */
+  private readonly ciAlignment;
+  /** 最近关闭 PR 的尝试索引（run 级缓存；仅 fix-and-pr 模式参与判定） */
+  private readonly attemptIndex;
+  /** 同告警尝试记录（run 级；报告与 PR 正文标记数据源） */
+  private readonly attemptTracking;
+  /** PR 落点仓库（第一个仓库；尝试标记只能写进该仓库的 PR） */
+  private attemptRepo;
+  /** PR check 回环结果（run 级；仅在 `--wait-pr-checks` 且创建 PR 时递增） */
+  private readonly prCheckWatchReport;
+  /** 交付跳过记录（基线红；`computeSummary` 据此派生 summary 计数） */
+  private readonly deliverySkips;
+  /** 已记录的预算跳过（`stage:work`；逐包命中不刷审计） */
+  private readonly budgetSkips;
+  /** `draft` 档的跳过记录（sanity: PR 创建后回填载体编号） */
+  private baselineRedDraft?;
+  private readonly alertOutcomes;
   constructor(options: DependfixAppOptions);
+  /**
+   * 请求中止本次运行（平台执行超时 / 运维中止的接入点；协作式、可重复调用）。
+   *
+   * 语义与留痕口径见 [app/abort.ts](./abort.ts) 的 `recordRunAbort`；核心三步：
+   * ① 立即终止在跑子进程树；② 不再启动新工作（仓库边界 / 验证链 / 安装命令三重短路）；
+   * ③ 放弃交付（半成品不落地）。不抛错、不中断调用栈。
+   */
+  abort(reason?: string): void;
   /** 供辅助方法使用的状态切片。 */
   private get ctx();
   /** 执行完整的编排流程，返回结构化结果和退出码。 */
@@ -2057,7 +2998,6 @@ export declare class DependfixApp {
   private runStartupSecurityChecks;
   private executeMode;
   private executeReportMode;
-  private processRepoForReport;
   private executeFixMode;
   private processRepoForFix;
   /**
@@ -2078,16 +3018,6 @@ export declare class DependfixApp {
    * - dry-run 模式仅列清单并打印 "would delete"，不执行删除
    */
   private executeCleanupBranchesMode;
-  /**
-   * 重复 PR 处理：在新 PR 上添加评论指向被取代的旧 PR + 添加 `duplicate` label。
-   *
-   * 失败仅记录 warning（家务活 best-effort），不阻断主流程：
-   * - 新 PR 已创建成功，用户已可访问
-   * - 评论失败不影响 PR 本身的可用性
-   * - 但需要 `issues: write` token scope（比 `pull-requests: write` 宽）；
-   *   若 token 权限不足，error 会被记录但不阻塞
-   */
-  private handleDuplicatePRs;
   /**
    * 多仓库并发执行管线。
    *
@@ -2108,10 +3038,6 @@ export declare class DependfixApp {
    * - 未配置 `--owner`：沿用现有 resolveAlertRepositories 语义
    */
   private resolveRepositories;
-  /** pnpm-audit 模式不创建 GitHub client（无 token）；github-dependabot 模式返回主 token client。 */
-  private githubClientOrNull;
-  private createClient;
 }
-//#endregion
-export type { AiAssessment, AiChatResult, AiConfig, AiFileChange, AiReplaceBlock, AiUsage, AlertClass, AlertSourceKind, AssessmentContextInput, AuthProvider, AuthProviderOptions, FromAppParams, FromPatParams, SeverityThreshold };
+export type { AiAssessment, AiChatResult, AiConfig, AiFileChange, AiReplaceBlock, AiUsage, AlertClass, AlertSourceKind, AssessmentContextInput, AuthProvider, AuthProviderOptions, FromAppParams, FromPatParams, ManifestUpgradeApplied, OverrideUpsert, PackageJson, SeverityThreshold, VersionedOverridesApplyResult, VersionedOverridesPlan };
 //# sourceMappingURL=index.d.mts.map