feat(memory-core): discover wake instance address from parent chain (#12419) (#12563)

neo-gpt · web-flow · commit 56a082f5e146 · 2026-06-05T15:32:45.000+02:00
diff --git a/ai/mcp/server/shared/services/BootEnvelopeResolver.mjs b/ai/mcp/server/shared/services/BootEnvelopeResolver.mjs
@@ -1,5 +1,10 @@
+import {execFileSync as defaultExecFileSync} from 'child_process';
+
+import {resolveInstancePid} from '../../../../daemons/bridge/instanceResolver.mjs';
 import Base from '../../../../../src/core/Base.mjs';
 
+const USER_DATA_DIR_PATTERN = /(?:^|\s)--user-data-dir=(?:"([^"]+)"|'([^']+)'|(.+?))(?=\s--|$)/;
+
 /**
  * @summary Resolves the per-instance wake-routing address from the boot environment into
  * `overrideMetadata` for the auto-bootstrapped wake subscription.
@@ -24,12 +29,14 @@ import Base from '../../../../../src/core/Base.mjs';
  * - `NEO_HARNESS_INSTANCE_ADDRESS_TYPE` — the address kind: one of `userDataDir`, `pid`,
  *   `tmuxSession`, `webhookUrl`.
  *
- * Both must be set together or both omitted. Omitting both is the normal **default instance** — the
- * primary macOS app started without `--user-data-dir`, which is routed by the *absence* of an
- * address (see the bridge daemon's default-instance resolution). A partially-set envelope is a
- * configuration error and **fails closed** (throws): a non-default instance with a broken address
- * must never silently fall back to the default route, because that misroutes its wakes into the
- * default instance's window.
+ * Both must be set together or both omitted. Omitting both first attempts a narrow macOS Electron
+ * parent-chain fallback: if this MCP server was spawned under an app/helper process whose command
+ * line carries `--user-data-dir`, that path is used as a `userDataDir` address. Otherwise omission
+ * remains the normal **default instance** — the primary macOS app started without `--user-data-dir`,
+ * routed by the *absence* of an address (see the bridge daemon's default-instance resolution). A
+ * partially-set envelope is a configuration error and **fails closed** (throws): a non-default
+ * instance with a broken address must never silently fall back to the default route, because that
+ * misroutes its wakes into the default instance's window.
  *
  * ## Dispatch coverage
  *
@@ -78,21 +85,36 @@ class BootEnvelopeResolver extends Base {
      * Resolves the boot instance-address envelope into wake-subscription `overrideMetadata`.
      *
      * @param {Object} [env=process.env] Environment source (injectable for tests).
+     * @param {Object} [options]
+     * @param {Boolean} [options.enableParentChainFallback=true] Whether to use the macOS Electron
+     *     parent-chain fallback when the explicit envelope is absent.
+     * @param {Number} [options.bootPid=process.pid] MCP server boot pid for fallback discovery.
+     * @param {String} [options.psOutput] Injectable `ps axww -o pid=,ppid=,command=` snapshot.
+     * @param {Function} [options.execFileSync=child_process.execFileSync] Injectable `ps` runner.
+     * @param {String} [options.platform=process.platform] Platform guard for tests.
      * @returns {Object|null} `overrideMetadata` to merge into the bootstrapped subscription
      *     (`{instanceAddress, addressType, ...}`), or `null` for the default instance (no address
      *     configured → routed by absence).
      * @throws {Error} When the envelope is partially configured, the address type is unrecognized,
      *     or the address type is recognized but not yet dispatchable (fail-closed to prevent
      *     misrouting a non-default instance to the default route).
      */
-    resolveOverrideMetadata(env = process.env) {
+    resolveOverrideMetadata(env = process.env, {
+        bootPid                   = process.pid,
+        enableParentChainFallback = true,
+        execFileSync              = defaultExecFileSync,
+        platform                  = process.platform,
+        psOutput
+    } = {}) {
         const instanceAddress = env.NEO_HARNESS_INSTANCE_ADDRESS?.trim(),
               addressType      = env.NEO_HARNESS_INSTANCE_ADDRESS_TYPE?.trim();
 
-        // Default instance: no address configured → no override. The daemon routes the arg-less
-        // main instance by the absence of an address.
+        // No explicit address configured: try the narrow macOS Electron fallback. If it cannot
+        // prove an instance address, keep the existing default-instance behavior (null).
         if (!instanceAddress && !addressType) {
-            return null;
+            return enableParentChainFallback
+                ? this.resolveParentChainOverrideMetadata({bootPid, execFileSync, platform, psOutput})
+                : null;
         }
 
         // Partial envelope is a misconfiguration. Fail closed rather than degrade to default
@@ -123,6 +145,158 @@ class BootEnvelopeResolver extends Base {
 
         return {instanceAddress, addressType};
     }
+
+    /**
+     * @summary Resolves `overrideMetadata` from the MCP server's macOS Electron parent chain.
+     *
+     * This fallback never runs when the explicit env envelope is present, and it returns `null` on
+     * every ambiguous/non-Electron/cloud shape so bootstrapping keeps the default-instance absence
+     * route instead of guessing.
+     *
+     * @param {Object} options
+     * @param {Number} [options.bootPid=process.pid] Starting pid for the parent-chain walk.
+     * @param {String} [options.psOutput] Injectable process snapshot.
+     * @param {Function} [options.execFileSync=child_process.execFileSync] Injectable `ps` runner.
+     * @param {String} [options.platform=process.platform] Platform guard.
+     * @returns {{instanceAddress:String,addressType:String}|null}
+     */
+    resolveParentChainOverrideMetadata({
+        bootPid      = process.pid,
+        execFileSync = defaultExecFileSync,
+        platform     = process.platform,
+        psOutput
+    } = {}) {
+        if (platform !== 'darwin') {
+            return null;
+        }
+
+        const snapshot = psOutput ?? this.readProcessSnapshot({execFileSync});
+        if (!snapshot) {
+            return null;
+        }
+
+        const userDataDir = this.resolveParentChainUserDataDir({bootPid, psOutput: snapshot});
+        if (!userDataDir) {
+            return null;
+        }
+
+        // Reuse the bridge daemon's main-pid resolver as the final proof that the discovered
+        // address maps to a concrete Electron app instance. If the snapshot cannot prove that,
+        // fail closed rather than emitting a route that might mis-target.
+        if (resolveInstancePid({userDataDir, psOutput: snapshot}) === null) {
+            return null;
+        }
+
+        return {
+            instanceAddress: userDataDir,
+            addressType    : 'userDataDir'
+        };
+    }
+
+    /**
+     * @summary Reads a full process snapshot for parent-chain address discovery.
+     * @param {Object} options
+     * @param {Function} [options.execFileSync=child_process.execFileSync]
+     * @returns {String|null}
+     */
+    readProcessSnapshot({execFileSync = defaultExecFileSync} = {}) {
+        try {
+            return execFileSync('ps', ['axww', '-o', 'pid=,ppid=,command='], {
+                encoding: 'utf8',
+                stdio   : ['ignore', 'pipe', 'pipe']
+            });
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * @summary Walks from the MCP server pid to its parents and extracts a proven Electron
+     * `--user-data-dir` value when present.
+     *
+     * @param {Object} options
+     * @param {Number} options.bootPid Starting pid for the parent-chain walk.
+     * @param {String} options.psOutput `ps axww -o pid=,ppid=,command=` snapshot.
+     * @param {Number} [options.maxDepth=12] Parent traversal cap.
+     * @returns {String|null}
+     */
+    resolveParentChainUserDataDir({bootPid, psOutput, maxDepth = 12} = {}) {
+        if (!bootPid || !psOutput) {
+            return null;
+        }
+
+        const byPid  = this.parseProcessSnapshot(psOutput),
+              seen   = new Set();
+        let   cursor = Number(bootPid);
+
+        for (let depth = 0; depth < maxDepth; depth++) {
+            const row = byPid.get(cursor);
+            if (!row || seen.has(row.pid)) {
+                return null;
+            }
+
+            seen.add(row.pid);
+
+            if (this.isElectronAppProcess(row.command)) {
+                const userDataDir = this.extractUserDataDir(row.command);
+                if (userDataDir) {
+                    return userDataDir;
+                }
+            }
+
+            if (!row.ppid || row.ppid === 1 || row.ppid === row.pid) {
+                return null;
+            }
+
+            cursor = row.ppid;
+        }
+
+        return null;
+    }
+
+    /**
+     * @summary Parses `ps axww -o pid=,ppid=,command=` rows by pid.
+     * @param {String} psOutput
+     * @returns {Map<Number,{pid:Number,ppid:Number,command:String}>}
+     */
+    parseProcessSnapshot(psOutput = '') {
+        return new Map(psOutput.split('\n')
+            .map(line => line.trim())
+            .filter(Boolean)
+            .map(line => {
+                const match = line.match(/^(\d+)\s+(\d+)\s+(.*)$/);
+                if (!match) {
+                    return null;
+                }
+                const pid  = Number(match[1]),
+                      ppid = Number(match[2]);
+
+                return {pid, ppid, command: match[3]};
+            })
+            .filter(Boolean)
+            .map(row => [row.pid, row]));
+    }
+
+    /**
+     * @summary Detects macOS Electron app/main/helper process commands.
+     * @param {String} command
+     * @returns {Boolean}
+     */
+    isElectronAppProcess(command = '') {
+        return command.includes('.app/Contents/') &&
+            (command.includes('/Contents/MacOS/') || /Helper|Framework/i.test(command));
+    }
+
+    /**
+     * @summary Extracts a `--user-data-dir` value from a process command line.
+     * @param {String} command
+     * @returns {String|null}
+     */
+    extractUserDataDir(command = '') {
+        const match = command.match(USER_DATA_DIR_PATTERN);
+
+        return match ? (match[1] || match[2] || match[3] || '').trim() || null : null;
+    }
 }
 
 export default Neo.setupClass(BootEnvelopeResolver);
diff --git a/test/playwright/unit/ai/mcp/server/shared/services/BootEnvelopeResolver.spec.mjs b/test/playwright/unit/ai/mcp/server/shared/services/BootEnvelopeResolver.spec.mjs
@@ -30,10 +30,22 @@ import BootEnvelopeResolver from '../../../../../../../../ai/mcp/server/shared/s
  */
 
 test.describe('Neo.ai.mcp.server.shared.services.BootEnvelopeResolver (#12418)', () => {
-    const NEO_DIR = '/Users/example/.claude-instances/Neo';
+    const NEO_DIR     = '/Users/example/.claude-instances/Neo';
+    const DEFAULT_DIR = '/Users/example/Library/Application Support/Claude';
+    const PS_ELECTRON_PARENT_CHAIN = [
+        `90001 20005 /Users/example/.nvm/versions/node/v22/bin/node /Users/example/neo/ai/mcp/server/memory-core/main.mjs`,
+        `20005 20001 /Applications/Claude.app/Contents/Frameworks/Claude Helper (Renderer).app/Contents/MacOS/Claude Helper (Renderer) --type=renderer --user-data-dir=${NEO_DIR} --app-path=/x`,
+        `20001 1 /Applications/Claude.app/Contents/MacOS/Claude --user-data-dir=${NEO_DIR}`,
+        `13106 1 /Applications/Claude.app/Contents/MacOS/Claude`,
+        `13119 13106 /Applications/Claude.app/Contents/Frameworks/Claude Helper.app/Contents/MacOS/Claude Helper --type=gpu-process --user-data-dir=${DEFAULT_DIR} --gpu-preferences=xyz`
+    ].join('\n');
 
     test('default instance — neither env var set returns null (routed by absence)', () => {
-        expect(BootEnvelopeResolver.resolveOverrideMetadata({})).toBeNull();
+        expect(BootEnvelopeResolver.resolveOverrideMetadata({}, {
+            bootPid : 90001,
+            platform: 'darwin',
+            psOutput: '90001 1 /usr/local/bin/node /tmp/server.mjs'
+        })).toBeNull();
     });
 
     test('empty-string env vars are treated as absent (default instance)', () => {
@@ -47,6 +59,10 @@ test.describe('Neo.ai.mcp.server.shared.services.BootEnvelopeResolver (#12418)',
         const result = BootEnvelopeResolver.resolveOverrideMetadata({
             NEO_HARNESS_INSTANCE_ADDRESS     : NEO_DIR,
             NEO_HARNESS_INSTANCE_ADDRESS_TYPE: 'userDataDir'
+        }, {
+            bootPid : 90001,
+            platform: 'darwin',
+            psOutput: PS_ELECTRON_PARENT_CHAIN
         });
 
         expect(result).toEqual({
@@ -70,12 +86,20 @@ test.describe('Neo.ai.mcp.server.shared.services.BootEnvelopeResolver (#12418)',
     test('fails closed on a partial envelope — address without type', () => {
         expect(() => BootEnvelopeResolver.resolveOverrideMetadata({
             NEO_HARNESS_INSTANCE_ADDRESS: NEO_DIR
+        }, {
+            bootPid : 90001,
+            platform: 'darwin',
+            psOutput: PS_ELECTRON_PARENT_CHAIN
         })).toThrow(/Partial boot envelope/);
     });
 
     test('fails closed on a partial envelope — type without address', () => {
         expect(() => BootEnvelopeResolver.resolveOverrideMetadata({
             NEO_HARNESS_INSTANCE_ADDRESS_TYPE: 'userDataDir'
+        }, {
+            bootPid : 90001,
+            platform: 'darwin',
+            psOutput: PS_ELECTRON_PARENT_CHAIN
         })).toThrow(/Partial boot envelope/);
     });
 
@@ -133,4 +157,61 @@ test.describe('Neo.ai.mcp.server.shared.services.BootEnvelopeResolver (#12418)',
         expect(BootEnvelopeResolver.validAddressTypes).toEqual(['userDataDir', 'pid', 'tmuxSession', 'webhookUrl']);
         expect(BootEnvelopeResolver.dispatchableAddressTypes).toEqual(['userDataDir', 'pid', 'tmuxSession', 'webhookUrl']);
     });
+
+    test('fallback discovers userDataDir from macOS Electron helper→main parent chain (#12419)', () => {
+        expect(BootEnvelopeResolver.resolveOverrideMetadata({}, {
+            bootPid : 90001,
+            platform: 'darwin',
+            psOutput: PS_ELECTRON_PARENT_CHAIN
+        })).toEqual({
+            instanceAddress: NEO_DIR,
+            addressType    : 'userDataDir'
+        });
+    });
+
+    test('fallback never overrides an explicit envelope value (#12419)', () => {
+        const explicitDir = '/Users/example/.claude-instances/Explicit';
+
+        expect(BootEnvelopeResolver.resolveOverrideMetadata({
+            NEO_HARNESS_INSTANCE_ADDRESS     : explicitDir,
+            NEO_HARNESS_INSTANCE_ADDRESS_TYPE: 'userDataDir'
+        }, {
+            bootPid : 90001,
+            platform: 'darwin',
+            psOutput: PS_ELECTRON_PARENT_CHAIN
+        })).toEqual({
+            instanceAddress: explicitDir,
+            addressType    : 'userDataDir'
+        });
+    });
+
+    test('fallback no-ops outside macOS / Electron parent chains (#12419)', () => {
+        expect(BootEnvelopeResolver.resolveOverrideMetadata({}, {
+            bootPid : 90001,
+            platform: 'linux',
+            psOutput: PS_ELECTRON_PARENT_CHAIN
+        })).toBeNull();
+
+        expect(BootEnvelopeResolver.resolveOverrideMetadata({}, {
+            bootPid : 90001,
+            platform: 'darwin',
+            psOutput: [
+                '90001 42 /usr/local/bin/node /Users/example/neo/ai/mcp/server/memory-core/main.mjs',
+                '42 1 /usr/bin/tmux new-session'
+            ].join('\n')
+        })).toBeNull();
+    });
+
+    test('fallback fails closed when discovered userDataDir cannot map to a main pid (#12419)', () => {
+        const helperOnlySnapshot = [
+            `90001 20005 /Users/example/.nvm/versions/node/v22/bin/node /Users/example/neo/ai/mcp/server/memory-core/main.mjs`,
+            `20005 20001 /Applications/Claude.app/Contents/Frameworks/Claude Helper (Renderer).app/Contents/MacOS/Claude Helper (Renderer) --type=renderer --user-data-dir=${NEO_DIR} --app-path=/x`
+        ].join('\n');
+
+        expect(BootEnvelopeResolver.resolveOverrideMetadata({}, {
+            bootPid : 90001,
+            platform: 'darwin',
+            psOutput: helperOnlySnapshot
+        })).toBeNull();
+    });
 });
