@orchid-labs/pluxx 0.1.10 → 0.1.12

package/dist/index.js

@@ -7461,6 +7461,99 @@ var HooksSchema = external_exports.object({
   beforeTabFileRead: external_exports.array(HookEntrySchema).optional(),
   afterTabFileEdit: external_exports.array(HookEntrySchema).optional()
 }).catchall(external_exports.array(HookEntrySchema));
+var RuntimeReadinessRefreshSchema = external_exports.object({
+  command: external_exports.string(),
+  timeoutMs: external_exports.number().int().positive().default(1e4),
+  detached: external_exports.boolean().default(true)
+});
+var RuntimeReadinessDependencySchema = external_exports.object({
+  id: external_exports.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Use lowercase kebab-case for readiness dependency ids"),
+  kind: external_exports.enum(["status-file"]).default("status-file"),
+  path: external_exports.string(),
+  format: external_exports.enum(["json"]).default("json"),
+  statusField: external_exports.string().default("status"),
+  readyValues: external_exports.array(external_exports.string()).default(["succeeded"]),
+  pendingValues: external_exports.array(external_exports.string()).default(["running"]),
+  failedValues: external_exports.array(external_exports.string()).default(["failed"]),
+  refresh: RuntimeReadinessRefreshSchema,
+  description: external_exports.string().optional()
+}).superRefine((dependency, ctx) => {
+  const ready = new Set(dependency.readyValues);
+  const pending = new Set(dependency.pendingValues);
+  const failed = new Set(dependency.failedValues);
+  const overlap = [
+    ...ready,
+    ...pending
+  ].filter(
+    (value, index, values) => values.indexOf(value) === index && (ready.has(value) ? 1 : 0) + (pending.has(value) ? 1 : 0) + (failed.has(value) ? 1 : 0) > 1
+  );
+  if (overlap.length > 0) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["readyValues"],
+      message: `Readiness dependency values must not overlap across ready/pending/failed buckets: ${overlap.join(", ")}`
+    });
+  }
+});
+var RuntimeReadinessGateSchema = external_exports.object({
+  dependency: external_exports.string(),
+  applyTo: external_exports.array(external_exports.enum(["mcp-tools", "skills", "commands"])).nonempty().default(["mcp-tools"]),
+  tools: external_exports.array(external_exports.string()).nonempty().optional(),
+  skills: external_exports.array(external_exports.string()).nonempty().optional(),
+  commands: external_exports.array(external_exports.string()).nonempty().optional(),
+  timeoutMs: external_exports.number().int().positive().default(15e3),
+  pollMs: external_exports.number().int().positive().default(500),
+  onTimeout: external_exports.enum(["continue", "warn", "fail"]).default("warn"),
+  message: external_exports.string().optional()
+}).superRefine((gate, ctx) => {
+  if (gate.tools && !gate.applyTo.includes("mcp-tools")) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["tools"],
+      message: 'Runtime readiness gate.tools requires applyTo to include "mcp-tools".'
+    });
+  }
+  if (gate.skills && !gate.applyTo.includes("skills")) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["skills"],
+      message: 'Runtime readiness gate.skills requires applyTo to include "skills".'
+    });
+  }
+  if (gate.commands && !gate.applyTo.includes("commands")) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["commands"],
+      message: 'Runtime readiness gate.commands requires applyTo to include "commands".'
+    });
+  }
+});
+var RuntimeReadinessSchema = external_exports.object({
+  dependencies: external_exports.array(RuntimeReadinessDependencySchema).default([]),
+  gates: external_exports.array(RuntimeReadinessGateSchema).default([])
+}).superRefine((config, ctx) => {
+  const seenDependencyIds = /* @__PURE__ */ new Set();
+  for (const [index, dependency] of config.dependencies.entries()) {
+    if (seenDependencyIds.has(dependency.id)) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["dependencies", index, "id"],
+        message: `Runtime readiness dependency id "${dependency.id}" is duplicated.`
+      });
+    }
+    seenDependencyIds.add(dependency.id);
+  }
+  const dependencyIds = new Set(config.dependencies.map((dependency) => dependency.id));
+  for (const [index, gate] of config.gates.entries()) {
+    if (!dependencyIds.has(gate.dependency)) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["gates", index, "dependency"],
+        message: `Runtime readiness gate references unknown dependency "${gate.dependency}".`
+      });
+    }
+  }
+});
 var BrandSchema = external_exports.object({
   displayName: external_exports.string(),
   shortDescription: external_exports.string().optional(),
@@ -7590,6 +7683,8 @@ var PluginConfigSchema = external_exports.object({
   instructions: external_exports.string().optional(),
   // MCP servers
   mcp: external_exports.record(external_exports.string(), McpServerSchema).optional(),
+  // Runtime readiness gates
+  readiness: RuntimeReadinessSchema.optional(),
   // Hooks
   hooks: HooksSchema.optional(),
   // Scripts (copied to all targets)
@@ -7616,6 +7711,37 @@ var PLUXX_COMPILER_BUCKETS = [
   "distribution"
 ];
 function getPluginCompilerBuckets(config) {
+  const runtimeMcpSurface = {
+    servers: config.mcp,
+    hasRuntimeAuth: Object.values(config.mcp ?? {}).some((server) => server.auth?.type !== "none" && server.auth !== void 0)
+  };
+  const runtimeReadinessSurface = {
+    config: config.readiness
+  };
+  const runtimePayloadSurface = {
+    scriptsPath: config.scripts,
+    assetsPath: config.assets,
+    passthroughPaths: config.passthrough ?? []
+  };
+  const distributionBrandingSurface = {
+    identity: {
+      name: config.name,
+      version: config.version,
+      description: config.description,
+      author: config.author,
+      repository: config.repository,
+      license: config.license,
+      keywords: config.keywords
+    },
+    brand: config.brand
+  };
+  const distributionInstallSurface = {
+    userConfig: config.userConfig ?? []
+  };
+  const distributionOutputSurface = {
+    targets: config.targets,
+    outDir: config.outDir
+  };
   return {
     instructions: {
       path: config.instructions
@@ -7636,25 +7762,24 @@ function getPluginCompilerBuckets(config) {
       rules: config.permissions
     },
     runtime: {
-      mcp: config.mcp,
-      scriptsPath: config.scripts,
-      assetsPath: config.assets,
-      passthroughPaths: config.passthrough ?? []
+      mcp: runtimeMcpSurface.servers,
+      readiness: runtimeReadinessSurface.config,
+      scriptsPath: runtimePayloadSurface.scriptsPath,
+      assetsPath: runtimePayloadSurface.assetsPath,
+      passthroughPaths: runtimePayloadSurface.passthroughPaths,
+      mcpSurface: runtimeMcpSurface,
+      readinessSurface: runtimeReadinessSurface,
+      payloadSurface: runtimePayloadSurface
     },
     distribution: {
-      identity: {
-        name: config.name,
-        version: config.version,
-        description: config.description,
-        author: config.author,
-        repository: config.repository,
-        license: config.license,
-        keywords: config.keywords
-      },
-      brand: config.brand,
-      userConfig: config.userConfig ?? [],
-      targets: config.targets,
-      outDir: config.outDir
+      identity: distributionBrandingSurface.identity,
+      brand: distributionBrandingSurface.brand,
+      userConfig: distributionInstallSurface.userConfig,
+      targets: distributionOutputSurface.targets,
+      outDir: distributionOutputSurface.outDir,
+      brandingSurface: distributionBrandingSurface,
+      installSurface: distributionInstallSurface,
+      outputSurface: distributionOutputSurface
     }
   };
 }
@@ -7671,7 +7796,7 @@ function getConfiguredCompilerBuckets(config) {
   );
   if (hasPermissions) configured.push("permissions");
   const hasRuntime = Boolean(
-    buckets.runtime.mcp && Object.keys(buckets.runtime.mcp).length > 0 || buckets.runtime.scriptsPath || buckets.runtime.assetsPath || buckets.runtime.passthroughPaths.length > 0
+    buckets.runtime.mcp && Object.keys(buckets.runtime.mcp).length > 0 || buckets.runtime.readiness && (buckets.runtime.readiness.dependencies.length > 0 || buckets.runtime.readiness.gates.length > 0) || buckets.runtime.scriptsPath || buckets.runtime.assetsPath || buckets.runtime.passthroughPaths.length > 0
   );
   if (hasRuntime) configured.push("runtime");
   configured.push("distribution");
@@ -7683,6 +7808,139 @@ function definePlugin(config) {
   return PluginConfigSchema.parse(config);
 }
 
+// src/runtime-readiness-registry.ts
+function getEnabledRuntimeReadinessBindings(capability, plan) {
+  return capability.bindings.filter((binding) => {
+    switch (binding.gate) {
+      case "session-start":
+        return plan.needsSessionStart;
+      case "mcp-gate":
+        return plan.needsMcpGate;
+      case "prompt-gate":
+        return plan.needsPromptGate;
+    }
+  });
+}
+var NAMED_PROMPT_TARGET_NOTE = "Named `skills` / `commands` readiness targets currently translate through prompt-entry gating with best-effort matching because the core four do not share one exact per-skill or per-command runtime interception surface.";
+var CODEX_EXTERNAL_NOTE = "Codex readiness currently translates into generated hook/config guidance rather than an enforced plugin-bundled runtime surface.";
+function getRuntimeReadinessNamedPromptTargetNote() {
+  return NAMED_PROMPT_TARGET_NOTE;
+}
+function getRuntimeReadinessExternalConfigNote() {
+  return CODEX_EXTERNAL_NOTE;
+}
+function getRuntimeReadinessCapability(platform, pluginRootVar = "PLUGIN_ROOT") {
+  switch (platform) {
+    case "claude-code":
+      return {
+        platform,
+        delivery: "bundled-hooks",
+        bundleEnforced: true,
+        namedPromptTargetScope: "best-effort",
+        scriptPath: "hooks/pluxx-readiness.mjs",
+        companionArtifacts: [],
+        bindings: [
+          {
+            gate: "session-start",
+            event: "SessionStart",
+            command: `node \${${pluginRootVar}}/hooks/pluxx-readiness.mjs session-start`
+          },
+          {
+            gate: "mcp-gate",
+            event: "PreToolUse",
+            matcher: "MCP",
+            command: `node \${${pluginRootVar}}/hooks/pluxx-readiness.mjs mcp-gate`
+          },
+          {
+            gate: "prompt-gate",
+            event: "UserPromptSubmit",
+            command: `node \${${pluginRootVar}}/hooks/pluxx-readiness.mjs prompt-gate`
+          }
+        ]
+      };
+    case "cursor":
+      return {
+        platform,
+        delivery: "bundled-hooks",
+        bundleEnforced: true,
+        namedPromptTargetScope: "best-effort",
+        scriptPath: "hooks/pluxx-readiness.mjs",
+        companionArtifacts: [],
+        bindings: [
+          {
+            gate: "session-start",
+            event: "sessionStart",
+            command: "node ./hooks/pluxx-readiness.mjs session-start"
+          },
+          {
+            gate: "mcp-gate",
+            event: "beforeMCPExecution",
+            command: "node ./hooks/pluxx-readiness.mjs mcp-gate"
+          },
+          {
+            gate: "prompt-gate",
+            event: "beforeSubmitPrompt",
+            command: "node ./hooks/pluxx-readiness.mjs prompt-gate"
+          }
+        ]
+      };
+    case "codex":
+      return {
+        platform,
+        delivery: "generated-guidance",
+        bundleEnforced: false,
+        namedPromptTargetScope: "best-effort",
+        scriptPath: ".codex/pluxx-readiness.mjs",
+        companionArtifacts: [".codex/readiness.generated.json", ".codex/hooks.generated.json"],
+        bindings: [
+          {
+            gate: "session-start",
+            event: "SessionStart",
+            command: "node ./.codex/pluxx-readiness.mjs session-start"
+          },
+          {
+            gate: "mcp-gate",
+            event: "PreToolUse",
+            matcher: "MCP",
+            command: "node ./.codex/pluxx-readiness.mjs mcp-gate"
+          },
+          {
+            gate: "prompt-gate",
+            event: "UserPromptSubmit",
+            command: "node ./.codex/pluxx-readiness.mjs prompt-gate"
+          }
+        ],
+        notes: CODEX_EXTERNAL_NOTE
+      };
+    case "opencode":
+      return {
+        platform,
+        delivery: "runtime-callbacks",
+        bundleEnforced: true,
+        namedPromptTargetScope: "best-effort",
+        scriptPath: "runtime/pluxx-readiness.mjs",
+        companionArtifacts: [],
+        bindings: [
+          {
+            gate: "session-start",
+            event: "session.created",
+            command: "node ./runtime/pluxx-readiness.mjs session-start"
+          },
+          {
+            gate: "mcp-gate",
+            event: "tool.execute.before",
+            command: "node ./runtime/pluxx-readiness.mjs mcp-gate"
+          },
+          {
+            gate: "prompt-gate",
+            event: "chat.message",
+            command: "node ./runtime/pluxx-readiness.mjs prompt-gate"
+          }
+        ]
+      };
+  }
+}
+
 // src/validation/platform-rules.ts
 var STANDARD_SKILL_FRONTMATTER = [
   "name",
@@ -8456,7 +8714,7 @@ var CORE_FOUR_PRIMITIVE_CAPABILITIES = {
       runtime: {
         mode: "preserve",
         nativeSurfaces: [".mcp.json", ".app.json", ".codex/config.toml", "scripts/", "assets/"],
-        notes: "Bundle-local MCP config exists, but active MCP state also lives in config.toml."
+        notes: `Bundle-local MCP config exists, but active MCP state also lives in config.toml. ${getRuntimeReadinessExternalConfigNote()}`
       },
       distribution: {
         mode: "preserve",
@@ -8630,6 +8888,57 @@ function renderCompatibilityMatrixMarkdown() {
 `;
 }
 
+// src/runtime-script-contract.ts
+var INSTALLER_OWNED_CHECK_ENV_PATH = "scripts/check-env.sh";
+var RUNTIME_SCRIPT_ROLE_PATHS = {
+  "install-validation": INSTALLER_OWNED_CHECK_ENV_PATH,
+  "runtime-env": "scripts/load-env.sh",
+  "runtime-bootstrap": "scripts/bootstrap-runtime.sh",
+  "runtime-entrypoint": "scripts/start-mcp.sh"
+};
+var PORTABLE_RUNTIME_SCRIPT_ROLES = [
+  RUNTIME_SCRIPT_ROLE_PATHS["runtime-env"],
+  RUNTIME_SCRIPT_ROLE_PATHS["runtime-bootstrap"],
+  RUNTIME_SCRIPT_ROLE_PATHS["runtime-entrypoint"]
+];
+function getPortableRuntimeScriptRoleGuidance() {
+  return `Use separate runtime scripts such as ${PORTABLE_RUNTIME_SCRIPT_ROLES.join(", ")} instead.`;
+}
+function getRuntimeScriptRoleForPath(path) {
+  const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
+  for (const [role, rolePath] of Object.entries(RUNTIME_SCRIPT_ROLE_PATHS)) {
+    if (normalized === rolePath) return role;
+  }
+  return null;
+}
+function getRuntimeScriptPathsForRoles(roles) {
+  return roles.map((role) => RUNTIME_SCRIPT_ROLE_PATHS[role]);
+}
+function formatRuntimeScriptRoles(roles) {
+  return getRuntimeScriptPathsForRoles(roles).join(", ");
+}
+function referencesInstallerOwnedCheckEnv(command) {
+  return command.includes("check-env.sh");
+}
+function getInstallerOwnedCheckEnvRuntimeMessage(serverName) {
+  return `MCP server "${serverName}" references ${INSTALLER_OWNED_CHECK_ENV_PATH} in its runtime command or args. Pluxx install rewrites that file into a no-op after userConfig materialization, so runtime startup must not depend on it. ${getPortableRuntimeScriptRoleGuidance()}`;
+}
+function getInstallerOwnedCheckEnvHookMessage(eventName) {
+  return `Hook "${eventName}" references ${INSTALLER_OWNED_CHECK_ENV_PATH} as part of a broader runtime command. Treat that script as installer-owned and install-time only, because local installs may rewrite it into a no-op after required config is materialized.`;
+}
+function getConsumerEnvScriptMissingDetail() {
+  return `This bundle does not ship a ${INSTALLER_OWNED_CHECK_ENV_PATH} file.`;
+}
+function getConsumerEnvScriptActiveDetail() {
+  return `This bundle still runs ${INSTALLER_OWNED_CHECK_ENV_PATH}, which usually means required config was not materialized into the installed plugin.`;
+}
+function getConsumerRuntimeScriptRolesDetail(roles) {
+  if (roles.length === 0) {
+    return "This bundle does not include any of the known portable runtime script-role files.";
+  }
+  return `This bundle includes the following known runtime script-role files: ${formatRuntimeScriptRoles(roles)}.`;
+}
+
 // src/compiler-intent.ts
 import { existsSync, readFileSync } from "fs";
 import { resolve } from "path";
@@ -9241,6 +9550,14 @@ NODE
 function hasInstallerUserConfig(config, platform) {
   return collectUserConfigEntries(config, [platform]).length > 0;
 }
+function renderInstallerRuntimeBootstrapSnippet(installDirVariable) {
+  return `
+if [[ -f "${installDirVariable}/scripts/bootstrap-runtime.sh" ]]; then
+  echo "Preparing local plugin runtime dependencies..."
+  bash "${installDirVariable}/scripts/bootstrap-runtime.sh"
+fi
+`;
+}
 function renderInstallClaudeCodeScript(config) {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -9305,6 +9622,7 @@ mkdir -p "$INSTALL_ROOT/.claude-plugin" "$INSTALL_ROOT/plugins"
 rm -rf "$INSTALL_ROOT/plugins/$PLUGIN_NAME"
 cp -R "$BUNDLE_DIR" "$INSTALL_ROOT/plugins/$PLUGIN_NAME"
 ${renderInstallerUserConfigSnippet(config, "claude-code", "$INSTALL_ROOT/plugins/$PLUGIN_NAME")}
+${renderInstallerRuntimeBootstrapSnippet("$INSTALL_ROOT/plugins/$PLUGIN_NAME")}
 
 cat > "$INSTALL_ROOT/.claude-plugin/marketplace.json" <<JSON
 {
@@ -9398,6 +9716,7 @@ mkdir -p "$(dirname "$INSTALL_DIR")"
 rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
 ${renderInstallerUserConfigSnippet(config, "cursor", "$INSTALL_DIR")}
+${renderInstallerRuntimeBootstrapSnippet("$INSTALL_DIR")}
 
 echo "Installed $PLUGIN_NAME to $INSTALL_DIR"
 echo "If Cursor is already open, use Developer: Reload Window or restart Cursor so the plugin is picked up."
@@ -9456,6 +9775,7 @@ mkdir -p "$(dirname "$INSTALL_DIR")"
 rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
 ${renderInstallerUserConfigSnippet(config, "codex", "$INSTALL_DIR")}
+${renderInstallerRuntimeBootstrapSnippet("$INSTALL_DIR")}
 
 mkdir -p "$(dirname "$MARKETPLACE_PATH")"
 
@@ -9571,6 +9891,7 @@ mkdir -p "$(dirname "$INSTALL_DIR")" "$SKILLS_ROOT"
 rm -rf "$INSTALL_DIR"
 cp -R "$BUNDLE_DIR" "$INSTALL_DIR"
 ${renderInstallerUserConfigSnippet(config, "opencode", "$INSTALL_DIR")}
+${renderInstallerRuntimeBootstrapSnippet("$INSTALL_DIR")}
 
 export ENTRY_PATH
 export PLUGIN_NAME
@@ -9856,6 +10177,7 @@ import { existsSync as existsSync5, lstatSync as lstatSync2, readdirSync as read
 import { resolve as resolve5 } from "path";
 
 // src/cli/doctor.ts
+import { spawn } from "child_process";
 import { accessSync, constants, existsSync as existsSync4, lstatSync, readFileSync as readFileSync4, readdirSync as readdirSync2 } from "fs";
 import { basename, dirname as dirname2, resolve as resolve4 } from "path";
 
@@ -9872,6 +10194,29 @@ var CONFIG_FILES = [
 // src/cli/install.ts
 import { resolve as resolve3, dirname } from "path";
 import { existsSync as existsSync3, symlinkSync, mkdirSync as mkdirSync2, rmSync as rmSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2, cpSync, readdirSync } from "fs";
+
+// src/mcp-stdio-paths.ts
+function findHostPluginRootVars(value) {
+  const matches = value.match(/\$\{(?:CLAUDE_PLUGIN_ROOT|CURSOR_PLUGIN_ROOT|PLUGIN_ROOT)\}/g) ?? [];
+  return [...new Set(matches.map((match) => match.slice(2, -1)))];
+}
+function findLeakedPluginRootVars(platform, values) {
+  const leaks = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    for (const pluginRootVar of findHostPluginRootVars(value)) {
+      if (platform === "claude-code") {
+        if (pluginRootVar !== "CLAUDE_PLUGIN_ROOT") {
+          leaks.add(pluginRootVar);
+        }
+        continue;
+      }
+      leaks.add(pluginRootVar);
+    }
+  }
+  return [...leaks];
+}
+
+// src/cli/install.ts
 function getInstallTargets(pluginName) {
   const home = process.env.HOME ?? "~";
   return [
@@ -9935,9 +10280,39 @@ function getInstallTargets(pluginName) {
 function getClaudeMarketplaceName(pluginName) {
   return `pluxx-local-${pluginName}`;
 }
+function readBundleManifestVersion(rootDir, platform) {
+  const manifestPath = manifestPathForPlatform(platform);
+  if (!manifestPath) return void 0;
+  const filepath = resolve3(rootDir, manifestPath);
+  if (!existsSync3(filepath)) return void 0;
+  try {
+    const manifest = JSON.parse(readFileSync3(filepath, "utf-8"));
+    return typeof manifest.version === "string" ? manifest.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveClaudeInstalledCachePath(pluginName, version) {
+  if (!version) return void 0;
+  const home = process.env.HOME ?? "~";
+  return resolve3(home, ".claude/plugins/cache", getClaudeMarketplaceName(pluginName), pluginName, version);
+}
+function resolveExpectedInstalledConsumerPath(target, pluginName) {
+  if (target.platform === "claude-code" && pluginName !== "") {
+    const cachePath = resolveClaudeInstalledCachePath(
+      pluginName,
+      readBundleManifestVersion(target.sourceDir, "claude-code")
+    );
+    if (cachePath) return cachePath;
+  }
+  return target.pluginDir;
+}
 function resolveInstalledConsumerPath(target, pluginName) {
   if (target.platform === "claude-code" && pluginName !== "") {
-    return target.pluginDir;
+    const expectedPath = resolveExpectedInstalledConsumerPath(target, pluginName);
+    if (existsSync3(expectedPath)) return expectedPath;
+    if (existsSync3(target.pluginDir)) return target.pluginDir;
+    return expectedPath;
   }
   return target.pluginDir;
 }
@@ -10013,7 +10388,8 @@ function findInstalledBundleIntegrityIssues(rootDir, platform) {
   if (!manifestPath) {
     return {
       missingManifestPaths: [],
-      missingHookTargets: []
+      missingHookTargets: [],
+      invalidRuntimeScripts: []
     };
   }
   const manifestFile = resolve3(rootDir, manifestPath);
@@ -10021,7 +10397,8 @@ function findInstalledBundleIntegrityIssues(rootDir, platform) {
     return {
       manifestIssue: `missing plugin manifest at ${manifestPath}`,
       missingManifestPaths: [],
-      missingHookTargets: []
+      missingHookTargets: [],
+      invalidRuntimeScripts: []
     };
   }
   let manifest;
@@ -10031,7 +10408,8 @@ function findInstalledBundleIntegrityIssues(rootDir, platform) {
     return {
       manifestIssue: `plugin manifest at ${manifestPath} is not parseable: ${error instanceof Error ? error.message : String(error)}`,
       missingManifestPaths: [],
-      missingHookTargets: []
+      missingHookTargets: [],
+      invalidRuntimeScripts: []
     };
   }
   const missingManifestPaths = readBundleManifestReferences(manifest).filter((value) => {
@@ -10042,14 +10420,16 @@ function findInstalledBundleIntegrityIssues(rootDir, platform) {
   if (!hooksReference) {
     return {
       missingManifestPaths,
-      missingHookTargets: []
+      missingHookTargets: [],
+      invalidRuntimeScripts: findInstalledRuntimeScriptIssues(rootDir, manifest)
     };
   }
   const hooksPath = resolveBundleReference(rootDir, hooksReference);
   if (!hooksPath || !existsSync3(hooksPath)) {
     return {
       missingManifestPaths,
-      missingHookTargets: []
+      missingHookTargets: [],
+      invalidRuntimeScripts: findInstalledRuntimeScriptIssues(rootDir, manifest)
     };
   }
   try {
@@ -10064,15 +10444,47 @@ function findInstalledBundleIntegrityIssues(rootDir, platform) {
     )].sort();
     return {
       missingManifestPaths,
-      missingHookTargets
+      missingHookTargets,
+      invalidRuntimeScripts: findInstalledRuntimeScriptIssues(rootDir, manifest)
     };
   } catch {
     return {
       missingManifestPaths,
-      missingHookTargets: []
+      missingHookTargets: [],
+      invalidRuntimeScripts: findInstalledRuntimeScriptIssues(rootDir, manifest)
     };
   }
 }
+function findInstalledRuntimeScriptIssues(rootDir, manifest) {
+  const mcpReference = typeof manifest.mcpServers === "string" ? manifest.mcpServers : void 0;
+  if (!mcpReference) return [];
+  const mcpPath = resolveBundleReference(rootDir, mcpReference);
+  if (!mcpPath || !existsSync3(mcpPath)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync3(mcpPath, "utf-8"));
+    const issues = /* @__PURE__ */ new Set();
+    for (const [serverName, server] of Object.entries(parsed.mcpServers ?? {})) {
+      if (!server || typeof server !== "object") continue;
+      const serverRecord = server;
+      const args = Array.isArray(serverRecord.args) ? serverRecord.args.filter((value) => typeof value === "string") : [];
+      const commandTargets = [
+        typeof serverRecord.command === "string" ? serverRecord.command : "",
+        ...args
+      ].flatMap(extractBundleCommandTargets);
+      for (const target of commandTargets) {
+        const resolved = resolveBundleReference(rootDir, target);
+        if (!resolved || !existsSync3(resolved) || !resolved.endsWith(".sh")) continue;
+        const content = readFileSync3(resolved, "utf-8");
+        if (!content.includes("check-env.sh")) continue;
+        const relativePath = resolved.startsWith(`${rootDir}/`) ? resolved.slice(rootDir.length + 1) : resolved;
+        issues.add(`runtime script ${relativePath} for MCP server "${serverName}" still references installer-owned scripts/check-env.sh`);
+      }
+    }
+    return [...issues].sort();
+  } catch {
+    return [];
+  }
+}
 function planInstallPlugin(distDir, pluginName, platforms) {
   const targets = getInstallTargets(pluginName);
   const filtered = platforms ? targets.filter((t) => platforms.includes(t.platform)) : targets;
@@ -10224,6 +10636,10 @@ var MUTATING_PREFIX_PATTERN = new RegExp(`^(${MUTATING_PREFIXES.join("|")})\\b`,
 // src/cli/doctor.ts
 var MATERIALIZED_ENV_MARKER = "materialized required config";
 var MIN_NODE_MAJOR = 18;
+var STDIO_LAUNCH_SMOKE_TIMEOUT_MS = 1200;
+function renderInstalledPluginRoot(value, rootDir) {
+  return value.replaceAll("${PLUGIN_ROOT}", rootDir).replaceAll("${CLAUDE_PLUGIN_ROOT}", rootDir).replaceAll("${CURSOR_PLUGIN_ROOT}", rootDir).replaceAll("${CODEX_PLUGIN_ROOT}", rootDir).replaceAll("${OPENCODE_PLUGIN_ROOT}", rootDir);
+}
 function addCheck(checks, check) {
   checks.push(check);
 }
@@ -10422,14 +10838,14 @@ function checkInstalledUserConfig(checks, rootDir) {
   }
 }
 function checkInstalledEnvValidation(checks, rootDir) {
-  const envScriptPath = "scripts/check-env.sh";
+  const envScriptPath = INSTALLER_OWNED_CHECK_ENV_PATH;
   const resolvedPath = resolve4(rootDir, envScriptPath);
   if (!existsSync4(resolvedPath)) {
     addCheck(checks, {
       level: "info",
       code: "consumer-env-script-missing",
       title: "No install-time env validation script found",
-      detail: "This bundle does not ship a scripts/check-env.sh file.",
+      detail: getConsumerEnvScriptMissingDetail(),
       fix: "No action needed unless this plugin is expected to validate runtime secrets on install.",
       path: envScriptPath
     });
@@ -10451,12 +10867,30 @@ function checkInstalledEnvValidation(checks, rootDir) {
     level: "warning",
     code: "consumer-env-script-active",
     title: "Install-time env validation is still active",
-    detail: "This bundle still runs scripts/check-env.sh, which usually means required config was not materialized into the installed plugin.",
+    detail: getConsumerEnvScriptActiveDetail(),
     fix: "If authenticated tools fail, reinstall the plugin and provide the requested userConfig values or required env vars.",
     path: envScriptPath
   });
 }
-function checkInstalledMcpConfig(checks, rootDir, layout) {
+function checkInstalledRuntimeScriptRoles(checks, rootDir) {
+  const roleFiles = [
+    "scripts/check-env.sh",
+    "scripts/load-env.sh",
+    "scripts/bootstrap-runtime.sh",
+    "scripts/start-mcp.sh"
+  ];
+  const presentRoles = roleFiles.filter((relativePath) => existsSync4(resolve4(rootDir, relativePath))).map((relativePath) => getRuntimeScriptRoleForPath(relativePath)).filter((role) => role !== null);
+  if (presentRoles.length === 0) return;
+  addCheck(checks, {
+    level: "info",
+    code: "consumer-runtime-script-roles",
+    title: "Known runtime script-role files detected",
+    detail: getConsumerRuntimeScriptRolesDetail(presentRoles),
+    fix: "No action needed unless the runtime startup chain is unexpectedly missing a script you rely on.",
+    path: "scripts/"
+  });
+}
+async function checkInstalledMcpConfig(checks, rootDir, layout) {
   if (!layout.mcpConfigPath) {
     addCheck(checks, {
       level: "info",
@@ -10504,8 +10938,9 @@ function checkInstalledMcpConfig(checks, rootDir, layout) {
         path: layout.mcpConfigPath
       });
     }
-    const remoteEntries = servers.filter((server) => "url" in server);
-    const stdioEntries = servers.filter((server) => "command" in server);
+    const namedServers = Object.entries(payload.mcpServers ?? {}).map(([name, server]) => ({ name, ...server }));
+    const remoteEntries = namedServers.filter((server) => "url" in server);
+    const stdioEntries = namedServers.filter((server) => "command" in server);
     const inlineHeaderEntries = servers.filter((server) => {
       if ("headers" in server && server.headers && typeof server.headers === "object") return true;
       if ("http_headers" in server && server.http_headers && typeof server.http_headers === "object") return true;
@@ -10531,6 +10966,38 @@ function checkInstalledMcpConfig(checks, rootDir, layout) {
           path: layout.mcpConfigPath
         });
       }
+      const leakedPluginRootVars = [...new Set(
+        stdioEntries.flatMap((server) => {
+          const serverRecord = server;
+          const serverArgs = Array.isArray(serverRecord.args) ? serverRecord.args.filter((value) => typeof value === "string") : [];
+          const values = [
+            typeof server.command === "string" ? server.command : "",
+            ...serverArgs
+          ];
+          return findLeakedPluginRootVars(layout.platform, values);
+        })
+      )].sort();
+      if (leakedPluginRootVars.length > 0) {
+        addCheck(checks, {
+          level: "warning",
+          code: "consumer-mcp-stdio-host-root-leak",
+          title: "Installed stdio MCP config contains the wrong host root contract",
+          detail: `This installed ${layout.platform} MCP config still contains plugin root variable${leakedPluginRootVars.length === 1 ? "" : "s"} that do not belong in this host bundle: ${leakedPluginRootVars.map((pluginRootVar) => `\${${pluginRootVar}}`).join(", ")}.`,
+          fix: "Author global stdio MCP paths as `./...` or `${PLUGIN_ROOT}/...`, then rebuild and reinstall so Pluxx can normalize the correct host-specific path.",
+          path: layout.mcpConfigPath
+        });
+      }
+      const launchResults = await smokeCheckInstalledStdioServers(rootDir, stdioEntries);
+      for (const result of launchResults) {
+        addCheck(checks, {
+          level: result.ok ? "success" : "error",
+          code: result.ok ? "consumer-mcp-stdio-launch-valid" : "consumer-mcp-stdio-launch-failed",
+          title: result.ok ? `Installed stdio MCP server launches for ${result.serverName}` : `Installed stdio MCP server failed to stay up for ${result.serverName}`,
+          detail: `${result.command || "(empty command)"} \u2014 ${result.detail}`,
+          fix: result.ok ? "No action needed." : "Launch the installed command directly from the plugin directory, fix any missing runtime files/dependencies, then reinstall and rerun pluxx verify-install.",
+          path: layout.mcpConfigPath
+        });
+      }
     }
     if (remoteEntries.length > 0 && inlineHeaderEntries.length > 0) {
       addCheck(checks, {
@@ -10577,6 +11044,9 @@ function checkInstalledBundleIntegrity(checks, rootDir, layout) {
   if (issues.missingHookTargets.length > 0) {
     details.push(`hook commands reference missing bundle target${issues.missingHookTargets.length === 1 ? "" : "s"}: ${issues.missingHookTargets.join(", ")}`);
   }
+  if (issues.invalidRuntimeScripts.length > 0) {
+    details.push(`runtime startup still depends on installer-owned validation: ${issues.invalidRuntimeScripts.join(", ")}`);
+  }
   if (details.length === 0) {
     addCheck(checks, {
       level: "success",
@@ -10612,6 +11082,87 @@ function findMissingInstalledStdioRuntimePaths(rootDir, stdioEntries) {
   }
   return [...missing].sort();
 }
+async function smokeCheckInstalledStdioServers(rootDir, stdioEntries) {
+  const results = [];
+  for (const server of stdioEntries) {
+    const serverName = typeof server.name === "string" ? server.name : "unknown";
+    const command = typeof server.command === "string" ? renderInstalledPluginRoot(server.command, rootDir) : "";
+    const args = Array.isArray(server.args) ? server.args.filter((value) => typeof value === "string").map((value) => renderInstalledPluginRoot(value, rootDir)) : [];
+    const envRecord = server.env && typeof server.env === "object" ? Object.fromEntries(
+      Object.entries(server.env).filter((entry) => typeof entry[1] === "string").map(([key, value]) => [key, renderInstalledPluginRoot(value, rootDir)])
+    ) : {};
+    if (command.trim().length === 0) {
+      results.push({
+        serverName,
+        command: "",
+        ok: false,
+        detail: "stdio command is empty"
+      });
+      continue;
+    }
+    const renderedCommand = [command, ...args].join(" ");
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    const child = spawn(command, args, {
+      cwd: rootDir,
+      env: {
+        ...process.env,
+        ...envRecord
+      },
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    child.stdout?.on("data", (chunk) => {
+      if (stdoutChunks.reduce((sum, entry) => sum + entry.length, 0) < 4096) {
+        stdoutChunks.push(Buffer.from(chunk));
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (stderrChunks.reduce((sum, entry) => sum + entry.length, 0) < 4096) {
+        stderrChunks.push(Buffer.from(chunk));
+      }
+    });
+    const exitResult = await new Promise((resolveResult) => {
+      let settled = false;
+      const settle = (result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        resolveResult(result);
+      };
+      const timeout = setTimeout(() => {
+        child.stdin?.end();
+        child.kill("SIGTERM");
+        settle({
+          serverName,
+          command: renderedCommand,
+          ok: true,
+          detail: `process stayed alive for ${STDIO_LAUNCH_SMOKE_TIMEOUT_MS}ms before teardown`
+        });
+      }, STDIO_LAUNCH_SMOKE_TIMEOUT_MS);
+      child.once("error", (error) => {
+        settle({
+          serverName,
+          command: renderedCommand,
+          ok: false,
+          detail: `failed to spawn: ${error.message}`
+        });
+      });
+      child.once("exit", (code, signal) => {
+        const stdout = Buffer.concat(stdoutChunks).toString("utf-8").trim();
+        const stderr = Buffer.concat(stderrChunks).toString("utf-8").trim();
+        const output = [stderr, stdout].filter(Boolean).join(" | ");
+        settle({
+          serverName,
+          command: renderedCommand,
+          ok: false,
+          detail: `process exited before ready window (code=${code ?? "null"}, signal=${signal ?? "null"})${output ? `: ${output}` : ""}`
+        });
+      });
+    });
+    results.push(exitResult);
+  }
+  return results;
+}
 function isLikelyLocalRuntimePath(value) {
   return value.startsWith("./") || value.startsWith("../") || value.startsWith(".\\") || value.startsWith("..\\");
 }
@@ -10785,7 +11336,8 @@ async function doctorConsumer(rootDir = process.cwd()) {
   checkInstalledBundleIntegrity(checks, rootDir, layout);
   checkInstalledUserConfig(checks, rootDir);
   checkInstalledEnvValidation(checks, rootDir);
-  checkInstalledMcpConfig(checks, rootDir, layout);
+  checkInstalledRuntimeScriptRoles(checks, rootDir);
+  await checkInstalledMcpConfig(checks, rootDir, layout);
   if (layout.platform === "opencode") {
     checkInstalledOpenCodeHostBridge(checks, rootDir);
     checkInstalledOpenCodeSkills(checks, rootDir);
@@ -10800,7 +11352,7 @@ function buildCheckFromReport(target, pluginName, report) {
   const stale = staleReason !== void 0;
   return {
     platform: target.platform,
-    installPath: target.pluginDir,
+    installPath: consumerPath,
     consumerPath,
     built: target.built,
     installed: existsSync5(consumerPath),
@@ -10952,11 +11504,13 @@ function getVerifyInstallRecoveryActions(check) {
 }
 export {
   CORE_FOUR_PRIMITIVE_CAPABILITIES,
+  INSTALLER_OWNED_CHECK_ENV_PATH,
   PLATFORM_LIMITS,
   PLATFORM_LIMIT_POLICIES,
   PLATFORM_VALIDATION_RULES,
   PLUXX_COMPILER_BUCKETS,
   PLUXX_COMPILER_INTENT_PATH,
+  PORTABLE_RUNTIME_SCRIPT_ROLES,
   PluginConfigSchema,
   buildGeneratedPermissionHookScript,
   buildOpenCodePermissionMap,
@@ -10964,15 +11518,25 @@ export {
   definePlugin,
   formatPublishPlan,
   getConfiguredCompilerBuckets,
+  getConsumerEnvScriptActiveDetail,
+  getConsumerEnvScriptMissingDetail,
   getCoreFourPrimitiveCapabilities,
+  getEnabledRuntimeReadinessBindings,
+  getInstallerOwnedCheckEnvHookMessage,
+  getInstallerOwnedCheckEnvRuntimeMessage,
   getPlatformCompatibilityMatrix,
   getPlatformRules,
   getPluginCompilerBuckets,
+  getPortableRuntimeScriptRoleGuidance,
+  getRuntimeReadinessCapability,
+  getRuntimeReadinessExternalConfigNote,
+  getRuntimeReadinessNamedPromptTargetNote,
   parsePermissionRule,
   permissionRulesNeedToolLevelDowngrade,
   planPublish,
   printVerifyInstallResult,
   readCompilerIntent,
+  referencesInstallerOwnedCheckEnv,
   renderCompatibilityMatrixMarkdown,
   runPublish,
   verifyInstall