@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

package/AGENT_SETUP.md

@@ -1,6 +1,6 @@
 # FX 数据诊断：Agent 安装与管理
 
-本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261026070913`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
+本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261107142011`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
 
 用户明确要求安装、更新、回退、卸载或检查 FX 数据诊断时，也会触发薄 Skill，并直接执行对应管理命令，不先运行 `context` 或读取诊断规则；只有开始诊断时才按薄 Skill 加载内容。普通聊天不主动加载。
 
@@ -49,20 +49,22 @@
 - 独立 Node 环境下，用其绝对路径运行配套 `npm-cli.js`（Unix：`lib/node_modules/npm/bin/npm-cli.js`；Windows：`node_modules/npm/bin/npm-cli.js`）。通过同一环境的 `npm root -g` 找到包，沿用自定义 prefix，再用同一 Node 调用包内 `bin/core-ai.mjs` 登记。路径含空格时保留引号；Windows PowerShell 调用带引号的可执行路径需要 `&`。不依赖用户项目目录。
 - 全局目录不可写时仅为本次安装指定用户目录的 `--prefix`；现有源找不到本包时仅为本次命令指定 `--registry=https://registry.npmjs.org`，不改全局 npm 配置。
 - 安装失败时同时读取 stderr 中的错误和分项检查。Node 路径失效时修复原运行环境；内容损坏、所有权冲突或权限错误应处理具体错误，不通过第二份安装绕过。需要进一步排错时再运行 `doctor`。
-- 复用旧版时，若 `install` 尚未返回 `checks` 和 `context`，仅此分支补跑稳定入口的 `doctor`、`context` 验证，不因此升级或重新下载。Python 缺失不阻止登记，首次解析材料时再准备。
+- 复用旧版时，若 `install` 尚未返回 `checks` 和 `context`，仅此分支补跑稳定入口的 `doctor`、`context` 验证，不因此升级或重新下载。Python 缺失不阻止登记，首次运行包内 Python 脚本时再准备。
 - WorkBuddy 的 `.workbuddy/skills` 与 `.workbuddy-ai/skills` 由 CLI 按本机线索选择；无法确认时按 CLI 提示处理，不自行扫描客户端缓存或改成两处同时登记。
 
 ## 按需使用
 
-用户明确要求用 FX 数据诊断分析问题后，按薄 Skill 执行 `context`，读取返回的 `agent_rules`，只加载当前问题需要的 Skill 和引用。固定本次调查的版本与 `pinned_cli`；普通聊天和管理请求无需预加载诊断内容。
+用户明确要求用 FX 数据诊断分析问题后，按薄 Skill 调用一次稳定入口的 `context`，读取返回的 `agent_rules`，只加载当前问题需要的 Skill 和引用。CLI 同时在后台检查更新，固定本次调查返回的版本与 `pinned_cli`；同一调查继续复用，不重复调用稳定入口的 `context`。普通聊天和管理请求无需预加载诊断内容或检查更新。
 
-已有 SigNoZ MCP 直接复用；实时查询受阻时才按包内配置 Skill 处理，凭据只保存在本机。Python 解析按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。
+已有 SigNoZ MCP 直接复用；实时查询受阻时才按包内配置 Skill 处理，凭据只保存在本机。Python 按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。
 
 ## 更新与回退
 
-用户要求更新时，调用稳定入口的 `update`；要求回退到上次更新前时调用 `rollback`，明确指定版本时调用 `update --version <版本号>`。新调查使用切换后的版本，进行中的调查保持原版本。新增客户端只登记，不隐式更新。
+用户要求更新时，调用稳定入口的 `update`；要求回退到上次更新前时调用 `rollback`，明确指定版本时调用 `update --version <版本号>`。新调查使用切换后的版本，进行中的调查保持原版本。回退不锁定后续版本，下一次新诊断仍检查最新版；需要持续使用旧版时按配置变量关闭后台更新。新增客户端只登记，不隐式更新。
 
-用户要求自动更新时，通过当前客户端或系统调度同一稳定入口的 `update`，告知是否设置成功；普通诊断不自动检查或更新。版本切换后按客户端要求刷新技能或新开聊天。
+使用时的后台更新由 CLI 完成，无需 Agent 设置定时任务或另跑 `update`。通知读取、去重和提示按 [安装副本的助手规则](content/AGENTS.md#安装副本的助手规则)执行，不轮询等待。
+
+旧版用户需先手动升级一次才能获得后台更新能力。版本切换后按客户端要求刷新技能或新开聊天。
 
 若旧试用版提示需要迁移，先用当前 npm 包替换全局程序，直接调用新包 CLI 的 `update`，再登记与检查。迁移保留客户端登记、诊断材料和独立 MCP 配置；旧试用版不作为回退目标。
 
@@ -83,5 +85,6 @@ CLI 使用首次安装记录的 Node/npm 和 prefix，在无网络模式下清
 | `FX_DATA_DIAGNOSTICS_HOME` | 自定义共享安装目录 |
 | `FX_DATA_DIAGNOSTICS_PYTHON` | 自定义 Python 可执行文件 |
 | `FX_DATA_DIAGNOSTICS_AGENT_HOME` | 自定义客户端用户目录，通常无需设置 |
+| `FX_DATA_DIAGNOSTICS_AUTO_UPDATE` | 默认开启后台更新；设为 `0` 可关闭，适用于受限环境或需要持续使用旧版时 |
 
 显式 CLI 参数优先，其次是环境变量，未指定时使用默认目录或自动发现的运行环境。

package/README.md

@@ -22,13 +22,13 @@
 
 ## 更新
 
-> 更新 FX 数据诊断。
+每次开始新诊断时，工具会在后台检查更新，不等待更新即可排查。更新成功后，各 Agent 的下一次新诊断使用新版；当前调查保持原版本，更新失败也不影响排查。Agent 会随后续使用提示更新状态，没有新版时不打扰你。
 
-已启用的 Agent 共用更新后的版本。需要自动更新时，可以说：
+需要立即更新并等待完成时说：
 
-> 帮我设置每天上午 9 点（北京时间）检查并更新 FX 数据诊断的任务，失败时通知我。
+> 更新 FX 数据诊断。
 
-能否设置定时任务取决于当前Agent。若新版有问题，可以说“把 FX 数据诊断回退到这次更新前的版本”。
+旧版用户先手动更新一次，即可获得后台更新能力。若新版有问题，可以说“把 FX 数据诊断回退到这次更新前的版本”；需要持续使用旧版时，同时让 Agent 关闭后台更新。
 
 ## 卸载
 
@@ -38,4 +38,4 @@
 
 ---
 
-**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261026070913/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。
+**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261107142011/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。

package/bin/core-ai.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-// Distribution only: diagnostic rules and parsers live in the unchanged content bundle.
+// Distribution only: diagnostic rules and scripts live in the unchanged content bundle.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -29,7 +29,7 @@ function argumentsFor(argv) {
     if (args[i] === '--activate-package') {
       if (command !== 'update') throw new Error('--activate-package is reserved for the update subprocess');
       options.activatePackage = true;
-    } else if (['--home', '--agent-home', '--agent', '--skills-dir', '--registry', '--version'].includes(args[i])) {
+    } else if (['--home', '--agent-home', '--agent', '--skills-dir', '--registry', '--version', '--background-job'].includes(args[i])) {
       if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`Missing value for ${args[i]}`);
       options[args[i].slice(2)] = args[++i];
     } else rest.push(args[i]);
@@ -53,11 +53,11 @@ function commandHelp(argv) {
   let target;
   if (['help', '--help', '-h'].includes(command)) target = Object.hasOwn(commands, args[0]) ? args[0] : 'help';
   else if (Object.hasOwn(commands, command) && args.some(arg => arg === '--help' || arg === '-h')) target = command;
-  else return null; // metric/python keep their parser or script help arguments.
+  else return null; // python keeps the script's own help arguments.
   const note = '帮助只显示说明，不执行命令。安装和管理成功以命令返回结果为准，简短反馈后停止，无需额外 status 或 doctor。';
   if (target !== 'help') return { ok: true, action: 'help', command: target, ...commands[target], note };
   return { ok: true, action: 'help', name: commandName, display_name: 'FX 数据诊断',
-    commands: [...Object.values(commands).map(value => value.usage), 'metric <parser options>', 'python <script> [args...]'],
+    commands: [...Object.values(commands).map(value => value.usage), 'python <script> [args...]'],
     registry: defaultRegistry, note };
 }
 
@@ -183,9 +183,13 @@ ${powershell} context
 
 后续管理命令使用同一组 Node 和稳定脚本路径，将 context 替换为对应子命令，不依赖 PATH 中的全局 CLI 版本。
 
-context 返回当前版本、内容路径和 agent_rules。读取 agent_rules，按问题只读取所需 Skill 和引用，不预加载全部知识，也不切换用户工作区。包内仓库相对路径以 content_root 为基准，文档链接相对引用文件解析。
+每次新诊断只调用一次稳定入口 context：立即取得并固定本次版本，同时后台检查更新，不等待网络。同一调查继续复用首次结果，不重复调用稳定入口 context；需要重新读取固定路径时使用 pinned_cli context，不触发新检查。
 
-当前调查固定使用首次 context 返回的 node、pinned_cli 和内容版本。脚本通过 <node> <pinned_cli> python <脚本绝对路径> ... 执行；Windows PowerShell 同样在带引号的 Node 路径前加 &。Metric 调用先读取 analyze-engine-metric 的输入表：纯文本用 metric --metric；SigNoZ JSON 用 metric --metric-log-json <文件> --task-name <选定 task>。通过 session 获取临时目录，日志和产物不写入安装内容。只有解析脚本需要 Python；doctor 的 python.available=false 表示按需补齐，不代表安装失败。已有 MCP 直接复用；实时查询受阻时才读取 setup-signoz-mcp。
+context 返回当前版本、内容路径和 agent_rules。读取 agent_rules，按问题只读取所需知识（先看对应域的 workflow.md），不预加载全部知识，也不切换用户工作区。包内仓库相对路径以 content_root 为基准，文档链接相对引用文件解析。
+
+context、status、session 的 auto_update.notification，以及 python 标准错误中 fx_data_diagnostics.auto_update.notification，是更新提示。有提示时按 message 简短告知用户；无新版不打扰。不为获取状态额外调用 CLI 或轮询；本轮没有后续 CLI 调用时，下次使用再补报。更新成功只影响下次新诊断，失败继续使用本次版本。
+
+当前调查固定使用首次 context 返回的 node、pinned_cli 和内容版本。脚本通过 <node> <pinned_cli> python <脚本绝对路径> ... 执行；Windows PowerShell 同样在带引号的 Node 路径前加 &。通过 session 获取临时目录，保存日志和 Metric 正文，不写入安装内容。只有包内 Python 脚本需要 Python；doctor 的 python.available=false 表示按需补齐，不代表安装失败。已有 MCP 直接复用；实时查询受阻时才读取 setup-signoz-mcp。
 
 用户要求更新时执行稳定入口 update，默认使用 latest；要求回退到上次更新前时执行 rollback，也可用 --version 指定版本。已保留版本校验通过后直接复用。各客户端的新调查共用切换后的版本，进行中调查继续使用原 pinned_cli。更新后按客户端要求刷新技能或新开聊天；安装副本不做 Git 更新。
 
@@ -262,7 +266,7 @@ function skillChecks(targets, home, installId) {
 function contextFor(root, home, pkg, manifest) {
   const content = path.join(root, 'content');
   return { version: pkg.version, source_commit: manifest.source_commit, content_root: content,
-    agent_rules: path.join(content, 'AGENTS.md'), skills_root: path.join(content, '.agents', 'skills'),
+    agent_rules: path.join(content, 'AGENTS.md'),
     pinned_cli: path.join(root, 'bin', 'core-ai.mjs'), node: process.execPath,
     launcher: launchers(home).executable, launcher_script: launchers(home).script };
 }
@@ -362,6 +366,7 @@ function install(home, options, { sourceRoot = packageRoot, action = 'install' }
   const { pkg, manifest } = verifyBundle(sourceRoot, { allowMacMetadata: isInstalledBundle(sourceRoot, home) });
   noSymlinkAncestors(home);
   const prior = ownedState(home, false);
+  if (options['background-job']) assertBackgroundJob(home, options['background-job'], pkg.version);
   if (!prior && fs.existsSync(home) && fs.readdirSync(home).length) throw new Error('Refusing to take over a nonempty installation directory');
   const ownership = prior?.ownership || { schema_version: 1, home, install_id: randomUUID() };
   const registrationOnly = Boolean(action === 'install' && prior?.state?.lifecycle_protocol === lifecycleProtocol);
@@ -387,9 +392,13 @@ function install(home, options, { sourceRoot = packageRoot, action = 'install' }
   if (!prior) atomicWrite(path.join(home, homeMarker), JSON.stringify(ownership));
   const releaseLock = acquireInstallLock(home);
   let backup = [];
+  const launcherBackup = [];
   const release = path.join(home, 'releases', pkg.version);
   const stage = `${release}.${randomUUID()}.tmp`;
   try {
+    // A download may outlive its worker or a manual version change. Recheck at
+    // activation, under the installation lock, before touching shared entries.
+    if (options['background-job']) assertBackgroundJob(home, options['background-job'], pkg.version);
     backup = writeDirectories.map(target => ({ ...target, existed: fs.existsSync(target.directory), text: fs.existsSync(path.join(target.directory, 'SKILL.md')) ? fs.readFileSync(path.join(target.directory, 'SKILL.md')) : null, owner: fs.existsSync(path.join(target.directory, ownerFile)) ? fs.readFileSync(path.join(target.directory, ownerFile)) : null }));
     if (fs.existsSync(release)) {
       verifyBundle(release, { allowMacMetadata: Boolean(prior?.state) });
@@ -412,15 +421,21 @@ function install(home, options, { sourceRoot = packageRoot, action = 'install' }
       [path.join(home, 'bin', commandName), `#!/bin/sh\nexec ${quote(process.execPath)} ${quote(launchers(home).script)} "$@"\n`],
       [path.join(home, 'bin', `${commandName}.cmd`), `@echo off\r\n"${process.execPath}" "%~dp0core-ai.mjs" %*\r\n`],
     ]) {
-      if (!registrationOnly || !fs.existsSync(file)) atomicWrite(file, text, 0o755);
+      if (!registrationOnly || !fs.existsSync(file)) {
+        const existed = fs.existsSync(file);
+        launcherBackup.push({ file, existed, text: existed ? fs.readFileSync(file) : null,
+          mode: existed ? fs.statSync(file).mode & 0o777 : 0o755 });
+        atomicWrite(file, text, 0o755);
+      }
     }
     const registrationReady = performance.now();
     const checks = { integrity: { status: 'ok' }, skills: skillChecks(targets, home, ownership.install_id), context: { status: 'ok' } };
     if (checks.skills.status !== 'ok') throw new Error(checks.skills.entries.filter(entry => entry.status === 'error').map(entry => entry.error).join('; '));
     const context = contextFor(release, home, pkg, manifest);
     fs.accessSync(context.agent_rules, fs.constants.R_OK);
-    if (!fs.statSync(context.skills_root).isDirectory()) throw new Error('Diagnostic skills directory is unavailable');
-    fs.accessSync(context.skills_root, fs.constants.R_OK);
+    const knowledgeRoot = path.join(context.content_root, 'knowledge');
+    if (!fs.statSync(knowledgeRoot).isDirectory()) throw new Error('Diagnostic knowledge directory is unavailable');
+    fs.accessSync(knowledgeRoot, fs.constants.R_OK);
     if (!registrationOnly) atomicWrite(path.join(home, homeMarker), JSON.stringify(ownership));
     const releaseProtocols = { ...prior?.state?.release_protocols };
     if (prior?.state?.lifecycle_protocol === lifecycleProtocol) releaseProtocols[prior.state.version] = lifecycleProtocol;
@@ -430,6 +445,9 @@ function install(home, options, { sourceRoot = packageRoot, action = 'install' }
     const npmInstallation = prior?.state ? prior.state.npm_installation : detectNpmInstallation(sourceRoot);
     const state = { schema_version: 1, lifecycle_protocol: lifecycleProtocol, release_protocols: releaseProtocols, install_id: ownership.install_id, package: pkg.name, version: pkg.version, previous_version: prior?.state?.version === pkg.version ? prior.state.previous_version : prior?.state?.version || null, registry, skills: targets, source_commit: manifest.source_commit,
       ...(npmInstallation ? { npm_installation: npmInstallation } : {}) };
+    // Copying and validation can outlast the background deadline. The last
+    // check belongs immediately before committing the active version too.
+    if (options['background-job']) assertBackgroundJob(home, options['background-job'], pkg.version);
     if (JSON.stringify(state) !== JSON.stringify(prior?.state)) atomicWrite(path.join(home, 'state.json'), JSON.stringify(state, null, 2));
     const finished = performance.now();
     const elapsed = (from, to) => Math.round((to - from) * 100) / 100;
@@ -440,6 +458,10 @@ function install(home, options, { sourceRoot = packageRoot, action = 'install' }
         agent_hint: '安装登记与文件检查已完成。按返回结果用 2–3 句话反馈版本、首次安装或复用、需要的刷新及使用提示后结束；不再运行 status/ls/doctor/context 或读取源码、客户端缓存。本工具不要求安装清单或长期记忆，仍遵循客户端强制规则。客户端发现未验证时只提示刷新或新开聊天。' } : {}),
       refresh: 'Open a new Agent conversation if the skill has not refreshed.' });
   } catch (error) {
+    for (const item of launcherBackup) {
+      if (item.existed) atomicWrite(item.file, item.text, item.mode);
+      else fs.rmSync(item.file, { force: true });
+    }
     for (const item of backup) {
       if (item.existed) { atomicWrite(path.join(item.directory, 'SKILL.md'), item.text, 0o644); atomicWrite(path.join(item.directory, ownerFile), item.owner); }
       else if (fs.existsSync(item.directory)) fs.rmSync(item.directory, { recursive: true });
@@ -565,11 +587,187 @@ function update(home, options, action = 'update') {
   for (const key of Object.keys(env)) if (key.toLowerCase() === 'path') delete env[key];
   env.PATH = [path.dirname(process.execPath), inheritedPath].filter(Boolean).join(path.delimiter);
   Object.assign(env, { FX_DATA_DIAGNOSTICS_HOME: home, NPM_CONFIG_USERCONFIG: path.join(npmHome, 'user.npmrc'), NPM_CONFIG_GLOBALCONFIG: path.join(npmHome, 'global.npmrc'), NPM_CONFIG_CACHE: path.join(npmHome, 'cache'), NPM_CONFIG_REGISTRY: registry, NPM_CONFIG_UPDATE_NOTIFIER: 'false' });
-  const result = spawnSync(process.execPath, [npmExecutable(), 'exec', '--yes', '--registry', registry, '--package', `${state.package}@${version}`, '--', commandName, 'update', '--activate-package', '--home', home, '--registry', registry], { cwd: npmHome, env, stdio: 'inherit' });
+  const background = options['background-job'];
+  if (background) assertBackgroundJob(home, background, version);
+  const result = spawnSync(process.execPath, [npmExecutable(), 'exec', '--yes', '--registry', registry,
+    ...(background ? ['--fetch-retries=0', '--fetch-timeout=15000', '--ignore-scripts'] : []),
+    '--package', `${state.package}@${version}`, '--', commandName, 'update', '--activate-package', '--home', home, '--registry', registry,
+    ...(background ? ['--background-job', background] : [])], { cwd: npmHome, env, stdio: 'inherit' });
   if (result.error) throw result.error;
   process.exitCode = result.status ?? 1;
 }
 
+// Automatic updates belong to the shared installation, not to an Agent. Only
+// a new diagnostic entry starts a worker; pinned scripts merely carry notices.
+const autoUpdateFile = 'auto-update.json';
+const autoUpdateLock = '.auto-update.lock';
+const autoUpdateNotice = 'auto-update-notice.json';
+const autoUpdateTimeout = 60_000;
+const autoUpdateEnabled = () => process.env.FX_DATA_DIAGNOSTICS_AUTO_UPDATE !== '0';
+const readOptional = file => { try { return json(file); } catch { return null; } };
+
+function deadProcess(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); } catch (error) { return error.code === 'ESRCH'; }
+  return false;
+}
+
+function newerVersion(candidate, current) {
+  if (!versionPattern.test(candidate) || !versionPattern.test(current)) return false;
+  const split = value => { const [core, ...pre] = value.split('-'); return { core: core.split('.').map(BigInt), pre: pre.join('-') }; };
+  const next = split(candidate), old = split(current);
+  for (let i = 0; i < 3; i++) if (next.core[i] !== old.core[i]) return next.core[i] > old.core[i];
+  if (!next.pre || !old.pre) return Boolean(old.pre && !next.pre);
+  const left = next.pre.split('.'), right = old.pre.split('.');
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    if (left[i] === undefined || right[i] === undefined) return right[i] === undefined;
+    if (left[i] === right[i]) continue;
+    const numericLeft = /^\d+$/.test(left[i]), numericRight = /^\d+$/.test(right[i]);
+    if (numericLeft && numericRight) return BigInt(left[i]) > BigInt(right[i]);
+    return numericLeft !== numericRight ? !numericLeft : left[i] > right[i];
+  }
+  return false;
+}
+
+function updateJobOwned(home, id) {
+  const lock = readOptional(path.join(home, autoUpdateLock));
+  return lock?.id === id && lock.hostname === os.hostname();
+}
+
+function releaseUpdateJob(home, id) {
+  try {
+    if (updateJobOwned(home, id)) fs.rmSync(path.join(home, autoUpdateLock), { force: true });
+  } catch { /* Optional background bookkeeping cannot fail a diagnostic call. */ }
+}
+
+function saveUpdateJob(home, job, status) {
+  if (!updateJobOwned(home, job.id) || ownedState(home, false)?.state?.install_id !== job.install_id) return;
+  job.status = status;
+  atomicWrite(path.join(home, autoUpdateFile), JSON.stringify(job));
+  const message = status === 'updating'
+    ? `发现 FX 数据诊断新版 ${job.target_version}，正在后台更新。本次分析继续使用已固定版本，更新成功后下次诊断生效。`
+    : status === 'updated'
+      ? `FX 数据诊断已后台更新至 ${job.target_version}，供下次新诊断使用；进行中的分析仍使用各自已固定的版本。`
+      : status === 'failed'
+        ? 'FX 数据诊断后台检查或更新未完成，继续使用当前可用版本，不影响本次排查。'
+        : null;
+  if (message) atomicWrite(path.join(home, autoUpdateNotice), JSON.stringify({ id: `${job.id}:${status}`, install_id: job.install_id, status, message }));
+}
+
+function autoUpdateDetails(home) {
+  if (!autoUpdateEnabled()) return null;
+  try {
+    const state = ownedState(home, false)?.state;
+    if (!state) return null;
+    const job = readOptional(path.join(home, autoUpdateFile));
+    const details = job?.install_id === state.install_id
+      ? { status: job.status, ...(job.target_version ? { target_version: job.target_version } : {}) } : null;
+    // Claim one notice without deleting a newer notice written concurrently.
+    // Other clients may receive the next state; the worker never writes to a
+    // parent's terminal and diagnostic/script stdout keeps its original shape.
+    const claimed = path.join(home, `${autoUpdateNotice}.${randomUUID()}.read`);
+    try {
+      fs.renameSync(path.join(home, autoUpdateNotice), claimed);
+      const notice = readOptional(claimed);
+      if (notice?.install_id === state.install_id) return { ...details, notification: { id: notice.id, status: notice.status, message: notice.message } };
+    } catch { /* No notice, or another CLI already delivered it. */ }
+    finally { fs.rmSync(claimed, { force: true }); }
+    return details;
+  } catch { return null; } // Update bookkeeping must never block diagnosis.
+}
+
+function assertBackgroundJob(home, id, version) {
+  const job = readOptional(path.join(home, autoUpdateFile));
+  const state = ownedState(home, false)?.state;
+  if (!updateJobOwned(home, id) || job?.id !== id || job.status !== 'updating'
+    || Date.now() >= job.expires_at || deadProcess(job.pid)
+    || !state || state.install_id !== job.install_id || state.version !== job.base_version
+    || version !== job.target_version) throw new Error('Background update is no longer applicable; keeping the current installation');
+}
+
+function startAutoUpdate(home) {
+  if (!autoUpdateEnabled()) return;
+  let job;
+  try {
+    const { state } = ownedState(home);
+    if (!state) return;
+    const lockPath = path.join(home, autoUpdateLock);
+    const existing = readOptional(lockPath);
+    if (fs.existsSync(lockPath)) {
+      // Age alone does not permit stealing a live worker's lock. Failed jobs
+      // have no cooldown; after a dead worker the next diagnosis can try again.
+      if (existing?.hostname !== os.hostname() || !deadProcess(existing.pid)) return;
+      if (readOptional(lockPath)?.id !== existing.id) return;
+      fs.unlinkSync(lockPath);
+    }
+    job = { id: randomUUID(), install_id: state.install_id, base_version: state.version,
+      pid: process.pid, hostname: os.hostname(), status: 'checking', expires_at: Date.now() + autoUpdateTimeout };
+    const fd = fs.openSync(lockPath, 'wx', 0o600);
+    try { fs.writeFileSync(fd, JSON.stringify(job)); } finally { fs.closeSync(fd); }
+    saveUpdateJob(home, job, 'checking');
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^(NPM_TOKEN|NODE_AUTH_TOKEN)$/i.test(key)));
+    const child = spawn(process.execPath, [path.join(home, 'releases', state.version, 'bin/core-ai.mjs'), '__background-update', job.id, '--home', home],
+      { cwd: home, env, detached: true, stdio: 'ignore', windowsHide: true });
+    child.on('error', () => {
+      try { saveUpdateJob(home, job, 'failed'); } catch { /* Diagnosis still works. */ }
+      finally { releaseUpdateJob(home, job.id); }
+    });
+    if (child.pid) {
+      // Hand the live lock to the worker before the launching CLI exits.
+      job.pid = child.pid;
+      atomicWrite(lockPath, JSON.stringify(job));
+    }
+    child.unref();
+  } catch (error) {
+    if (job && updateJobOwned(home, job.id)) {
+      try { saveUpdateJob(home, job, 'failed'); } catch { /* Best effort only. */ }
+      finally { releaseUpdateJob(home, job.id); }
+    }
+  }
+}
+
+async function backgroundUpdate(home, id) {
+  const job = readOptional(path.join(home, autoUpdateFile));
+  if (job?.id !== id || !updateJobOwned(home, id)) return;
+  job.pid = process.pid;
+  try {
+    const state = ownedState(home).state;
+    if (!state || state.install_id !== job.install_id || state.version !== job.base_version) return;
+    saveUpdateJob(home, job, 'checking');
+    const registry = registryOrigin(state.registry);
+    const response = await fetch(`${registry}/${encodeURIComponent(state.package)}/latest`,
+      { signal: AbortSignal.timeout(3_000), redirect: 'error', headers: { Accept: 'application/json', 'Cache-Control': 'no-cache' } });
+    if (!response.ok) throw new Error('Version check failed');
+    const latest = await response.json();
+    if (latest.name !== state.package || typeof latest.version !== 'string' || !versionPattern.test(latest.version)) throw new Error('Invalid latest version');
+    if (!newerVersion(latest.version, state.version)) { saveUpdateJob(home, job, 'current'); return; }
+    job.target_version = latest.version;
+    saveUpdateJob(home, job, 'updating');
+    assertBackgroundJob(home, id, latest.version);
+    // Reuse the explicit-version updater in an isolated child. Its output must
+    // not keep the initiating Agent tool open or mix with diagnostic results.
+    await new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, [fileURLToPath(import.meta.url), 'update', '--version', latest.version,
+        '--home', home, '--background-job', id], { cwd: home, env: process.env, stdio: 'ignore', windowsHide: true });
+      const timer = setTimeout(() => {
+        // Invalidate activation before stopping the child: npm may have its own
+        // subprocess, which must not activate a release after this deadline.
+        try { saveUpdateJob(home, job, 'failed'); } catch { /* Best effort. */ }
+        child.kill('SIGKILL');
+        reject(new Error('Background update timed out'));
+      }, Math.max(1, job.expires_at - Date.now()));
+      child.once('error', error => { clearTimeout(timer); reject(error); });
+      child.once('exit', code => { clearTimeout(timer); code === 0 ? resolve() : reject(new Error('Background update failed')); });
+    });
+    if (ownedState(home, false)?.state?.version !== latest.version) throw new Error('Version activation was not confirmed');
+    saveUpdateJob(home, job, 'updated');
+  } catch {
+    try { if (job.status !== 'failed') saveUpdateJob(home, job, 'failed'); } catch { /* Never disturb the active release. */ }
+  } finally {
+    releaseUpdateJob(home, id);
+  }
+}
+
 function python() {
   const configured = process.env.FX_DATA_DIAGNOSTICS_PYTHON;
   const candidates = configured ? [[configured]] : process.platform === 'win32' ? [['py', '-3'], ['python'], ['python3']] : [['python3'], ['python']];
@@ -577,7 +775,7 @@ function python() {
     const probe = spawnSync(args[0], [...args.slice(1), '-I', '-B', '-c', 'import sys; print(sys.executable); sys.exit(0 if sys.version_info >= (3,9) else 1)'], { encoding: 'utf8' });
     if (probe.status === 0) return { executable: probe.stdout.trim(), available: true };
   }
-  return { available: false, requirement: 'Python 3.9+ is required for offline Metric parsing.' };
+  return { available: false, requirement: 'Python 3.9+ is required to run bundled scripts.' };
 }
 
 function uninstall(home) {
@@ -595,7 +793,7 @@ function uninstall(home) {
   // Remove only owned program files. Configuration, npm cache and evidence are retained.
   // Keep the stable command and state until version cleanup completes, so a
   // client-denied recursive deletion can be confirmed and retried normally.
-  for (const name of ['releases', 'bin', 'state.json']) fs.rmSync(path.join(home, name), { recursive: true, force: true });
+  for (const name of [autoUpdateLock, autoUpdateFile, autoUpdateNotice, 'releases', 'bin', 'state.json']) fs.rmSync(path.join(home, name), { recursive: true, force: true });
   const finished = performance.now();
   const elapsed = (from, to) => Math.round((to - from) * 100) / 100;
   emit({ ok: true, action: 'uninstall', complete: npmPackage.status !== 'unconfirmed', home,
@@ -625,7 +823,7 @@ function doctor(home) {
   checks.python = { status: runtime.available ? 'ok' : 'unavailable', ...runtime };
   const errors = [integrityError, ...(checks.skills.entries || []).filter(entry => entry.status === 'error').map(entry => entry.error)].filter(Boolean);
   const result = { ok: errors.length === 0, version: installed?.state?.version ?? null, integrity: checks.integrity.status,
-    python: runtime, capabilities: { metric: checks.integrity.status === 'ok' && runtime.available }, skills: installed?.state?.skills || [], checks };
+    python: runtime, skills: installed?.state?.skills || [], checks };
   if (result.ok) emit(result);
   else { process.stderr.write(`${JSON.stringify({ ...result, error: errors.join('; ') })}\n`); process.exitCode = 1; }
 }
@@ -637,11 +835,13 @@ async function main() {
   if (help) return emit(help);
   const { command, options, rest } = argumentsFor(process.argv.slice(2));
   const home = normalizedPath(options.home || process.env.FX_DATA_DIAGNOSTICS_HOME || installedBundleHome(packageRoot) || defaultHome());
+  if (command === '__background-update') return backgroundUpdate(home, rest[0]);
+  if (options['background-job'] && command !== 'update') throw new Error('--background-job is reserved for background updates');
   let current;
   try { current = ownedState(home, false); }
   catch (error) { if (command === 'doctor') return doctor(home); throw error; }
   const activeRoot = current?.state ? path.join(home, 'releases', current.state.version) : null;
-  const pinned = isInstalledBundle(packageRoot, home) && ['context', 'python', 'metric'].includes(command);
+  const pinned = isInstalledBundle(packageRoot, home) && ['context', 'python'].includes(command);
   const migrationRequired = Boolean(current?.state && current.state.lifecycle_protocol !== lifecycleProtocol);
   if (command === 'doctor') {
     if (!activeRoot || packageRoot === activeRoot || migrationRequired) return doctor(home);
@@ -649,7 +849,7 @@ async function main() {
     // diagnostic content is damaged. Fall back here only if the CLI is unsafe.
     try { bundleMetadata(activeRoot); } catch { return doctor(home); }
   }
-  if (migrationRequired && (command === 'install' || (!pinned && ['context', 'python', 'metric', 'version', '--version'].includes(command)))) {
+  if (migrationRequired && (command === 'install' || (!pinned && ['context', 'python', 'version', '--version'].includes(command)))) {
     throw new Error('Existing installation requires migration: run npm install -g @fx-data/ai-diagnostics, then use the new global fx-data-diagnostics update command');
   }
   // npm installation is a bootstrap. Re-running it must not switch an existing
@@ -674,17 +874,33 @@ async function main() {
   if (command === 'update') return update(home, options);
   if (command === 'rollback') return update(home, options, 'rollback');
   if (command === 'uninstall') return uninstall(home);
-  const { pkg, manifest, content } = verifyBundle(packageRoot, { allowMacMetadata: isInstalledBundle(packageRoot, home) });
+  const { pkg, manifest } = verifyBundle(packageRoot, { allowMacMetadata: isInstalledBundle(packageRoot, home) });
   if (command === '--version' || command === 'version') return emit({ version: pkg.version, package: pkg.name });
-  if (command === 'status') return emit({ ok: true, installed: Boolean(current?.state), home, ...current?.state, lifecycle_protocol: current?.state?.lifecycle_protocol ?? null, migration_required: migrationRequired, launcher: current?.state ? launchers(home).executable : null, launcher_script: current?.state ? launchers(home).script : null, node: process.execPath });
-  if (command === 'context') return emit(contextFor(packageRoot, home, pkg, manifest));
-  if (command === 'session') return emit({ directory: fs.mkdtempSync(path.join(os.tmpdir(), 'core-ai-')) });
-  if (command === 'metric' || command === 'python') {
+  if (command === 'status') {
+    const auto = autoUpdateDetails(home);
+    return emit({ ok: true, installed: Boolean(current?.state), home, ...current?.state, lifecycle_protocol: current?.state?.lifecycle_protocol ?? null, migration_required: migrationRequired, launcher: current?.state ? launchers(home).executable : null, launcher_script: current?.state ? launchers(home).script : null, node: process.execPath, ...(auto ? { auto_update: auto } : {}) });
+  }
+  if (command === 'context') {
+    // Capture paths before starting the worker. Direct calls to a pinned release
+    // are continuations, even if that release is still the current one.
+    const context = contextFor(packageRoot, home, pkg, manifest);
+    const auto = autoUpdateDetails(home);
+    const directPinned = isInstalledBundle(packageRoot, home)
+      && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+    if (current?.state && !directPinned) startAutoUpdate(home);
+    return emit({ ...context, ...(auto ? { auto_update: auto } : {}) });
+  }
+  if (command === 'session') {
+    const auto = autoUpdateDetails(home);
+    return emit({ directory: fs.mkdtempSync(path.join(os.tmpdir(), 'core-ai-')), ...(auto ? { auto_update: auto } : {}) });
+  }
+  if (command === 'python') {
     const runtime = python();
     if (!runtime.available) throw new Error(runtime.requirement);
-    const args = command === 'metric' ? [path.join(content, '.agents/skills/analyze-engine-metric/scripts/analyze_engine_metric.py'), ...rest] : rest;
-    if (!args.length) throw new Error('A script or Python option is required');
-    const result = spawnSync(runtime.executable, ['-I', '-B', ...args], { stdio: 'inherit' });
+    if (!rest.length) throw new Error('A script or Python option is required');
+    const auto = autoUpdateDetails(home);
+    if (auto?.notification) process.stderr.write(`${JSON.stringify({ fx_data_diagnostics: { auto_update: auto } })}\n`);
+    const result = spawnSync(runtime.executable, ['-I', '-B', ...rest], { stdio: 'inherit' });
     if (result.error) throw result.error;
     process.exitCode = result.status ?? 1;
     return;