ai-lens 0.8.84 → 0.8.85

package/.commithash

@@ -1 +1 @@
-8a405c3
+5905663

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 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.85 — 2026-06-09
+- feat: manage your own data from the CLI. `ai-lens list-sessions` lists your sessions, `ai-lens find-session <query>` finds one by id / project / source, and `ai-lens delete-sessions` removes your own sessions — by id (the short id shown by `list-sessions` works) or by `--from`/`--to` date range. Delete is a dry-run by default and only acts with `--yes`; it can only ever touch your own data, and a mistyped or ambiguous id is reported rather than silently ignored.
+- feat: `ai-lens import claude-code --from <date> --to <date>` imports a precise date window (events outside it are left out). Re-running an import over a window you've already imported is safe — it adds zero duplicates (every event has a stable id the server de-duplicates on), so you can re-seed a lost day without fear of doubling your history.
+
 ## 0.8.84 — 2026-06-08
 - fix: `ai-lens init` no longer wipes your saved auth token when a re-authentication is started but not finished — a closed browser, a timeout, or a transient server hiccup that briefly mis-flags a valid token. Previously this left `authToken: null` in your config and silently stopped all event capture until someone noticed; now the existing token is kept until a new one is actually obtained. If a server that requires auth does end up without a token, init now prints a loud "capture is OFF" error instead of a quiet note.
 

package/bin/ai-lens.js

@@ -23,6 +23,21 @@ switch (command) {
     await importCmd();
     break;
   }
+  case 'list-sessions': {
+    const { default: listSessions } = await import('../cli/list-sessions.js');
+    await listSessions();
+    break;
+  }
+  case 'find-session': {
+    const { default: findSession } = await import('../cli/find-session.js');
+    await findSession();
+    break;
+  }
+  case 'delete-sessions': {
+    const { default: deleteSessions } = await import('../cli/delete-sessions.js');
+    await deleteSessions();
+    break;
+  }
   case 'version':
   case '--version':
   case '-v': {
@@ -54,8 +69,15 @@ switch (command) {
     console.log('  import <source>  Import local history (source: claude-code)');
     console.log('    --days N         Window in days (default 30; 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('  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('  version         Show package version and commit hash');
     process.exit(command ? 1 : 0);
 }

package/cli/data-api.js

@@ -0,0 +1,80 @@
+/**
+ * Shared HTTP helpers for the self-service data commands (list-sessions,
+ * find-session, delete-sessions). Thin wrappers over the SAME endpoints the
+ * dashboard uses — `GET /api/sessions` and `DELETE /api/dashboard/chains/:id` —
+ * so there is no bespoke server surface to keep in sync.
+ *
+ * Auth: these endpoints sit behind `requireAuth`, which accepts an
+ * `ailens_dev_` personal token (or an Auth0 JWT). The git-email header fallback
+ * used by the ingest path does NOT authenticate here, so a token is required in
+ * any Auth0-configured deployment; a token-less self-host (no AUTH0_DOMAIN) is
+ * resolved to its singleton developer server-side. A 401 ⇒ tell the user to init.
+ */
+import { getServerUrl, getAuthToken } from '../client/config.js';
+
+const TIMEOUT_MS = 15_000;
+
+export class ApiError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+  }
+}
+
+/** Auth headers for a data request — token when we have one, else nothing. */
+export function authHeaders() {
+  const token = getAuthToken();
+  return token ? { 'X-Auth-Token': token } : {};
+}
+
+async function apiFetch(path, opts = {}) {
+  const url = new URL(path, getServerUrl());
+  let res;
+  try {
+    res = await fetch(url, {
+      ...opts,
+      headers: { ...authHeaders(), ...(opts.headers || {}) },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (err) {
+    throw new ApiError(`Cannot reach server at ${getServerUrl()} (${err.code || err.message}).`, 0);
+  }
+  if (res.status === 401) {
+    throw new ApiError('Not authenticated. Run `npx ai-lens init` to sign in (or set AI_LENS_AUTH_TOKEN).', 401);
+  }
+  return res;
+}
+
+/**
+ * List the caller's own sessions. Without the `team_members` scope the server
+ * forces `developer_id = self`, so this is always self-scoped for a normal token.
+ * Returns the raw session objects (session_id, source, project_path, started_at,
+ * last_event_at, duration_minutes, event_count, used_plan_mode, …).
+ */
+export async function fetchSessions({ days, source, limit } = {}) {
+  const params = new URLSearchParams();
+  if (Number.isFinite(days) && days > 0) params.set('days', String(days));
+  if (source) params.set('source', source);
+  if (Number.isFinite(limit) && limit > 0) params.set('limit', String(limit));
+  const qs = params.toString();
+  const res = await apiFetch(`/api/sessions${qs ? `?${qs}` : ''}`);
+  if (!res.ok) throw new ApiError(`Server returned HTTP ${res.status} listing sessions.`, res.status);
+  const data = await res.json();
+  return Array.isArray(data) ? data : (data.sessions || []);
+}
+
+/**
+ * Delete one session by id. The server resolves the id to the activity CHAIN it
+ * belongs to and deletes the whole chain (events + analyses + chunks + costs),
+ * owner-scoped — only the caller's own data. 403/404 are returned, not thrown,
+ * so a batch can report-and-continue.
+ */
+export async function deleteSessionById(id) {
+  const res = await apiFetch(`/api/dashboard/chains/${encodeURIComponent(id)}`, { method: 'DELETE' });
+  if (res.status === 403) return { ok: false, status: 403, reason: 'not yours' };
+  if (res.status === 404) return { ok: false, status: 404, reason: 'not found / already deleted' };
+  if (!res.ok) return { ok: false, status: res.status, reason: `HTTP ${res.status}` };
+  const body = await res.json().catch(() => ({}));
+  return { ok: true, status: res.status, body };
+}

package/cli/data-format.js

@@ -0,0 +1,78 @@
+/**
+ * Shared flag parsing + session formatting for the self-service data commands.
+ */
+import { basename } from 'node:path';
+
+/** Shared ISO-date validator for `--from`/`--to` flags (lenient Date.parse). */
+export const isValidDate = (s) => typeof s === 'string' && !Number.isNaN(Date.parse(s));
+
+/**
+ * Generic argv parser shared by list/find/delete. Mirrors cli/import.js: a value
+ * flag whose next token is missing or is itself another flag does NOT consume it
+ * (records a missing-value error instead) — so `--source --yes` can't silently
+ * swallow `--yes`. An int flag whose value isn't a number is an error too, never
+ * a silently-dropped NaN. Non-flag tokens collect into `positional`.
+ */
+export function parseArgs(argv, { bools = {}, values = {}, ints = new Set() } = {}) {
+  const flags = {};
+  const positional = [];
+  const errors = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (bools[arg]) { flags[bools[arg]] = true; continue; }
+    if (values[arg]) {
+      const next = argv[i + 1];
+      if (next == null || next.startsWith('--')) { errors.push(`Missing value for ${arg}.`); continue; }
+      i++;
+      const key = values[arg];
+      if (ints.has(key)) {
+        const n = parseInt(next, 10);
+        if (Number.isNaN(n)) { errors.push(`Invalid number for ${arg}: "${next}".`); continue; }
+        flags[key] = n;
+      } else {
+        flags[key] = next;
+      }
+      continue;
+    }
+    if (arg.startsWith('--')) { errors.push(`Unknown flag "${arg}".`); continue; }
+    positional.push(arg);
+  }
+  return { flags, positional, errors };
+}
+
+export function shortId(id) {
+  return String(id || '').slice(0, 8);
+}
+
+/** ISO/Date/number → `YYYY-MM-DD HH:MM`. Tolerates the JSON-serialized shapes. */
+export function fmtDate(value) {
+  if (!value) return '—';
+  const s = typeof value === 'string' ? value : new Date(value).toISOString();
+  return Number.isNaN(Date.parse(s)) ? '—' : s.slice(0, 16).replace('T', ' ');
+}
+
+function fmtProject(p) {
+  if (!p) return '—';
+  return basename(p) || p;
+}
+
+const pad = (s, n) => String(s).padEnd(n);
+const padL = (s, n) => String(s).padStart(n);
+
+// Single source of truth for column widths so the header and the rows can't drift.
+const COL = { id: 8, source: 11, project: 24, started: 16, dur: 6, events: 6 };
+
+export const SESSION_HEADER =
+  `${pad('id', COL.id)}  ${pad('source', COL.source)}  ${pad('project', COL.project)}  ${pad('started', COL.started)}  ${padL('dur', COL.dur)}  ${padL('events', COL.events)}`;
+
+/** One aligned line per session for the list/find tables. */
+export function formatSessionLine(s) {
+  const id = pad(shortId(s.session_id), COL.id);
+  const src = pad(String(s.source || '?').slice(0, COL.source), COL.source);
+  const proj = pad(fmtProject(s.project_path).slice(0, COL.project), COL.project);
+  const started = pad(fmtDate(s.started_at), COL.started);
+  const dur = padL(`${Math.round(Number(s.duration_minutes) || 0)}m`, COL.dur);
+  const ev = padL(`${Number(s.event_count) || 0}`, COL.events);
+  const plan = s.used_plan_mode ? '  plan' : '';
+  return `${id}  ${src}  ${proj}  ${started}  ${dur}  ${ev}${plan}`;
+}

package/cli/delete-sessions.js

@@ -0,0 +1,207 @@
+/**
+ * `ai-lens delete-sessions` — delete your OWN sessions, by id or by date range.
+ *
+ *   ai-lens delete-sessions <id> <id> …                 # explicit ids (full or short)
+ *   ai-lens delete-sessions --from D --to D [--source S] # a window
+ *
+ * DRY-RUN BY DEFAULT: prints what would be deleted and stops. Pass --yes to
+ * actually delete. Both modes resolve the matching sessions client-side (same
+ * `GET /api/sessions` the dashboard uses), then delete EACH via the existing
+ * owner-scoped `DELETE /api/dashboard/chains/:id` — no new server endpoint.
+ *
+ * Ids are resolved against your session list, so a SHORT id (as printed by
+ * `ai-lens list-sessions`) works — exact match or unique prefix. A prefix that
+ * matches several sessions is rejected; one that matches none is reported, not
+ * silently treated as "already deleted".
+ *
+ * Blast radius: the server resolves each id to the activity CHAIN it belongs to
+ * and deletes the whole chain (events + analyses + chunks + costs). Two ids in
+ * the same chain ⇒ the second delete is a harmless "already deleted".
+ */
+import { initLogger, heading, info, success, warn, error, detail, blank } from './logger.js';
+import { getVersionInfo } from './hooks.js';
+import { fetchSessions, deleteSessionById, ApiError } from './data-api.js';
+import { parseArgs, shortId, formatSessionLine, SESSION_HEADER, isValidDate } from './data-format.js';
+
+const DAY_MS = 86_400_000;
+// Wide window for resolving ids against the session list — covers practically all
+// history so a short id from `list-sessions` resolves regardless of its age.
+const RESOLVE_WINDOW_DAYS = 3650;
+// Matches the server's MAX_LIST_LIMIT; hitting it means older sessions were dropped.
+const RESOLVE_LIMIT = 5000;
+// A non-matching token this long is taken as a full id outside the list window
+// (still attempted); a shorter non-match is treated as a typo and reported.
+const LITERAL_ID_MIN_LEN = 12;
+
+export function parseDeleteArgs(argv) {
+  return parseArgs(argv, {
+    bools: { '--yes': 'yes', '--json': 'json' },
+    values: { '--from': 'from', '--to': 'to', '--source': 'source', '--days': 'days' },
+    ints: new Set(['days']),
+  });
+}
+
+/**
+ * Keep sessions whose START falls in the window. Lower bound is `--from` (00:00)
+ * or, when only `--days N` is given, a rolling `now - N days`. Upper bound is
+ * `--to` (inclusive of that whole day). Any bound may be absent.
+ */
+export function inRange(session, { from, to, days }, now = Date.now()) {
+  const t = Date.parse(session.started_at);
+  if (Number.isNaN(t)) return false;
+  const lowerMs = from
+    ? Date.parse(from)
+    : (Number.isFinite(days) && days > 0 ? now - days * DAY_MS : null);
+  if (lowerMs != null && t < lowerMs) return false;
+  if (to && t >= Date.parse(to) + DAY_MS) return false;
+  return true;
+}
+
+/**
+ * Resolve an id token against the visible sessions: exact match or unique prefix.
+ * Returns { kind: 'resolved', session } | { kind: 'ambiguous', candidates }
+ *       | { kind: 'literal' } (long, no match — try as-is) | { kind: 'none' }.
+ */
+export function resolveId(token, sessions) {
+  const exact = sessions.find((s) => s.session_id === token);
+  if (exact) return { kind: 'resolved', session: exact };
+  const pre = sessions.filter((s) => String(s.session_id).startsWith(token));
+  if (pre.length === 1) return { kind: 'resolved', session: pre[0] };
+  if (pre.length > 1) return { kind: 'ambiguous', candidates: pre };
+  if (token.length >= LITERAL_ID_MIN_LEN) return { kind: 'literal' };
+  return { kind: 'none' };
+}
+
+export default async function deleteSessions() {
+  const { flags, positional, errors } = parseDeleteArgs(process.argv.slice(3));
+  const { version, commit } = getVersionInfo();
+  initLogger(`v${version} (${commit})`);
+
+  const usage = 'Usage: ai-lens delete-sessions <id…> | --from YYYY-MM-DD --to YYYY-MM-DD [--source S] [--days N]   (add --yes to confirm)';
+  const rangeMode = flags.from != null || flags.to != null || flags.days != null;
+
+  if (errors.length) {
+    errors.forEach((e) => error(e));
+    info(usage);
+    process.exitCode = 1;
+    return;
+  }
+  if (flags.from && !isValidDate(flags.from)) { error(`Invalid --from "${flags.from}". Use YYYY-MM-DD.`); process.exitCode = 1; return; }
+  if (flags.to && !isValidDate(flags.to)) { error(`Invalid --to "${flags.to}". Use YYYY-MM-DD.`); process.exitCode = 1; return; }
+  if (flags.from && flags.to && Date.parse(flags.from) > Date.parse(flags.to)) {
+    error(`--from "${flags.from}" is after --to "${flags.to}".`); process.exitCode = 1; return;
+  }
+  if (!positional.length && !rangeMode) {
+    error('Nothing to delete: pass session id(s) or a --from/--to range.');
+    info(usage);
+    process.exitCode = 1;
+    return;
+  }
+
+  // One session fetch serves both id-resolution and range selection.
+  let sessions;
+  try {
+    sessions = await fetchSessions({ days: RESOLVE_WINDOW_DAYS, source: flags.source, limit: RESOLVE_LIMIT });
+  } catch (err) {
+    error(err instanceof ApiError ? err.message : `Failed to load sessions: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  // The list endpoint caps at RESOLVE_LIMIT rows (newest first). If we hit the cap,
+  // older sessions are invisible here — warn so a range that "matches nothing" or a
+  // short id that "doesn't resolve" isn't mistaken for "no such data".
+  if (sessions.length >= RESOLVE_LIMIT) {
+    warn(`Only the ${RESOLVE_LIMIT} most-recent sessions were loaded — older ones may not resolve. Use the full id, or a tighter --source.`);
+  }
+
+  const targets = [];
+  const seen = new Set();
+  const addTarget = (id, session) => {
+    if (!id || seen.has(id)) return;
+    seen.add(id);
+    targets.push({ id, session });
+  };
+
+  // Resolve explicit id tokens. Ambiguous prefixes abort the whole command
+  // (deleting the wrong chain is unrecoverable); unknown short tokens are skipped.
+  const ambiguous = [];
+  const notFound = [];
+  for (const token of positional) {
+    const r = resolveId(token, sessions);
+    if (r.kind === 'resolved') addTarget(r.session.session_id, r.session);
+    else if (r.kind === 'literal') addTarget(token, null);
+    else if (r.kind === 'ambiguous') ambiguous.push({ token, n: r.candidates.length });
+    else notFound.push(token);
+  }
+  if (ambiguous.length) {
+    for (const a of ambiguous) error(`"${a.token}" matches ${a.n} sessions — use a longer prefix or the full id.`);
+    info('Nothing deleted.');
+    process.exitCode = 1;
+    return;
+  }
+  for (const t of notFound) warn(`No session matches "${t}" — skipping.`);
+
+  if (rangeMode) {
+    for (const s of sessions.filter((s) => inRange(s, flags))) addTarget(s.session_id, s);
+  }
+
+  if (targets.length === 0) {
+    info('No sessions matched — nothing to delete.');
+    return;
+  }
+
+  // Preview.
+  heading(`${flags.yes ? 'Deleting' : 'Would delete'} ${targets.length} session(s)`);
+  warn('Each id removes the WHOLE activity chain it belongs to (all grouped sessions + their analyses).');
+  if (rangeMode) {
+    const lo = flags.from || (flags.days ? `last ${flags.days}d` : '…');
+    detail(`Range selects sessions that STARTED in ${lo}…${flags.to || 'now'} (a session that began earlier and ran into the window is not matched).`);
+  }
+  const withMeta = targets.filter((t) => t.session);
+  if (withMeta.length) {
+    info(SESSION_HEADER);
+    for (const t of withMeta) info(formatSessionLine(t.session));
+  }
+  const idOnly = targets.filter((t) => !t.session).map((t) => t.id);
+  if (idOnly.length) info(`Plus ${idOnly.length} full id(s) given directly: ${idOnly.map(shortId).join(', ')}`);
+  blank();
+
+  if (!flags.yes) {
+    info('Dry run — nothing deleted. Re-run with --yes to confirm.');
+    return;
+  }
+
+  // Execute.
+  let deletedChains = 0, deletedEvents = 0, skipped = 0, failed = 0;
+  const results = [];
+  for (const { id } of targets) {
+    let r;
+    try {
+      r = await deleteSessionById(id);
+    } catch (err) {
+      // 401 (auth) or network — fatal for the whole batch.
+      error(err instanceof ApiError ? err.message : `Delete failed: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (r.ok) {
+      deletedChains++;
+      deletedEvents += Number(r.body?.deleted_events) || 0;
+    } else if (r.status === 404) {
+      skipped++;
+    } else {
+      failed++;
+      warn(`  ${shortId(id)}: ${r.reason}`);
+    }
+    results.push({ id, ...r });
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify({ deletedChains, deletedEvents, skipped, failed, results }, null, 2));
+    return;
+  }
+  blank();
+  success(`Deleted ${deletedChains} chain(s), ${deletedEvents} event(s).`);
+  if (skipped) detail(`${skipped} already gone (same-chain or previously deleted).`);
+  if (failed) warn(`${failed} could not be deleted (not yours or server error).`);
+}

package/cli/find-session.js

@@ -0,0 +1,70 @@
+/**
+ * `ai-lens find-session <query>` — find your own sessions by a substring of the
+ * session id, project path, or source. Reuses the existing `GET /api/sessions`
+ * API (same data the dashboard lists), then filters client-side.
+ *
+ * The matcher (`matchSession`) is deliberately isolated so it can later be
+ * repointed at a richer/changed endpoint (e.g. content search) without touching
+ * the command shell.
+ */
+import { initLogger, heading, info, error, detail, blank } from './logger.js';
+import { getVersionInfo } from './hooks.js';
+import { fetchSessions, ApiError } from './data-api.js';
+import { parseArgs, SESSION_HEADER, formatSessionLine } from './data-format.js';
+
+/** True when `query` (case-insensitive) appears in the session's id/project/source. */
+export function matchSession(session, query) {
+  if (!query) return true;
+  const q = query.toLowerCase();
+  return [session.session_id, session.project_path, session.source]
+    .some((field) => String(field || '').toLowerCase().includes(q));
+}
+
+export function parseFindArgs(argv) {
+  return parseArgs(argv, {
+    bools: { '--json': 'json' },
+    values: { '--days': 'days', '--source': 'source', '--limit': 'limit' },
+    ints: new Set(['days', 'limit']),
+  });
+}
+
+export default async function findSession() {
+  const { flags, positional, errors } = parseFindArgs(process.argv.slice(3));
+  const { version, commit } = getVersionInfo();
+  initLogger(`v${version} (${commit})`);
+
+  const query = positional.join(' ').trim();
+  if (errors.length || !query) {
+    errors.forEach((e) => error(e));
+    if (!query) error('Missing search query.');
+    info('Usage: ai-lens find-session <query> [--days N] [--source S] [--limit N] [--json]');
+    process.exitCode = 1;
+    return;
+  }
+
+  let sessions;
+  try {
+    sessions = await fetchSessions({ days: flags.days, source: flags.source, limit: flags.limit });
+  } catch (err) {
+    error(err instanceof ApiError ? err.message : `Failed to search sessions: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const matches = sessions.filter((s) => matchSession(s, query));
+
+  if (flags.json) {
+    console.log(JSON.stringify(matches, null, 2));
+    return;
+  }
+
+  heading(`Sessions matching "${query}"`);
+  if (matches.length === 0) {
+    info(`No match in ${sessions.length} session(s). Widen with --days / --source.`);
+    return;
+  }
+  info(SESSION_HEADER);
+  for (const s of matches) info(formatSessionLine(s));
+  blank();
+  detail(`${matches.length} of ${sessions.length} session(s) matched. Full id with --json.`);
+}

package/cli/import/claude-code.js

@@ -5,7 +5,19 @@
  * (cli/import/transcript-map.js), enriches with developer + git identity,
  * redacts + spools via the live client pipeline (writeToSpool), and lets the
  * existing sender ship them to POST /api/events. Historical timestamps are kept
- * verbatim; re-import is idempotent via the server content-hash dedup.
+ * verbatim.
+ *
+ * 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
+ * already-ingested window inserts zero duplicate rows. This is the robust
+ * guarantee — independent of timestamp proximity and of payload size. (The
+ * server's 5-second content-hash window is a separate, secondary layer; because
+ * import keeps timestamps verbatim it happens to catch re-imports too, but it
+ * does nothing when `raw` is tiny — only the event_id UNIQUE constraint does.) A
+ * per-file fingerprint ledger additionally short-circuits unchanged transcripts
+ * 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 { join, basename } from 'node:path';
@@ -46,26 +58,63 @@ const DRAIN_BATCH = 4000;
 // 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 }) {
-  if (since != null) {
-    if (typeof since !== 'string' || Number.isNaN(Date.parse(since))) {
-      return `Invalid --since "${since}". Use YYYY-MM-DD.`;
+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 cutoff ISO string from flags. `--days 0` / no window ⇒ epoch (all). */
-export function resolveCutoff({ days, since }, now = new Date()) {
-  if (since) return new Date(Date.parse(since)).toISOString();
+/**
+ * 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 : 30;
   return new Date(now.getTime() - d * DAY_MS).toISOString();
 }
 
+/**
+ * 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();
@@ -214,7 +263,7 @@ async function drainSpool({ timeoutMs = 120_000 } = {}) {
 
 export default async function importClaudeCode(flags) {
   const {
-    days = 30, since = null, dryRun = false, projects = null,
+    days = 30, since = null, from = null, to = null, dryRun = false, projects = null,
     noRedact = false, analysisMaxAgeDays: amAgeFlag = 30,
   } = flags;
   const analysisMaxAgeDays = Number.isInteger(amAgeFlag) && amAgeFlag >= 0 ? amAgeFlag : 30;
@@ -232,18 +281,36 @@ export default async function importClaudeCode(flags) {
   }
   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.');
 
-  const flagErr = validateFlags({ days, since });
+  const flagErr = validateFlags({ days, since, from, to });
   if (flagErr) { error(flagErr); process.exitCode = 1; return; }
 
-  const cutoff = resolveCutoff({ days, since });
+  const lower = resolveLowerBound({ from }); // inclusive per-event lower, or null
+  const upper = resolveUpperBound({ to });   // exclusive per-event upper, or null
+  const lowerMs = lower != null ? Date.parse(lower) : null; // precomputed for the per-event filter
+  const upperMs = upper != null ? Date.parse(upper) : null;
+  // `--from`/`--to` is an explicit, precisely-clipped window. It re-reads files
+  // (the ledger marks a file "covered up to now", which a bounded window must not
+  // trust) and records NO coverage — re-import idempotency comes from the
+  // event_id UNIQUE dedup instead. `--days`/`--since` keep the fast ledger path.
+  const rangeMode = lower != null || upper != null;
+  // File-level cutoff (which transcripts to read). In range mode WITHOUT a lower
+  // bound (`--to` only) read everything and let the per-event upper clip decide —
+  // otherwise the default 30d cutoff would skip older files and import nothing.
+  const cutoff = (rangeMode && lower == null)
+    ? new Date(0).toISOString()
+    : resolveCutoff({ days, since, from });
   const projectFilter = projects
     ? projects.split(',').map(normalizeProjectArg).filter(Boolean)
     : null;
   ensureDataDir();
   const ledger = loadLedger();
+  // Human-readable window label for the progress lines.
+  const windowLabel = (from || to)
+    ? `${from || 'start'}…${to || 'now'}`
+    : (since || (days === 0 ? 'all' : days + 'd'));
   if (!dryRun) info(`Server: ${getServerUrl()}`);
-  info(dryRun ? `Scanning (dry-run, window: ${since || (days === 0 ? 'all' : days + 'd')})…`
-              : `Importing window: ${since || (days === 0 ? 'all' : days + 'd')} (cutoff ${cutoff.slice(0, 10)})`);
+  info(dryRun ? `Scanning (dry-run, window: ${windowLabel})…`
+              : `Importing window: ${windowLabel} (cutoff ${cutoff.slice(0, 10)}${upper ? `, until ${to}` : ''})`);
 
   const allFiles = [...new Set(walkJsonl(PROJECTS_DIR))];
   let filesIncluded = 0, filesSkipped = 0, eventCount = 0, sessionCount = 0, liveSkipped = 0;
@@ -276,7 +343,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 (ledgerCovers(ledger[filePath], cutoff, fp)) { filesSkipped++; continue; }
+    if (!rangeMode && ledgerCovers(ledger[filePath], cutoff, fp)) { filesSkipped++; continue; }
     candidates.push({ filePath, fp });
   }
 
@@ -308,11 +375,22 @@ export default async function importClaudeCode(flags) {
     const emitTerminal = (nowMs - fp.mtimeMs) >= TERMINAL_DORMANT_MS;
     const mapped = mapTranscript(lines, { sessionId, projectPath, fileId, isSubagentFile, agentId, agentSlug: null, emitTerminal });
     if (mapped.length === 0) { filesSkipped++; continue; }
-    const events = sliceEvents(mapped, coverage); // import only pre-live events
+    // 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;
+    });
     if (events.length === 0) {
-      // Whole session is at/after the live boundary — live already owns it.
-      liveSkipped++;
-      if (!dryRun) pendingCommit.push({ filePath, entry: { covered_cutoff: cutoff, complete_all: days === 0, fingerprint: fp } });
+      // 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 } });
+      }
       continue;
     }
 
@@ -351,7 +429,8 @@ export default async function importClaudeCode(flags) {
     if (!isSubagentFile) (lastTs >= new Date(nowMs - analysisMaxAgeDays * 86400_000).toISOString() ? withinWindow++ : older++);
     if (!lastDate || lastTs > lastDate) lastDate = lastTs;
     // Defer the ledger commit until this file's events have actually shipped (flush()).
-    if (!dryRun) pendingCommit.push({ filePath, entry: { covered_cutoff: cutoff, complete_all: days === 0, fingerprint: fp } });
+    // 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 (filesIncluded % 25 === 0) info(`  …${filesIncluded} files, ${eventCount} events — last ${(lastDate || '').slice(0, 10)}`);
   }
 

package/cli/import.js

@@ -6,7 +6,7 @@ import { initLogger, error, info } from './logger.js';
 import { getVersionInfo } from './hooks.js';
 
 const BOOL_FLAGS = { '--dry-run': 'dryRun', '--no-redact': 'noRedact' };
-const VALUE_FLAGS = { '--days': 'days', '--since': 'since', '--projects': 'projects', '--analysis-max-age-days': 'analysisMaxAgeDays' };
+const VALUE_FLAGS = { '--days': 'days', '--since': 'since', '--from': 'from', '--to': 'to', '--projects': 'projects', '--analysis-max-age-days': 'analysisMaxAgeDays' };
 const INT_KEYS = new Set(['days', 'analysisMaxAgeDays']);
 
 /**
@@ -17,7 +17,7 @@ const INT_KEYS = new Set(['days', 'analysisMaxAgeDays']);
  * REAL import instead of a preview.)
  */
 export function parseFlags(argv) {
-  const flags = { days: 30, since: null, dryRun: false, projects: null, noRedact: false, analysisMaxAgeDays: 30 };
+  const flags = { days: 30, since: null, from: null, to: null, dryRun: false, projects: null, noRedact: false, analysisMaxAgeDays: 30 };
   const errors = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -44,7 +44,7 @@ export default async function importCmd() {
 
   if (errors.length) {
     errors.forEach((e) => error(e));
-    info('Usage: ai-lens import claude-code [--days N | --since YYYY-MM-DD] [--projects A,B] [--dry-run] [--no-redact]');
+    info('Usage: ai-lens import claude-code [--days N | --since YYYY-MM-DD | --from YYYY-MM-DD --to YYYY-MM-DD] [--projects A,B] [--dry-run] [--no-redact]');
     process.exitCode = 1;
     return;
   }

package/cli/list-sessions.js

@@ -0,0 +1,53 @@
+/**
+ * `ai-lens list-sessions` — list your own sessions (thin client over
+ * `GET /api/sessions`). Filters: --days, --source, --limit. --json for raw output.
+ */
+import { initLogger, heading, info, error, detail, blank } from './logger.js';
+import { getVersionInfo } from './hooks.js';
+import { fetchSessions, ApiError } from './data-api.js';
+import { parseArgs, SESSION_HEADER, formatSessionLine } from './data-format.js';
+
+export function parseListFlags(argv) {
+  return parseArgs(argv, {
+    bools: { '--json': 'json' },
+    values: { '--days': 'days', '--source': 'source', '--limit': 'limit' },
+    ints: new Set(['days', 'limit']),
+  });
+}
+
+export default async function listSessions() {
+  const { flags, errors } = parseListFlags(process.argv.slice(3));
+  const { version, commit } = getVersionInfo();
+  initLogger(`v${version} (${commit})`);
+
+  if (errors.length) {
+    errors.forEach((e) => error(e));
+    info('Usage: ai-lens list-sessions [--days N] [--source claude_code|cursor|codex] [--limit N] [--json]');
+    process.exitCode = 1;
+    return;
+  }
+
+  let sessions;
+  try {
+    sessions = await fetchSessions({ days: flags.days, source: flags.source, limit: flags.limit });
+  } catch (err) {
+    error(err instanceof ApiError ? err.message : `Failed to list sessions: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(sessions, null, 2));
+    return;
+  }
+
+  heading(`Your sessions${flags.source ? ` (${flags.source})` : ''}${flags.days ? `, last ${flags.days}d` : ''}`);
+  if (sessions.length === 0) {
+    info('No sessions found for this window.');
+    return;
+  }
+  info(SESSION_HEADER);
+  for (const s of sessions) info(formatSessionLine(s));
+  blank();
+  detail(`${sessions.length} session(s). Full id with --json. Remove with: ai-lens delete-sessions <id>`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lens",
-  "version": "0.8.84",
+  "version": "0.8.85",
   "type": "module",
   "description": "Centralized session analytics for AI coding tools",
   "bin": {