@git-stunts/git-warp 10.1.1 → 10.3.2

package/bin/warp-graph.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
@@ -10,12 +11,16 @@ import WarpGraph from '../src/domain/WarpGraph.js';
 import GitGraphAdapter from '../src/infrastructure/adapters/GitGraphAdapter.js';
 import HealthCheckService from '../src/domain/services/HealthCheckService.js';
 import ClockAdapter from '../src/infrastructure/adapters/ClockAdapter.js';
+import NodeCryptoAdapter from '../src/infrastructure/adapters/NodeCryptoAdapter.js';
 import {
   REF_PREFIX,
   buildCheckpointRef,
   buildCoverageRef,
   buildWritersPrefix,
   parseWriterIdFromRef,
+  buildCursorActiveRef,
+  buildCursorSavedRef,
+  buildCursorSavedPrefix,
 } from '../src/domain/utils/RefLayout.js';
 import { HookInstaller, classifyExistingHook } from '../src/domain/services/HookInstaller.js';
 import { renderInfoView } from '../src/visualization/renderers/ascii/info.js';
@@ -23,6 +28,8 @@ import { renderCheckView } from '../src/visualization/renderers/ascii/check.js';
 import { renderHistoryView, summarizeOps } from '../src/visualization/renderers/ascii/history.js';
 import { renderPathView } from '../src/visualization/renderers/ascii/path.js';
 import { renderMaterializeView } from '../src/visualization/renderers/ascii/materialize.js';
+import { parseCursorBlob } from '../src/domain/utils/parseCursorBlob.js';
+import { renderSeekView } from '../src/visualization/renderers/ascii/seek.js';
 import { renderGraphView } from '../src/visualization/renderers/ascii/graph.js';
 import { renderSvg } from '../src/visualization/renderers/svg/index.js';
 import { layoutGraph, queryResultToGraphData, pathResultToGraphData } from '../src/visualization/layouts/index.js';
@@ -44,6 +51,7 @@ Commands:
   history          Show writer history
   check            Report graph health/GC status
   materialize      Materialize and checkpoint all graphs
+  seek             Time-travel: step through graph history by Lamport tick
   view             Interactive TUI graph browser (requires @git-stunts/git-warp-tui)
   install-hooks    Install post-merge git hook
 
@@ -74,6 +82,14 @@ Path options:
 
 History options:
   --node <id>           Filter patches touching node id
+
+Seek options:
+  --tick <N|+N|-N>      Jump to tick N, or step forward/backward
+  --latest              Clear cursor, return to present
+  --save <name>         Save current position as named cursor
+  --load <name>         Restore a saved cursor
+  --list                List all saved cursors
+  --drop <name>         Delete a saved cursor
 `;
 
 /**
@@ -169,7 +185,7 @@ function consumeBaseArg({ argv, index, options, optionDefs, positionals }) {
   if (arg === '--view') {
     // Valid view modes: ascii, browser, svg:FILE, html:FILE
     // Don't consume known commands as modes
-    const KNOWN_COMMANDS = ['info', 'query', 'path', 'history', 'check', 'materialize', 'install-hooks'];
+    const KNOWN_COMMANDS = ['info', 'query', 'path', 'history', 'check', 'materialize', 'seek', 'install-hooks'];
     const nextArg = argv[index + 1];
     const isViewMode = nextArg &&
       !nextArg.startsWith('-') &&
@@ -271,6 +287,17 @@ async function resolveGraphName(persistence, explicitGraph) {
   throw usageError('Multiple graphs found; specify --graph');
 }
 
+/**
+ * Collects metadata about a single graph (writer count, refs, patches, checkpoint).
+ * @param {Object} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the graph to inspect
+ * @param {Object} [options]
+ * @param {boolean} [options.includeWriterIds=false] - Include writer ID list
+ * @param {boolean} [options.includeRefs=false] - Include checkpoint/coverage refs
+ * @param {boolean} [options.includeWriterPatches=false] - Include per-writer patch counts
+ * @param {boolean} [options.includeCheckpointDate=false] - Include checkpoint date
+ * @returns {Promise<Object>} Graph info object
+ */
 async function getGraphInfo(persistence, graphName, {
   includeWriterIds = false,
   includeRefs = false,
@@ -322,6 +349,7 @@ async function getGraphInfo(persistence, graphName, {
       persistence,
       graphName,
       writerId: 'cli',
+      crypto: new NodeCryptoAdapter(),
     });
     const writerPatches = {};
     for (const writerId of writerIds) {
@@ -334,13 +362,29 @@ async function getGraphInfo(persistence, graphName, {
   return info;
 }
 
+/**
+ * Opens a WarpGraph for the given CLI options.
+ * @param {Object} options - Parsed CLI options
+ * @param {string} [options.repo] - Repository path
+ * @param {string} [options.graph] - Explicit graph name
+ * @param {string} [options.writer] - Writer ID
+ * @returns {Promise<{graph: Object, graphName: string, persistence: Object}>}
+ * @throws {CliError} If the specified graph is not found
+ */
 async function openGraph(options) {
   const { persistence } = await createPersistence(options.repo);
   const graphName = await resolveGraphName(persistence, options.graph);
+  if (options.graph) {
+    const graphNames = await listGraphNames(persistence);
+    if (!graphNames.includes(options.graph)) {
+      throw notFoundError(`Graph not found: ${options.graph}`);
+    }
+  }
   const graph = await WarpGraph.open({
     persistence,
     graphName,
     writerId: options.writer,
+    crypto: new NodeCryptoAdapter(),
   });
   return { graph, graphName, persistence };
 }
@@ -603,6 +647,9 @@ function renderInfo(payload) {
     if (graph.coverage?.sha) {
       lines.push(`  coverage: ${graph.coverage.sha}`);
     }
+    if (graph.cursor?.active) {
+      lines.push(`  cursor: tick ${graph.cursor.tick} (${graph.cursor.mode})`);
+    }
   }
   return `${lines.join('\n')}\n`;
 }
@@ -742,6 +789,26 @@ function renderError(payload) {
   return `Error: ${payload.error.message}\n`;
 }
 
+/**
+ * Wraps SVG content in a minimal HTML document and writes it to disk.
+ * @param {string} filePath - Destination file path
+ * @param {string} svgContent - SVG markup to embed
+ */
+function writeHtmlExport(filePath, svgContent) {
+  const html = `<!DOCTYPE html>\n<html><head><meta charset="utf-8"><title>git-warp</title></head><body>\n${svgContent}\n</body></html>`;
+  fs.writeFileSync(filePath, html);
+}
+
+/**
+ * Writes a command result to stdout/stderr in the appropriate format.
+ * Dispatches to JSON, SVG file, HTML file, ASCII view, or plain text
+ * based on the combination of flags.
+ * @param {Object} payload - Command result payload
+ * @param {Object} options
+ * @param {boolean} options.json - Emit JSON to stdout
+ * @param {string} options.command - Command name (info, query, path, etc.)
+ * @param {string|boolean} options.view - View mode (true for ascii, 'svg:PATH', 'html:PATH', 'browser')
+ */
 function emit(payload, { json, command, view }) {
   if (json) {
     process.stdout.write(`${stableStringify(payload)}\n`);
@@ -766,6 +833,14 @@ function emit(payload, { json, command, view }) {
         fs.writeFileSync(svgPath, payload._renderedSvg);
         process.stderr.write(`SVG written to ${svgPath}\n`);
       }
+    } else if (view && typeof view === 'string' && view.startsWith('html:')) {
+      const htmlPath = view.slice(5);
+      if (!payload._renderedSvg) {
+        process.stderr.write('No graph data — skipping HTML export.\n');
+      } else {
+        writeHtmlExport(htmlPath, payload._renderedSvg);
+        process.stderr.write(`HTML written to ${htmlPath}\n`);
+      }
     } else if (view) {
       process.stdout.write(`${payload._renderedAscii}\n`);
     } else {
@@ -783,6 +858,14 @@ function emit(payload, { json, command, view }) {
         fs.writeFileSync(svgPath, payload._renderedSvg);
         process.stderr.write(`SVG written to ${svgPath}\n`);
       }
+    } else if (view && typeof view === 'string' && view.startsWith('html:')) {
+      const htmlPath = view.slice(5);
+      if (!payload._renderedSvg) {
+        process.stderr.write('No path found — skipping HTML export.\n');
+      } else {
+        writeHtmlExport(htmlPath, payload._renderedSvg);
+        process.stderr.write(`HTML written to ${htmlPath}\n`);
+      }
     } else if (view) {
       process.stdout.write(renderPathView(payload));
     } else {
@@ -818,6 +901,15 @@ function emit(payload, { json, command, view }) {
     return;
   }
 
+  if (command === 'seek') {
+    if (view) {
+      process.stdout.write(renderSeekView(payload));
+    } else {
+      process.stdout.write(renderSeek(payload));
+    }
+    return;
+  }
+
   if (command === 'install-hooks') {
     process.stdout.write(renderInstallHooks(payload));
     return;
@@ -859,12 +951,19 @@ async function handleInfo({ options }) {
   const graphs = [];
   for (const name of graphNames) {
     const includeDetails = detailGraphs.has(name);
-    graphs.push(await getGraphInfo(persistence, name, {
+    const info = await getGraphInfo(persistence, name, {
       includeWriterIds: includeDetails || isViewMode,
       includeRefs: includeDetails || isViewMode,
       includeWriterPatches: isViewMode,
       includeCheckpointDate: isViewMode,
-    }));
+    });
+    const activeCursor = await readActiveCursor(persistence, name);
+    if (activeCursor) {
+      info.cursor = { active: true, tick: activeCursor.tick, mode: activeCursor.mode };
+    } else {
+      info.cursor = { active: false };
+    }
+    graphs.push(info);
   }
 
   return {
@@ -883,7 +982,9 @@ async function handleInfo({ options }) {
  */
 async function handleQuery({ options, args }) {
   const querySpec = parseQueryArgs(args);
-  const { graph, graphName } = await openGraph(options);
+  const { graph, graphName, persistence } = await openGraph(options);
+  const cursorInfo = await applyCursorCeiling(graph, persistence, graphName);
+  emitCursorWarning(cursorInfo, null);
   let builder = graph.query();
 
   if (querySpec.match !== null) {
@@ -904,7 +1005,7 @@ async function handleQuery({ options, args }) {
       const edges = await graph.getEdges();
       const graphData = queryResultToGraphData(payload, edges);
       const positioned = await layoutGraph(graphData, { type: 'query' });
-      if (typeof options.view === 'string' && options.view.startsWith('svg:')) {
+      if (typeof options.view === 'string' && (options.view.startsWith('svg:') || options.view.startsWith('html:'))) {
         payload._renderedSvg = renderSvg(positioned, { title: `${graphName} query` });
       } else {
         payload._renderedAscii = renderGraphView(positioned, { title: `QUERY: ${graphName}` });
@@ -974,7 +1075,9 @@ function mapQueryError(error) {
  */
 async function handlePath({ options, args }) {
   const pathOptions = parsePathArgs(args);
-  const { graph, graphName } = await openGraph(options);
+  const { graph, graphName, persistence } = await openGraph(options);
+  const cursorInfo = await applyCursorCeiling(graph, persistence, graphName);
+  emitCursorWarning(cursorInfo, null);
 
   try {
     const result = await graph.traverse.shortestPath(
@@ -994,7 +1097,7 @@ async function handlePath({ options, args }) {
       ...result,
     };
 
-    if (options.view && result.found && typeof options.view === 'string' && options.view.startsWith('svg:')) {
+    if (options.view && result.found && typeof options.view === 'string' && (options.view.startsWith('svg:') || options.view.startsWith('html:'))) {
       const graphData = pathResultToGraphData(payload);
       const positioned = await layoutGraph(graphData, { type: 'path' });
       payload._renderedSvg = renderSvg(positioned, { title: `${graphName} path` });
@@ -1020,6 +1123,8 @@ async function handlePath({ options, args }) {
  */
 async function handleCheck({ options }) {
   const { graph, graphName, persistence } = await openGraph(options);
+  const cursorInfo = await applyCursorCeiling(graph, persistence, graphName);
+  emitCursorWarning(cursorInfo, null);
   const health = await getHealth(persistence);
   const gcMetrics = await getGcMetrics(graph);
   const status = await graph.status();
@@ -1157,9 +1262,15 @@ function buildCheckPayload({
  */
 async function handleHistory({ options, args }) {
   const historyOptions = parseHistoryArgs(args);
-  const { graph, graphName } = await openGraph(options);
+  const { graph, graphName, persistence } = await openGraph(options);
+  const cursorInfo = await applyCursorCeiling(graph, persistence, graphName);
+  emitCursorWarning(cursorInfo, null);
+
   const writerId = options.writer;
-  const patches = await graph.getWriterPatches(writerId);
+  let patches = await graph.getWriterPatches(writerId);
+  if (cursorInfo.active) {
+    patches = patches.filter(({ patch }) => patch.lamport <= cursorInfo.tick);
+  }
   if (patches.length === 0) {
     throw notFoundError(`No patches found for writer: ${writerId}`);
   }
@@ -1184,12 +1295,23 @@ async function handleHistory({ options, args }) {
   return { payload, exitCode: EXIT_CODES.OK };
 }
 
-async function materializeOneGraph({ persistence, graphName, writerId }) {
-  const graph = await WarpGraph.open({ persistence, graphName, writerId });
-  await graph.materialize();
+/**
+ * Materializes a single graph, creates a checkpoint, and returns summary stats.
+ * When a ceiling tick is provided (seek cursor active), the checkpoint step is
+ * skipped because the user is exploring historical state, not persisting it.
+ * @param {Object} params
+ * @param {Object} params.persistence - GraphPersistencePort adapter
+ * @param {string} params.graphName - Name of the graph to materialize
+ * @param {string} params.writerId - Writer ID for the CLI session
+ * @param {number} [params.ceiling] - Optional seek ceiling tick
+ * @returns {Promise<{graph: string, nodes: number, edges: number, properties: number, checkpoint: string|null, writers: Object, patchCount: number}>}
+ */
+async function materializeOneGraph({ persistence, graphName, writerId, ceiling }) {
+  const graph = await WarpGraph.open({ persistence, graphName, writerId, crypto: new NodeCryptoAdapter() });
+  await graph.materialize(ceiling !== undefined ? { ceiling } : undefined);
   const nodes = await graph.getNodes();
   const edges = await graph.getEdges();
-  const checkpoint = await graph.createCheckpoint();
+  const checkpoint = ceiling !== undefined ? null : await graph.createCheckpoint();
   const status = await graph.status();
 
   // Build per-writer patch counts for the view renderer
@@ -1241,12 +1363,20 @@ async function handleMaterialize({ options }) {
   }
 
   const results = [];
+  let cursorWarningEmitted = false;
   for (const name of targets) {
     try {
+      const cursor = await readActiveCursor(persistence, name);
+      const ceiling = cursor ? cursor.tick : undefined;
+      if (cursor && !cursorWarningEmitted) {
+        emitCursorWarning({ active: true, tick: cursor.tick, maxTick: null }, null);
+        cursorWarningEmitted = true;
+      }
       const result = await materializeOneGraph({
         persistence,
         graphName: name,
         writerId: options.writer,
+        ceiling,
       });
       results.push(result);
     } catch (error) {
@@ -1465,6 +1595,828 @@ function getHookStatusForCheck(repoPath) {
   }
 }
 
+// ============================================================================
+// Cursor I/O Helpers
+// ============================================================================
+
+/**
+ * Reads the active seek cursor for a graph from Git ref storage.
+ *
+ * @private
+ * @param {Object} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @returns {Promise<{tick: number, mode?: string}|null>} Cursor object, or null if no active cursor
+ * @throws {Error} If the stored blob is corrupted or not valid JSON
+ */
+async function readActiveCursor(persistence, graphName) {
+  const ref = buildCursorActiveRef(graphName);
+  const oid = await persistence.readRef(ref);
+  if (!oid) {
+    return null;
+  }
+  const buf = await persistence.readBlob(oid);
+  return parseCursorBlob(buf, 'active cursor');
+}
+
+/**
+ * Writes (creates or overwrites) the active seek cursor for a graph.
+ *
+ * Serializes the cursor as JSON, stores it as a Git blob, and points
+ * the active cursor ref at that blob.
+ *
+ * @private
+ * @param {Object} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @param {{tick: number, mode?: string}} cursor - Cursor state to persist
+ * @returns {Promise<void>}
+ */
+async function writeActiveCursor(persistence, graphName, cursor) {
+  const ref = buildCursorActiveRef(graphName);
+  const json = JSON.stringify(cursor);
+  const oid = await persistence.writeBlob(Buffer.from(json, 'utf8'));
+  await persistence.updateRef(ref, oid);
+}
+
+/**
+ * Removes the active seek cursor for a graph, returning to present state.
+ *
+ * No-op if no active cursor exists.
+ *
+ * @private
+ * @param {Object} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @returns {Promise<void>}
+ */
+async function clearActiveCursor(persistence, graphName) {
+  const ref = buildCursorActiveRef(graphName);
+  const exists = await persistence.readRef(ref);
+  if (exists) {
+    await persistence.deleteRef(ref);
+  }
+}
+
+/**
+ * Reads a named saved cursor from Git ref storage.
+ *
+ * @private
+ * @param {Object} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @param {string} name - Saved cursor name
+ * @returns {Promise<{tick: number, mode?: string}|null>} Cursor object, or null if not found
+ * @throws {Error} If the stored blob is corrupted or not valid JSON
+ */
+async function readSavedCursor(persistence, graphName, name) {
+  const ref = buildCursorSavedRef(graphName, name);
+  const oid = await persistence.readRef(ref);
+  if (!oid) {
+    return null;
+  }
+  const buf = await persistence.readBlob(oid);
+  return parseCursorBlob(buf, `saved cursor '${name}'`);
+}
+
+/**
+ * Persists a cursor under a named saved-cursor ref.
+ *
+ * Serializes the cursor as JSON, stores it as a Git blob, and points
+ * the named saved-cursor ref at that blob.
+ *
+ * @private
+ * @param {Object} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @param {string} name - Saved cursor name
+ * @param {{tick: number, mode?: string}} cursor - Cursor state to persist
+ * @returns {Promise<void>}
+ */
+async function writeSavedCursor(persistence, graphName, name, cursor) {
+  const ref = buildCursorSavedRef(graphName, name);
+  const json = JSON.stringify(cursor);
+  const oid = await persistence.writeBlob(Buffer.from(json, 'utf8'));
+  await persistence.updateRef(ref, oid);
+}
+
+/**
+ * Deletes a named saved cursor from Git ref storage.
+ *
+ * No-op if the named cursor does not exist.
+ *
+ * @private
+ * @param {Object} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @param {string} name - Saved cursor name to delete
+ * @returns {Promise<void>}
+ */
+async function deleteSavedCursor(persistence, graphName, name) {
+  const ref = buildCursorSavedRef(graphName, name);
+  const exists = await persistence.readRef(ref);
+  if (exists) {
+    await persistence.deleteRef(ref);
+  }
+}
+
+/**
+ * Lists all saved cursors for a graph, reading each blob to include full cursor state.
+ *
+ * @private
+ * @param {Object} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @returns {Promise<Array<{name: string, tick: number, mode?: string}>>} Array of saved cursors with their names
+ * @throws {Error} If any stored blob is corrupted or not valid JSON
+ */
+async function listSavedCursors(persistence, graphName) {
+  const prefix = buildCursorSavedPrefix(graphName);
+  const refs = await persistence.listRefs(prefix);
+  const cursors = [];
+  for (const ref of refs) {
+    const name = ref.slice(prefix.length);
+    if (name) {
+      const oid = await persistence.readRef(ref);
+      if (oid) {
+        const buf = await persistence.readBlob(oid);
+        const cursor = parseCursorBlob(buf, `saved cursor '${name}'`);
+        cursors.push({ name, ...cursor });
+      }
+    }
+  }
+  return cursors;
+}
+
+// ============================================================================
+// Seek Arg Parser
+// ============================================================================
+
+/**
+ * Parses CLI arguments for the `seek` command into a structured spec.
+ *
+ * Supports mutually exclusive actions: `--tick <value>`, `--latest`,
+ * `--save <name>`, `--load <name>`, `--list`, `--drop <name>`.
+ * Defaults to `status` when no flags are provided.
+ *
+ * @private
+ * @param {string[]} args - Raw CLI arguments following the `seek` subcommand
+ * @returns {{action: string, tickValue: string|null, name: string|null}} Parsed spec
+ * @throws {CliError} If arguments are invalid or flags are combined
+ */
+function parseSeekArgs(args) {
+  const spec = {
+    action: 'status', // status, tick, latest, save, load, list, drop
+    tickValue: null,
+    name: null,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--tick') {
+      if (spec.action !== 'status') {
+        throw usageError('--tick cannot be combined with other seek flags');
+      }
+      spec.action = 'tick';
+      const val = args[i + 1];
+      if (val === undefined) {
+        throw usageError('Missing value for --tick');
+      }
+      spec.tickValue = val;
+      i += 1;
+    } else if (arg.startsWith('--tick=')) {
+      if (spec.action !== 'status') {
+        throw usageError('--tick cannot be combined with other seek flags');
+      }
+      spec.action = 'tick';
+      spec.tickValue = arg.slice('--tick='.length);
+    } else if (arg === '--latest') {
+      if (spec.action !== 'status') {
+        throw usageError('--latest cannot be combined with other seek flags');
+      }
+      spec.action = 'latest';
+    } else if (arg === '--save') {
+      if (spec.action !== 'status') {
+        throw usageError('--save cannot be combined with other seek flags');
+      }
+      spec.action = 'save';
+      const val = args[i + 1];
+      if (val === undefined || val.startsWith('-')) {
+        throw usageError('Missing name for --save');
+      }
+      spec.name = val;
+      i += 1;
+    } else if (arg.startsWith('--save=')) {
+      if (spec.action !== 'status') {
+        throw usageError('--save cannot be combined with other seek flags');
+      }
+      spec.action = 'save';
+      spec.name = arg.slice('--save='.length);
+      if (!spec.name) {
+        throw usageError('Missing name for --save');
+      }
+    } else if (arg === '--load') {
+      if (spec.action !== 'status') {
+        throw usageError('--load cannot be combined with other seek flags');
+      }
+      spec.action = 'load';
+      const val = args[i + 1];
+      if (val === undefined || val.startsWith('-')) {
+        throw usageError('Missing name for --load');
+      }
+      spec.name = val;
+      i += 1;
+    } else if (arg.startsWith('--load=')) {
+      if (spec.action !== 'status') {
+        throw usageError('--load cannot be combined with other seek flags');
+      }
+      spec.action = 'load';
+      spec.name = arg.slice('--load='.length);
+      if (!spec.name) {
+        throw usageError('Missing name for --load');
+      }
+    } else if (arg === '--list') {
+      if (spec.action !== 'status') {
+        throw usageError('--list cannot be combined with other seek flags');
+      }
+      spec.action = 'list';
+    } else if (arg === '--drop') {
+      if (spec.action !== 'status') {
+        throw usageError('--drop cannot be combined with other seek flags');
+      }
+      spec.action = 'drop';
+      const val = args[i + 1];
+      if (val === undefined || val.startsWith('-')) {
+        throw usageError('Missing name for --drop');
+      }
+      spec.name = val;
+      i += 1;
+    } else if (arg.startsWith('--drop=')) {
+      if (spec.action !== 'status') {
+        throw usageError('--drop cannot be combined with other seek flags');
+      }
+      spec.action = 'drop';
+      spec.name = arg.slice('--drop='.length);
+      if (!spec.name) {
+        throw usageError('Missing name for --drop');
+      }
+    } else if (arg.startsWith('-')) {
+      throw usageError(`Unknown seek option: ${arg}`);
+    }
+  }
+
+  return spec;
+}
+
+/**
+ * Resolves a tick value (absolute or relative +N/-N) against available ticks.
+ *
+ * For relative values, steps through the sorted tick array (with 0 prepended
+ * as a virtual "empty state" position) by the given delta from the current
+ * position. For absolute values, clamps to maxTick.
+ *
+ * @private
+ * @param {string} tickValue - Raw tick string from CLI args (e.g. "5", "+1", "-2")
+ * @param {number|null} currentTick - Current cursor tick, or null if no active cursor
+ * @param {number[]} ticks - Sorted ascending array of available Lamport ticks
+ * @param {number} maxTick - Maximum tick across all writers
+ * @returns {number} Resolved tick value (clamped to valid range)
+ * @throws {CliError} If tickValue is not a valid integer or relative delta
+ */
+function resolveTickValue(tickValue, currentTick, ticks, maxTick) {
+  // Relative: +N or -N
+  if (tickValue.startsWith('+') || tickValue.startsWith('-')) {
+    const delta = parseInt(tickValue, 10);
+    if (!Number.isInteger(delta)) {
+      throw usageError(`Invalid tick delta: ${tickValue}`);
+    }
+    const base = currentTick ?? 0;
+
+    // Find the current position in sorted ticks, then step by delta
+    // Include tick 0 as a virtual "empty state" position (avoid duplicating if already present)
+    const allPoints = (ticks.length > 0 && ticks[0] === 0) ? [...ticks] : [0, ...ticks];
+    const currentIdx = allPoints.indexOf(base);
+    const startIdx = currentIdx === -1 ? 0 : currentIdx;
+    const targetIdx = Math.max(0, Math.min(allPoints.length - 1, startIdx + delta));
+    return allPoints[targetIdx];
+  }
+
+  // Absolute
+  const n = parseInt(tickValue, 10);
+  if (!Number.isInteger(n) || n < 0) {
+    throw usageError(`Invalid tick value: ${tickValue}. Must be a non-negative integer, or +N/-N for relative.`);
+  }
+
+  // Clamp to maxTick
+  return Math.min(n, maxTick);
+}
+
+// ============================================================================
+// Seek Handler
+// ============================================================================
+
+/**
+ * Handles the `git warp seek` command across all sub-actions.
+ *
+ * Dispatches to the appropriate logic based on the parsed action:
+ * - `status`: show current cursor position or "no cursor" state
+ * - `tick`: set the cursor to an absolute or relative Lamport tick
+ * - `latest`: clear the cursor, returning to present state
+ * - `save`: persist the active cursor under a name
+ * - `load`: restore a named cursor as the active cursor
+ * - `list`: enumerate all saved cursors
+ * - `drop`: delete a named saved cursor
+ *
+ * @private
+ * @param {Object} params - Command parameters
+ * @param {Object} params.options - CLI options (repo, graph, writer, json)
+ * @param {string[]} params.args - Raw CLI arguments following the `seek` subcommand
+ * @returns {Promise<{payload: Object, exitCode: number}>} Command result with payload and exit code
+ * @throws {CliError} On invalid arguments or missing cursors
+ */
+async function handleSeek({ options, args }) {
+  const seekSpec = parseSeekArgs(args);
+  const { graph, graphName, persistence } = await openGraph(options);
+  const activeCursor = await readActiveCursor(persistence, graphName);
+  const { ticks, maxTick, perWriter } = await graph.discoverTicks();
+  const frontierHash = computeFrontierHash(perWriter);
+  if (seekSpec.action === 'list') {
+    const saved = await listSavedCursors(persistence, graphName);
+    return {
+      payload: {
+        graph: graphName,
+        action: 'list',
+        cursors: saved,
+        activeTick: activeCursor ? activeCursor.tick : null,
+        maxTick,
+      },
+      exitCode: EXIT_CODES.OK,
+    };
+  }
+  if (seekSpec.action === 'drop') {
+    const existing = await readSavedCursor(persistence, graphName, seekSpec.name);
+    if (!existing) {
+      throw notFoundError(`Saved cursor not found: ${seekSpec.name}`);
+    }
+    await deleteSavedCursor(persistence, graphName, seekSpec.name);
+    return {
+      payload: {
+        graph: graphName,
+        action: 'drop',
+        name: seekSpec.name,
+        tick: existing.tick,
+      },
+      exitCode: EXIT_CODES.OK,
+    };
+  }
+  if (seekSpec.action === 'latest') {
+    await clearActiveCursor(persistence, graphName);
+    await graph.materialize();
+    const nodes = await graph.getNodes();
+    const edges = await graph.getEdges();
+    const diff = computeSeekStateDiff(activeCursor, { nodes: nodes.length, edges: edges.length }, frontierHash);
+    const tickReceipt = await buildTickReceipt({ tick: maxTick, perWriter, graph });
+    return {
+      payload: {
+        graph: graphName,
+        action: 'latest',
+        tick: maxTick,
+        maxTick,
+        ticks,
+        nodes: nodes.length,
+        edges: edges.length,
+        perWriter: serializePerWriter(perWriter),
+        patchCount: countPatchesAtTick(maxTick, perWriter),
+        diff,
+        tickReceipt,
+        cursor: { active: false },
+      },
+      exitCode: EXIT_CODES.OK,
+    };
+  }
+  if (seekSpec.action === 'save') {
+    if (!activeCursor) {
+      throw usageError('No active cursor to save. Use --tick first.');
+    }
+    await writeSavedCursor(persistence, graphName, seekSpec.name, activeCursor);
+    return {
+      payload: {
+        graph: graphName,
+        action: 'save',
+        name: seekSpec.name,
+        tick: activeCursor.tick,
+      },
+      exitCode: EXIT_CODES.OK,
+    };
+  }
+  if (seekSpec.action === 'load') {
+    const saved = await readSavedCursor(persistence, graphName, seekSpec.name);
+    if (!saved) {
+      throw notFoundError(`Saved cursor not found: ${seekSpec.name}`);
+    }
+    await graph.materialize({ ceiling: saved.tick });
+    const nodes = await graph.getNodes();
+    const edges = await graph.getEdges();
+    await writeActiveCursor(persistence, graphName, { tick: saved.tick, mode: saved.mode ?? 'lamport', nodes: nodes.length, edges: edges.length, frontierHash });
+    const diff = computeSeekStateDiff(activeCursor, { nodes: nodes.length, edges: edges.length }, frontierHash);
+    const tickReceipt = await buildTickReceipt({ tick: saved.tick, perWriter, graph });
+    return {
+      payload: {
+        graph: graphName,
+        action: 'load',
+        name: seekSpec.name,
+        tick: saved.tick,
+        maxTick,
+        ticks,
+        nodes: nodes.length,
+        edges: edges.length,
+        perWriter: serializePerWriter(perWriter),
+        patchCount: countPatchesAtTick(saved.tick, perWriter),
+        diff,
+        tickReceipt,
+        cursor: { active: true, mode: saved.mode, tick: saved.tick, maxTick, name: seekSpec.name },
+      },
+      exitCode: EXIT_CODES.OK,
+    };
+  }
+  if (seekSpec.action === 'tick') {
+    const currentTick = activeCursor ? activeCursor.tick : null;
+    const resolvedTick = resolveTickValue(seekSpec.tickValue, currentTick, ticks, maxTick);
+    await graph.materialize({ ceiling: resolvedTick });
+    const nodes = await graph.getNodes();
+    const edges = await graph.getEdges();
+    await writeActiveCursor(persistence, graphName, { tick: resolvedTick, mode: 'lamport', nodes: nodes.length, edges: edges.length, frontierHash });
+    const diff = computeSeekStateDiff(activeCursor, { nodes: nodes.length, edges: edges.length }, frontierHash);
+    const tickReceipt = await buildTickReceipt({ tick: resolvedTick, perWriter, graph });
+    return {
+      payload: {
+        graph: graphName,
+        action: 'tick',
+        tick: resolvedTick,
+        maxTick,
+        ticks,
+        nodes: nodes.length,
+        edges: edges.length,
+        perWriter: serializePerWriter(perWriter),
+        patchCount: countPatchesAtTick(resolvedTick, perWriter),
+        diff,
+        tickReceipt,
+        cursor: { active: true, mode: 'lamport', tick: resolvedTick, maxTick, name: 'active' },
+      },
+      exitCode: EXIT_CODES.OK,
+    };
+  }
+
+  // status (bare seek)
+  if (activeCursor) {
+    await graph.materialize({ ceiling: activeCursor.tick });
+    const nodes = await graph.getNodes();
+    const edges = await graph.getEdges();
+    const prevCounts = readSeekCounts(activeCursor);
+    const prevFrontierHash = typeof activeCursor.frontierHash === 'string' ? activeCursor.frontierHash : null;
+    if (prevCounts.nodes === null || prevCounts.edges === null || prevCounts.nodes !== nodes.length || prevCounts.edges !== edges.length || prevFrontierHash !== frontierHash) {
+      await writeActiveCursor(persistence, graphName, { tick: activeCursor.tick, mode: activeCursor.mode ?? 'lamport', nodes: nodes.length, edges: edges.length, frontierHash });
+    }
+    const diff = computeSeekStateDiff(activeCursor, { nodes: nodes.length, edges: edges.length }, frontierHash);
+    const tickReceipt = await buildTickReceipt({ tick: activeCursor.tick, perWriter, graph });
+    return {
+      payload: {
+        graph: graphName,
+        action: 'status',
+        tick: activeCursor.tick,
+        maxTick,
+        ticks,
+        nodes: nodes.length,
+        edges: edges.length,
+        perWriter: serializePerWriter(perWriter),
+        patchCount: countPatchesAtTick(activeCursor.tick, perWriter),
+        diff,
+        tickReceipt,
+        cursor: { active: true, mode: activeCursor.mode, tick: activeCursor.tick, maxTick, name: 'active' },
+      },
+      exitCode: EXIT_CODES.OK,
+    };
+  }
+  await graph.materialize();
+  const nodes = await graph.getNodes();
+  const edges = await graph.getEdges();
+  const tickReceipt = await buildTickReceipt({ tick: maxTick, perWriter, graph });
+  return {
+    payload: {
+      graph: graphName,
+      action: 'status',
+      tick: maxTick,
+      maxTick,
+      ticks,
+      nodes: nodes.length,
+      edges: edges.length,
+      perWriter: serializePerWriter(perWriter),
+      patchCount: countPatchesAtTick(maxTick, perWriter),
+      diff: null,
+      tickReceipt,
+      cursor: { active: false },
+    },
+    exitCode: EXIT_CODES.OK,
+  };
+}
+
+/**
+ * Converts the per-writer Map from discoverTicks() into a plain object for JSON output.
+ *
+ * @private
+ * @param {Map<string, {ticks: number[], tipSha: string|null}>} perWriter - Per-writer tick data
+ * @returns {Object<string, {ticks: number[], tipSha: string|null}>} Plain object keyed by writer ID
+ */
+function serializePerWriter(perWriter) {
+  const result = {};
+  for (const [writerId, info] of perWriter) {
+    result[writerId] = { ticks: info.ticks, tipSha: info.tipSha, tickShas: info.tickShas };
+  }
+  return result;
+}
+
+/**
+ * Counts the total number of patches across all writers at or before the given tick.
+ *
+ * @private
+ * @param {number} tick - Lamport tick ceiling (inclusive)
+ * @param {Map<string, {ticks: number[], tipSha: string|null}>} perWriter - Per-writer tick data
+ * @returns {number} Total patch count at or before the given tick
+ */
+function countPatchesAtTick(tick, perWriter) {
+  let count = 0;
+  for (const [, info] of perWriter) {
+    for (const t of info.ticks) {
+      if (t <= tick) {
+        count++;
+      }
+    }
+  }
+  return count;
+}
+
+/**
+ * Computes a stable fingerprint of the current graph frontier (writer tips).
+ *
+ * Used to suppress seek diffs when graph history may have changed since the
+ * previous cursor snapshot (e.g. new writers/patches, rewritten refs).
+ *
+ * @private
+ * @param {Map<string, {tipSha: string|null}>} perWriter - Per-writer metadata from discoverTicks()
+ * @returns {string} Hex digest of the frontier fingerprint
+ */
+function computeFrontierHash(perWriter) {
+  const tips = {};
+  for (const [writerId, info] of perWriter) {
+    tips[writerId] = info?.tipSha || null;
+  }
+  return crypto.createHash('sha256').update(stableStringify(tips)).digest('hex');
+}
+
+/**
+ * Reads cached seek state counts from a cursor blob.
+ *
+ * Counts may be missing for older cursors (pre-diff support). In that case
+ * callers should treat the counts as unknown and suppress diffs.
+ *
+ * @private
+ * @param {Object|null} cursor - Parsed cursor blob object
+ * @returns {{nodes: number|null, edges: number|null}} Parsed counts
+ */
+function readSeekCounts(cursor) {
+  if (!cursor || typeof cursor !== 'object') {
+    return { nodes: null, edges: null };
+  }
+
+  const nodes = typeof cursor.nodes === 'number' && Number.isFinite(cursor.nodes) ? cursor.nodes : null;
+  const edges = typeof cursor.edges === 'number' && Number.isFinite(cursor.edges) ? cursor.edges : null;
+  return { nodes, edges };
+}
+
+/**
+ * Computes node/edge deltas between the current seek position and the previous cursor.
+ *
+ * Returns null if the previous cursor is missing cached counts.
+ *
+ * @private
+ * @param {Object|null} prevCursor - Cursor object read before updating the position
+ * @param {{nodes: number, edges: number}} next - Current materialized counts
+ * @param {string} frontierHash - Frontier fingerprint of the current graph
+ * @returns {{nodes: number, edges: number}|null} Diff object or null when unknown
+ */
+function computeSeekStateDiff(prevCursor, next, frontierHash) {
+  const prev = readSeekCounts(prevCursor);
+  if (prev.nodes === null || prev.edges === null) {
+    return null;
+  }
+  const prevFrontierHash = typeof prevCursor?.frontierHash === 'string' ? prevCursor.frontierHash : null;
+  if (!prevFrontierHash || prevFrontierHash !== frontierHash) {
+    return null;
+  }
+  return {
+    nodes: next.nodes - prev.nodes,
+    edges: next.edges - prev.edges,
+  };
+}
+
+/**
+ * Builds a per-writer operation summary for patches at an exact tick.
+ *
+ * Uses discoverTicks() tickShas mapping to locate patch SHAs, then loads and
+ * summarizes patch ops. Typically only a handful of writers have a patch at any
+ * single Lamport tick.
+ *
+ * @private
+ * @param {Object} params
+ * @param {number} params.tick - Lamport tick to summarize
+ * @param {Map<string, {tickShas?: Object}>} params.perWriter - Per-writer tick metadata from discoverTicks()
+ * @param {Object} params.graph - WarpGraph instance
+ * @returns {Promise<Object<string, Object>|null>} Map of writerId → { sha, opSummary }, or null if empty
+ */
+async function buildTickReceipt({ tick, perWriter, graph }) {
+  if (!Number.isInteger(tick) || tick <= 0) {
+    return null;
+  }
+
+  const receipt = {};
+
+  for (const [writerId, info] of perWriter) {
+    const sha = info?.tickShas?.[tick];
+    if (!sha) {
+      continue;
+    }
+
+    const patch = await graph.loadPatchBySha(sha);
+    const ops = Array.isArray(patch?.ops) ? patch.ops : [];
+    receipt[writerId] = { sha, opSummary: summarizeOps(ops) };
+  }
+
+  return Object.keys(receipt).length > 0 ? receipt : null;
+}
+
+/**
+ * Renders a seek command payload as a human-readable string for terminal output.
+ *
+ * Handles all seek actions: list, drop, save, latest, load, tick, and status.
+ *
+ * @private
+ * @param {Object} payload - Seek result payload from handleSeek
+ * @returns {string} Formatted output string (includes trailing newline)
+ */
+function renderSeek(payload) {
+  const formatDelta = (n) => {
+    if (typeof n !== 'number' || !Number.isFinite(n) || n === 0) {
+      return '';
+    }
+    const sign = n > 0 ? '+' : '';
+    return ` (${sign}${n})`;
+  };
+
+  const formatOpSummaryPlain = (summary) => {
+    const order = [
+      ['NodeAdd', '+', 'node'],
+      ['EdgeAdd', '+', 'edge'],
+      ['PropSet', '~', 'prop'],
+      ['NodeTombstone', '-', 'node'],
+      ['EdgeTombstone', '-', 'edge'],
+      ['BlobValue', '+', 'blob'],
+    ];
+
+    const parts = [];
+    for (const [opType, symbol, label] of order) {
+      const n = summary?.[opType];
+      if (typeof n === 'number' && Number.isFinite(n) && n > 0) {
+        parts.push(`${symbol}${n}${label}`);
+      }
+    }
+    return parts.length > 0 ? parts.join(' ') : '(empty)';
+  };
+
+  const appendReceiptSummary = (baseLine) => {
+    const tickReceipt = payload?.tickReceipt;
+    if (!tickReceipt || typeof tickReceipt !== 'object') {
+      return `${baseLine}\n`;
+    }
+
+    const entries = Object.entries(tickReceipt)
+      .filter(([writerId, entry]) => writerId && entry && typeof entry === 'object')
+      .sort(([a], [b]) => a.localeCompare(b));
+
+    if (entries.length === 0) {
+      return `${baseLine}\n`;
+    }
+
+    const maxWriterLen = Math.max(5, ...entries.map(([writerId]) => writerId.length));
+    const receiptLines = [`  Tick ${payload.tick}:`];
+    for (const [writerId, entry] of entries) {
+      const sha = typeof entry.sha === 'string' ? entry.sha.slice(0, 7) : '';
+      const opSummary = entry.opSummary && typeof entry.opSummary === 'object' ? entry.opSummary : entry;
+      receiptLines.push(`    ${writerId.padEnd(maxWriterLen)}  ${sha.padEnd(7)}  ${formatOpSummaryPlain(opSummary)}`);
+    }
+
+    return `${baseLine}\n${receiptLines.join('\n')}\n`;
+  };
+
+  const buildStateStrings = () => {
+    const nodeLabel = payload.nodes === 1 ? 'node' : 'nodes';
+    const edgeLabel = payload.edges === 1 ? 'edge' : 'edges';
+    const patchLabel = payload.patchCount === 1 ? 'patch' : 'patches';
+    return {
+      nodesStr: `${payload.nodes} ${nodeLabel}${formatDelta(payload.diff?.nodes)}`,
+      edgesStr: `${payload.edges} ${edgeLabel}${formatDelta(payload.diff?.edges)}`,
+      patchesStr: `${payload.patchCount} ${patchLabel}`,
+    };
+  };
+
+  if (payload.action === 'list') {
+    if (payload.cursors.length === 0) {
+      return 'No saved cursors.\n';
+    }
+    const lines = [];
+    for (const c of payload.cursors) {
+      const active = c.tick === payload.activeTick ? ' (active)' : '';
+      lines.push(`  ${c.name}: tick ${c.tick}${active}`);
+    }
+    return `${lines.join('\n')}\n`;
+  }
+
+  if (payload.action === 'drop') {
+    return `Dropped cursor "${payload.name}" (was at tick ${payload.tick}).\n`;
+  }
+
+  if (payload.action === 'save') {
+    return `Saved cursor "${payload.name}" at tick ${payload.tick}.\n`;
+  }
+
+  if (payload.action === 'latest') {
+    const { nodesStr, edgesStr } = buildStateStrings();
+    return appendReceiptSummary(
+      `${payload.graph}: returned to present (tick ${payload.maxTick}, ${nodesStr}, ${edgesStr})`,
+    );
+  }
+
+  if (payload.action === 'load') {
+    const { nodesStr, edgesStr } = buildStateStrings();
+    return appendReceiptSummary(
+      `${payload.graph}: loaded cursor "${payload.name}" at tick ${payload.tick} of ${payload.maxTick} (${nodesStr}, ${edgesStr})`,
+    );
+  }
+
+  if (payload.action === 'tick') {
+    const { nodesStr, edgesStr, patchesStr } = buildStateStrings();
+    return appendReceiptSummary(
+      `${payload.graph}: tick ${payload.tick} of ${payload.maxTick} (${nodesStr}, ${edgesStr}, ${patchesStr})`,
+    );
+  }
+
+  // status
+  if (payload.cursor && payload.cursor.active) {
+    const { nodesStr, edgesStr, patchesStr } = buildStateStrings();
+    return appendReceiptSummary(
+      `${payload.graph}: tick ${payload.tick} of ${payload.maxTick} (${nodesStr}, ${edgesStr}, ${patchesStr})`,
+    );
+  }
+
+  return `${payload.graph}: no cursor active, ${payload.ticks.length} ticks available\n`;
+}
+
+/**
+ * Reads the active cursor and sets `_seekCeiling` on the graph instance
+ * so that subsequent materialize calls respect the time-travel boundary.
+ *
+ * Called by non-seek commands (query, path, check, etc.) that should
+ * honour an active seek cursor.
+ *
+ * @private
+ * @param {Object} graph - WarpGraph instance
+ * @param {Object} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @returns {Promise<{active: boolean, tick: number|null, maxTick: number|null}>} Cursor info — maxTick is always null; non-seek commands intentionally skip discoverTicks() for performance
+ */
+async function applyCursorCeiling(graph, persistence, graphName) {
+  const cursor = await readActiveCursor(persistence, graphName);
+  if (cursor) {
+    graph._seekCeiling = cursor.tick;
+    return { active: true, tick: cursor.tick, maxTick: null };
+  }
+  return { active: false, tick: null, maxTick: null };
+}
+
+/**
+ * Prints a seek cursor warning banner to stderr when a cursor is active.
+ *
+ * No-op if the cursor is not active.
+ *
+ * Non-seek commands (query, path, check, history, materialize) pass null for
+ * maxTick to avoid the cost of discoverTicks(); the banner then omits the
+ * "of {maxTick}" suffix. Only the seek handler itself populates maxTick.
+ *
+ * @private
+ * @param {{active: boolean, tick: number|null, maxTick: number|null}} cursorInfo - Result from applyCursorCeiling
+ * @param {number|null} maxTick - Maximum Lamport tick (from discoverTicks), or null if unknown
+ * @returns {void}
+ */
+function emitCursorWarning(cursorInfo, maxTick) {
+  if (cursorInfo.active) {
+    const maxLabel = maxTick !== null && maxTick !== undefined ? ` of ${maxTick}` : '';
+    process.stderr.write(`\u26A0 seek active (tick ${cursorInfo.tick}${maxLabel}) \u2014 run "git warp seek --latest" to return to present\n`);
+  }
+}
+
 async function handleView({ options, args }) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     throw usageError('view command requires an interactive terminal (TTY)');
@@ -1500,6 +2452,7 @@ const COMMANDS = new Map([
   ['history', handleHistory],
   ['check', handleCheck],
   ['materialize', handleMaterialize],
+  ['seek', handleSeek],
   ['view', handleView],
   ['install-hooks', handleInstallHooks],
 ]);
@@ -1534,7 +2487,7 @@ async function main() {
     throw usageError(`Unknown command: ${command}`);
   }
 
-  const VIEW_SUPPORTED_COMMANDS = ['info', 'check', 'history', 'path', 'materialize', 'query'];
+  const VIEW_SUPPORTED_COMMANDS = ['info', 'check', 'history', 'path', 'materialize', 'query', 'seek'];
   if (options.view && !VIEW_SUPPORTED_COMMANDS.includes(command)) {
     throw usageError(`--view is not supported for '${command}'. Supported commands: ${VIEW_SUPPORTED_COMMANDS.join(', ')}`);
   }