v0.6.0 - plugin MCP: HTTP attach-only bridge

Replace the Claude plugin MCP child-process bridge with a Node stdio-to-HTTP proxy that attaches to the running daemon over /mcp-rpc. SessionStart is status-only and no longer resolves or shells into cortex.exe. Remove legacy dev app URL routing and local-spawn fallback behavior.

Validation: node --test plugins/cortex-plugin/scripts/run-mcp.contract.test.cjs; node plugins/cortex-plugin/scripts/dry-run-matrix.cjs; node --check plugin scripts; python tools/audit_spawn_paths.py --strict; live stdin parse-error smoke against local daemon.

Author: AdityaVG13

plugins/cortex-plugin/ROUTING.md

@@ -1,65 +1,57 @@
-# Cortex Plugin Routing Policy (App-First + Local Service-First)
+# Cortex Plugin Routing Policy (HTTP Attach-Only)
 
-The plugin prefers app-managed routing, but local plugin mode is allowed for
-plugin-only users. In local mode, `cortex plugin mcp` performs service-first
-daemon ensure on Windows and then bridges MCP.
+The Claude Code plugin never starts a Cortex daemon and never shells into a
+`cortex` binary for the MCP bridge. The Control Center/service owns daemon
+lifecycle. The plugin attaches to an already-running daemon over HTTP.
 
 ## Priority Order
+
 1. Explicit plugin URL (`CLAUDE_PLUGIN_OPTION_CORTEX_URL`)
 2. App route URL (`CORTEX_APP_URL`)
-3. Local route (`localhost` with service-first ensure)
-
-## Binary Selection Order (for MCP bridge and SessionStart probes)
-1. Explicit binary override (`CORTEX_APP_BINARY`, `CORTEX_DAEMON_BINARY`, `CORTEX_PLUGIN_CORTEX_BINARY`)
-2. App-managed canonical install (`~/.cortex/bin/cortex[.exe]`)
-3. Common workspace dev/release builds (`~/cortex/daemon-rs/target*`)
-4. Bundled plugin runtime binary (`CLAUDE_PLUGIN_DATA/bin/cortex[.exe]`) -- allowed as local fallback when safe
+3. Local attach-only route (`http://127.0.0.1:7437`)
 
-This keeps plugin tooling aligned with the app daemon in development and avoids
-relying on stale bundled binaries when a canonical app-managed binary exists.
-
-## Local Binary Safety Gate
-- In local mode, plugin scripts reject temporary runtime binaries by default.
-- App-managed binaries are preferred; plugin-bundled fallback is allowed when safe.
-- Optional strict mode:
-  - `CORTEX_PLUGIN_REQUIRE_APP_BINARY=1` forces app-managed binary only.
-- Optional compatibility override:
-  - `CORTEX_PLUGIN_ALLOW_BUNDLED_BINARY=1` permits bundled fallback even when strict mode is set.
+`CORTEX_DEV_PREFER_APP=1` is strict: it requires `CORTEX_APP_URL` and fails
+instead of falling back.
 
 ## Supported Environment Inputs
+
 - `CLAUDE_PLUGIN_OPTION_CORTEX_URL`
   - Preferred explicit route for team/remote endpoint.
 - `CLAUDE_PLUGIN_OPTION_CORTEX_API_KEY`
-  - Optional API key for explicit remote route.
+  - Required API key for non-local explicit remote routes.
 - `CORTEX_APP_URL`
   - Preferred app-managed endpoint route during development.
+- `CORTEX_API_KEY`
+  - Fallback API key for app-managed remote routes.
 - `CORTEX_PLUGIN_DRY_RUN=1`
-  - Prints resolved route and exits without launching MCP bridge child.
-- `CORTEX_APP_BINARY`, `CORTEX_DAEMON_BINARY`, `CORTEX_PLUGIN_CORTEX_BINARY`
-  - Optional explicit binary override for plugin bridge/hook execution.
-- `CORTEX_WORKSPACE_ROOT`
-  - Optional workspace root used to discover dev/release daemon builds.
-- `CORTEX_PLUGIN_REQUIRE_APP_BINARY=1`
-  - Optional strict policy to require app-managed binary in local mode.
-- `CORTEX_PLUGIN_ALLOW_BUNDLED_BINARY=1`
-  - Optional escape hatch to permit bundled plugin binaries when strict mode is active.
+  - Prints resolved route and exits without opening the MCP proxy loop.
+
+Legacy local-spawn toggles are ignored by the MCP entry point because no local
+spawn path exists there anymore.
 
 ## Route Matrix
-- Plugin URL set -> route `remote` -> pass `--url` and optional `--api-key`
-- No plugin URL, app URL set -> route `remote` -> pass `--url`
-- No plugin/app URL -> route `local` -> service-first ensure on Windows, then local bridge
+
+- Plugin URL set -> route `remote` -> Node stdio-to-HTTP proxy
+- No plugin URL, app URL set -> route `remote` -> Node stdio-to-HTTP proxy
+- No plugin/app URL -> route `local` -> Node stdio-to-HTTP proxy to `127.0.0.1:7437`
+- `CORTEX_DEV_PREFER_APP=1` without `CORTEX_APP_URL` -> explicit failure
 
 ## Lifecycle Guarantees
+
 - Plugin SessionStart hook is status-only and never starts/stops daemon.
-- SessionStart probes `/readiness` first and falls back to `/health` for older daemons.
-- Plugin MCP bridge never direct-spawns daemon binaries itself.
-- Local plugin mode delegates daemon readiness to `cortex plugin mcp` service-first policy (Windows) or returns a clear unsupported-local-ensure error on non-Windows.
-- If local mode resolves only temporary binaries, plugin blocks fallback and surfaces safe-binary guidance.
+- SessionStart probes `/readiness` first and falls back to `/health`.
+- Plugin MCP bridge posts JSON-RPC to `/mcp-rpc` with:
+  - `X-Cortex-Request: true`
+  - `Authorization: Bearer <token>` for local or remote authenticated routes
+  - `X-Source-Agent`
+  - optional `X-Source-Model`
+- Local token auth is read from `CORTEX_TOKEN_PATH`, `CORTEX_HOME/cortex.token`,
+  or `~/.cortex/cortex.token`.
+- If local mode cannot reach a ready daemon, the bridge exits with
+  `APP_INIT_REQUIRED` and instructs the user to open Cortex Control Center.
 
 ## Lockstep Requirement
-Plugin-bundled daemon versions and app daemon versions should ship in lockstep.
 
-Minimum release guard:
-1. Build plugin bundle from the same daemon commit used by app release artifacts.
-2. Keep plugin version and daemon release manifest aligned in release checklist.
-3. Add CI guard that fails release when plugin bundle daemon version differs from app daemon version.
+Plugin release artifacts and app daemon versions should still ship in lockstep,
+but plugin MCP routing no longer depends on a bundled or canonical daemon binary.
+

plugins/cortex-plugin/scripts/dry-run-matrix.cjs

@@ -2,78 +2,67 @@
 /**
  * Dry-run matrix for `run-mcp.cjs` routing resolver.
  *
- * Invokes `resolveRoute` with 5 representative environment shapes and asserts
- * the resulting (mode, spawnAllowed) pair matches the documented behavior
- * matrix in `docs/internal/v060/plugin-routing.md`.
- *
- * Exit code 0 = all 5 pass. Exit code 1 = at least one mismatch.
- *
- * Run: `node plugins/cortex-plugin/scripts/dry-run-matrix.cjs`
+ * The plugin MCP entry point is HTTP attach-only. It never local-spawns a
+ * cortex daemon process; missing local daemon readiness is reported at runtime.
  */
 
 const assert = require('node:assert/strict');
-const { resolveRoute } = require('./run-mcp.cjs');
+const { DEFAULT_LOCAL_BASE_URL, resolveRoute } = require('./run-mcp.cjs');
 
 const cases = [
   {
-    name: '1. Explicit URL set — remote route, no local spawn',
+    name: '1. Explicit URL set - remote HTTP route, no local spawn',
     config: { cortexUrl: 'https://cortex.myteam.com:7437' },
     env: {},
     expected: { mode: 'remote', spawnAllowed: false, hasUrl: true, reasonMatch: /explicit plugin URL/ }
   },
   {
-    name: '2. Dev prefer app + URL set — remote route, no local spawn',
+    name: '2. Dev prefer app + CORTEX_APP_URL set - remote HTTP route, no local spawn',
     config: {},
     env: {
       CORTEX_DEV_PREFER_APP: '1',
-      CORTEX_DEV_APP_URL: 'http://127.0.0.1:7437'
+      CORTEX_APP_URL: 'http://127.0.0.1:7437'
     },
     expected: { mode: 'remote', spawnAllowed: false, hasUrl: true, reasonMatch: /dev prefer app/ }
   },
   {
-    name: '3. Dev prefer app + NO URL — explicit failure',
+    name: '3. Dev prefer app + NO CORTEX_APP_URL - explicit failure',
     config: {},
     env: { CORTEX_DEV_PREFER_APP: '1' },
-    expected: { mode: 'fail', spawnAllowed: false, hasUrl: false, reasonMatch: /CORTEX_DEV_PREFER_APP=1/ }
+    expected: { mode: 'fail', spawnAllowed: false, hasUrl: false, reasonMatch: /CORTEX_APP_URL/ }
   },
   {
-    name: '4. No URL, local spawn allowed — local route',
+    name: '4. No URL - local HTTP attach-only route, no local spawn',
     config: {},
     env: {},
-    expected: { mode: 'local', spawnAllowed: true, hasUrl: false, reasonMatch: /local service-first/ }
+    expected: { mode: 'local', spawnAllowed: false, hasUrl: true, reasonMatch: /local HTTP attach-only/ }
   },
   {
-    name: '5. No URL, local spawn disabled — explicit failure',
+    name: '5. Local-spawn disable flag is redundant - still local HTTP attach-only',
     config: {},
     env: { CORTEX_DEV_DISABLE_LOCAL_SPAWN: '1' },
-    expected: {
-      mode: 'fail',
-      spawnAllowed: false,
-      hasUrl: false,
-      reasonMatch: /CORTEX_DEV_DISABLE_LOCAL_SPAWN=1/
-    }
+    expected: { mode: 'local', spawnAllowed: false, hasUrl: true, reasonMatch: /local HTTP attach-only/ }
   },
-  // Extra bonus cases to lock corner behavior
   {
     name: '6. Explicit URL beats dev prefer app',
     config: { cortexUrl: 'https://explicit.example' },
     env: {
       CORTEX_DEV_PREFER_APP: '1',
-      CORTEX_DEV_APP_URL: 'http://should-be-ignored'
+      CORTEX_APP_URL: 'http://should-be-ignored'
     },
     expected: { mode: 'remote', spawnAllowed: false, hasUrl: true, reasonMatch: /explicit plugin URL/ }
   },
   {
-    name: '7. Local disable overridden by CORTEX_PLUGIN_ALLOW_LOCAL_SPAWN',
+    name: '7. Legacy local-spawn allow flag is ignored - no spawn path exists',
     config: {},
     env: {
       CORTEX_DEV_DISABLE_LOCAL_SPAWN: '1',
       CORTEX_PLUGIN_ALLOW_LOCAL_SPAWN: '1'
     },
-    expected: { mode: 'local', spawnAllowed: true, hasUrl: false, reasonMatch: /local service-first/ }
+    expected: { mode: 'local', spawnAllowed: false, hasUrl: true, reasonMatch: /local HTTP attach-only/ }
   },
   {
-    name: '8. CORTEX_APP_URL alone → remote app route',
+    name: '8. CORTEX_APP_URL alone - remote app route',
     config: {},
     env: { CORTEX_APP_URL: 'http://127.0.0.1:7437' },
     expected: { mode: 'remote', spawnAllowed: false, hasUrl: true, reasonMatch: /app route/ }
@@ -92,11 +81,14 @@ for (const tc of cases) {
     } else {
       assert.equal(route.url, '', 'expected empty url');
     }
+    if (route.mode === 'local') {
+      assert.equal(route.url, DEFAULT_LOCAL_BASE_URL);
+    }
     if (tc.expected.reasonMatch) {
       assert.match(route.reason, tc.expected.reasonMatch, 'reason mismatch');
     }
     console.log(`PASS  ${tc.name}`);
-    console.log(`      → mode=${route.mode} spawnAllowed=${route.spawnAllowed} reason="${route.reason}"`);
+    console.log(`      -> mode=${route.mode} spawnAllowed=${route.spawnAllowed} reason="${route.reason}"`);
     pass++;
   } catch (err) {
     console.error(`FAIL  ${tc.name}`);
@@ -107,3 +99,4 @@ for (const tc of cases) {
 
 console.log(`\n${pass}/${cases.length} passed. ${fail} failed.`);
 process.exit(fail === 0 ? 0 : 1);
+