@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/cli/commands/plugins.ts

@@ -10,7 +10,9 @@ import { createRequire } from "node:module";
 
 import type { Command } from "commander";
 
+import { cliIpcCall } from "../../ipc/cli-client.js";
 import { yellow } from "../lib/cli-colors.js";
+import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import type { PluginDiffResult } from "../lib/diff-plugin.js";
 import type {
@@ -29,9 +31,7 @@ import {
   parseGitHubPluginSpec,
 } from "../lib/parse-github-plugin-spec.js";
 import {
-  DEFAULT_PIN_HISTORY_LIMIT,
   DEFAULT_PLUGIN_REF,
-  DEFAULT_PLUGIN_UPGRADE_STRATEGY,
   PLUGIN_UPGRADE_STRATEGIES,
   type PluginUpgradeStrategy,
 } from "../lib/plugin-constants.js";
@@ -48,11 +48,22 @@ import {
 } from "../lib/toggle-plugin.js";
 import type { PluginUpgradeResult } from "../lib/upgrade-plugin.js";
 import { getCliLogger } from "../logger.js";
+import { pluginsHelp } from "./plugins.help.js";
 
 const loadModule = createRequire(import.meta.url);
 
 /** Lazy accessors: each getter loads its implementation module on first use. */
 const libs = {
+  get catalogCache() {
+    return loadModule(
+      "../lib/plugin-catalog-cache.js",
+    ) as typeof import("../lib/plugin-catalog-cache.js");
+  },
+  get catalogLocal() {
+    return loadModule(
+      "../lib/plugin-catalog-local.js",
+    ) as typeof import("../lib/plugin-catalog-local.js");
+  },
   get diff() {
     return loadModule(
       "../lib/diff-plugin.js",
@@ -104,254 +115,194 @@ const log = getCliLogger("plugins");
 
 export function registerPluginsCommand(program: Command): void {
   registerCommand(program, {
-    name: "plugins",
+    name: pluginsHelp.name,
     transport: "local",
-    description:
-      "List, search, install, and manage external plugins (`list` shows what is installed, `search` queries the marketplace)",
+    description: pluginsHelp.description,
     build: (plugins) => {
       // Materialize the `@vellumai/plugin-api` shim once for the whole command
       // group, before any subcommand action runs. A subcommand that resolves a
       // plugin hook in this fresh CLI process — `uninstall` running a plugin's
       // `shutdown` — needs the package importable; the daemon materializes the
       // same shim at boot, this covers the standalone CLI. Dynamically imported
-      // so the daemon-internal module stays out of the CLI's static graph
-      // (`cli/no-daemon-internals`). Best-effort: a failed shim just means such a
-      // hook's import may not resolve.
+      // so the daemon-internal module stays out of the CLI's static graph and
+      // does not weigh on every invocation. Best-effort: a failed shim just
+      // means such a hook's import may not resolve.
       plugins.hook("preAction", async () => {
         const { ensurePluginApiShim } =
           await import("../../plugins/ensure-plugin-api-shim.js");
         await ensurePluginApiShim().catch(() => {});
       });
 
-      plugins.addHelpText(
-        "after",
-        `
-Examples:
-  $ assistant plugins install example
-  $ assistant plugins install example --force
-  $ assistant plugins install https://github.com/owner/repo
-  $ assistant plugins install https://github.com/owner/repo/tree/main/sub/path --name my-plugin
-  $ assistant plugins install example --ref my-feature-branch
-  $ assistant plugins versions example
-  $ assistant plugins versions example --json
-  $ assistant plugins install example --pin <sha> --force
-  $ assistant plugins list
-  $ assistant plugins list --json
-  $ assistant plugins list --all
-  $ assistant plugins list --all --json
-  $ assistant plugins inspect example
-  $ assistant plugins inspect example --json
-  $ assistant plugins diff example
-  $ assistant plugins diff example --json
-  $ assistant plugins upgrade example
-  $ assistant plugins upgrade example --dry-run
-  $ assistant plugins upgrade example --strategy ours
-  $ assistant plugins upgrade example --strategy theirs
-  $ assistant plugins upgrade example --strategy assistant
-  $ assistant plugins search example
-  $ assistant plugins search "^example"
-  $ assistant plugins search example --json
-  $ assistant plugins uninstall example
-  $ assistant plugins enable example
-  $ assistant plugins disable example`,
-      );
+      applyCommandHelp(plugins, pluginsHelp);
 
-      plugins
-        .command("install <name-or-url>")
-        .description(
-          "Install a plugin by name from the Vellum platform (content is served as a verified tarball from the plugin's pinned commit), or directly from a GitHub URL (untrusted)",
-        )
-        .option("--force", "Overwrite an existing install")
-        .option(
-          "--ref <ref>",
-          `Marketplace manifest revision to read the pin from (default: ${DEFAULT_PLUGIN_REF}). Marketplace installs only — for a GitHub URL, put the ref in the URL (.../tree/<ref>/...)`,
-        )
-        .option(
-          "--pin <sha>",
-          "Install a specific reviewed marketplace pin (full commit SHA); run `plugins versions <name>` to list them. Marketplace installs only",
-        )
-        .option(
-          "--allow-unreviewed",
-          "With --pin, install a SHA that is not in the reviewed marketplace history (advanced; the curated adapter may not match). Marketplace installs only",
-        )
-        .option(
-          "--name <name>",
-          "Install directory name for a GitHub-URL install (default: derived from the repo or sub-path leaf). Ignored for marketplace installs",
-        )
-        .addHelpText(
-          "after",
-          `
-A GitHub URL (anything containing a slash) installs directly from that repo,
-bypassing the marketplace whitelist. Such a plugin is UNTRUSTED — it has not
-been reviewed and its hooks/tools run with full assistant access — so the
-install prints a warning. Use it for a plugin still under development that is
-not in the catalog yet. The ref comes from the URL's /tree/<ref>/ segment, or
-defaults to the repository's default branch.
-
-Examples:
-  $ assistant plugins install https://github.com/owner/repo
-  $ assistant plugins install https://github.com/owner/repo/tree/my-branch/path/to/plugin
-  $ assistant plugins install owner/repo --name my-plugin --force`,
-        )
-        .action(
-          async (
-            nameOrUrl: string,
-            opts: {
-              force?: boolean;
-              ref?: string;
-              pin?: string;
-              allowUnreviewed?: boolean;
-              name?: string;
-            },
-          ) => {
-            try {
-              const direct = looksLikeGitHubSpec(nameOrUrl);
-              // A plain marketplace install by name is platform-managed: the
-              // content flows through the platform install endpoint (which
-              // serves a verified `.tgz`), not a GitHub clone. The advanced
-              // pin/ref/allow-unreviewed selectors still resolve a specific
-              // reviewed revision through the marketplace-git path, and a
-              // GitHub URL installs directly (untrusted).
-              const usesMarketplaceGit =
-                !direct &&
-                Boolean(opts.pin || opts.ref || opts.allowUnreviewed);
-
-              let result;
-              let untrusted = false;
-              if (!direct && !usesMarketplaceGit) {
+      subcommand(plugins, "install").action(
+        async (
+          nameOrUrl: string,
+          opts: {
+            force?: boolean;
+            ref?: string;
+            pin?: string;
+            allowUnreviewed?: boolean;
+            name?: string;
+          },
+        ) => {
+          try {
+            const direct = looksLikeGitHubSpec(nameOrUrl);
+            // A plain marketplace install by name is platform-managed: the
+            // content flows through the platform install endpoint (which
+            // serves a verified `.tgz`), not a GitHub clone. The advanced
+            // pin/ref/allow-unreviewed selectors still resolve a specific
+            // reviewed revision through the marketplace-git path, and a
+            // GitHub URL installs directly (untrusted).
+            const usesMarketplaceGit =
+              !direct && Boolean(opts.pin || opts.ref || opts.allowUnreviewed);
+
+            let result;
+            let untrusted = false;
+            if (!direct && !usesMarketplaceGit) {
+              // Platform-managed install serves a verified tarball from the
+              // pinned commit. With platform features disabled (air-gapped /
+              // self-hosted) there is no platform to call, so resolve the pin
+              // from the bundled catalog and install through the GitHub path.
+              if (libs.catalogLocal.arePlatformFeaturesEnabled()) {
                 result = await libs.installPlatform.installPluginViaPlatform(
                   { name: nameOrUrl, force: opts.force },
                   { fetch: globalThis.fetch.bind(globalThis) },
                 );
               } else {
-                const installOpts = direct
-                  ? resolveDirectInstallOptions(nameOrUrl, opts)
-                  : await resolveInstallOptions(nameOrUrl, opts);
-                if (installOpts === null) {
+                const source =
+                  libs.catalogLocal.resolveBundledPluginSource(nameOrUrl);
+                if (!source) {
+                  console.error(
+                    `Plugin "${nameOrUrl}" is not in the bundled marketplace catalog.`,
+                  );
                   process.exitCode = 1;
                   return;
                 }
-                if (installOpts.directSource) {
-                  printUntrustedPluginWarning(
-                    installOpts.name,
-                    installOpts.directSource,
-                  );
-                  untrusted = true;
-                }
-                result = await libs.installGitHub.installPlugin(installOpts, {
-                  fetch: globalThis.fetch.bind(globalThis),
-                });
-              }
-              log.info(
-                {
-                  name: result.name,
-                  target: result.target,
-                  fileCount: result.fileCount,
-                  ref: result.ref,
-                  commit: result.commit,
-                  untrusted,
-                },
-                "external plugin installed",
-              );
-              const pinned = result.commit
-                ? ` at ${result.commit.slice(0, 7)}`
-                : "";
-              const label = untrusted ? "untrusted plugin" : "plugin";
-              console.log(
-                `Installed ${label} "${result.name}" (${result.fileCount} file${result.fileCount === 1 ? "" : "s"})${pinned} → ${result.target}`,
-              );
-            } catch (err) {
-              if (
-                err instanceof libs.installGitHub.PluginAlreadyInstalledError
-              ) {
-                console.error(`${err.message}\nPass --force to overwrite.`);
-                process.exitCode = 1;
-                return;
+                result = await libs.installGitHub.installPlugin(
+                  {
+                    name: nameOrUrl,
+                    force: opts.force,
+                    trustedSource: {
+                      owner: source.owner,
+                      repo: source.repo,
+                      rootPath: source.path,
+                      ref: source.ref,
+                    },
+                  },
+                  { fetch: globalThis.fetch.bind(globalThis) },
+                );
               }
-              if (err instanceof libs.installGitHub.PluginNotFoundError) {
-                console.error(err.message);
+            } else {
+              const installOpts = direct
+                ? resolveDirectInstallOptions(nameOrUrl, opts)
+                : await resolveInstallOptions(nameOrUrl, opts);
+              if (installOpts === null) {
                 process.exitCode = 1;
                 return;
               }
-              if (
-                err instanceof libs.installGitHub.InvalidPluginNameError ||
-                err instanceof libs.pinHistory.PluginPinHistoryError
-              ) {
-                console.error(err.message);
-                process.exitCode = 1;
-                return;
+              if (installOpts.directSource) {
+                printUntrustedPluginWarning(
+                  installOpts.name,
+                  installOpts.directSource,
+                );
+                untrusted = true;
               }
-              const message = err instanceof Error ? err.message : String(err);
-              console.error(`Plugin install failed: ${message}`);
+              result = await libs.installGitHub.installPlugin(installOpts, {
+                fetch: globalThis.fetch.bind(globalThis),
+              });
+            }
+            log.info(
+              {
+                name: result.name,
+                target: result.target,
+                fileCount: result.fileCount,
+                ref: result.ref,
+                commit: result.commit,
+                untrusted,
+              },
+              "external plugin installed",
+            );
+            const pinned = result.commit
+              ? ` at ${result.commit.slice(0, 7)}`
+              : "";
+            const label = untrusted ? "untrusted plugin" : "plugin";
+            console.log(
+              `Installed ${label} "${result.name}" (${result.fileCount} file${result.fileCount === 1 ? "" : "s"})${pinned} → ${result.target}`,
+            );
+          } catch (err) {
+            if (err instanceof libs.installGitHub.PluginAlreadyInstalledError) {
+              console.error(`${err.message}\nPass --force to overwrite.`);
+              process.exitCode = 1;
+              return;
+            }
+            if (err instanceof libs.installGitHub.PluginNotFoundError) {
+              console.error(err.message);
               process.exitCode = 1;
+              return;
             }
-          },
-        );
+            if (
+              err instanceof libs.installGitHub.InvalidPluginNameError ||
+              err instanceof libs.pinHistory.PluginPinHistoryError
+            ) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin install failed: ${message}`);
+            process.exitCode = 1;
+          }
+        },
+      );
 
-      plugins
-        .command("versions <name>")
-        .description(
-          "List the recent reviewed marketplace pins for a plugin, newest first. Install an older one with `plugins install <name> --pin <sha>`",
-        )
-        .option("--json", "Emit machine-readable JSON instead of a table")
-        .option(
-          "--limit <n>",
-          `Maximum number of pins to show (default: ${DEFAULT_PIN_HISTORY_LIMIT})`,
-        )
-        .action(
-          async (name: string, opts: { json?: boolean; limit?: string }) => {
-            let limit: number | undefined;
-            if (opts.limit !== undefined) {
-              limit = Number.parseInt(opts.limit, 10);
-              if (!Number.isInteger(limit) || limit < 1) {
-                console.error("--limit must be a positive integer.");
-                process.exitCode = 1;
-                return;
-              }
+      subcommand(plugins, "versions").action(
+        async (name: string, opts: { json?: boolean; limit?: string }) => {
+          let limit: number | undefined;
+          if (opts.limit !== undefined) {
+            limit = Number.parseInt(opts.limit, 10);
+            if (!Number.isInteger(limit) || limit < 1) {
+              console.error("--limit must be a positive integer.");
+              process.exitCode = 1;
+              return;
             }
-            try {
-              const history = await libs.pinHistory.listPinHistory(
-                name,
-                { fetch: globalThis.fetch.bind(globalThis) },
-                limit !== undefined ? { limit } : {},
-              );
+          }
+          try {
+            const history = await libs.pinHistory.listPinHistory(
+              name,
+              { fetch: globalThis.fetch.bind(globalThis) },
+              limit !== undefined ? { limit } : {},
+            );
 
-              if (opts.json) {
-                process.stdout.write(JSON.stringify(history, null, 2) + "\n");
-                return;
-              }
+            if (opts.json) {
+              process.stdout.write(JSON.stringify(history, null, 2) + "\n");
+              return;
+            }
 
-              // Logged after the JSON early-return so the logger's stdout
-              // writes never corrupt --json output.
-              log.info({ name, count: history.length }, "plugin versions");
-              for (const line of formatVersions(name, history)) {
-                console.log(line);
-              }
-            } catch (err) {
-              if (
-                err instanceof libs.installGitHub.InvalidPluginNameError ||
-                err instanceof libs.pinHistory.PluginPinHistoryError
-              ) {
-                console.error(err.message);
-                process.exitCode = 1;
-                return;
-              }
-              const message = err instanceof Error ? err.message : String(err);
-              console.error(`Plugin versions failed: ${message}`);
+            // Logged after the JSON early-return so the logger's stdout
+            // writes never corrupt --json output.
+            log.info({ name, count: history.length }, "plugin versions");
+            for (const line of formatVersions(name, history)) {
+              console.log(line);
+            }
+          } catch (err) {
+            if (
+              err instanceof libs.installGitHub.InvalidPluginNameError ||
+              err instanceof libs.pinHistory.PluginPinHistoryError
+            ) {
+              console.error(err.message);
               process.exitCode = 1;
+              return;
             }
-          },
-        );
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin versions failed: ${message}`);
+            process.exitCode = 1;
+          }
+        },
+      );
 
-      plugins
-        .command("list")
-        .description("List plugins installed in your workspace.")
-        .option("--json", "Emit machine-readable JSON instead of a table")
-        .option(
-          "--all",
-          "Include first-party default plugins and disabled plugins in the listing",
-        )
-        .action((opts: { json?: boolean; all?: boolean }) => {
+      subcommand(plugins, "list").action(
+        (opts: { json?: boolean; all?: boolean }) => {
           if (opts.all) {
             const all = libs.installed.listAllPlugins();
 
@@ -429,15 +380,11 @@ Examples:
           console.log(
             `${installed.length} plugin${installed.length === 1 ? "" : "s"} installed.`,
           );
-        });
-
-      plugins
-        .command("inspect <name>")
-        .description(
-          "Show a plugin's local install metadata, the marketplace pin, whether an update is available, and the surfaces (skills, hooks, tools) it contributes",
-        )
-        .option("--json", "Emit machine-readable JSON instead of a summary")
-        .action(async (name: string, opts: { json?: boolean }) => {
+        },
+      );
+
+      subcommand(plugins, "inspect").action(
+        async (name: string, opts: { json?: boolean }) => {
           try {
             const inspection = await libs.inspect.inspectPlugin(
               { name },
@@ -478,34 +425,11 @@ Examples:
             console.error(`Plugin inspect failed: ${message}`);
             process.exitCode = 1;
           }
-        });
-
-      plugins
-        .command("diff <name>")
-        .description(
-          "Show a unified diff of local edits to an installed plugin against the commit it was installed at",
-        )
-        .option(
-          "--json",
-          "Emit the machine-readable diff result as JSON (files: { path, status, diff, binary, reconstructed }[]) instead of a unified diff",
-        )
-        .addHelpText(
-          "after",
-          `
-Arguments:
-  name   Install name (kebab-case directory under the workspace plugins dir);
-         run 'assistant plugins list' to see installed names.
-
-The baseline is the exact commit the plugin was installed at (recorded in its
-install-meta.json), re-materialized through the install pipeline — so an
-install-time adapter transform never reads as a local change. To compare
-against the marketplace's current pin instead, use 'plugins upgrade --dry-run'.
-
-Examples:
-  $ assistant plugins diff example
-  $ assistant plugins diff example --json`,
-        )
-        .action(async (name: string, opts: { json?: boolean }) => {
+        },
+      );
+
+      subcommand(plugins, "diff").action(
+        async (name: string, opts: { json?: boolean }) => {
           try {
             const result = await libs.diff.diffPlugin(
               { name },
@@ -545,20 +469,19 @@ Examples:
             console.error(`Plugin diff failed: ${message}`);
             process.exitCode = 1;
           }
-        });
-
-      plugins
-        .command("search <query>")
-        .description(
-          "Search the plugins/marketplace.json catalog for plugin names matching <query> (case-insensitive regex)",
-        )
-        .option("--json", "Emit machine-readable JSON instead of a table")
-        .action(async (query: string, opts: { json?: boolean }) => {
+        },
+      );
+
+      subcommand(plugins, "search").action(
+        async (query: string, opts: { json?: boolean }) => {
           try {
-            const result = await libs.search.searchPlugins(
-              { query },
+            libs.search.assertValidSearchPattern(query);
+            const catalog = await libs.catalogCache.getPluginCatalog(
+              DEFAULT_PLUGIN_REF,
               { fetch: globalThis.fetch.bind(globalThis) },
             );
+            const matches = libs.search.filterPluginCatalog(catalog, query);
+            const result = { query, ref: catalog.ref, matches };
 
             if (opts.json) {
               process.stdout.write(JSON.stringify(result, null, 2) + "\n");
@@ -600,69 +523,37 @@ Examples:
               process.exitCode = 1;
               return;
             }
+            if (err instanceof libs.search.PluginCatalogUnavailableError) {
+              console.error(
+                "The plugin catalog is temporarily unavailable. Try again shortly.",
+              );
+              process.exitCode = 1;
+              return;
+            }
             const message = err instanceof Error ? err.message : String(err);
             console.error(`Plugin search failed: ${message}`);
             process.exitCode = 1;
           }
-        });
-
-      plugins
-        .command("publish")
-        .description(
-          "Validate and submit the plugin in the current directory to the Vellum marketplace catalog",
-        )
-        .option(
-          "--print",
-          "Print the entry JSON without submitting to the platform",
-        )
-        .option(
-          "--path <dir>",
-          "Validate a plugin at the given path instead of CWD",
-        )
-        .option("--force", "Skip the confirmation prompt")
-        .option("--json", "Emit machine-readable JSON instead of human output")
-        .option(
-          "--category <cat>",
-          "Set the category, skipping the interactive prompt",
-        )
-        .addHelpText(
-          "after",
-          `
-
-Validates the plugin in the current directory (or --path), resolves the
-git commit SHA and GitHub remote, and submits the entry to the Vellum
-platform API. The platform creates a pull request against
-vellum-ai/vellum-assistant adding the plugin to the marketplace catalog.
-
-Requires a connected Vellum platform account (run \`assistant platform connect\`).
-Use --print to validate and print the entry without submitting.
-
-Examples:
-$ assistant plugins publish
-$ assistant plugins publish --print
-$ assistant plugins publish --path ./my-plugin --category productivity
-$ assistant plugins publish --json`,
-        )
-        .action(
-          async (opts: {
-            print?: boolean;
-            path?: string;
-            force?: boolean;
-            json?: boolean;
-            category?: string;
-          }) => {
-            const ok = await runPublish(opts, { confirmPrompt });
-            if (!ok) {
-              process.exitCode = 1;
-            }
-          },
-        );
+        },
+      );
 
-      plugins
-        .command("uninstall <name>")
-        .description("Remove a plugin from <workspaceDir>/plugins/<name>/")
-        .option("--force", "Skip the confirmation prompt")
-        .action(async (name: string, opts: { force?: boolean }) => {
+      subcommand(plugins, "publish").action(
+        async (opts: {
+          print?: boolean;
+          path?: string;
+          force?: boolean;
+          json?: boolean;
+          category?: string;
+        }) => {
+          const ok = await runPublish(opts, { confirmPrompt });
+          if (!ok) {
+            process.exitCode = 1;
+          }
+        },
+      );
+
+      subcommand(plugins, "uninstall").action(
+        async (name: string, opts: { force?: boolean }) => {
           try {
             if (!opts.force) {
               const result = await confirmPrompt({
@@ -679,7 +570,32 @@ $ assistant plugins publish --json`,
                 return;
               }
             }
-            const result = await libs.uninstall.uninstallPlugin({ name });
+            // Prefer the daemon: it runs the plugin's `shutdown` hook and drops
+            // the plugin's tools/hooks in the main process — symmetric to how
+            // install runs `init` there. Fall back to a local uninstall only
+            // when the daemon is unreachable (a transport error carries no
+            // `statusCode`); an operator can still uninstall while it's stopped,
+            // and `shutdown` then runs in this process, the only one available.
+            const daemon = await cliIpcCall<{ name: string; target: string }>(
+              "plugins_uninstall",
+              { pathParams: { name } },
+            );
+            let result: { name: string; target: string };
+            if (daemon.ok && daemon.result) {
+              result = daemon.result;
+            } else if (daemon.statusCode === undefined) {
+              log.debug(
+                { name, error: daemon.error },
+                "uninstall could not reach the daemon; running shutdown + removal locally",
+              );
+              result = await libs.uninstall.uninstallPlugin({ name });
+            } else {
+              // The daemon reached a decision (not installed, bad name, …);
+              // surface it rather than silently retrying locally.
+              console.error(daemon.error ?? "Plugin uninstall failed.");
+              process.exitCode = 1;
+              return;
+            }
             log.info(
               { name: result.name, target: result.target },
               "external plugin uninstalled",
@@ -702,93 +618,91 @@ $ assistant plugins publish --json`,
             console.error(`Plugin uninstall failed: ${message}`);
             process.exitCode = 1;
           }
-        });
-
-      plugins
-        .command("disable <name>")
-        .description(
-          "Disable a plugin by creating a .disabled sentinel file. Works for both user-installed and default plugins. Takes effect immediately in a running assistant.",
-        )
-        .action((name: string) => {
-          try {
-            const result = disablePlugin(name);
-            log.info({ name: result.name }, "plugin disabled");
-            console.log(`Disabled plugin "${result.name}".`);
-          } catch (err) {
-            if (
-              err instanceof PluginAlreadyInStateException ||
-              err instanceof ToggleInvalidPluginNameError ||
-              err instanceof PluginDirectoryNotFoundError
-            ) {
-              console.error(err.message);
-              process.exitCode = 1;
-              return;
-            }
-            const message = err instanceof Error ? err.message : String(err);
-            console.error(`Plugin disable failed: ${message}`);
+        },
+      );
+
+      subcommand(plugins, "disable").action((name: string) => {
+        try {
+          const result = disablePlugin(name);
+          log.info({ name: result.name }, "plugin disabled");
+          console.log(`Disabled plugin "${result.name}".`);
+        } catch (err) {
+          if (
+            err instanceof PluginAlreadyInStateException ||
+            err instanceof ToggleInvalidPluginNameError ||
+            err instanceof PluginDirectoryNotFoundError
+          ) {
+            console.error(err.message);
             process.exitCode = 1;
+            return;
           }
-        });
-
-      plugins
-        .command("enable <name>")
-        .description(
-          "Re-enable a disabled plugin by removing the .disabled sentinel file. Takes effect immediately.",
-        )
-        .action((name: string) => {
-          try {
-            const result = enablePlugin(name);
-            log.info({ name: result.name }, "plugin enabled");
-            console.log(`Enabled plugin "${result.name}".`);
-          } catch (err) {
-            if (
-              err instanceof PluginAlreadyInStateException ||
-              err instanceof ToggleInvalidPluginNameError
-            ) {
-              console.error(err.message);
-              process.exitCode = 1;
-              return;
-            }
-            const message = err instanceof Error ? err.message : String(err);
-            console.error(`Plugin enable failed: ${message}`);
+          const message = err instanceof Error ? err.message : String(err);
+          console.error(`Plugin disable failed: ${message}`);
+          process.exitCode = 1;
+        }
+      });
+
+      subcommand(plugins, "enable").action((name: string) => {
+        try {
+          const result = enablePlugin(name);
+          log.info({ name: result.name }, "plugin enabled");
+          console.log(`Enabled plugin "${result.name}".`);
+        } catch (err) {
+          if (
+            err instanceof PluginAlreadyInStateException ||
+            err instanceof ToggleInvalidPluginNameError
+          ) {
+            console.error(err.message);
             process.exitCode = 1;
+            return;
           }
-        });
-
-      plugins
-        .command("upgrade <name>")
-        .description(
-          "Upgrade an installed plugin to the marketplace's current pin",
-        )
-        .option(
-          "--dry-run",
-          "Show what would change without modifying the install",
-        )
-        .option(
-          "--strategy <strategy>",
-          `How to reconcile local edits with the pin: ${PLUGIN_UPGRADE_STRATEGIES.join(", ")} (default: ${DEFAULT_PLUGIN_UPGRADE_STRATEGY})`,
-        )
-        .option("--json", "Emit machine-readable JSON instead of a summary")
-        .action(
-          async (
-            name: string,
-            opts: { dryRun?: boolean; strategy?: string; json?: boolean },
-          ) => {
-            const strategy = opts.strategy;
-            if (
-              strategy !== undefined &&
-              !(PLUGIN_UPGRADE_STRATEGIES as readonly string[]).includes(
-                strategy,
-              )
-            ) {
-              console.error(
-                `Invalid --strategy "${strategy}". Expected one of: ${PLUGIN_UPGRADE_STRATEGIES.join(", ")}.`,
+          const message = err instanceof Error ? err.message : String(err);
+          console.error(`Plugin enable failed: ${message}`);
+          process.exitCode = 1;
+        }
+      });
+
+      subcommand(plugins, "upgrade").action(
+        async (
+          name: string,
+          opts: { dryRun?: boolean; strategy?: string; json?: boolean },
+        ) => {
+          const strategy = opts.strategy;
+          if (
+            strategy !== undefined &&
+            !(PLUGIN_UPGRADE_STRATEGIES as readonly string[]).includes(strategy)
+          ) {
+            console.error(
+              `Invalid --strategy "${strategy}". Expected one of: ${PLUGIN_UPGRADE_STRATEGIES.join(", ")}.`,
+            );
+            process.exitCode = 1;
+            return;
+          }
+          try {
+            // Prefer the daemon: when the upgrade re-materializes files it runs
+            // the plugin's `shutdown` + `init` hooks in the main process —
+            // symmetric to how install/uninstall run their lifecycle there.
+            // Fall back to a local upgrade only when the daemon is unreachable
+            // (a transport error carries no `statusCode`); an operator can still
+            // upgrade while it's stopped, and the new code is picked up on the
+            // daemon's next start. A daemon-side decision (not installed, not
+            // upgradable, …) is surfaced rather than silently retried locally.
+            const daemon = await cliIpcCall<PluginUpgradeResult>(
+              "plugins_upgrade",
+              {
+                pathParams: { name },
+                body: { dryRun: opts.dryRun, strategy },
+              },
+            );
+            let result: PluginUpgradeResult;
+            if (daemon.ok && daemon.result) {
+              result = daemon.result;
+            } else if (daemon.statusCode === undefined) {
+              log.debug(
+                { name, error: daemon.error },
+                "upgrade could not reach the daemon; upgrading locally",
               );
-              process.exitCode = 1;
-              return;
-            }
-            try {
-              const result = await libs.upgrade.upgradePlugin(
+              result = await libs.upgrade.upgradePlugin(
                 {
                   name,
                   dryRun: opts.dryRun,
@@ -796,44 +710,49 @@ $ assistant plugins publish --json`,
                 },
                 { fetch: globalThis.fetch.bind(globalThis) },
               );
+            } else {
+              console.error(daemon.error ?? "Plugin upgrade failed.");
+              process.exitCode = 1;
+              return;
+            }
 
-              if (opts.json) {
-                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-                return;
-              }
+            if (opts.json) {
+              process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+              return;
+            }
 
-              // Logged after the JSON early-return: the CLI logger writes
-              // info to stdout, which would otherwise corrupt --json output.
-              log.info(
-                {
-                  name: result.name,
-                  outcome: result.outcome,
-                  from: result.fromCommit,
-                  to: result.toCommit,
-                },
-                "plugin upgrade",
-              );
+            // Logged after the JSON early-return: the CLI logger writes
+            // info to stdout, which would otherwise corrupt --json output.
+            log.info(
+              {
+                name: result.name,
+                outcome: result.outcome,
+                from: result.fromCommit,
+                to: result.toCommit,
+              },
+              "plugin upgrade",
+            );
 
-              for (const line of formatUpgrade(result)) {
-                console.log(line);
-              }
-            } catch (err) {
-              if (
-                err instanceof libs.uninstall.PluginNotInstalledError ||
-                err instanceof libs.upgrade.PluginNotUpgradableError ||
-                err instanceof libs.upgrade.PluginMergeBaselineError ||
-                err instanceof libs.installGitHub.InvalidPluginNameError
-              ) {
-                console.error(err.message);
-                process.exitCode = 1;
-                return;
-              }
-              const message = err instanceof Error ? err.message : String(err);
-              console.error(`Plugin upgrade failed: ${message}`);
+            for (const line of formatUpgrade(result)) {
+              console.log(line);
+            }
+          } catch (err) {
+            if (
+              err instanceof libs.uninstall.PluginNotInstalledError ||
+              err instanceof libs.upgrade.PluginNotUpgradableError ||
+              err instanceof libs.upgrade.PluginMergeBaselineError ||
+              err instanceof libs.installGitHub.InvalidPluginNameError
+            ) {
+              console.error(err.message);
               process.exitCode = 1;
+              return;
             }
-          },
-        );
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin upgrade failed: ${message}`);
+            process.exitCode = 1;
+          }
+        },
+      );
     },
   });
 }
@@ -1283,7 +1202,7 @@ function formatUpgrade(result: PluginUpgradeResult): string[] {
         `Upgraded "${name}" ${move}`,
         "",
         `${count}→ ${result.target}`,
-        "Restart the assistant to pick up the upgrade.",
+        "The upgrade is picked up live (no restart required).",
       ];
       if (mergeNote) {
         lines.push(mergeNote);