@dependfix/engine 0.1.3 → 0.4.0

package/dist/index.d.mts

@@ -1,8 +1,9 @@
+import { i as FromPatParams, n as AuthProviderOptions, r as FromAppParams, t as AuthProvider } from "./auth-provider.mjs";
 import { Octokit } from "@octokit/rest";
-import { AlertClass, AlertSourceKind, AppError, FixAction, FixError, Logger, NormalizedSecurityAlert, RepositoryResult, RunResult, RunSummary, SeverityThreshold, createEmptyRunSummary } from "@dependfix/core";
+import { AlertClass, AlertSeverity, AlertSourceKind, AppError, FixAction, FixError, Logger, NormalizedSecurityAlert, RepositoryResult, RunResult, RunSummary, SeverityThreshold, createEmptyRunSummary } from "@dependfix/core";
 import { z } from "zod";
 //#region src/github/client.d.ts
-interface RetryPolicyOptions {
+export interface RetryPolicyOptions {
   /** 最大重试次数（默认 3；0 = 不重试） */
   maxRetries?: number;
   /** 指数退避基数毫秒（默认 1000；测试时可调小） */
@@ -13,9 +14,25 @@ interface RetryPolicyOptions {
    */
   maxBackoffMs?: number;
 }
-interface OctokitClientOptions {
-  /** GitHub Personal Access Token */
-  token: string;
+export interface OctokitClientOptions {
+  /**
+   * 认证抽象层（M18.1 实施后唯一推荐入口）。
+   *
+   * 调用方应通过 `fromPat(token)` 或 `fromApp(params)` 构造；
+   * 优先使用此字段，新代码不得使用 deprecated 的 `token` 字段。
+   *
+   * @see {@link ../auth/auth-provider} AuthProvider 接口定义
+   * @see [C22 PAT 无感升级评估 §4.2 AuthProvider 接口设计](../../../../docs/design/governance/c22-pat-backward-compat.md)
+   */
+  auth?: AuthProvider;
+  /**
+   * @deprecated 使用 `auth` 替代。
+   *
+   * 保留作为低层入口；`token` 路径与 `auth: fromPat(token)` 行为等价
+   * （共享同一 retry policy 与限流重试 hook）。
+   * 计划在 M19+ 评估移除。
+   */
+  token?: string;
   /**
    * API 基地址。
    * 默认 `https://api.github.com`。
@@ -27,6 +44,10 @@ interface OctokitClientOptions {
    * 默认 maxRetries=3。对 429、primary rate limit（403 + x-ratelimit-remaining: 0）、
    * secondary rate limit（403/429 带 secondary/abuse/retry 特征）自动退避重试；
    * 权限类 403 不重试。
+   *
+   * 行为由具体 AuthProvider 实现决定：
+   * - `PatAuthProvider` 委托给本函数（`createGitHubClient({ token, retry })`）—— retry 字段透传生效
+   * - `AppAuthProvider` 自管 retry（commit 4 实施）
    */
   retry?: RetryPolicyOptions;
 }
@@ -41,6 +62,11 @@ interface OctokitClientOptions {
  *
  * @example
  * ```typescript
+ * // 推荐：使用 auth 抽象层（M18.1 实施后）
+ * import { fromPat } from '@dependfix/engine/auth'
+ * const octokit = createGitHubClient({ auth: fromPat('ghp_xxxx') })
+ *
+ * // 向后兼容：使用 token 字段（deprecated）
  * const octokit = createGitHubClient({ token: 'ghp_xxxx' })
  *
  * // 仓库信息
@@ -53,7 +79,7 @@ interface OctokitClientOptions {
  * )
  * ```
  */
-declare function createGitHubClient(options: OctokitClientOptions): Octokit;
+export declare function createGitHubClient(options: OctokitClientOptions): Octokit;
 /**
  * 计算限流重试等待时间（纯函数，可单测）。
  *
@@ -73,10 +99,52 @@ declare function createGitHubClient(options: OctokitClientOptions): Octokit;
  * - 权限类 403（无限流特征）
  * - 其他状态码
  */
-declare function computeRetryDelayMs(error: unknown, attempt: number, baseDelayMs?: number, maxBackoffMs?: number): number | null;
+export declare function computeRetryDelayMs(error: unknown, attempt: number, baseDelayMs?: number, maxBackoffMs?: number): number | null;
+//#endregion
+//#region src/github/code-quality-fetcher.d.ts
+export interface FetchCodeQualityFindingsParams {
+  /** 仓库所属组织或用户 */
+  owner: string;
+  /** 仓库名称 */
+  repo: string;
+  /**
+   * 告警状态过滤。
+   * 默认 `open`；GitHub 合法值 `open` / `resolved` / `dismissed`。
+   */
+  state?: 'open' | 'resolved' | 'dismissed';
+  /** 每页数量，默认 100（GitHub API 最大值） */
+  perPage?: number;
+}
+/**
+ * 拉取指定仓库的 Code Quality findings 并映射为标准化模型。
+ *
+ * - 自动分页（cursor-based：before/after 走 `Link` header，与 GitHub 通用分页一致）
+ * - 仅处理 `state=open` 的 finding（可通过 `params.state` 覆盖）
+ * - severity：`rule.severity`（error/warning/note）经 `mapCodeQualitySeverity` 映射
+ * - Code Quality findings **不可自动修复**（`fixable: false`、`fixStrategy: null`），
+ *   首版统一归 C 类（`alertClass: 'report-only'`），不实现模板化修复
+ * - 异常通过 `mapGitHubError` 转为 `AppError`
+ * - 空仓库返回 `[]`，不抛异常
+ *
+ * @param client - 已认证的 Octokit 实例（来自 `createGitHubClient`）
+ * @param params - 仓库标识与过滤参数
+ * @returns 标准化告警列表
+ */
+export declare function fetchCodeQualityFindings(client: Octokit, params: FetchCodeQualityFindingsParams): Promise<NormalizedSecurityAlert[]>;
+/**
+ * 映射 Code Quality severity：
+ * - `error` → `high`（语义对齐 code-scanning 映射：error 表示需立即关注）
+ * - `warning` → `medium`
+ * - `note` → `low`
+ * - 缺失或非法值 → `'unknown'`（不静默丢弃）
+ *
+ * 与 code-scanning 共用 `error/warning/note` 值域（GitHub CodeQL 规则同源），
+ * 映射口径与 `mapCodeScanningSeverity` 对齐（避免新源不一致）。
+ */
+export declare function mapCodeQualitySeverity(severity: string | null | undefined): AlertSeverity;
 //#endregion
 //#region src/github/code-scanning-fetcher.d.ts
-interface FetchCodeScanningAlertsParams {
+export interface FetchCodeScanningAlertsParams {
   /** 仓库所属组织或用户 */
   owner: string;
   /** 仓库名称 */
@@ -105,10 +173,10 @@ interface FetchCodeScanningAlertsParams {
  * @param params - 仓库标识与过滤参数
  * @returns 标准化告警列表
  */
-declare function fetchCodeScanningAlerts(client: Octokit, params: FetchCodeScanningAlertsParams): Promise<NormalizedSecurityAlert[]>;
+export declare function fetchCodeScanningAlerts(client: Octokit, params: FetchCodeScanningAlertsParams): Promise<NormalizedSecurityAlert[]>;
 //#endregion
 //#region src/github/dependabot-fetcher.d.ts
-interface FetchDependabotAlertsParams {
+export interface FetchDependabotAlertsParams {
   /** 仓库所属组织或用户 */
   owner: string;
   /** 仓库名称 */
@@ -135,11 +203,16 @@ interface FetchDependabotAlertsParams {
  *
  * @example
  * ```typescript
- * const octokit = createGitHubClient({ token: 'ghp_xxxx' })
+ * // 推荐：使用 auth 抽象层（M18.1 实施后）
+ * import { fromPat } from '@dependfix/engine/auth'
+ * const octokit = createGitHubClient({ auth: fromPat('ghp_xxxx') })
  * const alerts = await fetchDependabotAlerts(octokit, { owner: 'foo', repo: 'bar' })
+ *
+ * // 向后兼容：使用 token 字段（deprecated）
+ * const octokit = createGitHubClient({ token: 'ghp_xxxx' })
  * ```
  */
-declare function fetchDependabotAlerts(client: Octokit, params: FetchDependabotAlertsParams): Promise<NormalizedSecurityAlert[]>;
+export declare function fetchDependabotAlerts(client: Octokit, params: FetchDependabotAlertsParams): Promise<NormalizedSecurityAlert[]>;
 //#endregion
 //#region src/github/errors.d.ts
 /**
@@ -148,10 +221,10 @@ declare function fetchDependabotAlerts(client: Octokit, params: FetchDependabotA
  * @param error   - 原始错误（`RequestError` 或网络异常）
  * @param context - 调用上下文描述（如 `'fetch repo info for foo/bar'`），会附加到错误消息中
  */
-declare function mapGitHubError(error: unknown, context: string): AppError;
+export declare function mapGitHubError(error: unknown, context: string): AppError;
 //#endregion
 //#region src/github/pr-creator.d.ts
-interface CreatePullRequestParams {
+export interface CreatePullRequestParams {
   /** 已认证的 Octokit 实例 */
   octokit: Octokit;
   /** 仓库 owner */
@@ -167,20 +240,20 @@ interface CreatePullRequestParams {
   /** PR 内容（Markdown） */
   body: string;
 }
-interface PullRequestResult {
+export interface PullRequestResult {
   /** PR 编号 */
   number: number;
   /** PR HTML URL */
   htmlUrl: string;
 }
-interface FixBranchResult {
+export interface FixBranchResult {
   /** 分支名 */
   branchName: string;
   /** 是否为新创建 */
   created: boolean;
 }
 /** dependfix 自动修复 PR 的公开信息（用于查重/取代判定） */
-interface DependfixOpenPR {
+export interface DependfixOpenPR {
   /** PR 编号 */
   number: number;
   /** PR HTML URL */
@@ -203,15 +276,15 @@ interface DependfixOpenPR {
  * 不用 diff hash 是因为 pnpm 版本等非确定性因素会使锁文件内容漂移，
  * 导致"告警没变但指纹变"。
  */
-declare function computeFixFingerprint(actions: FixAction[]): string;
+export declare function computeFixFingerprint(actions: FixAction[]): string;
 /**
  * 从分支名提取内容指纹（`dependfix/auto-fix-{fp8}` → `{fp8}`）。
  * 指纹格式为 8 位 hex；分支名不含 `-` 后的内容、前缀不匹配或格式不合法时返回 null
  * （如旧版 runId 分支，会被 supersede）。
  */
-declare function extractFingerprintFromBranch(branchName: string): string | null;
+export declare function extractFingerprintFromBranch(branchName: string): string | null;
 /** fix-and-pr 去重决策结果 */
-interface FixAndPrPlan {
+export interface FixAndPrPlan {
   /** skip = 已有同内容 PR，不重复提交；create = 需要新建 PR */
   action: 'skip' | 'create';
   /** action=skip 时命中的同内容 PR */
@@ -224,7 +297,7 @@ interface FixAndPrPlan {
  * - 存在同指纹 open PR → skip（仅需关闭其余异指纹 PR）
  * - 否则 → create（关闭全部旧 PR，先建新后关旧由调用方保证）
  */
-declare function computeFixAndPrPlan(existingPRs: DependfixOpenPR[], fingerprint: string): FixAndPrPlan;
+export declare function computeFixAndPrPlan(existingPRs: DependfixOpenPR[], fingerprint: string): FixAndPrPlan;
 /**
  * 在工作目录创建修复分支。
  *
@@ -233,18 +306,27 @@ declare function computeFixAndPrPlan(existingPRs: DependfixOpenPR[], fingerprint
  *
  * @returns 分支名和是否为新创建
  */
-declare function createFixBranch(branchName: string, workDir: string): FixBranchResult;
+export declare function createFixBranch(branchName: string, workDir: string): 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。
+ *
+ * @see [C22 PAT 无感升级评估 §5.1 兼容性](../../../../docs/design/governance/c22-pat-backward-compat.md)
  */
-declare function stageAndCommit(message: string, workDir: string): void;
-/**
- * 推送分支到远程 origin。
- */
-declare function pushBranch(branchName: string, workDir: string): void;
+export declare function stageAndCommit(message: string, workDir: string, author?: {
+  name: string;
+  email: string;
+}): void;
+export declare function pushBranch(branchName: string, workDir: string): void;
 /**
  * 查找目标仓库中所有 open 状态的 dependfix 自动修复 PR。
  *
@@ -252,17 +334,35 @@ declare function pushBranch(branchName: string, workDir: string): void;
  * 按 head 分支前缀 `dependfix/auto-fix-` 过滤。假设 PR 数量不多（单页 100 足够），
  * 未来 PR 数量增大时可引入 label 索引（backlog 已登记演进项）。
  */
-declare function findDependfixOpenPR(octokit: Octokit, owner: string, repo: string): Promise<DependfixOpenPR[]>;
+export declare function findDependfixOpenPR(octokit: Octokit, owner: string, repo: string): Promise<DependfixOpenPR[]>;
 /**
  * 关闭 Pull Request（用于 supersede 旧 PR）。
  */
-declare function closePullRequest(octokit: Octokit, owner: string, repo: string, pullNumber: number): Promise<void>;
+export declare function closePullRequest(octokit: Octokit, owner: string, repo: string, pullNumber: number): Promise<void>;
+/**
+ * 在 Pull Request 上添加评论。
+ *
+ * 使用 `issues.createComment` 端点（GitHub PR 评论复用 issue comment API），
+ * 需要 token 具备 `issues: write` 权限（比 `pull-requests: write` 宽）。
+ *
+ * 用于在新 PR 上评论指向被取代的旧 PR，避免用户手动排查重复 PR。
+ */
+export declare function commentOnPullRequest(octokit: Octokit, owner: string, repo: string, pullNumber: number, body: string): Promise<void>;
+/**
+ * 在 Pull Request 上添加 label。
+ *
+ * 使用 `issues.addLabels` 端点（GitHub PR label 复用 issue label API），
+ * 需要 token 具备 `issues: write` 权限。
+ *
+ * 用于标记重复 PR（如 `duplicate` label），便于用户过滤和管理。
+ */
+export declare function addLabelToPullRequest(octokit: Octokit, owner: string, repo: string, pullNumber: number, labels: string[]): Promise<void>;
 /**
  * 通过 GitHub API 创建 Pull Request。
  */
-declare function createPullRequest(params: CreatePullRequestParams): Promise<PullRequestResult>;
+export declare function createPullRequest(params: CreatePullRequestParams): Promise<PullRequestResult>;
 /** 分支清理状态（用于 cleanup-branches 清单分类） */
-interface DependfixBranchStatus {
+export interface DependfixBranchStatus {
   /** 分支名 */
   branch: string;
   /** 关联 PR 编号（无 PR 记录时为 null） */
@@ -275,19 +375,19 @@ interface DependfixBranchStatus {
 /**
  * 列出远端所有 `dependfix/` 前缀分支（git.listMatchingRefs 精确前缀匹配）。
  */
-declare function listDependfixBranches(octokit: Octokit, owner: string, repo: string): Promise<string[]>;
+export declare function listDependfixBranches(octokit: Octokit, owner: string, repo: string): Promise<string[]>;
 /**
  * 查询分支对应的最近 PR 状态（pulls.list head 精确匹配，按最近更新取 1 条）。
  */
-declare function getBranchPrStatus(octokit: Octokit, owner: string, repo: string, branch: string): Promise<DependfixBranchStatus>;
+export declare function getBranchPrStatus(octokit: Octokit, owner: string, repo: string, branch: string): Promise<DependfixBranchStatus>;
 /**
  * 删除远端分支（git ref delete）。失败（分支保护、不存在）由调用方捕获处理。
  */
-declare function deleteRemoteBranch(octokit: Octokit, owner: string, repo: string, branch: string): Promise<void>;
+export declare function deleteRemoteBranch(octokit: Octokit, owner: string, repo: string, branch: string): Promise<void>;
 /**
  * 判定交互确认回答是否为"是"（y/yes，大小写不敏感；空输入默认拒绝）。
  */
-declare function isConfirmAnswer(answer: string): boolean;
+export declare function isConfirmAnswer(answer: string): boolean;
 /**
  * 从 RunResult 生成 PR body（Markdown）。
  *
@@ -299,11 +399,11 @@ declare function isConfirmAnswer(answer: string): boolean;
  *
  * @param supersededNumbers 被本 PR 取代并已关闭的旧 PR 编号列表（用于 Supersedes 声明）
  */
-declare function generatePRBody(result: RunResult, supersededNumbers?: number[]): string;
+export declare function generatePRBody(result: RunResult, supersededNumbers?: number[]): string;
 //#endregion
 //#region src/github/repo-policy.d.ts
 /** 单条 glob 模式长度上限（加固：防止超长模式引入匹配开销；受信配置 + 短输入） */
-declare const MAX_GLOB_PATTERN_LENGTH = 200;
+export declare const MAX_GLOB_PATTERN_LENGTH = 200;
 /**
  * 将仓库 glob 模式转正则（`owner/*`、`owner/pkg-*`）。
  *
@@ -317,10 +417,10 @@ declare const MAX_GLOB_PATTERN_LENGTH = 200;
  * 多通配符模式存在理论 O(n^k) 回溯面（`[^/]*` 单层字符类、输入 ≤ ~140 字符，风险低）；
  * 正则引擎演进时需专项 ReDoS 审计。
  */
-declare function repoGlobToRegExp(pattern: string): RegExp;
+export declare function repoGlobToRegExp(pattern: string): RegExp;
 /** glob 模式匹配 `owner/repo`（完整匹配）。 */
-declare function matchesRepoGlob(pattern: string, fullName: string): boolean;
-interface RepoPolicy {
+export declare function matchesRepoGlob(pattern: string, fullName: string): boolean;
+export interface RepoPolicy {
   /** 白名单 glob（仅作用于发现结果；显式列表不受影响） */
   include?: string[];
   /** 黑名单 glob（显式列表 + 发现结果均受约束；与 include 冲突时胜出） */
@@ -329,30 +429,30 @@ interface RepoPolicy {
   topicsExclude?: string[];
 }
 /** 是否命中任一 exclude 模式（黑名单）。 */
-declare function matchesRepoExclude(policy: RepoPolicy, fullName: string): boolean;
+export declare function matchesRepoExclude(policy: RepoPolicy, fullName: string): boolean;
 /** 是否通过 include 白名单（include 为空 = 不限制；非空 = 必须命中任一模式）。 */
-declare function matchesRepoInclude(policy: RepoPolicy, fullName: string): boolean;
+export declare function matchesRepoInclude(policy: RepoPolicy, fullName: string): boolean;
 /** topic 黑名单：仓库 topics 含任一指定 topic 即排除（大小写归一化后比较）。 */
-declare function matchesTopicsExclude(policy: RepoPolicy, topics: string[]): boolean;
+export declare function matchesTopicsExclude(policy: RepoPolicy, topics: string[]): boolean;
 /**
  * 过滤显式仓库列表：仅受 exclude 约束（白名单 include 不适用于显式列表，
  * 设计要点：显式优先，用户显式指定的仓库不应被 include 静默剔除）。
  */
-declare function filterExplicitRepositories(policy: RepoPolicy, repositories: string[]): string[];
+export declare function filterExplicitRepositories(policy: RepoPolicy, repositories: string[]): string[];
 //#endregion
 //#region src/github/repo-selector.d.ts
 /**
  * 从文件读取仓库列表（每行一个 `owner/repo`）。
  * 空行和 `#` 开头的注释行会被跳过。
  */
-declare function readReposFile(filePath: string): string[];
+export declare function readReposFile(filePath: string): string[];
 /**
  * 合并 CLI 传入仓库列表与文件中的仓库列表，去重并校验。
  */
-declare function resolveRepoList(cliRepos: string[], reposFilePath?: string): string[];
+export declare function resolveRepoList(cliRepos: string[], reposFilePath?: string): string[];
 //#endregion
 //#region src/github/repository-discovery.d.ts
-interface RepositoryDiscoveryOptions {
+export interface RepositoryDiscoveryOptions {
   /** 已认证的 Octokit 实例 */
   client: Octokit;
   /** owner / org 列表（分别拉取后合并） */
@@ -376,8 +476,14 @@ interface RepositoryDiscoveryOptions {
   probeDependabot?: boolean;
   /** dependabot.yml 探测并发上限（默认 5，避免一次性打爆 API） */
   probeConcurrency?: number;
+  /**
+   * 发现规模上限：最多保留的仓库数（按 fullName 字典序排序后截断）。
+   * 默认 100；设为 0 或负数表示不限制。
+   * 大 org 场景下防止一次性全量发现导致 API 配额不可控消耗和超时。
+   */
+  maxRepos?: number;
 }
-interface DiscoveredRepository {
+export interface DiscoveredRepository {
   /** `owner/repo` 格式 */
   fullName: string;
   defaultBranch: string;
@@ -393,24 +499,80 @@ interface DiscoveredRepository {
  * 2. topic 过滤（`--repo-topics`，AND 语义）
  * 3. 名单策略过滤（include / exclude / topicsExclude，探测前应用）
  * 4. dependabot.yml 探测（仅候选仓库触达 contents API；404 视为不支持，不剔除）
+ * 5. 规模上限截断（`maxRepos`，按 fullName 字典序排序后截断）
  *
  * 结果按 `fullName` 字典序排序，保证同输入多次运行结果一致
  * （runId / 指纹稳定性前提）。
  *
  * @throws AppError（mapGitHubError 转换；token 权限、网络等全局性问题 fail-fast）
  */
-declare function discoverRepositories(options: RepositoryDiscoveryOptions): Promise<DiscoveredRepository[]>;
+export declare function discoverRepositories(options: RepositoryDiscoveryOptions): Promise<DiscoveredRepository[]>;
 /**
  * 合并显式仓库列表与发现结果：
  * - 显式优先：显式列表保持原顺序且在前
  * - 发现结果仅补充未出现的项（去重；大小写不敏感——GitHub full_name 恒小写，
  *   显式 `Owner/Repo` 与发现 `owner/repo` 视为同一仓库）
  */
-declare function mergeRepositories(explicit: string[], discovered: string[]): string[];
+export declare function mergeRepositories(explicit: string[], discovered: string[]): string[];
+//#endregion
+//#region src/github/token-scope.d.ts
+/**
+ * 凭据权限面启动检查（安全治理：超权限 token 启动即警告）。
+ *
+ * 判定依据 GitHub API 的 `GET /user` 响应头：
+ * - `x-oauth-scopes`：classic PAT 的 scope 列表（`repo` 即全量仓库权限）
+ * - `x-accepted-github-permissions`：fine-grained PAT / 内置 GITHUB_TOKEN 的
+ *   已接受权限列表（`resource: access` 格式）
+ *
+ * 语义：最小权限 = fine-grained token（仅目标仓库的
+ * `contents`/`pull-requests` 写 + `security-events` 读 + `metadata` 读）。
+ * classic PAT 的 `repo` scope 是全量仓库权限，属于超权限——一旦被恶意
+ * 依赖脚本窃取即可接管所有可见仓库（威胁链 B 路径的最终防线是凭据权限面）。
+ * 检查为 best-effort：网络失败 / 无 token / 无法判定时静默跳过，不阻断运行。
+ */
+export interface TokenScopeWarning {
+  code: 'CLASSIC_REPO_SCOPE' | 'MISSING_SECURITY_EVENTS';
+  message: string;
+}
+export interface TokenScopeAnalysis {
+  /** classic PAT 的 scopes（x-oauth-scopes 解析结果） */
+  scopes?: string[];
+  /** fine-grained PAT 的 accepted permissions（x-accepted-github-permissions 解析结果） */
+  acceptedPermissions?: string[];
+  /** 需要提示用户的权限问题（空 = 无问题） */
+  warnings: TokenScopeWarning[];
+}
+export interface TokenScopeCheckResult extends TokenScopeAnalysis {
+  /** 探测是否成功（鉴权/网络失败为 false，调用方静默跳过） */
+  ok: boolean;
+  /** 认证用户登录名（探测成功时填充） */
+  login?: string;
+}
+/**
+ * 解析 GitHub token 权限面并输出警告（纯函数，可单测）。
+ *
+ * @param scopeHeader `GET /user` 响应的 `x-oauth-scopes` 头（classic PAT 才有值）
+ * @param acceptedHeader `GET /user` 响应的 `x-accepted-github-permissions` 头（fine-grained / 内置 token 才有值）
+ * @param options.codeScanningEnabled 是否开启 Code Scanning 源（开启时校验 security-events 权限）
+ */
+export declare function analyzeTokenScope(scopeHeader: string | undefined, acceptedHeader: string | undefined, options?: {
+  codeScanningEnabled?: boolean;
+}): TokenScopeAnalysis;
+/**
+ * 探测 token 权限面（网络调用，best-effort）。
+ * 任何失败（鉴权 401 / 网络错误 / 超时）均静默返回 `ok: false`，不抛错。
+ */
+export declare function checkTokenPermissions(client: Octokit, options?: {
+  codeScanningEnabled?: boolean;
+}): Promise<TokenScopeCheckResult>;
 //#endregion
 //#region src/code-scanning/rule-classifier.d.ts
 /**
- * A 类自动修复白名单：仅收录"删除/改动后不影响程序行为"且**已有修复模板**的规则。
+ * A 类自动修复白名单默认集合（默认值常量；测试 disjointness 不变量用）。
+ *
+ * **与 active config 的关系**：本导出为默认常量（向后兼容历史测试与外部引用），
+ * 运行时 classifyRule 实际从 `getActiveRulesConfig().autoFixable` 读取。
+ * 若配置已被 setActiveRulesConfig 替换，本常量与运行时分类可能不一致（设计意图）。
  *
  * 选择标准（实现时评审确认）：
  * - 可模板化：修复动作可机械描述（删行 / 对齐 / 移除空白）
@@ -425,9 +587,9 @@ declare function mergeRepositories(explicit: string[], discovered: string[]): st
  * 纯格式规则（eol-last 等）实际出现频率低；此处先建立机制，
  * 规则命中与否不影响分层正确性。
  */
-declare const AUTO_FIXABLE_RULES: Set<string>;
+export declare const AUTO_FIXABLE_RULES: ReadonlySet<string>;
 /**
- * B 类建议修复列表：高风险 / 需人工判断的规则。
+ * B 类建议规则默认列表（默认值常量；测试 disjointness 不变量用）。
  *
  * 收录原则：
  * - 安全敏感（注入 / XSS / 路径穿越 / 密码学等），修复需结合业务语义
@@ -440,25 +602,90 @@ declare const AUTO_FIXABLE_RULES: Set<string>;
  * 其余语言（go/ruby/csharp/cpp 等）与未收录变体（如 js/reflected-xss）落 C 类兜底；
  * 真实仓库 API 样本核对（rule id 格式与变体分布）登记为演进项。
  */
-declare const SUGGESTED_RULES: Set<string>;
+export declare const SUGGESTED_RULES: Set<string>;
 /**
  * 规则分类：
  * - A 类白名单 → `'auto-fixable'`
  * - B 类建议列表 → `'suggested'`
  * - 其余（含空字符串）→ `'report-only'`（C 类，默认，不静默丢弃）
+ *
+ * 读取自当前生效配置（`getActiveRulesConfig()`）；首次调用前需通过
+ * `setActiveRulesConfig` 替换或保持默认。
+ */
+export declare function classifyRule(ruleId: string | null | undefined): AlertClass;
+/**
+ * B 类建议规则的人工修复方向（报告/PR body 建议区块展示）。
+ * 读取自当前生效配置（`getActiveRulesConfig().suggested`）；未收录规则返回通用建议（C 类兜底，不静默）。
  */
-declare function classifyRule(ruleId: string | null | undefined): AlertClass;
-/** 生成修复建议方向文本；未知规则返回通用建议（C 类兜底）。 */
-declare function suggestionFor(ruleId: string | null | undefined): string;
+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 后用于匹配；空串非法） */
+  id: string;
+  /** 分类 */
+  class: RuleClass;
+  /** B 类建议文本（A/C 类可省略） */
+  suggestion?: string;
+}
+export interface RulesConfigFile {
+  rules: RuleConfigEntry[];
+}
+/** 编译后的内部表示：高性能查找（A 类 Set / B 类 Map） */
+export interface CompiledRulesConfig {
+  autoFixable: ReadonlySet<string>;
+  suggested: ReadonlyMap<string, string>;
+}
+/** 默认规则配置（编译后；与既有常量表等价，单点声明保持向后兼容） */
+export declare const DEFAULT_RULES_CONFIG: CompiledRulesConfig;
+/**
+ * 解析 JSON 配置输入为编译后配置。
+ *
+ * 校验规则（全部失败均降级返回 null，由调用方走默认）：
+ * - 顶层必须是对象，含 `rules` 数组
+ * - 每个 entry 必须含非空 `id`（trim 后）、合法 `class`
+ * - 同 id 在多个 class 中出现 → 拒绝（disjointness 不变量）
+ * - suggested 必须含 `suggestion` 字段且非空
+ *
+ * @returns 解析成功 → 编译后配置；失败 → null（调用方降级）
+ */
+export declare function parseRulesConfig(input: unknown): CompiledRulesConfig | null;
+/**
+ * 从 JSON 文件路径加载并编译。读取失败 / 解析失败 / 校验失败 → 返回 null（调用方降级）。
+ */
+export declare function loadRulesConfigFromFile(configPath: string): CompiledRulesConfig | null;
+/** 环境变量名：Code Scanning 规则分类配置文件路径 */
+export declare const RULE_CONFIG_ENV = "CODE_SCANNING_RULES_CONFIG_PATH";
+/**
+ * 从 env 读取 `RULE_CONFIG_ENV` 并尝试加载。
+ *
+ * - env 未设或空 → 返回 null（调用方继续走默认）
+ * - 路径不存在 → 返回 null
+ * - 加载失败 → 返回 null（错误已写入 stderr）
+ */
+export declare function loadRulesConfigFromEnv(env: NodeJS.ProcessEnv): CompiledRulesConfig | null;
+/** 获取当前生效的配置（classifyRule / suggestionFor 内部使用） */
+export declare function getActiveRulesConfig(): CompiledRulesConfig;
+/**
+ * 替换为自定义配置。
+ *
+ * **使用协议**：运行时模块初始化时（如 AppContext 装配）调用一次；
+ * 测试可临时覆盖后通过 `resetActiveRulesConfig` 恢复。频繁切换会破坏
+ * `code-scanning-fetcher` 的可预测行为（同一规则在不同 fetch 中分类不同）。
+ */
+export declare function setActiveRulesConfig(config: CompiledRulesConfig): void;
+/** 重置为默认配置（测试 cleanup + 运行时 fallback） */
+export declare function resetActiveRulesConfig(): void;
 //#endregion
 //#region src/code-scanning/templates.d.ts
-interface TemplateApplyResult {
+export interface TemplateApplyResult {
   /** 修改后的文件内容 */
   content: string;
   /** 是否实际产生修改（false = 文件已合规，无需改动） */
   changed: boolean;
 }
-interface CodeScanningFixTemplate {
+export interface CodeScanningFixTemplate {
   /** 对应规则 id（A 类白名单成员） */
   ruleId: string;
   /**
@@ -471,10 +698,10 @@ interface CodeScanningFixTemplate {
   describe(filePath: string, changed: boolean, alert: NormalizedSecurityAlert): string;
 }
 /** 获取规则对应的修复模板；无模板返回 undefined（调用方回退建议模式）。 */
-declare function getCodeScanningFixTemplate(ruleId: string): CodeScanningFixTemplate | undefined;
+export declare function getCodeScanningFixTemplate(ruleId: string): CodeScanningFixTemplate | undefined;
 //#endregion
 //#region src/fixers/dependency/index.d.ts
-interface UpgradeDependencyParams {
+export interface UpgradeDependencyParams {
   /** 包名（如 `'lodash'`, `'@babel/traverse'`） */
   packageName: string;
   /** 目标精确版本（如 `'4.17.21'`） */
@@ -489,7 +716,7 @@ interface UpgradeDependencyParams {
    */
   manifestDir?: string;
 }
-interface DependencyFixResult {
+export interface DependencyFixResult {
   packageName: string;
   /** 升级前版本声明（保留原始 range 格式，如 `^4.17.20`） */
   fromVersion: string;
@@ -504,7 +731,7 @@ interface DependencyFixResult {
   /** 成功但存在需要用户注意的附加信息（如 overrides 写入位置可能被 pnpm 忽略） */
   warning?: string;
 }
-interface PackageJson {
+export interface PackageJson {
   name?: string;
   dependencies?: Record<string, string>;
   devDependencies?: Record<string, string>;
@@ -535,7 +762,7 @@ interface DependencyInfo {
  * @param params - 包名、目标版本、工作目录、可选成员目录
  * @returns 修复结果
  */
-declare function upgradeDependency(params: UpgradeDependencyParams): Promise<DependencyFixResult>;
+export declare function upgradeDependency(params: UpgradeDependencyParams): Promise<DependencyFixResult>;
 /**
  * 通过 pnpm `overrides` 升级间接（transitive）依赖。
  *
@@ -550,7 +777,7 @@ declare function upgradeDependency(params: UpgradeDependencyParams): Promise<Dep
  * @param params - 包名、目标版本、工作目录
  * @returns 修复结果
  */
-declare function overrideTransitiveDependency(params: UpgradeDependencyParams): Promise<DependencyFixResult>;
+export declare function overrideTransitiveDependency(params: UpgradeDependencyParams): Promise<DependencyFixResult>;
 /**
  * 通过 pnpm `overrides` **批量**写入覆盖条目并执行 install（多版本共存 / 单 major 统一入口）。
  *
@@ -573,7 +800,7 @@ declare function overrideTransitiveDependency(params: UpgradeDependencyParams):
  * @param params - 包名、overrides 映射（`pkg@major` 或 `pkg` → `^target`）、工作目录
  * @returns 修复结果（fromVersion 为空字符串，表示多实例无单一来源版本）
  */
-declare function applyVersionedOverrides(params: {
+export declare function applyVersionedOverrides(params: {
   packageName: string;
   versionedOverrides: Record<string, string>;
   workDir: string;
@@ -587,7 +814,7 @@ declare function applyVersionedOverrides(params: {
  * extractPrefix('4.17.20')   // ''
  * extractPrefix('*')         // '^'  (默认)
  */
-declare function extractPrefix(version: string): string;
+export declare function extractPrefix(version: string): string;
 /**
  * 检测版本声明是否包含包管理器协议前缀
  * （`workspace:` / `catalog:` / `link:` / `file:` / `npm:` / `github:` /
@@ -607,7 +834,7 @@ declare function extractPrefix(version: string): string;
  * isNonSemverDeclaration('gitlab:...')    // true
  * isNonSemverDeclaration('https://...tgz') // true
  */
-declare function isNonSemverDeclaration(version: string): boolean;
+export declare function isNonSemverDeclaration(version: string): boolean;
 /**
  * 从版本声明中提取主版本号（major）。
  * 去除前缀后匹配第一个 semver 段。
@@ -618,7 +845,7 @@ declare function isNonSemverDeclaration(version: string): boolean;
  * parseMajorVersion('1.2.3')      // 1
  * parseMajorVersion('*')          // -1
  */
-declare function parseMajorVersion(version: string): number;
+export declare function parseMajorVersion(version: string): number;
 /**
  * 比较两个语义化版本（`x.y.z`，可选 pre-release 后缀）。
  *
@@ -631,16 +858,16 @@ declare function parseMajorVersion(version: string): number;
  * compareSemver('5.4.20', '6.4.3')    // -1
  * compareSemver('1.2.3', '1.2.3')     // 0
  */
-declare function compareSemver(a: string, b: string): number;
+export declare function compareSemver(a: string, b: string): number;
 /**
  * 在 `package.json` 的 `dependencies` / `devDependencies` / `optionalDependencies` 中按顺序查找包。
  */
-declare function findDependencyVersion(pkg: PackageJson, packageName: string): DependencyInfo | null;
+export declare function findDependencyVersion(pkg: PackageJson, packageName: string): DependencyInfo | null;
 /**
  * 确保 `package.json` 中存在 `pnpm.overrides` 对象，若不存在则创建。
  * 返回 `overrides` 对象的引用，调用方可直接写入。
  */
-declare function ensurePnpmOverrides(pkg: PackageJson): Record<string, string>;
+export declare function ensurePnpmOverrides(pkg: PackageJson): Record<string, string>;
 /**
  * 从 `pnpm-lock.yaml` 中读取指定包的**所有**锁定版本实例。
  *
@@ -654,7 +881,7 @@ declare function ensurePnpmOverrides(pkg: PackageJson): Record<string, string>;
  *
  * @returns 去重后的版本列表（如 `['5.4.14', '8.2.0']`），未找到返回 `[]`
  */
-declare function readLockfileVersions(lockfilePath: string, packageName: string): string[];
+export declare function readLockfileVersions(lockfilePath: string, packageName: string): string[];
 /**
  * 从 `pnpm-lock.yaml` 中读取指定包的当前锁定版本。
  *
@@ -663,7 +890,7 @@ declare function readLockfileVersions(lockfilePath: string, packageName: string)
  *
  * @returns 锁定版本字符串（如 `'5.0.0'`），未找到返回 `null`
  */
-declare function readLockfileVersion(lockfilePath: string, packageName: string): string | null;
+export declare function readLockfileVersion(lockfilePath: string, packageName: string): string | null;
 /**
  * 读取当前已生效的 pnpm overrides 映射（与写入位置保持一致）：
  * - 存在 `pnpm-workspace.yaml` → 读取其中 `overrides` 字段（pnpm v10+ 推荐位置）
@@ -675,13 +902,13 @@ declare function readLockfileVersion(lockfilePath: string, packageName: string):
  *
  * @returns 已有 overrides 映射（key → 版本声明）；无配置或解析失败返回 {}
  */
-declare function readExistingOverrides(workDir: string): Record<string, string>;
+export declare function readExistingOverrides(workDir: string): Record<string, string>;
 /**
  * 探测当前 pnpm 大版本（pnpm v10+ 对无 `pnpm-workspace.yaml` 的项目
  * 可能不读取 `package.json#pnpm.overrides`，写入会"假成功"）。
  * 探测失败（pnpm 不可用 / 输出异常）返回 null，调用方降级为不告警。
  */
-declare function detectPnpmMajor(workDir: string): number | null;
+export declare function detectPnpmMajor(workDir: string): number | null;
 /**
  * 跨线修复判定（2026-08-06 复盘 PR #28）。
  *
@@ -695,12 +922,12 @@ declare function detectPnpmMajor(workDir: string): number | null;
  * lockfile 中无该包实例（versions 为空）时返回 false——"无实例"场景由
  * partitionSubmanifestAlerts 的常规跳过逻辑处理，避免重复计数。
  */
-declare function isCrossMajorFixRequired(lockfilePath: string, alert: NormalizedSecurityAlert): boolean;
+export declare function isCrossMajorFixRequired(lockfilePath: string, alert: NormalizedSecurityAlert): boolean;
 //#endregion
 //#region src/fixers/pnpm/index.d.ts
-type LockfileFailureCategory = 'LOCKFILE_NOT_FOUND' | 'MANIFEST_MISMATCH' | 'LOCKFILE_VERSION_MISMATCH' | 'CORRUPTED_LOCKFILE' | 'CREDENTIAL_ERROR' | 'RESOLVE_ERROR' | 'UNKNOWN';
-type RepairStrategy = 'REGENERATE' | 'FIX_ENTRIES' | 'PIN_TOOLCHAIN' | 'REINSTALL' | 'SKIP';
-interface RepairLockfileParams {
+export type LockfileFailureCategory = 'LOCKFILE_NOT_FOUND' | 'MANIFEST_MISMATCH' | 'LOCKFILE_VERSION_MISMATCH' | 'CORRUPTED_LOCKFILE' | 'CREDENTIAL_ERROR' | 'RESOLVE_ERROR' | 'MINIMUM_RELEASE_AGE' | 'UNKNOWN';
+export type RepairStrategy = 'REGENERATE' | 'FIX_ENTRIES' | 'PIN_TOOLCHAIN' | 'REINSTALL' | 'SKIP';
+export interface RepairLockfileParams {
   /** 工作目录（必须包含 package.json 和 pnpm-lock.yaml） */
   workDir: string;
   /** 可选：期望的 pnpm 版本（优先于 packageManager 字段） */
@@ -708,7 +935,7 @@ interface RepairLockfileParams {
     pnpmVersion?: string;
   };
 }
-interface LockfileDiff {
+export interface LockfileDiff {
   /** lockfile 行数变化（正=增加） */
   linesChanged: number;
   /** packages 条数变化（正=增加） */
@@ -716,14 +943,14 @@ interface LockfileDiff {
   /** 简要文字摘要 */
   summary: string;
 }
-interface RepairAttempt {
+export interface RepairAttempt {
   strategy: RepairStrategy;
   command: string;
   success: boolean;
   error?: string;
   durationMs: number;
 }
-interface LockfileRepairResult {
+export interface LockfileRepairResult {
   success: boolean;
   failureCategory?: LockfileFailureCategory;
   failureDetail?: string;
@@ -744,21 +971,21 @@ interface ClassificationResult {
  * 执行 `pnpm i --frozen-lockfile` 并解析失败分类。
  * 成功时返回 { ok: true }。
  */
-declare function classifyLockfileFailure(workDir: string): ClassificationResult;
+export declare function classifyLockfileFailure(workDir: string): ClassificationResult;
 /** 从 lockfile 内容提取 `lockfileVersion` 字段值（如 `9.0`）；缺失返回 null。 */
-declare function extractLockfileVersion(content: string): string | null;
+export declare function extractLockfileVersion(content: string): string | null;
 /**
  * 比较修复前后 lockfile，返回行数与包数量变化摘要。
  */
-declare function computeLockfileDiff(beforePath: string, afterPath: string): LockfileDiff;
+export declare function computeLockfileDiff(beforePath: string, afterPath: string): LockfileDiff;
 /** 校验 pnpm 版本格式是否合法（非法返回 false，调用方回退裸命令/报错）。 */
-declare function isValidPnpmVersion(version: string | undefined | null): version is string;
+export declare function isValidPnpmVersion(version: string | undefined | null): version is string;
 /**
  * 从 package.json 的 `packageManager` 字段解析 pnpm 版本。
  * 优先级: toolchain.pnpmVersion > packageManager > null
  * 非法 toolchain 版本 → 回退 packageManager；两者都非法/缺失 → null（裸命令兜底）。
  */
-declare function resolvePnpmVersion(workDir: string, toolchain?: {
+export declare function resolvePnpmVersion(workDir: string, toolchain?: {
   pnpmVersion?: string;
 }): string | null;
 /**
@@ -774,10 +1001,10 @@ declare function resolvePnpmVersion(workDir: string, toolchain?: {
  *    - 验证失败 → 继续下一个策略
  * 5. 所有策略失败 → 回滚 lockfile、返回失败结果
  */
-declare function repairLockfile(params: RepairLockfileParams): LockfileRepairResult;
+export declare function repairLockfile(params: RepairLockfileParams): LockfileRepairResult;
 //#endregion
 //#region src/fixers/code-scanning/index.d.ts
-interface ApplyCodeScanningFixParams {
+export interface ApplyCodeScanningFixParams {
   /** 工作目录（告警 manifestPath 为相对路径，resolve 后读取） */
   workDir: string;
   alert: NormalizedSecurityAlert;
@@ -790,8 +1017,8 @@ interface ApplyCodeScanningFixParams {
  * 仅处理 `source === 'code-scanning'` 且 `alertClass === 'auto-fixable'` 的告警；
  * 其余返回 `null`（调用方不生成动作记录）。
  */
-declare function applyCodeScanningFix(params: ApplyCodeScanningFixParams): FixAction | null;
-interface SourceFileSnapshot {
+export declare function applyCodeScanningFix(params: ApplyCodeScanningFixParams): FixAction | null;
+export interface SourceFileSnapshot {
   /** 相对路径（告警 manifestPath） */
   path: string;
   /** 快照时文件是否存在 */
@@ -803,12 +1030,12 @@ interface SourceFileSnapshot {
  * 快照单个源码文件（修复前调用；文件不存在时记录 existed:false）。
  * 路径越界返回 null；读取失败返回 null（调用方按失败处理，不中断主流程）。
  */
-declare function snapshotSourceFile(workDir: string, relativePath: string): SourceFileSnapshot | null;
+export declare function snapshotSourceFile(workDir: string, relativePath: string): SourceFileSnapshot | null;
 /**
  * 恢复源码文件（验证失败回滚；原不存在的文件将被删除）。
  * 返回是否恢复成功（写回/删除失败返回 false，调用方在 action.error 记录"可能残留"）。
  */
-declare function restoreSourceFile(workDir: string, snapshot: SourceFileSnapshot): boolean;
+export declare function restoreSourceFile(workDir: string, snapshot: SourceFileSnapshot): boolean;
 /**
  * 将相对路径解析到工作目录内（防 `../` 与绝对路径逃逸；防符号链接逃逸）。
  * 返回 null 表示越界（调用方拒绝处理）。
@@ -819,25 +1046,25 @@ declare function restoreSourceFile(workDir: string, snapshot: SourceFileSnapshot
  * realpath 内；不存在 → 逐级向上对最近存在的父目录做 realpath 校验。
  * 返回**真实路径**（后续读写走真实路径，避免再次经过 symlink）。
  */
-declare function resolveWithinWorkDir(workDir: string, relativePath: string): string | null;
+export declare function resolveWithinWorkDir(workDir: string, relativePath: string): string | null;
 //#endregion
 //#region src/config/index.d.ts
-declare const RUNTIME_MODES: readonly ["report-only", "fix", "fix-and-pr", "cleanup-branches"];
-declare const SEVERITY_THRESHOLDS: readonly ["critical", "high", "medium", "all"];
-declare const ALERT_SOURCES: readonly AlertSourceKind[];
+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[];
 /**
  * 环境变量统一前缀（v0.2 起替代旧项目名遗留的 `AUTO_FIX_GITHUB_SECURITY_`）。
  * 所有环境变量读取必须经由 {@link readEnv}，禁止散落硬编码，防止改名漏网。
  */
-declare const ENV_PREFIX = "DEPENDFIX_";
+export declare const ENV_PREFIX = "DEPENDFIX_";
 /**
  * 从统一前缀读取环境变量。
  * @param env 进程环境
  * @param name 变量名（不含前缀），如 `'MODE'` → `DEPENDFIX_MODE`
  */
-declare function readEnv(env: NodeJS.ProcessEnv, name: string): string | undefined;
-type RuntimeMode = typeof RUNTIME_MODES[number];
-interface RuntimeConfig {
+export declare function readEnv(env: NodeJS.ProcessEnv, name: string): string | undefined;
+export type RuntimeMode = typeof RUNTIME_MODES[number];
+export interface RuntimeConfig {
   mode: RuntimeMode;
   severityThreshold: SeverityThreshold;
   repositories: string[];
@@ -889,6 +1116,14 @@ interface RuntimeConfig {
    * 需要 token 具备 `security-events: read` 权限（GITHUB_TOKEN 默认具备）。
    */
   codeScanningEnabled: boolean;
+  /**
+   * 是否同时拉取 Code Quality findings（与 Dependabot 并行源；可与 codeScanningEnabled 同开）。
+   * 默认关闭（opt-in，向后兼容）；开启后 GitHub 源下 Dependabot + Code Quality
+   * 并行拉取、互不覆盖。Code Quality findings 不可自动修复（首版统一 C 类），
+   * 仅做最小报告接入（不实现 CodeQL 完整语义解析）。
+   * 需要 token 具备 fine-grained `Code quality: read`（classic PAT 需 `repo`/`public_repo`）。
+   */
+  codeQualityEnabled: boolean;
   /**
    * 跨线告警（推荐版本跨大版本）显式授权自动升级（`--allow-major-upgrade`）。
    *
@@ -939,6 +1174,11 @@ interface RuntimeConfig {
    * （由策略链 REGENERATE/REINSTALL 兜底）。
    */
   toolchainPnpmVersion?: string;
+  /**
+   * 发现规模上限（`--max-repos` / `DEPENDFIX_MAX_REPOS`）：最多保留的仓库数。
+   * 默认 100；设为 0 或负数表示不限制。大 org 场景下防止一次性全量发现。
+   */
+  maxRepos: number;
   /**
    * AI 研判配置（`--ai` 系列参数 / `DEPENDFIX_AI_*` env）。
    * 默认关闭（opt-in）；开启后依赖升级验证失败或 major 升级时触发
@@ -953,8 +1193,8 @@ interface RuntimeConfig {
  * - `major`：仅 major 升级时触发
  * - `both`（默认）：验证失败 或 major 升级均触发
  */
-type AiTriggerKind = 'failure' | 'major' | 'both';
-interface AiOptions {
+export type AiTriggerKind = 'failure' | 'major' | 'both';
+export interface AiOptions {
   /** AI 研判总开关（默认 false，opt-in；dry-run 下不触发） */
   enabled: boolean;
   /** 提供商：openai-compatible（默认，DeepSeek 等指定 baseUrl）/ anthropic */
@@ -979,7 +1219,7 @@ interface AiOptions {
   /** 触发范围（默认 both） */
   trigger: AiTriggerKind;
 }
-interface CliConfigOverrides {
+export interface CliConfigOverrides {
   mode?: RuntimeMode;
   severityThreshold?: SeverityThreshold;
   repositories?: string[];
@@ -1007,6 +1247,8 @@ interface CliConfigOverrides {
   alertSource?: AlertSourceKind;
   /** 是否同时拉取 Code Scanning alerts（默认 false） */
   codeScanningEnabled?: boolean;
+  /** 是否同时拉取 Code Quality findings（默认 false） */
+  codeQualityEnabled?: boolean;
   /**
    * 跨线告警显式授权自动升级（仅 CLI `--allow-major-upgrade` 入口，
    * 无 env 通道；Action 不支持）。详见 RuntimeConfig.allowMajorUpgrade。
@@ -1025,6 +1267,11 @@ interface CliConfigOverrides {
   upgradeGroups?: Record<string, string[]>;
   /** lockfile 修复用的 pnpm 版本（工具链固定；缺省从 packageManager 解析） */
   toolchainPnpmVersion?: string;
+  /**
+   * 发现规模上限（`--max-repos` / `DEPENDFIX_MAX_REPOS`）：最多保留的仓库数。
+   * 默认 100；设为 0 或负数表示不限制。大 org 场景下防止一次性全量发现。
+   */
+  maxRepos?: number;
   /** AI 研判总开关（`--ai`） */
   aiEnabled?: boolean;
   /** AI 提供商（`--ai-provider`：openai-compatible / anthropic） */
@@ -1049,15 +1296,15 @@ interface CliConfigOverrides {
    */
   history?: string;
 }
-interface ResolveRuntimeConfigOptions {
+export interface ResolveRuntimeConfigOptions {
   env?: NodeJS.ProcessEnv;
   cliOverrides?: CliConfigOverrides;
   /** 工作目录，用于从 git remote 推断仓库名（默认 `process.cwd()`） */
   workDir?: string;
 }
-declare const DEFAULT_RUNTIME_CONFIG: Omit<RuntimeConfig, 'githubToken' | 'repositories' | 'dryRun' | 'createPullRequest' | 'commit' | 'cleanupBranches' | 'cleanupBranchesAuto'>;
-declare function readEnvConfig(env?: NodeJS.ProcessEnv): CliConfigOverrides;
-declare function resolveRuntimeConfig(options?: ResolveRuntimeConfigOptions): RuntimeConfig;
+export declare const DEFAULT_RUNTIME_CONFIG: Omit<RuntimeConfig, 'githubToken' | 'repositories' | 'dryRun' | 'createPullRequest' | 'commit' | 'cleanupBranches' | 'cleanupBranchesAuto'>;
+export declare function readEnvConfig(env?: NodeJS.ProcessEnv): CliConfigOverrides;
+export declare function resolveRuntimeConfig(options?: ResolveRuntimeConfigOptions): RuntimeConfig;
 /**
  * 从 git remote origin 推断 owner/repo。
  *
@@ -1068,10 +1315,10 @@ declare function resolveRuntimeConfig(options?: ResolveRuntimeConfigOptions): Ru
  *
  * @returns `owner/repo` 或 `null`（非 GitHub / 无 origin）
  */
-declare function inferRepoFromGitRemote(workDir: string): string | null;
+export declare function inferRepoFromGitRemote(workDir: string): string | null;
 //#endregion
 //#region src/report/archiver.d.ts
-interface ArchiveRepoStats {
+export interface ArchiveRepoStats {
   repository: string;
   alertsCount: number;
   fixable: number;
@@ -1081,7 +1328,7 @@ interface ArchiveRepoStats {
   durationMs: number;
 }
 /** index.json 单条趋势记录（字段与 RunSummary/RepositoryResult 口径一致）。 */
-interface ArchiveRunEntry {
+export interface ArchiveRunEntry {
   runId: string;
   startedAt: string;
   /** 本次运行总时长（finishedAt - startedAt，毫秒） */
@@ -1092,10 +1339,10 @@ interface ArchiveRunEntry {
   /** 按仓库统计（趋势基础字段） */
   repoStats: ArchiveRepoStats[];
 }
-interface ArchiveIndex {
+export interface ArchiveIndex {
   runs: ArchiveRunEntry[];
 }
-interface ArchiveResult {
+export interface ArchiveResult {
   /** 汇总 json 路径 */
   summaryJsonPath: string;
   /** 单仓库报告文件路径列表 */
@@ -1114,14 +1361,14 @@ interface ArchiveResult {
  * 可靠性：index.json 采用临时文件 + 原子 rename 写入（并发/中断安全）；
  * 解析失败的损坏索引先备份为 `index.json.corrupt-{ts}.bak` 再重建，历史不静默丢失。
  */
-declare function writeArchive(runResult: RunResult, outputDir?: string): ArchiveResult;
+export declare function writeArchive(runResult: RunResult, outputDir?: string): ArchiveResult;
 /** 读取归档索引（不存在时返回空索引；条目级字段兜底防旧版/手写索引形状异常）。 */
-declare function readArchiveIndex(outputDir?: string): ArchiveIndex;
+export declare function readArchiveIndex(outputDir?: string): ArchiveIndex;
 /**
  * 查询某仓库的历史运行摘要（倒序时间：最新在前）。
  * 仅返回包含该仓库的运行；无结果返回 []。
  */
-declare function queryRepoHistory(repo: string, outputDir?: string): ArchiveRunEntry[];
+export declare function queryRepoHistory(repo: string, outputDir?: string): ArchiveRunEntry[];
 //#endregion
 //#region src/report/history.d.ts
 /**
@@ -1133,14 +1380,14 @@ declare function queryRepoHistory(repo: string, outputDir?: string): ArchiveRunE
  * 行格式：`YYYY-MM-DD HH:mm:ss  告警 N / 修复 N / 失败 N  时长 Xs  runId=...`
  * 无历史时返回提示行（非空，调用方直接打印）。
  */
-declare function formatHistory(entries: ArchiveRunEntry[], repo: string): string;
+export declare function formatHistory(entries: ArchiveRunEntry[], repo: string): string;
 //#endregion
 //#region src/multirepo/scheduler.d.ts
 /** 并发上限（1-16，配置校验范围） */
-declare const MAX_CONCURRENCY_LIMIT = 16;
+export declare const MAX_CONCURRENCY_LIMIT = 16;
 /** 默认并发（保守：行为与现状一致，逐仓库串行） */
-declare const DEFAULT_CONCURRENCY = 1;
-interface ConcurrencySchedulerOptions<T> {
+export declare const DEFAULT_CONCURRENCY = 1;
+export interface ConcurrencySchedulerOptions<T> {
   items: T[];
   /** 并发窗口（1-16） */
   concurrency: number;
@@ -1162,9 +1409,16 @@ interface ConcurrencySchedulerOptions<T> {
  *   onError 兜底，保证"单仓库失败不中断整体"）
  * - 任务完成顺序不保证（并发下与输入顺序无关），但每个任务都会被调度
  */
-declare function runWithConcurrency<T>(options: ConcurrencySchedulerOptions<T>): Promise<void>;
+export declare function runWithConcurrency<T>(options: ConcurrencySchedulerOptions<T>): Promise<void>;
 /** 校验并发值是否在 1-16 范围内（config 层调用，抛 AppError）。 */
-declare function isValidConcurrency(value: number): boolean;
+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 {
@@ -1180,9 +1434,9 @@ interface AiUsage {
  * 估算单次调用成本（USD）。
  * 模型不在单价表返回 undefined（不估算，避免误导）。
  */
-declare function estimateCostUsd(model: string, inputTokens: number, outputTokens: number): number | undefined;
+export declare function estimateCostUsd(model: string, inputTokens: number, outputTokens: number): number | undefined;
 /** 聚合多次 AI 调用的 token 消耗（run 级）。 */
-declare class AiUsageTracker {
+export declare class AiUsageTracker {
   private calls;
   private inputTokens;
   private outputTokens;
@@ -1214,6 +1468,14 @@ interface AppContext {
   startedAt: string;
   finishedAt: string;
 }
+/**
+ * 按动作构成生成 PR 标题（收尾审查遗留修复：cs-only 修复不再误标 "N upgrades"，
+ * lockfile-only 不再出现 "0 upgrades"）。
+ * - 依赖升级 + code-scanning 修复分别计数；均为 0 时（lockfile-only）中性标题。
+ * - ⚠️ 不变式：`upgrades = alertsFixed - codeFixes` 依赖 computeSummary 与
+ *   codeFixes 过滤条件一致（均 success && !noOp）；任一侧口径变更必须同步。
+ */
+export declare function buildPrTitle(summary: Pick<RunSummary, 'alertsFixed'>, actions: FixAction[]): string;
 //#endregion
 //#region src/helpers/index.d.ts
 /**
@@ -1226,7 +1488,7 @@ interface AppContext {
  * @param alerts 已过滤出 fixable && recommendedVersion 非空的告警
  * @returns 每包仅一条的代表告警
  */
-declare function dedupeFixableAlerts(alerts: NormalizedSecurityAlert[]): NormalizedSecurityAlert[];
+export declare function dedupeFixableAlerts(alerts: NormalizedSecurityAlert[]): NormalizedSecurityAlert[];
 /**
  * 读取修复涉及的关键文件快照（逐包回滚基线）。
  *
@@ -1235,23 +1497,27 @@ declare function dedupeFixableAlerts(alerts: NormalizedSecurityAlert[]): Normali
  * 用于成员级修复将成员 manifest 纳入回滚基线。
  * 用于逐包升级验证失败时精确回滚该包产生的改动，而不影响此前已成功的包。
  */
-declare function snapshotTrackedFiles(workDir: string, extraPaths?: string[]): Record<string, string | null>;
+export declare function snapshotTrackedFiles(workDir: string, extraPaths?: string[]): Record<string, string | null>;
 /**
  * 恢复文件快照（逐包回滚）。原不存在的文件将被删除。
  */
-declare function restoreTrackedFiles(workDir: string, snapshot: Record<string, string | null>): void;
+export declare function restoreTrackedFiles(workDir: string, snapshot: Record<string, string | null>): void;
 /**
- * 快速验证（逐包）：仅运行 `pnpm lint`（脚本存在时）。
+ * 快速验证（逐包）：运行验证命令序列。
+ *
+ * 有自定义命令时执行完整序列（含 install + setup + lint + build），
+ * 否则仅运行 `pnpm lint`（脚本存在时）。
  *
- * 完整验证（install + lint + build）成本高，逐包执行不现实；
- * lint 是依赖兼容性的快速信号（本次坏 PR 即因 lint 失败）。
- * 无 lint 脚本时视为通过（与 verifyProject 的跳过语义一致）。
+ * 设计决策（run 33946113272 复盘）：旧版仅跑 `pnpm lint`，但 Nuxt 等框架
+ * 项目 lint 依赖 `nuxt prepare` 生成的 `.nuxt/tsconfig.json`——无 prepare
+ * 步骤会导致 ESLint OOM。自定义命令已含 prepare，走完整序列可避免此问题；
+ * `pnpm install` 在 node_modules 已就绪时近乎空操作，性能影响可忽略。
  */
-declare function quickVerifyProject(ctx: Pick<AppContext, 'logger' | 'workDir'>, repo: string): Promise<boolean>;
+export declare function quickVerifyProject(ctx: Pick<AppContext, 'logger' | 'workDir' | 'customCommands'>, repo: string): Promise<boolean>;
 /**
  * 成员级可修复告警条目：告警 + 所属成员目录（相对 workDir，如 `packages/web`）。
  */
-interface MemberManifestAlert {
+export interface MemberManifestAlert {
   alert: NormalizedSecurityAlert;
   /** 成员目录（相对 workDir，如 `packages/web`） */
   manifestDir: string;
@@ -1259,7 +1525,7 @@ interface MemberManifestAlert {
 /**
  * 告警分区结果：根 manifest / 成员 manifest（可自动修复）/ 其他（人工）。
  */
-interface SubmanifestPartition {
+export interface SubmanifestPartition {
   root: NormalizedSecurityAlert[];
   member: MemberManifestAlert[];
   sub: NormalizedSecurityAlert[];
@@ -1291,7 +1557,7 @@ interface SubmanifestPartition {
  *   - 其余 → sub（单根模型无法安全修 / 多版本共存 / 降级风险 / 跨线 / 非成员路径，
  *     需人工处理）
  */
-declare function partitionSubmanifestAlerts(alerts: NormalizedSecurityAlert[], workDir: string): SubmanifestPartition;
+export declare function partitionSubmanifestAlerts(alerts: NormalizedSecurityAlert[], workDir: string): SubmanifestPartition;
 /**
  * 判断包是否为**根** `package.json` 的直接依赖（仅查根声明的
  * dependencies / devDependencies / optionalDependencies）。
@@ -1300,19 +1566,19 @@ declare function partitionSubmanifestAlerts(alerts: NormalizedSecurityAlert[], w
  * 根 manifest，跨线升级准入必须与修复器能力对齐——仅成员声明的包（root 未声明）
  * 进入跨线链路必然失败，维持人工处理。
  */
-declare function isRootDirectDependency(workDir: string, packageName: string): boolean;
+export declare function isRootDirectDependency(workDir: string, packageName: string): boolean;
 //#endregion
 //#region src/grouping/index.d.ts
 /** 分组来源（决定分组优先级与命名语义） */
-type GroupSource = 'explicit' | 'dependabot' | 'types' | 'scope' | 'prefix' | 'single';
-interface DependencyGroup {
+export type GroupSource = 'explicit' | 'dependabot' | 'types' | 'scope' | 'prefix' | 'single';
+export interface DependencyGroup {
   /** 组名（日志与统计用） */
   name: string;
   /** 组内包名（保持输入顺序） */
   packages: string[];
   source: GroupSource;
 }
-interface GroupingResult {
+export interface GroupingResult {
   /** 有序分组（处理顺序即升级执行顺序） */
   groups: DependencyGroup[];
   /**
@@ -1321,7 +1587,7 @@ interface GroupingResult {
    */
   cleanupCandidates: string[];
 }
-interface GroupingOptions {
+export interface GroupingOptions {
   /** 工作目录（读取 package.json / pnpm-lock.yaml / .github/dependabot.yml） */
   workDir: string;
   /** 用户显式分组：组名 -> 包列表（最高优先级，覆盖自动分组） */
@@ -1352,7 +1618,7 @@ interface PackageJsonLike {
  * 裸 `*`（全匹配）视为不匹配，防止误分组（设计稿 §3）。
  * 中间通配（`foo*bar`）不支持。
  */
-declare function matchesPattern(packageName: string, pattern: string): boolean;
+export declare function matchesPattern(packageName: string, pattern: string): boolean;
 /**
  * 解析 `.github/dependabot.yml`（或 `.yaml` 变体）中 npm ecosystem 的 `groups` → patterns。
  *
@@ -1360,7 +1626,7 @@ declare function matchesPattern(packageName: string, pattern: string): boolean;
  * 解析为 dependabot 语法子集：仅 `groups.<name>.patterns`；`exclude-patterns` /
  * `dependency-type` / `update-types` 忽略（设计稿 §3）。
  */
-declare function parseDependabotGroups(workDir: string): Record<string, string[]>;
+export declare function parseDependabotGroups(workDir: string): Record<string, string[]>;
 /**
  * 从 `@types/x` 提取主包名。
  *
@@ -1371,14 +1637,14 @@ declare function parseDependabotGroups(workDir: string): Record<string, string[]
  *
  * 非 @types 包返回 `null`。
  */
-declare function extractMainPackage(packageName: string): string | null;
+export declare function extractMainPackage(packageName: string): string | null;
 /**
  * 判定 @types 的主包是否仍然存在（任一命中即存在）：
  * 1. package.json 直接依赖（dependencies / devDependencies / optionalDependencies）
  * 2. pnpm.overrides（间接依赖修复场景）
  * 3. lockfile 中存在（间接依赖场景）
  */
-declare function isMainPackagePresent(pkg: PackageJsonLike, lockfilePath: string, mainPackage: string): boolean;
+export declare function isMainPackagePresent(pkg: PackageJsonLike, lockfilePath: string, mainPackage: string): boolean;
 /**
  * 构建升级分组（主入口）。
  *
@@ -1392,19 +1658,52 @@ declare function isMainPackagePresent(pkg: PackageJsonLike, lockfilePath: string
  * 4. 非 @types 单包组
  * 5. @types 归并（主包有告警并入其组）/ 独立组 / 清理候选（主包已不存在）
  */
-declare function buildUpgradeGroups(alerts: NormalizedSecurityAlert[], options: GroupingOptions): GroupingResult;
+export declare function buildUpgradeGroups(alerts: NormalizedSecurityAlert[], options: GroupingOptions): GroupingResult;
+//#endregion
+//#region src/runners/network-audit.d.ts
+/**
+ * 执行期网络外联审计 + 出站白名单拦截（安全治理：恶意脚本外联回传/下载 payload 的事故溯源与阻断）。
+ *
+ * 捕获面（实证驱动，2026-08-14）：
+ * - **命令输出 URL 提取**（主）：执行命令 stdout/stderr 中的 http(s) URL——
+ *   pnpm install 输出含完整 tarball URL（registry 域名 + 包名 + 版本），
+ *   确定性捕获 pnpm/npm 的 registry 外联（pnpm 11 undici 直连不走代理 env，实证确认）
+ * - **本地拦截代理**（辅）：注入 HTTP(S)_PROXY 捕获尊重代理的工具（curl/wget/npm CLI/git http）；
+ *   仅当环境无既有代理时注入（覆盖用户代理会破坏其网络行为，稳定性优先）；
+ *   **deny-by-default**：非白名单域名的 CONNECT/HTTP 请求直接 502 拒绝（不建上游连接），
+ *   记录为违规外联（`violation`）；白名单命中才放行（registry/GitHub 默认域 + 可配置扩展）
+ * - 覆盖边界：undici 直连（node fetch/https.request 默认不读代理 env）不在连接级拦截范围——
+ *   命令输出 URL 提取对这类外联提供冗余判定（攻击者绕过代理 env 也会被命中并归类违规）
+ *
+ * 无敏感信息：仅记录方法 + 目标（host/URL），不记录请求体与响应体。
+ */
+type NetworkAuditSource = 'proxy' | 'command-output';
+interface NetworkAuditEntry {
+  /** 记录时间（ISO） */
+  time: string;
+  /** 来源：proxy = 审计代理捕获；command-output = 命令输出 URL 提取 */
+  source: NetworkAuditSource;
+  /** 请求方法（CONNECT / GET / POST / ...） */
+  method: string;
+  /** 外联目标（proxy：host:port；command-output：完整 URL） */
+  target: string;
+  /** deny-by-default 拦截的违规外联标记（白名单校验失败的外联为 true） */
+  violation?: boolean;
+}
 //#endregion
 //#region src/runners/verification-runner.d.ts
 /**
  * 单条命令的执行结果
  */
-interface CommandResult {
+export interface CommandResult {
   /** 执行的命令文本 */
   command: string;
-  /** 退出码（0 = 成功） */
+  /** 退出码（0 = 成功；-1 = 启动失败或超时被杀） */
   exitCode: number;
   /** 执行耗时（毫秒） */
   durationMs: number;
+  /** 是否因超时被中止（默认 false） */
+  timedOut?: boolean;
   /** stdout 摘要（截断到 200 行，已脱敏） */
   stdout: string;
   /** stderr 摘要（截断到 200 行，已脱敏） */
@@ -1413,7 +1712,7 @@ interface CommandResult {
 /**
  * 验证执行参数
  */
-interface VerificationParams {
+export interface VerificationParams {
   /** 工作目录 */
   workDir: string;
   /**
@@ -1421,11 +1720,22 @@ interface VerificationParams {
    * 默认: `pnpm install --frozen-lockfile` → `pnpm lint` → `pnpm build`
    */
   commands?: string[];
+  /**
+   * 单命令超时（毫秒），超时中止该命令并终止其进程树。
+   * 默认 10 分钟（恶意死循环脚本超时中止，防长时间占用）。
+   */
+  commandTimeoutMs?: number;
+  /**
+   * 关闭执行期网络外联审计（默认开启）。
+   * 审计记录命令输出中的外联 URL + 注入本地审计代理捕获尊重代理的工具外联；
+   * 仅当环境无既有代理时注入（覆盖用户代理会破坏其网络行为）。
+   */
+  networkAuditDisabled?: boolean;
 }
 /**
  * 验证执行结果
  */
-interface VerificationResult {
+export interface VerificationResult {
   /** 所有命令是否全部成功 */
   success: boolean;
   /** 每条命令的详细结果 */
@@ -1434,17 +1744,22 @@ interface VerificationResult {
   failedCommand?: string;
   /** 失败详情（仅 success=false 时填充） */
   failure?: string;
+  /** 执行期网络外联记录（审计开启时；空数组 = 无外联或未捕获到） */
+  networkAudit?: NetworkAuditEntry[];
+  /** 非白名单外联违规（deny-by-default 拦截记录；空数组 = 无违规或审计关闭） */
+  networkViolations?: NetworkAuditEntry[];
 }
 /**
  * 压缩验证命令输出为报告可读的摘要（首尾各取若干行，超长中间省略）。
  * 完整输出由日志承载；报告保持紧凑，避免 error 字段失控膨胀。
  */
-declare function summarizeVerificationOutput(output: string): string;
+export declare function summarizeVerificationOutput(output: string): string;
 /**
  * 构造失败验证命令的 error 描述：`exit code N — <stdout/stderr 摘要>`。
- * 无输出时退化为裸 `exit code N`。stdout/stderr 已在 execCommand 中脱敏、截断 200 行。
+ * 无输出时退化为裸 `exit code N`；超时命令归类为 `timed out after Xms`。
+ * stdout/stderr 已在 execCommand 中脱敏、截断 200 行。
  */
-declare function formatVerificationError(cr: CommandResult): string;
+export declare function formatVerificationError(cr: CommandResult): string;
 /**
  * 按顺序在工作目录执行命令序列，任一命令失败则停止。
  *
@@ -1456,11 +1771,11 @@ declare function formatVerificationError(cr: CommandResult): string;
  * }
  * ```
  */
-declare function runVerification(params: VerificationParams): Promise<VerificationResult>;
+export declare function runVerification(params: VerificationParams): Promise<VerificationResult>;
 /**
  * 对外暴露以支持单独测试
  */
-declare function sanitizeOutput(output: string): string;
+export declare function sanitizeOutput(output: string): string;
 //#endregion
 //#region src/alerts/pnpm-audit-fetcher.d.ts
 /**
@@ -1473,7 +1788,7 @@ declare function sanitizeOutput(output: string): string;
  * - repository 由调用方注入（显式 --repo → git remote → local 兜底）
  * - audit 自身失败（无 lockfile / pnpm 不可用 / JSON 解析失败）→ 硬失败，绝不静默空跑
  */
-interface FetchPnpmAuditAlertsParams {
+export interface FetchPnpmAuditAlertsParams {
   /** 扫描工作目录（lockfile 所在目录） */
   workDir: string;
   /** 注入的仓库标识（owner/repo 或 local 兜底） */
@@ -1484,7 +1799,7 @@ interface FetchPnpmAuditAlertsParams {
  *
  * @throws AppError('AUDIT_FAILED') — pnpm 不可用 / 无 lockfile / JSON 解析失败
  */
-declare function fetchPnpmAuditAlerts(params: FetchPnpmAuditAlertsParams): Promise<NormalizedSecurityAlert[]>;
+export declare function fetchPnpmAuditAlerts(params: FetchPnpmAuditAlertsParams): Promise<NormalizedSecurityAlert[]>;
 interface RiskRecord {
   advisoryId: string;
   packageName: string;
@@ -1492,18 +1807,26 @@ interface RiskRecord {
   title: string;
   htmlUrl: string;
   patchedVersion: string | null;
+  /** GitHub Advisory ID（pnpm audit `advisory.github_advisory_id`，GitHub Advisory Database 收录时） */
+  ghsaId?: string;
+  /** CVE ID 列表（pnpm audit `advisory.cves[]` 字符串数组） */
+  cveIds?: string[];
 }
 /**
  * 解析 pnpm audit 报告（legacy + modern 双格式），按
  * `packageName:advisoryId:severity` 去重（保留首个，advisoryId 优先补全）。
  */
-declare function parseAuditReport(report: unknown): RiskRecord[];
+export declare function parseAuditReport(report: unknown): RiskRecord[];
 /**
- * advisoryId 的稳定数字哈希（`NormalizedSecurityAlert.id` 为 number）。
+ * advisoryId 的稳定数字哈希（M20 之前使用，M20 后保留以维持向后兼容 `NormalizedSecurityAlert.id: number`）。
+ *
  * 取 sha256 前 4 字节完整 uint32（非设计稿的 `% 2^31`：uint32 语义更自然，
  * 碰撞概率 ~2^-32/对，12 条告警场景生日界 ~1.6e-8，可忽略）。
+ *
+ * M20 弃用：唯一去重键改为 `upstreamId`，详见 [`normalizeUpstreamId`](../../../core/src/alerts/upstream-id.ts)。
+ * 本函数保留仅为兼容现有 `NormalizedSecurityAlert.id: number` 字段，**不是**平台去重键。
  */
-declare function hashAdvisoryId(packageName: string, advisoryId: string): number;
+export declare function hashAdvisoryId(packageName: string, advisoryId: string): number;
 //#endregion
 //#region src/ai/provider.d.ts
 interface AiConfig {
@@ -1611,10 +1934,10 @@ interface AssessmentContextInput {
  * maskSecrets('call failed with key sk-abc12345xyz', ['sk-abc12345xyz'])
  * // → 'call failed with key sk-a****yz'
  */
-declare function maskSecrets(text: string, secrets: string[]): string;
+export declare function maskSecrets(text: string, secrets: string[]): string;
 //#endregion
 //#region src/ai/index.d.ts
-interface AssessResult {
+export interface AssessResult {
   /** 结构化研判（降级时为 null，走建议模式） */
   assessment: AiAssessment | null;
   /**
@@ -1627,7 +1950,7 @@ interface AssessResult {
   /** 降级原因（脱敏后的错误消息；成功时为 undefined） */
   error?: string;
 }
-interface AssessOptions {
+export interface AssessOptions {
   config: AiConfig;
   context: AssessmentContextInput;
   /** 注入请求函数（默认全局 fetch；测试用 vi.fn） */
@@ -1646,10 +1969,18 @@ interface AssessOptions {
  *
  * 降级语义：调用方走建议模式（报告输出人工建议），不静默、可审计。
  */
-declare function assessBreakingChange(options: AssessOptions): Promise<AssessResult>;
+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
-interface DependfixAppOptions {
+export interface DependfixAppOptions {
   /** 已解析的运行时配置 */
   config: RuntimeConfig;
   /** 工作目录（默认 `process.cwd()`） */
@@ -1660,20 +1991,45 @@ interface DependfixAppOptions {
   verbose?: boolean;
   /** 自定义验证命令（覆盖默认命令链） */
   commands?: string[];
+  /**
+   * 执行环境：`local`（CLI/MCP 等用户机器直接执行）| `container`（平台容器沙箱）。
+   * 默认 `local`。容器内执行属于设计内隔离行为（非 root + 临时目录），
+   * 不触发本地模式不可信代码风险警告。
+   */
+  executionEnvironment?: 'local' | 'container';
+  /**
+   * 自定义 Logger（平台层注入 MemoryLogger 用于捕获执行日志）。
+   * 未提供时使用内部 createLogger（输出到 console）。
+   */
+  logger?: Logger;
 }
-interface DependfixRunResult {
+export interface DependfixRunResult {
   /** 结构化运行结果（用于报告生成） */
   result: RunResult;
   /** 进程退出码：0=全部成功, 1=部分失败, 2=全部失败 */
   exitCode: number;
 }
-declare class DependfixApp {
+/**
+ * 输出"部分源拉取失败"汇总（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 {
   private readonly config;
   private readonly workDir;
   private readonly reportOutputDir;
   private readonly logger;
   private readonly verbose;
   private readonly customCommands?;
+  private readonly executionEnvironment;
   private readonly runId;
   private readonly allAlerts;
   private readonly allActions;
@@ -1691,6 +2047,14 @@ declare class DependfixApp {
   private get ctx();
   /** 执行完整的编排流程，返回结构化结果和退出码。 */
   run(): Promise<DependfixRunResult>;
+  /**
+   * 启动安全自检（best-effort，任何失败不阻断运行）：
+   * - 本地模式风险提示：fix/fix-and-pr 会在用户机器直接执行目标仓库的
+   *   依赖脚本（不可信代码）；容器环境（平台沙箱）属于设计内隔离，跳过。
+   * - token 权限面探测：超权限 token（classic repo scope）启动即警告，
+   *   Code Scanning 开启但缺 security-events 权限时提示。
+   */
+  private runStartupSecurityChecks;
   private executeMode;
   private executeReportMode;
   private processRepoForReport;
@@ -1714,6 +2078,16 @@ 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;
   /**
    * 多仓库并发执行管线。
    *
@@ -1739,5 +2113,5 @@ declare class DependfixApp {
   private createClient;
 }
 //#endregion
-export { ALERT_SOURCES, AUTO_FIXABLE_RULES, type AiAssessment, type AiChatResult, type AiConfig, type AiFileChange, AiOptions, type AiReplaceBlock, AiTriggerKind, type AiUsage, AiUsageTracker, type AlertClass, type AlertSourceKind, ApplyCodeScanningFixParams, ArchiveIndex, ArchiveRepoStats, ArchiveResult, ArchiveRunEntry, AssessOptions, AssessResult, type AssessmentContextInput, CliConfigOverrides, CodeScanningFixTemplate, CommandResult, ConcurrencySchedulerOptions, CreatePullRequestParams, DEFAULT_CONCURRENCY, DEFAULT_RUNTIME_CONFIG, DependencyFixResult, DependencyGroup, DependfixApp, DependfixAppOptions, DependfixBranchStatus, DependfixOpenPR, DependfixRunResult, DiscoveredRepository, ENV_PREFIX, FetchCodeScanningAlertsParams, FetchDependabotAlertsParams, FetchPnpmAuditAlertsParams, FixAndPrPlan, FixBranchResult, GroupSource, GroupingOptions, GroupingResult, LockfileDiff, LockfileFailureCategory, LockfileRepairResult, MAX_CONCURRENCY_LIMIT, MAX_GLOB_PATTERN_LENGTH, MemberManifestAlert, OctokitClientOptions, PackageJson, PullRequestResult, RUNTIME_MODES, RepairAttempt, RepairLockfileParams, RepairStrategy, RepoPolicy, RepositoryDiscoveryOptions, ResolveRuntimeConfigOptions, RetryPolicyOptions, RuntimeConfig, RuntimeMode, SEVERITY_THRESHOLDS, SUGGESTED_RULES, type SeverityThreshold, SourceFileSnapshot, SubmanifestPartition, TemplateApplyResult, UpgradeDependencyParams, VerificationParams, VerificationResult, applyCodeScanningFix, applyVersionedOverrides, assessBreakingChange, buildUpgradeGroups, classifyLockfileFailure, classifyRule, closePullRequest, compareSemver, computeFixAndPrPlan, computeFixFingerprint, computeLockfileDiff, computeRetryDelayMs, createFixBranch, createGitHubClient, createPullRequest, dedupeFixableAlerts, deleteRemoteBranch, detectPnpmMajor, discoverRepositories, ensurePnpmOverrides, estimateCostUsd, extractFingerprintFromBranch, extractLockfileVersion, extractMainPackage, extractPrefix, fetchCodeScanningAlerts, fetchDependabotAlerts, fetchPnpmAuditAlerts, filterExplicitRepositories, findDependencyVersion, findDependfixOpenPR, formatHistory, formatVerificationError, generatePRBody, getBranchPrStatus, getCodeScanningFixTemplate, hashAdvisoryId, inferRepoFromGitRemote, isConfirmAnswer, isCrossMajorFixRequired, isMainPackagePresent, isNonSemverDeclaration, isRootDirectDependency, isValidConcurrency, isValidPnpmVersion, listDependfixBranches, mapGitHubError, maskSecrets, matchesPattern, matchesRepoExclude, matchesRepoGlob, matchesRepoInclude, matchesTopicsExclude, mergeRepositories, overrideTransitiveDependency, parseAuditReport, parseDependabotGroups, parseMajorVersion, partitionSubmanifestAlerts, pushBranch, queryRepoHistory, quickVerifyProject, readArchiveIndex, readEnv, readEnvConfig, readExistingOverrides, readLockfileVersion, readLockfileVersions, readReposFile, repairLockfile, repoGlobToRegExp, resolvePnpmVersion, resolveRepoList, resolveRuntimeConfig, resolveWithinWorkDir, restoreSourceFile, restoreTrackedFiles, runVerification, runWithConcurrency, sanitizeOutput, snapshotSourceFile, snapshotTrackedFiles, stageAndCommit, suggestionFor, summarizeVerificationOutput, upgradeDependency, writeArchive };
+export type { AiAssessment, AiChatResult, AiConfig, AiFileChange, AiReplaceBlock, AiUsage, AlertClass, AlertSourceKind, AssessmentContextInput, AuthProvider, AuthProviderOptions, FromAppParams, FromPatParams, SeverityThreshold };
 //# sourceMappingURL=index.d.mts.map