ccdeck 3.36.6 → 3.36.7

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-B1ngNkKH.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.7",
   "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,8 @@
     "3.36.1",
     "3.36.4",
     "3.36.5",
-    "3.36.6"
+    "3.36.6",
+    "3.36.7"
   ],
   "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/reports.mjs

@@ -14,6 +14,9 @@
 //     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),
+//   - 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 +29,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
@@ -64,6 +70,7 @@ 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 { 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 +89,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 +323,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 +338,8 @@ export function createReporter({
   ready = prefsRead,
   versions = () => ({}),
   usage = usageDay,
+  setup = setupFacts,
+  setupKnown = () => whenSetupKnown(),
 } = {}) {
   const errorsSent = [];
   const lastSentAt = new Map();
@@ -351,6 +367,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
@@ -446,17 +476,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 +501,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 +619,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 +637,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

@@ -19,9 +19,10 @@
 // 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 day as the reporter says it: the UTC date, "2026-10-01". */
 export function utcDay(date) {
@@ -71,6 +72,9 @@ 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 {
@@ -107,21 +111,48 @@ 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}`);
+    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 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. */
@@ -169,7 +200,7 @@ export function createUsageDay({ now = () => new Date() } = {}) {
     return changes;
   }
 
-  return { noteUse, noteProject, finished, markSent, saved, restore, version };
+  return { noteUse, noteProject, noteFolder, firstUse, onFirstUse, finished, markSent, saved, restore, version };
 }
 
 /** The deck's own tally, which the event pipeline feeds and the reporter reads. */