Implement session tokens --since / --until filters

Both options were parsed but never applied in analyzeTokens, so they
were silent no-ops. Apply them session-level using file mtime (last
activity), skipping out-of-window files before the expensive per-file
parse.

Extract isFileWithinTimeRange as a pure, exported helper so the bound
checks are unit-testable without fixture files. Inclusive on both
ends.

Folded into v0.2.1 CHANGELOG alongside the --project fix.

Author: AnExiledDev

cli/CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Fixes
 
 - **`session tokens --project` now works with absolute paths** — the filter was comparing an on-disk slug (e.g. `-workspaces-projects-CodeForge`) to the raw `--project` path (e.g. `/workspaces/projects/CodeForge`), which never matched. Absolute paths and paths starting with `./` / `../` are now encoded to Claude's slug form (replacing `/` and `.` with `-`) before matching. Plain substrings without separators still pass through unchanged, so `--project CodeForge` keeps working.
+- **`session tokens --since` / `--until` now actually filter results** — both options were parsed but never applied. Filtering is session-level and uses file mtime (last-activity time) so sessions outside the window are skipped without being parsed.
 
 ## v0.2.0 — 2026-04-16
 

cli/src/commands/session/tokens.ts

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import type { Command } from "commander";
+import { stat } from "fs/promises";
 import { basename, isAbsolute, resolve } from "path";
 import { readLines } from "../../search/engine.js";
 import { discoverSessionFiles } from "../../utils/glob.js";
@@ -104,6 +105,25 @@ export function pathToProjectSlug(input: string): string {
 	return input;
 }
 
+/**
+ * Pure check for whether a file's last-modified time falls within an optional
+ * [since, until] window. Exported for direct unit testing without fixtures.
+ *
+ * Semantics:
+ * - `since`: mtime must be >= since (inclusive)
+ * - `until`: mtime must be <= until (inclusive)
+ * - If both bounds are omitted, always returns true.
+ */
+export function isFileWithinTimeRange(
+	mtime: Date,
+	since?: Date,
+	until?: Date,
+): boolean {
+	if (since && mtime < since) return false;
+	if (until && mtime > until) return false;
+	return true;
+}
+
 function isSubagentPath(filePath: string): boolean {
 	return filePath.includes("/subagents/");
 }
@@ -332,13 +352,28 @@ async function analyzeTokens(options: {
 		? pathToProjectSlug(options.project)
 		: undefined;
 
+	const hasTimeFilter = !!(options.since || options.until);
+
 	for (const filePath of files) {
 		// Filter by project (slug-to-slug match; absolute paths are encoded).
 		if (projectNeedle) {
 			const project = extractProjectFromPath(filePath);
 			if (!project?.includes(projectNeedle)) continue;
 		}
 
+		// Filter by file mtime (session activity time) before the expensive
+		// per-file parse. Sessions outside the window are skipped without reads.
+		if (hasTimeFilter) {
+			try {
+				const st = await stat(filePath);
+				if (!isFileWithinTimeRange(st.mtime, options.since, options.until)) {
+					continue;
+				}
+			} catch {
+				continue;
+			}
+		}
+
 		const stats = await analyzeSessionTokens(filePath);
 		if (!stats) continue;
 

cli/tests/tokens.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import { pathToProjectSlug } from "../src/commands/session/tokens.js";
+import {
+	isFileWithinTimeRange,
+	pathToProjectSlug,
+} from "../src/commands/session/tokens.js";
 
 describe("pathToProjectSlug", () => {
 	test("encodes absolute paths to claude's slug form", () => {
@@ -41,3 +44,31 @@ describe("pathToProjectSlug", () => {
 		expect(abs2.endsWith("-bar")).toBe(true);
 	});
 });
+
+describe("isFileWithinTimeRange", () => {
+	const jan1 = new Date("2026-01-01T00:00:00Z");
+	const feb1 = new Date("2026-02-01T00:00:00Z");
+	const mar1 = new Date("2026-03-01T00:00:00Z");
+
+	test("returns true when no bounds are given", () => {
+		expect(isFileWithinTimeRange(feb1)).toBe(true);
+	});
+
+	test("since: includes mtimes at or after the bound", () => {
+		expect(isFileWithinTimeRange(feb1, jan1)).toBe(true);
+		expect(isFileWithinTimeRange(feb1, feb1)).toBe(true); // inclusive
+		expect(isFileWithinTimeRange(feb1, mar1)).toBe(false);
+	});
+
+	test("until: includes mtimes at or before the bound", () => {
+		expect(isFileWithinTimeRange(feb1, undefined, mar1)).toBe(true);
+		expect(isFileWithinTimeRange(feb1, undefined, feb1)).toBe(true); // inclusive
+		expect(isFileWithinTimeRange(feb1, undefined, jan1)).toBe(false);
+	});
+
+	test("since + until: inclusive range", () => {
+		expect(isFileWithinTimeRange(feb1, jan1, mar1)).toBe(true);
+		expect(isFileWithinTimeRange(jan1, feb1, mar1)).toBe(false);
+		expect(isFileWithinTimeRange(mar1, jan1, feb1)).toBe(false);
+	});
+});