Hivemind turns agent traces into skills and shares with your team

Summary

Generates a machine-stable install_id (UUID v4) on first hivemind install, persists to ~/.deeplake/install-id (mode 0600), and sends it as the X-Hivemind-Install-Id header on /auth/device/code and /auth/device/token. Pairs with the companion deeplake-api PR (activeloopai/deeplake-api#239) that uses this header as the anonymous PostHog distinct_id, collapsing all install attempts from the same machine onto one anon Person.

Why

Today every hivemind install retry mints a fresh OAuth device_code → backend hashes that into a fresh hivemind_intent_<hash> anon distinct_id → fresh anonymous PostHog Person. One user × 5 retries = 5 orphan anon Persons, only one of which (the attempt whose device flow completes) gets aliased to the user's identified Auth0 ID. The other 4 sit forever inflating the funnel denominator.

With a stable install_id, all attempts from one machine share one anon Person; on completion that one Person merges with the identified user. Clean Person identity, accurate funnel.

Design notes

• install-id.ts is a fs-only module (no fetch imports), following the same static-analysis split as auth-creds.ts. The reason for the split is documented in auth-creds.ts — per-file rules flag fs+fetch co-occurrence.
• Lazy homedir() accessor (not bound at module load) so tests can flip process.env.HOME between cases against a single module instance. Same pattern as auth-creds.ts; the rationale (V8 coverage-merge flake from vi.resetModules + dynamic re-import) is documented there.
• Graceful degradation: if the file can't be read OR written (e.g. read-only $HOME, unusual permissions), getOrCreateInstallID() returns "" and hivemindInstallIDHeader() returns {} — the network code spreads it into the headers object as a no-op, so the request still goes out and the backend falls back to its pre-install-id behavior. No CLI flow ever breaks because of install-id issues.
• Corrupt on-disk values are rotated: a strict UUID regex validates the file content; anything else triggers regenerate-and-persist.

Test plan

• [x] tsc --noEmit clean
• [x] 9 new unit tests pass (tests/claude-code/install-id.test.ts):
  • Generate + persist on first call
  • Stability across repeated calls
  • Reuse of existing valid on-disk ID
  • Rotation of corrupt value
  • Whitespace trimming
  • File mode 0600 (POSIX-only)
  • Header shape correct
  • Header + getOrCreateInstallID share state
  • Empty header when ~/.deeplake is unwritable
• [x] Existing auth-creds.test.ts still passes (no regression on the sibling module)
• [ ] Manual after merge: clean install on a fresh $HOME, verify ~/.deeplake/install-id is created, verify PostHog signup_intent event carries install_id property AND distinct_id = "hivemind_install_<uuid>"

Notes for reviewer

• The header name X-Hivemind-Install-Id and the file path ~/.deeplake/install-id are coordinated with deeplake-api PR #239. Renaming either requires synchronized change there.
• This PR is the consumer side. The backend has a graceful fallback for older CLIs that don't send the header, so the order of release doesn't matter for safety. It DOES matter for analytics: ideally the backend ships first so that when this CLI release goes out, signup_intents start landing under stable IDs immediately. If this ships first while the backend hasn't yet read the header, we just send a no-op header and the backend behaves identically to today.
• The bundle/build-time tests in this repo (which check for embed-daemon.js, capture.js etc. in the built artifact) were failing pre-PR on a fresh worktree without npm run build. Source-level tests cover the change here; bundle/runtime verification happens in the standard CI build step.

Summary by CodeRabbit

• New Features

  • Added machine-stable install ID that persists locally on first use and is sent with device authorization requests
  • System gracefully handles unavailable storage by omitting the header when necessary

• Tests

  • Added comprehensive test suite validating install ID generation, persistence, and error handling

Live E2E test plan (run against locally-built CLI + locally-built deeplake-api)

Companion to activeloopai/deeplake-api#239. Each repo's PR linked from the other.

Setup

# 1. Build this CLI bundle from the worktree
cd ~/al-projects/hivemind-worktrees/install-id
ln -sf ~/al-projects/hivemind/node_modules ./node_modules
npm run build
grep -c 'X-Hivemind-Install-Id' bundle/cli.js   # should print 1

# 2. Boot the companion deeplake-api locally with the install-id-reading code
#    (see deeplake-api PR #239 for that setup)

# 3. Fresh sandbox HOME so install-id file is generated by THIS PR's code
SANDBOX=/tmp/hivemind-install-id-test-$(date +%s)
mkdir -p "$SANDBOX/.claude"

Test A — fresh install on a clean machine

HOME=$SANDBOX HIVEMIND_API_URL=http://localhost:8080 \
  node ~/al-projects/hivemind-worktrees/install-id/bundle/cli.js install --only claude

Sign in with an existing account at the verification URL.

| Assertion | Result |
|-----------|--------|
| ~/.deeplake/install-id created in sandbox, mode 0600, contents valid UUID v4 | ✓ 3b46129e-8ec5-4c40-b3db-bcd739005cab |
| signup_intent.distinct_id = hivemind_install_<that-uuid> (NOT the legacy hivemind_intent_<sha>) | ✓ |
| Backend received X-Hivemind-Install-Id header on /auth/device/code AND /auth/device/token | ✓ (alias and login_completed both used install-id-derived anon) |

Test B — second install from same machine, install-id reused

# Keep install-id file, drop creds so device flow re-triggers
rm $SANDBOX/.deeplake/credentials.json
HOME=$SANDBOX HIVEMIND_API_URL=http://localhost:8080 \
  node ~/al-projects/hivemind-worktrees/install-id/bundle/cli.js install --only claude

Sign in again.

Critical assertion (the entire point of this PR):

| Assertion | Result |
|-----------|--------|
| Install-id file unchanged between attempts | ✓ 3b46129e-... same UUID |
| Second signup_intent.distinct_id equals first | ✓ both = hivemind_install_3b46129e-8ec5-4c40-b3db-bcd739005cab |
| Total anonymous PostHog Persons created for the user: 1, not 2 | ✓ — proven by both events sharing the same distinct_id |

Without this PR, the two attempts would produce two distinct hivemind_intent_<sha256> IDs (different device_codes → different hashes), creating two orphan anon Persons. This PR collapses them.

Backward compatibility

The deeplake-api side falls back to its pre-install-id behavior (hivemind_intent_<sha256(device_code)>) when the X-Hivemind-Install-Id header is absent. So:

• Old hivemind + new deeplake-api: works (backend uses device_code hash, as today)
• New hivemind + old deeplake-api: works (backend ignores the unknown header)
• New hivemind + new deeplake-api: install-id collapsing kicks in

Either repo can ship first without breaking anything.