Close the last raw-stderr default in the plugin diagnostics chain

resolvePluginWarningHandler still fell back to a raw stderr write when
given neither a diagnostics collector nor an explicit onWarning, the
same silent-default shape that produced four rounds of one-off fixes
at the call-site level. Make the choice a required discriminated
union (diagnostics or onWarning, no third option) so the compiler
enumerates every caller.

pluginWarningSink drops its own fallback parameter, since that was
only ever reachable through the branch just removed.

Each of the five call sites the compiler surfaced now builds its own
explicit union locally: real callers that hold a diagnostics
collector keep using it, and the handful of standalone/test call
sites that pass neither get the raw stderr writer via a single named
export, stderrPluginWarning, instead of five copies of the same
inline lambda — greppable, and one place to change if the prefix or
destination ever does.

Extends the behavioural stderr-capture test to pin that
resolveToolPlugins still falls back correctly (one write per
warning) when called with no collector at all.

Author: TheGreatAxios

src/plugins/data-only.ts

@@ -7,6 +7,7 @@ import { loadDataOnlyCommands } from "./data-only-commands.js";
 import { loadSkillCommands } from "./skill-commands.js";
 import {
   resolvePluginWarningHandler,
+  stderrPluginWarning,
   type PluginLoadDiagnostics,
 } from "./diagnostics.js";
 
@@ -80,8 +81,14 @@ export async function loadDataOnlyPlugin(
   } = {},
 ): Promise<DataOnlyPlugin | null> {
   const cwd = opts.cwd ?? process.cwd();
-  // Prefer diagnostics collector; else explicit onWarning; else stderr default.
-  const onWarning = resolvePluginWarningHandler(opts);
+  // Prefer diagnostics collector; else explicit onWarning; else stderrPluginWarning.
+  const onWarning = resolvePluginWarningHandler(
+    opts.diagnostics !== undefined
+      ? { diagnostics: opts.diagnostics }
+      : opts.onWarning !== undefined
+        ? { onWarning: opts.onWarning }
+        : { onWarning: stderrPluginWarning },
+  );
 
   const [nativeManifest, claudeManifest, agents, commands, skillCmds] = await Promise.all([
     readManifestJson(pluginDir),

src/plugins/diagnostics.test.ts

@@ -97,13 +97,10 @@ describe("plugin load diagnostics wiring", () => {
       "agents/a.md": "---\nskills: [nope, also-missing]\n---\nbody\n",
     });
     const diag = createPluginLoadDiagnostics();
-    const stderrLines: string[] = [];
-    const sink = pluginWarningSink(diag, (msg) => stderrLines.push(msg));
+    const sink = pluginWarningSink(diag);
 
-    // Sink itself must not hit fallback when diag is set.
     sink("should only land in diag");
     expect(diag.warnings).toEqual(["should only land in diag"]);
-    expect(stderrLines).toEqual([]);
 
     diag.warnings.length = 0;
     const mod = await loadPluginEntry(dir, {

src/plugins/diagnostics.ts

@@ -15,34 +15,28 @@ export function createPluginLoadDiagnostics(): PluginLoadDiagnostics {
   return { warnings: [] };
 }
 
+/** Build an onWarning callback that records into `diag`. */
+export function pluginWarningSink(diag: PluginLoadDiagnostics): (msg: string) => void {
+  return (msg) => {
+    diag.warnings.push(msg);
+  };
+}
+
 /**
- * Build an onWarning callback that records into `diag` when provided, else
- * falls back to the given sink (default: one stderr line per message).
+ * Resolve the warning sink for a load call. There is no default: callers
+ * must decide between a diagnostics collector (batched into one summary,
+ * safe mid-frame) and an explicit onWarning (e.g. a raw stderr writer for
+ * headless paths where no frame is being held).
  */
-export function pluginWarningSink(
-  diag: PluginLoadDiagnostics | undefined,
-  fallback: (msg: string) => void = (msg) => process.stderr.write(`plugins: ${msg}\n`),
+export function resolvePluginWarningHandler(
+  opts: { diagnostics: PluginLoadDiagnostics } | { onWarning: (msg: string) => void },
 ): (msg: string) => void {
-  if (diag !== undefined) {
-    return (msg) => {
-      diag.warnings.push(msg);
-    };
-  }
-  return fallback;
+  return "diagnostics" in opts ? pluginWarningSink(opts.diagnostics) : opts.onWarning;
 }
 
-/**
- * Resolve the warning sink for a load call. Prefer a diagnostics collector when
- * provided (so batch callers can emit one summary); else an explicit onWarning;
- * else one stderr line per message.
- */
-export function resolvePluginWarningHandler(opts: {
-  diagnostics?: PluginLoadDiagnostics;
-  onWarning?: (msg: string) => void;
-}): (msg: string) => void {
-  if (opts.diagnostics !== undefined) return pluginWarningSink(opts.diagnostics);
-  if (opts.onWarning !== undefined) return opts.onWarning;
-  return pluginWarningSink(undefined);
+/** Named raw-stderr choice: `{ onWarning: stderrPluginWarning }`. */
+export function stderrPluginWarning(msg: string): void {
+  process.stderr.write(`plugins: ${msg}\n`);
 }
 
 /**

src/plugins/loader.ts

@@ -10,6 +10,7 @@ import { parsePluginManifest, type PluginManifest } from "./manifest.js";
 import { loadDataOnlyPlugin } from "./data-only.js";
 import {
   resolvePluginWarningHandler,
+  stderrPluginWarning,
   type PluginLoadDiagnostics,
 } from "./diagnostics.js";
 import {
@@ -116,9 +117,15 @@ export async function loadPluginEntry(
   } = {},
 ): Promise<PluginModule | null> {
   const cwd = opts.cwd ?? process.cwd();
-  // Prefer diagnostics collector when provided so batch discovery can summarize;
-  // explicit onWarning is for tests / one-off sinks; default is stderr per line.
-  const onWarning = resolvePluginWarningHandler(opts);
+  // Prefer diagnostics collector so batch discovery can summarize; explicit
+  // onWarning for tests; else stderrPluginWarning.
+  const onWarning = resolvePluginWarningHandler(
+    opts.diagnostics !== undefined
+      ? { diagnostics: opts.diagnostics }
+      : opts.onWarning !== undefined
+        ? { onWarning: opts.onWarning }
+        : { onWarning: stderrPluginWarning },
+  );
   const origin = opts.origin;
   let target = entryPath;
   let pluginDir = entryPath;
@@ -657,12 +664,12 @@ export async function discoverClaudeInstalledPlugins(
   try {
     parsed = JSON.parse(raw);
   } catch {
-    // Prefer collector when present; else one stderr line (default sink).
+    // Prefer collector when present; else stderrPluginWarning.
     resolvePluginWarningHandler(
-      opts.diagnostics !== undefined ? { diagnostics: opts.diagnostics } : {},
-    )(
-      `failed to parse ${registryPath}`,
-    );
+      opts.diagnostics !== undefined
+        ? { diagnostics: opts.diagnostics }
+        : { onWarning: stderrPluginWarning },
+    )(`failed to parse ${registryPath}`);
     return [];
   }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
@@ -674,10 +681,12 @@ export async function discoverClaudeInstalledPlugins(
   }
 
   const pluginsRoot = resolve(home, ".claude", "plugins");
-  // Default expand-skip sink respects diagnostics when provided so discovery
-  // can emit one summary; explicit onExpandSkip (tests) still wins.
+  // Default expand-skip sink: diagnostics when provided, else
+  // stderrPluginWarning; explicit onExpandSkip (tests) still wins.
   const warnExpand = resolvePluginWarningHandler(
-    opts.diagnostics !== undefined ? { diagnostics: opts.diagnostics } : {},
+    opts.diagnostics !== undefined
+      ? { diagnostics: opts.diagnostics }
+      : { onWarning: stderrPluginWarning },
   );
   const onExpandSkip =
     opts.onExpandSkip

src/plugins/tool-plugins.ts

@@ -5,6 +5,7 @@ import type { PluginCredentialField } from "./manifest.js";
 import { scrubSecrets } from "../web/secret-scrub.js";
 import {
   resolvePluginWarningHandler,
+  stderrPluginWarning,
   type PluginLoadDiagnostics,
 } from "./diagnostics.js";
 
@@ -52,7 +53,9 @@ export async function resolveToolPlugins(args: {
   diagnostics?: PluginLoadDiagnostics;
 }): Promise<ToolPlugin[]> {
   const onWarning = resolvePluginWarningHandler(
-    args.diagnostics === undefined ? {} : { diagnostics: args.diagnostics },
+    args.diagnostics !== undefined
+      ? { diagnostics: args.diagnostics }
+      : { onWarning: stderrPluginWarning },
   );
   const out: ToolPlugin[] = [];
   for (const cand of args.candidates) {

src/tui/plugin-diagnostics-sink.test.ts

@@ -247,3 +247,32 @@ describe("interactive plugin diagnostics never hit raw stderr", () => {
     expect(writes).toBe(0);
   });
 });
+
+// The interactive paths above always hand `resolveToolPlugins` a diagnostics
+// collector. Headless/standalone callers (exec's tool-plugin resolution,
+// direct unit tests) may supply neither `diagnostics` nor `onWarning` —
+// `resolveToolPlugins` still resolves that case, but now via its own
+// explicit stderr fallback rather than delegating to
+// `resolvePluginWarningHandler`'s old default. This pins that the fallback
+// still fires exactly once per warning (not silently dropped) when no
+// collector is in play, matching a genuinely headless call site.
+describe("resolveToolPlugins without a diagnostics collector", () => {
+  test("falls back to one explicit stderr write per failure", async () => {
+    const candidate: ToolPluginCandidate = {
+      id: "throws",
+      name: "Throws",
+      credentials: [],
+      factory: () => {
+        throw new Error("boom");
+      },
+    };
+    const { result: tools, writes } = await withStderrCapture(async () =>
+      resolveToolPlugins({
+        candidates: [candidate],
+        pluginConfig: { throws: { enabled: true, consented: true } },
+      }),
+    );
+    expect(tools).toEqual([]);
+    expect(writes).toBe(1);
+  });
+});