create-agdf 0.14.5 → 0.20.0

package/lib/installers/opencode.js

@@ -6,25 +6,47 @@ import process from "node:process";
 import { generatedRoot, pluginDefinition } from "../cli/runtime-context.js";
 import { evaluateOpenCodeRepositoryActivation } from "./opencode-activation.js";
 import { resolveLocalValidator } from "../runtime/local-validator.js";
-import { digestDirectory } from "../runtime/plugin-provenance.js";
+import { digestDirectory } from "#agdf-core/runtime/plugin-provenance.js";
+import { hostSkillName, projectHostSkillNames } from "#agdf-core/skill-dispatch/contract.js";
 import { validateLocalOpenCodePackageSource } from "./local-development.js";
+import { npmInvocation } from "./npm-invocation.js";
+import { execHostFileSync } from "../host-command.js";
+import { atomicWrite } from "#agdf-core/control-state/run-state-writer.js";
+import { assertUnchangedOwnedFile, fileContentDigest, ownedFileSnapshot } from "../lifecycle/owned-mutation.js";
 
-const contractModules = ["gate-transition.md", "interaction.md", "modes.md", "quality.md", "context-graph.md", "control-scaffold.md", "closeout.md"];
-const openCodeSkillNames = pluginDefinition.skillSet.map((skill) => pluginDefinition.opencode.skillPrefix + skill.slug);
-const globalOpenCodeSkillNames = pluginDefinition.skillSet.map((skill) => pluginDefinition.opencode.globalSkillPrefix + skill.slug);
+function runtimeContractModuleNames(definition) {
+  const modules = definition?.runtimeContract?.modules;
+  if (definition?.runtimeContract?.schemaVersion !== 1 || !Array.isArray(modules) || modules.length === 0) {
+    throw new Error("OpenCode installation requires the definition-owned runtimeContract inventory.");
+  }
+  const names = modules.map((modulePath) => {
+    const match = /^meta\/contracts\/([a-z0-9-]+\.md)$/.exec(modulePath);
+    if (!match) throw new Error(`OpenCode runtime contract has an invalid module path: ${modulePath}`);
+    return match[1];
+  });
+  if (new Set(names).size !== names.length) throw new Error("OpenCode runtime contract modules must be unique.");
+  if (names[0] !== "request-activation.md" || names[1] !== "task-target-resolution.md") {
+    throw new Error("OpenCode runtime contract must place request activation before task-target resolution.");
+  }
+  return Object.freeze(names);
+}
+
+const contractModules = runtimeContractModuleNames(pluginDefinition);
+const openCodeSkillNames = pluginDefinition.skillSet.map((skill) => hostSkillName(pluginDefinition, "opencode", skill.slug));
+const globalOpenCodeSkillNames = pluginDefinition.skillSet.map((skill) => hostSkillName(pluginDefinition, "opencode", skill.slug, { global: true }));
 const globalOpenCodeSkillOwnershipMarker = "<!-- AGDF-GLOBAL-SKILL: ";
 const globalOpenCodeInstructionsOwnershipMarker = "<!-- AGDF-GLOBAL-INSTRUCTIONS -->";
 const globalOpenCodeRuntimeContractOwnershipMarker = "<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->";
 const globalOpenCodeValidatorOwnershipMarker = "// AGDF-GLOBAL-LOCAL-VALIDATOR";
 const globalOpenCodeAgentOwnershipMarker = `<!-- AGDF-GLOBAL-AGENT: ${pluginDefinition.opencode.evaluatorAgentName} -->`;
 const globalOpenCodeValidatorPackageOwner = "create-agdf";
+const requestActivationGuardStart = "<!-- AGDF-REQUEST-ACTIVATION-GUARD:START -->";
+const requestActivationGuardEnd = "<!-- AGDF-REQUEST-ACTIVATION-GUARD:END -->";
+const openCodeRouterFileName = "agdf-agent-router.md";
 export const openCodePluginEntrypoint = `./node_modules/${pluginDefinition.opencode.npmPackage}/opencode-plugin.js`;
-const testNpmCliPath = process.env.NODE_ENV === "test" ? process.env.AGDF_TEST_NPM_CLI_PATH || "" : "";
-const npmCommand = testNpmCliPath ? process.execPath : process.platform === "win32" ? process.execPath : "npm";
-const npmPrefixArgs = testNpmCliPath ? [testNpmCliPath] : process.platform === "win32" ? [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")] : [];
-
 export function openCodeNpmInvocation(args) {
-  return { executable: npmCommand, args: [...npmPrefixArgs, ...args] };
+  const invocation = npmInvocation(args);
+  return { executable: invocation.executable, args: [...invocation.args] };
 }
 
 function openCodeLifecycleError(phase, message, evidence = {}) {
@@ -55,6 +77,7 @@ export function installOpenCodeGlobalPlugin(configDir, dependencies = {}) {
   }
   const previousPackage = resolveOpenCodePackage(configDir);
   const configPath = join(configDir, "opencode.json");
+  const originalConfigSnapshot = ownedFileSnapshot(configPath);
   let config = {};
 
   if (existsSync(configPath)) {
@@ -117,19 +140,30 @@ export function installOpenCodeGlobalPlugin(configDir, dependencies = {}) {
     const packageSource = resolveOpenCodeInstallPackageSource(dependencies.packageSource);
     localPackageSource = packageSource.local;
     const packageSpecifier = packageSource.specifier;
-    const invocation = openCodeNpmInvocation(["install", "--silent", "--save-prod", "--save-exact", packageSpecifier]);
+    const invocation = openCodeNpmInvocation([
+      "install",
+      "--silent",
+      "--ignore-scripts",
+      "--no-audit",
+      "--no-fund",
+      "--save-prod",
+      "--save-exact",
+      packageSpecifier,
+    ]);
     execFileSync(invocation.executable, invocation.args, {
       cwd: configDir,
       stdio: "pipe",
     });
   } catch (error) {
+    const failedInvocation = openCodeNpmInvocation(["install"]);
     throw openCodeLifecycleError("plugin_operation", `Failed to install ${pluginDefinition.opencode.npmPackage} into the OpenCode config directory: ${(error.stderr || error.message).toString().trim()}`, {
-      executable: npmCommand,
-      args: [...npmPrefixArgs, "install"],
+      executable: failedInvocation.executable,
+      args: failedInvocation.args,
     });
   }
   try {
-    writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+    assertUnchangedOwnedFile(configPath, originalConfigSnapshot);
+    atomicWrite(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`);
   } catch (error) {
     throw openCodeLifecycleError("configuration", `Failed to write OpenCode config ${configPath}: ${error.message}`, { configPath });
   }
@@ -155,6 +189,7 @@ export function installOpenCodeGlobalPlugin(configDir, dependencies = {}) {
 function globalOpenCodeConfigPaths(configDir) {
   return {
     instructions: join(configDir, pluginDefinition.opencode.instructionsFileName),
+    router: join(configDir, "node_modules", pluginDefinition.opencode.npmPackage, "generated", ".opencode", openCodeRouterFileName),
     runtimeContract: join(configDir, pluginDefinition.opencode.runtimeContractFileName),
     contracts: join(configDir, "contracts"),
     skills: join(configDir, "skills"),
@@ -197,7 +232,7 @@ function globalOpenCodeOwnershipMarkerIsValid(content, marker, placement) {
 }
 
 function assertGlobalOpenCodeFileWritable(path, marker, placement) {
-  if (!existsSync(path)) return;
+  if (fileContentDigest(path) === null) return;
   const existing = readFileSync(path, "utf8");
   if (!globalOpenCodeOwnershipMarkerIsValid(existing, marker, placement)) {
     throw new Error(`Refusing to overwrite unowned global OpenCode file: ${path}`);
@@ -232,43 +267,62 @@ function writeOwnedGlobalOpenCodeFile(path, content, marker, placement) {
     assertGlobalOpenCodeFileWritable(path, marker, placement);
   }
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, content, "utf8");
-}
-
-function globalOpenCodeBoundary() {
-  return [
-    "## Global OpenCode Surface Boundary",
-    "",
-    "This skill is globally discoverable, but global plugin or skill presence is not repository governance activation.",
-    "Before applying AGDF gates, later artefacts or implementation guidance, inspect the current repository for valid `.agdf/control/config.json` durable control.",
-    "If durable control is missing or invalid, stop and direct the user to `npx --yes @agdf/cli@latest opencode-repo` in this repository.",
-    "When durable control is valid, use the global `agdf-global-*` skill surface; existing local OpenCode assets remain a compatibility path.",
-    "Only exact `Approval: <GateName>` values can advance AGDF gates; host permissions and plugin hooks never grant delivery authority.",
-    "Resolve and use the installed version-matched `agdf/bin/agdf-local.js` validator for deterministic checks.",
-    "If activation, approval, evidence or validator ownership is missing or unclear, stop before later artefacts or implementation.",
-    "Use `opencode-status --json` to inspect installed hook declarations, version divergence and evaluator availability without treating SDK declarations as live hook execution proof.",
-    "",
-  ].join("\n");
+  atomicWrite(path, content);
 }
 
 function globalOpenCodeActivationGuard() {
   return [
     "## Repository Activation Guard",
     "",
-    "Apply AGDF governance only when this repository has valid `.agdf/control/config.json` durable control.",
-    "If it is missing or invalid, stop and direct the user to `npx --yes @agdf/cli@latest opencode-repo`; the global installation alone is not activation.",
+    "This guard is reachable only after positive Request Activation and applies only to a target-bound route.",
+    "Control-independent help, global plugin lifecycle, global runtime checks and global installation status bypass this guard and never invent or inspect a repository target.",
+    "For a target-bound route, continue only when the current OpenCode plugin system context explicitly declares this repository AGDF-active and supplies an exact `AGDF dispatcher binding:`.",
+    "If either signal is absent, stop and direct the user to `npx --yes @agdf/cli@latest opencode-repo`; the global installation alone is not activation.",
+    "Do not inspect files, search installed packages, derive a runtime path or request shell permission to establish activation or recover a missing binding.",
+    "The Conditional Executable Dispatch section below is unreachable unless both signals are present.",
     "",
   ].join("\n");
 }
 
 function toGlobalOpenCodeContent(content) {
-  let next = content;
-  for (const skill of pluginDefinition.skillSet) {
-    const localName = `${pluginDefinition.opencode.skillPrefix}${skill.slug}`;
-    const globalName = `${pluginDefinition.opencode.globalSkillPrefix}${skill.slug}`;
-    next = next.replaceAll(localName, globalName);
+  return projectHostSkillNames(content, pluginDefinition, "opencode", { global: true });
+}
+
+export function toGlobalOpenCodeInstructionsBootstrap(content) {
+  const localRouterReference = `the sibling \`${openCodeRouterFileName}\``;
+  const globalRouterReference = `\`./node_modules/${pluginDefinition.opencode.npmPackage}/generated/.opencode/${openCodeRouterFileName}\``;
+  const globalBootstrap = toGlobalOpenCodeContent(content);
+  if (globalBootstrap.split(localRouterReference).length !== 2) {
+    throw new Error("OpenCode micro-bootstrap must contain exactly one on-demand router reference.");
+  }
+  return globalBootstrap.replace(localRouterReference, globalRouterReference);
+}
+
+function toGlobalOpenCodeSkillContent(content) {
+  return toGlobalOpenCodeContent(content).replace(
+    "## Executable Dispatch\n",
+    [
+      "## Conditional Executable Dispatch",
+      "",
+      "Use only the exact dispatcher binding supplied by the active OpenCode plugin system context.",
+      "Never search for, infer or construct an executable or runtime path from this skill, the npm package, the filesystem or prior messages.",
+      "Without the explicit active declaration and exact binding, return the activation recovery above without invoking `bash` or another tool.",
+      "",
+    ].join("\n"),
+  );
+}
+
+function insertRepositoryActivationGuard(content) {
+  const startCount = content.split(requestActivationGuardStart).length - 1;
+  const endCount = content.split(requestActivationGuardEnd).length - 1;
+  if (startCount !== 1 || endCount !== 1) {
+    throw new Error(`OpenCode skill must contain exactly one Request Activation Guard; found ${startCount} start and ${endCount} end markers.`);
   }
-  return next;
+  const start = content.indexOf(requestActivationGuardStart);
+  const end = content.indexOf(requestActivationGuardEnd, start);
+  if (end < start) throw new Error("OpenCode Request Activation Guard markers are out of order.");
+  const insertion = end + requestActivationGuardEnd.length;
+  return `${content.slice(0, insertion)}\n\n${globalOpenCodeActivationGuard()}${content.slice(insertion)}`;
 }
 
 export function installOpenCodeGlobalSurface(configDir) {
@@ -276,17 +330,12 @@ export function installOpenCodeGlobalSurface(configDir) {
   const paths = globalOpenCodeConfigPaths(configDir);
   const generatedOpenCodeRoot = join(generatedRoot, ".opencode");
   const generatedInstructions = readFileSync(join(generatedOpenCodeRoot, pluginDefinition.opencode.instructionsFileName), "utf8");
+  const generatedRouter = join(generatedOpenCodeRoot, openCodeRouterFileName);
+  if (!existsSync(generatedRouter)) throw new Error(`OpenCode on-demand router is unavailable: ${generatedRouter}`);
   const generatedRuntimeContract = readFileSync(join(generatedOpenCodeRoot, pluginDefinition.opencode.runtimeContractFileName), "utf8");
   const globalInstructions = [
     globalOpenCodeInstructionsOwnershipMarker,
-    "# AGDF Global OpenCode instructions",
-    "",
-    "AGDF native skills are globally discoverable through OpenCode.",
-    "",
-    globalOpenCodeBoundary(),
-    "Valid `.agdf/control/` is the repository source of truth for active governance; legacy `.opencode/` assets remain supported without being required.",
-    "",
-    toGlobalOpenCodeContent(generatedInstructions),
+    toGlobalOpenCodeInstructionsBootstrap(generatedInstructions),
   ].join("\n");
   const globalRuntimeContract = `${globalOpenCodeRuntimeContractOwnershipMarker}\n${generatedRuntimeContract}`;
   const localValidator = `${globalOpenCodeValidatorOwnershipMarker}\nimport process from "node:process";\nimport { fileURLToPath } from "node:url";\nimport { runLocalValidator } from "../../node_modules/create-agdf/lib/runtime/local-validator.js";\n\nconst ownedPackageRoot = fileURLToPath(new URL("../../node_modules/create-agdf", import.meta.url));\nprocess.exitCode = runLocalValidator({ ownedPackageRoot, expectedVersion: ${JSON.stringify(pluginDefinition.version)}, surface: "opencode" }, process.argv.slice(2));\n`;
@@ -337,12 +386,14 @@ export function installOpenCodeGlobalSurface(configDir) {
     const sourcePath = join(generatedOpenCodeRoot, "skills", sourceName, "SKILL.md");
     const sourceContent = readFileSync(sourcePath, "utf8");
     const marker = `${globalOpenCodeSkillOwnershipMarker}${skillName} -->`;
-    const content = toGlobalOpenCodeContent(sourceContent).replace(/^(---[\s\S]*?\n---\n)/, `$1${marker}\n\n${globalOpenCodeActivationGuard()}`);
+    const markedContent = toGlobalOpenCodeSkillContent(sourceContent).replace(/^(---[\s\S]*?\n---\n)/, `$1${marker}\n\n`);
+    const content = insertRepositoryActivationGuard(markedContent);
     writeOwnedGlobalOpenCodeFile(join(paths.skills, skillName, "SKILL.md"), content, marker, "after-frontmatter");
   }
 
   return {
     instructions: paths.instructions,
+    router: paths.router,
     runtimeContract: paths.runtimeContract,
     contracts: paths.contracts,
     skills: paths.skills,
@@ -435,8 +486,8 @@ export function resolveOpenCodeInstalledPackage(configDir, packageName, dependen
   }
 }
 
-function resolveOpenCodePackage(configDir) {
-  return resolveOpenCodeInstalledPackage(configDir, pluginDefinition.opencode.npmPackage);
+function resolveOpenCodePackage(configDir, dependencies = {}) {
+  return resolveOpenCodeInstalledPackage(configDir, pluginDefinition.opencode.npmPackage, dependencies);
 }
 
 const requiredExperimentalHooks = [
@@ -453,7 +504,7 @@ function packageLocalPath(packageRoot, candidate) {
 
 function openCodeHostProbe(dependencies = {}) {
   const executable = dependencies.openCodeBin ?? process.env.AGDF_OPENCODE_BIN ?? "opencode";
-  const run = dependencies.execFileSync ?? execFileSync;
+  const run = dependencies.execFileSync ?? execHostFileSync;
   try {
     return {
       name: "opencode",
@@ -716,6 +767,11 @@ function evaluateGlobalOpenCodeSurface(configDir) {
     path: paths.skills,
     instructions: paths.instructions,
     runtime_contract: paths.runtimeContract,
+    router: {
+      path: paths.router,
+      present: existsSync(paths.router),
+      loading: "on_demand",
+    },
     contracts: paths.contracts,
     expected_skill_count: globalOpenCodeSkillNames.length,
     skill_count: skillCount,
@@ -733,6 +789,7 @@ function evaluateGlobalOpenCodeSurface(configDir) {
     },
     present: existsSync(paths.skills),
     complete: existsSync(paths.instructions)
+      && existsSync(paths.router)
       && existsSync(paths.runtimeContract)
       && contractCount === contractModules.length
       && skillCount === openCodeSkillNames.length
@@ -743,25 +800,16 @@ function evaluateGlobalOpenCodeSurface(configDir) {
   };
 }
 
-export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(), transition = null, dependencies = {}) {
+export function evaluateOpenCodeGlobalStatus(configDir = defaultOpenCodeConfigDir(), dependencies = {}) {
   const configPath = join(configDir, "opencode.json");
-  const configState = readOpenCodeConfig(configPath);
+  const configState = (dependencies.readOpenCodeConfig ?? readOpenCodeConfig)(configPath);
   const plugins = Array.isArray(configState.config.plugin) ? configState.config.plugin : [];
   const globalConfigured = plugins.includes(openCodePluginEntrypoint);
   const legacyPluginConfigured = plugins.some((entry) => entry === pluginDefinition.opencode.npmPackage || entry.startsWith(`${pluginDefinition.opencode.npmPackage}@`));
-  const packageState = resolveOpenCodePackage(configDir);
+  const packageState = (dependencies.resolveOpenCodePackage ?? resolveOpenCodePackage)(configDir, dependencies);
   const packageVersionStatus = openCodePackageVersionStatus(packageState);
-  const globalNativeSurface = evaluateGlobalOpenCodeSurface(configDir);
-  const hostSdk = evaluateOpenCodeHostSdk(configDir, dependencies);
-  const sessionSignals = {
-    active: process.env.AGDF_PLUGIN_ACTIVE === "1",
-    version: process.env.AGDF_PLUGIN_VERSION || "",
-    control_dir: process.env.AGDF_CONTROL_DIR || "",
-    repository_surface: process.env.AGDF_OPENCODE_REPOSITORY_SURFACE === "1",
-    repository_activation: process.env.AGDF_OPENCODE_REPOSITORY_ACTIVATION || "",
-  };
-  const repositoryActivation = evaluateOpenCodeRepositoryActivation(targetDir);
-  const gateCheckSkillPath = join(targetDir, ".opencode", "skills", `${pluginDefinition.opencode.skillPrefix}gate-check`, "SKILL.md");
+  const globalNativeSurface = (dependencies.evaluateGlobalOpenCodeSurface ?? evaluateGlobalOpenCodeSurface)(configDir, dependencies);
+  const hostSdk = (dependencies.evaluateOpenCodeHostSdk ?? evaluateOpenCodeHostSdk)(configDir, dependencies);
 
   const findings = [];
   if (!configState.exists) findings.push("OpenCode global config not found.");
@@ -782,12 +830,6 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
   if (hostSdk.host_sdk_version.status === "divergent") {
     findings.push(`OpenCode host ${hostSdk.host_sdk_version.host_version} and plugin SDK ${hostSdk.host_sdk_version.sdk_version} diverge; policy is warning-only.`);
   }
-  if (!sessionSignals.active) findings.push("No active AGDF OpenCode session signal is visible in this process.");
-  if (!repositoryActivation.active) {
-    findings.push(repositoryActivation.state === "invalid_control"
-      ? "Current repository has invalid AGDF durable control configuration."
-      : "Current repository does not contain valid AGDF durable control configuration.");
-  }
 
   return {
     schema_version: "1",
@@ -807,11 +849,50 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
       installed_version: packageState.installed_version || null,
       expected_version: pluginDefinition.version,
       version_status: packageVersionStatus,
-      ...(transition ? { transition } : {}),
       error: packageState.error,
     },
     ...hostSdk,
     global_native_surface: globalNativeSurface,
+    findings,
+    next_step: packageVersionStatus !== "current"
+      ? "Run npx --yes @agdf/cli@latest opencode to install or repair the OpenCode package version."
+      : !globalNativeSurface.complete
+      ? "Run npx --yes @agdf/cli@latest opencode to install or repair the global native OpenCode skill surface."
+      : hostSdk.experimental_hooks.aggregate === "uninspectable"
+      ? "Repair the installed OpenCode plugin SDK so its declarations can be inspected; do not assume dynamic hook support."
+      : hostSdk.experimental_hooks.aggregate === "degraded"
+      ? "Use static AGDF instructions and review OpenCode compatibility before relying on dynamic hook injection."
+      : hostSdk.host_sdk_version.status === "divergent"
+      ? "Run npx --yes @agdf/cli@latest opencode to align the plugin SDK to the exact OpenCode host version; status itself remains read-only."
+      : "Global OpenCode installation is current; a repository target is not required for global status or lifecycle operations.",
+  };
+}
+
+export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeConfigDir(), transition = null, dependencies = {}) {
+  const globalStatus = evaluateOpenCodeGlobalStatus(configDir, dependencies);
+  const sessionSignals = {
+    active: process.env.AGDF_PLUGIN_ACTIVE === "1",
+    version: process.env.AGDF_PLUGIN_VERSION || "",
+    control_dir: process.env.AGDF_CONTROL_DIR || "",
+    repository_surface: process.env.AGDF_OPENCODE_REPOSITORY_SURFACE === "1",
+    repository_activation: process.env.AGDF_OPENCODE_REPOSITORY_ACTIVATION || "",
+  };
+  const repositoryActivation = (dependencies.evaluateOpenCodeRepositoryActivation ?? evaluateOpenCodeRepositoryActivation)(targetDir);
+  const gateCheckSkillPath = join(targetDir, ".opencode", "skills", `${pluginDefinition.opencode.skillPrefix}gate-check`, "SKILL.md");
+  const findings = [...globalStatus.findings];
+  if (!sessionSignals.active) findings.push("No active AGDF OpenCode session signal is visible in this process.");
+  if (!repositoryActivation.active) {
+    findings.push(repositoryActivation.state === "invalid_control"
+      ? "Current repository has invalid AGDF durable control configuration."
+      : "Current repository does not contain valid AGDF durable control configuration.");
+  }
+
+  return {
+    ...globalStatus,
+    package: {
+      ...globalStatus.package,
+      ...(transition ? { transition } : {}),
+    },
     session: sessionSignals,
     repository_activation: repositoryActivation.state,
     repository_control: {
@@ -829,16 +910,10 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
     },
     visible_entrypoint: repositoryActivation.active ? `${pluginDefinition.opencode.globalSkillPrefix}gate-check (native skill)` : "none until durable AGDF control is configured for this repository",
     findings,
-    next_step: packageVersionStatus !== "current"
-      ? "Run npx --yes @agdf/cli@latest opencode to install or repair the OpenCode package version."
-      : !globalNativeSurface.complete
-      ? "Run npx --yes @agdf/cli@latest opencode to install or repair the global native OpenCode skill surface."
-      : hostSdk.experimental_hooks.aggregate === "uninspectable"
-      ? "Repair the installed OpenCode plugin SDK so its declarations can be inspected; do not assume dynamic hook support."
-      : hostSdk.experimental_hooks.aggregate === "degraded"
-      ? "Use static AGDF instructions and review OpenCode compatibility before relying on dynamic hook injection."
-      : hostSdk.host_sdk_version.status === "divergent"
-      ? "Run npx --yes @agdf/cli@latest opencode to align the plugin SDK to the exact OpenCode host version; status itself remains read-only."
+    next_step: globalStatus.package.version_status !== "current" || !globalStatus.global_native_surface.complete
+      || globalStatus.experimental_hooks.aggregate !== "declared_supported"
+      || globalStatus.host_sdk_version.status === "divergent"
+      ? globalStatus.next_step
       : repositoryActivation.state === "invalid_control"
       ? "Repair .agdf/control/config.json so it contains valid artifact_language, chat_language and runtime_language values."
       : repositoryActivation.active
@@ -854,7 +929,14 @@ export function printOpenCodeStatus(report, json, io = console) {
   }
 
   io.log("AGDF OpenCode status");
+  if (report.operation_status) {
+    io.log(`Operation: ${report.operation_status.operation_id}`);
+    io.log(`Outcome: ${report.operation_status.outcome}`);
+    io.log(`Target: ${report.operation_status.target ?? "global"}`);
+    io.log(`Authorizes: ${report.operation_status.authorizes ? "yes" : "no"}`);
+  }
   io.log(`Status: ${report.status}`);
+  if (report.installation_status) io.log(`Installation health: ${report.installation_status}`);
   io.log(`Global config: ${report.global_config.plugin_configured ? "configured" : "missing"} (${report.global_config.path})`);
   if (report.global_config.parse_error) io.log(`Config parse error: ${report.global_config.parse_error}`);
   io.log(`Package loadable: ${report.package.loadable ? "yes" : "no"}`);
@@ -878,13 +960,15 @@ export function printOpenCodeStatus(report, json, io = console) {
   }
   io.log(`Global native skills: ${report.global_native_surface.complete ? "complete" : "incomplete"} (${report.global_native_surface.skill_count}/${report.global_native_surface.expected_skill_count})`);
   io.log(`Global skill path: ${report.global_native_surface.path}`);
-  io.log(`Session active signal: ${report.session.active ? "yes" : "no"}`);
-  if (report.session.version) io.log(`Session plugin version: ${report.session.version}`);
-  if (report.session.control_dir) io.log(`Session control dir: ${report.session.control_dir}`);
-  io.log(`Repository activation: ${report.repository_activation}`);
-  io.log(`Repository control: ${report.repository_control.path} (${report.repository_control.diagnostic})`);
-  io.log(`Legacy repository surface: ${report.repository_surface.legacy_present ? "present" : "absent"}`);
-  io.log(`Visible entrypoint: ${report.visible_entrypoint}`);
+  if (report.session) {
+    io.log(`Session active signal: ${report.session.active ? "yes" : "no"}`);
+    if (report.session.version) io.log(`Session plugin version: ${report.session.version}`);
+    if (report.session.control_dir) io.log(`Session control dir: ${report.session.control_dir}`);
+    io.log(`Repository activation: ${report.repository_activation}`);
+    io.log(`Repository control: ${report.repository_control.path} (${report.repository_control.diagnostic})`);
+    io.log(`Legacy repository surface: ${report.repository_surface.legacy_present ? "present" : "absent"}`);
+    io.log(`Visible entrypoint: ${report.visible_entrypoint}`);
+  }
   io.log(`Next step: ${report.next_step}`);
 
   if (report.findings.length > 0) {
@@ -893,3 +977,116 @@ export function printOpenCodeStatus(report, json, io = console) {
     for (const finding of report.findings) io.log(`- ${finding}`);
   }
 }
+
+export function planOpenCodeGlobalUninstall(configDir) {
+  const surface = "opencode";
+    if (!configDir) throw new Error("OpenCode uninstall requires its explicit config directory.");
+    const configPath = join(configDir, "opencode.json");
+    if (!existsSync(configPath)) throw new Error(`OpenCode config not found: ${configPath}`);
+    const originalConfigSnapshot = ownedFileSnapshot(configPath);
+    let config;
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      throw new Error(`Refusing to modify unreadable OpenCode config: ${configPath}`);
+    }
+    if (config.plugin !== undefined && !Array.isArray(config.plugin)) {
+      throw new Error(`Refusing to modify OpenCode config with non-array plugin field: ${configPath}`);
+    }
+    const next = { ...config };
+    next.plugin = (config.plugin ?? []).filter((entry) => !isOwnedOpenCodePluginEntry(entry));
+    if (Array.isArray(config.instructions)) next.instructions = config.instructions.filter((entry) => entry !== "AGDF.md");
+    const npm = openCodeNpmInvocation(["uninstall", "--silent", pluginDefinition.opencode.npmPackage]);
+    const mutations = [
+      { kind: "write", path: configPath, content: `${JSON.stringify(next, null, 2)}\n`, ownership: "exact_known_entries", expectedSnapshot: originalConfigSnapshot },
+      { kind: "command", executable: npm.executable, args: npm.args, cwd: configDir },
+    ];
+    const retained = ["repository AGDF files", ".agdf/control"];
+    for (const candidate of openCodeOwnedGlobalFiles(configDir)) {
+      if (!existsSync(candidate.path)) continue;
+      const expectedSnapshot = ownedFileSnapshot(candidate.path);
+      const content = readFileSync(candidate.path, "utf8");
+      if (candidate.owned(content)) mutations.push({ kind: "remove", path: candidate.path, ownership: "agdf_marker", expectedSnapshot });
+      else retained.push(candidate.path);
+    }
+    return Object.freeze({
+      operation: "uninstall",
+      surface,
+      scope: "global",
+      mutations: Object.freeze(mutations),
+      retained: Object.freeze(retained),
+      expected: Object.freeze({ installation_status: "not_installed" }),
+    });
+}
+function openCodeOwnedGlobalFiles(configDir) {
+  const firstLine = (marker) => (content) => content.split(/\r?\n/)[0] === marker;
+  const afterFrontmatter = (marker) => (content) => {
+    const lines = content.split(/\r?\n/);
+    const end = lines.findIndex((line, index) => index > 0 && line === "---");
+    return end >= 0 && lines[end + 1] === marker;
+  };
+  const ownedValidatorPackage = (content) => {
+    try {
+      const manifest = JSON.parse(content);
+      return manifest?.agdf?.owner === "create-agdf"
+        && manifest?.agdf?.surface === "opencode-global-validator";
+    } catch {
+      return false;
+    }
+  };
+  const files = [
+    { path: join(configDir, pluginDefinition.opencode.instructionsFileName), owned: firstLine("<!-- AGDF-GLOBAL-INSTRUCTIONS -->") },
+    { path: join(configDir, pluginDefinition.opencode.runtimeContractFileName), owned: firstLine("<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->") },
+    { path: join(configDir, "agdf", "bin", "agdf-local.js"), owned: firstLine("// AGDF-GLOBAL-LOCAL-VALIDATOR") },
+    { path: join(configDir, "agdf", "package.json"), owned: ownedValidatorPackage },
+    {
+      path: join(configDir, "agents", `${pluginDefinition.opencode.evaluatorAgentName}.md`),
+      owned: afterFrontmatter(`<!-- AGDF-GLOBAL-AGENT: ${pluginDefinition.opencode.evaluatorAgentName} -->`),
+    },
+  ];
+  for (const modulePath of pluginDefinition.runtimeContract.modules) {
+    const prefix = "meta/contracts/";
+    if (!modulePath.startsWith(prefix) || modulePath.slice(prefix.length).includes("/")) {
+      throw new Error(`Invalid definition-owned runtime contract module path: ${modulePath}`);
+    }
+    const moduleName = modulePath.slice(prefix.length);
+    files.push({ path: join(configDir, "contracts", moduleName), owned: firstLine("<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->") });
+  }
+  for (const skill of pluginDefinition.skillSet) {
+    const name = hostSkillName(pluginDefinition, "opencode", skill.slug, { global: true });
+    const marker = `<!-- AGDF-GLOBAL-SKILL: ${name} -->`;
+    files.push({ path: join(configDir, "skills", name, "SKILL.md"), owned: afterFrontmatter(marker) });
+  }
+  return files;
+}
+
+function isOwnedOpenCodePluginEntry(entry) {
+  return typeof entry === "string"
+    && (entry === openCodePluginEntrypoint
+      || entry === pluginDefinition.opencode.npmPackage
+      || entry.startsWith(`${pluginDefinition.opencode.npmPackage}@`));
+}
+
+export function verifyOpenCodeGlobalUninstall(plan, configDir, evaluate = evaluateOpenCodeGlobalStatus) {
+    const report = evaluate(configDir);
+    const remainingOwnedFiles = plan.mutations
+      .filter((mutation) => mutation.kind === "remove")
+      .map((mutation) => mutation.path)
+      .filter((path) => existsSync(path));
+    const configClean = report.global_config?.plugin_configured === false
+      && report.global_config?.legacy_plugin_configured === false;
+    const packageRemoved = report.package?.loadable === false;
+    const statusClean = report.status === "not_configured";
+    const evidence = [
+      report.global_config?.path || join(configDir, "opencode.json"),
+      ...(configClean ? [] : ["postcondition_failed:agdf_plugin_entry_still_configured_or_uninspectable"]),
+      ...(packageRemoved ? [] : ["postcondition_failed:create-agdf_package_still_loadable_or_uninspectable"]),
+      ...(statusClean ? [] : [`postcondition_failed:observed_status:${report.status || "unknown"}`]),
+      ...remainingOwnedFiles.map((path) => `still_present:${path}`),
+    ];
+    return statusClean && configClean && packageRemoved && remainingOwnedFiles.length === 0
+      ? { status: "healthy", evidence: [...evidence, "marker_owned_global_files_removed"] }
+      : { status: "failed", evidence };
+}
+
+export const bootstrapCommands = () => ({ install: "npx --yes @agdf/cli@latest opencode", repository: "npx --yes @agdf/cli@latest opencode-repo" });

package/lib/installers/packaged-app-marketplace.js

@@ -0,0 +1,67 @@
+import { lstatSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
+import process from "node:process";
+import { packagedAppCopies, sameFileSystemEntry } from "#agdf-core/runtime/host-installation.js";
+
+const OWNERSHIP_FILE = ".agdf-owned.json";
+
+function ownedMarketplaceMarker(root, fs) {
+  try {
+    const type = fs.lstatSync(root);
+    if (type.isSymbolicLink() || !type.isDirectory()) return null;
+    const marker = JSON.parse(fs.readFileSync(join(root, OWNERSHIP_FILE), "utf8"));
+    return marker?.schema_version === 1
+      && marker.owner === "create-agdf"
+      && marker.marketplace_id === basename(root)
+      && (marker.profile_id ?? "runtime-plugin") === "runtime-plugin"
+      && marker.staging_state === "ready"
+      ? marker
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// A committed marketplace is not what packaged hosts see while their private copy of the same location
+// (see packagedAppCopies) survives: Claude Code inside Claude Desktop loads the plugin in place from it.
+// A stale AGDF-owned copy is retired, so the package falls back to the committed root. When the copy is
+// this process's own view, the install itself ran inside a package and stays invisible outside of it.
+export function reconcilePackagedAppMarketplaceCopies({
+  root,
+  sourceDigest,
+  pluginDigest,
+  env = process.env,
+  platform = process.platform,
+  now = Date.now,
+  fs = { lstatSync, readFileSync, renameSync, rmSync },
+} = {}) {
+  return packagedAppCopies(root, { env, platform }).map((copy) => {
+    const observed = { package: copy.package, path: copy.path };
+    if (sameFileSystemEntry(copy.path, root)) return Object.freeze({ ...observed, state: "install_view" });
+    const marker = ownedMarketplaceMarker(copy.path, fs);
+    if (!marker) return Object.freeze({ ...observed, state: "foreign" });
+    if (marker.source_digest === sourceDigest && marker.plugin_digest === pluginDigest) {
+      return Object.freeze({ ...observed, state: "current" });
+    }
+    const retiredPath = `${copy.path}.retired-${now()}`;
+    try {
+      fs.renameSync(copy.path, retiredPath);
+    } catch (error) {
+      return Object.freeze({ ...observed, state: "stale", reason: error?.code || "rename_failed" });
+    }
+    try {
+      fs.rmSync(retiredPath, { recursive: true, force: true });
+    } catch {
+      return Object.freeze({ ...observed, state: "retired", cleanup: retiredPath });
+    }
+    return Object.freeze({ ...observed, state: "retired" });
+  });
+}
+
+export function packagedAppCopyEvidence(copies) {
+  return copies.map((copy) => `packaged_app_copy:${copy.package}:${copy.state}${copy.reason ? `:${copy.reason}` : ""}${copy.cleanup ? `:cleanup_pending=${copy.cleanup}` : ""}`);
+}
+
+export function packagedAppCopiesHealthy(copies) {
+  return copies.every((copy) => ["current", "retired"].includes(copy.state));
+}