@sdsrs/code-graph 0.111.0 → 0.111.1

package/README.md

@@ -160,9 +160,11 @@ Then reconnect the MCP server in Claude Code with `/mcp`.
 Set it in the `env` block of `~/.claude/settings.json` (the environment of the
 process hosting the MCP server), then reconnect with `/mcp`.
 
-An update that keeps failing also stops retrying on its own: after 5 failed
-attempts at the *same* release, the updater goes check-only until a newer
-release is published. Run `code-graph-mcp doctor` to see the state.
+An update that keeps failing also stops hammering: after 5 failed attempts at
+the *same* release the updater drops to one retry per day (and retries
+immediately when a newer release is published), instead of re-downloading on
+every session. While it is in that state the statusline shows `⚠ update stuck`
+and `code-graph-mcp doctor` prints the manual update command.
 
 #### Invited-memory mode (quieter prompts)
 

package/claude-plugin/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.111.0",
+  "version": "0.111.1",
   "keywords": [
     "code-graph",
     "ast",

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

@@ -57,6 +57,20 @@ const FETCH_TIMEOUT_MS = 3000;
 // STUCK_UPDATE_ATTEMPTS (drift-guarded in statusline.test.js) so the moment the
 // updater gives up is the moment the statusline stops promising "↻ updating".
 const MAX_UPDATE_ATTEMPTS = 5;
+// ...but suspension is not permanent. The cap alone assumed every repeated
+// failure is permanent, and the causes are not distinguishable at the failure
+// site: a briefly-missing `.sha256` sidecar, a captive portal, a temporarily
+// full disk burn the budget just as fast as a broken tar — and SessionStart
+// forces a check with only a 2-minute floor, so ~5 Claude Code restarts in ~10
+// minutes exhaust it. Before this, recovery required a NEWER release (or
+// hand-deleting update-state.json, which nothing tells the user to do), so a
+// ten-minute outage could park the updater for days. One retry per day keeps
+// the per-session treadmill dead while guaranteeing self-heal.
+//
+// Note the retry can NOT be keyed to `--force`: session-init passes --force on
+// every session start, so re-arming there would restore the exact treadmill
+// this cap exists to stop.
+const SUSPENSION_RETRY_MS = 24 * 60 * 60 * 1000;
 
 function isSilentMode(argv = process.argv.slice(2), env = process.env) {
   return argv.includes('--silent') || env.CODE_GRAPH_AUTO_UPDATE_SILENT === '1';
@@ -880,8 +894,17 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
       // always starts with a full budget. The counter used to be unscoped, which
       // only mattered because nothing ever read it: the download chain re-ran on
       // every single session no matter how many times it had already failed.
-      const attempts = state.latestVersion === latest.version ? (state.updateAttempts || 0) : 0;
-      if (attempts >= MAX_UPDATE_ATTEMPTS) {
+      const sameTarget = state.latestVersion === latest.version;
+      const attempts = sameTarget ? (state.updateAttempts || 0) : 0;
+      // A suspended release gets one retry per day (SUSPENSION_RETRY_MS), so a
+      // transient cause — sidecar blip, captive portal, briefly-full disk —
+      // heals itself instead of parking the updater until the next release.
+      // Spend the retry by entering the attempt path with the budget one short:
+      // if it fails again it re-suspends immediately (and re-stamps the clock),
+      // costing at most one download per day rather than one per session.
+      const suspendedAt = sameTarget && state.suspendedAt ? Date.parse(state.suspendedAt) : NaN;
+      const retryDue = Number.isFinite(suspendedAt) && (Date.now() - suspendedAt) >= SUSPENSION_RETRY_MS;
+      if (attempts >= MAX_UPDATE_ATTEMPTS && !retryDue) {
         // Suspended — check-only from here until a newer release moves the
         // target. The one thing still worth attempting is a MISSING cached
         // binary: without it the MCP server has no engine at all, so that
@@ -895,18 +918,32 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
           latestVersion: latest.version,
           updateAvailable: true,
           updateAttempts: attempts,
+          // Stamp on ENTRY to suspension, then leave it alone: the retry clock
+          // must measure time since we gave up, not time since the last check
+          // (which every session would reset, making the retry unreachable).
+          suspendedAt: (sameTarget && state.suspendedAt) || new Date().toISOString(),
           rateLimited: false,
           binaryUpdated: healedMissing || state.binaryUpdated,
         });
         console.error(
           `[code-graph] Auto-update to v${latest.version} suspended after ${attempts} failed attempts on this machine. ` +
           'Update manually (`/plugin update code-graph-mcp`, or `npm install -g @sdsrs/code-graph`) or run `code-graph-mcp doctor`. ' +
-          'Retries resume automatically when a newer release is published.'
+          'Retried automatically once a day, and immediately when a newer release is published.'
         );
         return { updateAvailable: true, suspended: true, from: installedVersion, to: latest.version };
       }
       const result = await downloadAndInstall(latest);
       const success = result.pluginUpdated;
+      // Suspension clock. It restarts when the daily retry is spent and fails,
+      // which is what keeps `retryDue` from staying true and turning the retry
+      // back into a per-session treadmill; it clears on success and on a new
+      // target version, so a stale stamp from the previous release cannot make
+      // the next one look instantly retry-due.
+      let nextSuspendedAt;
+      if (success) nextSuspendedAt = null;
+      else if (retryDue) nextSuspendedAt = new Date().toISOString();
+      else if (!sameTarget) nextSuspendedAt = null;
+      else nextSuspendedAt = state.suspendedAt || null;
       const newState = {
         lastCheck: new Date().toISOString(),
         installedVersion: success ? latest.version : installedVersion,
@@ -918,6 +955,7 @@ async function checkForUpdate({ installMissing = false, force = false, requestJs
         // forever, asserting a self-heal that never happens. The statusline stops
         // trusting it past STUCK_UPDATE_ATTEMPTS; success resets to 0.
         updateAttempts: success ? 0 : attempts + 1,
+        suspendedAt: nextSuspendedAt,
         lastUpdate: success ? new Date().toISOString() : state.lastUpdate,
         rateLimited: false,
         binaryUpdated: result.binaryUpdated,

package/claude-plugin/scripts/doctor.js

@@ -214,7 +214,7 @@ function runDiagnostics({ checkOnly = false } = {}) {
       results.push({
         name: 'Auto-update',
         status: 'warn',
-        detail: `v${state.latestVersion} failed to install ${attempts}× — auto-retry suspended until a newer release. `
+        detail: `v${state.latestVersion} failed to install ${attempts}× — auto-retry throttled to once a day. `
           + 'Update manually: `npm install -g @sdsrs/code-graph` (or `/plugin update code-graph-mcp`)',
       });
     } else if (state && state.updateAvailable && state.binaryUpdated === false) {

package/claude-plugin/scripts/launcher-install.js

@@ -129,7 +129,20 @@ function installBinaryInBackground({
   // `npm.cmd` (needs a shell) and passing `args` alongside `shell: true` is
   // DEP0190 — runtime-deprecated in Node 24, and unescaped. It pre-quotes the
   // whole command into `file` with empty `args`, and carries windowsHide.
-  const npm = npmInvocation(['install', '-g', `@sdsrs/code-graph@${version}`]);
+  // try/catch because quoteCmdArg THROWS on an argument it cannot quote, and
+  // `version` is read from plugin.json — our own file, but a parse of somebody
+  // else's disk. Uncaught, the throw escapes mcp-launcher.js and kills the MCP
+  // server AFTER the 0-tool stub is already serving, turning a bad version
+  // string into a dead server instead of a failed install. Every sibling call
+  // in auto-update.js is already inside a try.
+  let npm;
+  try {
+    npm = npmInvocation(['install', '-g', `@sdsrs/code-graph@${version}`]);
+  } catch (e) {
+    process.stderr.write(`[code-graph] cannot build the npm install command: ${e.message}\n`);
+    finish(onFailed);
+    return;
+  }
   runStep(npm.file, npm.args, npmTimeoutMs, '[code-graph][npm]', spawnFn, (npmExit) => {
     if (resolved()) {
       if (npmExit === 0 && recordGlobalInstall) {

package/claude-plugin/scripts/npm-exec.js

@@ -30,7 +30,13 @@ function quoteCmdArg(arg) {
   if (/["%!\r\n]/.test(s)) {
     throw new Error(`npm argument cannot be safely quoted for cmd.exe: ${JSON.stringify(s)}`);
   }
-  return `"${s}"`;
+  // Double a trailing run of backslashes. cmd.exe itself does not treat `\` as
+  // an escape, but the RECEIVING program's MSVCRT argv parser does: `"C:\x\"`
+  // reads the final `\"` as an escaped quote and swallows the rest of the
+  // command line into that argument. Only reachable for path-shaped args, which
+  // no current call site passes — but this helper reads as general-purpose.
+  const trailing = /\\+$/.exec(s);
+  return `"${trailing ? s + trailing[0] : s}"`;
 }
 
 /**

package/claude-plugin/scripts/statusline.js

@@ -19,16 +19,29 @@ const cleanupDisabledStatusline = lifecycle.cleanupDisabledStatusline || (() =>
 // real status instead. Without this, a persistently-failing update (missing
 // tar/curl, full disk, blocked network) pins "updating" forever.
 const STUCK_UPDATE_ATTEMPTS = 5;
-function updatePending() {
+function readUpdateState() {
   try {
-    const st = JSON.parse(fs.readFileSync(
+    return JSON.parse(fs.readFileSync(
       path.join(os.homedir(), '.cache', 'code-graph', 'update-state.json'), 'utf8'));
-    if ((st.updateAttempts || 0) >= STUCK_UPDATE_ATTEMPTS) return false;
-    if (st.updateAvailable) return true;
-    if (st.latestVersion && st.installedVersion && st.latestVersion !== st.installedVersion) return true;
-  } catch { /* no state file or unreadable — treat as no pending update */ }
+  } catch { return null; /* no state file or unreadable */ }
+}
+function updatePending(st = readUpdateState()) {
+  if (!st) return false;
+  if ((st.updateAttempts || 0) >= STUCK_UPDATE_ATTEMPTS) return false;
+  if (st.updateAvailable) return true;
+  if (st.latestVersion && st.installedVersion && st.latestVersion !== st.installedVersion) return true;
   return false;
 }
+// The updater has given up on this release (auto-update.js MAX_UPDATE_ATTEMPTS).
+// This has to be SHOWN, not merely not-lied-about: the updater's own stderr
+// notice is written by a process session-init spawns `detached` with
+// `stdio: 'ignore'`, so nobody ever sees it, and updatePending() going quiet
+// above means the only remaining signal was running `doctor` by hand. A user
+// who never runs doctor would sit on a permanently parked updater with no way
+// to know (found by pre-release review of v0.111.0, fixed in v0.111.1).
+function updateStuck(st = readUpdateState()) {
+  return !!(st && st.updateAvailable && (st.updateAttempts || 0) >= STUCK_UPDATE_ATTEMPTS);
+}
 
 const disabledCleanup = cleanupDisabledStatusline();
 if (disabledCleanup.cleaned) process.exit(0);
@@ -94,7 +107,10 @@ const bin = findBinary();
 if (!bin) {
   // No usable binary yet. If an update is queued, the background downloader is
   // still fetching it \u2014 that is "updating", not a broken "offline" state.
-  process.stdout.write(updatePending() ? 'code-graph: \u21bb updating' : 'code-graph: offline');
+  process.stdout.write(
+    updateStuck() ? 'code-graph: \u26a0 update stuck'
+      : updatePending() ? 'code-graph: \u21bb updating'
+        : 'code-graph: offline');
   process.exit(0);
 }
 
@@ -121,6 +137,8 @@ function renderHealth(s) {
   // index doesn't masquerade as fully current.
   if (s.index_version_stale) line += ' | \u21bb rebuilding';
   if (s.watching) line += ' | watching';
+  // A parked updater is otherwise invisible in normal use — see updateStuck().
+  if (updateStuck()) line += ' | \u26a0 update stuck';
   return line;
 }
 
@@ -144,7 +162,8 @@ function statusUnavailable(errText) {
   // phrase so a cached binary predating the marker still reads as "updating".
   const errStr = errText || '';
   const binaryOutdated = errStr.includes('code-graph:schema-too-new') || /schema version/i.test(errStr);
-  return (binaryOutdated || updatePending()) ? 'code-graph: \u21bb updating' : 'code-graph: offline';
+  if (binaryOutdated || updatePending()) return 'code-graph: \u21bb updating';
+  return updateStuck() ? 'code-graph: \u26a0 update stuck' : 'code-graph: offline';
 }
 
 let report = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.111.0",
+  "version": "0.111.1",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -35,10 +35,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.111.0",
-    "@sdsrs/code-graph-linux-arm64": "0.111.0",
-    "@sdsrs/code-graph-darwin-x64": "0.111.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.111.0",
-    "@sdsrs/code-graph-win32-x64": "0.111.0"
+    "@sdsrs/code-graph-linux-x64": "0.111.1",
+    "@sdsrs/code-graph-linux-arm64": "0.111.1",
+    "@sdsrs/code-graph-darwin-x64": "0.111.1",
+    "@sdsrs/code-graph-darwin-arm64": "0.111.1",
+    "@sdsrs/code-graph-win32-x64": "0.111.1"
   }
 }