instar 1.2.25 → 1.2.27

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.27",
   "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,
+};