create-agdf 0.14.5 → 0.20.1

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

@@ -0,0 +1,285 @@
+import process from "node:process";
+import { inspectPluginList } from "../../installers/plugin-command.js";
+import { execHostFileSync } from "../../host-command.js";
+import { pluginDefinition } from "../../cli/runtime-context.js";
+import { historicalEvidenceEntries, rollbackMarketplaceFilesystem, captureOptions, runPluginPhase, lifecycleAdapterError, pluginListHasPlugin, pluginVersionFromList, versionMismatchMessage, recoveryAttempt } from "../../installers/plugin-command.js";
+import { classifyMarketplaceList, prepareLocalMarketplace } from "../../installers/local-marketplace.js";
+import { recoverClaudeCacheTemp } from "../../installers/claude-cache-recovery.js";
+import { packagedAppCopiesHealthy, packagedAppCopyEvidence, reconcilePackagedAppMarketplaceCopies } from "../../installers/packaged-app-marketplace.js";
+import { compareInstallationProvenance, detectPackagedAppProcess, readClaudeInstallationRecord, readInstallationDigests, removeClaudeInstallationRecord, writeClaudeInstallationRecord } from "#agdf-core/runtime/host-installation.js";
+import { prepareClaudePluginMcp, migrateLegacyClaudeMcpRegistration } from "./plugin-mcp.js";
+import { loadedClaudeSessions, loadedSessionEvidence, loadedSessionLockHint } from "./loaded-sessions.js";
+
+const PLUGIN_ID = "agdf@agdf";
+
+export function packagedAppRefusal(packageName) {
+  return `AGDF install refused: this process runs inside the packaged app ${packageName}, whose %LOCALAPPDATA% writes stay private to that app. Run the installation from a terminal outside ${packageName}.`;
+}
+
+// Runs before any marketplace, data-root or host-registration change: an install from inside a packaged
+// app would only update that app's private copy and stay invisible to every other process.
+export function preflightClaudeInstall({ env = process.env, platform = process.platform, detect = detectPackagedAppProcess } = {}) {
+  const verdict = detect({ env, platform });
+  if (verdict.status === "inside_package") {
+    throw lifecycleAdapterError("packaged_app", packagedAppRefusal(verdict.package), { packaged_app: verdict.package });
+  }
+  return [`packaged_app_preflight:${verdict.status}${verdict.reason ? `:${verdict.reason}` : ""}`];
+}
+
+// Claude Code lists plugins as JSON; hosts without --json keep the text listing. The user-scope entry
+// is the one this installer manages; `enabled` is unknown (null) when only text is available.
+export function readClaudePluginState(exec) {
+  try {
+    const parsed = JSON.parse(String(exec("claude", ["plugin", "list", "--json"], captureOptions()) ?? ""));
+    if (!Array.isArray(parsed)) throw new Error("plugin list JSON is not an array");
+    const entries = parsed.filter((item) => item?.id === PLUGIN_ID);
+    // Entries of other scopes belong to single projects; only a user-scope entry serves every session.
+    const entry = entries.some((item) => typeof item.scope === "string")
+      ? entries.find((item) => item.scope === "user")
+      : entries[0];
+    return Object.freeze({
+      source: "json",
+      installed: Boolean(entry),
+      version: typeof entry?.version === "string" ? entry.version : "",
+      enabled: entry ? entry.enabled !== false : null,
+      installPath: typeof entry?.installPath === "string" ? entry.installPath : null,
+    });
+  } catch {
+    const output = String(runPluginPhase(exec, "claude", ["plugin", "list"], "verification", captureOptions()) ?? "");
+    const installed = pluginListHasPlugin(output, PLUGIN_ID);
+    return Object.freeze({
+      source: "text_fallback",
+      installed,
+      version: installed ? pluginVersionFromList(output, PLUGIN_ID) : "",
+      enabled: null,
+      installPath: null,
+    });
+  }
+}
+
+// Compares the committed provenance with what Claude Code can load: the marketplace plugin root it
+// serves in place, the installation record every process can read and, whenever Claude Code lists it,
+// the cached copy a copying host serves.
+export function verifyClaudeInstallation({ transaction, pluginState, env = process.env, readRecord = readClaudeInstallationRecord }) {
+  const expected = { source_digest: transaction.sourceDigest, runtime_digest: transaction.runtimeDigest };
+  const observations = [
+    ["marketplace", transaction.pluginRoot ? readInstallationDigests(transaction.pluginRoot) : null],
+    ["record", readRecord({ env })],
+    ...(pluginState?.installPath ? [["cache", readInstallationDigests(pluginState.installPath)]] : []),
+  ].map(([name, observed]) => ({ name, observed, status: compareInstallationProvenance(expected, observed) }));
+  const status = observations.some((item) => item.status === "mismatch") ? "mismatch"
+    : observations.every((item) => item.status === "matched") ? "matched" : "unknown";
+  return Object.freeze({
+    status,
+    evidence: [
+      `installation_verification:${status}`,
+      ...observations.filter((item) => item.status !== "matched").map(({ name, observed, status: itemStatus }) =>
+        `installation_verification:${name}:${itemStatus}:expected=${expected.source_digest}/${expected.runtime_digest}:observed=${observed ? `${observed.source_digest}/${observed.runtime_digest}` : "none"}`),
+    ],
+  });
+}
+
+export function installClaudeGlobalPlugin({
+  exec = execHostFileSync,
+  prepare = prepareLocalMarketplace,
+  dataRoot,
+  recoverCache = recoverClaudeCacheTemp,
+  cacheRecoveryOptions = {},
+  env = process.env,
+  migrateMcp = migrateLegacyClaudeMcpRegistration,
+  prepareMcp = prepareClaudePluginMcp,
+  loadedSessions = loadedClaudeSessions,
+  reconcilePackagedCopies = reconcilePackagedAppMarketplaceCopies,
+  preflight = preflightClaudeInstall,
+  recordInstallation = writeClaudeInstallationRecord,
+  removeInstallationRecord = removeClaudeInstallationRecord,
+  verifyInstallation = verifyClaudeInstallation,
+} = {}) {
+  const expectedVersion = pluginDefinition.version;
+  const preflightEvidence = preflight({ env });
+  const nativeOutput = [];
+  const sessions = loadedSessions({ env });
+  let transaction;
+  try {
+    transaction = prepare({ expectedVersion, ...(dataRoot ? { dataRoot } : {}) });
+  } catch (error) {
+    throw loadedSessionLockHint(error, sessions);
+  }
+  const migration = { state: "unknown", source: "", addedLocal: false, removedLegacy: false };
+  let previousPluginRemoved = false;
+  let pluginInstalled = false;
+  let pluginOperation = "unchanged";
+  let cacheRecovery = null;
+  let after;
+  let installedVersion;
+  let commitResult;
+  const installPlugin = () => {
+    try {
+      nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "install", PLUGIN_ID], "plugin_operation", captureOptions()));
+      pluginInstalled = true;
+    } catch (installError) {
+      cacheRecovery = recoverCache({ error: installError, expectedVersion, ...cacheRecoveryOptions });
+      if (cacheRecovery.status !== "recovered") {
+        installError.evidence = { ...(installError.evidence ?? {}), claude_cache_recovery: cacheRecovery.reason };
+        throw installError;
+      }
+      try {
+        nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "install", PLUGIN_ID], "plugin_operation", captureOptions()));
+        pluginInstalled = true;
+      } catch (retryError) {
+        retryError.evidence = { ...(retryError.evidence ?? {}), claude_cache_recovery: "claude_cache_temp_retry_exhausted" };
+        throw retryError;
+      }
+    }
+  };
+  try {
+    const marketplaceOutput = runPluginPhase(exec, "claude", ["plugin", "marketplace", "list", "--json"], "marketplace", captureOptions());
+    migrateMarketplace({ exec, output: marketplaceOutput, root: transaction.root, nativeOutput, migration });
+    nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "marketplace", "update", "agdf"], "marketplace", captureOptions()));
+    const before = readClaudePluginState(exec);
+    // Claude Code loads the owned directory marketplace in place, but a host that serves its cached copy
+    // sees new content only after a reinstall. Reinstall exactly when that copy does not carry the
+    // committed content or cannot be inspected; an unchanged install then opens no window without plugin.
+    const committed = { source_digest: transaction.sourceDigest, runtime_digest: transaction.runtimeDigest };
+    const cacheCurrent = Boolean(before.installPath)
+      && compareInstallationProvenance(committed, readInstallationDigests(before.installPath)) === "matched";
+    if (!before.installed) {
+      installPlugin();
+      pluginOperation = "installed";
+    } else if (before.version !== expectedVersion || !cacheCurrent) {
+      nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "uninstall", PLUGIN_ID, "--keep-data"], "plugin_operation", captureOptions()));
+      previousPluginRemoved = true;
+      installPlugin();
+      pluginOperation = "reinstalled";
+    }
+    after = readClaudePluginState(exec);
+    installedVersion = after.version;
+    const historicalRebuild = transaction.existingClassification === "owned_supported_historical_rebuild";
+    if ((historicalRebuild && installedVersion !== expectedVersion)
+        || (installedVersion && installedVersion !== expectedVersion)) {
+      throw lifecycleAdapterError("version", versionMismatchMessage("Claude Code", PLUGIN_ID, expectedVersion, installedVersion, "npx --yes @agdf/cli@latest claude"));
+    }
+    commitResult = transaction.commit({ tolerateCleanupFailure: true }) ?? { cleanup: "none" };
+  } catch (error) {
+    recoverMarketplace({ exec, migration, transaction, error, previousPluginRemoved, pluginInstalled });
+    throw error;
+  }
+
+  // From the commit on the new state is what Claude Code serves; every later step reports, none rolls back.
+  const guarded = (operation, fallback) => {
+    try { return operation(); } catch (error) { return fallback(error); }
+  };
+  const recordStatus = transaction.pluginRoot
+    ? guarded(() => {
+      recordInstallation({
+        pluginRoot: transaction.pluginRoot,
+        marketplaceRoot: transaction.root,
+        sourceDigest: transaction.sourceDigest,
+        runtimeDigest: transaction.runtimeDigest,
+        env,
+      });
+      return "written";
+    }, (error) => {
+      // A previous record would now describe another install and make every session report drift.
+      const stale = guarded(() => { removeInstallationRecord({ env }); return "stale_removed"; }, () => "stale_kept");
+      return `failed:${error?.code || "write_failed"}:${stale}`;
+    })
+    : "not_applicable";
+  // Claude Code loads this plugin in place from the marketplace, so a packaged host's private copy of
+  // it would keep serving the previous state to its sessions. Also checked when nothing changed here.
+  const packagedCopies = guarded(
+    () => reconcilePackagedCopies({ root: transaction.root, sourceDigest: transaction.sourceDigest, pluginDigest: transaction.digest, env }),
+    () => null,
+  );
+  const packagedCopiesHealthy = Boolean(packagedCopies) && packagedAppCopiesHealthy(packagedCopies);
+  const verification = guarded(
+    () => verifyInstallation({ transaction, pluginState: after, env }),
+    (error) => ({ status: "unknown", evidence: [`installation_verification:unknown:${error?.code || "check_failed"}`] }),
+  );
+  // Both steps are best effort: the plugin already works, and the launcher installs the MCP runtime
+  // on first start when the prewarm could not run.
+  const mcpEvidence = guarded(() => [
+    ...migrateMcp({ exec, env }),
+    ...(transaction.pluginRoot ? prepareMcp({ exec, env, pluginRoot: transaction.pluginRoot }) : []),
+  ], () => ["claude_plugin_mcp:deferred_to_first_start"]);
+  const cleanupPending = commitResult.cleanup === "pending";
+  // A disabled plugin loads nothing in any session, whatever its files contain.
+  const disabled = after.enabled === false;
+  const healthy = Boolean(installedVersion) && packagedCopiesHealthy && verification.status === "matched"
+    && recordStatus === "written" && !cleanupPending && !disabled;
+  return {
+    surface: "claude",
+    operation: migration.state === "owned_local_current" ? "update" : "install",
+    expectedVersion,
+    installedVersion,
+    verificationStatus: healthy ? "healthy" : "degraded",
+    evidence: [
+      "durable_local_marketplace",
+      `marketplace:${migration.state}`,
+      "claude plugin list",
+      ...preflightEvidence,
+      `plugin_list:${after.source}`,
+      `plugin_operation:${pluginOperation}`,
+      ...(disabled ? ["plugin_enabled:false", "plugin_enable_command:claude plugin enable agdf@agdf"] : []),
+      ...(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),
+      ...loadedSessionEvidence(sessions),
+      ...(cacheRecovery?.status === "recovered" ? ["claude_cache_temp_recovery:bounded_retry"] : []),
+      ...(installedVersion ? [] : ["host_did_not_expose_version"]),
+      `installation_record:${recordStatus}`,
+      ...verification.evidence,
+      ...(cleanupPending ? [`marketplace_cleanup:pending:${commitResult.reason}`] : []),
+      ...(packagedCopies ? packagedAppCopyEvidence(packagedCopies) : ["packaged_app_copy:check_failed"]),
+      ...mcpEvidence,
+    ],
+    packagedAppCopies: packagedCopies,
+    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),
+  };
+}
+
+function migrateMarketplace({ exec, output, root, nativeOutput, migration }) {
+  const classification = classifyMarketplaceList("claude", 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 === "legacy_github") {
+    nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "marketplace", "remove", "agdf", "--scope", "user"], "marketplace", captureOptions()));
+    migration.removedLegacy = true;
+  }
+  if (["absent", "legacy_github"].includes(classification.state)) {
+    nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "marketplace", "add", root, "--scope", "user"], "marketplace", captureOptions()));
+    migration.addedLocal = true;
+  }
+}
+
+function recoverMarketplace({ exec, migration, transaction, error, previousPluginRemoved = false, pluginInstalled = false }) {
+  const recovery = [];
+  const attempt = recoveryAttempt(exec, "claude", recovery);
+  if (migration?.addedLocal) attempt(["plugin", "marketplace", "remove", "agdf", "--scope", "user"]);
+  if (migration?.removedLegacy && migration.source) attempt(["plugin", "marketplace", "add", migration.source, "--scope", "user"]);
+  if (pluginInstalled) attempt(["plugin", "uninstall", PLUGIN_ID, "--keep-data"]);
+  const filesystemRestored = rollbackMarketplaceFilesystem(transaction, recovery);
+  if (previousPluginRemoved && filesystemRestored) attempt(["plugin", "install", PLUGIN_ID]);
+  error.evidence = { ...(error.evidence ?? {}), rollback: recovery };
+}
+
+export function inspectClaudePlugin(exec = execHostFileSync) {
+  return inspectPluginList({ surface: "claude", exec, executable: "claude", args: ["plugin", "list"], expectedVersion: pluginDefinition.version,
+    selectPlugin: () => PLUGIN_ID,
+  });
+}
+
+export const uninstallCommand = () => ({ executable: "claude", args: ["plugin", "uninstall", PLUGIN_ID, "--scope", "user"] });
+
+export const bootstrapCommands = () => ({ install: "npx --yes @agdf/cli@latest claude", repository: "npx --yes @agdf/cli@latest claude-repo" });

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

@@ -0,0 +1,39 @@
+import { existsSync, rmSync } from "node:fs";
+import { ownedRuntimeCheckRules } from "./permission-rules.js";
+import { defaultClaudeSettingsPath, readClaudeSettings, revokeClaudeRuntimeRule } from "../../runtime-check-consent/claude-settings.js";
+import { readRuntimeCheckReceipt } from "../../runtime-check-consent/state.js";
+
+// Claude Code runs plugin hooks whenever the plugin is enabled and needs no permission rule for them,
+// so enabling the AGDF plugin is the runtime-check consent. Nothing is written outside the plugin,
+// which lets `claude plugin uninstall` remove the capability completely.
+export const CLAUDE_PLUGIN_DISABLE_COMMAND = "claude plugin disable agdf@agdf";
+
+export function claudeRuntimeCheckState(requested = "enabled") {
+  return {
+    requested,
+    effective: "enabled",
+    reason: "host_plugin_enablement",
+    capability_identity: null,
+    verification: "host_managed",
+  };
+}
+
+// Earlier releases wrote an exact permission rule and an AGDF receipt; both are removed wherever the
+// CLI touches Claude runtime checks so updates converge on the plugin-only state.
+export function removeLegacyClaudeRuntimeCheckState({ claudeSettingsPath = defaultClaudeSettingsPath(), dataRoot } = {}) {
+  const removed = [];
+  let settings = null;
+  try { settings = readClaudeSettings(claudeSettingsPath).settings; } catch {}
+  for (const rule of ownedRuntimeCheckRules(settings)) {
+    revokeClaudeRuntimeRule({ path: claudeSettingsPath, rule });
+    removed.push("permission_rule");
+  }
+  if (dataRoot) {
+    const receipt = readRuntimeCheckReceipt(dataRoot, "claude");
+    if (receipt.status === "valid" && existsSync(receipt.path)) {
+      rmSync(receipt.path);
+      removed.push("receipt");
+    }
+  }
+  return removed;
+}

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

@@ -0,0 +1,2 @@
+import { environmentSessionCommand } from "../session-command.js";
+export const sessionCommand = (_root, platform) => environmentSessionCommand("claude", platform);

package/lib/host-adapters/claude/uninstall.js

@@ -0,0 +1,80 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import { execHostFileSync } from "../../host-command.js";
+import { captureOptions, commandErrorText } from "../../installers/plugin-command.js";
+import { classifyMarketplaceList, defaultAgdfDataRoot, localMarketplaceRoot } from "../../installers/local-marketplace.js";
+import { defaultClaudeSettingsPath, readClaudeSettings } from "../../runtime-check-consent/claude-settings.js";
+import { readRuntimeCheckReceipt } from "../../runtime-check-consent/state.js";
+import { inspectClaudePlugin, uninstallCommand } from "./plugin.js";
+import { ownedRuntimeCheckRules } from "./permission-rules.js";
+import { ownedFileSnapshot } from "../../lifecycle/owned-mutation.js";
+import { claudeInstallationRecordPath } from "#agdf-core/runtime/host-installation.js";
+
+export { ownedRuntimeCheckRules };
+
+const MARKETPLACE_LIST = ["plugin", "marketplace", "list", "--json"];
+const MARKETPLACE_REMOVE = ["plugin", "marketplace", "remove", "agdf", "--scope", "user"];
+
+function inspectMarketplace(exec, marketplaceRoot) {
+  try {
+    return classifyMarketplaceList("claude", exec("claude", MARKETPLACE_LIST, captureOptions()), marketplaceRoot);
+  } catch (error) {
+    return { state: "unknown", source: "", reason: commandErrorText(error) || "marketplace_list_failed" };
+  }
+}
+
+// Removes every Claude-only AGDF trace that is present and provably AGDF-owned. The marketplace
+// directory is shared with other hosts and the plugin cache belongs to Claude Code, so both are
+// reported as retained instead of deleted; a registration without its directory is what breaks hosts.
+export function planClaudeGlobalUninstall({
+  exec = execHostFileSync, env = process.env, platform = process.platform,
+  claudeSettingsPath = defaultClaudeSettingsPath({ env }),
+} = {}) {
+  const mutations = [];
+  const retained = ["repository AGDF files", ".agdf/control"];
+  if (inspectClaudePlugin(exec).status !== "not_installed") {
+    const command = uninstallCommand();
+    mutations.push({ kind: "command", executable: command.executable, args: command.args });
+  }
+  const marketplaceRoot = localMarketplaceRoot({ env, platform });
+  const marketplace = inspectMarketplace(exec, marketplaceRoot);
+  if (marketplace.state === "owned_local_current") {
+    mutations.push({ kind: "command", executable: "claude", args: MARKETPLACE_REMOVE });
+  } else if (marketplace.state !== "absent") {
+    retained.push(`Claude marketplace registration agdf (${marketplace.reason || marketplace.state})`);
+  }
+  const rules = ownedRuntimeCheckRules(readClaudeSettings(claudeSettingsPath).settings);
+  if (rules.length) mutations.push({ kind: "claude_permission_rules", path: claudeSettingsPath, rules });
+  const receipt = readRuntimeCheckReceipt(defaultAgdfDataRoot({ env, platform }), "claude");
+  if (receipt.status === "valid") mutations.push({ kind: "remove", path: receipt.path, expectedSnapshot: ownedFileSnapshot(receipt.path) });
+  if (existsSync(marketplaceRoot)) retained.push(`shared AGDF marketplace directory (may still serve Codex): ${marketplaceRoot}`);
+  const cacheRoot = join(dirname(claudeSettingsPath), "plugins", "cache", "agdf");
+  if (existsSync(cacheRoot)) retained.push(`Claude Code plugin cache (host-owned): ${cacheRoot}`);
+  const installationRecord = claudeInstallationRecordPath({ env });
+  if (existsSync(installationRecord)) {
+    retained.push(`AGDF installation record in the Claude plugin data (removed by Claude Code with that data): ${installationRecord}`);
+  }
+  return Object.freeze({
+    operation: "uninstall",
+    surface: "claude",
+    scope: "global",
+    mutations: Object.freeze(mutations),
+    retained: Object.freeze(retained),
+    expected: Object.freeze({ installation_status: "not_installed" }),
+    claude: Object.freeze({ marketplaceRoot, claudeSettingsPath, marketplaceRemoval: marketplace.state === "owned_local_current" }),
+  });
+}
+
+export function verifyClaudeGlobalUninstall(plan, { exec = execHostFileSync, inspect = (_surface, run) => inspectClaudePlugin(run) } = {}) {
+  const evidence = [];
+  const plugin = inspect("claude", exec);
+  evidence.push(...(plugin.evidence ?? []));
+  if (plugin.status !== "not_installed") evidence.push(`observed:${plugin.status}`);
+  const marketplace = plan.claude?.marketplaceRemoval ? inspectMarketplace(exec, plan.claude.marketplaceRoot) : { state: "absent" };
+  if (marketplace.state === "owned_local_current") evidence.push("observed:marketplace_registered");
+  const rules = plan.claude ? ownedRuntimeCheckRules(readClaudeSettings(plan.claude.claudeSettingsPath).settings) : [];
+  if (rules.length) evidence.push(`observed:runtime_check_rules:${rules.length}`);
+  const healthy = plugin.status === "not_installed" && marketplace.state !== "owned_local_current" && rules.length === 0;
+  return { status: healthy ? "healthy" : "failed", evidence };
+}

package/lib/host-adapters/codex/config-source.js

@@ -0,0 +1,48 @@
+// A bounded lexical view for the adapter's deliberately narrow TOML readers.
+// Keep UTF-16 offsets and line endings so edits and hashes always use original
+// bytes. Comments and multiline string payloads cannot supply tables, enabled
+// fields or ownership markers. This is not a general TOML parser: unsupported
+// MCP shapes still fail the existing structural/ownership checks.
+export function codexConfigSyntax(content) {
+  if (Buffer.byteLength(content) > 65_536) throw Error('AGDF_MCP_CODEX_CONFIG_INVALID');
+  const syntax = content.split('');
+  const hide = (start, end) => {
+    for (let i = start; i < end; i++) if (content[i] !== '\n' && content[i] !== '\r') syntax[i] = ' ';
+  };
+  for (let i = 0; i < content.length;) {
+    if (content[i] === '#') {
+      const end = content.indexOf('\n', i);
+      hide(i, end < 0 ? content.length : end);
+      i = end < 0 ? content.length : end;
+      continue;
+    }
+    const quote = content[i];
+    if (quote !== '"' && quote !== "'") { i++; continue; }
+    const start = i, multiline = content.startsWith(quote.repeat(3), i);
+    i += multiline ? 3 : 1;
+    let closed = false;
+    while (i < content.length) {
+      if (quote === '"' && content[i] === '\\') {
+        if (!multiline && /[\r\n]/u.test(content[i + 1] ?? '')) throw Error('AGDF_MCP_CODEX_CONFIG_INVALID');
+        i += 2; continue;
+      }
+      if (!multiline && /[\r\n]/u.test(content[i])) throw Error('AGDF_MCP_CODEX_CONFIG_INVALID');
+      if (content[i] !== quote) { i++; continue; }
+      if (!multiline) { i++; closed = true; break; }
+      let end = i;
+      while (content[end] === quote) end++;
+      const count = end - i;
+      if (count > 5) throw Error('AGDF_MCP_CODEX_CONFIG_INVALID');
+      i = end;
+      if (count >= 3) { closed = true; break; }
+    }
+    if (!closed) throw Error('AGDF_MCP_CODEX_CONFIG_INVALID');
+    if (multiline) {
+      hide(start, i);
+      // Keep a non-boolean placeholder so a multiline enabled value is unknown,
+      // rather than mistaken for a missing field with its default value.
+      syntax[start] = quote; syntax[start + 1] = quote;
+    }
+  }
+  return syntax.join('');
+}

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

@@ -0,0 +1,19 @@
+export const CODEX_REGISTRATION_REVISION = 1;
+
+function semverBase(version) {
+  return version.split("+")[0];
+}
+
+export function codexLocalInstallVersion(version, sourceDigest) {
+  if (!/^[a-f0-9]{64}$/.test(sourceDigest)) throw new Error("AGDF local source digest must be a deterministic SHA-256 value.");
+  return `${semverBase(version)}+codex.local-${sourceDigest.slice(0, 12)}`;
+}
+
+export function isCodexLocalInstallVersion(version, candidate, sourceDigest = "") {
+  if (typeof candidate !== "string") return false;
+  if (sourceDigest) return candidate === codexLocalInstallVersion(version, sourceDigest);
+  const escaped = semverBase(version).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped}\\+codex\\.local-[a-f0-9]{12}$`).test(candidate);
+}
+
+export const marketplaceEntries = parsed => parsed?.marketplaces;

package/lib/host-adapters/codex/mcp-startup.js

@@ -0,0 +1,14 @@
+// AGDF-owned CLI sessions need the actual server tool catalog before the first
+// turn. Wait within each existing server startup timeout instead of sampling
+// the optional-server catalog after Codex's one-second grace period. This is
+// an invocation override; it changes no user config, permissions or timeouts.
+export const CODEX_MCP_STARTUP_ARGS = Object.freeze(['-c', 'mcp_optional_startup_grace_ms=0']);
+
+export function independentCodexEnvironment(env) {
+  const result = { ...env };
+  // These identify the invoking session or its connector pipe, not host policy.
+  // Preserve sandbox, network, approval, executable and authentication settings.
+  for (const key of ['CODEX_THREAD_ID', 'CODEX_SESSION_ID', 'CODEX_TOOL_CALL_ID',
+    'CODEX_APP_TOOLS_PIPE_PATH', 'CODEX_INTERNAL_ORIGINATOR_OVERRIDE']) delete result[key];
+  return result;
+}

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

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { runMcpLifecycle } from "../../mcp-lifecycle/service.js";
+import { CODEX_PLUGIN_MCP_FILE } from "#agdf-core/runtime/plugin-provenance.js";
+
+// The AGDF MCP server ships with the Codex runtime plugin (root mcp.json, absolute paths written
+// by the installer). These helpers retire the user-scope registration earlier releases wrote into
+// ~/.codex/config.toml, which `codex plugin remove` never touches and which would share the server
+// name with the plugin, and prewarm the plugin runtime.
+
+const LEGACY_ENTRYPOINT = /[\\/]@agdf[\\/]mcp-server[\\/]bin[\\/]agdf-mcp\.js$/u;
+
+export function migrateLegacyCodexMcpRegistration({ exec, env = process.env, mcpLifecycle = runMcpLifecycle }) {
+  let entry;
+  try { entry = JSON.parse(String(exec("codex", ["mcp", "get", "agdf", "--json"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) ?? "")); } catch { return []; }
+  const args = entry?.transport?.args;
+  // Only the AGDF-owned server registered by earlier releases is migrated; the plugin's own server
+  // starts the plugin-local launcher instead.
+  if (!Array.isArray(args) || args.length !== 3 || !LEGACY_ENTRYPOINT.test(String(args[0]))
+      || args[1] !== "--surface" || args[2] !== "codex") return [];
+  try {
+    const report = mcpLifecycle({ action: "disable", surface: "codex", scope: "user", target: homedir(), env, exec });
+    return [`legacy_user_mcp_registration:${report.result}`];
+  } catch {
+    return ["legacy_user_mcp_registration:retained"];
+  }
+}
+
+export function prepareCodexPluginMcp({ exec, pluginRoot, execPath = process.execPath }) {
+  try {
+    const args = JSON.parse(readFileSync(join(pluginRoot, CODEX_PLUGIN_MCP_FILE), "utf8")).mcpServers.agdf.args;
+    exec(execPath, [...args, "--prepare"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return ["codex_plugin_mcp:prepared"];
+  } catch {
+    return ["codex_plugin_mcp:deferred_to_first_start"];
+  }
+}