@semalt-ai/code 1.8.5 → 1.20.0

package/lib/checkpoints.js

@@ -0,0 +1,757 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Checkpoints & rewind (Task 4.3)
+// ---------------------------------------------------------------------------
+//
+// Before each file-tool mutation the prior state of the affected file(s) is
+// snapshotted to ~/.semalt-ai/checkpoints/<session>/<seq>.json so `/rewind`
+// (and `semalt-code rewind`) can restore it. Restoration is a straight
+// content-restore (write the prior bytes back, or delete a file that did not
+// exist before) — never a fragile reverse-diff replay.
+//
+//   "checkpoints": {
+//     "enabled": true,            // master switch
+//     "max_file_bytes": 5242880,  // per-file snapshot cap; oversize → not
+//                                 //   snapshotted, recorded rewind-unavailable
+//     "max_per_session": 100      // retention cap; oldest pruned
+//   }
+//
+// SCOPE LIMIT (load-bearing, surfaced to the user): checkpoints cover FILE-TOOL
+// mutations only (write, append, edit_file, replace_in_file, delete_file,
+// move_file, copy_file, upload). Shell side effects — a command that created a
+// file, touched a DB, or hit the network — are NOT reversible and are out of
+// scope. `/rewind` must say so; a false sense of "full undo" is worse than no
+// undo.
+//
+// CONVERSATION-REWIND FORWARD-COMPAT (load-bearing): this task ships
+// file-rewind only, but every checkpoint records its conversation linkage —
+// `turn` = { turnId, promptId, promptIndex, messageCountAtStart } — so a future
+// Task 4.3b can add code/conversation/both rewind WITHOUT changing the on-disk
+// format. Do not remove these fields.
+//
+// Load-bearing properties:
+//   * Capture point — capture happens in the executor (agentExecFile) AFTER the
+//     permission gate approves and BEFORE the mutation; a denied/withheld call
+//     never reaches the executor, and a call the executor itself refuses
+//     (--readonly, sandbox, dry-run) produces no committed checkpoint because
+//     commit only runs on a status:'ok' result.
+//   * Subagents — a subagent reuses the parent's agentExecFile, so its
+//     mutations are checkpointed into the PARENT session space automatically and
+//     are rewindable.
+//   * Fail-safe, not fail-blocking — if snapshotting fails (disk full, EACCES),
+//     the mutation still proceeds; checkpointing is a safety net, never a gate.
+//   * External-modification integrity — `/rewind` records what the agent LEFT
+//     (post-mutation existence + content hash) and, before overwriting, compares
+//     the current file against it. A file changed out-of-band (user/other
+//     process) is reported and NOT clobbered unless the user forces it.
+
+const crypto = require('crypto');
+const os = require('os');
+const path = require('path');
+const realFs = require('fs');
+
+const {
+  DEFAULT_CHECKPOINT_MAX_FILE_BYTES,
+  DEFAULT_CHECKPOINT_MAX_PER_SESSION,
+} = require('./constants');
+
+// The file-tool actions that mutate file content/existence and are therefore
+// checkpointable. Directory ops (make_dir/remove_dir) are not snapshotted (a
+// directory tree is out of scope for this task); shell is never reversible.
+const CHECKPOINTABLE_ACTIONS = new Set([
+  'write', 'append', 'edit_file', 'replace_in_file',
+  'delete_file', 'move_file', 'copy_file', 'upload',
+]);
+
+const DEFAULT_ROOT = path.join(os.homedir(), '.semalt-ai', 'checkpoints');
+
+// Validate + canonicalize the `config.checkpoints` section. Pure; consumed by
+// lib/config.js normalizeConfig. Unknown/invalid fields fall back to defaults.
+function normalizeCheckpoints(raw) {
+  const out = {
+    enabled: true,
+    max_file_bytes: DEFAULT_CHECKPOINT_MAX_FILE_BYTES,
+    max_per_session: DEFAULT_CHECKPOINT_MAX_PER_SESSION,
+  };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;
+  if (raw.enabled === false) out.enabled = false;
+  if (Number.isInteger(raw.max_file_bytes) && raw.max_file_bytes > 0) out.max_file_bytes = raw.max_file_bytes;
+  if (Number.isInteger(raw.max_per_session) && raw.max_per_session > 0) out.max_per_session = raw.max_per_session;
+  return out;
+}
+
+function _sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// Compute the set of file targets a given mutating action will touch, each
+// tagged with a role so rewind knows how to reverse it.
+//   write/append/edit/replace/upload → the single primary file
+//   delete_file                      → the file being removed (recreated on rewind)
+//   move_file                        → the src (returns) + the dst (overwritten)
+//   copy_file                        → the dst only (src is untouched)
+function _targetsFor(action, args) {
+  const abs = (p) => (typeof p === 'string' && p ? path.resolve(p) : null);
+  switch (action) {
+    case 'write':
+    case 'append':
+    case 'edit_file':
+    case 'replace_in_file':
+    case 'upload':
+    case 'delete_file': {
+      const p = abs(args[0]);
+      return p ? [{ path: p, role: 'primary' }] : [];
+    }
+    case 'move_file': {
+      const src = abs(args[0]);
+      const dst = abs(args[1]);
+      const out = [];
+      if (src) out.push({ path: src, role: 'move_src' });
+      if (dst) out.push({ path: dst, role: 'move_dst' });
+      return out;
+    }
+    case 'copy_file': {
+      const dst = abs(args[1]);
+      return dst ? [{ path: dst, role: 'copy_dst' }] : [];
+    }
+    default:
+      return [];
+  }
+}
+
+// Build the checkpoint store. Injectable seams (`fs`, `now`, `log`, `audit`,
+// `rootDir`) keep it unit-testable without touching the real filesystem/clock.
+//   getConfig  — live config (read per op so a config change takes effect)
+//   sessionId  — initial session id; setSession() can realign it before any
+//                capture (chat aligns it with the chat session.id)
+function createCheckpointStore({
+  getConfig,
+  sessionId = null,
+  rootDir = DEFAULT_ROOT,
+  fs = realFs,
+  now = () => new Date().toISOString(),
+  log,
+  audit,
+  restoreGuard,
+} = {}) {
+  const warn = typeof log === 'function' ? log : () => {};
+  // Restore-path re-validation (Task 4.3b, Part 1). Before each file write/delete
+  // in the restore path, the target is re-checked against the CURRENT guards
+  // (isPathSafe / secret-file / protected-config / active `deny` rules) so a
+  // rewind can never re-write a path the guards now forbid — e.g. a path that
+  // was inside the CWD at capture but a `deny` rule (or --allow-anywhere being
+  // off) now covers. Injected by the executor owner (index.js); undefined in the
+  // store's own unit tests defaults to "allow" (a no-op). This is a per-target
+  // refusal (the offending file is skipped, the rest of the rewind proceeds),
+  // and `force` does NOT bypass it — force overrides only the external-mod check.
+  const _restoreGuard = typeof restoreGuard === 'function'
+    ? restoreGuard
+    : () => ({ ok: true });
+  const logCheckpoint = (audit && typeof audit.logCheckpoint === 'function')
+    ? audit.logCheckpoint
+    : require('./audit').logCheckpoint;
+
+  let _session = sessionId || _genId();
+  let _turnCounter = 0;
+  let _turn = { turnId: null, promptId: null, promptIndex: null, messageCountAtStart: null };
+
+  function _genId() { return crypto.randomBytes(4).toString('hex'); }
+
+  function _cfg() {
+    let c = {};
+    try { c = (getConfig ? getConfig() : {}) || {}; } catch { c = {}; }
+    return normalizeCheckpoints(c.checkpoints);
+  }
+
+  function enabled() { return _cfg().enabled; }
+  function getSession() { return _session; }
+  function setSession(id) { if (id && typeof id === 'string') _session = id; }
+
+  // Called by the agent loop at the start of each user turn so every checkpoint
+  // captured during that turn (including a subagent's) is linked to it. This is
+  // the forward-compat hook for conversation-rewind (Task 4.3b).
+  function setTurnContext({ promptIndex = null, messageCountAtStart = null, promptText = '' } = {}) {
+    _turnCounter += 1;
+    const promptId = promptText
+      ? _sha256(Buffer.from(String(promptText))).slice(0, 12)
+      : null;
+    _turn = {
+      turnId: `turn-${_turnCounter}`,
+      promptId,
+      promptIndex: Number.isInteger(promptIndex) ? promptIndex : null,
+      messageCountAtStart: Number.isInteger(messageCountAtStart) ? messageCountAtStart : null,
+    };
+  }
+
+  function _sessionDir(session = _session) { return path.join(rootDir, session); }
+
+  // Read the on-disk prior state of one target (pre-mutation) honoring the size
+  // cap. A missing file is a normal, rewindable state (rewind = delete). A
+  // directory or an oversize file is recorded but flagged not-rewindable. A
+  // genuine read error (EACCES etc.) throws so the caller can fail safe.
+  function _readPrior(p, maxBytes) {
+    let st;
+    try {
+      st = fs.statSync(p);
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        return { path: p, existedBefore: false, isDir: false, oversize: false, rewindable: true, priorContentB64: null, priorMode: null, priorSize: 0 };
+      }
+      throw err;
+    }
+    if (st.isDirectory()) {
+      return { path: p, existedBefore: true, isDir: true, oversize: false, rewindable: false, priorContentB64: null, priorMode: st.mode, priorSize: st.size };
+    }
+    if (st.size > maxBytes) {
+      return { path: p, existedBefore: true, isDir: false, oversize: true, rewindable: false, priorContentB64: null, priorMode: st.mode, priorSize: st.size };
+    }
+    const buf = fs.readFileSync(p);
+    return { path: p, existedBefore: true, isDir: false, oversize: false, rewindable: true, priorContentB64: buf.toString('base64'), priorMode: st.mode, priorSize: st.size };
+  }
+
+  // Read the current state of a target for the after-snapshot / external-mod
+  // check: { exists, hash } (hash null if absent or unreadable).
+  function _readCurrent(p) {
+    try {
+      const st = fs.statSync(p);
+      if (st.isDirectory()) return { exists: true, hash: null, isDir: true };
+      const buf = fs.readFileSync(p);
+      return { exists: true, hash: _sha256(buf), isDir: false };
+    } catch {
+      return { exists: false, hash: null, isDir: false };
+    }
+  }
+
+  // Phase 1 (pre-mutation): read prior state into memory. Returns a handle with
+  // commit()/discard(). Returns null when checkpointing is off, the action is
+  // not checkpointable, or snapshotting fails (fail-safe — the mutation still
+  // proceeds). Nothing is written to disk until commit().
+  async function beginCapture(action, args) {
+    if (!enabled()) return null;
+    if (!CHECKPOINTABLE_ACTIONS.has(action)) return null;
+    const cfg = _cfg();
+    const targets = _targetsFor(action, args);
+    if (!targets.length) return null;
+
+    let priors;
+    try {
+      priors = targets.map((t) => Object.assign(_readPrior(t.path, cfg.max_file_bytes), { role: t.role }));
+    } catch (err) {
+      warn(`checkpoint: could not snapshot prior state for ${action} (${err.message}); rewind will be unavailable for this change`);
+      return null;
+    }
+
+    return {
+      action,
+      targets: priors,
+      commit: () => _commit(action, priors),
+      discard: () => {},
+    };
+  }
+
+  function _nextSeq(dir) {
+    let max = 0;
+    try {
+      for (const name of fs.readdirSync(dir)) {
+        const m = /^(\d+)\.json$/.exec(name);
+        if (m) { const n = parseInt(m[1], 10); if (n > max) max = n; }
+      }
+    } catch { /* dir may not exist yet */ }
+    return max + 1;
+  }
+
+  // Phase 2 (post-mutation, on success): record the after-state, persist the
+  // checkpoint record, audit it, and prune. Fail-safe — a write failure here is
+  // warned and swallowed (the mutation already happened).
+  function _commit(action, priors) {
+    const cfg = _cfg();
+    try {
+      const dir = _sessionDir();
+      fs.mkdirSync(dir, { recursive: true });
+      const seq = _nextSeq(dir);
+
+      const targets = priors.map((p) => {
+        const after = _readCurrent(p.path);
+        return {
+          path: p.path,
+          role: p.role,
+          existedBefore: p.existedBefore,
+          isDir: p.isDir,
+          oversize: p.oversize,
+          rewindable: p.rewindable,
+          priorContentB64: p.priorContentB64,
+          priorMode: p.priorMode,
+          afterExists: after.exists,
+          afterHash: after.hash,
+        };
+      });
+
+      const record = {
+        version: 1,
+        seq,
+        session: _session,
+        ts: now(),
+        action,
+        // Conversation linkage for Task 4.3b — DO NOT remove.
+        turn: { ..._turn },
+        targets,
+        // Whole-checkpoint convenience flag: true only if every target can be
+        // restored. A checkpoint with an oversize/dir target is still recorded
+        // (so the user sees it) but flagged so rewind reports what it can't do.
+        rewindable: targets.every((t) => t.rewindable),
+      };
+
+      const file = path.join(dir, `${seq}.json`);
+      fs.writeFileSync(file, JSON.stringify(record, null, 2));
+
+      const paths = targets.map((t) => t.path).join(', ');
+      try { logCheckpoint(seq, `${action} ${paths}`); } catch { /* audit never throws */ }
+      warn(`checkpoint:${seq} ${action} ${paths}`);
+      _prune(dir, cfg.max_per_session);
+      return { seq, action, targets, rewindable: record.rewindable };
+    } catch (err) {
+      warn(`checkpoint: failed to record snapshot for ${action} (${err.message}); rewind will be unavailable for this change`);
+      return null;
+    }
+  }
+
+  function _prune(dir, maxPerSession) {
+    try {
+      const seqs = [];
+      for (const name of fs.readdirSync(dir)) {
+        const m = /^(\d+)\.json$/.exec(name);
+        if (m) seqs.push(parseInt(m[1], 10));
+      }
+      if (seqs.length <= maxPerSession) return;
+      seqs.sort((a, b) => a - b);
+      const drop = seqs.slice(0, seqs.length - maxPerSession);
+      for (const s of drop) {
+        try { fs.unlinkSync(path.join(dir, `${s}.json`)); } catch { /* best effort */ }
+      }
+    } catch { /* best effort */ }
+  }
+
+  function _loadRecord(seq, session = _session) {
+    try {
+      const file = path.join(_sessionDir(session), `${seq}.json`);
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch { return null; }
+  }
+
+  // All full records for a session, sorted by seq ascending.
+  function _allRecords(session = _session) {
+    const dir = _sessionDir(session);
+    const recs = [];
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { return recs; }
+    for (const name of names) {
+      const m = /^(\d+)\.json$/.exec(name);
+      if (!m) continue;
+      const rec = _loadRecord(parseInt(m[1], 10), session);
+      if (rec) recs.push(rec);
+    }
+    recs.sort((a, b) => a.seq - b.seq);
+    return recs;
+  }
+
+  // The after-state the agent LAST left at `p` is the after-state of the
+  // highest-seq checkpoint touching that path. The external-modification check
+  // compares the current file against THIS — not against the checkpoint being
+  // rewound to — so rewinding to an earlier point (with the agent's own later
+  // writes in between) is not mistaken for an out-of-band edit.
+  function _latestAfterFor(p, records) {
+    for (let i = records.length - 1; i >= 0; i--) {
+      const t = (records[i].targets || []).find((x) => x.path === p);
+      if (t) return t;
+    }
+    return null;
+  }
+
+  // List checkpoints for the (given) session, newest last, with a short summary
+  // of what each would undo.
+  function list(session = _session) {
+    const dir = _sessionDir(session);
+    const out = [];
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { return out; }
+    for (const name of names) {
+      const m = /^(\d+)\.json$/.exec(name);
+      if (!m) continue;
+      const rec = _loadRecord(parseInt(m[1], 10), session);
+      if (rec) out.push(rec);
+    }
+    out.sort((a, b) => a.seq - b.seq);
+    return out.map((rec) => ({
+      seq: rec.seq,
+      ts: rec.ts,
+      action: rec.action,
+      turn: rec.turn || null,
+      rewindable: rec.rewindable,
+      summary: _summarize(rec),
+      paths: (rec.targets || []).map((t) => t.path),
+    }));
+  }
+
+  function _summarize(rec) {
+    const t = (rec.targets || []);
+    if (rec.action === 'move_file' && t.length === 2) {
+      return `move ${t[0].path} → ${t[1].path}`;
+    }
+    if (rec.action === 'copy_file') return `copy → ${t[0] ? t[0].path : '?'}`;
+    if (rec.action === 'delete_file') return `delete ${t[0] ? t[0].path : '?'}`;
+    return `${rec.action} ${t[0] ? t[0].path : '?'}`;
+  }
+
+  // Restore one target to its prior state. existedBefore → write the prior
+  // bytes back; !existedBefore → remove the file if it now exists.
+  function _restoreTarget(t) {
+    if (t.existedBefore) {
+      const dir = path.dirname(t.path);
+      if (dir && dir !== '.') fs.mkdirSync(dir, { recursive: true });
+      const buf = Buffer.from(t.priorContentB64 || '', 'base64');
+      fs.writeFileSync(t.path, buf);
+      if (Number.isInteger(t.priorMode)) {
+        try { fs.chmodSync(t.path, t.priorMode); } catch { /* best effort */ }
+      }
+    } else {
+      try { fs.unlinkSync(t.path); } catch (err) { if (err && err.code !== 'ENOENT') throw err; }
+    }
+  }
+
+  // Has a target been changed out-of-band since the agent last left it? Compares
+  // the current file against the LATEST agent-left after-state for that path
+  // (across the whole session), so the agent's own later writes are never
+  // mistaken for an external edit. `ref` falls back to the target itself.
+  function _externallyModified(t, ref) {
+    const expect = ref || t;
+    const cur = _readCurrent(t.path);
+    if (cur.exists !== expect.afterExists) return true;
+    if (cur.exists && expect.afterExists && cur.hash !== expect.afterHash) return true;
+    return false;
+  }
+
+  // Restore a checkpoint. `seq` may be a number or 'last'.
+  //
+  // `mode` (Task 4.3b) selects WHAT is restored:
+  //   'code'         — files only (the original 4.3 behavior).
+  //   'conversation' — session history only (truncate back to the turn that
+  //                    produced this checkpoint); files untouched.
+  //   'both'         — files + history together (default), the coherent linked
+  //                    state: the code as it was AND the conversation back to the
+  //                    point that produced it (code-without-conversation leaves
+  //                    the agent amnesiac; conversation-without-code leaves it
+  //                    reasoning over stale files).
+  //
+  // For the file half: by default an out-of-band modification BLOCKS the restore
+  // (nothing is touched) and is reported; pass { force: true } to overwrite
+  // anyway. Non-rewindable targets (oversize/dir) are skipped and reported. Each
+  // target is additionally re-validated against the current guards (Part 1) — a
+  // path the guards now forbid is REFUSED (skipped) regardless of `force`.
+  //
+  // For the conversation half: pass the live `messages` array; the (truncated)
+  // history is returned as `conversation.messages` for the caller to apply (the
+  // store never owns the conversation). Cutting is always on a turn boundary, so
+  // no orphaned tool_call/tool-result pair is ever left behind.
+  function rewind(seq, { force = false, session = _session, mode = 'both', messages = null } = {}) {
+    const wantCode = mode === 'code' || mode === 'both';
+    const wantConversation = mode === 'conversation' || mode === 'both';
+
+    let targetSeq = seq;
+    if (seq === 'last' || seq == null) {
+      const items = list(session);
+      if (!items.length) return { ok: false, error: 'No checkpoints to rewind.' };
+      targetSeq = items[items.length - 1].seq;
+    }
+    targetSeq = parseInt(targetSeq, 10);
+    const rec = _loadRecord(targetSeq, session);
+    if (!rec) return { ok: false, error: `Checkpoint ${seq} not found.` };
+
+    const out = { ok: true, seq: targetSeq, action: rec.action, mode };
+
+    // ---- Code (file) restore ------------------------------------------------
+    if (wantCode) {
+      const allRecords = _allRecords(session);
+      const targets = rec.targets || [];
+      const restorable = targets.filter((t) => t.rewindable);
+      const unrewindable = targets.filter((t) => !t.rewindable);
+      const externallyModified = restorable.filter((t) => _externallyModified(t, _latestAfterFor(t.path, allRecords)));
+
+      if (externallyModified.length && !force) {
+        return {
+          ok: false,
+          blocked: true,
+          seq: targetSeq,
+          mode,
+          externallyModified: externallyModified.map((t) => t.path),
+          unrewindable: unrewindable.map((t) => t.path),
+          message: `Rewind blocked: ${externallyModified.length} file(s) changed since the agent last wrote them — restoring would discard those out-of-band edits. Re-run with force to overwrite.`,
+        };
+      }
+
+      const restored = [];
+      const failed = [];
+      const refused = [];
+      for (const t of restorable) {
+        // Part 1: re-validate against the CURRENT guards before writing/deleting.
+        // `force` overrides the external-mod check above, NOT these guards.
+        let verdict;
+        try { verdict = _restoreGuard(t.path, { willDelete: !t.existedBefore, role: t.role }); }
+        catch (err) { verdict = { ok: false, reason: `guard error: ${err.message}` }; }
+        if (verdict && verdict.ok === false) {
+          refused.push({ path: t.path, reason: verdict.reason || 'refused by current guards' });
+          continue;
+        }
+        try { _restoreTarget(t); restored.push(t.path); }
+        catch (err) { failed.push({ path: t.path, error: err.message }); }
+      }
+
+      try { logCheckpoint(targetSeq, `rewind restored ${restored.length} file(s)${force && externallyModified.length ? ` (forced over ${externallyModified.length} external edit(s))` : ''}${refused.length ? ` (refused ${refused.length} by guards)` : ''}`); } catch { /* never throws */ }
+
+      out.restored = restored;
+      out.failed = failed;
+      out.refused = refused;
+      out.forcedOverExternal = force ? externallyModified.map((t) => t.path) : [];
+      out.unrewindable = unrewindable.map((t) => t.path);
+      if (failed.length) out.ok = false;
+    }
+
+    // ---- Conversation (history) restore -------------------------------------
+    if (wantConversation) {
+      if (!Array.isArray(messages)) {
+        out.conversation = { ok: false, reason: 'no conversation available to rewind' };
+        if (mode === 'conversation') out.ok = false;
+      } else {
+        const plan = planConversationRewind(messages, rec.turn);
+        if (plan.ok) {
+          // Post-rewind message policy: DISCARD. The messages after the rewind
+          // point are removed from active history (returned as `removed` for the
+          // caller to optionally archive — the store does not retain them).
+          out.conversation = {
+            ok: true,
+            cutIndex: plan.cutIndex,
+            removedCount: plan.removed.length,
+            messages: plan.kept,
+            removed: plan.removed,
+            turnId: rec.turn && rec.turn.turnId ? rec.turn.turnId : null,
+          };
+          try { logCheckpoint(targetSeq, `rewind truncated conversation to ${rec.turn && rec.turn.turnId ? rec.turn.turnId : `seq ${targetSeq}`} (${plan.removed.length} message(s) discarded)`); } catch { /* never throws */ }
+        } else {
+          out.conversation = { ok: false, reason: plan.reason };
+          out.ok = false;
+        }
+      }
+    }
+
+    return out;
+  }
+
+  return {
+    enabled,
+    getSession,
+    setSession,
+    setTurnContext,
+    beginCapture,
+    list,
+    rewind,
+    // test/diagnostic seams
+    _sessionDir,
+    _loadRecord,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Conversation-rewind helpers (Task 4.3b, Part 2) — pure, unit-testable.
+// ---------------------------------------------------------------------------
+
+// Native function-calling requires a consistent tool_calls ↔ tool-result map: a
+// tool message must answer a preceding assistant tool_call, and an assistant
+// tool_call must be answered (the 4.0c invariant — an orphan breaks the next
+// turn). Returns the list of orphaned tool_call ids ([] = consistent). Used to
+// PROVE a conversation cut never left a dangling pair.
+function findOrphanedToolCalls(messages) {
+  const declared = new Set();
+  const answered = new Set();
+  for (const m of (Array.isArray(messages) ? messages : [])) {
+    if (m && m.role === 'assistant' && Array.isArray(m.tool_calls)) {
+      for (const tc of m.tool_calls) { if (tc && tc.id) declared.add(tc.id); }
+    }
+    if (m && m.role === 'tool' && m.tool_call_id) answered.add(m.tool_call_id);
+  }
+  const orphans = [];
+  for (const id of declared) { if (!answered.has(id)) orphans.push(id); }
+  for (const id of answered) { if (!declared.has(id)) orphans.push(id); }
+  return orphans;
+}
+
+// Snap an arbitrary message index back to the start of its turn — the nearest
+// `user` message at or before `idx`. A turn always begins with a user message
+// and all of its assistant/tool messages follow, so cutting at a user boundary
+// can never split a tool_call/tool-result pair. Returns 0 if no user message is
+// at/before idx (cut everything).
+function snapToTurnBoundary(messages, idx) {
+  const n = Array.isArray(messages) ? messages.length : 0;
+  let i = Math.min(typeof idx === 'number' ? idx : n, n - 1);
+  for (; i >= 0; i--) {
+    if (messages[i] && messages[i].role === 'user') return i;
+  }
+  return 0;
+}
+
+// Locate, in the CURRENT messages array, the index of the user message that
+// began the turn this checkpoint belongs to. Robust to index shifts (e.g.
+// compaction since capture): prefer matching the recorded promptId (a hash of
+// the turn's user prompt) against user messages; fall back to promptIndex /
+// messageCountAtStart only when they still point at a user message. Returns -1
+// when the turn can no longer be located (it was compacted/cleared away).
+function locateTurnStart(messages, turn) {
+  if (!Array.isArray(messages) || !turn) return -1;
+  if (turn.promptId) {
+    for (let i = 0; i < messages.length; i++) {
+      const m = messages[i];
+      if (m && m.role === 'user' && typeof m.content === 'string'
+          && _sha256(Buffer.from(m.content)).slice(0, 12) === turn.promptId) {
+        return i;
+      }
+    }
+  }
+  const candidates = [];
+  if (Number.isInteger(turn.promptIndex)) candidates.push(turn.promptIndex);
+  if (Number.isInteger(turn.messageCountAtStart)) candidates.push(turn.messageCountAtStart - 1);
+  // Prefer a candidate that is exactly a user message (a turn boundary).
+  for (const c of candidates) {
+    if (c >= 0 && c < messages.length && messages[c] && messages[c].role === 'user') return c;
+  }
+  // Otherwise fall back to the first in-range candidate — snapToTurnBoundary will
+  // walk it back to the nearest user boundary, so a stale index that lands
+  // mid-turn never cuts a tool_call/tool-result pair.
+  for (const c of candidates) {
+    if (c >= 0 && c < messages.length) return c;
+  }
+  return -1;
+}
+
+// Plan a conversation rewind: given the live messages and a checkpoint's turn
+// linkage, return where to cut on a turn boundary. { ok, cutIndex, kept, removed }
+// or { ok:false, reason }. The cut removes the turn's user prompt and everything
+// after it (discard policy) — the conversation returns to the coherent state
+// before that prompt was issued.
+function planConversationRewind(messages, turn) {
+  if (!Array.isArray(messages)) return { ok: false, reason: 'no conversation available to rewind' };
+  if (!turn) return { ok: false, reason: 'checkpoint has no turn linkage' };
+  let idx = locateTurnStart(messages, turn);
+  if (idx < 0) return { ok: false, reason: 'could not locate this turn in the current conversation (it may have been compacted or cleared)' };
+  idx = snapToTurnBoundary(messages, idx);
+  return { ok: true, cutIndex: idx, kept: messages.slice(0, idx), removed: messages.slice(idx) };
+}
+
+// Resolve the most-recently-active session directory under rootDir (by the
+// newest checkpoint file mtime). Used by the standalone `semalt-code rewind`
+// command, which runs in a fresh process with no in-memory session.
+function latestSession(rootDir = DEFAULT_ROOT, fs = realFs) {
+  let entries = [];
+  try { entries = fs.readdirSync(rootDir); } catch { return null; }
+  let best = null;
+  let bestMtime = -1;
+  for (const name of entries) {
+    const dir = path.join(rootDir, name);
+    let files = [];
+    try {
+      const st = fs.statSync(dir);
+      if (!st.isDirectory()) continue;
+      files = fs.readdirSync(dir).filter((f) => /^\d+\.json$/.test(f));
+    } catch { continue; }
+    if (!files.length) continue;
+    for (const f of files) {
+      try {
+        const m = fs.statSync(path.join(dir, f)).mtimeMs;
+        if (m > bestMtime) { bestMtime = m; best = name; }
+      } catch { /* skip */ }
+    }
+  }
+  return best;
+}
+
+// The three restore modes (Task 4.3b). `both` is the default — the coherent
+// linked state (files + the conversation that produced them).
+const REWIND_MODES = ['code', 'conversation', 'both'];
+
+// Parse a user-supplied mode token, defaulting to 'both'. Unknown tokens return
+// null so the caller can reject them rather than silently rewinding the wrong
+// surface.
+function normalizeRewindMode(token) {
+  if (token == null || token === '') return 'both';
+  const t = String(token).toLowerCase();
+  return REWIND_MODES.includes(t) ? t : null;
+}
+
+// Surfaced wherever rewind is shown so the user never mistakes it for full undo.
+const SCOPE_NOTICE =
+  'Note: rewind restores file-tool changes only (write/edit/delete/move/copy/upload). '
+  + 'Shell side effects (commands that created files, touched a DB, or hit the network) are NOT reversible.';
+
+// Render the checkpoint list as plain text (no ANSI) for both the CLI command
+// and the in-chat /rewind view.
+function formatCheckpointList(items, { session } = {}) {
+  const lines = [];
+  lines.push(`Checkpoints${session ? ` (session ${session})` : ''}:`);
+  if (!items.length) {
+    lines.push('  (none — nothing to rewind yet)');
+  } else {
+    for (const it of items) {
+      const flag = it.rewindable ? '' : ' [partial: some files too large/dir — rewind unavailable]';
+      const turn = it.turn && it.turn.turnId ? ` · ${it.turn.turnId}` : '';
+      lines.push(`  [${it.seq}] ${it.summary}${turn}${flag}`);
+    }
+    lines.push('');
+    lines.push('Rewind with:  /rewind <seq>   or   /rewind last   (add  force  to override out-of-band edits)');
+  }
+  lines.push(SCOPE_NOTICE);
+  return lines.join('\n');
+}
+
+// Render a rewind() result as plain text.
+function formatRewindResult(res) {
+  if (!res) return 'Rewind failed: no result.';
+  if (res.error) return `Rewind failed: ${res.error}`;
+  if (res.blocked) {
+    const lines = [res.message];
+    for (const p of res.externallyModified) lines.push(`  changed: ${p}`);
+    lines.push(`Re-run:  /rewind ${res.seq} force`);
+    return lines.join('\n');
+  }
+  const modeLabel = res.mode ? ` [${res.mode}]` : '';
+  const lines = [`Rewound checkpoint [${res.seq}]${modeLabel} (${res.action}).`];
+  for (const p of res.restored || []) lines.push(`  restored: ${p}`);
+  for (const p of res.forcedOverExternal || []) lines.push(`  overwrote out-of-band edit: ${p}`);
+  for (const r of res.refused || []) lines.push(`  refused (current guards): ${r.path} — ${r.reason}`);
+  for (const p of res.unrewindable || []) lines.push(`  skipped (too large / directory — no snapshot): ${p}`);
+  for (const f of res.failed || []) lines.push(`  FAILED: ${f.path} — ${f.error}`);
+  if (res.conversation) {
+    if (res.conversation.ok) {
+      lines.push(`  conversation: rewound to ${res.conversation.turnId || 'the matching turn'} — ${res.conversation.removedCount} message(s) discarded`);
+    } else {
+      lines.push(`  conversation: not rewound — ${res.conversation.reason}`);
+    }
+  }
+  lines.push(SCOPE_NOTICE);
+  return lines.join('\n');
+}
+
+module.exports = {
+  CHECKPOINTABLE_ACTIONS,
+  DEFAULT_ROOT,
+  SCOPE_NOTICE,
+  REWIND_MODES,
+  normalizeRewindMode,
+  normalizeCheckpoints,
+  createCheckpointStore,
+  latestSession,
+  formatCheckpointList,
+  formatRewindResult,
+  // Conversation-rewind helpers (Task 4.3b) — pure, exported for reuse + tests.
+  findOrphanedToolCalls,
+  snapToTurnBoundary,
+  locateTurnStart,
+  planConversationRewind,
+};