@ai-adoption-score/ai-coding-usage 1.0.0 → 1.1.0

package/README.md

@@ -5,11 +5,46 @@ Score. It counts how a person uses Claude Code and Codex on their Mac and, once
 company's survey. Prompts, the AI's answers, code, file names, command text and session titles never leave the Mac.
 
 You don't install it yourself: your survey page shows one line with a code,
-`npx @ai-adoption-score/ai-coding-usage@1 connect <code>`, to paste into Claude Code, Codex or Terminal.
+`npx @ai-adoption-score/ai-coding-usage@latest connect <code>`, to paste into Claude Code, Codex or Terminal.
 
 Connected once, it shares by itself: a hook in Claude Code and Codex syncs after a session's replies, at most every 5
 minutes and always when a session ends, and an automatic ping-back, once an hour and without any numbers, tells the
-report "no AI use today" from "no signal".
+report "no AI use today" from "no signal". Once a day the ping-back also looks for a newer version on npm and puts it
+in place, so nobody runs the line again to get it.
+
+## How it works, step by step
+
+In short: connect, choose on the survey page, then share. Before the choice, only repository names leave the Mac.
+
+1. **The person pastes the line from their survey page** into Claude Code, Codex or Terminal. The code in it works
+   once, for 30 minutes; the server trades it for a token for this Mac.
+2. **The add-on puts its hooks and the ping-back in place** and copies itself to `~/.ai-adoption-score`. Why: the
+   survey gets the numbers after every session without anyone running a command again, and a hook can't run from
+   npx's temporary folder. The ping-back carries no numbers; it lets the report tell "no AI use today" from "no signal".
+3. **It sends the names of the repositories used in the last 30 days, and nothing else.** Why: the person chooses on
+   their survey page, and the page needs the names to list them. The choice isn't asked in the terminal, because the
+   line usually runs inside Claude Code or Codex, where the add-on can't ask questions. The server keeps the list for
+   an hour at most.
+4. **The person ticks what to share** on their survey page; everything is ticked to start with. When they press
+   Share, the list is deleted, and with it the names they didn't tick.
+5. **Only then do numbers leave the Mac:** the last 30 days of what they ticked, then the new numbers after each
+   session. Before every sync the add-on asks what they chose and keeps everything else on the Mac; the server checks
+   the same rule again.
+6. **It keeps itself up to date.** Once a day the ping-back asks npm for the latest version. A newer one is
+   downloaded, checked against the checksum npm lists for it, started once to see that it runs on this Mac's Node, and
+   put in place of the add-on's copy; the hooks, the ping-back and the settings stay as they are. Why: a fix or a new
+   number reaches every Mac without anyone running the line again. It never goes back to an older version, skips a
+   version npm marks as withdrawn, and keeps the copy that works when anything fails.
+7. **It removes itself** when the Mac is disconnected on the survey page or the survey closes. `disconnect` does the
+   same from the Mac.
+
+The person makes their choice on the survey page, so the survey's server keeps it and the add-on follows the server's
+answer. It still checks what it's told:
+
+- It reads 30 days back at most, whatever the server asks for.
+- It shares nothing when the choice isn't one of the two kinds the server keeps: what the person ticked, or
+  `{ "all": true }` for links made before people could choose.
+- It sends the token over https only. Plain http works only for this Mac's own address (`localhost`), for testing.
 
 ## Commands
 
@@ -17,13 +52,14 @@ report "no AI use today" from "no signal".
   hooks and the ping-back in place. Then it sends the names of the repositories used in the last 30 days, and nothing
   else, so the person can choose on their survey page which to share; a background wait shares the last 30 days of
   those once they press Share. The server defaults to `https://app.ai-adoption-score.app`;
-  `AI_ADOPTION_SCORE_SERVER` or `--server http://localhost:3000` point it at a local app. Run again on a Mac that is
-  connected, it keeps that Mac's link on the same server (the survey page still shows one Mac) and lets the person
-  choose again; a link on another server is disconnected, and its token never goes to the new one.
+  `AI_ADOPTION_SCORE_SERVER` or `--server http://localhost:3000` point it at a local app; any other server has to be
+  https. Run again on a Mac that is connected, it keeps that Mac's link on the same server (the survey page still
+  shows one Mac) and lets the person choose again; a link on another server is disconnected, and its token never goes
+  to the new one.
 - `sync`: shares now instead of after the next session. It counts the window again and sends the rows that changed
   since the server last accepted them; the server replaces what it had, so nothing counts twice.
-- `status`: which survey this Mac shares with, what the person chose, the hooks and when they last ran, and when it
-  last shared.
+- `status`: which survey this Mac shares with, what the person chose, the hooks and when they last ran, when it last
+  shared, and the add-on's version and when it last looked for a newer one.
 - `disconnect`: stops sharing from this Mac and removes everything it put in place.
 - `preview [--days 30] [--company github.com/acme] [--json]`: what would be shared, without sending.
 
@@ -58,14 +94,15 @@ nothing, and `disconnect` still takes them away.
 
 For testing, `AI_ADOPTION_SCORE_HOME`, `AI_ADOPTION_SCORE_CLAUDE_SETTINGS`, `AI_ADOPTION_SCORE_CODEX_HOOKS` and
 `AI_ADOPTION_SCORE_LAUNCH_AGENTS` move each of these elsewhere, and `AI_ADOPTION_SCORE_SKIP_LAUNCHCTL=1` leaves launchd
-alone. `AI_ADOPTION_SCORE_NODE` names a Node for `run.sh` to try.
+alone. `AI_ADOPTION_SCORE_NODE` names a Node for `run.sh` to try. `AI_ADOPTION_SCORE_REGISTRY` points the daily update
+at another npm registry; like the server, it has to be https, or http on this Mac itself.
 
 ## Try it
 
 Count this Mac's last 30 days and see what would be shared, without connecting and without sending anything:
 
 ```bash
-npx @ai-adoption-score/ai-coding-usage@1 preview
+npx @ai-adoption-score/ai-coding-usage@latest preview
 ```
 
 Add `--json` to see the exact rows, or `--days 7` for a shorter window. It needs Node.js 18.17 or newer and git, and
@@ -102,10 +139,10 @@ again and ticks it. Work outside any repository is one more box.
 ## What a row holds
 
 One row per session, day, repository and branch: the tool, a hash of the session id, the day and the first and last
-moment, the repository and branch and whether the branch is pushed, active minutes, prompts, stops, rejected actions,
-commands, file edits, lines added and removed, connector calls by name, skills, helper agents, commits and pushed
-commits, and per model its replies and tokens. `npx @ai-adoption-score/ai-coding-usage@1 preview --json` prints the exact rows this Mac
-would send.
+moment, the repository and branch and whether the branch is pushed, active minutes and the same time by hour, prompts,
+stops, rejected actions, commands, file edits, lines added and removed, connector calls by name, skills, helper agents,
+commits and pushed commits, and per model its replies and tokens. `npx @ai-adoption-score/ai-coding-usage@latest
+preview --json` prints the exact rows this Mac would send.
 
 Never shared: prompts, AI answers, code, file names and paths, command text, session titles.
 
@@ -125,3 +162,7 @@ Never shared: prompts, AI answers, code, file names and paths, command text, ses
   lines as added. A failed or turned-down edit, or a scratch file elsewhere, doesn't count.
 - Active minutes add up the gaps under five minutes. A commit counts for the session whose window holds it, from its
   first moment to an hour after its last; each commit counts once.
+- Time by hour (`minutesByHour`, from 1.1) is the same active time cut at the hours (UTC). A minute when several
+  sessions were active at once is split between them, so a person's rows add up to the time they really spent: on one
+  Mac with sessions side by side, 30 days of active minutes came to 185 hours and their time by hour to the 92 really
+  spent. Only the rows that are shared take part, so a session that stays on the Mac takes no share.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-adoption-score/ai-coding-usage",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Shares how you use Claude Code and Codex with your company's AI Adoption Score survey. Never prompts, AI answers, code or file names.",
   "homepage": "https://ai-adoption-score.app/product/ai-coding-usage",
   "repository": {

package/src/api.mjs

@@ -7,6 +7,22 @@ const TIMEOUT_MS = 20_000
 
 export const CLIENT_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
 
+/** Plain http goes only to this Mac itself, for testing; the device token goes anywhere else over https. */
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]'])
+
+/** Why the add-on won't talk to `server`, or null when it will. @param {string} server */
+export function serverProblem(server) {
+  let url
+  try {
+    url = new URL(server)
+  } catch {
+    return `"${server}" isn't a web address.`
+  }
+  if (url.protocol === 'https:') return null
+  if (url.protocol === 'http:' && LOCAL_HOSTS.has(url.hostname)) return null
+  return `"${server}" isn't https. Plain http works only for this Mac's own address (localhost), for testing.`
+}
+
 /**
  * @param {string} server @param {string} path @param {unknown} body @param {string} [token]
  * @returns {Promise<{ status: number, body: any, retryAfterSeconds: number | null }>}
@@ -25,6 +41,8 @@ export async function get(server, path, token) {
 
 /** @param {string} server @param {string} path @param {'GET' | 'POST'} method @param {unknown} body @param {string} [token] */
 async function request(server, path, method, body, token) {
+  const problem = serverProblem(server)
+  if (problem) throw new Error(problem)
   const controller = new AbortController()
   const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
   try {

package/src/checkin.mjs

@@ -8,11 +8,12 @@ import { log } from './log.mjs'
 import { paths } from './paths.mjs'
 import { localDay } from './rows.mjs'
 import { readState, updateState } from './state.mjs'
+import { updateIfDue } from './update.mjs'
 
 /**
  * The hourly check-in (a launchd agent): tells the survey this Mac is there, and whether each tool's hook is still in
  * place and running. It sends no usage numbers. A day with a check-in and no use is a real zero in the report; a day
- * without one is a gap.
+ * without one is a gap. Once a day it also looks for a newer add-on (update.mjs).
  */
 
 const NOT_APPROVED_GRACE_MS = 15 * 60_000
@@ -91,6 +92,12 @@ export async function runCheckIn(env = process.env) {
     log(`check-in: ${response.status} ${status ?? ''} claude=${checkIn.claudeHook} codex=${checkIn.codexHook}`, env)
   } catch (error) {
     log(`check-in failed: ${error instanceof Error ? error.message : String(error)}`, env)
+    return 0
+  }
+  try {
+    await updateIfDue(env)
+  } catch (error) {
+    log(`update failed: ${error instanceof Error ? error.message : String(error)}`, env)
   }
   return 0
 }

package/src/choice.mjs

@@ -19,13 +19,33 @@ export function repositoryOwner(repository) {
   return parts.length >= 3 ? `${parts[0]}/${parts[1]}`.toLowerCase() : null
 }
 
+/**
+ * The choice in the server's answer, taken only in one of the two shapes the server keeps: what the person ticked, or
+ * `{ all: true }` for links made before people could choose. Anything else shares nothing.
+ * @param {unknown} value @returns {RepositoryChoice | null}
+ */
+export function readChoice(value) {
+  if (!value || typeof value !== 'object') return null
+  const choice = /** @type {Record<string, unknown>} */ (value)
+  if ('all' in choice) return choice.all === true ? { all: true } : null
+  const names = (list) => Array.isArray(list) && list.every((name) => typeof name === 'string')
+  if (!names(choice.repositories) || !names(choice.owners)) return null
+  if (typeof choice.outsideGit !== 'boolean' || typeof choice.localFolders !== 'boolean') return null
+  return {
+    repositories: /** @type {string[]} */ (choice.repositories),
+    owners: /** @type {string[]} */ (choice.owners),
+    outsideGit: choice.outsideGit,
+    localFolders: choice.localFolders,
+  }
+}
+
 /**
  * Whether a session in `repository` (null outside any repository) is shared. Nothing is, before the person chooses.
  * @param {RepositoryChoice | null} choice @param {string | null} repository
  */
 export function isShared(choice, repository) {
   if (!choice) return false
-  if ('all' in choice) return true
+  if ('all' in choice) return choice.all === true
   if (!repository) return choice.outsideGit
   if (choice.repositories.includes(repository)) return true
   if (repository.startsWith(LOCAL_PREFIX)) return choice.localFolders
@@ -64,7 +84,7 @@ export function repositoryList(rows) {
 /** What this Mac shares, in a line for `status`. @param {RepositoryChoice | null} choice */
 export function describeChoice(choice) {
   if (!choice) return 'nothing yet: choose your repositories on your survey page'
-  if ('all' in choice) return 'every repository'
+  if ('all' in choice) return choice.all === true ? 'every repository' : 'nothing'
   const parts = [`${choice.repositories.length} ${choice.repositories.length === 1 ? 'repository' : 'repositories'}`]
   if (choice.owners.length > 0) parts.push(`new ones from ${choice.owners.join(', ')}`)
   if (choice.outsideGit) parts.push('work outside a repository')

package/src/cli.mjs

@@ -4,13 +4,14 @@ import { existsSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { CLIENT_VERSION, post } from './api.mjs'
+import { CLIENT_VERSION, post, serverProblem } from './api.mjs'
 import { runCheckIn } from './checkin.mjs'
 import { DEFAULT_SERVER, readConfig, writeConfig } from './config.mjs'
 import { runHook } from './hook.mjs'
 import { hookState, installAll, uninstallAll } from './install.mjs'
 import { paths } from './paths.mjs'
-import { scanUsage } from './scan.mjs'
+import { daysToRead, scanUsage } from './scan.mjs'
+import { timeByHour } from './rows.mjs'
 import { readState } from './state.mjs'
 import { describeChoice, repositoryList } from './choice.mjs'
 import { formatSummary } from './summary.mjs'
@@ -29,8 +30,9 @@ Usage
   connect     Link this Mac to your survey with the code from your survey page. It adds a hook to Claude Code and
               Codex and an automatic ping-back, and sends the names of the repositories you used in the last 30 days, so
               you can choose on your survey page which to share. Then it shares the last 30 days of those, and after
-              that, after each session. Run it again to change your choice.
-  status      Show which survey this Mac shares with, what you chose, its hooks, and when it last shared.
+              that, after each session. Run it again to change your choice. Once a day the ping-back looks for a
+              newer version of the add-on and puts it in place.
+  status      Show which survey this Mac shares with, what you chose, its hooks, when it last shared, and its version.
   sync        Share now, instead of after the next session.
   disconnect  Stop sharing from this Mac: removes the hooks, the ping-back and the add-on's settings.
   preview     Count this Mac's last 30 days and show what would be shared. Nothing is sent.
@@ -108,12 +110,9 @@ async function connect(args) {
     else if (!code) code = args[index]
     else return fail(`Unknown option "${args[index]}".`)
   }
-  if (!code) return fail('Add the code from your survey page: npx @ai-adoption-score/ai-coding-usage@1 connect K7Q2-9M4X')
-  try {
-    new URL(server)
-  } catch {
-    return fail(`"${server}" isn't a web address.`)
-  }
+  if (!code) return fail('Add the code from your survey page: npx @ai-adoption-score/ai-coding-usage@latest connect K7Q2-9M4X')
+  const problem = serverProblem(server)
+  if (problem) return fail(problem)
   // Run again on a Mac that is connected: the same server carries the link on with the new token, so it doesn't
   // count a second Mac. A token never goes to another server; that survey is told the Mac left once this one connects.
   const previous = readConfig()
@@ -131,7 +130,9 @@ async function connect(args) {
   if (response.status !== 200 || response.body?.status !== 'connected') {
     return fail(response.body?.error ?? `Couldn't connect: the server answered ${response.status}.`)
   }
-  const { token, companyName, syncIntervalSeconds, historyDays } = response.body
+  const { token, companyName, syncIntervalSeconds } = response.body
+  // However far back the survey asks for, the add-on reads 30 days at most.
+  const historyDays = daysToRead(response.body.historyDays)
   // A new connection starts with nothing sent.
   rmSync(paths().state, { force: true })
   const config = { server, token, companyName, connectedAt: new Date().toISOString(), syncIntervalSeconds, historyDays }
@@ -149,7 +150,7 @@ async function connect(args) {
   say(`  Codex: ${HOOK_WORDS[installed.codex] ?? installed.codex}`)
   say(`  Automatic ping-back: ${installed.checkIn === 'added' ? 'added, so the survey knows this Mac is still connected (no numbers)' : "couldn't add it"}`)
   // The person chooses which repositories to share before any session leaves this Mac: only the names go now.
-  const scan = await scanUsage({ days: historyDays || 30 })
+  const scan = await scanUsage({ days: historyDays })
   const list = repositoryList(scan.rows)
   const listed = await post(server, '/api/usage/repositories', list, token)
   if (listed.body?.status !== 'choosing') {
@@ -227,6 +228,7 @@ async function status() {
   say(`Codex hook: ${hookState('codex')}${state.hookRuns.codex ? `, last ran ${state.hookRuns.codex}` : ''}`)
   say(state.lastSyncAt ? `Last shared: ${state.lastSyncAt}.` : 'Nothing shared yet.')
   if (state.lastCheckInAt) say(`Last ping-back: ${state.lastCheckInAt}.`)
+  say(`Add-on ${CLIENT_VERSION}; it looks for a newer version once a day${state.lastUpdateCheckAt ? `, last on ${state.lastUpdateCheckAt}` : ''}.`)
   if (state.lastError) say(`Last problem: ${state.lastError}`)
   return 0
 }
@@ -266,6 +268,6 @@ async function preview(rest) {
   }
   if (process.platform !== 'darwin') return fail('AI Coding Usage works on a Mac for now. Nothing was read.')
   const scan = await scanUsage({ days })
-  process.stdout.write(json ? `${JSON.stringify({ since: scan.since, until: scan.until, rows: scan.rows }, null, 2)}\n` : `${formatSummary(scan, { companyAccounts })}\n`)
+  process.stdout.write(json ? `${JSON.stringify({ since: scan.since, until: scan.until, rows: timeByHour(scan.rows) }, null, 2)}\n` : `${formatSummary(scan, { companyAccounts })}\n`)
   return 0
 }

package/src/rows.mjs

@@ -12,7 +12,8 @@ import { createHash } from 'node:crypto'
  *   repository: string | null, branch: string | null, branchPushed: boolean, activeMinutes: number,
  *   prompts: number, interrupts: number, rejectedActions: number, commands: number, fileEdits: number,
  *   linesAdded: number, linesRemoved: number, connectors: Record<string, number>, skills: number,
- *   helperAgents: number, commits: number, commitsPushed: number, models: Record<string, ModelTokens>
+ *   helperAgents: number, commits: number, commitsPushed: number, models: Record<string, ModelTokens>,
+ *   minutesByHour?: Record<string, number>
  * }} UsageRow
  *
  * What a row collects before it is finished; `gitTop` and `times` never leave the Mac.
@@ -111,6 +112,57 @@ export function changedLines(before, after) {
   return { added: newEnd - start, removed: oldEnd - start }
 }
 
+/** Each finished row's moments, kept here so they never leave the Mac: `timeByHour` needs them. */
+const momentsOf = new WeakMap()
+const HOUR_MS = 3_600_000
+
+/**
+ * Time with AI by hour (owner, 2026-10-30): each row's active stretches, the gaps under five minutes between its
+ * moments, cut at the hours (UTC, `YYYY-MM-DDTHH`), with a stretch when several of `rows` were active at once shared
+ * evenly between them. So the rows of a day add up to the time the person really spent with AI, however many sessions
+ * ran side by side, where active minutes count each session's own. Only the rows given take part, so a session that
+ * isn't shared changes nothing in the ones that are.
+ * @param {UsageRow[]} rows @returns {UsageRow[]}
+ */
+export function timeByHour(rows) {
+  /** @type {Array<[number, number, number]>} */
+  const points = []
+  rows.forEach((row, index) => {
+    const times = momentsOf.get(row) ?? []
+    for (let at = 1; at < times.length; at += 1) {
+      if (times[at] > times[at - 1] && times[at] - times[at - 1] < ACTIVE_GAP_MS) points.push([times[at - 1], 1, index], [times[at], -1, index])
+    }
+  })
+  // At the same moment, a stretch ends before the next begins.
+  points.sort((left, right) => left[0] - right[0] || left[1] - right[1])
+  /** @type {Map<string, number>[]} */
+  const shares = rows.map(() => new Map())
+  /** @type {Map<number, number>} the rows active now, and how many of their stretches */
+  const open = new Map()
+  let previous = 0
+  for (const [time, step, index] of points) {
+    for (let from = previous; open.size > 0 && from < time; ) {
+      const to = Math.min((Math.floor(from / HOUR_MS) + 1) * HOUR_MS, time)
+      const hour = new Date(from).toISOString().slice(0, 13)
+      for (const active of open.keys()) shares[active].set(hour, (shares[active].get(hour) ?? 0) + (to - from) / open.size)
+      from = to
+    }
+    const count = (open.get(index) ?? 0) + step
+    if (count > 0) open.set(index, count)
+    else open.delete(index)
+    previous = time
+  }
+  return rows.map((row, index) => {
+    /** @type {Record<string, number>} */
+    const minutesByHour = {}
+    for (const [hour, ms] of shares[index]) {
+      const minutes = Math.round(ms / 6_000) / 10
+      if (minutes > 0) minutesByHour[hour] = minutes
+    }
+    return { ...row, minutesByHour }
+  })
+}
+
 /** Working time: the gaps between a row's moments that are shorter than five minutes, added up. */
 function activeMinutes(times) {
   if (times.length === 0) return 0
@@ -130,7 +182,7 @@ function activeMinutes(times) {
 export function finishRow(draft, isPushed) {
   const times = [...draft.times].sort((left, right) => left - right)
   const { sessionId, gitTop, times: _times, ...rest } = draft
-  return {
+  const row = {
     ...rest,
     sessionKey: createHash('sha256').update(`${draft.tool}:${sessionId}`).digest('hex').slice(0, 32),
     firstEventAt: new Date(times[0]).toISOString(),
@@ -138,6 +190,8 @@ export function finishRow(draft, isPushed) {
     branchPushed: isPushed(gitTop, draft.branch),
     activeMinutes: activeMinutes(times),
   }
+  momentsOf.set(row, times)
+  return row
 }
 
 /** Whether a row has anything worth sending: a reply from the AI or a prompt from the person. */

package/src/scan.mjs

@@ -5,13 +5,22 @@ import { loadDesktopConnectorNames } from './connectors.mjs'
 import { assignCommits, createGitInfo } from './git.mjs'
 import { createRowSet, finishRow, hasUse, windowStart } from './rows.mjs'
 
+/** The add-on never reads further back than this, whatever the server asks for. */
+export const MAX_HISTORY_DAYS = 30
+
+/** How many days to read: a whole number from 1 to 30, and 30 when `days` isn't one. @param {unknown} days */
+export function daysToRead(days) {
+  const whole = Math.trunc(Number(days))
+  return Number.isFinite(whole) && whole >= 1 ? Math.min(whole, MAX_HISTORY_DAYS) : MAX_HISTORY_DAYS
+}
+
 /**
- * Reads this Mac's Claude Code and Codex records for the last `days` calendar days and returns the rows that would be
- * sent, with how much of the records could be read. Nothing is written and nothing leaves the Mac.
+ * Reads this Mac's Claude Code and Codex records for the last `days` calendar days, 30 at most, and returns the rows
+ * that would be sent, with how much of the records could be read. Nothing is written and nothing leaves the Mac.
  * @param {{ days?: number, now?: number, env?: NodeJS.ProcessEnv }} [options]
  */
-export async function scanUsage({ days = 30, now = Date.now(), env = process.env } = {}) {
-  const since = windowStart(now, days)
+export async function scanUsage({ days = MAX_HISTORY_DAYS, now = Date.now(), env = process.env } = {}) {
+  const since = windowStart(now, daysToRead(days))
   const rows = createRowSet()
   const gitInfo = createGitInfo()
   const claudeHealth = { files: 0, lines: 0, unreadable: 0 }

package/src/state.mjs

@@ -5,13 +5,14 @@ import { paths } from './paths.mjs'
 
 /**
  * What the add-on remembers between runs, beside its settings: which rows the server accepted (by a hash of each), when
- * it last synced, when each tool's hook last ran, and how long the server asked it to wait. Only names and numbers.
+ * it last synced, when each tool's hook last ran, how long the server asked it to wait, and when it last looked for a
+ * newer version. Only names and numbers.
  *
  * @typedef {{
  *   sent: Record<string, string>,
  *   lastSyncStartedAt?: string, lastSyncAt?: string, notBefore?: string,
  *   hookRuns: Partial<Record<'claude-code' | 'codex', string>>,
- *   lastCheckInAt?: string, lastError?: string
+ *   lastCheckInAt?: string, lastError?: string, lastUpdateCheckAt?: string
  * }} UsageState
  */
 

package/src/sync.mjs

@@ -4,12 +4,12 @@ import { closeSync, openSync, readFileSync, rmSync, writeSync } from 'node:fs'
 import { constants, setPriority } from 'node:os'
 import { get, post, CLIENT_VERSION } from './api.mjs'
 import { reportedHookState } from './checkin.mjs'
-import { isShared } from './choice.mjs'
+import { isShared, readChoice } from './choice.mjs'
 import { isCurrentConfig, writeConfig } from './config.mjs'
 import { hookState, uninstallAll } from './install.mjs'
 import { log } from './log.mjs'
 import { paths } from './paths.mjs'
-import { localDay } from './rows.mjs'
+import { localDay, timeByHour } from './rows.mjs'
 import { scanUsage } from './scan.mjs'
 import { readState, updateState } from './state.mjs'
 
@@ -96,7 +96,7 @@ export async function askChoice(config) {
   if (response.status === 429) return { status: 'waiting', choice: null, retryAfterSeconds: response.retryAfterSeconds }
   const status = response.body?.status ?? (response.status === 401 ? 'revoked' : 'error')
   if (status === 'error') throw new Error(response.body?.error ?? `The server answered ${response.status}.`)
-  return { status, choice: response.body?.choice ?? null, retryAfterSeconds: null }
+  return { status, choice: readChoice(response.body?.choice), retryAfterSeconds: null }
 }
 
 /**
@@ -136,8 +136,9 @@ export async function syncNow(config, { background = false, reason = 'manual', e
     }
     const { choice } = asked
 
-    const scan = await scanUsage({ days: config.historyDays || 30, env })
-    const included = scan.rows.filter((row) => sendsTool(row.tool, config, state, env) && isShared(choice, row.repository))
+    const scan = await scanUsage({ days: config.historyDays, env })
+    // Time by hour among the rows that go out only, so a session that stays on the Mac takes no share of it.
+    const included = timeByHour(scan.rows.filter((row) => sendsTool(row.tool, config, state, env) && isShared(choice, row.repository)))
     const changed = included.filter((row) => state.sent[rowKey(row)] !== rowHash(row))
     const checkIn = {
       day: localDay(Date.now()),

package/src/update.mjs

@@ -0,0 +1,173 @@
+// @ts-check
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+import { CLIENT_VERSION, serverProblem } from './api.mjs'
+import { log } from './log.mjs'
+import { paths } from './paths.mjs'
+import { readState, updateState } from './state.mjs'
+
+/**
+ * The add-on keeps itself up to date (owner, 2026-10-30): once a day the ping-back asks npm for the latest version.
+ * When there is a newer one, it downloads it, checks it is byte for byte the file npm lists for that version, checks
+ * that it starts on this Mac's Node, and puts it in place of its own copy; the next hook or ping-back runs it. Nothing
+ * is sent to npm but the request itself. The hooks, the ping-back and the settings stay as they are, and anything that
+ * goes wrong leaves the copy that works.
+ */
+
+const PACKAGE = '@ai-adoption-score/ai-coding-usage'
+const REGISTRY = 'https://registry.npmjs.org'
+const CHECK_EVERY_MS = 24 * 60 * 60_000
+const TIMEOUT_MS = 30_000
+const MAX_DOWNLOAD_BYTES = 5 * 1024 * 1024
+
+/** "1.2.3" as numbers; null for anything else, such as a pre-release. @param {unknown} version */
+function versionParts(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(version))
+  return match ? match.slice(1).map(Number) : null
+}
+
+/** Whether `candidate` is a later release than `current`; never a step back. @param {unknown} candidate @param {unknown} current */
+export function isNewer(candidate, current) {
+  const next = versionParts(candidate)
+  const now = versionParts(current)
+  if (!next || !now) return false
+  for (let index = 0; index < 3; index += 1) if (next[index] !== now[index]) return next[index] > now[index]
+  return false
+}
+
+/** Whether this Node is new enough for `engines.node` written as ">=18.17"; any other form is left to the start check. */
+function nodeFits(engines, running = process.versions.node) {
+  const wanted = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(String(engines?.node ?? '').trim())
+  if (!wanted) return true
+  const need = wanted.slice(1).map((part) => Number(part ?? 0))
+  const have = running.split('.').map(Number)
+  for (let index = 0; index < 3; index += 1) if ((have[index] ?? 0) !== need[index]) return (have[index] ?? 0) > need[index]
+  return true
+}
+
+/** @param {string} url @param {Record<string, string>} headers */
+async function download(url, headers = {}) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
+  try {
+    const response = await fetch(url, { headers: { 'user-agent': `ai-coding-usage/${CLIENT_VERSION}`, ...headers }, signal: controller.signal })
+    if (!response.ok) throw new Error(`${url} answered ${response.status}`)
+    const body = Buffer.from(await response.arrayBuffer())
+    if (body.length > MAX_DOWNLOAD_BYTES) throw new Error(`${url} is larger than expected`)
+    return body
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * The files of an npm package: a gzipped tar with every entry under `package/`. Only plain files whose path stays
+ * inside the package are read; links and anything else are left out.
+ * @param {Buffer} tarball @returns {Map<string, { data: Buffer, mode: number }>}
+ */
+export function readPackage(tarball) {
+  const archive = gunzipSync(tarball)
+  const files = new Map()
+  /** @type {string | null} */
+  let paxPath = null
+  for (let offset = 0; offset + 512 <= archive.length; ) {
+    const header = archive.subarray(offset, offset + 512)
+    if (header.every((byte) => byte === 0)) break
+    const field = (start, length) => header.subarray(start, start + length).toString('utf8').replace(/\0[\s\S]*$/, '')
+    const size = parseInt(field(124, 12).trim() || '0', 8)
+    const type = field(156, 1) || '0'
+    const prefix = field(257, 5) === 'ustar' ? field(345, 155) : ''
+    const name = paxPath ?? (prefix ? `${prefix}/${field(0, 100)}` : field(0, 100))
+    paxPath = null
+    const body = archive.subarray(offset + 512, offset + 512 + size)
+    offset += 512 + Math.ceil(size / 512) * 512
+    if (type === 'x') {
+      // An extended header: its `path` names the next entry.
+      paxPath = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(body.toString('utf8'))?.[1] ?? null
+      continue
+    }
+    if (type !== '0') continue
+    const parts = name.split('/')
+    if (parts[0] !== 'package' || parts.length < 2 || parts.some((part) => part === '' || part === '.' || part === '..')) continue
+    files.set(parts.slice(1).join('/'), { data: Buffer.from(body), mode: parseInt(field(100, 8).trim() || '644', 8) & 0o755 })
+  }
+  return files
+}
+
+/**
+ * Puts `version` in place of the add-on's copy, when it is the one npm lists and it starts here.
+ * @param {{ version: string, dist?: { tarball?: string, integrity?: string } }} manifest @param {string} registry
+ */
+async function install(manifest, registry, env) {
+  const where = paths(env)
+  const tarball = manifest.dist?.tarball
+  const integrity = /^sha512-(.+)$/.exec(manifest.dist?.integrity ?? '')?.[1]
+  if (!tarball || !integrity || new URL(tarball).origin !== new URL(registry).origin) throw new Error(`npm lists no file for ${manifest.version} that can be checked`)
+  const archive = await download(tarball)
+  if (createHash('sha512').update(archive).digest('base64') !== integrity) throw new Error(`the file for ${manifest.version} isn't the one npm lists`)
+  const files = readPackage(archive)
+  const listed = JSON.parse(files.get('package.json')?.data.toString('utf8') ?? '{}')
+  if (listed.name !== PACKAGE || listed.version !== manifest.version || !files.has('bin/ai-coding-usage.mjs')) throw new Error(`the file for ${manifest.version} isn't this add-on`)
+
+  // The new copy beside the old one, as connecting puts it: its program and its package.json, nothing else.
+  const fresh = `${where.app}.update`
+  const previous = `${where.app}.previous`
+  rmSync(fresh, { recursive: true, force: true })
+  try {
+    for (const [path, file] of files) {
+      if (path !== 'package.json' && !path.startsWith('bin/') && !path.startsWith('src/')) continue
+      mkdirSync(dirname(join(fresh, path)), { recursive: true })
+      writeFileSync(join(fresh, path), file.data, { mode: file.mode })
+    }
+    try {
+      // It has to start on this Node before it replaces the copy that works: its help loads all of it and exits.
+      execFileSync(process.execPath, [join(fresh, 'bin', 'ai-coding-usage.mjs'), 'help'], { stdio: 'ignore', timeout: TIMEOUT_MS, env })
+    } catch {
+      throw new Error(`${manifest.version} doesn't start on Node ${process.versions.node}`)
+    }
+    rmSync(previous, { recursive: true, force: true })
+    renameSync(where.app, previous)
+    try {
+      renameSync(fresh, where.app)
+    } catch (error) {
+      renameSync(previous, where.app)
+      throw error
+    }
+    rmSync(previous, { recursive: true, force: true })
+  } finally {
+    rmSync(fresh, { recursive: true, force: true })
+  }
+}
+
+/**
+ * The ping-back's daily look at npm. `AI_ADOPTION_SCORE_REGISTRY` points it at another registry, for testing; like the
+ * survey's server, it has to be https, or http on this Mac itself.
+ * @returns {Promise<'not-due' | 'up-to-date' | 'updated' | 'skipped'>}
+ */
+export async function updateIfDue(env = process.env, now = Date.now()) {
+  const last = readState(env).lastUpdateCheckAt
+  if (last && now - Date.parse(last) < CHECK_EVERY_MS) return 'not-due'
+  const registry = env.AI_ADOPTION_SCORE_REGISTRY || REGISTRY
+  const problem = serverProblem(registry)
+  if (problem) throw new Error(problem)
+  const document = JSON.parse(
+    (await download(`${registry.replace(/\/+$/, '')}/${PACKAGE.replace('/', '%2f')}`, { accept: 'application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8' })).toString('utf8')
+  )
+  // npm answered: the next look is tomorrow, whatever happens next.
+  updateState((current) => {
+    current.lastUpdateCheckAt = new Date(now).toISOString()
+  }, env)
+  const latest = document?.['dist-tags']?.latest
+  const manifest = document?.versions?.[latest]
+  if (!isNewer(latest, CLIENT_VERSION) || !manifest) return 'up-to-date'
+  if (manifest.deprecated || !nodeFits(manifest.engines)) {
+    log(`update: ${latest} is out, but ${manifest.deprecated ? 'it was withdrawn' : `it needs Node ${manifest.engines.node}`}; staying on ${CLIENT_VERSION}`, env)
+    return 'skipped'
+  }
+  await install(manifest, registry, env)
+  log(`update: ${CLIENT_VERSION} → ${latest}`, env)
+  return 'updated'
+}