openmerit 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.9 — 2026-10-24
+
+- Add opt-in coding-agent installation milestones, component/connection diagnostics and consent-gated setup/installation correlation retained across resumed approval and upgrades. Carry browser usage and unlink choices into setup; keep standalone CLI analytics default-off and MCP prompt-content capture off.
+- Add bounded installation-event retries with stable delivery IDs. Report verification and remote revocation failures even when existing local command exit semantics remain successful.
+- Coordinate the independently released Scout browser/device/MCP lifecycle telemetry, correct HTTP-200 logical-error accounting, and distinguish key authorization from verified installation. These are observed events, not skipped-call detection, guaranteed delivery or downstream model-execution tracking.
+- Preserve existing package exports, model-decision guidance and legal metadata. Existing installations need an installer rerun; npm publication does not deploy Scout or the main website.
+
 ## 0.1.8 — 2026-10-24
 
 - Install an owned startup rule requiring Scout before explicit or implicit application-model choices, including pretrained/local/browser models, weight downloads and SDK defaults. Keep detailed access-policy and search instructions in the skill. These instructions are guidance, not hard enforcement.

package/dist/terminal/src/install.mjs

@@ -1,10 +1,11 @@
 import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { homedir, hostname } from 'node:os';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { openBrowser } from './browser.mjs';
+import { clientVersion, setupHeaders, setupUUID, sendInstallationEvent, setupCorrelationEnabled } from './telemetry.mjs';
 
 // One-command coding-agent setup: device sign-in in the browser, then the MCP
 // server, startup rule and Scout skill. Built to be run by a person or by a coding agent:
@@ -101,10 +102,10 @@ expired or revoked, run \`npx -y openmerit@latest login\` and then
 
 export const help = `OpenMerit · coding-agent setup
 
-  openmerit install [--client claude-code] [--scope user|project] [--plan] [--json] [--no-open]
+  openmerit install [--client claude-code] [--scope user|project] [--setup-id UUID] [--plan] [--json] [--no-open]
   openmerit status  [--client claude-code] [--scope user|project] [--check] [--json]
   openmerit remove  [--client claude-code] [--scope user|project] [--plan] [--json]
-  openmerit login   [--json] [--no-open]     Replace this device's key
+  openmerit login   [--setup-id UUID] [--json] [--no-open]     Replace this device's key
   openmerit logout  [--json]                 Revoke this device's key
   openmerit project --policy existing-only|existing-first [--endpoint-id <id> ...] [--plan]
   openmerit doctor  [--json]
@@ -144,12 +145,12 @@ async function save(path, value) {
   await writeFile(path, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
 }
 
-async function request(path, { method = 'GET', body, key } = {}) {
+async function request(path, { method = 'GET', body, key, telemetry } = {}) {
   let response;
   try {
     response = await fetch(`${server()}${path}`, {
       method, redirect: 'error', signal: AbortSignal.timeout(15_000),
-      headers: { ...(body ? { 'Content-Type': 'application/json' } : {}), ...(key ? { Authorization: `Bearer ${key}` } : {}), 'X-Scout-Client': 'cli', 'X-Scout-Analytics-Content': 'off' },
+      headers: { ...(body ? { 'Content-Type': 'application/json' } : {}), ...(key ? { Authorization: `Bearer ${key}` } : {}), ...setupHeaders(telemetry?.properties) },
       ...(body ? { body: JSON.stringify(body) } : {}),
     });
   } catch { throw new Stop(`Could not reach ${server()}. Check your connection and retry.`, exitCodes.unreachable); }
@@ -177,7 +178,7 @@ function claudePaths(root, scope) {
   };
 }
 const configuredServer = (config, root, scope) => scope === 'user' ? config.mcpServers?.openmerit : config.projects?.[root]?.mcpServers?.openmerit;
-const serverConfig = key => ({ type: 'http', url: `${server()}/scout/mcp`, headers: { Authorization: `Bearer ${key}`, 'X-Scout-Analytics-Content': 'off' } });
+const serverConfig = (key, telemetry) => ({ type: 'http', url: `${server()}/scout/mcp`, headers: { Authorization: `Bearer ${key}`, ...setupHeaders(telemetry.properties, 'agent') } });
 const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value;
 const serverHash = value => value ? hash(JSON.stringify(canonical(value))) : null;
 
@@ -201,8 +202,9 @@ async function inspect(root, scope) {
   const projectFile = await object(join(root, '.mcp.json'));
   return {
     paths, record, owned, current, installedSkill, installedRule,
-    // A pending header hash covers an install interrupted between add and record.
-    serverOwned: !current || owned && (serverHash(current) === record.serverHash || !!record.pendingAuth && hash(current.headers?.Authorization ?? '') === record.pendingAuth),
+    // A full pending hash covers interruption without accepting edited headers.
+    // Keep pendingAuth compatibility for records from the earlier installer.
+    serverOwned: !current || owned && (serverHash(current) === record.serverHash || serverHash(current) === record.pendingServerHash || !!record.pendingAuth && hash(current.headers?.Authorization ?? '') === record.pendingAuth),
     skillOwned: installedSkill === null || owned && [record.skillHash, record.pendingSkill].includes(hash(installedSkill)),
     ruleOwned: installedRule === null || owned && record.version === 3 && [record.ruleHash, record.pendingRule].includes(hash(installedRule)),
     // The pre-release installer recorded its rule hash; only an unchanged rule is removed.
@@ -220,6 +222,15 @@ function conflicts(state) {
   return found;
 }
 
+function diagnostics(state) {
+  return {
+    installed: state.owned && !!state.current && state.serverOwned && state.installedSkill !== null && state.skillOwned && state.installedRule !== null && state.ruleOwned && !state.shadowed,
+    server_status: state.current ? state.serverOwned ? 'matches' : 'modified_or_unowned' : 'missing',
+    skill_status: state.installedSkill === null ? 'missing' : state.skillOwned ? 'matches' : 'modified_or_unowned',
+    rule_status: state.installedRule === null ? 'missing' : state.ruleOwned ? 'matches' : 'modified_or_unowned',
+  };
+}
+
 async function credentials() {
   const saved = await object(credentialsPath());
   return saved.version === 1 && saved.server === server() && typeof saved.key === 'string' ? saved : null;
@@ -227,33 +238,56 @@ async function credentials() {
 
 // Device login. Starts or resumes a login, waits a bounded time, and stores the
 // key only on disk. Never prints the key.
-async function login({ client, scope, open, log, wait }) {
+async function login({ client, scope, open, log, wait, telemetry }) {
+  await telemetry.step('login', 'started');
   let pending = await object(pendingPath());
   if (!(pending.server === server() && pending.expiresAt > Date.now() && typeof pending.deviceCode === 'string')) {
     const deviceName = (process.env.OPENMERIT_DEVICE_NAME ?? hostname()).replace(/[^\x20-\x7e]/g, '').slice(0, 64) || 'this device';
-    const { status, data } = await request('/connect/api/device', { method: 'POST', body: { client, scope, device_name: deviceName } });
+    const { status, data } = await request('/connect/api/device', { method: 'POST', body: { client, scope, device_name: deviceName }, telemetry });
     if (status !== 200 || !data.device_code) throw new Stop(data.error ?? `Could not start sign-in (HTTP ${status}).`, status === 429 ? exitCodes.unreachable : exitCodes.error);
-    pending = { server: server(), deviceCode: data.device_code, userCode: data.user_code, url: data.verification_uri_complete, interval: data.interval, expiresAt: Date.now() + data.expires_in * 1000, opened: false };
+    pending = { server: server(), deviceCode: data.device_code, userCode: data.user_code, url: data.verification_uri_complete, interval: data.interval, expiresAt: Date.now() + data.expires_in * 1000, opened: false, setup_id: telemetry.properties.setup_id, installation_id: telemetry.properties.installation_id };
     await save(pendingPath(), pending);
   }
+  const approvalURL = new URL(pending.url);
+  // Rebuild consent on every resume, so old query parameters cannot override a
+  // later refusal. Only opt-in setup IDs are ever sent to the approval page.
+  for (const key of ['setup_id', 'analytics', 'analytics_account']) approvalURL.searchParams.delete(key);
+  if (setupCorrelationEnabled() && setupUUID(telemetry.properties.setup_id)) approvalURL.searchParams.set('setup_id', telemetry.properties.setup_id);
+  // Browser usage consent is independent of CLI opt-in. Only an explicit
+  // cross-surface refusal disables it; account unlinking must not disable usage.
+  if (process.env.DO_NOT_TRACK === '1') approvalURL.searchParams.set('analytics', 'off');
+  if (process.env.OPENMERIT_ANALYTICS_ACCOUNT === 'off' || process.env.DO_NOT_TRACK === '1') approvalURL.searchParams.set('analytics_account', 'off');
+  pending = { ...pending, url: approvalURL.href, setup_id: telemetry.properties.setup_id, installation_id: telemetry.properties.installation_id };
+  await save(pendingPath(), pending);
   log(`Approve this device in your browser (opening it now):\n\n  ${pending.url}\n\n  Code: ${pending.userCode} (expires ${new Date(pending.expiresAt).toLocaleTimeString()})\n`);
+  await telemetry.step('browser_open', 'started');
   if (open && !pending.opened && !pending.openFailed) {
     // Only the approval page on the configured OpenMerit server may be opened.
-    const approvalPage = url => { const u = new URL(url); return `${u.origin}` === server() && u.pathname === '/connect' && [...u.searchParams.keys()].join() === 'code' && !u.username && !u.password && !u.hash; };
+    const approvalPage = url => {
+      const u = new URL(url);
+      return u.origin === server() && u.pathname === '/connect' && !!u.searchParams.get('code')
+        && [...u.searchParams.keys()].every(key => ['code', 'setup_id', 'analytics', 'analytics_account'].includes(key) && u.searchParams.getAll(key).length === 1)
+        && (!u.searchParams.has('setup_id') || setupUUID(u.searchParams.get('setup_id')))
+        && ['analytics', 'analytics_account'].every(key => !u.searchParams.has(key) || u.searchParams.get(key) === 'off')
+        && !u.username && !u.password && !u.hash;
+    };
     const opened = await openBrowser(pending.url, { allowed: approvalPage }).catch(() => false);
     pending = { ...pending, ...(opened ? { opened: true } : { openFailed: true }) };
     await save(pendingPath(), pending);
   }
+  await telemetry.step('browser_open', pending.opened ? 'ok' : pending.openFailed ? 'error' : 'pending');
+  await telemetry.step('login', 'started');
   // With the approval page open, keep waiting for the Approve click (inside a
   // coding agent's 10-minute command limit) so nobody has to rerun anything.
   // Without a browser, return soon so the agent can show the link.
   const deadline = Date.now() + (wait ?? (pending.opened ? 540 : 30)) * 1000;
   let interval = (pending.interval ?? 5) * 1000;
   for (;;) {
-    const { status, data } = await request('/connect/api/token', { method: 'POST', body: { device_code: pending.deviceCode } });
+    const { status, data } = await request('/connect/api/token', { method: 'POST', body: { device_code: pending.deviceCode }, telemetry });
     if (status === 200 && data.access_token) {
-      await save(credentialsPath(), { version: 1, server: server(), key: data.access_token, keyId: data.key_id, createdAt: new Date().toISOString() });
+      await save(credentialsPath(), { version: 1, server: server(), key: data.access_token, keyId: data.key_id, setup_id: telemetry.properties.setup_id, createdAt: new Date().toISOString() });
       await rm(pendingPath(), { force: true });
+      await telemetry.step('login', 'ok');
       return data.access_token;
     }
     if (data.error === 'slow_down') interval += 5000;
@@ -268,16 +302,20 @@ async function login({ client, scope, open, log, wait }) {
 }
 
 // A real MCP initialize and tool discovery with the stored key; no search.
-async function verify(key) {
-  const call = (id, method, params = {}) => request('/scout/mcp', { method: 'POST', key, body: { jsonrpc: '2.0', id, method, params } });
-  const init = await call(1, 'initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'openmerit-cli', version: '1' } });
-  if (init.status === 401) return 'key_rejected';
-  if (init.status !== 200 || !init.data.result) return 'failed';
-  const tools = await call(2, 'tools/list');
-  return tools.data.result?.tools?.some(tool => tool.name === 'scout_models') ? 'connected' : 'failed';
+async function verify(key, telemetry) {
+  await telemetry.step('verification', 'started');
+  const call = (id, method, params = {}) => request('/scout/mcp', { method: 'POST', key, telemetry, body: { jsonrpc: '2.0', id, method, params } });
+  const init = await call(1, 'initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'openmerit-cli', version: clientVersion ?? 'unknown' } });
+  let connection = init.status === 401 ? 'key_rejected' : 'failed';
+  if (init.status === 200 && init.data.result) {
+    const tools = await call(2, 'tools/list');
+    connection = tools.status === 401 ? 'key_rejected' : tools.status === 200 && tools.data.result?.tools?.some(tool => tool.name === 'scout_models') ? 'connected' : 'failed';
+  }
+  await telemetry.step('verification', connection === 'connected' ? 'ok' : 'error', { connection, ...(connection === 'connected' ? {} : { code: connection === 'key_rejected' ? 'access_denied' : 'command_error' }) });
+  return connection;
 }
 
-async function install(root, { client, scope, plan, open, log, wait }) {
+async function install(root, { client, scope, plan, open, log, wait, telemetry }) {
   const state = await inspect(root, scope);
   const found = conflicts(state);
   const changes = [
@@ -290,14 +328,19 @@ async function install(root, { client, scope, plan, open, log, wait }) {
   if (plan) return { action: 'install', applied: false, client, scope, changes, conflicts: found };
   if (found.length) throw new Stop(found.join('\n'), exitCodes.conflict, 'Nothing was changed.');
   await claude(['--version'], root);
+  if (setupCorrelationEnabled()) telemetry.properties.installation_id ??= randomUUID();
+  await telemetry.step('preflight', 'ok');
   let key = (await credentials())?.key;
   // A revoked or expired key gets a fresh sign-in instead of a broken install.
-  if (key && await verify(key) === 'key_rejected') { await rm(credentialsPath(), { force: true }); key = undefined; log('The saved device key is no longer valid; signing in again.'); }
-  key ??= await login({ client, scope, open, log, wait });
-  const next = serverConfig(key);
+  if (key && await verify(key, telemetry) === 'key_rejected') { await rm(credentialsPath(), { force: true }); key = undefined; log('The saved device key is no longer valid; signing in again.'); }
+  key ??= await login({ client, scope, open, log, wait, telemetry });
+  await telemetry.step('configuration', 'started');
+  const next = serverConfig(key, telemetry);
+  const ids = { setup_id: telemetry.properties.setup_id, installation_id: telemetry.properties.installation_id };
   // Record intent first so an interrupted install is repaired by rerunning.
-  await save(state.paths.record, { version: 3, scope, client, serverHash: serverHash(state.current), skillHash: state.installedSkill === null ? null : hash(state.installedSkill), ruleHash: state.installedRule === null ? null : hash(state.installedRule), pendingAuth: hash(next.headers.Authorization), pendingSkill: hash(skill), pendingRule: hash(rule) });
-  if (state.current?.url !== next.url || state.current?.headers?.Authorization !== next.headers.Authorization) {
+  await save(state.paths.record, { version: 3, scope, client, ...ids, serverHash: serverHash(state.current), skillHash: state.installedSkill === null ? null : hash(state.installedSkill), ruleHash: state.installedRule === null ? null : hash(state.installedRule), pendingServerHash: serverHash(next), pendingSkill: hash(skill), pendingRule: hash(rule) });
+  telemetry.properties.applied = true;
+  if (serverHash(state.current) !== serverHash(next)) {
     if (state.current) await claude(['mcp', 'remove', '--scope', state.paths.mcpScope, 'openmerit'], root, key);
     await claude(['mcp', 'add-json', '--scope', state.paths.mcpScope, 'openmerit', JSON.stringify(next)], root, key);
   }
@@ -307,8 +350,10 @@ async function install(root, { client, scope, plan, open, log, wait }) {
   // Record what Claude actually wrote, so later edits are detected precisely.
   const written = configuredServer(await object(state.paths.mcpFile), root, scope);
   if (!written) throw new Stop('Claude Code did not save the "openmerit" MCP server.', exitCodes.error, 'Run "openmerit doctor".');
-  await save(state.paths.record, { version: 3, scope, client, serverHash: serverHash(written), skillHash: hash(skill), ruleHash: hash(rule), installedAt: new Date().toISOString() });
-  const connection = await verify(key);
+  await save(state.paths.record, { version: 3, scope, client, ...ids, serverHash: serverHash(written), skillHash: hash(skill), ruleHash: hash(rule), installedAt: new Date().toISOString() });
+  await telemetry.step('configuration', 'ok', diagnostics(await inspect(root, scope)));
+  const connection = await verify(key, telemetry);
+  if (connection !== 'connected') telemetry.outcome = 'error';
   if (connection === 'key_rejected') throw new Stop('OpenMerit rejected this device key (expired or revoked).', exitCodes.denied, 'Run "openmerit login", then rerun install.');
   return { action: 'install', applied: true, client, scope, changes, connection,
     next: connection === 'connected'
@@ -316,37 +361,51 @@ async function install(root, { client, scope, plan, open, log, wait }) {
       : 'Installed, but the connection check failed. Run "openmerit doctor".' };
 }
 
-async function status(root, { client, scope, check }) {
+async function status(root, { client, scope, check, telemetry }) {
+  await telemetry.step('status', 'started');
   const state = await inspect(root, scope), saved = await credentials();
-  const installed = state.owned && !!state.current && state.serverOwned && state.installedSkill !== null && state.skillOwned && state.installedRule !== null && state.ruleOwned && !state.shadowed;
-  return { action: 'status', client, scope, installed, signedIn: !!saved,
-    server: state.current ? state.serverOwned ? 'matches' : 'modified_or_unowned' : 'missing',
-    skill: state.installedSkill === null ? 'missing' : state.skillOwned ? 'matches' : 'modified_or_unowned',
-    rule: state.installedRule === null ? 'missing' : state.ruleOwned ? 'matches' : 'modified_or_unowned',
-    conflicts: conflicts(state), connection: check && saved ? await verify(saved.key) : 'not_checked' };
+  const details = diagnostics(state), found = conflicts(state);
+  const connection = check && saved ? await verify(saved.key, telemetry) : 'not_checked';
+  telemetry.outcome = ['failed', 'key_rejected'].includes(connection) ? 'error' : found.length ? 'conflict' : details.installed ? 'ok' : 'not_installed';
+  await telemetry.step('status', telemetry.outcome, { ...details, connection });
+  return { action: 'status', client, scope, installed: details.installed, signedIn: !!saved,
+    server: details.server_status, skill: details.skill_status, rule: details.rule_status,
+    conflicts: found, connection };
 }
 
-async function revokeKey() {
+async function revokeKey(telemetry) {
   const saved = await credentials();
   if (!saved) return false;
-  const { status } = await request('/connect/api/keys/self', { method: 'DELETE', key: saved.key }).catch(() => ({ status: 0 }));
+  await telemetry.step('remove', 'started');
+  const { status } = await request('/connect/api/keys/self', { method: 'DELETE', key: saved.key, telemetry }).catch(() => ({ status: 0 }));
   await rm(credentialsPath(), { force: true });
+  if (status !== 200) telemetry.outcome = 'error';
+  await telemetry.step('remove', status === 200 ? 'ok' : 'error', status === 200 ? {} : {
+    code: status === 0 ? 'openmerit_unreachable' : status === 401 || status === 403 ? 'access_denied' : 'command_error',
+  });
   return status === 200;
 }
 
-async function remove(root, { client, scope, plan }) {
+async function remove(root, { client, scope, plan, telemetry }) {
+  await telemetry.step('remove', 'started');
   const state = await inspect(root, scope);
-  if (!state.owned) return { action: 'remove', applied: false, client, scope, changes: [], note: 'No OpenMerit installation by this installer in this scope.' };
+  if (!state.owned) {
+    telemetry.outcome = 'not_installed';
+    await telemetry.step('remove', 'not_installed');
+    return { action: 'remove', applied: false, client, scope, changes: [], note: 'No OpenMerit installation by this installer in this scope.' };
+  }
   const changes = [...(state.current && state.serverOwned ? [`Remove MCP server "openmerit" (${state.paths.mcpScope} scope)`] : []),
     ...(state.installedSkill !== null && state.skillOwned ? [`Delete ${state.paths.skill}`] : []),
     ...(state.installedRule !== null && state.ruleOwned ? [`Delete ${state.paths.rule}`] : []), 'Revoke and delete this device key'];
   const kept = [...(state.serverOwned ? [] : ['the edited "openmerit" MCP server']), ...(state.skillOwned ? [] : [state.paths.skill]), ...(state.ruleOwned ? [] : [state.paths.rule]), policyPath];
   if (plan) return { action: 'remove', applied: false, client, scope, changes, keeps: kept };
+  telemetry.properties.applied = true;
   if (state.current && state.serverOwned) await claude(['mcp', 'remove', '--scope', state.paths.mcpScope, 'openmerit'], root);
   if (state.installedSkill !== null && state.skillOwned) await rm(dirname(state.paths.skill), { recursive: true, force: true });
   if (state.installedRule !== null && state.ruleOwned) await rm(state.paths.rule, { force: true });
   await rm(state.paths.record, { force: true });
-  const revoked = await revokeKey();
+  const revoked = await revokeKey(telemetry);
+  await telemetry.step('remove', telemetry.outcome, diagnostics(await inspect(root, scope)));
   return { action: 'remove', applied: true, client, scope, changes, keeps: kept, keyRevoked: revoked };
 }
 
@@ -359,20 +418,23 @@ async function project(root, { policy, ids, plan }) {
   return { action: 'project', applied: !plan, path: policyPath, policy: value, note: 'Endpoint IDs limit discovery only; they do not prove access or authorize spending.' };
 }
 
-async function doctor(root, { scope }) {
+async function doctor(root, { scope, telemetry }) {
+  await telemetry.step('status', 'started');
   const checks = [];
   const add = (name, ok, detail) => checks.push({ name, ok, detail });
   const [major, minor] = process.versions.node.split('.').map(Number);
   add('node', major > 22 || major === 22 && minor >= 19, `Node.js ${process.versions.node} (22.19+ required)`);
   try { const { stdout } = await exec('claude', ['--version'], { timeout: 10_000 }); add('claude', true, stdout.trim().slice(0, 80)); }
   catch { add('claude', false, 'Claude Code (claude) is not on PATH'); }
-  const reach = await request('/scout/api/status').catch(error => ({ status: 0, error }));
+  const reach = await request('/scout/api/status', { telemetry }).catch(error => ({ status: 0, error }));
   add('openmerit', reach.status === 200, reach.status === 200 ? `${server()} reachable` : `${server()} unreachable`);
   const saved = await credentials();
   add('key', !!saved, saved ? `Device key ${saved.keyId ?? ''} stored in ${credentialsPath()}` : 'Not signed in. Run "openmerit install" or "openmerit login".');
-  if (saved && reach.status === 200) { const connection = await verify(saved.key); add('mcp', connection === 'connected', `MCP check: ${connection}`); }
+  if (saved && reach.status === 200) { const connection = await verify(saved.key, telemetry); add('mcp', connection === 'connected', `MCP check: ${connection}`); }
   const state = await inspect(root, scope).catch(() => null);
   if (state) add('install', state.owned && !!state.current && state.installedSkill !== null && state.installedRule !== null && !conflicts(state).length, state.owned ? conflicts(state).join(' ') || (state.current && state.installedSkill !== null && state.installedRule !== null ? `Installed (${scope} scope)` : 'Installation incomplete. Rerun "openmerit install".') : `Not installed in ${scope} scope`);
+  telemetry.outcome = checks.every(check => check.ok) ? 'ok' : 'error';
+  await telemetry.step('status', telemetry.outcome, { ...(state ? diagnostics(state) : {}), ...(reach.status === 200 ? {} : { code: 'openmerit_unreachable', connection: 'failed' }) });
   return { action: 'doctor', ok: checks.every(check => check.ok), checks };
 }
 
@@ -389,12 +451,39 @@ function render(result) {
   return lines.join('\n');
 }
 
-export async function main(args, { root = process.cwd(), print = console.log, printError = console.error } = {}) {
+export async function main(args, dependencies = {}) {
+  const telemetry = {
+    stage: 'started', outcome: 'ok',
+    properties: { command: ['install', 'status', 'remove', 'login', 'logout', 'project', 'doctor'].includes(args[0]) ? args[0] : 'unknown', agent: 'claude-code', scope: 'user', applied: false, installed: false, connection: 'not_checked' },
+    async step(stage, outcome, properties = {}) {
+      this.stage = stage;
+      if (outcome === 'ok') delete this.properties.code;
+      Object.assign(this.properties, properties);
+      await sendInstallationEvent({ ...this.properties, stage, outcome });
+    },
+    async fail(error) {
+      this.outcome = ({ 10: 'pending', 11: 'denied', 20: 'conflict' })[error.exit] ?? 'error';
+      const code = ({ 10: 'approval_pending', 11: 'access_denied', 20: 'install_conflict', 30: 'openmerit_unreachable' })[error.exit] ?? 'command_error';
+      await this.step(this.stage, this.outcome, { code, ...(this.stage === 'verification' ? { connection: error.exit === exitCodes.denied ? 'key_rejected' : 'failed' } : {}) });
+    },
+  };
+  try {
+    const code = await runMain(args, dependencies, telemetry);
+    await telemetry.step('completed', telemetry.outcome);
+    return code;
+  } catch (error) {
+    await telemetry.fail(error);
+    await telemetry.step('completed', telemetry.outcome);
+    throw error;
+  }
+}
+
+async function runMain(args, { root = process.cwd(), print = console.log, printError = console.error }, telemetry) {
   const [action, ...rest] = args;
   if (!action || rest.includes('--help') || rest.includes('-h')) { print(help); return exitCodes.ok; }
-  const options = { client: undefined, scope: 'user', plan: false, check: false, json: false, open: true, policy: undefined, ids: [] };
-  const allowed = { install: ['--client', '--scope', '--plan', '--json', '--no-open'], status: ['--client', '--scope', '--check', '--json'], remove: ['--client', '--scope', '--plan', '--json'],
-    login: ['--json', '--no-open'], logout: ['--json'], project: ['--policy', '--endpoint-id', '--plan', '--json'], doctor: ['--scope', '--json'] }[action];
+  const options = { client: undefined, scope: 'user', plan: false, check: false, json: false, open: true, policy: undefined, ids: [], telemetry };
+  const allowed = { install: ['--client', '--scope', '--setup-id', '--plan', '--json', '--no-open'], status: ['--client', '--scope', '--check', '--json'], remove: ['--client', '--scope', '--plan', '--json'],
+    login: ['--setup-id', '--json', '--no-open'], logout: ['--json'], project: ['--policy', '--endpoint-id', '--plan', '--json'], doctor: ['--scope', '--json'] }[action];
   if (!allowed) throw new Error('Unknown command. Run openmerit --help.');
   for (let i = 0; i < rest.length; i++) {
     const option = rest[i];
@@ -402,6 +491,7 @@ export async function main(args, { root = process.cwd(), print = console.log, pr
     const value = () => { const v = rest[++i]; if (v === undefined || v.startsWith('--')) throw new Error(`${option} needs a value.`); return v; };
     if (option === '--client') options.client = value();
     else if (option === '--scope') options.scope = value();
+    else if (option === '--setup-id') { options.setup_id = value(); if (!setupUUID(options.setup_id)) throw new Error('--setup-id must be a UUID v4.'); }
     else if (option === '--policy') options.policy = value();
     else if (option === '--endpoint-id') options.ids.push(value());
     else if (option === '--no-open') options.open = false;
@@ -418,17 +508,41 @@ export async function main(args, { root = process.cwd(), print = console.log, pr
   const wait = process.env.OPENMERIT_LOGIN_WAIT === undefined ? undefined : Number(process.env.OPENMERIT_LOGIN_WAIT);
   const log = text => (options.json ? printError : print)(text);
   try {
+    telemetry.properties.scope = options.scope;
+    // Hydrate correlation without creating identities or writing anything. A
+    // pending approval owns its setup ID even when the resumed command omits it.
+    if (['install', 'status', 'remove', 'doctor'].includes(action)) {
+      telemetry.stage = 'preflight';
+      const state = await inspect(root, options.scope);
+      Object.assign(telemetry.properties, diagnostics(state));
+      if (state.owned) for (const key of ['setup_id', 'installation_id']) if (setupUUID(state.record[key])) telemetry.properties[key] = state.record[key];
+    }
+    if (options.setup_id) telemetry.properties.setup_id = options.setup_id;
+    if (['install', 'login'].includes(action)) {
+      const saved = await credentials();
+      if (!telemetry.properties.setup_id && setupUUID(saved?.setup_id)) telemetry.properties.setup_id = saved.setup_id;
+      const pending = await object(pendingPath());
+      if (pending.server === server() && pending.expiresAt > Date.now() && typeof pending.deviceCode === 'string') {
+        if (setupUUID(pending.setup_id)) telemetry.properties.setup_id = pending.setup_id;
+        if (!telemetry.properties.installation_id && setupUUID(pending.installation_id)) telemetry.properties.installation_id = pending.installation_id;
+      }
+    }
+    await telemetry.step('started', 'started');
+    await telemetry.step('preflight', 'started');
     const result = action === 'install' ? await install(root, { ...options, log, wait })
       : action === 'status' ? await status(root, options)
       : action === 'remove' ? await remove(root, options)
       : action === 'project' ? await project(root, options)
       : action === 'doctor' ? await doctor(root, options)
-      : action === 'logout' ? { action, revoked: await revokeKey(), note: 'Signed out. This device key was revoked and deleted. Agents configured with it stop working until you run install again.' }
-      : (await revokeKey(), await rm(pendingPath(), { force: true }), await login({ client: 'claude-code', scope: 'user', open: options.open, log, wait }), { action, signedIn: true, note: 'Signed in. Run "openmerit install" again to give your coding agents the new key.' });
+      : action === 'logout' ? { action, revoked: await revokeKey(telemetry), note: 'Signed out. This device key was revoked and deleted. Agents configured with it stop working until you run install again.' }
+      : (await revokeKey(telemetry), await login({ client: 'claude-code', scope: 'user', open: options.open, log, wait, telemetry }), { action, signedIn: true, note: 'Signed in. Run "openmerit install" again to give your coding agents the new key.' });
+    if (result.conflicts?.length && telemetry.outcome !== 'error') { telemetry.outcome = 'conflict'; telemetry.properties.code = 'install_conflict'; }
+    if (options.plan) await telemetry.step(telemetry.stage, telemetry.outcome, { applied: false });
     print(options.json ? JSON.stringify({ ok: true, ...result }, null, 2) : render(result));
     return action === 'doctor' && !result.ok ? exitCodes.error : exitCodes.ok;
   } catch (error) {
     if (!(error instanceof Stop)) throw error;
+    await telemetry.fail(error);
     if (options.json) print(JSON.stringify({ ok: false, action, code: Object.keys(exitCodes).find(k => exitCodes[k] === error.exit), message: error.message, next: error.next }, null, 2));
     else printError([error.message, error.next].filter(Boolean).join('\n'));
     return error.exit;

package/dist/terminal/src/telemetry.mjs

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 
-let clientVersion;
+export let clientVersion;
 for (const path of ['../../../package.json', '../../../../package.json']) {
   try { const pkg = JSON.parse(readFileSync(new URL(path, import.meta.url), 'utf8')); if (pkg.name === 'openmerit') { clientVersion = pkg.version; break; } } catch {}
 }
@@ -31,6 +31,74 @@ const environment = () => ({ ...(clientVersion ? { client_version: clientVersion
 
 const anonymousId = randomUUID();
 export const telemetryEnabled = () => process.env.OPENMERIT_TELEMETRY === '1' && process.env.DO_NOT_TRACK !== '1';
+export const setupCorrelationEnabled = () => telemetryEnabled() && process.env.OPENMERIT_ANALYTICS_ACCOUNT !== 'off';
+export const setupUUID = value => typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+// Device/verifier traffic is CLI opt-in. Installed MCP usage retains its existing
+// default, but explicit privacy refusals must survive into future agent sessions.
+export function setupHeaders(ids = {}, client = 'cli') {
+  return {
+    'X-Scout-Client': client,
+    'X-Scout-Agent': 'claude-code',
+    ...(clientVersion ? { 'X-Scout-Client-Version': clientVersion } : {}),
+    'X-Scout-Analytics-Content': 'off',
+    ...(client === 'cli' ? { 'X-Scout-Analytics': telemetryEnabled() ? 'on' : 'off' } : process.env.DO_NOT_TRACK === '1' ? { 'X-Scout-Analytics': 'off' } : {}),
+    ...(process.env.OPENMERIT_ANALYTICS_ACCOUNT === 'off' || process.env.DO_NOT_TRACK === '1' ? { 'X-Scout-Analytics-Account': 'off' } : {}),
+    ...(setupCorrelationEnabled() && setupUUID(ids.setup_id) ? { 'X-Scout-Setup-Id': ids.setup_id } : {}),
+    ...(setupCorrelationEnabled() && setupUUID(ids.installation_id) ? { 'X-Scout-Installation-Id': ids.installation_id } : {}),
+  };
+}
+export function installationProperties(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const out = {};
+  const enums = {
+    stage: ['started', 'preflight', 'login', 'browser_open', 'configuration', 'verification', 'status', 'remove', 'completed'],
+    outcome: ['started', 'ok', 'error', 'pending', 'denied', 'conflict', 'not_installed'],
+    command: ['install', 'status', 'remove', 'login', 'logout', 'project', 'doctor', 'unknown'],
+    agent: ['claude-code'], scope: ['user', 'project'],
+    rule_status: ['matches', 'missing', 'modified_or_unowned'],
+    skill_status: ['matches', 'missing', 'modified_or_unowned'],
+    server_status: ['matches', 'missing', 'modified_or_unowned'],
+    connection: ['connected', 'failed', 'key_rejected', 'not_checked'],
+    code: ['command_error', 'approval_pending', 'access_denied', 'install_conflict', 'openmerit_unreachable'],
+  };
+  for (const [key, values] of Object.entries(enums)) {
+    if (input[key] === undefined && !['stage', 'outcome'].includes(key)) continue;
+    if (!values.includes(input[key])) return null;
+    out[key] = input[key];
+  }
+  for (const key of ['setup_id', 'installation_id']) if (setupUUID(input[key])) out[key] = input[key];
+  for (const key of ['applied', 'installed']) if (typeof input[key] === 'boolean') out[key] = input[key];
+  return out;
+}
+export async function sendInstallationEvent(input) {
+  if (!telemetryEnabled()) return;
+  const properties = installationProperties(input);
+  if (!properties) return;
+  if (!setupCorrelationEnabled()) { delete properties.setup_id; delete properties.installation_id; }
+  // One immutable envelope across a transient retry. A hard total deadline
+  // bounds awaited milestones even if the transport ignores cancellation.
+  const body = JSON.stringify({ event: 'scout_installation_step', event_id: randomUUID(), anonymousId, properties: { ...properties, ...environment() } });
+  const controller = new AbortController();
+  let timer;
+  try {
+    await Promise.race([
+      (async () => {
+        for (let attempt = 0; attempt < 2 && !controller.signal.aborted && telemetryEnabled(); attempt++) {
+          try {
+            const response = await fetch('https://openmerit.ai/scout/api/analytics', {
+              method: 'POST', headers: { 'Content-Type': 'application/json', ...setupHeaders(properties) },
+              body, signal: controller.signal, redirect: 'error',
+            });
+            await response.body?.cancel();
+            if (response.ok || response.status !== 429 && response.status < 500) return;
+          } catch { /* Only a bounded retry; never export error text. */ }
+        }
+      })(),
+      new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(); }, 1500); }),
+    ]);
+  } catch { /* Never affect setup, even if the transport ignores abort. */ }
+  finally { clearTimeout(timer); }
+}
 export const errorType = error => ['Error', 'TypeError', 'RangeError', 'SyntaxError', 'ReferenceError', 'URIError', 'EvalError', 'AggregateError', 'AbortError'].includes(error?.name) ? error.name : 'Error';
 export function terminalProperties(event, input) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
@@ -65,12 +133,13 @@ export function sendTerminalEvent(event, input) {
 }
 async function sendAnalytics(event, properties) {
   const controller = new AbortController();
+  const body = JSON.stringify({ event, event_id: randomUUID(), anonymousId, properties: { ...properties, ...environment() } });
   let timer;
   try {
     await Promise.race([
       Promise.resolve().then(() => fetch('https://openmerit.ai/scout/api/analytics', {
-        method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Scout-Client': 'cli', 'X-Scout-Analytics': 'on' },
-        body: JSON.stringify({ event, anonymousId, properties: { ...properties, ...environment() } }), signal: controller.signal, redirect: 'error',
+        method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Scout-Client': 'cli', 'X-Scout-Analytics': 'on', ...(process.env.OPENMERIT_ANALYTICS_ACCOUNT === 'off' ? { 'X-Scout-Analytics-Account': 'off' } : {}) },
+        body, signal: controller.signal, redirect: 'error',
       })).then(response => response.body?.cancel()),
       new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(); }, 750); timer.unref(); }),
     ]);
@@ -78,7 +147,8 @@ async function sendAnalytics(event, properties) {
   finally { clearTimeout(timer); }
 }
 
-// Consent is independent of terminal discovery. Never persist an identity.
+// Consent is independent of terminal discovery. Command identity is ephemeral;
+// the installer separately manages the owned installation's correlation IDs.
 export function commandTelemetry(args) {
   if (process.env.OPENMERIT_TELEMETRY !== '1' || process.env.DO_NOT_TRACK === '1') return async () => {};
   const started = performance.now();
@@ -90,12 +160,13 @@ export function commandTelemetry(args) {
   async function send(event, properties) {
     if (!telemetryEnabled()) return;
     const controller = new AbortController();
+    const body = JSON.stringify({ event, event_id: randomUUID(), anonymousId, properties: { ...properties, ...environment(), command_id } });
     let timer;
     try {
       await Promise.race([
         Promise.resolve().then(() => fetch('https://openmerit.ai/scout/api/analytics', {
-          method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Scout-Client': 'cli', 'X-Scout-Analytics': 'on' },
-          body: JSON.stringify({ event, anonymousId, properties: { ...properties, ...environment(), command_id } }),
+          method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Scout-Client': 'cli', 'X-Scout-Analytics': 'on', ...(process.env.OPENMERIT_ANALYTICS_ACCOUNT === 'off' ? { 'X-Scout-Analytics-Account': 'off' } : {}) },
+          body,
           signal: controller.signal, redirect: 'error',
         })).then(response => response.body?.cancel()),
         new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(); }, 750); }),

package/docs/inference-terminal.md

@@ -6,6 +6,8 @@ It reads existing evidence independently of inference. It does not call a model,
 
 ## Optional CLI product analytics
 
+**Coding-agent setup telemetry — npm 0.1.9:** opted-in setup adds stage/outcome/component/connection diagnostics and random setup/installation correlation, described in the [Scout lifecycle contract](scout.md#coding-agent-lifecycle-instrumentation-npm-019). Unlike the process-only terminal identity below, an opted-in setup stores its installation UUID in the existing ownership record and installed MCP headers for later calls. No paths, credentials, device names or task content are exported. The copied website prompt explicitly carries usage/unlink preferences; standalone commands still require `OPENMERIT_TELEMETRY=1`, and `DO_NOT_TRACK=1` overrides it. Plans and status checks do not create an installation identity. Older npm 0.1.8 installations need an installer rerun; hosted browser/server collection requires the matching independent Scout deployment.
+
 Available in npm 0.1.7. CLI product analytics are off unless `OPENMERIT_TELEMETRY=1`; `DO_NOT_TRACK=1` always disables them. Terminal `discovery` configuration and `--no-discovery` are unrelated to analytics consent.
 
 When explicitly enabled, the CLI posts `cli_command_started` and `cli_command_completed` to `https://openmerit.ai/scout/api/analytics`, with a fresh `crypto.randomUUID()` identity for that process only. No identity file, cookie, or installation ID is stored. Properties contain only a command category (`help`, `dash`, `eval_init`, `eval_doctor`, `eval_plan`, `eval_run`, `eval_watch`, `eval_report`, or `unknown`), plus completion outcome (`ok` or `error`) and integer elapsed milliseconds capped at one day. Paths, arguments, prompts, configuration, model IDs, error text, environment contents, machine names, and email are not included.

package/docs/scout-data-policy.md

@@ -1,8 +1,10 @@
 # Scout beta data policy
 
-Updated 23 October 2026.
+Updated 24 October 2026.
 
-**Coding-agent reset, 23 October 2026:** this build removes Scout's coding-agent backend and setup/connection tracking. The Claude Code panel is a web-only placeholder with no installation or authentication flow. MCP and agent OAuth metadata routes return HTTP 404 in this build; the website, browser sign-in and JSON API remain. Earlier MCP references below describe the policy before this reset. Existing analytics records and remote grants are not deleted by this reset. A source-only replacement adds device sign-in: Scout stores the approving account, device name you chose (the host name by default), client, scope, timestamps and hashes of device codes and keys, but never a key itself. It is not deployed yet.
+**Coding-agent setup, 24 October 2026:** hosted Scout supports device sign-in and MCP; stable npm 0.1.8 installs Claude Code's MCP configuration, startup rule and Scout skill after approval. This supersedes the 23 October web-placeholder reset. Scout stores the approving account, device name you chose (the host name by default), client, scope, timestamps and hashes of device codes and keys, but never a plaintext key. Local setup stores the key in private configuration; external coding agents have their own data handling. Installation and startup guidance do not guarantee an agent will invoke Scout.
+
+**Lifecycle telemetry — npm 0.1.9 and matching Scout deployment:** this revision adds consent-gated setup-click, clipboard/launch-request, device-authorization, installation/component-verification and MCP-invocation diagnostics. Linked setup uses random setup and installation UUIDs to correlate those milestones; the local ownership record and installed MCP headers retain them across sessions/upgrades. Unlinked mode omits these IDs. Copied setup prompts carry usage/unlink preferences into installation, while standalone CLI telemetry remains opt-in and DNT overrides it. Installed MCP prompt-content capture remains off. The revision also adds bounded delivery retries and sanitized Cloudflare delivery counters, without identity, content, URLs, device codes or credentials in those counters. Existing installations need an installer rerun; these changes do not backfill earlier activity. See the [lifecycle contract](scout.md#coding-agent-lifecycle-instrumentation-npm-019). Release acceptance is recorded separately.
 
 **Version-5 diagnostics:** Scout serving builds collect page views/leaves, bounded engagement, allowlisted acquisition/UTM and browser/device categories, and sampled browser performance observations where supported and usage analytics is enabled. Native URL properties use only reconstructed public paths, never raw visitor URLs, queries or fragments. Linked activity can join same-tab visits, signup and searches; unlinking retains request-only server identity, not a cross-request funnel. Feedback records a useful/not-useful rating and optional fixed reason, with linked trace/retry correlation, not free text. Server diagnostics include bounded stage/provider failure codes and actual pipeline attempt tokens when reported, not invented charges or executions of recommended models. See the [technical contract](scout.md#version-5-instrumentation). Main-site/docs collection and CLI publication have separate release boundaries. No replay or ranking experiment is enabled, and none of the prompt-content or retention controls below change.
 
@@ -22,7 +24,7 @@ Scout processes your submitted task to generate recommendations. With usage anal
 | --- | --- |
 | Submitted task and model restrictions | Required to interpret the task, find suitable models and return recommendations. Scout sends task information to OpenAI even when analytics is off. |
 | Recommendations and search diagnostics | When usage analytics is enabled, PostHog receives task categories, model IDs, ranks, available quality/cost/latency evidence, timings, cache status and outcomes. These describe recommendations, not execution of those models on your data. |
-| Product interactions and errors | Enabled analytics includes visits, preset selections, sign-in activity, results viewed, evidence opened, copies, provider-link clicks and coding-agent setup activity. API/MCP events include method, outcome and confirmed connections. Error reports use bounded categories and application stack locations, not raw error messages. |
+| Product interactions and errors | Enabled analytics includes visits, preset selections, sign-in activity, results viewed, evidence opened, copies, provider-link clicks and coding-agent setup activity. API/MCP events record request outcomes. Lifecycle-enabled builds add allowlisted method/tool, reported agent/harness and version, setup/installation correlation and verified-connection diagnostics. A launch request is not proof an app opened, and key authorization is not proof of installation. Error reports use bounded categories and application stack locations, not raw error messages. |
 | Account details | Clerk handles Google/GitHub login. Enabled account analytics can synchronize your name, verified primary email, signup time and connected providers to PostHog. Account and session lifecycle events help us understand onboarding and returning use. |
 | Optional prompt content | Only when prompt sharing is enabled, PostHog also receives the submitted prompt and written task breakdown, for at most three tasks. Prompt text is limited to 4,000 characters, with up to 1,000 characters per excerpt or five-layer field. Common sensitive patterns are removed where detected; this is not guaranteed anonymization. All such text is confined to `$ai_trace.$ai_input_state={prompt,tasks}`; new ordinary `scout_search_details` events contain no prompt, excerpt or layer prose. |
 
@@ -39,7 +41,7 @@ Open **Privacy & analytics** in the [Scout footer](/scout/#analytics-settings):
 
 Scout respects Do Not Track and Global Privacy Control for these analytics. An authenticated browser also communicates its usage preference to the server; the latest received account preference controls background synchronization. A browser that is offline or not signed in cannot update that account preference until it reconnects and authenticates.
 
-API/MCP clients can send `X-Scout-Analytics: off` to disable analytics. Prompt text still requires explicit `X-Scout-Analytics-Content: on`; general opt-out and supported privacy signals take precedence. CLI content capture is always off. Copied agent setup instructions disable prompt-content sharing and do not inherit this browser's account-linkage setting. See the [technical analytics guide](scout.md#product-analytics) for the full contract.
+API/MCP clients can send `X-Scout-Analytics: off` to disable analytics. Prompt text still requires explicit `X-Scout-Analytics-Content: on`; general opt-out and supported privacy signals take precedence. CLI content capture is always off. Older 0.1.8 setup does not inherit this browser's account-linkage setting; the 0.1.9 lifecycle revision explicitly carries usage and unlink preferences into the command and installed headers. Later browser changes do not rewrite existing agent configuration; rerun setup to update it. Request-only refusals in that revision do not overwrite saved account-wide preferences. See the [technical analytics guide](scout.md#product-analytics) for the full contract.
 
 Enabled signed-in analytics normally uses a stable account identifier linked to the profile above; hashing does not make it anonymous, and a pre-sign-in visit can be joined after login. In unlinking mode the server uses fresh unrelated random identifiers, sends no profile/identify operation, ignores previously linked browser identifiers and supplied trace IDs, and does not return an analytics trace ID for later interactions to reuse. Account opt-out and deletion gates still apply before sending. Clerk profile/lifecycle analytics can continue separately under general usage consent. Past records remain linked; signing out or selecting this option does not unlink them. Unlinked request events cannot support cross-request funnels or automatic account-based historical deletion. Prompt text itself may identify a person: unlinking is not anonymization.
 

package/docs/scout.md

@@ -24,6 +24,28 @@ Examples go through the same interpretation and ranking as typed prompts, with n
 
 ## Product analytics
 
+### Coding-agent lifecycle instrumentation — npm 0.1.9
+
+Npm 0.1.9 includes these installer changes; browser/server instrumentation requires the matching independent Scout deployment. Release acceptance is recorded separately. Rerun the installer to update existing 0.1.8 installations; nothing backfills historical events. This contract supersedes the no-retry and process-only setup-identity descriptions below for lifecycle-enabled builds. Homepage/docs deployment remains separate.
+
+| Touchpoint | Event and meaning |
+|---|---|
+| Add to coding agent | `scout_agent_setup_started` records the click. `scout_agent_launch_requested` records an attempted Claude deep link, **not proof the app opened**. `scout_agent_setup_copied` separately records clipboard success/failure. |
+| Device authorization | Server-owned `scout_connect_step` records device creation, approval-page requests, pending/slow polling, approval or denial, expiry, key collection, device listing and revocation. Expected pending polls are not exceptions. Browser failures use `scout_connect_client_error` with a fixed stage/code. |
+| Installation | Opt-in `scout_installation_step` records preflight, login/browser opening, configuration, verification, status, removal and completion. `applied`, component states and `connection` distinguish a plan, incomplete installation and a verified connection. A command exit of zero alone does not establish installation success. |
+| MCP connection | `scout_request_completed` records every handled MCP request, including initialization/discovery and authentication failures. Allowlisted `mcp_method`, `mcp_tool`, reported agent and package version distinguish verifier probes from agent calls. Unrecognized names become `other`/`unknown`, never raw strings. |
+| Each invocation/task | `scout_tool_invocation_started` and `scout_tool_invocation_completed` bracket authenticated tool dispatch. `scout_search_completed` counts an accepted recommendation attempt; `scout_search_details` retains each task's shortlist. All share the request trace. Protocol/tool errors are failures even with HTTP 200. |
+
+When browser usage analytics is enabled, the copied setup prompt explicitly sets `OPENMERIT_TELEMETRY=1`; usage-disabled prompts instead set `DO_NOT_TRACK=1`. Account-unlinked prompts also set `OPENMERIT_ANALYTICS_ACCOUNT=off`. A linked setup gets a random `--setup-id` UUID that joins the click, resumed login, installation and later invocations. An opted-in installation stores a separate random `installation_id` in its existing ownership record and MCP headers; upgrades reuse it. These identifiers contain no account, hostname or project path. They are correlation hints, not authentication. Plans and status checks do not create an installation identity. Standalone CLI telemetry remains default-off, and `DO_NOT_TRACK=1` wins. Installed MCP content capture remains off.
+
+The approval page initializes the same browser privacy controls and authenticated account preference synchronization as Scout, without inventing a Scout pageview. Installer URL refusals (`analytics=off`, `analytics_account=off`) remain effective without changing the browser's stored settings; a request-only refusal does not overwrite the account preference. A collected key is labelled **authorized**, not a verified installation. Account-wide opt-out still requires the authenticated preference endpoint and continues to gate linked and unlinked account requests. Unlinking removes setup/installation identifiers as well as browser/trace linkage. A privacy change in a browser does not rewrite an already installed agent's headers; rerun setup with the desired settings. Existing account opt-outs are not automatically reset.
+
+First trigger and first task mean **first observed** tool call and task for that installation/account. They are derived from the same event stream, not additional search counts. Discovery is not a trigger. Recommendation completion is not downstream model execution or application-task success. No transcript is read, and this instrumentation cannot prove a startup rule loaded, a model decision occurred without calling Scout, or a native app actually opened. Missing consent, storage, connectivity or abrupt termination can leave a funnel incomplete; missing events must not be presented as a verified zero or a proven skipped call.
+
+Initialization can record an allowlisted harness name and semver-shaped reported harness version; the installed headers report the npm installer version, not Claude's current version or invoking model. The stateless service cannot infer the coding agent's model from Scout's own provider generation events. Installer milestones include a fixed `command` category so status/doctor/project completion is never counted as a new installation. Setup milestone submission allows one transient retry within a hard 1.5-second total deadline; general CLI/terminal delivery retains the separately documented behavior below.
+
+Browser event submission retries one transient failure with a stable event UUID. Server delivery retries transport failures, HTTP 429 and 5xx up to three total attempts, with the same event UUIDs/timestamps and a 1.5-second timeout per attempt. Permanent 4xx responses do not retry. Product responses do not wait for delivery. There is no durable product-event queue or exactly-once guarantee; bounded retries can still exhaust. The serving Worker configuration enables sanitized Cloudflare console counters (`scout_analytics_delivery`: delivered, failed, request-suppressed or account-suppressed), with query redaction and invocation logs disabled. Counters contain no identity, trace, device code, URL, content or credential and remain available independently of PostHog delivery. They are operational diagnostics, not PostHog service-log ingestion or session replay. `X-Scout-Analytics-Status` reports only whether the request permits capture, never a receipt of ingestion.
+
 ### Version-5 instrumentation
 
 This contract applies to version-5 Scout serving builds. The serving rollout is independent of main-site publication and the npm package; npm 0.1.7 includes the opt-in CLI additions, while the website collector remains source-only. Prompt-content choices, redaction, retention and account deletion controls are unchanged. Main-site publication remains blocked by [source divergence](site-documentation.md#website-analytics-source-only-unreleased). Earlier dated receipts below describe earlier releases, not acceptance of version 5.

package/docs/security.md

@@ -63,6 +63,8 @@ Scout serving, main-site documentation and npm publication are separate releases
 
 ## Hosted Scout analytics
 
+**Coding-agent lifecycle instrumentation — npm 0.1.9 and matching Scout deployment:** setup clicks, clipboard/deep-link attempts, device authorization states, opted-in installation/component verification and each dispatched MCP invocation gain typed milestones and fixed error codes. Linked setup uses random setup/installation UUIDs, never paths, machine names, device codes, keys or transcript content. The browser handoff explicitly carries usage/unlink choices into setup; standalone CLI analytics remains opt-in. Setup/installation IDs are omitted in unlinked mode, DNT wins, and installed MCP prompt-content capture stays off. Request-only suppression no longer overwrites the saved account-wide preference. Explicit account opt-out/deletion gates remain in force. See the [lifecycle contract](scout.md#coding-agent-lifecycle-instrumentation-npm-019) for event meanings, bounded delivery retries and diagnostic counters. Existing installations require an installer rerun; release acceptance is separate, and no historical completeness, replay, transcript collection or skipped-call detection is claimed.
+
 **Version-5 instrumentation:** the [serving contract](scout.md#version-5-instrumentation) adds validated native web events and explicit CTA-only `$autocapture` mapping, not general DOM capture. Acquisition/UTM/device values are categorical allowlists; public URL properties are reconstructed without raw URLs. Browser performance is sampled and support-dependent. Linked same-tab signup/search identity is separate from unlinking's request-only identifiers. Logical MCP errors count even with HTTP 200; stage/provider codes, actual attempt tokens and feedback/retry traces exclude raw messages and free text. CLI diagnostics are opt-in in npm 0.1.7, adding sanitized version/platform/runtime and bounded application basename frames, never absolute paths or environment contents. Prompt sharing, retention, deletion gates and necessary provider processing are unchanged. Replay is a separate, inactive spike; no experiment is active. Main-site publication remains blocked by documented source divergence; the Scout rollout does not publish npm or activate alert notifications.
 
 **Beta evaluation rollout, 22 October 2026:** The serving configuration enables `SCOUT_BETA_EVALUATION_LOGGING=true`, alongside `POSTHOG_CAPTURE_CONTENT=true` and complete account-sync/deletion configuration. The browser defaults content on only without a stored content choice; saved off, general opt-out, DNT/GPC and unreadable storage keep it off. API/MCP still require `X-Scout-Analytics-Content: on`; CLI content is always off. This is product evaluation/debugging, not foundation model training. Deployment is owner-approved; this is not legal certification, and beta status establishes no consent or legal basis. Main-site `/docs/` publication remains blocked by source divergence; the [policy](/scout/data-policy/) is generated from the same Markdown and published with Scout instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmerit",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Evidence-driven model decisions for coding harnesses.",
   "type": "module",
   "bin": {