create-walle 0.9.24 → 0.9.26

package/template/wall-e/lib/brain-read-pool-client.js

@@ -0,0 +1,311 @@
+'use strict';
+
+const path = require('node:path');
+const { Worker } = require('node:worker_threads');
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 20 * 1000;
+const DEFAULT_CLOSE_TIMEOUT_MS = 5 * 1000;
+const DEFAULT_POOL_SIZE = 2;
+
+function _durationMs(value, fallback, min = 0) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.max(min, Math.trunc(n)) : fallback;
+}
+
+function _poolSize(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_POOL_SIZE;
+  return Math.min(8, Math.max(1, Math.trunc(n)));
+}
+
+class BrainReadWorkerSlot {
+  constructor(options = {}) {
+    if (!options.dbPath) throw new Error('BrainReadWorkerSlot requires dbPath');
+    this.dbPath = options.dbPath;
+    this.workerPath = options.workerPath;
+    this.requestTimeoutMs = options.requestTimeoutMs;
+    this.closeTimeoutMs = options.closeTimeoutMs;
+    this.logger = options.logger || console;
+    this.index = options.index || 0;
+    this._worker = null;
+    this._startPromise = null;
+    this._ready = false;
+    this._closed = false;
+    this._nextRequestId = 1;
+    this._pending = new Map();
+    this._status = {
+      ready: false,
+      pendingClientRequests: 0,
+      completed: 0,
+      failed: 0,
+      active: null,
+      pending: 0,
+    };
+  }
+
+  start() {
+    if (this._closed) return Promise.reject(new Error('Brain read worker is closed'));
+    if (this._ready) return Promise.resolve(this);
+    if (this._startPromise) return this._startPromise;
+
+    this._startPromise = new Promise((resolve, reject) => {
+      const worker = new Worker(this.workerPath, {
+        workerData: { dbPath: this.dbPath, slot: this.index },
+        env: {
+          ...process.env,
+          WALL_E_PROCESS_ROLE: 'brain-read-worker',
+        },
+      });
+      this._worker = worker;
+
+      const failStart = (err) => {
+        if (this._ready) return;
+        this._startPromise = null;
+        this._worker = null;
+        try { worker.terminate(); } catch {}
+        reject(err instanceof Error ? err : new Error(String(err || 'Brain read worker failed to start')));
+      };
+
+      worker.on('message', (msg) => {
+        if (!msg || typeof msg !== 'object') return;
+        if (msg.type === 'ready') {
+          this._ready = true;
+          this._status = { ...this._status, ...(msg.status || {}), ready: true };
+          resolve(this);
+          return;
+        }
+        if (msg.type === 'status') {
+          this._status = {
+            ...this._status,
+            ...(msg.status || {}),
+            ready: this._ready,
+            pendingClientRequests: this._pending.size,
+          };
+          return;
+        }
+        if (msg.type === 'response') {
+          this._finishRequest(msg.requestId, msg.error, msg.result);
+          return;
+        }
+        if (msg.type === 'closed') {
+          this._ready = false;
+          this._closed = true;
+          this._status.ready = false;
+          this._rejectAllPending(new Error('Brain read worker closed'));
+          return;
+        }
+        if (msg.type === 'fatal') {
+          const err = new Error(msg.message || msg.error || 'Brain read worker fatal error');
+          err.code = msg.code || 'WALL_E_BRAIN_READ_WORKER_FATAL';
+          if (!this._ready) failStart(err);
+          this._rejectAllPending(err);
+        }
+      });
+
+      worker.on('error', (err) => {
+        if (!this._ready) failStart(err);
+        this._rejectAllPending(err);
+      });
+      worker.on('exit', (code) => {
+        const wasReady = this._ready;
+        this._ready = false;
+        this._worker = null;
+        this._startPromise = null;
+        this._status.ready = false;
+        if (!this._closed && code !== 0) {
+          const err = new Error(`Brain read worker exited with code ${code}`);
+          err.code = 'WALL_E_BRAIN_READ_WORKER_EXITED';
+          if (!wasReady) failStart(err);
+          this._rejectAllPending(err);
+        }
+      });
+    });
+
+    return this._startPromise;
+  }
+
+  async request(op, payload = {}, options = {}) {
+    await this.start();
+    if (!this._worker) throw new Error('Brain read worker is not running');
+    const requestId = this._nextRequestId++;
+    const timeoutMs = _durationMs(options.timeoutMs, this.requestTimeoutMs);
+    return await new Promise((resolve, reject) => {
+      let timer = null;
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          this._pending.delete(requestId);
+          this._status.pendingClientRequests = this._pending.size;
+          reject(new Error(`Brain read worker request timed out: ${op}`));
+        }, timeoutMs);
+        if (typeof timer.unref === 'function') timer.unref();
+      }
+      this._pending.set(requestId, { op, resolve, reject, timer });
+      this._status.pendingClientRequests = this._pending.size;
+      try {
+        this._worker.postMessage({ type: 'request', requestId, op, payload });
+      } catch (err) {
+        this._finishRequest(requestId, err);
+      }
+    });
+  }
+
+  getStatus() {
+    return {
+      ...this._status,
+      ready: this._ready,
+      closed: this._closed,
+      pendingClientRequests: this._pending.size,
+      index: this.index,
+    };
+  }
+
+  async close(options = {}) {
+    if (this._closed) return { ok: true, alreadyClosed: true };
+    const worker = this._worker;
+    this._closed = true;
+    if (!worker) {
+      this._rejectAllPending(new Error('Brain read worker closed'));
+      return { ok: true, alreadyClosed: true };
+    }
+    const timeoutMs = _durationMs(options.timeoutMs, this.closeTimeoutMs);
+    await new Promise((resolve) => {
+      let done = false;
+      const finish = () => {
+        if (done) return;
+        done = true;
+        resolve();
+      };
+      let timer = null;
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => worker.terminate().finally(finish), timeoutMs);
+        if (typeof timer.unref === 'function') timer.unref();
+      }
+      const onMessage = (msg) => {
+        if (msg?.type !== 'closed') return;
+        if (timer) clearTimeout(timer);
+        worker.off('message', onMessage);
+        finish();
+      };
+      worker.on('message', onMessage);
+      try { worker.postMessage({ type: 'close' }); }
+      catch {
+        if (timer) clearTimeout(timer);
+        worker.off('message', onMessage);
+        worker.terminate().finally(finish);
+      }
+    });
+    this._ready = false;
+    this._worker = null;
+    this._rejectAllPending(new Error('Brain read worker closed'));
+    return { ok: true };
+  }
+
+  _finishRequest(requestId, error, result) {
+    const pending = this._pending.get(requestId);
+    if (!pending) return;
+    this._pending.delete(requestId);
+    this._status.pendingClientRequests = this._pending.size;
+    if (pending.timer) clearTimeout(pending.timer);
+    if (error) {
+      const err = error instanceof Error ? error : new Error(String(error.message || error || 'Brain read worker request failed'));
+      if (error.code) err.code = error.code;
+      pending.reject(err);
+    } else {
+      pending.resolve(result);
+    }
+  }
+
+  _rejectAllPending(err) {
+    const pending = Array.from(this._pending.values());
+    this._pending.clear();
+    this._status.pendingClientRequests = 0;
+    for (const req of pending) {
+      if (req.timer) clearTimeout(req.timer);
+      req.reject(err);
+    }
+  }
+}
+
+class BrainReadPoolClient {
+  constructor(options = {}) {
+    if (!options.dbPath) throw new Error('BrainReadPoolClient requires dbPath');
+    this.dbPath = options.dbPath;
+    this.workerPath = options.workerPath || path.resolve(__dirname, '..', 'workers', 'brain-read-worker.js');
+    this.requestTimeoutMs = _durationMs(options.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+    this.closeTimeoutMs = _durationMs(options.closeTimeoutMs, DEFAULT_CLOSE_TIMEOUT_MS);
+    this.size = _poolSize(options.size ?? process.env.WALL_E_BRAIN_READ_POOL_SIZE);
+    this.logger = options.logger || console;
+    this._workers = Array.from({ length: this.size }, (_, index) => new BrainReadWorkerSlot({
+      dbPath: this.dbPath,
+      workerPath: this.workerPath,
+      requestTimeoutMs: this.requestTimeoutMs,
+      closeTimeoutMs: this.closeTimeoutMs,
+      logger: this.logger,
+      index,
+    }));
+    this._roundRobin = 0;
+  }
+
+  async request(op, payload = {}, options = {}) {
+    if (!op) throw new Error('Brain read pool request requires op');
+    const worker = this._pickWorker(options.heavy);
+    return worker.request(op, payload, options);
+  }
+
+  getBrainStats(options) {
+    return this.request('getBrainStats', {}, options);
+  }
+
+  listMemories(payload = {}, options) {
+    return this.request('listMemories', payload, options);
+  }
+
+  listChatMessages(payload = {}, options) {
+    return this.request('listChatMessages', payload, options);
+  }
+
+  listSessions(payload = {}, options) {
+    return this.request('listSessions', payload, options);
+  }
+
+  listRuntimeEvents(payload = {}, options) {
+    return this.request('listRuntimeEvents', payload, options);
+  }
+
+  searchMemories(payload = {}, options) {
+    return this.request('searchMemories', payload, { ...(options || {}), heavy: true });
+  }
+
+  getStatus() {
+    return {
+      size: this.size,
+      workers: this._workers.map((worker) => worker.getStatus()),
+    };
+  }
+
+  async close(options = {}) {
+    await Promise.allSettled(this._workers.map((worker) => worker.close(options)));
+    return { ok: true };
+  }
+
+  _pickWorker(heavy) {
+    if (heavy) {
+      return this._workers
+        .slice()
+        .sort((a, b) => a.getStatus().pendingClientRequests - b.getStatus().pendingClientRequests)[0];
+    }
+    const worker = this._workers[this._roundRobin % this._workers.length];
+    this._roundRobin += 1;
+    return worker;
+  }
+}
+
+function createBrainReadPoolClient(options = {}) {
+  return new BrainReadPoolClient(options);
+}
+
+module.exports = {
+  BrainReadPoolClient,
+  BrainReadWorkerSlot,
+  createBrainReadPoolClient,
+};

package/template/wall-e/lib/diagnostics-flags.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_VALUES = new Set(['0', 'false', 'no', 'off']);
+
+function _flagValue(env, names) {
+  for (const name of names) {
+    if (Object.prototype.hasOwnProperty.call(env, name)) return env[name];
+  }
+  return undefined;
+}
+
+function _truthy(value) {
+  if (value == null) return false;
+  return TRUE_VALUES.has(String(value).trim().toLowerCase());
+}
+
+function _falsey(value) {
+  if (value == null) return false;
+  return FALSE_VALUES.has(String(value).trim().toLowerCase());
+}
+
+function _enabledByFlag(env, names, defaultValue = false) {
+  const value = _flagValue(env, names);
+  if (_truthy(value)) return true;
+  if (_falsey(value)) return false;
+  return defaultValue;
+}
+
+function runtimeDiagnosticsEnabled(env = process.env) {
+  return _enabledByFlag(env, [
+    'WALL_E_RUNTIME_DIAGNOSTICS',
+    'WALLE_RUNTIME_DIAGNOSTICS',
+    'WALL_E_DIAGNOSTICS',
+    'WALLE_DIAGNOSTICS',
+  ], false);
+}
+
+function eventLoopMonitorEnabled(env = process.env) {
+  return runtimeDiagnosticsEnabled(env) && _enabledByFlag(env, [
+    'WALL_E_EVENT_LOOP_MONITOR',
+    'WALLE_EVENT_LOOP_MONITOR',
+  ], true);
+}
+
+function runtimeEventLedgerEnabled(env = process.env) {
+  return runtimeDiagnosticsEnabled(env) && _enabledByFlag(env, [
+    'WALL_E_RUNTIME_EVENT_LEDGER',
+    'WALLE_RUNTIME_EVENT_LEDGER',
+  ], true);
+}
+
+function bootProfileEnabled(env = process.env) {
+  return runtimeDiagnosticsEnabled(env) && _enabledByFlag(env, [
+    'WALL_E_BOOT_PROFILE',
+    'WALLE_BOOT_PROFILE',
+  ], true);
+}
+
+function perfLogsEnabled(env = process.env) {
+  return runtimeDiagnosticsEnabled(env) && _enabledByFlag(env, [
+    'WALL_E_PERF_LOGS',
+    'WALLE_PERF_LOGS',
+  ], true);
+}
+
+function flagSnapshot(env = process.env) {
+  const runtime = runtimeDiagnosticsEnabled(env);
+  return {
+    runtime_diagnostics: runtime,
+    event_loop_monitor: eventLoopMonitorEnabled(env),
+    runtime_event_ledger: runtimeEventLedgerEnabled(env),
+    boot_profile: bootProfileEnabled(env),
+    perf_logs: perfLogsEnabled(env),
+  };
+}
+
+module.exports = {
+  runtimeDiagnosticsEnabled,
+  eventLoopMonitorEnabled,
+  runtimeEventLedgerEnabled,
+  bootProfileEnabled,
+  perfLogsEnabled,
+  flagSnapshot,
+  _truthy,
+  _falsey,
+};

package/template/wall-e/lib/event-loop-monitor.js

@@ -16,16 +16,77 @@
 // All timers are unref'd so the monitor never keeps the process alive.
 
 const { monitorEventLoopDelay } = require('perf_hooks');
+const { eventLoopMonitorEnabled } = require('./diagnostics-flags');
 
 let _histogram = null;
 let _timer = null;
 let _peakMs = 0;
 let _lastWarn = null;
 let _onWarn = null;
+let _getContext = null;
 
 const NS_PER_MS = 1e6;
 const _ms = (ns) => Math.round((Number(ns) || 0) / NS_PER_MS);
 
+function _safeString(value, limit = 160) {
+  return String(value || '')
+    .replace(/\/Users\/[^/\s]+/g, '/Users/<user>')
+    .replace(/[A-Za-z]:\\Users\\[^\\\s]+/g, 'C:\\Users\\<user>')
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '<uuid>')
+    .replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, '<email>')
+    .slice(0, limit);
+}
+
+function _safeContext(value, depth = 0) {
+  if (value == null) return value;
+  if (depth > 4) return '[truncated]';
+  if (typeof value === 'string') return _safeString(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (Array.isArray(value)) return value.slice(0, 10).map((item) => _safeContext(item, depth + 1));
+  if (typeof value === 'object') {
+    const out = {};
+    for (const [key, item] of Object.entries(value).slice(0, 20)) {
+      out[_safeString(key, 80)] = _safeContext(item, depth + 1);
+    }
+    return out;
+  }
+  return _safeString(value);
+}
+
+function _summarizeContext(context) {
+  if (!context || typeof context !== 'object') return '';
+  const parts = [];
+  const schedulerActive = Array.isArray(context.scheduler?.active) ? context.scheduler.active : [];
+  if (schedulerActive.length) {
+    const active = schedulerActive.slice(0, 3).map((job) => {
+      const name = _safeString(job.name || job.job || job.id || 'job', 60);
+      const age = Number(job.ageMs || job.runtimeMs || job.durationMs || 0);
+      return age > 0 ? `${name}@${Math.round(age)}ms` : name;
+    });
+    parts.push(`scheduler=${active.join(',')}`);
+  }
+  const runtimeActive = Array.isArray(context.runtime_active) ? context.runtime_active : [];
+  if (runtimeActive.length) {
+    const active = runtimeActive.slice(0, 3).map((op) => {
+      const name = _safeString(op.name || 'operation', 60);
+      const age = Number(op.ageMs || 0);
+      return age > 0 ? `${name}@${Math.round(age)}ms` : name;
+    });
+    parts.push(`runtime=${active.join(',')}`);
+  }
+  const pool = context.worker_pool;
+  if (pool && typeof pool === 'object') {
+    const busy = Number(pool.busy ?? pool.busyCount);
+    const size = Number(pool.size ?? pool.maxWorkers ?? pool.concurrency);
+    const queued = Number(pool.queued ?? pool.queueDepth ?? pool.queuedOrRunning);
+    const poolBits = [];
+    if (Number.isFinite(busy) && Number.isFinite(size)) poolBits.push(`${busy}/${size} busy`);
+    if (Number.isFinite(queued)) poolBits.push(`${queued} queued`);
+    if (poolBits.length) parts.push(`workers=${poolBits.join(',')}`);
+  }
+  return parts.join('; ').slice(0, 360);
+}
+
 function isRunning() {
   return _histogram != null;
 }
@@ -37,15 +98,18 @@ function isRunning() {
  * @param {number} [opts.sampleMs=10000]       how often to evaluate + reset the window
  * @param {number} [opts.warnThresholdMs=1000] warn if the worst spell in a window exceeds this
  * @param {function} [opts.onWarn]             called as ({ maxMs, meanMs, p99Ms }) on a warning
+ * @param {function} [opts.getContext]         returns scheduler/runtime context for attribution
  * @param {function} [opts.log=console.warn]   where warnings are written
  */
 function start(opts = {}) {
+  if (opts.force !== true && !eventLoopMonitorEnabled()) return false;
   if (_histogram) return; // already running
   const resolution = Math.max(1, Number(opts.resolutionMs) || 20);
   const sampleMs = Math.max(1000, Number(opts.sampleMs) || 10000);
   const warnThresholdMs = Math.max(50, Number(opts.warnThresholdMs) || 1000);
   const log = typeof opts.log === 'function' ? opts.log : console.warn;
   _onWarn = typeof opts.onWarn === 'function' ? opts.onWarn : null;
+  _getContext = typeof opts.getContext === 'function' ? opts.getContext : null;
 
   _histogram = monitorEventLoopDelay({ resolution });
   _histogram.enable();
@@ -58,13 +122,19 @@ function start(opts = {}) {
     if (maxMs > _peakMs) _peakMs = maxMs;
 
     if (maxMs >= warnThresholdMs) {
-      _lastWarn = { at: new Date().toISOString(), maxMs, meanMs, p99Ms };
-      log(`[wall-e] event loop blocked up to ${maxMs}ms in the last ${Math.round(sampleMs / 1000)}s (mean ${meanMs}ms, p99 ${p99Ms}ms) — a synchronous DB query or sync I/O is starving the loop`);
-      if (_onWarn) { try { _onWarn({ maxMs, meanMs, p99Ms }); } catch { /* never let a hook break the monitor */ } }
+      let context = null;
+      if (_getContext) {
+        try { context = _safeContext(_getContext()); } catch {}
+      }
+      _lastWarn = { at: new Date().toISOString(), maxMs, meanMs, p99Ms, context };
+      const contextSummary = _summarizeContext(context);
+      log(`[wall-e] event loop blocked up to ${maxMs}ms in the last ${Math.round(sampleMs / 1000)}s (mean ${meanMs}ms, p99 ${p99Ms}ms) — a synchronous DB query or sync I/O is starving the loop${contextSummary ? `; active: ${contextSummary}` : ''}`);
+      if (_onWarn) { try { _onWarn({ maxMs, meanMs, p99Ms, context }); } catch { /* never let a hook break the monitor */ } }
     }
     _histogram.reset();
   }, sampleMs);
   _timer.unref?.();
+  return true;
 }
 
 /** Cheap snapshot for a health endpoint. Safe to call when not running. */
@@ -88,6 +158,7 @@ function stop() {
   if (_timer) { clearInterval(_timer); _timer = null; }
   if (_histogram) { try { _histogram.disable(); } catch {} _histogram = null; }
   _onWarn = null;
+  _getContext = null;
 }
 
 module.exports = { start, stop, stats, isRunning };

package/template/wall-e/lib/mcp-integration.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const http = require('http');
 const path = require('path');
 const { spawn } = require('child_process');
+const { resolveRealNode } = require('./real-node');
 
 const WALLE_SERVER_NAME = 'wall-e';
 const AGENT_INSTRUCTIONS_BEGIN = '<!-- wall-e-memory-routing:start -->';
@@ -54,7 +55,12 @@ function _requestedMcpTransport(opts = {}) {
 function wallEMcpStdioConfig() {
   return {
     type: 'stdio',
-    command: process.execPath,
+    // resolveRealNode() de-bundles a SELF-SIGNED bundle clone (agents spawn this MCP per session,
+    // so a self-signed bundle path is a restart-storm multiplier) but KEEPS a Developer-ID-signed
+    // bundle exec (trust-cached → no storm, AND macOS TCC prompts show "Wall-E", not "node"). See
+    // lib/real-node.js. Configs self-heal when this changes: the mismatch is detected as
+    // `wrong_command` / `updated` and rewritten on the next ensure.
+    command: resolveRealNode(),
     args: [wallEMcpStdioScript()],
   };
 }

package/template/wall-e/lib/real-node.js

@@ -0,0 +1,98 @@
+'use strict';
+
+// Resolve the REAL node binary for spawning children / configuring the Wall-E MCP command.
+//
+// create-walle (macOS) clones node into self-signed `.app` bundles so the top-level CTM and
+// Wall-E daemons show a real icon + name in Activity Monitor. When Wall-E runs from that
+// bundle, `process.execPath` IS the clone. Writing that clone as the MCP `command` (or
+// spawning children from it) makes every agent launch the Wall-E MCP — and every other
+// child — as a novel, self-signed, un-trust-cached executable. macOS's endpoint-security
+// stack (Gatekeeper/syspolicyd/amfid, plus EDR like PANW Traps and Santa) cold-authorizes
+// each through the synchronous, serialized EndpointSecurity AUTH_EXEC hook; on a
+// multi-session restart, dozens fire at once and stall process creation system-wide.
+//
+// MCP servers need no icon, so point them at the real node binary (one stable, trust-cached
+// cdhash) and keep the bundle exec only for the top-level daemon itself.
+//
+// EXCEPTION — a Developer-ID-signed bundle: the stall above is specific to SELF-SIGNED bundle
+// clones, which carry no Team Identifier and are never in the OS trust cache, so each exec is
+// cold-authorized. A Developer-ID-signed bundle exec has a stable Team ID and IS trust-cached, so
+// it does NOT trigger the storm — and running the MCP under it makes macOS TCC prompts show the
+// branded name ("Wall-E") instead of the anonymous "node". So when the current bundle exec carries
+// a stable Team Identifier, we keep it; we only de-bundle the self-signed case.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync, spawnSync } = require('node:child_process');
+
+let _cached;
+
+function isBundleExec(p) {
+  return !!p && p.includes('.app/Contents/MacOS/');
+}
+
+// The code-signing Team Identifier of a binary, or '' when unsigned/self-signed. A non-empty
+// value ⇒ Developer-ID/notarized ⇒ stable + trust-cached (safe to exec repeatedly, branded TCC).
+function execTeamId(p) {
+  if (process.platform !== 'darwin' || !p) return '';
+  try {
+    const out = spawnSync('codesign', ['-dv', '--verbose=4', p], { encoding: 'utf8' });
+    const text = `${out.stdout || ''}\n${out.stderr || ''}`; // codesign reports to stderr
+    const m = text.match(/^TeamIdentifier=(.+)$/m);
+    const team = m ? m[1].trim() : '';
+    return team === 'not set' ? '' : team;
+  } catch {
+    return '';
+  }
+}
+
+// Pure decision — all IO injected so both branches are unit-testable without macOS / codesign.
+//   deps.execPath   — the current process.execPath
+//   deps.teamIdOf   — (path) => Team Identifier string ('' if self-signed)
+//   deps.existsSync — (path) => boolean
+//   deps.readOrigin — () => the `node-origin` path recorded next to the bundle, or ''
+//   deps.realNode   — () => `node -e process.execPath` result, or ''
+//   deps.env        — process.env (for CTM_REAL_NODE)
+function _resolveRealNode(deps) {
+  const { execPath, teamIdOf, existsSync, readOrigin, realNode, env } = deps;
+  if (!isBundleExec(execPath)) return execPath;
+  // A Developer-ID-signed (or notarized) bundle exec is stable + trust-cached + branded — keep it:
+  // no exec-storm (it's trust-cached) and TCC prompts show "Wall-E", not "node". Only de-bundle a
+  // SELF-SIGNED bundle (no Team ID), whose novel cdhash would trigger the AUTH_EXEC storm above.
+  if (teamIdOf(execPath)) return execPath;
+
+  const candidates = [];
+  try { const o = readOrigin(); if (o) candidates.push(o); } catch {}
+  if (env && env.CTM_REAL_NODE) candidates.push(env.CTM_REAL_NODE);
+  try { const r = realNode(); if (r) candidates.push(r); } catch {}
+  candidates.push('/opt/homebrew/bin/node', '/usr/local/bin/node', '/usr/bin/node');
+
+  for (const c of candidates) {
+    try {
+      if (c && !isBundleExec(c) && existsSync(c)) return c;
+    } catch {}
+  }
+  return execPath;
+}
+
+function resolveRealNode() {
+  if (_cached) return _cached;
+  _cached = _resolveRealNode({
+    execPath: process.execPath,
+    teamIdOf: execTeamId,
+    existsSync: fs.existsSync,
+    env: process.env,
+    readOrigin: () => {
+      const bundleRoot = path.resolve(path.dirname(process.execPath), '..', '..', '..');
+      return fs.readFileSync(path.join(bundleRoot, 'node-origin'), 'utf8').trim();
+    },
+    realNode: () => execFileSync('node', ['-e', 'process.stdout.write(process.execPath)'], { encoding: 'utf8' }).trim(),
+  });
+  return _cached;
+}
+
+function _resetCacheForTests() {
+  _cached = undefined;
+}
+
+module.exports = { resolveRealNode, isBundleExec, execTeamId, _resolveRealNode, _resetCacheForTests };