ccdeck 3.36.6 → 3.36.8

package/dist/web/index.html

@@ -64,7 +64,7 @@
           stored === "light" || (stored !== "dark" && light) ? "light" : "dark");
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-B2C4N7Bl.js"></script>
+    <script type="module" crossorigin src="/assets/index-4ecbC_Cy.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BkXTN4dZ.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccdeck",
-  "version": "3.36.6",
+  "version": "3.36.8",
   "description": "Local dashboard for Claude Code and Codex CLI sessions: which Claude Code session needs input, every tool call and Claude Code subagent live, token cost and quota, several Claude accounts. Run npx ccdeck.",
   "type": "module",
   "bin": {

package/release-notes.json

@@ -65,7 +65,9 @@
     "3.36.1",
     "3.36.4",
     "3.36.5",
-    "3.36.6"
+    "3.36.6",
+    "3.36.7",
+    "3.36.8"
   ],
   "3.36.3": [
     {

package/src/server/activation.mjs

@@ -0,0 +1,76 @@
+// Whether this deck got set up, and how long its first session took to arrive —
+// the "does a new install actually work" half of the usage reports
+// (reports.mjs).
+//
+// WHAT IT ANSWERS. An "install" event says somebody ran ccdeck once. It does not
+// say whether the Claude hooks went in, whether Codex is being watched, or
+// whether a session ever reached the deck — and an install that never sees a
+// session is somebody who tried ccdeck and left. So two facts ride on the
+// reports that carry facts:
+//
+//   - `claudeHooks`: "ok" when this boot installed the hooks, "failed" when it
+//     tried and could not (a settings.json it refuses to rewrite), "off" when it
+//     did not try (no Claude Code found, or --no-claude);
+//   - `codexWatch`: "on" when the Codex rollout watcher runs, else "off".
+//
+// and one "activated" event goes out per install, when its first session
+// arrives, saying how long after the install that was — in coarse buckets,
+// never a time.
+//
+// The boot (bin/deck.js) is what knows the setup, and it reaches this module
+// through noteSetup. This file imports nothing, so the boot can load it early.
+
+/** Not known yet, until the boot says. */
+let setup = null;
+let settle;
+const known = new Promise(r => { settle = r; });
+
+/**
+ * What the boot set up. `claude` is the hook install job — a promise of null
+ * (not attempted), `{ ok: true }` or `{ ok: false }` — or null when Claude is
+ * not wanted; `codex` is whether the rollout watcher runs. Never throws, and a
+ * job that rejects reads as "failed".
+ */
+export function noteSetup({ claude = null, codex = false } = {}) {
+  Promise.resolve(claude)
+    .then(
+      job => (job == null ? "off" : job.ok ? "ok" : "failed"),
+      () => "failed",
+    )
+    .then(claudeHooks => {
+      setup = { claudeHooks, codexWatch: codex ? "on" : "off" };
+      settle();
+    });
+}
+
+/** The setup facts, or none while the boot has not said. */
+export function setupFacts() {
+  return setup ? { ...setup } : {};
+}
+
+/** Resolves once the boot has said, or after `ms`, whichever is first — so a
+ *  report never waits on a boot that will not say (a test, a respawn). */
+export function whenSetupKnown(ms = 10_000) {
+  let timer;
+  return Promise.race([
+    known,
+    new Promise(r => { timer = setTimeout(r, ms); timer.unref?.(); }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+/** How long after the install the first session came, as a bucket: "5m" (under
+ *  five minutes), "1h", "1d", "7d", or "later". A clock that went backwards
+ *  reads as the shortest. */
+export function sinceInstallBucket(installedAt, firstAt) {
+  const ms = Date.parse(firstAt) - Date.parse(installedAt);
+  if (!Number.isFinite(ms)) return undefined;
+  if (ms < 5 * MINUTE) return "5m";
+  if (ms < HOUR) return "1h";
+  if (ms < DAY) return "1d";
+  if (ms < 7 * DAY) return "7d";
+  return "later";
+}

package/src/server/deck-prefs.mjs

@@ -93,8 +93,14 @@ export const DEFAULTS = Object.freeze({
   // not yet acknowledged, retried on the next start so switching off while
   // offline still ends in a deletion; `usage` is the day's tally of sessions,
   // subagents and projects, counts and days only, so a restart carries it on
-  // (usage-day.mjs).
-  report: Object.freeze({ installId: "", lastVersion: "", lastActiveDay: "", forget: "", usage: null }),
+  // (usage-day.mjs); `installedAt` is when the id was made, and
+  // `firstSessionAt`/`firstProvider`/`activationSent` the install's first
+  // session and whether the "activated" event saying so got through — the times
+  // stay here, only a bucket leaves (activation.mjs).
+  report: Object.freeze({
+    installId: "", lastVersion: "", lastActiveDay: "", forget: "", usage: null,
+    installedAt: "", firstSessionAt: "", firstProvider: "", activationSent: false,
+  }),
   // The accounts this deck signed in itself, and the re-sign-in prompts
   // somebody put off (#1893) — keyed by account identity, written by the deck
   // and never by a page. See account-origins.mjs.
@@ -294,8 +300,8 @@ export function normalise(raw) {
   };
 }
 
-/** The reporter's own state, coerced: four strings, empty when absent, and the
- *  day's tally, null until there is one. */
+/** The reporter's own state, coerced: strings empty when absent, the day's
+ *  tally null until there is one, and one flag. */
 function normaliseReport(raw) {
   const src = raw && typeof raw === "object" ? raw : {};
   const text = v => (typeof v === "string" ? v : "");
@@ -305,6 +311,10 @@ function normaliseReport(raw) {
     lastActiveDay: text(src.lastActiveDay),
     forget: text(src.forget),
     usage: src.usage && typeof src.usage === "object" ? normaliseUsage(src.usage) : null,
+    installedAt: text(src.installedAt),
+    firstSessionAt: text(src.firstSessionAt),
+    firstProvider: text(src.firstProvider),
+    activationSent: src.activationSent === true,
   };
 }
 

package/src/server/event-pipeline.mjs

@@ -239,6 +239,11 @@ export function pushEvent(raw, source, opts = {}) {
     } else {
       noteRefusedTranscript(raw.transcript_path);
     }
+  } else if (source === "codex" && !opts.replay) {
+    // Codex has no hooks: its sessions arrive from the rollout watcher, which
+    // emits only what a rollout gains while the deck watches. That is use too.
+    usageDay.noteUse(raw);
+    usageDay.noteFolder(raw?.cwd);
   }
 
   return evt;

package/src/server/feature-use.mjs

@@ -0,0 +1,42 @@
+// Which features got used today, for the "active" report's `features` (see
+// usage-day.mjs for the list and reports.mjs for what leaves).
+//
+// Two doors in. The page names what it saw opened — a panel shown, a dialog
+// opened — through POST /api/feature, once per name per day (feature-use.ts).
+// The server names what a request did: the routes below are actions somebody
+// takes on purpose, never something a page polls, so the request is the use.
+// Either way only a name off FEATURES is kept, and only as "used today".
+import { readBody, send } from "./http-io.mjs";
+import { usageDay } from "./usage-day.mjs";
+
+/** The requests that are a feature being used. Only actions: a read the page
+ *  makes on its own (the quota, the roster, a radio probe) says nothing about
+ *  what somebody chose to do. */
+const ROUTE_FEATURES = new Map([
+  ["POST /api/claude-accounts/switch", "account-switch"],
+  ["POST /api/claude-accounts/admin", "accounts-manage"],
+  ["POST /api/cswap-auto", "auto-switch"],
+  ["POST /api/lan/invite", "lan-pairing"],
+  ["POST /api/lan/peer", "lan-pairing"],
+  ["POST /api/feedback", "feedback-sent"],
+  ["POST /api/upgrade", "self-update"],
+  ["POST /api/clear", "clear-board"],
+]);
+
+/** Note the feature a request is, if it is one. Called for requests that got
+ *  past the deck's own gates. */
+export function noteRouteFeature(method, pathname) {
+  const name = ROUTE_FEATURES.get(`${method} ${pathname}`);
+  if (name) usageDay.noteFeature(name);
+}
+
+/** POST /api/feature — the page saying it showed or opened something.
+ *  `{ name }`; a name off the list is a 400, and nothing about it is kept. */
+export async function handleFeature(req, res) {
+  const raw = await readBody(req).catch(() => null);
+  let body = null;
+  try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
+  const name = typeof body?.name === "string" ? body.name : "";
+  if (!usageDay.noteFeature(name)) return send(res, 400, { ok: false, reason: "unknown_feature" });
+  return send(res, 200, { ok: true });
+}

package/src/server/index.mjs

@@ -63,6 +63,8 @@ import { serveStatic } from "./static-serve.mjs";
 // transcript watch between hook events, and POST /api/forget. See
 // session-tracking.mjs.
 import { handleForget, startOutputWatch } from "./session-tracking.mjs";
+// Which features were used today, for the usage reports — see feature-use.mjs.
+import { handleFeature, noteRouteFeature } from "./feature-use.mjs";
 // Exported from this file before it moved, and still.
 export { HARD_TRACKED_SESSIONS } from "./session-tracking.mjs";
 // The desktop app's update as its window sees it — the state the app reports
@@ -285,6 +287,11 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
       return send(res, 401, { error: "unauthenticated" });
     }
 
+    // A request that is somebody using a feature on purpose — switching an
+    // account, pairing a deck — counts as that feature used today. Past the
+    // gates above, so only the deck's own callers count. See feature-use.mjs.
+    noteRouteFeature(req.method, url.pathname);
+
     // `?persist=0` — another deck was elected to write this event to the log
     // the two of them share. Absent, this deck writes it.
     if (req.method === "POST" && url.pathname === "/api/event") return guard(handleEventIngest(req, res, url.searchParams.get("persist") !== "0"), res);
@@ -387,6 +394,10 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     // Above the 404 below, which is what every real route has to be.
     if (req.method === "POST" && url.pathname === "/api/forget") return guard(handleForget(req, res), res);
 
+    // POST /api/feature — the page saying it showed a panel or opened a dialog,
+    // once per name per day. A name, never what was in it. See feature-use.mjs.
+    if (req.method === "POST" && url.pathname === "/api/feature") return guard(handleFeature(req, res), res);
+
     // AN UNMATCHED /api/ PATH IS A 404, not the SPA shell.
     //
     // serveStatic falls back to index.html for a path it cannot find, which is

package/src/server/reports.mjs

@@ -13,7 +13,13 @@
 //     ccdeck gets counted without counting anything else about them, and which
 //     alone also carries coarse counts of how much: how many sessions,
 //     subagents and projects the deck heard from on the last day it was used,
-//     and that day's date — numbers, never their names (see usage-day.mjs),
+//     and that day's date — numbers, never their names (see usage-day.mjs) —
+//     and which of the deck's features were used that day, as fixed names
+//     ("usage-history", "account-switch") and nothing about what was done
+//     with them (feature-use.mjs),
+//   - an "activated" event, once, when a new install's first session arrives:
+//     how long after the install it came, as a bucket ("5m", "1h", "1d", "7d",
+//     "later"), and whether it was a Claude or a Codex session (activation.mjs),
 //   - errors: a request handler that threw on this server, or an error the page
 //     caught, with home folders, email addresses and key-shaped strings
 //     scrubbed out before they leave,
@@ -26,11 +32,14 @@
 // the channel (the desktop app, npm, or a source checkout) and the runtime, plus
 // a coarse sketch of the environment: the logical CPU count, the RAM in MB, the
 // locale, the shell and terminal names, and the Claude Code and Codex CLI
-// versions. Every one of those is a small fixed token or a number, safe by
-// construction — no path, no hostname, no user name, no project name, no prompt,
-// no free text ever reaches any field, so there is nothing in them to scrub. A
-// field that cannot be told is left out rather than guessed. The install id is
-// random, made at the first check-in, and tied to nothing on the machine.
+// versions — and, on install, update, active and activated, what the boot set
+// up: whether the Claude hooks went in ("ok", "failed", "off") and whether
+// Codex is watched ("on", "off"). Every one of those is a small fixed token or
+// a number, safe by construction — no path, no hostname, no user name, no
+// project name, no prompt, no free text ever reaches any field, so there is
+// nothing in them to scrub. A field that cannot be told is left out rather than
+// guessed. The install id is random, made at the first check-in, and tied to
+// nothing on the machine.
 //
 // The one field that IS derived from the machine is `deviceId`: a stable, hashed
 // device id sent with EVERY report — install, update and active — while reports
@@ -63,7 +72,8 @@ import { reportsVetoed } from "./deck-prefs.mjs";
 import { isGitCheckout } from "./install-layout.mjs";
 import { heldPrefs, prefsRead } from "./prefs-state.mjs";
 import { RUNNING_VERSION } from "./running-version.mjs";
-import { usageDay, utcDay } from "./usage-day.mjs";
+import { FEATURES, usageDay, utcDay } from "./usage-day.mjs";
+import { setupFacts, sinceInstallBucket, whenSetupKnown } from "./activation.mjs";
 
 export const REPORTS_API = "https://api.ccdeck.dev";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -82,7 +92,10 @@ const SAME_ERROR_QUIET_MS = 60 * 60 * 1000;
 const MESSAGE_MAX = 500;
 const STACK_MAX = 4000;
 
-const EMPTY_REPORT = Object.freeze({ installId: "", lastVersion: "", lastActiveDay: "", forget: "", usage: null });
+const EMPTY_REPORT = Object.freeze({
+  installId: "", lastVersion: "", lastActiveDay: "", forget: "", usage: null,
+  installedAt: "", firstSessionAt: "", firstProvider: "", activationSent: false,
+});
 
 /** Is this deck sending reports right now? The switch, which is on unless
  *  somebody turned it off, and the machine's consent. */
@@ -313,6 +326,10 @@ export function scrub(text, home = homedir()) {
  *   the day's tally: the "active" report carries the last finished day's totals,
  *   read only when an "active" is about to be sent, and the tally is saved into
  *   the prefs so a restart does not lose the day. Default: the deck's own.
+ * @param {() => { claudeHooks?: string, codexWatch?: string }} [deps.setup] what the
+ *   boot set up, folded into install, update and active (activation.mjs).
+ * @param {() => Promise<unknown>} [deps.setupKnown] what start() waits for besides the
+ *   prefs, so the first install event carries the setup. Bounded.
  */
 export function createReporter({
   fetchImpl = globalThis.fetch,
@@ -324,6 +341,8 @@ export function createReporter({
   ready = prefsRead,
   versions = () => ({}),
   usage = usageDay,
+  setup = setupFacts,
+  setupKnown = () => whenSetupKnown(),
 } = {}) {
   const errorsSent = [];
   const lastSentAt = new Map();
@@ -351,6 +370,20 @@ export function createReporter({
     return { ...facts, ...versionFacts() };
   }
 
+  /** What the boot set up — the Claude hooks and the Codex watcher — as the two
+   *  fixed tokens activation.mjs names, or nothing while it has not said. */
+  function setupNow() {
+    try {
+      const s = setup() ?? {};
+      const out = {};
+      addIf(out, "claudeHooks", ["ok", "failed", "off"].includes(s.claudeHooks) ? s.claudeHooks : undefined);
+      addIf(out, "codexWatch", ["on", "off"].includes(s.codexWatch) ? s.codexWatch : undefined);
+      return out;
+    } catch {
+      return {};
+    }
+  }
+
   /** The coarse usage the "active" report carries: the last finished day before
    *  `today`, its date as `usageDay` and its counts beside it. Nothing at all
    *  when there is no such day yet — a first launch has no yesterday — and only
@@ -364,6 +397,9 @@ export function createReporter({
       addIf(out, "sessions", count(raw.sessions));
       addIf(out, "subagents", count(raw.subagents));
       addIf(out, "projects", count(raw.projects));
+      // The features used that day, as names off the fixed list — an empty list
+      // is a real answer (the deck ran, nothing was opened), not a missing one.
+      out.features = Array.isArray(raw.features) ? raw.features.filter(f => FEATURES.includes(f)) : [];
       return out;
     } catch {
       return {};
@@ -446,17 +482,21 @@ export function createReporter({
     // The id is made here, the first time there is something to send under it.
     if (!prefs.current().report.installId) {
       await prefs.update(prev =>
-        prev.reports === false || prev.report.installId ? undefined : { report: { ...prev.report, installId: randomUUID() } },
+        prev.reports === false || prev.report.installId
+          ? undefined
+          // When the id is made is when this install began: the clock the first
+          // session is measured against. Kept here, never sent as a time.
+          : { report: { ...prev.report, installId: randomUUID(), installedAt: now().toISOString() } },
       );
     }
     const { installId, lastVersion, lastActiveDay } = prefs.current().report;
     if (!installId) return;
     if (!lastVersion) {
-      if (await call("POST", "/v1/app/events", { installId, kind: "install", ...factsNow() })) {
+      if (await call("POST", "/v1/app/events", { installId, kind: "install", ...factsNow(), ...setupNow() })) {
         await remember(installId, { lastVersion: facts.version });
       }
     } else if (lastVersion !== facts.version) {
-      if (await call("POST", "/v1/app/events", { installId, kind: "update", fromVersion: lastVersion, ...factsNow() })) {
+      if (await call("POST", "/v1/app/events", { installId, kind: "update", fromVersion: lastVersion, ...factsNow(), ...setupNow() })) {
         await remember(installId, { lastVersion: facts.version });
       }
     }
@@ -467,14 +507,52 @@ export function createReporter({
       // report it belongs to — so a checkIn that sends nothing new never asks the
       // deck for its counts.
       const used = coarseUsage(today);
-      if (await call("POST", "/v1/app/events", { installId, kind: "active", ...factsNow(), ...used })) {
+      if (await call("POST", "/v1/app/events", { installId, kind: "active", ...factsNow(), ...setupNow(), ...used })) {
         if (used.usageDay) usage.markSent(used.usageDay);
         await remember(installId, { lastActiveDay: today });
       }
     }
+    await sendActivation();
     await saveUsage();
   }
 
+  /**
+   * The install's first session, said once: an "activated" event with how long
+   * after the install it came, in a bucket, and which CLI it came from.
+   *
+   * Only for an install whose start this deck saw — `installedAt` is made with
+   * the id, so an install from before this version has none and is never
+   * measured: its first session was long ago, and "now" would be a lie. The time
+   * is taken from the first use this run heard, so a session that arrived before
+   * the first check-in had an id is still dated when it happened. A send that
+   * cannot get through is tried again at the next check-in.
+   */
+  async function sendActivation() {
+    const first = usage.firstUse?.();
+    let r = prefs.current().report;
+    if (!reportsOn(prefs.current(), env) || !r.installId || !r.installedAt || r.activationSent) return;
+    if (!r.firstSessionAt) {
+      if (!first) return;
+      await remember(r.installId, { firstSessionAt: first.at, firstProvider: first.provider });
+      r = prefs.current().report;
+      if (!r.firstSessionAt) return;
+    }
+    const body = { installId: r.installId, kind: "activated", ...factsNow(), ...setupNow() };
+    addIf(body, "firstSession", sinceInstallBucket(r.installedAt, r.firstSessionAt));
+    addIf(body, "firstProvider", r.firstProvider === "codex" || r.firstProvider === "claude" ? r.firstProvider : undefined);
+    if (await call("POST", "/v1/app/events", body)) await remember(r.installId, { activationSent: true });
+  }
+
+  /** The first session this run heard, sent the moment it lands rather than at
+   *  the next check-in, hours later or on a next launch that may never come. */
+  async function onFirstSession() {
+    try {
+      await sendActivation();
+    } catch {
+      // A settings file that cannot be written this minute; the next check-in tries again.
+    }
+  }
+
   /** The heartbeat. While reports are on and an id exists, tell the API this deck
    *  is still here — it moves the install's "last seen" and writes no event, so it
    *  carries the id and nothing else: no facts, no deviceId. Like every send it is
@@ -547,7 +625,10 @@ export function createReporter({
    *  open. The first check-in already puts a freshly launched deck online, so the
    *  first ping is a full interval out — nothing pings at boot. */
   function start() {
-    Promise.resolve(ready).catch(() => {}).then(restoreUsage).then(checkIn);
+    Promise.all([Promise.resolve(ready).catch(() => {}), Promise.resolve(setupKnown()).catch(() => {})])
+      .then(restoreUsage)
+      .then(checkIn)
+      .then(() => usage.onFirstUse?.(() => void onFirstSession()));
     if (!timer) {
       timer = setInterval(() => void checkIn(), CHECK_IN_EVERY_MS);
       timer.unref?.();
@@ -562,7 +643,7 @@ export function createReporter({
     pingTimer = null;
   }
 
-  return { checkIn, ping, setReports, reportError, restoreUsage, saveUsage, start, stop };
+  return { checkIn, ping, setReports, reportError, restoreUsage, saveUsage, sendActivation, start, stop };
 }
 
 // ── the deck's own providers ─────────────────────────────────────────────────

package/src/server/usage-day.mjs

@@ -12,16 +12,47 @@
 // WHAT IS KEPT. In memory, the session ids, the subagent ids and the folders the
 // transcripts sit in, so a session heard from a hundred times counts once. They
 // never leave this module: what is saved between runs (prefs.json, beside the
-// install id) and what is sent are three counts and the day they belong to.
+// install id) and what is sent are three counts, the day they belong to, and
+// the names of the features used that day — fixed tokens off FEATURES, a yes
+// for each, never what was done with them.
 //
 // A RESTART MID-DAY. The saved counts come back as a floor and the new run
 // counts on top of them, so a session that was running across the restart is
 // counted twice. That is the price of keeping no ids on disk, and a restart is
 // rare next to the day's sessions.
 //
-// Only what a hook said counts: a hook fires because somebody is running the
-// CLI. Replayed lines, a rollout read off disk and the deck's own synthetic
-// events are not use.
+// Only live use counts: a Claude hook fires because somebody is running the
+// CLI, and the Codex watcher emits only what a rollout gains while the deck
+// watches (its first scan skips every file's history). Replayed lines and the
+// deck's own synthetic events are not use.
+
+/**
+ * The features a day can say were used — fixed tokens, never anything a caller
+ * makes up. The page names the ones it sees opened (POST /api/feature, through
+ * feature-use.ts), the server the ones a route or a session shows. A name not on
+ * this list is dropped wherever it comes from.
+ */
+export const FEATURES = Object.freeze([
+  // Panels the page showed that day (each can be closed, and the choice is kept).
+  "usage-panel", "machine-panel", "detail-panel", "accounts-panel",
+  // Dialogs somebody opened.
+  "tool-detail", "session-summary", "context-window", "usage-history", "browser-watch",
+  "feedback", "keyboard-help", "share-accounts", "account-projects", "add-account",
+  "process-list", "lan-setup", "claude-fm",
+  // What the server saw done.
+  "account-switch", "accounts-manage", "auto-switch", "lan-pairing", "feedback-sent",
+  "self-update", "clear-board",
+  // Which CLI the day's sessions came from.
+  "claude-sessions", "codex-sessions",
+]);
+const FEATURE_SET = new Set(FEATURES);
+
+/** Only known feature names, once each, in the list's order. */
+function knownFeatures(list) {
+  if (!Array.isArray(list)) return [];
+  const have = new Set(list.filter(f => FEATURE_SET.has(f)));
+  return FEATURES.filter(f => have.has(f));
+}
 
 /** The day as the reporter says it: the UTC date, "2026-10-01". */
 export function utcDay(date) {
@@ -35,10 +66,13 @@ function whole(n) {
   return Number.isInteger(n) && n >= 0 ? n : 0;
 }
 
-/** Saved totals, coerced: a day and three counts, or null for anything else. */
+/** Saved totals, coerced: a day, three counts and the features used, or null for anything else. */
 function savedTotals(raw) {
   if (!raw || typeof raw !== "object" || typeof raw.day !== "string" || !DAY.test(raw.day)) return null;
-  return { day: raw.day, sessions: whole(raw.sessions), subagents: whole(raw.subagents), projects: whole(raw.projects) };
+  return {
+    day: raw.day, sessions: whole(raw.sessions), subagents: whole(raw.subagents), projects: whole(raw.projects),
+    features: knownFeatures(raw.features),
+  };
 }
 
 /** What prefs.json keeps for this, coerced — deck-prefs.mjs normalises with it. */
@@ -71,14 +105,18 @@ export function createUsageDay({ now = () => new Date() } = {}) {
   let sent = "";
   /** Moves on every change, so the reporter saves only when there is something new. */
   let changes = 0;
+  /** The first use this run heard, `{ at, provider }`, for activation.mjs. */
+  let first = null;
+  const firstListeners = [];
 
   function fresh(day, floor = null) {
     return {
       day,
-      floor: floor ?? { sessions: 0, subagents: 0, projects: 0 },
+      floor: floor ?? { sessions: 0, subagents: 0, projects: 0, features: [] },
       sessions: new Set(),
       subagents: new Set(),
       projects: new Set(),
+      features: new Set(),
     };
   }
 
@@ -88,6 +126,7 @@ export function createUsageDay({ now = () => new Date() } = {}) {
       sessions: c.floor.sessions + c.sessions.size,
       subagents: c.floor.subagents + c.subagents.size,
       projects: c.floor.projects + c.projects.size,
+      features: knownFeatures([...c.floor.features, ...c.features]),
     };
   }
 
@@ -107,21 +146,56 @@ export function createUsageDay({ now = () => new Date() } = {}) {
     changes++;
   }
 
-  /** A live hook payload: its session, and the subagent it came from if any. */
+  /** A live payload: its session, and the subagent it came from if any. */
   function noteUse(raw) {
     const sid = raw?.session_id;
     if (!sid || typeof sid !== "string") return;
     const c = today();
     add(c.sessions, sid);
     if (typeof raw.agent_id === "string" && raw.agent_id) add(c.subagents, `${sid}\u0000${raw.agent_id}`);
+    add(c.features, raw.provider === "codex" ? "codex-sessions" : "claude-sessions");
+    if (!first) {
+      first = { at: now().toISOString(), provider: raw.provider === "codex" ? "codex" : "claude" };
+      for (const fn of firstListeners) {
+        try { fn(first); } catch { /* a listener's failure is its own */ }
+      }
+    }
   }
 
-  /** A transcript path a hook carried, already accepted as Claude's. */
+  /** A transcript path a Claude hook carried, already accepted as Claude's:
+   *  the project is the folder it sits in. */
   function noteProject(path) {
     if (!path || typeof path !== "string") return;
     add(today().projects, folderOf(path));
   }
 
+  /** A feature somebody used today — a name off FEATURES, or nothing. */
+  function noteFeature(name) {
+    if (!FEATURE_SET.has(name)) return false;
+    add(today().features, name);
+    return true;
+  }
+
+  /** A Codex session's working directory, which is its project. */
+  function noteFolder(dir) {
+    if (!dir || typeof dir !== "string") return;
+    add(today().projects, dir);
+  }
+
+  /** The first use this run heard, or null. */
+  function firstUse() {
+    return first ? { ...first } : null;
+  }
+
+  /** Call `fn` with the first use, once, when it happens — or now, if it has. */
+  function onFirstUse(fn) {
+    if (first) {
+      try { fn(first); } catch { /* as above */ }
+      return;
+    }
+    firstListeners.push(fn);
+  }
+
   /** The totals of the last finished day before `day`, if they have not gone
    *  out yet; null when there is none. Rolls over first, so a deck that ran past
    *  midnight with nothing said since still has yesterday finished. */
@@ -156,7 +230,7 @@ export function createUsageDay({ now = () => new Date() } = {}) {
       if (!t) continue;
       const c = today();
       if (t.day === c.day) {
-        c.floor = { sessions: t.sessions, subagents: t.subagents, projects: t.projects };
+        c.floor = { sessions: t.sessions, subagents: t.subagents, projects: t.projects, features: t.features };
       } else if (t.day < c.day && (!done || t.day > done.day)) {
         done = t;
       }
@@ -169,7 +243,7 @@ export function createUsageDay({ now = () => new Date() } = {}) {
     return changes;
   }
 
-  return { noteUse, noteProject, finished, markSent, saved, restore, version };
+  return { noteUse, noteProject, noteFolder, noteFeature, firstUse, onFirstUse, finished, markSent, saved, restore, version };
 }
 
 /** The deck's own tally, which the event pipeline feeds and the reporter reads. */