amalgm 0.1.152 → 0.1.153

package/runtime/scripts/amalgm-mcp/state/merge3.js

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * Minimal three-way line-based merge (diff3) for live-document reconcile.
+ *
+ * merge3(base, ours, theirs) — all three are whole-file strings — answers:
+ * given that both OURS and THEIRS evolved from BASE, what single text keeps
+ * both sides' changes? Hunks (line regions changed relative to BASE) that
+ * touch different base regions merge automatically; hunks that overlap are
+ * conflicts. On conflict this module NEVER picks a winner silently: the
+ * merged text keeps OURS for the conflicted region and the conflict is
+ * reported to the caller, which is responsible for preserving THEIRS
+ * durably (docs.js writes a sidecar file).
+ *
+ * No dependencies by design — this ships in the published package. The diff
+ * is a plain LCS over lines (common prefix/suffix trimmed first); regions too
+ * large to LCS degrade to a single whole-region hunk, which can only ever
+ * OVER-report a conflict, never lose an edit.
+ */
+
+// Cap on the LCS DP table (cells = changed-lines² after prefix/suffix trim).
+// 4M cells ≈ 16MB of Int32 — beyond it the changed region collapses into one
+// hunk per side, trading merge granularity for bounded memory.
+const MAX_LCS_CELLS = 4 * 1024 * 1024;
+
+/** Split into lines with their terminators kept, so join('') reassembles exactly. */
+function splitLines(text) {
+  if (text === '') return [];
+  return text.split(/(?<=\n)/);
+}
+
+/**
+ * Longest common subsequence between a[aStart..aEnd) and b[bStart..bEnd),
+ * returned as matched index pairs [aIndex, bIndex] in increasing order.
+ */
+function lcsMatches(a, aStart, aEnd, b, bStart, bEnd) {
+  const n = aEnd - aStart;
+  const m = bEnd - bStart;
+  const width = m + 1;
+  const table = new Int32Array((n + 1) * width);
+  for (let i = 1; i <= n; i += 1) {
+    const line = a[aStart + i - 1];
+    for (let j = 1; j <= m; j += 1) {
+      table[i * width + j] = line === b[bStart + j - 1]
+        ? table[(i - 1) * width + (j - 1)] + 1
+        : Math.max(table[(i - 1) * width + j], table[i * width + (j - 1)]);
+    }
+  }
+  const matches = [];
+  let i = n;
+  let j = m;
+  while (i > 0 && j > 0) {
+    if (a[aStart + i - 1] === b[bStart + j - 1]
+      && table[i * width + j] === table[(i - 1) * width + (j - 1)] + 1) {
+      matches.push([aStart + i - 1, bStart + j - 1]);
+      i -= 1;
+      j -= 1;
+    } else if (table[(i - 1) * width + j] >= table[i * width + (j - 1)]) {
+      i -= 1;
+    } else {
+      j -= 1;
+    }
+  }
+  matches.reverse();
+  return matches;
+}
+
+/**
+ * Regions where `side` differs from `base`, as
+ * {baseStart, baseLength, sideStart, sideLength} in base order. Outside these
+ * hunks the two arrays match line for line.
+ */
+function diffHunks(base, side) {
+  let prefix = 0;
+  const maxPrefix = Math.min(base.length, side.length);
+  while (prefix < maxPrefix && base[prefix] === side[prefix]) prefix += 1;
+  let baseEnd = base.length;
+  let sideEnd = side.length;
+  while (baseEnd > prefix && sideEnd > prefix && base[baseEnd - 1] === side[sideEnd - 1]) {
+    baseEnd -= 1;
+    sideEnd -= 1;
+  }
+  const n = baseEnd - prefix;
+  const m = sideEnd - prefix;
+  if (n === 0 && m === 0) return [];
+  if (n === 0 || m === 0 || n * m > MAX_LCS_CELLS) {
+    return [{ baseStart: prefix, baseLength: n, sideStart: prefix, sideLength: m }];
+  }
+
+  const hunks = [];
+  let b = prefix;
+  let s = prefix;
+  for (const [mb, ms] of lcsMatches(base, prefix, baseEnd, side, prefix, sideEnd)) {
+    if (mb > b || ms > s) {
+      hunks.push({ baseStart: b, baseLength: mb - b, sideStart: s, sideLength: ms - s });
+    }
+    b = mb + 1;
+    s = ms + 1;
+  }
+  if (baseEnd > b || sideEnd > s) {
+    hunks.push({ baseStart: b, baseLength: baseEnd - b, sideStart: s, sideLength: sideEnd - s });
+  }
+  return hunks;
+}
+
+/**
+ * The side's lines corresponding to the group's base range [start, end).
+ * Between its own hunks a side matches the base line for line, so the range
+ * extends from the first hunk (pulled back by the matched lead-in) to the
+ * last hunk (pushed forward by the matched tail).
+ */
+function sideSlice(group, sideHunks, baseLines, sideLines) {
+  if (sideHunks.length === 0) return baseLines.slice(group.start, group.end);
+  const first = sideHunks[0];
+  const last = sideHunks[sideHunks.length - 1];
+  const lo = first.sideStart - (first.baseStart - group.start);
+  const hi = last.sideStart + last.sideLength + (group.end - (last.baseStart + last.baseLength));
+  return sideLines.slice(lo, hi);
+}
+
+/**
+ * Three-way merge of whole-file strings.
+ *
+ * Returns {text, conflicts}: `text` is the merged result; `conflicts` lists
+ * every overlapping region as {baseStart, baseEnd, ours, theirs} (line
+ * indices into BASE; `ours`/`theirs` are that region's text on each side).
+ * For conflicted regions `text` keeps OURS.
+ *
+ * Fast paths: either side identical to base (or to the other side) short-
+ * circuits without diffing.
+ */
+function merge3(baseText, oursText, theirsText) {
+  if (oursText === theirsText) return { text: oursText, conflicts: [] };
+  if (oursText === baseText) return { text: theirsText, conflicts: [] };
+  if (theirsText === baseText) return { text: oursText, conflicts: [] };
+
+  const base = splitLines(baseText);
+  const ours = splitLines(oursText);
+  const theirs = splitLines(theirsText);
+  const hunks = [
+    ...diffHunks(base, ours).map((h) => ({ ...h, side: 'ours' })),
+    ...diffHunks(base, theirs).map((h) => ({ ...h, side: 'theirs' })),
+  ].sort((a, b) => (a.baseStart - b.baseStart)
+    || (a.side === b.side ? 0 : a.side === 'ours' ? -1 : 1));
+
+  // Group hunks whose base ranges overlap. Adjacent (touching) ranges stay
+  // separate — they merge cleanly — with one exception: insertions from both
+  // sides at the exact same base point have no defined order, so they group
+  // (and therefore conflict) too.
+  const groups = [];
+  for (const hunk of hunks) {
+    const group = groups[groups.length - 1];
+    const joins = group && (
+      hunk.baseStart < group.end
+      || (hunk.baseStart === group.end && hunk.baseLength === 0
+        && group.hunks.some((h) => h.side !== hunk.side
+          && h.baseLength === 0 && h.baseStart === hunk.baseStart))
+    );
+    if (joins) {
+      group.hunks.push(hunk);
+      group.end = Math.max(group.end, hunk.baseStart + hunk.baseLength);
+    } else {
+      groups.push({ start: hunk.baseStart, end: hunk.baseStart + hunk.baseLength, hunks: [hunk] });
+    }
+  }
+
+  const out = [];
+  const conflicts = [];
+  let cursor = 0;
+  for (const group of groups) {
+    out.push(base.slice(cursor, group.start).join(''));
+    const oursHunks = group.hunks.filter((h) => h.side === 'ours');
+    const theirsHunks = group.hunks.filter((h) => h.side === 'theirs');
+    const oursRegion = sideSlice(group, oursHunks, base, ours).join('');
+    const theirsRegion = sideSlice(group, theirsHunks, base, theirs).join('');
+    if (theirsHunks.length === 0 || oursRegion === theirsRegion) {
+      out.push(oursRegion);
+    } else if (oursHunks.length === 0) {
+      out.push(theirsRegion);
+    } else {
+      // Overlap with different content on each side: keep OURS in the text,
+      // surface the conflict to the caller.
+      conflicts.push({
+        baseStart: group.start,
+        baseEnd: group.end,
+        ours: oursRegion,
+        theirs: theirsRegion,
+      });
+      out.push(oursRegion);
+    }
+    cursor = group.end;
+  }
+  out.push(base.slice(cursor).join(''));
+  return { text: out.join(''), conflicts };
+}
+
+module.exports = { merge3 };

package/runtime/scripts/amalgm-mcp/state/rest.js

@@ -109,6 +109,21 @@ async function handleDocUpdate(body, sendJson) {
   }
 }
 
+// Versioned whole-text write (the SDK write contract — semantics live in
+// docs.writeDocText): body {path, text, baseHash?, baseSeq?}. `baseHash` is
+// the sha256 returned by open/write for the exact text the writer read;
+// with it, stale writes three-way merge instead of clobbering live edits.
+async function handleDocWrite(body, sendJson) {
+  try {
+    sendJson(200, require('./docs').writeDocText(body?.path, body?.text, {
+      baseHash: body?.baseHash,
+      baseSeq: body?.baseSeq,
+    }));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
 async function handleResourceList(sendJson) {
   try {
     sendJson(200, { resources: appResources.listAppResources() });
@@ -134,7 +149,11 @@ async function handleEvents(query, sendJson) {
 
 function handleStream(req, res, query) {
   appResources.ensureAppResourcesLoaded();
-  const after = parsePositiveInt(query.after, 0);
+  // Ordered-bootstrap mode (docs/local-live-protocol.md §3): the snapshot
+  // travels on the stream itself as the first data frame, so `after` is
+  // ignored — the snapshot IS the resume point.
+  const bootstrap = String(query.bootstrap || '').trim() === '1';
+  const after = bootstrap ? 0 : parsePositiveInt(query.after, 0);
 
   res.writeHead(200, {
     'Content-Type': 'text/event-stream; charset=utf-8',
@@ -144,23 +163,26 @@ function handleStream(req, res, query) {
   });
   res.write(': local-live-store connected\n\n');
 
-  const gap = replayGapAfter(after);
-  if (gap) {
-    sendSseControl(res, 'reset', { ...gap, reset: true });
-    res.end();
-    return;
-  }
+  let backlog = [];
+  if (!bootstrap) {
+    const gap = replayGapAfter(after);
+    if (gap) {
+      sendSseControl(res, 'reset', { ...gap, reset: true });
+      res.end();
+      return;
+    }
 
-  const backlog = listEventsAfter(after, { limit: STREAM_REPLAY_MAX_EVENTS + 1 });
-  if (backlog.length > STREAM_REPLAY_MAX_EVENTS) {
-    sendSseControl(res, 'reset', {
-      code: 'state_replay_too_large',
-      message: 'Too many missed events to replay; fetch a fresh snapshot.',
-      after,
-      reset: true,
-    });
-    res.end();
-    return;
+    backlog = listEventsAfter(after, { limit: STREAM_REPLAY_MAX_EVENTS + 1 });
+    if (backlog.length > STREAM_REPLAY_MAX_EVENTS) {
+      sendSseControl(res, 'reset', {
+        code: 'state_replay_too_large',
+        message: 'Too many missed events to replay; fetch a fresh snapshot.',
+        after,
+        reset: true,
+      });
+      res.end();
+      return;
+    }
   }
 
   // One teardown for every way the stream can die. Idempotent because close
@@ -195,12 +217,48 @@ function handleStream(req, res, query) {
     }
   };
 
+  // The subscriber registers BEFORE the bootstrap snapshot is built so no
+  // event can slip between them: events landing mid-build are held here and
+  // flushed after the snapshot frame. `floorSeq` is the resume point — the
+  // client's `after` in legacy mode, the snapshot's seq once it is built.
+  let heldWhileBootstrapping = bootstrap ? [] : null;
+  let floorSeq = after;
   unsubscribe = subscribeStateEvents((event) => {
-    if (event.seq > after) writeSafe(() => sendSseEvent(res, event));
+    if (heldWhileBootstrapping) {
+      heldWhileBootstrapping.push(event);
+      return;
+    }
+    if (event.seq > floorSeq) writeSafe(() => sendSseEvent(res, event));
   });
 
-  for (const event of backlog) {
-    writeSafe(() => sendSseEvent(res, event));
+  if (bootstrap) {
+    let snapshot;
+    try {
+      // Exactly the REST snapshot path (handleSnapshot), including its
+      // failure contract: a resource read throwing must surface as a clean
+      // stream error, not a response that never completes.
+      snapshot = buildSnapshot(query.resources);
+    } catch (error) {
+      writeSafe(() => sendSseControl(res, 'error', {
+        status: Number(error?.statusCode) || 500,
+        error: error?.message || 'internal error',
+      }));
+      teardown();
+      return;
+    }
+    floorSeq = snapshot.seq;
+    writeSafe(() => sendSseControl(res, 'snapshot', snapshot));
+    const held = heldWhileBootstrapping;
+    heldWhileBootstrapping = null;
+    // Events that landed while the snapshot was being built: anything at or
+    // below snapshot.seq is already inside it; the rest flush in seq order.
+    for (const event of held) {
+      if (event.seq > floorSeq) writeSafe(() => sendSseEvent(res, event));
+    }
+  } else {
+    for (const event of backlog) {
+      writeSafe(() => sendSseEvent(res, event));
+    }
   }
 
   // A named event (not an SSE comment) so EventSource clients can observe it
@@ -224,6 +282,7 @@ function handleStream(req, res, query) {
 module.exports = {
   handleDocOpen,
   handleDocUpdate,
+  handleDocWrite,
   handleEvents,
   handleResourceEmit,
   handleResourceList,

package/runtime/scripts/amalgm-mcp/tests/browser-transport.test.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const assert = require('node:assert/strict');
-const test = require('node:test');
+const { after, test } = require('node:test');
 
 // Transport semantics: in attached mode a session's identity is established
 // once at attach (daemon tab selection + a stamp on the guest document) and
@@ -15,6 +15,16 @@ const test = require('node:test');
 const attach = require('../browser/attach');
 const { surfaces, knownSessions } = require('../browser/sessions');
 
+// These transport tests assert their exact daemon command sequence. A real
+// browser-auth bundle on the developer machine would prepend `state load`, so
+// keep the fixture hermetic and restore the caller's environment afterward.
+const savedCookieSource = process.env.AMALGM_BROWSER_COOKIE_SOURCE;
+process.env.AMALGM_BROWSER_COOKIE_SOURCE = '0';
+after(() => {
+  if (savedCookieSource === undefined) delete process.env.AMALGM_BROWSER_COOKIE_SOURCE;
+  else process.env.AMALGM_BROWSER_COOKIE_SOURCE = savedCookieSource;
+});
+
 // Patch attach.run before engine destructures it (engine binds at require).
 const calls = [];
 let nextResults = [];

package/runtime/scripts/amalgm-mcp/tests/state-docs-merge.test.js

@@ -0,0 +1,251 @@
+'use strict';
+
+// Three-way merge on external disk edits: a writer that read the file, then
+// wrote a full text based on that stale read while a human typed via Yjs,
+// must not delete the human's live edits (the audit's silent-loss finding).
+// Unit tests cover state/merge3; integration tests cover the docs.js wiring:
+// merged splices, conflict sidecars, the event's `conflict` field, and the
+// watcher ignoring sidecars.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-docs-merge-test-'));
+process.env.AMALGM_DIR = path.join(tempRoot, '.amalgm');
+
+const Y = require('yjs');
+const { closeLocalDb } = require('../state/db');
+const docs = require('../state/docs');
+const { merge3 } = require('../state/merge3');
+const { listEventsAfter, currentSeq } = require('../state/events');
+
+const docDir = path.join(tempRoot, 'workspace');
+fs.mkdirSync(docDir, { recursive: true });
+
+function writeDoc(name, text) {
+  const target = path.join(docDir, name);
+  fs.writeFileSync(target, text, 'utf8');
+  return target;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function clientFromState(stateBase64) {
+  const doc = new Y.Doc();
+  Y.applyUpdate(doc, new Uint8Array(Buffer.from(stateBase64, 'base64')));
+  return doc;
+}
+
+function encodeLocalEdit(doc, mutate) {
+  let captured = null;
+  const listener = (update) => { captured = update; };
+  doc.on('update', listener);
+  mutate(doc.getText('content'));
+  doc.off('update', listener);
+  assert.ok(captured, 'edit should produce an update');
+  return Buffer.from(captured).toString('base64');
+}
+
+function sidecarsFor(target) {
+  const ext = path.extname(target);
+  const stem = path.basename(target, ext);
+  const pattern = new RegExp(
+    `^${stem}\\.conflicted-\\d{8}-\\d{6}(?:-\\d+)?${ext.replace('.', '\\.')}$`,
+  );
+  return fs.readdirSync(path.dirname(target))
+    .filter((name) => pattern.test(name))
+    .map((name) => path.join(path.dirname(target), name));
+}
+
+test.after(() => {
+  docs.closeAllDocs();
+  closeLocalDb();
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// merge3 unit tests
+// ---------------------------------------------------------------------------
+
+test('merge3: fast paths short-circuit when one side did not move', () => {
+  const base = 'a\nb\nc\n';
+  assert.deepEqual(merge3(base, base, 'a\nB\nc\n'), { text: 'a\nB\nc\n', conflicts: [] });
+  assert.deepEqual(merge3(base, 'a\nB\nc\n', base), { text: 'a\nB\nc\n', conflicts: [] });
+  assert.deepEqual(merge3(base, 'same\n', 'same\n'), { text: 'same\n', conflicts: [] });
+});
+
+test('merge3: disjoint edits both survive', () => {
+  const base = 'l1\nl2\nl3\nl4\nl5\n';
+  const ours = 'l1 mine\nl2\nl3\nl4\nl5\n';
+  const theirs = 'l1\nl2\nl3\nl4\nl5 theirs\n';
+  const merged = merge3(base, ours, theirs);
+  assert.equal(merged.text, 'l1 mine\nl2\nl3\nl4\nl5 theirs\n');
+  assert.equal(merged.conflicts.length, 0);
+});
+
+test('merge3: adjacent-but-not-overlapping lines merge cleanly', () => {
+  const base = 'l1\nl2\nl3\nl4\n';
+  const ours = 'l1\nl2 mine\nl3\nl4\n';
+  const theirs = 'l1\nl2\nl3 theirs\nl4\n';
+  const merged = merge3(base, ours, theirs);
+  assert.equal(merged.text, 'l1\nl2 mine\nl3 theirs\nl4\n');
+  assert.equal(merged.conflicts.length, 0);
+});
+
+test('merge3: overlapping edits conflict and keep OURS', () => {
+  const base = 'l1\nl2\nl3\n';
+  const ours = 'l1\nl2 mine\nl3\n';
+  const theirs = 'l1\nl2 theirs\nl3\n';
+  const merged = merge3(base, ours, theirs);
+  assert.equal(merged.text, 'l1\nl2 mine\nl3\n');
+  assert.equal(merged.conflicts.length, 1);
+  assert.equal(merged.conflicts[0].ours, 'l2 mine\n');
+  assert.equal(merged.conflicts[0].theirs, 'l2 theirs\n');
+});
+
+test('merge3: identical overlapping changes apply once, no conflict', () => {
+  const base = 'l1\nl2\nl3\nl4\n';
+  // Both sides made the SAME change to l2; ours also changed l4 on its own.
+  const ours = 'l1\nl2 same-change\nl3\nl4 mine\n';
+  const theirs = 'l1\nl2 same-change\nl3\nl4\n';
+  const merged = merge3(base, ours, theirs);
+  assert.equal(merged.text, 'l1\nl2 same-change\nl3\nl4 mine\n');
+  assert.equal(merged.conflicts.length, 0);
+});
+
+test('merge3: insertions from both sides at the same point conflict', () => {
+  const base = 'l1\nl2\n';
+  const ours = 'l1\nours inserted\nl2\n';
+  const theirs = 'l1\ntheirs inserted\nl2\n';
+  const merged = merge3(base, ours, theirs);
+  assert.equal(merged.conflicts.length, 1);
+  assert.equal(merged.text, ours, 'conflicted insertion keeps OURS');
+});
+
+test('merge3: whole-file rewrite vs one-line local edit conflicts, local line survives', () => {
+  const base = 'l1\nl2\nl3\n';
+  const ours = 'l1\nl2 human edit\nl3\n';
+  const theirs = 'completely\ndifferent\nfile\ncontents\n';
+  const merged = merge3(base, ours, theirs);
+  assert.equal(merged.conflicts.length, 1);
+  assert.ok(merged.text.includes('l2 human edit\n'), 'local edit must survive the rewrite');
+  assert.equal(merged.text, ours, 'a total-overlap rewrite keeps the live doc text');
+});
+
+// ---------------------------------------------------------------------------
+// Integration: stale-based external writes against live Yjs edits.
+// Timing mirrors state-docs.test.js: the watcher reconcile debounce is 200ms
+// and the doc's own write-back 300ms, so the external write lands immediately
+// after the (unflushed) local edit and reconcile sees both sides diverged.
+// ---------------------------------------------------------------------------
+
+test('disjoint external write merges: human edit and agent edit both land', async () => {
+  const base = 'l1\nl2\nl3\nl4\nl5\n';
+  const target = writeDoc('merge-disjoint.md', base);
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+  const before = currentSeq();
+
+  // Human types line 1 via Yjs (write-back still debounced: disk is stale)…
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('l1'.length, ' human')),
+  ]);
+  // …while an agent that read the ORIGINAL file writes a full text with only
+  // line 5 changed — based on the old content, without the human's edit.
+  fs.writeFileSync(target, 'l1\nl2\nl3\nl4\nl5 agent\n', 'utf8');
+  await sleep(900);
+
+  assert.equal(
+    docs.getDocText(target),
+    'l1 human\nl2\nl3\nl4\nl5 agent\n',
+    'both the live edit and the disjoint external edit must survive',
+  );
+  assert.equal(fs.readFileSync(target, 'utf8'), 'l1 human\nl2\nl3\nl4\nl5 agent\n');
+  assert.equal(sidecarsFor(target).length, 0, 'clean merge writes no sidecar');
+  const conflictEvents = listEventsAfter(before)
+    .filter((e) => e.resource === opened.resource && e.patch?.conflict);
+  assert.equal(conflictEvents.length, 0, 'clean merge publishes no conflict');
+});
+
+test('overlapping external write conflicts: OURS kept, THEIRS preserved in sidecar, conflict published', async () => {
+  const base = 'alpha\nbeta\ngamma\n';
+  const target = writeDoc('merge-conflict.md', base);
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+  const before = currentSeq();
+
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('alpha\nbeta'.length, ' (human)')),
+  ]);
+  const theirs = 'alpha\nbeta (agent)\ngamma\n';
+  fs.writeFileSync(target, theirs, 'utf8');
+  await sleep(900);
+
+  // The live doc keeps the human's line — never silently replaced.
+  assert.equal(docs.getDocText(target), 'alpha\nbeta (human)\ngamma\n');
+  // The merged text overwrote THEIRS on disk (intended: THEIRS is in the sidecar).
+  assert.equal(fs.readFileSync(target, 'utf8'), 'alpha\nbeta (human)\ngamma\n');
+
+  const sidecars = sidecarsFor(target);
+  assert.equal(sidecars.length, 1, 'conflict must write exactly one sidecar');
+  assert.equal(fs.readFileSync(sidecars[0], 'utf8'), theirs, 'sidecar holds the full incoming disk text');
+
+  const conflictEvents = listEventsAfter(before)
+    .filter((e) => e.resource === opened.resource && e.patch?.conflict);
+  assert.equal(conflictEvents.length, 1);
+  const { conflict } = conflictEvents[0].patch;
+  assert.equal(conflict.sidecarPath, sidecars[0]);
+  assert.equal(conflict.hunks, 1);
+  assert.ok(typeof conflict.at === 'string' && !Number.isNaN(Date.parse(conflict.at)));
+
+  // Sidecars can never become live docs…
+  assert.throws(() => docs.openDoc(sidecars[0]), /sidecar/);
+  // …and the watcher ignores them: poking the sidecar emits nothing.
+  const settled = currentSeq();
+  fs.writeFileSync(sidecars[0], `${theirs}poke\n`, 'utf8');
+  await sleep(700);
+  const after = listEventsAfter(settled).filter((e) => e.resource === opened.resource);
+  assert.equal(after.length, 0, `sidecar writes must not re-ingest (got ${JSON.stringify(after)})`);
+  assert.equal(docs.getDocText(target), 'alpha\nbeta (human)\ngamma\n');
+});
+
+test('mixed external write: conflicting hunk keeps OURS, disjoint hunk still lands', async () => {
+  const base = 'h1\nh2\nh3\nh4\nh5\n';
+  const target = writeDoc('merge-mixed.md', base);
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+  const before = currentSeq();
+
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('h1'.length, ' human')),
+  ]);
+  // The agent's stale-based write touches line 1 (conflicts with the human)
+  // AND line 5 (disjoint — must merge in).
+  const theirs = 'h1 agent\nh2\nh3\nh4\nh5 agent\n';
+  fs.writeFileSync(target, theirs, 'utf8');
+  await sleep(900);
+
+  assert.equal(
+    docs.getDocText(target),
+    'h1 human\nh2\nh3\nh4\nh5 agent\n',
+    'human line kept on conflict, disjoint agent line merged in',
+  );
+  assert.equal(fs.readFileSync(target, 'utf8'), 'h1 human\nh2\nh3\nh4\nh5 agent\n');
+
+  const sidecars = sidecarsFor(target);
+  assert.equal(sidecars.length, 1);
+  assert.equal(fs.readFileSync(sidecars[0], 'utf8'), theirs);
+
+  // The merged splice and the conflict ride the same doc event.
+  const conflictEvents = listEventsAfter(before)
+    .filter((e) => e.resource === opened.resource && e.patch?.conflict);
+  assert.equal(conflictEvents.length, 1);
+  assert.ok(conflictEvents[0].patch.yjs, 'merged splice and conflict share one event patch');
+  assert.equal(conflictEvents[0].patch.conflict.hunks, 1);
+  assert.equal(conflictEvents[0].source, 'doc:disk');
+});