Add bounded CLI and Hub usage telemetry for 0.8.1

.github/workflows/ci.yml

@@ -46,6 +46,9 @@ jobs:
       - run: npm ci
       - run: npm run typecheck
       - run: npm run test
+      - name: Test isolated telemetry benchmark transport
+        if: matrix.node-version == '22.22.0'
+        run: npm run benchmark:telemetry:test
       - name: Run evaluator tests
         if: matrix.node-version == '22.22.0'
         run: npm run eval:test
@@ -102,6 +105,11 @@ jobs:
           src/team/workflow/__tests__/repository-team-workflow-port.test.ts
           test/team-inbox-spec-authoring-real.contract.test.ts
           test/capabilities.test.ts
+          test/telemetry.test.ts
+          test/telemetry-delivery.test.ts
+          test/telemetry-context-schema.test.ts
+          test/telemetry-project-context.test.ts
+          test/telemetry-project-capture.test.ts
           src/logging/__tests__/policy.test.ts
           src/wiki/operations/__tests__/durability.test.ts
           src/wiki/operations/__tests__/identity-precision.test.ts

.mex/ROUTER.md

@@ -152,6 +152,23 @@ Then read this file fully before doing anything else in this session.
   all memory and other limits stay unchanged. A clean enforcing run on the new
   calibrated head remains required. Local same-code memory/latency evidence is
   retained in `docs/design/graph-isolation-diagnostic.json`.
+- Graph performance PR #180 passed the final checks (run `34291831733`) and
+  merged into `codex/0.8.1` as `d64f171`; the preceding calibration notes are
+  historical. Main remains separate.
+- Telemetry v2 is implemented on `codex/0.8.1-telemetry`, based on that merge,
+  and shared in draft PR #188 targeting `codex/0.8.1`. Local verification and
+  latency evidence for `9cbfab8` are retained. The follow-up context additions
+  pass 353 focused tests, typecheck/build and a separate actual-CLI benchmark;
+  fresh full and platform CI remains required. The approved random installation UUID is shared
+  across CLI and Hub. The user additionally approved existing scaffold UUIDs
+  for shared-project estimates and configured AI-tool names from project setup;
+  these cannot establish team size or identify the invoking agent. The bounded
+  reader never creates or repairs project identity. Content, paths, queries,
+  names, repository remotes, and contact data remain outside the event catalog.
+  Namespaced CLI outcomes, explicit Hub actions/pages, and terminal jobs use a
+  bounded per-user queue and cancellable delivery. Pure discovery/read commands
+  remain quiet. CLI feedback uses the existing Hub hosted form without an
+  analytics identity. See `docs/design/telemetry-v2.md` for validation status.
 - Targeted graph get/query/impact consumers use one provenance-bound immutable
   snapshot and discard output if graph or exact source identity changes.
 - The graph half of Checkpoint 2 is working in the Project Hub: grouped symbol

.mex/context/architecture.md

@@ -23,7 +23,7 @@ edges:
 # Broad overview: keep this empty unless a claim depends on a few specific symbols.
 # Entry shape: { node: "function:<tier-1-id>", fingerprint: "mh:64:<hex>" }
 grounds_to: []
-last_updated: 2026-09-06
+last_updated: 2026-09-09
 mex:
   id: mx_01M1M0CJ5C5XQV0HM5VM787WQS
   type: architecture
@@ -99,7 +99,7 @@ revision: 1
   can use Claude Code, Codex, or OpenCode, and prompt-only fallback works with
   any file-reading agent.
 - A local browser connects only to the loopback Project Hub and exchanges a one-use bootstrap token for a private session.
-- **posthog-node** — optional anonymous CLI telemetry; disabled for the development repository and by `DO_NOT_TRACK=1` or `MEX_TELEMETRY=0`.
+- **PostHog ingestion** — optional pseudonymous CLI/Hub events share one random installation UUID. A bounded read-only configuration snapshot can add the existing scaffold UUID for shared-project estimates and known configured AI-tool names; it never identifies the invoking agent or creates project identity. Names, remotes, paths, content, queries, and contact details remain excluded. A bounded per-user outbox and cancellable Node HTTP transport replace the SDK. Development checkouts and opt-out controls disable collection/delivery; see `TELEMETRY.md`.
 
 <!-- mex:entity
 id: mx_01M1M0CJ1E1X7BW1Q7PMGPVCRC

.mex/context/setup.md

@@ -82,7 +82,7 @@ revision: 1
 ## Environment Variables
 
 - No environment variable is required for normal local CLI/library operation.
-- `MEX_TELEMETRY=0` or `DO_NOT_TRACK=1` (optional) — disable anonymous telemetry; the development repository also disables it automatically.
+- `MEX_TELEMETRY=0` or `DO_NOT_TRACK=1` (optional) — disable pseudonymous CLI/Hub telemetry; the development repository also disables it automatically.
 - `MEX_HOME` (optional) — override the base directory used for global MEX configuration, primarily for isolation in tests.
 - `MEX_DEV` (optional) — force development-repository behavior, including telemetry suppression.
 - `MEX_ENFORCE_RELEASE_BUDGETS=1` (release CI only) — enforce the pinned release resource budgets on the calibrated runner.

.mex/patterns/INDEX.md

@@ -4,6 +4,7 @@ Lookup table for project-specific pattern files.
 
 | Pattern | Use when |
 |---------|----------|
+| [`usage-telemetry.md`](usage-telemetry.md) | Changing CLI/Hub event coverage, opt-out, queue delivery, or usage measurement |
 | [`contract-first-external-adapter.md`](contract-first-external-adapter.md) | Freezing a consumer port before an independently owned implementation is pinned |
 | [`fresh-graph-hub-integration.md`](fresh-graph-hub-integration.md) | Connecting a real graph read or maintenance capability to the local Project Hub |
 | [`local-first-team-state.md`](local-first-team-state.md) | Adding canonical team artifacts, read-only repository observations, or per-user SQLite state |

.mex/patterns/usage-telemetry.md

@@ -0,0 +1,100 @@
+---
+name: usage-telemetry
+description: Extend CLI and Hub usage measurement without leaking product data or delaying command exit.
+triggers:
+  - telemetry
+  - command outcomes
+  - retention analytics
+edges:
+  - target: context/conventions.md
+    condition: Before changing a capture, delivery, or persistence boundary
+  - target: patterns/release-performance-gate.md
+    condition: When evaluating a material command or Hub resource regression
+last_updated: 2026-09-09
+---
+
+# Usage telemetry
+
+## Context
+
+Read `TELEMETRY.md`, `docs/design/telemetry-v2.md`, and the closed catalog in
+`src/telemetry/schema.ts`. The shared random installation ID is approved for
+CLI/Hub repeat-use measurement. The user also approved the existing scaffold
+UUID for shared-project estimates and the project's configured AI-tool names.
+Neither installation counts nor shared scaffold IDs establish team size.
+Contact details belong to the separate voluntary hosted form, with no
+installation or scaffold ID appended.
+
+## Steps
+
+1. State the product question and denominator. Separate attempts, successful
+   completion, previews, applied changes, replay, and background job completion.
+2. Add only fixed names and bounded approved properties to the central catalog.
+   Project context permits an existing UUIDv4 and a sorted, unique selection of
+   at most six known AI-tool names. Never spread config, request bodies,
+   arguments, error objects, URLs, or other IDs.
+3. Capture from registered CLI command ancestry or a validated Hub server action.
+   Derive page categories locally. Pure discovery/read contracts, Hub polling,
+   SSE and idle timers must not manufacture engagement events.
+4. Preserve opt-out checks before capture and send. Keep inspection non-mutating.
+   Revalidate persisted data before transport; wrong schema/unsafe paths fail quiet.
+5. Preserve bounded delivery and cleanup. Test sockets/DNS and actual process
+   close, not only a Promise timeout around a fake sender. Do not introduce a
+   detached sender, unbounded queue, blocking lock, or retry loop.
+
+## Gotchas
+
+- `process.exit()` skips cleanup. Preserve action exit codes using normal return;
+  complete once in postAction or the main error/finally path, never both.
+- Atomic rename alone does not prevent a stale feedback/notice writer from
+  replacing an opt-out preference. Preserve the dedicated opt-out marker,
+  which only explicit enable removes.
+- A started event without completion can mean abrupt termination or delivery
+  loss. It does not prove product failure. Original timestamps/UUIDs survive retry.
+- A CLI command may finish before its final event can be sent. Later eligible use
+  drains the bounded queue. Seven-day expiry is enforced on subsequent access;
+  without a daemon, an untouched disk file may physically remain longer.
+- A request timeout alone is insufficient if unresolved DNS or referenced sockets
+  keep Node alive. Run the built CLI against a real hanging loopback endpoint.
+- For a cancellation test, await the actual loopback request/query before
+  timing the flush. Fixed setup sleeps can put first-use transport initialization
+  inside the cancellation interval. Preserve the production grace and elapsed
+  limit, and assert real cancellation, stopped queries and retained queue data.
+- Fixtures should inject a silent sink. Tests that enable telemetry must isolate
+  `MEX_HOME`, redirect only to loopback, and deny all other egress.
+- Read project metadata through the bounded, non-mutating telemetry reader;
+  never mint a scaffold ID to fill an event. Ordinary CLI operations reuse one
+  snapshot; setup/init can reread at completion after saving configuration.
+  Hub metadata stays fixed from its first enabled event until restart.
+- Match each command's actual project selection. Graph maintenance/status use
+  their exact root with local `--root` before parent `--root`; they must not
+  borrow an ancestor scaffold. Hub capture uses its bound project root exactly.
+  Ordinary commands retain their nearest-Git-root discovery behavior.
+- `configured_ai_tools` describes project setup, not the invoking agent.
+  Allow multiple selected tools without process/account probing. Missing or
+  malformed configuration omits context; unknown tool names never enter events.
+- Count distinct installations per scaffold over a stated window, such as 28
+  completed UTC days, and label two or more as a shared-project estimate.
+  One person's several machines and copied scaffold IDs can inflate it;
+  shared installations can hide it. Anyone with project config access can
+  associate its UUID with that project.
+
+## Verify
+
+Run focused catalog/privacy/outbox/opt-out/CLI/Hub tests, then typecheck and the
+appropriate integrated tests/build. Use `benchmark:telemetry:test` for harness
+safety and `benchmark:telemetry` with a preserved baseline for paired latency.
+Do not run other builds/tests during timing. Keep raw measurements and report
+local timing separately from pinned CI gates.
+
+## Debug
+
+Use `mex telemetry inspect` without creating state. Check opt-out precedence,
+queue availability, catalog rejection, request cancellation and expired claims.
+Do not fix missing events by capturing arguments/content or relaxing bounds.
+
+## Update scaffold
+
+Update the catalog documentation, metric definitions and `.mex/ROUTER.md` when
+coverage or guarantees change. Preserve existing grounding evidence; telemetry
+work does not authorize graph refresh or baseline acceptance.

README.es.md

@@ -386,17 +386,17 @@ Las estructuras de Markdown existentes siguen siendo válidas y las lecturas del
 
 MEX no sube sus registros canónicos, Graph, índice de la Wiki, borradores, selección de identidad ni sesiones de Hub a un servicio de MEX. No ofrece transporte automático entre miembros del equipo: el contenido se comparte mediante las operaciones habituales de Git que tú realizas. Hub escucha en la interfaz de loopback y la capa de recuperación local de MEX no requiere credenciales de modelos.
 
-MEX tiene **telemetría seudónima de uso de la CLI**, activada por defecto salvo que la desactives. Cada invocación que cumpla las condiciones envía como máximo un evento. Los campos permitidos por MEX son un identificador aleatorio de la máquina, el nombre del comando, la versión de MEX, el sistema operativo, la versión de Node y, cuando existe una identidad disponible, un identificador de la estructura de MEX; el SDK de PostHog también añade metadatos con el nombre y la versión de su biblioteca. MEX no añade argumentos de comandos, rutas de archivos, nombres de repositorios, contenido de archivos ni direcciones IP al contenido enviado, aunque el servicio receptor puede observar los metadatos habituales del transporte.
+MEX tiene **telemetría seudónima de uso de la CLI y del Hub**, activada por defecto salvo que la desactives. Registra nombres de comandos, resultados, acciones explícitas del Hub, categorías de páginas y resultados de trabajos. Ambos usan un UUID aleatorio de instalación para medir el uso recurrente. Cuando están disponibles, también se envían el UUID existente del scaffold para estimar el uso compartido de un proyecto y los nombres de las herramientas de IA seleccionadas en su configuración; estos datos no identifican al agente que ejecuta el comando ni demuestran el tamaño de un equipo. Quien tenga acceso a la configuración puede asociar el UUID del scaffold con ese proyecto. No se envían nombres, remotos de repositorios, argumentos, rutas, contenido, búsquedas ni datos de contacto. El servicio receptor puede observar los metadatos habituales del transporte. Una cola local limitada y una espera breve al terminar la CLI permiten posponer el envío sin cambiar el resultado del comando.
 
 Consulta o desactiva la telemetría con:
 
 ```bash
 mex telemetry inspect
 mex telemetry status
-mex config set telemetry off
+mex telemetry disable
 ```
 
-También puedes desactivarla con `MEX_TELEMETRY=0` o `DO_NOT_TRACK=1`. Consulta la [política de telemetría](https://github.com/mex-memory/mex/blob/v0.8.0/TELEMETRY.md) para conocer los controles y el contenido exacto que se envía. Los agentes de programación conectados a MEX pueden tener su propio comportamiento de red y telemetría; eso depende de esas herramientas, no de MEX.
+También puedes desactivarla con `MEX_TELEMETRY=0` o `DO_NOT_TRACK=1`. Consulta la [política de telemetría](TELEMETRY.md) para conocer los controles y el contenido exacto que se envía. Los agentes de programación conectados a MEX pueden tener su propio comportamiento de red y telemetría; eso depende de esas herramientas, no de MEX.
 
 <a id="what-mex-is-not"></a>
 

README.md

@@ -373,17 +373,17 @@ Existing Markdown scaffolds remain valid, and Graph reads never migrate a store
 
 MEX does not upload its canonical records, Graph, Wiki index, drafts, identity selection, or Hub sessions to a MEX service. It provides no automatic team transport: sharing happens through normal Git actions you perform. The Hub binds to loopback, and MEX's local retrieval layer requires no model credentials.
 
-MEX has **pseudonymous CLI usage telemetry**, enabled by default unless you opt out. An eligible invocation sends at most one event. MEX's allowlisted fields are a random machine identifier, command name, MEX version, operating system, Node version, and—when an existing identity is available—a scaffold identifier; the PostHog SDK also adds its library name/version metadata. MEX does not add command arguments, file paths, repository names, file contents, or IP addresses to the payload, though the ingestion service can observe ordinary transport metadata.
+MEX has **pseudonymous CLI and Hub usage telemetry**, enabled by default unless you opt out. Namespaced commands, outcomes, explicit Hub actions, page categories, and job results help measure feature use and returning installations. Both surfaces reuse one random installation UUID. When available, events also include the existing scaffold UUID to estimate shared-project use and configured AI-tool names from project setup; these do not identify the currently invoking agent or prove team size. Someone with access to project configuration can associate its scaffold UUID with that project. Names, repository remotes, argument values, paths, content, search text, and contact details stay excluded. The ingestion service can observe ordinary transport metadata. Delivery uses a bounded local queue and short CLI cleanup grace; offline telemetry does not change command results.
 
 Check or disable telemetry with:
 
 ```bash
 mex telemetry inspect
 mex telemetry status
-mex config set telemetry off
+mex telemetry disable
 ```
 
-It can also be disabled with `MEX_TELEMETRY=0` or `DO_NOT_TRACK=1`. See the [telemetry policy](https://github.com/mex-memory/mex/blob/v0.8.0/TELEMETRY.md) for the controls and exact payload. Coding agents connected to MEX may have their own network and telemetry behavior; that is governed by those tools, not by MEX.
+It can also be disabled with `MEX_TELEMETRY=0` or `DO_NOT_TRACK=1`. See the [telemetry policy](TELEMETRY.md) for the controls, event catalog, privacy boundary, and delivery limits. Coding agents connected to MEX may have their own network and telemetry behavior; that is governed by those tools, not by MEX.
 
 ## What MEX is not
 

README.pt-BR.md

@@ -386,17 +386,17 @@ As estruturas existentes em Markdown continuam válidas, e as consultas ao Graph
 
 O MEX não envia seus registros canônicos, Graph, índice da Wiki, rascunhos, seleção de identidade ou sessões do Hub para um serviço MEX. Ele não oferece transporte automático entre integrantes da equipe: o compartilhamento acontece pelas ações normais do Git que você executa. O Hub escuta no endereço de loopback, e a camada local de consulta do MEX não exige credenciais de modelo.
 
-O MEX tem **telemetria pseudônima de uso da CLI**, ativada por padrão, a menos que você a desative. Uma execução elegível envia no máximo um evento. Os campos permitidos pelo MEX são um identificador aleatório da máquina, nome do comando, versão do MEX, sistema operacional, versão do Node e — quando uma identidade existente está disponível — um identificador da estrutura MEX; o SDK do PostHog também acrescenta metadados com o nome e a versão de sua biblioteca. O MEX não inclui argumentos de comandos, caminhos de arquivos, nomes de repositórios, conteúdo de arquivos ou endereços IP nos dados enviados, embora o serviço de ingestão possa observar os metadados normais de transporte.
+O MEX tem **telemetria pseudônima de uso da CLI e do Hub**, ativada por padrão, a menos que você a desative. Registra nomes de comandos, resultados, ações explícitas do Hub, categorias de páginas e resultados de tarefas. Ambos usam um UUID aleatório da instalação para medir o uso recorrente. Quando disponíveis, também são enviados o UUID existente do scaffold para estimar o uso compartilhado de um projeto e os nomes das ferramentas de IA selecionadas na configuração; esses dados não identificam o agente que executa o comando nem comprovam o tamanho da equipe. Quem tem acesso à configuração pode associar o UUID do scaffold àquele projeto. Não são enviados nomes, remotos de repositórios, argumentos, caminhos, conteúdo, pesquisas ou dados de contato. O serviço receptor pode observar metadados normais de transporte. Uma fila local limitada e uma breve espera ao encerrar a CLI permitem adiar o envio sem alterar o resultado do comando.
 
 Confira ou desative a telemetria com:
 
 ```bash
 mex telemetry inspect
 mex telemetry status
-mex config set telemetry off
+mex telemetry disable
 ```
 
-Ela também pode ser desativada com `MEX_TELEMETRY=0` ou `DO_NOT_TRACK=1`. Consulte a [política de telemetria](https://github.com/mex-memory/mex/blob/v0.8.0/TELEMETRY.md) para conhecer os controles e os dados exatos enviados. Os agentes de programação conectados ao MEX podem ter seus próprios comportamentos de rede e telemetria; isso é regido por essas ferramentas, não pelo MEX.
+Ela também pode ser desativada com `MEX_TELEMETRY=0` ou `DO_NOT_TRACK=1`. Consulte a [política de telemetria](TELEMETRY.md) para conhecer os controles e os dados exatos enviados. Os agentes de programação conectados ao MEX podem ter seus próprios comportamentos de rede e telemetria; isso é regido por essas ferramentas, não pelo MEX.
 
 <a id="what-mex-is-not"></a>