@sdsrs/code-graph 0.116.0 → 0.118.0

package/claude-plugin/scripts/auto-update.js

@@ -7,7 +7,7 @@ const http = require('http');
 const crypto = require('crypto');
 const path = require('path');
 const os = require('os');
-const { CACHE_DIR, PLUGIN_ID, MARKETPLACE_NAME, readManifest, readJson, writeJsonAtomic, installedPluginsPath, pluginsCacheDir } = require('./lifecycle');
+const { CACHE_DIR, PLUGIN_ID, MARKETPLACE_NAME, readManifest, readJson, readJsonResult, writeJsonAtomic, installedPluginsPath, pluginsCacheDir } = require('./lifecycle');
 const { claudeHome } = require('./claude-config');
 const { clearCache: clearBinaryCache, globalNodeModulesCandidates, nvmNodeModulesDirs, PLATFORM_PKG, detectLibc } = require('./find-binary');
 const { readBinaryVersion, compareVersions, isDevMode } = require('./version-utils');
@@ -118,14 +118,53 @@ function getPlatformAssetName({ platform = os.platform(), arch = os.arch(), libc
 
 // ── State Persistence ──────────────────────────────────────
 
+// `readJson(STATE_FILE) || {}` was the lossy-read shape the audit swept for on
+// settings.json — still live here, on the one file that holds THREE independent
+// give-up budgets: the update suspension (`updateAttempts` / `suspendedAt`), the
+// binary self-heal budget (`binaryHealAttempts`) and the GitHub rate-limit
+// backoff (`rateLimited` + `lastCheck`). Collapsing "could not read it" into
+// "fresh install" re-armed all three at once, so one corrupt or unreadable cache
+// file turned off every guard that exists to stop an unbounded retry loop —
+// silently, and on every session thereafter (audit 2026-08-16 review Minor tail).
+//
+// Only a genuine ENOENT (or an empty file, which is what a crash mid-write
+// leaves) may be read as a fresh start. Anything else returns the marker below;
+// `checkForUpdate` skips the session and rewrites a clean file, so the next
+// session starts from real state rather than looping here.
 function readState() {
-  return readJson(STATE_FILE) || {};
+  const res = readJsonResult(STATE_FILE);
+  if (res.value) return res.value;
+  if (res.missing) return {};
+  return { stateUnreadable: (res.error && res.error.code) || 'invalid-json' };
 }
 
+// One stderr line per process when the state file cannot be written. Not a
+// throw: the caller's job (checking for an update) is unaffected, and a hook that
+// dies over its own bookkeeping is worse than one that keeps going. But not
+// silence either — every throttle in this file (update cooldown, GitHub
+// rate-limit backoff, binary self-heal budget) is stored in that one file, so a
+// read-only or full ~/.claude means the updater re-runs its whole check EVERY
+// session, forever, with nothing anywhere saying why (2026-08-16 audit §四).
+// The unlink/cleanup `catch {}`s elsewhere in this file stay silent on purpose:
+// a failed cleanup costs a stale temp file, not a broken invariant.
+let stateWriteWarned = false;
 function saveState(state) {
   try {
-    writeJsonAtomic(STATE_FILE, state);
-  } catch { /* ok */ }
+    // The marker is an in-memory signal, never a persisted field: several call
+    // sites do `saveState({ ...readState(), ... })`, and a persisted
+    // `stateUnreadable` would park the updater permanently.
+    const { stateUnreadable, ...clean } = state || {};
+    void stateUnreadable;
+    writeJsonAtomic(STATE_FILE, clean);
+  } catch (e) {
+    if (!stateWriteWarned) {
+      stateWriteWarned = true;
+      console.error(
+        `[code-graph] Could not save update state to ${STATE_FILE} (${e && e.message ? e.message : e}). ` +
+        'Update throttling and rate-limit backoff will not persist across sessions.',
+      );
+    }
+  }
 }
 
 // ── Throttle ───────────────────────────────────────────────
@@ -177,7 +216,11 @@ function shouldCheck(state, { force = false, binaryMissing = false, binaryStale
   if (state.rateLimited) return elapsed >= RATE_LIMIT_INTERVAL_MS;
   if (binaryMissing) return true;
   if (!isUpdateSuspended(state)) {
-    if (binaryStale) return true;
+    // ...and only while that heal still has a retry budget. Once it is spent,
+    // the bypass re-fetched the API and re-entered the ~40MB download on every
+    // single session (P1-14) — the same reasoning that keeps `binaryStale` out
+    // of the suspended branch.
+    if (binaryStale && !isBinaryHealExhausted(state)) return true;
     if (force) return elapsed >= SESSION_START_MIN_GAP_MS;
   }
   const interval = state.updateAvailable === false ? UP_TO_DATE_RECHECK_MS : CHECK_INTERVAL_MS;
@@ -606,8 +649,13 @@ async function downloadAndInstall(latest, {
       return { pluginUpdated: false, binaryUpdated: await downloadBin(latest), marketplaceRefreshed: false };
     }
     const tarballPath = path.join(tmpDir, PLUGIN_ASSET_NAME);
+    // `-f` like every sibling fetch in this file (the binary at :435 and both
+    // sha256 sidecars). This was the one download without it, so a 404/503 wrote
+    // GitHub's HTML body here and exited 0; the checksum below still failed
+    // closed, but as "sha mismatch" — a wrong diagnosis of a fetch that never
+    // succeeded (2026-08-16 audit §四).
     exec('curl', [
-      '-sL', '-o', tarballPath,
+      '-sfL', '-o', tarballPath,
       '-H', 'Accept: application/octet-stream',
       latest.pluginTarballUrl,
     ], hidden({ timeout: 30000, stdio: 'pipe' }));
@@ -726,9 +774,82 @@ async function downloadAndInstall(latest, {
  * on the shell-matches-latest path. Extracted + injectable so the wiring itself is
  * regression-tested, not just the predicate. Returns true iff a download promoted.
  */
-async function selfHealStaleBinary(latest, { needsUpdate = cachedBinaryNeedsUpdate, download = downloadBinary } = {}) {
-  if (!needsUpdate(latest)) return false;
-  return await download(latest);
+/**
+ * Replace a missing/stale cached binary — BOUNDED, per target version.
+ *
+ * This had no counter, so a promote that could not land (the Windows case named
+ * at promoteVerifiedBinary: the running MCP server holds the .exe, rename →
+ * EACCES) re-downloaded ~40MB on every session forever: the caller cleared
+ * `updateAttempts`/`suspendedAt` unconditionally right after calling this, and
+ * `shouldCheck`'s `binaryStale` arm bypasses the throttle (audit 2026-08-16
+ * P1-14; measured 8 calls → 8 downloads).
+ *
+ * Counted the same way as selfHealGlobalPkgs, including its hard-won rule:
+ * success is "the binary is no longer stale", NOT "download() returned true".
+ * A download whose promote silently failed used to reset the budget on every
+ * run, which is a cap that can never be reached.
+ *
+ * The counter is deliberately SEPARATE from `updateAttempts`: that one tracks
+ * the plugin-shell update, and the branch this runs in resets it because the
+ * shell IS current. Sharing it would have made each reset re-arm the other.
+ *
+ * @returns {{healed: boolean, patch: object}} patch is spread into the state save
+ */
+async function selfHealStaleBinary(latest, {
+  state = {}, needsUpdate = cachedBinaryNeedsUpdate, download = downloadBinary,
+  // "Present" must mean USABLE, not merely on disk. A truncated, non-executable
+  // or wrong-arch cached binary leaves the MCP server exactly as dead as a
+  // missing one, and every sibling predicate here already treats unreadable as
+  // needing replacement (cachedBinaryNeedsUpdate, cachedBinaryStaleVsState).
+  // Keying on existsSync alone put a corrupt binary under the stale budget,
+  // which isBinaryHealExhausted only re-arms when a NEW release ships — so five
+  // quick failures parked the only recovery path permanently (pre-tag review of
+  // the P1-14 fix).
+  binaryPresent = () => {
+    const p = cachedBinaryPath();
+    return fs.existsSync(p) && readBinaryVersion(p) !== null;
+  },
+} = {}) {
+  if (!latest || !needsUpdate(latest)) {
+    // Healthy → clear any leftover counter so the next real staleness starts fresh.
+    return {
+      healed: false,
+      patch: state.binaryHealAttempts ? { binaryHealAttempts: 0, binaryHealVersion: null } : {},
+    };
+  }
+  // A MISSING binary is exempt from the attempt budget: with no engine at all
+  // the MCP server is dead, and `needsUpdate` returns true for "absent" too —
+  // letting the stale-heal counter absorb those failures would permanently
+  // park the only recovery path after five offline session starts (batch
+  // review of the P1-14 fix). The budget exists to stop re-downloading over a
+  // binary that RUNS but cannot be replaced (Windows EACCES-on-rename); a
+  // missing binary keeps the pre-P1-14 unbounded retry on purpose.
+  const missing = !binaryPresent();
+  const attempts = state.binaryHealVersion === latest.version ? (state.binaryHealAttempts || 0) : 0;
+  if (!missing && attempts >= MAX_UPDATE_ATTEMPTS) return { healed: false, patch: {} };
+  await download(latest);
+  // Re-read the disk, not the return value (see above).
+  const stillStale = needsUpdate(latest);
+  return {
+    healed: !stillStale,
+    patch: {
+      binaryHealVersion: latest.version,
+      binaryHealAttempts: !stillStale ? 0 : missing ? attempts : attempts + 1,
+    },
+  };
+}
+
+/**
+ * The stale-binary heal has spent its budget on the release we are tracking.
+ * Read by shouldCheck: with the heal parked, the `binaryStale` throttle bypass
+ * can accomplish nothing and would just re-fetch the API (and, worse, re-enter
+ * the download path) every session. Re-arms itself when `latestVersion` moves.
+ */
+function isBinaryHealExhausted(state) {
+  return Boolean(state)
+    && Boolean(state.binaryHealVersion)
+    && state.binaryHealVersion === state.latestVersion
+    && (state.binaryHealAttempts || 0) >= MAX_UPDATE_ATTEMPTS;
 }
 
 // ── Global npm package self-heal ───────────────────────────
@@ -889,6 +1010,16 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
     // bypasses auto-update.js, so re-sync state.installedVersion every call.
     const installedVersion = readManifest().version || '0.0.0';
 
+    // A state we could not read authorises nothing: every throttle, budget and
+    // suspension below is derived from it, so acting on a blank stand-in would
+    // bypass all of them at once. Skip this session and rewrite a clean file —
+    // `lastCheck` stamped now means the ordinary interval applies from here, so
+    // the recovery is bounded rather than an immediate retry.
+    if (state.stateUnreadable) {
+      saveState({ installedVersion, lastCheck: new Date().toISOString() });
+      return null;
+    }
+
     // Time-based throttle. Two conditions override it: a missing cache binary
     // (launcher cannot start) and a present-but-stale binary (otherwise it stays
     // pinned to the old version for up to a full check interval — the binary
@@ -1052,7 +1183,8 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
     // OR stale (see selfHealStaleBinary). The shell version (manifest.version)
     // can match latest while the cached binary lags — this is exactly the wild
     // failure observed in the field (shell at v0.45, binary pinned at v0.16.6).
-    const selfHealedBinary = await selfHealStaleBinary(latest);
+    const binaryHeal = await selfHealStaleBinary(latest, { state });
+    const selfHealedBinary = binaryHeal.healed;
 
     // Same for the GLOBAL npm delivery surface (the `code-graph-mcp` CLI on
     // PATH + any explicitly-installed platform package): nothing else ever
@@ -1078,6 +1210,10 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
       suspendedAt: null,
       rateLimited: false,
       binaryUpdated: selfHealedBinary || state.binaryUpdated,
+      // The shell-update counters above reset because the shell IS current.
+      // The BINARY heal keeps its own, un-reset budget — clearing it here is
+      // what made the stale-binary re-download unbounded (P1-14).
+      ...binaryHeal.patch,
       ...globalHeal,
     });
     return selfHealedBinary
@@ -1101,7 +1237,7 @@ module.exports = {
   PLUGIN_ASSET_NAME,
   downloadBinary, cachedBinaryPath, cachedBinaryNeedsUpdate, cachedBinaryStaleVsState,
   getPlatformAssetName,
-  selfHealStaleBinary,
+  selfHealStaleBinary, isBinaryHealExhausted,
   selfHealGlobalPkgs, staleGlobalPkgs, globalPkgVersion, npmInstallGlobal,
   shouldHealGlobalsOnThrottle, inactiveNodeGlobalRelics,
   downloadAndInstall, refreshMarketplaceClone, marketplaceCloneDir,

package/claude-plugin/scripts/doctor.js

@@ -12,7 +12,7 @@ const {
 } = require('./lifecycle');
 const { findBinary, clearCache: clearBinaryCache } = require('./find-binary');
 const { hidden } = require('./proc-opts');
-const { MAX_UPDATE_ATTEMPTS } = require('./auto-update');
+const { MAX_UPDATE_ATTEMPTS, isBinaryHealExhausted } = require('./auto-update');
 
 // ── Diagnostics ───────────────────────────────────────────
 
@@ -29,7 +29,7 @@ function classifyEmbeddings(hc) {
   const ep = (hc && hc.embedding_progress) || '0/0';
   const [done, total] = ep.split('/').map(Number);
   if (hc && hc.model_available === false) {
-    return { name: 'Embeddings', status: 'warn',
+    return { name: 'Embeddings', status: 'warn', advisory: true,
       detail: 'binary built without embed-model — semantic search is FTS5-only; reinstall via npm/plugin for the hybrid binary' };
   }
   if (!total) {
@@ -65,7 +65,7 @@ function classifyEmbeddings(hc) {
               ? `last model download: ${hc.model_download}`
               : 'model not loaded and NO download has ever been attempted on this machine — restart the MCP server, or set CODE_GRAPH_MODEL_DIR to a manually populated model dir (see README → Offline usage)')
       : `embedding_status=${(hc && hc.embedding_status) || 'unknown'}`;
-    return { name: 'Embeddings', status: 'warn',
+    return { name: 'Embeddings', status: 'warn', advisory: true,
       detail: `vector INACTIVE — ${total} embeddable nodes, 0 embedded; semantic search is FTS5-only (${why})` };
   }
   if (done < total) {
@@ -156,7 +156,10 @@ function classifyHealthReport(hc) {
   }
   const rows = [];
   if (hc.issue && String(hc.issue).includes('schema')) {
-    rows.push({ name: 'Schema', status: 'warn', detail: hc.issue, fixId: 'schema-mismatch' });
+    // advisory: its "repair" only prints guidance (migration happens when the
+    // binary next runs), so it can never be counted fixed and would pin the
+    // exit code at 1 forever.
+    rows.push({ name: 'Schema', status: 'warn', advisory: true, detail: hc.issue, fixId: 'schema-mismatch' });
   } else {
     rows.push({ name: 'Schema', status: 'ok', detail: `v${hc.schema_version}` });
   }
@@ -215,6 +218,10 @@ function runHealthCheckCli(binary) {
   return execFileSync(binary, ['health-check', '--json'], hidden({
     cwd: process.cwd(),
     timeout: 5000,
+    // Same shape statusline.js hardened (audit P1-17): a wedged binary that
+    // ignores SIGTERM makes Node's timeout unreachable, so doctor — the tool
+    // you run BECAUSE something is wrong — would hang instead of diagnosing.
+    killSignal: 'SIGKILL',
     encoding: 'utf8',
     stdio: ['pipe', 'pipe', 'pipe'],
   })).trim();
@@ -402,6 +409,7 @@ function runDiagnostics({ checkOnly = false } = {}) {
     results.push({
       name: 'Hooks',
       status: 'warn',
+      advisory: true,
       detail:
         `settings.json was unusable and has been REBUILT — your original is at ` +
         `${hookResult.rebuiltFrom}. Merge anything you need back by hand.`,
@@ -530,6 +538,7 @@ function runDiagnostics({ checkOnly = false } = {}) {
       results.push({
         name: 'Global npm relics',
         status: 'warn',
+        advisory: true,
         detail: relics.map((r) => `${r.name}@${r.version} (${r.nodeModulesDir.replace(home, '~')})`).join('; ')
           + ' — installed under a non-active node version; auto-heal cannot reach another node\'s prefix. '
           + 'Remove each via `nvm use <that node> && npm rm -g <pkg>`, or uninstall the unused node (`nvm uninstall <ver>`).',
@@ -676,6 +685,52 @@ function binaryVersionResolved({
   return Boolean(actual) && actual === pluginVersion();
 }
 
+/**
+ * Mirror of BOTH `binary-broken` diagnoses: the binary is on disk but does not
+ * run (runDiagnostics step 2, `--version` unreadable) or its health-check failed
+ * with no recoverable payload (healthRows' last arm). Re-asks the same two
+ * questions the diagnosis asked, so "resolved" cannot mean something weaker than
+ * "not raised". Cache dropped first: the promote happens in a CHILD process and
+ * find-binary memoizes.
+ */
+function binaryBrokenResolved({
+  find = findBinary, readVersion = readBinaryVersion, rows = healthRows,
+} = {}) {
+  clearBinaryCache();
+  const binary = find();
+  if (!binary) return false;
+  if (!readVersion(binary)) return false;
+  try {
+    return !rows(binary).some((r) => r.fixId === 'binary-broken');
+  } catch { return false; }
+}
+
+/**
+ * Build the binary in the source checkout. Injectable for the same reason
+ * rebuildIndexInPlace is: `execSync` is destructured at load, so a test that
+ * patches child_process afterwards would silently run a real 10-minute cargo
+ * build. Returns true on exit 0; throws what the build threw.
+ */
+function buildBinaryFromSource(cmd) {
+  execSync(cmd, hidden({
+    cwd: path.resolve(__dirname, '..', '..'),
+    stdio: 'inherit',
+    timeout: 600000,  // embed-model (Candle) builds exceed the old 5min
+  }));
+  clearBinaryCache();
+  return true;
+}
+
+/** Manual recovery for a binary we could not repair — the end of every failed arm. */
+function printBinaryRecovery() {
+  console.log('     Reinstall: npm install -g @sdsrs/code-graph');
+  console.log('     Or download the release asset for your platform:');
+  console.log('       https://github.com/sdsrss/code-graph-mcp/releases');
+  if (os.platform() === 'darwin') {
+    console.log('     macOS may also have quarantined it: xattr -d com.apple.quarantine <binary>');
+  }
+}
+
 /** Mirror of the `update-incomplete` diagnosis (runDiagnostics step 5). */
 function updateIncompleteResolved({ readStateFile = readUpdateState } = {}) {
   const state = readStateFile();
@@ -750,6 +805,20 @@ function autoUpdateNoOpReason(state = readUpdateState(), env = process.env) {
     return `auto-update is SUSPENDED after ${state.updateAttempts} failed attempts on v${state.latestVersion} `
       + '(it retries once a day, and immediately when a newer release is published)';
   }
+  // The BINARY self-heal carries its own budget, independent of the update
+  // suspension above: the updater can be perfectly healthy while the binary
+  // download has given up on this release. That is precisely the state a
+  // `binary-broken` / stale-version row comes from, and it was the one parked
+  // state doctor could not name — so the user was told to update manually with
+  // no hint that the automatic repair had already stopped trying (audit
+  // 2026-08-16 review Minor tail). Uses the updater's own predicate rather than
+  // a second copy of the condition, which is keyed to `latestVersion` and so
+  // re-arms itself when a newer release appears.
+  if (isBinaryHealExhausted(state)) {
+    return `the binary self-heal has given up on v${state.latestVersion} after `
+      + `${state.binaryHealAttempts} failed download attempts (it re-arms when a newer `
+      + 'release is published)';
+  }
   if (state.rateLimited) {
     return 'the updater is in its GitHub rate-limit backoff (up to 1h)';
   }
@@ -770,6 +839,8 @@ function runRepairs(results, {
   updateResolved = updateIncompleteResolved,
   integrityOk = integrityResolved,
   rebuildIndex = rebuildIndexInPlace,
+  binaryUsable = binaryBrokenResolved,
+  buildBinary = buildBinaryFromSource,
 } = {}) {
   const fixable = results.filter(r => r.fixId);
   if (fixable.length === 0) return 0;
@@ -851,6 +922,63 @@ function runRepairs(results, {
         break;
       }
 
+      case 'binary-broken': {
+        // The binary EXISTS but cannot run: a truncated or corrupted download, a
+        // wrong-arch asset, a missing libc, macOS quarantine, or a real crash.
+        // This fixId had no arm at all, so doctor printed "1 issue(s) found.
+        // Fixing..." and then "0/1 addressed" with nothing between the two
+        // (audit 2026-08-16 P1-13).
+        if (devMode()) {
+          // A source checkout is never repaired by downloading a release asset.
+          // Preserve the feature set for the same reason the binary-stale arm
+          // does — never silently downgrade a hybrid dev binary to FTS5-only.
+          const embed = detectEmbedModel(findBinary());
+          const buildCmd = devBuildCommand(embed === true);
+          console.log('\n  Binary is present but does not run — rebuilding from source...');
+          if (embed === null) {
+            console.log('    (could not probe the current feature set — building FTS5-only;');
+            console.log('     for semantic search rebuild with `cargo build --release --features embed-model`)');
+          }
+          console.log(`    → ${buildCmd}`);
+          try {
+            if (!buildBinary(buildCmd)) {
+              console.log('  ❌ Build failed');
+              break;
+            }
+          } catch {
+            console.log('  ❌ Build failed');
+            break;
+          }
+        } else {
+          console.log('\n  Binary is present but does not run — re-downloading it...');
+          try {
+            // The updater's stale-binary self-heal treats an unreadable
+            // `--version` as "replace it", so this reaches the verified
+            // download+promote path even without a newer release.
+            runAutoUpdate();
+          } catch {
+            console.log('  ❌ Update check failed');
+            printBinaryRecovery();
+            break;
+          }
+        }
+        // Exit 0 proves the command ran, not that the binary works. Ask it.
+        if (binaryUsable()) {
+          console.log('  ✅ Binary runs again');
+          fixed++;
+        } else {
+          console.log('  ❌ The binary still cannot run');
+          if (!devMode()) {
+            const why = autoUpdateNoOpReason();
+            if (why) console.log(`     Why the re-download may have done nothing: ${why}.`);
+            printBinaryRecovery();
+          } else {
+            console.log('     The build completed but the produced binary still fails --version/health-check.');
+          }
+        }
+        break;
+      }
+
       case 'binary-not-exec': {
         const binary = findBinary();
         if (binary) {
@@ -1017,17 +1145,30 @@ function runRepairs(results, {
 // ── Main ──────────────────────────────────────────────────
 
 // Exit status for a doctor run reflects what remains BROKEN, not what was found:
-//   --check-only → every found issue is unresolved (report cleanliness, no repair).
-//   repair mode  → issueCount minus what runRepairs resolved. A run that fixes
+//   --check-only → every found BLOCKING issue is unresolved (report cleanliness,
+//                  no repair).
+//   repair mode  → blocking count minus what runRepairs resolved. A run that fixes
 //                  everything ("N/N addressed") reports 0 so `doctor && …` and
 //                  self-heal automation don't read a successful repair as a
 //                  failure. runRepairs counts an issue fixed only when its repair
 //                  reports success — and the hooks arm re-scans after install() to
 //                  confirm, so a still-broken re-scan is NOT counted (stays
-//                  unresolved → exit 1). An issue with no working repair
-//                  (schema-mismatch is advisory only) likewise keeps this > 0.
+//                  unresolved → exit 1).
+//
+// `advisory: true` rows are excluded. They are reported like any other warn but
+// describe something this tool cannot act on and that is not broken: a binary
+// deliberately built without embed-model, npm relics under a node version whose
+// prefix we cannot reach, a settings.json we already rebuilt, a schema note whose
+// "repair" only prints guidance. Every one of those used to pin the exit code at
+// 1 for the life of the install, so `doctor && <next step>` could never proceed —
+// a permanently-red check is one nobody reads (2026-08-16 audit §四).
+//
+// Advisory is an EXPLICIT marker, never inferred from a missing fixId: inferring
+// it would silently exempt the next row somebody forgets to wire to a repair,
+// which is the opposite failure. `doctor_rows_are_repairable_or_advisory`
+// (doctor.test.js) holds that line.
 function unresolvedCount({ checkOnly, issueCount, fixed }) {
-  return checkOnly ? issueCount : issueCount - fixed;
+  return checkOnly ? issueCount : Math.max(0, issueCount - fixed);
 }
 
 function runDoctor(opts = {}) {
@@ -1035,20 +1176,25 @@ function runDoctor(opts = {}) {
   console.log(formatReport(results, { checkOnly: opts.checkOnly }));
 
   const issues = results.filter(r => r.status === 'warn' || r.status === 'error');
+  const blocking = issues.filter(r => !r.advisory);
 
   let fixed = 0;
   if (issues.length > 0 && !opts.checkOnly) {
     fixed = runRepairs(results);
-    console.log(`\n  ${fixed}/${issues.length} issue(s) addressed.`);
+    console.log(`\n  ${fixed}/${blocking.length} issue(s) addressed.`);
+    const advisoryCount = issues.length - blocking.length;
+    if (advisoryCount > 0) {
+      console.log(`  ${advisoryCount} advisory note(s) above need no action here.`);
+    }
   }
 
   const unresolved = unresolvedCount({
-    checkOnly: opts.checkOnly, issueCount: issues.length, fixed,
+    checkOnly: opts.checkOnly, issueCount: blocking.length, fixed,
   });
   return { results, issueCount: issues.length, unresolved };
 }
 
-module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, classifyIntegrity, classifyHealthReport, parseHealthPayload, integrityResolved, healthRows, detectEmbedModel, devBuildCommand, binaryVersionResolved, updateIncompleteResolved, autoUpdateNoOpReason };
+module.exports = { runDiagnostics, formatReport, runRepairs, runDoctor, runDoctorCli, parseDoctorArgs, unresolvedCount, surveyHookCoverage, relicRepairGuard, classifyEmbeddings, classifyIntegrity, classifyHealthReport, parseHealthPayload, integrityResolved, healthRows, detectEmbedModel, devBuildCommand, binaryVersionResolved, updateIncompleteResolved, binaryBrokenResolved, autoUpdateNoOpReason };
 
 // Shared by BOTH doctor entry points: `node doctor.js …` and `node lifecycle.js
 // doctor …`. It exists as one function because the first version of this guard

package/claude-plugin/scripts/hook-emit.js

@@ -5,22 +5,88 @@
 // post-grep-inject) cannot drift apart (feedback_hook_class_bug_sweep — no
 // inline copies of shared logic). DRY mirror of the project-root.js precedent.
 //
-// Why these two shapes:
+// Why these three shapes:
 //   - PreToolUse plain stdout on exit 0 goes to the DEBUG LOG ONLY — it never
 //     reaches the model (CC docs, code.claude.com/docs/en/hooks.md, v2026-06).
-//     `additionalContext` DOES reach the model, but only alongside a
-//     permissionDecision. For the safe-tool pre hooks (Read fanout hint, Edit
-//     impact summary) the elevation to `allow` is negligible and is what makes
-//     the carried context visible.
+//     `additionalContext` is what surfaces the carried text.
+//   - `permissionDecision: 'allow'` is NOT a delivery detail. The CC hooks
+//     reference defines it as: "skip the interactive permission prompt" (deny
+//     rules and connector/`requiresUserInteraction` prompts still apply). On a
+//     machine that prompts for a tool, a hook sending `allow` has answered the
+//     user's prompt for them. That is defensible for READ-ONLY Read; it is not
+//     for Edit, which writes to disk — a delivery hook must never buy context
+//     visibility with the user's write consent (audit 2026-08-16 P0-2).
+//     Therefore: `emitPreToolAllowContext` is for Read ONLY, and every
+//     write-capable tool uses `emitPreToolContext` (no decision at all, which
+//     the docs' own PreToolUse example marks as "no decision; normal permission
+//     flow applies"). If a future CC drops additionalContext without a decision,
+//     the correct outcome is that the Edit impact summary goes quiet — NOT that
+//     it re-acquires the elevation.
 //   - PostToolUse honors `additionalContext` permission-neutrally (no
 //     permissionDecision), so the Bash-side grep answer can be injected without
 //     skipping CC's default permission prompt for the underlying tool call.
 
+// Ceiling on injected context, applied at the ONE place all three hooks emit
+// through. `cg-answer.js` has capped its own output at 4000 bytes since it was
+// written; the hook payloads it sits alongside had no cap at all, and they are
+// assembled from unbounded lists — pre-edit-guide joins every direct caller's
+// `name (file)` onto a single line, so editing a 200-caller symbol injected a
+// multi-kilobyte wall into the model's context on every Edit (2026-08-16 audit
+// §四). This is the model's context window, not a log: the whole value of an
+// impact summary is that it is small enough to read.
+//
+// Truncation is announced, never silent — a summary that stops mid-list without
+// saying so is worse than one that says it was cut, because the reader cannot
+// tell a short blast radius from a clipped one.
+const MAX_INJECTED_BYTES = 4000;
+
+function capContext(text) {
+  const s = String(text == null ? '' : text);
+  if (Buffer.byteLength(s, 'utf8') <= MAX_INJECTED_BYTES) return s;
+  const notice = `\n  … truncated at ${MAX_INJECTED_BYTES} bytes — re-run the CLI command above for the full result.\n`;
+  const budget = MAX_INJECTED_BYTES - Buffer.byteLength(notice, 'utf8');
+  // Slice on a UTF-16 code-unit boundary that fits the byte budget. This keeps
+  // the byte cap exact and never splits a 1-3 byte UTF-8 character (ASCII, Latin,
+  // CJK — what file paths and symbol names actually contain). It CAN split an
+  // astral-plane character (emoji, 2 code units) into a lone surrogate:
+  // `JSON.stringify` escapes that, so the envelope stays parseable and the model
+  // sees one replacement character at the cut. Saying so rather than claiming
+  // "never cut in half", which is what this comment used to claim (v0.118.0
+  // pre-tag review verified the emoji case).
+  let end = s.length;
+  while (end > 0 && Buffer.byteLength(s.slice(0, end), 'utf8') > budget) {
+    end -= Math.max(1, Math.ceil((Buffer.byteLength(s.slice(0, end), 'utf8') - budget) / 4));
+  }
+  // Prefer cutting at the last newline inside the budget, so the truncated text
+  // ends on a whole line rather than mid-token.
+  const nl = s.lastIndexOf('\n', end);
+  if (nl > budget / 2) end = nl;
+  return s.slice(0, end) + notice;
+}
+
+/**
+ * PreToolUse additionalContext envelope with NO permissionDecision (string, no
+ * trailing newline). The permission-neutral shape: the tool's normal permission
+ * flow is untouched. Use this for every write-capable tool (Edit/Write/…).
+ * @param {string} text
+ * @returns {string} JSON line
+ */
+function emitPreToolContext(text) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      additionalContext: capContext(text),
+    },
+  });
+}
+
 /**
  * PreToolUse allow + additionalContext envelope (string, no trailing newline).
- * Used by the safe-tool delivery hooks (pre-read-guide / pre-edit-guide) so
- * their carried hint/impact text reaches the model instead of dying in the
- * debug log.
+ *
+ * READ-ONLY TOOLS ONLY (pre-read-guide). `allow` skips the user's interactive
+ * permission prompt; for Read that grants nothing the model could not already
+ * get, and it is what keeps the fanout hint visible. Do not reuse it for a tool
+ * that mutates state — see the note above.
  * @param {string} text
  * @returns {string} JSON line
  */
@@ -29,7 +95,7 @@ function emitPreToolAllowContext(text) {
     hookSpecificOutput: {
       hookEventName: 'PreToolUse',
       permissionDecision: 'allow',
-      additionalContext: text,
+      additionalContext: capContext(text),
     },
   });
 }
@@ -45,9 +111,12 @@ function emitPostToolContext(text) {
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'PostToolUse',
-      additionalContext: text,
+      additionalContext: capContext(text),
     },
   });
 }
 
-module.exports = { emitPreToolAllowContext, emitPostToolContext };
+module.exports = {
+  emitPreToolContext, emitPreToolAllowContext, emitPostToolContext,
+  capContext, MAX_INJECTED_BYTES,
+};