From dc1a72b94e6f1f82141bb1373d4171eda19c8303 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Mon, 1 Jun 2026 22:40:58 +0200
Subject: [PATCH 1/8] feat(core): two-way union merge for adopt auto-merge mode
 (#120)

Adopt compares user-vault vs rendered-shard with no merge base, so a
three-way merge (differ.ts) is impossible. twoWayUnionMerge does a
best-effort union via diffLines: keep common lines, union each side's
unique lines, and report a conflict when both sides replaced the same
span (caller prompts on those).

Documented limitations (inherent to having no base): keeps user bytes so
it cannot apply shard deletions, and can duplicate non-adjacent related
edits. content is only valid when hasConflict is false. Binary inputs
always conflict.

Tests: identical / pure-insertion each side / shard-deletion-kept /
non-overlapping-both / overlapping-replacement-conflict / binary / empty
/ CRLF, plus determinism and common-line-survival properties (fast-check).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 source/core/adopt-merge.ts     |  96 ++++++++++++++++++++++++++++
 tests/unit/adopt-merge.test.ts | 111 +++++++++++++++++++++++++++++++++
 2 files changed, 207 insertions(+)
 create mode 100644 source/core/adopt-merge.ts
 create mode 100644 tests/unit/adopt-merge.test.ts

diff --git a/source/core/adopt-merge.ts b/source/core/adopt-merge.ts
new file mode 100644
index 0000000..e86e0e9
--- /dev/null
+++ b/source/core/adopt-merge.ts
@@ -0,0 +1,96 @@
+/**
+ * Two-way union merge for `shardmind adopt --mode=auto-merge` (#120).
+ *
+ * Adopt compares the user's vault file against the rendered shard file with
+ * **no common ancestor** — the vault was cloned without shardmind, so the
+ * original shard version that produced the user's bytes is unrecorded. A
+ * base-anchored three-way merge (`core/differ.ts`, used by `update`) is
+ * therefore impossible here.
+ *
+ * What we can do instead is a *union* merge: keep every line the two sides
+ * share, keep each side's unique lines, and treat a region where BOTH sides
+ * replaced the same span as a conflict that the caller resolves by prompting.
+ *
+ * This is a deliberately weaker, best-effort operation — surfaced as such in
+ * the mode picker and docs. Its limitations are inherent to having no base:
+ *
+ *   - It **keeps the user's bytes** and therefore **does not apply shard
+ *     deletions**: content the shard removed looks "user-unique" and is
+ *     retained.
+ *   - "Non-conflicting" is a line-*adjacency* heuristic. Two edits to the
+ *     same idea that `diffLines` does not align as one replacement run are
+ *     both kept (union), which can duplicate content. Overlapping (adjacent
+ *     removed+added) runs are always reported as conflicts, never combined.
+ *
+ * `content` is the union and is only meaningful when `hasConflict === false`;
+ * the caller sends conflicting files to the per-file prompt instead.
+ */
+
+import { diffLines } from 'diff';
+
+export interface TwoWayMergeResult {
+  /** The union-merged bytes. Only valid when `hasConflict === false`. */
+  content: Buffer;
+  /** True when some region needs a human decision (or the input is binary). */
+  hasConflict: boolean;
+}
+
+/**
+ * Union-merge `userContent` and `shardContent`.
+ *
+ * Binary inputs can't be line-merged, so they always conflict (the caller
+ * prompts). For text, walk `diffLines` and group each maximal run of
+ * non-common parts: a run touching only one side is unioned in; a run
+ * touching both sides (a replacement) marks a conflict.
+ */
+export function twoWayUnionMerge(
+  userContent: Buffer,
+  shardContent: Buffer,
+  isBinary: boolean,
+): TwoWayMergeResult {
+  if (isBinary) {
+    // No meaningful line merge — force a prompt. `content` is unused.
+    return { content: userContent, hasConflict: true };
+  }
+
+  const parts = diffLines(userContent.toString('utf8'), shardContent.toString('utf8'));
+
+  let hasConflict = false;
+  let out = '';
+
+  let i = 0;
+  while (i < parts.length) {
+    const part = parts[i]!;
+    if (!part.added && !part.removed) {
+      // Common to both sides — emit verbatim (raw value preserves the
+      // exact bytes, including any CRLF / trailing newline).
+      out += part.value;
+      i++;
+      continue;
+    }
+
+    // Gather the maximal contiguous run of changed parts.
+    let runHasUser = false; // removed === present in user, absent in shard
+    let runHasShard = false; // added === present in shard, absent in user
+    let runValue = '';
+    let j = i;
+    while (j < parts.length && (parts[j]!.added || parts[j]!.removed)) {
+      if (parts[j]!.removed) runHasUser = true;
+      if (parts[j]!.added) runHasShard = true;
+      runValue += parts[j]!.value;
+      j++;
+    }
+
+    if (runHasUser && runHasShard) {
+      // Both sides replaced the same span — a real conflict. Leave it for
+      // the per-file prompt; the union `content` is no longer usable.
+      hasConflict = true;
+    } else {
+      // Pure one-side change (user-unique OR shard-unique lines) — union it.
+      out += runValue;
+    }
+    i = j;
+  }
+
+  return { content: Buffer.from(out, 'utf8'), hasConflict };
+}
diff --git a/tests/unit/adopt-merge.test.ts b/tests/unit/adopt-merge.test.ts
new file mode 100644
index 0000000..23ed93f
--- /dev/null
+++ b/tests/unit/adopt-merge.test.ts
@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import * as fc from 'fast-check';
+import { twoWayUnionMerge } from '../../source/core/adopt-merge.js';
+
+const buf = (s: string) => Buffer.from(s, 'utf8');
+
+describe('twoWayUnionMerge', () => {
+  it('identical content → no conflict, content unchanged', () => {
+    const s = 'line1\nline2\n';
+    const r = twoWayUnionMerge(buf(s), buf(s), false);
+    expect(r.hasConflict).toBe(false);
+    expect(r.content.toString('utf8')).toBe(s);
+  });
+
+  it('pure shard insertion → union takes the shard line, no conflict', () => {
+    const user = 'line1\nline2\n';
+    const shard = 'line1\ninserted\nline2\n';
+    const r = twoWayUnionMerge(buf(user), buf(shard), false);
+    expect(r.hasConflict).toBe(false);
+    expect(r.content.toString('utf8')).toBe(shard);
+  });
+
+  it('pure user-only line (shard deleted it) → union KEEPS the user line, no conflict', () => {
+    // Demonstrates the documented limitation: without a base, a shard
+    // deletion is indistinguishable from a user-unique line, so it is kept.
+    const user = 'line1\nmine\nline2\n';
+    const shard = 'line1\nline2\n';
+    const r = twoWayUnionMerge(buf(user), buf(shard), false);
+    expect(r.hasConflict).toBe(false);
+    expect(r.content.toString('utf8')).toBe(user);
+  });
+
+  it('non-overlapping edits on both sides → union of both, no conflict', () => {
+    const user = 'header\nmine\nfooter\n';
+    const shard = 'header\nfooter\ntheirs\n';
+    const r = twoWayUnionMerge(buf(user), buf(shard), false);
+    expect(r.hasConflict).toBe(false);
+    const out = r.content.toString('utf8');
+    expect(out).toContain('mine');
+    expect(out).toContain('theirs');
+    expect(out).toContain('header');
+    expect(out).toContain('footer');
+  });
+
+  it('overlapping replacement of the same line → conflict', () => {
+    const user = 'line1\nMINE\nline3\n';
+    const shard = 'line1\nTHEIRS\nline3\n';
+    const r = twoWayUnionMerge(buf(user), buf(shard), false);
+    expect(r.hasConflict).toBe(true);
+  });
+
+  it('binary input → always conflict (no line merge attempted)', () => {
+    const user = '\x00\x01mine';
+    const shard = '\x00\x01theirs';
+    const r = twoWayUnionMerge(buf(user), buf(shard), true);
+    expect(r.hasConflict).toBe(true);
+  });
+
+  it('empty user file, shard has content → union is the shard content', () => {
+    const r = twoWayUnionMerge(buf(''), buf('a\nb\n'), false);
+    expect(r.hasConflict).toBe(false);
+    expect(r.content.toString('utf8')).toBe('a\nb\n');
+  });
+
+  it('preserves CRLF bytes in unioned regions', () => {
+    const user = 'a\r\nb\r\n';
+    const shard = 'a\r\ninserted\r\nb\r\n';
+    const r = twoWayUnionMerge(buf(user), buf(shard), false);
+    expect(r.hasConflict).toBe(false);
+    expect(r.content.toString('utf8')).toBe(shard);
+  });
+
+  // ── Properties ──────────────────────────────────────────────────────
+
+  it('property: deterministic — same inputs produce the same result', () => {
+    fc.assert(
+      fc.property(fc.string(), fc.string(), (u, s) => {
+        const a = twoWayUnionMerge(buf(u), buf(s), false);
+        const b = twoWayUnionMerge(buf(u), buf(s), false);
+        return (
+          a.hasConflict === b.hasConflict &&
+          a.content.equals(b.content)
+        );
+      }),
+    );
+  });
+
+  it('property: when no conflict, every common line survives in the union', () => {
+    // Build user/shard from a shared anchor list with side-unique insertions
+    // so the merge is a clean union; assert the anchors all appear.
+    fc.assert(
+      fc.property(
+        fc.uniqueArray(fc.stringMatching(/^[a-z]{1,8}$/), { minLength: 1, maxLength: 6 }),
+        fc.stringMatching(/^[A-Z]{1,8}$/),
+        fc.stringMatching(/^[0-9]{1,8}$/),
+        (anchors, userExtra, shardExtra) => {
+          // user = anchors with userExtra appended; shard = anchors with
+          // shardExtra appended. The trailing insertions are on different
+          // sides at the same tail position, so they may or may not conflict;
+          // we only assert the invariant on the no-conflict branch.
+          const user = [...anchors, userExtra].join('\n') + '\n';
+          const shard = [...anchors, shardExtra].join('\n') + '\n';
+          const r = twoWayUnionMerge(buf(user), buf(shard), false);
+          if (r.hasConflict) return true; // precondition not met
+          const out = r.content.toString('utf8');
+          return anchors.every((a) => out.includes(a));
+        },
+      ),
+    );
+  });
+});

From fe5cc2e38a903c595d822518bc94c8036103b6ae Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Mon, 1 Jun 2026 22:45:49 +0200
Subject: [PATCH 2/8] feat(core): executor support for merged adopt resolutions
 (#120)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extend AdoptResolution with a { kind:'merged', content, hash } variant so
the auto-merge mode can hand the executor pre-merged union bytes. The
executor writes them as `modified` ownership at the merged hash (it's
user-customized content), buckets them in a new summary.adoptedMerged,
adds the 'differs-merged' AdoptApplyKind, and snapshots merged paths for
rollback alongside use_shard (both overwrite the user's file). A future
`update` three-way-merges the result against the cached shard template.

labelForAction gains the merged glyph so its exhaustive switch typechecks.

Integration test: differs + merged resolution → union bytes on disk,
`modified` ownership at the merged hash, adoptedMerged bucket.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 source/commands/hooks/use-adopt-machine.ts |  2 +
 source/core/adopt-executor.ts              | 53 ++++++++++++++++++----
 tests/integration/adopt.test.ts            | 53 ++++++++++++++++++++++
 3 files changed, 99 insertions(+), 9 deletions(-)

diff --git a/source/commands/hooks/use-adopt-machine.ts b/source/commands/hooks/use-adopt-machine.ts
index 2a608b8..5d109fc 100644
--- a/source/commands/hooks/use-adopt-machine.ts
+++ b/source/commands/hooks/use-adopt-machine.ts
@@ -505,5 +505,7 @@ function labelForAction(kind: AdoptApplyKind): string {
       return '→';
     case 'differs-use-shard':
       return '↻';
+    case 'differs-merged':
+      return '⊕';
   }
 }
diff --git a/source/core/adopt-executor.ts b/source/core/adopt-executor.ts
index 13aa830..62ff8f0 100644
--- a/source/core/adopt-executor.ts
+++ b/source/core/adopt-executor.ts
@@ -60,11 +60,25 @@ const SNAPSHOT_CONCURRENCY = 16;
  * One decision per `differs` entry. The diff UI returns this shape; the
  * executor reads it. Two values mirror the spec's two-choice prompt.
  */
-export type AdoptResolution = 'keep_mine' | 'use_shard';
+/**
+ * One decision per `differs` entry. `keep_mine` / `use_shard` mirror the
+ * per-file prompt. `merged` carries the bytes produced by the auto-merge
+ * mode's two-way union merge (#120) so the executor can write them without
+ * re-running the merge; the machine computes them and supplies the hash.
+ */
+export type AdoptResolution =
+  | 'keep_mine'
+  | 'use_shard'
+  | { kind: 'merged'; content: Buffer; hash: string };
 
 /** Map vault-relative path → resolution for every `plan.differs[]` entry. */
 export type AdoptResolutions = Record<string, AdoptResolution>;
 
+/** A resolution that overwrites the user's file → needs a rollback snapshot. */
+function overwritesUserFile(resolution: AdoptResolution | undefined): boolean {
+  return resolution === 'use_shard' || (typeof resolution === 'object' && resolution.kind === 'merged');
+}
+
 export interface AdoptRunnerOptions {
   vaultRoot: string;
   manifest: ShardManifest;
@@ -100,7 +114,8 @@ export type AdoptApplyKind =
   | 'matches'
   | 'shard-only'
   | 'differs-keep-mine'
-  | 'differs-use-shard';
+  | 'differs-use-shard'
+  | 'differs-merged';
 
 export type AdoptProgressEvent =
   | { kind: 'start'; total: number }
@@ -124,6 +139,8 @@ export interface AdoptSummary {
   matchedAuto: string[];
   adoptedMine: string[];
   adoptedShard: string[];
+  /** Files written by the auto-merge mode's union merge (#120). */
+  adoptedMerged: string[];
   installedFresh: string[];
   totalManaged: number;
 }
@@ -215,6 +232,7 @@ export async function runAdopt(opts: AdoptRunnerOptions): Promise<AdoptResult> {
     matchedAuto: [],
     adoptedMine: [],
     adoptedShard: [],
+    adoptedMerged: [],
     installedFresh: [],
     totalManaged: 0,
   };
@@ -279,7 +297,11 @@ export async function runAdopt(opts: AdoptRunnerOptions): Promise<AdoptResult> {
         );
       }
       const action: AdoptApplyKind =
-        resolution === 'keep_mine' ? 'differs-keep-mine' : 'differs-use-shard';
+        resolution === 'keep_mine'
+          ? 'differs-keep-mine'
+          : resolution === 'use_shard'
+            ? 'differs-use-shard'
+            : 'differs-merged';
       onProgress?.({
         kind: 'file',
         index,
@@ -292,13 +314,25 @@ export async function runAdopt(opts: AdoptRunnerOptions): Promise<AdoptResult> {
         fileStates[c.path] = buildFileState(c, c.userHash, 'modified');
         onFileTouched?.(c.path, false);
         summary.adoptedMine.push(c.path);
-      } else {
+      } else if (resolution === 'use_shard') {
         if (!dryRun) {
           await writeVaultFileBuffer(vaultRoot, c.path, c.shardContent);
         }
         fileStates[c.path] = buildFileState(c, c.shardHash, 'managed');
         onFileTouched?.(c.path, false);
         summary.adoptedShard.push(c.path);
+      } else {
+        // Auto-merge (#120): write the union-merged bytes. The result is
+        // user-customized content (it contains the user's lines), so it is
+        // recorded as `modified` ownership at the merged hash — exactly like
+        // a kept-but-edited managed file. A future `update` three-way-merges
+        // it against the cached shard template, which is the proper base.
+        if (!dryRun) {
+          await writeVaultFileBuffer(vaultRoot, c.path, resolution.content);
+        }
+        fileStates[c.path] = buildFileState(c, resolution.hash, 'modified');
+        onFileTouched?.(c.path, false);
+        summary.adoptedMerged.push(c.path);
       }
     }
 
@@ -363,10 +397,11 @@ async function createBackupDir(vaultRoot: string, now: Date): Promise<string> {
 }
 
 /**
- * Snapshot every path the apply phase will overwrite. Only `differs +
- * use_shard` triggers a snapshot — `matches` writes nothing,
- * `differs + keep_mine` writes nothing, and `shard-only` writes to a
- * path that doesn't exist yet (rollback erases via `addedPaths` instead).
+ * Snapshot every path the apply phase will overwrite — `differs + use_shard`
+ * and `differs + merged` (auto-merge) both replace existing user bytes.
+ * `matches` writes nothing, `differs + keep_mine` writes nothing, and
+ * `shard-only` writes to a path that doesn't exist yet (rollback erases via
+ * `addedPaths` instead).
  *
  * Tolerates ENOENT defensively: a `differs-use-shard` path whose user
  * file vanished between plan-time and execute-time is unusual but not
@@ -383,7 +418,7 @@ async function snapshotForRollback(
   await fsp.mkdir(filesBackupDir, { recursive: true });
 
   const toSnapshot = plan.differs
-    .filter((c) => resolutions[c.path] === 'use_shard')
+    .filter((c) => overwritesUserFile(resolutions[c.path]))
     .map((c) => c.path);
 
   await mapConcurrent(toSnapshot, SNAPSHOT_CONCURRENCY, async (rel) => {
diff --git a/tests/integration/adopt.test.ts b/tests/integration/adopt.test.ts
index cc21e1b..ba812b0 100644
--- a/tests/integration/adopt.test.ts
+++ b/tests/integration/adopt.test.ts
@@ -299,6 +299,59 @@ describe('adopt pipeline (against examples/minimal-shard)', () => {
     expect(result.summary.installedFresh).toContain('brain/North Star.md');
   });
 
+  it('differs + merged resolution: writes the union bytes as `modified`, buckets as adoptedMerged (#120)', async () => {
+    // The executor does not re-run the merge — it writes whatever bytes the
+    // `merged` resolution carries (the machine computes them via
+    // twoWayUnionMerge). Feed explicit merged bytes to isolate the executor's
+    // merged branch from the merge algorithm (unit-tested separately).
+    const { manifest, schema } = await loadShard();
+    const selections = defaultModuleSelections(schema);
+    const validator = buildValuesValidator(schema);
+    const values = validator.parse(resolveComputedDefaults(schema, VALUES));
+
+    await runInstall({
+      vaultRoot: vault,
+      manifest,
+      schema,
+      tempDir: MINIMAL_SHARD,
+      resolved: RESOLVED,
+      tarballSha256: 'deadbeef',
+      values: values as Record<string, unknown>,
+      selections,
+    });
+    await fsp.rm(path.join(vault, '.shardmind'), { recursive: true, force: true });
+    await fsp.rm(path.join(vault, 'shard-values.yaml'), { force: true });
+
+    // Mutate Home.md so it classifies as `differs`.
+    await fsp.writeFile(path.join(vault, 'Home.md'), '# Home — my preferred shape\n', 'utf-8');
+
+    const adoptPlan = await plan(vault);
+    expect(adoptPlan.differs.map((c) => c.path)).toContain('Home.md');
+
+    const mergedBytes = Buffer.from('# Home — union of mine + shard\n', 'utf-8');
+    const mergedHash = sha256(mergedBytes);
+    // Resolve every differs path (minimal-shard has a time-varying template
+    // that also classifies as `differs`); only Home.md uses `merged`.
+    const resolutions: AdoptResolutions = {};
+    for (const c of adoptPlan.differs) resolutions[c.path] = 'keep_mine';
+    resolutions['Home.md'] = { kind: 'merged', content: mergedBytes, hash: mergedHash };
+
+    const { result } = await adopt(vault, resolutions);
+
+    // Merged bytes are on disk.
+    const homeDisk = await fsp.readFile(path.join(vault, 'Home.md'), 'utf-8');
+    expect(homeDisk).toBe('# Home — union of mine + shard\n');
+
+    // Recorded as user-customized (modified) at the merged hash.
+    const state = (await readState(vault)) as ShardState;
+    expect(state.files['Home.md']?.ownership).toBe('modified');
+    expect(state.files['Home.md']?.rendered_hash).toBe(mergedHash);
+
+    expect(result.summary.adoptedMerged).toContain('Home.md');
+    expect(result.summary.adoptedMine).not.toContain('Home.md');
+    expect(result.summary.adoptedShard).not.toContain('Home.md');
+  });
+
   it('rejects adopt when .shardmind/state.json already exists', async () => {
     // Simulate a previously-installed vault.
     const { manifest, schema } = await loadShard();

From 363c30ee3bd377a12cffaba0f03c9ce3992433ce Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Mon, 1 Jun 2026 23:06:26 +0200
Subject: [PATCH 3/8] feat(adopt): batch mode picker + --mode flag for the
 differs set (#120)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a top-level AdoptModePicker shown once (when files differ and no
--mode/--yes) before the per-file loop, plus a --mode flag for
non-interactive runs:

- keep-all-mine / use-all-theirs resolve every divergent file one way.
- auto-merge two-way-unions the non-conflicting files (writing merged
  bytes) and sends only the conflicting ones to the per-file prompt;
  non-interactive auto-merge falls those back to keep_mine.
- decide-per-file is the existing per-file loop.

Machine: new mode-select phase + applyMode; the diff-review phase now
iterates a `queue` (the files needing a prompt) with pre-seeded
resolutions, so per-file and auto-merge share one loop. --yes is shorthand
for keep-all-mine; --mode overrides it. AdoptMode is component-owned
(AdoptModePicker) and imported by the machine, mirroring AdoptDiffAction —
components never import from commands.

UI: AdoptSummary renders the new adoptedMerged bucket with a
"review recommended" note. The auto-merge option is labelled best-effort.

Tests: AdoptModePicker component test (modes + firedRef guard); Layer 1
scenarios 27-30 (keep-all / use-all / auto-merge mixed conflict / --mode
non-interactive); scenarios 20-21 updated to pass through the picker;
Layer 2 PTY scenario 20 picks decide-per-file; AdoptSummary merged-bucket
test + fixture.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 source/commands/adopt.tsx                  |  24 +++-
 source/commands/hooks/use-adopt-machine.ts | 145 ++++++++++++++++++---
 source/components/AdoptModePicker.tsx      |  75 +++++++++++
 source/components/AdoptSummary.tsx         |   8 ++
 tests/component/AdoptModePicker.test.tsx   |  76 +++++++++++
 tests/component/AdoptSummary.test.tsx      |  12 ++
 tests/component/flows/adopt-flow.test.tsx  | 138 ++++++++++++++++++++
 tests/component/flows/helpers.tsx          |   1 +
 tests/e2e/tui/adopt-diff.test.ts           |  14 ++
 9 files changed, 470 insertions(+), 23 deletions(-)
 create mode 100644 source/components/AdoptModePicker.tsx
 create mode 100644 tests/component/AdoptModePicker.test.tsx

diff --git a/source/commands/adopt.tsx b/source/commands/adopt.tsx
index 44db3fb..9cf2ee8 100644
--- a/source/commands/adopt.tsx
+++ b/source/commands/adopt.tsx
@@ -5,6 +5,7 @@ import { ShardMindError, assertNever } from '../runtime/types.js';
 
 import { Spinner, StatusMessage, Alert } from '../components/ui.js';
 import AdoptValuesGate from '../components/AdoptValuesGate.js';
+import AdoptModePicker from '../components/AdoptModePicker.js';
 import AdoptDiffView from '../components/AdoptDiffView.js';
 import AdoptSummary from '../components/AdoptSummary.js';
 import CommandFrame from '../components/CommandFrame.js';
@@ -28,6 +29,12 @@ export const options = zod.object({
     .boolean()
     .default(false)
     .describe('Skip prompts; auto-keep your version on every differs decision'),
+  mode: zod
+    .enum(['keep-all-mine', 'use-all-theirs', 'auto-merge', 'decide-per-file'])
+    .optional()
+    .describe(
+      'Resolve all divergent files non-interactively. auto-merge is best-effort (keeps your bytes, ignores shard deletions, may duplicate — review after)',
+    ),
   verbose: zod.boolean().default(false).describe('Show per-file action history during adopt'),
   dryRun: zod
     .boolean()
@@ -46,18 +53,20 @@ type Props = {
 
 export default function Adopt({ args, options }: Props) {
   const [shardRef] = args;
-  const { values: valuesFile, yes, verbose, dryRun, noUpdateCheck } = options;
+  const { values: valuesFile, yes, mode, verbose, dryRun, noUpdateCheck } = options;
 
   const {
     phase,
     onWizardComplete,
     onWizardCancel,
     onWizardError,
+    onModeSelect,
     onDiffChoice,
   } = useAdoptMachine({
     shardRef: shardRef!,
     valuesFile,
     yes,
+    mode,
     verbose,
     dryRun,
     vaultRoot: process.cwd(),
@@ -108,15 +117,24 @@ export default function Adopt({ args, options }: Props) {
           </Box>
         </CommandFrame>
       );
+    case 'mode-select':
+      return (
+        <CommandFrame dryRun={dryRun} selfUpdateBanner={banner}>
+          <AdoptModePicker
+            differsCount={phase.plan.differs.length}
+            onSelect={onModeSelect}
+          />
+        </CommandFrame>
+      );
     case 'diff-review': {
-      const target = phase.plan.differs[phase.currentIndex];
+      const target = phase.queue[phase.currentIndex];
       if (!target || target.kind !== 'differs') return null;
       return (
         <CommandFrame dryRun={dryRun} selfUpdateBanner={banner}>
           <AdoptDiffView
             path={target.path}
             index={phase.currentIndex + 1}
-            total={phase.plan.differs.length}
+            total={phase.queue.length}
             shardContent={target.shardContent}
             userContent={target.userContent}
             isBinary={target.isBinary}
diff --git a/source/commands/hooks/use-adopt-machine.ts b/source/commands/hooks/use-adopt-machine.ts
index 5d109fc..296c972 100644
--- a/source/commands/hooks/use-adopt-machine.ts
+++ b/source/commands/hooks/use-adopt-machine.ts
@@ -41,7 +41,10 @@ import { loadValuesYaml } from '../../core/values-io.js';
 import {
   classifyAdoption,
   type AdoptPlan,
+  type AdoptClassification,
 } from '../../core/adopt-planner.js';
+import { twoWayUnionMerge } from '../../core/adopt-merge.js';
+import { sha256 } from '../../core/fs-utils.js';
 import {
   assertAdoptable,
   rollbackAdopt,
@@ -65,11 +68,14 @@ import {
 
 import type { WizardResult } from '../../components/InstallWizard.js';
 import type { AdoptDiffAction } from '../../components/AdoptDiffView.js';
+import type { AdoptMode } from '../../components/AdoptModePicker.js';
 
 export interface UseAdoptMachineInput {
   shardRef: string;
   valuesFile: string | undefined;
   yes: boolean;
+  /** Non-interactive batch mode from `--mode`; overrides the picker. */
+  mode: AdoptMode | undefined;
   verbose: boolean;
   dryRun: boolean;
   vaultRoot: string;
@@ -94,11 +100,21 @@ export type Phase =
       ctx: PreparedContext;
       result: WizardResult;
     }
+  | {
+      kind: 'mode-select';
+      ctx: PreparedContext;
+      result: WizardResult;
+      plan: AdoptPlan;
+    }
   | {
       kind: 'diff-review';
       ctx: PreparedContext;
       result: WizardResult;
       plan: AdoptPlan;
+      // The files that still need a per-file decision. For `decide-per-file`
+      // this is every `differs`; for `auto-merge` it's only the conflicting
+      // ones (the rest are pre-resolved in `resolutions`).
+      queue: AdoptClassification[];
       currentIndex: number;
       resolutions: AdoptResolutions;
     }
@@ -131,11 +147,12 @@ export interface UseAdoptMachineOutput {
   onWizardComplete: (result: WizardResult) => void;
   onWizardCancel: () => void;
   onWizardError: (err: Error) => void;
+  onModeSelect: (mode: AdoptMode) => void;
   onDiffChoice: (action: AdoptDiffAction) => void;
 }
 
 export function useAdoptMachine(input: UseAdoptMachineInput): UseAdoptMachineOutput {
-  const { shardRef, valuesFile, yes, verbose, dryRun, vaultRoot } = input;
+  const { shardRef, valuesFile, yes, mode, verbose, dryRun, vaultRoot } = input;
   const { exit } = useApp();
 
   const [phase, setPhase] = useState<Phase>({ kind: 'booting' });
@@ -285,31 +302,28 @@ export function useAdoptMachine(input: UseAdoptMachineInput): UseAdoptMachineOut
           selections: validatedResult.selections,
         });
 
-        if (plan.differs.length === 0 || yes) {
-          // --yes auto-resolves every differs as `keep_mine` — preserves
-          // the user's bytes, which is the safe default for retroactive
-          // adoption (the user opted into keeping the vault they already
-          // had). They can re-run with explicit decisions if they want.
-          const resolutions: AdoptResolutions = {};
-          for (const c of plan.differs) resolutions[c.path] = 'keep_mine';
-          await executeAdopt(ctx, validatedResult, plan, resolutions);
+        if (plan.differs.length === 0) {
+          await executeAdopt(ctx, validatedResult, plan, {});
           return;
         }
 
-        setPhase({
-          kind: 'diff-review',
-          ctx,
-          result: validatedResult,
-          plan,
-          currentIndex: 0,
-          resolutions: {},
-        });
+        // `--mode` overrides the picker; `--yes` is shorthand for
+        // keep-all-mine (preserve the user's bytes — the safe default for
+        // retroactive adoption). With neither, prompt for the mode.
+        const effectiveMode: AdoptMode | undefined =
+          mode ?? (yes ? 'keep-all-mine' : undefined);
+        if (effectiveMode) {
+          await applyMode(effectiveMode, ctx, validatedResult, plan, false);
+          return;
+        }
+
+        setPhase({ kind: 'mode-select', ctx, result: validatedResult, plan });
       } catch (err) {
         finish({ kind: 'error', error: err as Error });
       }
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [vaultRoot, yes, finish],
+    [vaultRoot, yes, mode, finish],
   );
 
   const executeAdopt = useCallback(
@@ -439,6 +453,87 @@ export function useAdoptMachine(input: UseAdoptMachineInput): UseAdoptMachineOut
     [vaultRoot, dryRun, verbose, finish],
   );
 
+  // Resolve the `differs` set according to a batch mode, then either execute
+  // directly or drop into the per-file prompt for whatever's left.
+  const applyMode = useCallback(
+    async (
+      selected: AdoptMode,
+      ctx: PreparedContext,
+      result: WizardResult,
+      plan: AdoptPlan,
+      interactive: boolean,
+    ) => {
+      try {
+        if (selected === 'keep-all-mine' || selected === 'use-all-theirs') {
+          const decision = selected === 'keep-all-mine' ? 'keep_mine' : 'use_shard';
+          const resolutions: AdoptResolutions = {};
+          for (const c of plan.differs) resolutions[c.path] = decision;
+          await executeAdopt(ctx, result, plan, resolutions);
+          return;
+        }
+
+        if (selected === 'decide-per-file') {
+          setPhase({
+            kind: 'diff-review',
+            ctx,
+            result,
+            plan,
+            queue: plan.differs,
+            currentIndex: 0,
+            resolutions: {},
+          });
+          return;
+        }
+
+        // auto-merge: two-way-union each differs file; non-conflicting files
+        // resolve to their merged bytes, conflicting files queue for a prompt.
+        const resolutions: AdoptResolutions = {};
+        const queue: AdoptClassification[] = [];
+        for (const c of plan.differs) {
+          if (c.kind !== 'differs') continue;
+          const merged = twoWayUnionMerge(c.userContent, c.shardContent, c.isBinary);
+          if (merged.hasConflict) {
+            queue.push(c);
+          } else {
+            resolutions[c.path] = {
+              kind: 'merged',
+              content: merged.content,
+              hash: sha256(merged.content),
+            };
+          }
+        }
+
+        if (queue.length === 0) {
+          await executeAdopt(ctx, result, plan, resolutions);
+          return;
+        }
+
+        if (interactive) {
+          setPhase({
+            kind: 'diff-review',
+            ctx,
+            result,
+            plan,
+            queue,
+            currentIndex: 0,
+            resolutions,
+          });
+          return;
+        }
+
+        // Non-interactive auto-merge (`--mode=auto-merge` with no prompts):
+        // conflicting files fall back to keep_mine (preserve the user's
+        // bytes). They still surface in the summary's adoptedMine bucket.
+        for (const c of queue) resolutions[c.path] = 'keep_mine';
+        await executeAdopt(ctx, result, plan, resolutions);
+      } catch (err) {
+        finish({ kind: 'error', error: err as Error });
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [finish],
+  );
+
   const onWizardComplete = useCallback(
     (result: WizardResult) => {
       const current = phaseRef.current;
@@ -458,15 +553,24 @@ export function useAdoptMachine(input: UseAdoptMachineInput): UseAdoptMachineOut
     [finish],
   );
 
+  const onModeSelect = useCallback(
+    (selected: AdoptMode) => {
+      const current = phaseRef.current;
+      if (current.kind !== 'mode-select') return;
+      void applyMode(selected, current.ctx, current.result, current.plan, true);
+    },
+    [applyMode],
+  );
+
   const onDiffChoice = useCallback(
     (action: AdoptDiffAction) => {
       const current = phaseRef.current;
       if (current.kind !== 'diff-review') return;
-      const target = current.plan.differs[current.currentIndex];
+      const target = current.queue[current.currentIndex];
       if (!target) return;
       const next = { ...current.resolutions, [target.path]: action };
       const nextIndex = current.currentIndex + 1;
-      if (nextIndex < current.plan.differs.length) {
+      if (nextIndex < current.queue.length) {
         setPhase({ ...current, currentIndex: nextIndex, resolutions: next });
         return;
       }
@@ -480,6 +584,7 @@ export function useAdoptMachine(input: UseAdoptMachineInput): UseAdoptMachineOut
     onWizardComplete,
     onWizardCancel,
     onWizardError,
+    onModeSelect,
     onDiffChoice,
   };
 }
diff --git a/source/components/AdoptModePicker.tsx b/source/components/AdoptModePicker.tsx
new file mode 100644
index 0000000..57a3cf4
--- /dev/null
+++ b/source/components/AdoptModePicker.tsx
@@ -0,0 +1,75 @@
+import { useRef } from 'react';
+import { Box, Text } from 'ink';
+import { Select } from './ui.js';
+
+/**
+ * Batch resolution mode for the `differs` set (#120). `keep-all-mine` /
+ * `use-all-theirs` resolve every file one way; `auto-merge` two-way-unions
+ * the non-conflicting files and prompts on the rest; `decide-per-file` is the
+ * per-file prompt loop. Selected via `--mode` or this picker. Defined here
+ * (component-owned) so the command machine imports it the same way it imports
+ * `AdoptDiffAction` / `WizardResult` — components never import from commands.
+ */
+export type AdoptMode =
+  | 'keep-all-mine'
+  | 'use-all-theirs'
+  | 'auto-merge'
+  | 'decide-per-file';
+
+interface AdoptModePickerProps {
+  /** Number of files that differ from the shard (drives the header count). */
+  differsCount: number;
+  onSelect: (mode: AdoptMode) => void;
+}
+
+const MODE_VALUES = new Set<AdoptMode>([
+  'keep-all-mine',
+  'use-all-theirs',
+  'auto-merge',
+  'decide-per-file',
+]);
+
+/**
+ * Top-level batch resolution picker shown once before the per-file diff loop
+ * (#120). Deciding individually across dozens of divergent files is poor UX;
+ * this lets the user resolve them all at once, with per-file prompting kept
+ * as a mode.
+ *
+ * The auto-merge label is deliberately honest: it is a best-effort two-way
+ * union merge (no merge base exists for adopt), so it keeps the user's bytes,
+ * does NOT apply shard deletions, and can duplicate non-adjacent edits — the
+ * user should review merged files. See `core/adopt-merge.ts`.
+ */
+export default function AdoptModePicker({ differsCount, onSelect }: AdoptModePickerProps) {
+  // `Select` can fire onChange more than once if Ink re-focuses the instance
+  // (see CollisionReview / DiffView). One-shot decision → guard it.
+  const firedRef = useRef(false);
+
+  return (
+    <Box flexDirection="column" gap={1}>
+      <Text bold color="yellow">
+        {differsCount} file{differsCount === 1 ? '' : 's'} differ from the shard.
+      </Text>
+      <Text>How should I resolve them?</Text>
+
+      <Select
+        options={[
+          { label: 'Keep all mine — record every divergent file as my version', value: 'keep-all-mine' },
+          { label: 'Use all theirs — overwrite every divergent file with the shard version', value: 'use-all-theirs' },
+          {
+            label:
+              'Auto-merge (best-effort) — keep both sides where they don’t overlap, prompt on conflicts; review merged files after',
+            value: 'auto-merge',
+          },
+          { label: 'Decide per file', value: 'decide-per-file' },
+        ]}
+        onChange={(v) => {
+          if (firedRef.current) return;
+          if (!MODE_VALUES.has(v as AdoptMode)) return;
+          firedRef.current = true;
+          onSelect(v as AdoptMode);
+        }}
+      />
+    </Box>
+  );
+}
diff --git a/source/components/AdoptSummary.tsx b/source/components/AdoptSummary.tsx
index 09d1143..2972157 100644
--- a/source/components/AdoptSummary.tsx
+++ b/source/components/AdoptSummary.tsx
@@ -14,6 +14,7 @@ import type { AdoptSummary as AdoptSummaryData } from '../core/adopt-executor.js
  *   - matched-auto       (byte-equivalent → managed silently)
  *   - adopted as managed (use_shard decisions; user file overwritten)
  *   - kept as managed    (keep_mine decisions; user bytes recorded)
+ *   - auto-merged        (#120 auto-merge mode; union bytes written)
  *   - installed fresh    (shard-only paths; new bytes written)
  *
  * Counts add up to `state.files` length so the user has a precise sense
@@ -74,6 +75,13 @@ export default function AdoptSummary({
             {summary.adoptedShard.length} switched to the shard's version
           </Text>
         )}
+        {summary.adoptedMerged.length > 0 && (
+          <Text>
+            <Text color="magenta">  ⊕ </Text>
+            {summary.adoptedMerged.length} auto-merged (best-effort —{' '}
+            <Text bold>review recommended</Text>)
+          </Text>
+        )}
         {summary.installedFresh.length > 0 && (
           <Text>
             <Text color="blue">  + </Text>
diff --git a/tests/component/AdoptModePicker.test.tsx b/tests/component/AdoptModePicker.test.tsx
new file mode 100644
index 0000000..956001d
--- /dev/null
+++ b/tests/component/AdoptModePicker.test.tsx
@@ -0,0 +1,76 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup } from 'ink-testing-library';
+import React from 'react';
+import AdoptModePicker from '../../source/components/AdoptModePicker.js';
+import { ENTER, ARROW_DOWN, tick, waitFor, waitForCall } from './helpers.js';
+
+afterEach(() => {
+  cleanup();
+});
+
+async function mount(node: React.ReactElement) {
+  const r = render(node);
+  await tick(30);
+  return r;
+}
+
+describe('AdoptModePicker', () => {
+  it('shows the differ count and the four modes', async () => {
+    const { lastFrame } = await mount(
+      <AdoptModePicker differsCount={7} onSelect={vi.fn()} />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('Keep all mine'));
+    const frame = lastFrame() ?? '';
+    expect(frame).toMatch(/7 files differ/);
+    expect(frame).toContain('Use all theirs');
+    expect(frame).toMatch(/Auto-merge \(best-effort\)/);
+    expect(frame).toContain('Decide per file');
+  });
+
+  it('singularizes the count for one file', async () => {
+    const { lastFrame } = await mount(
+      <AdoptModePicker differsCount={1} onSelect={vi.fn()} />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('Keep all mine'));
+    expect(lastFrame() ?? '').toMatch(/1 file differ(?!s)/);
+  });
+
+  it('ENTER on the focused option selects keep-all-mine', async () => {
+    const onSelect = vi.fn();
+    const { stdin, lastFrame } = await mount(
+      <AdoptModePicker differsCount={3} onSelect={onSelect} />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('Keep all mine'));
+    stdin.write(ENTER);
+    await waitForCall(onSelect);
+    expect(onSelect).toHaveBeenCalledWith('keep-all-mine');
+  });
+
+  it('arrowing to the third option selects auto-merge', async () => {
+    const onSelect = vi.fn();
+    const { stdin, lastFrame } = await mount(
+      <AdoptModePicker differsCount={3} onSelect={onSelect} />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('Auto-merge'));
+    stdin.write(ARROW_DOWN);
+    await tick(40);
+    stdin.write(ARROW_DOWN);
+    await tick(40);
+    stdin.write(ENTER);
+    await waitForCall(onSelect);
+    expect(onSelect).toHaveBeenCalledWith('auto-merge');
+  });
+
+  it('double ENTER selects exactly once (firedRef guard)', async () => {
+    const onSelect = vi.fn();
+    const { stdin, lastFrame } = await mount(
+      <AdoptModePicker differsCount={3} onSelect={onSelect} />,
+    );
+    await waitFor(lastFrame, (f) => f.includes('Keep all mine'));
+    stdin.write(ENTER);
+    await waitForCall(onSelect);
+    stdin.write(ENTER);
+    await tick(60);
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/tests/component/AdoptSummary.test.tsx b/tests/component/AdoptSummary.test.tsx
index 3b20a46..3e5425f 100644
--- a/tests/component/AdoptSummary.test.tsx
+++ b/tests/component/AdoptSummary.test.tsx
@@ -23,6 +23,7 @@ function makeSummary(overrides: Partial<AdoptSummaryData> = {}): AdoptSummaryDat
     matchedAuto: ['CLAUDE.md', 'README.md'],
     adoptedMine: [],
     adoptedShard: [],
+    adoptedMerged: [],
     installedFresh: [],
     totalManaged: 2,
     ...overrides,
@@ -74,6 +75,17 @@ describe('AdoptSummary', () => {
     expect(frame).toContain('1 installed fresh');
   });
 
+  it('renders the auto-merged bucket with a review-recommended note (#120)', () => {
+    const summary = makeSummary({
+      adoptedMerged: ['notes/a.md', 'notes/b.md'],
+      totalManaged: 4,
+    });
+    const { lastFrame } = render(<AdoptSummary {...baseProps} summary={summary} />);
+    const frame = lastFrame() ?? '';
+    expect(frame).toMatch(/2 auto-merged/);
+    expect(frame).toMatch(/review recommended/i);
+  });
+
   it('omits zero-count rows', () => {
     const summary = makeSummary({
       matchedAuto: ['a.md'],
diff --git a/tests/component/flows/adopt-flow.test.tsx b/tests/component/flows/adopt-flow.test.tsx
index f3a10c3..85b5a59 100644
--- a/tests/component/flows/adopt-flow.test.tsx
+++ b/tests/component/flows/adopt-flow.test.tsx
@@ -68,6 +68,29 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-26)',
     r.stdin.write(ENTER);
   }
 
+  /**
+   * Drive the `AdoptModePicker` (#120) shown when there are differing files
+   * and no `--mode`/`--yes`: wait for it, then arrow to the requested mode
+   * (Keep all mine / Use all theirs / Auto-merge / Decide per file) and ENTER.
+   */
+  async function pickMode(
+    r: ReturnType<typeof mountAdopt>,
+    mode: 'keep-all-mine' | 'use-all-theirs' | 'auto-merge' | 'decide-per-file',
+  ): Promise<void> {
+    await waitFor(r.lastFrame, (f) => /files? differ from the shard/.test(f), 20_000);
+    const downs = {
+      'keep-all-mine': 0,
+      'use-all-theirs': 1,
+      'auto-merge': 2,
+      'decide-per-file': 3,
+    }[mode];
+    for (let i = 0; i < downs; i++) {
+      r.stdin.write(ARROW_DOWN);
+      await tick(40);
+    }
+    r.stdin.write(ENTER);
+  }
+
   // ───── Scenario 19: empty vault → all shard-only → Summary ─────
 
   it('19. empty vault → adopt → all shard-only → Summary', async () => {
@@ -124,6 +147,8 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-26)',
         vaultRoot: vault,
       });
       await driveAdoptConfirm(r);
+      // Three files differ → mode picker; choose per-file to reach the loop.
+      await pickMode(r, 'decide-per-file');
       // Walk three AdoptDiffView prompts via the shared iteration
       // helper. ENTER on default option = "Keep mine". The #109
       // regression would manifest as iteration 2 timing out on
@@ -152,6 +177,8 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-26)',
         vaultRoot: vault,
       });
       await driveAdoptConfirm(r);
+      // One file differs → mode picker; choose per-file to reach the prompt.
+      await pickMode(r, 'decide-per-file');
       await waitFor(r.lastFrame, (f) => /\(1 of 1\)/.test(f), 20_000);
       // ARROW_DOWN + ENTER → use_shard.
       r.stdin.write(ARROW_DOWN);
@@ -340,6 +367,117 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-26)',
       await cleanupVault(vault);
     }
   }, 45_000);
+
+  // ───── Scenario 27: mode picker → Keep all mine → no prompts, all kept (#120) ─────
+
+  it('27. mode picker → Keep all mine → all divergent files kept, no per-file prompts', async () => {
+    const { stub, fixtures } = getCtx();
+    stub.setRef(SHARD_SLUG, 'v0.1.0', STUB_SHA, fixtures.byVersion['0.1.0']!);
+    const vault = await makeVaultDir('s27-keep-all');
+    try {
+      await writeRel(vault, 'Home.md', '# my Home\nkeep me\n');
+      await writeRel(vault, 'brain/North Star.md', '# my NS\nkeep me too\n');
+      const r = mountAdopt({ shardRef: `${SHARD_REF}#v0.1.0`, vaultRoot: vault });
+      await driveAdoptConfirm(r);
+      await pickMode(r, 'keep-all-mine');
+      const frame = await waitFor(
+        r.lastFrame,
+        (f) => /Adopted shardmind\/minimal/.test(f),
+        30_000,
+      );
+      expect(frame).toMatch(/kept your version/);
+      // Both user files survive byte-for-byte.
+      expect(await fs.readFile(path.join(vault, 'Home.md'), 'utf-8')).toContain('keep me');
+      expect(
+        await fs.readFile(path.join(vault, 'brain/North Star.md'), 'utf-8'),
+      ).toContain('keep me too');
+    } finally {
+      await cleanupVault(vault);
+    }
+  }, 60_000);
+
+  // ───── Scenario 28: mode picker → Use all theirs → all overwritten (#120) ─────
+
+  it('28. mode picker → Use all theirs → divergent files overwritten with shard bytes', async () => {
+    const { stub, fixtures } = getCtx();
+    stub.setRef(SHARD_SLUG, 'v0.1.0', STUB_SHA, fixtures.byVersion['0.1.0']!);
+    const vault = await makeVaultDir('s28-use-all');
+    try {
+      await writeRel(vault, 'Home.md', 'my pre-existing Home\n');
+      const r = mountAdopt({ shardRef: `${SHARD_REF}#v0.1.0`, vaultRoot: vault });
+      await driveAdoptConfirm(r);
+      await pickMode(r, 'use-all-theirs');
+      const frame = await waitFor(
+        r.lastFrame,
+        (f) => /Adopted shardmind\/minimal/.test(f),
+        30_000,
+      );
+      expect(frame).toMatch(/switched to the shard/);
+      expect(await fs.readFile(path.join(vault, 'Home.md'), 'utf-8')).not.toContain(
+        'my pre-existing Home',
+      );
+    } finally {
+      await cleanupVault(vault);
+    }
+  }, 60_000);
+
+  // ───── Scenario 29: mode picker → Auto-merge → non-conflict auto, conflict prompts (#120) ─────
+
+  it('29. Auto-merge → non-conflicting file auto-resolved, conflicting file prompts', async () => {
+    const { stub, fixtures } = getCtx();
+    stub.setRef(SHARD_SLUG, 'v0.1.0', STUB_SHA, fixtures.byVersion['0.1.0']!);
+    const vault = await makeVaultDir('s29-auto-merge');
+    try {
+      // Empty user file → pure insertion vs the rendered shard → union merge
+      // with no conflict (auto-resolved, no prompt).
+      await writeRel(vault, 'Home.md', '');
+      // Wholly different content → a replaced span → conflict → prompts.
+      await writeRel(vault, 'brain/North Star.md', '# totally different\nxyz\n');
+      const r = mountAdopt({ shardRef: `${SHARD_REF}#v0.1.0`, vaultRoot: vault });
+      await driveAdoptConfirm(r);
+      await pickMode(r, 'auto-merge');
+      // Only the conflicting file enters the prompt loop.
+      await waitFor(r.lastFrame, (f) => /\(1 of 1\)/.test(f), 20_000);
+      r.stdin.write(ENTER); // keep mine on the conflict
+      const frame = await waitFor(
+        r.lastFrame,
+        (f) => /Adopted shardmind\/minimal/.test(f),
+        30_000,
+      );
+      expect(frame).toMatch(/auto-merged/);
+      // The empty Home.md was union-merged to the shard's rendered bytes.
+      const home = await fs.readFile(path.join(vault, 'Home.md'), 'utf-8');
+      expect(home.length).toBeGreaterThan(0);
+    } finally {
+      await cleanupVault(vault);
+    }
+  }, 60_000);
+
+  // ───── Scenario 30: --mode (non-interactive) overrides --yes, no picker (#120) ─────
+
+  it('30. --yes --mode=use-all-theirs → non-interactive, no picker, files overwritten', async () => {
+    const { stub, fixtures } = getCtx();
+    stub.setRef(SHARD_SLUG, 'v0.1.0', STUB_SHA, fixtures.byVersion['0.1.0']!);
+    const vault = await makeVaultDir('s30-mode-flag');
+    try {
+      await writeRel(vault, 'Home.md', 'my pre-existing Home\n');
+      const valuesFile = path.join(vault, 'values.yaml');
+      await fs.writeFile(valuesFile, stringifyYaml(DEFAULT_VALUES), 'utf-8');
+      const r = mountAdopt({
+        shardRef: `${SHARD_REF}#v0.1.0`,
+        vaultRoot: vault,
+        options: { yes: true, values: valuesFile, mode: 'use-all-theirs' },
+      });
+      // No picker, no value gate — fully non-interactive. --mode overrides
+      // --yes's default of keep-all-mine, so Home.md is overwritten.
+      await waitFor(r.lastFrame, (f) => /Adopted shardmind\/minimal/.test(f), 30_000);
+      expect(await fs.readFile(path.join(vault, 'Home.md'), 'utf-8')).not.toContain(
+        'my pre-existing Home',
+      );
+    } finally {
+      await cleanupVault(vault);
+    }
+  }, 60_000);
 });
 
 async function writeRel(vault: string, rel: string, content: string): Promise<void> {
diff --git a/tests/component/flows/helpers.tsx b/tests/component/flows/helpers.tsx
index 840fece..33cfa8d 100644
--- a/tests/component/flows/helpers.tsx
+++ b/tests/component/flows/helpers.tsx
@@ -256,6 +256,7 @@ export function mountUpdate(opts: {
 export interface AdoptOptions {
   values?: string;
   yes?: boolean;
+  mode?: 'keep-all-mine' | 'use-all-theirs' | 'auto-merge' | 'decide-per-file';
   verbose?: boolean;
   dryRun?: boolean;
   noUpdateCheck?: boolean;
diff --git a/tests/e2e/tui/adopt-diff.test.ts b/tests/e2e/tui/adopt-diff.test.ts
index 6fbb41f..8fbd9ab 100644
--- a/tests/e2e/tui/adopt-diff.test.ts
+++ b/tests/e2e/tui/adopt-diff.test.ts
@@ -27,6 +27,7 @@ import { ensureBuilt } from '../helpers/build-once.js';
 import {
   spawnCliPty,
   ENTER,
+  ARROW_DOWN,
   PTY_VIEWPORT_ROWS,
 } from './helpers/pty-cli.js';
 import { tick } from '../../component/helpers.js';
@@ -121,6 +122,19 @@ describe.skipIf(skipOnWindows)(
             });
             handle.write(ENTER);
 
+            // Three files differ → the AdoptModePicker (#120) appears.
+            // Choose "Decide per file" (4th option) to reach the per-file
+            // loop this scenario exercises.
+            await handle.waitForScreen((s) => /files differ from the shard/.test(s), {
+              timeoutMs: 30_000,
+              description: 'adopt mode picker',
+            });
+            for (let i = 0; i < 3; i++) {
+              handle.write(ARROW_DOWN);
+              await tick(120);
+            }
+            handle.write(ENTER);
+
             // Walk three sequential AdoptDiffView prompts. ENTER
             // alone selects "Keep mine" (first option). The #109
             // fingerprint: iteration 2's `(2 of 3)` counter must

From fb83ca8eaca644cf0a1df1690dcdf5b715e3800f Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Mon, 1 Jun 2026 23:08:40 +0200
Subject: [PATCH 4/8] docs(adopt): document the batch mode picker + best-effort
 auto-merge (#120)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ARCHITECTURE §10.5: new mode-select step (3a) + the four modes; flags
  table gains --mode; a plain-spoken note that auto-merge is a best-effort
  two-way union merge (no base) that keeps user bytes, does NOT apply shard
  deletions, and can duplicate non-adjacent edits. Apply step snapshots
  differs+merged too; implementation-modules line gains adopt-merge +
  AdoptModePicker.
- AUTHORING: adopt description mentions the batch modes + --mode.
- CHANGELOG: [Unreleased] Added entry.
- CLAUDE.md: AdoptModePicker.tsx + adopt-merge.ts in the trees + module table.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md         | 12 ++++++++++++
 CLAUDE.md            |  3 +++
 docs/ARCHITECTURE.md | 13 +++++++++----
 docs/AUTHORING.md    |  2 +-
 4 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6e95c11..fbabfe1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,18 @@ Between releases: see `git log` for merged work and [`ROADMAP.md`](ROADMAP.md) f
 
 ## [Unreleased]
 
+### Added (adopt batch operations — #120)
+
+Closes [#120](https://github.com/breferrari/shardmind/issues/120). `shardmind adopt` against a divergent vault asked for a decision on *every* differing file (the flagship obsidian-mind run had 35). A top-level mode picker now resolves the whole set at once, with per-file prompting kept as a mode.
+
+- **Mode picker** (`source/components/AdoptModePicker.tsx`) shown once before the per-file loop when files differ and neither `--mode` nor `--yes` is set: **Keep all mine** / **Use all theirs** / **Auto-merge (best-effort)** / **Decide per file**. A `--mode=keep-all-mine|use-all-theirs|auto-merge|decide-per-file` flag drives it non-interactively (overrides `--yes`, which is now shorthand for keep-all-mine).
+
+- **Auto-merge is a best-effort two-way *union* merge** (`source/core/adopt-merge.ts`), not a three-way merge: adopt has no merge base (the vault was cloned without shardmind), so a base-anchored merge is impossible. It keeps common lines, unions each side's unique lines, and sends files where both sides replaced the same span to the per-file prompt. **Its limits are surfaced, not hidden:** it keeps the user's bytes so it **does not apply shard deletions**, and can duplicate non-adjacent edits. Merged files are written as `modified` ownership and flagged **"review recommended"** in the Summary. Non-interactive auto-merge keeps-mine on conflicts.
+
+- **Executor** gains a `{ kind:'merged', content, hash }` resolution (`adopt-executor.ts`): writes the union bytes, records `modified` ownership at the merged hash, snapshots merged paths for rollback, and buckets them in `summary.adoptedMerged`. A subsequent `update` three-way-merges the result against the cached shard template (the proper base). The machine's `diff-review` phase now iterates a `queue` (only the files needing a prompt) with pre-seeded resolutions, so per-file and auto-merge share one loop.
+
+- **Tests**: `adopt-merge` unit matrix + determinism/union properties (fast-check); executor merged-resolution integration test; `AdoptModePicker` component test (modes + firedRef guard); Layer 1 flow scenarios 27-30 (keep-all / use-all / auto-merge mixed conflict / `--mode` non-interactive); Layer 2 PTY scenario picks decide-per-file; `AdoptSummary` merged-bucket test. **Docs**: `docs/ARCHITECTURE.md §10.5` (modes + best-effort note), `docs/AUTHORING.md`, `CLAUDE.md`.
+
 ### Changed (hook lifecycle split — #102) — **breaking, shard-author-facing**
 
 Part of [#102](https://github.com/breferrari/shardmind/issues/102) (the engine + fixture + docs; the issue stays open until the release-window items below land). Splits the single `post-install` hook into three named slots with engine-enforced contracts, turning yesterday's comment-checked conventions into machine-checked signals. Ships in the same release as [#121](https://github.com/breferrari/shardmind/issues/121) (engine version-compatibility check), which is the guard that stops a pre-0.2 engine from silently ignoring the new slots; obsidian-mind's hook migration ([`obsidian-mind#75`](https://github.com/breferrari/obsidian-mind/issues/75)) ships in the same window.
diff --git a/CLAUDE.md b/CLAUDE.md
index 42fb2cf..735879b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -146,6 +146,7 @@ shardmind/
 │   │   ├── ExistingInstallGate.tsx    # Install: existing-install disambiguation
 │   │   ├── DiffView.tsx               # Three-way diff + conflict resolution
 │   │   ├── AdoptValuesGate.tsx        # Adopt: values confirm-or-override page (#104)
+│   │   ├── AdoptModePicker.tsx        # Adopt: batch mode picker (keep-all / use-all / auto-merge / per-file) (#120)
 │   │   ├── AdoptDiffView.tsx          # Adopt: 2-way diff (no merge base) + per-file prompt
 │   │   ├── AdoptSummary.tsx           # Final adopt report (matched / mine / shard / fresh)
 │   │   ├── NewValuesPrompt.tsx        # Update: prompt for newly required values
@@ -180,6 +181,7 @@ shardmind/
 │   │   ├── install-executor.ts        # Apply install plan with rollback
 │   │   ├── adopt-planner.ts           # Classify user vault vs shard (matches/differs/shard-only)
 │   │   ├── adopt-executor.ts          # Apply adopt plan with snapshot-rollback
+│   │   ├── adopt-merge.ts             # Two-way union merge for adopt --mode=auto-merge (#120)
 │   │   ├── values-io.ts               # Shared YAML load for shard-values.yaml
 │   │   ├── values-defaults.ts         # `valuesAreDefaults(values, schema)` — Invariant 2 helper
 │   │   ├── update-check.ts            # 24h cached latest-version lookup (status + update)
@@ -338,6 +340,7 @@ Each file in `source/core/` maps 1:1 to a section in `docs/IMPLEMENTATION.md`:
 | `update-executor.ts` | §4.12 | Apply update plan with snapshot-based rollback |
 | `adopt-planner.ts` | §4.17 | Classify user vault vs shard outputs (matches / differs / shard-only) |
 | `adopt-executor.ts` | §4.18 | Apply adopt plan with snapshot-based rollback |
+| `adopt-merge.ts` | SHARD-LAYOUT.md §Adopt semantics | Two-way union merge for `adopt --mode=auto-merge` (#120) |
 | `values-io.ts` | §4.13 | Shared YAML load for shard-values.yaml (install + update) |
 | `values-defaults.ts` | §4.16 (HookContext extensions) | `valuesAreDefaults(values, schema)` — deep-equal pure fn for Invariant 2 |
 | `status.ts` | §4.14 | Pure StatusReport builder for the `shardmind` (status) command |
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 1b419d5..307873a 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -875,15 +875,20 @@ Phase ordering (logical; UI may interleave loading messages — see IMPLEMENTATI
 2. **Values gate** (`source/components/AdoptValuesGate.tsx`, #104) — adopt's user already has a populated vault, so it opens on a single confirm page that surfaces the values that will drive classification (resolved defaults, computed defaults, `--values` prefill, each labelled with its provenance) plus the module default, with **Use these values / Override individually / Cancel**. "Override individually" drops into the same `InstallWizard` install uses (per-value + module editing). Required values with no default and no prefill open straight into the wizard (no confident set to confirm). This step runs **before** classification because `.njk` templates need values to render before their output bytes can be hashed.
 3. **Classify** (`source/core/adopt-planner.ts::classifyAdoption`) — for every shard output, render or read, hash, stat the user's vault, and assign one of four buckets:
    - **matches** — byte-identical post-render → managed silently.
-   - **differs** — bytes differ → 2-way diff prompt (`AdoptDiffView`); user picks `keep_mine` (record user's hash, ownership=`modified`) or `use_shard` (overwrite with shard bytes, ownership=`managed`).
+   - **differs** — bytes differ → resolved per the chosen batch mode (below); `keep_mine` records the user's hash (ownership=`modified`), `use_shard` overwrites with shard bytes (ownership=`managed`), `merged` writes union bytes (ownership=`modified`).
    - **shard-only** — user doesn't have the path → install fresh, managed.
    - Implicit **user-only** — paths in vault but not in shard → never enumerated, left untouched.
-4. **Apply** (`source/core/adopt-executor.ts::runAdopt`) — snapshot any `differs+use_shard` user file before overwriting, write shard-only fresh installs, write engine metadata (`state.json`, cached manifest+schema, templates cache, vault-root `shard-values.yaml`). Snapshot-then-restore rollback on any failure between snapshot and final state-write.
+3a. **Mode select** (`source/components/AdoptModePicker.tsx`, #120) — when there is at least one `differs` file and neither `--mode` nor `--yes` is set, adopt prompts once for how to resolve the whole set rather than file-by-file. Four modes:
+   - **Keep all mine** / **Use all theirs** — resolve every `differs` one way.
+   - **Auto-merge (best-effort)** — two-way-union each file (`source/core/adopt-merge.ts`): non-conflicting files resolve to their merged bytes; files where both sides replaced the same span fall through to the per-file prompt. **This is a union merge with no merge base** (adopt has no record of the original shard version): it keeps the user's bytes, **does not apply shard deletions**, and can duplicate non-adjacent edits — merged files are flagged "review recommended" in the Summary. Non-interactive auto-merge (`--mode=auto-merge` under `--yes`) keeps-mine on conflicts.
+   - **Decide per file** — the per-file `AdoptDiffView` prompt (`keep_mine` / `use_shard`).
+4. **Apply** (`source/core/adopt-executor.ts::runAdopt`) — snapshot any user file an apply will overwrite (`differs+use_shard` and `differs+merged`), write shard-only fresh installs, write engine metadata (`state.json`, cached manifest+schema, templates cache, vault-root `shard-values.yaml`). Snapshot-then-restore rollback on any failure between snapshot and final state-write.
 5. **Hooks** — run the install-side slots via the orchestrator: `bootstrap` (unmanaged setup), then `personalize` (managed edits) unless `valuesAreDefaults` (engine-skipped, Invariant 2). `newFiles=summary.installedFresh`. Non-fatal (Helm semantics, §9.3).
 6. **Re-hash** — recompute managed-file hashes per `state.ts::rehashManagedFiles` so any hook edits to managed paths land in the recorded state.
 
 Flags:
-- `--yes` — skip the values gate + auto-pick `keep_mine` on every `differs`. Preserves the user's bytes on every divergence; safe default for retroactive adoption.
+- `--yes` — skip the values gate + the mode picker; resolve every `differs` as `keep_mine` (shorthand for `--mode=keep-all-mine`). Preserves the user's bytes on every divergence; safe default for retroactive adoption.
+- `--mode <keep-all-mine|use-all-theirs|auto-merge|decide-per-file>` (#120) — resolve the `differs` set non-interactively without the picker. Overrides `--yes`'s default. Combine with `--yes`/`--values` for a fully non-interactive run (the flag governs the diff set, not value collection).
 - `--values <file>` — prefill value answers (same shape as `install --values`); shown on the gate's confirm page as `(from --values)`.
 - `--verbose` — show per-file action history during the apply phase.
 - `--dry-run` — run the full pipeline (fetch, values gate, classify) without touching the vault. Summary reports what *would* happen.
@@ -892,7 +897,7 @@ Volatile templates (`{# shardmind: volatile #}`) skip the differs prompt entirel
 
 Excluded modules' files in the user's vault are not classified — adopt mirrors install's "module excluded → file not installed" rule, so user content at those paths stays user-content without any prompt.
 
-Implementation modules: `source/core/adopt-planner.ts` (IMPLEMENTATION §4.17), `source/core/adopt-executor.ts` (§4.18). Orchestration lives in `source/commands/hooks/use-adopt-machine.ts`; UI components are `source/components/AdoptValuesGate.tsx` (values confirm-or-override), `source/components/AdoptDiffView.tsx` + `source/components/AdoptSummary.tsx`.
+Implementation modules: `source/core/adopt-planner.ts` (IMPLEMENTATION §4.17), `source/core/adopt-executor.ts` (§4.18), `source/core/adopt-merge.ts` (two-way union merge for auto-merge mode). Orchestration lives in `source/commands/hooks/use-adopt-machine.ts`; UI components are `source/components/AdoptValuesGate.tsx` (values confirm-or-override), `source/components/AdoptModePicker.tsx` (batch mode picker), `source/components/AdoptDiffView.tsx` + `source/components/AdoptSummary.tsx`.
 
 ### 10.6 Install Location
 
diff --git a/docs/AUTHORING.md b/docs/AUTHORING.md
index c3d49ea..8994b87 100644
--- a/docs/AUTHORING.md
+++ b/docs/AUTHORING.md
@@ -15,7 +15,7 @@ A shard ships:
 
 Users run `shardmind install <namespace>/<shard>`. The engine downloads the tarball, walks the shard root applying Tier 1 exclusions + `.shardmindignore` + symlink rejection, prompts for values, lets the user opt out of removable modules, renders + copies + caches, writes `state.json`, and runs your hook. Users never edit your shard directly — they edit their vault, and the next `shardmind update` merges upstream changes into their customizations via three-way merge.
 
-A user who already cloned your repo (typically before shardmind support existed) can run `shardmind adopt <namespace>/<shard>` instead. Adopt walks the existing vault, classifies each shard-output path against what the install would have produced, and asks the user — for any file that differs — whether to keep their version (recorded as `ownership: 'modified'`) or accept the shard's. Files matching exactly are auto-managed; files only the shard ships are installed fresh. After adopt, `shardmind update` works normally — the cache made at adopt time becomes the merge base. See `docs/SHARD-LAYOUT.md §Adopt semantics` for the full contract.
+A user who already cloned your repo (typically before shardmind support existed) can run `shardmind adopt <namespace>/<shard>` instead. Adopt walks the existing vault, classifies each shard-output path against what the install would have produced, and — for any file that differs — lets the user resolve the whole set at once (keep all mine / use all theirs / best-effort auto-merge / decide per file, or the `--mode` flag) before recording each file's `ownership` (`modified` for kept/merged, `managed` for use-shard). Files matching exactly are auto-managed; files only the shard ships are installed fresh. After adopt, `shardmind update` works normally — the cache made at adopt time becomes the merge base. See `docs/SHARD-LAYOUT.md §Adopt semantics` for the full contract.
 
 ## 2. File layout
 

From 6b1ae4dec33455228f0b2332a03a84bf533bc197 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Mon, 1 Jun 2026 23:11:57 +0200
Subject: [PATCH 5/8] =?UTF-8?q?refactor(adopt):=20simplify=20pass=20?=
 =?UTF-8?q?=E2=80=94=20applyMode=20dedup=20(#120)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/simplify findings (efficiency clean; altitude confirmed the union shape,
queue refactor, AdoptMode ownership, and --mode/--yes modeling are right):
- keep-all-mine/use-all-theirs build resolutions via Object.fromEntries
  instead of an explicit loop.
- Extract a local enterDiffReview() to dedup the two diff-review setPhase
  calls (decide-per-file + auto-merge interactive).
- Document the coupling between pickMode's arrow-count map and the picker's
  option order.

Skipped (noted): formatSize duplication (CollisionReview/AdoptDiffView) is
pre-existing and out of this diff's scope; the diff-review phase's `plan`
field is consumed by executeAdopt, not dead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 source/commands/hooks/use-adopt-machine.ts | 35 +++++++++-------------
 tests/component/flows/adopt-flow.test.tsx  |  2 ++
 2 files changed, 16 insertions(+), 21 deletions(-)

diff --git a/source/commands/hooks/use-adopt-machine.ts b/source/commands/hooks/use-adopt-machine.ts
index 296c972..b5e7734 100644
--- a/source/commands/hooks/use-adopt-machine.ts
+++ b/source/commands/hooks/use-adopt-machine.ts
@@ -463,25 +463,26 @@ export function useAdoptMachine(input: UseAdoptMachineInput): UseAdoptMachineOut
       plan: AdoptPlan,
       interactive: boolean,
     ) => {
+      const enterDiffReview = (
+        queue: AdoptClassification[],
+        resolutions: AdoptResolutions,
+      ) =>
+        setPhase({ kind: 'diff-review', ctx, result, plan, queue, currentIndex: 0, resolutions });
+
       try {
         if (selected === 'keep-all-mine' || selected === 'use-all-theirs') {
           const decision = selected === 'keep-all-mine' ? 'keep_mine' : 'use_shard';
-          const resolutions: AdoptResolutions = {};
-          for (const c of plan.differs) resolutions[c.path] = decision;
-          await executeAdopt(ctx, result, plan, resolutions);
+          await executeAdopt(
+            ctx,
+            result,
+            plan,
+            Object.fromEntries(plan.differs.map((c) => [c.path, decision])),
+          );
           return;
         }
 
         if (selected === 'decide-per-file') {
-          setPhase({
-            kind: 'diff-review',
-            ctx,
-            result,
-            plan,
-            queue: plan.differs,
-            currentIndex: 0,
-            resolutions: {},
-          });
+          enterDiffReview(plan.differs, {});
           return;
         }
 
@@ -509,15 +510,7 @@ export function useAdoptMachine(input: UseAdoptMachineInput): UseAdoptMachineOut
         }
 
         if (interactive) {
-          setPhase({
-            kind: 'diff-review',
-            ctx,
-            result,
-            plan,
-            queue,
-            currentIndex: 0,
-            resolutions,
-          });
+          enterDiffReview(queue, resolutions);
           return;
         }
 
diff --git a/tests/component/flows/adopt-flow.test.tsx b/tests/component/flows/adopt-flow.test.tsx
index 85b5a59..3843f27 100644
--- a/tests/component/flows/adopt-flow.test.tsx
+++ b/tests/component/flows/adopt-flow.test.tsx
@@ -78,6 +78,8 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-26)',
     mode: 'keep-all-mine' | 'use-all-theirs' | 'auto-merge' | 'decide-per-file',
   ): Promise<void> {
     await waitFor(r.lastFrame, (f) => /files? differ from the shard/.test(f), 20_000);
+    // Arrow counts must match AdoptModePicker.tsx's option order
+    // (keep-all-mine, use-all-theirs, auto-merge, decide-per-file).
     const downs = {
       'keep-all-mine': 0,
       'use-all-theirs': 1,

From 85d842da4a5822878ca7f1f3a63549eb3c0f427d Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Mon, 1 Jun 2026 23:21:38 +0200
Subject: [PATCH 6/8] =?UTF-8?q?fix(adopt):=20harden=20round=201=20?=
 =?UTF-8?q?=E2=80=94=20docs=20drift,=20deps=20clarity,=20edge=20coverage?=
 =?UTF-8?q?=20(#120)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/harden round 1 (adversarial + correctness + docs; correctness agent found
the union shape, queue refactor, hash parity, type narrowing, and switch
exhaustiveness all sound):

- Docs drift the agents caught: SHARD-LAYOUT §Adopt still said "two choices,
  no third" and described per-file-only resolution — rewritten for the four
  modes + the three differs outcomes (keep_mine/use_shard/merged) + the
  best-effort auto-merge limits. IMPLEMENTATION §3.5 adopt mermaid gains the
  mode-select + auto-merge nodes (it omitted them). Both also fix a leftover
  #104 "Wizard" reference.
- adopt-executor: the "missing resolution" error message now lists `merged`.
- use-adopt-machine: applyMode deps tightened to [executeAdopt, finish];
  clarifying comments on the two closure-stability eslint-disables.
- Tests: document the conservative trailing-newline-only conflict (diffLines
  aligns it as a replacement; merge never normalizes newlines — pinned so the
  behaviour is explicit); flow scenario 31 covers the untested
  --yes --mode=auto-merge non-interactive fallback (conflict → keep-mine).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/IMPLEMENTATION.md                     | 16 +++++++---
 docs/SHARD-LAYOUT.md                       |  8 ++---
 source/commands/hooks/use-adopt-machine.ts | 10 +++++-
 source/core/adopt-executor.ts              |  2 +-
 source/core/adopt-merge.ts                 |  3 ++
 tests/component/flows/adopt-flow.test.tsx  | 36 ++++++++++++++++++++++
 tests/unit/adopt-merge.test.ts             | 12 ++++++++
 7 files changed, 76 insertions(+), 11 deletions(-)

diff --git a/docs/IMPLEMENTATION.md b/docs/IMPLEMENTATION.md
index d151d1f..8d26005 100644
--- a/docs/IMPLEMENTATION.md
+++ b/docs/IMPLEMENTATION.md
@@ -163,17 +163,23 @@ graph TD
     E["adopt-planner.ts::classifyAdoption<br/>resolveModules walks shard, render or read each output<br/>per-output sha256 vs sha256(user vault path)<br/>→ matches | differs | shard-only buckets"] --> F1
 
     F1{Any<br/>differs?}
-    F1 -->|Yes, --yes| F2["auto-resolve every differs as keep_mine"]
-    F1 -->|Yes, interactive| F3["diff-review loop<br/>AdoptDiffView per file → keep_mine / use_shard"]
+    F1 -->|"Yes, --mode / --yes"| F2["applyMode (non-interactive)<br/>keep-all-mine / use-all-theirs /<br/>auto-merge (conflicts→keep_mine) / —"]
+    F1 -->|Yes, interactive| FM["mode-select — AdoptModePicker (#120)<br/>keep-all-mine · use-all-theirs ·<br/>auto-merge · decide-per-file"]
     F1 -->|No| G
 
+    FM -->|keep-all / use-all| G
+    FM -->|"auto-merge"| FA["adopt-merge.ts::twoWayUnionMerge<br/>non-conflicting → merged bytes<br/>conflicting → queue"]
+    FM -->|decide-per-file| F3
+    FA -->|conflicts| F3
+    FA -->|no conflicts| G
+    F3["diff-review loop (queue)<br/>AdoptDiffView per file → keep_mine / use_shard"] --> G
+
     F2 --> G
-    F3 --> G
 
-    G["adopt-executor.ts::runAdopt<br/>① Snapshot every differs+use_shard user file<br/>② Apply per classification + resolution<br/>③ Cache templates + manifest + schema<br/>④ Write shard-values.yaml + state.json"] --> H
+    G["adopt-executor.ts::runAdopt<br/>① Snapshot every differs+use_shard / differs+merged user file<br/>② Apply per classification + resolution (keep_mine / use_shard / merged)<br/>③ Cache templates + manifest + schema<br/>④ Write shard-values.yaml + state.json"] --> H
 
     H["hooks (orchestrator)<br/>bootstrap → personalize (non-fatal)<br/>newFiles = summary.installedFresh"] --> I
-    I["summary — AdoptSummary<br/>Counts: matched-auto / kept-mine / use-shard / fresh<br/>+ hook output"]
+    I["summary — AdoptSummary<br/>Counts: matched-auto / kept-mine / use-shard / merged / fresh<br/>+ hook output"]
 
     G -->|Any failure| R["rollbackAdopt<br/>Restore snapshot + erase added paths<br/>+ drop .shardmind/ + shard-values.yaml"]
 
diff --git a/docs/SHARD-LAYOUT.md b/docs/SHARD-LAYOUT.md
index e3fcb0b..9911a1f 100644
--- a/docs/SHARD-LAYOUT.md
+++ b/docs/SHARD-LAYOUT.md
@@ -214,22 +214,22 @@ Pre-conditions enforced before any walk:
 
 Phases (logical order; UI may interleave loading messages):
 1. Fetch shard at target version into a temp directory.
-2. Wizard collects values (same component / pipeline as install) and module selections. Wizard runs **before** classification because `.njk` templates need values to render before their output bytes can be hashed.
+2. Collect values via the `AdoptValuesGate` confirm-or-override page (#104) and module selections — same value pipeline as install. Runs **before** classification because `.njk` templates need values to render before their output bytes can be hashed.
 3. Classify each file the shard would install at the chosen module selections, comparing the rendered (or copied) bytes against the user's vault:
    - **Matches shard content exactly** → record hash, mark managed automatically. "Exactly" means byte-for-byte equality after the standard render pipeline (frontmatter normalized via `parseYaml → stringifyYaml`, see `renderer.ts`). A pristine clone with default values + clean YAML lands here for every file; non-default vaults legitimately produce `differs` for any rendered output the user's bytes don't post-render-equal. This is the same equality `drift.ts` enforces on update.
-   - **Differs from shard content** → 2-way diff UI (no merge base); user marks "my modification" (record user's content hash as managed) or "use shard's version" (overwrite, record shard hash as managed). Two choices, no third "leave untracked" — adopt is the moment the file becomes managed; the user can later modify it freely and the merge engine handles it on update.
+   - **Differs from shard content** → resolved per a batch mode (#120). When ≥1 file differs and neither `--mode` nor `--yes` is set, `AdoptModePicker` prompts once for the whole set: **keep all mine** / **use all theirs** / **auto-merge (best-effort)** / **decide per file**. Each `differs` file ends as one of: `keep_mine` (record user's hash, ownership `modified`), `use_shard` (overwrite, ownership `managed`), or `merged` (write union bytes, ownership `modified`). There is no "leave untracked" outcome — adopt is the moment the file becomes managed; the merge engine handles later edits on update. **Auto-merge** is a two-way *union* merge (`core/adopt-merge.ts`): adopt has no merge base, so it keeps common + each side's unique lines, sends overlapping replacements to the per-file prompt, **does not apply shard deletions**, and can duplicate non-adjacent edits — merged files are flagged "review recommended". Non-interactive auto-merge keeps-mine on conflicts.
    - **Volatile templates** (carry `{# shardmind: volatile #}`) skip the prompt: user's bytes are recorded as managed without a differs comparison (volatile content is never expected to match across renders, so a prompt would be meaningless). Symmetric with install, which records volatile-template outputs the same way.
    - **Excluded modules' files** are not classified. If the user's vault contains them, they stay as user content.
    - User has the path but it's not a shard output → user-only, left unmanaged (not in `state.files`).
    - Shard has the path but the user's vault doesn't → shard-only, installed fresh and recorded as managed.
-4. For every `differs` decision, apply: write shard bytes for "use shard's", leave user bytes for "my modification". `keep mine` paths still become `state.files` entries hashed at the user's bytes — adopt is the entry point into management.
+4. For every `differs` decision, apply: write shard bytes for `use_shard`, union bytes for `merged`, leave user bytes for `keep_mine`. All three become `state.files` entries (hashed at the user's / merged / shard bytes respectively) — adopt is the entry point into management.
 5. Write `.shardmind/state.json` + cached `.shardmind/shard.yaml` + cached `.shardmind/shard-schema.yaml` + vault-root `shard-values.yaml`; cache the shard source under `.shardmind/templates/` so future `update` runs have a merge base.
 6. Run the install-side hook slots via the orchestrator: `bootstrap` (always), then `personalize` (managed edits) unless the engine skips it because values are defaults (Invariant 2). `newFiles` = paths classified shard-only and freshly installed, `removedFiles` = [].
 7. Re-hash managed files per the usual post-hook semantics.
 
 Future `shardmind update` calls work normally — merge base is the adopt-time cache.
 
-Reuses: drift detection (`core/drift.ts`), install-executor, value collection (`AdoptValuesGate` confirm page → `InstallWizard` on override, #104), hook runtime. New surfaces: 2-way diff UI component (`AdoptDiffView`), adopt-planner, adopt-executor.
+Reuses: drift detection (`core/drift.ts`), install-executor, value collection (`AdoptValuesGate` confirm page → `InstallWizard` on override, #104), hook runtime. New surfaces: batch mode picker (`AdoptModePicker`, #120), two-way union merge (`core/adopt-merge.ts`, #120), 2-way diff UI component (`AdoptDiffView`), adopt-planner, adopt-executor.
 
 ## Naming decisions
 
diff --git a/source/commands/hooks/use-adopt-machine.ts b/source/commands/hooks/use-adopt-machine.ts
index b5e7734..afe068c 100644
--- a/source/commands/hooks/use-adopt-machine.ts
+++ b/source/commands/hooks/use-adopt-machine.ts
@@ -322,6 +322,10 @@ export function useAdoptMachine(input: UseAdoptMachineInput): UseAdoptMachineOut
         finish({ kind: 'error', error: err as Error });
       }
     },
+    // References `applyMode` + `executeAdopt` via closure (defined below);
+    // both are stable across a session (their own deps — vaultRoot, dryRun,
+    // verbose, finish — are fixed CLI flags / process.cwd), so a captured
+    // binding is never stale. Listing them here would be a TDZ ref.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [vaultRoot, yes, mode, finish],
   );
@@ -523,8 +527,12 @@ export function useAdoptMachine(input: UseAdoptMachineInput): UseAdoptMachineOut
         finish({ kind: 'error', error: err as Error });
       }
     },
+    // `executeAdopt` + `finish` are the only non-stable values applyMode
+    // calls. `setPhase` is a stable useState setter; `twoWayUnionMerge` /
+    // `sha256` are module imports. `ctx`/`result`/`plan` are arguments. The
+    // deps cover the closure; the lint rule can't see callbacks-as-args.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [finish],
+    [executeAdopt, finish],
   );
 
   const onWizardComplete = useCallback(
diff --git a/source/core/adopt-executor.ts b/source/core/adopt-executor.ts
index 62ff8f0..b4384e0 100644
--- a/source/core/adopt-executor.ts
+++ b/source/core/adopt-executor.ts
@@ -293,7 +293,7 @@ export async function runAdopt(opts: AdoptRunnerOptions): Promise<AdoptResult> {
         throw new ShardMindError(
           `Missing adopt resolution for ${c.path}`,
           'ADOPT_WRITE_FAILED',
-          'Every `differs` classification needs a `keep_mine` or `use_shard` decision before runAdopt is called.',
+          'Every `differs` classification needs a `keep_mine` / `use_shard` / `merged` resolution before runAdopt is called.',
         );
       }
       const action: AdoptApplyKind =
diff --git a/source/core/adopt-merge.ts b/source/core/adopt-merge.ts
index e86e0e9..bfffcbb 100644
--- a/source/core/adopt-merge.ts
+++ b/source/core/adopt-merge.ts
@@ -21,6 +21,9 @@
  *     same idea that `diffLines` does not align as one replacement run are
  *     both kept (union), which can duplicate content. Overlapping (adjacent
  *     removed+added) runs are always reported as conflicts, never combined.
+ *   - Newlines are never normalized, so a file that differs only in its
+ *     trailing newline is a conflict (it prompts) — deliberately conservative
+ *     rather than risk masking a real diff.
  *
  * `content` is the union and is only meaningful when `hasConflict === false`;
  * the caller sends conflicting files to the per-file prompt instead.
diff --git a/tests/component/flows/adopt-flow.test.tsx b/tests/component/flows/adopt-flow.test.tsx
index 3843f27..f1ba8ad 100644
--- a/tests/component/flows/adopt-flow.test.tsx
+++ b/tests/component/flows/adopt-flow.test.tsx
@@ -480,6 +480,42 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-26)',
       await cleanupVault(vault);
     }
   }, 60_000);
+
+  // ───── Scenario 31: --yes --mode=auto-merge → non-interactive, conflicts keep-mine (#120) ─────
+
+  it('31. --yes --mode=auto-merge → non-conflicting merged, conflicting falls back to keep-mine', async () => {
+    const { stub, fixtures } = getCtx();
+    stub.setRef(SHARD_SLUG, 'v0.1.0', STUB_SHA, fixtures.byVersion['0.1.0']!);
+    const vault = await makeVaultDir('s31-auto-merge-yes');
+    try {
+      // Empty file → non-conflicting union (auto-merged); divergent file →
+      // conflict. Under --yes (no prompt) the conflict must fall back to
+      // keep-mine, not hang waiting for a decision.
+      await writeRel(vault, 'Home.md', '');
+      await writeRel(vault, 'brain/North Star.md', '# totally different\nxyz\n');
+      const valuesFile = path.join(vault, 'values.yaml');
+      await fs.writeFile(valuesFile, stringifyYaml(DEFAULT_VALUES), 'utf-8');
+      const r = mountAdopt({
+        shardRef: `${SHARD_REF}#v0.1.0`,
+        vaultRoot: vault,
+        options: { yes: true, values: valuesFile, mode: 'auto-merge' },
+      });
+      const frame = await waitFor(
+        r.lastFrame,
+        (f) => /Adopted shardmind\/minimal/.test(f),
+        30_000,
+      );
+      // Home.md auto-merged to the shard bytes; North Star kept (conflict fallback).
+      expect(frame).toMatch(/auto-merged/);
+      expect(frame).toMatch(/kept your version/);
+      expect(await fs.readFile(path.join(vault, 'Home.md'), 'utf-8')).not.toBe('');
+      expect(
+        await fs.readFile(path.join(vault, 'brain/North Star.md'), 'utf-8'),
+      ).toContain('totally different');
+    } finally {
+      await cleanupVault(vault);
+    }
+  }, 60_000);
 });
 
 async function writeRel(vault: string, rel: string, content: string): Promise<void> {
diff --git a/tests/unit/adopt-merge.test.ts b/tests/unit/adopt-merge.test.ts
index 23ed93f..523e264 100644
--- a/tests/unit/adopt-merge.test.ts
+++ b/tests/unit/adopt-merge.test.ts
@@ -49,6 +49,18 @@ describe('twoWayUnionMerge', () => {
     expect(r.hasConflict).toBe(true);
   });
 
+  it('trailing-newline-only difference → conservative conflict (documented)', () => {
+    // diffLines aligns "line2" vs "line2\n" as a replacement (removed+added
+    // in one run), so a file that differs ONLY in its final newline is
+    // reported as a conflict and falls through to the per-file prompt rather
+    // than auto-resolving. This is intentional best-effort behaviour: the
+    // merge never normalizes newlines (that could mask a real diff), so it
+    // errs toward asking. Pinned so the choice is explicit, not accidental.
+    const user = 'line1\nline2';
+    const shard = 'line1\nline2\n';
+    expect(twoWayUnionMerge(buf(user), buf(shard), false).hasConflict).toBe(true);
+  });
+
   it('binary input → always conflict (no line merge attempted)', () => {
     const user = '\x00\x01mine';
     const shard = '\x00\x01theirs';

From 26c5d75ac5546b93dc869a66cbcb67008a9a4ca4 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Mon, 1 Jun 2026 23:30:01 +0200
Subject: [PATCH 7/8] =?UTF-8?q?docs(roadmap):=20check=20#120=20=E2=80=94?=
 =?UTF-8?q?=20adopt=20batch=20operations?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ROADMAP.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index 5547f1b..3496f21 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -127,7 +127,7 @@ UX gaps surfaced during real obsidian-mind v6 install + adopt runs. None block t
 - [x] Wizard scroll indicator + boolean prompt consistency (Y/n typed input → selectable Yes/No) ([#100](https://github.com/breferrari/shardmind/issues/100)) — smallest item, recommended starting point.
 - [x] `multiselect` value type for module-set questions ([#101](https://github.com/breferrari/shardmind/issues/101)) — pairs with #100 (shortens module list). First-class value type + scrollable widget + per-option `default` + min/max; value→module gating stays #80.
 - [x] Adopt: replace step-by-step install wizard with confirm-or-override values flow ([#104](https://github.com/breferrari/shardmind/issues/104))
-- [ ] Adopt batch operations (keep all mine / use all theirs / auto-merge non-conflicting) ([#120](https://github.com/breferrari/shardmind/issues/120)) — pairs with #104.
+- [x] Adopt batch operations (keep all mine / use all theirs / auto-merge non-conflicting) ([#120](https://github.com/breferrari/shardmind/issues/120)) — pairs with #104.
 - [ ] Hook stderr presentation in Summary (truncate, dim, label as non-fatal) ([#105](https://github.com/breferrari/shardmind/issues/105))
 
 ### 0.1.x — Done gate

From 7f0da507f8f5cb11a2f9547aec29904e6ab5a708 Mon Sep 17 00:00:00 2001
From: Brenno Ferrari <brennoferrari@gmail.com>
Date: Mon, 1 Jun 2026 23:38:44 +0200
Subject: [PATCH 8/8] fix(adopt): address Copilot review (#120)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six Copilot comments, all valid:

1. AdoptModePicker header was "1 file differ" — fix subject/verb agreement
   to "1 file differs" / "N files differ"; update the component test and the
   flow-test pickMode regex (which keyed on "differ from").
2. twoWayUnionMerge round-trips through UTF-8 (decode → diff → re-encode). A
   non-binary file that isn't clean UTF-8 (Latin-1 bytes, no NUL) would have
   its bytes replaced by U+FFFD and silently corrupted. Detect
   non-round-trippable input and force a conflict (prompt) instead of merging.
   New unit test with a 0xFF byte.
3. overwritesUserFile: add a `!= null` guard before `typeof === 'object'`
   (typeof null === 'object') — defensive on the unvalidated resolutions map.
4. --mode help + ARCHITECTURE flag said "non-interactively", but
   decide-per-file still prompts and auto-merge prompts on conflicts. Reworded
   both to match actual behavior.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md                      |  2 +-
 source/commands/adopt.tsx                 |  2 +-
 source/components/AdoptModePicker.tsx     |  2 +-
 source/core/adopt-executor.ts             |  8 +++++++-
 source/core/adopt-merge.ts                | 18 +++++++++++++++++-
 tests/component/AdoptModePicker.test.tsx  |  2 +-
 tests/component/flows/adopt-flow.test.tsx |  2 +-
 tests/unit/adopt-merge.test.ts            |  9 +++++++++
 8 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 307873a..dbbf472 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -888,7 +888,7 @@ Phase ordering (logical; UI may interleave loading messages — see IMPLEMENTATI
 
 Flags:
 - `--yes` — skip the values gate + the mode picker; resolve every `differs` as `keep_mine` (shorthand for `--mode=keep-all-mine`). Preserves the user's bytes on every divergence; safe default for retroactive adoption.
-- `--mode <keep-all-mine|use-all-theirs|auto-merge|decide-per-file>` (#120) — resolve the `differs` set non-interactively without the picker. Overrides `--yes`'s default. Combine with `--yes`/`--values` for a fully non-interactive run (the flag governs the diff set, not value collection).
+- `--mode <keep-all-mine|use-all-theirs|auto-merge|decide-per-file>` (#120) — choose how to resolve the `differs` set, skipping the picker. `keep-all-mine`/`use-all-theirs`/`auto-merge` are non-interactive (`auto-merge` still prompts on conflicts unless `--yes` is also set, which keeps-mine on them); `decide-per-file` is the per-file prompt loop. Overrides `--yes`'s default. The flag governs the diff set, not value collection — combine with `--yes`/`--values` for a fully non-interactive run.
 - `--values <file>` — prefill value answers (same shape as `install --values`); shown on the gate's confirm page as `(from --values)`.
 - `--verbose` — show per-file action history during the apply phase.
 - `--dry-run` — run the full pipeline (fetch, values gate, classify) without touching the vault. Summary reports what *would* happen.
diff --git a/source/commands/adopt.tsx b/source/commands/adopt.tsx
index 9cf2ee8..2259271 100644
--- a/source/commands/adopt.tsx
+++ b/source/commands/adopt.tsx
@@ -33,7 +33,7 @@ export const options = zod.object({
     .enum(['keep-all-mine', 'use-all-theirs', 'auto-merge', 'decide-per-file'])
     .optional()
     .describe(
-      'Resolve all divergent files non-interactively. auto-merge is best-effort (keeps your bytes, ignores shard deletions, may duplicate — review after)',
+      'Resolve divergent files in bulk, skipping the mode picker. keep-all-mine/use-all-theirs/auto-merge are non-interactive (auto-merge still prompts on conflicts unless --yes); decide-per-file is the per-file prompt. auto-merge is best-effort (keeps your bytes, ignores shard deletions, may duplicate — review after)',
     ),
   verbose: zod.boolean().default(false).describe('Show per-file action history during adopt'),
   dryRun: zod
diff --git a/source/components/AdoptModePicker.tsx b/source/components/AdoptModePicker.tsx
index 57a3cf4..e1d29af 100644
--- a/source/components/AdoptModePicker.tsx
+++ b/source/components/AdoptModePicker.tsx
@@ -48,7 +48,7 @@ export default function AdoptModePicker({ differsCount, onSelect }: AdoptModePic
   return (
     <Box flexDirection="column" gap={1}>
       <Text bold color="yellow">
-        {differsCount} file{differsCount === 1 ? '' : 's'} differ from the shard.
+        {differsCount} file{differsCount === 1 ? ' differs' : 's differ'} from the shard.
       </Text>
       <Text>How should I resolve them?</Text>
 
diff --git a/source/core/adopt-executor.ts b/source/core/adopt-executor.ts
index b4384e0..33a682e 100644
--- a/source/core/adopt-executor.ts
+++ b/source/core/adopt-executor.ts
@@ -76,7 +76,13 @@ export type AdoptResolutions = Record<string, AdoptResolution>;
 
 /** A resolution that overwrites the user's file → needs a rollback snapshot. */
 function overwritesUserFile(resolution: AdoptResolution | undefined): boolean {
-  return resolution === 'use_shard' || (typeof resolution === 'object' && resolution.kind === 'merged');
+  // `resolution != null` guards the `typeof === 'object'` branch against a
+  // null map value (typeof null === 'object') even though the type excludes
+  // it — this runs on unvalidated `resolutions[path]` lookups.
+  return (
+    resolution === 'use_shard' ||
+    (resolution != null && typeof resolution === 'object' && resolution.kind === 'merged')
+  );
 }
 
 export interface AdoptRunnerOptions {
diff --git a/source/core/adopt-merge.ts b/source/core/adopt-merge.ts
index bfffcbb..4a62273 100644
--- a/source/core/adopt-merge.ts
+++ b/source/core/adopt-merge.ts
@@ -56,7 +56,23 @@ export function twoWayUnionMerge(
     return { content: userContent, hasConflict: true };
   }
 
-  const parts = diffLines(userContent.toString('utf8'), shardContent.toString('utf8'));
+  const userText = userContent.toString('utf8');
+  const shardText = shardContent.toString('utf8');
+
+  // The merge round-trips through UTF-8 (decode → diff → re-encode). A
+  // non-binary file (no NUL, so `looksBinary` returned false) that is still
+  // not clean UTF-8 — e.g. Latin-1 / Windows-1252 bytes — would have its
+  // invalid bytes replaced by U+FFFD and silently corrupted in the union
+  // output. Detect non-round-trippable input and force a prompt instead of
+  // merging it.
+  if (
+    !Buffer.from(userText, 'utf8').equals(userContent) ||
+    !Buffer.from(shardText, 'utf8').equals(shardContent)
+  ) {
+    return { content: userContent, hasConflict: true };
+  }
+
+  const parts = diffLines(userText, shardText);
 
   let hasConflict = false;
   let out = '';
diff --git a/tests/component/AdoptModePicker.test.tsx b/tests/component/AdoptModePicker.test.tsx
index 956001d..1f2539b 100644
--- a/tests/component/AdoptModePicker.test.tsx
+++ b/tests/component/AdoptModePicker.test.tsx
@@ -32,7 +32,7 @@ describe('AdoptModePicker', () => {
       <AdoptModePicker differsCount={1} onSelect={vi.fn()} />,
     );
     await waitFor(lastFrame, (f) => f.includes('Keep all mine'));
-    expect(lastFrame() ?? '').toMatch(/1 file differ(?!s)/);
+    expect(lastFrame() ?? '').toMatch(/1 file differs from the shard/);
   });
 
   it('ENTER on the focused option selects keep-all-mine', async () => {
diff --git a/tests/component/flows/adopt-flow.test.tsx b/tests/component/flows/adopt-flow.test.tsx
index f1ba8ad..2f549e0 100644
--- a/tests/component/flows/adopt-flow.test.tsx
+++ b/tests/component/flows/adopt-flow.test.tsx
@@ -77,7 +77,7 @@ describe('adopt command — Layer 1 flow tests (#111 Phase 1, scenarios 19-26)',
     r: ReturnType<typeof mountAdopt>,
     mode: 'keep-all-mine' | 'use-all-theirs' | 'auto-merge' | 'decide-per-file',
   ): Promise<void> {
-    await waitFor(r.lastFrame, (f) => /files? differ from the shard/.test(f), 20_000);
+    await waitFor(r.lastFrame, (f) => /files? differs? from the shard/.test(f), 20_000);
     // Arrow counts must match AdoptModePicker.tsx's option order
     // (keep-all-mine, use-all-theirs, auto-merge, decide-per-file).
     const downs = {
diff --git a/tests/unit/adopt-merge.test.ts b/tests/unit/adopt-merge.test.ts
index 523e264..be826ef 100644
--- a/tests/unit/adopt-merge.test.ts
+++ b/tests/unit/adopt-merge.test.ts
@@ -61,6 +61,15 @@ describe('twoWayUnionMerge', () => {
     expect(twoWayUnionMerge(buf(user), buf(shard), false).hasConflict).toBe(true);
   });
 
+  it('non-UTF-8 but non-binary input → conflict, never lossy-merged', () => {
+    // 0xFF is invalid UTF-8 and there is no NUL, so the planner's looksBinary
+    // returns false. Merging would corrupt the byte via U+FFFD; the guard
+    // forces a prompt instead.
+    const user = Buffer.from([0x61, 0xff, 0x0a]); // "a", 0xFF, "\n"
+    const shard = Buffer.from('a\nb\n', 'utf8');
+    expect(twoWayUnionMerge(user, shard, false).hasConflict).toBe(true);
+  });
+
   it('binary input → always conflict (no line merge attempted)', () => {
     const user = '\x00\x01mine';
     const shard = '\x00\x01theirs';