@skillcap/gdh 0.6.0 → 0.8.0

package/node_modules/@gdh/adapters/dist/index.js

@@ -9,8 +9,8 @@ import { CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH, CLAUDE_CHECK_UPDATE_WORKER_RELA
 import { renderClaudeCheckUpdateWorker } from "./claude-update-worker-render.js";
 import { CLAUDE_STATUSLINE_RELATIVE_PATH, renderClaudeUpdateStatusline, } from "./claude-statusline-render.js";
 import { CLAUDE_SETTINGS_RELATIVE_PATH, patchClaudeSettingsForGdhSessionStart, patchClaudeSettingsForGdhStatusline, } from "./claude-settings-patch.js";
-import { GDH_AGENT_CONTRACT_VERSION, GDH_CURSOR_RULE_VERSION, GDH_GUIDANCE_INDEX_VERSION, GDH_GUIDANCE_UNIT_VERSION, GDH_MCP_LAUNCHER_VERSION, GDH_PROJECT_CONFIG_VERSION, GDH_RECIPE_SCHEMA_VERSION, GDH_RULES_SCHEMA_VERSION, GDH_SCENARIO_SCHEMA_VERSION, definePackageBoundary, resolveCurrentGdhInstall, resolveGdhProductMetadata, } from "@gdh/core";
-import { createDefaultGuidanceUnits, getGuidanceStatus, resolveGuidanceQuery, } from "@gdh/docs";
+import { GDH_AGENT_CONTRACT_VERSION, GDH_CURSOR_RULE_VERSION, GDH_GUIDANCE_INDEX_VERSION, GDH_GUIDANCE_UNIT_VERSION, GDH_PROJECT_CONFIG_VERSION, GDH_RECIPE_SCHEMA_VERSION, GDH_RULES_SCHEMA_VERSION, GDH_SCENARIO_SCHEMA_VERSION, assertProjectLifecycleCompatibilityInvariant, definePackageBoundary, resolveCurrentGdhInstall, resolveGdhProductMetadata, } from "@gdh/core";
+import { createDefaultGuidanceUnits, getGuidanceStatus, resolveGuidanceQuery, resolveRecoveryHints, } from "@gdh/docs";
 import { inspectGuidanceAudit } from "@gdh/observability";
 import { inspectRuntimeBridgeSurface } from "@gdh/runtime";
 import { scanGodotProjectInventory } from "@gdh/scan";
@@ -65,8 +65,13 @@ export const CLAUDE_SCAN_COMMAND_RELATIVE_PATH = ".claude/commands/gdh/scan.md";
 export const CODEX_SCAN_SKILL_RELATIVE_PATH = ".codex/skills/gdh-scan/SKILL.md";
 export const CURSOR_SCAN_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-scan/SKILL.md";
 export const LOCAL_PATH_HINTS_RELATIVE_PATH = ".gdh-state/local-paths.json";
-export const MCP_LAUNCHER_RELATIVE_PATH = ".gdh/bin/gdh-mcp.mjs";
+export const CODEX_PROJECT_CONFIG_RELATIVE_PATH = ".codex/config.toml";
 export const GDH_MCP_SERVER_NAME = "gdh";
+// Phase 17 UX-01: single source of truth for the `/gdh-status` preview-header
+// literal. The character between "dry-run)" and "not" is em-dash U+2014 (NOT
+// two hyphens). Centralizing here prevents silent drift across the 3
+// `/gdh-status` renderer bodies (Pitfall #5 three-adapter parity).
+const PREVIEW_HEADER_LITERAL = "Preview (dry-run) — not applied";
 const execFile = promisify(execFileCallback);
 export async function getSupportedAgentAdaptersStatus(targetPath, options = {}) {
     const includeUserLocal = options.includeUserLocal ?? true;
@@ -216,17 +221,18 @@ export async function inspectProjectLifecycleCompatibility(targetPath) {
         await inspectGuidanceUnitLifecycleSurface(resolvedTargetPath, projectConfig),
         inspectMcpManifestLifecycleSurface(resolvedTargetPath, projectConfig.mcp.enabled, adapterStatus),
         inspectCursorRuleLifecycleSurface(resolvedTargetPath, adapterStatus),
-        inspectMcpLauncherLifecycleSurface(resolvedTargetPath, projectConfig.mcp.enabled, adapterStatus),
         inspectRuntimeBridgeLifecycleSurface(resolvedTargetPath, bridgeStatus),
     ]);
 }
 export async function buildGdhStatusResult(targetPath) {
     const context = await buildAuthoringContext(targetPath);
     const projectLifecycle = await inspectProjectLifecycleCompatibility(targetPath);
+    const recoveryHints = resolveRecoveryHints(projectLifecycle.reasons);
     return {
         ...context.status,
         product: resolveGdhProductMetadata(),
         projectLifecycle,
+        recoveryHints,
     };
 }
 export async function createGsdSnapshot(targetPath, options = {}) {
@@ -471,9 +477,12 @@ export function renderClaudeStatusCommand(pinnedVersion) {
         "Follow this order:",
         "",
         `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field.`,
-        `2. Check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\`.`,
-        "3. Surface any degraded or unavailable capabilities.",
-        "4. Suggest the most productive next step based on current state.",
+        "2. Distinguish `blockingReasons` (needs /gdh-update or manual intervention) from `coupledReasons` (fixable via /gdh-migrate).",
+        `3. Check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\`.`,
+        `4. ${PREVIEW_HEADER_LITERAL} — migrate output at this step describes planned actions ("would delete …") not applied ones ("deleted").`,
+        "5. If status JSON `recoveryHints` array is non-empty, surface each entry's `{command, skillName}` pair.",
+        "6. Surface any degraded or unavailable capabilities.",
+        "7. Suggest the most productive next step based on current state.",
         "</process>",
         "",
         "<rules>",
@@ -512,7 +521,10 @@ export function renderCodexStatusSkill(pinnedVersion) {
         "Follow this order:",
         "",
         `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field`,
+        "- distinguish `blockingReasons` (needs /gdh-update or manual intervention) from `coupledReasons` (fixable via /gdh-migrate)",
         `- check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\``,
+        `- ${PREVIEW_HEADER_LITERAL} — migrate output describes planned actions ("would delete …") not applied ones ("deleted")`,
+        "- if status JSON `recoveryHints` array is non-empty, surface each entry's `{command, skillName}` pair",
         "- surface any degraded or unavailable capabilities",
         "- suggest the most productive next step based on current state",
         "</process>",
@@ -551,7 +563,10 @@ export function renderCursorStatusSkill(pinnedVersion) {
         "Follow this order:",
         "",
         `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field`,
+        "- distinguish `blockingReasons` (needs /gdh-update or manual intervention) from `coupledReasons` (fixable via /gdh-migrate)",
         `- check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\``,
+        `- ${PREVIEW_HEADER_LITERAL} — migrate output describes planned actions ("would delete …") not applied ones ("deleted")`,
+        "- if status JSON `recoveryHints` array is non-empty, surface each entry's `{command, skillName}` pair",
         "- surface any degraded or unavailable capabilities",
         "- suggest the most productive next step based on current state",
         "</process>",
@@ -695,10 +710,11 @@ export function renderClaudeMigrateCommand(pinnedVersion) {
         "<process>",
         "Follow this order:",
         "",
-        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations.`,
-        "2. Explain what each migration step will change and why.",
-        `3. Offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves.`,
-        `4. After apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded.`,
+        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations (this is a dry-run; the JSON \`mode\` field will be \`"preview"\`).`,
+        "2. Inspect `compatibility.blockingReasons` vs `compatibility.coupledReasons` — if `blockingReasons` is non-empty, STOP: `migrate --apply` cannot fix them (recommend `/gdh-update` or manual intervention per each reason's recovery hint). If only `coupledReasons` is non-empty, proceed.",
+        "3. Explain what each migration step will change and why (use \"would\" verb forms — \"would delete\", \"would create\", \"would refresh\").",
+        `4. Offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves — after apply, the JSON \`mode\` field becomes \`"applied"\` and verbs switch to past tense ("deleted", "created", "refreshed").`,
+        `5. After apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded.`,
         "</process>",
         "",
         "<rules>",
@@ -735,9 +751,10 @@ export function renderCodexMigrateSkill(pinnedVersion) {
         "<process>",
         "Follow this order:",
         "",
-        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations`,
-        "- explain what each migration step will change and why",
-        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves`,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations (this is a dry-run; the JSON \`mode\` field will be \`"preview"\`)`,
+        "- inspect `compatibility.blockingReasons` vs `compatibility.coupledReasons` — if `blockingReasons` is non-empty, STOP: `migrate --apply` cannot fix them (recommend `/gdh-update` or manual intervention per each reason's recovery hint); if only `coupledReasons` is non-empty, proceed",
+        "- explain what each migration step will change and why (use \"would\" verb forms — \"would delete\", \"would create\", \"would refresh\")",
+        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves — after apply, the JSON \`mode\` field becomes \`"applied"\` and verbs switch to past tense ("deleted", "created", "refreshed")`,
         `- after apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded`,
         "</process>",
         "",
@@ -773,9 +790,10 @@ export function renderCursorMigrateSkill(pinnedVersion) {
         "<process>",
         "Follow this order:",
         "",
-        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations`,
-        "- explain what each migration step will change and why",
-        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves`,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations (this is a dry-run; the JSON \`mode\` field will be \`"preview"\`)`,
+        "- inspect `compatibility.blockingReasons` vs `compatibility.coupledReasons` — if `blockingReasons` is non-empty, STOP: `migrate --apply` cannot fix them (recommend `/gdh-update` or manual intervention per each reason's recovery hint); if only `coupledReasons` is non-empty, proceed",
+        "- explain what each migration step will change and why (use \"would\" verb forms — \"would delete\", \"would create\", \"would refresh\")",
+        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves — after apply, the JSON \`mode\` field becomes \`"applied"\` and verbs switch to past tense ("deleted", "created", "refreshed")`,
         `- after apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded`,
         "</process>",
         "",
@@ -831,6 +849,7 @@ export function renderClaudeUpdateCommand(_pinnedVersion) {
         "2. Surface the planned version delta and re-bake action count to the human conversationally.",
         "3. Apply: run `npx -y @skillcap/gdh@latest self-update [version]` (omit `[version]` to apply against npm latest; forward whatever positional the user passed to `/gdh-update`).",
         "4. Verify: run `npx -y @skillcap/gdh@latest verify drift` to confirm every baked surface matches the new pin.",
+        "5. Read the `pendingMigration` field in the self-update stdout JSON. When non-null, narrate the chain to the human and run `npx -y @skillcap/gdh@latest migrate --apply` as the next action; when null, confirm no migration is pending and stop.",
         "</process>",
         "",
         "<rules>",
@@ -868,6 +887,7 @@ export function renderCodexUpdateSkill(_pinnedVersion) {
         "2. Surface the planned version delta and re-bake action count to the human conversationally.",
         "3. Apply: run `npx -y @skillcap/gdh@latest self-update [version]` (omit `[version]` to apply against npm latest; forward whatever positional the user passed to `/gdh-update`).",
         "4. Verify: run `npx -y @skillcap/gdh@latest verify drift` to confirm every baked surface matches the new pin.",
+        "5. Read the `pendingMigration` field in the self-update stdout JSON. When non-null, narrate the chain to the human and run `npx -y @skillcap/gdh@latest migrate --apply` as the next action; when null, confirm no migration is pending and stop.",
         "</process>",
         "",
         "<rules>",
@@ -903,6 +923,7 @@ export function renderCursorUpdateSkill(_pinnedVersion) {
         "2. Surface the planned version delta and re-bake action count to the human conversationally.",
         "3. Apply: run `npx -y @skillcap/gdh@latest self-update [version]` (omit `[version]` to apply against npm latest; forward whatever positional the user passed to `/gdh-update`).",
         "4. Verify: run `npx -y @skillcap/gdh@latest verify drift` to confirm every baked surface matches the new pin.",
+        "5. Read the `pendingMigration` field in the self-update stdout JSON. When non-null, narrate the chain to the human and run `npx -y @skillcap/gdh@latest migrate --apply` as the next action; when null, confirm no migration is pending and stop.",
         "</process>",
         "",
         "<rules>",
@@ -1257,34 +1278,26 @@ export function renderCursorVerifySkill(pinnedVersion) {
 async function inspectProjectMcpSupport(targetPath, options) {
     const projectConfig = await readProjectConfig(targetPath);
     const enabled = resolveProjectMcpEnabled(projectConfig);
-    const launcherContent = options.pinnedVersion === null
-        ? null
-        : renderManagedMcpLauncher(options.pinnedVersion);
     const managedMcpEntry = buildManagedMcpServerEntry({
-        targetPath,
-        integrationRootPath: options.integrationRootPath,
-        launcherPathForConfig: path.resolve(options.integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH),
+        pinnedVersion: options.pinnedVersion ?? "latest",
     });
-    const [projectFile, cursorFile, launcherSource, localPathHints] = await Promise.all([
+    const [projectFile, cursorFile, codexProjectContent, localPathHints] = await Promise.all([
         inspectJsonFile(path.join(options.integrationRootPath, PROJECT_MCP_RELATIVE_PATH)),
         inspectJsonFile(path.join(options.integrationRootPath, CURSOR_MCP_RELATIVE_PATH)),
-        fs.readFile(path.join(options.integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH), "utf8").catch(() => null),
+        fs.readFile(path.join(options.integrationRootPath, CODEX_PROJECT_CONFIG_RELATIVE_PATH), "utf8").catch(() => null),
         readLocalPathHints(options.integrationRootPath),
     ]);
-    const launcherBootstrap = await inspectLauncherBootstrap(localPathHints);
     const codexConfigPath = path.join(os.homedir(), ".codex/config.toml");
     const codexServerName = projectConfig === null ? null : createCodexServerName(projectConfig.projectKeySeed);
     return {
         enabled,
         integrationRootPath: options.integrationRootPath,
-        launcherContent,
         localPathHints,
-        launcherBootstrap,
-        launcherFile: inspectLauncherFile(launcherSource, launcherContent, enabled, launcherBootstrap),
         projectFile: inspectManagedMcpFile(projectFile, enabled, PROJECT_MCP_RELATIVE_PATH, "Claude project MCP config", managedMcpEntry),
         cursorFile: inspectManagedMcpFile(cursorFile, enabled, CURSOR_MCP_RELATIVE_PATH, "Cursor project MCP config", managedMcpEntry),
+        codexProjectFile: inspectManagedCodexProjectFile(codexProjectContent, enabled, options.pinnedVersion),
         codexRegistration: options.includeUserLocal
-            ? await inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, options.integrationRootPath)
+            ? await inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, options.integrationRootPath, options.pinnedVersion)
             : {
                 present: false,
                 state: "ready",
@@ -1361,71 +1374,52 @@ function inspectManagedMcpFile(file, enabled, relativePath, displayName, expecte
         summary: `${displayName} includes the managed \`${GDH_MCP_SERVER_NAME}\` MCP server entry.`,
     };
 }
-function inspectLauncherFile(launcherSource, expectedContent, enabled, bootstrap) {
+function inspectManagedCodexProjectFile(content, enabled, pinnedVersion) {
+    const relativePath = CODEX_PROJECT_CONFIG_RELATIVE_PATH;
     if (!enabled) {
         return {
-            present: launcherSource !== null,
+            present: content !== null,
             state: "ready",
-            summary: "The managed GDH MCP launcher is disabled for this target.",
+            summary: "Codex project MCP config is disabled for this target.",
         };
     }
-    if (expectedContent === null) {
+    if (pinnedVersion === null) {
         return {
-            present: launcherSource !== null,
+            present: content !== null,
             state: "missing",
-            summary: "The managed GDH MCP launcher is pending project onboard: no `gdh_version` is pinned yet, so there is no expected launcher content to compare against.",
+            summary: `Codex project MCP config cannot be validated yet: no \`gdh_version\` is pinned (run \`gdh setup\` or \`gdh migrate --apply\`).`,
         };
     }
-    if (launcherSource === null) {
+    if (content === null) {
         return {
             present: false,
             state: "missing",
-            summary: `The managed GDH MCP launcher is missing and should live at ${MCP_LAUNCHER_RELATIVE_PATH}.`,
+            summary: `Codex project MCP config is missing and should define the managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` entry at ${relativePath}.`,
         };
     }
-    if (launcherSource !== expectedContent) {
+    const existingSection = extractManagedCodexSection(content);
+    const expectedSection = renderManagedCodexProjectSection(pinnedVersion);
+    if (existingSection === null) {
         return {
             present: true,
             state: "misconfigured",
-            summary: "The managed GDH MCP launcher exists but no longer matches the expected launcher content.",
+            summary: `${relativePath} exists but does not contain the managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` section.`,
         };
     }
-    return {
-        present: true,
-        state: bootstrap.state,
-        summary: bootstrap.state === "ready"
-            ? "The managed GDH MCP launcher is present and can resolve the current GDH bootstrap path."
-            : bootstrap.summary,
-    };
-}
-async function inspectLauncherBootstrap(localPathHints) {
-    const envDevRepoPath = process.env["GDH_DEV_REPO"]?.trim() || null;
-    const effectiveDevRepoPath = envDevRepoPath ?? localPathHints.gdhDevRepoPath;
-    if (effectiveDevRepoPath !== null) {
-        const cliEntryPath = path.join(effectiveDevRepoPath, "packages/cli/dist/cli.js");
-        if (await fileExists(cliEntryPath)) {
-            return {
-                state: "ready",
-                summary: `The managed GDH MCP launcher will bootstrap from the current GDH checkout at ${effectiveDevRepoPath}.`,
-            };
-        }
+    if (existingSection !== expectedSection) {
         return {
+            present: true,
             state: "misconfigured",
-            summary: `The configured GDH checkout at ${effectiveDevRepoPath} does not contain packages/cli/dist/cli.js yet. Run \`corepack yarn build\` in the GDH checkout or update the local path hints.`,
-        };
-    }
-    if (await executableExistsOnPath("gdh")) {
-        return {
-            state: "ready",
-            summary: "The managed GDH MCP launcher can resolve `gdh` from PATH.",
+            summary: `${relativePath} managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` section does not match the expected GDH shape.`,
         };
     }
     return {
-        state: "missing",
-        summary: "The managed GDH MCP launcher cannot find `gdh` on PATH and no local GDH checkout hint is recorded. Run `gdh adapters install <target> --dev-repo <path-to-gdh>` or install `gdh` on PATH.",
+        present: true,
+        state: "ready",
+        summary: `Codex project MCP config includes the managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` entry.`,
     };
 }
-async function inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, integrationRootPath) {
+async function inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, integrationRootPath, pinnedVersion) {
     if (!enabled || codexServerName === null) {
         return {
             present: false,
@@ -1449,16 +1443,22 @@ async function inspectCodexRegistration(targetPath, enabled, codexServerName, co
             summary: `Codex does not yet have the expected user-local MCP registration \`${codexServerName}\` in ${codexConfigPath}.`,
         };
     }
-    const expectedLauncherPath = path.join(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH);
+    if (pinnedVersion === null) {
+        return {
+            present: true,
+            state: "misconfigured",
+            summary: `Codex MCP registration \`${codexServerName}\` exists but no \`gdh_version\` is pinned; cannot validate the expected npx invocation.`,
+        };
+    }
     if (!isMatchingCodexRegistration(registration, {
         targetPath,
         integrationRootPath,
-        launcherPath: expectedLauncherPath,
+        pinnedVersion,
     })) {
         return {
             present: true,
             state: "misconfigured",
-            summary: `Codex MCP registration \`${codexServerName}\` exists but does not point at the managed GDH launcher ${expectedLauncherPath}.`,
+            summary: `Codex MCP registration \`${codexServerName}\` exists but does not match the expected \`npx -y @skillcap/gdh@${pinnedVersion} mcp serve\` invocation.`,
         };
     }
     return {
@@ -1648,14 +1648,14 @@ async function inspectCodexAdapter(targetPath, guidance, projectMcp, pinnedVersi
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
-            kind: "launcher_file",
+            kind: "mcp_file",
             scope: "repo",
             targetPath: projectMcp.integrationRootPath,
-            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
-            present: projectMcp.launcherFile.present,
-            state: projectMcp.launcherFile.state,
-            summary: projectMcp.launcherFile.summary,
-            version: GDH_MCP_LAUNCHER_VERSION,
+            relativePath: CODEX_PROJECT_CONFIG_RELATIVE_PATH,
+            present: projectMcp.codexProjectFile.present,
+            state: projectMcp.codexProjectFile.state,
+            summary: projectMcp.codexProjectFile.summary,
+            version: null,
         }));
         if (options.includeUserLocal) {
             surfaces.push(createSurfaceStatus({
@@ -1763,15 +1763,6 @@ async function inspectClaudeAdapter(targetPath, guidance, projectMcp, pinnedVers
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
-            kind: "launcher_file",
-            scope: "repo",
-            targetPath: projectMcp.integrationRootPath,
-            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
-            present: projectMcp.launcherFile.present,
-            state: projectMcp.launcherFile.state,
-            summary: projectMcp.launcherFile.summary,
-            version: GDH_MCP_LAUNCHER_VERSION,
-        }), createSurfaceStatus({
             kind: "mcp_file",
             scope: "repo",
             targetPath: projectMcp.integrationRootPath,
@@ -1863,15 +1854,6 @@ async function inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVers
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
-            kind: "launcher_file",
-            scope: "repo",
-            targetPath: projectMcp.integrationRootPath,
-            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
-            present: projectMcp.launcherFile.present,
-            state: projectMcp.launcherFile.state,
-            summary: projectMcp.launcherFile.summary,
-            version: GDH_MCP_LAUNCHER_VERSION,
-        }), createSurfaceStatus({
             kind: "mcp_file",
             scope: "repo",
             targetPath: projectMcp.integrationRootPath,
@@ -1955,17 +1937,17 @@ async function planInstallActions(targetPath, adapters, requestedAgents, options
     const effectiveDevRepoPath = options.devRepoPath ?? resolveCurrentGdhInstall(import.meta.url).defaultDevRepoPath;
     if (options.user) {
         if (requestedAgents.includes("codex")) {
-            actions.push(...planCodexUserInstallActions(targetPath, projectMcp, options.integrationRootPath));
+            actions.push(...planCodexUserInstallActions(targetPath, projectMcp, options.integrationRootPath, options.pinnedVersion));
         }
         return dedupeInstallActions(actions);
     }
-    actions.push(...planSharedRepoInstallActions(targetPath, projectMcp, requestedAgents[0] ?? "claude", effectiveDevRepoPath, options.integrationRootPath));
+    actions.push(...planSharedRepoInstallActions(targetPath, projectMcp, requestedAgents[0] ?? "claude", effectiveDevRepoPath, options.integrationRootPath, options.pinnedVersion));
     for (const adapter of adapters) {
         if (!requestedAgents.includes(adapter.agent)) {
             continue;
         }
         if (adapter.agent === "codex") {
-            actions.push(...planCodexRepoInstallActions(targetPath, adapter, options.pinnedVersion));
+            actions.push(...planCodexRepoInstallActions(targetPath, adapter, options.pinnedVersion, projectMcp, options.integrationRootPath));
             continue;
         }
         if (adapter.agent === "claude") {
@@ -1978,27 +1960,11 @@ async function planInstallActions(targetPath, adapters, requestedAgents, options
     }
     return dedupeInstallActions(actions);
 }
-function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDevRepoPath, integrationRootPath) {
+function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDevRepoPath, integrationRootPath, pinnedVersion) {
     if (!projectMcp.enabled) {
         return [];
     }
     const actions = [];
-    if (projectMcp.launcherFile.state !== "ready") {
-        actions.push(createInstallAction({
-            agent,
-            kind: "write_file",
-            scope: "repo",
-            targetPath: integrationRootPath,
-            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
-            state: "planned",
-            mode: projectMcp.launcherFile.present ? "replace" : "create",
-            summary: projectMcp.launcherFile.present
-                ? "Replace the managed GDH MCP launcher with the current launcher content."
-                : "Create the managed GDH MCP launcher under .gdh/bin/.",
-            version: GDH_MCP_LAUNCHER_VERSION,
-            content: projectMcp.launcherContent,
-        }));
-    }
     if (projectMcp.projectFile.state !== "ready") {
         actions.push(createInstallAction({
             agent,
@@ -2011,11 +1977,7 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
             summary: projectMcp.projectFile.present
                 ? "Replace the managed `gdh` MCP entry in .mcp.json while preserving any non-GDH servers."
                 : "Create .mcp.json with the managed `gdh` MCP entry.",
-            content: renderManagedMcpConfig(path.join(integrationRootPath, PROJECT_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({
-                targetPath,
-                integrationRootPath,
-                launcherPathForConfig: path.resolve(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH),
-            })),
+            content: renderManagedMcpConfig(path.join(integrationRootPath, PROJECT_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({ pinnedVersion })),
         }));
     }
     if (projectMcp.cursorFile.state !== "ready") {
@@ -2030,11 +1992,7 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
             summary: projectMcp.cursorFile.present
                 ? "Replace the managed `gdh` MCP entry in .cursor/mcp.json while preserving any non-GDH servers."
                 : "Create .cursor/mcp.json with the managed `gdh` MCP entry.",
-            content: renderManagedMcpConfig(path.join(integrationRootPath, CURSOR_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({
-                targetPath,
-                integrationRootPath,
-                launcherPathForConfig: path.resolve(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH),
-            })),
+            content: renderManagedMcpConfig(path.join(integrationRootPath, CURSOR_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({ pinnedVersion })),
         }));
     }
     if (projectMcp.localPathHints.gdhDevRepoPath !== effectiveDevRepoPath) {
@@ -2104,8 +2062,8 @@ function agentLabel(agent) {
             return "Cursor";
     }
 }
-function planCodexRepoInstallActions(targetPath, adapter, pinnedVersion) {
-    return [
+function planCodexRepoInstallActions(targetPath, adapter, pinnedVersion, projectMcp, integrationRootPath) {
+    const actions = [
         planSkillInstallAction("codex", targetPath, adapter, CODEX_ONBOARD_SKILL_RELATIVE_PATH, renderCodexOnboardSkill, "gdh-onboard", pinnedVersion),
         planSkillInstallAction("codex", targetPath, adapter, CODEX_STATUS_SKILL_RELATIVE_PATH, renderCodexStatusSkill, "gdh-status", pinnedVersion),
         planSkillInstallAction("codex", targetPath, adapter, CODEX_MIGRATE_SKILL_RELATIVE_PATH, renderCodexMigrateSkill, "gdh-migrate", pinnedVersion),
@@ -2115,18 +2073,42 @@ function planCodexRepoInstallActions(targetPath, adapter, pinnedVersion) {
         planSkillInstallAction("codex", targetPath, adapter, CODEX_VERIFY_SKILL_RELATIVE_PATH, renderCodexVerifySkill, "gdh-verify", pinnedVersion),
         planSkillInstallAction("codex", targetPath, adapter, CODEX_SCAN_SKILL_RELATIVE_PATH, renderCodexScanSkill, "gdh-scan", pinnedVersion),
     ];
+    if (projectMcp.enabled && projectMcp.codexProjectFile.state !== "ready") {
+        const absolutePath = path.join(integrationRootPath, CODEX_PROJECT_CONFIG_RELATIVE_PATH);
+        const existingContent = fsSync.existsSync(absolutePath)
+            ? fsSync.readFileSync(absolutePath, "utf8")
+            : null;
+        actions.push(createInstallAction({
+            agent: "codex",
+            kind: "write_file",
+            scope: "repo",
+            targetPath: integrationRootPath,
+            relativePath: CODEX_PROJECT_CONFIG_RELATIVE_PATH,
+            state: "planned",
+            mode: projectMcp.codexProjectFile.present ? "replace" : "create",
+            summary: projectMcp.codexProjectFile.present
+                ? `Replace the managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` section in .codex/config.toml while preserving any non-GDH content.`
+                : `Create .codex/config.toml with the managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` entry so Codex can discover the project MCP server without a user-global registration.`,
+            content: renderManagedCodexProjectConfig(existingContent, pinnedVersion),
+        }));
+    }
+    return actions;
 }
-function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath) {
+function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath, pinnedVersion) {
     if (!projectMcp.enabled || projectMcp.codexServerName === null) {
         return [];
     }
-    const expectedLauncherPath = path.join(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH);
-    const codexArgs = buildManagedLauncherInvocationArgs({
-        targetPath,
-        integrationRootPath,
-        launcherPath: expectedLauncherPath,
-        useAbsoluteTargetPath: true,
-    });
+    const resolvedTargetPath = path.resolve(targetPath);
+    const resolvedIntegrationRootPath = path.resolve(integrationRootPath);
+    const codexCommandArgs = [
+        "-y",
+        `@skillcap/gdh@${pinnedVersion}`,
+        "mcp",
+        "serve",
+    ];
+    if (resolvedTargetPath !== resolvedIntegrationRootPath) {
+        codexCommandArgs.push("--target", resolvedTargetPath);
+    }
     const actions = [];
     if (projectMcp.codexRegistration.present) {
         actions.push(createInstallAction({
@@ -2138,7 +2120,7 @@ function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath
             absolutePath: projectMcp.codexConfigPath,
             state: "planned",
             mode: "replace",
-            summary: `Remove the existing Codex MCP registration \`${projectMcp.codexServerName}\` before re-registering it with the managed GDH launcher.`,
+            summary: `Remove the existing Codex MCP registration \`${projectMcp.codexServerName}\` before re-registering it with the managed GDH npx invocation.`,
             command: ["codex", "mcp", "remove", projectMcp.codexServerName],
         }));
     }
@@ -2151,15 +2133,15 @@ function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath
         absolutePath: projectMcp.codexConfigPath,
         state: "planned",
         mode: projectMcp.codexRegistration.present ? "replace" : "create",
-        summary: `Register the managed GDH launcher with Codex as \`${projectMcp.codexServerName}\`.`,
+        summary: `Register the managed GDH MCP server with Codex as \`${projectMcp.codexServerName}\` via pinned npx invocation.`,
         command: [
             "codex",
             "mcp",
             "add",
             projectMcp.codexServerName,
             "--",
-            "node",
-            ...codexArgs,
+            "npx",
+            ...codexCommandArgs,
         ],
     }));
     return actions;
@@ -2377,64 +2359,11 @@ function resolveProjectMcpEnabled(projectConfig) {
 function createCodexServerName(projectKeySeed) {
     return `gdh-${projectKeySeed}`;
 }
-export function renderManagedMcpLauncher(pinnedVersion) {
-    return [
-        "#!/usr/bin/env node",
-        `// GDH MCP launcher v${GDH_MCP_LAUNCHER_VERSION}`,
-        'import fs from "node:fs";',
-        'import path from "node:path";',
-        'import { spawnSync } from "node:child_process";',
-        'import { fileURLToPath } from "node:url";',
-        "",
-        "const launcherPath = fileURLToPath(import.meta.url);",
-        'const integrationRootPath = path.resolve(path.dirname(launcherPath), "../..");',
-        'const targetOptionIndex = process.argv.indexOf("--target");',
-        "const configuredTargetPath =",
-        '  targetOptionIndex >= 0 && typeof process.argv[targetOptionIndex + 1] === "string"',
-        "    ? process.argv[targetOptionIndex + 1]",
-        "    : null;",
-        "const targetPath = configuredTargetPath",
-        "  ? path.resolve(integrationRootPath, configuredTargetPath)",
-        "  : integrationRootPath;",
-        'const hintsPath = path.join(integrationRootPath, ".gdh-state", "local-paths.json");',
-        "",
-        "let gdhDevRepoPath = null;",
-        "try {",
-        '  const raw = fs.readFileSync(hintsPath, "utf8");',
-        "  const parsed = JSON.parse(raw);",
-        '  if (typeof parsed.gdhDevRepoPath === "string" && parsed.gdhDevRepoPath.length > 0) {',
-        "    gdhDevRepoPath = parsed.gdhDevRepoPath;",
-        "  }",
-        "} catch {}",
-        "",
-        "const effectiveDevRepoPath = process.env.GDH_DEV_REPO?.trim() || gdhDevRepoPath;",
-        "if (effectiveDevRepoPath) {",
-        '  const devCliEntryPath = path.join(effectiveDevRepoPath, "packages/cli/dist/cli.js");',
-        "  if (fs.existsSync(devCliEntryPath)) {",
-        '    const result = spawnSync(process.execPath, [devCliEntryPath, "mcp", "serve", "--target", targetPath], { stdio: "inherit" });',
-        "    process.exit(result.status ?? 1);",
-        "  }",
-        "}",
-        "",
-        `const result = spawnSync("npx", ["-y", "@skillcap/gdh@${pinnedVersion}", "mcp", "serve", "--target", targetPath], { stdio: "inherit", cwd: targetPath });`,
-        'if (result.error && result.error.code === "ENOENT") {',
-        `  console.error("GDH MCP launcher could not launch npx for @skillcap/gdh@${pinnedVersion}. Ensure Node.js 20+ is installed (npx ships with Node), or configure the contributor dev escape hatch via the GDH_DEV_REPO env var or .gdh-state/local-paths.json gdhDevRepoPath.");`,
-        "  process.exit(1);",
-        "}",
-        "process.exit(result.status ?? 1);",
-        "",
-    ].join("\n");
-}
 function buildManagedMcpServerEntry(input) {
     return {
         type: "stdio",
-        command: "node",
-        args: buildManagedLauncherInvocationArgs({
-            targetPath: input.targetPath,
-            integrationRootPath: input.integrationRootPath,
-            launcherPath: input.launcherPathForConfig,
-            useAbsoluteTargetPath: true,
-        }),
+        command: "npx",
+        args: ["-y", `@skillcap/gdh@${input.pinnedVersion}`, "mcp", "serve"],
     };
 }
 function getManagedMcpServerEntry(jsonObject) {
@@ -2475,6 +2404,64 @@ function readExistingMcpConfig(absolutePath) {
         return {};
     }
 }
+// Renders the managed [mcp_servers.gdh] section for Codex project-local
+// config. The section body is line-based (no TOML parser) — preserves any
+// other content the user has in the file via regex replacement of the
+// bracketed header span. Exotic forms (inline-table `mcp_servers.gdh = {...}`
+// or dotted-key `mcp_servers.gdh.command = "..."`) are not detected; users
+// with those forms may end up with a duplicate and must migrate manually.
+export function renderManagedCodexProjectSection(pinnedVersion) {
+    return [
+        "[mcp_servers.gdh]",
+        'command = "npx"',
+        `args = ["-y", "@skillcap/gdh@${pinnedVersion}", "mcp", "serve"]`,
+    ].join("\n");
+}
+export function renderManagedCodexProjectConfig(existingContent, pinnedVersion) {
+    const section = renderManagedCodexProjectSection(pinnedVersion);
+    if (existingContent === null || existingContent.trim() === "") {
+        return `${section}\n`;
+    }
+    const lines = existingContent.split("\n");
+    const sectionStart = lines.findIndex((line) => /^\[mcp_servers\.gdh\]\s*$/.test(line));
+    if (sectionStart === -1) {
+        const trailingNewline = existingContent.endsWith("\n") ? "" : "\n";
+        const separator = existingContent.length > 0 ? "\n" : "";
+        return `${existingContent}${trailingNewline}${separator}${section}\n`;
+    }
+    let sectionEnd = lines.length;
+    for (let i = sectionStart + 1; i < lines.length; i++) {
+        if (/^\[/.test(lines[i] ?? "")) {
+            sectionEnd = i;
+            break;
+        }
+    }
+    const before = lines.slice(0, sectionStart).join("\n");
+    const afterLines = lines.slice(sectionEnd);
+    const after = afterLines.join("\n");
+    const beforeJoin = before.length > 0 ? `${before}\n` : "";
+    const afterNonEmpty = after.replace(/^\s+/, "");
+    const afterJoin = afterNonEmpty.length > 0 ? `\n\n${afterNonEmpty}` : "\n";
+    return `${beforeJoin}${section}${afterJoin}`;
+}
+function extractManagedCodexSection(content) {
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => /^\[mcp_servers\.gdh\]\s*$/.test(line));
+    if (start === -1) {
+        return null;
+    }
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^\[/.test(lines[i] ?? "")) {
+            end = i;
+            break;
+        }
+    }
+    return lines
+        .slice(start, end)
+        .join("\n")
+        .replace(/\s+$/, "");
+}
 function normalizeJson(value) {
     if (Array.isArray(value)) {
         return value.map((entry) => normalizeJson(entry));
@@ -2614,14 +2601,19 @@ async function listCodexMcpServers() {
     }
 }
 function isMatchingCodexRegistration(registration, input) {
-    const expectedArgs = buildManagedLauncherInvocationArgs({
-        targetPath: input.targetPath,
-        integrationRootPath: input.integrationRootPath,
-        launcherPath: input.launcherPath,
-        useAbsoluteTargetPath: true,
-    });
+    const resolvedTargetPath = path.resolve(input.targetPath);
+    const resolvedIntegrationRootPath = path.resolve(input.integrationRootPath);
+    const expectedArgs = [
+        "-y",
+        `@skillcap/gdh@${input.pinnedVersion}`,
+        "mcp",
+        "serve",
+    ];
+    if (resolvedTargetPath !== resolvedIntegrationRootPath) {
+        expectedArgs.push("--target", resolvedTargetPath);
+    }
     return (registration.transport?.type === "stdio" &&
-        registration.transport.command === "node" &&
+        registration.transport.command === "npx" &&
         JSON.stringify(registration.transport.args ?? []) === JSON.stringify(expectedArgs));
 }
 async function inspectProjectConfigLifecycleSurface(targetPath) {
@@ -3054,60 +3046,6 @@ function inspectCursorRuleLifecycleSurface(targetPath, adapterStatus) {
         },
     });
 }
-function inspectMcpLauncherLifecycleSurface(targetPath, mcpEnabled, adapterStatus) {
-    if (!mcpEnabled) {
-        return createLifecycleSurfaceStatus({
-            surface: "mcp_launcher",
-            management: "managed",
-            state: "compatible",
-            summary: "Project-scoped MCP launcher is not required while MCP is disabled.",
-            reasons: [],
-            probes: [],
-            action: null,
-        });
-    }
-    const launcherSurface = findAdapterSurface(adapterStatus, "claude", "launcher_file") ??
-        findAdapterSurface(adapterStatus, "cursor", "launcher_file") ??
-        findAdapterSurface(adapterStatus, "codex", "launcher_file");
-    const probes = launcherSurface === null
-        ? []
-        : [
-            createVersionProbe({
-                targetPath,
-                relativePath: launcherSurface.relativePath ?? MCP_LAUNCHER_RELATIVE_PATH,
-                present: launcherSurface.present,
-                expectedVersion: GDH_MCP_LAUNCHER_VERSION,
-                detectedVersion: launcherSurface.present ? launcherSurface.version : null,
-            }),
-        ];
-    if (launcherSurface?.state === "ready") {
-        return createLifecycleSurfaceStatus({
-            surface: "mcp_launcher",
-            management: "managed",
-            state: "compatible",
-            summary: "Managed MCP launcher file matches the current GDH version.",
-            reasons: [],
-            probes,
-            action: null,
-        });
-    }
-    return createLifecycleSurfaceStatus({
-        surface: "mcp_launcher",
-        management: "managed",
-        state: launcherSurface?.present ? "migration_available" : "migration_needed",
-        summary: "Managed MCP launcher file needs to be created or refreshed through the adapter install flow.",
-        reasons: launcherSurface?.present
-            ? ["mcp_launcher_misconfigured"]
-            : ["mcp_launcher_missing"],
-        probes,
-        action: {
-            kind: "run_repair",
-            summary: "Run GDH migrate or adapters install to refresh the managed MCP launcher file.",
-            command: ["gdh", "adapters", "install", targetPath],
-            autoApplicable: true,
-        },
-    });
-}
 function inspectRuntimeBridgeLifecycleSurface(targetPath, bridgeStatus) {
     const probes = bridgeStatus.managedArtifacts.map((artifact) => createVersionProbe({
         targetPath,
@@ -3366,14 +3304,35 @@ async function inspectYamlSurfaceDirectory(input) {
 }
 function summarizeProjectLifecycleCompatibility(targetPath, surfaces) {
     const state = resolveProjectLifecycleState(surfaces);
-    const reasons = dedupe(surfaces.flatMap((surface) => surface.reasons).filter((reason) => reason.length > 0));
-    return {
+    const blocking = [];
+    const coupled = [];
+    for (const surface of surfaces) {
+        const bucket = surface.state === "migration_blocked" || surface.state === "compatibility_degraded"
+            ? blocking
+            : surface.state === "migration_needed" || surface.state === "migration_available"
+                ? coupled
+                : null;
+        if (bucket) {
+            for (const reason of surface.reasons) {
+                if (reason.length > 0)
+                    bucket.push(reason);
+            }
+        }
+    }
+    const blockingReasons = dedupe(blocking);
+    const coupledReasons = dedupe(coupled.filter((r) => !blockingReasons.includes(r)));
+    const reasons = [...blockingReasons, ...coupledReasons];
+    const result = {
         targetPath,
         state,
         summary: summarizeProjectLifecycleState(state, surfaces),
         reasons,
+        blockingReasons,
+        coupledReasons,
         surfaces,
     };
+    assertProjectLifecycleCompatibilityInvariant(result);
+    return result;
 }
 function resolveProjectLifecycleState(surfaces) {
     if (surfaces.some((surface) => surface.state === "migration_blocked")) {
@@ -3501,4 +3460,9 @@ function normalizeChangedFiles(files) {
 export { bumpAndRebakePin, } from "./self-update-mechanics.js";
 export { CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH } from "./claude-update-hook-render.js";
 export { CLAUDE_STATUSLINE_RELATIVE_PATH } from "./claude-statusline-render.js";
+// Internal aggregator exposed for Wave 0 unit tests
+// (packages/adapters/src/lifecycle-compatibility.test.ts). Callers outside this
+// package should continue to use inspectProjectLifecycleCompatibility, which
+// wraps this function with filesystem probing and surface discovery.
+export { summarizeProjectLifecycleCompatibility };
 //# sourceMappingURL=index.js.map