@evomap/evolver 1.89.2 → 1.89.4

package/src/experiment/metrics.js

@@ -0,0 +1,75 @@
+// src/experiment/metrics.js
+//
+// Pure, table-driven mapping from a human metric label (e.g. "完成耗时 (s)",
+// "轮次", "token", "通过率") onto a per-arm field + comparison direction.
+// No I/O, no side effects -- safe to unit-test in isolation.
+'use strict';
+
+function num(v, fallback) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : (fallback === undefined ? 0 : fallback);
+}
+
+function round(n, digits) {
+  const f = Math.pow(10, digits);
+  return Math.round((num(n) + Number.EPSILON) * f) / f;
+}
+
+// Ordered rules. The FIRST rule whose any keyword is a (case-insensitive)
+// substring of the metric label wins. Order matters: pass-rate / rounds /
+// tokens / cost are checked before duration so a label like "通过率" is not
+// swallowed by a looser rule.
+const METRIC_RULES = [
+  { keys: ['通过率', 'pass', 'success', 'accuracy', '准确', '正确率'], field: 'passRate', lowerIsBetter: false },
+  { keys: ['轮次', 'turn', 'round', 'step', 'iteration', '迭代'], field: 'rounds', lowerIsBetter: true },
+  { keys: ['token', '令牌'], field: 'tokensTotal', lowerIsBetter: true },
+  { keys: ['成本', 'cost', 'usd', '价格', '费用'], field: 'costUsd', lowerIsBetter: true },
+  { keys: ['耗时', 'duration', 'latency', '延迟', '秒', 'second', '(s)', 'time'], field: 'durationMs', lowerIsBetter: true },
+];
+
+/**
+ * Resolve a metric label to the per-arm field used for scoring, the
+ * comparison direction, and the display unit.
+ *
+ * @param {string} metricStr
+ * @returns {{ metricField: string, lowerIsBetter: boolean, scoreUnit: string, recognized: boolean }}
+ */
+function deriveMetric(metricStr) {
+  const m = String(metricStr || '').toLowerCase();
+  for (const rule of METRIC_RULES) {
+    if (rule.keys.some((k) => m.includes(String(k).toLowerCase()))) {
+      if (rule.field === 'durationMs') {
+        // Seconds-flavoured labels ("(s)", "秒", "seconds") -> report in seconds.
+        if (/\(s\)|秒|second/.test(m)) {
+          return { metricField: 'durationSec', lowerIsBetter: true, scoreUnit: 'seconds', recognized: true };
+        }
+        return { metricField: 'durationMs', lowerIsBetter: true, scoreUnit: 'ms', recognized: true };
+      }
+      return { metricField: rule.field, lowerIsBetter: rule.lowerIsBetter, scoreUnit: 'raw', recognized: true };
+    }
+  }
+  // Unrecognized -> degrade to pass-rate (higher is better). Caller records a warning.
+  return { metricField: 'passRate', lowerIsBetter: false, scoreUnit: 'raw', recognized: false };
+}
+
+/**
+ * Pull the scalar score for one arm given the resolved metric field.
+ *
+ * @param {object} arm  a normalized arm (see comparison.normalizeArm)
+ * @param {string} metricField
+ * @returns {number}
+ */
+function scoreArm(arm, metricField) {
+  if (!arm) return 0;
+  switch (metricField) {
+    case 'durationSec': return round(num(arm.durationMs) / 1000, 2);
+    case 'durationMs': return num(arm.durationMs);
+    case 'rounds': return num(arm.rounds);
+    case 'tokensTotal': return num(arm.tokensTotal);
+    case 'costUsd': return round(num(arm.costUsd), 4);
+    case 'passRate': return round(num(arm.passRate), 4);
+    default: return round(num(arm.passRate), 4);
+  }
+}
+
+module.exports = { deriveMetric, scoreArm, METRIC_RULES, round, num };

package/src/forceUpdate.js

@@ -38,6 +38,173 @@ const FORCE_UPDATE_NOOP = Symbol('FORCE_UPDATE_NOOP');
 // fire its own reportForceUpdateOutcome. See test/forceUpdateConcurrencyGuard.test.js.
 const FORCE_UPDATE_BUSY = Symbol('FORCE_UPDATE_BUSY');
 
+// Structured failure taxonomy. Historically every failing branch of
+// _executeForceUpdateInner just `return false`, so the only thing that ever
+// reached the hub (via reportForceUpdateOutcome) was the literal string
+// "executeForceUpdate returned false" — degit-missing, tag-404, version
+// mismatch and copy-EPERM were all indistinguishable in EvolverUpgradeAttempt.
+// Each branch now returns _fail(code, detail); the reporter encodes it as
+// `error = code + ': ' + detail`, so operators can GROUP BY the code prefix
+// without any hub schema / DB migration. Codes are a small stable set — keep
+// new ones coarse and additive so historical `error LIKE 'code%'` queries
+// don't churn.
+const FORCE_UPDATE_FAIL_CODES = Object.freeze({
+  INSTALL_GUARD_NAME_MISMATCH: 'install_guard_name_mismatch',
+  INSTALL_GUARD_UNREADABLE: 'install_guard_unreadable',
+  BAD_REQUIRED_VERSION: 'bad_required_version',
+  CURRENT_VERSION_UNPARSABLE: 'current_version_unparsable',
+  NPX_NOT_FOUND: 'npx_not_found',
+  DEGIT_TIMEOUT: 'degit_timeout',
+  DEGIT_FAILED: 'degit_failed',
+  DOWNLOAD_INCOMPLETE: 'download_incomplete',
+  DOWNLOADED_VERSION_MISMATCH: 'downloaded_version_mismatch',
+  DELETE_FAILED: 'delete_failed',
+  COPY_FAILED: 'copy_failed',
+  ALL_CHANNELS_EXHAUSTED: 'all_channels_exhausted',
+});
+
+// Build the structured failure result that replaces a bare `return false`.
+// Shape: { ok:false, code, detail }. Distinct from `true`, FORCE_UPDATE_NOOP
+// and FORCE_UPDATE_BUSY, so the three call sites' `result === true` /
+// `result === SENTINEL` checks keep classifying it as "failed" unchanged —
+// this is backward compatible. Frozen so a downstream consumer cannot mutate
+// the code/detail before it is reported. detail is best-effort context (an
+// errno, a version delta, an entry name); it is redacted + truncated to
+// ERROR_MAX by the reporter before it leaves the process.
+function _fail(code, detail) {
+  return Object.freeze({
+    ok: false,
+    code: String(code),
+    detail: detail == null ? '' : String(detail),
+  });
+}
+
+// Compact "CODE: message" rendering of a thrown error for the detail field.
+function _errStr(e) {
+  if (!e) return 'unknown';
+  var code = e.code ? String(e.code) + ': ' : '';
+  return code + (e.message != null ? String(e.message) : String(e));
+}
+
+// Map a Channel 1 (GitHub Release / degit) throw to a structured failure.
+// `phase` records how far the try block got before throwing, so a readFileSync
+// ENOENT (truncated download) is not misread as an npx ENOENT (npx missing):
+//   'degit' -> the npx/degit spawn itself
+//   'parse' -> degit exited 0 but the downloaded package.json is missing/invalid
+//   'copy'  -> the staged tree downloaded fine but cpSync into INSTALL_ROOT failed
+function _classifyChannel1Error(e, phase) {
+  if (phase === 'delete') {
+    var deleteEntry = e && e._evolverEntry ? String(e._evolverEntry) + ': ' : '';
+    return _fail(FORCE_UPDATE_FAIL_CODES.DELETE_FAILED, deleteEntry + _errStr(e));
+  }
+  if (phase === 'copy') {
+    var entry = e && e._evolverEntry ? String(e._evolverEntry) + ': ' : '';
+    return _fail(FORCE_UPDATE_FAIL_CODES.COPY_FAILED, entry + _errStr(e));
+  }
+  if (phase === 'parse') {
+    return _fail(FORCE_UPDATE_FAIL_CODES.DOWNLOAD_INCOMPLETE,
+      'missing/invalid package.json in downloaded tree: ' + _errStr(e));
+  }
+  // phase === 'degit' (the spawn). ENOENT here is the npx binary itself, not a
+  // file inside the download — that distinction is exactly why `phase` exists.
+  if (e && e.code === 'ENOENT') {
+    return _fail(FORCE_UPDATE_FAIL_CODES.NPX_NOT_FOUND, _errStr(e));
+  }
+  // execFileSync timeout kills the child with SIGTERM (and sets .killed); some
+  // platforms surface ETIMEDOUT instead. Either way it is a 60s timeout.
+  if (e && (e.killed || e.signal === 'SIGTERM' || e.code === 'ETIMEDOUT')) {
+    return _fail(FORCE_UPDATE_FAIL_CODES.DEGIT_TIMEOUT,
+      'degit timed out after 60s' + (e.signal ? ' (signal=' + e.signal + ')' : ''));
+  }
+  // Generic degit/network/tag-not-found failure. degit prints the real reason
+  // ("could not find commit hash for v…", "could not resolve host") to stderr,
+  // so keep a tail of it. Redact + strip control chars HERE, before the tail
+  // slice: the downstream reporter redact (a2aProtocol.reportForceUpdateOutcome)
+  // runs after this, so slicing first could chop a token's prefix anchor and
+  // let the bare value slip past the prefix-anchored redact patterns. Stripping
+  // ANSI/NUL/newlines also keeps the persisted error free of terminal-injection
+  // sequences and log-line noise.
+  var detail = _errStr(e);
+  var stderr = '';
+  if (e && e.stderr != null) {
+    try {
+      var redactString = require('./gep/sanitize').redactString;
+      stderr = redactString(String(e.stderr)).replace(/[\x00-\x1f\x7f]/g, ' ').trim();
+    } catch (_) {
+      // sanitize unavailable — still strip control chars so logs stay clean.
+      stderr = String(e.stderr).replace(/[\x00-\x1f\x7f]/g, ' ').trim();
+    }
+  }
+  if (stderr) detail += ' | stderr=' + stderr.slice(-300);
+  return _fail(FORCE_UPDATE_FAIL_CODES.DEGIT_FAILED, detail);
+}
+
+function _isRetryableFsLockError(e) {
+  var code = e && e.code;
+  return code === 'EPERM' || code === 'EBUSY' || code === 'EACCES' ||
+    code === 'ENOTEMPTY' || code === 'EMFILE' || code === 'ENFILE';
+}
+
+function _waitForFsLockRetry() {
+  var until = Date.now() + 200;
+  while (Date.now() < until) { /* spin */ }
+}
+
+function _retryFsLockOperation(fn) {
+  var err = null;
+  for (var attempt = 0; attempt < 3; attempt++) {
+    try {
+      return fn();
+    } catch (e) {
+      err = e;
+      if (!_isRetryableFsLockError(e)) break;
+      if (attempt < 2) _waitForFsLockRetry();
+    }
+  }
+  throw err;
+}
+
+function _recoverPackageCommitMarkerIfMissing(installRoot) {
+  var pkgDst = path.join(installRoot, 'package.json');
+  if (fs.existsSync(pkgDst)) return false;
+  var entries;
+  try {
+    entries = fs.readdirSync(installRoot);
+  } catch (_) {
+    return false;
+  }
+  var backups = entries
+    .filter(function (name) { return /^package\.json\.\d+\.evolver-old$/.test(name); })
+    .sort();
+  for (var i = backups.length - 1; i >= 0; i--) {
+    try {
+      fs.renameSync(path.join(installRoot, backups[i]), pkgDst);
+      console.warn('[ForceUpdate] Recovered package.json commit marker from ' + backups[i]);
+      return true;
+    } catch (_) {}
+  }
+  return false;
+}
+
+function _restorePackageBackup(pkgBackup, pkgDst) {
+  if (!fs.existsSync(pkgBackup)) return false;
+  if (fs.existsSync(pkgDst)) {
+    try { fs.rmSync(pkgBackup, { force: true }); } catch (_) {}
+    return false;
+  }
+  try {
+    fs.renameSync(pkgBackup, pkgDst);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function _isForceUpdateKeepEntry(name) {
+  return name === 'node_modules' || name === 'memory' || name === '.git' || name === 'MEMORY.md' ||
+    name === '.env' || name === '.env.local' || name === 'USER.md' || name === '.evolver';
+}
+
 // Module-level mutex: shared by every caller that requires('../forceUpdate'),
 // so the heartbeat-thread trigger in a2aProtocol.js and the evolve-tick path
 // in enrich/pipeline cannot run executeForceUpdate concurrently. This is a
@@ -163,12 +330,33 @@ function _executeForceUpdateInner(forceUpdate) {
       console.warn('[ForceUpdate] Refusing — ' + INSTALL_ROOT +
         '/package.json has name="' + (pkg && pkg.name) +
         '", expected "@evomap/evolver". Aborting to avoid data loss.');
-      return false;
+      return _fail(FORCE_UPDATE_FAIL_CODES.INSTALL_GUARD_NAME_MISMATCH,
+        'install root package.json name="' + (pkg && pkg.name) + '", expected "@evomap/evolver"');
     }
   } catch (e) {
-    console.warn('[ForceUpdate] Refusing — cannot read ' + INSTALL_ROOT +
-      '/package.json: ' + (e && e.message || e));
-    return false;
+    if (_recoverPackageCommitMarkerIfMissing(INSTALL_ROOT)) {
+      try {
+        const recoveredPkg = JSON.parse(fs.readFileSync(path.join(INSTALL_ROOT, 'package.json'), 'utf8'));
+        if (!recoveredPkg || (recoveredPkg.name !== '@evomap/evolver' && recoveredPkg.name !== 'evolver')) {
+          console.warn('[ForceUpdate] Refusing — recovered ' + INSTALL_ROOT +
+            '/package.json has name="' + (recoveredPkg && recoveredPkg.name) +
+            '", expected "@evomap/evolver". Aborting to avoid data loss.');
+          return _fail(FORCE_UPDATE_FAIL_CODES.INSTALL_GUARD_NAME_MISMATCH,
+            'recovered install root package.json name="' + (recoveredPkg && recoveredPkg.name) +
+            '", expected "@evomap/evolver"');
+        }
+      } catch (recoverReadErr) {
+        console.warn('[ForceUpdate] Refusing — cannot read recovered ' + INSTALL_ROOT +
+          '/package.json: ' + (recoverReadErr && recoverReadErr.message || recoverReadErr));
+        return _fail(FORCE_UPDATE_FAIL_CODES.INSTALL_GUARD_UNREADABLE,
+          'cannot read recovered install root package.json: ' + _errStr(recoverReadErr));
+      }
+    } else {
+      console.warn('[ForceUpdate] Refusing — cannot read ' + INSTALL_ROOT +
+        '/package.json: ' + (e && e.message || e));
+      return _fail(FORCE_UPDATE_FAIL_CODES.INSTALL_GUARD_UNREADABLE,
+        'cannot read install root package.json: ' + _errStr(e));
+    }
   }
 
   const requiredVersion = normalizeRequiredVersion(forceUpdate.required_version);
@@ -176,7 +364,8 @@ function _executeForceUpdateInner(forceUpdate) {
     console.warn('[ForceUpdate] Refusing — required_version "' +
       String(forceUpdate.required_version || '').replace(/^[>=^~\s]+/, '') +
       '" is not a concrete semver (ranges not accepted).');
-    return false;
+    return _fail(FORCE_UPDATE_FAIL_CODES.BAD_REQUIRED_VERSION,
+      'required_version=' + JSON.stringify(forceUpdate && forceUpdate.required_version) + ' is not a concrete semver');
   }
 
   function getCurrentVersion() {
@@ -207,7 +396,8 @@ function _executeForceUpdateInner(forceUpdate) {
   if (versionCmp === null) {
     console.warn('[ForceUpdate] Refusing — current installed version "' +
       currentVersion + '" is not a concrete semver.');
-    return false;
+    return _fail(FORCE_UPDATE_FAIL_CODES.CURRENT_VERSION_UNPARSABLE,
+      'current installed version "' + currentVersion + '" is not a concrete semver');
   }
   if (versionCmp >= 0) {
     console.log('[ForceUpdate] already satisfies required version, no-op (current=' +
@@ -230,6 +420,14 @@ function _executeForceUpdateInner(forceUpdate) {
   const TMP_TARGET = fs.mkdtempSync(path.join(os.tmpdir(), '.evolver-update-tmp-'));
 
   // Channel 1: GitHub Release (via degit pinned to exact version tag)
+  //
+  // channel1Failure captures the structured reason this channel failed, so the
+  // terminal `return` can surface it instead of a bare `false`. `phase` tracks
+  // how far we got before any throw, so _classifyChannel1Error can tell a
+  // degit-spawn failure (phase 'degit') from a truncated download (phase
+  // 'parse') from a delete/copy-into-INSTALL_ROOT failure.
+  var channel1Failure = null;
+  var phase = 'degit';
   try {
     console.log('[ForceUpdate] Channel 1: GitHub Release download (v' + requiredVersion + ')...');
     var npxBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
@@ -240,6 +438,7 @@ function _executeForceUpdateInner(forceUpdate) {
       encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 60000, windowsHide: true, maxBuffer: MAX_EXEC_BUFFER,
     });
+    phase = 'parse';
     var tmpPkg = JSON.parse(fs.readFileSync(path.join(TMP_TARGET, 'package.json'), 'utf8'));
     // Require exact version match — a ">=" check would allow a compromised hub to
     // request version "0.0.1" and install any version including unreleased HEAD code.
@@ -247,44 +446,110 @@ function _executeForceUpdateInner(forceUpdate) {
       var entries = fs.readdirSync(INSTALL_ROOT, { withFileTypes: true });
       for (var ei = 0; ei < entries.length; ei++) {
         var eName = entries[ei].name;
-        if (eName === 'node_modules' || eName === 'memory' || eName === '.git' || eName === 'MEMORY.md'
-            || eName === '.env' || eName === '.env.local' || eName === 'USER.md' || eName === '.evolver') continue;
-        try { fs.rmSync(path.join(INSTALL_ROOT, eName), { recursive: true, force: true }); } catch (_) {}
+        // package.json is the install's commit marker: keep the OLD one in
+        // place through the entire delete+copy below and swap in the new one
+        // atomically at the very end (see "commit marker" block). If it were
+        // deleted here and any later cpSync threw (ENOSPC, a Windows lock that
+        // outlasts the retries, a kill), the install root would be left with
+        // no package.json — and the install-guard at the top of this function
+        // refuses on an unreadable package.json, wedging the node in
+        // install_guard_unreadable on every subsequent attempt with no path
+        // that ever re-copies it. Deferring it keeps the install self-healing.
+        if (_isForceUpdateKeepEntry(eName) || eName === 'package.json') continue;
+        try {
+          (function (entryName) {
+            phase = 'delete';
+            _retryFsLockOperation(function () {
+              fs.rmSync(path.join(INSTALL_ROOT, entryName), {
+                recursive: true, force: true, maxRetries: 3, retryDelay: 200,
+              });
+            });
+          })(eName);
+        } catch (rmErr) {
+          console.warn('[ForceUpdate] rmSync failed for ' + eName + ': ' + (rmErr.message || rmErr));
+          try { rmErr._evolverEntry = eName; } catch (_) {}
+          throw rmErr;
+        }
       }
+      phase = 'copy';
       var newEntries = fs.readdirSync(TMP_TARGET, { withFileTypes: true });
       for (var ni = 0; ni < newEntries.length; ni++) {
+        // Deferred: package.json is the commit marker, written last after every
+        // other entry has copied successfully (see below). Keep-list entries are
+        // local state and must not be overwritten by the downloaded release.
+        if (newEntries[ni].name === 'package.json' || _isForceUpdateKeepEntry(newEntries[ni].name)) continue;
         var src = path.join(TMP_TARGET, newEntries[ni].name);
         var dst = path.join(INSTALL_ROOT, newEntries[ni].name);
-        // On Windows, files held open by antivirus or the OS itself raise EPERM/EBUSY.
-        // Retry up to 3 times with a short delay before propagating the error.
-        var copyErr = null;
-        for (var attempt = 0; attempt < 3; attempt++) {
-          try {
-            fs.cpSync(src, dst, { recursive: true });
-            copyErr = null;
-            break;
-          } catch (cpErr) {
-            copyErr = cpErr;
-            var code = cpErr && cpErr.code;
-            if (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES') break;
-            // Brief busy-wait — execFileSync has already blocked the event loop,
-            // so a synchronous spin is acceptable here.
-            var until = Date.now() + 200;
-            while (Date.now() < until) { /* spin */ }
-          }
-        }
-        if (copyErr) {
+        try {
+          (function (copySrc, copyDst) {
+            _retryFsLockOperation(function () {
+              fs.cpSync(copySrc, copyDst, { recursive: true });
+            });
+          })(src, dst);
+        } catch (copyErr) {
           console.warn('[ForceUpdate] cpSync failed for ' + newEntries[ni].name + ': ' + (copyErr.message || copyErr));
+          // Tag the failing entry so _classifyChannel1Error can name it in the
+          // copy_failed detail. phase is already 'copy' here.
+          try { copyErr._evolverEntry = newEntries[ni].name; } catch (_) {}
           throw copyErr;
         }
       }
+      // Commit marker: every other entry copied successfully, so swap in the
+      // new package.json LAST. POSIX gets an atomic rename-over-existing. Windows
+      // cannot rename over an existing destination, so it first renames the old
+      // package.json to a recoverable same-directory backup; the install guard
+      // restores that backup on the next tick if the process dies mid-commit.
+      var pkgSrc = path.join(TMP_TARGET, 'package.json');
+      var pkgDst = path.join(INSTALL_ROOT, 'package.json');
+      var pkgTmp = pkgDst + '.' + process.pid + '.evolver-tmp';
+      var pkgBackup = pkgDst + '.' + process.pid + '.evolver-old';
+      try {
+        _retryFsLockOperation(function () {
+          try { fs.rmSync(pkgTmp, { force: true }); } catch (_) {}
+          fs.cpSync(pkgSrc, pkgTmp);
+          if (process.platform === 'win32') {
+            if (!fs.existsSync(pkgDst)) _recoverPackageCommitMarkerIfMissing(INSTALL_ROOT);
+            try { fs.rmSync(pkgBackup, { force: true }); } catch (_) {}
+            fs.renameSync(pkgDst, pkgBackup);
+            try {
+              fs.renameSync(pkgTmp, pkgDst);
+            } catch (commitErr) {
+              _restorePackageBackup(pkgBackup, pkgDst);
+              throw commitErr;
+            }
+            try { fs.rmSync(pkgBackup, { force: true }); } catch (_) {}
+          } else {
+            fs.renameSync(pkgTmp, pkgDst);
+          }
+        });
+      } catch (pkgErr) {
+        _restorePackageBackup(pkgBackup, pkgDst);
+        try { fs.rmSync(pkgTmp, { force: true }); } catch (_) {}
+        console.warn('[ForceUpdate] package.json commit (atomic replace) failed: ' + (pkgErr.message || pkgErr));
+        try { pkgErr._evolverEntry = 'package.json commit'; } catch (_) {}
+        throw pkgErr;
+      }
       try { fs.rmSync(TMP_TARGET, { recursive: true, force: true }); } catch (_) {}
       console.log('[ForceUpdate] GitHub Release update successful: ' + tmpPkg.version);
       return true;
     }
+    // degit succeeded and produced a parseable package.json, but it did not
+    // satisfy the exact-version check above. Two distinct causes, two codes:
+    if (!tmpPkg.version) {
+      // degit produced a parseable package.json with no version field — a
+      // malformed/incomplete download, not a stale/tampered tag mismatch.
+      channel1Failure = _fail(FORCE_UPDATE_FAIL_CODES.DOWNLOAD_INCOMPLETE,
+        'downloaded package.json has no version field');
+    } else {
+      // version present but not the exact tag we asked for (stale tag, mirror
+      // lag, or a tampered/redirected tag). Refuse and record the delta.
+      channel1Failure = _fail(FORCE_UPDATE_FAIL_CODES.DOWNLOADED_VERSION_MISMATCH,
+        'downloaded version=' + JSON.stringify(tmpPkg.version) + ', expected ' + requiredVersion);
+    }
     try { fs.rmSync(TMP_TARGET, { recursive: true, force: true }); } catch (_) {}
   } catch (e) {
-    console.warn('[ForceUpdate] GitHub Release failed:', e && e.message || e);
+    channel1Failure = _classifyChannel1Error(e, phase);
+    console.warn('[ForceUpdate] GitHub Release failed (' + channel1Failure.code + '):', e && e.message || e);
     try { fs.rmSync(TMP_TARGET, { recursive: true, force: true }); } catch (_) {}
     // Fall through to Channel 2 (manual download URL hint) instead of
     // returning. A Channel 1 error (degit missing, network down, tag not
@@ -301,7 +566,12 @@ function _executeForceUpdateInner(forceUpdate) {
   } catch (_) {}
 
   console.warn('[ForceUpdate] All automatic channels exhausted. Current version: ' + getCurrentVersion());
-  return false;
+  // Surface the concrete Channel 1 failure when we have one (the common case:
+  // degit/network/copy/version-mismatch). channel1Failure is null only when
+  // Channel 1 was never entered, which cannot happen here — but fall back to a
+  // terminal code so the reporter never lands on the legacy "returned false".
+  return channel1Failure || _fail(FORCE_UPDATE_FAIL_CODES.ALL_CHANNELS_EXHAUSTED,
+    'no automatic channel succeeded; current=' + getCurrentVersion() + ' target=' + requiredVersion);
 }
 
 // Test-only hook: re-implements the EXACT same operator-strip + semver
@@ -318,10 +588,21 @@ function _isAcceptedRequiredVersionForTesting(raw) {
   return normalizeRequiredVersion(raw) !== '';
 }
 
+// Type guard: is `result` a structured failure (vs true / NOOP / BUSY)?
+// Call sites use this to decide whether to forward result as opts.failure to
+// reportForceUpdateOutcome. Kept tiny and dependency-free so all three
+// duplicated triggers (a2aProtocol heartbeat, proxy manager, enrich tick) can
+// share one definition.
+function isForceUpdateFailure(result) {
+  return !!result && typeof result === 'object' && result.ok === false && typeof result.code === 'string';
+}
+
 module.exports = {
   executeForceUpdate,
   FORCE_UPDATE_NOOP,
   FORCE_UPDATE_BUSY,
+  FORCE_UPDATE_FAIL_CODES,
+  isForceUpdateFailure,
   // Test-only hook: reset the in-flight mutex so unit tests do not leak state
   // across cases. Production callers must NOT touch this -- the mutex is the
   // load-bearing invariant that prevents concurrent state-file writes.