fix: use managed codex binary for source migration (#81582)

* fix: use managed codex binary for source migration

* docs: document codex reserved sdk subpaths

docs/plugins/sdk-subpaths.md

@@ -361,10 +361,16 @@ focused channel/runtime subpaths, `config-contracts`, `string-coerce-runtime`,
   </Accordion>
 
   <Accordion title="Reserved bundled-helper subpaths">
-    There are currently no reserved bundled-helper SDK subpaths. Owner-specific
-    helpers live inside the owning plugin package, while reusable host contracts
-    use generic SDK subpaths such as `plugin-sdk/gateway-runtime`,
-    `plugin-sdk/security-runtime`, and `plugin-sdk/plugin-config-runtime`.
+    These private compatibility surfaces are reserved for their owning bundled
+    plugin. New reusable host contracts should use generic SDK subpaths such as
+    `plugin-sdk/gateway-runtime`, `plugin-sdk/security-runtime`, and
+    `plugin-sdk/plugin-config-runtime`.
+
+    | Subpath | Key exports |
+    | --- | --- |
+    | `plugin-sdk/codex-mcp-projection` | Codex-owned user MCP server projection helper for the bundled Codex app-server harness |
+    | `plugin-sdk/codex-native-task-runtime` | Codex-owned detached task runtime helpers for native subagent mirroring |
+
   </Accordion>
 </AccordionGroup>
 

extensions/codex/src/migration/plan.ts

@@ -441,6 +441,9 @@ export async function buildCodexMigrationPlan(
           "Codex app-backed plugins were planned without source app accessibility verification. Re-run with --verify-plugin-apps to force a fresh source app/list check before planning native plugin activation.",
         ]
       : []),
+    ...(source.plugins.some((plugin) => plugin.sourceKind === "cache")
+      ? ["Codex cached plugin bundles remain manual-review only."]
+      : []),
     ...(source.pluginDiscoveryError
       ? [
           `Codex app-server plugin inventory discovery failed: ${source.pluginDiscoveryError}. Cached plugin bundles, if any, are advisory only.`,

extensions/codex/src/migration/provider.test.ts

@@ -140,7 +140,7 @@ function sourceAppCacheKey(fixture: { codexHome: string }): string {
       start: {
         transport: "stdio",
         command: "codex",
-        commandSource: "config",
+        commandSource: "managed",
         args: ["app-server", "--listen", "stdio://"],
         headers: {},
         env: {
@@ -242,6 +242,14 @@ describe("buildCodexMigrationProvider", () => {
       method: "plugin/list",
       requestParams: { cwds: [] },
     });
+    expectRecordFields((mockCallArg(appServerRequest) as { startOptions?: unknown }).startOptions, {
+      command: "codex",
+      commandSource: "managed",
+      env: {
+        CODEX_HOME: fixture.codexHome,
+        HOME: path.dirname(fixture.codexHome),
+      },
+    });
     expect(
       appServerRequest.mock.calls.some(
         ([arg]) => (arg as { method?: string }).method === "plugin/install",

extensions/codex/src/migration/source.ts

@@ -245,7 +245,7 @@ function sourceCodexAppServerStartOptions(codexHome: string): CodexAppServerStar
   return {
     transport: "stdio",
     command: "codex",
-    commandSource: "config",
+    commandSource: "managed",
     args: ["app-server", "--listen", "stdio://"],
     headers: {},
     env: {