Skip to content

Adonis0123/adonis-skills / skills/agentic-review-handoff

agentic-review-handoff

Verified

Validate pasted review findings before fixes; run same-session automatic Git review-fix-re-review with a headless Reviewer and no redundant confirmation; start fresh-eyes Git diff Review Intake; resume review-loop sessions or packets; get a DecisionConsult from another AI; or run first-principles/DDD/high-cohesion review. Requires Git and review/consult intent; ordinary implementation or commit-only requests do not start a review loop.

scripts/review-loop/auto-run.mjs

View on GitHub
/**
 * review-loop auto run — single-writer Fixer-driven loop with headless Reviewer.
 *
 * Commands (via cmdRun / cmdContinue):
 *   run --repo [--reviewer] [--completion pass|review] [--base] [--rounds 3] [--packet]
 *   run --continue --repo [--packet] [--rounds]
 */
import fs from "node:fs";
import path from "node:path";
import {
  resolveRepoRoot,
  resolveBranch,
  ensureReviewHandoffLayout,
  createPacketFile,
  readPacketMeta,
  runtimeDir,
  latestActivePacket,
  validatePacketPath,
  lastPhysicalH1,
  listPhysicalH1s,
} from "./repositories.mjs";
import { resolveFromPrefs } from "./prefs.mjs";
import {
  assertLauncherMatchesProduct,
  assertLauncherName,
  createAdapter,
  parseFallback,
  DELIVERY_UNKNOWN,
} from "./adapters.mjs";
import {
  computeEvidenceIdentity,
  freezeRoundEvidence,
  normalizePathFilter,
  resolveBaseSha,
} from "./evidence.mjs";
import {
  parseReviewFindings,
  parseReReview,
  formatReviewFindingsStage,
  formatReReviewStage,
  formatDecisionClosureStage,
  lifecycleForVerdict,
  parseMarkdownTables,
  findingFromRow,
  missingFindingsTableColumns,
  extractVerdict,
} from "./schema.mjs";
import {
  appendStageAuto,
  seedPacketHash,
  loadRunState,
  saveRunState,
  contentHash,
} from "./stage-writer.mjs";

const DEFAULT_ROUNDS = 3;
const REVIEWER_REQUIRED_MESSAGE =
  "REVIEWER_REQUIRED: pass --host=<your product> to use the saved Reviewer preference " +
  "(review-loop prefs), or --reviewer=codex|grok|claude";

function reviewedEvidenceIdentity({ baseSha, evidence, sourceRound }) {
  return {
    baseSha,
    pathFilter: normalizePathFilter(evidence.pathFilter),
    digest: evidence.digest,
    coveredPaths: Array.isArray(evidence.coveredPaths)
      ? (normalizePathFilter(evidence.coveredPaths) ?? [])
      : null,
    sourceRound,
  };
}

/**
 * Build Reviewer prompt for a round.
 */
export function buildReviewerPrompt({
  round,
  packetPath,
  baseSha,
  evidencePath,
  paths,
  priorFindingIds,
  correctionNote,
}) {
  const schemaRound1 = `Output MUST include:
1. A markdown findings table with columns:
   ID | 严重度 | 标题 | 证据 | Target files | Required fix | Acceptance check
   Severity must be [阻塞] or [非阻塞].
2. A final Verdict line exactly one of: PASS | PASS_WITH_CONCERNS | BLOCKED | NO_FINDINGS
Rules:
- PASS / NO_FINDINGS: zero blocking findings.
- BLOCKED: ≥1 [阻塞] finding with falsifiable breakage.
- PASS_WITH_CONCERNS: only [非阻塞] remaining.
- Style/taste is never blocking.
- Never place a literal pipe character in table cells (TypeScript unions, shell pipes, etc.). Use &#124; instead.`;

  const schemaRoundN = `Output MUST include ALL of:
1. ## Prior Findings Reassessment — table: ID | 状态(resolved|partially|unresolved) | 复核证据
   Cover every prior finding ID: ${priorFindingIds.join(", ") || "(none)"}
2. ## New Findings — same columns as first-round findings table (only load-bearing blockers allowed)
3. ## Regression Surface — short conclusion
4. Exactly one terminal Verdict: PASS | PASS_WITH_CONCERNS | BLOCKED | NO_FINDINGS
Missing any section (including Verdict) is malformed.
Never place a literal pipe character in table cells. Use &#124; instead.`;

  const parts = [
    "You are a read-only code reviewer in an auto review loop.",
    `Packet path: ${packetPath}`,
    `Base SHA (pinned): ${baseSha}`,
    `Frozen evidence file (authoritative — read this file): ${evidencePath}`,
    `Paths in scope: ${(paths || []).join(", ") || "(see evidence file)"}`,
    `Round: ${round}`,
    round <= 1 ? schemaRound1 : schemaRoundN,
    "Do not modify any files. Do not write the packet. Stdout only.",
    "Do not block merely because a useful check would write caches or temporary files; report that check for the visible Fixer/host to run.",
  ];
  if (correctionNote) {
    parts.push(`CORRECTION (previous output was malformed): ${correctionNote}`);
    parts.push("Re-emit a complete valid response only.");
  }
  return parts.join("\n");
}

/**
 * @param {object} opts
 * @param {string} [opts.repoRoot]
 * @param {string} [opts.cwd]
 * @param {string} [opts.reviewer]  codex|grok|claude; required unless continue inherits
 * @param {string} [opts.reviewerCommand] account launcher name (e.g. grok002)
 * @param {string} [opts.base]
 * @param {number} [opts.rounds]
 * @param {'review'|'pass'} [opts.completion]
 * @param {boolean} [opts.untilPass]
 * @param {string} [opts.packetPath]
 * @param {string} [opts.packetId]
 * @param {boolean} [opts.continue]
 * @param {boolean} [opts.intake]
 * @param {string} [opts.scopeSlug]
 * @param {(cfg: object) => ReturnType<typeof createAdapter>} [opts.adapterFactory]
 * @param {object} [opts.adapterOpts] extra adapter options (bin, timeoutMs, ...)
 */
export async function cmdRun(opts) {
  const repoRoot = opts.repoRoot || resolveRepoRoot(opts.cwd || process.cwd());
  const isContinue = Boolean(opts.continue || opts.cont);
  // No Reviewer named: the saved preference picks it and the timeout fallbacks (review-loop prefs).
  let reviewerFrom = null;
  if (!isContinue && !(opts.reviewer ?? opts.productReviewer) && opts.host) {
    const picked = resolveFromPrefs({
      host: opts.host,
      env: opts.env ?? process.env,
    });
    opts = {
      ...opts,
      reviewer: picked.reviewer,
      fallback: opts.fallback ?? picked.fallback,
    };
    reviewerFrom = {
      source: picked.prefs.source,
      order: picked.prefs.order,
      host: String(opts.host).toLowerCase(),
    };
  }
  const isIntake = opts.intake === true;
  if (isIntake && isContinue) {
    throw new Error("--intake cannot be combined with --continue");
  }
  if (isIntake && (opts.packetPath || opts.packetId)) {
    throw new Error(
      "--intake cannot be combined with a caller-provided packet",
    );
  }
  // Validate selection before creating any packet: a fresh run has no default
  // Reviewer, and a bad flag must not leave an orphan packet behind.
  const requestedReviewer = opts.reviewer ?? opts.productReviewer ?? null;
  if (!isContinue && !requestedReviewer) {
    throw new Error(REVIEWER_REQUIRED_MESSAGE);
  }
  if (
    requestedReviewer != null &&
    !["codex", "grok", "claude"].includes(
      String(requestedReviewer).toLowerCase(),
    )
  ) {
    throw new Error(
      `--reviewer must be codex|grok|claude, got ${requestedReviewer}`,
    );
  }
  if (opts.reviewerCommand != null) {
    assertLauncherName(opts.reviewerCommand);
    if (requestedReviewer) {
      assertLauncherMatchesProduct(
        opts.reviewerCommand,
        String(requestedReviewer).toLowerCase(),
      );
    }
  }
  ensureReviewHandoffLayout(repoRoot);
  const branch = resolveBranch(repoRoot);
  // Resolve / create packet
  let packetPath = opts.packetPath || null;
  let packetId = opts.packetId || null;
  if (!packetPath && packetId) {
    // Locate by packet_id's own slug (never recompute slug from current branch algorithm)
    const segments = String(packetId).split("/");
    if (segments.length === 2 && segments[0] && segments[1]) {
      const candidate = path.join(
        repoRoot,
        ".review-handoff",
        "active",
        segments[0],
        `${segments[1]}.md`,
      );
      if (fs.existsSync(candidate)) packetPath = candidate;
    }
  }
  if (!packetPath && isContinue) {
    packetPath = latestActivePacket(repoRoot, branch);
  }

  if (!packetPath) {
    if (isContinue) throw new Error("run --continue requires an active packet");
    const created = createPacketFile(
      repoRoot,
      branch,
      opts.scopeSlug || "auto-loop",
      isIntake ? "intake" : "handoff",
    );
    packetPath = created.packetPath;
    packetId = created.packetId;
  }

  // Containment: writes/continues require active packet; read of archive only if already archived terminal
  const absPacket = path.isAbsolute(packetPath)
    ? packetPath
    : path.resolve(repoRoot, packetPath);
  const validated = validatePacketPath(repoRoot, branch, absPacket, {
    activeOnly: isContinue || Boolean(opts.packetPath),
  });
  // First create path already under active; continue/explicit packet must stay active
  packetPath = validated.packetPath;
  packetId = validated.packetId;
  const packetMeta = readPacketMeta(packetPath);
  if (packetMeta.frontmatter.mode === "classic") {
    throw new Error(
      `review-loop run cannot take over a classic packet: ${packetPath}`,
    );
  }

  // Reviewer: explicit flag wins; else continue inherits prior. A fresh run has
  // no silent default: the caller asks the user once (or picks a product other
  // than the visible host) and passes it, so a Codex host never reviews itself
  // by accident.
  const priorState = loadRunState(repoRoot, packetId) ?? {};
  let reviewer = opts.reviewer || opts.productReviewer || null;
  const inherited = !reviewer && isContinue && Boolean(priorState.reviewer);
  if (inherited) reviewer = priorState.reviewer;
  if (!reviewer) {
    throw new Error(REVIEWER_REQUIRED_MESSAGE);
  }
  reviewer = String(reviewer).toLowerCase();
  if (!["codex", "grok", "claude"].includes(reviewer)) {
    throw new Error(`--reviewer must be codex|grok|claude, got ${reviewer}`);
  }
  // Account launcher (e.g. grok002) stays bound to the product it was chosen for.
  let reviewerCommand = opts.reviewerCommand ?? null;
  if (
    reviewerCommand == null &&
    isContinue &&
    priorState.reviewerCommand &&
    priorState.reviewer === reviewer
  ) {
    reviewerCommand = priorState.reviewerCommand;
  }
  if (reviewerCommand != null) {
    assertLauncherName(reviewerCommand);
    assertLauncherMatchesProduct(reviewerCommand, reviewer);
  }
  // Products to try when the Reviewer times out; continue inherits the list it started with.
  const fallback = parseFallback(
    opts.fallback ?? (isContinue ? priorState.fallback : null),
    reviewer,
  );

  // completion=pass means every actionable in-scope concern is fixed and
  // re-reviewed within budget. Continue inherits the original authorization.
  let completion = opts.completion ?? (opts.untilPass ? "pass" : null);
  if (!completion && isContinue && priorState.completion) {
    completion = priorState.completion;
  }
  completion = String(completion || "pass").toLowerCase();
  if (!["review", "pass"].includes(completion)) {
    throw new Error(`--completion must be review|pass, got ${completion}`);
  }

  // F4: continue inherits persisted roundsBudget unless explicit --rounds.
  // `--rounds +N` is additive authorization (T5); bare N is absolute ceiling.
  const roundsBudget = resolveRoundsBudget(opts.rounds, priorState, isContinue);

  /** @type {{ from: string, to: string, reason: string }[]} */
  const fallbacks = [];
  const result = await withPacketLock(repoRoot, packetId, () =>
    runBody({
      ...opts,
      repoRoot,
      branch,
      packetPath,
      packetId,
      reviewer,
      reviewerCommand,
      fallback,
      fallbacks,
      completion,
      roundsBudget,
      isContinue,
    }),
  );
  // Say how the Reviewer was chosen, and which one timed out and who took over, whatever the outcome.
  if (!result || typeof result !== "object") return result;
  return {
    ...result,
    ...(reviewerFrom ? { reviewerFrom } : {}),
    ...(fallbacks.length ? { fallbacks } : {}),
  };
}

/**
 * Recompute the current worktree identity without writing packet/runtime files.
 * Callers compare baseSha + pathFilter + digest with a successful run result.
 */
export function cmdEvidence(opts) {
  const repoRoot = opts.repoRoot || resolveRepoRoot(opts.cwd || process.cwd());
  const baseSha = resolveBaseSha(repoRoot, opts.base);
  return {
    ok: true,
    status: "attested",
    evidence: computeEvidenceIdentity({
      repoRoot,
      baseSha,
      paths: normalizePathFilter(opts.paths ?? opts.path) ?? undefined,
    }),
  };
}

/**
 * Per-packet recoverable async lock (mkdir + dead-pid reclaim).
 * Holds the lock across awaited reviewer invokes.
 */
export async function withPacketLock(repoRoot, packetId, operation) {
  const lockDir = path.join(runtimeDir(repoRoot, packetId), ".auto-run.lock");
  const ownerFile = path.join(lockDir, "owner");
  const ownerToken = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;

  const tryAcquire = () => {
    fs.mkdirSync(lockDir);
    // N1: publish owner immediately after mkdir (no await between)
    fs.writeFileSync(ownerFile, `${ownerToken}\n${process.pid}\n`, "utf8");
  };

  const GRACE_MS = 2000;
  try {
    tryAcquire();
  } catch (err) {
    if (err?.code !== "EEXIST") throw err;
    let owner = "";
    let ownerMissing = false;
    try {
      owner = fs.readFileSync(ownerFile, "utf8");
    } catch {
      ownerMissing = true;
    }
    if (ownerMissing || !String(owner).trim()) {
      // N1/N2: incomplete or empty owner — honor short grace based on dir mtime, then reclaim
      let mtimeMs = 0;
      try {
        mtimeMs = fs.statSync(lockDir).mtimeMs;
      } catch {
        mtimeMs = 0;
      }
      if (mtimeMs && Date.now() - mtimeMs < GRACE_MS) {
        const e = new Error("packet lock held (owner not published yet)");
        // @ts-expect-error
        e.code = "PACKET_LOCK_HELD";
        throw e;
      }
      fs.rmSync(lockDir, { recursive: true, force: true });
      tryAcquire();
    } else {
      const oldPid = Number(String(owner).split("\n")[1] || 0);
      let alive = false;
      if (oldPid > 0) {
        try {
          process.kill(oldPid, 0);
          alive = true;
        } catch {
          alive = false;
        }
      }
      if (alive || !oldPid) {
        // invalid/zero pid with non-empty owner → treat as held unless stale mtime
        let mtimeMs = 0;
        try {
          mtimeMs = fs.statSync(lockDir).mtimeMs;
        } catch {
          mtimeMs = 0;
        }
        if (alive || (mtimeMs && Date.now() - mtimeMs < GRACE_MS)) {
          const e = new Error(`packet lock held by pid ${oldPid || "unknown"}`);
          // @ts-expect-error
          e.code = "PACKET_LOCK_HELD";
          throw e;
        }
      }
      // reclaim stale lock only when owner pid is dead (or grace expired for invalid pid)
      fs.rmSync(lockDir, { recursive: true, force: true });
      tryAcquire();
    }
  }

  try {
    return await operation();
  } finally {
    // Only delete if we still own the lock
    try {
      const cur = fs.readFileSync(ownerFile, "utf8");
      if (cur.startsWith(ownerToken)) {
        fs.rmSync(lockDir, { recursive: true, force: true });
      }
    } catch {
      /* ignore */
    }
  }
}

async function runBody(ctx) {
  const {
    repoRoot,
    packetPath: initialPacketPath,
    packetId,
    reviewer: requestedReviewer,
    reviewerCommand: requestedCommand,
    fallback = [],
    fallbacks = [],
    completion,
    roundsBudget,
    isContinue,
    base,
    adapterFactory,
    adapterOpts,
  } = ctx;
  // The Reviewer of this round: the requested one, or a fallback after it timed out.
  let reviewer = requestedReviewer;
  let reviewerCommand = requestedCommand;

  let packetPath = initialPacketPath;
  let state = loadRunState(repoRoot, packetId) ?? {};

  // Pin base SHA BEFORE any external call (A6)
  let baseSha = state.baseSha;
  if (!baseSha) {
    baseSha = resolveBaseSha(repoRoot, base);
  }
  if (!state.packetHash) {
    seedPacketHash(repoRoot, packetId, packetPath);
    state = loadRunState(repoRoot, packetId);
  }

  // Reconciliation BEFORE Reviewer: hash drift fail-closed; optional ledger rebuild.
  // No pendingStage auto-replay (v3.3.1 SIMPLIFY_TO_C — crash-safe dual-write not claimed).
  const recon = reconcileRuntimeState({
    repoRoot,
    packetId,
    packetPath,
    state,
  });
  if (recon.error) return recon.error;
  state = recon.state;
  if (recon.packetPath) packetPath = recon.packetPath;

  // Pin packet baseline BEFORE long Reviewer await (F1: never re-read as trusted oldHash later)
  const roundStartPacketHash =
    state.packetHash || contentHash(fs.readFileSync(packetPath, "utf8"));

  // Persist base + reviewer + baseline early so DELIVERY_UNKNOWN retries cannot drift
  saveRunState(repoRoot, packetId, {
    ...state,
    baseSha,
    reviewer,
    reviewerCommand,
    fallback,
    completion,
    packetHash: roundStartPacketHash,
    roundStartPacketHash,
    pendingStage: null, // clear stale journal if present after explicit fail-closed above
    updated: new Date().toISOString(),
  });
  state = loadRunState(repoRoot, packetId);

  // Round from reconciled durable state (not only raw pre-recovery state.round)
  const round = Number(state.round ?? 0);
  const nextRound = isContinue ? round + 1 : Math.max(round, 0) + 1;

  const metaNow = readPacketMeta(packetPath);
  if (!isContinue) {
    if (round > 0) {
      throw new Error(
        `packet already has round=${round} (lastVerdict=${state.lastVerdict ?? "n/a"}); use run --continue or a new packet`,
      );
    }
    const physical = listPhysicalH1s(metaNow.text);
    const initialAnchor = physical.length === 1 ? physical[0].anchor : null;
    const legalInitialPair =
      (initialAnchor === "review_handoff" &&
        metaNow.lastAnchor === "review_handoff") ||
      (initialAnchor === "review_intake" &&
        metaNow.lastAnchor === "review_intake");
    if (!legalInitialPair) {
      throw new Error(
        `invalid initial packet anchors: physical=${physical.map((entry) => entry.anchor).join(",") || "none"}, last_anchor=${metaNow.lastAnchor ?? "none"}; expected one matched review_handoff or review_intake anchor`,
      );
    }
  }

  // If continuing from BLOCKED, require legitimate Fix Completion (A2)
  if (isContinue) {
    const meta = readPacketMeta(packetPath);
    if (meta.lifecycleState === "archived") {
      return terminalReport({
        status: "already_archived",
        packetPath,
        state,
        evidence: state.evidence ?? null,
        message: "Packet already archived",
      });
    }
    if (state.lastVerdict === "BLOCKED" || meta.lifecycleState === "blocked") {
      const last = lastPhysicalH1(meta.text);
      const lastIsFixCompletion =
        last &&
        (last.anchor === "fix_completion" ||
          /^fix_completion/.test(last.anchor));
      if (!lastIsFixCompletion || meta.lastAnchor !== "fix_completion") {
        throw new Error(
          "run --continue after BLOCKED requires a trailing # Fix Completion stage (use fix-completion)",
        );
      }
    }
  }

  const effectiveRound = isContinue ? nextRound : 1;
  if (effectiveRound > roundsBudget && !state.budgetOverride) {
    return budgetExhaustedReport({ packetPath, state, roundsBudget });
  }

  // Freeze evidence (reuse same-round file if already frozen — A6)
  // F3: continue inherits pinned path scope unless explicit new paths provided
  /** @type {string[]|undefined} */
  let pathFilter = ctx.paths;
  if (!pathFilter && ctx.path) {
    pathFilter = Array.isArray(ctx.path) ? ctx.path : [ctx.path];
  }
  if (typeof pathFilter === "string") {
    pathFilter = pathFilter
      .split(",")
      .map((s) => s.trim())
      .filter(Boolean);
  }
  if (
    (!pathFilter || !pathFilter.length) &&
    (Array.isArray(state.pathFilter) || Array.isArray(state.paths))
  ) {
    pathFilter = state.pathFilter || state.paths;
  }
  pathFilter = normalizePathFilter(pathFilter) ?? undefined;
  if (pathFilter?.length) {
    // Paths live only in auto-run-state.json. Never rewrite packet + reseed hash here:
    // that would absorb external packet edits and defeat PACKET_HASH_MISMATCH (R1 #1).
    saveRunState(repoRoot, packetId, {
      ...loadRunState(repoRoot, packetId),
      pathFilter,
      paths: pathFilter,
      baseSha,
      reviewer,
      updated: new Date().toISOString(),
    });
    state = loadRunState(repoRoot, packetId);
  }

  const evidenceDir = path.join(runtimeDir(repoRoot, packetId), "evidence");
  const evidencePath = path.join(evidenceDir, `round-${effectiveRound}.diff`);
  let evidence;
  if (fs.existsSync(evidencePath) && state[`evidenceRound${effectiveRound}`]) {
    const diffText = fs.readFileSync(evidencePath, "utf8");
    const digest = contentHash(diffText);
    if (state[`evidenceDigest${effectiveRound}`]) {
      if (state[`evidenceDigest${effectiveRound}`] !== digest) {
        return {
          ok: false,
          status: "evidence_hash_mismatch",
          message: `Frozen evidence round-${effectiveRound}.diff digest mismatch; refuse to proceed`,
          packetPath,
        };
      }
    } else {
      // F6: backfill digest on first resume of legacy state
      saveRunState(repoRoot, packetId, {
        ...loadRunState(repoRoot, packetId),
        [`evidenceDigest${effectiveRound}`]: digest,
      });
    }
    evidence = {
      evidencePath,
      diffText,
      lineCount: diffText.split("\n").length,
      paths:
        state.evidence?.sourceRound === effectiveRound &&
        Array.isArray(state.evidence.coveredPaths)
          ? state.evidence.coveredPaths
          : [],
      pathFilter: pathFilter || state.pathFilter || state.paths || null,
      coveredPaths:
        state.evidence?.sourceRound === effectiveRound &&
        Array.isArray(state.evidence.coveredPaths)
          ? state.evidence.coveredPaths
          : null,
      digest,
    };
  } else {
    evidence = freezeRoundEvidence({
      repoRoot,
      packetId,
      baseSha,
      round: effectiveRound,
      paths: pathFilter,
    });
    const digest = contentHash(evidence.diffText);
    saveRunState(repoRoot, packetId, {
      ...loadRunState(repoRoot, packetId),
      [`evidenceRound${effectiveRound}`]: true,
      [`evidenceDigest${effectiveRound}`]: digest,
      evidencePath: evidence.evidencePath,
      pathFilter: evidence.pathFilter,
      paths: pathFilter || state.paths || null,
      baseSha,
      reviewer,
      updated: new Date().toISOString(),
    });
    evidence.digest = digest;
  }

  const reviewEvidence = reviewedEvidenceIdentity({
    baseSha,
    evidence,
    sourceRound: effectiveRound,
  });

  const makeAdapter = (product, command) =>
    (adapterFactory || createAdapter)(product, {
      repoRoot,
      packetId,
      command,
      ...(adapterOpts || {}),
    });
  let adapter = makeAdapter(reviewer, reviewerCommand);

  const priorFindingIds =
    Array.isArray(state.findingIds) && state.findingIds.length
      ? state.findingIds
      : Object.keys(state.findingCatalog || {});
  // All historical blockers in catalog (not only currently open) so re-opened
  // blockers still gate PASS after a prior resolve.
  const priorBlockingIds = catalogBlockingIds(state.findingCatalog);
  let prompt = buildReviewerPrompt({
    round: effectiveRound,
    packetPath,
    baseSha,
    evidencePath: evidence.evidencePath,
    paths: evidence.paths,
    priorFindingIds,
  });

  // Invoke reviewer (long await — packet must not be re-baselined from post-await content)
  let invokeResult =
    effectiveRound <= 1 || !adapter.getSessionId?.()
      ? await adapter.newSession(prompt)
      : await adapter.resume(adapter.getSessionId(), prompt);

  // A Reviewer that timed out returned nothing and, being read-only, changed nothing: hand the same round to the
  // next product in --fallback, in a new session that reads the same packet. Only a timeout moves on; a stop by
  // the user or any other failure stays DELIVERY_UNKNOWN.
  const remaining = fallback.filter((p) => p !== reviewer);
  while (
    !invokeResult.ok &&
    invokeResult.timedOut === true &&
    remaining.length
  ) {
    const next = remaining.shift();
    fallbacks.push({ from: reviewer, to: next, reason: invokeResult.error });
    reviewer = next;
    reviewerCommand = null;
    saveRunState(repoRoot, packetId, {
      ...(loadRunState(repoRoot, packetId) ?? state),
      reviewer,
      reviewerCommand: null,
    });
    adapter = makeAdapter(reviewer, null);
    invokeResult = await adapter.newSession(prompt);
  }

  if (!invokeResult.ok) {
    return deliveryUnknownReport({
      packetPath,
      state,
      error: invokeResult.error,
      code: invokeResult.code || DELIVERY_UNKNOWN,
    });
  }

  // Parse + one correction
  let parsed =
    effectiveRound <= 1
      ? parseReviewFindings(invokeResult.text)
      : parseReReview(invokeResult.text, priorFindingIds, {
          priorBlockingIds:
            priorBlockingIds.length > 0
              ? priorBlockingIds
              : state.openBlocking || priorFindingIds,
        });

  if (!parsed.ok) {
    const correction = buildReviewerPrompt({
      round: effectiveRound,
      packetPath,
      baseSha,
      evidencePath: evidence.evidencePath,
      paths: evidence.paths,
      priorFindingIds,
      correctionNote: parsed.error,
    });
    const retry = await adapter.resume(adapter.getSessionId(), correction);
    if (!retry.ok) {
      return deliveryUnknownReport({
        packetPath,
        state,
        error: retry.error,
        code: retry.code || DELIVERY_UNKNOWN,
      });
    }
    parsed =
      effectiveRound <= 1
        ? parseReviewFindings(retry.text)
        : parseReReview(retry.text, priorFindingIds, {
            priorBlockingIds:
              priorBlockingIds.length > 0
                ? priorBlockingIds
                : state.openBlocking || priorFindingIds,
          });
    if (!parsed.ok) {
      return {
        ok: false,
        status: "malformed_reviewer_output",
        message: `Reviewer output malformed after one correction: ${parsed.error}`,
        packetPath,
        error: parsed.error,
        // packet must have no half-write
      };
    }
    invokeResult = retry;
  }

  // Structured finding ledger (runtime state) — single source for PWC concerns / close
  let findingCatalog;
  let openBlocking;
  let openConcerns;
  let findingIds;
  try {
    const sets = computeFindingLedger({
      effectiveRound,
      parsed,
      priorCatalog: state.findingCatalog || {},
      priorFindingIds,
    });
    findingCatalog = sets.findingCatalog;
    openBlocking = sets.openBlocking;
    openConcerns = sets.openConcerns;
    findingIds = sets.findingIds;
    assertVerdictOpenSets(parsed.verdict, openBlocking, openConcerns);
  } catch (err) {
    return {
      ok: false,
      status: "malformed_reviewer_output",
      message: `Finding ledger / verdict invariant failed: ${err?.message || err}`,
      packetPath,
      error: err?.message || String(err),
    };
  }

  const concernsRequireFix =
    parsed.verdict === "PASS_WITH_CONCERNS" && completion === "pass";
  // Default review mode keeps PWC as a user choice. Explicit completion=pass
  // turns it into ordinary in-scope work and avoids a second confirmation.
  const lifecycle = concernsRequireFix
    ? "blocked"
    : lifecycleForVerdict(
        effectiveRound <= 1 ? "review_findings" : "re_review",
        parsed.verdict,
      );

  let sectionMarkdown;
  let lastAnchor;
  if (effectiveRound <= 1) {
    sectionMarkdown = formatReviewFindingsStage({
      verdict: parsed.verdict,
      findings: parsed.findings,
      reviewer,
      baseSha,
      evidencePath: evidence.evidencePath,
      requireFixHandoff: concernsRequireFix,
    });
    // First-round strict PWC gets the same actionable handoff as BLOCKED.
    lastAnchor =
      parsed.verdict === "BLOCKED" || concernsRequireFix
        ? "fix_handoff"
        : "review_findings";
  } else {
    sectionMarkdown = formatReReviewStage({
      verdict: parsed.verdict,
      reassessments: parsed.reassessments,
      newFindings: parsed.newFindings,
      regressionSurface: parsed.regressionSurface,
      reviewer,
      round: effectiveRound,
      evidencePath: evidence.evidencePath,
    });
    lastAnchor = "re_review";
  }

  const nextLedger = {
    baseSha,
    round: effectiveRound,
    roundsBudget,
    reviewer,
    completion,
    lastVerdict: parsed.verdict,
    findingIds,
    findingCatalog,
    openBlocking,
    openConcerns,
    lifecycle,
    evidencePath: evidence.evidencePath,
    lineCount: evidence.lineCount,
    evidence: reviewEvidence,
  };

  // F1: after all Reviewer awaits (incl. one correction), still must match pre-await pin
  {
    const afterReviewHash = contentHash(fs.readFileSync(packetPath, "utf8"));
    if (afterReviewHash !== roundStartPacketHash) {
      return {
        ok: false,
        status: "packet_hash_mismatch",
        message:
          "PACKET_HASH_MISMATCH: packet changed during Reviewer invoke; refuse to absorb external rewrite (roundStartPacketHash pinned before await)",
        packetPath,
        expectedHash: roundStartPacketHash,
        actualHash: afterReviewHash,
      };
    }
  }

  let writeResult;
  try {
    writeResult = commitStageWithLedger({
      repoRoot,
      packetPath,
      packetId,
      sectionMarkdown,
      lastAnchor,
      lifecycleState: lifecycle,
      extra: {
        base_sha: baseSha,
        reviewer,
        round: String(effectiveRound),
        mode: "auto",
        completion,
      },
      nextLedger,
      priorState: loadRunState(repoRoot, packetId) ?? state,
      expectedHash: roundStartPacketHash,
    });
    packetPath = writeResult.packetPath;
  } catch (err) {
    if (err?.code === "PACKET_HASH_MISMATCH") {
      return {
        ok: false,
        status: "packet_hash_mismatch",
        message: err.message,
        packetPath,
      };
    }
    throw err;
  }

  const finalState = loadRunState(repoRoot, packetId) ?? {
    ...nextLedger,
    packetPath,
    packetHash: writeResult.packetHash,
  };

  // Clean packet STOP if present on terminal
  const packetStop = path.join(runtimeDir(repoRoot, packetId), "STOP");
  if (lifecycle === "archived" && fs.existsSync(packetStop)) {
    fs.unlinkSync(packetStop);
  }

  const concernRows = openConcerns.map((id) =>
    catalogEntryToConcern(id, findingCatalog[id]),
  );

  if (parsed.verdict === "BLOCKED") {
    // Budget is a ceiling: on the final budgeted round, BLOCKED exits immediately
    // (plan flowchart: 轮次 < 预算? 否 → 预算耗尽). Do not ask for another fix pass.
    if (effectiveRound >= roundsBudget && !finalState.budgetOverride) {
      const unresolvedReassessments =
        effectiveRound > 1
          ? (parsed.reassessments || []).filter(
              (r) => r.status === "unresolved" || r.status === "partially",
            )
          : [];
      return budgetExhaustedReport({
        packetPath,
        state: finalState,
        roundsBudget,
        openBlocking,
        // Round 1: findings; Re-review: open blockers from ledger + unresolved reassessments
        findings:
          effectiveRound <= 1
            ? parsed.findings
            : openBlocking.map((id) =>
                catalogEntryToConcern(id, findingCatalog[id]),
              ),
        reassessments: unresolvedReassessments,
      });
    }
    return {
      ok: true,
      status: "blocked",
      verdict: parsed.verdict,
      round: effectiveRound,
      packetPath,
      packetId,
      openBlocking,
      openConcerns,
      findings:
        effectiveRound <= 1
          ? parsed.findings
          : openBlocking.map((id) =>
              catalogEntryToConcern(id, findingCatalog[id]),
            ),
      message:
        "BLOCKED — Fixer should address open blocking findings, append # Fix Completion, then: review-loop run --continue",
      warning: evidence.warning,
      evidence: reviewEvidence,
      needsContinue: true,
    };
  }

  if (parsed.verdict === "PASS_WITH_CONCERNS") {
    if (concernsRequireFix) {
      if (effectiveRound >= roundsBudget && !finalState.budgetOverride) {
        return budgetExhaustedReport({
          packetPath,
          state: finalState,
          roundsBudget,
          openConcerns,
          findings: concernRows,
        });
      }
      return {
        ok: true,
        status: "concerns_require_fix",
        verdict: parsed.verdict,
        completion,
        round: effectiveRound,
        packetPath,
        packetId,
        openConcerns,
        concerns: concernRows,
        message:
          "PASS_WITH_CONCERNS under completion=pass — Fixer should address the concerns, append # Fix Completion, then run --continue; no user confirmation needed",
        warning: evidence.warning,
        evidence: reviewEvidence,
        needsContinue: true,
      };
    }
    return {
      ok: true,
      status: "awaiting_user_decision",
      verdict: parsed.verdict,
      round: effectiveRound,
      packetPath,
      packetId,
      openConcerns,
      concerns: concernRows,
      message:
        "PASS_WITH_CONCERNS — non-blocking concerns remain; user decides archive or another round",
      warning: evidence.warning,
      evidence: reviewEvidence,
    };
  }

  // PASS / NO_FINDINGS
  return {
    ok: true,
    status: "archived",
    verdict: parsed.verdict,
    round: effectiveRound,
    packetPath,
    packetId,
    message: `✅ auto loop complete — Verdict ${parsed.verdict} after ${effectiveRound} round(s)`,
    warning: evidence.warning,
    evidence: reviewEvidence,
    report: {
      verdict: parsed.verdict,
      rounds: effectiveRound,
      findingIds,
      lineCount: evidence.lineCount,
    },
  };
}

function deliveryUnknownReport({ packetPath, state, error, code }) {
  return {
    ok: false,
    status: "DELIVERY_UNKNOWN",
    code: code || DELIVERY_UNKNOWN,
    message: `Reviewer invoke failed (no retry): ${error}`,
    packetPath,
    state,
  };
}

/**
 * Parse --rounds: absolute N, or additive +N on continue (T5 budget re-authorization).
 * @param {string|number|null|undefined} raw
 * @param {Record<string, unknown>} prior
 * @param {boolean} isContinue
 */
export function resolveRoundsBudget(raw, prior = {}, isContinue = false) {
  if (raw == null || raw === "") {
    const inherited =
      isContinue && prior.roundsBudget != null
        ? Number(prior.roundsBudget)
        : DEFAULT_ROUNDS;
    return Number.isFinite(inherited) && inherited >= 1
      ? inherited
      : DEFAULT_ROUNDS;
  }
  const text = String(raw).trim();
  if (text.startsWith("+")) {
    const delta = Number(text.slice(1));
    if (!Number.isFinite(delta) || delta < 1) {
      throw new Error("--rounds +N requires a positive finite N");
    }
    const base =
      prior.roundsBudget != null
        ? Number(prior.roundsBudget)
        : prior.round != null
          ? Number(prior.round)
          : DEFAULT_ROUNDS;
    const baseBudget =
      Number.isFinite(base) && base >= 1 ? base : DEFAULT_ROUNDS;
    return baseBudget + delta;
  }
  const n = Number(text);
  if (!Number.isFinite(n) || n < 1) {
    throw new Error("--rounds must be a positive finite number");
  }
  return n;
}

/**
 * Latest # Fix Completion stance from packet (actual stage text, not canned copy).
 * `count` is the number of # Fix Completion stages physically on the packet —
 * the only truthful "fix rounds completed" figure (reviewer rounds may run ahead).
 * @param {string|null|undefined} packetPath
 * @returns {{ present: boolean, count: number, conclusion: string|null, findingStatus: string|null, verification: string|null }}
 */
export function extractLatestFixCompletionStance(packetPath) {
  const empty = {
    present: false,
    count: 0,
    conclusion: null,
    findingStatus: null,
    verification: null,
  };
  if (!packetPath || !fs.existsSync(packetPath)) return empty;
  let body = fs.readFileSync(packetPath, "utf8");
  if (body.startsWith("---")) {
    const end = body.indexOf("\n---", 3);
    if (end !== -1) body = body.slice(end + 4);
  }
  /** @type {string|null} */
  let lastSection = null;
  let count = 0;
  // Split on top-level H1 (fence-unaware is ok: Fix Completion stages are not fenced titles)
  for (const chunk of body.split(/^# /m)) {
    if (/^Fix Completion(?:\s*\(round\s+\d+\))?\s*(?:\n|$)/i.test(chunk)) {
      lastSection = chunk;
      count += 1;
    }
  }
  if (!lastSection) return empty;

  const h2Body = (heading) => {
    const re = new RegExp(
      `##\\s*${heading}\\s*\\n([\\s\\S]*?)(?=\\n##\\s|$)`,
      "i",
    );
    const m = lastSection.match(re);
    return m ? m[1].trim() : null;
  };
  return {
    present: true,
    count,
    conclusion: h2Body("Fix Conclusion"),
    findingStatus: h2Body("Finding Status"),
    verification: h2Body("Verification"),
  };
}

function budgetExhaustedReport({
  packetPath,
  state,
  roundsBudget,
  openBlocking,
  openConcerns,
  findings,
  reassessments,
}) {
  const unresolvedBlocking = openBlocking || state.openBlocking || [];
  const unresolvedConcerns = openConcerns || state.openConcerns || [];
  const unresolved = [...unresolvedBlocking, ...unresolvedConcerns];
  const fixerStance = extractLatestFixCompletionStance(packetPath);
  const unresolvedReassessments = Array.isArray(reassessments)
    ? reassessments
    : [];

  /** @type {Record<string, unknown>} */
  const fixerPosition = fixerStance.present
    ? {
        present: true,
        conclusion: fixerStance.conclusion,
        findingStatus: fixerStance.findingStatus,
        verification: fixerStance.verification,
        // Actual # Fix Completion stages on packet — never the reviewer round counter
        fixRoundsCompleted: fixerStance.count,
      }
    : {
        present: false,
        conclusion: null,
        findingStatus: null,
        verification: null,
        fixRoundsCompleted: 0,
        // First-round budget exhaust (--rounds 1) never had a Fix Completion stage
        note: "No # Fix Completion stage on packet (budget exhausted before a fix pass, or Fix Completion missing)",
      };

  return {
    ok: false,
    status: "budget_exhausted",
    message: `Round budget (${roundsBudget}) exhausted with unresolved review findings`,
    packetPath,
    openBlocking: unresolvedBlocking,
    openConcerns: unresolvedConcerns,
    unresolved,
    lastVerdict: state.lastVerdict || "BLOCKED",
    roundsUsed: state.round,
    roundsBudget,
    // 双方立场:Reviewer 末轮真实证据 + Fixer 最新 Fix Completion 实际结论
    positions: {
      reviewer: {
        lastVerdict: state.lastVerdict || "BLOCKED",
        openBlocking: unresolvedBlocking,
        openConcerns: unresolvedConcerns,
        findingIds: state.findingIds || [],
        // New findings this round (may be empty when only prior blockers remain)
        findings: findings || [],
        // Unresolved/partially reassessments with Reviewer 复核证据 (re-review exhaust)
        reassessments: unresolvedReassessments,
      },
      fixer: fixerPosition,
    },
    recommendation:
      "Authorize more rounds: run --continue --rounds +N (additive) or --rounds N (absolute ceiling)",
  };
}

function terminalReport(x) {
  return { ok: true, ...x };
}

/**
 * Fence-aware top-level H1 sections (title + body after the H1 line).
 * @param {string} text
 * @returns {{ title: string, body: string }[]}
 */
export function splitTopLevelH1Sections(text) {
  const lines = String(text).split("\n");
  /** @type {{ title: string, bodyLines: string[] }[]} */
  const sections = [];
  let fenced = false;
  /** @type {{ title: string, bodyLines: string[] }|null} */
  let current = null;
  for (const line of lines) {
    if (/^\s*(```|~~~)/.test(line)) {
      fenced = !fenced;
      if (current) current.bodyLines.push(line);
      continue;
    }
    if (!fenced) {
      const m = line.match(/^# ([^#].*?)\s*$/);
      if (m) {
        if (current) sections.push(current);
        current = { title: m[1].trim(), bodyLines: [] };
        continue;
      }
    }
    if (current) current.bodyLines.push(line);
  }
  if (current) sections.push(current);
  return sections.map((s) => ({
    title: s.title,
    body: s.bodyLines.join("\n"),
  }));
}

/**
 * Completed review rounds from durable packet H1 chain (not bare frontmatter).
 * Review Findings → 1; first Re-review → 2; Re-review (round N) → N.
 * @param {string} text
 */
export function completedReviewRoundFromPacket(text) {
  let maxRound = 0;
  for (const sec of splitTopLevelH1Sections(text)) {
    if (/^Review Findings$/i.test(sec.title)) {
      maxRound = Math.max(maxRound, 1);
      continue;
    }
    const m = sec.title.match(/^Re-review(?:\s*\(round\s+(\d+)\))?$/i);
    if (m) {
      maxRound = Math.max(maxRound, m[1] ? Number(m[1]) : 2);
    }
  }
  return maxRound;
}

/**
 * @param {string} body
 * @returns {ReturnType<typeof findingFromRow>[]|null}
 */
export function extractFindingsFromSectionBody(body) {
  let slice = body;
  const split = String(body).split(/##\s*Findings/i);
  if (split.length >= 2) {
    slice = split[1].split(/##\s+/)[0] ?? split[1];
  }
  const tables = parseMarkdownTables(slice);
  const table = tables.find((t) =>
    t.headers.some((h) => h === "id" || h === "finding id"),
  );
  if (!table) return null;
  if (missingFindingsTableColumns(table.headers).length) return null;
  if (table.columnMismatch) return null;
  return table.rows
    .map(findingFromRow)
    .filter((f) => f.id && f.id !== "(none)" && !/^[-—]+$/.test(f.id));
}

/**
 * Rebuild finding ledger by replaying Review Findings + Re-review stages from packet.
 * Fail-closed if stages are not parseable (STATE_MIGRATION_REQUIRED).
 * @param {string} packetText
 */
export function rebuildLedgerFromPacketText(packetText) {
  const sections = splitTopLevelH1Sections(packetText);
  /** @type {Record<string, ReturnType<typeof catalogEntryFromFinding>>} */
  let findingCatalog = {};
  /** @type {string[]} */
  let findingIds = [];
  /** @type {string[]} */
  let openBlocking = [];
  /** @type {string[]} */
  let openConcerns = [];
  let round = 0;
  /** @type {string|null} */
  let lastVerdict = null;

  for (const sec of sections) {
    if (/^Review Findings$/i.test(sec.title)) {
      const findings = extractFindingsFromSectionBody(sec.body);
      if (!findings) {
        throw new Error(
          "STATE_MIGRATION_REQUIRED: cannot parse # Review Findings findings table",
        );
      }
      const sectionText = `# Review Findings\n${sec.body}`;
      const verdict = extractVerdict(sectionText);
      if (!verdict) {
        throw new Error(
          "STATE_MIGRATION_REQUIRED: # Review Findings missing Verdict",
        );
      }
      const ledger = computeFindingLedger({
        effectiveRound: 1,
        parsed: { findings, verdict },
        priorCatalog: {},
        priorFindingIds: [],
      });
      assertVerdictOpenSets(verdict, ledger.openBlocking, ledger.openConcerns);
      findingCatalog = ledger.findingCatalog;
      findingIds = ledger.findingIds;
      openBlocking = ledger.openBlocking;
      openConcerns = ledger.openConcerns;
      round = 1;
      lastVerdict = verdict;
      continue;
    }
    const reMatch = sec.title.match(/^Re-review(?:\s*\(round\s+(\d+)\))?$/i);
    if (reMatch) {
      const nextRound = reMatch[1]
        ? Number(reMatch[1])
        : Math.max(round + 1, 2);
      const sectionText = `# ${sec.title}\n${sec.body}`;
      const parsed = parseReReview(sectionText, findingIds, {
        priorBlockingIds: catalogBlockingIds(findingCatalog),
      });
      if (!parsed.ok) {
        throw new Error(
          `STATE_MIGRATION_REQUIRED: cannot parse re-review stage: ${parsed.error}`,
        );
      }
      const ledger = computeFindingLedger({
        effectiveRound: nextRound,
        parsed,
        priorCatalog: findingCatalog,
        priorFindingIds: findingIds,
      });
      assertVerdictOpenSets(
        parsed.verdict,
        ledger.openBlocking,
        ledger.openConcerns,
      );
      findingCatalog = ledger.findingCatalog;
      findingIds = ledger.findingIds;
      openBlocking = ledger.openBlocking;
      openConcerns = ledger.openConcerns;
      round = nextRound;
      lastVerdict = parsed.verdict;
    }
  }

  if (round === 0) {
    throw new Error(
      "STATE_MIGRATION_REQUIRED: no # Review Findings stage to rebuild ledger from",
    );
  }
  return {
    findingCatalog,
    findingIds,
    openBlocking,
    openConcerns,
    round,
    lastVerdict,
  };
}

/**
 * @param {Record<string, unknown>} state
 * @param {ReturnType<typeof readPacketMeta>} meta
 * @param {string} packetText
 */
export function needsLedgerRebuild(state, meta, packetText) {
  const completed = completedReviewRoundFromPacket(packetText);
  if (completed === 0) return false;
  const catalog = /** @type {Record<string, {blocking?: boolean}>} */ (
    state.findingCatalog || {}
  );
  const keys = Object.keys(catalog);
  if (keys.length === 0) return true;
  const stateRound = Number(state.round ?? 0);
  if (stateRound < completed) return true;
  const findingIds = Array.isArray(state.findingIds)
    ? state.findingIds.map(String)
    : [];
  if (findingIds.length !== keys.length) return true;
  for (const id of findingIds) {
    if (!catalog[id]) return true;
  }
  for (const id of state.openBlocking || []) {
    if (!catalog[String(id)]?.blocking) return true;
  }
  for (const id of state.openConcerns || []) {
    const e = catalog[String(id)];
    if (!e || e.blocking) return true;
  }
  if (
    state.lastVerdict &&
    meta.lifecycleState &&
    state.lifecycle &&
    state.lifecycle !== meta.lifecycleState
  ) {
    return true;
  }
  return false;
}

/**
 * Append stage then update runtime ledger.
 * Requires expectedHash (round-start pin) — never re-derives baseline from current file alone.
 * Non-goal: crash-safe dual-write; mid-write kill may leave packet/runtime inconsistent
 * (caller gets PACKET_HASH_MISMATCH or STATE_RECOVERY_REQUIRED on next run).
 */
export function commitStageWithLedger(opts) {
  const {
    repoRoot,
    packetPath,
    packetId,
    sectionMarkdown,
    lastAnchor,
    lifecycleState,
    extra,
    nextLedger,
    priorState,
    expectedHash,
  } = opts;
  if (!expectedHash) {
    throw new Error(
      "commitStageWithLedger requires expectedHash (roundStart pin)",
    );
  }
  const text = fs.readFileSync(packetPath, "utf8");
  const currentHash = contentHash(text);
  if (currentHash !== expectedHash) {
    const err = new Error(
      "PACKET_HASH_MISMATCH: packet diverged from pinned expectedHash before stage write",
    );
    // @ts-expect-error
    err.code = "PACKET_HASH_MISMATCH";
    throw err;
  }

  const writeResult = appendStageAuto({
    repoRoot,
    packetPath,
    packetId,
    sectionMarkdown,
    lastAnchor,
    lifecycleState,
    extra,
    expectedHash,
  });

  const finalized = {
    ...priorState,
    ...nextLedger,
    packetPath: writeResult.packetPath,
    packetHash: writeResult.packetHash,
    lastAnchor: writeResult.meta?.lastAnchor ?? lastAnchor,
    lifecycleState:
      lifecycleState === "archived"
        ? "archived"
        : (writeResult.meta?.lifecycleState ?? lifecycleState),
    pendingStage: null,
    roundStartPacketHash: null,
    updated: new Date().toISOString(),
  };
  saveRunState(repoRoot, packetId, finalized);
  return writeResult;
}

/**
 * Pre-Reviewer reconcile: hash drift fail-closed; rebuild missing ledger from packet stages.
 * Stale pendingStage from old journal builds → STATE_RECOVERY_REQUIRED (no auto-replay).
 * @returns {{ state: Record<string, unknown>, packetPath?: string, error?: object }}
 */
export function reconcileRuntimeState({
  repoRoot,
  packetId,
  packetPath,
  state,
}) {
  let s = { ...(state || {}) };
  let pathNow = packetPath;
  let meta = readPacketMeta(pathNow);
  let text = meta.text;
  let currentHash = contentHash(fs.readFileSync(pathNow, "utf8"));

  // Legacy incomplete journal: refuse silent guess
  if (s.pendingStage && typeof s.pendingStage === "object") {
    return {
      state: s,
      error: {
        ok: false,
        status: "STATE_RECOVERY_REQUIRED",
        message:
          "STATE_RECOVERY_REQUIRED: leftover pendingStage from crash-safe journal (removed in v3.3.1). Clear runtime auto-run-state.json pendingStage after manual inspection, or start a new packet. Auto-replay is intentionally disabled.",
        packetPath: pathNow,
        recovery:
          "Inspect packet under active/ or archive/; if stages look complete, delete pendingStage from auto-run-state.json and re-run with --packet; otherwise create a new review-loop run packet.",
      },
    };
  }

  if (s.packetHash && currentHash !== s.packetHash) {
    return {
      state: s,
      error: {
        ok: false,
        status: "packet_hash_mismatch",
        message:
          "PACKET_HASH_MISMATCH: packet was modified outside auto loop; refuse continue and stop",
        packetPath: pathNow,
        expectedHash: s.packetHash,
        actualHash: currentHash,
      },
    };
  }

  // --- ledger rebuild / migration (explicit, only when catalog incomplete) ---
  if (needsLedgerRebuild(s, meta, text)) {
    try {
      const rebuilt = rebuildLedgerFromPacketText(text);
      const completion =
        s.completion || meta.frontmatter?.completion || "review";
      const lifecycle =
        rebuilt.lastVerdict === "PASS_WITH_CONCERNS" && completion === "pass"
          ? "blocked"
          : lifecycleForVerdict(
              rebuilt.round <= 1 ? "review_findings" : "re_review",
              rebuilt.lastVerdict || "BLOCKED",
            );
      s = {
        ...s,
        findingCatalog: rebuilt.findingCatalog,
        findingIds: rebuilt.findingIds,
        openBlocking: rebuilt.openBlocking,
        openConcerns: rebuilt.openConcerns,
        round: rebuilt.round,
        lastVerdict: rebuilt.lastVerdict,
        completion,
        lifecycle,
        packetHash: currentHash,
        packetPath: pathNow,
        ledgerRebuiltFromPacket: true,
        pendingStage: null,
        updated: new Date().toISOString(),
      };
      saveRunState(repoRoot, packetId, s);
    } catch (err) {
      return {
        state: s,
        error: {
          ok: false,
          status: "STATE_MIGRATION_REQUIRED",
          message: err?.message || String(err),
          packetPath: pathNow,
          recovery:
            "Packet review stages could not rebuild findingCatalog. Create a new packet with review-loop run, or restore a complete auto-run-state.json.",
        },
      };
    }
  }

  return { state: s, packetPath: pathNow };
}

/**
 * Historical blocker IDs from findingCatalog (blocking identity never demotes).
 * @param {Record<string, {blocking?: boolean}>|null|undefined} catalog
 * @returns {string[]}
 */
export function catalogBlockingIds(catalog) {
  return Object.entries(catalog || {})
    .filter(([, e]) => e && e.blocking)
    .map(([id]) => id);
}

/**
 * @param {{ id: string, severity?: string, title?: string, targetFiles?: string, blocking?: boolean, evidence?: string, requiredFix?: string, acceptanceCheck?: string }} f
 */
function catalogEntryFromFinding(f) {
  return {
    severity: f.severity || "",
    title: f.title || "",
    targetFiles: f.targetFiles || "",
    blocking: Boolean(f.blocking),
    evidence: f.evidence || "",
    requiredFix: f.requiredFix || "",
    acceptanceCheck: f.acceptanceCheck || "",
  };
}

/**
 * @param {string} id
 * @param {{ severity?: string, title?: string, targetFiles?: string, blocking?: boolean }|undefined} entry
 */
function catalogEntryToConcern(id, entry) {
  return {
    id,
    severity: entry?.severity || "",
    title: entry?.title || "",
    targetFiles: entry?.targetFiles || "",
    blocking: Boolean(entry?.blocking),
  };
}

/**
 * Build findingCatalog + openBlocking + openConcerns from a parsed round.
 * Recomputes open sets from full catalog + latest reassessment (not only prior open sets).
 *
 * @param {{
 *   effectiveRound: number,
 *   parsed: { findings?: any[], newFindings?: any[], reassessments?: {id:string,status:string}[] },
 *   priorCatalog: Record<string, object>,
 *   priorFindingIds: string[],
 * }} opts
 */
export function computeFindingLedger(opts) {
  const { effectiveRound, parsed, priorCatalog, priorFindingIds } = opts;
  /** @type {Record<string, ReturnType<typeof catalogEntryFromFinding>>} */
  const findingCatalog = { ...(priorCatalog || {}) };

  if (effectiveRound <= 1) {
    const findings = parsed.findings || [];
    const seen = new Set();
    for (const f of findings) {
      if (seen.has(f.id)) {
        throw new Error(`duplicate finding id in round 1: ${f.id}`);
      }
      seen.add(f.id);
      findingCatalog[f.id] = catalogEntryFromFinding(f);
    }
    return {
      findingCatalog,
      openBlocking: findings.filter((f) => f.blocking).map((f) => f.id),
      openConcerns: findings.filter((f) => !f.blocking).map((f) => f.id),
      findingIds: findings.map((f) => f.id),
    };
  }

  for (const f of parsed.newFindings || []) {
    if (findingCatalog[f.id]) {
      throw new Error(`New Findings reuses existing finding id: ${f.id}`);
    }
    findingCatalog[f.id] = catalogEntryFromFinding(f);
  }

  const reassessMap = new Map(
    (parsed.reassessments || []).map((r) => [
      r.id,
      String(r.status).toLowerCase(),
    ]),
  );
  const newIds = new Set((parsed.newFindings || []).map((f) => f.id));
  /** @type {string[]} */
  const openBlocking = [];
  /** @type {string[]} */
  const openConcerns = [];

  for (const [id, entry] of Object.entries(findingCatalog)) {
    if (newIds.has(id)) {
      if (entry.blocking) openBlocking.push(id);
      else openConcerns.push(id);
      continue;
    }
    const status = reassessMap.get(id);
    if (!status) {
      throw new Error(`missing reassessment status for catalog id ${id}`);
    }
    if (status === "resolved") continue;
    if (status === "unresolved" || status === "partially") {
      if (entry.blocking) openBlocking.push(id);
      else openConcerns.push(id);
      continue;
    }
    throw new Error(`invalid reassessment status for ${id}: ${status}`);
  }

  const findingIds = [
    ...priorFindingIds,
    ...(parsed.newFindings || []).map((f) => f.id),
  ].filter((v, i, a) => a.indexOf(v) === i);

  return { findingCatalog, openBlocking, openConcerns, findingIds };
}

/**
 * Fail-closed verdict vs open-set invariants (before packet write).
 * @param {string} verdict
 * @param {string[]} openBlocking
 * @param {string[]} openConcerns
 */
export function assertVerdictOpenSets(verdict, openBlocking, openConcerns) {
  const v = String(verdict).toUpperCase();
  const b = openBlocking || [];
  const c = openConcerns || [];
  if (v === "PASS_WITH_CONCERNS") {
    if (b.length) {
      throw new Error("PASS_WITH_CONCERNS requires openBlocking empty");
    }
    if (!c.length) {
      throw new Error("PASS_WITH_CONCERNS requires at least one openConcern");
    }
  }
  if (v === "PASS" || v === "NO_FINDINGS") {
    if (b.length || c.length) {
      throw new Error(
        `${v} requires openBlocking and openConcerns both empty (got blocking=${b.join(",") || "∅"} concerns=${c.join(",") || "∅"})`,
      );
    }
  }
  if (v === "BLOCKED" && !b.length) {
    throw new Error("BLOCKED requires at least one openBlocking id");
  }
}

/**
 * Resolve accepted concerns for close from structured runtime state only.
 * Round-1 PWC without ledger may one-time backfill from openConcerns empty + catalog empty
 * is not allowed for re-review packets.
 *
 * @param {{
 *   state: Record<string, unknown>|null,
 *   lastAnchor: string|null,
 * }} opts
 * @returns {{ id: string, severity: string, title: string, targetFiles?: string, blocking?: boolean }[]}
 */
export function resolveConcernsForClose(opts) {
  const state = opts.state || {};
  const lastAnchor = opts.lastAnchor || "";
  const catalog = /** @type {Record<string, any>} */ (
    state.findingCatalog || null
  );
  const openConcerns = Array.isArray(state.openConcerns)
    ? state.openConcerns.map(String)
    : null;
  const openBlocking = Array.isArray(state.openBlocking)
    ? state.openBlocking.map(String)
    : [];

  if (openBlocking.length) {
    throw new Error(
      `close refuses openBlocking still set (${openBlocking.join(", ")}); only PASS_WITH_CONCERNS with no blockers may close`,
    );
  }

  if (
    catalog &&
    typeof catalog === "object" &&
    openConcerns &&
    openConcerns.length
  ) {
    /** @type {ReturnType<typeof catalogEntryToConcern>[]} */
    const rows = [];
    for (const id of openConcerns) {
      if (!catalog[id]) {
        throw new Error(
          `close openConcerns id ${id} missing from findingCatalog`,
        );
      }
      if (catalog[id].blocking) {
        throw new Error(
          `close openConcerns id ${id} is blocking in catalog (expected non-blocking concern)`,
        );
      }
      rows.push(catalogEntryToConcern(id, catalog[id]));
    }
    return rows;
  }

  // One-time first-round backfill only: review_findings + missing structured state
  // (legacy packets written before findingCatalog). Re-review must fail closed.
  if (lastAnchor === "review_findings" || lastAnchor === "fix_handoff") {
    throw new Error(
      "close missing findingCatalog/openConcerns in auto-run-state.json for first-round PWC; re-run review-loop run so ledger is written, then close again",
    );
  }

  throw new Error(
    "close fail-closed: re-review/terminal PWC requires findingCatalog + non-empty openConcerns in runtime auto-run-state.json (no Markdown reparse). Recovery: re-run the loop from a clean packet, or restore runtime state.",
  );
}

/**
 * User Decision Closure: accept PASS_WITH_CONCERNS and archive without re-review.
 * Does not rewrite original Verdict to PASS.
 *
 * @param {{
 *   repoRoot?: string,
 *   cwd?: string,
 *   packetPath: string,
 *   reason?: string,
 * }} opts
 */
export async function cmdClose(opts) {
  const repoRoot = opts.repoRoot || resolveRepoRoot(opts.cwd || process.cwd());
  const branch = resolveBranch(repoRoot);
  const reason = String(opts.reason || "").trim();
  if (reason !== "accept-concerns") {
    throw new Error(
      "close --reason must be accept-concerns (only supported reason this version)",
    );
  }
  if (!opts.packetPath) throw new Error("--packet required");
  const abs = path.isAbsolute(opts.packetPath)
    ? opts.packetPath
    : path.resolve(repoRoot, opts.packetPath);
  const { packetPath, packetId, meta } = validatePacketPath(
    repoRoot,
    branch,
    abs,
    {
      activeOnly: true,
    },
  );
  if (meta.lifecycleState === "archived") {
    throw new Error("close refuses lifecycle_state=archived (already closed)");
  }
  if (meta.lifecycleState !== "awaiting_user_decision") {
    throw new Error(
      `close refuses lifecycle_state=${meta.lifecycleState} (need awaiting_user_decision after PASS_WITH_CONCERNS)`,
    );
  }
  const last = lastPhysicalH1(meta.text);
  const okPrior =
    last &&
    (last.anchor === "review_findings" ||
      last.anchor === "re_review" ||
      /^re_review/.test(last.anchor));
  if (!okPrior) {
    throw new Error(
      `close refuses last_anchor=${meta.lastAnchor ?? last?.anchor ?? "none"} (need review_findings or re_review after PASS_WITH_CONCERNS)`,
    );
  }

  return withPacketLock(repoRoot, packetId, async () => {
    let pathLocked = packetPath;
    let state = loadRunState(repoRoot, packetId) ?? {};
    const recon = reconcileRuntimeState({
      repoRoot,
      packetId,
      packetPath: pathLocked,
      state,
    });
    if (recon.error) {
      throw new Error(
        recon.error.message ||
          `close reconciliation failed: ${recon.error.status}`,
      );
    }
    state = recon.state;
    if (recon.packetPath) pathLocked = recon.packetPath;

    const metaLocked = readPacketMeta(pathLocked);
    if (metaLocked.lifecycleState !== "awaiting_user_decision") {
      throw new Error(
        `close under lock refuses lifecycle_state=${metaLocked.lifecycleState} (need awaiting_user_decision)`,
      );
    }
    const lastLocked = lastPhysicalH1(metaLocked.text);
    const ok =
      lastLocked &&
      (lastLocked.anchor === "review_findings" ||
        lastLocked.anchor === "re_review" ||
        /^re_review/.test(lastLocked.anchor));
    if (!ok) {
      throw new Error(
        `close under lock refuses last_anchor=${metaLocked.lastAnchor ?? lastLocked?.anchor ?? "none"}`,
      );
    }

    const concerns = resolveConcernsForClose({
      state,
      lastAnchor: metaLocked.lastAnchor ?? lastLocked?.anchor ?? null,
    });

    const closedAt = new Date().toISOString();
    const section = formatDecisionClosureStage({
      reason,
      originalVerdict: "PASS_WITH_CONCERNS",
      concerns,
      closedAt,
    });

    const expectedHash =
      state.packetHash || contentHash(fs.readFileSync(pathLocked, "utf8"));
    const written = commitStageWithLedger({
      repoRoot,
      packetPath: pathLocked,
      packetId,
      sectionMarkdown: section,
      lastAnchor: "decision_closure",
      lifecycleState: "archived",
      extra: {
        close_reason: reason,
        closed_at: closedAt,
      },
      nextLedger: {
        ...state,
        openConcerns: [],
        openBlocking: [],
        lifecycle: "archived",
        lastVerdict: "PASS_WITH_CONCERNS",
        closeReason: reason,
        closedAt,
      },
      priorState: state,
      expectedHash,
    });
    const reportMeta = readPacketMeta(written.packetPath);
    return {
      ok: true,
      status: "archived",
      reason,
      packetPath: written.packetPath,
      packetId,
      lastAnchor: "decision_closure",
      lifecycleState: "archived",
      originalVerdict: "PASS_WITH_CONCERNS",
      acceptedConcernIds: concerns.map((c) => c.id),
      evidence: state.evidence ?? null,
      message:
        "PASS_WITH_CONCERNS accepted as backlog — packet archived via Decision Closure (original Verdict not rewritten to PASS)",
      report: {
        originalVerdict: "PASS_WITH_CONCERNS",
        closeReason: reason,
        acceptedConcernIds: concerns.map((c) => c.id),
        closedAt,
        lastAnchor: reportMeta.lastAnchor,
        lifecycleState: reportMeta.lifecycleState,
        evidence: state.evidence ?? null,
      },
    };
  });
}

/**
 * Fixer helper: append Fix Completion after addressing blockers or strict concerns.
 */
export async function cmdAppendFixCompletion(opts) {
  const repoRoot = opts.repoRoot || resolveRepoRoot(opts.cwd || process.cwd());
  const branch = resolveBranch(repoRoot);
  if (!opts.packetPath) throw new Error("--packet required");
  const abs = path.isAbsolute(opts.packetPath)
    ? opts.packetPath
    : path.resolve(repoRoot, opts.packetPath);
  // F4: writes only accept active packets
  const { packetPath, packetId, meta } = validatePacketPath(
    repoRoot,
    branch,
    abs,
    {
      activeOnly: true,
    },
  );
  if (meta.lifecycleState === "archived") {
    throw new Error("fix-completion refuses lifecycle_state=archived");
  }
  // F3: legal stage gate — must follow Fix Handoff or a re-review that needs fixes
  const last = lastPhysicalH1(meta.text);
  const okPrior =
    last &&
    (last.anchor === "fix_handoff" ||
      last.anchor === "re_review" ||
      /^re_review/.test(last.anchor) ||
      last.anchor === "fix_completion");
  if (!okPrior) {
    throw new Error(
      `fix-completion refuses last_anchor=${meta.lastAnchor ?? last?.anchor ?? "none"} (need fix_handoff or re_review with unresolved work)`,
    );
  }
  const body =
    opts.body ||
    (opts.bodyFile ? fs.readFileSync(opts.bodyFile, "utf8") : null);
  if (!body) throw new Error("--body-file or body required");
  let section = String(body).trim();
  // Must be a top-level H1 (# Title), not ## subsection
  if (!/^# [^#\n]/.test(section)) {
    section = `# Fix Completion\n\n${section}\n`;
  }
  // Canonical title required (A2) — reject forged non-fix-completion H1s
  const firstH1 = section.split("\n").find((l) => /^# [^#]/.test(l)) ?? "";
  if (!/^#\s*Fix Completion(\s*\(round\s+\d+\))?\s*$/i.test(firstH1.trim())) {
    throw new Error(
      'fix-completion body must start with "# Fix Completion" H1',
    );
  }
  // F2/F3: require full Fix Completion H2 set — no placeholder auto-fabricate
  const requiredH2 = [
    "Fix Conclusion",
    "Original Findings Snapshot",
    "Finding Status",
    "Verification",
    "Re-review Instructions",
  ];
  const missing = requiredH2.filter(
    (h) => !new RegExp(`##\\s*${h}`, "i").test(section),
  );
  if (missing.length) {
    throw new Error(
      `fix-completion missing required H2 sections: ${missing.join(", ")}`,
    );
  }
  // F3: hold same packet lock as run; re-check last anchor + packet hash under lock
  return withPacketLock(repoRoot, packetId, async () => {
    let state = loadRunState(repoRoot, packetId) ?? {};
    if (state.pendingStage && typeof state.pendingStage === "object") {
      throw new Error(
        "STATE_RECOVERY_REQUIRED: leftover pendingStage; clear after inspection or start a new packet (auto journal removed in v3.3.1)",
      );
    }
    const currentHash = contentHash(fs.readFileSync(packetPath, "utf8"));
    const expectedHash = state.packetHash || currentHash;
    if (state.packetHash && currentHash !== state.packetHash) {
      const err = new Error(
        "PACKET_HASH_MISMATCH: packet was modified outside auto loop before fix-completion",
      );
      // @ts-expect-error
      err.code = "PACKET_HASH_MISMATCH";
      throw err;
    }

    const metaLocked = readPacketMeta(packetPath);
    const lastLocked = lastPhysicalH1(metaLocked.text);
    const ok =
      lastLocked &&
      (lastLocked.anchor === "fix_handoff" ||
        lastLocked.anchor === "re_review" ||
        /^re_review/.test(lastLocked.anchor));
    if (!ok) {
      throw new Error(
        `fix-completion under lock refuses last_anchor=${metaLocked.lastAnchor} (need fix_handoff or re_review)`,
      );
    }

    // Same commit path as review stages: pin expectedHash, append, update runtime
    // (does not mutate finding catalog / open sets — only lastAnchor + hash)
    return commitStageWithLedger({
      repoRoot,
      packetPath,
      packetId,
      sectionMarkdown: section,
      lastAnchor: "fix_completion",
      lifecycleState: "in_progress",
      nextLedger: {
        ...state,
        lastVerdict: state.lastVerdict || "BLOCKED",
        lifecycle: "in_progress",
      },
      priorState: state,
      expectedHash,
    });
  });
}
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall