Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

31.5 KB
Raw Blame
import { randomUUID } from 'node:crypto';
import {
  existsSync,
  lstatSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  realpathSync,
  renameSync,
  rmSync,
  symlinkSync,
  unlinkSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { basename, join } from 'node:path';
import { afterEach, describe, expect, test, vi } from 'vitest';
import { DocumentDurabilityStateError } from '../../../server/src/document-durability-state';
import {
  getWatcherDecisionRingSnapshot,
  isSelfRemoval,
  removalTracker,
  writeTracker,
} from '../../../server/src/file-watcher';
import { contentHash } from '../../../server/src/version-hash';
import {
  agentWriteMd,
  createTestClient,
  createTestServer,
  getServerState,
  pollUntil,
  readTestDoc,
  type TestServer,
  wait,
} from './test-harness';

const ACK_MARKER = 'ACK-APPEND-MARKER';
const STALE_WRITE_DELAY_MS = 200;

let server: TestServer | undefined;
let ownedProjectDir: string | undefined;

afterEach(async () => {
  if (server) {
    await server.cleanup();
    server = undefined;
  }
  if (ownedProjectDir) {
    rmSync(ownedProjectDir, { recursive: true, force: true });
    ownedProjectDir = undefined;
  }
});

async function acknowledgeWrite(
  target: TestServer,
  docName: string,
): Promise<{ stale: string; acknowledged: string }> {
  await agentWriteMd(
    target.port,
    '---\ntags: [stale-write-test]\n---\n\n# Doc\n\noriginal-body\n',
    { docName, position: 'replace' },
  );
  await pollUntil(() => readTestDoc(target.contentDir, docName).includes('original-body'));
  const stale = readTestDoc(target.contentDir, docName);
  await agentWriteMd(target.port, `${ACK_MARKER}\n`, { docName, position: 'append' });
  await pollUntil(() => readTestDoc(target.contentDir, docName).includes(ACK_MARKER));
  const file = join(target.contentDir, `${docName}.md`);
  await pollUntil(
    () => !writeTracker.get(file)?.some((entry) => entry.hash === contentHash(stale)),
  );
  return { stale, acknowledged: readTestDoc(target.contentDir, docName) };
}

async function restoreStale(target: TestServer, docName: string, stale: string): Promise<void> {
  writeFileSync(join(target.contentDir, `${docName}.md`), stale, 'utf-8');
  await pollUntil(
    () => target.instance.durabilityState.getStaleExternalWrite(docName) !== undefined,
    undefined,
    undefined,
    `stale external-write conflict for ${docName}`,
  );
}

async function resolveConflict(
  target: TestServer,
  file: string,
  strategy: string,
  content?: string,
): Promise<Response> {
  return fetch(`${target.baseUrl}/api/sync/resolve-conflict`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ file, strategy, content }),
  });
}

async function unloadDocument(target: TestServer, docName: string): Promise<void> {
  await target.instance.sessionManager.closeAllForDoc(docName);
  const hocuspocus = target.instance.hocuspocus;
  const document = hocuspocus.documents.get(docName);
  if (!document) throw new Error(`document ${docName} not loaded`);
  const shouldUnload = hocuspocus.shouldUnloadDocument;
  hocuspocus.shouldUnloadDocument = (candidate) =>
    candidate === document || shouldUnload.call(hocuspocus, candidate);
  try {
    await hocuspocus.unloadDocument(document);
  } finally {
    hocuspocus.shouldUnloadDocument = shouldUnload;
  }
}

function lifecycleOf(
  target: TestServer,
  docName: string,
): { status?: unknown; kind?: unknown; reason?: unknown } {
  const document = target.instance.hocuspocus.documents.get(docName);
  if (!document) throw new Error(`document ${docName} not loaded`);
  return target.instance.conflicts.lifecycleOf(document, docName) ?? {};
}

function observeLifecycleStatuses(target: TestServer, docName: string): unknown[] {
  const document = target.instance.hocuspocus.documents.get(docName);
  if (!document) throw new Error(`document ${docName} not loaded`);
  const lifecycle = document.getMap('lifecycle');
  const seen: unknown[] = [];
  lifecycle.observe(() => seen.push(lifecycle.get('status')));
  return seen;
}

function lifecycleStatusOf(target: TestServer, docName: string): unknown {
  const document = target.instance.hocuspocus.documents.get(docName);
  if (!document) return 'document-unloaded';
  return target.instance.conflicts.lifecycleOf(document, docName)?.status;
}

async function awaitWatcherObservationOfDoc(docName: string): Promise<void> {
  await pollUntil(
    () =>
      getWatcherDecisionRingSnapshot().some((record) => basename(record.path) === `${docName}.md`),
    15_000,
    25,
    `the file watcher to observe the creation of ${docName}.md, without which @parcel/watcher can coalesce that creation with the unlink the resolution issues next into one batch entry that its inotify backend drops outright`,
  );
}

async function awaitWatcherDecisionForDoc(docName: string, ringOffset: number): Promise<void> {
  await pollUntil(
    () =>
      getWatcherDecisionRingSnapshot()
        .slice(ringOffset)
        .some(
          (record) =>
            basename(record.path) === `${docName}.md` && record.decision === 'self-removal-skip',
        ),
    15_000,
    25,
    `the file watcher to classify the disk event this resolution produced for ${docName}.md as the server's own removal, without which the assertions after it race that event`,
  );
}

describe('stale external write does not roll back an acknowledged agent write', () => {
  test.skip.each([false, true])(
    'resolves nonempty stale sides to an explicit empty file (unloaded=%s)',
    {
      tags: ['quarantine'],
      meta: {
        issue: 'https://github.com/inkeep/agents-private/issues/5729',
        owner: 'get-main-green',
        until: '2026-12-01',
      },
    },
    async (unloaded) => {
      server = await createTestServer();
      const docName = 'explicit-empty';
      const { stale } = await acknowledgeWrite(server, docName);
      await restoreStale(server, docName, stale);
      if (unloaded) await unloadDocument(server, docName);
      const response = await resolveConflict(server, `${docName}.md`, 'content', '');
      expect(response.status).toBe(200);
      expect(existsSync(join(server.contentDir, `${docName}.md`))).toBe(true);
      expect(readTestDoc(server.contentDir, docName)).toBe('');
      expect(server.instance.durabilityState.getStaleExternalWrite(docName)).toBeUndefined();
      const client = await createTestClient(server.port, docName);
      try {
        expect(client.ytext.toString()).toBe('');
      } finally {
        await client.cleanup();
      }
    },
  );
  test('a corrupt recovery snapshot stops startup with actionable diagnostics and preserves bytes', async () => {
    ownedProjectDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-stale-boot-')));
    const snapshot = join(ownedProjectDir, '.ok', 'local', 'stale-external-writes.json');
    mkdirSync(join(ownedProjectDir, '.ok', 'local'), { recursive: true });
    const raw = '{protected edits, truncated';
    writeFileSync(snapshot, raw);
    await expect(
      createTestServer({ contentDir: ownedProjectDir, configHomedirOverride: ownedProjectDir }),
    ).rejects.toThrow(DocumentDurabilityStateError);
    expect(readFileSync(snapshot, 'utf-8')).toBe(raw);
  });

  test('a shareable template stale conflict can be listed, read and resolved', async () => {
    const docName = '.ok/templates/stale-template';
    const file = `${docName}.md`;
    ownedProjectDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-shareable-template-')));
    mkdirSync(join(ownedProjectDir, '.ok', 'templates'), { recursive: true });
    writeFileSync(join(ownedProjectDir, file), 'rejected\n');
    server = await createTestServer({
      contentDir: ownedProjectDir,
      keepContentDir: true,
      debounce: 50,
      maxDebounce: 200,
    });
    const state = server.instance.durabilityState;
    state.setReconciledBase(docName, 'acknowledged\n');
    state.recordStaleExternalWrite(docName, 'rejected\n');
    const list = await (await fetch(`${server.baseUrl}/api/sync/conflicts`)).json();
    expect(list.conflicts).toContainEqual(expect.objectContaining({ file }));
    const response = await fetch(
      `${server.baseUrl}/api/sync/conflict-content?file=${encodeURIComponent(file)}`,
    );
    expect(response.status).toBe(200);
    expect(await response.json()).toMatchObject({ ours: 'acknowledged\n', theirs: 'rejected\n' });
    expect((await resolveConflict(server, file, 'mine')).status).toBe(200);
    expect(readFileSync(join(server.contentDir, file), 'utf-8')).toBe('acknowledged\n');
    expect(state.getStaleExternalWrite(docName)).toBeUndefined();
  });

  test('an unloaded late-write snapshot exposes and restores the retained candidate', async () => {
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const docName = `retained-${randomUUID()}`;
    const state = server.instance.durabilityState;
    const retained = 'acknowledged\n\nnext edit retained\n';
    writeFileSync(join(server.contentDir, `${docName}.md`), 'rejected\n');
    state.setReconciledBase(docName, 'acknowledged\n');
    state.recordStaleExternalWrite(docName, 'rejected\n', retained);
    const sides = await (
      await fetch(`${server.baseUrl}/api/sync/conflict-content?file=${docName}.md`)
    ).json();
    expect(sides.ours).toBe(retained);
    expect((await resolveConflict(server, `${docName}.md`, 'mine')).status).toBe(200);
    expect(readTestDoc(server.contentDir, docName)).toBe(retained);
  });
  test.skip.each(['mine', 'content'])(
    'a repeated stale save after %s remains protected',
    {
      tags: ['quarantine'],
      meta: {
        issue: 'https://github.com/inkeep/agents-private/issues/5729',
        owner: 'get-main-green',
        until: '2026-12-01',
      },
    },
    async (strategy) => {
      server = await createTestServer({ debounce: 50, maxDebounce: 200 });
      const docName = `repeat-${randomUUID()}`;
      const { stale, acknowledged } = await acknowledgeWrite(server, docName);
      await restoreStale(server, docName, stale);
      expect((await resolveConflict(server, `${docName}.md`, strategy, acknowledged)).status).toBe(
        200,
      );
      expect(lifecycleOf(server, docName).status).toBeUndefined();
      await restoreStale(server, docName, stale);
      expect(lifecycleOf(server, docName).status).toBe('conflict');
      expect(getServerState(server, docName)?.ytext.toString()).toBe(acknowledged);
    },
  );

  test.skip.each(['theirs', 'delete'])(
    '%s resolves the stale conflict and updates disk and lifecycle',
    {
      tags: ['quarantine'],
      meta: {
        issue: 'https://github.com/inkeep/agents-private/issues/5729',
        owner: 'get-main-green',
        until: '2026-12-01',
      },
    },
    async (strategy) => {
      server = await createTestServer({ debounce: 50, maxDebounce: 200 });
      const docName = `resolve-${randomUUID()}`;
      const { stale } = await acknowledgeWrite(server, docName);
      await restoreStale(server, docName, stale);
      const lifecycleStatuses = observeLifecycleStatuses(server, docName);
      expect((await resolveConflict(server, `${docName}.md`, strategy)).status).toBe(200);
      expect(server.instance.durabilityState.listStaleExternalWrites()).toEqual([]);
      expect(server.instance.durabilityState.isDisplacedVersion(docName, stale)).toBe(false);
      if (strategy === 'delete') {
        expect(existsSync(join(server.contentDir, `${docName}.md`))).toBe(false);
        expect(lifecycleStatuses).toContain('deleted-upstream');
        const tags = await (await fetch(`${server.baseUrl}/api/tags/stale-write-test`)).json();
        expect(tags.docs.map((entry: { docName: string }) => entry.docName)).not.toContain(docName);
      } else {
        expect(readTestDoc(server.contentDir, docName)).toBe(stale);
        expect(getServerState(server, docName)?.ytext.toString()).toBe(stale);
        expect(lifecycleOf(server, docName).status).toBeUndefined();
      }
    },
  );

  test.skip('a successful delete resolution leaves no resident document, so suppressing the self-delete must move that unload onto the resolution path', {
    tags: ['quarantine'],
    meta: {
      issue: 'https://github.com/inkeep/agents-private/issues/5729',
      owner: 'get-main-green',
      until: '2026-12-01',
    },
  }, async () => {
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const docName = `unload-${randomUUID()}`;
    const { stale } = await acknowledgeWrite(server, docName);
    await restoreStale(server, docName, stale);
    expect(server.instance.hocuspocus.documents.has(docName)).toBe(true);
    expect((await resolveConflict(server, `${docName}.md`, 'delete')).status).toBe(200);
    await pollUntil(
      () => server?.instance.hocuspocus.documents.has(docName) === false,
      15_000,
      25,
      `${docName} to be unloaded from hocuspocus.documents after its successful delete resolution`,
    );
  });

  test.skip('an unloaded stale write is listed, and delete then restore starts fresh', {
    tags: ['quarantine'],
    meta: {
      issue: 'https://github.com/inkeep/agents-private/issues/5729',
      owner: 'get-main-green',
      until: '2026-12-01',
    },
  }, async () => {
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const docName = `unloaded-${randomUUID()}`;
    const { stale, acknowledged } = await acknowledgeWrite(server, docName);
    await unloadDocument(server, docName);
    await restoreStale(server, docName, stale);
    expect(server.instance.hocuspocus.documents.has(docName)).toBe(false);
    const conflicts = await (await fetch(`${server.baseUrl}/api/sync/conflicts`)).json();
    expect(conflicts.conflicts).toContainEqual(expect.objectContaining({ file: `${docName}.md` }));
    const sides = await (
      await fetch(`${server.baseUrl}/api/sync/conflict-content?file=${docName}.md`)
    ).json();
    expect(sides.ours).toBe(acknowledged);
    unlinkSync(join(server.contentDir, `${docName}.md`));
    await pollUntil(
      () => server?.instance.durabilityState.getReconciledBase(docName) === undefined,
    );
    expect(server.instance.durabilityState.listStaleExternalWrites()).toEqual([]);
    writeFileSync(join(server.contentDir, `${docName}.md`), stale, 'utf-8');
    const client = await createTestClient(server.port, docName);
    try {
      expect(client.ytext.toString()).toBe(stale);
      expect(lifecycleOf(server, docName).status).toBeUndefined();
      expect(server.instance.durabilityState.getReconciledBase(docName)).toBe(stale);
      await pollUntil(async () => {
        const tags = await (await fetch(`${server?.baseUrl}/api/tags/stale-write-test`)).json();
        return tags.docs.some((entry: { docName: string }) => entry.docName === docName);
      });
    } finally {
      await client.cleanup();
    }
  });

  test.skip('conflict paths round-trip when content is a project subdirectory', {
    tags: ['quarantine'],
    meta: {
      issue: 'https://github.com/inkeep/agents-private/issues/5729',
      owner: 'get-main-green',
      until: '2026-12-01',
    },
  }, async () => {
    ownedProjectDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-stale-subdir-')));
    const contentDir = join(ownedProjectDir, 'notes');
    mkdirSync(contentDir);
    server = await createTestServer({
      contentDir,
      projectDir: ownedProjectDir,
      debounce: 50,
      maxDebounce: 200,
    });
    const docName = `subdir-${randomUUID()}`;
    const { stale } = await acknowledgeWrite(server, docName);
    await restoreStale(server, docName, stale);
    const list = await (await fetch(`${server.baseUrl}/api/sync/conflicts`)).json();
    const file = `notes/${docName}.md`;
    expect(list.conflicts).toContainEqual(expect.objectContaining({ file }));
    const response = await fetch(
      `${server.baseUrl}/api/sync/conflict-content?file=${encodeURIComponent(file)}`,
    );
    expect(response.status).toBe(200);
    expect((await response.json()).ours).toContain(ACK_MARKER);
    expect((await resolveConflict(server, file, 'mine')).status).toBe(200);
    expect(readTestDoc(contentDir, docName)).toContain(ACK_MARKER);
  });

  test('resolution preserves an in-tree symlink and restores a missing file from recorded theirs', async () => {
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const docName = `alias-${randomUUID()}`;
    const target = join(server.contentDir, `${docName}-target.md`);
    const alias = join(server.contentDir, `${docName}.md`);
    writeFileSync(target, 'stale\n');
    symlinkSync(target, alias);
    const state = server.instance.durabilityState;
    state.setReconciledBase(docName, 'acknowledged\n');
    state.recordDisplacedVersion(docName, 'stale\n');
    state.recordStaleExternalWrite(docName, 'stale\n');
    expect((await resolveConflict(server, `${docName}.md`, 'mine')).status).toBe(200);
    expect(lstatSync(alias).isSymbolicLink()).toBe(true);
    expect(readFileSync(target, 'utf-8')).toBe('acknowledged\n');
    const missingDoc = `missing-${randomUUID()}`;
    state.setReconciledBase(missingDoc, 'acknowledged\n');
    state.recordStaleExternalWrite(missingDoc, 'stale\n');
    expect((await resolveConflict(server, `${missingDoc}.md`, 'theirs')).status).toBe(200);
    expect(readTestDoc(server.contentDir, missingDoc)).toBe('stale\n');
    const danglingDoc = `dangling-${randomUUID()}`;
    const danglingTarget = join(server.contentDir, `${danglingDoc}-target.md`);
    const danglingAlias = join(server.contentDir, `${danglingDoc}.md`);
    symlinkSync(danglingTarget, danglingAlias);
    state.setReconciledBase(danglingDoc, 'acknowledged\n');
    state.recordStaleExternalWrite(danglingDoc, 'stale\n');
    expect((await resolveConflict(server, `${danglingDoc}.md`, 'theirs')).status).toBe(200);
    expect(lstatSync(danglingAlias).isSymbolicLink()).toBe(true);
    expect(readFileSync(danglingTarget, 'utf-8')).toBe('stale\n');
    expect(state.listStaleExternalWrites()).toEqual([]);
  });

  test.skip('a delete resolution removes an in-tree symlink at the alias and the watcher attributes it there, not at its target', {
    tags: ['quarantine'],
    meta: {
      issue: 'https://github.com/inkeep/agents-private/issues/5729',
      owner: 'get-main-green',
      until: '2026-12-01',
    },
  }, async () => {
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const docName = `alias-delete-${randomUUID()}`;
    const target = join(server.contentDir, `${docName}-target.md`);
    const alias = join(server.contentDir, `${docName}.md`);
    writeFileSync(target, 'stale\n');
    symlinkSync(target, alias);
    await awaitWatcherObservationOfDoc(docName);
    const state = server.instance.durabilityState;
    state.setReconciledBase(docName, 'acknowledged\n');
    state.recordStaleExternalWrite(docName, 'stale\n');
    const ringOffset = getWatcherDecisionRingSnapshot().length;
    expect((await resolveConflict(server, `${docName}.md`, 'delete')).status).toBe(200);
    expect(existsSync(alias)).toBe(false);
    expect(readFileSync(target, 'utf-8')).toBe('stale\n');
    await awaitWatcherDecisionForDoc(docName, ringOffset);
  });

  test('a failed disk write leaves the acknowledged document and conflict unchanged', async () => {
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const docName = `directory-${randomUUID()}`;
    const file = join(server.contentDir, `${docName}.md`);
    mkdirSync(file);
    const state = server.instance.durabilityState;
    state.setReconciledBase(docName, 'acknowledged\n');
    state.recordStaleExternalWrite(docName, 'stale\n');
    const failed = await resolveConflict(server, `${docName}.md`, 'content', 'replacement\n');
    expect(failed.status).toBe(500);
    expect(server.instance.conflicts.has(docName)).toBe(true);
    expect(state.getReconciledBase(docName)).toBe('acknowledged\n');
    expect(state.getStaleExternalWrite(docName)?.diskContent).toBe('stale\n');
    expect(lstatSync(file).isDirectory()).toBe(true);
  });

  test('a delete resolution whose unlink fails leaves no removal declared', async () => {
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const docName = `unlink-fail-${randomUUID()}`;
    const file = join(server.contentDir, `${docName}.md`);
    mkdirSync(file);
    const state = server.instance.durabilityState;
    state.setReconciledBase(docName, 'acknowledged\n');
    state.recordStaleExternalWrite(docName, 'stale\n');

    const declared = vi.spyOn(removalTracker, 'set');
    try {
      const failed = await resolveConflict(server, `${docName}.md`, 'delete');
      expect(failed.status).toBe(500);
      expect(lstatSync(file).isDirectory()).toBe(true);
      expect(declared).toHaveBeenCalledWith(
        join(realpathSync(server.contentDir), `${docName}.md`),
        expect.any(Number),
      );
    } finally {
      declared.mockRestore();
    }
    expect(isSelfRemoval(join(realpathSync(server.contentDir), `${docName}.md`))).toBe(false);

    rmSync(file, { recursive: true });
  });

  test.skip.each(['mine', 'delete'])(
    'a durability filesystem failure during %s keeps the conflict retryable',
    {
      tags: ['quarantine'],
      meta: {
        issue: 'https://github.com/inkeep/agents-private/issues/5729',
        owner: 'get-main-green',
        until: '2026-12-01',
      },
    },
    async (strategy) => {
      server = await createTestServer({ debounce: 50, maxDebounce: 200 });
      const docName = `retry-${randomUUID()}`;
      const { stale, acknowledged } = await acknowledgeWrite(server, docName);
      await restoreStale(server, docName, stale);
      const statePath = join(server.instance.lockDir, 'stale-external-writes.json');
      renameSync(statePath, `${statePath}.backup`);
      mkdirSync(statePath);
      const ringOffset = getWatcherDecisionRingSnapshot().length;
      const failed = await resolveConflict(server, `${docName}.md`, strategy);
      expect(failed.status).toBe(500);
      expect((await failed.json()).detail).toBeTruthy();
      if (strategy === 'delete') await awaitWatcherDecisionForDoc(docName, ringOffset);
      expect.soft(server.instance.durabilityState.getStaleExternalWrite(docName)).toBeDefined();
      expect.soft(lifecycleStatusOf(server, docName)).toBe('conflict');
      if (strategy === 'mine')
        expect.soft(readTestDoc(server.contentDir, docName)).toBe(acknowledged);
      else expect.soft(existsSync(join(server.contentDir, `${docName}.md`))).toBe(false);
      rmSync(statePath, { recursive: true });
      renameSync(`${statePath}.backup`, statePath);
      const retry = await resolveConflict(server, `${docName}.md`, 'mine');
      expect(retry.status).toBe(200);
      expect(await retry.json()).toEqual({});
      expect(server.instance.durabilityState.getStaleExternalWrite(docName)).toBeUndefined();
      expect(lifecycleStatusOf(server, docName)).toBeUndefined();
    },
  );

  test('resolution refuses an escaping symlink without modifying its target', async () => {
    ownedProjectDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-stale-outside-')));
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const docName = `escape-${randomUUID()}`;
    const outside = join(ownedProjectDir, 'outside.md');
    writeFileSync(outside, 'outside\n');
    symlinkSync(outside, join(server.contentDir, `${docName}.md`));
    const state = server.instance.durabilityState;
    state.setReconciledBase(docName, 'acknowledged\n');
    state.recordStaleExternalWrite(docName, 'stale\n');
    for (const strategy of ['mine', 'theirs', 'content', 'delete']) {
      const response = await resolveConflict(server, `${docName}.md`, strategy, 'replacement\n');
      expect(response.status).toBe(400);
      expect(await response.json()).toMatchObject({
        status: 400,
        type: 'urn:ok:error:path-escape',
      });
      expect(readFileSync(outside, 'utf-8')).toBe('outside\n');
      expect(state.getStaleExternalWrite(docName)).toBeDefined();
    }
  });
  test('exact pre-write bytes restored on disk keep the acknowledged append and conflict the doc', async () => {
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const { port, contentDir } = server;
    const docName = `stale-rollback-${randomUUID()}`;

    await agentWriteMd(port, '# Doc\n\noriginal-body\n', { docName, position: 'replace' });
    await pollUntil(() => readTestDoc(contentDir, docName).includes('original-body'));
    const staleBytes = readTestDoc(contentDir, docName);

    await agentWriteMd(port, `${ACK_MARKER}\n`, { docName, position: 'append' });
    await pollUntil(() => readTestDoc(contentDir, docName).includes(ACK_MARKER));

    await wait(STALE_WRITE_DELAY_MS);
    writeFileSync(join(contentDir, `${docName}.md`), staleBytes, 'utf-8');

    await pollUntil(
      () => lifecycleOf(server as TestServer, docName).status === 'conflict',
      10_000,
      100,
      'stale-write lifecycle conflict',
    );

    expect(lifecycleOf(server, docName).reason).toBe('stale-external-write');
    expect(getServerState(server, docName)?.ytext.toString()).toContain(ACK_MARKER);

    const retry = await fetch(`http://127.0.0.1:${port}/api/agent-write-md`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ docName, markdown: 'retry\n', position: 'append' }),
    });
    expect(retry.status).toBe(409);

    const conflictsResponse = await fetch(`http://127.0.0.1:${port}/api/sync/conflicts`);
    const conflicts = (await conflictsResponse.json()) as {
      conflicts: Array<{
        file: string;
        detectedAt: string;
        conflictKind?: 'git' | 'stale-external-write';
      }>;
    };
    expect(conflicts.conflicts).toContainEqual(
      expect.objectContaining({
        file: `${docName}.md`,
        detectedAt: expect.any(String),
        conflictKind: 'stale-external-write',
      }),
    );

    const contentResponse = await fetch(
      `http://127.0.0.1:${port}/api/sync/conflict-content?file=${docName}.md&source=ytext`,
    );
    const sides = (await contentResponse.json()) as {
      ours: string;
      theirs: string;
      conflictKind?: 'git' | 'stale-external-write';
    };
    expect(sides.ours).toContain(ACK_MARKER);
    expect(sides.theirs).toBe(staleBytes);
    expect(sides.conflictKind).toBe('stale-external-write');

    for (const request of [
      { file: docName, strategy: 'mine' },
      {
        file: docName,
        strategy: 'content',
        content: '<<<<<<< current\ndraft\n=======\nstill unresolved\n>>>>>>> incoming\n',
      },
    ]) {
      const aliasResolution = await fetch(`http://127.0.0.1:${port}/api/sync/resolve-conflict`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(request),
      });
      expect(aliasResolution.status).toBe(404);
      expect(await aliasResolution.json()).toMatchObject({
        type: 'urn:ok:error:no-conflict-tracked',
      });
      expect(lifecycleOf(server, docName).status).toBe('conflict');
      expect(readTestDoc(contentDir, docName)).toBe(staleBytes);
      expect(getServerState(server, docName)?.ytext.toString()).toContain(ACK_MARKER);
    }

    const markerResolution = await resolveConflict(
      server,
      `${docName}.md`,
      'content',
      '<<<<<<< current\ndraft\n=======\nstill unresolved\n>>>>>>> incoming\n',
    );
    expect(markerResolution.status).toBe(422);
    expect(lifecycleOf(server, docName).status).toBe('conflict');

    const resolution = await resolveConflict(server, `${docName}.md`, 'content', sides.ours);
    expect(resolution.status).toBe(200);
    expect(readTestDoc(contentDir, docName)).toContain(ACK_MARKER);
    expect(lifecycleOf(server, docName).status).toBeUndefined();

    writeFileSync(join(contentDir, `${docName}.md`), staleBytes, 'utf-8');
    await pollUntil(
      () => lifecycleOf(server as TestServer, docName).status === 'conflict',
      10_000,
      100,
      'repeated stale-write lifecycle conflict',
    );

    const repeatedResolution = await resolveConflict(server, `${docName}.md`, 'mine');
    expect(repeatedResolution.status).toBe(200);

    await agentWriteMd(port, 'retry-after-resolution\n', { docName, position: 'append' });
    await pollUntil(() => readTestDoc(contentDir, docName).includes('retry-after-resolution'));
  });

  test.skip('content resolution accepts a Setext heading and preserves the submitted bytes', {
    tags: ['quarantine'],
    meta: {
      issue: 'https://github.com/inkeep/agents-private/issues/5729',
      owner: 'get-main-green',
      until: '2026-12-01',
    },
  }, async () => {
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const docName = `setext-resolution-${randomUUID()}`;
    const { stale, acknowledged } = await acknowledgeWrite(server, docName);
    await restoreStale(server, docName, stale);

    const content = `Release notes\n=======\n\n${acknowledged}`;
    const response = await resolveConflict(server, `${docName}.md`, 'content', content);

    expect(response.status).toBe(200);
    expect(readTestDoc(server.contentDir, docName)).toBe(content);
    expect(getServerState(server, docName)?.ytext.toString()).toBe(content);
    expect(lifecycleOf(server, docName).status).toBeUndefined();
    expect(server.instance.durabilityState.getStaleExternalWrite(docName)).toBeUndefined();
  });

  test('an unrelated external edit still reconciles into the Y.Doc', async () => {
    server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const { port, contentDir } = server;
    const docName = `unrelated-external-${randomUUID()}`;

    await agentWriteMd(port, '# Doc\n\noriginal-body\n', { docName, position: 'replace' });
    await pollUntil(() => readTestDoc(contentDir, docName).includes('original-body'));

    await agentWriteMd(port, `${ACK_MARKER}\n`, { docName, position: 'append' });
    await pollUntil(() => readTestDoc(contentDir, docName).includes(ACK_MARKER));

    await wait(STALE_WRITE_DELAY_MS);
    const settled = readTestDoc(contentDir, docName);
    writeFileSync(join(contentDir, `${docName}.md`), `${settled}\nEXTERNAL-EDIT-LINE\n`, 'utf-8');

    await pollUntil(
      () =>
        getServerState(server as TestServer, docName)
          ?.ytext.toString()
          .includes('EXTERNAL-EDIT-LINE') === true,
      10_000,
      100,
      'unrelated external edit applied',
    );

    expect(lifecycleOf(server, docName).status).toBeUndefined();
  });

  test('a restart keeps the acknowledged content and stale-write conflict', async () => {
    server = await createTestServer({
      debounce: 50,
      maxDebounce: 200,
      keepContentDir: true,
    });
    const docName = `stale-restart-${randomUUID()}`;
    const contentDir = server.contentDir;

    await agentWriteMd(server.port, '# Doc\n\noriginal-body\n', {
      docName,
      position: 'replace',
    });
    await pollUntil(() => readTestDoc(contentDir, docName).includes('original-body'));
    const staleBytes = readTestDoc(contentDir, docName);
    await agentWriteMd(server.port, `${ACK_MARKER}\n`, { docName, position: 'append' });
    await pollUntil(() => readTestDoc(contentDir, docName).includes(ACK_MARKER));
    await wait(STALE_WRITE_DELAY_MS);
    writeFileSync(join(contentDir, `${docName}.md`), staleBytes, 'utf-8');
    await pollUntil(
      () => lifecycleOf(server as TestServer, docName).status === 'conflict',
      10_000,
      100,
      'pre-restart stale-write lifecycle conflict',
    );

    await server.cleanup();
    server = undefined;
    server = await createTestServer({ contentDir, debounce: 50, maxDebounce: 200 });
    const client = await createTestClient(server.port, docName);
    try {
      expect(client.ytext.toString()).toContain(ACK_MARKER);
      expect(lifecycleOf(server, docName)).toMatchObject({
        status: 'conflict',
        kind: 'reconcile',
        reason: 'stale-external-write',
      });
    } finally {
      await client.cleanup();
    }
  });
});