thoth-agents 0.3.8 → 0.3.9

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import {
   getOpenCodeVersion,
   isOpenCodeInstalled,
   opencodeAdapter
-} from "../chunk-6GQYMWWT.js";
+} from "../chunk-MY2GIOOH.js";
 import {
   CODEX_ROLE_NAMES,
   REQUIRED_SKILLS,
@@ -12,6 +12,7 @@ import {
   applyClaudeCodePlan,
   applyClaudeCodeSetup,
   applyCodexPlan,
+  applyCodexPluginSetup,
   applyCodexSetup,
   applyOpenCodePlan,
   buildClaudeCodeModelPlan,
@@ -19,6 +20,7 @@ import {
   buildClaudeCodeSyncPlan,
   buildClaudeCodeUpdatePlan,
   buildCodexModelPlan,
+  buildCodexPluginSetupPlan,
   buildCodexSetupPlan,
   buildCodexSyncPlan,
   buildCodexUpdatePlan,
@@ -28,14 +30,15 @@ import {
   claudeCodeAdapter,
   codexAdapter,
   defaultClaudeCodeModelRoles,
+  finalizeHarnessInstall,
   formatClaudeCodeSetupPlan,
+  formatCodexPluginSetupPlan,
   formatCodexSetupPlan,
   getClaudeCodeModelRoles,
   getClaudeCodeStatus,
   getCodexModelRoles,
   getCodexStatus,
   getModelOptions,
-  getNpxCommand,
   getOpenCodeModelRoles,
   getOpenCodeStatus,
   getOperationHarness,
@@ -44,7 +47,7 @@ import {
   listOperationHarnesses,
   normalizeEffortSelection,
   syncOpenCodeOwnedSkills
-} from "../chunk-3WNTCPVK.js";
+} from "../chunk-XEEYNMPC.js";
 import {
   ALL_AGENT_NAMES,
   detectCurrentConfig,
@@ -52,9 +55,10 @@ import {
   getDefaultOpenCodeModel,
   getDefaultOpenCodeVariant,
   getExistingLiteConfigPath,
+  resolveExecutingPackageVersion,
   updateOpenCodeMainConfig,
   writeLiteConfig
-} from "../chunk-F2K4CS5J.js";
+} from "../chunk-2TLT6WWY.js";
 
 // src/cli/index.ts
 import { pathToFileURL } from "url";
@@ -74,402 +78,6 @@ function getHarnessAdapter(harness) {
 import { existsSync } from "fs";
 import { homedir } from "os";
 import { cwd } from "process";
-
-// src/cli/codex-plugin-install.ts
-import { spawnSync } from "child_process";
-var MARKETPLACE_NAME = "thoth-agents";
-var MARKETPLACE_SOURCE = "EremesNG/thoth-agents";
-var PLUGIN_ID = "thoth-agents@thoth-agents";
-var MARKETPLACE_TARGET = "codex://marketplaces/thoth-agents";
-var PLUGIN_TARGET = "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 defaultCommandExecutor(command, args, options) {
-  const invocation = command === "codex" ? getCodexCommand(args) : { command, args: [...args] };
-  const result = spawnSync(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 isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function parseRecordArray(value) {
-  return Array.isArray(value) && value.every(isRecord) ? value : null;
-}
-function parseManagerRecord(content) {
-  try {
-    const parsed = JSON.parse(content);
-    return isRecord(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 (isRecord(entry.marketplaceSource)) {
-    sources.push(entry.marketplaceSource.repo, entry.marketplaceSource.source);
-  }
-  return sources.filter(
-    (source) => typeof source === "string"
-  );
-}
-function isCanonicalMarketplace(entry) {
-  if (entry.name !== MARKETPLACE_NAME) return false;
-  const canonical = MARKETPLACE_SOURCE.toLowerCase();
-  return marketplaceSources(entry).some(
-    (source) => normalizeMarketplaceSource(source) === canonical
-  );
-}
-function inspectCodexManager(executor, cwd2) {
-  const marketplaceResult = executor(
-    "codex",
-    ["plugin", "marketplace", "list", "--json"],
-    { cwd: cwd2 }
-  );
-  const pluginResult = executor(
-    "codex",
-    ["plugin", "list", "--available", "--json"],
-    { cwd: cwd2 }
-  );
-  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_NAME
-  );
-  let marketplace = "absent";
-  if (namedMarketplaces.length > 0) {
-    marketplace = namedMarketplaces.every(isCanonicalMarketplace) ? "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_ID
-  );
-  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 commandItem(action, projectRoot) {
-  if (action === "register-marketplace") {
-    return {
-      action,
-      targetPath: MARKETPLACE_TARGET,
-      description: "Register the package-owned thoth-agents Codex marketplace.",
-      command: {
-        executable: "codex",
-        args: ["plugin", "marketplace", "add", MARKETPLACE_SOURCE, "--json"],
-        cwd: projectRoot
-      }
-    };
-  }
-  return {
-    action,
-    targetPath: PLUGIN_TARGET,
-    description: "Install and enable the thoth-agents Codex plugin from its native marketplace.",
-    command: {
-      executable: "codex",
-      args: ["plugin", "add", PLUGIN_ID, "--json"],
-      cwd: projectRoot
-    }
-  };
-}
-function buildCodexPluginSetupPlan(config) {
-  const commandExecutor = config.commandExecutor ?? defaultCommandExecutor;
-  const inspection = inspectCodexManager(commandExecutor, config.projectRoot);
-  const items = [];
-  if (inspection.ready) {
-    if (inspection.marketplace === "absent") {
-      items.push(commandItem("register-marketplace", config.projectRoot));
-    }
-    if (inspection.plugin === "absent" || inspection.plugin === "disabled") {
-      items.push(commandItem("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 uniqueMessages(messages) {
-  return [...new Set(messages)];
-}
-function boundedCommandFailure(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 = uniqueMessages(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: boundedCommandFailure(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: uniqueMessages(diagnostics),
-      error: "Codex did not verify the expected marketplace and enabled plugin after mutation."
-    };
-  }
-  return { success: true, changed, diagnostics: uniqueMessages(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/thoth-mem-install.ts
-import { spawnSync as spawnSync2 } from "child_process";
-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 isRecord2(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 isRecord2(value) && typeof value.name === "string" && value.name.length > 0 && typeof value.outcome === "string" && STEP_OUTCOMES.has(value.outcome);
-}
-function isProviderSetupResult(value, expectedHarness) {
-  return isRecord2(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 isRecord2(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.ts
 var GREEN = "\x1B[32m";
 var BLUE = "\x1B[34m";
 var YELLOW = "\x1B[33m";
@@ -628,14 +236,32 @@ function printThothMemSetupResult(result, dryRun) {
   );
   return true;
 }
-function installThothMemForHarness(harness, dryRun, dependencies) {
-  const setup = dependencies.runThothMemSetup ?? runThothMemSetup;
-  return printThothMemSetupResult(
-    setup({ harness, dryRun, cwd: cwd() }),
-    dryRun
-  );
+function finalizeInstallForHarness(harness, dryRun, version, dependencies) {
+  const finalize = dependencies.finalizeHarnessInstall ?? finalizeHarnessInstall;
+  const result = finalize({
+    harness,
+    version,
+    dryRun,
+    cwd: cwd(),
+    runThothMemSetup: dependencies.runThothMemSetup,
+    ledgerOptions: dependencies.installLedgerOptions ?? {
+      homeDir: dependencies.homeDir ?? homedir()
+    }
+  });
+  const providerComplete = printThothMemSetupResult(result.provider, dryRun);
+  if (!providerComplete) return false;
+  if (!result.success) {
+    printError(result.error ?? "Failed to record the completed CLI install.");
+    return false;
+  }
+  if (result.ledger.status === "planned") {
+    printInfo(`CLI-managed install record planned: ${result.ledger.path}`);
+  } else if (result.ledger.status === "recorded") {
+    printSuccess(`CLI-managed install version recorded: ${result.ledger.path}`);
+  }
+  return true;
 }
-async function runInstall(config, dependencies) {
+async function runInstall(config, dependencies, pluginVersion) {
   const detected = detectCurrentConfig();
   const isUpdate = detected.isInstalled;
   printHeader(isUpdate);
@@ -656,8 +282,10 @@ async function runInstall(config, dependencies) {
   if (config.dryRun) {
     printInfo("Dry run mode - skipping main config update");
   } else {
-    const mainConfigResult = updateOpenCodeMainConfig({
+    const updateMainConfig = dependencies.updateOpenCodeMainConfig ?? updateOpenCodeMainConfig;
+    const mainConfigResult = updateMainConfig({
       ensurePlugin: true,
+      pluginVersion,
       disableDefaults: true
     });
     if (!handleStepResult(mainConfigResult, "Main config updated")) return 1;
@@ -702,7 +330,12 @@ ${JSON.stringify(liteConfig, null, 2)}
   ))
     return 1;
   printStep(step++, totalSteps, "Configuring provider-owned thoth-mem...");
-  if (!installThothMemForHarness("opencode", config.dryRun, dependencies)) {
+  if (!finalizeInstallForHarness(
+    "opencode",
+    config.dryRun,
+    pluginVersion,
+    dependencies
+  )) {
     return 1;
   }
   console.log();
@@ -733,6 +366,14 @@ function createInstallConfig(args) {
 }
 async function install(args, dependencies = {}) {
   const config = createInstallConfig(args);
+  const resolvePackageVersion = dependencies.resolveExecutingPackageVersion ?? resolveExecutingPackageVersion;
+  const packageVersion = resolvePackageVersion();
+  if (!packageVersion.ok) {
+    printError(
+      `Could not resolve the executing thoth-agents package version: ${packageVersion.error.message}`
+    );
+    return 1;
+  }
   if (config.agent === "codex") {
     const projectRoot = cwd();
     const pluginPlan = buildCodexPluginSetupPlan({
@@ -751,7 +392,7 @@ async function install(args, dependencies = {}) {
       reset: config.reset,
       scope: "user",
       projectRoot,
-      homeDir: homedir()
+      homeDir: dependencies.homeDir ?? homedir()
     });
     console.log(formatCodexSetupPlan(plan));
     const result = applyCodexSetup(plan);
@@ -760,8 +401,18 @@ async function install(args, dependencies = {}) {
       printError(`Codex install failed: ${result.error}`);
       return 1;
     }
-    if (!installRequiredSkillsForHarness("codex", config.dryRun)) return 1;
-    if (!installThothMemForHarness("codex", config.dryRun, dependencies)) {
+    if (!installRequiredSkillsForHarness(
+      "codex",
+      config.dryRun,
+      dependencies.homeDir ?? homedir()
+    ))
+      return 1;
+    if (!finalizeInstallForHarness(
+      "codex",
+      config.dryRun,
+      packageVersion.version,
+      dependencies
+    )) {
       return 1;
     }
     printSuccess(
@@ -783,8 +434,18 @@ async function install(args, dependencies = {}) {
       printError(`Claude Code install failed: ${result.error}`);
       return 1;
     }
-    if (!installRequiredSkillsForHarness("claude", config.dryRun)) return 1;
-    if (!installThothMemForHarness("claude", config.dryRun, dependencies)) {
+    if (!installRequiredSkillsForHarness(
+      "claude",
+      config.dryRun,
+      dependencies.homeDir ?? homedir()
+    ))
+      return 1;
+    if (!finalizeInstallForHarness(
+      "claude",
+      config.dryRun,
+      packageVersion.version,
+      dependencies
+    )) {
       return 1;
     }
     printSuccess(
@@ -792,7 +453,7 @@ async function install(args, dependencies = {}) {
     );
     return 0;
   }
-  return runInstall(config, dependencies);
+  return runInstall(config, dependencies, packageVersion.version);
 }
 
 // src/cli/commands.ts
@@ -808,6 +469,20 @@ function formatTarget(target) {
   const observed = target.observed ? ` observed ${target.observed}` : "";
   return `- ${label}${location}${state}${expected}${observed}`;
 }
+function formatCliManagedInstall(targets) {
+  const target = targets.find(
+    ({ label }) => label === "CLI-managed install version"
+  );
+  if (!target) return [];
+  const executing = target.expected?.replace(/^executing\s+/, "") ?? "unknown";
+  const recorded = target.observed?.replace(/^recorded\s+/, "") ?? "unknown";
+  return [
+    "Official CLI-managed install:",
+    `Executing CLI version: ${executing}`,
+    `Recorded complete-install version: ${recorded}`,
+    "Native marketplace versions do not advance this record."
+  ];
+}
 function formatPaths(paths) {
   return paths.map((path) => {
     const label = path.label ? `${path.label}: ` : "";
@@ -843,6 +518,7 @@ function formatHarnessStatusReport(reports) {
       `${report.displayName ?? getOperationHarness(report.harness).displayName} (${report.harness})`,
       `State: ${report.state}`,
       `Summary: ${report.summary}`,
+      ...formatCliManagedInstall(report.targets),
       ...report.providerCapability ? [
         "Provider evidence:",
         `Provider capability: ${report.providerCapability.state}`,
@@ -924,6 +600,8 @@ function formatOperationApplyResult(result) {
   ]);
 }
 function printHelp() {
+  const packageVersion = resolveExecutingPackageVersion();
+  const exactPluginEntry = packageVersion.ok ? `thoth-agents@${packageVersion.version}` : "thoth-agents@<executing-version-unavailable>";
   console.log(`
 thoth-agents CLI (npm binary: thoth-agents)
 
@@ -937,9 +615,9 @@ Commands:
   (no command)          Open the interactive TUI in a TTY; fall back to OpenCode install in CI/non-TTY
   install               Install OpenCode, Codex, or Claude Code agent assets
   generate              Generate harness-specific artifacts
-  status                Show managed install status
+  status                Show official CLI-managed versions and managed install status
   list                  List managed surfaces and actions
-  update                Preview managed updates
+  update                Preview a complete selected-harness CLI refresh
   sync                  Preview managed configuration sync
   model                 Preview role model/provider settings
 
@@ -947,6 +625,7 @@ Options:
   --tmux=yes|no          Enable tmux integration (yes/no)
   --no-tui               Non-interactive mode
   --dry-run              Simulate install without writing files
+  --apply                Apply a reviewed update, sync, or model plan
   --reset                Repair managed installer-owned targets
   --agent=opencode|codex|claude
                          Select OpenCode plugin install (default), Codex agent-pack, or Claude Code plugin setup
@@ -961,10 +640,18 @@ Generate options:
 
 OpenCode plugin config and the npm binary are separate surfaces.
 OpenCode loads the plugin with config such as:
-  plugin: ["thoth-agents@latest"]
+  plugin: ["${exactPluginEntry}"]
 
 That plugin entry does not create a global thoth-agents command.
 Run this CLI through a global install, npx, or pnpm dlx.
+@latest selects the CLI release; OpenCode receives that exact version pin.
+
+Update performs the complete selected-harness CLI refresh and records success last.
+The official record is $XDG_CONFIG_HOME/thoth-agents/install-state.json,
+or ~/.config/thoth-agents/install-state.json when XDG_CONFIG_HOME is unset.
+Codex and Claude marketplace versions remain native-manager-owned and do not prove
+that CLI-managed agents, skills, configuration, or provider setup are aligned.
+Runtime release checks notify only; use the latest CLI install or interactive CLI Update.
 
 OpenCode install configures the adaptive seven-role roster and native task delegation.
 Provider capability is external and reported only from caller-supplied evidence.
@@ -997,18 +684,16 @@ function operationContext() {
 function selectedHarness(args, fallback = "opencode") {
   return args.harness ?? fallback;
 }
-function statusReports(args) {
+function statusReports(args, context = operationContext()) {
   const harnesses = args.all || !args.harness ? SUPPORTED_OPERATION_HARNESSES : [args.harness];
-  const context = operationContext();
   return harnesses.map((harness) => {
     if (harness === "opencode") return getOpenCodeStatus(context);
     if (harness === "claude") return getClaudeCodeStatus(context);
     return getCodexStatus(context);
   });
 }
-function buildOperationPlan(command, args) {
+function buildOperationPlan(command, args, context = operationContext()) {
   const harness = selectedHarness(args);
-  const context = operationContext();
   if (harness === "opencode") {
     return command === "update" ? buildOpenCodeUpdatePlan(context) : buildOpenCodeSyncPlan(context);
   }
@@ -1099,7 +784,7 @@ function applyOperationPlan(plan) {
   if (plan.harness === "claude") return applyClaudeCodePlan(plan);
   return applyCodexPlan(plan);
 }
-function printPlanOrApply(plan, args) {
+function printPlanOrApply(plan, args, applyPlan) {
   if (args.apply && args.dryRun) {
     console.error("--apply cannot be combined with --dry-run.");
     return 1;
@@ -1108,12 +793,17 @@ function printPlanOrApply(plan, args) {
     console.log(formatOperationPlan(plan));
     return 0;
   }
-  console.log(formatOperationApplyResult(applyOperationPlan(plan)));
-  return 0;
+  const result = applyPlan(plan);
+  console.log(formatOperationApplyResult(result));
+  return result.applied ? 0 : 1;
 }
 async function runOperationCommand(command, args, services) {
   if (command === "status") {
-    console.log(formatHarnessStatusReport(statusReports(args)));
+    console.log(
+      formatHarnessStatusReport(
+        statusReports(args, services.operationContext())
+      )
+    );
     return 0;
   }
   if (command === "list") {
@@ -1121,11 +811,19 @@ async function runOperationCommand(command, args, services) {
     return 0;
   }
   if (command === "update" || command === "sync") {
-    return printPlanOrApply(buildOperationPlan(command, args), args);
+    return printPlanOrApply(
+      buildOperationPlan(command, args, services.operationContext()),
+      args,
+      services.applyOperationPlan ?? applyOperationPlan
+    );
   }
   const plan = await buildModelPlan(args, services);
   if (!plan) return printModelGuidance();
-  return printPlanOrApply(plan, args);
+  return printPlanOrApply(
+    plan,
+    args,
+    services.applyOperationPlan ?? applyOperationPlan
+  );
 }
 function printHarnessGeneration(args) {
   if (!args.dryRun) {