@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/workflows/review-fix-loop-utils.cjs

@@ -1,7 +1,7 @@
 // review-fix-loop-utils.cjs — review-fix-loop.js 的可测纯函数模块
 //
 // workflow 编排逻辑的纯函数抽到独立 .cjs，
-// 供 vitest 单测直接 require（extensions/universal/subagent-workflow/src/__tests__/review-fix-loop-utils.test.ts）
+// 供 vitest 单测直接 require（packages/subagent-core/src/__tests__/review-fix-loop-utils.test.ts）
 // 与 worker 运行时共用（review-fix-loop.js 经 workerData.scriptPath 定位本文件）。
 //
 // 本文件不依赖 workflow 全局（$ARGS/agent/parallel/phase/log），所有需要报错的函数
@@ -310,10 +310,16 @@ function normIssueId(s) {
  * fix 阶段（fix-attempted/deferred 标记）与 ES3 校验共用——精确键查表会把
  * "mf-1"/"MF-1 (fixed)" 等漂移 ID 判为未追踪，导致 fix-attempted → fixed/regressed
  * → needs-redesign 状态链静默失效；deferred 侧漂移则创建幽灵条目（原条目仍 open 阻塞收敛）。
+ *
+ * 首查必须 Object.hasOwn（上收 zsw 侧同款修复）：truthy 查表（issues[issueId]）会让
+ * 原型链键（"__proto__"/"toString"/"constructor"）误命中——ID 来自 LLM 产出，攻击面
+ * 真实存在；误命中会把非 own 键当台账键返回，后续 issues[key].severity 读取原型
+ * 成员（undefined 或函数）污染 fix 对账。归一化回退段的 Object.keys 只枚举 own 键，
+ * 本就无此问题。
  */
 function findIssueKey(issues, issueId) {
   if (!issues || typeof issueId !== "string" || !issueId) return undefined;
-  if (issues[issueId]) return issueId;
+  if (Object.hasOwn(issues, issueId)) return issueId;
   const norm = normIssueId(issueId);
   if (!norm) return undefined;
   for (const key of Object.keys(issues)) {
@@ -322,6 +328,64 @@ function findIssueKey(issues, issueId) {
   return undefined;
 }
 
+/**
+ * deferred 条目的有效 severity（m9 交叉核对）：自报 severity 可被单边绕过（fix agent
+ * 与审核方同一 LLM，有少干活动机，把 must-fix 标 minor 塞进 deferred 即过旧校验）——
+ * 与追踪表交叉核对：trackedIssues 中能找到的 ID 以其追踪 severity 为准；追踪表无此 ID
+ * 采信自报。仅认真实 severity 等级（critical/major/minor/trivial）；"unknown"（reconcile
+ * 新 ID 默认）等非等级值不覆盖自报，避免误伤合法 minor deferral。
+ */
+function resolveDeferredEffectiveSeverity(d, trackedIssues, idMap) {
+  const sev = typeof d.severity === "string" ? d.severity.toLowerCase() : "";
+  let effectiveSev = sev;
+  if (trackedIssues && typeof d.issue_id === "string" && d.issue_id) {
+    const trackedKey = findIssueKey(trackedIssues, translateId(idMap, d.issue_id, trackedIssues));
+    const trackedSev = trackedKey ? trackedIssues[trackedKey].severity : undefined;
+    const ts = typeof trackedSev === "string" ? trackedSev.toLowerCase() : "";
+    if (ts === "critical" || ts === "major" || ts === "minor" || ts === "trivial") {
+      effectiveSev = ts;
+    }
+  }
+  return effectiveSev;
+}
+
+/** deferred 违规收集（TC3）：有效 severity 非 minor/trivial 即违规；falsy 条目跳过。 */
+function collectDeferredViolations(result, trackedIssues, idMap) {
+  const violations = [];
+  for (const d of result.deferred || []) {
+    if (!d) continue;
+    const effectiveSev = resolveDeferredEffectiveSeverity(d, trackedIssues, idMap);
+    if (effectiveSev && effectiveSev !== "minor" && effectiveSev !== "trivial") {
+      violations.push({ issue_id: d.issue_id || "(unnamed)", severity: effectiveSev });
+    }
+  }
+  return violations;
+}
+
+/** must-fix 申报 ID 归一化：string 直接归一；对象形态取 .id 归一；其余空串。 */
+function normMustFixEntryId(id) {
+  if (typeof id === "string") return normIssueId(id);
+  return id && typeof id.id === "string" ? normIssueId(id.id) : "";
+}
+
+/**
+ * must-fix 漏修违规收集（m3）：ID 归一化比较——大小写 + 尾部括号尾注（如 "(fixed)"）
+ * 漂移不误杀：严格 trim 比较会把 "mf-1"/"MF-1 (fixed)" 判漏修，整轮 fix-failure 误杀。
+ */
+function collectMustFixNotFixedViolations(result, mustFixIds) {
+  const violations = [];
+  const fixedIds = new Set((result.fixes || [])
+    .map((f) => (f && typeof f.issue_id === "string" ? normIssueId(f.issue_id) : ""))
+    .filter(Boolean));
+  for (const id of mustFixIds) {
+    const norm = normMustFixEntryId(id);
+    if (norm && !fixedIds.has(norm)) {
+      violations.push({ issue_id: norm, severity: "must-fix-not-fixed" });
+    }
+  }
+  return violations;
+}
+
 /**
  * ES3 硬校验（5.3-P1 红线）：(1) deferred 只允许 minor/trivial；(2) must-fix 必须全进
  * fixes[]——mustFixIds 中未修复且未显式处理的 ID 判 violation（漏修）。mustFixIds
@@ -335,40 +399,9 @@ function findIssueKey(issues, issueId) {
  * 翻译任一侧都会制造假失配（must-fix-not-fixed 误杀整 run）。
  */
 function validateFixResult(result, mustFixIds, trackedIssues, idMap) {
-  const violations = [];
-  for (const d of result.deferred || []) {
-    if (!d) continue;
-    const sev = typeof d.severity === "string" ? d.severity.toLowerCase() : "";
-    // m9: 自报 severity 可被单边绕过（fix agent 与审核方同一 LLM，有少干活动机，
-    // 把 must-fix 标 minor 塞进 deferred 即过旧校验）——与追踪表交叉核对：
-    // trackedIssues 中能找到的 ID 以其追踪 severity 为准；追踪表无此 ID 采信自报。
-    let effectiveSev = sev;
-    if (trackedIssues && typeof d.issue_id === "string" && d.issue_id) {
-      const trackedKey = findIssueKey(trackedIssues, translateId(idMap, d.issue_id, trackedIssues));
-      const trackedSev = trackedKey ? trackedIssues[trackedKey].severity : undefined;
-      const ts = typeof trackedSev === "string" ? trackedSev.toLowerCase() : "";
-      // 仅认真实 severity 等级（critical/major/minor/trivial）；"unknown"（reconcile 新
-      // ID 默认）等非等级值不覆盖自报，避免误伤合法 minor deferral
-      if (ts === "critical" || ts === "major" || ts === "minor" || ts === "trivial") {
-        effectiveSev = ts;
-      }
-    }
-    if (effectiveSev && effectiveSev !== "minor" && effectiveSev !== "trivial") {
-      violations.push({ issue_id: d.issue_id || "(unnamed)", severity: effectiveSev });
-    }
-  }
+  const violations = collectDeferredViolations(result, trackedIssues, idMap);
   if (Array.isArray(mustFixIds) && mustFixIds.length > 0) {
-    // m3: ID 归一化比较——大小写 + 尾部括号尾注（如 "(fixed)"）漂移不误杀：
-    // 严格 trim 比较会把 "mf-1"/"MF-1 (fixed)" 判漏修，整轮 fix-failure 误杀
-    const fixedIds = new Set((result.fixes || [])
-      .map((f) => (f && typeof f.issue_id === "string" ? normIssueId(f.issue_id) : ""))
-      .filter(Boolean));
-    for (const id of mustFixIds) {
-      const norm = typeof id === "string" ? normIssueId(id) : (id && typeof id.id === "string" ? normIssueId(id.id) : "");
-      if (norm && !fixedIds.has(norm)) {
-        violations.push({ issue_id: norm, severity: "must-fix-not-fixed" });
-      }
-    }
+    violations.push(...collectMustFixNotFixedViolations(result, mustFixIds));
   }
   return violations;
 }
@@ -785,7 +818,9 @@ function resolveIssueIdentity(entry, { issues, dormant }) {
  */
 function translateId(idMap, id, issues) {
   if (typeof id !== "string" || !id) return id;
-  if (issues && issues[id]) return id;
+  // Object.hasOwn：truthy 查表会让原型链键（"__proto__"/"toString"）误判为台账键
+  // 直接返回，跳过 idMap 翻译（与 findIssueKey 同款加固，nextFreeId 键空间同理）。
+  if (issues && Object.hasOwn(issues, id)) return id;
   if (idMap && Object.prototype.hasOwnProperty.call(idMap, id)) return idMap[id];
   return id;
 }
@@ -821,6 +856,88 @@ function translateReconSets(reconSeen, reconEscalate, reconFixed, idMap, issues)
  * 未知 ID（不在 prevIssues 中）按新发现处理；stuckThreshold 复用 stuckThreshold 参数。
  * @returns { issues, stuck, stuckIds, knownRemaining }
  */
+/** 条目克隆：浅拷贝 + history 复制——reconcile 不修改入参条目，转换落在新条目上。 */
+function cloneTrackedIssue(issue) {
+  return { ...issue, history: [...(issue.history || [])] };
+}
+
+/**
+ * 5.1-5 显式升级：reconciliation 声明 escalate → 重新 open（保留历史与 fixAttempts），
+ * 进入修复循环；未升级的 deferred 留 known-remaining，不参与判定。
+ */
+function escalateDeferredIssue(entry, id, escalated, round) {
+  if (!escalated.has(id)) return;
+  entry.status = "open";
+  entry.openStreak = 0;
+  entry.history.push({ round, status: "escalated" });
+}
+
+/**
+ * open/regressed + 声明 fixed（verify-first）→ 清账，命中返回 true（调用方跳过后续
+ * 转换）。与"fix result claiming fixed is NOT evidence"原则不冲突：这里的 fixed 声明
+ * 来自 reviewer 亲自读目标后的申报（evidence 非空由调用方过滤），正是该原则认可的
+ * 证据形态——此前它被收集侧整体丢弃，open 条目无消除通道。
+ */
+function applyReconciledFix(entry, id, fixedDeclared, round) {
+  if (!((entry.status === "open" || entry.status === "regressed") && fixedDeclared.has(id))) return false;
+  entry.status = "fixed";
+  entry.openStreak = 0;
+  entry.history.push({ round, status: "fixed", via: "reconciliation" });
+  return true;
+}
+
+/**
+ * fix-attempted 判定：未再现（未 seen）→ fixed；再现 → regressed（fixAttempts+1）。
+ */
+function applyFixAttemptedOutcome(entry, statusNow, id, seen, round) {
+  if (statusNow !== "fix-attempted") return;
+  if (!seen.has(id)) {
+    entry.status = "fixed";
+    entry.openStreak = 0;
+    entry.history.push({ round, status: "fixed" });
+  } else {
+    entry.status = "regressed";
+    // fixAttempts 语义 = 修复失败次数：初始 0，每次 regressed +1（RC-7「经 2 次修复
+    // 仍未收敛」= 第 2 次 regressed 后触发，修复见 findNeedsRedesign 阈值）。
+    entry.fixAttempts = (entry.fixAttempts || 0) + 1;
+    entry.history.push({ round, status: "regressed" });
+  }
+}
+
+/**
+ * MF-2: fixed 条目再次被报告（seen）→ 回归：转 regressed + fixAttempts+1（已确认修复
+ * 的问题复发同样计修复失败，needs-redesign 可达）；openStreak 由统一 if 累计
+ * （首轮回归 1）。未 seen → 保持 fixed（漏报不误转）。修复前此处无转换——fixed 条目
+ * 复发时 fixAttempts/openStreak 均不增长，与收敛终止组合后默认配置下 R3 即以
+ * converged 提前终止而 must-fix 仍活跃（MF-2）。
+ */
+function applyFixedRegression(entry, statusNow, id, seen, round) {
+  if (!(statusNow === "fixed" && seen.has(id))) return;
+  entry.status = "regressed";
+  entry.fixAttempts = (entry.fixAttempts || 0) + 1;
+  entry.history.push({ round, status: "regressed" });
+}
+
+// open/regressed 且本轮仍在（seen）→ openStreak +1（跨轮字段）；漏报（未 seen）不增长（保守）。
+// status 读 entry 当前值——fix-attempted/fixed 分支本轮转出的 regressed 同样累计（原语义）。
+function accrueOpenStreak(entry, id, seen, stuckThreshold, stuckIds) {
+  if (seen.has(id) && (entry.status === "open" || entry.status === "regressed")) {
+    entry.openStreak = (entry.openStreak || 0) + 1;
+    if (entry.openStreak >= stuckThreshold) stuckIds.push(id);
+  }
+}
+
+// 新 ID（reviewer 声明的新发现）→ open。新 ID 首现 openStreak=1：统一判定语义
+// openStreak >= stuckThreshold（与既有条目分支一致）。边界：stuckThreshold=1 时新 ID
+// 首现即 stuck（语义自洽：阈值为 1 表示「任何未解决条目出现即视为卡住」，属显式配置而非 bug）。
+function registerNewFinding(issues, id, round, stuckThreshold, stuckIds) {
+  issues[id] = {
+    firstSeen: round, severity: "unknown", status: "open", openStreak: 1,
+    history: [{ round, status: "open" }], fixAttempts: 0,
+  };
+  if (issues[id].openStreak >= stuckThreshold) stuckIds.push(id);
+}
+
 function reconcileIssues(prevIssues, { seenIds, escalateIds, fixedIds, round, stuckThreshold }) {
   const issues = {};
   const seen = new Set(seenIds || []);
@@ -828,67 +945,20 @@ function reconcileIssues(prevIssues, { seenIds, escalateIds, fixedIds, round, st
   const fixedDeclared = new Set(fixedIds || []);
   const stuckIds = [];
   for (const [id, issue] of Object.entries(prevIssues || {})) {
-    issues[id] = { ...issue, history: [...(issue.history || [])] };
+    const entry = cloneTrackedIssue(issue);
+    issues[id] = entry;
     if (issue.status === "deferred") {
-      // 5.1-5 显式升级：reconciliation 声明 escalate → 重新 open（保留历史与 fixAttempts），
-      // 进入修复循环；未升级的 deferred 留 known-remaining，不参与判定。
-      if (escalated.has(id)) {
-        issues[id].status = "open";
-        issues[id].openStreak = 0;
-        issues[id].history.push({ round, status: "escalated" });
-      }
-      continue;
-    }
-    // open/regressed + 声明 fixed（verify-first）→ 清账。与"fix result claiming fixed
-    // is NOT evidence"原则不冲突：这里的 fixed 声明来自 reviewer 亲自读目标后的申报
-    // （evidence 非空由调用方过滤），正是该原则认可的证据形态——此前它被收集侧
-    // 整体丢弃，open 条目无消除通道。
-    if ((issues[id].status === "open" || issues[id].status === "regressed") && fixedDeclared.has(id)) {
-      issues[id].status = "fixed";
-      issues[id].openStreak = 0;
-      issues[id].history.push({ round, status: "fixed", via: "reconciliation" });
+      escalateDeferredIssue(entry, id, escalated, round);
       continue;
     }
-    if (issue.status === "fix-attempted") {
-      if (!seen.has(id)) {
-        issues[id].status = "fixed";
-        issues[id].openStreak = 0;
-        issues[id].history.push({ round, status: "fixed" });
-      } else {
-        issues[id].status = "regressed";
-        // fixAttempts 语义 = 修复失败次数：初始 0，每次 regressed +1（RC-7「经 2 次修复
-        // 仍未收敛」= 第 2 次 regressed 后触发，修复见 findNeedsRedesign 阈值）。
-        issues[id].fixAttempts = (issue.fixAttempts || 0) + 1;
-        issues[id].history.push({ round, status: "regressed" });
-      }
-    }
-    // MF-2: fixed 条目再次被报告（seen）→ 回归：转 regressed + fixAttempts+1（已确认修复
-    // 的问题复发同样计修复失败，needs-redesign 可达）；openStreak 由下方统一 if 累计
-    // （首轮回归 1）。未 seen → 保持 fixed（漏报不误转）。修复前此处无转换——fixed 条目
-    // 复发时 fixAttempts/openStreak 均不增长，与收敛终止组合后默认配置下 R3 即以
-    // converged 提前终止而 must-fix 仍活跃（MF-2）。
-    if (issue.status === "fixed" && seen.has(id)) {
-      issues[id].status = "regressed";
-      issues[id].fixAttempts = (issue.fixAttempts || 0) + 1;
-      issues[id].history.push({ round, status: "regressed" });
-    }
-    // open/regressed 且本轮仍在（seen）→ openStreak +1（跨轮字段）；漏报（未 seen）不增长（保守）
-    if (seen.has(id) && (issues[id].status === "open" || issues[id].status === "regressed")) {
-      issues[id].openStreak = (issues[id].openStreak || 0) + 1;
-      if (issues[id].openStreak >= stuckThreshold) stuckIds.push(id);
-    }
+    if (applyReconciledFix(entry, id, fixedDeclared, round)) continue;
+    applyFixAttemptedOutcome(entry, issue.status, id, seen, round);
+    applyFixedRegression(entry, issue.status, id, seen, round);
+    accrueOpenStreak(entry, id, seen, stuckThreshold, stuckIds);
   }
-  // 新 ID（reviewer 声明的新发现）→ open
   for (const id of seen) {
     if (issues[id]) continue;
-    issues[id] = {
-      firstSeen: round, severity: "unknown", status: "open", openStreak: 1,
-      history: [{ round, status: "open" }], fixAttempts: 0,
-    };
-    // 新 ID 首现 openStreak=1：统一判定语义 openStreak >= stuckThreshold（与下方既有
-    // 条目分支一致）。边界：stuckThreshold=1 时新 ID 首现即 stuck（语义自洽：阈值为 1
-    // 表示「任何未解决条目出现即视为卡住」，属显式配置而非 bug）。
-    if (issues[id].openStreak >= stuckThreshold) stuckIds.push(id);
+    registerNewFinding(issues, id, round, stuckThreshold, stuckIds);
   }
   const knownRemaining = computeKnownRemaining(issues);
   return { issues, stuck: stuckIds.length > 0, stuckIds, knownRemaining };
@@ -1417,7 +1487,10 @@ const FALLOW_DEF = { name: "fallow-scan", title: "FALLOW STATIC ANALYSIS", repor
  *
  * - def 只含标识（path/name/report/title），**不读文件**——agent 内容的加载与 systemPrompt
  *   注入由主线程 resolveAgentOpts（agent-call 按 path 加载）统一完成
- * - `fallow-scan` 是脚本内部保留字（fallowScan 参数前置插入的首批），非用户参数值域
+ * - `fallow-scan` 是脚本内部保留字（fallowScan 参数前置插入的首批），非用户参数值域：
+ *   本函数对字面值仍静默映射 FALLOW_DEF（fallowScan 前置批与 batchN 兼容形态依赖此
+ *   映射），用户参数侧的拒收在脚本层——fixAgent=fallow-scan 由 review-fix-loop.js
+ *   在调用本函数前 fail-fast（RX2-F2），防 fix 派发静默退化为通用 subagent
  * @param batchNames 批内 agentRef 路径数组
  */
 function resolveAgentDefs(batchNames) {

package/workflows/review-fix-loop-utils.d.cts

@@ -0,0 +1,287 @@
+// review-fix-loop-utils.cjs 的消费面类型声明（test-only 类型基建：src/__tests__/
+// review-fix-loop-utils.test.ts 顶层 import 本模块；tsc 纳入测试后需要声明锚点）。
+// 与 .cjs 同名同目录的 .d.cts 会被 TS 自动关联（相对路径导入解析）。
+// 仅声明测试消费的导出——未来消费新导出时在编译期报缺并在此补充。
+// 参数对象字段全可选（cjs 侧对缺省字段有兜底/容忍 undefined 的拼接语义）。
+
+/** fail 回调（测试侧实现为抛错终止，签名兼容 (msg: string) => void）。 */
+export type FailFn = (msg: string) => void;
+
+/** 评分条目（landScores/backfillFixRegression 的 scores 元素形态）。 */
+export interface ScoreEntry {
+  round?: number;
+  targetKind?: string;
+  targetName?: string;
+  batch?: number;
+  dimensions: Record<string, unknown>;
+  total?: number | null;
+  note?: string;
+  [key: string]: unknown;
+}
+
+/** workflow 跨轮状态（applyCleanRoundBackfill 的 state 形态）。 */
+export interface AgentState {
+  issues: Record<string, IssueEntry>;
+  knownRemaining: string[];
+  scores: ScoreEntry[];
+  fixResults?: unknown[];
+  dormant?: Array<{ id: string; reason?: string; detail?: string; round?: number; revived?: boolean; [key: string]: unknown }>;
+  idMap?: { round?: number; map?: Record<string, string> };
+  [key: string]: unknown;
+}
+
+/** issue 记录（issues map 值形态，测试按用例裁剪字段）。 */
+export interface IssueEntry {
+  id?: string;
+  issue_id?: string;
+  title?: string;
+  status?: string;
+  severity?: string;
+  description?: string;
+  reason?: string;
+  fixAttempts?: number;
+  openStreak?: number;
+  firstSeen?: number;
+  history?: Array<{ round?: number; status?: string; [key: string]: unknown }>;
+  deferredReason?: string;
+  [key: string]: unknown;
+}
+
+export declare function parseBatches(args: Record<string, unknown>, fail: FailFn): string[][];
+export declare function resolveBatchNames(
+  rawBatchNames: string[] | undefined,
+  batches: string[][],
+  fail: FailFn,
+): string[];
+export declare function buildReviewInstruction(targetType: string, target: string): string;
+export declare function lockReviewBase(
+  targetType: string,
+  target: string,
+  run?: (cmd: string) => string,
+): { base: string; hash: string };
+export declare function buildScopedRecheckPrompt(args: {
+  header?: string;
+  round?: number;
+  max?: number;
+  roundDir?: string;
+  reportFile?: string;
+  modifiedFiles?: string[];
+  affectedFiles?: string[];
+  aggPath?: string;
+  fixResult?: Record<string, unknown> | null;
+  aggRound?: number;
+  fixRound?: number;
+  reviewPrompt?: string;
+  reviewInstruction?: string;
+}): string;
+export declare function wrapUntrusted(content: string, tag: string): string;
+export declare function buildFixPrompt(args: {
+  header?: string;
+  reportContent?: string;
+  fixPrompt?: string;
+  commitInstr?: string;
+  caution?: string[];
+  guidance?: Array<{ id?: string; guidance?: string; [key: string]: unknown }>;
+}): string;
+export declare function buildAggregatorPrompt(args: {
+  header?: string;
+  round?: number;
+  max?: number;
+  roundDir?: string;
+  reviewResults?: unknown;
+  prevFixResult?: unknown;
+  prevTitles?: unknown;
+}): string;
+export declare function resolveReviewReportPath(
+  parsed: { report_content?: string; report_file?: string; [key: string]: unknown },
+  roundDir: string,
+  reportName: string,
+): { reportFile?: string; reportContent: string; [key: string]: unknown };
+export declare function normalizeFixResult(raw: unknown): {
+  fixed_count: number;
+  fixes: Array<{ issue_id: string; description?: string; [key: string]: unknown }>;
+  deferred: Array<{ issue_id: string; reason?: string; severity?: string; [key: string]: unknown }>;
+  [key: string]: unknown;
+};
+export declare function normIssueId(s: string | null | undefined): string;
+export declare function findIssueKey(
+  issues: Record<string, unknown> | null | undefined,
+  issueId: string,
+): string | undefined;
+export declare function hasOpenResidue(issues: Record<string, unknown> | undefined): boolean;
+export declare function normTitle(s: string | undefined): string;
+export declare function matchByTitle(
+  title: string,
+  issues: Record<string, unknown>,
+  dormant: unknown,
+): { kind: string; id?: string; [key: string]: unknown };
+export declare function nextFreeId(existingIds: string[]): string;
+export declare function resolveIssueIdentity(
+  entry: { id?: string; title?: string; [key: string]: unknown },
+  ctx: { issues: Record<string, unknown>; dormant: unknown[] },
+): { kind: string; id: string; [key: string]: unknown };
+export declare function translateId(
+  idMap: Record<string, string> | null | undefined,
+  id: string,
+  issues: Record<string, unknown>,
+): string;
+export declare function translateReconSets(
+  reconSeen: Set<unknown>,
+  reconEscalate: Set<unknown>,
+  reconFixed: Set<unknown>,
+  idMap: Record<string, string>,
+  issues: Record<string, unknown>,
+): { seen: Set<string>; escalate: Set<string>; fixed: Set<string> };
+export declare function validateFixResult(
+  result: unknown,
+  mustFixIds?: string[],
+  trackedIssues?: Record<string, unknown>,
+  idMap?: Record<string, string>,
+): Array<Record<string, unknown>>;
+export declare function reconcileIssues(
+  prevIssues: Record<string, unknown>,
+  opts: {
+    seenIds: Set<string> | string[];
+    escalateIds?: Set<string> | string[];
+    fixedIds?: Set<string> | string[];
+    round: number;
+    stuckThreshold: number;
+  },
+): { issues: Record<string, IssueEntry>; stuck: boolean; knownRemaining: string[]; [key: string]: unknown };
+export declare function normalizeReviewResult(raw: unknown): {
+  report_file?: string;
+  report_content?: string;
+  [key: string]: unknown;
+};
+export declare function checkConvergence(opts: {
+  prevStreak?: number;
+  newFindings?: number;
+  newFindingsCritical?: number;
+  convergeNewIssues?: number;
+  convergeRounds?: number;
+}): { converged: boolean; streak: number; [key: string]: unknown };
+export declare function findNeedsRedesign(
+  issues: Record<string, unknown>,
+  maxFixAttempts: number,
+): Array<{ issue_id: string; [key: string]: unknown }>;
+export declare function parseResult(raw: unknown): Record<string, unknown>;
+export declare function normalizeAggregatorResult(raw: unknown): {
+  must_fix: number;
+  suggestion: number;
+  must_fix_ids: Array<{ id?: string; issue_id?: string; severity?: string; [key: string]: unknown }>;
+  scores?: ScoreEntry[];
+  [key: string]: unknown;
+};
+export declare function parseAggregatedMd(content: string): {
+  must_fix: number;
+  suggestion: number;
+  [key: string]: unknown;
+};
+export declare function resolveRunRoot(opts: {
+  runId?: string;
+  cwd?: string;
+  homeDir?: string;
+  tmpDir?: string;
+  exec?: (cmd: string) => string;
+  mkdir?: (p: string) => void;
+}): { root: string; slug: string; degraded: boolean; [key: string]: unknown };
+export declare function computeOrigin(
+  entry: { [key: string]: unknown },
+  opts: { lastModifiedFiles?: string[]; fixImpactFiles?: string[] },
+): { origin: string; evidence?: unknown; [key: string]: unknown };
+export declare function recordDormant(
+  dormant: unknown[],
+  entries: unknown[],
+  round: number,
+  excludeIds?: unknown[] | Set<unknown>,
+): Array<{ id: string; [key: string]: unknown }>;
+export declare function filterActiveIds(
+  entries: Array<{ id?: string; adjudication?: string; [key: string]: unknown }>,
+): string[];
+export declare function filterDormantFromRecon(
+  reconSeen: Set<string>,
+  reconEscalate: Set<string>,
+  dormant: Array<{ id?: string; [key: string]: unknown }>,
+): { seen: Set<string>; escalate: Set<string> };
+export declare function landScores(
+  existingScores?: ScoreEntry[] | null,
+  rawScores?: Array<Record<string, unknown> | null> | null,
+  batchIndex?: number,
+): { scores: ScoreEntry[]; landed: number; malformed: number };
+export declare function countMissingFields(entries: unknown[]): {
+  active: number;
+  missingGuidance: number;
+  missingEvidence: number;
+};
+export declare function backfillFixRegression(opts: {
+  scores?: ScoreEntry[];
+  fixResult?: Record<string, unknown> | null;
+  issues?: Record<string, unknown>;
+  round?: number;
+  batch?: number;
+  cleanRound?: boolean;
+  mode?: string;
+}): ScoreEntry[];
+export declare function applyCleanRoundBackfill(
+  state: Omit<AgentState, "issues"> & { issues: Record<string, unknown> | Record<string, IssueEntry> },
+  opts: {
+    reconSeen: Set<string> | string[];
+    reconEscalate: Set<string> | string[];
+    reconFixed?: Set<string> | string[];
+    round: number;
+    stuckThreshold: number;
+    batch?: number;
+  },
+): { state: AgentState; stuck: boolean; [key: string]: unknown };
+export declare function resolveAggregatorModel(raw: string | undefined, fallback: string | string | undefined): string;
+export declare function resolveAgentDefs(batchNames: string[]): Array<Record<string, unknown>>;
+export declare function recordAgentClean(
+  state: { agentStatus: Record<string, unknown>; fixCount?: number },
+  agentName: string,
+  batchIndex: number,
+): void;
+export declare function recordAgentDirty(
+  state: { agentStatus: Record<string, unknown>; fixCount?: number },
+  agentName: string,
+  mustFix: number,
+  batchIndex: number,
+): void;
+export declare function shouldSkipAgent(status: unknown, fixCount: number, batchIndex: number): boolean;
+export declare function updateStuckState(
+  prevMustFix: number,
+  stuckCount: number,
+  mustFix: number,
+  stuckThreshold: number,
+): { prevMustFix: number; stuckCount: number; [key: string]: unknown };
+export declare function resolveBatchTerminated(
+  batchClean: boolean,
+  terminated: string | undefined,
+): string | undefined;
+
+export declare const TARGET_TYPES: string[];
+export declare const VALID_ARG_KEYS: Set<string>;
+export declare const ROUND_CONTEXT_MARKER: string;
+export declare function buildR1ReviewPrompt(args: {
+  header?: string;
+  roundDir?: string;
+  reportFile?: string;
+  prevBatchesHint?: string;
+  reviewPrompt?: string;
+  reviewInstruction?: string;
+}): string;
+export declare function buildR2ReviewPrompt(args: {
+  header?: string;
+  round?: number;
+  max?: number;
+  roundDir?: string;
+  reportFile?: string;
+  aggPath?: string;
+  fixResult?: Record<string, unknown> | null;
+  aggRound?: number;
+  fixRound?: number;
+  knownRemaining?: string[];
+  dormant?: unknown[];
+  openIssues?: unknown[];
+  reviewPrompt?: string;
+  reviewInstruction?: string;
+}): string;

package/workflows/review-fix-loop.js

@@ -22,9 +22,10 @@
 //
 // 用法：
 //   workflow run review-fix-loop --args targetType=git-diff target=main \
-//     batch1="/path/reviewer-a.md,/path/reviewer-b.md" autoCommit=true
+//     batch1="/path/reviewer-a.md,/path/reviewer-b.md" autoCommit=true（pi 宿主语法）
 //   workflow run review-fix-loop --args targetType=file target=/path/to/doc.md \
-//     batch1="/path/doc-reviewer.md" autoCommit=false
+//     batch1="/path/doc-reviewer.md" autoCommit=false（pi 宿主语法）
+//   zsw workflow --workflow review-fix-loop --task "<任务书>" --workdir <绝对路径>（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际执行以 SessionStart 注入段的 node "<绝对路径>/bin/zsw.js" 形态为准；per-workflow 参数用 zsw 专属 flag --target-type/--target/--batch1 等，语义见 @pi-meta parameters）
 //
 // S4 路径统一：batch1..batchN/fixAgent 值 = agentRef（.md 绝对路径，<available_subagents> 的
 // <location>）；fallowScan=true 独立参数前置插入静态分析批次（不占 batchN）。
@@ -75,7 +76,8 @@ usage: |
   - batch1..batchN 与 agents 互斥（至少传一个 batchN）；值 = agentRef（.md 绝对路径，<available_subagents> 的 <location>）
   - fixAgent：fix 阶段执行者（agentRef），缺省用通用 subagent + 内联 fixPrompt
   - fallowScan=true 仅 targetType=git-diff 合法（前置静态分析批次，不占 batchN）
-  - 示例：workflow run review-fix-loop --args targetType=git-diff target=main batch1="/path/fallow-agent.md,/path/reviewer.md" autoCommit=true
+  - 示例（pi 宿主语法）：workflow run review-fix-loop --args targetType=git-diff target=main batch1="/path/fallow-agent.md,/path/reviewer.md" autoCommit=true
+  - 示例（zsw 宿主直参语法；`zsw` 为 CLI 简写，实际以注入段 node "<绝对路径>/bin/zsw.js" 形态为准）：zsw workflow --workflow review-fix-loop --task "<任务书>" --workdir <绝对路径>（per-workflow 参数用 zsw 专属 flag --target-type/--target/--batch1 等，语义见 @pi-meta parameters）
 */
 
 // ── 参数解析 + 白名单校验（fail-fast） ────────────────────────────
@@ -187,11 +189,18 @@ const skipCleanAgents = coerceBool($ARGS.skipCleanAgents, true);
 // RC-5（fix 后全批全量重审放大 token）在默认场景消失。传 true 启用可选强回归模式：fix 后重派
 // 全批，clean agent 走限定 prompt（buildScopedRecheckPrompt，只审 modifiedFiles，5.5）。
 const recheckAfterFix = coerceBool($ARGS.recheckAfterFix, false);
-// fixAgent（5.3）：值语义同 batchN 的 agent 项（内置名 / agent.md 路径），解析复用
-// resolveAgentDefs 白名单与加载逻辑。传入时 fix 阶段用 agent({agent: ...}) 派发（代码场景
-// 的 verify 命令写在该 agent.md 内）；未传保持现状（通用 subagent + 内联 prompt）。
+// fixAgent（5.3）：值 = .md 绝对路径（同 batchN 的 agent 项值域）；`fallow-scan` 是
+// fallowScan 参数的内部保留字，显式拒收（RX2-F2）——resolveAgentDefs 对它会静默映射
+// 为内置工具型 FALLOW_DEF（无 path），fix 派发即退化为通用 subagent + 内联 prompt，
+// 与「不属于 fixAgent 值域」相悖，故在解析前 fail-fast。其余合法值解析复用
+// resolveAgentDefs 白名单与加载逻辑：传入时 fix 阶段用 agent({agent: ...}) 派发
+// （代码场景的 verify 命令写在该 agent.md 内）；未传保持现状（通用 subagent + 内联 prompt）。
 const FIX_AGENT_RAW = typeof $ARGS.fixAgent === "string" && $ARGS.fixAgent.trim()
   ? $ARGS.fixAgent.trim() : undefined;
+if (FIX_AGENT_RAW === "fallow-scan") {
+  fail("fixAgent=fallow-scan 是内部保留字：fallow-scan 是 fallowScan 前置批次的内部标记，不属于 fixAgent 值域。" +
+    "要跑 fallow 静态分析前置批请用参数 fallowScan=true（需 targetType=git-diff）；要指定 fix 执行者请传 agent .md 绝对路径。");
+}
 const FIX_DEF = FIX_AGENT_RAW ? resolveAgentDefs([FIX_AGENT_RAW])[0] : null;
 // 5.7 收敛终止参数：maxFixAttempts（needs-redesign 阈值，RC-7）/ convergeNewIssues +
 // convergeRounds（新发现率收敛阈值）
@@ -1039,7 +1048,9 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
       const r1IdMap = {};
       for (const entry of agg.must_fix_ids) {
         const id = typeof entry === "string" ? entry : entry && entry.id;
-        if (!id || state.issues[id]) continue;
+        // Object.hasOwn：truthy 查表会让原型链键（"__proto__"/"toString"）误判已登记
+        // 而 continue 跳过真实条目（与 utils findIssueKey 同款加固；id 来自 LLM 产出）。
+        if (!id || Object.hasOwn(state.issues, id)) continue;
         if (!activeIds.has(id)) continue;
         const resolved = resolveIssueIdentity(
           typeof entry === "string" ? { id } : entry,