@lorekit/cli 1.54.0 → 1.55.1

package/bin/lorekit.mjs

@@ -10,7 +10,7 @@ import { COMMANDS_BY_NAME, STRICT_FLAG_COMMANDS, COMMAND_ALIASES } from '../src/
 // Catalog-derived, so the default this help PROMISES is the one the server
 // applies — see src/surfaces.generated.mjs.
 import { PURGE_RETENTION_DAYS_DEFAULT } from '../src/surfaces.generated.mjs';
-import { traceCommand } from '../src/telemetry.mjs';
+import { traceCommand, meterCommand } from '../src/telemetry.mjs';
 import { loadDotEnv } from '../src/dotenv.mjs';
 
 // Read the version from package.json so it always matches the published
@@ -863,12 +863,23 @@ async function main() {
 
   // Machine-facing commands (`hook`, `mcp`) own their stdout — a host's JSON
   // contract and JSON-RPC frames respectively — so they must bypass the usage
-  // and version branches, which print. They are also deliberately UNTRACED:
-  // they fire on every agent event, and a span per event is a cost the caller
-  // never asked for. `machine` in the registry is the single statement of that.
+  // and version branches, which print. `machine` in the registry is the single
+  // statement of that.
+  //
+  // They stay UNTRACED — a span per agent event is a firehose of near-identical
+  // traces, and these fire several times per turn — but they are no longer
+  // SILENT. `meterCommand` emits the invocation COUNTER only, carrying the same
+  // identity attributes the traced commands do, on a much tighter export budget
+  // (see `METERED_TIMEOUT_MS`). Without it the durable telemetry identity would
+  // differentiate users across `list`/`search`/`stats` while the traffic that
+  // actually dominates — the hooks on every turn — stayed invisible.
+  //
+  // The command runs FIRST and its exit code is returned unchanged: the host's
+  // stdout contract is written by `run` before any export is attempted, and a
+  // telemetry failure can neither alter the exit code nor corrupt the frame.
   const machineEntry = COMMANDS_BY_NAME.get(command);
   if (machineEntry?.machine) {
-    return machineEntry.run(args);
+    return meterCommand(machineEntry.name, VERSION, () => machineEntry.run(args));
   }
 
   if (args.version) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.54.0",
+  "version": "1.55.1",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/commands.mjs

@@ -25,6 +25,13 @@
 // event, and own their stdout (a host's JSON contract / JSON-RPC frames), so a
 // span's cost and an error message's bytes are both unacceptable there. They are
 // marked `machine` and dispatched before the usage branches.
+//
+// `traced: false` does NOT mean unmeasured. The dispatcher routes `machine`
+// commands through `meterCommand`, which emits the invocation COUNTER (with the
+// same identity attributes the traced commands carry) and no span, on a tighter
+// export budget. These two are the highest-volume entry points in the CLI, so
+// leaving them entirely silent meant the usage that dominates was the usage
+// nobody could see — a span each is still the wrong trade, a counter is not.
 
 import { install } from './install.mjs';
 import { uninstall } from './uninstall.mjs';

package/src/control.mjs

@@ -513,7 +513,7 @@ function projectDirFrom({ env, userConfig, repoConfig, root }) {
 // `store` override). Used by `migrate` so it works regardless of the active
 // mode. `home` is the per-user tier root; `project` is the opt-in repo tier.
 export function localStoreDirs(root = process.cwd(), env = process.env) {
-  const home = userConfigDir(env);
+  const home = homeRoot(env);
   const userConfig = readJson(path.join(home, 'config.json'));
   const repoConfig = readJson(path.join(root, '.lorekit.json'));
   return { home, project: projectDirFrom({ env, userConfig, repoConfig, root }) };
@@ -534,7 +534,7 @@ export function resolveDenies(root, { env = process.env } = {}) {
 
 // IO wrapper — load env + config files, derive the connection, then resolve.
 export function loadControl(root, { env = process.env } = {}) {
-  const home = userConfigDir(env);
+  const home = homeRoot(env);
   const userConfig = readJson(path.join(home, 'config.json'));
   const repoConfig = readJson(path.join(root, '.lorekit.json'));
   const conn = resolveProjectConnection(root, splitEndpoint);
@@ -545,9 +545,19 @@ export function loadControl(root, { env = process.env } = {}) {
   return resolveControl({ env, userConfig, repoConfig, connection, root, home });
 }
 
-// The per-user home tier root (also holds config.json): $LOREKIT_HOME, default
-// `~/.lorekit`. Moved from the old `~/.agent-memory` location.
-function userConfigDir(env) {
+/**
+ * The per-user home tier root (also holds config.json and telemetry-id.json):
+ * $LOREKIT_HOME, default `~/.lorekit`. Moved from the old `~/.agent-memory`
+ * location.
+ *
+ * Exported because `telemetry-identity.mjs` stores the install id in the same
+ * directory and must resolve it the SAME way. Re-deriving
+ * `LOREKIT_HOME || ~/.lorekit` there would put a second copy of this rule in
+ * the tree, and a drift between them would not fail loudly — it would mint a
+ * fresh "install" for a user who already had one, in a directory unrelated to
+ * their store.
+ */
+export function homeRoot(env = process.env) {
   return env.LOREKIT_HOME || path.join(os.homedir(), '.lorekit');
 }
 

package/src/deeplink-pure.mjs

@@ -131,6 +131,13 @@ export function loreScopeUrl(scope, opts = {}) {
 // own scope, coherent with the detail view. A lesson older than that window or
 // archived can still open blank — a dashboard-side limitation the link can't fix.
 // `scope` is the lesson's own scope. Pure.
+//
+// NOTE FOR ANYONE HAND-BUILDING A URL INSTEAD OF CALLING THIS: the `lesson`
+// param takes a JSON-encoded `{scope, key}`, NOT a memory id. If you hold the
+// `id` a write returned, the param is `?memoryId=<uuid>` (raw, not JSON-encoded).
+// `/lore` now also accepts a UUID in `?lesson=` so the wrong combination
+// resolves rather than silently doing nothing — but that is a safety net, and
+// this function is the thing to call when you have a scope and key.
 export function buildLessonUrl(scope, key, opts = {}) {
   const params = { lesson: { scope, key } };
   if (scope) params.scope = scope;

package/src/doctor.mjs

@@ -23,6 +23,7 @@ import {
   resolveTelemetryTokenSource,
   probeTelemetryExport,
 } from './telemetry.mjs';
+import { describeIdentity } from './telemetry-identity.mjs';
 import { deriveScope } from './scope.mjs';
 import { loadControl, HOOK_INSTRUCTION_EVENTS } from './control.mjs';
 import { createStore } from './store/index.mjs';
@@ -537,6 +538,23 @@ async function checkTelemetryExport(args, root, record) {
 
   record('info', 'telemetry', `export on → ${config.endpoint} ${c.dim(`(credential from ${source})`)}`);
 
+  // What identity the exported telemetry carries, and where it lives. Reported
+  // because the id is otherwise invisible: it is minted silently on first run,
+  // and a user who wants to see or reset it needs the path. `describeIdentity`
+  // never mints, so running `doctor` cannot itself create the file — the line
+  // below reads "not yet minted" on a machine that has only ever run `doctor`.
+  const identity = describeIdentity();
+  const linked = identity.accountId
+    ? `account ${identity.accountId}`
+    : 'no account linked yet — any authenticated command links it';
+  record(
+    'info',
+    'telemetry',
+    identity.installId
+      ? `identity: install ${identity.installId} · ${linked} ${c.dim(`(${identity.file} — delete to reset)`)}`
+      : `identity: not yet minted ${c.dim(`(will be written to ${identity.file})`)}`,
+  );
+
   // The probe writes a real span to a real backend — only on explicit request.
   if (!required) return;
 

package/src/mcp.mjs

@@ -26,6 +26,20 @@ export function buildRemoteUrl(endpoint, token) {
 
 let idCounter = 0;
 
+/**
+ * Response header naming the account the request authenticated as, set by the
+ * edge REST router for every non-service-role caller.
+ *
+ * The CLI's only way to know its own account id without a dedicated `/me`
+ * round-trip: it rides along on calls the CLI was making anyway. Cached by
+ * `RemoteStore._rest` so LOCAL, fully-offline runs can still report which
+ * account they belong to — see `telemetry-identity.mjs`.
+ *
+ * Kept in step with `CALLER_USER_ID_HEADER` in
+ * `supabase/functions/_shared/api/router.ts`.
+ */
+export const USER_ID_HEADER = 'x-lorekit-user-id';
+
 // Returns { ok, httpStatus, result, error, networkError }.
 //
 // `opts.traceparent` is an optional W3C traceparent header value (see
@@ -223,10 +237,20 @@ export async function restFetch(baseUrl, token, path, { method = 'GET', body, ti
     const text = await res.text();
     let data = null;
     try { data = text ? JSON.parse(text) : null; } catch { /* non-JSON body */ }
+    // The account this call authenticated as, as the server resolved it. Read on
+    // BOTH the success and failure paths: a 429 or a 404 is still an
+    // authenticated request, and rate-limited traffic is exactly when knowing
+    // whose it is matters most. Surfaced, not cached, here — `mcp.mjs` is in
+    // `control.mjs`'s import graph (`splitEndpoint`), and the identity module
+    // reads `homeRoot` from `control.mjs`, so importing it here would close an
+    // import cycle. `RemoteStore._rest` — the ONE caller of this function, so
+    // nothing is missed by doing it a layer out — does the caching.
+    const userId = res.headers?.get?.(USER_ID_HEADER) ?? null;
     if (!res.ok) {
       return {
         ok: false,
         httpStatus: res.status,
+        userId,
         // How long the server asked the caller to wait, in seconds, or null when
         // it did not say. Only a 429 carries one today (`tooManyRequests` sets
         // BOTH a `retryAfterSeconds` body field and the `Retry-After` header),
@@ -236,7 +260,7 @@ export async function restFetch(baseUrl, token, path, { method = 'GET', body, ti
         error: data?.error ? { message: data.error, code: data.code } : { code: res.status, message: text.slice(0, 200) || res.statusText },
       };
     }
-    return { ok: true, httpStatus: res.status, data };
+    return { ok: true, httpStatus: res.status, data, userId };
   } catch (e) {
     return { ok: false, networkError: String(e?.message ?? e) };
   } finally {

package/src/store/remote.mjs

@@ -19,6 +19,7 @@
 // no longer a transport for this store.
 // Zero-dependency.
 import { restFetch, mcpToRestBase } from '../mcp.mjs';
+import { rememberAccountId } from '../telemetry-identity.mjs';
 import { getActiveTraceparent } from '../telemetry.mjs';
 import { withReadFields } from './entry-fields.mjs';
 import { normalizeCreatedAt } from './created-at.mjs';
@@ -139,7 +140,26 @@ class RemoteStore {
 
   async _rest(path, opts = {}) {
     if (!this.usable()) return { ok: false, unusable: true };
-    return restFetch(this.restBase, this.token, path, { ...opts, traceparent: this._tp() });
+    const res = await restFetch(this.restBase, this.token, path, { ...opts, traceparent: this._tp() });
+    // Learn (and persist) which account this token belongs to, from the
+    // `X-LoreKit-User-Id` header the edge sets on every authenticated response.
+    // This is the ONE choke point for the CLI's remote traffic, so a single call
+    // site covers every command.
+    //
+    // Why cache it at all, when the server already knows: a run that never
+    // leaves the machine (`--offline`, the local two-tier store, `lorekit hook`)
+    // makes no request, so there is no server-side span to carry `auth.user_id`.
+    // Persisting it here is what lets THOSE runs report an account and join to
+    // server-side `usage_events` / `auth.user_id`.
+    //
+    // `rememberAccountId` is total, is a no-op when the value is unchanged, and
+    // never creates the identity file — so a user who opted out of telemetry
+    // gets nothing written even though they still receive the header. Guarded
+    // anyway so a store operation can never fail on a telemetry concern.
+    try {
+      rememberAccountId(res?.userId);
+    } catch { /* identity is an enrichment, never a precondition */ }
+    return res;
   }
 
   // ── Memory operations → REST ──────────────────────────────────────────────

package/src/telemetry-identity.mjs

@@ -0,0 +1,276 @@
+// LoreKit CLI — durable telemetry identity.
+//
+// The CLI's own OTLP export (src/telemetry.mjs) was, by construction,
+// unattributable: one span per command carrying the command name, a bounded
+// flag allow-list and the runtime/OS tuple, and nothing that linked two runs.
+// Server-side that gap does not exist — every authenticated REST/MCP call lands
+// on an edge root span carrying `auth.user_id`, and `usage_events` records the
+// same id — but a run that never leaves the machine (`--offline`, the two-tier
+// local store, `lorekit hook`) makes no server call at all, so 1000 local spans
+// could equally be one user or a thousand.
+//
+// This module closes that gap with TWO ids, because they answer different
+// questions and neither substitutes for the other:
+//
+//   • installId — a random, opaque, locally-minted id, persisted so it survives
+//     across runs. Always available once minted, including fully offline. It
+//     differentiates INSTALLS: the same person on a laptop and in CI is two
+//     ids, and two people sharing a container are one.
+//
+//   • accountId — the LoreKit account (Supabase auth UUID) the CLI last
+//     authenticated as, learned from the `X-LoreKit-User-Id` response header
+//     that `restFetch` reads off any authenticated call and cached here. Once
+//     learned it is stamped on EVERY later run, offline ones included, which is
+//     what makes local CLI usage joinable to server-side `auth.user_id` and
+//     `usage_events.user_id`.
+//
+// PRIVACY — this runs on end-users' machines, so the invariants matter more
+// than the feature:
+//
+//   1. Nothing is minted, and NO FILE IS EVER CREATED, while telemetry is
+//      disabled. `ensureInstallId` takes the resolved config and returns null
+//      when export is off, so an opt-out (LOREKIT_TELEMETRY=0, DO_NOT_TRACK=1,
+//      `telemetry.disabled`) never gets a tracking id written to their disk.
+//   2. `rememberAccountId` only ever UPDATES an existing file — it never
+//      creates one. The file exists only where (1) already minted an install
+//      id, so an opted-out user's account id is not recorded either, even
+//      though the header is on every response they receive.
+//   3. The install id is opaque and carries nothing derived from the machine —
+//      no hostname, no MAC, no username, no path. It is random, so it says
+//      "these runs are the same install" and nothing else about who that is.
+//   4. It is a plain file the user owns and can inspect or delete; `doctor`
+//      prints its location for exactly that reason. Deleting it resets the
+//      install identity, which is the whole opt-out-after-the-fact story.
+//
+// Everything here is TOTAL: an unreadable file, an unwritable home, a corrupt
+// JSON body and a full disk all degrade to "no identity" rather than throwing.
+// Telemetry must never be the thing that breaks a command — the same contract
+// `exportInvocation` holds.
+
+import process from 'node:process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { homeRoot } from './control.mjs';
+import { writeFileAtomic } from './config.mjs';
+
+/** Filename under the home tier. Sits beside `config.json` and the local store. */
+const IDENTITY_FILE = 'telemetry-id.json';
+
+/**
+ * Absolute path to the identity file: `$LOREKIT_HOME/telemetry-id.json`,
+ * defaulting to `~/.lorekit/telemetry-id.json`.
+ *
+ * Resolved through `homeRoot` — the SAME function that resolves the home-tier
+ * store and `config.json` — rather than re-deriving `LOREKIT_HOME || ~/.lorekit`
+ * here. A duplicated path resolution is not like the duplicated regexes
+ * elsewhere in the zero-dep CLI: if the two drifted, the id would silently land
+ * in a different directory than the store it belongs to, minting a "new install"
+ * for a user who had one all along.
+ *
+ * @param {object} [env] defaults to process.env
+ */
+export function identityPath(env = process.env) {
+  return path.join(homeRoot(env), IDENTITY_FILE);
+}
+
+/**
+ * Read the stored identity, or an empty object. TOTAL — a missing file, an
+ * unreadable one, a corrupt body, or a body that is valid JSON but not an
+ * object all yield `{}`.
+ *
+ * The `typeof` guards are not defensive noise: `JSON.parse('null')`,
+ * `JSON.parse('42')` and `JSON.parse('"x"')` all succeed, and a non-string
+ * `installId` reaching an attribute bag would be emitted as `String(value)` —
+ * so `{"installId": {}}` would ship the literal `[object Object]` as an
+ * identity and quietly fold every such install into one bucket.
+ *
+ * @param {string} [file] defaults to {@link identityPath}
+ * @returns {{ installId?: string, accountId?: string }}
+ */
+export function readIdentity(file = identityPath()) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    const out = {};
+    if (typeof parsed.installId === 'string' && parsed.installId) out.installId = parsed.installId;
+    if (typeof parsed.accountId === 'string' && parsed.accountId) out.accountId = parsed.accountId;
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Persist an identity object, creating the home directory if needed.
+ * Returns true on success, false on any failure (unwritable home, full disk).
+ *
+ * @param {{ installId?: string, accountId?: string }} identity
+ * @param {string} [file] defaults to {@link identityPath}
+ */
+function writeIdentity(identity, file = identityPath()) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify(identity, null, 2)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mint a fresh install id: 32 random hex characters.
+ *
+ * Deliberately opaque and machine-independent. A hostname- or MAC-derived id
+ * would be stable without a file, but it would also be a fingerprint the user
+ * cannot reset and one that leaks their machine into a span attribute.
+ */
+export function mintInstallId() {
+  const b = new Uint8Array(16);
+  // The WebCrypto global, as in telemetry.mjs — see the note there on why this
+  // is used unqualified rather than imported from `node:crypto`.
+  crypto.getRandomValues(b);
+  return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Resolve the install id, minting and persisting one on first use.
+ *
+ * Returns null — no identity, same as today's behaviour — when:
+ *   • telemetry export is disabled (`config.enabled !== true`). This is the
+ *     opt-out invariant: no id is minted and no file is created.
+ *   • the id could not be persisted. An id that cannot be stored would be a
+ *     DIFFERENT value on every run, which is strictly worse than none: it
+ *     inflates the distinct-install count to equal the invocation count and is
+ *     indistinguishable, in the data, from that many real installs. A read-only
+ *     home therefore reports no identity rather than a misleading one.
+ *
+ * @param {{ enabled?: boolean }} config  the resolved telemetry config
+ * @param {object} [opts]
+ * @param {string} [opts.file] defaults to {@link identityPath}
+ * @returns {string | null}
+ */
+export function ensureInstallId(config, { file = identityPath() } = {}) {
+  // Delegates rather than repeating the mint-and-persist logic: two copies of
+  // "read, mint if absent, preserve accountId, bail if unwritable" is two places
+  // for the opt-out invariant to be broken independently.
+  return ensureIdentity(config, { file }).installId;
+}
+
+/**
+ * Resolve the full identity for a run — install id (minted on first use) plus
+ * any cached account id — in ONE file read.
+ *
+ * The single entry point callers should use. `ensureInstallId` reads the file
+ * and so did a follow-up `readIdentity()` for the account id, which put two
+ * reads of the same small file on `lorekit hook`'s per-turn path for no reason.
+ *
+ * Same contract as {@link ensureInstallId}: nothing is minted and no file is
+ * created while export is disabled, and a non-persistable id reports as no
+ * identity rather than as a fresh one per run.
+ *
+ * @param {{ enabled?: boolean }} config  the resolved telemetry config
+ * @param {object} [opts]
+ * @param {string} [opts.file] defaults to {@link identityPath}
+ * @returns {{ installId: string | null, accountId: string | null }}
+ */
+export function ensureIdentity(config, { file = identityPath() } = {}) {
+  if (!config || config.enabled !== true) return { installId: null, accountId: null };
+  const stored = readIdentity(file);
+  const accountId = stored.accountId ?? null;
+  if (stored.installId) return { installId: stored.installId, accountId };
+  const installId = mintInstallId();
+  // Preserve any accountId already cached — a corrupt-but-partial file should
+  // not lose the account linkage on the run that repairs the install id.
+  if (!writeIdentity({ ...stored, installId }, file)) return { installId: null, accountId: null };
+  return { installId, accountId };
+}
+
+/**
+ * Cache the LoreKit account id the CLI just authenticated as.
+ *
+ * Called from `restFetch` for every authenticated response that carries an
+ * `X-LoreKit-User-Id` header — so the id is learned on any remote call and then
+ * available to every later run, including offline ones.
+ *
+ * NEVER CREATES THE FILE. It writes only when a file with an install id already
+ * exists, which is exactly the set of machines where telemetry was enabled and
+ * minted one. That is what keeps an opted-out user's account id off their disk
+ * without threading the telemetry config all the way into the HTTP layer.
+ *
+ * A no-op when the value is unchanged, so the common case is one read and no
+ * write. Returns true only when something was actually persisted.
+ *
+ * @param {string | null | undefined} accountId
+ * @param {object} [opts]
+ * @param {string} [opts.file] defaults to {@link identityPath}
+ */
+export function rememberAccountId(accountId, { file = identityPath() } = {}) {
+  if (typeof accountId !== 'string' || !accountId) return false;
+  const stored = readIdentity(file);
+  if (!stored.installId) return false; // no file / telemetry never enabled
+  if (stored.accountId === accountId) return false;
+  return writeIdentity({ ...stored, accountId }, file);
+}
+
+/**
+ * The identity RESOURCE attribute, or `{}` when there is no identity.
+ *
+ * `service.instance.id` is the OTel semconv key for "which instance of this
+ * service produced the telemetry", which is exactly what an install is — so the
+ * install id belongs on the resource under the standard key rather than under a
+ * `lorekit.*` one a backend has no built-in understanding of. Distinct installs
+ * are then countable with no LoreKit-specific knowledge.
+ *
+ * @param {{ installId?: string | null }} identity
+ */
+export function identityResourceAttributes({ installId } = {}) {
+  return installId ? { 'service.instance.id': installId } : {};
+}
+
+/**
+ * The identity attribute for a CLI span / metric data point, or `{}` when there
+ * is no identity to report.
+ *
+ * `user.id` is the ACCOUNT when one is known, else `install:<installId>`. This
+ * mirrors the browser RUM decision (`web/src/lib/dash0-rum.ts`: an `anon:<uuid>`
+ * upgraded in place to the real id), so a backend that folds `user.id` into
+ * unique-user analytics answers "how many PEOPLE use the CLI" — collapsing one
+ * person's laptop and CI runs into one user — while `service.instance.id` on the
+ * resource still tells those installs apart underneath. The `install:` prefix
+ * keeps a pre-auth run visibly distinct from a real account id instead of
+ * silently occupying the same value space.
+ *
+ * CARDINALITY: this rides on the `lorekit.cli.invocations` counter as well as
+ * the span, so the counter's series count is multiplied by the number of
+ * distinct users. That is inherent to being able to differentiate them at all,
+ * and it is bounded by real adoption rather than by anything a caller controls
+ * — but it is the reason no FURTHER identity dimension belongs on the metric.
+ *
+ * @param {{ installId?: string | null, accountId?: string | null }} identity
+ */
+export function identityAttributes({ installId, accountId } = {}) {
+  if (!installId) {
+    // No install id means nothing was persisted (opted out, or unwritable
+    // home). An accountId alone is not emitted: it can only have come from a
+    // file that also holds an installId, so this branch means "no identity".
+    return {};
+  }
+  return { 'user.id': accountId || `install:${installId}` };
+}
+
+/**
+ * Read-only view of the identity for `doctor` to report: what is stored, where,
+ * and whether an account has been linked yet. Never mints anything, so running
+ * `doctor` cannot itself create the file.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.file] defaults to {@link identityPath}
+ */
+export function describeIdentity({ file = identityPath() } = {}) {
+  const stored = readIdentity(file);
+  return {
+    file,
+    installId: stored.installId ?? null,
+    accountId: stored.accountId ?? null,
+  };
+}

package/src/telemetry.mjs

@@ -12,10 +12,19 @@
 //   • Opt-out honored: LOREKIT_TELEMETRY=0|off|false|no|disable, or the
 //     cross-vendor DO_NOT_TRACK=1, disables all export.
 //   • No PII is ever attached: only the command name, a bounded allow-list of
-//     boolean flags, the CLI/runtime/OS identity, and the outcome. Never a
-//     path, cwd, token, endpoint, repo, or scope string.
+//     boolean flags, the CLI/runtime/OS identity, the outcome, and the durable
+//     telemetry identity described below. Never a path, cwd, token, endpoint,
+//     repo, or scope string.
 //   • Disabled outright when no OTLP endpoint resolves.
 //
+// IDENTITY — runs are attributable, which they deliberately were not before.
+// `telemetry-identity.mjs` supplies an opaque, locally-minted install id
+// (`service.instance.id` on the resource) and, once any authenticated call has
+// taught the CLI which account it is, that account on `user.id`. Read that
+// module's header for the invariants; the one that constrains THIS file is that
+// nothing is minted while export is disabled, so `ensureInstallId` is only ever
+// called with an already-enabled config.
+//
 // The default endpoint + token below are baked into the published package and
 // are therefore public by design. The token MUST be Dash0 ingestion-only
 // (write/POST spans, no read/query/manage) — anyone can unpack the npm tarball
@@ -26,6 +35,11 @@
 import process from 'node:process';
 import { TELEMETRY_TOKEN } from './telemetry-token.mjs';
 import { readLorekitJson } from './config.mjs';
+import {
+  ensureIdentity,
+  identityAttributes,
+  identityResourceAttributes,
+} from './telemetry-identity.mjs';
 
 // ── Baked-in defaults (public by design) ──────────────────────────────────────
 // The endpoint is a committed default; the token is injected at publish time
@@ -231,7 +245,7 @@ export function resolveDeploymentEnvironment(env = process.env) {
   return value || undefined;
 }
 
-function resourceAttributes(version, env = process.env) {
+function resourceAttributes(version, env = process.env, identity = {}) {
   const attrs = [
     { key: 'service.name', value: { stringValue: 'cli' } },
     { key: 'service.namespace', value: { stringValue: 'lorekit' } },
@@ -243,6 +257,12 @@ function resourceAttributes(version, env = process.env) {
   ];
   const deploymentEnv = resolveDeploymentEnvironment(env);
   if (deploymentEnv) attrs.push({ key: 'deployment.environment.name', value: { stringValue: deploymentEnv } });
+  // `service.instance.id` — the install. Omitted entirely when there is no
+  // identity (opted out, or an unwritable home), never placeholdered: a
+  // constant stand-in would fold every such machine into one instance.
+  for (const [key, value] of Object.entries(identityResourceAttributes(identity))) {
+    attrs.push({ key, value: { stringValue: String(value) } });
+  }
   return attrs;
 }
 
@@ -332,11 +352,11 @@ export function commandAttributes({ command, args = {}, outcome, exitCode, extra
   return attrs;
 }
 
-export function buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId }) {
+export function buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId, identity }) {
   return {
     resourceSpans: [
       {
-        resource: { attributes: resourceAttributes(version) },
+        resource: { attributes: resourceAttributes(version, process.env, identity) },
         scopeSpans: [
           {
             scope: { name: 'cli', version: String(version) },
@@ -362,11 +382,11 @@ export function buildTracePayload({ version, name, attributes, startMs, endMs, s
   };
 }
 
-export function buildMetricsPayload({ version, attributes, startMs, endMs }) {
+export function buildMetricsPayload({ version, attributes, startMs, endMs, identity }) {
   return {
     resourceMetrics: [
       {
-        resource: { attributes: resourceAttributes(version) },
+        resource: { attributes: resourceAttributes(version, process.env, identity) },
         scopeMetrics: [
           {
             scope: { name: 'cli', version: String(version) },
@@ -396,6 +416,31 @@ export function buildMetricsPayload({ version, attributes, startMs, endMs }) {
   };
 }
 
+// ── Identity ──────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the durable telemetry identity for this run: the install id (minting
+ * and persisting one on first use) plus any account id a previous authenticated
+ * call cached.
+ *
+ * TOTAL and side-effect-free when export is off — `ensureInstallId` returns
+ * null for a disabled config without touching the disk, so the opt-out
+ * invariant holds here by delegation rather than by a second check that could
+ * drift from it.
+ *
+ * @param {{ enabled?: boolean }} config
+ * @returns {{ installId: string | null, accountId: string | null }}
+ */
+function resolveIdentity(config) {
+  try {
+    return ensureIdentity(config);
+  } catch {
+    // Identity is an enrichment, never a precondition. A failure here degrades
+    // to the pre-identity behaviour: telemetry still exports, unattributed.
+    return { installId: null, accountId: null };
+  }
+}
+
 // ── Export ────────────────────────────────────────────────────────────────────
 
 async function post(url, headers, payload, timeoutMs) {
@@ -420,16 +465,71 @@ async function post(url, headers, payload, timeoutMs) {
  * can never delay or fail the CLI. Awaited before process exit (Node would
  * otherwise drop the in-flight request), but capped at timeoutMs.
  */
-export async function exportInvocation(config, { version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId }, { timeoutMs = 1500 } = {}) {
+export async function exportInvocation(config, { version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId, identity }, { timeoutMs = 1500 } = {}) {
   if (!config || !config.enabled) return;
-  const trace = buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId });
-  const metric = buildMetricsPayload({ version, attributes, startMs, endMs });
+  // `user.id` rides on BOTH payloads: on the span so a trace is attributable,
+  // and on the counter data point so "distinct users who ran `search`" is
+  // answerable without touching traces at all.
+  const identified = { ...attributes, ...identityAttributes(identity) };
+  const trace = buildTracePayload({ version, name, attributes: identified, startMs, endMs, status, statusMessage, traceId, spanId, identity });
+  const metric = buildMetricsPayload({ version, attributes: identified, startMs, endMs, identity });
   await Promise.all([
     post(`${config.endpoint}/v1/traces`, config.headers, trace, timeoutMs),
     post(`${config.endpoint}/v1/metrics`, config.headers, metric, timeoutMs),
   ]);
 }
 
+/**
+ * Export ONLY the invocation counter — no span — for the machine-facing
+ * commands (`hook`, `mcp`).
+ *
+ * These are the highest-volume entry points by a wide margin: `hook` fires on
+ * every agent turn, several times per turn. They were `traced: false` and so
+ * emitted nothing at all, which meant the identity work above would have
+ * differentiated users across the human-facing commands while the traffic that
+ * actually dominates stayed invisible.
+ *
+ * Metric-only, and on a much tighter budget than {@link exportInvocation}, for
+ * three reasons specific to this path:
+ *   • A span per hook invocation would be a firehose of near-identical traces
+ *     for no analytical gain over a counter — the question here is "how much,
+ *     by whom", not "what happened inside this one".
+ *   • `hook` and `mcp` own stdout as a machine contract (the host parses it),
+ *     and `traceCommand`'s 1500 ms export budget sits between the command
+ *     finishing and the process exiting. On a per-turn hook that is a latency
+ *     the user feels; {@link METERED_TIMEOUT_MS} is the cap that keeps it
+ *     imperceptible, accepting a dropped data point over a delayed agent.
+ *   • Nothing here is allowed to change the exit code or stdout, so every
+ *     failure path returns quietly.
+ *
+ * @param {object} config  resolved telemetry config
+ * @param {string} command  `hook` | `mcp`
+ * @param {string} version  CLI version
+ * @param {object} [extraAttrs]  bounded extra dimensions (e.g. the hook event)
+ */
+export async function countInvocation(config, command, version, extraAttrs = {}) {
+  if (!config || !config.enabled) return;
+  const identity = resolveIdentity(config);
+  const now = Date.now();
+  const attributes = {
+    ...commandAttributes({ command, outcome: CLI_OUTCOMES.OK, extraAttrs }),
+    ...identityAttributes(identity),
+  };
+  await post(
+    `${config.endpoint}/v1/metrics`,
+    config.headers,
+    buildMetricsPayload({ version, attributes, startMs: now, endMs: now, identity }),
+    METERED_TIMEOUT_MS,
+  );
+}
+
+/**
+ * The export budget for the metric-only machine-facing path. Deliberately much
+ * shorter than the 1500 ms default: this sits on the agent's per-turn critical
+ * path, so a slow collector must cost a data point, not a visible stall.
+ */
+export const METERED_TIMEOUT_MS = 400;
+
 /**
  * Send ONE synthetic span to the configured OTLP endpoint and report what the
  * collector said about it.
@@ -551,6 +651,54 @@ function normalizeExitCode(result) {
   return result ?? 0;
 }
 
+/**
+ * Run a MACHINE-facing command (`hook`, `mcp`) and count the invocation —
+ * counter only, no span. Returns the command's exit code unchanged.
+ *
+ * The export is STARTED BEFORE the command runs and awaited after, so it
+ * overlaps the command's own work instead of being serialized behind it. That
+ * ordering is what makes this affordable on `hook`, which fires several times
+ * per agent turn: by the time there is anything to await, the POST has usually
+ * already completed, and {@link METERED_TIMEOUT_MS} caps the worst case.
+ *
+ * It also makes the count robust for `mcp`, which is a LONG-LIVED stdio server —
+ * `run()` does not return until the server exits, and a killed server would
+ * never have reported at all if the export waited for it. Since the counter
+ * reports the invocation rather than its outcome (a machine-facing command's
+ * verdict belongs to its stdout contract, which the host reads), there is
+ * nothing to learn by waiting.
+ *
+ * Nothing here can affect the command: the exit code is passed through
+ * untouched, and every telemetry failure is swallowed.
+ *
+ * @param {string} command  `hook` | `mcp`
+ * @param {string} version  CLI version
+ * @param {() => Promise<number>} run  the command handler
+ */
+export async function meterCommand(command, version, run) {
+  let config;
+  try {
+    config = resolveTelemetryConfig();
+  } catch {
+    config = { enabled: false };
+  }
+
+  // Fast path — no export configured. The overwhelmingly common case for these
+  // two commands (the baked-in token is absent in the source tree), so it must
+  // cost nothing at all: no identity read, no timer, no promise.
+  if (!config.enabled) return normalizeExitCode(await run());
+
+  // `.catch` attached IMMEDIATELY, before any await: an unawaited rejecting
+  // promise is an unhandled rejection, which on a machine-facing command would
+  // print to stderr and pollute a host's log.
+  const pending = countInvocation(config, command, version).catch(() => {});
+  try {
+    return normalizeExitCode(await run());
+  } finally {
+    await pending;
+  }
+}
+
 /**
  * Time a human-facing command, record its outcome, and export one span + one
  * counter point. Returns the command's exit code unchanged. Telemetry failures
@@ -601,6 +749,14 @@ export async function traceCommand(command, args, version, run) {
     }
   }
 
+  // Resolved once, before the command runs, so the export in `finally` cannot
+  // pay for a first-run mint on the crash path — and so a command that itself
+  // learns the account id (any remote call, via `restFetch`) does not race the
+  // read. A run that learns it for the first time reports `install:<id>` and the
+  // NEXT run reports the account; one deliberately-late run beats a mid-command
+  // re-read whose result depends on which subcommand happened to phone home.
+  const identity = resolveIdentity(config);
+
   const startMs = Date.now();
   let exitCode = 0;
   // `outcome` is the command's VERDICT (ok | failure | error); `status` is the
@@ -673,6 +829,7 @@ export async function traceCommand(command, args, version, run) {
         statusMessage,
         traceId: _activeTraceId,
         spanId: _activeSpanId,
+        identity,
       });
     } catch {
       // never let telemetry break the CLI