thoth-agents 0.3.8 → 0.3.9

package/dist/{chunk-3WNTCPVK.js → chunk-XEEYNMPC.js}

@@ -15,6 +15,7 @@ import {
   createStepBudgetSection,
   ensureConfigDir,
   exa,
+  findPackageRoot,
   generateLiteConfig,
   getAgentOverride,
   getAgentPackContract,
@@ -24,14 +25,16 @@ import {
   getExistingLiteConfigPath,
   getOpenCodeManagedModelStatePath,
   getPrimaryModelId,
+  isValidPackageVersion,
   loadAgentPrompt,
   parseConfig,
   renderPromptSection,
   renderRolePrompt,
+  resolveExecutingPackageVersion,
   updateOpenCodeMainConfig,
   writeConfig,
   writeLiteConfig
-} from "./chunk-F2K4CS5J.js";
+} from "./chunk-2TLT6WWY.js";
 
 // src/cli/codex-paths.ts
 import { homedir } from "os";
@@ -83,7 +86,7 @@ function isExplicitEffort(selection) {
 }
 
 // src/cli/codex-install.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
 import { basename } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
@@ -1540,27 +1543,6 @@ function readManagedModelState(path, version) {
   return parseManagedModelStateJson(readFileSync3(path, "utf8"), version);
 }
 
-// src/cli/package-root.ts
-import { existsSync as existsSync4 } from "fs";
-import { dirname as dirname4, join as join2, parse } from "path";
-function findPackageRoot(startDir) {
-  let currentDir = startDir;
-  const filesystemRoot = parse(startDir).root;
-  while (true) {
-    if (existsSync4(join2(currentDir, "package.json"))) {
-      return currentDir;
-    }
-    if (currentDir === filesystemRoot) {
-      return null;
-    }
-    const parentDir = dirname4(currentDir);
-    if (parentDir === currentDir) {
-      return null;
-    }
-    currentDir = parentDir;
-  }
-}
-
 // src/cli/codex-install.ts
 var ROOT_START = "<!-- thoth-agents:codex-root:start -->";
 var ROOT_END = "<!-- thoth-agents:codex-root:end -->";
@@ -1672,7 +1654,7 @@ function applyCodexManagedModelOverrides(config, overrides) {
           `Missing Codex role TOML content for ${override.role}.`
         );
       }
-      const before = existsSync5(roleItem.targetPath) ? readFileSync4(roleItem.targetPath, "utf8") : roleItem.content;
+      const before = existsSync4(roleItem.targetPath) ? readFileSync4(roleItem.targetPath, "utf8") : roleItem.content;
       const model = normalizeCodexRuntimeModel(override.model);
       let updated = replaceRoleTomlModel(before, model);
       if (override.clearEffort) {
@@ -1725,7 +1707,7 @@ function resolveRoleTomlContent(options) {
     options.nextState.configuredEfforts ??= {};
     options.nextState.configuredEfforts[key] = configuredEffort;
   }
-  if (options.reset || !existsSync5(options.targetPath)) {
+  if (options.reset || !existsSync4(options.targetPath)) {
     options.nextState.models[key] = renderedModel;
     if (configuredModel !== void 0) {
       options.nextState.configuredModels ??= {};
@@ -1799,7 +1781,7 @@ function buildCodexSetupPlan(config) {
         action: "write-role-toml",
         targetPath: target.path,
         description: `Materialize Codex role subagent ${target.role}.`,
-        requiresBackup: existsSync5(target.path),
+        requiresBackup: existsSync4(target.path),
         role: target.role,
         renderedModel: parseRoleTomlModel(
           roleArtifactContent(target.role, render.artifacts)
@@ -1818,7 +1800,7 @@ function buildCodexSetupPlan(config) {
       action: "write-managed-model-state",
       targetPath: targets.managedModelsPath,
       description: "Record thoth-agents-managed Codex role model ownership state.",
-      requiresBackup: existsSync5(targets.managedModelsPath),
+      requiresBackup: existsSync4(targets.managedModelsPath),
       content: stableJson3(nextManagedModelState)
     },
     {
@@ -1885,7 +1867,7 @@ function applyCodexSetup(plan) {
       }
       if (item.content === void 0) continue;
       const content = item.action === "merge-managed-block" ? mergeManagedBlock(
-        existsSync5(item.targetPath) ? readFileSync4(item.targetPath, "utf8") : "",
+        existsSync4(item.targetPath) ? readFileSync4(item.targetPath, "utf8") : "",
         item.content
       ) : item.content;
       if (writeTextWithBackup(item.targetPath, content))
@@ -2473,11 +2455,123 @@ function formatClaudeCodeSetupPlan(plan) {
   return ["Claude Code setup plan:", ...lines].join("\n");
 }
 
-// src/cli/skills.ts
-import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync6 } from "fs";
+// src/cli/install-ledger.ts
+import {
+  copyFileSync as copyFileSync3,
+  existsSync as existsSync5,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync5,
+  renameSync as renameSync2,
+  rmSync,
+  writeFileSync as writeFileSync3
+} from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join3 } from "path";
+import { dirname as dirname4, join as join2 } from "path";
+var INSTALL_LEDGER_SCHEMA_VERSION = 1;
+var INSTALL_HARNESSES = /* @__PURE__ */ new Set([
+  "opencode",
+  "codex",
+  "claude"
+]);
+function hasOnlyKeys(value, keys) {
+  const actual = Object.keys(value);
+  return actual.length === keys.length && actual.every((key) => keys.includes(key));
+}
+function parseInstallLedger(serialized) {
+  let parsed;
+  try {
+    parsed = JSON.parse(serialized);
+  } catch (error) {
+    return { success: false, error: `Malformed install ledger JSON: ${error}` };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { success: false, error: "Install ledger must be a JSON object." };
+  }
+  const root = parsed;
+  if (!hasOnlyKeys(root, ["schemaVersion", "harnesses"]) || root.schemaVersion !== INSTALL_LEDGER_SCHEMA_VERSION || !root.harnesses || typeof root.harnesses !== "object" || Array.isArray(root.harnesses)) {
+    return { success: false, error: "Install ledger schema is unsupported." };
+  }
+  const harnesses = root.harnesses;
+  for (const [harness, value] of Object.entries(harnesses)) {
+    if (!INSTALL_HARNESSES.has(harness) || !value || typeof value !== "object" || Array.isArray(value) || !hasOnlyKeys(value, ["version"]) || !isValidPackageVersion(value.version)) {
+      return {
+        success: false,
+        error: `Install ledger record for ${harness} is invalid.`
+      };
+    }
+  }
+  return { success: true, ledger: parsed };
+}
+function getInstallLedgerPath(options = {}) {
+  const env = options.env ?? process.env;
+  const configuredRoot = env.XDG_CONFIG_HOME?.trim();
+  const homeDir = options.homeDir ?? env.HOME ?? env.USERPROFILE ?? homedir2();
+  const configRoot = options.configRoot ?? (configuredRoot || join2(homeDir, ".config"));
+  return join2(configRoot, "thoth-agents", "install-state.json");
+}
+function readInstallLedger(options = {}) {
+  const path = getInstallLedgerPath(options);
+  if (!existsSync5(path)) return { status: "missing", path };
+  let serialized;
+  try {
+    serialized = readFileSync5(path, "utf8");
+  } catch (error) {
+    return {
+      status: "invalid",
+      path,
+      error: `Could not read install ledger: ${error}`
+    };
+  }
+  const parsed = parseInstallLedger(serialized);
+  return parsed.success ? { status: "valid", path, ledger: parsed.ledger } : { status: "invalid", path, error: parsed.error };
+}
+function recordCompletedInstall(options) {
+  const { harness, version } = options;
+  const path = getInstallLedgerPath(options);
+  if (!INSTALL_HARNESSES.has(harness) || !isValidPackageVersion(version)) {
+    return {
+      success: false,
+      path,
+      error: "A supported harness and valid package version are required."
+    };
+  }
+  const current = readInstallLedger(options);
+  const ledger = {
+    schemaVersion: INSTALL_LEDGER_SCHEMA_VERSION,
+    harnesses: current.status === "valid" ? { ...current.ledger.harnesses } : {}
+  };
+  ledger.harnesses[harness] = { version };
+  const temporaryPath = `${path}.tmp`;
+  const repairedInvalidState = current.status === "invalid";
+  const backupPath = repairedInvalidState ? `${path}.bak` : void 0;
+  try {
+    mkdirSync3(dirname4(path), { recursive: true });
+    writeFileSync3(temporaryPath, `${JSON.stringify(ledger, null, 2)}
+`);
+    if (backupPath) copyFileSync3(path, backupPath);
+    (options.renameFile ?? renameSync2)(temporaryPath, path);
+    return {
+      success: true,
+      path,
+      ledger,
+      repairedInvalidState,
+      ...backupPath ? { backupPath } : {}
+    };
+  } catch (error) {
+    try {
+      rmSync(temporaryPath, { recursive: true, force: true });
+    } catch {
+    }
+    return {
+      success: false,
+      path,
+      error: `Could not record completed install: ${error}`
+    };
+  }
+}
+
+// src/cli/thoth-mem-install.ts
+import { spawnSync as spawnSync2 } from "child_process";
 
 // src/cli/npx-command.ts
 function getNpxCommand(args, options = {}) {
@@ -2490,7 +2584,226 @@ function getNpxCommand(args, options = {}) {
   };
 }
 
+// src/cli/thoth-mem-install.ts
+var THOTH_MEM_SETUP_TIMEOUT_MS = 12e4;
+var STATUS_EXIT_CODE = {
+  complete: 0,
+  failed: 1,
+  partial: 2,
+  requires_user_action: 3
+};
+var SETUP_STATUSES = new Set(
+  Object.keys(STATUS_EXIT_CODE)
+);
+var STEP_OUTCOMES = /* @__PURE__ */ new Set([
+  "planned",
+  "skipped",
+  "confirmed",
+  "failed",
+  "unavailable"
+]);
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isSetupStep(value) {
+  return isRecord4(value) && typeof value.name === "string" && value.name.length > 0 && typeof value.outcome === "string" && STEP_OUTCOMES.has(value.outcome);
+}
+function isProviderSetupResult(value, expectedHarness) {
+  return isRecord4(value) && typeof value.status === "string" && SETUP_STATUSES.has(value.status) && typeof value.changed === "boolean" && value.harness === expectedHarness && value.scope === "global" && typeof value.target === "string" && value.target.length > 0 && Array.isArray(value.steps) && value.steps.every(isSetupStep) && isStringArray(value.diagnostics) && isStringArray(value.manual_actions) && (value.receipt === null || typeof value.receipt === "string");
+}
+function parseProviderSetupResult(stdout, expectedHarness) {
+  let value;
+  try {
+    value = JSON.parse(stdout.trim());
+  } catch {
+    return void 0;
+  }
+  return isProviderSetupResult(value, expectedHarness) ? value : void 0;
+}
+function defaultCommandExecutor2(command, args, options) {
+  const result = spawnSync2(command, [...args], {
+    cwd: options.cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: options.timeoutMs
+  });
+  return {
+    exitCode: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error
+  };
+}
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function isTimeoutError(error) {
+  return isRecord4(error) && error.code === "ETIMEDOUT";
+}
+function invalidResult(harness, command, args, exitCode, error) {
+  return {
+    success: false,
+    evidenceValid: false,
+    status: "invalid",
+    changed: false,
+    harness,
+    steps: [],
+    diagnostics: [],
+    manualActions: [],
+    receipt: null,
+    command,
+    args,
+    exitCode,
+    error
+  };
+}
+function getThothMemSetupCommand(harness, dryRun, options = {}) {
+  return getNpxCommand(
+    [
+      "-y",
+      "thoth-mem@latest",
+      "setup",
+      harness,
+      "--scope",
+      "global",
+      ...dryRun ? ["--plan"] : [],
+      "--json"
+    ],
+    options
+  );
+}
+function runThothMemSetup(options) {
+  const { command, args } = getThothMemSetupCommand(
+    options.harness,
+    options.dryRun ?? false
+  );
+  const executor = options.commandExecutor ?? defaultCommandExecutor2;
+  let commandResult;
+  try {
+    commandResult = executor(command, args, {
+      cwd: options.cwd,
+      timeoutMs: THOTH_MEM_SETUP_TIMEOUT_MS
+    });
+  } catch (error) {
+    return invalidResult(
+      options.harness,
+      command,
+      args,
+      null,
+      `Unable to launch thoth-mem setup: ${describeError(error)}`
+    );
+  }
+  if (commandResult.error) {
+    const stderr = commandResult.stderr.trim().slice(0, 2e3);
+    return invalidResult(
+      options.harness,
+      command,
+      args,
+      commandResult.exitCode,
+      isTimeoutError(commandResult.error) ? `thoth-mem setup timed out after ${THOTH_MEM_SETUP_TIMEOUT_MS} ms${stderr ? `: ${stderr}` : "."}` : `Unable to launch thoth-mem setup: ${describeError(commandResult.error)}`
+    );
+  }
+  const provider = parseProviderSetupResult(
+    commandResult.stdout,
+    options.harness
+  );
+  if (!provider) {
+    const stderr = commandResult.stderr.trim();
+    return invalidResult(
+      options.harness,
+      command,
+      args,
+      commandResult.exitCode,
+      stderr ? `thoth-mem returned invalid JSON evidence: ${stderr.slice(0, 2e3)}` : "thoth-mem returned invalid JSON evidence."
+    );
+  }
+  const expectedExitCode = STATUS_EXIT_CODE[provider.status];
+  const evidenceValid = commandResult.exitCode === expectedExitCode;
+  return {
+    success: evidenceValid && provider.status === "complete",
+    evidenceValid,
+    status: provider.status,
+    changed: provider.changed,
+    harness: provider.harness,
+    target: provider.target,
+    steps: provider.steps,
+    diagnostics: provider.diagnostics,
+    manualActions: provider.manual_actions,
+    receipt: provider.receipt,
+    command,
+    args,
+    exitCode: commandResult.exitCode,
+    ...!evidenceValid ? {
+      error: `thoth-mem exit code ${String(commandResult.exitCode)} contradicts reported status ${provider.status} (expected ${expectedExitCode}).`
+    } : {}
+  };
+}
+
+// src/cli/install-completion.ts
+function isConsistentProviderSuccess(result, harness) {
+  return result.success && result.evidenceValid && result.status === "complete" && result.exitCode === 0 && result.harness === harness;
+}
+function finalizeHarnessInstall(options) {
+  const ledgerPath = getInstallLedgerPath(options.ledgerOptions);
+  const setup = options.runThothMemSetup ?? runThothMemSetup;
+  const provider = setup({
+    harness: options.harness,
+    dryRun: options.dryRun,
+    cwd: options.cwd
+  });
+  if (!isConsistentProviderSuccess(provider, options.harness)) {
+    return {
+      success: false,
+      provider,
+      ledger: { status: "not-attempted", path: ledgerPath },
+      error: provider.error ?? "thoth-mem setup did not return consistent complete evidence."
+    };
+  }
+  if (options.dryRun) {
+    return {
+      success: true,
+      provider,
+      ledger: { status: "planned", path: ledgerPath }
+    };
+  }
+  const record = options.recordCompletedInstall ?? recordCompletedInstall;
+  const ledger = record({
+    ...options.ledgerOptions,
+    harness: options.harness,
+    version: options.version
+  });
+  if (!ledger.success) {
+    return {
+      success: false,
+      provider,
+      ledger: {
+        status: "failed",
+        path: ledger.path,
+        error: ledger.error
+      },
+      error: ledger.error
+    };
+  }
+  return {
+    success: true,
+    provider,
+    ledger: {
+      status: "recorded",
+      path: ledger.path,
+      repairedInvalidState: ledger.repairedInvalidState,
+      ...ledger.backupPath ? { backupPath: ledger.backupPath } : {}
+    }
+  };
+}
+
 // src/cli/skills.ts
+import { spawnSync as spawnSync3 } from "child_process";
+import { existsSync as existsSync6 } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join3 } from "path";
 var SKILLS_CLI_AGENT = {
   opencode: "opencode",
   codex: "codex",
@@ -2530,19 +2843,19 @@ var REQUIRED_SKILLS = [
     description: "Conditional product and architecture decision interview"
   }
 ];
-function getRequiredSkillPaths(skill, harness, homeDir = homedir2()) {
+function getRequiredSkillPaths(skill, harness, homeDir = homedir3()) {
   return GLOBAL_SKILL_ROOTS[harness].map(
     (root) => join3(homeDir, ...root, skill.skillName, "SKILL.md")
   );
 }
-function getRequiredSkillPath(skill, harness, homeDir = homedir2()) {
+function getRequiredSkillPath(skill, harness, homeDir = homedir3()) {
   const [primaryPath] = getRequiredSkillPaths(skill, harness, homeDir);
   if (!primaryPath) {
     throw new Error(`No global skill root is configured for ${harness}.`);
   }
   return primaryPath;
 }
-function getInstalledRequiredSkillPath(skill, harness, homeDir = homedir2()) {
+function getInstalledRequiredSkillPath(skill, harness, homeDir = homedir3()) {
   return getRequiredSkillPaths(skill, harness, homeDir).find(
     (path) => existsSync6(path)
   );
@@ -2585,7 +2898,7 @@ function installRequiredSkill(skill, harness, options = {}) {
     options
   );
   try {
-    const result = spawnSync2(command, args, { stdio: "inherit" });
+    const result = spawnSync3(command, args, { stdio: "inherit" });
     if (result.status === 0) {
       return {
         skill,
@@ -2614,6 +2927,77 @@ function installRequiredSkill(skill, harness, options = {}) {
 }
 
 // src/cli/operations/types.ts
+function getInstallCompletionEvidence(completion, options) {
+  const targets = [
+    {
+      kind: "surface",
+      label: "Provider-owned thoth-mem setup",
+      state: completion.provider.success ? "installed" : "drift",
+      observed: completion.provider.status
+    }
+  ];
+  const warnings = [
+    ...completion.provider.diagnostics.map((message) => ({
+      severity: "minor",
+      code: `${options.codePrefix}-provider-diagnostic`,
+      message
+    })),
+    ...completion.provider.manualActions.map((message) => ({
+      severity: "important",
+      code: `${options.codePrefix}-provider-manual-action`,
+      message
+    }))
+  ];
+  if (completion.provider.receipt) {
+    targets.push({
+      kind: "file",
+      path: completion.provider.receipt,
+      label: "thoth-mem setup receipt",
+      observed: "provider-owned receipt"
+    });
+  }
+  if (completion.success) {
+    targets.push({
+      kind: "file",
+      path: completion.ledger.path,
+      label: "CLI-managed install version",
+      state: "installed",
+      observed: `recorded ${options.version}`
+    });
+  } else {
+    warnings.push({
+      severity: "critical",
+      code: `${options.codePrefix}-install-finalization-failed`,
+      message: completion.error ?? options.fallbackError
+    });
+  }
+  return { targets, warnings };
+}
+function getCliManagedInstallVersionTarget(harness, context2 = {}) {
+  const executing = resolveExecutingPackageVersion();
+  const ledger = readInstallLedger({
+    env: context2.env,
+    homeDir: context2.homeDir
+  });
+  const recordedVersion = ledger.status === "valid" ? ledger.ledger.harnesses[harness]?.version : void 0;
+  let state;
+  if (!executing.ok || ledger.status === "invalid") {
+    state = "unknown";
+  } else if (!recordedVersion) {
+    state = "missing";
+  } else {
+    state = recordedVersion === executing.version ? "installed" : "outdated";
+  }
+  return {
+    kind: "file",
+    path: ledger.path,
+    label: "CLI-managed install version",
+    state,
+    expected: executing.ok ? `executing ${executing.version}` : "executing unknown",
+    observed: ledger.status === "invalid" ? "recorded unknown (invalid ledger)" : recordedVersion ? `recorded ${recordedVersion}` : "recorded missing",
+    description: "Authoritative last complete CLI-managed install version; native marketplace state is independent."
+  };
+}
 var UNSUPPORTED_PROVIDER_CAPABILITY = {
   state: "unsupported",
   source: "none",
@@ -2872,10 +3256,16 @@ function statusFromSetupPlan(plan, context2) {
 }
 function getClaudeCodeStatus(context2 = { cwd: process.cwd() }, evidence = {}) {
   const providerCapability = classifyProviderCapabilityEvidence(evidence);
+  const installVersionTarget = getCliManagedInstallVersionTarget("claude", {
+    env: context2.env,
+    homeDir: context2.homeDir
+  });
   try {
     const plan = buildClaudeCodeSetupPlan(claudeCodeConfig(context2, true));
+    const status = statusFromSetupPlan(plan, context2);
     return {
-      ...statusFromSetupPlan(plan, context2),
+      ...status,
+      targets: [...status.targets, installVersionTarget],
       providerCapability
     };
   } catch (error) {
@@ -2885,7 +3275,7 @@ function getClaudeCodeStatus(context2 = { cwd: process.cwd() }, evidence = {}) {
       displayName: CLAUDE_CODE_DISPLAY_NAME,
       state: "unknown",
       summary: `Claude Code setup plan could not be built: ${message}`,
-      targets: [],
+      targets: [installVersionTarget],
       diagnostics: [
         {
           severity: "critical",
@@ -2907,11 +3297,50 @@ function planItemFromSetup(item) {
     backup: { required: false, strategy: "external" }
   };
 }
-function planFromSetup(id, action, title, summary, setupPlan, context2) {
+function claudeLedgerOptions(context2) {
+  return context2.installLedgerOptions ?? {
+    env: context2.env,
+    homeDir: context2.homeDir
+  };
+}
+function planFromSetup(id, action, title, summary, setupPlan, context2, version) {
   const status = statusFromSetupPlan(setupPlan, context2);
   const missingSkills = status.targets.some(
     (target) => target.kind === "skill" && target.state === "missing"
   );
+  const providerCommand = getThothMemSetupCommand("claude", true);
+  const nativeSetupItems = setupPlan.items.length > 0 ? setupPlan.items.map(planItemFromSetup) : [
+    {
+      title: "Verify Claude Code native marketplace and plugin state",
+      target: {
+        kind: "package",
+        path: setupPlan.pluginRoot,
+        label: "Claude Code native thoth-agents plugin"
+      },
+      preview: "Inspect and verify the canonical marketplace and enabled native plugin.",
+      backup: { required: false, strategy: "external" }
+    }
+  ];
+  const completionItems = version ? [
+    {
+      title: "Plan provider-owned thoth-mem setup for Claude Code",
+      target: {
+        kind: "surface",
+        label: "Provider-owned thoth-mem setup"
+      },
+      preview: `${providerCommand.command} ${providerCommand.args.join(" ")}`
+    },
+    {
+      title: "Record completed Claude Code CLI install",
+      target: {
+        kind: "file",
+        path: getInstallLedgerPath(claudeLedgerOptions(context2)),
+        label: "CLI-managed install version",
+        expected: `recorded ${version}`
+      },
+      preview: JSON.stringify({ harness: "claude", version })
+    }
+  ] : [];
   const plan = {
     id,
     harness: "claude",
@@ -2935,8 +3364,9 @@ function planFromSetup(id, action, title, summary, setupPlan, context2) {
       description: "Claude Code owns its marketplace snapshots and plugin cache."
     },
     items: [
-      ...setupPlan.items.map(planItemFromSetup),
-      claudeCodeRequiredSkillPlanItem()
+      ...nativeSetupItems,
+      claudeCodeRequiredSkillPlanItem(),
+      ...completionItems
     ],
     warnings: status.diagnostics,
     disclaimers: [
@@ -2944,36 +3374,51 @@ function planFromSetup(id, action, title, summary, setupPlan, context2) {
       ...setupPlan.disclaimers.map((message) => ({ message }))
     ]
   };
-  claudeCodePlanSources.set(plan, { setupPlan, context: context2 });
+  claudeCodePlanSources.set(plan, {
+    setupPlan,
+    context: context2,
+    ...version ? { version } : {}
+  });
   return plan;
 }
-function buildClaudeCodeInstallPlan(context2 = { cwd: process.cwd() }) {
-  return planFromSetup(
-    "claude-code-install-preview",
-    "install",
-    "Install Claude Code native plugin",
-    "Preview native marketplace registration, plugin installation, and required skills.",
-    buildClaudeCodeSetupPlan(claudeCodeConfig(context2, true)),
-    context2
+function buildCompleteClaudeCodePlan(action, context2) {
+  const resolveVersion = context2.resolveExecutingPackageVersion ?? resolveExecutingPackageVersion;
+  const packageVersion = resolveVersion();
+  const buildSetup = context2.buildClaudeCodeSetupPlan ?? buildClaudeCodeSetupPlan;
+  const plan = planFromSetup(
+    `claude-code-${action}-preview`,
+    action,
+    `${action === "install" ? "Install" : "Update"} complete Claude Code setup`,
+    "Preview native marketplace/plugin refresh, required skills, provider setup, and CLI ledger commit.",
+    buildSetup(claudeCodeConfig(context2, true, action === "update")),
+    context2,
+    packageVersion.ok ? packageVersion.version : void 0
   );
+  if (!packageVersion.ok) {
+    plan.canApply = false;
+    plan.warnings.push(
+      warning(
+        packageVersion.error.message,
+        "claude-code-package-version-unresolved"
+      )
+    );
+  }
+  return plan;
+}
+function buildClaudeCodeInstallPlan(context2 = { cwd: process.cwd() }) {
+  return buildCompleteClaudeCodePlan("install", context2);
 }
 function buildClaudeCodeUpdatePlan(context2 = { cwd: process.cwd() }) {
-  return planFromSetup(
-    "claude-code-update-preview",
-    "update",
-    "Reconcile Claude Code native plugin",
-    "Preview native marketplace, enabled-plugin, and required-skill reconciliation.",
-    buildClaudeCodeSetupPlan(claudeCodeConfig(context2, true, true)),
-    context2
-  );
+  return buildCompleteClaudeCodePlan("update", context2);
 }
 function buildClaudeCodeSyncPlan(context2 = { cwd: process.cwd() }) {
+  const buildSetup = context2.buildClaudeCodeSetupPlan ?? buildClaudeCodeSetupPlan;
   return planFromSetup(
     "claude-code-sync-preview",
     "sync",
     "Sync Claude Code native plugin",
     "Preview native marketplace, enabled-plugin, and required-skill reconciliation.",
-    buildClaudeCodeSetupPlan(claudeCodeConfig(context2, true)),
+    buildSetup(claudeCodeConfig(context2, true)),
     context2
   );
 }
@@ -3054,12 +3499,24 @@ function applyClaudeCodePlan(plan) {
       "Claude Code setup plan was not produced by a Claude Code operation plan builder in this process."
     );
   }
-  const result = applyClaudeCodeSetup({ ...source.setupPlan, dryRun: false });
+  if (source.version) {
+    const resolveVersion = source.context.resolveExecutingPackageVersion ?? resolveExecutingPackageVersion;
+    const currentVersion = resolveVersion();
+    if (!currentVersion.ok || currentVersion.version !== source.version) {
+      return rejectPlan(
+        plan,
+        currentVersion.ok ? `Approved package version changed from ${source.version} to ${currentVersion.version} before apply.` : currentVersion.error.message
+      );
+    }
+  }
+  const applySetup = source.context.applyClaudeCodeSetup ?? applyClaudeCodeSetup;
+  const result = applySetup({ ...source.setupPlan, dryRun: false });
   const requiredSkillWarnings = [];
   const requiredSkillTargets = [];
   if (result.success) {
+    const installSkill = source.context.installRequiredSkill ?? installRequiredSkill;
     for (const skill of REQUIRED_SKILLS) {
-      const installed = installRequiredSkill(skill, "claude", {
+      const installed = installSkill(skill, "claude", {
         homeDir: source.context.homeDir
       });
       const success2 = installed.status !== "failed";
@@ -3079,37 +3536,63 @@ function applyClaudeCodePlan(plan) {
       }
     }
   }
-  const success = result.success && requiredSkillWarnings.length === 0;
+  let success = result.success && requiredSkillWarnings.length === 0;
   let summary = result.error ?? `Failed to apply Claude Code ${plan.action} plan.`;
   if (success) {
     summary = `Applied Claude Code native ${plan.action} plan.`;
   } else if (requiredSkillWarnings.length > 0) {
     summary = "Claude Code plugin was installed, but required skills failed to install.";
   }
+  const changedTargets = [
+    ...result.changed.map((path) => ({
+      kind: "package",
+      path,
+      label: path.includes("/marketplaces/") ? "Claude Code marketplace" : "Claude Code plugin",
+      state: "installed"
+    })),
+    ...requiredSkillTargets
+  ];
+  const warnings = [
+    ...requiredSkillWarnings,
+    ...result.success ? [] : [
+      {
+        severity: "critical",
+        message: result.error ?? "apply failed."
+      }
+    ]
+  ];
+  if (success && source.version && plan.action !== "sync") {
+    const finalize = source.context.finalizeHarnessInstall ?? finalizeHarnessInstall;
+    const completion = finalize({
+      harness: "claude",
+      version: source.version,
+      dryRun: false,
+      cwd: source.context.cwd,
+      runThothMemSetup: source.context.runThothMemSetup,
+      ledgerOptions: claudeLedgerOptions(source.context)
+    });
+    const completionEvidence = getInstallCompletionEvidence(completion, {
+      codePrefix: "claude-code",
+      version: source.version,
+      fallbackError: "Claude Code install finalization failed."
+    });
+    warnings.push(...completionEvidence.warnings);
+    changedTargets.push(...completionEvidence.targets);
+    if (completion.success) {
+      summary = `Applied complete Claude Code ${plan.action} plan.`;
+    } else {
+      success = false;
+      summary = completion.error ?? "Claude Code install finalization failed.";
+    }
+  }
   return {
     harness: "claude",
     action: plan.action,
     applied: success,
     summary,
-    changedTargets: [
-      ...result.changed.map((path) => ({
-        kind: "package",
-        path,
-        label: path.includes("/marketplaces/") ? "Claude Code marketplace" : "Claude Code plugin",
-        state: "installed"
-      })),
-      ...requiredSkillTargets
-    ],
+    changedTargets,
     backups: [],
-    warnings: [
-      ...requiredSkillWarnings,
-      ...result.success ? [] : [
-        {
-          severity: "critical",
-          message: result.error ?? "apply failed."
-        }
-      ]
-    ],
+    warnings,
     disclaimers: claudeCodeDisclaimers()
   };
 }
@@ -3121,8 +3604,245 @@ function defaultClaudeCodeModelRoles() {
 }
 
 // src/cli/operations/codex.ts
-import { existsSync as existsSync8, readFileSync as readFileSync5 } from "fs";
-import { basename as basename2 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync6 } from "fs";
+import { basename as basename2 } from "path";
+
+// src/cli/codex-plugin-install.ts
+import { spawnSync as spawnSync4 } from "child_process";
+var MARKETPLACE_NAME2 = "thoth-agents";
+var MARKETPLACE_SOURCE2 = "EremesNG/thoth-agents";
+var PLUGIN_ID2 = "thoth-agents@thoth-agents";
+var MARKETPLACE_TARGET2 = "codex://marketplaces/thoth-agents";
+var PLUGIN_TARGET2 = "codex://plugins/thoth-agents@thoth-agents";
+function getCodexCommand(args, options = {}) {
+  if ((options.platform ?? process.platform) !== "win32") {
+    return { command: "codex", args: [...args] };
+  }
+  return {
+    command: options.commandShell ?? process.env.ComSpec ?? "cmd.exe",
+    args: ["/d", "/s", "/c", "codex", ...args]
+  };
+}
+function defaultCommandExecutor3(command, args, options) {
+  const invocation = command === "codex" ? getCodexCommand(args) : { command, args: [...args] };
+  const result = spawnSync4(invocation.command, invocation.args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true
+  });
+  return {
+    exitCode: result.status ?? (result.error ? 1 : 0),
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? result.error?.message ?? ""
+  };
+}
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseRecordArray(value) {
+  return Array.isArray(value) && value.every(isRecord5) ? value : null;
+}
+function parseManagerRecord(content) {
+  try {
+    const parsed = JSON.parse(content);
+    return isRecord5(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function normalizeMarketplaceSource(value) {
+  return value.trim().replace(/^git@github\.com:/i, "").replace(/^(?:https?|ssh):\/\/(?:git@)?github\.com\//i, "").replace(/^github\.com\//i, "").replace(/\/?\.git\/?$/i, "").replace(/\/$/, "").toLowerCase();
+}
+function marketplaceSources(entry) {
+  const sources = [entry.repo, entry.source];
+  if (isRecord5(entry.marketplaceSource)) {
+    sources.push(entry.marketplaceSource.repo, entry.marketplaceSource.source);
+  }
+  return sources.filter(
+    (source) => typeof source === "string"
+  );
+}
+function isCanonicalMarketplace2(entry) {
+  if (entry.name !== MARKETPLACE_NAME2) return false;
+  const canonical = MARKETPLACE_SOURCE2.toLowerCase();
+  return marketplaceSources(entry).some(
+    (source) => normalizeMarketplaceSource(source) === canonical
+  );
+}
+function inspectCodexManager(executor, cwd) {
+  const marketplaceResult = executor(
+    "codex",
+    ["plugin", "marketplace", "list", "--json"],
+    { cwd }
+  );
+  const pluginResult = executor(
+    "codex",
+    ["plugin", "list", "--available", "--json"],
+    { cwd }
+  );
+  const diagnostics = [];
+  if (marketplaceResult.exitCode !== 0 || pluginResult.exitCode !== 0) {
+    diagnostics.push(
+      "Codex native plugin state could not be inspected; no manager mutation will be attempted."
+    );
+    return {
+      ready: false,
+      marketplace: "unknown",
+      plugin: "unknown",
+      diagnostics
+    };
+  }
+  const marketplaceRecord = parseManagerRecord(marketplaceResult.stdout);
+  const pluginRecord = parseManagerRecord(pluginResult.stdout);
+  const marketplaces = marketplaceRecord ? parseRecordArray(marketplaceRecord.marketplaces) : null;
+  const installedPlugins = pluginRecord ? parseRecordArray(pluginRecord.installed) : null;
+  if (!marketplaces || !installedPlugins) {
+    diagnostics.push(
+      "Codex returned unparseable plugin manager JSON; no manager mutation will be attempted."
+    );
+    return {
+      ready: false,
+      marketplace: "unknown",
+      plugin: "unknown",
+      diagnostics
+    };
+  }
+  const namedMarketplaces = marketplaces.filter(
+    (entry) => entry.name === MARKETPLACE_NAME2
+  );
+  let marketplace = "absent";
+  if (namedMarketplaces.length > 0) {
+    marketplace = namedMarketplaces.every(isCanonicalMarketplace2) ? "installed" : "conflict";
+  }
+  if (marketplace === "conflict") {
+    diagnostics.push(
+      "A Codex marketplace named thoth-agents is registered from a different source; resolve it through Codex before retrying."
+    );
+  }
+  const matchingPlugins = installedPlugins.filter(
+    (entry) => entry.pluginId === PLUGIN_ID2
+  );
+  let plugin = "absent";
+  if (matchingPlugins.some((entry) => entry.enabled === true)) {
+    plugin = "installed";
+  } else if (matchingPlugins.length > 0) {
+    plugin = "disabled";
+  }
+  return {
+    ready: marketplace !== "conflict",
+    marketplace,
+    plugin,
+    diagnostics
+  };
+}
+function commandItem2(action, projectRoot) {
+  if (action === "register-marketplace") {
+    return {
+      action,
+      targetPath: MARKETPLACE_TARGET2,
+      description: "Register the package-owned thoth-agents Codex marketplace.",
+      command: {
+        executable: "codex",
+        args: ["plugin", "marketplace", "add", MARKETPLACE_SOURCE2, "--json"],
+        cwd: projectRoot
+      }
+    };
+  }
+  return {
+    action,
+    targetPath: PLUGIN_TARGET2,
+    description: "Install and enable the thoth-agents Codex plugin from its native marketplace.",
+    command: {
+      executable: "codex",
+      args: ["plugin", "add", PLUGIN_ID2, "--json"],
+      cwd: projectRoot
+    }
+  };
+}
+function buildCodexPluginSetupPlan(config) {
+  const commandExecutor = config.commandExecutor ?? defaultCommandExecutor3;
+  const inspection = inspectCodexManager(commandExecutor, config.projectRoot);
+  const items = [];
+  if (inspection.ready) {
+    if (inspection.marketplace === "absent") {
+      items.push(commandItem2("register-marketplace", config.projectRoot));
+    }
+    if (inspection.plugin === "absent" || inspection.plugin === "disabled") {
+      items.push(commandItem2("install-plugin", config.projectRoot));
+    }
+  }
+  return {
+    dryRun: config.dryRun === true,
+    items,
+    ready: inspection.ready,
+    projectRoot: config.projectRoot,
+    commandExecutor,
+    diagnostics: [
+      ...inspection.diagnostics,
+      "Codex installs thoth-agents from EremesNG/thoth-agents through its native plugin manager and owns the cached plugin files.",
+      "Restart Codex after installation; use /plugins to inspect marketplace and plugin state."
+    ]
+  };
+}
+function uniqueMessages3(messages) {
+  return [...new Set(messages)];
+}
+function boundedCommandFailure2(item, result) {
+  const detail = result.stderr.trim().replace(/\s+/g, " ").slice(0, 240);
+  return `${item.description} Codex exited with code ${result.exitCode}${detail ? `: ${detail}` : "."}`;
+}
+function applyCodexPluginSetup(plan) {
+  const changed = [];
+  const diagnostics = uniqueMessages3(plan.diagnostics);
+  if (!plan.ready) {
+    return {
+      success: false,
+      changed,
+      diagnostics,
+      error: "Codex native plugin manager state is not safe to mutate."
+    };
+  }
+  if (plan.dryRun) return { success: true, changed, diagnostics };
+  for (const item of plan.items) {
+    const result = plan.commandExecutor(
+      item.command.executable,
+      item.command.args,
+      { cwd: item.command.cwd }
+    );
+    if (result.exitCode !== 0) {
+      return {
+        success: false,
+        changed,
+        diagnostics,
+        error: boundedCommandFailure2(item, result)
+      };
+    }
+    changed.push(item.targetPath);
+  }
+  const inspection = inspectCodexManager(
+    plan.commandExecutor,
+    plan.projectRoot
+  );
+  diagnostics.push(...inspection.diagnostics);
+  if (inspection.marketplace !== "installed" || inspection.plugin !== "installed") {
+    return {
+      success: false,
+      changed,
+      diagnostics: uniqueMessages3(diagnostics),
+      error: "Codex did not verify the expected marketplace and enabled plugin after mutation."
+    };
+  }
+  return { success: true, changed, diagnostics: uniqueMessages3(diagnostics) };
+}
+function formatCodexPluginSetupPlan(plan) {
+  const lines = plan.items.map(
+    (item) => `- ${item.action}: ${item.command.executable} ${item.command.args.join(" ")}`
+  );
+  return ["Codex plugin setup plan:", ...lines].join("\n");
+}
+
+// src/cli/operations/codex.ts
 var CODEX_DISPLAY_NAME = "Codex";
 var codexPlanSources = /* @__PURE__ */ new WeakMap();
 var codexModelSources = /* @__PURE__ */ new WeakMap();
@@ -3245,7 +3965,7 @@ function backupForItem(item) {
 function rootBlockState(item) {
   if (!existsSync8(item.targetPath))
     return { state: "missing", observed: "absent" };
-  const content = readFileSync5(item.targetPath, "utf8");
+  const content = readFileSync6(item.targetPath, "utf8");
   if (item.content && content.includes(item.content)) {
     return { state: "installed", observed: "managed root block present" };
   }
@@ -3258,11 +3978,11 @@ function managedModelState(item) {
   if (!existsSync8(item.targetPath))
     return { state: "missing", observed: "absent" };
   try {
-    const parsed = JSON.parse(readFileSync5(item.targetPath, "utf8"));
+    const parsed = JSON.parse(readFileSync6(item.targetPath, "utf8"));
     if (parsed.version !== MANAGED_MODEL_STATE_VERSION || !parsed.models || typeof parsed.models !== "object" || Array.isArray(parsed.models)) {
       return { state: "unknown", observed: "invalid managed model state" };
     }
-    return item.content === readFileSync5(item.targetPath, "utf8") ? { state: "installed", observed: "managed model state current" } : { state: "drift", observed: "managed model state differs" };
+    return item.content === readFileSync6(item.targetPath, "utf8") ? { state: "installed", observed: "managed model state current" } : { state: "drift", observed: "managed model state differs" };
   } catch {
     return { state: "unknown", observed: "unparseable managed model state" };
   }
@@ -3270,7 +3990,7 @@ function managedModelState(item) {
 function userConfigState(item) {
   if (!existsSync8(item.targetPath))
     return { state: "missing", observed: "absent" };
-  const content = readFileSync5(item.targetPath, "utf8");
+  const content = readFileSync6(item.targetPath, "utf8");
   if (/^\s*default_mode_request_user_input\s*=\s*true\b/m.test(content)) {
     return {
       state: "installed",
@@ -3285,7 +4005,7 @@ function userConfigState(item) {
 function contentState(item) {
   if (!existsSync8(item.targetPath))
     return { state: "missing", observed: "absent" };
-  const observed = readFileSync5(item.targetPath, "utf8");
+  const observed = readFileSync6(item.targetPath, "utf8");
   if (item.content === observed)
     return { state: "installed", observed: "current" };
   if (item.role) {
@@ -3376,6 +4096,10 @@ function codexRequiredSkillPlanItem() {
 }
 function getCodexStatus(context2 = { cwd: process.cwd() }, evidence = {}) {
   const providerCapability = classifyProviderCapabilityEvidence(evidence);
+  const installVersionTarget = getCliManagedInstallVersionTarget("codex", {
+    env: context2.env,
+    homeDir: context2.homeDir
+  });
   let plan;
   try {
     plan = buildCodexSetupPlan(codexConfig(context2, true));
@@ -3386,7 +4110,7 @@ function getCodexStatus(context2 = { cwd: process.cwd() }, evidence = {}) {
       displayName: CODEX_DISPLAY_NAME,
       state: "unknown",
       summary: `Codex setup plan could not be built: ${message}`,
-      targets: [],
+      targets: [installVersionTarget],
       diagnostics: [
         {
           severity: "critical",
@@ -3420,7 +4144,8 @@ function getCodexStatus(context2 = { cwd: process.cwd() }, evidence = {}) {
       ...classified.map(
         ({ item, state: state2, observed }) => targetForItem2(item, state2, observed)
       ),
-      ...requiredSkills.targets
+      ...requiredSkills.targets,
+      installVersionTarget
     ],
     diagnostics,
     actions: codexActions,
@@ -3439,9 +4164,62 @@ function planItemFromSetup2(item) {
     backup: backupForItem(item)
   };
 }
-function planFromSetup2(id, action, title, summary, setupPlan, context2) {
+function planItemFromPluginSetup(item) {
+  return {
+    title: item.description,
+    target: {
+      kind: "package",
+      path: item.targetPath,
+      label: "Codex native plugin manager target"
+    },
+    preview: `${item.command.executable} ${item.command.args.join(" ")}`,
+    backup: { required: false, strategy: "external" }
+  };
+}
+function codexLedgerOptions(context2) {
+  return context2.installLedgerOptions ?? {
+    env: context2.env,
+    homeDir: context2.homeDir
+  };
+}
+function planFromSetup2(id, action, title, summary, setupPlan, context2, completion) {
   const status = getCodexStatus(context2);
-  const canApply = status.state === "installed" || status.state === "missing" || status.state === "outdated";
+  const canApply = (status.state === "installed" || status.state === "missing" || status.state === "outdated") && (completion?.pluginPlan.ready ?? true);
+  const providerCommand = getThothMemSetupCommand("codex", true);
+  const nativePluginItems = completion ? completion.pluginPlan.items.length > 0 ? completion.pluginPlan.items.map(planItemFromPluginSetup) : [
+    {
+      title: "Verify Codex native plugin manager state",
+      target: {
+        kind: "package",
+        label: "Codex native thoth-agents plugin"
+      },
+      preview: "Inspect and post-verify the canonical thoth-agents marketplace and enabled plugin.",
+      backup: { required: false, strategy: "external" }
+    }
+  ] : [];
+  const completionItems = completion ? [
+    {
+      title: "Plan provider-owned thoth-mem setup for Codex",
+      target: {
+        kind: "surface",
+        label: "Provider-owned thoth-mem setup"
+      },
+      preview: `${providerCommand.command} ${providerCommand.args.join(" ")}`
+    },
+    {
+      title: "Record completed Codex CLI install",
+      target: {
+        kind: "file",
+        path: getInstallLedgerPath(codexLedgerOptions(context2)),
+        label: "CLI-managed install version",
+        expected: `recorded ${completion.version}`
+      },
+      preview: JSON.stringify({
+        harness: "codex",
+        version: completion.version
+      })
+    }
+  ] : [];
   const plan = {
     id,
     harness: "codex",
@@ -3458,8 +4236,10 @@ function planFromSetup2(id, action, title, summary, setupPlan, context2) {
       description: "Codex setup apply uses the existing installer backup behavior for files that already exist."
     },
     items: [
+      ...nativePluginItems,
       ...setupPlan.items.map(planItemFromSetup2),
-      codexRequiredSkillPlanItem()
+      codexRequiredSkillPlanItem(),
+      ...completionItems
     ],
     warnings: [
       ...status.diagnostics,
@@ -3475,22 +4255,59 @@ function planFromSetup2(id, action, title, summary, setupPlan, context2) {
       ...setupPlan.disclaimers.map((message) => ({ message }))
     ]
   };
-  codexPlanSources.set(plan, { setupPlan, context: context2 });
+  codexPlanSources.set(plan, {
+    setupPlan,
+    context: context2,
+    ...completion ? {
+      pluginPlan: completion.pluginPlan,
+      version: completion.version
+    } : {}
+  });
   return plan;
 }
-function buildCodexUpdatePlan(context2 = { cwd: process.cwd() }) {
-  const setupPlan = buildCodexSetupPlan(codexConfig(context2, true));
-  return planFromSetup2(
-    "codex-update-preview",
-    "update",
-    "Update Codex managed setup",
-    "Preview Codex managed setup refresh using buildCodexSetupPlan().",
+function buildCompleteCodexPlan(action, context2) {
+  const resolveVersion = context2.resolveExecutingPackageVersion ?? resolveExecutingPackageVersion;
+  const packageVersion = resolveVersion();
+  const buildPlugin = context2.buildCodexPluginSetupPlan ?? buildCodexPluginSetupPlan;
+  const pluginPlan = buildPlugin({
+    dryRun: true,
+    projectRoot: context2.cwd,
+    commandExecutor: context2.codexPluginCommandExecutor
+  });
+  const buildSetup = context2.buildCodexSetupPlan ?? buildCodexSetupPlan;
+  const setupPlan = buildSetup(codexConfig(context2, true));
+  const plan = planFromSetup2(
+    `codex-${action}-preview`,
+    action,
+    `${action === "install" ? "Install" : "Update"} complete Codex setup`,
+    `Preview Codex native plugin, global agent pack, required skills, provider setup, and CLI ledger ${action}.`,
     setupPlan,
-    context2
+    context2,
+    packageVersion.ok ? { pluginPlan, version: packageVersion.version } : void 0
   );
+  if (!packageVersion.ok) {
+    plan.canApply = false;
+    plan.warnings.push(
+      warning2(packageVersion.error.message, "codex-package-version-unresolved")
+    );
+  }
+  if (!pluginPlan.ready) {
+    plan.canApply = false;
+    plan.warnings.push(
+      warning2(
+        "Codex native plugin manager state is not safe to mutate.",
+        "codex-native-plugin-not-ready"
+      )
+    );
+  }
+  return plan;
+}
+function buildCodexUpdatePlan(context2 = { cwd: process.cwd() }) {
+  return buildCompleteCodexPlan("update", context2);
 }
 function buildCodexSyncPlan(context2 = { cwd: process.cwd() }) {
-  const setupPlan = buildCodexSetupPlan(codexConfig(context2, true));
+  const buildSetup = context2.buildCodexSetupPlan ?? buildCodexSetupPlan;
+  const setupPlan = buildSetup(codexConfig(context2, true));
   return planFromSetup2(
     "codex-sync-preview",
     "sync",
@@ -3501,15 +4318,7 @@ function buildCodexSyncPlan(context2 = { cwd: process.cwd() }) {
   );
 }
 function buildCodexInstallPlan(context2 = { cwd: process.cwd() }) {
-  const setupPlan = buildCodexSetupPlan(codexConfig(context2, true));
-  return planFromSetup2(
-    "codex-install-preview",
-    "install",
-    "Install Codex managed setup",
-    "Preview Codex managed agent-pack setup using buildCodexSetupPlan().",
-    setupPlan,
-    context2
-  );
+  return buildCompleteCodexPlan("install", context2);
 }
 function normalizeCodexModel(input) {
   return normalizeCodexRuntimeModel(input.model);
@@ -3721,12 +4530,66 @@ function applyCodexPlan(plan) {
       "Codex setup plan was not produced by a Codex operation plan builder in this process."
     );
   }
-  const result = applyCodexSetup({ ...source.setupPlan, dryRun: false });
+  if (source.version) {
+    const resolveVersion = source.context.resolveExecutingPackageVersion ?? resolveExecutingPackageVersion;
+    const currentVersion = resolveVersion();
+    if (!currentVersion.ok || currentVersion.version !== source.version) {
+      return rejectPlan2(
+        plan,
+        currentVersion.ok ? `Approved package version changed from ${source.version} to ${currentVersion.version} before apply.` : currentVersion.error.message
+      );
+    }
+  }
+  const changedTargets = [];
+  const warnings = [];
+  if (source.pluginPlan) {
+    const applyPlugin = source.context.applyCodexPluginSetup ?? applyCodexPluginSetup;
+    const nativeResult = applyPlugin({
+      ...source.pluginPlan,
+      dryRun: false
+    });
+    warnings.push(
+      ...nativeResult.diagnostics.map((message) => ({
+        severity: "minor",
+        code: "codex-native-plugin-diagnostic",
+        message
+      }))
+    );
+    changedTargets.push(
+      ...nativeResult.changed.map((path) => ({
+        kind: "package",
+        path,
+        label: "Codex native plugin manager target",
+        state: "installed"
+      }))
+    );
+    if (!nativeResult.success) {
+      const message = nativeResult.error ?? "Codex native plugin setup failed.";
+      warnings.push({
+        severity: "critical",
+        code: "codex-native-plugin-failed",
+        message
+      });
+      return {
+        harness: "codex",
+        action: plan.action,
+        applied: false,
+        summary: message,
+        changedTargets,
+        backups: [],
+        warnings,
+        disclaimers: codexDisclaimers()
+      };
+    }
+  }
+  const applySetup = source.context.applyCodexSetup ?? applyCodexSetup;
+  const result = applySetup({ ...source.setupPlan, dryRun: false });
   const requiredSkillWarnings = [];
   const requiredSkillTargets = [];
   if (result.success) {
+    const installSkill = source.context.installRequiredSkill ?? installRequiredSkill;
     for (const skill of REQUIRED_SKILLS) {
-      const installed = installRequiredSkill(skill, "codex", {
+      const installed = installSkill(skill, "codex", {
         homeDir: source.context.homeDir
       });
       const success2 = installed.status !== "failed";
@@ -3746,31 +4609,56 @@ function applyCodexPlan(plan) {
       }
     }
   }
-  const success = result.success && requiredSkillWarnings.length === 0;
+  let success = result.success && requiredSkillWarnings.length === 0;
+  let summary = success ? `Applied Codex managed ${plan.action} plan.` : requiredSkillWarnings.length > 0 ? `Codex setup was written, but required skills failed to install.` : result.error ?? `Failed to apply Codex ${plan.action} plan.`;
+  warnings.push(...requiredSkillWarnings);
+  if (!result.success) {
+    warnings.push({
+      severity: "critical",
+      message: result.error ?? "Codex setup apply failed."
+    });
+  }
+  changedTargets.push(
+    ...result.changed.map((path) => ({
+      kind: path.endsWith(".json") ? "memory-state" : "generated-artifact",
+      path,
+      label: basename2(path),
+      state: "installed"
+    })),
+    ...requiredSkillTargets
+  );
+  if (success && source.version && plan.action !== "sync") {
+    const finalize = source.context.finalizeHarnessInstall ?? finalizeHarnessInstall;
+    const completion = finalize({
+      harness: "codex",
+      version: source.version,
+      dryRun: false,
+      cwd: source.context.cwd,
+      runThothMemSetup: source.context.runThothMemSetup,
+      ledgerOptions: codexLedgerOptions(source.context)
+    });
+    const completionEvidence = getInstallCompletionEvidence(completion, {
+      codePrefix: "codex",
+      version: source.version,
+      fallbackError: "Codex install finalization failed."
+    });
+    warnings.push(...completionEvidence.warnings);
+    changedTargets.push(...completionEvidence.targets);
+    if (completion.success) {
+      summary = `Applied complete Codex ${plan.action} plan.`;
+    } else {
+      success = false;
+      summary = completion.error ?? "Codex install finalization failed.";
+    }
+  }
   return {
     harness: "codex",
     action: plan.action,
     applied: success,
-    summary: success ? `Applied Codex managed ${plan.action} plan.` : requiredSkillWarnings.length > 0 ? `Codex setup was written, but required skills failed to install.` : result.error ?? `Failed to apply Codex ${plan.action} plan.`,
-    changedTargets: [
-      ...result.changed.map((path) => ({
-        kind: path.endsWith(".json") ? "memory-state" : "generated-artifact",
-        path,
-        label: basename2(path),
-        state: "installed"
-      })),
-      ...requiredSkillTargets
-    ],
+    summary,
+    changedTargets,
     backups: result.changed.filter((path) => existsSync8(`${path}.bak`)).map((path) => ({ path: `${path}.bak`, label: "managed backup" })),
-    warnings: [
-      ...requiredSkillWarnings,
-      ...result.success ? [] : [
-        {
-          severity: "critical",
-          message: result.error ?? "Codex setup apply failed."
-        }
-      ]
-    ],
+    warnings,
     disclaimers: codexDisclaimers()
   };
 }
@@ -3814,13 +4702,13 @@ function resolveOpenCodeEffort(input) {
 import {
   cpSync,
   existsSync as existsSync9,
-  mkdirSync as mkdirSync3,
+  mkdirSync as mkdirSync4,
   mkdtempSync,
-  renameSync as renameSync2,
-  rmSync,
+  renameSync as renameSync3,
+  rmSync as rmSync2,
   statSync
 } from "fs";
-import { homedir as homedir3 } from "os";
+import { homedir as homedir4 } from "os";
 import { dirname as dirname5, join as join4 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 
@@ -3848,7 +4736,7 @@ function defaultPackageRoot() {
 }
 function getOpenCodeOwnedSkillEntries(options = {}) {
   const packageRoot = options.packageRoot ?? defaultPackageRoot();
-  const homeDir = options.homeDir ?? homedir3();
+  const homeDir = options.homeDir ?? homedir4();
   return THOTH_OWNED_SKILL_NAMES.map((name) => ({
     name,
     sourcePath: join4(packageRoot, "skills", name),
@@ -3870,12 +4758,12 @@ function installOwnedSkills(skills) {
   const firstSkill = skills[0];
   if (!firstSkill) return;
   const globalRoot = dirname5(firstSkill.destinationPath);
-  mkdirSync3(globalRoot, { recursive: true });
+  mkdirSync4(globalRoot, { recursive: true });
   const transactionRoot = mkdtempSync(join4(globalRoot, ".thoth-agents-owned-"));
   const stagedRoot = join4(transactionRoot, "staged");
   const backupRoot = join4(transactionRoot, "backup");
-  mkdirSync3(stagedRoot, { recursive: true });
-  mkdirSync3(backupRoot, { recursive: true });
+  mkdirSync4(stagedRoot, { recursive: true });
+  mkdirSync4(backupRoot, { recursive: true });
   try {
     for (const skill of skills) {
       cpSync(skill.sourcePath, join4(stagedRoot, skill.name), {
@@ -3888,25 +4776,25 @@ function installOwnedSkills(skills) {
       const backupPath = join4(backupRoot, skill.name);
       const hadExistingDestination = existsSync9(skill.destinationPath);
       if (hadExistingDestination) {
-        renameSync2(skill.destinationPath, backupPath);
+        renameSync3(skill.destinationPath, backupPath);
       }
       try {
-        renameSync2(stagedPath, skill.destinationPath);
+        renameSync3(stagedPath, skill.destinationPath);
       } catch (error) {
         if (existsSync9(skill.destinationPath)) {
-          rmSync(skill.destinationPath, { recursive: true, force: true });
+          rmSync2(skill.destinationPath, { recursive: true, force: true });
         }
         if (hadExistingDestination && existsSync9(backupPath)) {
-          renameSync2(backupPath, skill.destinationPath);
+          renameSync3(backupPath, skill.destinationPath);
         }
         throw error;
       }
       if (existsSync9(backupPath)) {
-        rmSync(backupPath, { recursive: true, force: true });
+        rmSync2(backupPath, { recursive: true, force: true });
       }
     }
   } finally {
-    rmSync(transactionRoot, { recursive: true, force: true });
+    rmSync2(transactionRoot, { recursive: true, force: true });
   }
 }
 function syncOpenCodeOwnedSkills(options = {}) {
@@ -3928,7 +4816,8 @@ function syncOpenCodeOwnedSkills(options = {}) {
 
 // src/cli/operations/opencode.ts
 var PACKAGE_NAME = "thoth-agents";
-var EXPECTED_PLUGIN = `${PACKAGE_NAME}@latest`;
+var EXECUTING_PACKAGE_VERSION = resolveExecutingPackageVersion();
+var EXPECTED_PLUGIN = EXECUTING_PACKAGE_VERSION.ok ? `${PACKAGE_NAME}@${EXECUTING_PACKAGE_VERSION.version}` : null;
 var OPENAI_PRESET = "openai";
 var APPLIED_MODELS_PRESET = "agents";
 var ROLE_NAMES = [...ALL_AGENT_NAMES];
@@ -4053,7 +4942,11 @@ function issueOpenCodePlan(plan, status, context2, payload) {
   if (!planDigest.ok || !planDigest.digest || !statusDigest.ok || !statusDigest.digest) {
     return plan;
   }
-  const immutablePayload = payload.kind === "fixed" ? Object.freeze({ kind: "fixed", action: payload.action }) : Object.freeze({
+  const immutablePayload = payload.kind === "fixed" ? Object.freeze({
+    kind: "fixed",
+    action: payload.action,
+    version: payload.version
+  }) : Object.freeze({
     kind: "model",
     roles: Object.freeze(
       payload.roles.map((role) => Object.freeze({ ...role }))
@@ -4065,6 +4958,7 @@ function issueOpenCodePlan(plan, status, context2, payload) {
     harness: "opencode",
     action: payload.kind === "model" ? "model-config" : payload.action,
     context: immutableContext(context2),
+    runtimeContext: context2,
     payload: immutablePayload
   });
   return plan;
@@ -4138,7 +5032,7 @@ function targetForMainConfig(state) {
     path: getExistingConfigPath(),
     label: "OpenCode config",
     ...state ? { state } : {},
-    expected: `plugin includes ${EXPECTED_PLUGIN}`
+    expected: EXPECTED_PLUGIN ? `plugin includes ${EXPECTED_PLUGIN}` : "plugin version unavailable"
   };
 }
 function targetForLiteConfig(state) {
@@ -4216,7 +5110,7 @@ function configPluginMarker(config) {
   return plugins.length > 0 ? `plugin: ${JSON.stringify(plugins)}` : "plugin: []";
 }
 function hasExpectedPlugin(config) {
-  return Array.isArray(config?.plugin) && config.plugin.includes(EXPECTED_PLUGIN);
+  return EXPECTED_PLUGIN !== null && Array.isArray(config?.plugin) && config.plugin.includes(EXPECTED_PLUGIN);
 }
 function hasManagedPluginDrift(config) {
   return Array.isArray(config?.plugin) && config.plugin.some(
@@ -4356,6 +5250,13 @@ function getOpenCodeManagedStatus(context2 = { cwd: process.cwd() }) {
   const lite = parseConfig(litePath);
   const diagnostics = [];
   const skillStatus = openCodeSkillTargets(context2);
+  if (!EXECUTING_PACKAGE_VERSION.ok) {
+    diagnostics.push({
+      severity: "critical",
+      message: EXECUTING_PACKAGE_VERSION.error.message,
+      code: "opencode-package-version-unresolved"
+    });
+  }
   if (main.error) {
     diagnostics.push({
       severity: "critical",
@@ -4419,7 +5320,7 @@ function getOpenCodeManagedStatus(context2 = { cwd: process.cwd() }) {
         harness: "opencode",
         displayName: "OpenCode",
         state: "drift",
-        summary: "OpenCode config has a managed thoth-agents plugin entry that is not latest.",
+        summary: "OpenCode config has a managed thoth-agents plugin entry that does not match the executing CLI release.",
         targets: [
           { ...mainTarget, state: "drift" },
           {
@@ -4653,8 +5554,13 @@ function getOpenCodeManagedStatus(context2 = { cwd: process.cwd() }) {
   };
 }
 function getOpenCodeStatus(context2 = { cwd: process.cwd() }, evidence = {}) {
+  const managedStatus = getOpenCodeManagedStatus(context2);
   return {
-    ...getOpenCodeManagedStatus(context2),
+    ...managedStatus,
+    targets: [
+      ...managedStatus.targets,
+      getCliManagedInstallVersionTarget("opencode", context2)
+    ],
     providerCapability: classifyProviderCapabilityEvidence(evidence)
   };
 }
@@ -4737,52 +5643,77 @@ function planFromItems(id, action, title, summary, items, context2) {
     }
   };
 }
-function buildOpenCodeUpdatePlan(_context = { cwd: process.cwd() }) {
-  const path = getExistingConfigPath();
-  const { plan, status } = planFromItems(
-    "opencode-update-preview",
-    "update",
-    "Update OpenCode managed plugin entry",
-    `Preview ensuring plugin: ["${EXPECTED_PLUGIN}"].`,
+function packageVersionForContext(context2) {
+  return (context2.resolveExecutingPackageVersion ?? resolveExecutingPackageVersion)();
+}
+function ledgerOptionsForContext(context2) {
+  return context2.installLedgerOptions ?? {
+    env: context2.env,
+    homeDir: homeDirFromContext(context2)
+  };
+}
+function failedPackageVersionPlan(action, context2, error) {
+  const { plan } = planFromItems(
+    `opencode-${action}-version-unavailable`,
+    action,
+    `${action === "install" ? "Install" : action === "update" ? "Update" : "Sync"} OpenCode`,
+    "The executing package version could not be approved.",
     [
       {
-        title: "Ensure OpenCode plugin points at thoth-agents@latest",
-        target: targetForMainConfig(),
-        state: getOpenCodeStatus(_context).state,
-        preview: `plugin: ["${EXPECTED_PLUGIN}"]`,
-        backup: defaultBackup(path)
+        title: "Resolve exact thoth-agents package version",
+        target: { kind: "package", label: "Executing thoth-agents package" },
+        state: "unknown",
+        preview: error
       }
     ],
-    _context
+    context2
   );
-  return issueOpenCodePlan(plan, status, _context, {
-    kind: "fixed",
-    action: "update"
+  plan.canApply = false;
+  plan.warnings.push({
+    severity: "critical",
+    code: "opencode-package-version-unresolved",
+    message: error
   });
+  return plan;
 }
-function buildOpenCodeSyncPlan(context2 = { cwd: process.cwd() }) {
+function buildOpenCodeCompletePlan(action, context2) {
+  const packageVersion = packageVersionForContext(context2);
+  if (!packageVersion.ok) {
+    return failedPackageVersionPlan(
+      action,
+      context2,
+      packageVersion.error.message
+    );
+  }
+  const version = packageVersion.version;
+  const expectedPlugin = `${PACKAGE_NAME}@${version}`;
   const generatedConfig = generateLiteConfig({
     agent: "opencode",
     hasTmux: false,
     dryRun: true,
     reset: false
   });
-  const litePath = getExistingLiteConfigPath();
-  const ownedSkills = syncOpenCodeOwnedSkills({
+  const syncOwned = context2.syncOpenCodeOwnedSkills ?? syncOpenCodeOwnedSkills;
+  const ownedSkills = syncOwned({
     dryRun: true,
     homeDir: homeDirFromContext(context2)
   });
+  const providerCommand = getThothMemSetupCommand("opencode", true);
+  const ledgerPath = getInstallLedgerPath(ledgerOptionsForContext(context2));
   const { plan, status } = planFromItems(
-    "opencode-sync-preview",
-    "sync",
-    "Sync OpenCode managed configuration",
-    "Preview OpenCode plugin entry, default-agent disablement, and thoth-agents config sync.",
+    `opencode-${action}-preview`,
+    action,
+    `${action === "install" ? "Install" : "Update"} complete OpenCode setup`,
+    `Preview complete OpenCode refresh pinned to ${expectedPlugin}.`,
     [
       {
-        title: "Ensure OpenCode plugin points at thoth-agents@latest",
-        target: targetForMainConfig(),
+        title: `Ensure OpenCode plugin points at ${expectedPlugin}`,
+        target: {
+          ...targetForMainConfig(),
+          expected: `plugin includes ${expectedPlugin}`
+        },
         state: getOpenCodeStatus(context2).state,
-        preview: `plugin: ["${EXPECTED_PLUGIN}"]`,
+        preview: `plugin: ["${expectedPlugin}"]`,
         backup: defaultBackup(getExistingConfigPath())
       },
       {
@@ -4795,7 +5726,7 @@ function buildOpenCodeSyncPlan(context2 = { cwd: process.cwd() }) {
         title: "Write thoth-agents seven-role config",
         target: targetForLiteConfig(),
         preview: JSON.stringify(generatedConfig, null, 2),
-        backup: defaultBackup(litePath)
+        backup: defaultBackup(getExistingLiteConfigPath())
       },
       {
         title: "Synchronize global thoth-owned OpenCode skills",
@@ -4821,59 +5752,69 @@ function buildOpenCodeSyncPlan(context2 = { cwd: process.cwd() }) {
           null,
           2
         )
+      },
+      {
+        title: "Plan provider-owned thoth-mem setup",
+        target: {
+          kind: "surface",
+          label: "Provider-owned thoth-mem setup"
+        },
+        preview: `${providerCommand.command} ${providerCommand.args.join(" ")}`
+      },
+      {
+        title: "Record completed OpenCode CLI install",
+        target: {
+          kind: "file",
+          path: ledgerPath,
+          label: "CLI-managed install version",
+          expected: `recorded ${version}`
+        },
+        preview: JSON.stringify({ harness: "opencode", version })
       }
     ],
     context2
   );
+  plan.canApply = canApplyToManagedHealth("install", status);
   return issueOpenCodePlan(plan, status, context2, {
     kind: "fixed",
-    action: "sync"
+    action,
+    version
   });
 }
-function tuiInstallConfig() {
-  return {
+function buildOpenCodeUpdatePlan(context2 = { cwd: process.cwd() }) {
+  return buildOpenCodeCompletePlan("update", context2);
+}
+function buildOpenCodeSyncPlan(context2 = { cwd: process.cwd() }) {
+  const packageVersion = packageVersionForContext(context2);
+  if (!packageVersion.ok) {
+    return failedPackageVersionPlan(
+      "sync",
+      context2,
+      packageVersion.error.message
+    );
+  }
+  const generatedConfig = generateLiteConfig({
     agent: "opencode",
     hasTmux: false,
     dryRun: true,
     reset: false
-  };
-}
-function buildOpenCodeInstallPlan(context2 = { cwd: process.cwd() }) {
+  });
+  const litePath = getExistingLiteConfigPath();
   const ownedSkills = syncOpenCodeOwnedSkills({
     dryRun: true,
     homeDir: homeDirFromContext(context2)
   });
-  const generatedConfig = generateLiteConfig(tuiInstallConfig());
-  const installPreview = {
-    noTui: true,
-    hasTmux: false,
-    ownedSkills: ownedSkills.skills.map((skill) => skill.name),
-    requiredSkills: REQUIRED_SKILLS.map((skill) => skill.name),
-    equivalentCommand: "install --agent=opencode --no-tui --tmux=no"
-  };
-  const litePath = getExistingLiteConfigPath();
   const { plan, status } = planFromItems(
-    "opencode-install-preview",
-    "install",
-    "Preview install",
-    "Preview OpenCode install with the required global skills.",
+    "opencode-sync-preview",
+    "sync",
+    "Sync OpenCode managed configuration",
+    "Preview OpenCode plugin entry, default-agent disablement, and thoth-agents config sync.",
     [
       {
-        title: "Apply OpenCode TUI install options",
-        target: {
-          kind: "config",
-          path: getExistingConfigPath(),
-          label: "OpenCode install options",
-          state: getOpenCodeStatus(context2).state,
-          expected: "--no-tui --tmux=no plus required global skills"
-        },
-        preview: JSON.stringify(installPreview, null, 2)
-      },
-      {
-        title: "Ensure OpenCode plugin points at thoth-agents@latest",
+        title: `Ensure OpenCode plugin points at ${PACKAGE_NAME}@${packageVersion.version}`,
         target: targetForMainConfig(),
         state: getOpenCodeStatus(context2).state,
-        preview: `plugin: ["${EXPECTED_PLUGIN}"]`,
+        preview: `plugin: ["${PACKAGE_NAME}@${packageVersion.version}"]`,
         backup: defaultBackup(getExistingConfigPath())
       },
       {
@@ -4918,9 +5859,13 @@ function buildOpenCodeInstallPlan(context2 = { cwd: process.cwd() }) {
   );
   return issueOpenCodePlan(plan, status, context2, {
     kind: "fixed",
-    action: "install"
+    action: "sync",
+    version: packageVersion.version
   });
 }
+function buildOpenCodeInstallPlan(context2 = { cwd: process.cwd() }) {
+  return buildOpenCodeCompletePlan("install", context2);
+}
 function normalizeRoleModel(input) {
   if (input.provider && !input.model.includes("/")) {
     return `${input.provider}/${input.model}`;
@@ -4974,7 +5919,7 @@ function buildOpenCodeModelPlan(input, _context = { cwd: process.cwd() }) {
     plan.warnings.push(...effortWarnings);
   }
   if (input.harness !== "opencode") {
-    const rejectedPlan = {
+    return {
       ...plan,
       canApply: false,
       warnings: [
@@ -4986,13 +5931,12 @@ function buildOpenCodeModelPlan(input, _context = { cwd: process.cwd() }) {
         }
       ]
     };
-    return rejectedPlan;
   }
   const unsupportedRoles = input.roles.filter(
     (role) => !ROLE_NAMES.includes(role.role)
   );
   if (input.roles.length === 0 || unsupportedRoles.length > 0) {
-    const rejectedPlan = {
+    return {
       ...plan,
       canApply: false,
       warnings: [
@@ -5004,7 +5948,6 @@ function buildOpenCodeModelPlan(input, _context = { cwd: process.cwd() }) {
         }
       ]
     };
-    return rejectedPlan;
   }
   if (effortWarnings.length > 0) {
     return plan;
@@ -5261,9 +6204,10 @@ function applyModelPlan(roles) {
 function applyRequiredSkills(context2) {
   const warnings = [];
   const homeDir = homeDirFromContext(context2);
+  const installSkill = context2.installRequiredSkill ?? installRequiredSkill;
   for (const skill of REQUIRED_SKILLS) {
     try {
-      const result = installRequiredSkill(skill, "opencode", { homeDir });
+      const result = installSkill(skill, "opencode", { homeDir });
       if (result.status !== "failed") continue;
       warnings.push({
         severity: "critical",
@@ -5282,7 +6226,8 @@ function applyRequiredSkills(context2) {
   return { success: warnings.length === 0, warnings };
 }
 function applyOwnedSkills(context2) {
-  const result = syncOpenCodeOwnedSkills({
+  const syncOwned = context2.syncOpenCodeOwnedSkills ?? syncOpenCodeOwnedSkills;
+  const result = syncOwned({
     homeDir: homeDirFromContext(context2)
   });
   if (result.success) return { success: true, warnings: [] };
@@ -5309,8 +6254,32 @@ function applyOpenCodePlan(plan) {
       "opencode-plan-unissued"
     );
   }
+  if (issued.payload.kind === "fixed") {
+    const currentPackageVersion = packageVersionForContext(
+      issued.runtimeContext
+    );
+    if (!currentPackageVersion.ok) {
+      return rejectPlan3(
+        plan,
+        currentPackageVersion.error.message,
+        "critical",
+        "opencode-package-version-unresolved",
+        issued.context
+      );
+    }
+    if (currentPackageVersion.version !== issued.payload.version) {
+      return rejectPlan3(
+        plan,
+        `Approved package version changed from ${issued.payload.version} to ${currentPackageVersion.version} before apply.`,
+        "critical",
+        "opencode-package-version-changed",
+        issued.context
+      );
+    }
+  }
   const status = getOpenCodeStatus(issued.context);
-  if (!canApplyToManagedHealth(plan.action, status)) {
+  const healthAction = issued.payload.kind === "fixed" && (issued.payload.action === "install" || issued.payload.action === "update") ? "install" : plan.action;
+  if (!canApplyToManagedHealth(healthAction, status)) {
     return rejectPlan3(
       plan,
       `OpenCode state is ${status.state}; refusing to apply plan without a safe status.`,
@@ -5335,9 +6304,11 @@ function applyOpenCodePlan(plan) {
   const changedTargets = [];
   const backups = [];
   const warnings = [];
-  const mainConfigResult = updateOpenCodeMainConfig({
+  const updateMainConfig = issued.runtimeContext.updateOpenCodeMainConfig ?? updateOpenCodeMainConfig;
+  const mainConfigResult = updateMainConfig({
     ensurePlugin: true,
-    disableDefaults: issued.payload.action === "sync" || issued.payload.action === "install"
+    pluginVersion: issued.payload.version,
+    disableDefaults: true
   });
   if (!mainConfigResult.success) {
     return rejectPlan3(
@@ -5350,7 +6321,7 @@ function applyOpenCodePlan(plan) {
   }
   changedTargets.push({
     ...targetForMainConfig("installed"),
-    observed: `plugin includes ${EXPECTED_PLUGIN}`
+    observed: `plugin includes ${PACKAGE_NAME}@${issued.payload.version}`
   });
   if (existsSync10(`${mainConfigResult.configPath}.bak`)) {
     backups.push({
@@ -5358,68 +6329,95 @@ function applyOpenCodePlan(plan) {
       label: "OpenCode config backup"
     });
   }
-  if (issued.payload.action === "sync" || issued.payload.action === "install") {
-    const liteResult = writeLiteConfig(
-      {
-        agent: "opencode",
-        hasTmux: false,
-        dryRun: false,
-        reset: false
-      },
-      getExistingLiteConfigPath()
+  const writeLite = issued.runtimeContext.writeLiteConfig ?? writeLiteConfig;
+  const liteResult = writeLite(
+    {
+      agent: "opencode",
+      hasTmux: false,
+      dryRun: false,
+      reset: false
+    },
+    getExistingLiteConfigPath()
+  );
+  if (!liteResult.success) {
+    return rejectPlan3(
+      plan,
+      liteResult.error ?? "Failed to write thoth-agents config."
     );
-    if (!liteResult.success) {
-      return rejectPlan3(
-        plan,
-        liteResult.error ?? "Failed to write thoth-agents config."
-      );
-    }
-    changedTargets.push({
-      ...targetForLiteConfig("installed"),
-      observed: "seven-role roster written"
+  }
+  changedTargets.push({
+    ...targetForLiteConfig("installed"),
+    observed: "seven-role roster written"
+  });
+  if (existsSync10(`${liteResult.configPath}.bak`)) {
+    backups.push({
+      path: `${liteResult.configPath}.bak`,
+      label: "thoth-agents config backup"
     });
-    if (existsSync10(`${liteResult.configPath}.bak`)) {
-      backups.push({
-        path: `${liteResult.configPath}.bak`,
-        label: "thoth-agents config backup"
-      });
-    }
   }
-  if (issued.payload.action === "install" || issued.payload.action === "sync") {
-    const ownedSkills = applyOwnedSkills(issued.context);
-    warnings.push(...ownedSkills.warnings);
-    changedTargets.push({
-      kind: "skill",
-      label: "Thoth-owned OpenCode skills",
-      state: ownedSkills.success ? "installed" : "drift",
-      observed: ownedSkills.success ? "thoth-owned global skills synchronized" : "thoth-owned global skill synchronization failed"
+  const ownedSkills = applyOwnedSkills(issued.runtimeContext);
+  warnings.push(...ownedSkills.warnings);
+  changedTargets.push({
+    kind: "skill",
+    label: "Thoth-owned OpenCode skills",
+    state: ownedSkills.success ? "installed" : "drift",
+    observed: ownedSkills.success ? "thoth-owned global skills synchronized" : "thoth-owned global skill synchronization failed"
+  });
+  if (!ownedSkills.success) {
+    return {
+      harness: "opencode",
+      action: plan.action,
+      applied: false,
+      summary: "OpenCode configuration was written, but thoth-owned skills failed to synchronize.",
+      changedTargets,
+      backups,
+      warnings,
+      disclaimers: defaultDisclaimers()
+    };
+  }
+  const requiredSkills = applyRequiredSkills(issued.runtimeContext);
+  warnings.push(...requiredSkills.warnings);
+  changedTargets.push({
+    kind: "skill",
+    label: "Required OpenCode skills",
+    state: requiredSkills.success ? "installed" : "drift",
+    observed: requiredSkills.success ? "required external skills installed" : "required external skill installation failed"
+  });
+  if (!requiredSkills.success) {
+    return {
+      harness: "opencode",
+      action: plan.action,
+      applied: false,
+      summary: "OpenCode configuration was written, but required skills failed to install.",
+      changedTargets,
+      backups,
+      warnings,
+      disclaimers: defaultDisclaimers()
+    };
+  }
+  if (issued.payload.action === "install" || issued.payload.action === "update") {
+    const finalize = issued.runtimeContext.finalizeHarnessInstall ?? finalizeHarnessInstall;
+    const completion = finalize({
+      harness: "opencode",
+      version: issued.payload.version,
+      dryRun: false,
+      cwd: issued.runtimeContext.cwd,
+      runThothMemSetup: issued.runtimeContext.runThothMemSetup,
+      ledgerOptions: ledgerOptionsForContext(issued.runtimeContext)
     });
-    if (!ownedSkills.success) {
-      return {
-        harness: "opencode",
-        action: plan.action,
-        applied: false,
-        summary: "OpenCode configuration was written, but thoth-owned skills failed to synchronize.",
-        changedTargets,
-        backups,
-        warnings,
-        disclaimers: defaultDisclaimers()
-      };
-    }
-    const requiredSkills = applyRequiredSkills(issued.context);
-    warnings.push(...requiredSkills.warnings);
-    changedTargets.push({
-      kind: "skill",
-      label: "Required OpenCode skills",
-      state: requiredSkills.success ? "installed" : "drift",
-      observed: requiredSkills.success ? "required external skills installed" : "required external skill installation failed"
+    const completionEvidence = getInstallCompletionEvidence(completion, {
+      codePrefix: "opencode",
+      version: issued.payload.version,
+      fallbackError: "OpenCode install finalization failed."
     });
-    if (!requiredSkills.success) {
+    warnings.push(...completionEvidence.warnings);
+    changedTargets.push(...completionEvidence.targets);
+    if (!completion.success) {
       return {
         harness: "opencode",
         action: plan.action,
         applied: false,
-        summary: "OpenCode configuration was written, but required skills failed to install.",
+        summary: completion.error ?? "OpenCode install finalization failed.",
         changedTargets,
         backups,
         warnings,
@@ -5431,7 +6429,7 @@ function applyOpenCodePlan(plan) {
     harness: "opencode",
     action: plan.action,
     applied: true,
-    summary: plan.action === "install" ? "Applied OpenCode install plan." : plan.action === "sync" ? "Applied OpenCode managed configuration sync." : "Applied OpenCode plugin update.",
+    summary: plan.action === "install" ? "Applied OpenCode install plan." : plan.action === "sync" ? "Applied OpenCode managed configuration sync." : "Applied complete OpenCode update plan.",
     changedTargets,
     backups,
     warnings,
@@ -5463,13 +6461,13 @@ import { execFileSync } from "child_process";
 // src/cli/model-catalog/cache.ts
 import {
   existsSync as existsSync11,
-  mkdirSync as mkdirSync4,
-  readFileSync as readFileSync6,
-  renameSync as renameSync3,
+  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync7,
+  renameSync as renameSync4,
   unlinkSync,
-  writeFileSync as writeFileSync3
+  writeFileSync as writeFileSync4
 } from "fs";
-import { homedir as homedir4 } from "os";
+import { homedir as homedir5 } from "os";
 import { dirname as dirname6, posix, win32 } from "path";
 import { z as z2 } from "zod";
 var modelCatalogSourceSchema = z2.enum(["remote", "lkg", "manual"]);
@@ -5490,7 +6488,7 @@ var modelsDevCacheSchema = z2.object({
 function resolveModelsDevCachePath(options = {}) {
   const platform = options.platform ?? process.platform;
   const env = options.env ?? process.env;
-  const home = options.homeDir ?? homedir4();
+  const home = options.homeDir ?? homedir5();
   if (platform === "win32") {
     const path = win32;
     const base2 = env.LOCALAPPDATA ?? env.APPDATA ?? path.join(home, "AppData", "Local");
@@ -5502,7 +6500,7 @@ function resolveModelsDevCachePath(options = {}) {
 function readModelsDevCache(cachePath) {
   if (!existsSync11(cachePath)) return void 0;
   try {
-    const input = JSON.parse(readFileSync6(cachePath, "utf8"));
+    const input = JSON.parse(readFileSync7(cachePath, "utf8"));
     const parsed = modelsDevCacheSchema.safeParse(input);
     return parsed.success ? parsed.data : void 0;
   } catch {
@@ -5514,15 +6512,15 @@ function writeModelsDevCacheAtomic(cachePath, cache) {
   if (!validated.success) {
     throw new Error(`Invalid models.dev cache: ${validated.error.message}`);
   }
-  mkdirSync4(dirname6(cachePath), { recursive: true });
+  mkdirSync5(dirname6(cachePath), { recursive: true });
   const temporaryPath = `${cachePath}.${process.pid}.${Date.now()}.tmp`;
   try {
-    writeFileSync3(
+    writeFileSync4(
       temporaryPath,
       `${JSON.stringify(validated.data, null, 2)}
 `
     );
-    renameSync3(temporaryPath, cachePath);
+    renameSync4(temporaryPath, cachePath);
   } catch (error) {
     if (existsSync11(temporaryPath)) unlinkSync(temporaryPath);
     throw error;
@@ -5837,7 +6835,7 @@ async function getModelOptions(harness) {
 }
 
 // src/cli/tui/operations.ts
-import { existsSync as existsSync12, readFileSync as readFileSync7 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync8 } from "fs";
 var context = { cwd: process.cwd() };
 var codexContext = { cwd: process.cwd() };
 var claudeCodeContext = {
@@ -5879,7 +6877,7 @@ function getCodexModelRoles(source = codexContext) {
       const item = plan.items.find(
         (candidate) => candidate.action === "write-role-toml" && candidate.role === role
       );
-      const content = item && existsSync12(item.targetPath) ? readFileSync7(item.targetPath, "utf8") : item?.content;
+      const content = item && existsSync12(item.targetPath) ? readFileSync8(item.targetPath, "utf8") : item?.content;
       const effort = content ? parseRoleTomlEffort(content) : void 0;
       return {
         role,
@@ -6002,8 +7000,11 @@ export {
   buildClaudeCodeSetupPlan,
   applyClaudeCodeSetup,
   formatClaudeCodeSetupPlan,
+  buildCodexPluginSetupPlan,
+  applyCodexPluginSetup,
+  formatCodexPluginSetupPlan,
+  finalizeHarnessInstall,
   syncOpenCodeOwnedSkills,
-  getNpxCommand,
   REQUIRED_SKILLS,
   getRequiredSkillInstallCommand,
   installRequiredSkill,