@semalt-ai/code 1.8.4 → 1.19.0

package/test/checkpoints.test.js

@@ -0,0 +1,650 @@
+'use strict';
+
+// Unit tests for the checkpoint store (Task 4.3). These drive the store DIRECTLY
+// (no agent loop) with a temp rootDir and an injected no-op audit, simulating
+// the executor seam: beginCapture (pre-mutation) → do the fs mutation →
+// commit() (post-mutation). The agent-loop / subagent integration lives in
+// test/checkpoints-agent.test.js.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  normalizeCheckpoints,
+  createCheckpointStore,
+  latestSession,
+  CHECKPOINTABLE_ACTIONS,
+  SCOPE_NOTICE,
+  REWIND_MODES,
+  normalizeRewindMode,
+  formatCheckpointList,
+  formatRewindResult,
+  findOrphanedToolCalls,
+  snapToTurnBoundary,
+  locateTurnStart,
+  planConversationRewind,
+} = require('../lib/checkpoints');
+
+const { DEFAULT_CHECKPOINT_MAX_FILE_BYTES, DEFAULT_CHECKPOINT_MAX_PER_SESSION } = require('../lib/constants');
+
+const NOOP_AUDIT = { logCheckpoint: () => {} };
+
+function tmpdir(tag = 'cp') { return fs.mkdtempSync(path.join(os.tmpdir(), `semalt-${tag}-`)); }
+
+// Build a store over a fresh temp rootDir with a fixed session and a config.
+function makeStore(checkpoints = {}, { sessionId = 'sess1', fsImpl, restoreGuard } = {}) {
+  const root = tmpdir('cproot');
+  const store = createCheckpointStore({
+    getConfig: () => ({ checkpoints }),
+    sessionId,
+    rootDir: root,
+    audit: NOOP_AUDIT,
+    fs: fsImpl,
+    restoreGuard,
+  });
+  return { store, root };
+}
+
+// ---------------------------------------------------------------------------
+// normalizeCheckpoints
+// ---------------------------------------------------------------------------
+
+test('normalizeCheckpoints: defaults', () => {
+  const c = normalizeCheckpoints(undefined);
+  assert.strictEqual(c.enabled, true);
+  assert.strictEqual(c.max_file_bytes, DEFAULT_CHECKPOINT_MAX_FILE_BYTES);
+  assert.strictEqual(c.max_per_session, DEFAULT_CHECKPOINT_MAX_PER_SESSION);
+});
+
+test('normalizeCheckpoints: enabled:false honored; invalid numbers fall back', () => {
+  const c = normalizeCheckpoints({ enabled: false, max_file_bytes: -3, max_per_session: 'x' });
+  assert.strictEqual(c.enabled, false);
+  assert.strictEqual(c.max_file_bytes, DEFAULT_CHECKPOINT_MAX_FILE_BYTES);
+  assert.strictEqual(c.max_per_session, DEFAULT_CHECKPOINT_MAX_PER_SESSION);
+});
+
+test('normalizeCheckpoints: valid overrides applied', () => {
+  const c = normalizeCheckpoints({ max_file_bytes: 1234, max_per_session: 5 });
+  assert.strictEqual(c.max_file_bytes, 1234);
+  assert.strictEqual(c.max_per_session, 5);
+});
+
+test('checkpointable action set covers all mutating file tools', () => {
+  for (const a of ['write', 'append', 'edit_file', 'replace_in_file', 'delete_file', 'move_file', 'copy_file', 'upload']) {
+    assert.ok(CHECKPOINTABLE_ACTIONS.has(a), `${a} should be checkpointable`);
+  }
+  assert.ok(!CHECKPOINTABLE_ACTIONS.has('shell'));
+  assert.ok(!CHECKPOINTABLE_ACTIONS.has('read'));
+});
+
+// ---------------------------------------------------------------------------
+// Capture: prior state pre-mutation; committed only on demand; turn linkage
+// ---------------------------------------------------------------------------
+
+test('write: prior state captured pre-mutation; record persisted with turn linkage', async () => {
+  const { store } = makeStore();
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'a.txt');
+  fs.writeFileSync(file, 'ORIGINAL');
+
+  store.setTurnContext({ promptIndex: 3, messageCountAtStart: 4, promptText: 'do the thing' });
+
+  const h = await store.beginCapture('write', [file, 'NEW']);
+  assert.ok(h, 'beginCapture returns a handle');
+  // capture read the prior content BEFORE the mutation
+  assert.strictEqual(Buffer.from(h.targets[0].priorContentB64, 'base64').toString('utf8'), 'ORIGINAL');
+
+  // simulate the executor mutating the file
+  fs.writeFileSync(file, 'NEW');
+  const res = h.commit();
+  assert.ok(res && res.seq === 1);
+
+  const items = store.list();
+  assert.strictEqual(items.length, 1);
+  const rec = store._loadRecord(1);
+  assert.strictEqual(rec.action, 'write');
+  assert.strictEqual(rec.targets[0].path, file);
+  assert.strictEqual(rec.targets[0].existedBefore, true);
+  // after-state recorded for external-mod detection
+  assert.ok(rec.targets[0].afterExists);
+  assert.ok(rec.targets[0].afterHash);
+  // conversation linkage present + correct (forward-compat for Task 4.3b)
+  assert.strictEqual(rec.turn.turnId, 'turn-1');
+  assert.strictEqual(rec.turn.promptIndex, 3);
+  assert.strictEqual(rec.turn.messageCountAtStart, 4);
+  assert.match(rec.turn.promptId, /^[0-9a-f]{12}$/);
+});
+
+test('denied/withheld call (no commit) produces NO checkpoint', async () => {
+  const { store } = makeStore();
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'a.txt');
+  fs.writeFileSync(file, 'X');
+  const h = await store.beginCapture('write', [file, 'Y']);
+  assert.ok(h);
+  h.discard(); // simulate a denied gate / executor refusal — never commit
+  assert.strictEqual(store.list().length, 0, 'no checkpoint recorded for an uncommitted capture');
+});
+
+test('non-checkpointable action returns no handle', async () => {
+  const { store } = makeStore();
+  assert.strictEqual(await store.beginCapture('read', ['/x']), null);
+  assert.strictEqual(await store.beginCapture('shell', ['ls']), null);
+});
+
+test('disabled config: beginCapture is a no-op', async () => {
+  const { store } = makeStore({ enabled: false });
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'a.txt');
+  fs.writeFileSync(file, 'X');
+  assert.strictEqual(await store.beginCapture('write', [file, 'Y']), null);
+});
+
+// ---------------------------------------------------------------------------
+// Rewind: restore content; to-sequence; delete; move
+// ---------------------------------------------------------------------------
+
+async function captureAndMutate(store, action, args, mutate) {
+  const h = await store.beginCapture(action, args);
+  mutate();
+  return h ? h.commit() : null;
+}
+
+test('rewind restores prior content', async () => {
+  const { store } = makeStore();
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'a.txt');
+  fs.writeFileSync(file, 'ORIGINAL');
+  await captureAndMutate(store, 'write', [file, 'NEW'], () => fs.writeFileSync(file, 'NEW'));
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'NEW');
+
+  const res = store.rewind('last');
+  assert.ok(res.ok);
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'ORIGINAL');
+});
+
+test('rewind to a chosen sequence restores that point', async () => {
+  const { store } = makeStore();
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'a.txt');
+  fs.writeFileSync(file, 'V0');
+  await captureAndMutate(store, 'write', [file, 'V1'], () => fs.writeFileSync(file, 'V1')); // seq 1 (prior V0)
+  await captureAndMutate(store, 'write', [file, 'V2'], () => fs.writeFileSync(file, 'V2')); // seq 2 (prior V1)
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'V2');
+
+  // rewind to seq 1 restores the state prior to the first write → V0
+  const res = store.rewind(1);
+  assert.ok(res.ok);
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'V0');
+});
+
+test('delete rewind recreates the file with prior content', async () => {
+  const { store } = makeStore();
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'gone.txt');
+  fs.writeFileSync(file, 'KEEP ME');
+  await captureAndMutate(store, 'delete_file', [file], () => fs.unlinkSync(file));
+  assert.ok(!fs.existsSync(file), 'file deleted by the mutation');
+
+  const res = store.rewind('last');
+  assert.ok(res.ok);
+  assert.ok(fs.existsSync(file), 'rewind recreated the file');
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'KEEP ME');
+});
+
+test('write of a NEW file rewinds by deleting it (existedBefore=false)', async () => {
+  const { store } = makeStore();
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'created.txt');
+  await captureAndMutate(store, 'write', [file, 'HELLO'], () => fs.writeFileSync(file, 'HELLO'));
+  assert.ok(fs.existsSync(file));
+
+  const res = store.rewind('last');
+  assert.ok(res.ok);
+  assert.ok(!fs.existsSync(file), 'rewind removed the file the agent created');
+});
+
+test('move rewind returns the file to its origin', async () => {
+  const { store } = makeStore();
+  const dir = tmpdir('work');
+  const src = path.join(dir, 'src.txt');
+  const dst = path.join(dir, 'dst.txt');
+  fs.writeFileSync(src, 'PAYLOAD');
+  await captureAndMutate(store, 'move_file', [src, dst], () => { fs.renameSync(src, dst); });
+  assert.ok(!fs.existsSync(src) && fs.existsSync(dst), 'move happened');
+
+  const res = store.rewind('last');
+  assert.ok(res.ok);
+  assert.ok(fs.existsSync(src), 'src restored');
+  assert.ok(!fs.existsSync(dst), 'dst removed (it did not exist before the move)');
+  assert.strictEqual(fs.readFileSync(src, 'utf8'), 'PAYLOAD');
+});
+
+// ---------------------------------------------------------------------------
+// External-modification integrity
+// ---------------------------------------------------------------------------
+
+test('external modification blocks rewind (no clobber) unless forced', async () => {
+  const { store } = makeStore();
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'a.txt');
+  fs.writeFileSync(file, 'ORIGINAL');
+  await captureAndMutate(store, 'write', [file, 'AGENT'], () => fs.writeFileSync(file, 'AGENT'));
+
+  // a user/other process edits the file out of band AFTER the agent left it
+  fs.writeFileSync(file, 'USER EDIT');
+
+  const blocked = store.rewind('last');
+  assert.strictEqual(blocked.ok, false);
+  assert.strictEqual(blocked.blocked, true);
+  assert.deepStrictEqual(blocked.externallyModified, [file]);
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'USER EDIT', 'out-of-band edit NOT clobbered');
+
+  const forced = store.rewind('last', { force: true });
+  assert.ok(forced.ok);
+  assert.deepStrictEqual(forced.forcedOverExternal, [file]);
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'ORIGINAL', 'force overwrote the external edit');
+});
+
+// ---------------------------------------------------------------------------
+// Size cap, retention, fail-safe
+// ---------------------------------------------------------------------------
+
+test('size cap: oversized file is not snapshotted, recorded rewind-unavailable, capture still proceeds', async () => {
+  const { store } = makeStore({ max_file_bytes: 8 });
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'big.txt');
+  fs.writeFileSync(file, 'THIS IS WAY MORE THAN EIGHT BYTES');
+
+  const h = await store.beginCapture('write', [file, 'small']);
+  assert.ok(h, 'capture still returns a handle (mutation proceeds)');
+  assert.strictEqual(h.targets[0].oversize, true);
+  assert.strictEqual(h.targets[0].rewindable, false);
+  assert.strictEqual(h.targets[0].priorContentB64, null, 'oversize file not snapshotted');
+
+  fs.writeFileSync(file, 'small');
+  const res = h.commit();
+  assert.ok(res);
+  const rec = store._loadRecord(res.seq);
+  assert.strictEqual(rec.rewindable, false);
+
+  // rewind reports the file as unrewindable rather than corrupting it
+  const rw = store.rewind(res.seq);
+  assert.deepStrictEqual(rw.unrewindable, [file]);
+  assert.strictEqual(rw.restored.length, 0);
+});
+
+test('retention prunes the oldest checkpoints beyond max_per_session', async () => {
+  const { store } = makeStore({ max_per_session: 3 });
+  const dir = tmpdir('work');
+  for (let i = 0; i < 5; i++) {
+    const file = path.join(dir, `f${i}.txt`);
+    await captureAndMutate(store, 'write', [file, 'x'], () => fs.writeFileSync(file, 'x'));
+  }
+  const items = store.list();
+  assert.strictEqual(items.length, 3, 'only the newest 3 kept');
+  assert.deepStrictEqual(items.map((i) => i.seq), [3, 4, 5], 'oldest (1,2) pruned');
+});
+
+test('snapshot failure is fail-safe: beginCapture returns null, never throws', async () => {
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'a.txt');
+  fs.writeFileSync(file, 'X');
+  // inject an fs whose readFileSync throws a non-ENOENT error (e.g. EACCES)
+  const brokenFs = Object.assign({}, fs, {
+    readFileSync: () => { const e = new Error('EACCES'); e.code = 'EACCES'; throw e; },
+  });
+  const { store } = makeStore({}, { fsImpl: brokenFs });
+  let handle;
+  await assert.doesNotReject(async () => { handle = await store.beginCapture('write', [file, 'Y']); });
+  assert.strictEqual(handle, null, 'no checkpoint, but no throw — mutation will still proceed');
+});
+
+// ---------------------------------------------------------------------------
+// Multi-session helpers
+// ---------------------------------------------------------------------------
+
+test('latestSession resolves the most-recently-written session dir', async () => {
+  const root = tmpdir('cproot');
+  const sA = createCheckpointStore({ getConfig: () => ({ checkpoints: {} }), sessionId: 'A', rootDir: root, audit: NOOP_AUDIT });
+  const sB = createCheckpointStore({ getConfig: () => ({ checkpoints: {} }), sessionId: 'B', rootDir: root, audit: NOOP_AUDIT });
+  const dir = tmpdir('work');
+  const fA = path.join(dir, 'a.txt');
+  const fB = path.join(dir, 'b.txt');
+  fs.writeFileSync(fA, '1');
+  await captureAndMutate(sA, 'write', [fA, '2'], () => fs.writeFileSync(fA, '2'));
+  fs.writeFileSync(fB, '1');
+  await captureAndMutate(sB, 'write', [fB, '2'], () => fs.writeFileSync(fB, '2'));
+  // Pin mtimes explicitly so the assertion does not depend on sub-millisecond
+  // wall-clock gaps between the two captures (B is the most recent).
+  fs.utimesSync(path.join(root, 'A', '1.json'), new Date(1000), new Date(1000));
+  fs.utimesSync(path.join(root, 'B', '1.json'), new Date(2000), new Date(2000));
+  assert.strictEqual(latestSession(root), 'B');
+});
+
+// ---------------------------------------------------------------------------
+// Scope limit surfaced to the user (shell side effects not reversible)
+// ---------------------------------------------------------------------------
+
+test('the shell-not-reversible scope limit is stated in /rewind output', () => {
+  assert.match(SCOPE_NOTICE, /shell side effects/i);
+  assert.match(SCOPE_NOTICE, /not\b.*reversible/i);
+  // both the list view and the rewind result carry it
+  assert.match(formatCheckpointList([]), /shell side effects/i);
+  assert.match(formatRewindResult({ seq: 1, action: 'write', restored: ['/x'] }), /shell side effects/i);
+});
+
+test('formatRewindResult reports a blocked (externally-modified) rewind with a force hint', () => {
+  const out = formatRewindResult({ blocked: true, seq: 2, externallyModified: ['/p'], message: 'Rewind blocked: ...' });
+  assert.match(out, /\/rewind 2 force/);
+  assert.match(out, /changed: \/p/);
+});
+
+test('setSession realigns the checkpoint directory', async () => {
+  const root = tmpdir('cproot');
+  const store = createCheckpointStore({ getConfig: () => ({ checkpoints: {} }), sessionId: 'auto', rootDir: root, audit: NOOP_AUDIT });
+  store.setSession('chat-xyz');
+  assert.strictEqual(store.getSession(), 'chat-xyz');
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'a.txt');
+  await captureAndMutate(store, 'write', [file, 'x'], () => fs.writeFileSync(file, 'x'));
+  assert.ok(fs.existsSync(path.join(root, 'chat-xyz', '1.json')));
+});
+
+// ===========================================================================
+// Task 4.3b · Part 1 — restore-path guard re-validation
+// ===========================================================================
+
+test('restore re-validates current guards: a now-denied path is refused (skipped), a still-allowed path restores', async () => {
+  const dir = tmpdir('work');
+  const allowed = path.join(dir, 'ok.txt');
+  const denied = path.join(dir, 'secret.env');
+  // A guard that refuses anything ending in .env (simulating a deny rule /
+  // protected-config / isPathSafe change between capture and restore).
+  const restoreGuard = (p) => p.endsWith('.env')
+    ? { ok: false, reason: 'blocked by a deny permission rule' }
+    : { ok: true };
+  const { store } = makeStore({}, { restoreGuard });
+
+  fs.writeFileSync(allowed, 'A0');
+  fs.writeFileSync(denied, 'S0');
+  // One checkpoint that touches BOTH files (a move would, but simplest: two
+  // separate writes — rewind the most recent of each independently). Use a
+  // single record by capturing a move so both targets are in one checkpoint.
+  await captureAndMutate(store, 'write', [allowed, 'A1'], () => fs.writeFileSync(allowed, 'A1'));
+  await captureAndMutate(store, 'write', [denied, 'S1'], () => fs.writeFileSync(denied, 'S1'));
+
+  // Rewind the allowed file — restores fine.
+  const r1 = store.rewind(1, { mode: 'code' });
+  assert.ok(r1.ok);
+  assert.deepStrictEqual(r1.restored, [allowed]);
+  assert.strictEqual(fs.readFileSync(allowed, 'utf8'), 'A0');
+
+  // Rewind the denied file — refused (skipped), file untouched, rest of rewind not aborted.
+  const r2 = store.rewind(2, { mode: 'code' });
+  assert.deepStrictEqual(r2.restored, []);
+  assert.strictEqual(r2.refused.length, 1);
+  assert.strictEqual(r2.refused[0].path, denied);
+  assert.match(r2.refused[0].reason, /deny permission rule/);
+  assert.strictEqual(fs.readFileSync(denied, 'utf8'), 'S1', 'denied path NOT re-written');
+});
+
+test('force overrides only the external-mod check, NOT the restore guards', async () => {
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'x.env');
+  const restoreGuard = (p) => p.endsWith('.env') ? { ok: false, reason: 'protected' } : { ok: true };
+  const { store } = makeStore({}, { restoreGuard });
+
+  fs.writeFileSync(file, 'V0');
+  await captureAndMutate(store, 'write', [file, 'V1'], () => fs.writeFileSync(file, 'V1'));
+  // out-of-band edit so the external-mod path is exercised under force
+  fs.writeFileSync(file, 'USER');
+
+  const res = store.rewind('last', { mode: 'code', force: true });
+  // force got past the external-mod block, but the guard still refused the write
+  assert.deepStrictEqual(res.restored, []);
+  assert.strictEqual(res.refused.length, 1);
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'USER', 'guard refusal holds even under force');
+});
+
+test('a guard that throws fails closed (refused, not restored)', async () => {
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'a.txt');
+  const restoreGuard = () => { throw new Error('boom'); };
+  const { store } = makeStore({}, { restoreGuard });
+  fs.writeFileSync(file, 'V0');
+  await captureAndMutate(store, 'write', [file, 'V1'], () => fs.writeFileSync(file, 'V1'));
+  const res = store.rewind('last', { mode: 'code' });
+  assert.strictEqual(res.restored.length, 0);
+  assert.strictEqual(res.refused.length, 1);
+  assert.match(res.refused[0].reason, /guard error/);
+});
+
+test('with no restoreGuard injected the store defaults to allow (4.3 behavior preserved)', async () => {
+  const { store } = makeStore(); // no restoreGuard
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'a.txt');
+  fs.writeFileSync(file, 'V0');
+  await captureAndMutate(store, 'write', [file, 'V1'], () => fs.writeFileSync(file, 'V1'));
+  const res = store.rewind('last', { mode: 'code' });
+  assert.ok(res.ok);
+  assert.deepStrictEqual(res.restored, [file]);
+  assert.deepStrictEqual(res.refused, []);
+});
+
+// ===========================================================================
+// Task 4.3b · Part 2 — conversation rewind + restore modes
+// ===========================================================================
+
+// A small two-turn native conversation. Turn 1 ("do A") writes a.txt via a
+// native tool_call; turn 2 ("do B") writes b.txt. Indices:
+//   0 user "do A"  1 assistant(tool_call ca)  2 tool(ca)  3 assistant "done A"
+//   4 user "do B"  5 assistant(tool_call cb)  6 tool(cb)  7 assistant "done B"
+function nativeConversation() {
+  return [
+    { role: 'user', content: 'do A' },
+    { role: 'assistant', content: '', tool_calls: [{ id: 'ca', type: 'function', function: { name: 'write_file', arguments: '{}' } }] },
+    { role: 'tool', tool_call_id: 'ca', content: 'ok' },
+    { role: 'assistant', content: 'done A' },
+    { role: 'user', content: 'do B' },
+    { role: 'assistant', content: '', tool_calls: [{ id: 'cb', type: 'function', function: { name: 'write_file', arguments: '{}' } }] },
+    { role: 'tool', tool_call_id: 'cb', content: 'ok' },
+    { role: 'assistant', content: 'done B' },
+  ];
+}
+
+test('normalizeRewindMode: defaults to both; known modes pass; unknown → null', () => {
+  assert.strictEqual(normalizeRewindMode(undefined), 'both');
+  assert.strictEqual(normalizeRewindMode(''), 'both');
+  assert.strictEqual(normalizeRewindMode('code'), 'code');
+  assert.strictEqual(normalizeRewindMode('Conversation'), 'conversation');
+  assert.strictEqual(normalizeRewindMode('both'), 'both');
+  assert.strictEqual(normalizeRewindMode('bogus'), null);
+  assert.deepStrictEqual([...REWIND_MODES].sort(), ['both', 'code', 'conversation']);
+});
+
+test('findOrphanedToolCalls: clean native conversation has no orphans', () => {
+  assert.deepStrictEqual(findOrphanedToolCalls(nativeConversation()), []);
+});
+
+test('findOrphanedToolCalls: a tool_call with no result, or a result with no call, is an orphan', () => {
+  const dangling = nativeConversation().slice(0, 2); // user + assistant(tool_call ca), no tool result
+  assert.deepStrictEqual(findOrphanedToolCalls(dangling), ['ca']);
+  const orphanResult = [{ role: 'tool', tool_call_id: 'zz', content: 'x' }];
+  assert.deepStrictEqual(findOrphanedToolCalls(orphanResult), ['zz']);
+});
+
+test('snapToTurnBoundary snaps a mid-turn index back to the turn-start user message', () => {
+  const msgs = nativeConversation();
+  // index 6 is the tool result inside turn 2 → snaps back to user "do B" at 4
+  assert.strictEqual(snapToTurnBoundary(msgs, 6), 4);
+  // index 2 (tool result inside turn 1) → snaps to user "do A" at 0
+  assert.strictEqual(snapToTurnBoundary(msgs, 2), 0);
+  // already a user boundary stays put
+  assert.strictEqual(snapToTurnBoundary(msgs, 4), 4);
+});
+
+test('locateTurnStart matches by promptId even when indices shifted (compaction)', () => {
+  const crypto = require('crypto');
+  const promptId = crypto.createHash('sha256').update(Buffer.from('do B')).digest('hex').slice(0, 12);
+  // simulate compaction: a summary message was prepended, so the real index of
+  // "do B" is now 5, but the checkpoint recorded promptIndex 4.
+  const msgs = [{ role: 'system', content: 'summary' }, ...nativeConversation()];
+  const turn = { turnId: 'turn-2', promptId, promptIndex: 4, messageCountAtStart: 5 };
+  assert.strictEqual(locateTurnStart(msgs, turn), 5);
+});
+
+test('planConversationRewind cuts on the turn boundary; kept history has no orphaned tool_call', () => {
+  const crypto = require('crypto');
+  const msgs = nativeConversation();
+  const promptId = crypto.createHash('sha256').update(Buffer.from('do B')).digest('hex').slice(0, 12);
+  const plan = planConversationRewind(msgs, { turnId: 'turn-2', promptId, promptIndex: 4, messageCountAtStart: 5 });
+  assert.ok(plan.ok);
+  assert.strictEqual(plan.cutIndex, 4);
+  assert.strictEqual(plan.kept.length, 4);
+  assert.strictEqual(plan.removed.length, 4);
+  assert.deepStrictEqual(findOrphanedToolCalls(plan.kept), [], 'no orphaned tool_call after the cut');
+  assert.strictEqual(plan.kept[plan.kept.length - 1].content, 'done A');
+});
+
+test('planConversationRewind: missing turn linkage / unlocatable turn → ok:false', () => {
+  assert.strictEqual(planConversationRewind(nativeConversation(), null).ok, false);
+  // promptId that matches nothing and an out-of-range promptIndex
+  const r = planConversationRewind(nativeConversation(), { promptId: 'deadbeefdead', promptIndex: 99 });
+  assert.strictEqual(r.ok, false);
+  assert.match(r.reason, /could not locate/i);
+});
+
+// Build a store whose checkpoint for seq N is linked to a given turn.
+async function storeWithTurnLinkedWrite(turn, fileVal) {
+  const { store } = makeStore();
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'f.txt');
+  fs.writeFileSync(file, 'PRIOR');
+  store.setTurnContext(turn);
+  await captureAndMutate(store, 'write', [file, fileVal], () => fs.writeFileSync(file, fileVal));
+  return { store, file };
+}
+
+test('code mode: files restored, conversation untouched (4.3 behavior)', async () => {
+  const { store, file } = await storeWithTurnLinkedWrite({ promptIndex: 4, messageCountAtStart: 5, promptText: 'do B' }, 'NEW');
+  const msgs = nativeConversation();
+  const res = store.rewind('last', { mode: 'code', messages: msgs });
+  assert.ok(res.ok);
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'PRIOR');
+  assert.strictEqual(res.conversation, undefined, 'code mode does not touch conversation');
+});
+
+test('conversation mode: history truncated to the turn, files untouched', async () => {
+  const { store, file } = await storeWithTurnLinkedWrite({ promptIndex: 4, messageCountAtStart: 5, promptText: 'do B' }, 'NEW');
+  const msgs = nativeConversation();
+  const res = store.rewind('last', { mode: 'conversation', messages: msgs });
+  assert.ok(res.conversation.ok);
+  assert.strictEqual(res.conversation.cutIndex, 4);
+  assert.strictEqual(res.conversation.removedCount, 4);
+  assert.deepStrictEqual(findOrphanedToolCalls(res.conversation.messages), []);
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'NEW', 'conversation mode leaves files alone');
+});
+
+test('both mode (default): files + conversation restored to the linked point coherently', async () => {
+  const { store, file } = await storeWithTurnLinkedWrite({ promptIndex: 4, messageCountAtStart: 5, promptText: 'do B' }, 'NEW');
+  const msgs = nativeConversation();
+  const res = store.rewind('last', { messages: msgs }); // default mode = both
+  assert.strictEqual(res.mode, 'both');
+  assert.ok(res.ok);
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'PRIOR', 'files restored');
+  assert.ok(res.conversation.ok);
+  assert.strictEqual(res.conversation.messages.length, 4, 'conversation truncated to the turn');
+  assert.deepStrictEqual(findOrphanedToolCalls(res.conversation.messages), []);
+});
+
+test('Part 1 guard also applies under both mode (files refused, conversation still rewinds)', async () => {
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'x.env');
+  const restoreGuard = (p) => p.endsWith('.env') ? { ok: false, reason: 'protected' } : { ok: true };
+  const { store } = makeStore({}, { restoreGuard });
+  fs.writeFileSync(file, 'V0');
+  store.setTurnContext({ promptIndex: 4, messageCountAtStart: 5, promptText: 'do B' });
+  await captureAndMutate(store, 'write', [file, 'V1'], () => fs.writeFileSync(file, 'V1'));
+  const res = store.rewind('last', { mode: 'both', messages: nativeConversation() });
+  assert.deepStrictEqual(res.restored, [], 'file restore refused by the guard');
+  assert.strictEqual(res.refused.length, 1);
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'V1', 'guarded file untouched');
+  assert.ok(res.conversation.ok, 'conversation half still rewinds under both');
+});
+
+test('rewinding to a turn whose linkage points mid-tool-call cuts on the boundary, not mid-pair', async () => {
+  // The checkpoint records a promptIndex that (after edits) lands on the tool
+  // result INSIDE turn 2 rather than the user message. The cut must still land
+  // on the turn boundary (user "do B" at 4) so no orphan remains.
+  const { store } = await storeWithTurnLinkedWrite({ promptIndex: 6, messageCountAtStart: 7, promptText: '' }, 'NEW');
+  const msgs = nativeConversation();
+  const res = store.rewind('last', { mode: 'conversation', messages: msgs });
+  assert.ok(res.conversation.ok);
+  assert.strictEqual(res.conversation.cutIndex, 4, 'snapped back to the user boundary');
+  assert.deepStrictEqual(findOrphanedToolCalls(res.conversation.messages), []);
+});
+
+test('conversation mode with no messages provided → ok:false, surfaced', async () => {
+  const { store } = await storeWithTurnLinkedWrite({ promptIndex: 4, messageCountAtStart: 5, promptText: 'do B' }, 'NEW');
+  const res = store.rewind('last', { mode: 'conversation' });
+  assert.strictEqual(res.ok, false);
+  assert.strictEqual(res.conversation.ok, false);
+  assert.match(res.conversation.reason, /no conversation/i);
+});
+
+test('on-disk checkpoint format unchanged: a record written WITHOUT the 4.3b code still rewinds', async () => {
+  // Hand-author a v1 record exactly as Task 4.3 wrote it (turn linkage present,
+  // no new fields) and prove the 4.3b rewind reads it for both code + conversation.
+  const root = tmpdir('cproot');
+  const dir = tmpdir('work');
+  const file = path.join(dir, 'legacy.txt');
+  fs.writeFileSync(file, 'CURRENT');
+  const sessDir = path.join(root, 'legacy-sess');
+  fs.mkdirSync(sessDir, { recursive: true });
+  const crypto = require('crypto');
+  const priorB64 = Buffer.from('LEGACY-PRIOR').toString('base64');
+  const afterHash = crypto.createHash('sha256').update(Buffer.from('CURRENT')).digest('hex');
+  const promptId = crypto.createHash('sha256').update(Buffer.from('do B')).digest('hex').slice(0, 12);
+  const record = {
+    version: 1, seq: 1, session: 'legacy-sess', ts: '2026-01-01T00:00:00.000Z', action: 'write',
+    turn: { turnId: 'turn-2', promptId, promptIndex: 4, messageCountAtStart: 5 },
+    targets: [{ path: file, role: 'primary', existedBefore: true, isDir: false, oversize: false, rewindable: true, priorContentB64: priorB64, priorMode: 420, afterExists: true, afterHash }],
+    rewindable: true,
+  };
+  fs.writeFileSync(path.join(sessDir, '1.json'), JSON.stringify(record, null, 2));
+
+  const store = createCheckpointStore({ getConfig: () => ({ checkpoints: {} }), sessionId: 'legacy-sess', rootDir: root, audit: NOOP_AUDIT });
+  const res = store.rewind('last', { mode: 'both', messages: nativeConversation() });
+  assert.ok(res.ok);
+  assert.strictEqual(fs.readFileSync(file, 'utf8'), 'LEGACY-PRIOR', 'legacy record restores files');
+  assert.ok(res.conversation.ok, 'legacy turn linkage drives conversation rewind');
+  assert.strictEqual(res.conversation.cutIndex, 4);
+});
+
+test('rewind remains human-only: no rewind/checkpoint tool is registered (static, dynamic, specs, tags)', () => {
+  const { TOOL_REGISTRY, registryToolNames, dynamicToolEntries } = require('../lib/tool_registry');
+  const { TOOL_SPECS } = require('../lib/tool_specs');
+  const { TAG_REGISTRY } = require('../lib/constants');
+  const forbidden = /rewind|checkpoint/i;
+
+  assert.ok(!registryToolNames().some((n) => forbidden.test(n)), 'no static tool name mentions rewind/checkpoint');
+  assert.ok(!Object.keys(TOOL_REGISTRY).some((n) => forbidden.test(n)));
+  assert.ok(!Object.keys(TOOL_SPECS).some((n) => forbidden.test(n)), 'no tool spec for rewind/checkpoint');
+  assert.ok(!Object.keys(TAG_REGISTRY).some((n) => forbidden.test(n)), 'no XML tag for rewind/checkpoint');
+  assert.ok(!dynamicToolEntries().some(([n]) => forbidden.test(n)), 'no dynamic tool for rewind/checkpoint');
+});
+
+test('formatRewindResult surfaces mode, refused guards, and conversation truncation', () => {
+  const out = formatRewindResult({
+    seq: 3, mode: 'both', action: 'write', restored: ['/a'],
+    refused: [{ path: '/b.env', reason: 'blocked by a deny permission rule' }],
+    conversation: { ok: true, turnId: 'turn-2', removedCount: 4 },
+  });
+  assert.match(out, /\[3\] \[both\]/);
+  assert.match(out, /refused \(current guards\): \/b\.env/);
+  assert.match(out, /conversation: rewound to turn-2 — 4 message/);
+});