fix(rebase): consolidate conflict recovery guidance into single clear block

henrikje · claude · henrikje · commit 6be535dd8859 · 2026-03-26T22:18:52.000+01:00
The conflict output duplicated and contradicted itself — mentioning both
git and arb continue/abort per-repo, then repeating arb at the bottom.
Redesign: per-repo sections show only conflict files, trailing block
provides one set of aligned instructions with a muted git reassurance.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/commands/pull.ts b/src/commands/pull.ts
@@ -391,7 +391,7 @@ export async function runPull(
       repo: c.assessment.repo,
       stdout: c.stdout,
       stderr: c.stderr,
-      subcommand: c.assessment.pullMode === "rebase" ? ("rebase" as const) : ("merge" as const),
+      mode: "pull",
     })),
   );
 
@@ -411,7 +411,7 @@ export async function runPull(
     record.status = "completed";
     record.completedAt = new Date().toISOString();
     writeOperationRecord(wsDir, record);
-  } else {
+  } else if (conflicted.length === 0 && failed.length > 0) {
     info("Use 'arb pull --continue' to resume or 'arb pull --abort' to cancel");
   }
 
diff --git a/src/commands/retarget.ts b/src/commands/retarget.ts
@@ -360,7 +360,7 @@ export function registerRetargetCommand(program: Command): void {
             repo: c.assessment.repo,
             stdout: c.stdout,
             stderr: c.stderr,
-            subcommand: "rebase" as const,
+            mode: "retarget",
           })),
         );
         const reportCtx = { tty: shouldColor() };
@@ -380,7 +380,6 @@ export function registerRetargetCommand(program: Command): void {
           }
         } else {
           // Conflicts — config NOT updated (this is the bug fix)
-          info("Use 'arb retarget --continue' to resume or 'arb retarget --abort' to cancel");
         }
 
         // Phase 9: summary
diff --git a/src/lib/render/conflict-report.test.ts b/src/lib/render/conflict-report.test.ts
@@ -7,26 +7,34 @@ describe("buildConflictReport", () => {
     expect(buildConflictReport([])).toEqual([]);
   });
 
-  test("produces gap + message + gap + section for a single entry", () => {
+  test("produces gap + message + gap + section + trailing guidance for a single entry", () => {
     const entries: ConflictEntry[] = [
-      { repo: "api", stdout: "CONFLICT (content): Merge conflict in index.ts\n", stderr: "", subcommand: "rebase" },
+      { repo: "api", stdout: "CONFLICT (content): Merge conflict in index.ts\n", stderr: "", mode: "rebase" },
     ];
     const nodes = buildConflictReport(entries);
 
     expect(nodes[0]).toEqual({ kind: "gap" });
     const msg = nodes[1] as MessageNode;
     expect(msg.kind).toBe("message");
-    expect(msg.text).toBe("1 repo(s) have conflicts:");
+    expect(msg.text).toBe("1 repo has conflicts:");
 
     expect(nodes[2]).toEqual({ kind: "gap" });
     const section = nodes[3] as SectionNode;
     expect(section.kind).toBe("section");
     expect(section.header.plain).toBe("api");
+    expect(section.items).toHaveLength(1);
     expect(section.items[0]?.spans[0]?.attention).toBe("muted");
     expect(section.items[0]?.plain).toBe("CONFLICT (content): Merge conflict in index.ts");
-    expect(section.items[1]?.plain).toBe("cd api");
-    expect(section.items[2]?.plain).toBe("# fix conflicts, then: git rebase --continue");
-    expect(section.items[3]?.plain).toBe("# or to undo: git rebase --abort");
+
+    // Trailing guidance
+    expect(nodes[4]).toEqual({ kind: "gap" });
+    const cont = nodes[5] as MessageNode;
+    expect(cont.text).toBe("Fix conflicts, then: arb rebase --continue");
+    const abort = nodes[6] as MessageNode;
+    expect(abort.text).toBe("Or to abort:         arb rebase --abort");
+    const git = nodes[7] as MessageNode;
+    expect(git.level).toBe("muted");
+    expect(git.text).toContain("git rebase --continue/--abort per repo");
   });
 
   test("filters only CONFLICT lines from combined stdout/stderr", () => {
@@ -35,38 +43,67 @@ describe("buildConflictReport", () => {
         repo: "web",
         stdout: "Applying: abc\nCONFLICT (content): file.ts\nFailed to merge\n",
         stderr: "error: could not apply\nCONFLICT (modify/delete): old.ts\n",
-        subcommand: "merge",
+        mode: "merge",
       },
     ];
     const nodes = buildConflictReport(entries);
     const section = nodes[3] as SectionNode;
-    const conflictItems = section.items.filter((i) => i.spans[0]?.attention === "muted");
-    expect(conflictItems).toHaveLength(3); // 2 CONFLICT lines + 1 arb guidance line
-    expect(conflictItems[0]?.plain).toBe("CONFLICT (content): file.ts");
-    expect(conflictItems[1]?.plain).toBe("CONFLICT (modify/delete): old.ts");
+    const mutedItems = section.items.filter((i) => i.spans[0]?.attention === "muted");
+    expect(mutedItems).toHaveLength(2);
+    expect(mutedItems[0]?.plain).toBe("CONFLICT (content): file.ts");
+    expect(mutedItems[1]?.plain).toBe("CONFLICT (modify/delete): old.ts");
   });
 
-  test("uses correct subcommand in recovery instructions", () => {
-    const mergeEntries: ConflictEntry[] = [{ repo: "lib", stdout: "", stderr: "", subcommand: "merge" }];
+  test("uses mode for arb command and derives git subcommand", () => {
+    const mergeEntries: ConflictEntry[] = [{ repo: "lib", stdout: "", stderr: "", mode: "merge" }];
     const mergeNodes = buildConflictReport(mergeEntries);
-    const section = mergeNodes[3] as SectionNode;
-    expect(section.items.some((i) => i.plain.includes("git merge --continue"))).toBe(true);
-    expect(section.items.some((i) => i.plain.includes("git merge --abort"))).toBe(true);
+    const cont = mergeNodes[5] as MessageNode;
+    expect(cont.text).toContain("arb merge --continue");
+    const abort = mergeNodes[6] as MessageNode;
+    expect(abort.text).toContain("arb merge --abort");
+    const git = mergeNodes[7] as MessageNode;
+    expect(git.text).toContain("git merge --continue/--abort");
+
+    // pull and retarget use git rebase under the hood
+    const pullEntries: ConflictEntry[] = [{ repo: "lib", stdout: "", stderr: "", mode: "pull" }];
+    const pullNodes = buildConflictReport(pullEntries);
+    const pullCont = pullNodes[5] as MessageNode;
+    expect(pullCont.text).toContain("arb pull --continue");
+    const pullGit = pullNodes[7] as MessageNode;
+    expect(pullGit.text).toContain("git rebase --continue/--abort");
+
+    const retargetEntries: ConflictEntry[] = [{ repo: "lib", stdout: "", stderr: "", mode: "retarget" }];
+    const retargetNodes = buildConflictReport(retargetEntries);
+    const retargetCont = retargetNodes[5] as MessageNode;
+    expect(retargetCont.text).toContain("arb retarget --continue");
+    const retargetGit = retargetNodes[7] as MessageNode;
+    expect(retargetGit.text).toContain("git rebase --continue/--abort");
   });
 
   test("produces gap between multiple repo sections", () => {
     const entries: ConflictEntry[] = [
-      { repo: "api", stdout: "", stderr: "", subcommand: "rebase" },
-      { repo: "web", stdout: "", stderr: "", subcommand: "rebase" },
+      { repo: "api", stdout: "", stderr: "", mode: "rebase" },
+      { repo: "web", stdout: "", stderr: "", mode: "rebase" },
     ];
     const nodes = buildConflictReport(entries);
 
     const msg = nodes[1] as MessageNode;
-    expect(msg.text).toBe("2 repo(s) have conflicts:");
+    expect(msg.text).toBe("2 repos have conflicts:");
 
-    // Structure: gap, message, gap, section(api), gap, section(web)
+    // Structure: gap, message, gap, section(api), gap, section(web), gap, message, message, message
     const kinds = nodes.map((n) => n.kind);
-    expect(kinds).toEqual(["gap", "message", "gap", "section", "gap", "section"]);
+    expect(kinds).toEqual([
+      "gap",
+      "message",
+      "gap",
+      "section",
+      "gap",
+      "section",
+      "gap",
+      "message",
+      "message",
+      "message",
+    ]);
   });
 });
 
@@ -80,7 +117,7 @@ describe("buildStashPopFailureReport", () => {
 
     expect(nodes[0]).toEqual({ kind: "gap" });
     const msg = nodes[1] as MessageNode;
-    expect(msg.text).toBe("1 repo(s) need manual stash application:");
+    expect(msg.text).toBe("1 repo needs manual stash application:");
 
     expect(nodes[2]).toEqual({ kind: "gap" });
     const section = nodes[3] as SectionNode;
diff --git a/src/lib/render/conflict-report.ts b/src/lib/render/conflict-report.ts
@@ -5,15 +5,14 @@ export interface ConflictEntry {
   repo: string;
   stdout: string;
   stderr: string;
-  subcommand: "rebase" | "merge";
+  /** The arb command name: "rebase", "merge", "pull", "retarget" */
+  mode: string;
 }
 
 export function buildConflictReport(entries: ConflictEntry[]): OutputNode[] {
   if (entries.length === 0) return [];
-  const nodes: OutputNode[] = [
-    { kind: "gap" },
-    { kind: "message", level: "default", text: `${entries.length} repo(s) have conflicts:` },
-  ];
+  const header = entries.length === 1 ? "1 repo has conflicts:" : `${entries.length} repos have conflicts:`;
+  const nodes: OutputNode[] = [{ kind: "gap" }, { kind: "message", level: "default", text: header }];
   for (const e of entries) {
     const combined = `${e.stdout}\n${e.stderr}`;
     const conflictLines = combined.split("\n").filter((l) => l.startsWith("CONFLICT"));
@@ -22,24 +21,35 @@ export function buildConflictReport(entries: ConflictEntry[]): OutputNode[] {
       {
         kind: "section",
         header: cell(e.repo),
-        items: [
-          ...conflictLines.map((line) => cell(line, "muted")),
-          cell(`cd ${e.repo}`),
-          cell(`# fix conflicts, then: git ${e.subcommand} --continue`),
-          cell(`# or to undo: git ${e.subcommand} --abort`),
-          cell(`# or from workspace root: arb ${e.subcommand} --continue  /  arb ${e.subcommand} --abort`, "muted"),
-        ],
+        items: conflictLines.map((line) => cell(line, "muted")),
       },
     );
   }
+  // Safe: guarded by early return when entries is empty
+  const mode = entries[0]?.mode ?? "rebase";
+  const gitSub = mode === "merge" ? "merge" : "rebase";
+  nodes.push(
+    { kind: "gap" },
+    { kind: "message", level: "default", text: `Fix conflicts, then: arb ${mode} --continue` },
+    { kind: "message", level: "default", text: `Or to abort:         arb ${mode} --abort` },
+    {
+      kind: "message",
+      level: "muted",
+      text: `                     (or use git ${gitSub} --continue/--abort per repo)`,
+    },
+  );
   return nodes;
 }
 
 export function buildStashPopFailureReport(repos: { repo: string }[], verb: string): OutputNode[] {
   if (repos.length === 0) return [];
   const nodes: OutputNode[] = [
     { kind: "gap" },
-    { kind: "message", level: "default", text: `${repos.length} repo(s) need manual stash application:` },
+    {
+      kind: "message",
+      level: "default",
+      text: `${repos.length === 1 ? "1 repo needs" : `${repos.length} repos need`} manual stash application:`,
+    },
   ];
   for (const r of repos) {
     nodes.push(
diff --git a/src/lib/sync/continue-flow.ts b/src/lib/sync/continue-flow.ts
@@ -200,13 +200,14 @@ export async function runContinueFlow(params: ContinueFlowParams): Promise<void>
 
   // Step 9: Show conflict details for failures (B2 fix)
   if (newConflicts.length > 0) {
-    const subcommand = mode === "merge" ? ("merge" as const) : ("rebase" as const);
     const conflictNodes = buildConflictReport(
-      newConflicts.map((c) => ({ repo: c.repo, stdout: c.stdout, stderr: c.stderr, subcommand })),
+      newConflicts.map((c) => ({ repo: c.repo, stdout: c.stdout, stderr: c.stderr, mode })),
     );
     if (conflictNodes.length > 0) {
       process.stderr.write(render(conflictNodes, rCtx));
     }
+  } else if (stillConflicting.length > 0) {
+    info(`Fix conflicts, then: arb ${mode} --continue`);
   }
 
   // Step 10: Finalize
@@ -219,9 +220,6 @@ export async function runContinueFlow(params: ContinueFlowParams): Promise<void>
     writeOperationRecord(wsDir, record);
   } else {
     writeOperationRecord(wsDir, record);
-    if (newConflicts.length > 0 || stillConflicting.length > 0) {
-      info(`Use 'arb ${mode} --continue' to resume or 'arb ${mode} --abort' to cancel`);
-    }
   }
 
   // Step 11: Summary
diff --git a/src/lib/sync/integrate.ts b/src/lib/sync/integrate.ts
@@ -304,13 +304,12 @@ export async function integrate(
   });
 
   // Consolidated conflict report
-  const subcommand = mode === "rebase" ? ("rebase" as const) : ("merge" as const);
   const conflictNodes = buildConflictReport(
     conflicted.map((c) => ({
       repo: c.assessment.repo,
       stdout: c.stdout,
       stderr: c.stderr,
-      subcommand,
+      mode,
     })),
   );
 
@@ -326,8 +325,6 @@ export async function integrate(
     record.status = "completed";
     record.completedAt = new Date().toISOString();
     writeOperationRecord(wsDir, record);
-  } else {
-    info(`Use 'arb ${mode} --continue' to resume or 'arb ${mode} --abort' to cancel`);
   }
 
   // Update config after stale base fallback
diff --git a/test/integration/integrate.test.ts b/test/integration/integrate.test.ts
@@ -69,8 +69,9 @@ describe("rebase", () => {
       expect(result.output).toContain("CONFLICT");
       expect(result.output).toContain("conflict.txt");
       expect(result.output).toContain("conflict");
-      expect(result.output).toContain("git rebase --continue");
-      expect(result.output).toContain("git rebase --abort");
+      expect(result.output).toContain("arb rebase --continue");
+      expect(result.output).toContain("arb rebase --abort");
+      expect(result.output).toContain("git rebase --continue/--abort per repo");
       expect(result.output).toContain("Rebased 1 repo, 1 conflicted");
     }));
 
@@ -207,8 +208,9 @@ describe("merge", () => {
       expect(result.output).toContain("CONFLICT");
       expect(result.output).toContain("conflict.txt");
       expect(result.output).toContain("conflict");
-      expect(result.output).toContain("git merge --continue");
-      expect(result.output).toContain("git merge --abort");
+      expect(result.output).toContain("arb merge --continue");
+      expect(result.output).toContain("arb merge --abort");
+      expect(result.output).toContain("git merge --continue/--abort per repo");
       expect(result.output).toContain("Merged 1 repo, 1 conflicted");
     }));
 });
