@gswangg/pi-duncan 0.1.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@gswangg/pi-duncan",
+  "version": "0.1.0",
+  "description": "Session memory for pi — query dormant sessions, hand off context across session boundaries",
+  "keywords": ["pi-package"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gswangg/pi-duncan.git"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-ai": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-ai": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": ["extensions"],
+    "skills": ["skills"]
+  }
+}

package/skills/duncan/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: duncan
+description: Query dormant sessions to recover context from previous work. Use when the user asks about earlier sessions, what was decided before, what happened in a previous conversation, or needs information that was lost to compaction. Also use when the current context references work done in prior sessions.
+---
+
+# Duncan — Session Query
+
+Query dormant sessions using the `duncan` tool. Each past session retains its full conversation context and can be queried independently.
+
+## Usage
+
+Call the `duncan` tool with:
+- `question` — specific, self-contained question (the dormant session has no knowledge of this conversation)
+- `sessions` — which sessions to search
+- `limit` — (optional) max windows to query. defaults to 50 for multi-session modes, unlimited for parent/filename.
+- `offset` — (optional) skip N windows for pagination. use when a previous query didn't find what you needed.
+
+## Session Modes
+
+| Mode | When to use |
+|------|------------|
+| `ancestors` | Default. Walks up the parent chain. Start here when unsure. |
+| `parent` | Only the immediate parent session. |
+| `descendants` | Sessions spawned from the current one (children, BFS). |
+| `project` | All sessions in the same working directory, newest first. Use when the info might be in a sibling/unrelated session. |
+| `global` | All sessions across all working directories, newest first. Last resort when info might be in another project entirely. |
+| `<filename>` | A specific session file when you know exactly which one. |
+
+## Guidelines
+
+- Start with `ancestors` unless there's a reason to use another mode.
+- Keep questions **specific and self-contained** — the dormant session sees only its own conversation plus your question.
+- One question per call. If you need multiple things, make multiple calls.
+- Results include a `hasContext` signal — if no session has context, say so rather than guessing.
+- If results show pagination info (e.g. "50 of 200 windows"), call again with a higher `offset` to search further.

package/tests/compaction-windows.test.mjs

@@ -0,0 +1,285 @@
+/**
+ * Test: compaction windowing for duncan fan-out.
+ *
+ * Creates synthetic sessions with compaction entries using pi's SessionManager,
+ * then validates that getCompactionWindows() correctly splits sessions into
+ * independently queryable windows. Cross-validates the last window against
+ * buildSessionContext().
+ *
+ * Run: tsx tests/compaction-windows.test.mjs
+ */
+
+import { getCompactionWindows } from "../extensions/duncan.ts";
+
+const { SessionManager, buildSessionContext, parseSessionEntries } = await import("@mariozechner/pi-coding-agent");
+
+import { readFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// ============================================================================
+// Test helpers
+// ============================================================================
+
+const TEST_DIR = join("/tmp", "duncan-compaction-test");
+const TEST_CWD = "/workspace";
+
+function setup() {
+  if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+  mkdirSync(TEST_DIR, { recursive: true });
+}
+
+function teardown() {
+  if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+}
+
+function makeUser(t) {
+  return {
+    role: "user",
+    content: [{ type: "text", text: t }],
+    timestamp: Date.now(),
+  };
+}
+
+function makeAssistant(t) {
+  return {
+    role: "assistant",
+    content: [{ type: "text", text: t }],
+    provider: "test",
+    model: "test-model",
+    stopReason: "endTurn",
+    usage: { input: 100, output: 50, cacheRead: 0, cacheWrite: 0, totalTokens: 150 },
+    timestamp: Date.now(),
+  };
+}
+
+function text(msg) {
+  if (msg.role === "compactionSummary") return `[SUMMARY] ${msg.summary}`;
+  if (typeof msg.content === "string") return msg.content;
+  if (Array.isArray(msg.content)) {
+    return msg.content.filter(c => c.type === "text").map(c => c.text).join("");
+  }
+  return JSON.stringify(msg);
+}
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, msg) {
+  if (!condition) {
+    console.error(`  ✗ ${msg}`);
+    failed++;
+  } else {
+    console.log(`  ✓ ${msg}`);
+    passed++;
+  }
+}
+
+function findEntryByText(sm, targetText) {
+  return sm.getEntries().find(e =>
+    e.type === "message" && text(e.message) === targetText
+  );
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+function test1() {
+  console.log("\n--- Test 1: No compactions → single window ---");
+  const sm = new SessionManager(TEST_CWD, TEST_DIR, undefined, true);
+  sm.appendMessage(makeUser("hello"));
+  sm.appendMessage(makeAssistant("world"));
+  sm.appendMessage(makeUser("ping"));
+  sm.appendMessage(makeAssistant("pong"));
+
+  const entries = parseSessionEntries(readFileSync(sm.getSessionFile(), "utf-8"));
+  const windows = getCompactionWindows(entries);
+
+  assert(windows.length === 1, "1 window");
+  assert(windows[0].messages.length === 4, `4 messages (got ${windows[0].messages.length})`);
+
+  const ctx = buildSessionContext(entries.filter(e => e.type !== "session"));
+  assert(ctx.messages.length === 4, `buildSessionContext also 4`);
+}
+
+function test2() {
+  console.log("\n--- Test 2: One compaction → 2 windows ---");
+  const sm = new SessionManager(TEST_CWD, TEST_DIR, undefined, true);
+  sm.appendMessage(makeUser("W0-A"));
+  sm.appendMessage(makeAssistant("W0-A resp"));
+  sm.appendMessage(makeUser("W0-B"));
+  sm.appendMessage(makeAssistant("W0-B resp"));
+  sm.appendMessage(makeUser("W0-C (kept)"));
+  sm.appendMessage(makeAssistant("W0-C resp (kept)"));
+
+  const keptEntry = findEntryByText(sm, "W0-C (kept)");
+  assert(!!keptEntry, "found kept entry");
+  sm.appendCompaction("Summary: W0 discussed A, B, C", keptEntry.id, 50000, { readFiles: [], modifiedFiles: [] });
+
+  sm.appendMessage(makeUser("W1-A"));
+  sm.appendMessage(makeAssistant("W1-A resp"));
+
+  const entries = parseSessionEntries(readFileSync(sm.getSessionFile(), "utf-8"));
+  const windows = getCompactionWindows(entries);
+
+  assert(windows.length === 2, `2 windows (got ${windows.length})`);
+  assert(windows[0].messages.length === 6, `w0: 6 msgs (got ${windows[0].messages.length})`);
+  assert(windows[1].messages.length === 5, `w1: 5 msgs (got ${windows[1].messages.length})`);
+  assert(text(windows[1].messages[0]).includes("[SUMMARY]"), "w1 starts with summary");
+
+  // Cross-validate last window against buildSessionContext
+  const ctx = buildSessionContext(entries.filter(e => e.type !== "session"));
+  assert(ctx.messages.length === windows[1].messages.length,
+    `w1 matches buildSessionContext (${windows[1].messages.length} vs ${ctx.messages.length})`);
+  for (let i = 0; i < ctx.messages.length; i++) {
+    assert(text(ctx.messages[i]) === text(windows[1].messages[i]),
+      `  msg[${i}] matches`);
+  }
+}
+
+function test3() {
+  console.log("\n--- Test 3: Two compactions → 3 windows ---");
+  const sm = new SessionManager(TEST_CWD, TEST_DIR, undefined, true);
+  sm.appendMessage(makeUser("W0-A"));
+  sm.appendMessage(makeAssistant("W0-A resp"));
+  sm.appendMessage(makeUser("W0-B"));
+  sm.appendMessage(makeAssistant("W0-B resp"));
+
+  const w0Kept = findEntryByText(sm, "W0-B");
+  sm.appendCompaction("C1: covers W0", w0Kept.id, 40000, { readFiles: [], modifiedFiles: [] });
+
+  sm.appendMessage(makeUser("W1-A"));
+  sm.appendMessage(makeAssistant("W1-A resp"));
+  sm.appendMessage(makeUser("W1-B"));
+  sm.appendMessage(makeAssistant("W1-B resp"));
+
+  const w1Kept = findEntryByText(sm, "W1-B");
+  sm.appendCompaction("C2: covers C1+W1", w1Kept.id, 45000, { readFiles: [], modifiedFiles: [] });
+
+  sm.appendMessage(makeUser("W2-A"));
+  sm.appendMessage(makeAssistant("W2-A resp"));
+
+  const entries = parseSessionEntries(readFileSync(sm.getSessionFile(), "utf-8"));
+  const windows = getCompactionWindows(entries);
+
+  assert(windows.length === 3, `3 windows (got ${windows.length})`);
+  assert(windows[0].messages.length === 4, `w0: 4 msgs (got ${windows[0].messages.length})`);
+  assert(windows[1].messages.length === 7, `w1: 7 msgs (got ${windows[1].messages.length})`);
+  assert(windows[2].messages.length === 5, `w2: 5 msgs (got ${windows[2].messages.length})`);
+
+  // Cross-validate last window
+  const ctx = buildSessionContext(entries.filter(e => e.type !== "session"));
+  assert(ctx.messages.length === windows[2].messages.length,
+    `w2 matches buildSessionContext (${windows[2].messages.length} vs ${ctx.messages.length})`);
+}
+
+function test4() {
+  console.log("\n--- Test 4: Content isolation ---");
+  const sm = new SessionManager(TEST_CWD, TEST_DIR, undefined, true);
+
+  sm.appendMessage(makeUser("ALPHA-unique"));
+  sm.appendMessage(makeAssistant("ALPHA-resp"));
+  const alphaKept = findEntryByText(sm, "ALPHA-unique");
+  sm.appendCompaction("Summary: alpha", alphaKept.id, 30000);
+
+  sm.appendMessage(makeUser("BETA-unique"));
+  sm.appendMessage(makeAssistant("BETA-resp"));
+  const betaKept = findEntryByText(sm, "BETA-unique");
+  sm.appendCompaction("Summary: alpha+beta", betaKept.id, 35000);
+
+  sm.appendMessage(makeUser("GAMMA-unique"));
+  sm.appendMessage(makeAssistant("GAMMA-resp"));
+
+  const entries = parseSessionEntries(readFileSync(sm.getSessionFile(), "utf-8"));
+  const windows = getCompactionWindows(entries);
+
+  const w0 = windows[0].messages.map(text).join(" ");
+  const w1 = windows[1].messages.map(text).join(" ");
+  const w2 = windows[2].messages.map(text).join(" ");
+
+  assert(w0.includes("ALPHA") && !w0.includes("BETA") && !w0.includes("GAMMA"),
+    "w0: only ALPHA");
+  assert(w1.includes("BETA") && !w1.includes("GAMMA"),
+    "w1: BETA (+ alpha summary), no GAMMA");
+  assert(w2.includes("GAMMA") && w2.includes("BETA-unique"),
+    "w2: GAMMA + kept BETA (via firstKeptEntryId) + summary");
+}
+
+function test5() {
+  console.log("\n--- Test 5: JSONL structure dump ---");
+  const sm = new SessionManager(TEST_CWD, TEST_DIR, undefined, true);
+  sm.appendMessage(makeUser("A"));
+  sm.appendMessage(makeAssistant("A-r"));
+  const a = findEntryByText(sm, "A");
+  sm.appendCompaction("C1", a.id, 10000);
+  sm.appendMessage(makeUser("B"));
+  sm.appendMessage(makeAssistant("B-r"));
+  const b = findEntryByText(sm, "B");
+  sm.appendCompaction("C2", b.id, 15000);
+  sm.appendMessage(makeUser("C"));
+  sm.appendMessage(makeAssistant("C-r"));
+
+  const raw = readFileSync(sm.getSessionFile(), "utf-8").trim().split("\n");
+  console.log("\n  Raw JSONL:");
+  for (const line of raw) {
+    const e = JSON.parse(line);
+    if (e.type === "session") console.log(`    [session] id=${e.id.slice(0,8)}`);
+    else if (e.type === "message") console.log(`    [msg] id=${e.id} "${text(e.message)}"`);
+    else if (e.type === "compaction") console.log(`    [compact] id=${e.id} firstKept=${e.firstKeptEntryId} "${e.summary}"`);
+  }
+
+  const entries = parseSessionEntries(readFileSync(sm.getSessionFile(), "utf-8"));
+  const windows = getCompactionWindows(entries);
+
+  console.log(`\n  Windows: ${windows.length}`);
+  for (const w of windows) {
+    console.log(`    W${w.windowIndex}: ${w.messages.map(m => `${m.role}:"${text(m).slice(0,30)}"`).join(", ")}`);
+  }
+  assert(windows.length === 3, "3 windows");
+}
+
+function test6() {
+  console.log("\n--- Test 6: getDuncanTargets ---");
+
+  function getDuncanTargets(sessionFile) {
+    const content = readFileSync(sessionFile, "utf-8");
+    const entries = parseSessionEntries(content);
+    const windows = getCompactionWindows(entries);
+    return windows.map(w => ({ sessionFile, windowIndex: w.windowIndex, messages: w.messages }));
+  }
+
+  const sm1 = new SessionManager(TEST_CWD, TEST_DIR, undefined, true);
+  sm1.appendMessage(makeUser("simple"));
+  sm1.appendMessage(makeAssistant("reply"));
+  const t1 = getDuncanTargets(sm1.getSessionFile());
+  assert(t1.length === 1, "uncompacted: 1 target");
+
+  const sm2 = new SessionManager(TEST_CWD, TEST_DIR, undefined, true);
+  sm2.appendMessage(makeUser("X"));
+  sm2.appendMessage(makeAssistant("X-r"));
+  sm2.appendCompaction("C1", findEntryByText(sm2, "X").id, 20000);
+  sm2.appendMessage(makeUser("Y"));
+  sm2.appendMessage(makeAssistant("Y-r"));
+  const t2 = getDuncanTargets(sm2.getSessionFile());
+  assert(t2.length === 2, "compacted: 2 targets");
+  assert(t2[0].windowIndex === 0 && t2[1].windowIndex === 1, "correct indices");
+}
+
+// ============================================================================
+// Run
+// ============================================================================
+
+setup();
+try {
+  test1();
+  test2();
+  test3();
+  test4();
+  test5();
+  test6();
+  console.log(`\n${passed} passed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+  console.log("✅ All tests passed\n");
+} finally {
+  teardown();
+}

package/tests/lineage.test.mjs

@@ -0,0 +1,315 @@
+/**
+ * Test: lineage, session discovery, and pagination helpers.
+ *
+ * Run: tsx tests/lineage.test.mjs
+ */
+
+import {
+  getAncestorChain,
+  getDescendantChain,
+  getProjectSessions,
+  getGlobalSessions,
+  getSessionPreview,
+  getDuncanTargets,
+  readSessionHeader,
+  buildSessionTree,
+  resolveGeneration,
+} from "../extensions/duncan.ts";
+
+const { SessionManager, parseSessionEntries } = await import("@mariozechner/pi-coding-agent");
+
+import { readFileSync, mkdirSync, rmSync, existsSync, writeFileSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+
+// ============================================================================
+// Test helpers
+// ============================================================================
+
+const TEST_ROOT = join("/tmp", "duncan-lineage-test");
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, msg) {
+  if (!condition) {
+    console.error(`  ✗ ${msg}`);
+    failed++;
+  } else {
+    console.log(`  ✓ ${msg}`);
+    passed++;
+  }
+}
+
+function setup() {
+  if (existsSync(TEST_ROOT)) rmSync(TEST_ROOT, { recursive: true });
+  mkdirSync(TEST_ROOT, { recursive: true });
+}
+
+function teardown() {
+  if (existsSync(TEST_ROOT)) rmSync(TEST_ROOT, { recursive: true });
+}
+
+function makeUser(t) {
+  return { role: "user", content: [{ type: "text", text: t }], timestamp: Date.now() };
+}
+
+function makeAssistant(t) {
+  return {
+    role: "assistant", content: [{ type: "text", text: t }],
+    provider: "test", model: "test-model", stopReason: "endTurn",
+    usage: { input: 100, output: 50, cacheRead: 0, cacheWrite: 0, totalTokens: 150 },
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Create a session with messages, optionally as a child of another session file.
+ * Returns the session file path.
+ */
+function createSession(sessionDir, messages, parentSessionFile) {
+  mkdirSync(sessionDir, { recursive: true });
+  const sm = new SessionManager("/workspace", sessionDir, undefined, true);
+  // If parentSessionFile specified, we need to manually write the header with parentSession
+  // since SessionManager doesn't expose this in constructor.
+  if (parentSessionFile) {
+    // Write messages first to get the file created
+    for (const msg of messages) sm.appendMessage(msg);
+    const file = sm.getSessionFile();
+    // Rewrite the header line to include parentSession
+    const content = readFileSync(file, "utf-8");
+    const lines = content.split("\n");
+    const header = JSON.parse(lines[0]);
+    header.parentSession = parentSessionFile;
+    lines[0] = JSON.stringify(header);
+    writeFileSync(file, lines.join("\n"));
+    return file;
+  }
+  for (const msg of messages) sm.appendMessage(msg);
+  return sm.getSessionFile();
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+function testReadSessionHeader() {
+  console.log("\n--- readSessionHeader ---");
+  const dir = join(TEST_ROOT, "header-test");
+  const file = createSession(dir, [makeUser("hello"), makeAssistant("world")]);
+
+  const header = readSessionHeader(file);
+  assert(header !== null, "header is not null");
+  assert(typeof header.id === "string" && header.id.length > 0, `has id: ${header.id.slice(0, 8)}`);
+  assert(typeof header.timestamp === "string", `has timestamp`);
+  assert(header.parentSession === undefined, "no parentSession on root session");
+}
+
+function testReadSessionHeaderWithParent() {
+  console.log("\n--- readSessionHeader with parentSession ---");
+  const dir = join(TEST_ROOT, "parent-header-test");
+  const parent = createSession(dir, [makeUser("parent msg"), makeAssistant("parent resp")]);
+  const child = createSession(dir, [makeUser("child msg"), makeAssistant("child resp")], parent);
+
+  const header = readSessionHeader(child);
+  assert(header !== null, "header is not null");
+  assert(header.parentSession === parent, `parentSession points to parent file`);
+}
+
+function testBuildSessionTree() {
+  console.log("\n--- buildSessionTree ---");
+  const dir = join(TEST_ROOT, "tree-test");
+
+  const root = createSession(dir, [makeUser("root"), makeAssistant("root-r")]);
+  const child1 = createSession(dir, [makeUser("child1"), makeAssistant("child1-r")], root);
+  const child2 = createSession(dir, [makeUser("child2"), makeAssistant("child2-r")], root);
+  const grandchild = createSession(dir, [makeUser("grandchild"), makeAssistant("grandchild-r")], child1);
+
+  const nodes = buildSessionTree(dir);
+  assert(nodes.size === 4, `4 nodes (got ${nodes.size})`);
+
+  const rootNode = nodes.get(root);
+  assert(rootNode.children.length === 2, `root has 2 children`);
+  assert(rootNode.generation === 0, `root is gen 0`);
+
+  const child1Node = nodes.get(child1);
+  assert(child1Node.generation === 1, `child1 is gen 1`);
+  assert(child1Node.children.length === 1, `child1 has 1 child`);
+
+  const grandchildNode = nodes.get(grandchild);
+  assert(grandchildNode.generation === 2, `grandchild is gen 2`);
+  assert(grandchildNode.children.length === 0, `grandchild has 0 children`);
+}
+
+function testAncestorChain() {
+  console.log("\n--- getAncestorChain ---");
+  const dir = join(TEST_ROOT, "ancestor-test");
+
+  const gen0 = createSession(dir, [makeUser("gen0"), makeAssistant("gen0-r")]);
+  const gen1 = createSession(dir, [makeUser("gen1"), makeAssistant("gen1-r")], gen0);
+  const gen2 = createSession(dir, [makeUser("gen2"), makeAssistant("gen2-r")], gen1);
+
+  const chain = getAncestorChain(gen2, dir);
+  assert(chain.length === 3, `3 ancestors (got ${chain.length})`);
+  assert(chain[0] === gen2, `chain[0] is self`);
+  assert(chain[1] === gen1, `chain[1] is parent`);
+  assert(chain[2] === gen0, `chain[2] is grandparent`);
+
+  // Root has only itself
+  const rootChain = getAncestorChain(gen0, dir);
+  assert(rootChain.length === 1, `root chain is 1 (self)`);
+}
+
+function testDescendantChain() {
+  console.log("\n--- getDescendantChain ---");
+  const dir = join(TEST_ROOT, "descendant-test");
+
+  const root = createSession(dir, [makeUser("root"), makeAssistant("root-r")]);
+  const child1 = createSession(dir, [makeUser("child1"), makeAssistant("child1-r")], root);
+  const child2 = createSession(dir, [makeUser("child2"), makeAssistant("child2-r")], root);
+  const grandchild = createSession(dir, [makeUser("gc"), makeAssistant("gc-r")], child1);
+
+  const chain = getDescendantChain(root, dir);
+  assert(chain.length === 3, `3 descendants (got ${chain.length})`);
+  assert(!chain.includes(root), `excludes self`);
+  assert(chain.includes(child1), `includes child1`);
+  assert(chain.includes(child2), `includes child2`);
+  assert(chain.includes(grandchild), `includes grandchild`);
+
+  // BFS order: children before grandchildren
+  const child1Idx = chain.indexOf(child1);
+  const gcIdx = chain.indexOf(grandchild);
+  assert(child1Idx < gcIdx, `child1 before grandchild (BFS)`);
+
+  // Leaf has no descendants
+  const leafChain = getDescendantChain(grandchild, dir);
+  assert(leafChain.length === 0, `leaf has 0 descendants`);
+}
+
+function testGetProjectSessions() {
+  console.log("\n--- getProjectSessions ---");
+  const dir = join(TEST_ROOT, "project-test");
+
+  const s1 = createSession(dir, [makeUser("first"), makeAssistant("first-r")]);
+  const s2 = createSession(dir, [makeUser("second"), makeAssistant("second-r")]);
+  const s3 = createSession(dir, [makeUser("third"), makeAssistant("third-r")]);
+
+  const sessions = getProjectSessions(dir);
+  assert(sessions.length === 3, `3 sessions (got ${sessions.length})`);
+
+  // All files present
+  const basenames = new Set(sessions.map(f => basename(f)));
+  assert(basenames.has(basename(s1)) && basenames.has(basename(s2)) && basenames.has(basename(s3)), `all sessions present`);
+
+  // Sorted by filename descending (newest first)
+  const sorted = [...sessions].sort((a, b) => basename(b).localeCompare(basename(a)));
+  assert(sessions.every((f, i) => f === sorted[i]), `sorted newest first`);
+}
+
+function testGetGlobalSessions() {
+  console.log("\n--- getGlobalSessions ---");
+  // Global scans sibling directories under the parent of sessionDir
+  const sessionsRoot = join(TEST_ROOT, "sessions");
+  const projA = join(sessionsRoot, "--project-a--");
+  const projB = join(sessionsRoot, "--project-b--");
+
+  const a1 = createSession(projA, [makeUser("a1"), makeAssistant("a1-r")]);
+  const a2 = createSession(projA, [makeUser("a2"), makeAssistant("a2-r")]);
+  const b1 = createSession(projB, [makeUser("b1"), makeAssistant("b1-r")]);
+
+  // getGlobalSessions takes a sessionDir (one project) and scans its parent
+  const global = getGlobalSessions(projA);
+  assert(global.length === 3, `3 global sessions (got ${global.length})`);
+
+  // Should include sessions from both projects
+  const basenames = new Set(global.map(f => basename(f)));
+  assert(basenames.has(basename(a1)), `includes a1 from project A`);
+  assert(basenames.has(basename(b1)), `includes b1 from project B`);
+
+  // All sorted by filename descending (newest first)
+  const sorted = [...global].sort((a, b) => basename(b).localeCompare(basename(a)));
+  assert(global.every((f, i) => f === sorted[i]), `sorted newest first`);
+}
+
+function testGetSessionPreview() {
+  console.log("\n--- getSessionPreview ---");
+  const dir = join(TEST_ROOT, "preview-test");
+
+  const file = createSession(dir, [
+    makeUser("What is the airspeed velocity of an unladen swallow?"),
+    makeAssistant("African or European?"),
+  ]);
+
+  const preview = getSessionPreview(file);
+  assert(preview.includes("airspeed velocity"), `preview has first user message: "${preview}"`);
+
+  // Long messages get truncated
+  const longFile = createSession(dir, [
+    makeUser("A".repeat(200)),
+    makeAssistant("ok"),
+  ]);
+  const longPreview = getSessionPreview(longFile);
+  assert(longPreview.length <= 80, `long preview truncated (${longPreview.length} chars)`);
+  assert(longPreview.endsWith("..."), `truncated preview ends with ...`);
+}
+
+function testResolveGeneration() {
+  console.log("\n--- resolveGeneration ---");
+  const dir = join(TEST_ROOT, "gen-test");
+
+  const gen0 = createSession(dir, [makeUser("gen0"), makeAssistant("gen0-r")]);
+  const gen1 = createSession(dir, [makeUser("gen1"), makeAssistant("gen1-r")], gen0);
+  const gen2 = createSession(dir, [makeUser("gen2"), makeAssistant("gen2-r")], gen1);
+
+  assert(resolveGeneration(gen0, dir) === 0, `gen0 = 0`);
+  assert(resolveGeneration(gen1, dir) === 1, `gen1 = 1`);
+  assert(resolveGeneration(gen2, dir) === 2, `gen2 = 2`);
+}
+
+function testGetDuncanTargetsWithParent() {
+  console.log("\n--- getDuncanTargets across lineage ---");
+  const dir = join(TEST_ROOT, "targets-lineage");
+
+  const parent = createSession(dir, [
+    makeUser("parent-work"), makeAssistant("parent-done"),
+  ]);
+  const child = createSession(dir, [
+    makeUser("child-work"), makeAssistant("child-done"),
+  ], parent);
+
+  const parentTargets = getDuncanTargets(parent);
+  assert(parentTargets.length === 1, `parent: 1 window`);
+  assert(parentTargets[0].messages.length === 2, `parent window has 2 messages`);
+
+  const childTargets = getDuncanTargets(child);
+  assert(childTargets.length === 1, `child: 1 window`);
+
+  // Ancestor chain from child includes both
+  const chain = getAncestorChain(child, dir);
+  assert(chain.length === 2, `chain has 2 sessions`);
+  let totalWindows = 0;
+  for (const file of chain) totalWindows += getDuncanTargets(file).length;
+  assert(totalWindows === 2, `2 total windows across lineage`);
+}
+
+// ============================================================================
+// Run
+// ============================================================================
+
+setup();
+try {
+  testReadSessionHeader();
+  testReadSessionHeaderWithParent();
+  testBuildSessionTree();
+  testAncestorChain();
+  testDescendantChain();
+  testGetProjectSessions();
+  testGetGlobalSessions();
+  testGetSessionPreview();
+  testResolveGeneration();
+  testGetDuncanTargetsWithParent();
+  console.log(`\n${passed} passed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+  console.log("✅ All tests passed\n");
+} finally {
+  teardown();
+}