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 a raw stderr writer chosen visibly in
that function's own body, not inherited from a shared library
default.

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

@@ -80,8 +80,16 @@ 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 raw stderr —
+  // chosen here (not a hidden library default) for standalone/test callers
+  // that supply neither.
+  const onWarning = resolvePluginWarningHandler(
+    opts.diagnostics !== undefined
+      ? { diagnostics: opts.diagnostics }
+      : opts.onWarning !== undefined
+        ? { onWarning: opts.onWarning }
+        : { onWarning: (msg: string) => process.stderr.write(`plugins: ${msg}\n`) },
+  );
 
   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,23 @@ export function createPluginLoadDiagnostics(): PluginLoadDiagnostics {
   return { warnings: [] };
 }
 
-/**
- * Build an onWarning callback that records into `diag` when provided, else
- * falls back to the given sink (default: one stderr line per message).
- */
-export function pluginWarningSink(
-  diag: PluginLoadDiagnostics | undefined,
-  fallback: (msg: string) => void = (msg) => process.stderr.write(`plugins: ${msg}\n`),
-): (msg: string) => void {
-  if (diag !== undefined) {
-    return (msg) => {
-      diag.warnings.push(msg);
-    };
-  }
-  return fallback;
+/** Build an onWarning callback that records into `diag`. */
+export function pluginWarningSink(diag: PluginLoadDiagnostics): (msg: string) => void {
+  return (msg) => {
+    diag.warnings.push(msg);
+  };
 }
 
 /**
- * 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.
+ * 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 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);
+export function resolvePluginWarningHandler(
+  opts: { diagnostics: PluginLoadDiagnostics } | { onWarning: (msg: string) => void },
+): (msg: string) => void {
+  return "diagnostics" in opts ? pluginWarningSink(opts.diagnostics) : opts.onWarning;
 }
 
 /**

src/plugins/loader.ts

@@ -116,9 +116,17 @@ 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 when provided so batch discovery can
+  // summarize; explicit onWarning is for tests / one-off sinks; raw stderr
+  // is chosen here (not a hidden library default) for callers that supply
+  // neither.
+  const onWarning = resolvePluginWarningHandler(
+    opts.diagnostics !== undefined
+      ? { diagnostics: opts.diagnostics }
+      : opts.onWarning !== undefined
+        ? { onWarning: opts.onWarning }
+        : { onWarning: (msg: string) => process.stderr.write(`plugins: ${msg}\n`) },
+  );
   const origin = opts.origin;
   let target = entryPath;
   let pluginDir = entryPath;
@@ -657,12 +665,13 @@ 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 raw stderr — chosen here for
+    // callers (tests, standalone use) with no collector.
     resolvePluginWarningHandler(
-      opts.diagnostics !== undefined ? { diagnostics: opts.diagnostics } : {},
-    )(
-      `failed to parse ${registryPath}`,
-    );
+      opts.diagnostics !== undefined
+        ? { diagnostics: opts.diagnostics }
+        : { onWarning: (msg: string) => process.stderr.write(`plugins: ${msg}\n`) },
+    )(`failed to parse ${registryPath}`);
     return [];
   }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
@@ -675,9 +684,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.
+  // can emit one summary; explicit onExpandSkip (tests) still wins; raw
+  // stderr is the deliberate fallback when neither is given.
   const warnExpand = resolvePluginWarningHandler(
-    opts.diagnostics !== undefined ? { diagnostics: opts.diagnostics } : {},
+    opts.diagnostics !== undefined
+      ? { diagnostics: opts.diagnostics }
+      : { onWarning: (msg: string) => process.stderr.write(`plugins: ${msg}\n`) },
   );
   const onExpandSkip =
     opts.onExpandSkip

src/plugins/tool-plugins.ts

@@ -52,7 +52,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: (msg: string) => process.stderr.write(`plugins: ${msg}\n`) },
   );
   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);
+  });
+});