agent-hours 0.3.0

package/dist/core.js

@@ -0,0 +1,417 @@
+/**
+ * claude-hours core — ported 1:1 from the battle-tested Python reference
+ * (reference/claude_hours.py + reference/prototype-split.py).
+ *
+ * Parity is enforced by test/parity.test.mjs: same fixtures through both
+ * implementations must yield identical numbers.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+export const PROJECTS_BASE = path.join(os.homedir(), ".claude", "projects");
+/** /Users/x/code/foo -> -Users-x-code-foo (Claude Code's project dir naming). */
+export function projectToHash(p) {
+    return path.resolve(p).split(path.sep).join("-");
+}
+export function findProjectDir(projectArg) {
+    let hashName;
+    if (projectArg) {
+        hashName =
+            projectArg.includes(path.sep) || projectArg.startsWith("/")
+                ? projectToHash(projectArg)
+                : projectArg;
+    }
+    else {
+        hashName = projectToHash(process.cwd());
+    }
+    return path.join(PROJECTS_BASE, hashName);
+}
+/**
+ * Event classification, verified against real Claude Code logs (2026-06):
+ *
+ * - `promptSource` (newer logs): "typed" = human, "system" = scheduled
+ *   tasks/hooks (phantom prompts!), "queued" = injection moment of a queued
+ *   message — the human typing already happened at the queue-operation
+ *   enqueue event, so the injection itself is NOT human time.
+ * - `queue-operation` enqueue with human content = the moment of real typing
+ *   WHILE Claude was running (strong presence proof). Enqueues carrying
+ *   `<task-notification>` payloads are system traffic.
+ * - `isSidechain` = subagent transcript — machine, never a human prompt.
+ * - `isCompactSummary` = synthetic continuation prompt, not human.
+ * - `attachment` edited_text_file = user edited a file in an external editor
+ *   (presence proof, not a prompt).
+ * - Legacy logs without `promptSource` fall back to the shape heuristic:
+ *   type=user, not isMeta, content is a string or has text but no tool_result.
+ */
+export function classifyRecord(record) {
+    const work = { kind: "work", presence: false };
+    const r = record;
+    if (!r)
+        return work;
+    if (r["isSidechain"] === true)
+        return work;
+    const t = r["type"];
+    if (t === "queue-operation") {
+        const content = r["content"];
+        if (r["operation"] === "enqueue" &&
+            typeof content === "string" &&
+            !content.trimStart().startsWith("<task-notification")) {
+            return { kind: "prompt", presence: true };
+        }
+        return work;
+    }
+    if (t === "attachment") {
+        const a = r["attachment"];
+        if (a?.["type"] === "edited_text_file")
+            return { kind: "work", presence: true };
+        return work;
+    }
+    if (t === "user" && !r["isMeta"] && !r["isCompactSummary"]) {
+        const src = r["promptSource"];
+        if (src === "system" || src === "queued")
+            return work;
+        if (src === "typed")
+            return { kind: "prompt", presence: true };
+        const msg = r["message"];
+        const c = msg?.["content"];
+        if (typeof c === "string")
+            return { kind: "prompt", presence: true };
+        if (Array.isArray(c)) {
+            const items = c.filter((i) => i !== null && typeof i === "object");
+            const hasText = items.some((i) => i["type"] === "text");
+            const hasToolResult = items.some((i) => i["type"] === "tool_result");
+            if (hasText && !hasToolResult)
+                return { kind: "prompt", presence: true };
+        }
+    }
+    return work;
+}
+/** Convenience wrapper: just the kind. */
+export function classifyKind(record) {
+    return classifyRecord(record).kind;
+}
+/**
+ * Reads all events of one session JSONL, filtered to [sinceMs, untilMs].
+ * With forceWork (subagent transcripts) every event counts as machine work —
+ * subagent "user" messages are task prompts from the orchestrator, not humans.
+ */
+export function loadSessionEvents(jsonlPath, sinceMs, untilMs, forceWork = false) {
+    let raw;
+    try {
+        raw = fs.readFileSync(jsonlPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const tsStr = record?.["timestamp"];
+        if (typeof tsStr !== "string")
+            continue;
+        const ts = Date.parse(tsStr);
+        if (Number.isNaN(ts))
+            continue;
+        if (ts < sinceMs || ts > untilMs)
+            continue;
+        if (forceWork) {
+            events.push({ ts, kind: "work", presence: false });
+        }
+        else {
+            const c = classifyRecord(record);
+            events.push({ ts, kind: c.kind, presence: c.presence });
+        }
+    }
+    events.sort((a, b) => a.ts - b.ts);
+    return events;
+}
+/**
+ * Loads all sessions of a project directory: top-level *.jsonl PLUS subagent
+ * transcripts in <sessionUuid>/subagents/agent-*.jsonl (newer Claude Code
+ * versions store parallel-agent work there — missing them undercounts total
+ * activity whenever only subagents were running).
+ */
+export function loadProject(projectDir, sinceMs, untilMs) {
+    let entries;
+    try {
+        entries = fs.readdirSync(projectDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const sessions = [];
+    for (const f of entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => e.name).sort()) {
+        const events = loadSessionEvents(path.join(projectDir, f), sinceMs, untilMs);
+        if (events.length > 0)
+            sessions.push({ name: f, events });
+    }
+    for (const dir of entries.filter((e) => e.isDirectory()).map((e) => e.name).sort()) {
+        const subDir = path.join(projectDir, dir, "subagents");
+        let subFiles;
+        try {
+            subFiles = fs.readdirSync(subDir).filter((f) => f.endsWith(".jsonl")).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const f of subFiles) {
+            const events = loadSessionEvents(path.join(subDir, f), sinceMs, untilMs, true);
+            if (events.length > 0)
+                sessions.push({ name: `${dir}/subagents/${f}`, events });
+        }
+    }
+    return sessions;
+}
+/**
+ * Industry-standard active time (WakaTime/RescueTime style): sum of
+ * inter-event gaps, each gap capped at capMinutes ("cap bonus" — a pause
+ * longer than the cap still contributes capMinutes).
+ */
+export function activeMinutes(timesMs, capMinutes) {
+    if (timesMs.length < 2)
+        return 0;
+    let total = 0;
+    for (let i = 1; i < timesMs.length; i++) {
+        const gap = (timesMs[i] - timesMs[i - 1]) / 60000;
+        total += Math.min(gap, capMinutes);
+    }
+    return total;
+}
+/** Strict variant: gaps > cap count 0 (no cap bonus). Honest lower bound. */
+export function activeMinutesStrict(timesMs, capMinutes) {
+    if (timesMs.length < 2)
+        return 0;
+    let total = 0;
+    for (let i = 1; i < timesMs.length; i++) {
+        const gap = (timesMs[i] - timesMs[i - 1]) / 60000;
+        if (gap <= capMinutes)
+            total += gap;
+    }
+    return total;
+}
+/** All gaps >= minMinutes, sorted by duration descending. */
+export function findPauses(timesMs, minMinutes) {
+    const pauses = [];
+    for (let i = 1; i < timesMs.length; i++) {
+        const minutes = (timesMs[i] - timesMs[i - 1]) / 60000;
+        if (minutes >= minMinutes) {
+            pauses.push({ startMs: timesMs[i - 1], endMs: timesMs[i], minutes });
+        }
+    }
+    pauses.sort((a, b) => b.minutes - a.minutes);
+    return pauses;
+}
+/**
+ * Merge all sessions into ONE sorted timeline. Critical for parallel
+ * sessions/agents: per-session sums would double-count overlapping wall-clock
+ * time; the merged timeline counts every real minute exactly once.
+ */
+export function mergeEvents(sessions) {
+    const merged = [];
+    for (const s of sessions)
+        merged.push(...s.events);
+    merged.sort((a, b) => a.ts - b.ts);
+    return merged;
+}
+/** True if at least two sessions' time windows overlap. */
+export function detectOverlaps(sessions) {
+    const ranges = sessions
+        .filter((s) => s.events.length >= 2)
+        .map((s) => [s.events[0].ts, s.events[s.events.length - 1].ts])
+        .sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    for (let i = 1; i < ranges.length; i++) {
+        if (ranges[i][0] < ranges[i - 1][1])
+            return true;
+    }
+    return false;
+}
+/**
+ * The core USP. Total = capped inter-event time over the merged timeline of
+ * ALL events. Human-active = capped inter-PROMPT time (its own cap — "waiting
+ * for Claude and testing" counts as active). AI-solo = total − human.
+ */
+export function computeSplit(merged, capMinutes, promptCapMinutes) {
+    const allTimes = merged.map((e) => e.ts);
+    const promptTimes = merged.filter((e) => e.kind === "prompt").map((e) => e.ts);
+    const totalMinutes = activeMinutes(allTimes, capMinutes);
+    const humanMinutes = activeMinutes(promptTimes, promptCapMinutes);
+    return {
+        totalMinutes,
+        humanMinutes: Math.min(humanMinutes, totalMinutes),
+        aiSoloMinutes: Math.max(0, totalMinutes - humanMinutes),
+        promptCount: promptTimes.length,
+    };
+}
+/** Local-date key (YYYY-MM-DD) for a UTC timestamp at the given offset. */
+export function dayKey(tsMs, tzOffsetHours) {
+    return new Date(tsMs + tzOffsetHours * 3600_000).toISOString().slice(0, 10);
+}
+/** Local-hour key (YYYY-MM-DD HH:00) for a UTC timestamp at the given offset. */
+export function hourKey(tsMs, tzOffsetHours) {
+    return (new Date(tsMs + tzOffsetHours * 3600_000).toISOString().slice(0, 13).replace("T", " ") +
+        ":00");
+}
+/**
+ * Three-state model (replaces the binary inter-prompt heuristic, which counts
+ * Claude-working time inside prompt windows as fully human):
+ *
+ * Per prompt-to-prompt window, capped at promptCapMinutes (same cap semantics
+ * as the old heuristic, so the old number stays a true upper bound):
+ *
+ * 1. hands-on  — the reaction tail: time between the last event of any kind
+ *    and the next prompt. The human provably read/thought/typed then.
+ * 2. supervised — the agent-working part of the capped window, weighted by
+ *    watch evidence: reaction < 30 s ⇒ they were watching ⇒ 100 %, < 5 min ⇒
+ *    50 %, else 0 %. Hard presence proof inside the window (message typed
+ *    mid-turn, external file edit) forces 100 %.
+ * 3. AI autonomous — total minus the two above.
+ *
+ * Invariant: handsOn + supervised <= upperBound (old heuristic) <= total.
+ * A fast reaction proves presence at the END of a window, not throughout —
+ * capping supervision at the prompt-cap window encodes exactly that.
+ */
+export function computeRefinedSplit(merged, opts) {
+    const WATCH_FULL = opts.watchFullMinutes ?? 0.5;
+    const WATCH_HALF = opts.watchHalfMinutes ?? 5;
+    const n = merged.length;
+    const promptIdx = [];
+    for (let i = 0; i < n; i++)
+        if (merged[i].kind === "prompt")
+            promptIdx.push(i);
+    // Pass 1: totals per hour over the full event timeline.
+    let total = 0;
+    const byHour = new Map();
+    const hourOf = (tsMs) => hourKey(tsMs, opts.tzOffsetHours);
+    const bucket = (key) => {
+        let b = byHour.get(key);
+        if (!b) {
+            b = { total: 0, handsOn: 0, supervised: 0, ai: 0 };
+            byHour.set(key, b);
+        }
+        return b;
+    };
+    for (let i = 1; i < n; i++) {
+        const capped = Math.min((merged[i].ts - merged[i - 1].ts) / 60000, opts.capMinutes);
+        total += capped;
+        bucket(hourOf(merged[i - 1].ts)).total += capped;
+    }
+    // Pass 2: human states per prompt-to-prompt segment.
+    let handsOn = 0;
+    let supervised = 0;
+    for (let k = 1; k < promptIdx.length; k++) {
+        const p1 = promptIdx[k - 1];
+        const p2 = promptIdx[k];
+        const windowMin = (merged[p2].ts - merged[p1].ts) / 60000;
+        const cappedWindow = Math.min(windowMin, opts.promptCapMinutes);
+        const reactionMin = (merged[p2].ts - merged[p2 - 1].ts) / 60000;
+        const tail = Math.min(reactionMin, cappedWindow);
+        const agentPart = cappedWindow - tail;
+        let proof = false;
+        for (let j = p2 - 1; j > p1; j--) {
+            if (merged[j].presence) {
+                proof = true;
+                break;
+            }
+        }
+        let w = 0;
+        if (proof || reactionMin <= WATCH_FULL)
+            w = 1;
+        else if (reactionMin <= WATCH_HALF)
+            w = 0.5;
+        const sup = agentPart * w;
+        handsOn += tail;
+        supervised += sup;
+        // Hour attribution: tail to the hour of the tail gap's start; supervised
+        // distributed over the segment's work gaps proportionally to capped time.
+        bucket(hourOf(merged[p2 - 1].ts)).handsOn += tail;
+        if (sup > 0) {
+            let denom = 0;
+            for (let i = p1 + 1; i < p2; i++) {
+                denom += Math.min((merged[i].ts - merged[i - 1].ts) / 60000, opts.capMinutes);
+            }
+            if (denom > 0) {
+                for (let i = p1 + 1; i < p2; i++) {
+                    const g = Math.min((merged[i].ts - merged[i - 1].ts) / 60000, opts.capMinutes);
+                    bucket(hourOf(merged[i - 1].ts)).supervised += (sup * g) / denom;
+                }
+            }
+            else {
+                bucket(hourOf(merged[p1].ts)).supervised += sup;
+            }
+        }
+    }
+    for (const b of byHour.values()) {
+        b.ai = Math.max(0, b.total - b.handsOn - b.supervised);
+    }
+    const promptTimes = promptIdx.map((i) => merged[i].ts);
+    const upperBound = Math.min(activeMinutes(promptTimes, opts.promptCapMinutes), total);
+    const attention = handsOn + supervised;
+    return {
+        totalMinutes: total,
+        handsOnMinutes: handsOn,
+        supervisedMinutes: supervised,
+        attentionMinutes: attention,
+        upperBoundMinutes: upperBound,
+        aiAutonomousMinutes: total - attention,
+        promptCount: promptIdx.length,
+        byHour,
+    };
+}
+/**
+ * Per-day capped minutes. Each gap is attributed to the day of its EARLIER
+ * event (same convention as the Python reference's --by-day and --csv).
+ */
+export function bucketMinutesByDay(timesMs, capMinutes, tzOffsetHours) {
+    const days = new Map();
+    for (let i = 1; i < timesMs.length; i++) {
+        const gap = Math.min((timesMs[i] - timesMs[i - 1]) / 60000, capMinutes);
+        const day = dayKey(timesMs[i - 1], tzOffsetHours);
+        days.set(day, (days.get(day) ?? 0) + gap);
+    }
+    return days;
+}
+export function countByDay(timesMs, tzOffsetHours) {
+    const days = new Map();
+    for (const t of timesMs) {
+        const day = dayKey(t, tzOffsetHours);
+        days.set(day, (days.get(day) ?? 0) + 1);
+    }
+    return days;
+}
+/**
+ * Parses YYYY-MM-DD, "YYYY-MM-DD HH:MM[:SS]" or an ISO timestamp — all
+ * interpreted as UTC (same contract as the Python reference).
+ */
+export function parseDate(s) {
+    if (s.includes("T")) {
+        const ts = Date.parse(s);
+        if (Number.isNaN(ts))
+            throw new Error(`Cannot parse date '${s}'`);
+        return ts;
+    }
+    let iso;
+    if (s.includes(" ")) {
+        const m = s.match(/^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2})(:\d{2})?$/);
+        if (!m)
+            throw new Error(`Cannot parse date '${s}' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM)`);
+        iso = `${m[1]}T${m[2]}${m[3] ?? ":00"}Z`;
+    }
+    else {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+            throw new Error(`Cannot parse date '${s}' (expected YYYY-MM-DD)`);
+        }
+        iso = `${s}T00:00:00Z`;
+    }
+    const ts = Date.parse(iso);
+    if (Number.isNaN(ts))
+        throw new Error(`Cannot parse date '${s}'`);
+    return ts;
+}

package/dist/install.js

@@ -0,0 +1,84 @@
+/**
+ * `agent-hours install` — headroom-style one-shot integration.
+ *
+ * Drops a SKILL.md into the agents' skill directories so users can simply
+ * ask their agent "what did I work on this week?" and it knows to run this
+ * CLI and interpret the numbers. Idempotent; overwrites our own skill file
+ * only.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+export const SKILL_MD = `---
+name: agent-hours
+description: Billable hours and worklog from coding-agent session logs (Claude Code + Codex, merged). Use when the user asks "how many hours", "what did I work on", "time tracking", "billing", "invoice summary", "Stunden", "woran habe ich gearbeitet", "Arbeitszeit", "Abrechnung", or wants a per-hour/per-day work summary for a period.
+---
+
+# agent-hours
+
+Answer time-tracking and what-was-done questions by running the agent-hours
+CLI (reads local session logs retroactively — zero setup) and interpreting
+its output. Run it from the project directory the user asks about.
+
+## Commands
+
+\`\`\`bash
+npx agent-hours --json                          # full three-state split, machine-readable
+npx agent-hours --worklog --csv --by-day        # per-day: hours per state + description
+npx agent-hours --worklog --csv                 # per-hour variant
+npx agent-hours --json --since 2026-06-01 --until 2026-06-30
+npx agent-hours --all-projects --split          # everything on this machine
+\`\`\`
+
+## How to answer
+
+1. **"How many hours did I work?"** — run \`--json\`. Present the BAND, never a
+   single number as truth: hands-on hours (provable lower bound), attention
+   hours (model estimate incl. supervised agent time), upper bound. Mention
+   total agent runtime separately.
+2. **"What did I work on?"** — run \`--worklog --csv --by-day\` (or per-hour for
+   one day) and summarize the description column in your own words, grouped
+   by theme. This is free — do NOT pass --summarize unless the user asks.
+3. **Invoice/billing export** — write the CSV to ~/Downloads and remind the
+   user: browser/call time is not in the logs, add 15–25 % on top.
+
+## Notes
+
+- Sources are merged into ONE timeline (Claude Code + Codex; parallel agents
+  and agent-launched agents never double-count).
+- Claude Code prunes logs after cleanupPeriodDays (default 30) — if a range
+  looks empty, say so and recommend raising it in ~/.claude/settings.json.
+- Idle-cap methodology: gaps between events capped at 10 min (configurable
+  via --cap/--prompt-cap).
+`;
+function installSkillFile(skillDir) {
+    const target = path.join(skillDir, "agent-hours", "SKILL.md");
+    const existed = fs.existsSync(target);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, SKILL_MD);
+    return { target: skillDir, path: target, status: existed ? "updated" : "installed" };
+}
+/**
+ * Installs the skill for the requested agents. `homeDir` is overridable for
+ * tests. Codex is skipped (not failed) when ~/.codex doesn't exist.
+ */
+export function runInstall(agent, homeDir = os.homedir()) {
+    const results = [];
+    if (agent === "claude" || agent === "all") {
+        results.push(installSkillFile(path.join(homeDir, ".claude", "skills")));
+    }
+    if (agent === "codex" || agent === "all") {
+        if (fs.existsSync(path.join(homeDir, ".codex"))) {
+            results.push(installSkillFile(path.join(homeDir, ".codex", "skills")));
+        }
+        else {
+            results.push({
+                target: path.join(homeDir, ".codex"),
+                path: "",
+                status: "skipped",
+                reason: "~/.codex not found (Codex CLI not installed)",
+            });
+        }
+    }
+    return results;
+}

package/dist/sources/codex.js

@@ -0,0 +1,145 @@
+/**
+ * Codex CLI source adapter.
+ *
+ * Codex stores sessions in ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl.
+ * Every line has a top-level ISO `timestamp`; the first line is a
+ * `session_meta` record carrying `payload.cwd` (project matching) and
+ * `payload.source` ("exec" = non-interactive run launched by a script or
+ * another agent — its "user" messages are machine-authored, so the whole
+ * session counts as AI runtime; "tui"/IDE sessions have real human prompts).
+ *
+ * Verified against real logs 2026-06-12 (Codex CLI 0.135/0.139).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+export const CODEX_SESSIONS_BASE = path.join(os.homedir(), ".codex", "sessions");
+function walkJsonl(dir, out = []) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory())
+            walkJsonl(p, out);
+        else if (e.isFile() && e.name.endsWith(".jsonl"))
+            out.push(p);
+    }
+    return out;
+}
+/**
+ * Cheap header check: only the first line is needed to match the project.
+ * The session_meta line can be huge (it embeds the agent's base instructions),
+ * so read in growing chunks until the first newline appears.
+ */
+function readMeta(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const CHUNK = 65536;
+        const MAX = 4 * 1024 * 1024;
+        let data = Buffer.alloc(0);
+        let pos = 0;
+        let nl = -1;
+        while (nl < 0 && pos < MAX) {
+            const buf = Buffer.alloc(CHUNK);
+            const n = fs.readSync(fd, buf, 0, CHUNK, pos);
+            if (n <= 0)
+                break;
+            data = Buffer.concat([data, buf.subarray(0, n)]);
+            pos += n;
+            nl = data.indexOf(0x0a);
+        }
+        const firstLine = (nl >= 0 ? data.subarray(0, nl) : data).toString("utf8");
+        const rec = JSON.parse(firstLine);
+        if (rec["type"] !== "session_meta")
+            return null;
+        const payload = (rec["payload"] ?? {});
+        return {
+            cwd: typeof payload["cwd"] === "string" ? payload["cwd"] : null,
+            interactive: payload["source"] !== "exec",
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function parseEvents(file, sinceMs, untilMs, interactive) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        let r;
+        try {
+            r = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const tsStr = r["timestamp"];
+        if (typeof tsStr !== "string")
+            continue;
+        const ts = Date.parse(tsStr);
+        if (Number.isNaN(ts) || ts < sinceMs || ts > untilMs)
+            continue;
+        let kind = "work";
+        let presence = false;
+        if (interactive && r["type"] === "response_item") {
+            const p = (r["payload"] ?? {});
+            if (p["type"] === "message" && p["role"] === "user") {
+                const content = p["content"];
+                const text = Array.isArray(content)
+                    ? content.find((c) => c && typeof c === "object" && c["type"] === "input_text")?.["text"]
+                    : undefined;
+                // Codex injects environment/permission context as user-role messages
+                // wrapped in <tags> — those are not human.
+                if (typeof text === "string" && !text.trimStart().startsWith("<")) {
+                    kind = "prompt";
+                    presence = true;
+                }
+            }
+        }
+        events.push({ ts, kind, presence });
+    }
+    events.sort((a, b) => a.ts - b.ts);
+    return events;
+}
+/**
+ * Loads all Codex sessions whose cwd is the project path (or inside it).
+ * Session names are prefixed "codex:" for --by-session readability.
+ */
+export function loadCodexSessions(projectPath, sinceMs, untilMs, baseDir = CODEX_SESSIONS_BASE) {
+    const project = path.resolve(projectPath);
+    const sessions = [];
+    for (const file of walkJsonl(baseDir).sort()) {
+        const meta = readMeta(file);
+        if (!meta || !meta.cwd)
+            continue;
+        if (meta.cwd !== project && !meta.cwd.startsWith(project + path.sep))
+            continue;
+        const events = parseEvents(file, sinceMs, untilMs, meta.interactive);
+        if (events.length > 0) {
+            sessions.push({ name: `codex:${path.relative(baseDir, file)}`, events });
+        }
+    }
+    return sessions;
+}