feat: add 8-char cursor IDs for query pagination

Replace raw timestamp pagination with short cursor IDs. Cursors are
8-char hashes stored in ~/.agentcrumbs/.cursors.json with 1-hour TTL.

Flow: query --since 5m → output shows 'Next: --cursor a1b2c3d4' →
query --since 5m --cursor a1b2c3d4 for next page.

Keep --after/--before for explicit time windows.

Author: ericallam

docs/content/docs/cli/query.mdx

@@ -16,8 +16,9 @@ agentcrumbs query --since 5m
 | Flag | Description |
 | --- | --- |
 | `--since <duration>` | Relative time window (e.g., `5m`, `1h`, `24h`, `7d`) |
-| `--after <timestamp>` | Crumbs after this ISO timestamp (cursor for pagination) |
+| `--after <timestamp>` | Crumbs after this ISO timestamp |
 | `--before <timestamp>` | Crumbs before this ISO timestamp |
+| `--cursor <id>` | Resume from a previous page (8-char ID from output) |
 | `--limit <n>` | Results per page (default: 50) |
 | `--ns <pattern>` | Filter by namespace |
 | `--tag <tag>` | Filter by tag |
@@ -31,27 +32,33 @@ Time units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).
 
 ### Pagination
 
-Results are returned oldest-first, capped at `--limit` (default 50). When there are more results, the output includes a `Next page:` line with an `--after` timestamp you can use to fetch the next page.
+Results are returned oldest-first, capped at `--limit` (default 50). When there are more results, the output includes a short cursor ID for the next page.
 
 ```bash
 # First page
 agentcrumbs query --since 5m
-# Output: 50 of 128 crumbs. Next page: --after 2026-03-11T14:20:00.123Z
+# Output: 50 crumbs (1-50 of 128). Next: --cursor a1b2c3d4
 
 # Next page
-agentcrumbs query --since 5m --after 2026-03-11T14:20:00.123Z
+agentcrumbs query --since 5m --cursor a1b2c3d4
+# Output: 50 crumbs (51-100 of 128). Next: --cursor e5f6g7h8
 ```
 
+Cursors expire after 1 hour. You can also use `--after` / `--before` with ISO timestamps for explicit time windows without cursors.
+
 ### Examples
 
 ```bash
 # Last 5 minutes (all namespaces)
 agentcrumbs query --since 5m
 
+# Paginate through results
+agentcrumbs query --since 5m --cursor a1b2c3d4
+
 # Time window with absolute timestamps
 agentcrumbs query --after 2026-03-11T14:00:00Z --before 2026-03-11T14:05:00Z
 
-# Paginate through results
+# Smaller pages
 agentcrumbs query --since 1h --limit 25
 
 # Filter by session

packages/agentcrumbs/skills/agentcrumbs/SKILL.md

@@ -101,8 +101,8 @@ Start broad — query a time window across all namespaces, then paginate if ther
 # Start here: get recent crumbs across all services
 agentcrumbs query --since 5m
 
-# Paginate forward (timestamp from "Next page:" in output)
-agentcrumbs query --since 5m --after 2026-03-11T14:20:00.123Z
+# Paginate forward using the cursor from the output
+agentcrumbs query --since 5m --cursor a1b2c3d4
 
 # Time window with absolute bounds
 agentcrumbs query --after 2026-03-11T14:00:00Z --before 2026-03-11T14:05:00Z
@@ -115,6 +115,8 @@ agentcrumbs query --since 5m --tag error
 agentcrumbs query --session a1b2c3
 ```
 
+Results are paginated (50 per page by default). When there are more results, the output includes a `--cursor` ID for the next page. Pass it back to get the next page.
+
 Run `agentcrumbs <command> --help` for detailed options on any command.
 
 ## Enable tracing

packages/agentcrumbs/src/cli/commands/query.ts

@@ -2,13 +2,15 @@ import type { Crumb } from "../../types.js";
 import { formatCrumbPretty, formatCrumbJson } from "../format.js";
 import { getFlag, hasFlag } from "../args.js";
 import { parseAppFlags, readAllCrumbs } from "../app-store.js";
+import { saveCursor, resolveCursor } from "../cursor.js";
 
 export async function query(args: string[]): Promise<void> {
   const ns = getFlag(args, "--ns");
   const tag = getFlag(args, "--tag");
   const since = getFlag(args, "--since");
   const after = getFlag(args, "--after");
   const before = getFlag(args, "--before");
+  const cursor = getFlag(args, "--cursor");
   const session = getFlag(args, "--session");
   const match = getFlag(args, "--match");
   const json = hasFlag(args, "--json");
@@ -64,8 +66,18 @@ export async function query(args: string[]): Promise<void> {
 
   const total = filtered.length;
 
-  // Take first `limit` crumbs (oldest first) for forward pagination
-  const results = filtered.slice(0, limit);
+  // Resolve cursor to skip offset
+  let startIndex = 0;
+  if (cursor) {
+    const entry = resolveCursor(cursor);
+    if (!entry) {
+      process.stderr.write(`Cursor expired or invalid: ${cursor}\n`);
+      process.exit(1);
+    }
+    startIndex = entry.offset;
+  }
+
+  const results = filtered.slice(startIndex, startIndex + limit);
 
   if (results.length === 0) {
     process.stderr.write("No crumbs found matching filters.\n");
@@ -81,14 +93,20 @@ export async function query(args: string[]): Promise<void> {
   }
 
   // Pagination footer
-  const hasMore = total > results.length;
+  const endIndex = startIndex + results.length;
+  const hasMore = endIndex < total;
   if (hasMore) {
     const lastTs = results[results.length - 1]!.ts;
+    const nextCursor = saveCursor(lastTs, endIndex);
     process.stderr.write(
-      `\n${results.length} of ${total} crumbs. Next page: --after ${lastTs}\n`
+      `\n${results.length} crumbs (${startIndex + 1}-${endIndex} of ${total}). Next: --cursor ${nextCursor}\n`
     );
   } else {
-    process.stderr.write(`\n${results.length} crumbs.\n`);
+    if (startIndex > 0) {
+      process.stderr.write(`\n${results.length} crumbs (${startIndex + 1}-${endIndex} of ${total}).\n`);
+    } else {
+      process.stderr.write(`\n${results.length} crumbs.\n`);
+    }
   }
 }
 

packages/agentcrumbs/src/cli/cursor.ts

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createHash } from "node:crypto";
+
+const CURSOR_FILE = path.join(os.homedir(), ".agentcrumbs", ".cursors.json");
+const MAX_CURSORS = 50;
+const CURSOR_TTL = 60 * 60 * 1000; // 1 hour
+
+type CursorEntry = {
+  ts: string;
+  offset: number;
+  createdAt: number;
+};
+
+type CursorMap = Record<string, CursorEntry>;
+
+function readCursors(): CursorMap {
+  try {
+    return JSON.parse(fs.readFileSync(CURSOR_FILE, "utf-8")) as CursorMap;
+  } catch {
+    return {};
+  }
+}
+
+function writeCursors(cursors: CursorMap): void {
+  const dir = path.dirname(CURSOR_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(CURSOR_FILE, JSON.stringify(cursors));
+}
+
+function generateId(ts: string, offset: number): string {
+  const hash = createHash("sha256").update(`${ts}:${offset}`).digest("hex");
+  return hash.slice(0, 8);
+}
+
+function pruneOld(cursors: CursorMap): CursorMap {
+  const now = Date.now();
+  const entries = Object.entries(cursors)
+    .filter(([, v]) => now - v.createdAt < CURSOR_TTL)
+    .sort((a, b) => b[1].createdAt - a[1].createdAt)
+    .slice(0, MAX_CURSORS);
+  return Object.fromEntries(entries);
+}
+
+export function saveCursor(ts: string, offset: number): string {
+  const id = generateId(ts, offset);
+  const cursors = pruneOld(readCursors());
+  cursors[id] = { ts, offset, createdAt: Date.now() };
+  writeCursors(cursors);
+  return id;
+}
+
+export function resolveCursor(id: string): CursorEntry | undefined {
+  const cursors = readCursors();
+  return cursors[id];
+}

packages/agentcrumbs/src/cli/index.ts

@@ -36,9 +36,10 @@ Tail options:
 
 Query options:
   --since <duration>   Relative time window (e.g., 5m, 1h, 24h)
-  --after <timestamp>  Crumbs after this ISO timestamp (for pagination)
+  --after <timestamp>  Crumbs after this ISO timestamp
   --before <timestamp> Crumbs before this ISO timestamp
-  --limit <n>          Max results per page (default: 50)
+  --cursor <id>        Resume from a previous page (8-char ID from output)
+  --limit <n>          Results per page (default: 50)
   --ns <pattern>       Filter by namespace
   --tag <tag>          Filter by tag
   --session <id>       Filter by session ID