tokentrace 0.8.4 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to TokenTrace are documented here.
 
+## [0.9.0] - 2026-05-13
+
+### Added
+
+- Session Timeline pages for inspecting one imported CLI session as ordered interactions, model changes, token spikes, cache activity, tool calls, parser confidence, and unknown-cost events without exposing raw message bodies.
+- Saved Local Views on Sessions, with built-in local filters for unknown cost, high-cost sessions, Claude/Codex this month, estimated tokens, guardrail review, and parser review, plus user-created SQLite-backed views.
+- `tokentrace digest --since <last-scan|yesterday|YYYY-MM-DD>` for scoped local usage digests.
+- `tokentrace report --markdown` and `tokentrace review --json` for deterministic local summaries covering digest data, post-session movement, accounting state, parser warnings, and expensive sessions.
+- Overview Post-Session Review panel showing latest scan movement, unknown costs, parser follow-up, guardrail state, and expensive sessions.
+- Accounting invariant checks that verify processed tokens balance against fresh input, output, reasoning, and cache buckets.
+
+### Changed
+
+- Claude status line output now includes context-window usage when Claude provides it and distinguishes priced sessions from pricing-repair states.
+- Overview Data Readiness now includes token-bucket balance and keeps readiness tiles readable at normal desktop widths.
+
 ## [0.8.4] - 2026-05-13
 
 ### Changed

package/README.md

@@ -43,6 +43,12 @@ tokentrace repair --json
                         # Print unknown-cost repair groups as JSON
 tokentrace digest --json
                         # Print current-month local usage digest
+tokentrace digest --since yesterday
+                        # Print a scoped local usage digest
+tokentrace report --markdown
+                        # Print a deterministic Markdown report
+tokentrace review --json
+                        # Print post-session scan and review movement
 tokentrace insights --json
                         # Print local recommendations as JSON
 tokentrace status --json
@@ -139,6 +145,13 @@ Settings also supports optional local monthly usage guardrails. Set a cost
 limit, token limit, or both, and Overview will show month-to-date progress from
 imported local CLI usage.
 
+Sessions includes built-in and local saved views for recurring review paths:
+unknown cost, high-cost sessions, Claude/Codex this month, estimated tokens,
+guardrail review, and parser review. Open a session's **Timeline** link to see
+ordered interactions, model changes, token spikes, cache activity, tool calls,
+parser confidence, and unknown-cost events. Raw prompts and message bodies stay
+hidden by default.
+
 ## Ingestion Architecture
 
 TokenTrace's primary ingestion architecture is direct local filesystem ingestion:
@@ -188,6 +201,10 @@ tokentrace statusline claude
 
 Claude Code sends session JSON to the command on stdin. TokenTrace reads the transcript path, model, context usage, and session cost, then prints one compact local line:
 
+```text
+TokenTrace | Opus | session 3.3K tokens | cache 2.0K | cost $0.1235 | ctx 7% | priced
+```
+
 Do not set the Claude Code `statusLine.command` to plain `tokentrace`. Plain `tokentrace` starts the dashboard, while `tokentrace statusline claude` prints exactly one status-line response.
 
 ![TokenTrace Claude Code status line](docs/assets/claude-statusline.svg)
@@ -199,6 +216,15 @@ tokentrace status --json
 tokentrace watch --session
 ```
 
+Daily reporting commands stay deterministic and local:
+
+```bash
+tokentrace digest --since last-scan
+tokentrace digest --since 2026-05-01 --json
+tokentrace report --markdown --since yesterday
+tokentrace review --json
+```
+
 Codex CLI status-line integration is intentionally deferred until its status-line and hook contracts are stable enough to support without fragile terminal output parsing. Use `tokentrace watch --session --compact` in a terminal split or tmux pane as the current fallback. See [docs/CODEX_INTEGRATION_SPIKE.md](docs/CODEX_INTEGRATION_SPIKE.md) for the current decision.
 
 ## Screenshots

package/app/api/saved-views/[id]/route.ts

@@ -0,0 +1,16 @@
+import { NextResponse } from "next/server";
+import { deleteSavedView } from "@/src/lib/saved-views";
+
+export const dynamic = "force-dynamic";
+
+export async function DELETE(
+  _request: Request,
+  {
+    params
+  }: {
+    params: Promise<{ id: string }>;
+  }
+) {
+  const { id } = await params;
+  return NextResponse.json({ deleted: deleteSavedView(decodeURIComponent(id)) });
+}

package/app/api/saved-views/route.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from "next/server";
+import { readJsonObject } from "@/src/lib/api-json";
+import { getSavedViews, saveSavedView } from "@/src/lib/saved-views";
+
+export const dynamic = "force-dynamic";
+
+function object(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export async function GET() {
+  return NextResponse.json(getSavedViews());
+}
+
+export async function POST(request: Request) {
+  const parsed = await readJsonObject(request);
+  if (!parsed.ok) {
+    return NextResponse.json({ error: parsed.error }, { status: 400 });
+  }
+
+  try {
+    const view = saveSavedView({
+      name: typeof parsed.body.name === "string" ? parsed.body.name : "",
+      filters: object(parsed.body.filters)
+    });
+    return NextResponse.json({ view });
+  } catch (error) {
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : "could not save view" },
+      { status: 400 }
+    );
+  }
+}

package/app/page.tsx

@@ -10,6 +10,7 @@ import { HelpTooltip } from "@/components/ui/help-tooltip";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
 import { DataValue, FieldLabel, MonoText, PageHeader } from "@/components/ui/typography";
 import { getAnalyticsData, getScanTrustData } from "@/src/lib/analytics";
+import { buildAccountingInvariants, type AccountingInvariantReport } from "@/src/lib/accounting-invariants";
 import { buildDoctorReport, type DoctorReport } from "@/src/lib/doctor";
 import { getDefaultSearchRoots } from "@/src/ingestion/discovery";
 import { buildFirstRunStatus, type FirstRunStatus } from "@/src/lib/first-run-status";
@@ -18,6 +19,8 @@ import { dateRangeQueryParams, mergeHrefParams, resolveDateRange } from "@/src/l
 import { formatCurrency, formatSignedTokens, formatTokens, percent } from "@/src/lib/format";
 import { cn } from "@/src/lib/utils";
 import type { UsageGuardrailMetric } from "@/src/lib/usage-guardrails";
+import { buildScanDiff } from "@/src/lib/scan-diff";
+import { buildPostSessionReview, type PostSessionReview } from "@/src/lib/post-session-review";
 
 export const dynamic = "force-dynamic";
 
@@ -358,12 +361,14 @@ function readinessVariant(state: "ready" | "review" | "blocked") {
 
 function DataReadinessPanel({
   report,
+  accountingReport,
   selectedInteractions,
   selectedCachedTokens,
   repairHref,
   cachedEvidenceHref
 }: {
   report: DoctorReport;
+  accountingReport: AccountingInvariantReport;
   selectedInteractions: number;
   selectedCachedTokens: number;
   repairHref: string;
@@ -401,6 +406,17 @@ function DataReadinessPanel({
       state: selectedCachedTokens > 0 ? "ready" as const : "review" as const,
       href: cachedEvidenceHref
     },
+    {
+      label: "Token buckets",
+      value: accountingReport.balanceDeltaTokens === 0
+        ? "Balanced"
+        : `${formatTokens(Math.abs(accountingReport.balanceDeltaTokens))} delta`,
+      detail: accountingReport.balanceDeltaTokens === 0
+        ? "Processed tokens equal fresh input, output, reasoning, and cache buckets."
+        : "Some processed tokens are outside the visible buckets and need parser review.",
+      state: accountingReport.status === "ready" ? "ready" as const : "review" as const,
+      href: "/evidence?metric=processed-tokens"
+    },
     {
       label: "Boundaries",
       value: `${report.supportMatrix.summary.stable} stable, ${report.supportMatrix.summary.bestEffort} best effort`,
@@ -417,7 +433,7 @@ function DataReadinessPanel({
         <CardDescription>Current trust checks before acting on cost, token, parser, or cache numbers.</CardDescription>
       </CardHeader>
       <CardContent className="p-0">
-        <div className="grid border-t md:grid-cols-2 xl:grid-cols-5">
+        <div className="grid border-t md:grid-cols-2 xl:grid-cols-3 2xl:grid-cols-6">
           {items.map((item, index) => (
             <Link
               key={item.label}
@@ -441,6 +457,84 @@ function DataReadinessPanel({
   );
 }
 
+function PostSessionReviewPanel({ review }: { review: PostSessionReview }) {
+  return (
+    <Card>
+      <CardHeader className="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between">
+        <div>
+          <CardTitle>Post-Session Review</CardTitle>
+          <CardDescription>Latest scan movement, guardrail state, pricing gaps, parser warnings, and expensive sessions.</CardDescription>
+        </div>
+        <Badge variant={review.newlyImportedRecords > 0 ? "success" : "secondary"}>{review.headline}</Badge>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="grid border-y md:grid-cols-4 md:divide-x">
+          <div className="p-3">
+            <FieldLabel>Imported records</FieldLabel>
+            <DataValue className="mt-1">{review.newlyImportedRecords.toLocaleString()}</DataValue>
+          </div>
+          <div className="p-3">
+            <FieldLabel>Unknown cost</FieldLabel>
+            <DataValue className="mt-1">{review.unknownCostInteractions.toLocaleString()}</DataValue>
+          </div>
+          <div className="p-3">
+            <FieldLabel>Parser warnings</FieldLabel>
+            <DataValue className="mt-1">{review.parserWarnings.toLocaleString()}</DataValue>
+          </div>
+          <div className="p-3">
+            <FieldLabel>Token guardrail</FieldLabel>
+            <DataValue className="mt-1">{percent(review.guardrails.tokens.percent)}</DataValue>
+          </div>
+        </div>
+        <div className="grid gap-3 lg:grid-cols-2">
+          <div>
+            <h3 className="text-sm font-semibold">Expensive Sessions</h3>
+            <div className="mt-2 divide-y rounded-md border">
+              {review.expensiveSessions.slice(0, 3).map((session) => (
+                <Link
+                  key={session.id}
+                  href={session.href}
+                  className="flex min-w-0 items-center justify-between gap-3 p-3 text-sm transition-colors hover:bg-muted/40"
+                >
+                  <span className="min-w-0">
+                    <span className="block truncate font-medium">{session.title}</span>
+                    <span className="text-xs text-muted-foreground">{session.tool} / {session.models}</span>
+                  </span>
+                  <span className="shrink-0 text-right tabular-nums">
+                    <span className="block">{formatCurrency(session.cost)}</span>
+                    <span className="text-xs text-muted-foreground">{formatTokens(session.totalTokens)}</span>
+                  </span>
+                </Link>
+              ))}
+              {!review.expensiveSessions.length ? (
+                <div className="p-3 text-sm text-muted-foreground">No priced or token-heavy sessions yet.</div>
+              ) : null}
+            </div>
+          </div>
+          <div>
+            <h3 className="text-sm font-semibold">Parser Follow-Up</h3>
+            <div className="mt-2 divide-y rounded-md border">
+              {review.parserWarningSources.slice(0, 3).map((source) => (
+                <Link
+                  key={source.sourceFile}
+                  href={source.href}
+                  className="block min-w-0 p-3 text-sm transition-colors hover:bg-muted/40"
+                >
+                  <span className="font-medium">{source.parserStatus}</span>
+                  <MonoText className="mt-1 block truncate">{source.sourceFile}</MonoText>
+                </Link>
+              ))}
+              {!review.parserWarningSources.length ? (
+                <div className="p-3 text-sm text-muted-foreground">No parser follow-up from the current session set.</div>
+              ) : null}
+            </div>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
 type OverviewPageProps = {
   searchParams?: Promise<Record<string, string | string[] | undefined>>;
 };
@@ -449,6 +543,13 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
   const params = (await searchParams) ?? {};
   const range = resolveDateRange(params);
   const data = getAnalyticsData(range.filters);
+  const accountingReport = buildAccountingInvariants(range.filters);
+  const postSessionReview = buildPostSessionReview({
+    scanDiff: buildScanDiff(),
+    usageGuardrails: data.usageGuardrails,
+    summary: data.summary,
+    sessions: data.sessions
+  });
   const rangeLinkParams = dateRangeQueryParams(range);
   const evidenceLinks = Object.fromEntries(
     Object.entries(data.evidenceLinks).map(([key, href]) => [key, mergeHrefParams(href, rangeLinkParams)])
@@ -646,6 +747,7 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
       {summary.interactions > 0 ? (
         <DataReadinessPanel
           report={doctorReport}
+          accountingReport={accountingReport}
           selectedInteractions={summary.interactions}
           selectedCachedTokens={summary.cachedTokens}
           repairHref={repairFocusHref}
@@ -653,6 +755,8 @@ export default async function OverviewPage({ searchParams }: OverviewPageProps)
         />
       ) : null}
 
+      {summary.interactions > 0 ? <PostSessionReviewPanel review={postSessionReview} /> : null}
+
       <UsageGuardrailsPanel progress={data.usageGuardrails} />
 
       <Card>

package/app/sessions/[id]/page.tsx

@@ -0,0 +1,202 @@
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { ArrowLeft, Database, Layers, MessageSquare, ShieldCheck, Terminal } from "lucide-react";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
+import { DataValue, FieldLabel, MonoText, PageHeader } from "@/components/ui/typography";
+import { buildSessionTimeline, type SessionTimelineEventKind } from "@/src/lib/session-timeline";
+import { formatCurrency, formatDate, formatDuration, formatTokens } from "@/src/lib/format";
+
+export const dynamic = "force-dynamic";
+
+function eventVariant(kind: SessionTimelineEventKind) {
+  if (kind === "unknown-cost") return "destructive";
+  if (kind === "token-spike" || kind === "model-change") return "warning";
+  if (kind === "cache") return "success";
+  return "secondary";
+}
+
+function eventLabel(kind: SessionTimelineEventKind) {
+  return kind.replace(/-/g, " ");
+}
+
+function SummaryTile({
+  label,
+  value,
+  detail,
+  icon: Icon
+}: {
+  label: string;
+  value: string;
+  detail: string;
+  icon: typeof Database;
+}) {
+  return (
+    <Card>
+      <CardContent className="flex min-w-0 items-start gap-3 p-4">
+        <span className="mt-0.5 inline-flex h-9 w-9 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+          <Icon className="h-4 w-4" aria-hidden="true" />
+        </span>
+        <div className="min-w-0">
+          <FieldLabel>{label}</FieldLabel>
+          <DataValue className="mt-1 text-2xl">{value}</DataValue>
+          <div className="mt-1 text-xs text-muted-foreground">{detail}</div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+export default async function SessionTimelinePage({
+  params
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  const timeline = buildSessionTimeline(decodeURIComponent(id));
+  if (!timeline) notFound();
+
+  const sessionHref = `/sessions?source=${encodeURIComponent(timeline.session.sourceFile)}`;
+  const durationMs =
+    timeline.session.startedAt != null && timeline.session.endedAt != null
+      ? timeline.session.endedAt - timeline.session.startedAt
+      : null;
+
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title={timeline.session.title ?? "Session timeline"}
+        description={`${timeline.session.tool} usage events for ${timeline.session.project}. Raw prompts and message bodies stay hidden in this view.`}
+        actions={
+          <Button asChild variant="outline">
+            <Link href={sessionHref}>
+              <ArrowLeft className="h-4 w-4" />
+              Back to sessions
+            </Link>
+          </Button>
+        }
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Session Context</CardTitle>
+          <CardDescription>
+            Ordered local usage evidence from imported interaction records, parser metadata, pricing state, cache buckets, and tool calls.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="grid gap-3 md:grid-cols-2 xl:grid-cols-4">
+          <div className="min-w-0">
+            <FieldLabel>Source file</FieldLabel>
+            <MonoText className="mt-1 block truncate" title={timeline.session.sourceFile}>
+              {timeline.session.sourceFile}
+            </MonoText>
+          </div>
+          <div>
+            <FieldLabel>Started</FieldLabel>
+            <div className="mt-1 text-sm font-medium">{formatDate(timeline.session.startedAt)}</div>
+          </div>
+          <div>
+            <FieldLabel>Duration</FieldLabel>
+            <div className="mt-1 text-sm font-medium">{formatDuration(durationMs)}</div>
+          </div>
+          <div>
+            <FieldLabel>Parser</FieldLabel>
+            <div className="mt-1 flex flex-wrap items-center gap-2 text-sm font-medium">
+              {timeline.summary.parser ?? "unknown"}
+              {timeline.summary.parserConfidence != null ? (
+                <Badge variant="success">{Math.round(timeline.summary.parserConfidence * 100)}%</Badge>
+              ) : null}
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-5">
+        <SummaryTile
+          label="Processed"
+          value={formatTokens(timeline.summary.totalTokens)}
+          detail={`${timeline.summary.interactions.toLocaleString()} interactions`}
+          icon={Database}
+        />
+        <SummaryTile
+          label="Cache"
+          value={formatTokens(timeline.summary.cachedTokens)}
+          detail="Read and write cache tokens"
+          icon={Layers}
+        />
+        <SummaryTile
+          label="Cost"
+          value={formatCurrency(timeline.summary.cost)}
+          detail={`${timeline.summary.unknownCostInteractions.toLocaleString()} unknown interactions`}
+          icon={ShieldCheck}
+        />
+        <SummaryTile
+          label="Models"
+          value={timeline.summary.models.length.toLocaleString()}
+          detail={timeline.summary.models.slice(0, 2).join(", ") || "No model rows"}
+          icon={MessageSquare}
+        />
+        <SummaryTile
+          label="Tool calls"
+          value={timeline.summary.toolCalls.toLocaleString()}
+          detail="Imported tool-call rows"
+          icon={Terminal}
+        />
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Timeline</CardTitle>
+          <CardDescription>Interaction rows are expanded with model changes, spikes, cache activity, unknown cost, and tool calls.</CardDescription>
+        </CardHeader>
+        <CardContent className="table-scroll">
+          <Table className="min-w-[78rem]">
+            <TableHeader>
+              <TableRow>
+                <TableHead className="w-36">Time</TableHead>
+                <TableHead className="w-32">Event</TableHead>
+                <TableHead className="w-44">Detail</TableHead>
+                <TableHead className="w-36">Model</TableHead>
+                <TableHead className="w-24">Role</TableHead>
+                <TableHead className="w-24">Tokens</TableHead>
+                <TableHead className="w-24">Cache</TableHead>
+                <TableHead className="w-24">Cost</TableHead>
+                <TableHead className="w-36">Confidence</TableHead>
+                <TableHead className="w-28">Raw</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {timeline.events.map((event) => (
+                <TableRow key={event.id}>
+                  <TableCell>{formatDate(event.timestamp)}</TableCell>
+                  <TableCell>
+                    <Badge variant={eventVariant(event.kind)}>{eventLabel(event.kind)}</Badge>
+                  </TableCell>
+                  <TableCell>
+                    <div className="font-medium">{event.title}</div>
+                    <div className="mt-1 text-xs text-muted-foreground">{event.detail}</div>
+                  </TableCell>
+                  <TableCell className="max-w-36 truncate" title={event.model ?? undefined}>{event.model ?? "unknown"}</TableCell>
+                  <TableCell>{event.role ?? "unknown"}</TableCell>
+                  <TableCell className="tabular-nums">{formatTokens(event.totalTokens)}</TableCell>
+                  <TableCell className="tabular-nums">{formatTokens(event.cachedTokens)}</TableCell>
+                  <TableCell className="tabular-nums">{formatCurrency(event.cost)}</TableCell>
+                  <TableCell>
+                    <Badge variant={event.tokenConfidence === "exact" ? "success" : event.tokenConfidence === "unknown" ? "destructive" : "warning"}>
+                      {event.tokenConfidence ?? "unknown"}
+                    </Badge>
+                  </TableCell>
+                  <TableCell className="text-xs text-muted-foreground">
+                    {event.rawTextHidden ? "Hidden" : "Visible"}
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/app/sessions/page.tsx

@@ -6,6 +6,7 @@ import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@
 import { PageHeader } from "@/components/ui/typography";
 import { getAnalyticsData } from "@/src/lib/analytics";
 import { formatCurrency, formatTokens } from "@/src/lib/format";
+import { getSavedViews } from "@/src/lib/saved-views";
 
 export const dynamic = "force-dynamic";
 
@@ -16,13 +17,19 @@ export default async function SessionsPage({
     project?: string;
     tool?: string;
     model?: string;
+    query?: string;
     source?: string;
+    exact?: "all" | "exact" | "estimated";
     cost?: "all" | "priced" | "unknown";
+    from?: string;
+    to?: string;
+    highCost?: string;
     cache?: string;
   }>;
 }) {
   const params = await searchParams;
   const data = getAnalyticsData();
+  const savedViews = getSavedViews();
   return (
     <div className="space-y-6">
       <PageHeader
@@ -84,9 +91,15 @@ export default async function SessionsPage({
         initialProject={params?.project}
         initialTool={params?.tool}
         initialModel={params?.model}
+        initialQuery={params?.query}
         initialSource={params?.source}
+        initialExact={params?.exact}
         initialCost={params?.cost}
+        initialFrom={params?.from}
+        initialTo={params?.to}
+        initialHighCost={params?.highCost === "1"}
         initialCache={params?.cache === "1"}
+        savedViews={savedViews}
       />
     </div>
   );

package/bin/tokentrace.js

@@ -32,6 +32,10 @@ Usage:
                           Print metric evidence trail as JSON
   tokentrace digest --json
                           Print current-month local usage digest
+  tokentrace report --markdown
+                          Print a deterministic local Markdown report
+  tokentrace review --json
+                          Print post-session review movement as JSON
   tokentrace insights --json
                           Print local recommendations as JSON
   tokentrace repair --json
@@ -381,6 +385,16 @@ async function digest(args) {
   await runNodeScript("digest", args);
 }
 
+async function report(args) {
+  await initializeDatabase({ quiet: true, refreshPrices: false });
+  await runNodeScript("report", args);
+}
+
+async function review(args) {
+  await initializeDatabase({ quiet: true, refreshPrices: false });
+  await runNodeScript("review", args);
+}
+
 async function insights(args) {
   await initializeDatabase({ quiet: true, refreshPrices: false });
   await runNodeScript("insights", args);
@@ -558,6 +572,14 @@ async function main() {
     await digest(args);
     return;
   }
+  if (command === "report") {
+    await report(args);
+    return;
+  }
+  if (command === "review") {
+    await review(args);
+    return;
+  }
   if (command === "insights") {
     await insights(args);
     return;