openmerit 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.10 — 2026-10-26
+
+- Add default-on Claude Code background checks for compatible Scout skill/startup-rule updates, with daily checks, 15-minute failure backoff, non-blocking failure notices with the “update openmerit” fallback, manual `openmerit update`, persistent opt-out and a natural-language update instruction.
+- Verify npm package integrity and read a bounded instruction bundle without executing downloaded code. Preserve edited files, credentials, MCP configuration, privacy settings and project policy; serialize maintenance and recover interrupted instruction writes.
+- Disclose setup behavior, retain other Claude hooks/settings and require a new session to reliably load updated instructions. Existing installations need a one-time installer rerun after publication; incompatible releases require a reviewed manual upgrade. Hosted Scout and npm remain separate releases.
+- Enable Scout setup usage/installation diagnostics by default, honoring telemetry, DNT and account-unlink opt-outs. Terminal/evaluation analytics remain opt-in; MCP prompt-content capture remains off.
+
 ## 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.

package/dist/core/src/index.d.ts

@@ -7,13 +7,13 @@ export interface HarnessAdapter {
     scheduleWakeup?(request: HarnessWakeupRequest): Promise<HarnessDispatchReceipt>;
 }
 export interface IntentFactoryOptions {
-    readonly taskProfileId?: string;
+    readonly taskProfileId?: string | undefined;
     readonly authorizationPolicyId?: string;
-    readonly policy?: SupervisedGraduationPolicy;
+    readonly policy?: SupervisedGraduationPolicy | undefined;
     readonly id?: string;
     readonly requestedAt?: string;
-    readonly evaluationSpend?: number;
-    readonly targetId?: string;
+    readonly evaluationSpend?: number | undefined;
+    readonly targetId?: string | undefined;
     readonly additionalConstraints?: Readonly<Record<string, JsonValue>>;
 }
 export declare function createOpenMeritIntent(kind: IntentKind, options?: IntentFactoryOptions): OpenMeritIntent;
@@ -28,8 +28,8 @@ export interface VerificationResult {
 }
 export interface ResultInterpretation extends VerificationResult {
     readonly nextStage?: ImprovementCycleState["stage"];
-    readonly config?: OpenMeritProjectConfig;
-    readonly cyclePatch?: Partial<ImprovementCycleState>;
+    readonly config?: OpenMeritProjectConfig | undefined;
+    readonly cyclePatch?: Partial<ImprovementCycleState> | undefined;
 }
 export declare function validateObservabilityCoverage(profile: TaskProfile, coverage: ObservabilityCoverage, requireReady: boolean): readonly string[];
 export declare function interpretIntentResult(intent: OpenMeritIntent, result: AnyIntentResult, cycle: ImprovementCycleState, config: OpenMeritProjectConfig): ResultInterpretation;
@@ -52,7 +52,7 @@ export interface IssuedIntent {
     readonly receipt: HarnessDispatchReceipt;
 }
 export interface CoordinatorIssueOptions {
-    readonly additionalConstraints?: Readonly<Record<string, JsonValue>>;
+    readonly additionalConstraints?: Readonly<Record<string, JsonValue>> | undefined;
 }
 export interface AcceptedIntentResult {
     readonly intentKind: IntentKind;

package/dist/pi/src/index.js

@@ -536,7 +536,7 @@ export default function openMeritExtension(pi) {
         await dispatchIntent(pi, ctx, state, store, "establish_evals", registerCompletionTool, {
             applicationTargetRequired: true,
             detectedApplicationTargets: detectedTargetsConstraint(detectedApplicationTargets),
-            ...(detectedApplicationTargets.length === 1 && detectedApplicationTargets[0].configuredModelId ? { expectedIncumbentModelId: detectedApplicationTargets[0].configuredModelId } : {}),
+            ...(detectedApplicationTargets.length === 1 && detectedApplicationTargets[0]?.configuredModelId ? { expectedIncumbentModelId: detectedApplicationTargets[0]?.configuredModelId } : {}),
         });
     });
     pi.on("session_start", async (_event, ctx) => {
@@ -573,7 +573,7 @@ export default function openMeritExtension(pi) {
                         await dispatchIntent(pi, ctx, state, store, "establish_evals", registerCompletionTool, {
                             applicationTargetRequired: true,
                             detectedApplicationTargets: detectedTargetsConstraint(detectedApplicationTargets),
-                            ...(detectedApplicationTargets.length === 1 && detectedApplicationTargets[0].configuredModelId ? { expectedIncumbentModelId: detectedApplicationTargets[0].configuredModelId } : {}),
+                            ...(detectedApplicationTargets.length === 1 && detectedApplicationTargets[0]?.configuredModelId ? { expectedIncumbentModelId: detectedApplicationTargets[0]?.configuredModelId } : {}),
                         });
                     }
                 }
@@ -626,7 +626,7 @@ export default function openMeritExtension(pi) {
                 await dispatchIntent(pi, ctx, state, store, "establish_evals", registerCompletionTool, {
                     applicationTargetRequired: true,
                     detectedApplicationTargets: detectedTargetsConstraint(detectedApplicationTargets),
-                    ...(detectedApplicationTargets.length === 1 && detectedApplicationTargets[0].configuredModelId ? { expectedIncumbentModelId: detectedApplicationTargets[0].configuredModelId } : {}),
+                    ...(detectedApplicationTargets.length === 1 && detectedApplicationTargets[0]?.configuredModelId ? { expectedIncumbentModelId: detectedApplicationTargets[0]?.configuredModelId } : {}),
                 });
             }
             else {
@@ -652,7 +652,7 @@ export default function openMeritExtension(pi) {
                         await dispatchIntent(pi, ctx, state, store, "establish_evals", registerCompletionTool, {
                             applicationTargetRequired: true,
                             detectedApplicationTargets: detectedTargetsConstraint(detectedApplicationTargets),
-                            ...(detectedApplicationTargets.length === 1 && detectedApplicationTargets[0].configuredModelId ? { expectedIncumbentModelId: detectedApplicationTargets[0].configuredModelId } : {}),
+                            ...(detectedApplicationTargets.length === 1 && detectedApplicationTargets[0]?.configuredModelId ? { expectedIncumbentModelId: detectedApplicationTargets[0]?.configuredModelId } : {}),
                         });
                     }
                     return;

package/dist/protocol/src/index.d.ts

@@ -361,16 +361,16 @@ export declare const REQUIRED_CAPABILITIES: Readonly<Record<IntentKind, readonly
 export type ImprovementStage = "unconfigured" | "establishing_evidence" | "collecting_baseline" | "baseline_ready" | "discovering_candidates" | "candidates_ready" | "running_challenger_trials" | "challengers_ready" | "calculating_frontier" | "frontier_ready" | "awaiting_swap_approval" | "swap_approved" | "applying_swap" | "swap_applied" | "verifying_swap" | "swap_verified" | "verification_failed" | "rolling_back" | "monitoring";
 export interface ImprovementCycleState {
     readonly id: string;
-    readonly targetId?: string;
-    readonly taskProfileId?: string;
+    readonly targetId?: string | undefined;
+    readonly taskProfileId?: string | undefined;
     readonly stage: ImprovementStage;
-    readonly activeCandidateId?: string;
-    readonly previousCandidateId?: string;
-    readonly proposedCandidateId?: string;
+    readonly activeCandidateId?: string | undefined;
+    readonly previousCandidateId?: string | undefined;
+    readonly proposedCandidateId?: string | undefined;
     readonly verifiedSwapCount: number;
     readonly baselineEvidenceSufficient: boolean;
     readonly observabilityReady?: boolean;
-    readonly policy?: SupervisedGraduationPolicy;
+    readonly policy?: SupervisedGraduationPolicy | undefined;
 }
 export interface OpenMeritProjectConfig {
     readonly schemaVersion: 1;
@@ -382,13 +382,13 @@ export interface OpenMeritProjectConfig {
 export interface OpenMeritProjectState {
     readonly schemaVersion: 1;
     readonly cycle: ImprovementCycleState;
-    readonly activeIntent?: OpenMeritIntent;
-    readonly lastResult?: IntentResult;
+    readonly activeIntent?: OpenMeritIntent | undefined;
+    readonly lastResult?: IntentResult | undefined;
     /** Durable handoffs between discovery, trials, and frontier calculation. */
-    readonly candidates?: readonly CandidateDescriptor[];
-    readonly assessments?: readonly CandidateAssessment[];
-    readonly experimentManifest?: EvidenceReference;
-    readonly observability?: ObservabilityCoverage;
+    readonly candidates?: readonly CandidateDescriptor[] | undefined;
+    readonly assessments?: readonly CandidateAssessment[] | undefined;
+    readonly experimentManifest?: EvidenceReference | undefined;
+    readonly observability?: ObservabilityCoverage | undefined;
     readonly automation: {
         readonly paused?: boolean;
         readonly setupNudgeShown: boolean;
@@ -397,9 +397,9 @@ export interface OpenMeritProjectState {
         readonly modelCatalogFingerprint?: string;
         readonly modelCatalogChangedAt?: string;
         readonly processedSignalIds?: readonly string[];
-        readonly pendingIntentKind?: IntentKind;
-        readonly pendingIntentReason?: string;
-        readonly lastAssessmentAt?: string;
+        readonly pendingIntentKind?: IntentKind | undefined;
+        readonly pendingIntentReason?: string | undefined;
+        readonly lastAssessmentAt?: string | undefined;
         readonly baselineStartedAt?: string;
         readonly lastReassessmentTaskCount?: number;
         readonly lastReassessmentAt?: string;

package/dist/terminal/scout-update.json

@@ -0,0 +1 @@
+{"format":1,"contract":"scout-recommend-v1","version":"0.1.10","skill":"---\nname: openmerit-scout\ndescription: Consults OpenMerit Scout before choosing, adding, downloading, replacing or configuring any application inference model, including implicit choices while building features, pretrained browser/local models, SDK defaults, embeddings, OCR, speech, classification, detection, segmentation, LLMs and agents. Not for unrelated edits, ordinary inference calls or this coding agent's own model.\n---\n\n# OpenMerit · Scout\n\nBefore introducing, recommending, replacing or configuring an application\ninference model, call the `scout_models` tool on the `openmerit` MCP server.\nThis applies even when the user never mentions models or Scout. Downloading local\nweights, using a pretrained browser model or accepting an SDK default is a model\ndecision: consult Scout before model-specific code, installs or downloads.\nPreserve the user's explicit model choice; assess it rather than silently replacing\nit. Leave unchanged, approved application selections in place.\n\n## Project policy\n\nRead `.openmerit/scout.json` before searching. If it is absent, ask once whether this\nproject uses **existing-only** (only endpoints it can already reach) or\n**existing-first** (prefer them, ask before searching the whole catalogue), and\nwhich public catalogue endpoint IDs it can access. Save the answer:\n\n```sh\nnpx -y openmerit@latest project --policy existing-only --endpoint-id <id> ...\n```\n\nNever infer access from a model name, SDK or environment-variable name. Never\nrecord credentials, private URLs, prompts or customer data. An empty inventory\nis not permission to search all models.\n\n## Searching\n\nCall `scout_models` with a non-confidential task description and\n`endpointIds` set to the saved inventory, including `[]` when empty.\nExisting-only never broadens. For existing-first, if no existing candidate fits,\nexplain the gap and ask before a separate search without `endpointIds`. Send\nonly task requirements, never source files, secrets or real customer records.\n\nCompare model AND endpoint, evidence, reference cost/time, unknowns and\nwarnings. For multiple tasks read `tasks[].slots[0].recommendations`; the\ntop-level list is empty. Prefer the cheapest usable option the quality evidence\nsupports, without claiming benchmarks prove application accuracy. Use the\nreturned provider model ID and the project's actual SDK and protocol.\n\n## Boundaries\n\nAsk before adding providers or credentials, spending, deploying or external\nwrites. Report recommendation, endpoint connectivity and application checks as\nseparate results, each only after it succeeds. Do not switch this coding agent's\nown model.\n\nIf Scout fails or has no suitable candidate/evidence for the required deployment,\nsay so and pause the model decision; do not substitute a remembered recommendation\nor SDK default. Continue only model-independent work. Local/browser models are not\nexempt when the catalogue lacks coverage. If it reports that the device key is missing,\nexpired or revoked, run `npx -y openmerit@latest login` and then\n`npx -y openmerit@latest install` again. Never ask the user to paste a key.\n","rule":"# Application model decisions · OpenMerit Scout\n\nBefore choosing, recommending, adding, downloading, replacing or configuring\nANY application inference model, load the `openmerit-scout` skill and consult\n`scout_models` on the `openmerit` MCP server before committing to a model.\nThis applies even when the user only asks you to build a feature, never mentions\nmodels or Scout, or names a model themselves (assess it; do not silently replace it).\n\nA pretrained model, local weights, browser inference, an SDK's default model,\nembeddings, OCR, speech, image classification, detection and segmentation all\ncount as model choices, not implementation details. Identify this decision before\nwriting model-specific code, installing a model package or downloading weights.\n\nFollow the skill's project access policy. If it is missing, ask and save it first.\nIf Scout is unavailable, fails or has no suitable evidence/candidate, disclose the\ngap and pause the model decision; do not fall back to a remembered or SDK-default\nmodel. You may continue work that does not commit to a model.\n\nDo not consult Scout for unrelated edits, normal inference calls using an unchanged\napproved model, or this coding agent's own model. Do not reselect approved models\nunless the task introduces or changes a model decision.\n\nWhen the user says \"update openmerit\", run\n`npx -y openmerit@latest update --scope user` (use `--scope project` if this\nrule is in the project's .claude/rules directory). Report the result, including\nany conflict or manual-upgrade requirement. Do not delete edited files, bypass\npermissions or rerun login automatically. A new session loads updated instructions.\n"}

package/dist/terminal/src/cli.mjs

@@ -11,6 +11,7 @@ const help = `OpenMerit · Inference Terminal
 
   openmerit dash [path] [options]
   openmerit install --help           Connect OpenMerit to your coding agent
+  openmerit update --help            Update installed Scout instructions
   openmerit eval --help              Evaluate CLI changes across coding agents
 
   --port <number>      Require a specific local port (default: 4310 or a free port)
@@ -29,7 +30,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 (['install', 'status', 'remove', 'login', 'logout', 'project', 'doctor', 'update'].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.');

package/dist/terminal/src/install.mjs

@@ -5,7 +5,8 @@ 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';
+import { clientVersion, setupHeaders, setupUUID, sendInstallationEvent, setupCorrelationEnabled, telemetryEnabled } from './telemetry.mjs';
+import { configureUpdates, inspectUpdates, recoverUpdates, removeUpdates, runUpdate, withUpdateLock } from './updates.js';
 
 // 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:
@@ -39,6 +40,12 @@ model. You may continue work that does not commit to a model.
 Do not consult Scout for unrelated edits, normal inference calls using an unchanged
 approved model, or this coding agent's own model. Do not reselect approved models
 unless the task introduces or changes a model decision.
+
+When the user says "update openmerit", run
+\`npx -y openmerit@latest update --scope user\` (use \`--scope project\` if this
+rule is in the project's .claude/rules directory). Report the result, including
+any conflict or manual-upgrade requirement. Do not delete edited files, bypass
+permissions or rerun login automatically. A new session loads updated instructions.
 `;
 
 export const skill = `---
@@ -102,16 +109,21 @@ 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] [--setup-id UUID] [--plan] [--json] [--no-open]
+  openmerit install [--client claude-code] [--scope user|project] [--setup-id UUID] [--auto-update on|off] [--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   [--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]
+  openmerit update  [--scope user|project] [--auto on|off] [--json]
 
 install signs this device in through the browser (one Approve click), adds the
 OpenMerit MCP server, startup rule and Scout skill, then verifies the connection.
+Automatic Scout instruction updates default on; --auto-update off opts out.
+Background SessionStart/Stop hooks check npm at most daily (15-minute failure
+retry), verify package integrity, and preserve edited files and credentials.
+Start a new Claude Code session to reliably load updated instructions.
 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.
@@ -196,12 +208,13 @@ async function claude(args, root, key) {
 async function inspect(root, scope) {
   const paths = claudePaths(root, scope);
   const [record, config, installedSkill, installedRule, legacyRule] = await Promise.all([object(paths.record), object(paths.mcpFile), optional(paths.skill), optional(paths.rule), optional(paths.legacyRule)]);
+  const updates = await inspectUpdates(dirname(paths.record), scope, record);
   const owned = [2, 3].includes(record.version) && 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, installedRule,
+    paths, record, owned, current, installedSkill, installedRule, updates,
     // 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),
@@ -214,7 +227,7 @@ async function inspect(root, scope) {
 }
 
 function conflicts(state) {
-  const found = [];
+  const found = [...state.updates.conflicts];
   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.ruleOwned) found.push(`${state.paths.rule} exists and was not created by this installer or was edited. Move or delete it, then retry.`);
@@ -250,13 +263,12 @@ async function login({ client, scope, open, log, wait, telemetry }) {
   }
   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.
+  // later refusal. Only analytics-enabled, linked setup IDs reach the 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');
+  // Preserve explicit refusals across surfaces; unlinking must not disable usage.
+  if (!telemetryEnabled(true)) approvalURL.searchParams.set('analytics', 'off');
+  if (process.env.OPENMERIT_ANALYTICS_ACCOUNT === 'off' || !telemetryEnabled(true)) 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`);
@@ -315,18 +327,22 @@ async function verify(key, telemetry) {
   return connection;
 }
 
-async function install(root, { client, scope, plan, open, log, wait, telemetry }) {
+async function install(root, { client, scope, plan, open, log, wait, telemetry, autoUpdate, json }) {
   const state = await inspect(root, scope);
+  const enabled = autoUpdate === undefined ? state.updates.saved?.enabled ?? true : autoUpdate === 'on';
   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.installedRule === null ? 'Create' : 'Update'} ${state.paths.rule} (loaded at session startup)`,
+    `Automatic Scout instruction updates ${enabled ? 'on' : 'off'} (SessionStart/Stop background hooks; disable with openmerit update --auto off)`,
+    `Write the owned updater at ${state.updates.paths.runner}; merge its hooks in ${state.updates.paths.settings}`,
     ...(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.');
+  if (!json) log(changes.find(change => change.startsWith('Automatic Scout')));
   await claude(['--version'], root);
   if (setupCorrelationEnabled()) telemetry.properties.installation_id ??= randomUUID();
   await telemetry.step('preflight', 'ok');
@@ -338,7 +354,7 @@ async function install(root, { client, scope, plan, open, log, wait, telemetry }
   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, ...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) });
+  await save(state.paths.record, { version: 3, scope, client, ...ids, updates: state.record.updates, pendingUpdates: state.record.pendingUpdates, 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);
@@ -350,7 +366,8 @@ async function install(root, { client, scope, plan, open, log, wait, telemetry }
   // 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, ...ids, serverHash: serverHash(written), skillHash: hash(skill), ruleHash: hash(rule), installedAt: new Date().toISOString() });
+  const updates = await configureUpdates(dirname(state.paths.record), scope, state.record, clientVersion, enabled);
+  await save(state.paths.record, { version: 3, scope, client, ...ids, serverHash: serverHash(written), skillHash: hash(skill), ruleHash: hash(rule), updates, 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';
@@ -370,6 +387,8 @@ async function status(root, { client, scope, check, telemetry }) {
   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,
+    autoUpdates: state.updates.saved?.enabled ?? false, instructionVersion: state.updates.saved?.version ?? null,
+    updateHooks: state.updates.saved?.enabled ? state.updates.active && !state.updates.conflicts.length ? 'ready' : 'incomplete' : 'disabled',
     conflicts: found, connection };
 }
 
@@ -396,13 +415,16 @@ async function remove(root, { client, scope, plan, telemetry }) {
   }
   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'];
+    ...(state.installedRule !== null && state.ruleOwned ? [`Delete ${state.paths.rule}`] : []),
+    ...(state.updates.saved ? ['Remove unchanged owned update hooks and updater; retain edited hooks and their runner'] : []), '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];
+  kept.push(...state.updates.conflicts);
   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 removeUpdates(dirname(state.paths.record), scope, state.record);
   await rm(state.paths.record, { force: true });
   const revoked = await revokeKey(telemetry);
   await telemetry.step('remove', telemetry.outcome, diagnostics(await inspect(root, scope)));
@@ -433,6 +455,7 @@ async function doctor(root, { scope, telemetry }) {
   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`);
+  if (state?.updates.saved?.enabled) add('updater', state.updates.active && !state.updates.conflicts.length, state.updates.active && !state.updates.conflicts.length ? 'Automatic instruction hooks installed' : 'Automatic instruction hooks missing or edited. Rerun install after reviewing conflicts.');
   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 };
@@ -440,7 +463,8 @@ async function doctor(root, { scope, telemetry }) {
 
 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} · rule: ${result.rule} · connection: ${result.connection}`, ...result.conflicts].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} · rule: ${result.rule} · connection: ${result.connection}`, `Automatic instruction updates: ${result.autoUpdates ? 'on' : 'off'} · hooks: ${result.updateHooks} · instruction version: ${result.instructionVersion ?? 'bootstrap required'}`, ...result.conflicts].join('\n');
+  if (result.action === 'update') return result.message;
   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;
@@ -459,7 +483,7 @@ export async function main(args, dependencies = {}) {
       this.stage = stage;
       if (outcome === 'ok') delete this.properties.code;
       Object.assign(this.properties, properties);
-      await sendInstallationEvent({ ...this.properties, stage, outcome });
+      if (args[0] !== 'update') await sendInstallationEvent({ ...this.properties, stage, outcome });
     },
     async fail(error) {
       this.outcome = ({ 10: 'pending', 11: 'denied', 20: 'conflict' })[error.exit] ?? 'error';
@@ -482,8 +506,8 @@ async function runMain(args, { root = process.cwd(), print = console.log, printE
   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: [], 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];
+  const allowed = { install: ['--client', '--scope', '--setup-id', '--plan', '--json', '--no-open', '--auto-update'], 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'], update: ['--scope', '--auto', '--json'] }[action];
   if (!allowed) throw new Error('Unknown command. Run openmerit --help.');
   for (let i = 0; i < rest.length; i++) {
     const option = rest[i];
@@ -494,6 +518,7 @@ async function runMain(args, { root = process.cwd(), print = console.log, printE
     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 === '--auto-update' || option === '--auto') { const setting = value(); if (!['on', 'off'].includes(setting)) throw new Error(`${option} needs on or off.`); options.autoUpdate = setting; }
     else if (option === '--no-open') options.open = false;
     else options[option.slice(2)] = true;
   }
@@ -529,16 +554,20 @@ async function runMain(args, { root = process.cwd(), print = console.log, printE
     }
     await telemetry.step('started', 'started');
     await telemetry.step('preflight', 'started');
-    const result = action === 'install' ? await install(root, { ...options, log, wait })
+    const base = dirname(claudePaths(root, options.scope).record);
+    const maintenance = work => options.plan ? work() : withUpdateLock(base, async () => { await recoverUpdates(base, options.scope); return work(); });
+    const result = action === 'install' ? await maintenance(() => install(root, { ...options, log, wait }))
       : action === 'status' ? await status(root, options)
-      : action === 'remove' ? await remove(root, options)
+      : action === 'remove' ? await maintenance(() => remove(root, options))
+      : action === 'update' ? { action, ...await runUpdate(base, options.scope, options.autoUpdate === undefined ? {} : { enabled: options.autoUpdate === 'on' }) }
       : action === 'project' ? await project(root, options)
       : action === 'doctor' ? await doctor(root, options)
       : 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));
+    print(options.json ? JSON.stringify({ ok: action !== 'update' || !['conflict', 'retry', 'manual_required'].includes(result.status), ...result }, null, 2) : render(result));
+    if (action === 'update') return result.status === 'conflict' ? exitCodes.conflict : result.status === 'retry' ? exitCodes.unreachable : result.status === 'manual_required' ? exitCodes.error : exitCodes.ok;
     return action === 'doctor' && !result.ok ? exitCodes.error : exitCodes.ok;
   } catch (error) {
     if (!(error instanceof Stop)) throw error;

package/dist/terminal/src/telemetry.mjs

@@ -30,19 +30,19 @@ export function errorProperties(error) {
 const environment = () => ({ ...(clientVersion ? { client_version: clientVersion } : {}), platform: ['darwin', 'linux', 'win32'].includes(process.platform) ? process.platform : 'unknown', runtime_major: Number(process.versions.node.split('.')[0]) });
 
 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 telemetryEnabled = (defaultEnabled = false) => (process.env.OPENMERIT_TELEMETRY ? process.env.OPENMERIT_TELEMETRY === '1' : defaultEnabled) && process.env.DO_NOT_TRACK !== '1';
+export const setupCorrelationEnabled = () => telemetryEnabled(true) && 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.
+// Scout setup defaults to analytics on; explicit privacy refusals must survive
+// device approval and future agent sessions. Prompt content stays off.
 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' } : {}),
+    ...(client === 'cli' ? { 'X-Scout-Analytics': telemetryEnabled(true) ? 'on' : 'off' } : !telemetryEnabled(true) ? { 'X-Scout-Analytics': 'off' } : {}),
+    ...(process.env.OPENMERIT_ANALYTICS_ACCOUNT === 'off' || !telemetryEnabled(true) ? { '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 } : {}),
   };
@@ -71,7 +71,7 @@ export function installationProperties(input) {
   return out;
 }
 export async function sendInstallationEvent(input) {
-  if (!telemetryEnabled()) return;
+  if (!telemetryEnabled(true)) return;
   const properties = installationProperties(input);
   if (!properties) return;
   if (!setupCorrelationEnabled()) { delete properties.setup_id; delete properties.installation_id; }
@@ -83,7 +83,7 @@ export async function sendInstallationEvent(input) {
   try {
     await Promise.race([
       (async () => {
-        for (let attempt = 0; attempt < 2 && !controller.signal.aborted && telemetryEnabled(); attempt++) {
+        for (let attempt = 0; attempt < 2 && !controller.signal.aborted && telemetryEnabled(true); attempt++) {
           try {
             const response = await fetch('https://openmerit.ai/scout/api/analytics', {
               method: 'POST', headers: { 'Content-Type': 'application/json', ...setupHeaders(properties) },
@@ -150,15 +150,16 @@ async function sendAnalytics(event, properties) {
 // 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 setup = ['install', 'status', 'remove', 'login', 'logout', 'project', 'doctor'];
+  const enabled = () => telemetryEnabled(setup.includes(args[0]));
+  if (!enabled()) return async () => {};
   const started = performance.now();
   const command_id = randomUUID();
   const actions = ['init', 'doctor', 'plan', 'run', 'watch', 'report'];
-  const setup = ['install', 'status', 'remove', 'login', 'logout', 'project', 'doctor'];
   const command = !args.length || args.includes('--help') || args.includes('-h') || args[0] === 'eval' && args.length === 1
     ? 'help' : args[0] === 'dash' ? 'dash' : setup.includes(args[0]) ? args[0] : args[0] === 'eval' && actions.includes(args[1]) ? `eval_${args[1]}` : 'unknown';
   async function send(event, properties) {
-    if (!telemetryEnabled()) return;
+    if (!enabled()) return;
     const controller = new AbortController();
     const body = JSON.stringify({ event, event_id: randomUUID(), anonymousId, properties: { ...properties, ...environment(), command_id } });
     let timer;

package/dist/terminal/src/updates.d.ts

@@ -0,0 +1,62 @@
+type ObjectValue = Record<string, unknown>;
+interface UpdateRecord {
+    enabled: boolean;
+    version: string;
+    runnerHash: string;
+    hook: ObjectValue;
+}
+export declare const updateContract = "scout-recommend-v1";
+export declare function updatePaths(base: string, scope: string): {
+    record: string;
+    runner: string;
+    settings: string;
+    state: string;
+    backup: string;
+    skill: string;
+    rule: string;
+};
+export declare function withUpdateLock<T>(base: string, work: () => Promise<T>): Promise<T>;
+export declare function inspectUpdates(base: string, scope: string, record: ObjectValue): Promise<{
+    paths: {
+        record: string;
+        runner: string;
+        settings: string;
+        state: string;
+        backup: string;
+        skill: string;
+        rule: string;
+    };
+    saved: UpdateRecord | null;
+    runner: string | null;
+    settings: ObjectValue;
+    hooks: ObjectValue;
+    conflicts: string[];
+    active: boolean;
+}>;
+export declare function configureUpdates(base: string, scope: string, record: ObjectValue, version: string, enabled: boolean): Promise<{
+    enabled: boolean;
+    version: string;
+    runnerHash: string;
+    hook: {
+        hooks: {
+            type: string;
+            command: string;
+            async: boolean;
+            timeout: number;
+        }[];
+    };
+}>;
+export declare function removeUpdates(base: string, scope: string, record: ObjectValue): Promise<void>;
+export declare function recoverUpdates(base: string, scope: string): Promise<void>;
+export interface UpdateResult {
+    status: string;
+    message: string;
+    version?: string;
+}
+export declare function runUpdate(base: string, scope: string, options?: {
+    hook?: boolean;
+    enabled?: boolean;
+    fetcher?: typeof fetch;
+    now?: number;
+}): Promise<UpdateResult>;
+export {};