chainlesschain 0.162.163 → 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-rewind.js

@@ -31,6 +31,11 @@ import {
   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;
@@ -271,6 +276,102 @@ export function renderRewindWarnings(plan) {
   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),
+  };
+}

package/src/lib/review-pipeline.js

@@ -12,8 +12,16 @@
  * verifier verdicts, confidence-filter, rank, and render the structured report.
  * The fan-out of finder/verifier AGENTS is orchestration the command layer adds;
  * everything here is deterministic and testable without an LLM.
+ *
+ * P1-1 wiring (行评论锚定): when the caller supplies the reviewed file contents,
+ * each finding's output carries a re-anchorable comment ANCHOR (file + base hash
+ * + line + anchored line text + context) via [[review-comment-anchor.js]] instead
+ * of only a bare `line` coordinate — so a downstream IDE Diff Review can relocate
+ * or stale the comment after the agent edits the file, never reusing a dead line.
  */
 
+import { makeCommentAnchor } from "./review-comment-anchor.js";
+
 /** The finder dimensions a full review fans out across. */
 export const REVIEW_DIMENSIONS = Object.freeze([
   "correctness",
@@ -184,16 +192,44 @@ export function rankFindings(findings) {
   );
 }
 
-function toOutputFinding(f) {
-  return {
+/** Look a path's content up from a Map or plain object, or return undefined. */
+function lookupContent(fileContents, filePath) {
+  if (!fileContents) return undefined;
+  if (typeof fileContents.get === "function") return fileContents.get(filePath);
+  return fileContents[filePath];
+}
+
+function toOutputFinding(f, fileContents) {
+  const line = Number.isFinite(Number(f.line))
+    ? Math.floor(Number(f.line))
+    : null;
+  const failureScenario = String(f.failureScenario || f.failure_scenario || "");
+  const out = {
     path: String(f.path || ""),
-    line: Number.isFinite(Number(f.line)) ? Math.floor(Number(f.line)) : null,
+    line,
     category: f.category || (f.categories && f.categories[0]) || "correctness",
     severity: normalizeSeverity(f.severity),
-    failure_scenario: String(f.failureScenario || f.failure_scenario || ""),
+    failure_scenario: failureScenario,
     evidence: String(f.evidence || ""),
     confidence: clampConfidence(f.confidence),
   };
+  // P1-1: anchor the comment to the CODE it addresses, not to a coordinate, so
+  // an IDE diff review can relocate/stale it after edits (never reuse a dead
+  // line). Only when the caller supplied this file's content AND we have a
+  // valid 1-based line to anchor.
+  if (line != null && line >= 1) {
+    const content = lookupContent(fileContents, out.path);
+    if (typeof content === "string") {
+      out.anchor = makeCommentAnchor({
+        file: out.path,
+        content,
+        line,
+        comment: failureScenario || out.evidence,
+        id: `${out.path}:${line}:${out.category}`,
+      });
+    }
+  }
+  return out;
 }
 
 /**
@@ -202,17 +238,20 @@ function toOutputFinding(f) {
  * evidence output) plus severity/category rollups.
  *
  * @param {Array} rawFindings   findings from all finders
- * @param {object} [opts]       { verdicts, minConfidence }
+ * @param {object} [opts]       { verdicts, minConfidence, fileContents }
+ *   fileContents — optional Map/object of `path → current file content`. When a
+ *   finding's file is present, its output gains a re-anchorable `anchor` (P1-1);
+ *   omit it and the output is byte-identical to before.
  */
 export function buildReviewReport(
   rawFindings,
-  { verdicts = {}, minConfidence = 0 } = {},
+  { verdicts = {}, minConfidence = 0, fileContents = null } = {},
 ) {
   const deduped = dedupeFindings(rawFindings);
   const verified = applyVerdicts(deduped, verdicts);
   const filtered = filterByConfidence(verified, { minConfidence });
   const ranked = rankFindings(filtered);
-  const findings = ranked.map(toOutputFinding);
+  const findings = ranked.map((f) => toOutputFinding(f, fileContents));
 
   const bySeverity = { Critical: 0, High: 0, Medium: 0, Low: 0, Note: 0 };
   const byCategory = {};