scoutline 0.15.0 → 0.16.0

package/dist/commands/search.d.ts

@@ -13,6 +13,8 @@ import type { CommandContext, CommandResult } from "../command-invocation.js";
 import type { SearchCapability, SearchTopic, SearchType } from "../capabilities/search.js";
 import type { ResponseCache } from "../lib/cache.js";
 import type { RetryPolicy } from "../lib/execution.js";
+import type { ProviderDescriptor, ProviderId } from "../providers/types.js";
+import type { ConsumptionSink } from "../lib/consumption.js";
 type RecencyFilter = "oneDay" | "oneWeek" | "oneMonth" | "oneYear" | "noLimit";
 export interface SearchOptions {
     count?: number;
@@ -40,7 +42,155 @@ export interface SearchExecutionDependencies {
     readonly random: () => number;
     readonly retryPolicy?: RetryPolicy;
 }
+interface FormattedResult {
+    rank: number;
+    title: string;
+    url: string;
+    summary: string;
+    source?: string;
+    date?: string;
+    /** Set when merging multiple queries: how many sub-queries surfaced this URL. */
+    occurrences?: number;
+    /**
+     * Provenance (fan-out only, DESIGN D3): distinct providers that
+     * surfaced this URL, in first-encounter order. Omitted on the
+     * single-provider path — SCHEMA.md.
+     */
+    mergedFrom?: ProviderId[];
+}
+/**
+ * One arm of a merge grid: a Provider's results split into sub-queries.
+ * `provider` is absent on the single-provider `--merge` path (no
+ * provenance is tracked there); the fan-out path always sets it.
+ */
+export interface MergeGridArm {
+    provider?: ProviderId;
+    results: FormattedResult[][];
+}
+export interface MergeResultsOptions {
+    /** Emit mergedFrom provenance on every result (fan-out active). */
+    emitMergedFrom?: boolean;
+    /** Post-merge --count cap. Each arm was already asked for this count. */
+    count?: number;
+}
+/**
+ * Merge results from an (arm × sub-query) grid (DESIGN D3). Generalizes
+ * the pre-fan-out sub-query merge with exactly one new key: dedupe by
+ * `canonicalUrl(url)` (DESIGN D4) instead of the raw string. Ranking is
+ * unchanged — (occurrence count desc, best position asc) — but
+ * `occurrences` now counts across the whole arms × sub-queries grid.
+ * First-writer-wins: the earlier arm's title/summary/url win a collision
+ * (arm order is the tiebreak priority). Every URL accumulates
+ * `mergedFrom` (distinct providers, first-encounter order) when
+ * `emitMergedFrom` is set, and the merged list is sliced to `count`
+ * post-merge. The single-provider `--merge` path and the fan-out path
+ * share this one implementation.
+ */
+export declare function mergeResults(grid: MergeGridArm[], options?: MergeResultsOptions): FormattedResult[];
 export declare function search(query: string, options: SearchOptions | undefined, deps: SearchExecutionDependencies, context?: CommandContext): Promise<CommandResult>;
+/**
+ * Resolved activation plan. `mode` is the dispatcher hinge; `arms` is
+ * the ordered Provider list to execute (already expanded and
+ * filtered — never the `"all"` sentinel; the resolver owns the
+ * expansion against its injected descriptors). `suppress` is the
+ * human-readable reason the resolver ignored fan-out (e.g. "explicit
+ * pin: fan-out ignored"); emitted on the single-pin path so the user
+ * understands why fan-out did not engage.
+ */
+export interface FanoutPlan {
+    readonly mode: "single" | "fanout";
+    readonly arms: ProviderId[];
+    readonly suppress?: string;
+}
+/**
+ * Options for {@link resolveFanoutPlan}. The resolver is pure: every
+ * input is an injected value, no I/O, no environment reads. `configFanout`
+ * is the lone scalar read from the user config (Ticket 4 owns the
+ * registry row); `routing` is the typed routing table already in
+ * `HandlerDependencies`. `descriptors` is the live provider registry —
+ * the resolver uses it for `isConfigured(env)` + `capabilities()`
+ * filtering (the same gate `resolveEffectiveProvider` uses) so the
+ * arm list the executor sees is the same list the executor would
+ * otherwise walk, giving the dispatcher a single source of truth.
+ */
+export interface ResolveFanoutPlanOptions {
+    /** Raw `--provider` value (or undefined). Empty string is treated as absent. */
+    readonly explicitProviderRaw: string | undefined;
+    /** The resolved env the handler runs under (env + file-configured keys). */
+    readonly env: NodeJS.ProcessEnv;
+    /** Whether `fanout` is enabled in the active config. */
+    readonly configFanout: boolean;
+    /** Resolved per-capability routing table (routing-table plan). */
+    readonly routing?: Readonly<Record<string, readonly ProviderId[]>>;
+    /** Live provider registry; the resolver filters by capability "search". */
+    readonly descriptors: readonly ProviderDescriptor[];
+}
+/**
+ * Resolve the activation plan (D1). Tiers in precedence order:
+ *
+ *   1. **Explicit raw** (D1.1): a comma list or `"all"` → fanout
+ *      (`"all"` expands to configured ∩ advertising in registry
+ *      order); a single id → single (with suppress when
+ *      `configFanout=true`).
+ *   2. **SCOUTLINE_PROVIDER env** (D1.2): a pin → single (suppress
+ *      when `configFanout=true`).
+ *   3. **`configFanout=true` with no pin** (D1.3): fanout; arms =
+ *      `routing.search` filtered/deduped (if set), else configured ∩
+ *      advertising in registry order.
+ *   4. **Default** (D1.4): single; arm = first configured ∩
+ *      advertising in registry order (informational — the dispatcher
+ *      still consults `resolveEffectiveProvider` for quota ranking).
+ *
+ * The resolver exposes its decision only through the returned
+ * `FanoutPlan`; the dispatcher hinges on `mode`. The truth table is
+ * pinned by Ticket 3 tests.
+ */
+export declare function resolveFanoutPlan(options: ResolveFanoutPlanOptions): FanoutPlan;
+/**
+ * Options for {@link executeFanoutPlan}. The executor owns the
+ * per-arm Lifecycle (descriptor.create → adapter → executeSearch →
+ * close) and the merged error envelope. `query` is the resolved raw
+ * query; when `searchOptions.merge` is set the executor splits it on
+ * unescaped `|` and runs EVERY sub-query on EVERY arm — DESIGN D3's
+ * (arm × sub-query) merge grid.
+ *
+ * `dependencies` is a subset of {@link SearchExecutionDependencies}:
+ * the per-arm capability is constructed internally by the executor
+ * (one per arm), so the caller does not supply a single shared
+ * capability. Only the shared cache/policy seams cross arms.
+ */
+export interface FanoutExecutionDependencies {
+    readonly cache: ResponseCache;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly random: () => number;
+    readonly retryPolicy?: RetryPolicy;
+    /**
+     * Optional consumption sink (PB-T2 parity with the other billable
+     * seams). When present, every arm's `executeSearch` emits one
+     * consumption event per billable invoke attempt through it — fan-out
+     * arms must not silently skip local quota accounting (review fix,
+     * PR #36).
+     */
+    readonly consume?: ConsumptionSink;
+    /** Timestamp source for consumption events; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+export interface FanoutExecutionOptions {
+    readonly descriptors: readonly ProviderDescriptor[];
+    readonly env: NodeJS.ProcessEnv;
+    readonly query: string;
+    readonly searchOptions: SearchOptions;
+    readonly dependencies: FanoutExecutionDependencies;
+    readonly secrets?: string[];
+}
+/**
+ * Execute the fan-out plan: parallel per-arm search, settled wrapper,
+ * per-arm notices, D5/D6 exit policy, combined summary notice. The
+ * single-pin path is NOT routed through this executor (Tier 2 / Tier 4
+ * stay verbatim through `executeWithFallback`); the executor asserts
+ * `mode === "fanout"` on entry so a misuse throws loudly.
+ */
+export declare function executeFanoutPlan(plan: FanoutPlan, options: FanoutExecutionOptions, context?: CommandContext): Promise<CommandResult>;
 export declare const SEARCH_HELP: string;
 export {};
 //# sourceMappingURL=search.d.ts.map

package/dist/commands/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAqB,MAAM,0BAA0B,CAAC;AACjG,OAAO,KAAK,EACV,gBAAgB,EAIhB,WAAW,EACX,UAAU,EACX,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,KAAK,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/E,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC;AA+HD,wBAAsB,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,YAAK,EAC3B,IAAI,EAAE,2BAA2B,EACjC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,CA2DxB;AAGD,eAAO,MAAM,WAAW,QAmEhB,CAAC"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"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"}

package/dist/commands/search.js

@@ -10,7 +10,11 @@
  * execution and never enters an Adapter request or cache identity.
  */
 import { executeSearch } from "../lib/execution.js";
+import { canonicalUrl } from "../lib/url.js";
 import { formatSearchResultsPretty } from "../lib/tty.js";
+import { ValidationError, UnsupportedOptionError, UnsupportedCapabilityError, } from "../lib/errors.js";
+import { redactCredentialString } from "../lib/redact.js";
+import { parseProviderId, parseProviderIds } from "../providers/selection.js";
 function truncate(text, max) {
     if (!text)
         return "";
@@ -52,38 +56,68 @@ function buildControls(options) {
     return Object.keys(controls).length > 0 ? controls : undefined;
 }
 /**
- * Merge results from N parallel sub-queries: dedupe by URL, rank by
- * (occurrence count desc, then best position asc). First sub-query's
- * title/summary wins for each URL (highest-priority query).
+ * Merge results from an (arm × sub-query) grid (DESIGN D3). Generalizes
+ * the pre-fan-out sub-query merge with exactly one new key: dedupe by
+ * `canonicalUrl(url)` (DESIGN D4) instead of the raw string. Ranking is
+ * unchanged — (occurrence count desc, best position asc) — but
+ * `occurrences` now counts across the whole arms × sub-queries grid.
+ * First-writer-wins: the earlier arm's title/summary/url win a collision
+ * (arm order is the tiebreak priority). Every URL accumulates
+ * `mergedFrom` (distinct providers, first-encounter order) when
+ * `emitMergedFrom` is set, and the merged list is sliced to `count`
+ * post-merge. The single-provider `--merge` path and the fan-out path
+ * share this one implementation.
  */
-function mergeResults(byQuery) {
+export function mergeResults(grid, options = {}) {
+    const { emitMergedFrom = false, count } = options;
     const map = new Map();
-    for (const [, results] of byQuery.entries()) {
-        for (const r of results) {
-            const existing = map.get(r.url);
-            if (existing) {
-                existing.occurrences += 1;
-                existing.bestPos = Math.min(existing.bestPos, r.rank);
-            }
-            else {
-                map.set(r.url, {
-                    ...r,
-                    occurrences: 1,
-                    bestPos: r.rank,
-                });
+    for (const arm of grid) {
+        for (const results of arm.results) {
+            for (const r of results) {
+                // canonicalUrl is the Map key only; the emitted url stays the
+                // first writer's original string (DESIGN D3 "Identity").
+                const key = canonicalUrl(r.url);
+                const existing = map.get(key);
+                if (existing) {
+                    existing.occurrences += 1;
+                    existing.bestPos = Math.min(existing.bestPos, r.rank);
+                    if (emitMergedFrom && arm.provider && !existing.mergedFrom.includes(arm.provider)) {
+                        existing.mergedFrom.push(arm.provider);
+                    }
+                }
+                else {
+                    map.set(key, {
+                        ...r,
+                        occurrences: 1,
+                        bestPos: r.rank,
+                        mergedFrom: emitMergedFrom && arm.provider ? [arm.provider] : [],
+                    });
+                }
             }
         }
     }
-    const merged = Array.from(map.values());
+    let merged = Array.from(map.values());
     merged.sort((a, b) => {
         if (b.occurrences !== a.occurrences)
             return b.occurrences - a.occurrences;
         return a.bestPos - b.bestPos;
     });
+    // Post-merge --count slice (each arm was already asked for this count).
+    if (count !== undefined) {
+        merged = merged.slice(0, Math.max(0, count));
+    }
     return merged.map((r, i) => {
         const { bestPos: _bp, ...rest } = r;
         void _bp;
-        return { ...rest, rank: i + 1 };
+        const rank = i + 1;
+        if (!emitMergedFrom) {
+            // Omit mergedFrom entirely on the single path (SCHEMA.md) so the
+            // emitted objects stay byte-identical to the pre-fan-out merge.
+            const { mergedFrom: _mf, ...restNoProvenance } = rest;
+            void _mf;
+            return { ...restNoProvenance, rank };
+        }
+        return { ...rest, rank };
     });
 }
 function renderTextFormat(results, mode) {
@@ -130,19 +164,30 @@ function formatSources(sources, maxSummary) {
         return formatted;
     });
 }
+/**
+ * Split a `--merge` query into sub-queries: split on unescaped `|` (a
+ * literal pipe is escaped as `\|`), trim, and drop empty fragments. A
+ * merge query with no non-empty fragments is a usage error. Shared by
+ * the single-provider path and the fan-out executor — DESIGN D3's merge
+ * grid is (arm × sub-query), so every arm runs every sub-query.
+ */
+function splitMergeSubQueries(query) {
+    const subQueries = query
+        .split(/(?<!\\)\|/)
+        .map((q) => q.replace(/\\\|/g, "|").trim())
+        .filter((q) => q.length > 0);
+    if (subQueries.length === 0) {
+        throw new Error("--merge requires at least one non-empty query (split with '|')");
+    }
+    return subQueries;
+}
 export async function search(query, options = {}, deps, context) {
     const { capability, cache, sleep, random, retryPolicy } = deps;
     // Split query on `|` if --merge is set. Empty fragments are dropped.
     // A literal pipe in a single query can be escaped as `\|` (won't split).
     let subQueries = [query];
     if (options.merge) {
-        subQueries = query
-            .split(/(?<!\\)\|/)
-            .map((q) => q.replace(/\\\|/g, "|").trim())
-            .filter((q) => q.length > 0);
-        if (subQueries.length === 0) {
-            throw new Error("--merge requires at least one non-empty query (split with '|')");
-        }
+        subQueries = splitMergeSubQueries(query);
     }
     const isMerge = subQueries.length > 1;
     const controls = buildControls(options);
@@ -159,8 +204,12 @@ export async function search(query, options = {}, deps, context) {
         }, executionDeps);
     }));
     const perQueryFormatted = perQuerySources.map((sources) => formatSources(sources, options.maxSummary));
+    // The single-provider --merge path and the fan-out path (Ticket 3)
+    // share one merge implementation. The single path passes no provider
+    // and no count, so its output is byte-identical to the pre-fan-out
+    // merge (no mergedFrom field, no post-merge slice).
     const formattedResults = isMerge
-        ? mergeResults(perQueryFormatted)
+        ? mergeResults([{ results: perQueryFormatted }])
         : perQueryFormatted[0] || [];
     if (isMerge && context) {
         context.notice(`ℹ️  merged ${subQueries.length} queries → ${formattedResults.length} unique results`);
@@ -171,6 +220,267 @@ export async function search(query, options = {}, deps, context) {
         : formattedResults;
     return { kind: "data", data, presentations };
 }
+/**
+ * Configured ∩ advertising descriptors for `search`, in the registry
+ * order the descriptors were injected (production passes the stable
+ * `PROVIDER_IDS` order). Shared by the `"all"` expansion and the
+ * tier-3 default fan-out arms.
+ */
+function eligibleSearchArms(descriptors, env) {
+    const arms = [];
+    for (const descriptor of descriptors) {
+        if (!descriptor.isConfigured(env, "search"))
+            continue;
+        if (!descriptor.capabilities().has("search"))
+            continue;
+        arms.push(descriptor.id);
+    }
+    return arms;
+}
+/**
+ * Resolve the activation plan (D1). Tiers in precedence order:
+ *
+ *   1. **Explicit raw** (D1.1): a comma list or `"all"` → fanout
+ *      (`"all"` expands to configured ∩ advertising in registry
+ *      order); a single id → single (with suppress when
+ *      `configFanout=true`).
+ *   2. **SCOUTLINE_PROVIDER env** (D1.2): a pin → single (suppress
+ *      when `configFanout=true`).
+ *   3. **`configFanout=true` with no pin** (D1.3): fanout; arms =
+ *      `routing.search` filtered/deduped (if set), else configured ∩
+ *      advertising in registry order.
+ *   4. **Default** (D1.4): single; arm = first configured ∩
+ *      advertising in registry order (informational — the dispatcher
+ *      still consults `resolveEffectiveProvider` for quota ranking).
+ *
+ * The resolver exposes its decision only through the returned
+ * `FanoutPlan`; the dispatcher hinges on `mode`. The truth table is
+ * pinned by Ticket 3 tests.
+ */
+export function resolveFanoutPlan(options) {
+    const { explicitProviderRaw, env, configFanout, routing, descriptors } = options;
+    // Tier 1: explicit raw. parseProviderIds does the heavy lifting:
+    // comma-list → IDs, "all" → sentinel, single id → one-element
+    // array, garbage → null. We then translate each result into the
+    // dispatcher-facing mode. Unknown ids are left to the existing
+    // `resolveProviderId` path to surface VALIDATION_ERROR.
+    if (explicitProviderRaw !== undefined && explicitProviderRaw.trim().length > 0) {
+        const parsed = parseProviderIds(explicitProviderRaw);
+        if (parsed === "all") {
+            // `"all"` expands NOW so the executor never sees the sentinel.
+            return { mode: "fanout", arms: eligibleSearchArms(descriptors, env) };
+        }
+        if (Array.isArray(parsed)) {
+            if (parsed.length > 1) {
+                return { mode: "fanout", arms: parsed };
+            }
+            // Single id → single mode. Suppress notice when fanout=true so the
+            // user knows the explicit pin precedence overrode the switch.
+            const arm = parsed[0];
+            if (configFanout) {
+                return { mode: "single", arms: [arm], suppress: `explicit pin: fan-out ignored` };
+            }
+            return { mode: "single", arms: [arm] };
+        }
+        // parsed === null: a non-empty explicit value that names no valid
+        // id, comma list, or the "all" sentinel. Surface the typed
+        // VALIDATION_ERROR HERE (parseProviderId owns the CLI's
+        // provider-error wording and throws for every input this parse
+        // rejects) — falling through would let tier 3 (fanout=true)
+        // silently convert the typo'd pin into a fan-out activation and
+        // the error would never surface (review fix, PR #36).
+        parseProviderId(explicitProviderRaw);
+        // Unreachable: parseProviderId throws for every null-parse input.
+        // The return keeps the branch total should the parsers diverge.
+        return { mode: "single", arms: [] };
+    }
+    // Tier 2: SCOUTLINE_PROVIDER env pin → single.
+    const envProvider = env.SCOUTLINE_PROVIDER;
+    if (envProvider !== undefined && envProvider.trim().length > 0) {
+        const arm = envProvider.trim().toLowerCase();
+        if (configFanout) {
+            return { mode: "single", arms: [arm], suppress: `SCOUTLINE_PROVIDER pin: fan-out ignored` };
+        }
+        return { mode: "single", arms: [arm] };
+    }
+    // Tier 3: fanout=true with no pin → fanout; arms = routing.search
+    // (filtered/deduped) when set, else configured ∩ advertising in
+    // registry order.
+    if (configFanout) {
+        const routed = routing?.["search"];
+        if (routed !== undefined && routed.length > 0) {
+            // Filter against configured∩advertising while preserving the
+            // routed order; dedupe by first encounter (the routing list is
+            // a user-supplied preference, so first-write wins on the user's
+            // intent).
+            const eligible = new Set(eligibleSearchArms(descriptors, env));
+            const arms = [];
+            const seen = new Set();
+            for (const id of routed) {
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                if (!eligible.has(id))
+                    continue;
+                arms.push(id);
+            }
+            return { mode: "fanout", arms };
+        }
+        return { mode: "fanout", arms: eligibleSearchArms(descriptors, env) };
+    }
+    // Tier 4: default single path. The dispatcher still consults
+    // `resolveEffectiveProvider` for quota-ranked first-pick; the arm
+    // reported here is the informational first-eligible in registry
+    // order.
+    const firstEligible = eligibleSearchArms(descriptors, env);
+    return { mode: "single", arms: firstEligible.slice(0, 1) };
+}
+/**
+ * Run a single arm: create the adapter, run one executeSearch PER
+ * SUB-QUERY, and format the normalized sources into one
+ * FormattedResult[] per sub-query. The arm owns its transport per
+ * call (the one-client-per-query pattern unconditionally — each
+ * executeSearch isolates its client exactly like the single-provider
+ * `--merge` sub-queries in `search`).
+ */
+async function runFanoutArm(armId, subQueries, options) {
+    const descriptor = options.descriptors.find((d) => d.id === armId);
+    if (!descriptor) {
+        // Should never happen — the resolver already filtered — but a
+        // surface error here is safer than a bare undefined deref.
+        throw new ValidationError(`Unknown provider "${armId}" in fan-out plan.`, "Re-run with a configured provider.");
+    }
+    const adapter = descriptor.create({ env: options.env });
+    const capability = adapter.search;
+    if (!capability) {
+        throw new UnsupportedCapabilityError(armId, "search");
+    }
+    const controls = buildControls(options.searchOptions);
+    // One executeSearch per (arm × sub-query): sub-queries run in
+    // parallel inside the arm (same scheduling as the single-provider
+    // `--merge` path) and each call owns its transport. The consumption
+    // sink + clock are threaded so every billable call records.
+    const perSubQuerySources = await Promise.all(subQueries.map((q) => {
+        const request = controls ? { query: q, controls } : { query: q };
+        return executeSearch(capability, request, {
+            count: options.searchOptions.count,
+            noCache: options.searchOptions.noCache,
+            retryPolicy: options.dependencies.retryPolicy,
+        }, {
+            cache: options.dependencies.cache,
+            sleep: options.dependencies.sleep,
+            random: options.dependencies.random,
+            ...(options.dependencies.consume !== undefined
+                ? { consume: options.dependencies.consume }
+                : {}),
+            ...(options.dependencies.now !== undefined ? { now: options.dependencies.now } : {}),
+        });
+    }));
+    return perSubQuerySources.map((sources) => formatSources(sources, options.searchOptions.maxSummary));
+}
+/**
+ * Build a single arm's notice line (D5). Every failed arm is a "drop"
+ * in the D6 sense ("drops as notices + data"): an
+ * `UnsupportedOptionError` names the rejected control; any other
+ * error names its code and a redacted message. The message is
+ * redacted via `redactCredentialString` so a transport error that
+ * echoes a credential never reaches stderr verbatim.
+ */
+function armNotice(armId, error, secrets) {
+    if (error instanceof UnsupportedOptionError) {
+        return `arm ${armId} dropped: UNSUPPORTED_OPTION (${error.option})`;
+    }
+    const code = error?.code ?? "UNKNOWN_ERROR";
+    const rawMessage = error?.message ?? String(error);
+    const safeMessage = redactCredentialString(rawMessage, [...secrets]);
+    return `arm ${armId} dropped: ${code}: ${safeMessage}`;
+}
+/**
+ * Execute the fan-out plan: parallel per-arm search, settled wrapper,
+ * per-arm notices, D5/D6 exit policy, combined summary notice. The
+ * single-pin path is NOT routed through this executor (Tier 2 / Tier 4
+ * stay verbatim through `executeWithFallback`); the executor asserts
+ * `mode === "fanout"` on entry so a misuse throws loudly.
+ */
+export async function executeFanoutPlan(plan, options, context) {
+    if (plan.mode !== "fanout") {
+        throw new ValidationError("executeFanoutPlan only accepts mode='fanout'.", "Use the single-pin path for single mode.");
+    }
+    const arms = plan.arms;
+    if (arms.length === 0) {
+        // D6: zero arms resolved → VALIDATION_ERROR naming the configured
+        // set and the registry so the operator sees both halves of the
+        // mismatch (what could serve vs. what exists).
+        const configuredSet = options.descriptors
+            .filter((d) => d.isConfigured(options.env, "search") && d.capabilities().has("search"))
+            .map((d) => d.id)
+            .join(", ") || "(none)";
+        const registrySet = options.descriptors.map((d) => d.id).join(", ") || "(none)";
+        throw new ValidationError(`Fan-out produced no arms; configured search providers: ${configuredSet} (registry: ${registrySet}).`, "Configure at least one provider's API key, or unset 'fanout' / routing.search.");
+    }
+    // Sub-query split (DESIGN D3: the merge grid is arms × sub-queries).
+    // `--merge` composes with fan-out — every arm runs every sub-query
+    // (review fix, PR #36); without it the raw query is one sub-query.
+    const subQueries = options.searchOptions.merge
+        ? splitMergeSubQueries(options.query)
+        : [options.query];
+    // Run every arm in parallel. Promise.allSettled ensures one arm's
+    // failure does not abort the rest; the per-arm pipeline is isolated
+    // (one client per arm, no fallback chain).
+    const settled = await Promise.allSettled(arms.map((armId) => runFanoutArm(armId, subQueries, options).then((results) => ({ arm: armId, results }))));
+    const successes = [];
+    const failures = [];
+    for (let i = 0; i < settled.length; i++) {
+        const entry = settled[i];
+        const armId = arms[i];
+        if (entry !== undefined && entry.status === "fulfilled") {
+            successes.push(entry.value);
+        }
+        else if (entry !== undefined) {
+            failures.push({ arm: armId, error: entry.reason });
+        }
+    }
+    // Per-arm notices (D5). Every non-success arm surfaces here as a
+    // drop; UnsupportedOptionError carries the rejected control name.
+    if (context) {
+        for (const { arm, error } of failures) {
+            context.notice(armNotice(arm, error, options.secrets ?? []));
+        }
+    }
+    // D6: all-fail → throw the last arm's typed error through the boundary.
+    if (successes.length === 0) {
+        const last = failures[failures.length - 1];
+        if (last)
+            throw last.error;
+        throw new Error("Fan-out produced no successes and no failures; plan was empty after filtering.");
+    }
+    // Build the (arm × sub-query) grid for mergeResults. Each success
+    // carries one FormattedResult[] per sub-query; occurrence counting
+    // and mergedFrom accumulation span the whole grid (D3).
+    const grid = successes.map((s) => ({
+        provider: s.arm,
+        results: s.results,
+    }));
+    const merged = mergeResults(grid, {
+        emitMergedFrom: true,
+        count: options.searchOptions.count,
+    });
+    // Summary notice (D5). K = total raw results across the whole
+    // arms × sub-queries grid (the post-truncate counts the executor
+    // collected); M = merged unique count. An arm with 0 results
+    // contributes 0 to K — the notice still names the arm so the
+    // operator sees the full set.
+    const totalRaw = successes.reduce((sum, s) => sum + s.results.reduce((n, list) => n + list.length, 0), 0);
+    if (context) {
+        const armList = arms.join(", ");
+        context.notice(`fanned out to ${arms.length} providers (${armList}) → ${merged.length} unique of ${totalRaw} results`);
+    }
+    const presentations = buildPresentations(merged);
+    const data = options.searchOptions.fields && options.searchOptions.fields.length > 0
+        ? merged.map((r) => filterFields(r, options.searchOptions.fields))
+        : merged;
+    return { kind: "data", data, presentations };
+}
 // Help text
 export const SEARCH_HELP = `
 Search Command - Real-time web search (Z.AI, MiniMax, Tavily, Exa, or Brave)
@@ -181,6 +491,36 @@ Provider selection (precedence: explicit flag, then SCOUTLINE_PROVIDER, then zai
   --provider <zai|minimax|tavily|exa|brave|firecrawl|parallel|perplexity|jina>   Select the search provider (default: zai)
   SCOUTLINE_PROVIDER=<id>                 Fallback when --provider is not passed
 
+Multi-provider fan-out — activation tiers (highest precedence first):
+  1. --provider <tavily,exa,...> or --provider all
+        Fan-out on the listed providers; \`all\` expands to every
+        configured provider that advertises search, registry order.
+  2. A single --provider id, or SCOUTLINE_PROVIDER set
+        Single provider only — an explicit pin; fan-out is ignored.
+  3. \`scoutline config set fanout true\` (with no pin)
+        Fan-out on routing.search when set, else every configured
+        search provider, registry order.
+  4. No pin and fanout off (the default)
+        Single provider via the standard selection order.
+
+  Cost (when fan-out is active):
+  every search will bill ALL configured search providers — N arms = N billable calls.
+  Disable with \`scoutline config set fanout false\`.
+
+  Merging: arms run in parallel (one client each, pinned — no per-arm
+  fallback) and are deduped by canonical URL identity: scheme and host
+  lowercased; :80/:443 ports, fragments, and trailing slashes stripped;
+  utm_* and fbclid parameters removed (names are matched after
+  percent-decoding, so ?%66bclid=x collapses with ?fbclid=x; the raw
+  path — including dot segments — and userinfo are preserved verbatim).
+  The canonical form is a dedupe identity ONLY — the emitted url,
+  title, and summary are the first arm's originals. The first arm wins
+  metadata collisions; \`occurrences\` counts across all arms; the
+  merged list is sliced to --count after merging; \`--merge\` composes
+  with fan-out: every arm runs every sub-query and occurrences span
+  the arms × sub-queries grid. A failed arm is dropped with a stderr
+  notice; if every arm fails, the last arm's error surfaces.
+
 Note: support for the optional controls below varies by provider AND by
 control — a control accepted by one provider may be rejected
 (UNSUPPORTED_OPTION) by another before invocation. Run
@@ -237,6 +577,7 @@ Default JSON shape:
       "source": "example.com",
       "date": "2024-01-15",
       "occurrences": 2   // only present with --merge when >1
+      "mergedFrom": ["tavily", "exa"]   // fan-out only: arms that surfaced this result
     }
   ]
 `.trim();