@git-stunts/git-warp 10.1.2 → 10.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "10.1.2",
+  "version": "10.3.2",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",
@@ -79,7 +79,12 @@
     "prepare": "patch-package && node scripts/setup-hooks.js",
     "prepack": "npm run lint && npm run test:local",
     "install:git-warp": "bash scripts/install-git-warp.sh",
-    "uninstall:git-warp": "bash scripts/uninstall-git-warp.sh"
+    "uninstall:git-warp": "bash scripts/uninstall-git-warp.sh",
+    "test:node20": "docker compose -f docker-compose.test.yml --profile node20 run --build --rm test-node20",
+    "test:node22": "docker compose -f docker-compose.test.yml --profile node22 run --build --rm test-node22",
+    "test:bun": "docker compose -f docker-compose.test.yml --profile bun run --build --rm test-bun",
+    "test:deno": "docker compose -f docker-compose.test.yml --profile deno run --build --rm test-deno",
+    "test:matrix": "docker compose -f docker-compose.test.yml --profile full up --build --abort-on-container-exit"
   },
   "dependencies": {
     "@git-stunts/alfred": "^0.4.0",

package/src/domain/WarpGraph.js

@@ -178,6 +178,15 @@ export default class WarpGraph {
 
     /** @type {import('./services/TemporalQuery.js').TemporalQuery|null} */
     this._temporalQuery = null;
+
+    /** @type {number|null} */
+    this._seekCeiling = null;
+
+    /** @type {number|null} */
+    this._cachedCeiling = null;
+
+    /** @type {Map<string, string>|null} */
+    this._cachedFrontier = null;
   }
 
   /**
@@ -570,11 +579,16 @@ export default class WarpGraph {
    * When false or omitted (default), returns just the state for backward
    * compatibility with zero receipt overhead.
    *
+   * When a Lamport ceiling is active (via `options.ceiling` or the
+   * instance-level `_seekCeiling`), delegates to a ceiling-aware path
+   * that replays only patches with `lamport <= ceiling`, bypassing
+   * checkpoints, auto-checkpoint, and GC.
+   *
    * Side effects: Updates internal cached state, version vector, last frontier,
    * and patches-since-checkpoint counter. May trigger auto-checkpoint and GC
    * based on configured policies. Notifies subscribers if state changed.
    *
-   * @param {{receipts?: boolean}} [options] - Optional configuration
+   * @param {{receipts?: boolean, ceiling?: number|null}} [options] - Optional configuration
    * @returns {Promise<import('./services/JoinReducer.js').WarpStateV5|{state: import('./services/JoinReducer.js').WarpStateV5, receipts: import('./types/TickReceipt.js').TickReceipt[]}>} The materialized graph state, or { state, receipts } when receipts enabled
    * @throws {Error} If checkpoint loading fails or patch decoding fails
    * @throws {Error} If writer ref access or patch blob reading fails
@@ -583,6 +597,13 @@ export default class WarpGraph {
     const t0 = this._clock.now();
     // ZERO-COST: only resolve receipts flag when options provided
     const collectReceipts = options && options.receipts;
+    // Resolve ceiling: explicit option > instance-level seek ceiling > null (latest)
+    const ceiling = this._resolveCeiling(options);
+
+    // When ceiling is active, delegate to ceiling-aware path (with its own cache)
+    if (ceiling !== null) {
+      return await this._materializeWithCeiling(ceiling, collectReceipts, t0);
+    }
 
     try {
       // Check for checkpoint
@@ -658,6 +679,8 @@ export default class WarpGraph {
       }
 
       await this._setMaterializedState(state);
+      this._cachedCeiling = null;
+      this._cachedFrontier = null;
       this._lastFrontier = await this.getFrontier();
       this._patchesSinceCheckpoint = patchCount;
 
@@ -698,6 +721,124 @@ export default class WarpGraph {
     }
   }
 
+  /**
+   * Resolves the effective ceiling from options and instance state.
+   *
+   * Precedence: explicit `ceiling` in options overrides the instance-level
+   * `_seekCeiling`. Uses the `'ceiling' in options` check, so passing
+   * `{ ceiling: null }` explicitly clears the seek ceiling for that call
+   * (returns `null`), while omitting the key falls through to `_seekCeiling`.
+   *
+   * @param {{ceiling?: number|null}} [options] - Options object; when the
+   *   `ceiling` key is present (even if `null`), its value takes precedence
+   * @returns {number|null} Lamport ceiling to apply, or `null` for latest
+   * @private
+   */
+  _resolveCeiling(options) {
+    if (options && options.ceiling !== undefined) {
+      return options.ceiling;
+    }
+    return this._seekCeiling;
+  }
+
+  /**
+   * Materializes the graph with a Lamport ceiling (time-travel).
+   *
+   * Bypasses checkpoints entirely — replays all patches from all writers,
+   * filtering to only those with `lamport <= ceiling`. Skips auto-checkpoint
+   * and GC since this is an exploratory read.
+   *
+   * Uses a dedicated cache keyed on `ceiling` + frontier snapshot. Cache
+   * is bypassed when the writer frontier has advanced (new writers or
+   * updated tips) or when `collectReceipts` is `true` because the cached
+   * path does not retain receipt data.
+   *
+   * @param {number} ceiling - Maximum Lamport tick to include (patches with
+   *   `lamport <= ceiling` are replayed; `ceiling <= 0` yields empty state)
+   * @param {boolean} collectReceipts - When `true`, return receipts alongside
+   *   state and skip the ceiling cache
+   * @param {number} t0 - Start timestamp for performance logging
+   * @returns {Promise<import('./services/JoinReducer.js').WarpStateV5 |
+   *   {state: import('./services/JoinReducer.js').WarpStateV5,
+   *    receipts: import('./types/TickReceipt.js').TickReceipt[]}>}
+   *   Plain state when `collectReceipts` is falsy; `{ state, receipts }`
+   *   when truthy
+   * @private
+   */
+  async _materializeWithCeiling(ceiling, collectReceipts, t0) {
+    const frontier = await this.getFrontier();
+
+    // Cache hit: same ceiling, clean state, AND frontier unchanged.
+    // Bypass cache when collectReceipts is true — cached path has no receipts.
+    if (
+      this._cachedState && !this._stateDirty &&
+      ceiling === this._cachedCeiling && !collectReceipts &&
+      this._cachedFrontier !== null &&
+      this._cachedFrontier.size === frontier.size &&
+      [...frontier].every(([w, sha]) => this._cachedFrontier.get(w) === sha)
+    ) {
+      return this._cachedState;
+    }
+
+    const writerIds = [...frontier.keys()];
+
+    if (writerIds.length === 0 || ceiling <= 0) {
+      const state = createEmptyStateV5();
+      this._provenanceIndex = new ProvenanceIndex();
+      await this._setMaterializedState(state);
+      this._cachedCeiling = ceiling;
+      this._cachedFrontier = frontier;
+      this._logTiming('materialize', t0, { metrics: '0 patches (ceiling)' });
+      if (collectReceipts) {
+        return { state, receipts: [] };
+      }
+      return state;
+    }
+
+    const allPatches = [];
+    for (const writerId of writerIds) {
+      const writerPatches = await this._loadWriterPatches(writerId);
+      for (const entry of writerPatches) {
+        if (entry.patch.lamport <= ceiling) {
+          allPatches.push(entry);
+        }
+      }
+    }
+
+    let state;
+    let receipts;
+
+    if (allPatches.length === 0) {
+      state = createEmptyStateV5();
+      if (collectReceipts) {
+        receipts = [];
+      }
+    } else if (collectReceipts) {
+      const result = reduceV5(allPatches, undefined, { receipts: true });
+      state = result.state;
+      receipts = result.receipts;
+    } else {
+      state = reduceV5(allPatches);
+    }
+
+    this._provenanceIndex = new ProvenanceIndex();
+    for (const { patch, sha } of allPatches) {
+      this._provenanceIndex.addPatch(sha, patch.reads, patch.writes);
+    }
+
+    await this._setMaterializedState(state);
+    this._cachedCeiling = ceiling;
+    this._cachedFrontier = frontier;
+
+    // Skip auto-checkpoint and GC — this is an exploratory read
+    this._logTiming('materialize', t0, { metrics: `${allPatches.length} patches (ceiling=${ceiling})` });
+
+    if (collectReceipts) {
+      return { state, receipts };
+    }
+    return state;
+  }
+
   /**
    * Joins (merges) another state into the current cached state.
    *
@@ -1010,6 +1151,79 @@ export default class WarpGraph {
     return writerIds.sort();
   }
 
+  /**
+   * Discovers all distinct Lamport ticks across all writers.
+   *
+   * Walks each writer's patch chain from tip to root, reading commit
+   * messages (no CBOR blob deserialization) to extract Lamport timestamps.
+   * Stops when a non-patch commit (e.g. checkpoint) is encountered.
+   * Logs a warning for any non-monotonic lamport sequence within a single
+   * writer's chain.
+   *
+   * @returns {Promise<{
+   *   ticks: number[],
+   *   maxTick: number,
+   *   perWriter: Map<string, {ticks: number[], tipSha: string|null}>
+   * }>} `ticks` is the sorted (ascending) deduplicated union of all
+   *   Lamport values; `maxTick` is the largest value (0 if none);
+   *   `perWriter` maps each writer ID to its ticks in ascending order
+   *   and its current tip SHA (or `null` if the writer ref is missing)
+   * @throws {Error} If reading refs or commit metadata fails
+   */
+  async discoverTicks() {
+    const writerIds = await this.discoverWriters();
+    const globalTickSet = new Set();
+    const perWriter = new Map();
+
+    for (const writerId of writerIds) {
+      const writerRef = buildWriterRef(this._graphName, writerId);
+      const tipSha = await this._persistence.readRef(writerRef);
+      const writerTicks = [];
+      const tickShas = {};
+
+      if (tipSha) {
+        let currentSha = tipSha;
+        let lastLamport = Infinity;
+
+        while (currentSha) {
+          const nodeInfo = await this._persistence.getNodeInfo(currentSha);
+          const kind = detectMessageKind(nodeInfo.message);
+          if (kind !== 'patch') {
+            break;
+          }
+
+          const patchMeta = decodePatchMessage(nodeInfo.message);
+          globalTickSet.add(patchMeta.lamport);
+          writerTicks.push(patchMeta.lamport);
+          tickShas[patchMeta.lamport] = currentSha;
+
+          // Check monotonic invariant (walking newest→oldest, lamport should decrease)
+          if (patchMeta.lamport > lastLamport && this._logger) {
+            this._logger.warn(`[warp] non-monotonic lamport for writer ${writerId}: ${patchMeta.lamport} > ${lastLamport}`);
+          }
+          lastLamport = patchMeta.lamport;
+
+          if (nodeInfo.parents && nodeInfo.parents.length > 0) {
+            currentSha = nodeInfo.parents[0];
+          } else {
+            break;
+          }
+        }
+      }
+
+      perWriter.set(writerId, {
+        ticks: writerTicks.reverse(),
+        tipSha: tipSha || null,
+        tickShas,
+      });
+    }
+
+    const ticks = [...globalTickSet].sort((a, b) => a - b);
+    const maxTick = ticks.length > 0 ? ticks[ticks.length - 1] : 0;
+
+    return { ticks, maxTick, perWriter };
+  }
+
   // ============================================================================
   // Schema Migration Support
   // ============================================================================
@@ -3025,6 +3239,23 @@ export default class WarpGraph {
     return cone;
   }
 
+  /**
+   * Loads a single patch by its SHA.
+   *
+   * @param {string} sha - The patch commit SHA
+   * @returns {Promise<Object>} The decoded patch object
+   * @throws {Error} If the commit is not a patch or loading fails
+   *
+   * @public
+   * @remarks
+   * Thin wrapper around the internal `_loadPatchBySha` helper. Exposed for
+   * CLI/debug tooling (e.g. seek tick receipts) that needs to inspect patch
+   * operations without re-materializing intermediate states.
+   */
+  async loadPatchBySha(sha) {
+    return await this._loadPatchBySha(sha);
+  }
+
   /**
    * Loads a single patch by its SHA.
    *

package/src/domain/utils/RefLayout.js

@@ -8,6 +8,8 @@
  * - refs/warp/<graph>/writers/<writer_id>
  * - refs/warp/<graph>/checkpoints/head
  * - refs/warp/<graph>/coverage/head
+ * - refs/warp/<graph>/cursor/active
+ * - refs/warp/<graph>/cursor/saved/<name>
  *
  * @module domain/utils/RefLayout
  */
@@ -49,20 +51,22 @@ const PATH_TRAVERSAL_PATTERN = /\.\./;
  * Validates a graph name and throws if invalid.
  *
  * Graph names must not contain:
- * - Path traversal sequences (`../`)
+ * - Path traversal sequences (`..`)
  * - Semicolons (`;`)
  * - Spaces
  * - Null bytes (`\0`)
  * - Empty strings
  *
  * @param {string} name - The graph name to validate
- * @throws {Error} If the graph name is invalid
+ * @throws {Error} If the name is not a string, is empty, or contains
+ *   forbidden characters (`..`, `;`, space, `\0`)
  * @returns {void}
  *
  * @example
- * validateGraphName('events'); // OK
- * validateGraphName('../etc'); // throws
- * validateGraphName('my graph'); // throws
+ * validateGraphName('events');    // OK
+ * validateGraphName('team/proj'); // OK (slashes allowed)
+ * validateGraphName('../etc');    // throws — path traversal
+ * validateGraphName('my graph');  // throws — contains space
  */
 export function validateGraphName(name) {
   if (typeof name !== 'string') {
@@ -94,18 +98,20 @@ export function validateGraphName(name) {
  * Validates a writer ID and throws if invalid.
  *
  * Writer IDs must:
- * - Be ASCII ref-safe: only [A-Za-z0-9._-]
+ * - Be ASCII ref-safe: only `[A-Za-z0-9._-]`
  * - Be 1-64 characters long
  * - Not contain `/`, `..`, whitespace, or NUL
  *
  * @param {string} id - The writer ID to validate
- * @throws {Error} If the writer ID is invalid
+ * @throws {Error} If the ID is not a string, is empty, exceeds 64 characters,
+ *   or contains forbidden characters (`/`, `..`, whitespace, NUL, non-ASCII)
  * @returns {void}
  *
  * @example
- * validateWriterId('node-1'); // OK
- * validateWriterId('a/b'); // throws (contains /)
- * validateWriterId('x'.repeat(65)); // throws (too long)
+ * validateWriterId('node-1');        // OK
+ * validateWriterId('a/b');           // throws — contains forward slash
+ * validateWriterId('x'.repeat(65));  // throws — exceeds max length
+ * validateWriterId('has space');     // throws — contains whitespace
  */
 export function validateWriterId(id) {
   if (typeof id !== 'string') {
@@ -157,7 +163,7 @@ export function validateWriterId(id) {
  *
  * @param {string} graphName - The name of the graph
  * @param {string} writerId - The writer's unique identifier
- * @returns {string} The full ref path
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/writers/<writerId>`
  * @throws {Error} If graphName or writerId is invalid
  *
  * @example
@@ -174,7 +180,7 @@ export function buildWriterRef(graphName, writerId) {
  * Builds the checkpoint head ref path for the given graph.
  *
  * @param {string} graphName - The name of the graph
- * @returns {string} The full ref path
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/checkpoints/head`
  * @throws {Error} If graphName is invalid
  *
  * @example
@@ -190,7 +196,7 @@ export function buildCheckpointRef(graphName) {
  * Builds the coverage head ref path for the given graph.
  *
  * @param {string} graphName - The name of the graph
- * @returns {string} The full ref path
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/coverage/head`
  * @throws {Error} If graphName is invalid
  *
  * @example
@@ -204,10 +210,12 @@ export function buildCoverageRef(graphName) {
 
 /**
  * Builds the writers prefix path for the given graph.
- * Useful for listing all writer refs under a graph.
+ * Useful for listing all writer refs under a graph
+ * (e.g. via `git for-each-ref`).
  *
  * @param {string} graphName - The name of the graph
- * @returns {string} The writers prefix path
+ * @returns {string} The writers prefix path (with trailing slash),
+ *   e.g. `refs/warp/<graphName>/writers/`
  * @throws {Error} If graphName is invalid
  *
  * @example
@@ -219,6 +227,70 @@ export function buildWritersPrefix(graphName) {
   return `${REF_PREFIX}/${graphName}/writers/`;
 }
 
+/**
+ * Builds the active cursor ref path for the given graph.
+ *
+ * The active cursor is a single ref that stores the current time-travel
+ * position used by `git warp seek`. It points to a commit SHA representing
+ * the materialization frontier the user has seeked to.
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/cursor/active`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildCursorActiveRef('events');
+ * // => 'refs/warp/events/cursor/active'
+ */
+export function buildCursorActiveRef(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/cursor/active`;
+}
+
+/**
+ * Builds a saved (named) cursor ref path for the given graph and cursor name.
+ *
+ * Saved cursors are bookmarks created by `git warp seek --save <name>`.
+ * Each saved cursor persists a time-travel position that can be restored
+ * later without re-seeking.
+ *
+ * The cursor name is validated with the same rules as a writer ID
+ * (ASCII ref-safe: `[A-Za-z0-9._-]`, 1-64 characters).
+ *
+ * @param {string} graphName - The name of the graph
+ * @param {string} name - The cursor bookmark name (validated like a writer ID)
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/cursor/saved/<name>`
+ * @throws {Error} If graphName or name is invalid
+ *
+ * @example
+ * buildCursorSavedRef('events', 'before-tui');
+ * // => 'refs/warp/events/cursor/saved/before-tui'
+ */
+export function buildCursorSavedRef(graphName, name) {
+  validateGraphName(graphName);
+  validateWriterId(name);
+  return `${REF_PREFIX}/${graphName}/cursor/saved/${name}`;
+}
+
+/**
+ * Builds the saved cursor prefix path for the given graph.
+ * Useful for listing all saved cursor bookmarks under a graph
+ * (e.g. via `git for-each-ref`).
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The saved cursor prefix path (with trailing slash),
+ *   e.g. `refs/warp/<graphName>/cursor/saved/`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildCursorSavedPrefix('events');
+ * // => 'refs/warp/events/cursor/saved/'
+ */
+export function buildCursorSavedPrefix(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/cursor/saved/`;
+}
+
 // -----------------------------------------------------------------------------
 // Parsers
 // -----------------------------------------------------------------------------

package/src/domain/utils/parseCursorBlob.js

@@ -0,0 +1,51 @@
+/**
+ * Utilities for parsing seek-cursor blobs stored as Git refs.
+ *
+ * @module parseCursorBlob
+ */
+
+/**
+ * Parses and validates a cursor blob (Buffer) into a cursor object.
+ *
+ * The blob must contain UTF-8-encoded JSON representing a plain object with at
+ * minimum a finite numeric `tick` field.  Any additional fields (e.g. `mode`,
+ * `name`) are preserved in the returned object.
+ *
+ * @param {Buffer} buf - Raw blob contents (UTF-8 encoded JSON)
+ * @param {string} label - Human-readable label used in error messages
+ *   (e.g. `"active cursor"`, `"saved cursor 'foo'"`)
+ * @returns {{ tick: number, mode?: string, [key: string]: unknown }}
+ *   The validated cursor object.  `tick` is guaranteed to be a finite number.
+ * @throws {Error} If `buf` is not valid JSON
+ * @throws {Error} If the parsed value is not a plain JSON object (e.g. array,
+ *   null, or primitive)
+ * @throws {Error} If the `tick` field is missing, non-numeric, NaN, or
+ *   Infinity
+ *
+ * @example
+ * const buf = Buffer.from('{"tick":5,"mode":"lamport"}', 'utf8');
+ * const cursor = parseCursorBlob(buf, 'active cursor');
+ * // => { tick: 5, mode: 'lamport' }
+ *
+ * @example
+ * // Throws: "Corrupted active cursor: blob is not valid JSON"
+ * parseCursorBlob(Buffer.from('not json', 'utf8'), 'active cursor');
+ */
+export function parseCursorBlob(buf, label) {
+  let obj;
+  try {
+    obj = JSON.parse(new TextDecoder().decode(buf));
+  } catch {
+    throw new Error(`Corrupted ${label}: blob is not valid JSON`);
+  }
+
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error(`Corrupted ${label}: expected a JSON object`);
+  }
+
+  if (typeof obj.tick !== 'number' || !Number.isFinite(obj.tick)) {
+    throw new Error(`Corrupted ${label}: missing or invalid numeric tick`);
+  }
+
+  return obj;
+}

package/src/visualization/layouts/elkAdapter.js

@@ -6,20 +6,20 @@ const LAYOUT_PRESETS = {
   query: {
     'elk.algorithm': 'layered',
     'elk.direction': 'DOWN',
-    'elk.spacing.nodeNode': '40',
-    'elk.layered.spacing.nodeNodeBetweenLayers': '60',
+    'elk.spacing.nodeNode': '30',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '40',
   },
   path: {
     'elk.algorithm': 'layered',
     'elk.direction': 'RIGHT',
-    'elk.spacing.nodeNode': '40',
-    'elk.layered.spacing.nodeNodeBetweenLayers': '60',
+    'elk.spacing.nodeNode': '30',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '40',
   },
   slice: {
     'elk.algorithm': 'layered',
     'elk.direction': 'DOWN',
-    'elk.spacing.nodeNode': '40',
-    'elk.layered.spacing.nodeNodeBetweenLayers': '60',
+    'elk.spacing.nodeNode': '30',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '40',
   },
 };
 
@@ -46,7 +46,7 @@ function estimateNodeWidth(label) {
   return Math.max((label?.length ?? 0) * charWidth + padding, minWidth);
 }
 
-const NODE_HEIGHT = 40;
+const NODE_HEIGHT = 30;
 
 /**
  * Converts normalised graph data to an ELK graph JSON object.

package/src/visualization/renderers/ascii/graph.js

@@ -2,7 +2,9 @@
  * ASCII graph renderer: maps ELK-positioned nodes and edges onto a character grid.
  *
  * Pixel-to-character scaling:
- *   cellW = 8 px/char, cellH = 4 px/char (approximate monospace aspect ratio)
+ *   cellW = 10, cellH = 10
+ *   ELK uses NODE_HEIGHT=40, nodeNode=40, betweenLayers=60.
+ *   At cellH=10: 40px → 4 rows, compact 3-row nodes fit with natural gaps.
  */
 
 import { createBox } from './box.js';
@@ -11,8 +13,8 @@ import { ARROW } from './symbols.js';
 
 // ── Scaling constants ────────────────────────────────────────────────────────
 
-const CELL_W = 8;
-const CELL_H = 4;
+const CELL_W = 10;
+const CELL_H = 10;
 const MARGIN = 2;
 
 // ── Box-drawing characters (short keys for tight grid-stamping loops) ───────
@@ -76,8 +78,8 @@ function writeString(grid, r, c, str) {
 function stampNode(grid, node) {
   const r = toRow(node.y);
   const c = toCol(node.x);
-  const w = Math.max(scaleW(node.width), 4);
-  const h = Math.max(scaleH(node.height), 3);
+  const w = Math.max(toCol(node.width), 4);
+  const h = 3; // Always: border + label + border
 
   // Top border
   writeChar(grid, r, c, BOX.tl);
@@ -87,10 +89,8 @@ function stampNode(grid, node) {
   writeChar(grid, r, c + w - 1, BOX.tr);
 
   // Side borders
-  for (let j = 1; j < h - 1; j++) {
-    writeChar(grid, r + j, c, BOX.v);
-    writeChar(grid, r + j, c + w - 1, BOX.v);
-  }
+  writeChar(grid, r + 1, c, BOX.v);
+  writeChar(grid, r + 1, c + w - 1, BOX.v);
 
   // Bottom border
   writeChar(grid, r + h - 1, c, BOX.bl);
@@ -99,13 +99,13 @@ function stampNode(grid, node) {
   }
   writeChar(grid, r + h - 1, c + w - 1, BOX.br);
 
-  // Label (centered)
+  // Label (always on row 1)
   const label = node.label ?? node.id;
   const maxLabel = w - 4;
   const truncated = label.length > maxLabel
     ? `${label.slice(0, Math.max(maxLabel - 1, 1))}\u2026`
     : label;
-  const labelRow = r + Math.floor(h / 2);
+  const labelRow = r + 1;
   const labelCol = c + Math.max(1, Math.floor((w - truncated.length) / 2));
   writeString(grid, labelRow, labelCol, truncated);
 }
@@ -220,6 +220,8 @@ function drawArrowhead(grid, section, nodeSet) {
   const pc = toCol(prev.x);
 
   let arrow;
+  let ar = er;
+  let ac = ec;
   if (er > pr) {
     arrow = ARROW.down;
   } else if (er < pr) {
@@ -230,8 +232,21 @@ function drawArrowhead(grid, section, nodeSet) {
     arrow = ARROW.left;
   }
 
-  if (!isNodeCell(nodeSet, er, ec)) {
-    writeChar(grid, er, ec, arrow);
+  // If the endpoint is inside a node box, step back one cell into free space
+  if (isNodeCell(nodeSet, ar, ac)) {
+    if (er > pr) {
+      ar = er - 1;
+    } else if (er < pr) {
+      ar = er + 1;
+    } else if (ec > pc) {
+      ac = ec - 1;
+    } else {
+      ac = ec + 1;
+    }
+  }
+
+  if (!isNodeCell(nodeSet, ar, ac)) {
+    writeChar(grid, ar, ac, arrow);
   }
 }
 
@@ -282,8 +297,8 @@ function buildNodeSet(nodes) {
   for (const node of nodes) {
     const r = toRow(node.y);
     const c = toCol(node.x);
-    const w = Math.max(scaleW(node.width), 4);
-    const h = Math.max(scaleH(node.height), 3);
+    const w = Math.max(toCol(node.width), 4);
+    const h = 3; // Match compact node height
     for (let dr = 0; dr < h; dr++) {
       for (let dc = 0; dc < w; dc++) {
         set.add(`${r + dr},${c + dc}`);