## Summary
Replaces the random-UUID telemetry `distinct_id` with a stable
per-machine id derived from the host fingerprint, so PostHog's native
"Unique users" counts machines (funnels / retention / breakdowns work
with no HogQL). Every Argent entry point - installer, CLI, tool-server,
MCP - derives the id from one shared code path, so a given machine
reports a single identity across every event and across install /
uninstall / reinstall.
## What changed
- `distinct_id = uuidv5(hostFingerprint, NAMESPACE)`, where the
fingerprint comes from `simulator-server fingerprint`. Deterministic,
keeps the UUID shape, and never stores the raw hardware value in PostHog
(only the SHA-1-derived UUID leaves the process).
- The fingerprint is resolved in `buildPayload` - the single `capture()`
path shared by every entry point - so installer / CLI / tool-server /
MCP all produce the same id. Resolved lazily, once per process,
memoized.
- One-time, local-only migration: the first time a fingerprint resolves,
`~/.argent/telemetry-id` is rewritten from the legacy random UUID to the
derived id. No PostHog `alias` / `$identify` event is emitted.
- Fallback: if the fingerprint can't be resolved (unsupported platform,
binary absent), the stored or a fresh random UUID is used - identically
for every entry point on that machine, self-healing to the derived id on
the next successful resolve.
- Hardening: never throws; the fingerprint is validated (exactly 64 hex,
case-insensitive) before hashing; corrupt / empty / unreadable id files
self-heal; the binary is spawned at most once per process.
## Why the id is stable across install -> uninstall -> reinstall
Uninstall deletes `~/.argent/telemetry-id`. Because the id is
`uuidv5(fingerprint)` and the fingerprint is deterministic per machine,
a fresh install recomputes the identical id. Previously only the
tool-server resolved the fingerprint while the installer emitted under a
random UUID, so this cycle produced a different random id each time.
## Bundling note for reviewers
`@argent/telemetry` now depends on `@argent/native-devtools-ios` to
locate the binary. That package computes its bin dir from `__dirname` at
module load, which is undefined in an ES module. The installer / CLI /
MCP ship as ESM bundles, so `bundle-tools.cjs`'s ESM banner is extended
to shim `__dirname` / `__filename` (the CJS tool-server bundle already
has them natively). Without this shim those bundles would crash on load,
so the banner change is load-bearing.
## Testing
- Unit: 219 telemetry tests - RFC 4122 v5 vectors, migration,
idempotency, case/length validation, corrupt-file self-heal,
spawn-at-most-once, and all fallbacks.
- E2E on a real machine + booted iPhone 16 Pro: installer, CLI, and
tool-server runtimes all emit the same derived id; the id is stable
across a delete/recreate (uninstall/reinstall) cycle; a legacy v4 id
migrates locally with no alias/identify emitted; verified from an ESM
bundle placed in the real install's `dist/` so the binary resolves via
the bundled `__dirname` with no env override; tool calls against the
device carry the same id.
## Summary
Fixes telemetry attribution for tools dispatched by orchestrators.
`run-sequence`,
`flow-execute`, and `flow-add-step` run their steps via
`registry.invokeTool()`
directly, which minted a fresh, unregistered invocation id per nested
call — so the
`ai_client` / `platform` the HTTP layer captured for the outer request
never reached
the nested gestures, and they were recorded as **anonymous** in
telemetry.
Remove `opt_out` event that is a leftover.
## Changes
- Add an optional `recordChildInvocation` recorder to
`InvokeToolOptions` /
`ToolContext`, bound by the HTTP layer to the outer request's
attribution.
- New `invokeSubTool` helper: registers each sub-tool under a minted id
inheriting
the request's AI client, with the platform re-derived from the
sub-tool's **own**
device arg (`udid` / `device_id` / `avdName`); forwards the recorder so
propagation
survives arbitrary nesting (e.g. `flow-execute → run-sequence →
gesture-tap`).
- Route the three orchestrators' sub-dispatch through
- Refactor platform inference in the HTTP layer into a shared
`platformFromArgs`
helper (also hardened to not throw on a malformed device arg).
- Remove opt_out event leftover
Why re-derive platform per child: an orchestrator like `flow-execute`
has no platform
of its own and a single flow can target several devices, so the child's
device arg is
the only correct platform source; the parent's platform is the fallback.
Hubert Gancarczyk