diff --git a/src/lib/local-api.js b/src/lib/local-api.js
index bdebba3..1b4133a 100644
--- a/src/lib/local-api.js
+++ b/src/lib/local-api.js
@@ -377,6 +377,67 @@ function aggregateHourlyByDay(rows, dayKey, timeZoneContext) {
return Array.from(byHour.values()).sort((a, b) => a.hour.localeCompare(b.hour));
}
+function buildChangeTimeline({ rows, projectRows, configMtime }) {
+ const events = [];
+ const seenSources = new Map();
+ const seenModels = new Map();
+
+ for (const row of rows) {
+ const when = typeof row?.hour_start === "string" ? row.hour_start : null;
+ if (!when) continue;
+ const source = typeof row?.source === "string" ? row.source : null;
+ const model = typeof row?.model === "string" ? row.model : null;
+
+ if (source && !seenSources.has(source)) {
+ seenSources.set(source, when);
+ }
+ if (model && !seenModels.has(model)) {
+ seenModels.set(model, when);
+ }
+ }
+
+ for (const [source, when] of seenSources.entries()) {
+ events.push({
+ date: when.slice(0, 10),
+ event_type: "source_first_seen",
+ params: { source },
+ });
+ }
+
+ for (const [model, when] of Array.from(seenModels.entries()).slice(0, 8)) {
+ events.push({
+ date: when.slice(0, 10),
+ event_type: "model_first_seen",
+ params: { model },
+ });
+ }
+
+ if (projectRows.length > 0) {
+ const firstProjectRow = projectRows
+ .filter((row) => typeof row?.hour_start === "string")
+ .sort((a, b) => String(a.hour_start).localeCompare(String(b.hour_start)))[0];
+ if (firstProjectRow?.hour_start) {
+ events.push({
+ date: firstProjectRow.hour_start.slice(0, 10),
+ event_type: "project_attribution_started",
+ params: {},
+ });
+ }
+ }
+
+ if (configMtime) {
+ events.push({
+ date: configMtime.slice(0, 10),
+ event_type: "cloud_sync_configured",
+ params: {},
+ });
+ }
+
+ return events
+ .sort((a, b) => String(a.date).localeCompare(String(b.date)))
+ .slice(-12);
+}
+
// ---------------------------------------------------------------------------
// Sync helper
// ---------------------------------------------------------------------------
@@ -1153,6 +1214,20 @@ function createLocalApiHandler({ queuePath }) {
return true;
}
+ if (p === "/functions/tokentracker-change-timeline") {
+ const rows = readQueueData(qp);
+ const projectQueuePath = path.join(path.dirname(qp), "project.queue.jsonl");
+ const projectRows = readProjectQueueData(projectQueuePath);
+ const configPath = path.join(os.homedir(), ".tokentracker", "tracker", "config.json");
+ const configStat = fs.statSync(configPath, { throwIfNoEntry: false });
+ const configMtime = configStat?.mtime ? new Date(configStat.mtime).toISOString() : null;
+ json(res, {
+ generated_at: new Date().toISOString(),
+ events: buildChangeTimeline({ rows, projectRows, configMtime }),
+ });
+ return true;
+ }
+
// --- user-status (stub) ---
if (p === "/functions/tokentracker-user-status") {
json(res, {
diff --git a/test/change-timeline.test.js b/test/change-timeline.test.js
new file mode 100644
index 0000000..78c2d3c
--- /dev/null
+++ b/test/change-timeline.test.js
@@ -0,0 +1,96 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+const { test } = require("node:test");
+
+const { createLocalApiHandler } = require("../src/lib/local-api");
+
+function createRequest({ method = "GET", headers = {} } = {}) {
+ return {
+ method,
+ headers,
+ async *[Symbol.asyncIterator]() {},
+ };
+}
+
+function createResponse() {
+ return {
+ statusCode: null,
+ headers: null,
+ body: Buffer.alloc(0),
+ writeHead(statusCode, headers) {
+ this.statusCode = statusCode;
+ this.headers = headers;
+ },
+ end(chunk) {
+ this.body = chunk ? Buffer.from(chunk) : Buffer.alloc(0);
+ },
+ };
+}
+
+test("local timeline endpoint reports source, model, project, and config events", async () => {
+ const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "tokentracker-timeline-"));
+ const prevHome = process.env.HOME;
+ try {
+ process.env.HOME = tmp;
+ const trackerDir = path.join(tmp, ".tokentracker", "tracker");
+ await fs.mkdir(trackerDir, { recursive: true });
+ const queuePath = path.join(trackerDir, "queue.jsonl");
+ const projectQueuePath = path.join(trackerDir, "project.queue.jsonl");
+ const configPath = path.join(trackerDir, "config.json");
+
+ await fs.writeFile(
+ queuePath,
+ [
+ JSON.stringify({ source: "codex", model: "gpt-5.4", hour_start: "2026-04-18T00:00:00.000Z" }),
+ JSON.stringify({ source: "gemini", model: "gemini-2.5-pro", hour_start: "2026-04-20T00:00:00.000Z" }),
+ ].join("\n"),
+ "utf8",
+ );
+ await fs.writeFile(
+ projectQueuePath,
+ JSON.stringify({ project_key: "octo/api", source: "codex", hour_start: "2026-04-21T00:00:00.000Z" }),
+ "utf8",
+ );
+ await fs.writeFile(configPath, JSON.stringify({ baseUrl: "https://example.invalid", deviceToken: "token" }), "utf8");
+
+ const handler = createLocalApiHandler({ queuePath });
+ const req = createRequest();
+ const res = createResponse();
+
+ const handled = await handler(req, res, new URL("http://127.0.0.1/functions/tokentracker-change-timeline"));
+
+ assert.equal(handled, true);
+ assert.equal(res.statusCode, 200);
+ const payload = JSON.parse(res.body.toString("utf8"));
+ for (const event of payload.events) {
+ assert.ok(typeof event.event_type === "string", "event_type is a string");
+ assert.ok(event.params !== null && typeof event.params === "object", "params is an object");
+ assert.equal(event.title, undefined, "API must not embed pre-rendered titles");
+ assert.equal(event.detail, undefined, "API must not embed pre-rendered details");
+ }
+ const sourceEvents = payload.events.filter((e) => e.event_type === "source_first_seen");
+ assert.deepEqual(
+ sourceEvents.map((e) => e.params.source).sort(),
+ ["codex", "gemini"],
+ );
+ const modelEvents = payload.events.filter((e) => e.event_type === "model_first_seen");
+ assert.ok(modelEvents.some((e) => e.params.model === "gpt-5.4"));
+ assert.ok(payload.events.some((e) => e.event_type === "project_attribution_started"));
+ assert.ok(payload.events.some((e) => e.event_type === "cloud_sync_configured"));
+ } finally {
+ if (prevHome === undefined) delete process.env.HOME;
+ else process.env.HOME = prevHome;
+ await fs.rm(tmp, { recursive: true, force: true });
+ }
+});
+
+test("dashboard wires the change timeline card", () => {
+ const dashboardSrc = require("node:fs").readFileSync(
+ path.join(process.cwd(), "dashboard/src/ui/matrix-a/views/DashboardView.jsx"),
+ "utf8",
+ );
+ assert.match(dashboardSrc, /ChangeTimelineCard/);
+ assert.match(dashboardSrc, /changeTimelineEvents/);
+});