create-agdf 0.14.5 → 0.20.1

package/lib/host-adapters/codex/plugin.js

@@ -0,0 +1,243 @@
+import process from "node:process";
+import { inspectPluginList } from "../../installers/plugin-command.js";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { inspectGeneratedRepositoryMarketplace } from "#agdf-core/runtime/plugin-provenance.js";
+import { execHostFileSync } from "../../host-command.js";
+import { pluginDefinition } from "../../cli/runtime-context.js";
+import { historicalEvidenceEntries, rollbackMarketplaceFilesystem, captureOptions, runPluginPhase, lifecycleAdapterError, pluginVersionFromList, versionMismatchMessage, recoveryAttempt } from "../../installers/plugin-command.js";
+import { CODEX_REGISTRATION_REVISION, isCodexLocalInstallVersion } from "./identity.js";
+import { classifyMarketplaceList, inspectLocalMarketplaceProjection, prepareLocalMarketplace, inspectCodexOwnedManifestRepair } from "../../installers/local-marketplace.js";
+import { migrateLegacyCodexMcpRegistration, prepareCodexPluginMcp } from "./plugin-mcp.js";
+import { ownedFileSnapshot } from "../../lifecycle/owned-mutation.js";
+import { inspectCodexCockpitAdmission, inspectCodexSetup } from '../../mcp-lifecycle/adapters/codex.js';
+
+// Codex lists its complete remote catalog too. Keep capture bounded while allowing
+// that output to exceed Node's 1 MiB default; other host commands retain their limits.
+export const CODEX_PLUGIN_LIST_MAX_BUFFER = 4 * 1024 * 1024;
+
+export function installCodexGlobalPlugin({
+  exec = execHostFileSync,
+  prepare = prepareLocalMarketplace,
+  dataRoot,
+  env = process.env,
+  migrateMcp = migrateLegacyCodexMcpRegistration,
+  prepareMcp = prepareCodexPluginMcp,
+  target,
+} = {}) {
+  const expectedVersion = pluginDefinition.version;
+  const nativeOutput = [];
+  if (target) target = realpathSync(target);
+  // This check precedes prepare(), which publishes the marketplace candidate.
+  let cockpitAdmission = target ? inspectCodexCockpitAdmission({ target, env, exec }) : null;
+  const manifestRepair = cockpitAdmission && !cockpitAdmission.admitted
+    ? inspectCodexOwnedManifestRepair({ ...(dataRoot ? { dataRoot } : {}), env, expectedVersion }) : null;
+  if (manifestRepair) cockpitAdmission = inspectCodexCockpitAdmission({ target, env, exec, manifestRepair });
+  if (cockpitAdmission && !cockpitAdmission.admitted) throw lifecycleAdapterError('cockpit_conflict',
+    'Cockpit server identity is already occupied or configuration coverage is unresolved. Preserve the existing route; qualify the same-key candidate in an isolated native context before a guarded transition.', cockpitAdmission);
+  const legacyCockpit = target && inspectCodexSetup({ target, env }).entries.some(entry => entry.role === 'cockpit'
+    && entry.scope !== 'plugin' && entry.configured !== 'disabled');
+  manifestRepair?.assertCurrent();
+  const transaction = prepare({ expectedVersion, codexRegistrationRevision: CODEX_REGISTRATION_REVISION, ...(dataRoot ? { dataRoot } : {}) });
+  const expectedInstallVersion = transaction.codexInstallVersion ?? expectedVersion;
+  const migration = { state: "unknown", source: "", addedLocal: false, removedLegacy: false, refreshOwnedLocal: false, removedOwnedLocal: false };
+  try {
+    const marketplaceOutput = runPluginPhase(exec, "codex", ["plugin", "marketplace", "list", "--json"], "marketplace", captureOptions());
+    migrateMarketplace({ exec, output: marketplaceOutput, root: transaction.root, nativeOutput, migration, refreshOwnedLocal: transaction.changed === true });
+    nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "add", "agdf@agdf", "--json"], "plugin_operation", captureOptions()));
+    const listOutput = runPluginPhase(exec, "codex", ["plugin", "list"], "verification", { ...captureOptions(), maxBuffer: CODEX_PLUGIN_LIST_MAX_BUFFER });
+    const installedVersion = pluginVersionFromList(listOutput, "agdf@agdf");
+    if (installedVersion !== expectedInstallVersion) {
+      throw lifecycleAdapterError("version", versionMismatchMessage("Codex", "agdf@agdf", expectedInstallVersion, installedVersion, "npx --yes @agdf/cli@latest codex"));
+    }
+    if (!manifestRepair) transaction.commit(legacyCockpit ? { retainCockpitRollbackFor: target } : undefined);
+    const retainedCockpit = legacyCockpit && existsSync(`${transaction.root}.transaction.json`)
+      ? JSON.parse(readFileSync(`${transaction.root}.transaction.json`, 'utf8'))
+      : { previous_source_digest: transaction.sourceDigest, previous_version: expectedVersion };
+    // Best effort, both: retire the legacy user-scope `agdf` registration, which shares the plugin server
+    // name and survives `codex plugin remove`, then prewarm the runtime the launcher would install on first start.
+    const mcpEvidence = [
+      ...migrateMcp({ exec, env }),
+      ...(transaction.pluginRoot ? prepareMcp({ exec, pluginRoot: transaction.pluginRoot }) : []),
+    ];
+    if (manifestRepair) {
+      // Recovery does not turn failed ownership evidence into availability.
+      // Before deleting the backup, require a fresh, fully valid connected host.
+      const repairedAdmission = inspectCodexCockpitAdmission({ target, env, exec });
+      if (!repairedAdmission.admitted || repairedAdmission.native_provider_status !== 'owned_connected') throw lifecycleAdapterError('cockpit_repair_unconfirmed',
+        'The repaired owned plugin did not qualify in a fresh native context; preserve rollback.', repairedAdmission);
+      transaction.commit();
+      mcpEvidence.push('owned_manifest_repair:qualified_fresh_native_connection');
+    }
+    return {
+      surface: "codex", operation: migration.state === "owned_local_current" ? "update" : "install", expectedVersion: expectedInstallVersion, canonicalVersion: expectedVersion, installedVersion, verificationStatus: legacyCockpit ? 'configured_pending_restart' : "healthy",
+      ...(legacyCockpit ? { cockpitTransition: { state: 'qualification_pending', target,
+        previous_installation_retained: transaction.changed === true,
+        previous_plugin_digest: retainedCockpit.previous_source_digest ? `sha256:${retainedCockpit.previous_source_digest}` : null,
+        previous_plugin_version: retainedCockpit.previous_version ?? null } } : {}),
+      evidence: [
+        "durable_local_marketplace",
+        `marketplace:${migration.state}`,
+        "codex plugin list",
+        ...(transaction.pluginRoot ? [`staged_plugin_root:${transaction.pluginRoot}`, "staged_installation_provenance:matched"] : []),
+        ...(transaction.sourceDigest ? [`source_digest:${transaction.sourceDigest}`] : []),
+        ...(transaction.digest ? [`plugin_digest:${transaction.digest}`] : []),
+        ...(transaction.existingClassification === "owned_pre_provenance_rebuild" ? ["marketplace_recovery:owned_pre_provenance_rebuild", "loaded_session:restart_required"] : []),
+        ...(transaction.existingClassification === "owned_supported_historical_rebuild" ? ["marketplace_recovery:owned_supported_historical_rebuild", "loaded_session:fresh_session_required"] : []),
+        ...(transaction.existingClassification === "owned_damaged_rebuild" ? ["marketplace_recovery:owned_damaged_rebuild", "loaded_session:restart_required"] : []),
+        ...historicalEvidenceEntries(transaction),
+        ...(expectedInstallVersion === expectedVersion ? [] : [`canonical_version:${expectedVersion}`, `local_install_version:${expectedInstallVersion}`]),
+        ...mcpEvidence,
+        ...(cockpitAdmission ? ['cockpit_configuration_admission:passed', 'cockpit_native_provider:unobserved'] : []),
+        ...(legacyCockpit ? ['cockpit_transition:qualification_pending', 'cockpit_legacy:retained'] : []),
+      ],
+      pluginRoot: transaction.pluginRoot ?? null,
+      digest: transaction.digest ?? null,
+      runtimeDigest: transaction.runtimeDigest ?? null,
+      sourceDigest: transaction.sourceDigest ?? null,
+      historicalEvidence: transaction.historicalEvidence ?? null,
+      nativeOutput: nativeOutput.filter(Boolean).map(String),
+    };
+  } catch (error) {
+    recoverMarketplace({ exec, migration, transaction, error });
+    throw error;
+  }
+}
+
+function migrateMarketplace({ exec, output, root, nativeOutput, migration, refreshOwnedLocal = false }) {
+  const classification = classifyMarketplaceList("codex", output, root);
+  Object.assign(migration, classification);
+  if (["conflict", "unknown"].includes(classification.state)) {
+    throw lifecycleAdapterError("marketplace", `Refusing to replace non-AGDF marketplace registration agdf (${classification.reason || classification.state}).`, classification);
+  }
+  if (classification.state === "owned_local_current" && refreshOwnedLocal) {
+    migration.refreshOwnedLocal = true;
+    nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "marketplace", "remove", "agdf", "--json"], "marketplace", captureOptions()));
+    migration.removedOwnedLocal = true;
+    nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "marketplace", "add", root, "--json"], "marketplace", captureOptions()));
+    migration.addedLocal = true;
+    return;
+  }
+  if (classification.state === "legacy_github") {
+    nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "marketplace", "remove", "agdf", "--json"], "marketplace", captureOptions()));
+    migration.removedLegacy = true;
+  }
+  if (["absent", "legacy_github"].includes(classification.state)) {
+    nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "marketplace", "add", root, "--json"], "marketplace", captureOptions()));
+    migration.addedLocal = true;
+  }
+}
+
+function recoverMarketplace({ exec, migration, transaction, error }) {
+  const recovery = [];
+  const attempt = recoveryAttempt(exec, "codex", recovery);
+  if (migration?.refreshOwnedLocal) {
+    const refreshedRegistrationRemoved = migration.addedLocal
+      ? attempt(["plugin", "marketplace", "remove", "agdf", "--json"])
+      : true;
+    rollbackMarketplaceFilesystem(transaction, recovery);
+    if (migration.removedOwnedLocal && refreshedRegistrationRemoved) {
+      attempt(["plugin", "marketplace", "add", migration.source || transaction.root, "--json"]);
+    }
+    error.evidence = { ...(error.evidence ?? {}), rollback: recovery };
+    return;
+  }
+  if (migration?.addedLocal) attempt(["plugin", "marketplace", "remove", "agdf", "--json"]);
+  if (migration?.removedLegacy && migration.source) attempt(["plugin", "marketplace", "add", migration.source, "--json"]);
+  rollbackMarketplaceFilesystem(transaction, recovery);
+  error.evidence = { ...(error.evidence ?? {}), rollback: recovery };
+}
+
+export function inspectCodexPlugin(exec = execHostFileSync, options = {}, surface) {
+  return inspectPluginList({ surface, exec, executable: "codex", args: ["plugin", "list"], expectedVersion: pluginDefinition.version,
+    maxBuffer: CODEX_PLUGIN_LIST_MAX_BUFFER,
+    selectPlugin: () => "agdf@agdf",
+    // Codex also lists available marketplace entries after removal.
+    isInstalled(output, pluginId) {
+      return String(output).split(/\r?\n/).some(line => {
+        const fields = line.trim().split(/\s+/);
+        return fields[0] === pluginId && !(fields[1] === "not" && fields[2] === "installed");
+      });
+    },
+    localVersion(version) {
+      if (surface !== "codex" || !isCodexLocalInstallVersion(pluginDefinition.version, version)) return false;
+      try { return inspectLocalMarketplaceProjection(options)?.codexInstallVersion === version; }
+      catch { return false; }
+    },
+  });
+}
+
+export const uninstallCommand = () => ({ executable: "codex", args: ["plugin", "remove", "agdf@agdf"] });
+
+const CODEX_DISABLE_MARKER = "# AGDF-OWNED-REPOSITORY-PLUGIN-STATE";
+
+function pluginSection(content, selector) {
+  const escaped = JSON.stringify(selector).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return content.match(new RegExp(`\\[plugins\\.${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`))?.[0] ?? "";
+}
+
+function repositorySelector(targetDir, config = "") {
+  const repository = inspectGeneratedRepositoryMarketplace(targetDir);
+  if (repository.status === "matched") return repository.selector;
+  return pluginSection(config, "agdf@agdf-repo") ? "agdf@agdf-repo" : "agdf@agdf";
+}
+
+export function planCodexRepositoryDisable(targetDir) {
+  const surface = "codex";
+  const path = join(targetDir, ".codex", "config.toml");
+  const expectedSnapshot = ownedFileSnapshot(path);
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const selector = repositorySelector(targetDir, existing);
+  const escaped = JSON.stringify(selector).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const sectionPattern = new RegExp(`\\[plugins\\.${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`);
+  const currentSection = pluginSection(existing, selector);
+  const enabledMatches = [...currentSection.matchAll(/^enabled\s*=\s*(true|false)\s*$/gm)];
+  if (currentSection && enabledMatches.length !== 1) {
+    throw new Error(`Refusing to modify ambiguous AGDF plugin state in ${path}.`);
+  }
+  const section = currentSection
+    ? currentSection.replace(/^enabled\s*=\s*(true|false)\s*$/m, "enabled = false")
+    : `${CODEX_DISABLE_MARKER}\n[plugins.${JSON.stringify(selector)}]\nenabled = false`;
+  const content = currentSection
+    ? existing.replace(sectionPattern, section).replace(/\s*$/, "\n")
+    : `${existing.replace(/\s*$/, "")}${existing.trim() ? "\n\n" : ""}${section}\n`;
+  return Object.freeze({
+    operation: "disable",
+    surface,
+    scope: "repository",
+    mutations: Object.freeze([{ kind: "write", path, content, ownership: currentSection ? "exact_plugin_section" : "agdf_marker", expectedSnapshot }]),
+    retained: Object.freeze([join(targetDir, ".agdf", "control"), "global AGDF plugin availability"]),
+    expected: Object.freeze({ repository_status: "disabled" }),
+  });
+}
+
+export function verifyCodexRepositoryDisabled(targetDir) {
+  const path = join(targetDir, ".codex", "config.toml");
+  if (!existsSync(path)) return { status: "failed", evidence: [`missing:${path}`] };
+  const config = readFileSync(path, "utf8");
+  const selector = repositorySelector(targetDir, config);
+  const section = pluginSection(config, selector);
+  const matches = [...section.matchAll(/^enabled\s*=\s*(true|false)\s*$/gm)];
+  return matches.length === 1 && matches[0][1] === "false"
+    ? { status: "healthy", evidence: [`${path}:${selector}:enabled=false`] }
+    : { status: "failed", evidence: [`postcondition_failed:${path}:${selector}`] };
+}
+
+export function inspectCodexRepositoryStatus(targetDir) {
+    const repository = inspectGeneratedRepositoryMarketplace(targetDir);
+    const marketplace = repository.marketplacePath;
+    const disabled = join(targetDir, ".codex", "config.toml");
+    const config = existsSync(disabled) ? readFileSync(disabled, "utf8") : "";
+    const isDisabled = ["agdf@agdf-repo", "agdf@agdf"].some((selector) => {
+      const escaped = JSON.stringify(selector).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const section = config.match(new RegExp(`\\[plugins\\.${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`))?.[0] ?? "";
+      return /^enabled\s*=\s*false\s*$/m.test(section);
+    });
+    return {
+      status: isDisabled ? "disabled" : repository.status === "matched" ? "active" : repository.status === "invalid" ? "degraded" : "not_configured",
+      scope: "repository",
+      evidence: [marketplace, ...(repository.reason ? [repository.reason] : [])],
+    };
+}
+
+export const bootstrapCommands = () => ({ install: "npx --yes @agdf/cli@latest codex", repository: "npx --yes @agdf/cli@latest codex-repo" });

package/lib/host-adapters/codex/runtime-check.js

@@ -0,0 +1,27 @@
+export function codexRuntimeCheckEvidence({ capabilityIdentity, observedIdentity, hookEnabled, reviewRequired = false }) {
+  if (reviewRequired) return { status: "decision_required", reason: "host_review_required" };
+  if (hookEnabled && observedIdentity === capabilityIdentity) return { status: "enabled", capability_identity: capabilityIdentity, reason: "none" };
+  if (observedIdentity && observedIdentity !== capabilityIdentity) return { status: "renewal_required", reason: "capability_identity_changed" };
+  return { status: "decision_required", reason: "host_permission_unverified" };
+}
+
+export function projectCodexHookObservation(state, observation) {
+  if (state.requested !== "enabled" || state.effective !== "decision_required") return state;
+  const hook = observation?.status === "observed" ? observation.hook : null;
+  if (!hook || !["managed", "trusted", "modified", "untrusted"].includes(hook.trust_status)
+      || typeof hook.enabled !== "boolean") return { ...state, verification: "host_unverified",
+    next_action: "Inspect the AGDF session hook in Codex /hooks, then retry runtime-checks status --surface codex." };
+  if (["modified", "untrusted"].includes(hook.trust_status)) {
+    const evidence = codexRuntimeCheckEvidence({ reviewRequired: true });
+    return { ...state, effective: evidence.status, reason: evidence.reason,
+      verification: "hook_review_required",
+      next_action: "Open /hooks in Codex, review and trust the current AGDF session hook, then start a fresh session." };
+  }
+  if (!hook.enabled) return { ...state, effective: "decision_required",
+    reason: "host_permission_unverified", verification: "hook_disabled",
+    next_action: "Enable the AGDF session hook in Codex /hooks, then start a fresh session." };
+  // hooks/list proves trust, not a successful execution in a fresh host session.
+  return { ...state, effective: "decision_required", reason: "host_permission_unverified",
+    verification: "hook_trusted_session_unverified",
+    next_action: "Verify the already trusted AGDF session hook in the fresh Codex session." };
+}

package/lib/host-adapters/codex/session-command.js

@@ -0,0 +1,7 @@
+import { environmentSessionCommand } from "../session-command.js";
+
+// Shared hooks.json: Claude Code runs `command` everywhere (PowerShell on Windows resolves only plain
+// ${CLAUDE_PLUGIN_ROOT}); Codex aliases it to PLUGIN_ROOT and uses commandWindows on Windows.
+export const sessionCommand = (_root, platform) => platform === "win32"
+  ? environmentSessionCommand("codex", platform)
+  : "node \"${CLAUDE_PLUGIN_ROOT}/runtime/agdf-session-check.js\"";

package/lib/host-adapters/copilot/plugin.js

@@ -0,0 +1,220 @@
+import { inspectPluginList } from "../../installers/plugin-command.js";
+import { execFileSync } from "node:child_process";
+import { pluginDefinition } from "../../cli/runtime-context.js";
+import { captureOptions, runPluginPhase, lifecycleAdapterError, commandErrorText, pluginListHasPlugin, pluginVersionFromList, versionMismatchMessage } from "../../installers/plugin-command.js";
+import process from "node:process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { configureCopilotMarketplace, defaultCopilotSettingsPath, readCopilotSettings, restoreCopilotMarketplaceSettings } from "../../installers/copilot-settings.js";
+import { copilotMarketplaceSource } from "../../installers/copilot-marketplace-transport.js";
+import { verifyCopilotSkillDiscovery } from "../../installers/copilot-skill-discovery.js";
+import { inspectOwnedSharedMarketplaceForCopilotMigration, prepareCopilotMarketplace } from "../../installers/local-marketplace.js";
+import { npmInvocation } from "../../installers/npm-invocation.js";
+import { execHostFileSync } from "../../host-command.js";
+
+export const COPILOT_CLI_NPM_PACKAGE = "@github/copilot@1.0.80";
+
+export function installCopilotGlobalPlugin({
+  exec = execHostFileSync, packagedCopilotExec = execFileSync, prepare = prepareCopilotMarketplace,
+  dataRoot, pluginRoot, copilotSettingsPath = defaultCopilotSettingsPath(),
+} = {}) {
+  const expectedVersion = pluginDefinition.version;
+  const previousSettings = readCopilotSettings(copilotSettingsPath);
+  const transaction = prepare({ expectedVersion, ...(dataRoot ? { dataRoot } : {}), ...(pluginRoot ? { builtPluginRoot: pluginRoot } : {}) });
+  const effectivePluginRoot = transaction.pluginRoot;
+  const sourceDigest = transaction.sourceDigest;
+  const marketplaceRoot = transaction.root;
+  const desiredSource = copilotMarketplaceSource(marketplaceRoot, sourceDigest);
+  let before = "";
+  let activeExec = exec;
+  const bootstrapEvidence = [];
+  try {
+    before = activeExec("copilot", ["plugin", "list"], captureOptions());
+  } catch (error) {
+    if (!copilotCliUnavailable(error)) {
+      transaction.rollback();
+      throw lifecycleAdapterError("verification", commandErrorText(error), { executable: "copilot", args: ["plugin", "list"] });
+    }
+    const invocation = copilotNpmInvocation();
+    activeExec = (_executable, args, options) => packagedCopilotExec(invocation.executable, [...invocation.args, ...args], options);
+    try {
+      before = activeExec("copilot", ["plugin", "list"], captureOptions());
+      bootstrapEvidence.push(
+        error?.code === "ENOENT" ? "copilot_cli_not_found" : "copilot_cli_launcher_unavailable",
+        `copilot_cli_npm_package:${COPILOT_CLI_NPM_PACKAGE}`,
+      );
+    } catch (bootstrapError) {
+      transaction.commit();
+      return {
+        surface: "copilot", operation: "install", expectedVersion, installedVersion: null,
+        verificationStatus: "unavailable", manualHandoff: true,
+        evidence: ["copilot_cli_not_found", `copilot_cli_npm_bootstrap_failed:${commandErrorText(bootstrapError)}`, "durable_local_plugin_stage", `local_plugin_root:${effectivePluginRoot}`, `source_digest:${sourceDigest}`],
+        pluginRoot: effectivePluginRoot, runtimeDigest: transaction.runtimeDigest, sourceDigest, nativeOutput: [],
+      };
+    }
+  }
+  const directInstalled = pluginListHasPlugin(before, "agdf");
+  const marketplaceInstalled = pluginListHasPlugin(before, "agdf@agdf");
+  let legacySharedProjection = null;
+  try { legacySharedProjection = inspectOwnedSharedMarketplaceForCopilotMigration({ ...(dataRoot ? { dataRoot } : {}), expectedVersion }); } catch {}
+  let marketplace = null;
+  let registrationRemoved = false;
+  let settingsChanged = false;
+  let marketplacePluginRemoved = false;
+  let directRemoved = false;
+  let installedNewPlugin = false;
+  try {
+    const nativeOutput = [];
+    const marketplaceOutput = runPluginPhase(activeExec, "copilot", ["plugin", "marketplace", "list"], "marketplace", captureOptions());
+    marketplace = classifyCopilotMarketplaceList(marketplaceOutput, marketplaceRoot, {
+      ownedLegacyRoots: legacySharedProjection ? [legacySharedProjection.root] : [],
+    });
+    const configured = previousSettings.settings.extraKnownMarketplaces?.agdf;
+    if (configured) {
+      const source = configured.source;
+      const projection = source?.source === "directory" && typeof source.path === "string"
+        ? `agdf (Local: ${source.path})`
+        : source?.source === "git" && typeof source.url === "string" ? `agdf (URL: ${source.url})` : "agdf (Unknown source)";
+      const configuredState = classifyCopilotMarketplaceList(projection, marketplaceRoot, {
+        ownedLegacyRoots: legacySharedProjection ? [legacySharedProjection.root] : [],
+      });
+      if (configuredState.state === "conflict") marketplace = configuredState;
+    }
+    if (marketplace.state === "conflict") {
+      throw lifecycleAdapterError("marketplace", `Refusing to replace non-AGDF Copilot marketplace registration agdf (${marketplace.source || "unknown source"}).`);
+    }
+    // Reinstall even at the same public version: source content can change in a
+    // local checkout. The Git ref binds Copilot's catalog cache to that content.
+    if (marketplaceInstalled) {
+      nativeOutput.push(runPluginPhase(activeExec, "copilot", ["plugin", "uninstall", "agdf@agdf"], "plugin_operation", captureOptions()));
+      marketplacePluginRemoved = true;
+    }
+    if (marketplace.state !== "absent"
+        && JSON.stringify(previousSettings.settings.extraKnownMarketplaces?.agdf?.source) !== JSON.stringify(desiredSource)) {
+      nativeOutput.push(runPluginPhase(activeExec, "copilot", ["plugin", "marketplace", "remove", "agdf"], "marketplace", captureOptions()));
+      registrationRemoved = true;
+    }
+    // Copilot's documented declarative Git source accepts local file URLs;
+    // its imperative marketplace-add parser treats those URLs as directories.
+    configureCopilotMarketplace({ path: copilotSettingsPath, root: marketplaceRoot, sourceDigest });
+    settingsChanged = true;
+    if (directInstalled) {
+      nativeOutput.push(runPluginPhase(activeExec, "copilot", ["plugin", "uninstall", "agdf"], "plugin_operation", captureOptions()));
+      directRemoved = true;
+    }
+    nativeOutput.push(runPluginPhase(activeExec, "copilot", ["plugin", "install", "agdf@agdf"], "plugin_operation", captureOptions()));
+    installedNewPlugin = true;
+    const after = runPluginPhase(activeExec, "copilot", ["plugin", "list"], "verification", captureOptions());
+    if (!pluginListHasPlugin(after, "agdf@agdf")) throw lifecycleAdapterError("verification", "AGDF was not present in copilot plugin list after installation.");
+    const installedVersion = pluginVersionFromList(after, "agdf@agdf");
+    if (installedVersion && installedVersion !== expectedVersion) {
+      throw lifecycleAdapterError("version", versionMismatchMessage("GitHub Copilot", "agdf", expectedVersion, installedVersion, "npx --yes @agdf/cli@latest copilot"));
+    }
+    const skillOutput = runPluginPhase(activeExec, "copilot", ["skill", "list", "--json"], "verification", { ...captureOptions(), cwd: marketplaceRoot });
+    let discovery;
+    try { discovery = verifyCopilotSkillDiscovery(skillOutput, { definition: pluginDefinition, sourceDigest }); }
+    catch (error) { throw lifecycleAdapterError("verification", error.message); }
+    transaction.commit();
+    return {
+      surface: "copilot", operation: directInstalled || marketplaceInstalled ? "update" : "install", expectedVersion,
+      installedVersion: installedVersion || null, verificationStatus: installedVersion ? "healthy" : "degraded", manualHandoff: false,
+      evidence: [...bootstrapEvidence, "durable_local_plugin_stage", "copilot_marketplace_transport:git", "copilot plugin marketplace list",
+        ...(marketplace.state === "owned_legacy_shared" ? ["shared_marketplace_registration_migrated"] : []),
+        ...(marketplace.state === "owned_local_current" ? ["directory_marketplace_registration_migrated"] : []),
+        ...(directRemoved ? ["direct_install_migrated"] : []), "copilot plugin install agdf@agdf", "copilot plugin list", "copilot skill list --json",
+        `discovered_plugin_skills:${discovery.count}`, `discovered_plugin_root:${discovery.pluginRoot}`, "discovered_payload:matched",
+        `local_plugin_root:${effectivePluginRoot}`, `source_digest:${sourceDigest}`, ...(installedVersion ? [] : ["host_did_not_expose_version"])],
+      pluginRoot: effectivePluginRoot, runtimeDigest: transaction.runtimeDigest, sourceDigest, nativeOutput: nativeOutput.filter(Boolean).map(String),
+    };
+  } catch (error) {
+    const recover = (name, action) => {
+      try { action(); } catch (recoveryError) { error.evidence = { ...(error.evidence ?? {}), [name]: commandErrorText(recoveryError) }; }
+    };
+    if (installedNewPlugin) recover("new_plugin_cleanup", () => activeExec("copilot", ["plugin", "uninstall", "agdf@agdf"], captureOptions()));
+    recover("marketplace_filesystem_recovery", () => transaction.rollback());
+    if (settingsChanged || registrationRemoved || marketplacePluginRemoved) {
+      recover("marketplace_settings_recovery", () => restoreCopilotMarketplaceSettings(copilotSettingsPath, previousSettings));
+    }
+    if (registrationRemoved && !previousSettings.settings.extraKnownMarketplaces?.agdf) {
+      recover("marketplace_registration_recovery", () => activeExec("copilot", ["plugin", "marketplace", "add", marketplace.source], captureOptions()));
+    }
+    if (marketplacePluginRemoved) recover("marketplace_plugin_recovery", () => activeExec("copilot", ["plugin", "install", "agdf@agdf"], captureOptions()));
+    if (directRemoved) recover("direct_install_recovery", () => activeExec("copilot", ["plugin", "install", effectivePluginRoot], captureOptions()));
+    // Reinstallation can enable a previously disabled plugin. The prior user
+    // setting remains authoritative after native recovery has finished.
+    if (marketplacePluginRemoved || directRemoved) {
+      recover("plugin_enablement_recovery", () => restoreCopilotMarketplaceSettings(copilotSettingsPath, previousSettings));
+    }
+    throw error;
+  }
+}
+
+export function classifyCopilotMarketplaceList(output, expectedRoot, { ownedLegacyRoots = [] } = {}) {
+  const lines = String(output || "").split(/\r?\n/).filter((entry) => /^\s*[◆•]?\s*agdf\s+\(/.test(entry));
+  if (lines.length === 0) return { state: "absent", source: "" };
+  if (lines.length !== 1) return { state: "conflict", source: "multiple agdf marketplace registrations" };
+  const [line] = lines;
+  const local = line.match(/\(Local:\s*(.+)\)\s*$/);
+  if (local) {
+    if (resolve(local[1]) === resolve(expectedRoot)) return { state: "owned_local_current", source: local[1] };
+    if (ownedLegacyRoots.some((root) => resolve(root) === resolve(local[1]))) return { state: "owned_legacy_shared", source: local[1] };
+  }
+  const remote = line.match(/\((?:URL|Git):\s*(file:\/\/.+)\)\s*$/);
+  if (remote) {
+    try {
+      const url = new URL(remote[1]);
+      url.hash = "";
+      if (resolve(fileURLToPath(url)) === resolve(expectedRoot)) return { state: "owned_git_current", source: remote[1] };
+    } catch {}
+  }
+  return { state: "conflict", source: local?.[1] ?? line.trim() };
+}
+
+export function copilotNpmInvocation({ env = process.env, platform = process.platform, execPath = process.execPath } = {}) {
+  const args = ["exec", "--yes", `--package=${COPILOT_CLI_NPM_PACKAGE}`, "--", "copilot"];
+  if (env.npm_execpath) return { executable: execPath, args: [env.npm_execpath, ...args] };
+  const invocation = npmInvocation(args, { env, platform, execPath });
+  return { executable: invocation.executable, args: [...invocation.args] };
+}
+
+export function setCopilotPluginEnabled({ enabled, exec = execHostFileSync } = {}) {
+  if (typeof enabled !== "boolean") throw lifecycleAdapterError("plugin_operation", "Copilot plugin enabled state must be boolean.");
+  const operation = enabled ? "enable" : "disable";
+  try {
+    const nativeOutput = runPluginPhase(exec, "copilot", ["plugin", operation, "agdf"], "plugin_operation", captureOptions());
+    const listOutput = runPluginPhase(exec, "copilot", ["plugin", "list"], "verification", captureOptions());
+    if (!pluginListHasPlugin(listOutput, "agdf") && !pluginListHasPlugin(listOutput, "agdf@agdf")) {
+      throw lifecycleAdapterError("verification", "AGDF was not present in copilot plugin list after the state change.");
+    }
+    return {
+      surface: "copilot",
+      requestedState: enabled ? "enabled" : "disabled",
+      status: "command_accepted_host_state_unverified",
+      evidence: [`copilot plugin ${operation} agdf`, "copilot plugin list", "fresh_session_required"],
+      nativeOutput: String(nativeOutput || ""),
+    };
+  } catch (error) {
+    if (/\bmanaged\b/i.test(commandErrorText(error))) {
+      return {
+        surface: "copilot", requestedState: enabled ? "enabled" : "disabled", status: "managed",
+        evidence: ["managed_policy_precedence", commandErrorText(error)], nativeOutput: "",
+      };
+    }
+    throw error;
+  }
+}
+
+function copilotCliUnavailable(error) {
+  return error?.code === "ENOENT"
+    || /^Cannot find GitHub Copilot CLI(?:\s|$|\()/i.test(commandErrorText(error));
+}
+
+export function inspectCopilotPlugin(exec = execHostFileSync) {
+  return inspectPluginList({ surface: "copilot", exec, executable: "copilot", args: ["plugin", "list"], expectedVersion: pluginDefinition.version,
+    selectPlugin: output => pluginListHasPlugin(output, "agdf@agdf") ? "agdf@agdf" : "agdf",
+  });
+}
+
+export const uninstallCommand = () => ({ executable: "copilot", args: ["plugin", "uninstall", "agdf"] });
+
+export const bootstrapCommands = () => ({ install: "npx --yes @agdf/cli@latest copilot", repository: "npx --yes @agdf/cli@latest copilot-repo" });

package/lib/host-adapters/copilot/session-command.js

@@ -0,0 +1 @@
+export const sessionCommand = () => 'node "${PLUGIN_ROOT}/runtime/agdf-session-check.js"';

package/lib/host-adapters/opencode/runtime-check.js

@@ -0,0 +1,39 @@
+export function openCodeRuntimeCheckEvidence({ capabilityIdentity, observedIdentity, packageLoadable, hookObserved }) {
+  if (!packageLoadable) return { status: "unavailable", reason: "unsupported_host_capability" };
+  if (observedIdentity !== capabilityIdentity) return { status: "renewal_required", reason: "installed_identity_mismatch" };
+  if (!hookObserved) return { status: "degraded", reason: "host_permission_unverified" };
+  return { status: "enabled", capability_identity: capabilityIdentity, reason: "none" };
+}
+
+import { join } from "node:path";
+import process from "node:process";
+import { defaultOpenCodeConfigDir, resolveOpenCodeInstalledPackage } from "../../installers/opencode.js";
+import { pluginDefinition } from "../../cli/runtime-context.js";
+
+export function openCodeRuntimeSource() {
+  return resolveOpenCodeInstalledPackage(defaultOpenCodeConfigDir(), pluginDefinition.opencode.npmPackage);
+}
+
+export function executeOpenCodeRuntimeCheck({ directory, dataRoot, packageRoot, run, executable, statusResolver, entrypointExists }) {
+  const status = statusResolver(dataRoot, "opencode");
+  if (status.requested !== "enabled" || status.effective !== "decision_required") {
+    return { ...status, ran: false, output: "" };
+  }
+  const entrypoint = join(packageRoot, "generated", "plugins", "agdf", "runtime", "agdf-session-check.js");
+  if (!entrypointExists(entrypoint)) {
+    return { ...status, effective: "unavailable", reason: "unsupported_host_capability", verification: "entrypoint_missing", ran: false, output: "" };
+  }
+  const child = run(executable, [entrypoint], {
+    cwd: directory,
+    env: { ...process.env, AGDF_SURFACE: "opencode" },
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 10000,
+    maxBuffer: 1024 * 1024,
+  });
+  const output = String(child.stdout || "").trim().slice(0, 20000);
+  if (child.status !== 0 || !output.includes("AGDF automatic runtime check:")) {
+    return { ...status, effective: "degraded", reason: "host_permission_unverified", verification: "execution_failed", ran: true, output: "" };
+  }
+  return { ...status, effective: "enabled", reason: "none", verification: "host_observed", ran: true, output };
+}

package/lib/host-adapters/opencode/session-command.js

@@ -0,0 +1 @@
+export const sessionCommand = () => "plugin:agdf:automatic-runtime-checks";

package/lib/host-adapters/opencode/status.js

@@ -0,0 +1,43 @@
+import { defaultOpenCodeConfigDir } from "../../installers/opencode.js";
+export function inspectOpenCodeInstallation(options, evaluateOpenCodeGlobalStatus) {
+  const surface = "opencode";
+    const configDir = options.configDir ?? defaultOpenCodeConfigDir();
+    const report = evaluateOpenCodeGlobalStatus(configDir);
+    const healthy = report.status === "configured"
+      && report.global_config?.plugin_configured === true
+      && report.package?.loadable === true
+      && report.package?.version_status === "current"
+      && report.global_native_surface?.complete === true
+      && report.experimental_hooks?.aggregate === "declared_supported"
+      && report.host_sdk_version?.status === "matching";
+    const hasAgdfEvidence = report.global_config?.plugin_configured === true
+      || report.global_config?.legacy_plugin_configured === true
+      || report.package?.loadable === true
+      || report.global_native_surface?.present === true;
+    return {
+      status: healthy ? "healthy" : hasAgdfEvidence ? "degraded" : "not_installed",
+      surface,
+      version: report.package?.installed_version ?? null,
+      evidence: [
+        report.global_config?.path,
+        `package:${report.package?.version_status ?? "unknown"}`,
+        `global_native_surface:${report.global_native_surface?.complete === true ? "complete" : "incomplete"}`,
+        `experimental_hooks:${report.experimental_hooks?.aggregate ?? "unknown"}`,
+        `host_sdk_version:${report.host_sdk_version?.status ?? "unknown"};policy=${report.host_sdk_version?.policy ?? "unknown"}`,
+      ].filter(Boolean),
+      recommended_action: report.next_step || null,
+    };
+}
+
+export function inspectOpenCodeRepositoryStatus(targetDir, evaluateActivation) {
+    const activation = evaluateActivation(targetDir);
+    return {
+      status: activation.active ? "active" : activation.state === "invalid_control" ? "degraded" : "not_configured",
+      scope: "repository",
+      evidence: [
+        activation.config_path,
+        activation.diagnostic,
+        ...(activation.error ? [activation.error] : []),
+      ].filter(Boolean),
+    };
+}

package/lib/host-adapters/session-command.js

@@ -0,0 +1,11 @@
+export function environmentSessionCommand(surface, platform) {
+  const [primary, fallback] = surface === "claude"
+    ? ["CLAUDE_PLUGIN_ROOT", "PLUGIN_ROOT"]
+    : ["PLUGIN_ROOT", "CLAUDE_PLUGIN_ROOT"];
+  if (platform === "win32") {
+    const primaryValue = `[Environment]::GetEnvironmentVariable('${primary}')`;
+    const fallbackValue = `[Environment]::GetEnvironmentVariable('${fallback}')`;
+    return `node \"$(if (${primaryValue}) { ${primaryValue} } else { ${fallbackValue} })\\runtime\\agdf-session-check.js\"`;
+  }
+  return `node \"\${${primary}:-\${${fallback}}}/runtime/agdf-session-check.js\"`;
+}