openmerit 0.1.7-preview.4 → 0.1.7

package/dist/terminal/src/browser.mjs

@@ -1,9 +1,10 @@
 import { spawn } from 'node:child_process';
 
-// Only open the loopback address returned by our own server. Never use a shell.
-export function browserCommand(url, platform = process.platform, env = process.env) {
-  const target = new URL(url);
-  if (target.protocol !== 'http:' || target.hostname !== '127.0.0.1' || !/^http:\/\/127\.0\.0\.1:[0-9]+$/.test(url) || target.username || target.password || target.pathname !== '/' || target.search || target.hash) throw new Error('Expected a local terminal URL.');
+// By default, only open the loopback address returned by our own server.
+// Callers can pass a stricter or different check. Never use a shell.
+const terminalURL = url => { const target = new URL(url); return target.protocol === 'http:' && target.hostname === '127.0.0.1' && /^http:\/\/127\.0\.0\.1:[0-9]+$/.test(url) && !target.username && !target.password && target.pathname === '/' && !target.search && !target.hash; };
+export function browserCommand(url, platform = process.platform, env = process.env, allowed = terminalURL) {
+  if (!allowed(url)) throw new Error('Refusing to open an unexpected URL.');
   if (env.SSH_CONNECTION || env.SSH_TTY) return null;
   if (platform === 'darwin') return ['open', [url]];
   if (platform === 'win32') return ['rundll32.exe', ['url.dll,FileProtocolHandler', url]];
@@ -11,8 +12,8 @@ export function browserCommand(url, platform = process.platform, env = process.e
   return null;
 }
 
-export async function openBrowser(url, { platform = process.platform, env = process.env, spawnProcess = spawn, timeoutMs = 3000 } = {}) {
-  const command = browserCommand(url, platform, env);
+export async function openBrowser(url, { platform = process.platform, env = process.env, spawnProcess = spawn, timeoutMs = 3000, allowed } = {}) {
+  const command = browserCommand(url, platform, env, allowed);
   if (!command) return false;
   return new Promise(resolve => {
     let child, timer;

package/dist/terminal/src/cli.mjs

@@ -5,10 +5,12 @@ import { startTerminal } from './server.mjs';
 import { createCollector, loadConfig } from './collect.mjs';
 import { sampleSnapshot } from './sample.mjs';
 import { openBrowser } from './browser.mjs';
+import { commandTelemetry } from './telemetry.mjs';
 
 const help = `OpenMerit · Inference Terminal
 
   openmerit dash [path] [options]
+  openmerit install --help           Connect OpenMerit to your coding agent
   openmerit eval --help              Evaluate CLI changes across coding agents
 
   --port <number>      Require a specific local port (default: 4310 or a free port)
@@ -27,6 +29,7 @@ Coding-harness usage is outside this terminal's scope.
 
 async function main() {
   const args = process.argv.slice(2);
+  if (['install', 'status', 'remove', 'login', 'logout', 'project', 'doctor'].includes(args[0])) { const { main } = await import('./install.mjs'); process.exitCode = await main(args); return; }
   if (args[0] === 'eval') { const { main } = await import('../../eval/src/cli.mjs'); await main(args.slice(1)); return; }
   if (!args.length || args.includes('--help') || args.includes('-h')) { console.log(help); return; }
   if (args.shift() !== 'dash') throw new Error('Unknown command. Run openmerit --help.');
@@ -62,4 +65,10 @@ async function main() {
   }
   if (!noOpen && !await openBrowser(terminal.url)) console.log('  Open the local URL above in your browser.');
 }
-main().catch(error => { console.error(`\n  ${error.code === 'EADDRINUSE' ? 'Port is in use. Choose another with --port.' : error.message}\n`); process.exitCode = 1; });
+const completeTelemetry = commandTelemetry(process.argv.slice(2));
+const setupCodes = { 10: 'approval_pending', 11: 'access_denied', 20: 'install_conflict', 30: 'openmerit_unreachable' };
+main().then(() => completeTelemetry(process.exitCode ? 'error' : 'ok', undefined, setupCodes[process.exitCode]), async error => {
+  console.error(`\n  ${error.code === 'EADDRINUSE' ? 'Port is in use. Choose another with --port.' : error.message}\n`);
+  process.exitCode = 1;
+  await completeTelemetry('error', error);
+});

package/dist/terminal/src/install.mjs

@@ -0,0 +1,399 @@
+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 { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { openBrowser } from './browser.mjs';
+
+// One-command coding-agent setup: device sign-in in the browser, then the MCP
+// server and Scout skill. Built to be run by a person or by a coding agent:
+// no interactive prompts, bounded waits, resumable logins and explicit exit codes.
+export const exitCodes = { ok: 0, error: 1, pending: 10, denied: 11, conflict: 20, unreachable: 30 };
+const exec = promisify(execFile);
+const hash = value => createHash('sha256').update(value).digest('hex');
+const policyPath = '.openmerit/scout.json';
+const clients = { 'claude-code': 'Claude Code' };
+
+export const skill = `---
+name: openmerit-scout
+description: Use when choosing, adding, replacing or configuring an application inference model (an LLM or other model the user's application calls), for example when building extraction, classification, generation or agent features. Consults OpenMerit Scout for an evidence-based shortlist. Not for unrelated edits, ordinary inference calls or this coding agent's own model.
+---
+
+# OpenMerit · Scout
+
+Before introducing, recommending, replacing or configuring an application
+inference model, call the \`scout_models\` tool on the \`openmerit\` MCP server.
+This applies even when the user never mentions Scout. Preserve the user's explicit
+model choice; assess it rather than silently replacing it. Leave unchanged,
+approved application selections in place.
+
+## Project policy
+
+Read \`${policyPath}\` before searching. If it is absent, ask once whether this
+project uses **existing-only** (only endpoints it can already reach) or
+**existing-first** (prefer them, ask before searching the whole catalogue), and
+which public catalogue endpoint IDs it can access. Save the answer:
+
+\`\`\`sh
+npx -y openmerit@latest project --policy existing-only --endpoint-id <id> ...
+\`\`\`
+
+Never infer access from a model name, SDK or environment-variable name. Never
+record credentials, private URLs, prompts or customer data. An empty inventory
+is not permission to search all models.
+
+## Searching
+
+Call \`scout_models\` with a non-confidential task description and
+\`endpointIds\` set to the saved inventory, including \`[]\` when empty.
+Existing-only never broadens. For existing-first, if no existing candidate fits,
+explain the gap and ask before a separate search without \`endpointIds\`. Send
+only task requirements, never source files, secrets or real customer records.
+
+Compare model AND endpoint, evidence, reference cost/time, unknowns and
+warnings. For multiple tasks read \`tasks[].slots[0].recommendations\`; the
+top-level list is empty. Prefer the cheapest usable option the quality evidence
+supports, without claiming benchmarks prove application accuracy. Use the
+returned provider model ID and the project's actual SDK and protocol.
+
+## Boundaries
+
+Ask before adding providers or credentials, spending, deploying or external
+writes. Report recommendation, endpoint connectivity and application checks as
+separate results, each only after it succeeds. Do not switch this coding agent's
+own model.
+
+If Scout fails, say so and pause the model decision; do not substitute a
+remembered recommendation. If it reports that the device key is missing,
+expired or revoked, run \`npx -y openmerit@latest login\` and then
+\`npx -y openmerit@latest install\` again. Never ask the user to paste a key.
+`;
+
+export const help = `OpenMerit · coding-agent setup
+
+  openmerit install [--client claude-code] [--scope user|project] [--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 logout  [--json]                 Revoke this device's key
+  openmerit project --policy existing-only|existing-first [--endpoint-id <id> ...] [--plan]
+  openmerit doctor  [--json]
+
+install signs this device in through the browser (one Approve click), adds the
+OpenMerit MCP server and the Scout skill, then verifies the connection.
+It opens the approval page and waits up to 9 minutes for the Approve click
+(30 seconds when no browser could be opened). If it exits with approval
+pending, rerun the same command: it resumes the same request.
+--client defaults to the coding agent running the command. --scope defaults to user.
+--plan shows the changes without making them. Keys are never printed.
+
+Exit codes: 0 done, 10 approval pending, 11 denied or expired, 20 conflict,
+30 OpenMerit unreachable, 1 other error.
+`;
+
+class Stop extends Error { constructor(message, code, next) { super(message); this.exit = code; this.next = next; } }
+
+const server = () => (process.env.OPENMERIT_URL ?? 'https://openmerit.ai').replace(/\/+$/, '');
+const configDir = () => resolve(process.env.OPENMERIT_CONFIG_DIR ?? join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'openmerit'));
+const credentialsPath = () => join(configDir(), 'credentials.json');
+const pendingPath = () => join(configDir(), 'login.json');
+
+async function optional(path) {
+  try { return await readFile(path, 'utf8'); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+async function object(path) {
+  const text = await optional(path);
+  if (text === null) return {};
+  let value;
+  try { value = JSON.parse(text); } catch { throw new Stop(`Invalid JSON in ${path}; nothing was changed.`, exitCodes.conflict); }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Stop(`Expected a JSON object in ${path}.`, exitCodes.conflict);
+  return value;
+}
+async function save(path, value) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+
+async function request(path, { method = 'GET', body, key } = {}) {
+  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' },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+  } catch { throw new Stop(`Could not reach ${server()}. Check your connection and retry.`, exitCodes.unreachable); }
+  const data = await response.json().catch(() => ({}));
+  return { status: response.status, data };
+}
+
+function detectClient() {
+  if (process.env.CLAUDECODE === '1' || process.env.CLAUDE_CODE_ENTRYPOINT) return 'claude-code';
+  return null;
+}
+
+// Claude Code locations. Project scope keeps the key out of the repository:
+// the MCP entry uses Claude's private "local" scope, only the skill is in the project.
+function claudePaths(root, scope) {
+  const config = resolve(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'));
+  const base = scope === 'user' ? config : join(root, '.claude');
+  return {
+    skill: join(base, 'skills/openmerit-scout/SKILL.md'),
+    legacyRule: join(base, 'rules/openmerit.md'),
+    record: join(base, 'openmerit-install.json'),
+    mcpFile: process.env.CLAUDE_CONFIG_DIR ? join(config, '.claude.json') : join(homedir(), '.claude.json'),
+    mcpScope: scope === 'user' ? 'user' : 'local',
+  };
+}
+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 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;
+
+async function claude(args, root, key) {
+  try { return await exec('claude', args, { cwd: root, timeout: 30_000, maxBuffer: 1024 * 1024, windowsHide: true }); }
+  catch (error) {
+    if (error.code === 'ENOENT') throw new Stop('Claude Code (the claude command) was not found on PATH. Install it, then retry.', exitCodes.error);
+    // Claude echoes headers on some failures: scrub the key, and show only a short excerpt.
+    const detail = `${error.stderr ?? ''}${error.stdout ?? ''}`.split(key || '\u0000').join('[key]').replace(/om_[A-Za-z0-9_-]{20,}/g, '[key]').trim().slice(0, 300);
+    throw new Stop(`Claude Code could not complete "claude ${args.slice(0, 2).join(' ')}"${detail ? `: ${detail}` : '.'}`, exitCodes.error);
+  }
+}
+
+// Inspect the current Claude Code installation without changing anything.
+async function inspect(root, scope) {
+  const paths = claudePaths(root, scope);
+  const [record, config, installedSkill, legacyRule] = await Promise.all([object(paths.record), object(paths.mcpFile), optional(paths.skill), optional(paths.legacyRule)]);
+  const owned = record.version === 2 && record.scope === scope;
+  const current = configuredServer(config, root, scope);
+  const otherScope = configuredServer(config, root, scope === 'user' ? 'project' : 'user');
+  const projectFile = await object(join(root, '.mcp.json'));
+  return {
+    paths, record, owned, current, installedSkill,
+    // 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),
+    skillOwned: installedSkill === null || owned && [record.skillHash, record.pendingSkill].includes(hash(installedSkill)),
+    // The pre-release installer recorded its rule hash; only an unchanged rule is removed.
+    legacyRule: legacyRule !== null && record.version === 1 && hash(legacyRule) === record.ruleHash ? 'remove' : legacyRule !== null ? 'keep' : 'none',
+    shadowed: !!(otherScope || projectFile.mcpServers?.openmerit),
+  };
+}
+
+function conflicts(state) {
+  const found = [];
+  if (!state.serverOwned) found.push('Claude Code already has an MCP server named "openmerit" that this installer did not create or that was edited. Remove it with "claude mcp remove openmerit", then retry.');
+  if (!state.skillOwned) found.push(`${state.paths.skill} exists and was not created by this installer or was edited. Move or delete it, then retry.`);
+  if (state.shadowed) found.push('An "openmerit" MCP server exists in another Claude Code scope (or in .mcp.json). Remove it, then retry.');
+  return found;
+}
+
+async function credentials() {
+  const saved = await object(credentialsPath());
+  return saved.version === 1 && saved.server === server() && typeof saved.key === 'string' ? saved : null;
+}
+
+// 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 }) {
+  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 } });
+    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 };
+    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`);
+  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 opened = await openBrowser(pending.url, { allowed: approvalPage }).catch(() => false);
+    pending = { ...pending, ...(opened ? { opened: true } : { openFailed: true }) };
+    await save(pendingPath(), pending);
+  }
+  // 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 } });
+    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 rm(pendingPath(), { force: true });
+      return data.access_token;
+    }
+    if (data.error === 'slow_down') interval += 5000;
+    else if (data.error !== 'authorization_pending') {
+      await rm(pendingPath(), { force: true });
+      if (data.error === 'access_denied') throw new Stop('The sign-in request was denied. Nothing was installed.', exitCodes.denied, 'Rerun the command to start a new request.');
+      throw new Stop('The sign-in code expired or was already used. Nothing was installed.', exitCodes.denied, 'Rerun the command to get a new code.');
+    }
+    if (Date.now() + interval > deadline) throw new Stop(`Waiting for approval of code ${pending.userCode}.`, exitCodes.pending, `Open ${pending.url}, click Approve, then rerun the same command. It resumes this request.`);
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+}
+
+// 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 install(root, { client, scope, plan, open, log, wait }) {
+  const state = await inspect(root, scope);
+  const found = conflicts(state);
+  const changes = [
+    `${state.current ? 'Update' : 'Add'} MCP server "openmerit" in Claude Code (${state.paths.mcpScope} scope, ${state.paths.mcpFile})`,
+    `${state.installedSkill === null ? 'Create' : 'Update'} ${state.paths.skill}`,
+    ...(state.legacyRule === 'remove' ? [`Remove the unchanged earlier instructions at ${state.paths.legacyRule}`] : []),
+    ...(await credentials() ? [] : [`Sign this device in through the browser and store its key in ${credentialsPath()} (mode 600)`]),
+  ];
+  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);
+  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);
+  // Record intent first so an interrupted install is repaired by rerunning.
+  await save(state.paths.record, { version: 2, scope, client, serverHash: serverHash(state.current), skillHash: state.installedSkill === null ? null : hash(state.installedSkill), pendingAuth: hash(next.headers.Authorization), pendingSkill: hash(skill) });
+  if (state.current?.url !== next.url || state.current?.headers?.Authorization !== next.headers.Authorization) {
+    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);
+  }
+  await save(state.paths.skill, skill);
+  if (state.legacyRule === 'remove') await rm(state.paths.legacyRule, { force: true });
+  // 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: 2, scope, client, serverHash: serverHash(written), skillHash: hash(skill), installedAt: new Date().toISOString() });
+  const connection = await verify(key);
+  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'
+      ? `Scout is ready in new ${clients[client]} sessions. In a session that is already open, run /mcp and reconnect "openmerit".`
+      : 'Installed, but the connection check failed. Run "openmerit doctor".' };
+}
+
+async function status(root, { client, scope, check }) {
+  const state = await inspect(root, scope), saved = await credentials();
+  const installed = state.owned && !!state.current && state.serverOwned && state.installedSkill !== null && state.skillOwned && !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',
+    conflicts: conflicts(state), connection: check && saved ? await verify(saved.key) : 'not_checked' };
+}
+
+async function revokeKey() {
+  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 rm(credentialsPath(), { force: true });
+  return status === 200;
+}
+
+async function remove(root, { client, scope, plan }) {
+  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.' };
+  const changes = [...(state.current && state.serverOwned ? [`Remove MCP server "openmerit" (${state.paths.mcpScope} scope)`] : []),
+    ...(state.installedSkill !== null && state.skillOwned ? [`Delete ${state.paths.skill}`] : []), 'Revoke and delete this device key'];
+  const kept = [...(state.serverOwned ? [] : ['the edited "openmerit" MCP server']), ...(state.skillOwned ? [] : [state.paths.skill]), policyPath];
+  if (plan) return { action: 'remove', applied: false, client, scope, changes, keeps: kept };
+  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 });
+  await rm(state.paths.record, { force: true });
+  const revoked = await revokeKey();
+  return { action: 'remove', applied: true, client, scope, changes, keeps: kept, keyRevoked: revoked };
+}
+
+async function project(root, { policy, ids, plan }) {
+  if (!['existing-only', 'existing-first'].includes(policy)) throw new Stop('Choose --policy existing-only or existing-first.', exitCodes.error);
+  if (ids.length > 100 || new Set(ids).size !== ids.length || ids.some(id => typeof id !== 'string' || id.includes('://') || !/^[a-zA-Z0-9][a-zA-Z0-9/_.:+-]{0,159}$/.test(id))) throw new Stop('Use up to 100 unique public catalogue endpoint IDs, never credentials or URLs.', exitCodes.error);
+  const value = { version: 1, policy, endpointIds: ids }, file = join(root, policyPath), existing = await object(file);
+  if (Object.keys(existing).some(key => !['version', 'policy', 'endpointIds'].includes(key))) throw new Stop(`${policyPath} has unrecognized fields; edit it yourself instead.`, exitCodes.conflict);
+  if (!plan) await save(file, value);
+  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 }) {
+  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 }));
+  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}`); }
+  const state = await inspect(root, scope).catch(() => null);
+  if (state) add('install', state.owned && !conflicts(state).length, state.owned ? conflicts(state).join(' ') || `Installed (${scope} scope)` : `Not installed in ${scope} scope`);
+  return { action: 'doctor', ok: checks.every(check => check.ok), checks };
+}
+
+function render(result) {
+  if (result.action === 'doctor') return result.checks.map(c => `${c.ok ? '✓' : '✗'} ${c.name}: ${c.detail}`).join('\n');
+  if (result.action === 'status') return [`OpenMerit in ${clients[result.client]} (${result.scope} scope): ${result.installed ? 'installed' : 'not installed'}`, `Signed in: ${result.signedIn ? 'yes' : 'no'} · MCP server: ${result.server} · skill: ${result.skill} · connection: ${result.connection}`, ...result.conflicts].join('\n');
+  if (result.action === 'project') return `${result.applied ? 'Saved' : 'Would save'} ${result.path}: ${result.policy.policy}, ${result.policy.endpointIds.length} endpoint ID(s). ${result.note}`;
+  if (result.action === 'login') return result.note;
+  if (result.action === 'logout') return result.note;
+  const lines = [result.applied ? `Done (${result.action}):` : result.changes.length ? `Plan (${result.action}, nothing changed):` : result.note, ...result.changes.map(c => `  • ${c}`)];
+  if (result.conflicts?.length) lines.push('Conflicts (install would stop):', ...result.conflicts.map(c => `  • ${c}`));
+  if (result.connection) lines.push(`Connection check: ${result.connection}`);
+  if (result.next) lines.push('', result.next);
+  return lines.join('\n');
+}
+
+export async function main(args, { root = process.cwd(), print = console.log, printError = console.error } = {}) {
+  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];
+  if (!allowed) throw new Error('Unknown command. Run openmerit --help.');
+  for (let i = 0; i < rest.length; i++) {
+    const option = rest[i];
+    if (!allowed.includes(option)) throw new Error(`Unknown option for ${action}: ${option}`);
+    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 === '--policy') options.policy = value();
+    else if (option === '--endpoint-id') options.ids.push(value());
+    else if (option === '--no-open') options.open = false;
+    else options[option.slice(2)] = true;
+  }
+  if (!['user', 'project'].includes(options.scope)) throw new Error('Use --scope user or --scope project.');
+  if (['install', 'status', 'remove'].includes(action)) {
+    options.client ??= detectClient();
+    if (!options.client) throw new Error('Choose the coding agent with --client claude-code.');
+    if (!clients[options.client]) throw new Error(`Unsupported client "${options.client}". Supported: ${Object.keys(clients).join(', ')}.`);
+  }
+  root = resolve(root);
+  // Agents run commands with a few-minute timeout; wait well inside it, then resume.
+  const wait = process.env.OPENMERIT_LOGIN_WAIT === undefined ? undefined : Number(process.env.OPENMERIT_LOGIN_WAIT);
+  const log = text => (options.json ? printError : print)(text);
+  try {
+    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.' });
+    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;
+    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/server.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { basename } from 'node:path';
 import { createCollector, loadConfig } from './collect.mjs';
 import { sampleSnapshot } from './sample.mjs';
+import { telemetryEnabled, terminalProperties, sendTerminalEvent, errorProperties } from './telemetry.mjs';
 
 const assets = new Map([['/', ['index.html', 'text/html']], ['/app.js', ['app.js', 'text/javascript']], ['/flow.js', ['flow.js', 'text/javascript']], ['/flow.css', ['flow.css', 'text/css']], ['/styles.css', ['styles.css', 'text/css']], ['/favicon.svg', ['favicon.svg', 'image/svg+xml']]]);
 for (const file of ['baseten.png', 'groq.ico', 'cerebras.png', 'qwen.png', 'meta.ico', 'nomic.png', 'baai.png', 'ollama.png', 'lm-studio.png', 'vllm.png', 'anthropic.png', 'google.png', 'deepseek.ico', 'cohere.png', 'openai.png', 'mistral.png', 'openrouter.png', 'huggingface.svg']) assets.set(`/brands/${file}`, [`brands/${file}`, file.endsWith('.svg') ? 'image/svg+xml' : file.endsWith('.ico') ? 'image/x-icon' : 'image/png']);
@@ -16,7 +17,7 @@ export async function startTerminal({ root = process.cwd(), port = 4310, interva
     if(busy||closed)return;
     busy=true;
     try {const next=await collect();if(!closed)snapshot=next;}
-    catch {if(snapshot.loading)snapshot={...snapshot,loadError:true};}
+    catch (error) {if(snapshot.loading)snapshot={...snapshot,loadError:true};sendTerminalEvent('terminal_error',{code:'collection_error',...errorProperties(error)});}
     finally {busy=false;}
   };
   const server = createServer(async (request, response) => {
@@ -26,10 +27,34 @@ export async function startTerminal({ root = process.cwd(), port = 4310, interva
     const headers = { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer', 'Content-Security-Policy': "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; font-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'" };
     const send = (code, body, type = 'application/json') => { response.writeHead(code, { ...headers, 'Content-Type': `${type}; charset=utf-8` }); response.end(body); };
     if (!validHosts.includes(host) || (request.headers.origin && request.headers.origin !== `http://${host}`) || request.headers['sec-fetch-site'] === 'cross-site') return send(403, '{"error":"Local access only"}');
-    if (request.method !== 'GET') return send(405, '{"error":"Read-only terminal"}');
     let path;
     try { path = new URL(request.url, `http://${host}`).pathname; }
     catch { return send(400, '{"error":"Invalid request URL"}'); }
+    if (path === '/api/analytics' && request.method === 'POST') {
+      if (!telemetryEnabled() || request.headers.dnt === '1' || request.headers['sec-gpc'] === '1' || request.headers['x-scout-analytics'] === 'off') return send(204, '');
+      if (request.headers['content-type'] !== 'application/json') return send(415, '{}');
+      if (Number(request.headers['content-length']) > 2048) return send(413, '{}');
+      let size = 0, body = '', done = false;
+      const timeout = setTimeout(() => { if (!done) { done = true; send(408, '{}'); request.destroy(); } }, 1000);
+      request.on('data', chunk => {
+        if (done) return;
+        size += chunk.length;
+        if (size > 2048) { done = true; clearTimeout(timeout); send(413, '{}'); request.resume(); return; }
+        body += chunk.toString('utf8');
+      });
+      request.on('error', () => { done = true; clearTimeout(timeout); });
+      request.on('end', () => {
+        clearTimeout(timeout); if (done) return; done = true;
+        try {
+          const value = JSON.parse(body), properties = terminalProperties(value.event, value.properties);
+          if (!properties) return send(400, '{}');
+          sendTerminalEvent(value.event, properties);
+          return send(204, '');
+        } catch { return send(400, '{}'); }
+      });
+      return;
+    }
+    if (request.method !== 'GET') return send(405, '{"error":"Read-only terminal"}');
     if (path === '/api/snapshot') {
       const data=collect.current?.(snapshot)??snapshot;
       const revision=new URL(request.url,`http://${host}`).searchParams.get('repositoryRevision');
@@ -42,7 +67,7 @@ export async function startTerminal({ root = process.cwd(), port = 4310, interva
       return send(200,JSON.stringify(data));
     }
     if (path === '/api/sample') return send(200, JSON.stringify(sampleSnapshot()));
-    if (path === '/api/info') return send(200, JSON.stringify({ version: 1, defaultMode: demo ? 'sample' : 'live', interval }));
+    if (path === '/api/info') return send(200, JSON.stringify({ version: 1, defaultMode: demo ? 'sample' : 'live', interval, telemetry: telemetryEnabled() }));
     const asset = assets.get(path);
     if (!asset) return send(404, '{"error":"Not found"}');
     try { return send(200, await readFile(fileURLToPath(new URL(`../public/${asset[0]}`, import.meta.url))), asset[1]); }