instar 1.2.25 → 1.2.26

package/dist/utils/resolveNodeBinary.d.ts

@@ -0,0 +1,71 @@
+/**
+ * resolveNodeBinary — find a stable, currently-existing Node.js executable.
+ *
+ * Background:
+ *   The native-module heal path spawns child processes with `process.execPath`
+ *   as the executable target. That works UNTIL the underlying file disappears
+ *   from disk — most commonly when Homebrew (or any package manager) updates
+ *   Node while the server is still running. Brew swaps the
+ *   /opt/homebrew/bin/node symlink and removes the previous Cellar directory.
+ *   The running process keeps an open FD to the deleted binary so it continues
+ *   executing normally, but any NEW `spawnSync(process.execPath, ...)` returns
+ *   ENOENT — the file is gone from the filesystem.
+ *
+ *   Observed live on luna 2026-05-21: heal detected NODE_MODULE_VERSION
+ *   mismatch correctly, then logged
+ *   "rebuild failed (spawnSync /opt/homebrew/Cellar/node/25.6.1/bin/node ENOENT)"
+ *   even though `node --version` from a fresh shell still worked — Homebrew
+ *   had moved Node forward and removed the original Cellar path the process
+ *   was launched from.
+ *
+ * Strategy:
+ *   1. Try `process.execPath` first (cheapest, most likely correct).
+ *   2. If it's ENOENT, try `fs.realpathSync(process.execPath)` — if execPath
+ *      was a symlink at startup, the underlying target might still exist.
+ *   3. Otherwise fall back to a list of known-stable absolute paths in order:
+ *      - the bundled agent Node at <agentStateDir>/bin/node (passed in)
+ *      - /opt/homebrew/bin/node (macOS Homebrew's stable symlink)
+ *      - /usr/local/bin/node, /usr/bin/node
+ *   4. Final fallback: `which node` from PATH.
+ *
+ * Returns the first existing-and-executable absolute path, or null when
+ * none of the candidates resolve. Callers that get null should NOT silently
+ * proceed — the heal cannot continue without a working Node, and the failure
+ * mode is operator-visible (DegradationReporter event with a recovery hint).
+ *
+ * Spec / origin: heal-execpath-staleness fix (Luna self-heal failure, 2026-05-21).
+ */
+export interface ResolveOptions {
+    /** Optional path to the agent's bundled Node (e.g. <stateDir>/bin/node). */
+    agentBundledNode?: string;
+    /** Override the in-process execPath. For testing only. */
+    execPathOverride?: string;
+    /** Override the platform string. For testing only. */
+    platformOverride?: NodeJS.Platform;
+    /** Override fs.existsSync. For testing only. */
+    existsSyncOverride?: (p: string) => boolean;
+    /** Override the `which`/`where` lookup. For testing only. */
+    whichOverride?: () => string | null;
+}
+/**
+ * Result of a resolution attempt. Includes the source so callers can log
+ * which fallback fired (useful when investigating why heal needed help).
+ */
+export interface ResolvedNodeBinary {
+    /** Absolute path to the resolved Node executable. */
+    path: string;
+    /** Which strategy produced this path. */
+    source: 'execPath' | 'execPath-realpath' | 'agent-bundled' | 'homebrew' | 'usr-local' | 'usr-bin' | 'which';
+}
+/**
+ * Resolve a stable Node binary path. Returns the first viable candidate;
+ * null only when every strategy fails (rare — usually means Node was
+ * completely uninstalled mid-session).
+ */
+export declare function resolveStableNodeBinary(opts?: ResolveOptions): ResolvedNodeBinary | null;
+/**
+ * Convenience: returns just the path string, or null. Use the full
+ * resolver when you need to log which fallback fired.
+ */
+export declare function resolveStableNodeBinaryPath(opts?: ResolveOptions): string | null;
+//# sourceMappingURL=resolveNodeBinary.d.ts.map

package/dist/utils/resolveNodeBinary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveNodeBinary.d.ts","sourceRoot":"","sources":["../../src/utils/resolveNodeBinary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAOH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,gDAAgD;IAChD,kBAAkB,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,EACF,UAAU,GACV,mBAAmB,GACnB,eAAe,GACf,UAAU,GACV,WAAW,GACX,SAAS,GACT,OAAO,CAAC;CACb;AA8BD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,GAAE,cAAmB,GACxB,kBAAkB,GAAG,IAAI,CAmD3B;AAwBD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,GAAE,cAAmB,GAAG,MAAM,GAAG,IAAI,CAGpF"}

package/dist/utils/resolveNodeBinary.js

@@ -0,0 +1,152 @@
+/**
+ * resolveNodeBinary — find a stable, currently-existing Node.js executable.
+ *
+ * Background:
+ *   The native-module heal path spawns child processes with `process.execPath`
+ *   as the executable target. That works UNTIL the underlying file disappears
+ *   from disk — most commonly when Homebrew (or any package manager) updates
+ *   Node while the server is still running. Brew swaps the
+ *   /opt/homebrew/bin/node symlink and removes the previous Cellar directory.
+ *   The running process keeps an open FD to the deleted binary so it continues
+ *   executing normally, but any NEW `spawnSync(process.execPath, ...)` returns
+ *   ENOENT — the file is gone from the filesystem.
+ *
+ *   Observed live on luna 2026-05-21: heal detected NODE_MODULE_VERSION
+ *   mismatch correctly, then logged
+ *   "rebuild failed (spawnSync /opt/homebrew/Cellar/node/25.6.1/bin/node ENOENT)"
+ *   even though `node --version` from a fresh shell still worked — Homebrew
+ *   had moved Node forward and removed the original Cellar path the process
+ *   was launched from.
+ *
+ * Strategy:
+ *   1. Try `process.execPath` first (cheapest, most likely correct).
+ *   2. If it's ENOENT, try `fs.realpathSync(process.execPath)` — if execPath
+ *      was a symlink at startup, the underlying target might still exist.
+ *   3. Otherwise fall back to a list of known-stable absolute paths in order:
+ *      - the bundled agent Node at <agentStateDir>/bin/node (passed in)
+ *      - /opt/homebrew/bin/node (macOS Homebrew's stable symlink)
+ *      - /usr/local/bin/node, /usr/bin/node
+ *   4. Final fallback: `which node` from PATH.
+ *
+ * Returns the first existing-and-executable absolute path, or null when
+ * none of the candidates resolve. Callers that get null should NOT silently
+ * proceed — the heal cannot continue without a working Node, and the failure
+ * mode is operator-visible (DegradationReporter event with a recovery hint).
+ *
+ * Spec / origin: heal-execpath-staleness fix (Luna self-heal failure, 2026-05-21).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+/**
+ * Check whether a path exists AND is executable (or at least file-like).
+ * On macOS/Linux, regular files with the exec bit set qualify; on Windows
+ * we only check existence because exec semantics differ. Symlinks are
+ * followed via fs.statSync (not lstat).
+ */
+function isExecutableFile(p, existsSync) {
+    try {
+        if (!existsSync(p))
+            return false;
+        const stat = fs.statSync(p);
+        if (!stat.isFile())
+            return false;
+        // accessSync throws on missing exec bit; treat throw as "not executable".
+        if (os.platform() !== 'win32') {
+            try {
+                fs.accessSync(p, fs.constants.X_OK);
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a stable Node binary path. Returns the first viable candidate;
+ * null only when every strategy fails (rare — usually means Node was
+ * completely uninstalled mid-session).
+ */
+export function resolveStableNodeBinary(opts = {}) {
+    const existsSync = opts.existsSyncOverride ?? fs.existsSync;
+    const platform = opts.platformOverride ?? os.platform();
+    const execPath = opts.execPathOverride ?? process.execPath;
+    // 1. process.execPath as-is. Cheapest and almost always right.
+    if (isExecutableFile(execPath, existsSync)) {
+        return { path: execPath, source: 'execPath' };
+    }
+    // 2. Realpath of process.execPath. If execPath was a symlink at startup,
+    //    Node resolves it during init — but in some Homebrew failure modes,
+    //    the realpath target survives even when the original execPath has
+    //    been swept up. Try it.
+    try {
+        const real = fs.realpathSync(execPath);
+        if (real !== execPath && isExecutableFile(real, existsSync)) {
+            return { path: real, source: 'execPath-realpath' };
+        }
+    }
+    catch {
+        // realpath fails if execPath is gone; continue to fallbacks.
+    }
+    // 3. Agent's bundled Node, if the caller knows where it lives.
+    if (opts.agentBundledNode && isExecutableFile(opts.agentBundledNode, existsSync)) {
+        return { path: opts.agentBundledNode, source: 'agent-bundled' };
+    }
+    // 4. Platform-stable absolute paths in order of preference.
+    if (platform !== 'win32') {
+        const candidates = [
+            ['/opt/homebrew/bin/node', 'homebrew'],
+            ['/usr/local/bin/node', 'usr-local'],
+            ['/usr/bin/node', 'usr-bin'],
+        ];
+        for (const [candidate, source] of candidates) {
+            if (isExecutableFile(candidate, existsSync)) {
+                return { path: candidate, source };
+            }
+        }
+    }
+    // 5. Last resort: ask the OS where `node` lives on PATH.
+    const whichResult = opts.whichOverride
+        ? opts.whichOverride()
+        : whichNode(platform);
+    if (whichResult && isExecutableFile(whichResult, existsSync)) {
+        return { path: whichResult, source: 'which' };
+    }
+    return null;
+}
+/**
+ * Locate the first `node` on PATH via the platform's `which`/`where` tool.
+ * Returns null on any failure — the caller has its own fallback chain.
+ */
+function whichNode(platform) {
+    try {
+        const cmd = platform === 'win32' ? 'where' : 'which';
+        const result = spawnSync(cmd, ['node'], {
+            encoding: 'utf-8',
+            timeout: 5000,
+        });
+        if (result.status === 0 && result.stdout) {
+            // `where` (Windows) can return multiple paths; take the first.
+            const first = result.stdout.trim().split(/\r?\n/)[0];
+            if (first)
+                return first;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Convenience: returns just the path string, or null. Use the full
+ * resolver when you need to log which fallback fired.
+ */
+export function resolveStableNodeBinaryPath(opts = {}) {
+    const resolved = resolveStableNodeBinary(opts);
+    return resolved ? resolved.path : null;
+}
+//# sourceMappingURL=resolveNodeBinary.js.map

package/dist/utils/resolveNodeBinary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveNodeBinary.js","sourceRoot":"","sources":["../../src/utils/resolveNodeBinary.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.25",
+  "version": "1.2.26",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/scripts/fix-better-sqlite3.cjs

@@ -28,11 +28,25 @@ const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { resolveStableNodeBinary } = require('./resolve-node-binary.cjs');
 
 const MODULE_VERSION = process.versions.modules;
 const ARCH = process.arch;
 const PLATFORM = process.platform;
 
+// Resolve a stable Node binary up front. process.execPath is preferred when
+// it still exists; we fall back to /opt/homebrew/bin/node (or PATH-derived
+// node) when Homebrew has swept the original Cellar dir out from under us.
+// See scripts/resolve-node-binary.cjs and src/utils/resolveNodeBinary.ts.
+const _resolvedNode = resolveStableNodeBinary();
+const NODE_BIN = _resolvedNode ? _resolvedNode.path : process.execPath;
+if (_resolvedNode && _resolvedNode.source !== 'execPath') {
+  console.warn(
+    `[fix-better-sqlite3] process.execPath (${process.execPath}) is unreachable; ` +
+    `using ${_resolvedNode.source} fallback at ${NODE_BIN}.`
+  );
+}
+
 function findBetterSqlite3() {
   try {
     const resolved = require.resolve('better-sqlite3/package.json');
@@ -72,7 +86,7 @@ function getBetterSqliteVersion(pkgDir) {
 function verifyChildAbiMatches() {
   try {
     const out = execFileSync(
-      process.execPath,
+      NODE_BIN,
       ['-e', "process.stdout.write(process.versions.modules)"],
       { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 }
     );
@@ -94,7 +108,7 @@ function verifyChildAbiMatches() {
 function testBinary(pkgDir) {
   try {
     execFileSync(
-      process.execPath,
+      NODE_BIN,
       [
         '-e',
         "const Database = require('better-sqlite3'); const db = new Database(':memory:'); db.pragma('journal_mode = WAL'); db.close();",
@@ -180,7 +194,10 @@ function tryPrebuild(pkgDir, betterSqliteVersion) {
 
 /** Locate npm's CLI entry without needing a shell. */
 function findNpmCli() {
-  const nodeDir = path.dirname(process.execPath);
+  // Prefer the npm sibling of the resolved Node binary — when execPath is
+  // stale, NODE_BIN points at the live Node, and its sibling npm is the right
+  // pair for that ABI.
+  const nodeDir = path.dirname(NODE_BIN);
   const candidates = [
     path.resolve(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
     '/opt/homebrew/lib/node_modules/npm/bin/npm-cli.js',
@@ -215,13 +232,15 @@ function trySourceBuild(pkgDir) {
   // we're building FOR. Without this, a mixed environment (e.g. asdf Node 22
   // on PATH + server's Node 25 as execPath) compiles against the wrong
   // headers and produces an ABI-mismatched binary that silently fails later.
-  const execDir = path.dirname(process.execPath);
+  // Use NODE_BIN (the resolved Node) so the PATH prefix points at a Node that
+  // actually exists on disk — process.execPath may be stale.
+  const execDir = path.dirname(NODE_BIN);
   const childPath = `${execDir}${path.delimiter}${process.env.PATH || ''}`;
 
   try {
     console.log(`[fix-better-sqlite3] Source-building better-sqlite3 in ${rebuildCwd} (~30s)`);
     execFileSync(
-      process.execPath,
+      NODE_BIN,
       [npmCli, 'rebuild', 'better-sqlite3', '--build-from-source'],
       {
         cwd: rebuildCwd,

package/scripts/resolve-node-binary.cjs

@@ -0,0 +1,119 @@
+/**
+ * resolve-node-binary.cjs — CommonJS twin of src/utils/resolveNodeBinary.ts.
+ *
+ * Both files implement the same fallback chain. They are kept in sync because
+ * fix-better-sqlite3.cjs runs as a child process via execFileSync and cannot
+ * import the TypeScript module; the server-side ensureSqliteBindings code
+ * imports the TS module directly. If you change the resolution chain in one,
+ * mirror it in the other.
+ *
+ * Rationale: when Homebrew updates Node mid-session, process.execPath becomes
+ * ENOENT for any NEW spawnSync (even though the running process keeps its open
+ * FD). The heal path needs a stable fallback chain so it can rebuild and the
+ * subsystems can recover after restart.
+ *
+ * Spec / origin: heal-execpath-staleness fix (Luna self-heal failure, 2026-05-21).
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const { spawnSync } = require('node:child_process');
+
+function isExecutableFile(p, existsSync) {
+  try {
+    if (!existsSync(p)) return false;
+    const stat = fs.statSync(p);
+    if (!stat.isFile()) return false;
+    if (os.platform() !== 'win32') {
+      try {
+        fs.accessSync(p, fs.constants.X_OK);
+      } catch {
+        return false;
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function whichNode(platform) {
+  try {
+    const cmd = platform === 'win32' ? 'where' : 'which';
+    const result = spawnSync(cmd, ['node'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+    });
+    if (result.status === 0 && result.stdout) {
+      const first = result.stdout.trim().split(/\r?\n/)[0];
+      if (first) return first;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{agentBundledNode?: string, execPathOverride?: string,
+ *          platformOverride?: string, existsSyncOverride?: (p:string)=>boolean,
+ *          whichOverride?: () => string|null}} [opts]
+ * @returns {{path:string, source:string} | null}
+ */
+function resolveStableNodeBinary(opts = {}) {
+  const existsSync = opts.existsSyncOverride || fs.existsSync;
+  const platform = opts.platformOverride || os.platform();
+  const execPath = opts.execPathOverride || process.execPath;
+
+  // 1. process.execPath as-is.
+  if (isExecutableFile(execPath, existsSync)) {
+    return { path: execPath, source: 'execPath' };
+  }
+
+  // 2. Realpath of process.execPath.
+  try {
+    const real = fs.realpathSync(execPath);
+    if (real !== execPath && isExecutableFile(real, existsSync)) {
+      return { path: real, source: 'execPath-realpath' };
+    }
+  } catch {
+    /* realpath fails when execPath is gone; continue */
+  }
+
+  // 3. Agent's bundled Node.
+  if (opts.agentBundledNode && isExecutableFile(opts.agentBundledNode, existsSync)) {
+    return { path: opts.agentBundledNode, source: 'agent-bundled' };
+  }
+
+  // 4. Platform-stable absolute paths.
+  if (platform !== 'win32') {
+    const candidates = [
+      ['/opt/homebrew/bin/node', 'homebrew'],
+      ['/usr/local/bin/node', 'usr-local'],
+      ['/usr/bin/node', 'usr-bin'],
+    ];
+    for (const [candidate, source] of candidates) {
+      if (isExecutableFile(candidate, existsSync)) {
+        return { path: candidate, source };
+      }
+    }
+  }
+
+  // 5. PATH lookup.
+  const whichResult = opts.whichOverride ? opts.whichOverride() : whichNode(platform);
+  if (whichResult && isExecutableFile(whichResult, existsSync)) {
+    return { path: whichResult, source: 'which' };
+  }
+
+  return null;
+}
+
+function resolveStableNodeBinaryPath(opts = {}) {
+  const resolved = resolveStableNodeBinary(opts);
+  return resolved ? resolved.path : null;
+}
+
+module.exports = {
+  resolveStableNodeBinary,
+  resolveStableNodeBinaryPath,
+};

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-22T06:36:33.520Z",
-  "instarVersion": "1.2.25",
+  "generatedAt": "2026-05-22T06:46:36.393Z",
+  "instarVersion": "1.2.26",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {

package/upgrades/1.2.26.md

@@ -0,0 +1,51 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**fix(heal): better-sqlite3 self-heal now survives Homebrew Node updates that strand process.execPath.**
+
+When Homebrew (or any package manager) updates Node while an instar server is running, the brew install swaps the `/opt/homebrew/bin/node` symlink and removes the previous Cellar directory. The server process keeps an open file descriptor to the deleted binary, so it continues executing — but any new `spawnSync(process.execPath, ...)` call returns ENOENT. The native-module self-heal path runs through exactly that kind of spawn, so the heal silently fails. The agent then degrades to legacy-memory fallbacks and stays there across restarts (the next startup hits the same stale execPath).
+
+This was observed live on luna 2026-05-21. Server log showed the heal firing at 02:46:00, then 150ms later: `"rebuild failed (spawnSync /opt/homebrew/Cellar/node/25.6.1/bin/node ENOENT). SQLite subsystems may degrade."` Knowledge graph, conversation summaries, and the pending-relay queue all went offline while a healthy Node (a different Cellar version) was sitting on disk a few millimetres away.
+
+The fix:
+
+1. New `resolveStableNodeBinary()` helper at `src/utils/resolveNodeBinary.ts` (with a CommonJS twin at `scripts/resolve-node-binary.cjs`). It walks a fallback chain — `process.execPath` → `fs.realpathSync(execPath)` → optional caller-supplied bundled Node → `/opt/homebrew/bin/node` (the stable symlink Homebrew always maintains) → `/usr/local/bin/node` → `/usr/bin/node` → `which node` — and returns the first existing-and-executable path, or null when every candidate fails.
+
+2. `ensureSqliteBindings()` in `src/commands/server.ts` now resolves the spawn target through `resolveStableNodeBinary()` before invoking either the bundled `fix-better-sqlite3.cjs` or the npm-rebuild fallback. If resolution returns null, a structured DegradationReporter event is emitted with an explicit recovery hint instead of the previous "rebuild failed (ENOENT)" log line.
+
+3. `scripts/fix-better-sqlite3.cjs` resolves once at module load and uses the resolved path for every internal spawn (testBinary probe, verifyChildAbiMatches defence, source-build via npm). `findNpmCli` also resolves the npm sibling relative to the resolved Node so a stale execPath doesn't poison npm discovery.
+
+4. When the rebuild itself still fails after resolution, `ensureSqliteBindings()` emits a second DegradationReporter event (`ensureSqliteBindings.rebuildFailed`) with a user-actionable recovery hint. Previously the failure was a single yellow log line; now it surfaces through the same degradation channel operators already monitor.
+
+Fail-closed semantics preserved: if no Node binary is reachable anywhere, the heal does NOT proceed (the alternative — guessing wrong — risks producing an ABI-mismatched binary that fails silently later). The DegradationReporter event names the missing Node so the operator can fix it.
+
+## Evidence
+
+Failure mode reproduced and verified to stop:
+
+Reproduction (`tests/integration/heal-execpath-staleness.test.ts`) covers six scenarios drawn directly from the luna incident:
+
+1. `spawnSync` against a stale Cellar path (`/opt/homebrew/Cellar/node/0.0.0-removed-by-brew/bin/node`) returns ENOENT — the same shape as the luna server log line.
+2. The resolver returns a working fallback when execPath is stale. A child process spawned against the resolved path executes successfully.
+3. `fix-better-sqlite3.cjs` resolves a stable Node binary at module load (resolver and script both present, exported helpers callable).
+4. The resolver fails closed when no Node is reachable anywhere — does not silently pick a phantom path.
+5. The resolver rejects non-executable files even when they exist at the requested path (defence against `chmod -x` or write-only files).
+
+Plus seven unit tests in `tests/unit/resolveNodeBinary.test.ts` covering the full fallback chain branch-by-branch.
+
+The live fix on luna (manually-invoked `fix-better-sqlite3.cjs` via the resolved Node binary) brought her degradation count from 8 to 1, with SemanticMemory, TopicMemory, FeatureRegistry, and the pending-relay queue all returning to healthy. With this PR landed, the same recovery will run automatically on every server restart that detects the mismatch.
+
+## What to Tell Your User
+
+If your agent ever logged "rebuild failed (spawnSync ... ENOENT)" after a Homebrew Node update — most often visible as your knowledge graph or conversation summaries going offline while the agent still appears to be running — this fix lets the agent recover on the next restart without manual help. The heal now tries multiple Node paths instead of just the one the server happened to launch with, so a brew-swept-out-from-under-us Cellar path no longer blocks rebuild.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Heal survives stale `process.execPath` | automatic on next server restart |
+| DegradationReporter event on heal failure | automatic — surfaces through existing `/degradations` and any consumers watching that channel |

package/upgrades/side-effects/fix-heal-execpath-staleness.md

@@ -0,0 +1,92 @@
+# Side-Effects Review — fix(heal): resilient process.execPath resolution
+
+**Branch:** `echo/fix-heal-execpath-staleness`
+**Origin:** Luna self-heal failure 2026-05-21 (topic 9976, "topic-intent-layer"). Justin's framing: "the deeper issue that needs to be fixed: why couldn't Luna self heal?"
+**Scope guardrail:** sibling fix to the Topic Intent Layer work, not a fold-in. Heal-path only.
+
+## Summary
+
+When Homebrew updates Node mid-session, `process.execPath` becomes ENOENT. The native-module self-heal spawned subprocesses via that path, so the heal failed with `spawnSync … ENOENT` and the agent's SQLite-backed subsystems degraded. The fix resolves a stable Node binary through a fallback chain before spawning.
+
+Two new files:
+- `src/utils/resolveNodeBinary.ts` — TypeScript resolver used by `ensureSqliteBindings`.
+- `scripts/resolve-node-binary.cjs` — CommonJS twin used by `fix-better-sqlite3.cjs`.
+
+Two modified files:
+- `src/commands/server.ts` — `ensureSqliteBindings` resolves the spawn target before invoking the rebuild path; emits DegradationReporter events on resolver-null and rebuild-failed paths.
+- `scripts/fix-better-sqlite3.cjs` — Module-load resolution; every internal spawn uses the resolved `NODE_BIN`. `findNpmCli` resolves npm relative to the resolved Node, not raw `process.execPath`.
+
+Two new test files:
+- `tests/unit/resolveNodeBinary.test.ts` — 7 tests covering the fallback chain branch-by-branch.
+- `tests/integration/heal-execpath-staleness.test.ts` — 6 tests reproducing the failure shape and verifying the fix.
+
+## Over-block check
+
+Does this fix do MORE than what was asked?
+
+- The resolver does NOT change the once-per-process heal guard in `NativeModuleHealer`. That guard exists to prevent expensive rebuild loops and was deliberately left in place.
+- The resolver does NOT bypass `verifyChildAbiMatches` in the fix script. The ABI-divergence defence is still in place — it now runs against a resolved Node binary instead of process.execPath, which is what makes the defence actually work in the failure mode we're fixing.
+- The DegradationReporter events are NEW emissions but match the existing pattern (subsystem-init-failure events already use the same shape). They surface a previously-silent failure rather than introducing new noise.
+
+## Under-block check
+
+Does this fix leave the failure mode reachable through another path?
+
+Other call sites that spawn via `process.execPath` were audited:
+- `ServerSupervisor.preflightSelfHeal` — runs in the supervisor process, not the child server. Different process, different execPath lifecycle. Out of scope for this fix; supervisor process is short-lived and re-spawns on each cycle.
+- `NativeModuleHealer.healBetterSqlite3Sync` — spawns `npmPath` (a separate variable resolved via `findNpmPath`) with `process.execPath` as args[0]. ENOENT on execPath here would also fail. **Follow-up:** apply the same resolver to this path in a separate small PR. Out of scope for this commit to keep the diff tight per the original ask.
+
+The follow-up is tracked at the bottom of this artifact, not punted as an orphan TODO. (Per the `no-out-of-scope-trap` memory.)
+
+## Level-of-abstraction fit
+
+The resolver is a utility, not a subsystem. It does one thing: resolve a path. It's called from the existing heal-path call sites; it does not own any state, does not log autonomously, does not own the rebuild flow. The DegradationReporter emissions live in `ensureSqliteBindings`, not in the resolver — the resolver returns data, the caller decides whether to escalate.
+
+This matches the signal-vs-authority pattern: the resolver is the signal layer (returns "here's a working Node, here's how I found it, or null if nothing works"); the caller is the authority that decides what to do with that signal.
+
+## Signal-vs-authority compliance
+
+The resolver emits no degradation events, no logs, no side effects beyond resolving a path. It returns a structured value or null.
+
+The caller (`ensureSqliteBindings`) is the authority — it decides:
+- Whether to proceed with the rebuild (only if resolver returned a path).
+- Whether to emit a DegradationReporter event (yes when resolver returns null OR when rebuild fails after resolution).
+- What recovery hint to surface in the degradation impact field.
+
+Two emission sites, both with explicit recovery actions:
+- `ensureSqliteBindings.nodeBinaryResolution` — fires when the resolver returns null. Recovery: reinstall Node and restart.
+- `ensureSqliteBindings.rebuildFailed` — fires when rebuild fails after resolution. Recovery: restart agent OR run `npx instar update`.
+
+## Interactions with other systems
+
+- **NativeModuleHealer.openWithHeal** (the in-line heal path for direct constructor calls): NOT modified by this PR. That path still uses `process.execPath` internally. The follow-up applies the same resolver there.
+- **ServerSupervisor.preflightSelfHeal**: NOT modified. Supervisor runs in a separate process with its own execPath lifecycle.
+- **UpdateChecker.applyUpdate**: Already had its own rebuild path that worked on luna (visible in the server log at 02:35 and 03:21 — both successful rebuilds while the server kept running with stale bindings). No conflict: UpdateChecker's rebuilds happen in long-running processes that already hold the broken in-memory binding; they take effect on next restart. This fix ensures the next restart's preflight can actually run.
+- **PostUpdateMigrator**: NOT touched. Migrator script propagation works as before; no agent-side script needs migration for this fix because both new files (.ts + .cjs) live in the instar package itself.
+
+## Rollback cost
+
+Single-commit revert removes the resolver, the import, the call-site change in `ensureSqliteBindings`, and the resolver-pinned spawns in `fix-better-sqlite3.cjs`. The behavior reverts to "heal fails when execPath is stale" — the failure mode we're fixing, not a new one. No data migration, no config changes, no agent-side script propagation required.
+
+## Cross-framework portability (v1.0+)
+
+The heal path is framework-agnostic — it operates on Node binaries, not on the agent runtime (Claude Code vs Codex). The resolver uses standard Node APIs (`fs`, `os`, `child_process`) with no framework-specific code paths. Verified by:
+- Integration test passes under the test-running Node regardless of framework.
+- The Codex CLI runtime spawns differently but uses the same Node-binary substrate, so the resolver applies equally there.
+
+No `INSTAR_FRAMEWORK`-conditional code added; no framework-aware adapters needed for this fix.
+
+## Telemetry / observability
+
+Heal-attempt visibility before this PR: a single yellow log line on failure.
+Heal-attempt visibility after this PR: that log line PLUS a DegradationReporter event with structured fields (feature, primary, fallback, reason, impact). The event surfaces through `GET /degradations` (existing route) and any subscribers to the degradation event channel (existing pattern).
+
+When the resolver fires a non-execPath fallback, a `console.log(pc.dim(...))` line names which fallback fired and the resolved path. This is one extra log line per server startup that needed it; on healthy startups it doesn't fire.
+
+## Follow-ups (tracked, not orphaned)
+
+1. Apply `resolveStableNodeBinary` to `NativeModuleHealer.healBetterSqlite3Sync` so the in-line CLI-direct-construction heal path (CLI commands like `instar memory ...`, TokenLedger constructor, etc.) also benefits. Should be a small commit on a separate branch — the heal-path-fix scope intentionally excluded it to keep this diff tight.
+
+2. Consider whether the once-per-process heal guard in `NativeModuleHealer` should distinguish "heal failed due to spawn-target ENOENT" (transient, retryable when operator restores Node) from "heal failed due to rebuild error" (durable, don't retry). The current guard treats both the same. Lower priority than (1).
+
+Both items will be filed as initiatives so they don't drop. Not part of this commit.