mixdog 0.9.54 → 0.9.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.54",
+  "version": "0.9.55",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",
@@ -85,6 +85,7 @@
     "bench:corpus": "node scripts/routing-corpus.mjs",
     "bench:run": "node scripts/bench-run.mjs",
     "bench:recall": "node scripts/recall-bench.mjs",
+    "bench:tui-load": "node scripts/tui-runtime-load-bench.mjs",
     "audit:models": "node scripts/model-catalog-audit.mjs",
     "patch:replay": "node scripts/patch-replay.mjs",
     "build:tui": "node scripts/build-tui.mjs",

package/scripts/desktop-session-bridge-test.mjs

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, unl
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
 
 import {
   _normalizeSummaryIndex,
@@ -23,9 +24,55 @@ import {
   markSessionClosed,
   saveSession,
   saveSessionAsync,
+  saveSessionAsyncDeferred,
   setLiveSession,
 } from '../src/runtime/agent/orchestrator/session/store.mjs';
 
+test('deferred terminal save is registered for immediate exit drain', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'mixdog-deferred-terminal-'));
+  const previousDataDir = process.env.MIXDOG_DATA_DIR;
+  process.env.MIXDOG_DATA_DIR = root;
+  try {
+    const session = {
+      id: 'deferred_terminal_exit',
+      owner: 'user',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      messages: [{ role: 'assistant', content: 'terminal state' }],
+    };
+    const pending = saveSessionAsyncDeferred(session);
+    drainSessionStore();
+    await pending;
+    assert.equal(loadSession(session.id)?.messages?.[0]?.content, 'terminal state');
+  } finally {
+    drainSessionStore();
+    if (previousDataDir == null) delete process.env.MIXDOG_DATA_DIR;
+    else process.env.MIXDOG_DATA_DIR = previousDataDir;
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('exit drain writes deferred terminal state after an older worker-pending save', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'mixdog-deferred-order-'));
+  try {
+    const storeUrl = new URL('../src/runtime/agent/orchestrator/session/store.mjs', import.meta.url).href;
+    const output = execFileSync(process.execPath, ['--input-type=module', '-e', `
+      process.env.MIXDOG_DATA_DIR = ${JSON.stringify(root)};
+      const { saveSessionAsync, saveSessionAsyncDeferred, drainSessionStore, loadSession } = await import(${JSON.stringify(storeUrl)});
+      const base = { id: 'deferred_order_exit', owner: 'user', createdAt: Date.now(), updatedAt: Date.now() };
+      saveSessionAsync({ ...base, messages: [{ role: 'assistant', content: 'older worker snapshot' }], padding: 'x'.repeat(2_000_000) }).catch(() => {});
+      const terminal = saveSessionAsyncDeferred({ ...base, updatedAt: Date.now() + 1, messages: [{ role: 'assistant', content: 'newest terminal snapshot' }] });
+      drainSessionStore();
+      await Promise.allSettled([terminal]);
+      process.stdout.write(loadSession(base.id)?.messages?.[0]?.content || '');
+      process.exit(0);
+    `], { encoding: 'utf8' });
+    assert.equal(output, 'newest terminal snapshot');
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('desktop classification is optional and round-trips through the existing summary index', () => {
   const task = _sessionSummary({
     id: 'lead_task',

package/scripts/interrupted-turn-history-test.mjs

@@ -5,6 +5,7 @@ import { mkdtempSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { compactedOutgoingPromptRetained } from '../src/runtime/agent/orchestrator/session/manager/message-sanitize.mjs';
 
 process.env.MIXDOG_AGENT_TRACE_DISABLE = '1';
 const DATA_DIR = mkdtempSync(join(tmpdir(), 'mixdog-interrupted-turn-'));
@@ -16,6 +17,12 @@ const TOOL_USE_INTERRUPTION_MESSAGE = '[Request interrupted by user for tool use
 const STREAMING_INTERRUPTED_TOOL_RESULT = 'Interrupted by user';
 const TOOL_USE_REJECT_RESULT = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
 
+test('unchanged failed-turn snapshot reports an already-retained queued prompt', () => {
+    const messages = [{ role: 'user', content: 'queued prompt already in preflight session' }];
+    assert.equal(compactedOutgoingPromptRetained(messages, messages), true);
+    assert.equal(compactedOutgoingPromptRetained([], messages), false);
+});
+
 function deferred() {
     let resolve;
     const promise = new Promise((done) => { resolve = done; });
@@ -44,6 +51,7 @@ test('interrupted turns keep Claude Code-compatible model history boundaries', {
         getSession,
     } = await import('../src/runtime/agent/orchestrator/session/manager.mjs');
     const { saveSessionAsync } = await import('../src/runtime/agent/orchestrator/session/store.mjs');
+    const { enqueuePendingMessage } = await import('../src/runtime/agent/orchestrator/session/manager/pending-messages.mjs');
 
     const createTestSession = (tools = []) => createSession({
         provider: 'gemini',
@@ -79,6 +87,26 @@ test('interrupted turns keep Claude Code-compatible model history boundaries', {
         assert.equal(persisted.liveTurnMessages, null);
     });
 
+    await t.test('released queued IDs keep their spool copy after cancellation rewinds the prompt', async () => {
+        const session = createTestSession();
+        enqueuePendingMessage(session.id, 'queued prompt must replay');
+        await new Promise((resolve) => setImmediate(resolve));
+        await new Promise((resolve) => setTimeout(resolve, 30));
+        const entered = deferred();
+        provider.send = async (_messages, _model, _tools, opts) => {
+            entered.resolve();
+            return waitForAbort(opts);
+        };
+        const asking = askSession(session.id, '', null, null, process.cwd());
+        await entered.promise;
+        abortSessionTurn(session.id, 'user-cancel');
+        await expectInterrupted(asking);
+        await new Promise((resolve) => setTimeout(resolve, 30));
+        const spool = JSON.parse(readFileSync(join(DATA_DIR, 'session-pending-messages.json'), 'utf8'));
+        assert.equal(spool.sessions[session.id]?.length, 1);
+        assert.equal(spool.sessions[session.id][0].message, 'queued prompt must replay');
+    });
+
     await t.test('streaming: preserves a partial response without a newline', async () => {
         const session = createTestSession();
         const streamed = deferred();

package/scripts/pending-completion-drop-test.mjs

@@ -6,7 +6,7 @@
 // Genuine user/steering messages survive with order preserved in both paths.
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { mkdtempSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -18,10 +18,16 @@ process.env.MIXDOG_DATA_DIR = dataDir;
 const {
   enqueuePendingMessage,
   drainPendingMessages,
+  hydratePendingMessages,
+  acknowledgePendingMessages,
+  recordPendingMessageDelivery,
+  finalizePendingMessageDelivery,
+  releasePendingMessages,
   COMPLETION_NOTIFICATION_KIND,
   markCompletionEntry,
   _dropPendingMessageState,
 } = await import('../src/runtime/agent/orchestrator/session/manager/pending-messages.mjs');
+const texts = (entries) => entries.map((m) => (typeof m === 'string' ? m : m.text));
 
 test('live drain delivers the completion notification and keeps user order', () => {
   const sid = 'sess_live_1';
@@ -30,10 +36,12 @@ test('live drain delivers the completion notification and keeps user order', ()
   enqueuePendingMessage(sid, 'user second');
 
   // In-memory queue is populated (live, same process) → completion survives.
-  const drained = drainPendingMessages(sid).map((m) => (typeof m === 'string' ? m : m.text));
+  const delivered = drainPendingMessages(sid);
+  const drained = texts(delivered);
   assert.ok(drained.includes('user first') && drained.includes('user second'), 'user messages kept');
   assert.ok(drained.some((t) => /finished/.test(t)), 'live completion delivered, not dropped');
   assert.ok(drained.indexOf('user first') < drained.indexOf('user second'), 'user order preserved');
+  acknowledgePendingMessages(sid, delivered);
 });
 
 test('live drain preserves interleaved [user, completion, user] order', () => {
@@ -46,12 +54,28 @@ test('live drain preserves interleaved [user, completion, user] order', () => {
   enqueuePendingMessage(sid, markCompletionEntry('Async agent task zzz finished.\n\nResult:\n> done'));
   enqueuePendingMessage(sid, 'user second');
 
-  const drained = drainPendingMessages(sid).map((m) => (typeof m === 'string' ? m : m.text));
+  const delivered = drainPendingMessages(sid);
+  const drained = texts(delivered);
   const first = drained.indexOf('user first');
   const second = drained.indexOf('user second');
   const completion = drained.findIndex((t) => /finished/.test(t));
   assert.ok(completion !== -1, 'completion present in live drain');
   assert.ok(first < completion && completion < second, 'completion stays between the two users');
+  acknowledgePendingMessages(sid, delivered);
+});
+
+test('live drain asynchronously removes already-flushed persisted copies', async () => {
+  const sid = 'sess_live_flushed';
+  enqueuePendingMessage(sid, 'already flushed');
+  await new Promise((r) => setImmediate(r));
+  await new Promise((r) => setTimeout(r, 30));
+
+  const delivered = drainPendingMessages(sid);
+  assert.deepEqual(texts(delivered), ['already flushed']);
+  acknowledgePendingMessages(sid, delivered);
+  await new Promise((r) => setTimeout(r, 30));
+  const store = JSON.parse(readFileSync(join(dataDir, 'session-pending-messages.json'), 'utf8'));
+  assert.equal(store.sessions[sid], undefined, 'delivered live copy removed without a sync drain');
 });
 
 test('resume drain drops the completion notification, keeps user messages in order', async () => {
@@ -70,14 +94,146 @@ test('resume drain drops the completion notification, keeps user messages in ord
   assert.equal(marked.length, 1, 'completion notification persisted as a marked object');
   _dropPendingMessageState(sid, { clearPersisted: false });
 
-  const drained = drainPendingMessages(sid).map((m) => (typeof m === 'string' ? m : m.text));
+  await hydratePendingMessages(sid);
+  const delivered = drainPendingMessages(sid);
+  const drained = texts(delivered);
   assert.deepEqual(drained, ['user first', 'user second'], 'completion dropped on resume; user order kept');
   assert.ok(!drained.some((t) => /finished/.test(t)), 'no completion prose replayed on resume');
+  acknowledgePendingMessages(sid, delivered);
 
   // A second drain yields nothing — the completion was discarded, not deferred.
   assert.deepEqual(drainPendingMessages(sid), []);
 });
 
+test('hydrate crash before publish leaves durable entries for replay', async () => {
+  const sid = 'sess_hydrate_crash';
+  enqueuePendingMessage(sid, 'survives crash window');
+  await new Promise((r) => setImmediate(r));
+  await new Promise((r) => setTimeout(r, 30));
+  await hydratePendingMessages(sid, { beforePublish: () => { throw new Error('simulated crash'); } });
+  const store = JSON.parse(readFileSync(join(dataDir, 'session-pending-messages.json'), 'utf8'));
+  assert.equal(store.sessions[sid].length, 1, 'hydrate never deletes before memory publish');
+  await hydratePendingMessages(sid);
+  const delivered = drainPendingMessages(sid);
+  assert.deepEqual(texts(delivered), ['survives crash window']);
+  acknowledgePendingMessages(sid, delivered);
+});
+
+test('ids preserve identical foreign messages and dedupe only replay copies', async () => {
+  const sid = 'sess_identical_ids';
+  enqueuePendingMessage(sid, 'identical');
+  enqueuePendingMessage(sid, 'identical');
+  await new Promise((r) => setImmediate(r));
+  await new Promise((r) => setTimeout(r, 30));
+  await hydratePendingMessages(sid);
+  const delivered = drainPendingMessages(sid);
+  assert.equal(delivered.length, 2, 'same text with distinct ids is delivered twice');
+  assert.notEqual(delivered[0].id, delivered[1].id);
+  acknowledgePendingMessages(sid, [delivered[0]]);
+  releasePendingMessages(sid, [delivered[1]]);
+  await new Promise((r) => setTimeout(r, 30));
+  const store = JSON.parse(readFileSync(join(dataDir, 'session-pending-messages.json'), 'utf8'));
+  assert.deepEqual(store.sessions[sid].map((entry) => entry.id), [delivered[1].id], 'ack removes only the matching id');
+});
+
+test('post-completion hydration sweep picks up a late foreign spool entry', async () => {
+  const sid = 'sess_late_foreign';
+  await hydratePendingMessages(sid);
+  const spool = join(dataDir, 'session-pending-messages.json');
+  const store = JSON.parse(readFileSync(spool, 'utf8'));
+  store.sessions[sid] = [{ id: 'foreign_late_id', message: 'late foreign message', enqueuedAt: Date.now() }];
+  store.sessionTouchedAt[sid] = Date.now();
+  writeFileSync(spool, JSON.stringify(store));
+
+  assert.equal(await hydratePendingMessages(sid), 1);
+  const delivered = drainPendingMessages(sid);
+  assert.deepEqual(texts(delivered), ['late foreign message']);
+  acknowledgePendingMessages(sid, delivered);
+});
+
+test('enqueue replaces caller ids and delivery tracking stays session-scoped', () => {
+  const firstSid = 'sess_untrusted_id_a';
+  const secondSid = 'sess_untrusted_id_b';
+  enqueuePendingMessage(firstSid, { id: 'caller_id', content: 'first', text: 'first' });
+  enqueuePendingMessage(secondSid, { id: 'caller_id', content: 'second', text: 'second' });
+  const first = drainPendingMessages(firstSid);
+  const second = drainPendingMessages(secondSid);
+  assert.notEqual(first[0].id, 'caller_id');
+  assert.notEqual(second[0].id, 'caller_id');
+  assert.notEqual(first[0].id, second[0].id);
+  releasePendingMessages(firstSid, first);
+  releasePendingMessages(secondSid, second);
+});
+
+test('over-512 unconfirmed ledger IDs are retained and suppress restart replay', async () => {
+  const sid = 'sess_delivered_ledger';
+  const session = { id: sid, deliveredPendingMessageIds: [] };
+  const entries = Array.from({ length: 600 }, (_, i) => ({
+    id: `delivered_${i}`,
+    content: `message ${i}`,
+    text: `message ${i}`,
+    enqueuedAt: i + 1,
+  }));
+  recordPendingMessageDelivery(session, entries);
+  assert.equal(session.deliveredPendingMessageIds.length, 600, 'unconfirmed ids are never evicted');
+
+  const { saveSession, setLiveSession, loadSession } = await import('../src/runtime/agent/orchestrator/session/store.mjs');
+  saveSession({ ...session, owner: 'user', createdAt: Date.now(), updatedAt: Date.now(), messages: [] });
+  setLiveSession(null);
+  const spool = join(dataDir, 'session-pending-messages.json');
+  const store = JSON.parse(readFileSync(spool, 'utf8'));
+  store.sessions[sid] = [{ id: 'delivered_0', message: 'old surviving spool entry', enqueuedAt: Date.now() }];
+  store.sessionTouchedAt[sid] = Date.now();
+  writeFileSync(spool, JSON.stringify(store));
+  assert.equal(await hydratePendingMessages(sid), 0);
+  assert.deepEqual(drainPendingMessages(sid), []);
+  setLiveSession(null);
+  assert.equal(
+    loadSession(sid).deliveredPendingMessageIds.includes('delivered_0'),
+    false,
+    'restart cleanup prunes its now-confirmed id from the durable ledger',
+  );
+  assert.equal(loadSession(sid).deliveredPendingMessageIds.length, 0, 'spool-absent ledger ids are stale too');
+});
+
+test('hydration prunes a ledger id whose spool entry was already deleted', async () => {
+  const sid = 'sess_orphaned_ledger_id';
+  const { saveSession, setLiveSession, loadSession } = await import('../src/runtime/agent/orchestrator/session/store.mjs');
+  saveSession({
+    id: sid,
+    owner: 'user',
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    messages: [],
+    deliveredPendingMessageIds: ['cleanup_committed_before_crash'],
+  });
+  setLiveSession(null);
+  assert.equal(await hydratePendingMessages(sid), 0);
+  setLiveSession(null);
+  assert.deepEqual(loadSession(sid).deliveredPendingMessageIds, []);
+});
+
+test('spool cleanup waits for durable ledger save', async () => {
+  const sid = 'sess_durable_before_ack';
+  enqueuePendingMessage(sid, 'ordered cleanup');
+  await new Promise((r) => setImmediate(r));
+  await new Promise((r) => setTimeout(r, 30));
+  const delivered = drainPendingMessages(sid);
+  const session = { id: sid, deliveredPendingMessageIds: [] };
+  recordPendingMessageDelivery(session, delivered);
+  let releaseSave;
+  const durableSave = new Promise((resolve) => { releaseSave = resolve; });
+  const completing = finalizePendingMessageDelivery(session, delivered, durableSave);
+  await new Promise((r) => setImmediate(r));
+  let store = JSON.parse(readFileSync(join(dataDir, 'session-pending-messages.json'), 'utf8'));
+  assert.equal(store.sessions[sid].length, 1, 'spool remains until ledger save is durable');
+  releaseSave();
+  await completing;
+  store = JSON.parse(readFileSync(join(dataDir, 'session-pending-messages.json'), 'utf8'));
+  assert.equal(store.sessions[sid], undefined);
+  assert.deepEqual(session.deliveredPendingMessageIds, []);
+});
+
 test.after(() => {
   try { rmSync(dataDir, { recursive: true, force: true }); } catch { /* ignore */ }
 });

package/scripts/pending-messages-lock-nonblocking-test.mjs

@@ -0,0 +1,62 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, unlinkSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const dataDir = mkdtempSync(join(tmpdir(), 'mixpend-lock-'));
+process.env.MIXDOG_DATA_DIR = dataDir;
+
+const {
+  hydratePendingMessages,
+  drainPendingMessages,
+  acknowledgePendingMessages,
+} = await import('../src/runtime/agent/orchestrator/session/manager/pending-messages.mjs');
+
+test('held pending spool lock does not block the completion-loop drain', async () => {
+  const sid = 'sess_lock_held';
+  const spool = join(dataDir, 'session-pending-messages.json');
+  const lock = `${spool}.lock`;
+  // Let the module's one-shot orphan sweep complete before reproducing the
+  // runtime completion scenario; the debugger lock is acquired mid-session.
+  await new Promise((resolve) => setImmediate(resolve));
+  writeFileSync(spool, JSON.stringify({
+    version: 1,
+    updatedAt: Date.now(),
+    sessions: { [sid]: ['persisted steering'] },
+    sessionTouchedAt: { [sid]: Date.now() },
+  }));
+  // A live-pid foreign token is deliberately not stale-reclaimable.
+  writeFileSync(lock, `${process.pid} ${Date.now()} debugger-held-lock\n`);
+
+  const started = Date.now();
+  let loopTickAt = 0;
+  const loopTick = new Promise((resolve) => {
+    setTimeout(() => {
+      loopTickAt = Date.now();
+      resolve();
+    }, 25);
+  });
+  const hydration = hydratePendingMessages(sid);
+
+  // The terminal path is synchronous but now memory-only.
+  assert.deepEqual(drainPendingMessages(sid), []);
+  await loopTick;
+  assert.ok(loopTickAt - started < 250, `event loop stalled ${loopTickAt - started}ms`);
+
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  unlinkSync(lock);
+  await hydration;
+  const delivered = drainPendingMessages(sid);
+  assert.deepEqual(delivered.map((entry) => entry.text), ['persisted steering']);
+  const stored = JSON.parse(readFileSync(spool, 'utf8'));
+  assert.equal(stored.sessions[sid].length, 1, 'hydrate is read-only until delivery ack');
+  acknowledgePendingMessages(sid, delivered);
+  await new Promise((resolve) => setTimeout(resolve, 30));
+  const acknowledged = JSON.parse(readFileSync(spool, 'utf8'));
+  assert.equal(acknowledged.sessions[sid], undefined);
+});
+
+test.after(() => {
+  try { rmSync(dataDir, { recursive: true, force: true }); } catch {}
+});

package/scripts/process-lifecycle-test.mjs

@@ -289,7 +289,7 @@ test('concurrent writers serialize rotation', async () => {
       import { beginProcessLifecycle, finishProcessLifecycle, recordCatchableFatal } from './src/runtime/shared/process-lifecycle.mjs';
       beginProcessLifecycle({ directory: process.env.LEDGER_DIR, configureReports: false });
       for (let i = 0; i < 120; i++) recordCatchableFatal(1);
-      if (!finishProcessLifecycle('catchable-fatal-error', 1)) process.exit(4);
+      finishProcessLifecycle('catchable-fatal-error', 1);
     `;
     const children = Array.from({ length: 3 }, () => spawn(
       process.execPath,
@@ -306,10 +306,13 @@ test('concurrent writers serialize rotation', async () => {
       { code: 0, signal: null },
       { code: 0, signal: null },
     ]);
+    let records = 0;
     for (const path of [paths.ledger, paths.previousLedger]) {
+      if (!existsSync(path)) continue;
       assert.ok(readFileSync(path).byteLength <= LIFECYCLE_LEDGER_MAX_BYTES);
-      entries(path);
+      records += entries(path).length;
     }
+    assert.ok(records > 0);
     assert.equal(existsSync(paths.lock), false);
   } finally {
     rmSync(root, { recursive: true, force: true });

package/scripts/prompt-input-parity-test.mjs

@@ -0,0 +1,145 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  caretPosition,
+  offsetAtCell,
+  verticalOffset,
+} from '../src/tui/input-editing.mjs';
+import {
+  promptContentRows,
+  wrappedTextRows,
+} from '../src/tui/app/text-layout.mjs';
+
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+
+// Reference the pre-optimization behavior: enumerate every grapheme boundary,
+// then independently rescan its prefix through caretPosition().
+function referenceBoundaryPositions(text, width) {
+  const value = String(text || '');
+  const offsets = [0];
+  for (const { index, segment } of graphemeSegmenter.segment(value)) {
+    offsets.push(index + segment.length);
+  }
+  return [...new Set(offsets)]
+    .map((offset) => ({ offset, ...caretPosition(value, offset, width) }));
+}
+
+function referenceOffsetAtCell(text, row, col, width) {
+  const positions = referenceBoundaryPositions(text, width);
+  let best = positions[0];
+  let bestScore = Infinity;
+  for (const position of positions) {
+    const score = Math.abs(position.row - row) * 100000
+      + Math.abs(position.col - col);
+    if (score < bestScore) {
+      best = position;
+      bestScore = score;
+    }
+  }
+  return best.offset;
+}
+
+function referenceVerticalOffset(text, offset, width, direction, preferredColumn = null) {
+  const current = caretPosition(text, offset, width);
+  const targetColumn = Number.isFinite(preferredColumn) ? preferredColumn : current.col;
+  const targetRow = current.row + direction;
+  if (targetRow < 0) return { cursor: offset, preferredColumn: targetColumn };
+
+  const candidates = referenceBoundaryPositions(text, width)
+    .filter((position) => position.row === targetRow);
+  if (candidates.length === 0) return { cursor: offset, preferredColumn: targetColumn };
+
+  let best = candidates[0];
+  for (const candidate of candidates) {
+    const bestDistance = Math.abs(best.col - targetColumn);
+    const candidateDistance = Math.abs(candidate.col - targetColumn);
+    if (
+      candidateDistance < bestDistance
+      || (
+        candidateDistance === bestDistance
+        && candidate.col <= targetColumn
+        && candidate.col > best.col
+      )
+    ) {
+      best = candidate;
+    }
+  }
+  return { cursor: best.offset, preferredColumn: targetColumn };
+}
+
+const parityCases = [
+  { name: 'combining marks', text: 'Ae\u0301o\u0308Z' },
+  { name: 'emoji ZWJ sequences', text: 'a👨‍👩‍👧‍👦b👩🏽‍💻c' },
+  { name: 'wide CJK', text: 'ab界語cd漢字' },
+  { name: 'newlines at wrap boundaries', text: 'abc\n123456\n界a\nxyz' },
+  { name: 'trailing spaces', text: 'abc   \nxy  ' },
+  { name: 'tabs', text: 'a\tbc\t\n\tde' },
+  { name: 'ambiguous-width characters', text: 'A·Ω—α※B' },
+];
+
+test('mouse hit-testing matches prefix-rescan reference for complex graphemes and wrapping', () => {
+  const widths = [1, 2, 3, 4, 5, 7];
+  for (const { name, text } of parityCases) {
+    for (const width of widths) {
+      const positions = referenceBoundaryPositions(text, width);
+      const lastRow = Math.max(...positions.map((position) => position.row));
+      for (let row = -1; row <= lastRow + 2; row += 1) {
+        for (let col = -1; col <= width + 2; col += 1) {
+          assert.equal(
+            offsetAtCell(text, row, col, width),
+            referenceOffsetAtCell(text, row, col, width),
+            `${name}: width=${width}, row=${row}, col=${col}`,
+          );
+        }
+      }
+    }
+  }
+});
+
+test('prompt row cache stays isolated across alternating text and width keys', () => {
+  const alternatingPairs = [
+    ['x', 4],
+    ['abcdefghijkl', 4],
+    ['x', 4],
+    ['abc界', 3],
+    ['abc界', 7],
+    ['Ae\u0301o\u0308Z', 7],
+    ['abc界', 3],
+    ['Ae\u0301o\u0308Z', 2],
+    ['👨‍👩‍👧‍👦 trailing  ', 5],
+    ['abc界', 7],
+    ['👨‍👩‍👧‍👦 trailing  ', 1],
+    ['Ae\u0301o\u0308Z', 2],
+  ];
+
+  for (const [text, width] of alternatingPairs) {
+    assert.equal(
+      promptContentRows(text, width),
+      wrappedTextRows(`${text} `, width),
+      `prompt rows: text=${JSON.stringify(text)}, width=${width}`,
+    );
+  }
+});
+
+test('vertical navigation matches reference while widths alternate between calls', () => {
+  // Deliberately revisit values non-consecutively so a future single-entry
+  // boundary/layout cache cannot accidentally reuse positions from another width.
+  const alternatingWidths = [2, 7, 3, 6, 1, 5, 2, 4, 7, 3];
+  const preferredColumns = [null, 0, 1, 3, 8];
+  for (const { name, text } of parityCases) {
+    for (const width of alternatingWidths) {
+      for (let offset = 0; offset <= text.length; offset += 1) {
+        for (const direction of [-1, 1]) {
+          for (const preferredColumn of preferredColumns) {
+            assert.deepEqual(
+              verticalOffset(text, offset, width, direction, preferredColumn),
+              referenceVerticalOffset(text, offset, width, direction, preferredColumn),
+              `${name}: width=${width}, offset=${offset}, direction=${direction}, preferred=${preferredColumn}`,
+            );
+          }
+        }
+      }
+    }
+  }
+});