chainlesschain 0.162.162 → 0.162.164

package/src/lib/remote-approval-bridge.js

@@ -24,8 +24,8 @@
 import { randomBytes } from "crypto";
 import { WsRpcClient } from "./ws-rpc-client.js";
 import {
-  approvalFingerprintOk,
-  operationFingerprint,
+  fingerprintsMatch,
+  OperationApprovalRegistry,
 } from "./operation-fingerprint.js";
 import {
   buildDirectPairingUri,
@@ -60,9 +60,15 @@ export class RemoteApprovalBridge {
     this.client = null;
     this.remoteSessionId = null;
     this.pairing = null;
-    this._pending = new Map(); // requestId → { resolve, timer }
+    this._pending = new Map(); // requestId → { resolve, timer, fingerprint }
     this._counter = 0;
     this._closed = false;
+    // §8.2 cross-device approval registry: full-tuple operation fingerprints,
+    // single-winner across concurrent cards for one logical operation, at-most-
+    // once resolution, and validity-window enforcement — all fail-closed.
+    this._registry = new OperationApprovalRegistry({
+      clock: () => this._now(),
+    });
   }
 
   /** Connect, register the client-hosted remote session, start listening. */
@@ -117,15 +123,24 @@ export class RemoteApprovalBridge {
     const requestId = message.event.requestId || message.event.approvalId;
     const pending = requestId ? this._pending.get(requestId) : null;
     if (!pending) return;
-    // Confused-deputy guard: a resolve that carries an operation fingerprint
-    // must match the operation this ask published. A mismatch (stale card /
-    // replayed / swapped body) is rejected — the ask stays pending and fails
-    // closed on timeout. Absent fingerprint = legacy device, accepted.
+    // Confused-deputy guard: a resolve that echoes a fingerprint must match the
+    // operation this ask published. A mismatch (stale card / replayed / swapped
+    // body / different session·workspace·env·policy) is rejected — the ask stays
+    // pending and fails closed on timeout. An absent fingerprint is a legacy
+    // device: resolved via this ask's own fingerprint (still window-guarded).
     if (
-      !approvalFingerprintOk(pending.fingerprint, message.event.fingerprint)
+      message.event.fingerprint != null &&
+      !fingerprintsMatch(pending.fingerprint, message.event.fingerprint)
     ) {
       return;
     }
+    // Fail-closed §8.2 enforcement: single-winner (superseded card), at-most-once
+    // (duplicate), and validity window (not-yet-valid / expired). A rejected
+    // verdict leaves the ask pending so it still fails closed on timeout.
+    const verdict = this._registry.resolve(pending.fingerprint, {
+      now: this._now(),
+    });
+    if (!verdict.ok) return;
     this._pending.delete(requestId);
     clearTimeout(pending.timer);
     const answer = message.event.answer ?? message.event.approved;
@@ -159,11 +174,35 @@ export class RemoteApprovalBridge {
     tool,
     action = null,
     detail = null,
+    workspace = null,
+    session = null,
+    targetEnv = null,
+    policyVersion = null,
     timeoutMs,
     onRequestId = null,
   } = {}) {
     const requestId = `ra-${process.pid}-${++this._counter}-${randomBytes(4).toString("hex")}`;
-    const fingerprint = operationFingerprint({ tool, action, detail });
+    const askedAt = this._now();
+    const effectiveTimeout = timeoutMs || this.decisionTimeoutMs;
+    // §8.2 full-tuple descriptor: the fingerprint binds tool + params + target
+    // env + workspace + session + policy version + validity window, so an
+    // approval never carries over to a different operation OR a changed context.
+    // The validity window rides the ask lifetime — a resolve after it expires is
+    // rejected `expired`.
+    const desc = {
+      toolName: tool,
+      params: detail,
+      workspace,
+      session: session || this.agentSessionId,
+      targetEnv,
+      policyVersion,
+      notBefore: askedAt,
+      notAfter:
+        Number.isFinite(askedAt) && Number.isFinite(effectiveTimeout)
+          ? askedAt + effectiveTimeout
+          : null,
+    };
+    const card = this._registry.issue(desc);
     if (onRequestId) {
       try {
         onRequestId(requestId);
@@ -181,11 +220,11 @@ export class RemoteApprovalBridge {
           via: "timeout",
         });
         resolve({ approved: false, via: "timeout", from: null });
-      }, timeoutMs || this.decisionTimeoutMs);
+      }, effectiveTimeout);
       if (typeof timer.unref === "function") timer.unref();
       this._pending.set(requestId, {
         timer,
-        fingerprint,
+        fingerprint: card.fingerprint,
         resolve: (decision) => {
           this._publish({
             type: "permission.resolved",
@@ -202,8 +241,14 @@ export class RemoteApprovalBridge {
         tool: tool || null,
         action,
         detail,
-        fingerprint,
-        askedAt: this._now(),
+        // Full fingerprint (protocol) + short id / secret-free summary (what the
+        // operator eyeballs on the device to confirm it is the SAME card).
+        fingerprint: card.fingerprint,
+        shortId: card.shortId,
+        summary: card.summary,
+        notBefore: desc.notBefore,
+        notAfter: desc.notAfter,
+        askedAt,
       });
     });
   }
@@ -214,6 +259,9 @@ export class RemoteApprovalBridge {
     if (!pending) return false;
     this._pending.delete(requestId);
     clearTimeout(pending.timer);
+    // Consume the registry card so a late remote resolve for the SAME operation
+    // is a `duplicate`, never a second settle.
+    this._registry.resolve(pending.fingerprint, { now: this._now() });
     pending.resolve({ approved, via: "local", from: null });
     return true;
   }
@@ -248,6 +296,11 @@ export class RemoteApprovalBridge {
             : ctx?.args
               ? JSON.stringify(ctx.args).slice(0, 2000)
               : null,
+        // §8.2 context that binds the fingerprint (session defaults to this
+        // bridge's agent session inside requestDecision).
+        workspace: ctx?.cwd || ctx?.workspace || null,
+        targetEnv: ctx?.targetEnv || null,
+        policyVersion: ctx?.policyVersion || null,
       };
       if (onAsk) {
         try {

package/src/lib/repl-goal.js

@@ -0,0 +1,132 @@
+/**
+ * REPL `/goal <condition>` — a SESSION completion condition for interactive use.
+ *
+ * Three distinct "goal" concepts, kept separate on purpose:
+ *   - `cc goal`               → long-term, cross-session OKR (goal-store.js).
+ *   - headless --goal-condition → AUTO re-drives outer turns until met/exhausted.
+ *   - REPL `/goal <cond>`      → THIS: a human is present each turn, so it
+ *     EVALUATES + REPORTS after every turn whether the condition is met. It does
+ *     NOT auto-submit follow-ups (that autonomous loop belongs to headless, where
+ *     no human is watching) — the user decides whether to keep going.
+ *
+ * This is the pure, clock/dep-injected core over the already-tested
+ * goal-condition-engine.js; the agent-repl wiring is thin display + eval glue.
+ */
+
+import {
+  isDeterministicCondition,
+  runDeterministicCheck,
+  GoalConditionEngine,
+  GOAL_DECISION,
+} from "./goal-condition-engine.js";
+
+// Interactive sessions are human-paced, so the turn-count budget is generous —
+// it exists only as a backstop (the engine hard-caps at 100 regardless). The
+// meaningful signal in the REPL is met / not-yet-met, not budget exhaustion.
+export const REPL_GOAL_MAX_OUTER_TURNS = 100;
+
+/** Parse the `/goal` argument into an intent. Empty → status; a keyword → clear. */
+export function parseGoalCommand(arg) {
+  const s = String(arg ?? "").trim();
+  if (!s) return { action: "status" };
+  if (s === "clear" || s === "off" || s === "stop" || s === "drop")
+    return { action: "clear" };
+  return { action: "set", spec: s };
+}
+
+/**
+ * Create the REPL's session goal engine for a spec. Throws (via
+ * parseGoalCondition) on a malformed spec so the caller can report it.
+ */
+export function createReplGoal(spec, { now = () => 0 } = {}) {
+  return new GoalConditionEngine({
+    condition: spec,
+    budget: { maxOuterTurns: REPL_GOAL_MAX_OUTER_TURNS },
+    now,
+  });
+}
+
+/** Display lines shown when a goal is set. */
+export function renderGoalStart(engine) {
+  return [
+    `◎ goal set: ${engine.condition.source}`,
+    `  evaluated after each turn (≤ ${engine.budget.maxOuterTurns} turns); /goal clear to drop, /goal to check`,
+  ];
+}
+
+/** Display lines for `/goal` with no argument (status). */
+export function renderGoalStatus(engine) {
+  if (!engine)
+    return [
+      "No session goal. Set one with /goal <condition>",
+      "  e.g. /goal exit-zero:npm test · /goal file-exists:dist/app.js · /goal contains:ALL GREEN · /goal the tests pass",
+    ];
+  const s = engine.state;
+  return [
+    `◎ goal: ${engine.condition.source}`,
+    `  progress: outer turn ${s.outerTurns}/${engine.budget.maxOuterTurns}` +
+      (isDeterministicCondition(engine.condition)
+        ? ` (${engine.condition.kind} check)`
+        : " (model-judged)"),
+  ];
+}
+
+/** Verdict display lines for one evaluation's decision + events. */
+export function renderGoalVerdict(decision, events) {
+  const evaluated = (events || []).find((e) => e.type === "goal_evaluated");
+  if (decision === GOAL_DECISION.COMPLETE) {
+    const done = (events || []).find((e) => e.type === "goal_completed");
+    return [
+      `✔ goal met: ${done?.reason ?? evaluated?.reason ?? "condition met"}`,
+    ];
+  }
+  if (decision === GOAL_DECISION.EXHAUSTED) {
+    const ex = (events || []).find((e) => e.type === "goal_exhausted");
+    return [
+      `⛔ goal dropped — ${ex?.reason ?? "budget exhausted"}${ex?.limit ? ` (${ex.limit})` : ""}`,
+    ];
+  }
+  return [
+    `◎ goal not yet met: ${evaluated?.reason ?? "unmet"} · outer turn ${evaluated?.outerTurns ?? "?"}`,
+  ];
+}
+
+/**
+ * Evaluate the session goal against a completed turn's final text. Deterministic
+ * conditions run inline (contains/regex on the text; exit-zero/file-exists via
+ * injected `spawnSync`/`existsSync`); a model condition delegates to `judge`.
+ *
+ * @param {GoalConditionEngine} engine
+ * @param {string} finalText  the assistant's answer this turn
+ * @param {object} deps { cwd, spawnSync, existsSync, judge, tokens, costUsd }
+ *   judge(condition, {finalText}) => {met, reason, evidence}
+ * @returns {Promise<{decision, events, done, met}>}
+ */
+export async function evaluateReplGoalTurn(engine, finalText, deps = {}) {
+  engine.recordTurnUsage({ tokens: deps.tokens, costUsd: deps.costUsd });
+  const cond = engine.condition;
+  let evaluation;
+  if (isDeterministicCondition(cond)) {
+    evaluation = runDeterministicCheck(cond, {
+      lastOutput: finalText,
+      cwd: deps.cwd,
+      spawnSync: deps.spawnSync,
+      existsSync: deps.existsSync,
+    });
+  } else if (typeof deps.judge === "function") {
+    evaluation = await deps.judge(cond, { finalText });
+  } else {
+    evaluation = {
+      met: false,
+      reason: "no model judge available for this condition",
+      evidence: { kind: "model" },
+    };
+  }
+  const { decision, events } = engine.evaluate(evaluation);
+  return {
+    decision,
+    events,
+    done: engine.done,
+    met: decision === GOAL_DECISION.COMPLETE,
+  };
+}

package/src/lib/repl-rewind.js

@@ -25,6 +25,18 @@
  * turn be matched to its pre-mutation snapshot purely from the count.
  */
 
+import {
+  buildTurnBindingFromMarks,
+  resolveRestorePlan,
+  RESTORE_SCOPE,
+  TURN_COVERAGE,
+} from "./turn-binding.js";
+import { planSessionBranch } from "./session-branch.js";
+
+// Re-exported so the REPL handler can reference the scope constants from the
+// same module it imports the rewind helpers from.
+export { RESTORE_SCOPE };
+
 export const DEFAULT_LIST_LIMIT = 10;
 export const PREVIEW_CHARS = 60;
 
@@ -219,6 +231,147 @@ export function restoreClearedConversation(messages, marks, cleared) {
   };
 }
 
+/**
+ * Coverage-aware restore plan for a rewound turn, derived from the REPL's
+ * EXISTING implicit state (`listUserTurns()` output + `{atMessageCount,id,tool}`
+ * marks) — no new agent-loop events required. Bridges those into the explicit
+ * turn-binding table and asks `resolveRestorePlan` for the honest plan, so
+ * `/rewind` can warn when a restore can't be fully promised (side-effects, a
+ * missing checkpoint, or a conversation/files drift) instead of silently doing a
+ * lossy rewind.
+ *
+ * @param {Array} messages  live conversation (for listUserTurns)
+ * @param {Array<{atMessageCount:number,id:string,tool?:string}>} marks
+ * @param {number} turnIndex  message index returned by rewindToTurn()
+ * @param {string} [scope]  one of RESTORE_SCOPE (default BOTH)
+ * @returns {{scope, coverage, conversation, files, warnings:string[]}}
+ */
+export function buildRewindPlan(
+  messages,
+  marks,
+  turnIndex,
+  scope = RESTORE_SCOPE.BOTH,
+) {
+  const turns = listUserTurns(messages, { limit: 1000 });
+  const log = buildTurnBindingFromMarks(turns, marks);
+  const turn = log.get(`turn-${Number(turnIndex)}`);
+  return resolveRestorePlan(turn, scope);
+}
+
+/**
+ * Human-readable lines for a rewind plan's coverage + warnings, for `/rewind` to
+ * print before it truncates. Returns [] for a fully-restorable turn with no
+ * warnings (nothing worth interrupting the user for).
+ *
+ * @param {{coverage:string, warnings:string[]}} plan  from buildRewindPlan()
+ * @returns {string[]}
+ */
+export function renderRewindWarnings(plan) {
+  if (!plan) return [];
+  const lines = [];
+  if (plan.coverage && plan.coverage !== TURN_COVERAGE.FULL) {
+    lines.push(`  coverage: ${plan.coverage} (restore is not guaranteed)`);
+  }
+  for (const w of plan.warnings || []) lines.push(`  ⚠ ${w}`);
+  return lines;
+}
+
+/**
+ * Coverage-aware BRANCH plan for a chosen turn ("从这里分支" — P0-3's fourth
+ * restore action). Bridges the REPL's implicit state (`listUserTurns()` output +
+ * checkpoint marks) into the explicit turn-binding table exactly like
+ * buildRewindPlan(), then asks the pure [[session-branch.js]] planner for a
+ * deterministic branch plan (new session id, worktree-for-writes decision,
+ * honest coverage warnings). Unlike a rewind, a branch never truncates the live
+ * conversation — the origin session is preserved.
+ *
+ * @param {Array} messages  live conversation (for listUserTurns)
+ * @param {Array<{atMessageCount:number,id:string,tool?:string}>} marks
+ * @param {number} turnIndex  message index of the branch-point user turn
+ * @param {{parentSessionId?:string, seq?:number, writeIntent?:boolean}} [opts]
+ * @returns {object} the plan from planSessionBranch()
+ */
+export function buildBranchPlan(
+  messages,
+  marks,
+  turnIndex,
+  { parentSessionId = null, seq = 0, writeIntent = false } = {},
+) {
+  const turns = listUserTurns(messages, { limit: 1000 });
+  const log = buildTurnBindingFromMarks(turns, marks);
+  const turn = log.get(`turn-${Number(turnIndex)}`);
+  return planSessionBranch({ parentSessionId, turn, seq, writeIntent });
+}
+
+/**
+ * Human-readable coverage + warning lines for a branch plan, printed before the
+ * branch is written. Returns [] for a full-coverage branch with no warnings.
+ *
+ * @param {{coverage:string, warnings:string[]}} plan  from buildBranchPlan()
+ * @returns {string[]}
+ */
+export function renderBranchPlan(plan) {
+  if (!plan) return [];
+  const lines = [];
+  if (plan.coverage && plan.coverage !== TURN_COVERAGE.FULL) {
+    lines.push(
+      `  coverage: ${plan.coverage} (the branch inherits the working tree as-is)`,
+    );
+  }
+  for (const w of plan.warnings || []) lines.push(`  ⚠ ${w}`);
+  return lines;
+}
+
+/**
+ * Parse a `/rewind` argument line into a command + optional restore scope.
+ * Claude-Code parity: a rewind can restore the conversation only, the files
+ * only, or both. The turn number and an optional `--conversation` / `--files` /
+ * `--both` flag may appear in any order. `--branch` (optionally `--write`) turns
+ * the pick into a branch-from-here (P0-3) instead of a rewind.
+ *
+ *   /rewind                       → { command: "list", scope: BOTH }
+ *   /rewind clear                 → { command: "clear", scope: BOTH }
+ *   /rewind 3                     → { command: "turn", n: 3, scope: BOTH }
+ *   /rewind 3 --conversation      → { command: "turn", n: 3, scope: CONVERSATION }
+ *   /rewind --files 3             → { command: "turn", n: 3, scope: FILES }
+ *   /rewind 3 --branch            → { command: "branch", n: 3, writeIntent: false }
+ *   /rewind 3 --branch --write    → { command: "branch", n: 3, writeIntent: true }
+ *
+ * An unknown flag is ignored (kept forgiving); a non-numeric, flag-less arg with
+ * no turn number falls back to `list` so a typo can't silently rewind — and a
+ * `--branch` with no turn number lists too rather than branch off nothing.
+ *
+ * @param {string} arg  the text after `/rewind`
+ * @returns {{command:"list"|"clear"|"turn"|"branch", n?:number, scope:string, writeIntent?:boolean}}
+ */
+export function parseRewindArg(arg) {
+  const raw = String(arg == null ? "" : arg).trim();
+  if (raw === "clear" || raw === "undo-clear") {
+    return { command: "clear", scope: RESTORE_SCOPE.BOTH };
+  }
+  const tokens = raw.split(/\s+/).filter(Boolean);
+  let n = null;
+  let scope = RESTORE_SCOPE.BOTH;
+  let branch = false;
+  let writeIntent = false;
+  for (const t of tokens) {
+    if (t === "--files" || t === "--files-only") scope = RESTORE_SCOPE.FILES;
+    else if (
+      t === "--conversation" ||
+      t === "--conv" ||
+      t === "--conversation-only"
+    )
+      scope = RESTORE_SCOPE.CONVERSATION;
+    else if (t === "--both") scope = RESTORE_SCOPE.BOTH;
+    else if (t === "--branch" || t === "--fork") branch = true;
+    else if (t === "--write" || t === "--write-intent") writeIntent = true;
+    else if (n === null && /^\d+$/.test(t)) n = Number(t);
+  }
+  if (branch && n !== null) return { command: "branch", n, scope, writeIntent };
+  if (n === null) return { command: "list", scope };
+  return { command: "turn", n, scope };
+}
+
 /** Render the picker list (shared by /rewind and double-Esc). */
 export function renderTurnList(turns) {
   if (!turns.length) return "  (no user turns yet)";

package/src/lib/review-comment-anchor.js

@@ -0,0 +1,241 @@
+/**
+ * Review-comment anchoring + staleness — the "行评论 / comment-to-fix" half of
+ * P1-1 (原生复杂 Diff 与评论驱动修复) of
+ * CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md:
+ *
+ *   "行评论传递 file + base hash + line/hunk anchor + comment。
+ *    Agent 修复后评论标记为 resolved/outdated，不错误复用旧行号。"
+ *
+ * [[review-pipeline.js]] aggregates FINDINGS (dedup / verdicts / rank), but a
+ * finding's `line` is a raw number against one snapshot. Once the agent edits
+ * the file, that number is a lie: line 42 now points at unrelated code. Claude
+ * Code's diff review keeps a comment anchored to the CODE it addressed, not to a
+ * coordinate, and after a re-diff it relocates the comment or marks it stale —
+ * it never silently reuses the old line number against new content.
+ *
+ * This is the PURE anchoring core. An anchor captures the file, a content hash,
+ * the 1-based line and the anchored line's text plus a small context window. On
+ * a new file version it recomputes the comment's fate:
+ *
+ *   current   — file unchanged (hash match): line preserved.
+ *   moved     — the anchored line relocated UNIQUELY: line updated.
+ *   outdated  — the anchored line is gone (edited/deleted): line = null. The fix
+ *               most likely addressed it; the old number must NOT be reused.
+ *   ambiguous — several equally-plausible locations: line = null, needs a human.
+ *
+ * The hard invariant: whenever we cannot uniquely place the comment in the new
+ * content, `line` is null. No stale coordinate ever survives a re-anchor.
+ *
+ * PURE: no fs / clock / RNG. Content hashing uses node:crypto (deterministic).
+ */
+
+import { createHash } from "node:crypto";
+
+/** Terminal + transient states a comment can be in after re-anchoring. */
+export const ANCHOR_STATUS = Object.freeze({
+  CURRENT: "current", // file unchanged — line preserved
+  MOVED: "moved", // relocated uniquely — line updated
+  OUTDATED: "outdated", // anchored code gone — line null, do not reuse
+  AMBIGUOUS: "ambiguous", // multiple candidates — line null, needs human
+  RESOLVED: "resolved", // caller-set: the comment's issue was fixed
+});
+
+/** Deterministic content hash used as the anchor's base-version fingerprint. */
+export function hashContent(content) {
+  return createHash("sha256")
+    .update(String(content ?? ""))
+    .digest("hex");
+}
+
+function splitLines(content) {
+  return String(content ?? "").split("\n");
+}
+
+/** Normalize a line for matching — trailing CR + surrounding whitespace only,
+ *  preserving interior text so distinct statements stay distinct. */
+function norm(line) {
+  return String(line ?? "")
+    .replace(/\r$/, "")
+    .trim();
+}
+
+/**
+ * Build a review-comment anchor from the file content it was written against.
+ *
+ * @param {object} params
+ * @param {string} params.file          repo-relative path
+ * @param {string} params.content       the base file content the comment addresses
+ * @param {number} params.line          1-based line the comment anchors to
+ * @param {string} params.comment       the review text
+ * @param {string} [params.id]          stable comment id (caller-owned)
+ * @param {number} [params.contextRadius=2]  context lines captured each side
+ * @returns {object} an anchor record (serializable)
+ */
+export function makeCommentAnchor({
+  file,
+  content,
+  line,
+  comment,
+  id = null,
+  contextRadius = 2,
+} = {}) {
+  const lines = splitLines(content);
+  const idx = Number(line) - 1; // to 0-based
+  const inRange = Number.isInteger(idx) && idx >= 0 && idx < lines.length;
+  const radius = Math.max(0, Math.floor(Number(contextRadius) || 0));
+  return {
+    id: id == null ? null : String(id),
+    file: String(file ?? ""),
+    baseHash: hashContent(content),
+    line: inRange ? idx + 1 : null,
+    comment: String(comment ?? ""),
+    anchorLine: inRange ? String(lines[idx]) : "",
+    contextBefore: inRange ? lines.slice(Math.max(0, idx - radius), idx) : [],
+    contextAfter: inRange ? lines.slice(idx + 1, idx + 1 + radius) : [],
+    status: ANCHOR_STATUS.CURRENT,
+  };
+}
+
+/**
+ * Score how well a candidate index's neighbourhood matches the anchor context.
+ * Context is only a TIE-BREAKER among equal text matches, so a 0-radius anchor
+ * (bare line match) still relocates when the match is unique.
+ */
+function contextScore(anchor, lines, i) {
+  let score = 0;
+  const before = anchor.contextBefore || [];
+  for (let k = 0; k < before.length; k++) {
+    const li = i - before.length + k;
+    if (li >= 0 && norm(lines[li]) === norm(before[k])) score++;
+  }
+  const after = anchor.contextAfter || [];
+  for (let k = 0; k < after.length; k++) {
+    const li = i + 1 + k;
+    if (li < lines.length && norm(lines[li]) === norm(after[k])) score++;
+  }
+  return score;
+}
+
+/**
+ * Recompute a comment's fate against a new version of its file.
+ *
+ * @param {object} anchor        a record from makeCommentAnchor()
+ * @param {string} newContent    the file's new content
+ * @returns {object} the anchor with updated {status, line, previousLine}
+ */
+export function reanchorComment(anchor, newContent) {
+  if (!anchor || typeof anchor !== "object") return anchor;
+  const previousLine = anchor.line;
+  const newHash = hashContent(newContent);
+
+  // Unchanged file → the coordinate is still true.
+  if (newHash === anchor.baseHash) {
+    return {
+      ...anchor,
+      status: ANCHOR_STATUS.CURRENT,
+      line: previousLine,
+      previousLine,
+    };
+  }
+
+  const target = norm(anchor.anchorLine);
+  // An anchor with no captured text can never be relocated — it's stale.
+  if (target === "") {
+    return {
+      ...anchor,
+      status: ANCHOR_STATUS.OUTDATED,
+      line: null,
+      previousLine,
+    };
+  }
+
+  const lines = splitLines(newContent);
+  const candidates = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (norm(lines[i]) === target) candidates.push(i);
+  }
+
+  if (candidates.length === 0) {
+    // The exact anchored code no longer exists — the fix changed/removed it.
+    return {
+      ...anchor,
+      status: ANCHOR_STATUS.OUTDATED,
+      line: null,
+      previousLine,
+    };
+  }
+
+  // Disambiguate multiple text matches by surrounding context.
+  let best = -1;
+  const winners = [];
+  for (const i of candidates) {
+    const s = contextScore(anchor, lines, i);
+    if (s > best) {
+      best = s;
+      winners.length = 0;
+      winners.push(i);
+    } else if (s === best) {
+      winners.push(i);
+    }
+  }
+
+  if (winners.length !== 1) {
+    // Equally-plausible locations — refuse to guess; never reuse the old line.
+    return {
+      ...anchor,
+      status: ANCHOR_STATUS.AMBIGUOUS,
+      line: null,
+      previousLine,
+    };
+  }
+
+  const newLine = winners[0] + 1;
+  const status =
+    newLine === previousLine ? ANCHOR_STATUS.CURRENT : ANCHOR_STATUS.MOVED;
+  return { ...anchor, status, line: newLine, previousLine };
+}
+
+/**
+ * Explicitly mark a comment resolved (the agent's fix addressed its issue). A
+ * caller-driven terminal state distinct from the auto-detected OUTDATED, so a
+ * reviewer can tell "you fixed this" from "the code you commented on vanished".
+ */
+export function markResolved(anchor, resolvedReason = "") {
+  return {
+    ...anchor,
+    status: ANCHOR_STATUS.RESOLVED,
+    line: null,
+    resolvedReason: String(resolvedReason || ""),
+  };
+}
+
+/**
+ * Re-anchor a list of comments against a new file version and bucket them.
+ * `resolvedIds` (optional) forces those comment ids to RESOLVED before/around
+ * the automatic re-anchor.
+ *
+ * @param {Array} anchors
+ * @param {string} newContent
+ * @param {{resolvedIds?:Iterable<string>}} [opts]
+ * @returns {{comments:Array, current:string[], moved:string[],
+ *            outdated:string[], ambiguous:string[], resolved:string[]}}
+ */
+export function reconcileComments(anchors, newContent, { resolvedIds } = {}) {
+  const resolved = new Set([...(resolvedIds || [])].map((x) => String(x)));
+  const comments = (Array.isArray(anchors) ? anchors : []).map((a) => {
+    if (a && a.id != null && resolved.has(String(a.id))) {
+      return markResolved(a, "marked resolved by caller");
+    }
+    return reanchorComment(a, newContent);
+  });
+  const bucket = (status) =>
+    comments.filter((c) => c && c.status === status).map((c) => c.id);
+  return {
+    comments,
+    current: bucket(ANCHOR_STATUS.CURRENT),
+    moved: bucket(ANCHOR_STATUS.MOVED),
+    outdated: bucket(ANCHOR_STATUS.OUTDATED),
+    ambiguous: bucket(ANCHOR_STATUS.AMBIGUOUS),
+    resolved: bucket(ANCHOR_STATUS.RESOLVED),
+  };
+}