ai-lens 0.8.113 → 0.8.114

package/.commithash

@@ -1 +1 @@
-f10ad46
+507ff10

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 History of changes to the `ai-lens` CLI package on npm. New entries go on top. Format: `## X.Y.Z — YYYY-MM-DD`, followed by user-facing bullets.
 
+## 0.8.114 — 2026-07-01
+- fix(client): normalize Windows /c:/ drive paths so Cursor git metadata is captured
+- feat(team-memory): SessionStart recall + injection (T6)
+- feat(cli): `ai-lens local-server up|down|status` — one-command private local server
+- feat(dx): local-first compose, npx docs, DATA_DIR-aware config path
+- fix(import): read Cursor CLI store WAL — fix `no such table: meta`
+- fix(import): surface missing identity in cursor --dry-run + name hint
+- feat(client): nudge old-Node Cursor users to upgrade so import cursor works
+- feat(import): add `ai-lens import cursor` (IDE + CLI), at parity with claude-code
+- feat(cli): --use-repo-path implies --project-hooks
+- fix(cli): make --no-hooks an inert deprecated no-op so /setup installs hooks
+
 ## 0.8.113 — 2026-06-24
 - feat: track working-directory changes mid-session (Claude Code `CwdChanged`) so events are attributed to the project you `cd` into, not the one you started in
 - feat: capture the assistant's response text and thinking from the Claude Code transcript, not just token counts — the full turn-by-turn dialogue is now recorded

package/README.md

@@ -25,6 +25,8 @@ This will:
 
 Re-running is safe — it updates outdated hooks and skips current ones.
 
+> **No global install — always use `npx`.** The CLI is never placed on your `PATH`; run every command as `npx -y ai-lens <command>` (each run uses the latest published version). A bare `ai-lens …` will be "command not found". Note: `init` *does* install the **runtime** (the capture client) into `~/.ai-lens/client/` — only the CLI itself stays npx-only.
+
 ### Deploying hooks in a specific project (project-level hooks)
 
 To write hooks into the project directory (`.cursor/hooks.json` and `.claude/settings.json`) instead of global `~/.cursor/` and `~/.claude/`, run from the project root:
@@ -38,10 +40,17 @@ Add `--use-repo-path` to run `capture.js` directly from the package (repo or npx
 ### CLI commands
 
 ```bash
-npx ai-lens init       # Setup wizard — detect tools, install hooks, configure MCP
-npx ai-lens status     # Run health checks and generate a diagnostic report
-npx ai-lens remove     # Remove hooks, client files, and MCP config
-npx ai-lens version    # Show installed version
+npx ai-lens init                  # Setup wizard — detect tools, install hooks, configure MCP
+npx ai-lens status                # Run health checks and generate a diagnostic report
+npx ai-lens import <source>       # Backfill history. <source> = claude-code | cursor
+                                  #   [--days N | --since YYYY-MM-DD | --from … --to …] [--projects A,B] [--dry-run]
+npx ai-lens list-sessions         # List captured sessions
+npx ai-lens find-session <query>  # Find a captured session
+npx ai-lens delete-sessions <…>   # Delete captured sessions
+npx ai-lens local-server up       # Run a PRIVATE local server in Docker (data stays on your machine)
+                                  #   · down [--purge] | status · then offers to point the client at it
+npx ai-lens remove                # Remove hooks, client files, and MCP config
+npx ai-lens version               # Show installed version
 ```
 
 ### CLI options
@@ -64,6 +73,35 @@ export AI_LENS_SERVER_URL=https://ai-lens.rantsports.com
 export AI_LENS_PROJECTS="~/meta/, ~/meta-cursor/"   # optional, default: all
 ```
 
+### Private local server (your data stays on your machine)
+
+For a private trial or solo use — your sessions never leave your machine. **Prerequisite: Docker Desktop** (on Windows, with WSL2). Then one command stands up a local server (Postgres+pgvector + app) and offers to point the client at it:
+
+```bash
+npx -y ai-lens local-server up      # check Docker → pull → start → wait healthy → offer `init`
+#   → server at http://localhost:3000
+npx -y ai-lens local-server status  # container + health status
+npx -y ai-lens local-server down    # stop (add --purge to also delete the data volume)
+```
+
+It uses **public images only** (`pgvector/pgvector:pg16` + `ghcr.io/r-ms/ai-lens/app`) — no login, no build. The server runs in personal (self-host) mode and attributes events by git identity, so set BOTH (the server 400s without name):
+
+```bash
+git config --global user.email "you@example.com"
+git config --global user.name  "Your Name"
+```
+
+<details>
+<summary>Alternative: run from a repo checkout (for AI Lens development)</summary>
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.local.yml up -d postgres app
+AI_LENS_SERVER_URL=http://localhost:3000 npx -y ai-lens import claude-code --days 7
+```
+</details>
+
+Use a separate `AI_LENS_DATA_DIR` (e.g. `~/.ai-lens-local`) to isolate a local profile — its own `config.json` + spool — from your prod setup.
+
 <details>
 <summary>Manual hook setup</summary>
 
@@ -328,6 +366,6 @@ Build jobs trigger only when relevant files change (Dockerfile, server/**, dashb
 
 ## Requirements
 
-- Node.js 20+
+- Node.js 22.5+ (the CLI reads Cursor history via the built-in `node:sqlite`, available from 22.5; the server container runs Node 20 and is unaffected)
 - Docker + Docker Compose (for production deployment)
 - PostgreSQL 16 (for local development without Docker)

package/bin/ai-lens.js

@@ -38,6 +38,14 @@ switch (command) {
     await deleteSessions();
     break;
   }
+  case 'local-server':
+  case 'install-local-server': {
+    // `install-local-server` is an alias that always means `local-server up`.
+    if (command === 'install-local-server') process.env.AI_LENS_LOCAL_SUBVERB = 'up';
+    const { default: localServer } = await import('../cli/local-server.js');
+    await localServer();
+    break;
+  }
   case 'version':
   case '--version':
   case '-v': {
@@ -67,18 +75,25 @@ switch (command) {
     console.log('    --use-repo-path Run capture.js from this package; skip copy to ~/.ai-lens/client/');
     console.log('  remove          Remove AI Lens hooks and client files');
     console.log('  status          Run diagnostics and generate a status report');
-    console.log('  import <source>  Import local history (source: claude-code)');
-    console.log('    --days N         Window in days (default 30; 0 = all history)');
+    console.log('  import <source>  Import local history (sources: claude-code, cursor)');
+    console.log('    --days N         Window in days (default 90; 0 = all history)');
     console.log('    --since DATE     Import from YYYY-MM-DD instead of --days');
     console.log('    --from D --to D  Import a bounded YYYY-MM-DD..YYYY-MM-DD window (idempotent re-import)');
     console.log('    --dry-run        Scan + count, write nothing');
     console.log('    --projects LIST  Only these project paths (comma-separated)');
+    console.log('    --cursor-db PATH Cursor IDE state.vscdb override (default: auto-detect)');
+    console.log('    --cursor-chats PATH Cursor CLI chats dir override (default: ~/.cursor/chats)');
     console.log('  list-sessions   List your own sessions');
     console.log('    --days N --source S --limit N --json');
     console.log('  find-session <q>  Find your sessions by id / project / source substring');
     console.log('    --days N --source S --limit N --json');
     console.log('  delete-sessions  Delete your own sessions (dry-run unless --yes)');
     console.log('    <id…> | --from D --to D [--source S] [--days N] [--yes] [--json]');
+    console.log('  local-server <up|down|status>  Run a private local server in Docker (your data stays local)');
+    console.log('    up [--port N] [--yes] [--recreate]   Bring it up, then offer to point the client at it');
+    console.log('    down [--purge]                       Stop it (--purge also deletes the data volume)');
+    console.log('    status [--port N]                    Show container + health status');
+    console.log('  install-local-server  Alias for `local-server up`');
     console.log('  version         Show package version and commit hash');
     process.exit(command ? 1 : 0);
 }

package/cli/hooks.js

@@ -3,6 +3,7 @@ import { join, dirname } from 'node:path';
 import { homedir, release } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
+import { CONFIG_PATH } from '../client/config.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = join(__dirname, '..');
@@ -24,9 +25,12 @@ export function getVersionInfo() {
   return { version, commit };
 }
 
-// Stable install location for client files
+// Stable install location for client files. The install dir stays a fixed
+// ~/.ai-lens (its path is baked into hook configs and must not move), but
+// CONFIG_PATH is imported from client/config.js so config reads/writes honor
+// AI_LENS_DATA_DIR — same as the client runtime (was previously hardcoded here,
+// which broke DATA_DIR-based isolation).
 const CLIENT_INSTALL_DIR = join(homedir(), '.ai-lens', 'client');
-const CONFIG_PATH = join(homedir(), '.ai-lens', 'config.json');
 
 // Hooks always point to the installed copy at ~/.ai-lens/client/capture.js
 export const CAPTURE_PATH = join(CLIENT_INSTALL_DIR, 'capture.js');

package/cli/import/claude-code.js

@@ -7,6 +7,11 @@
  * existing sender ship them to POST /api/events. Historical timestamps are kept
  * verbatim.
  *
+ * Source-agnostic plumbing (window/flag resolution, coverage de-overlap, project
+ * filter, ledger, unified-event build + spool delivery) lives in ./common.js and
+ * is shared with the other import sources; this module keeps only the Claude Code
+ * reader, the claude_code event_id namespace, and the local-history preview.
+ *
  * Re-import is idempotent: every event carries a DETERMINISTIC event_id
  * (computeEventId below) and the server inserts with ON CONFLICT DO NOTHING
  * against the `events.event_id` UNIQUE constraint, so re-running over an
@@ -19,22 +24,34 @@
  * on the fast path; a bounded `--from/--to` re-import bypasses the ledger and
  * leans entirely on the event_id dedup.
  */
-import { createReadStream, existsSync, readdirSync, statSync, readFileSync, writeFileSync, mkdirSync, renameSync, realpathSync } from 'node:fs';
+import { createReadStream, existsSync, readdirSync, statSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { createInterface } from 'node:readline';
 import { createHash } from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 
-import { writeToSpool, canonicalizeProjectPath, deterministicEventId } from '../../client/capture.js';
-import { PENDING_DIR, SENDING_DIR, DATA_DIR, ensureDataDir, getGitIdentity, getGitMetadata, getServerUrl, getAuthToken, getMonitoredProjects } from '../../client/config.js';
+import { canonicalizeProjectPath, deterministicEventId } from '../../client/capture.js';
+import { DATA_DIR, ensureDataDir, getGitIdentity, getGitMetadata, getServerUrl, getAuthToken, getMonitoredProjects } from '../../client/config.js';
 import { mapTranscript } from './transcript-map.js';
-import { info, success, warn, error, heading, detail, blank, progress, progressDone } from '../logger.js';
+import {
+  TERMINAL_DORMANT_MS,
+  validateFlags, resolveCutoff, resolveLowerBound, resolveUpperBound,
+  resolveProjectFilter, projectMatches,
+  fetchCoverage, hasDeliverableIdentity, sliceEvents,
+  ledgerCovers, clipWindow, createImportShipper,
+} from './common.js';
+import { info, success, warn, error, heading, detail, blank, progress } from '../logger.js';
+
+// Re-export the source-agnostic helpers the test-suite (and callers) import from
+// this module — the stable public surface after the Phase-0 split into common.js.
+export {
+  validateFlags, resolveCutoff, resolveLowerBound, resolveUpperBound,
+  resolveProjectFilter, projectMatches, sliceEvents, hasDeliverableIdentity, ledgerCovers,
+};
 
 const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
 const LEDGER_PATH = join(DATA_DIR, 'import-state', 'claude-code.json');
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const DAY_MS = 86400_000;
 
 // TokenUsage gets a LIVE-compatible event_id (sha of the assistant line uuid,
 // exactly as client/capture.js:1363) so an imported call dedups against the same
@@ -46,52 +63,6 @@ export function computeEventId(ev) {
   return deterministicEventId(`claude_code:import:v1:${ev._seed}`);
 }
 
-const DAY_MS = 86400_000;
-// Drain the spool to the server every DRAIN_BATCH spooled events. MUST stay well
-// under sender.js MAX_QUEUE_SIZE (10_000) — once pending exceeds that, the sender
-// DROPS the oldest overflow files (data loss). Draining in batches also lets us
-// commit the ledger only AFTER a batch's events have actually shipped, so a failed
-// send never leaves files marked covered. (sender.js can't be imported for the
-// constant — it self-invokes main() on import.)
-const DRAIN_BATCH = 4000;
-// A transcript untouched for ≥ this long is treated as a finished session, so its
-// terminal Stop/SubagentStop marker is safe to emit (matches the 5h chain-gap).
-const TERMINAL_DORMANT_MS = 5 * 60 * 60 * 1000;
-
-const isValidDate = (s) => typeof s === 'string' && !Number.isNaN(Date.parse(s));
-
-/** Validate flags. Returns an error string, or null when ok. */
-export function validateFlags({ days, since, from, to }) {
-  // --from/--to define an explicit [from, to] window (lower = from, upper = to).
-  if (from != null || to != null) {
-    if (since != null) return 'Use either --since or --from/--to, not both.';
-    if (from != null && !isValidDate(from)) return `Invalid --from "${from}". Use YYYY-MM-DD.`;
-    if (to != null && !isValidDate(to)) return `Invalid --to "${to}". Use YYYY-MM-DD.`;
-    if (from != null && to != null && Date.parse(from) > Date.parse(to)) {
-      return `--from "${from}" is after --to "${to}".`;
-    }
-    return null;
-  }
-  if (since != null) {
-    if (!isValidDate(since)) return `Invalid --since "${since}". Use YYYY-MM-DD.`;
-  } else if (!Number.isInteger(days) || days < 0) {
-    return `Invalid --days "${days}". Use a non-negative integer (0 = all history).`;
-  }
-  return null;
-}
-
-/**
- * Resolve the lower-bound cutoff ISO string from flags. `--from` and `--since`
- * are equivalent lower bounds; `--days 0` / no window ⇒ epoch (all history).
- */
-export function resolveCutoff({ days, since, from }, now = new Date()) {
-  const lower = from || since;
-  if (lower) return new Date(Date.parse(lower)).toISOString();
-  if (days === 0) return new Date(0).toISOString();
-  const d = Number.isInteger(days) && days >= 0 ? days : 90;
-  return new Date(now.getTime() - d * DAY_MS).toISOString();
-}
-
 /**
  * Cheap preview for the init import offer — how many local transcripts (≈ sessions)
  * fall within the window and their date span, by file mtime (no file reads). Lets
@@ -117,122 +88,6 @@ export function previewClaudeCode({ days = 90, dir = PROJECTS_DIR } = {}, now =
   };
 }
 
-/**
- * Resolve the INCLUSIVE lower bound from `--from` (or null when open-ended).
- * Unlike the file-level `cutoff` (which only decides whether to read a file),
- * this clips PER EVENT so an explicit `--from/--to` window means exactly the
- * events in [from 00:00, to+1day) — a file touched inside the window no longer
- * drags in its older events. Only `--from`/`--to` engage this precise clipping;
- * `--days`/`--since` keep their looser file-level semantics.
- */
-export function resolveLowerBound({ from }) {
-  if (!from || !isValidDate(from)) return null;
-  return new Date(Date.parse(from)).toISOString();
-}
-
-/**
- * Resolve the EXCLUSIVE upper bound from `--to` (or null when open-ended).
- * `--to 2026-06-07` includes the whole of June 7 ⇒ exclusive bound is the next
- * midnight (2026-06-08T00:00Z).
- */
-export function resolveUpperBound({ to }) {
-  if (!to || !isValidDate(to)) return null;
-  return new Date(Date.parse(to) + DAY_MS).toISOString();
-}
-
-/** Expand a leading ~ and resolve to a canonical project (git) root. */
-function normalizeProjectArg(p) {
-  let s = (p || '').trim();
-  if (!s) return null;
-  if (s === '~' || s.startsWith('~/')) s = join(homedir(), s.slice(1));
-  let real = s;
-  try { real = realpathSync(s); } catch { /* path may not exist on disk — keep as given */ }
-  return canonicalizeProjectPath(real) || real;
-}
-
-/**
- * Resolve the effective project filter, mirroring live capture by default:
- *   --projects A,B → explicit list (each entry ~-expanded + git-root canonicalized)
- *   --projects all → no filter, even when one is configured (explicit override)
- *   (no flag)      → the live-capture filter (AI_LENS_PROJECTS / config
- *                    `projects`), so import never ships history that live
- *                    capture would have dropped via project_filter.
- * `monitored` is getMonitoredProjects() output: normalized absolute paths or
- * null. Matching semantics are identical to live capture's pathContains
- * (entry === path || path inside entry), so no extra canonicalization needed.
- * Returns { filter: string[]|null, source: 'flag'|'config'|null }.
- */
-export function resolveProjectFilter(projectsFlag, monitored) {
-  if (typeof projectsFlag === 'string' && projectsFlag.trim()) {
-    if (projectsFlag.trim().toLowerCase() === 'all') return { filter: null, source: null };
-    return { filter: projectsFlag.split(',').map(normalizeProjectArg).filter(Boolean), source: 'flag' };
-  }
-  if (Array.isArray(monitored) && monitored.length > 0) return { filter: monitored, source: 'config' };
-  return { filter: null, source: null };
-}
-
-/** Path-boundary match (so /repo does NOT match /repo2). */
-export function projectMatches(projectPath, filters) {
-  if (!filters) return true;
-  if (!projectPath) return false;
-  return filters.some((pf) => projectPath === pf || projectPath.startsWith(pf + '/'));
-}
-
-/**
- * Ask the server, for these session_ids, the earliest LIVE (non-import) event
- * timestamp it already has → { sessionId: minIso }. Best-effort: on any failure
- * (old server without the route, network) returns {} so we import everything
- * (TokenUsage still dedups on its live-compatible id; nothing is lost).
- */
-export async function fetchCoverage(sessionIds, { fetchImpl = globalThis.fetch } = {}) {
-  const out = {};
-  if (!sessionIds.length || !fetchImpl) return out;
-  const base = getServerUrl();
-  const token = getAuthToken();
-  // Auth: token preferred, else git-identity headers so coverage also works in
-  // self-host personal mode (no token) — same fallback the ingest path uses.
-  const ident = token ? null : getGitIdentity(process.cwd());
-  const authHeaders = token
-    ? { 'X-Auth-Token': token }
-    : (ident?.email ? { 'X-Developer-Git-Email': ident.email, ...(ident.name ? { 'X-Developer-Name': ident.name } : {}) } : {});
-  const CHUNK = 400;
-  for (let i = 0; i < sessionIds.length; i += CHUNK) {
-    const batch = sessionIds.slice(i, i + CHUNK);
-    try {
-      const res = await fetchImpl(new URL('/api/events/coverage', base), {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', ...authHeaders },
-        body: JSON.stringify({ session_ids: batch }),
-      });
-      if (res.ok) Object.assign(out, await res.json());
-    } catch { /* best-effort */ }
-  }
-  return out;
-}
-
-/**
- * Can the importer actually deliver events? A personal auth token OR a resolvable
- * git email (the ingest path accepts either). Pure-ish; takes the two resolvers so
- * it's testable without touching real git/env.
- */
-export function hasDeliverableIdentity(token, gitEmail) {
-  return !!token || !!gitEmail;
-}
-
-/**
- * Drop events at/after the live-coverage boundary for their session, so import
- * only adds the pre-live backlog. No boundary ⇒ keep all. (Pure, for tests.)
- */
-export function sliceEvents(events, coverage) {
-  return events.filter((ev) => {
-    const boundary = coverage[ev.session_id];
-    if (!boundary) return true;
-    // Compare instants, not strings — server timestamps may lack the ms ('…00Z'
-    // vs '…00.000Z'), which would mis-sort a boundary-equal event lexically.
-    return Date.parse(ev.timestamp) < Date.parse(boundary);
-  });
-}
-
 function walkJsonl(dir) {
   const out = [];
   let entries;
@@ -245,23 +100,6 @@ function walkJsonl(dir) {
   return out;
 }
 
-function loadLedger() {
-  try { return JSON.parse(readFileSync(LEDGER_PATH, 'utf-8')); } catch { return {}; }
-}
-function saveLedger(ledger) {
-  mkdirSync(join(DATA_DIR, 'import-state'), { recursive: true });
-  const tmp = LEDGER_PATH + '.tmp';
-  writeFileSync(tmp, JSON.stringify(ledger));
-  renameSync(tmp, LEDGER_PATH);
-}
-
-/** A file is already covered if a prior run imported a wider-or-equal window AND the file is unchanged. */
-export function ledgerCovers(entry, cutoff, fp) {
-  if (!entry || !entry.fingerprint) return false;
-  if (entry.fingerprint.mtimeMs !== fp.mtimeMs || entry.fingerprint.size !== fp.size) return false;
-  return entry.complete_all || (entry.covered_cutoff && entry.covered_cutoff <= cutoff);
-}
-
 /** Read one transcript file fully (line-by-line, never JSON.parse(whole_file)). */
 async function readTranscript(filePath) {
   const lines = [];
@@ -290,23 +128,6 @@ function firstSessionId(lines, fallback) {
   return fallback;
 }
 
-async function drainSpool({ timeoutMs = 120_000 } = {}) {
-  const senderPath = join(__dirname, '..', '..', 'client', 'sender.js');
-  const pendingCount = () => { try { return readdirSync(PENDING_DIR).filter((f) => f.endsWith('.json')).length; } catch { return 0; } };
-  const sendingCount = () => { try { return readdirSync(SENDING_DIR).filter((f) => f.endsWith('.json')).length; } catch { return 0; } };
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (pendingCount() === 0 && sendingCount() === 0) return true;
-    await new Promise((resolve) => {
-      const child = spawn(process.execPath, [senderPath], { stdio: 'ignore' });
-      child.on('exit', resolve);
-      child.on('error', resolve);
-    });
-    await new Promise((r) => setTimeout(r, 400));
-  }
-  return pendingCount() === 0 && sendingCount() === 0;
-}
-
 export default async function importClaudeCode(flags) {
   const {
     days = 90, since = null, from = null, to = null, dryRun = false, projects = null,
@@ -320,10 +141,17 @@ export default async function importClaudeCode(flags) {
     return;
   }
   // Need a way to attribute events: a token, OR a git email (self-host personal
-  // mode ships via the git-identity fallback, just like live capture).
-  if (!dryRun && !hasDeliverableIdentity(getAuthToken(), getGitIdentity(process.cwd())?.email)) {
-    error('No identity to attribute events. Run `npx ai-lens init` first, or set a git user.email (or AI_LENS_AUTH_TOKEN).');
-    return;
+  // mode ships via the git-identity fallback, just like live capture). Checked in
+  // dry-run too (as a warning, not a hard stop) so a green dry-run never hides a
+  // delivery blocker the real run would hit.
+  if (!hasDeliverableIdentity(getAuthToken(), getGitIdentity(process.cwd())?.email)) {
+    const idMsg = 'No identity to attribute events. Set git user.email AND user.name (self-host ingest needs both), or AI_LENS_AUTH_TOKEN, or run `npx ai-lens init`.';
+    if (dryRun) {
+      warn(`${idMsg} (dry-run continues, but a real import would NOT deliver until identity resolves.)`);
+    } else {
+      error(idMsg);
+      return;
+    }
   }
   if (noRedact) warn('⚠ --no-redact: secrets in raw transcripts are NOT redacted client-side and persist locally in the spool if a send fails. Use only for debugging.');
 
@@ -351,7 +179,11 @@ export default async function importClaudeCode(flags) {
     detail('Pass --projects all to import everything, or --projects A,B to override.');
   }
   ensureDataDir();
-  const ledger = loadLedger();
+  // Shared ship engine: spool → batched drain → ledger-commit-after-ship.
+  const shipper = createImportShipper({
+    ledgerPath: LEDGER_PATH, dryRun, source: 'claude_code', computeEventId, noRedact,
+    beforeDrain: (n) => progress(`shipping ${n} event(s) to the server…`),
+  });
   // Human-readable window label for the progress lines.
   const windowLabel = (from || to)
     ? `${from || 'start'}…${to || 'now'}`
@@ -366,23 +198,6 @@ export default async function importClaudeCode(flags) {
   let lastDate = null;
   const nowMs = Date.now();
 
-  // Batched shipping: spool events, and every DRAIN_BATCH events drain the spool
-  // to the server, committing the ledger only for files whose events have shipped.
-  let inFlight = 0;            // events spooled since the last successful drain
-  const pendingCommit = [];   // {filePath, entry} for fully-written, not-yet-committed files
-  let drainFailed = false;
-  const flush = async () => {
-    if (dryRun) { inFlight = 0; return true; }
-    progress(`shipping ${inFlight} event(s) to the server…`);
-    const ok = await drainSpool();
-    if (!ok) { drainFailed = true; return false; }
-    inFlight = 0;
-    for (const c of pendingCommit) ledger[c.filePath] = c.entry;
-    if (pendingCommit.length) saveLedger(ledger);
-    pendingCommit.length = 0;
-    return true;
-  };
-
   // Pass 1 — cheap shortlist (mtime + ledger), no file reads. A transcript's
   // filename basename IS the session UUID, so we can gather session ids for the
   // coverage query without reading anything.
@@ -393,7 +208,7 @@ export default async function importClaudeCode(flags) {
     try { st = statSync(filePath); } catch { continue; }
     const fp = { mtimeMs: Math.trunc(st.mtimeMs), size: st.size };
     if (st.mtime.toISOString() < cutoff) { filesSkipped++; continue; } // last write before window
-    if (!rangeMode && ledgerCovers(ledger[filePath], cutoff, fp)) { filesSkipped++; continue; }
+    if (!rangeMode && ledgerCovers(shipper.ledgerEntry(filePath), cutoff, fp)) { filesSkipped++; continue; }
     candidates.push({ filePath, fp });
   }
 
@@ -407,7 +222,7 @@ export default async function importClaudeCode(flags) {
   // Pass 2 — read, map, de-overlap, ship.
   let filesProcessed = 0;
   for (const { filePath, fp } of candidates) {
-    if (drainFailed) break;
+    if (shipper.failed) break;
     filesProcessed++;
     progress(`${dryRun ? 'scanning' : 'importing'}… ${filesProcessed}/${candidates.length} transcript(s) · ${eventCount} event(s) from ${sessionCount} session(s)`);
     const { lines, lastTs } = await readTranscript(filePath);
@@ -429,20 +244,14 @@ export default async function importClaudeCode(flags) {
     const mapped = mapTranscript(lines, { sessionId, projectPath, fileId, isSubagentFile, agentId, agentSlug: null, emitTerminal });
     if (mapped.length === 0) { filesSkipped++; continue; }
     // De-overlap with live coverage, then clip to the explicit [from, to] window.
-    const events = sliceEvents(mapped, coverage).filter((ev) => {
-      if (lowerMs == null && upperMs == null) return true;
-      const t = Date.parse(ev.timestamp);
-      if (lowerMs != null && t < lowerMs) return false;
-      if (upperMs != null && t >= upperMs) return false;
-      return true;
-    });
+    const events = clipWindow(sliceEvents(mapped, coverage), lowerMs, upperMs);
     if (events.length === 0) {
       // Nothing left for this file: either live already owns the session, or every
       // event fell outside the [from, to] window. Only the former is "live skipped";
       // only a full (unbounded) import may mark the file covered in the ledger.
       if (!rangeMode) {
         liveSkipped++;
-        if (!dryRun) pendingCommit.push({ filePath, entry: { covered_cutoff: cutoff, complete_all: days === 0, fingerprint: fp } });
+        if (!dryRun) shipper.deferCommit(filePath, { covered_cutoff: cutoff, complete_all: days === 0, fingerprint: fp });
       }
       continue;
     }
@@ -450,40 +259,18 @@ export default async function importClaudeCode(flags) {
     const ident = getGitIdentity(cwd);
     const gitMeta = getGitMetadata(projectPath);
 
-    for (const ev of events) {
-      const unified = {
-        event_id: computeEventId(ev),
-        source: 'claude_code',
-        session_id: ev.session_id,
-        type: ev.type,
-        project_path: ev.project_path,
-        timestamp: ev.timestamp,
-        data: { ...ev.data, _import: true }, // marks import rows so /coverage ignores them
-        raw: ev.raw,
-        developer_email: ident.email || null,
-        developer_name: ident.name || null,
-        git_remote: gitMeta.git_remote || null,
-        git_branch: gitMeta.git_branch || null,
-        git_commit: gitMeta.git_commit || null,
-      };
-      if (!dryRun) {
-        if (noRedact) writeRaw(unified); else writeToSpool(unified);
-        inFlight++;
-        // Drain BEFORE pending can approach the sender's overflow cap. Checked per
-        // event so a single huge transcript can't blow past it mid-file.
-        if (inFlight >= DRAIN_BATCH) { if (!(await flush())) break; }
-      }
-      eventCount++;
-    }
-    if (drainFailed) break;
+    // Drain BEFORE pending can approach the sender's overflow cap (handled inside
+    // shipper.ship per DRAIN_BATCH), so a single huge transcript can't blow past it.
+    eventCount += await shipper.ship(events, { ident, gitMeta });
+    if (shipper.failed) break;
 
     filesIncluded++;
     sessionCount++;
-    if (!isSubagentFile) (lastTs >= new Date(nowMs - analysisMaxAgeDays * 86400_000).toISOString() ? withinWindow++ : older++);
+    if (!isSubagentFile) (lastTs >= new Date(nowMs - analysisMaxAgeDays * DAY_MS).toISOString() ? withinWindow++ : older++);
     if (!lastDate || lastTs > lastDate) lastDate = lastTs;
     // Defer the ledger commit until this file's events have actually shipped (flush()).
     // A bounded `--from/--to` re-import never records coverage (it didn't read to "now").
-    if (!dryRun && !rangeMode) pendingCommit.push({ filePath, entry: { covered_cutoff: cutoff, complete_all: days === 0, fingerprint: fp } });
+    if (!dryRun && !rangeMode) shipper.deferCommit(filePath, { covered_cutoff: cutoff, complete_all: days === 0, fingerprint: fp });
     if (filesIncluded % 25 === 0) info(`  …${filesIncluded} files, ${eventCount} events — last ${(lastDate || '').slice(0, 10)}`);
   }
 
@@ -495,18 +282,10 @@ export default async function importClaudeCode(flags) {
   }
 
   info(`Spooled ${eventCount} event(s) from ${filesIncluded} session(s). Shipping…`);
-  const drained = await flush(); // ship the final partial batch + commit remaining ledger
+  const drained = await shipper.flush(); // ship the final partial batch + commit remaining ledger
   if (drained) success(`Imported ${sessionCount} session(s), ${eventCount} event(s).`);
   else warn(`Some events couldn't be shipped — their sessions were NOT marked imported and will retry on the next run. Check \`ai-lens status\`.`);
 
   detail(`Within ${analysisMaxAgeDays}d: ${withinWindow} session(s) eligible for auto-analysis. Older: ${older} (skipped by max-age ${analysisMaxAgeDays}, available on-demand).`);
   detail('Open /me to see your imported history.');
 }
-
-/** --no-redact path: write the event to pending/ WITHOUT client redaction. */
-function writeRaw(unified) {
-  const filename = `${unified.event_id}.json`;
-  const tmp = join(PENDING_DIR, filename + '.tmp.' + process.pid);
-  writeFileSync(tmp, JSON.stringify(unified));
-  renameSync(tmp, join(PENDING_DIR, filename));
-}