scoutline 0.10.2 → 0.11.0

package/dist/index.js

@@ -17,12 +17,13 @@ import { isExtractMode } from "./lib/extract.js";
 import { runCodeFile, evalCode, printInterfaces, printPromptTemplate, CODE_HELP, } from "./commands/code.js";
 import { isOutputMode, OUTPUT_MODES } from "./lib/output.js";
 import { formatErrorOutput } from "./lib/output.js";
-import { ConfigurationError, ValidationError, UnsupportedCapabilityError, getErrorExitCode, } from "./lib/errors.js";
+import { ValidationError, UnsupportedCapabilityError, getErrorExitCode, } from "./lib/errors.js";
 import { invokeCommand } from "./command-invocation.js";
 import { defaultResponseCache } from "./lib/cache.js";
 import { configuredSecrets } from "./lib/redact.js";
 import { resolveProviderId } from "./providers/selection.js";
-import { BUILT_IN_PROVIDER_DESCRIPTORS, getProviderDescriptor } from "./providers/registry.js";
+import { BUILT_IN_PROVIDER_DESCRIPTORS } from "./providers/registry.js";
+import { executeWithFallback } from "./lib/provider-fallback.js";
 import { visionOperationToCapability } from "./capabilities/vision.js";
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
@@ -64,11 +65,14 @@ and 'research' commands participate in Provider selection: Z.AI
 advertises and supplies repository-exploration and reader; Tavily
 advertises and supplies reader plus crawl, map, and research; Exa
 advertises and supplies search, reader, and research; MiniMax
-advertises and supplies none of those Provider-only Capabilities. A
-non-supplier returns UNSUPPORTED_CAPABILITY with no fallback. Z.AI-only
-commands (tools, tool, call, code) carry the flag but ignore it.
-Quota and doctor report per-Provider; --provider picks the effective
-Provider for metadata.
+advertises and supplies none of those Provider-only Capabilities.
+Provider fallback is always-on by default (0.11.0+): selecting a
+non-supplier emits a stderr notice and silently reroutes to the next
+eligible configured Provider in registry order. Use --no-fallback (or
+SCOUTLINE_NO_FALLBACK=1) to restore the previous strict
+UNSUPPORTED_CAPABILITY behavior. Z.AI-only commands (tools, tool,
+call, code) carry the flag but ignore it. Quota and doctor report
+per-Provider; --provider picks the effective Provider for metadata.
 
 Global Options:
   --output-format <data|json|pretty|compact|markdown|refs|tty>  Output mode (default: data)
@@ -137,6 +141,7 @@ function extractGlobalOptions(args) {
     let forcePretty = false;
     let forceRaw = false;
     let provider;
+    let noFallback = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--output-format" || arg === "-O") {
@@ -161,9 +166,19 @@ function extractGlobalOptions(args) {
             i += 1;
             continue;
         }
+        if (arg === "--no-fallback") {
+            // Provider-fallback kill-switch. Accepted before OR after the
+            // command token and removed from the rest stream so command-local
+            // parsing never observes it. Resolution against
+            // `SCOUTLINE_NO_FALLBACK` lives in `main` so a test that drives
+            // `extractGlobalOptions` directly can assert the flag shape in
+            // isolation.
+            noFallback = true;
+            continue;
+        }
         rest.push(arg);
     }
-    return { outputFormat, forcePretty, forceRaw, provider, rest };
+    return { outputFormat, forcePretty, forceRaw, provider, noFallback, rest };
 }
 function resolveOutputMode(explicit, forcePretty, forceRaw, adapter) {
     if (explicit !== undefined) {
@@ -200,63 +215,83 @@ async function handleVision(args, outputMode, deps) {
     // Resolve the effective Provider for Vision (DESIGN.md §6). Invalid
     // explicit/env input fails here with VALIDATION_ERROR before any Vision
     // support check or media access. Selection never consults credentials
-    // (FR-003); the configured check below is the caller's responsibility.
+    // (FR-003); the configured check below is the executor's responsibility
+    // (Provider Fallback Tech Plan §"Per-handler refactor pattern").
     const providerId = resolveProviderId(deps.provider, deps.env);
-    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
-    // Gate the operation on descriptor metadata BEFORE Adapter construction.
-    // An unsupported operation (e.g. MiniMax for any specialized op, diff, or
-    // video) fails with UNSUPPORTED_CAPABILITY before credentials, media,
-    // transport, cache, or any Z.AI fallback (FR-023, FR-024). No command
-    // branches on a Provider ID: the support check alone decides availability.
+    // Per-operation capability id (e.g. `vision.interpret-image`,
+    // `vision.chart`). The executor's preflight uses this to filter
+    // descriptors, and notice wording carries it verbatim. Vision
+    // sub-operations share the same `adapter.vision` slot — the
+    // per-operation capability is in the descriptor metadata.
     const capabilityId = visionOperationToCapability(operation);
-    if (!descriptor.capabilities().has(capabilityId)) {
-        throw new UnsupportedCapabilityError(providerId, capabilityId);
-    }
-    // FR-003: selection returns the default zai even when unconfigured. The
-    // dispatch layer surfaces a missing credential as ConfigurationError
-    // (exit 3), AFTER the capability support check (FR-023) but before any
-    // Adapter construction or media access (Fixup A — B5).
-    if (!descriptor.isConfigured(deps.env)) {
-        throw new ConfigurationError(`Provider "${providerId}" is not configured. Set the required API key.`);
-    }
-    const adapter = descriptor.create({ env: deps.env });
-    const visionCapability = adapter.vision;
-    if (!visionCapability || !visionCapability.supports(operation)) {
-        throw new UnsupportedCapabilityError(providerId, capabilityId);
-    }
     // Vision bypasses the response cache (FR-022). The shared execution
     // primitives (sleep/random) are the same ones Search consumes; they
     // drive retry backoff deterministically under test.
-    const visionDeps = {
-        capability: visionCapability,
+    const visionDepsShape = {
         sleep: deps.searchSleep,
         random: deps.searchRandom,
     };
-    switch (command) {
-        case "analyze":
-            return invokeCommand(deps.invocation, (context) => vision.analyze(source, prompt, visionDeps, context), outputMode, deps.now, deps.secrets);
-        case "ui-to-code": {
-            const outputType = flags.output || "code";
-            return invokeCommand(deps.invocation, (context) => vision.uiToCode(source, prompt, outputType, visionDeps, context), outputMode, deps.now, deps.secrets);
-        }
-        case "extract-text":
-            return invokeCommand(deps.invocation, (context) => vision.extractText(source, prompt, flags.language, visionDeps, context), outputMode, deps.now, deps.secrets);
-        case "diagnose-error":
-            return invokeCommand(deps.invocation, (context) => vision.diagnoseError(source, prompt, flags.context, visionDeps, context), outputMode, deps.now, deps.secrets);
-        case "diagram":
-            return invokeCommand(deps.invocation, (context) => vision.diagram(source, prompt, flags.type, visionDeps, context), outputMode, deps.now, deps.secrets);
-        case "chart":
-            return invokeCommand(deps.invocation, (context) => vision.chart(source, prompt, flags.focus, visionDeps, context), outputMode, deps.now, deps.secrets);
-        case "diff": {
-            const actual = positional[2];
-            const diffPrompt = positional[3];
-            return invokeCommand(deps.invocation, (context) => vision.diff(source, actual, diffPrompt, visionDeps, context), outputMode, deps.now, deps.secrets);
-        }
-        case "video":
-            return invokeCommand(deps.invocation, (context) => vision.video(source, prompt, visionDeps, context), outputMode, deps.now, deps.secrets);
-        default:
-            throw new ValidationError(`Unknown vision command: ${command}`, 'Run "scoutline vision --help" for available commands');
-    }
+    // Provider-fallback Ticket 02: route every vision operation through
+    // the shared executor. The existing vision URL→temp-file fallback
+    // stays inside the Z.AI adapter's invoke, layered beneath provider
+    // fallback.
+    return invokeCommand(deps.invocation, async (context) => {
+        const outcome = await executeWithFallback({
+            capabilityId,
+            commandLabel: "vision",
+            effectiveProvider: providerId,
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            fallbackEnabled: deps.fallbackEnabled,
+            writeStderr: (s) => deps.invocation.writeStderr(s),
+        }, async (descriptor) => {
+            const adapter = descriptor.create({ env: deps.env });
+            // The executor's preflight guarantees the descriptor advertises
+            // the capability and supplies a non-null adapter slot, so the
+            // cast is safe. Operation-level support is checked immediately
+            // against `visionCapability.supports(operation)` — descriptor
+            // metadata and adapter capability are independent sources of
+            // truth, and the live dispatch must fail closed on disagreement
+            // (Review Fix 4). A mismatch throws `UnsupportedCapabilityError`
+            // before any media work / transport use, and the Executor treats
+            // it as a `continue` so the next candidate (if any) gets a
+            // chance.
+            const visionCapability = adapter.vision;
+            if (!visionCapability || !visionCapability.supports(operation)) {
+                throw new UnsupportedCapabilityError(descriptor.id, capabilityId);
+            }
+            const visionDeps = {
+                capability: visionCapability,
+                ...visionDepsShape,
+            };
+            switch (command) {
+                case "analyze":
+                    return vision.analyze(source, prompt, visionDeps, context);
+                case "ui-to-code": {
+                    const outputType = flags.output || "code";
+                    return vision.uiToCode(source, prompt, outputType, visionDeps, context);
+                }
+                case "extract-text":
+                    return vision.extractText(source, prompt, flags.language, visionDeps, context);
+                case "diagnose-error":
+                    return vision.diagnoseError(source, prompt, flags.context, visionDeps, context);
+                case "diagram":
+                    return vision.diagram(source, prompt, flags.type, visionDeps, context);
+                case "chart":
+                    return vision.chart(source, prompt, flags.focus, visionDeps, context);
+                case "diff": {
+                    const actual = positional[2];
+                    const diffPrompt = positional[3];
+                    return vision.diff(source, actual, diffPrompt, visionDeps, context);
+                }
+                case "video":
+                    return vision.video(source, prompt, visionDeps, context);
+                default:
+                    throw new ValidationError(`Unknown vision command: ${command}`, 'Run "scoutline vision --help" for available commands');
+            }
+        });
+        return outcome.result;
+    }, outputMode, deps.now, deps.secrets);
 }
 /**
  * Map a Vision subcommand to its discriminated operation id. Used by
@@ -380,29 +415,14 @@ async function handleSearch(args, outputMode, deps) {
     if (type !== undefined && topic !== undefined) {
         throw new ValidationError("--type and --topic are mutually exclusive (--type has no editorial topic axis).", "Pass either --type or --topic, not both.");
     }
-    // Resolve the Provider ONLY inside shared Search (DESIGN.md §6). Other
-    // command families carry the parsed flag but never resolve or validate
-    // it. An invalid explicit/env value throws VALIDATION_ERROR here, before
-    // any Adapter construction or invocation. Selection never consults
-    // credentials (FR-003); the configured check below is the caller's
-    // responsibility (Fixup A — B5).
+    // Resolve the effective Provider ONLY inside shared Search (DESIGN.md §6).
+    // Other command families carry the parsed flag but never resolve or
+    // validate it. An invalid explicit/env value throws VALIDATION_ERROR
+    // here, before any Adapter construction or invocation. Selection never
+    // consults credentials (FR-003); the configured check is the
+    // executor's responsibility (Provider Fallback Tech Plan §"Per-handler
+    // refactor pattern").
     const providerId = resolveProviderId(deps.provider, deps.env);
-    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
-    if (!descriptor.capabilities().has("search")) {
-        throw new UnsupportedCapabilityError(providerId, "search");
-    }
-    // FR-003: selection returns the default zai even when unconfigured. The
-    // dispatch layer surfaces a missing credential as ConfigurationError
-    // (exit 3), AFTER the capability support check (FR-023) but before any
-    // Adapter construction (Fixup A — B5).
-    if (!descriptor.isConfigured(deps.env)) {
-        throw new ConfigurationError(`Provider "${providerId}" is not configured. Set the required API key.`);
-    }
-    const adapter = descriptor.create({ env: deps.env });
-    const capability = adapter.search;
-    if (!capability) {
-        throw new UnsupportedCapabilityError(providerId, "search");
-    }
     const query = positional.join(" ");
     const fieldsRaw = flags.fields;
     const fields = fieldsRaw
@@ -411,7 +431,7 @@ async function handleSearch(args, outputMode, deps) {
             .map((f) => f.trim())
             .filter(Boolean)
         : undefined;
-    return invokeCommand(deps.invocation, (context) => search(query, {
+    const searchOptions = {
         count,
         domain: flags.domain,
         recency: flags.recency,
@@ -425,12 +445,36 @@ async function handleSearch(args, outputMode, deps) {
         fields: fields && fields.length > 0 ? fields : undefined,
         noCache: flags["no-cache"] === true,
         merge: flags.merge === true,
-    }, {
-        capability,
-        cache: deps.searchCache,
-        sleep: deps.searchSleep,
-        random: deps.searchRandom,
-    }, context), outputMode, deps.now, deps.secrets);
+    };
+    // Provider-fallback Ticket 02: route the call through the shared
+    // fallback executor. The executor owns capability+configured+adapter
+    // preflight (FR-023/024), candidate plan ordering, error
+    // classification, exhaustion semantics, and notices. The handler
+    // keeps command-specific work (request building, flag parsing, which
+    // executeX). `--merge` runs the whole parallel sub-query batch inside
+    // a single attempt so a fallback switch replaces the entire batch,
+    // never individual sub-queries (Tech Plan §"Handler non-uniformity").
+    return invokeCommand(deps.invocation, async (context) => {
+        const outcome = await executeWithFallback({
+            capabilityId: "search",
+            commandLabel: "search",
+            effectiveProvider: providerId,
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            fallbackEnabled: deps.fallbackEnabled,
+            writeStderr: (s) => deps.invocation.writeStderr(s),
+        }, async (descriptor) => {
+            const adapter = descriptor.create({ env: deps.env });
+            const capability = adapter.search;
+            return search(query, searchOptions, {
+                capability,
+                cache: deps.searchCache,
+                sleep: deps.searchSleep,
+                random: deps.searchRandom,
+            }, context);
+        });
+        return outcome.result;
+    }, outputMode, deps.now, deps.secrets);
 }
 async function handleRead(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
@@ -460,40 +504,7 @@ async function handleRead(args, outputMode, deps) {
     // never consults credentials (FR-003) and never branches on Provider
     // ID; an unknown explicit/env value throws VALIDATION_ERROR here.
     const providerId = resolveProviderId(deps.provider, deps.env);
-    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
-    // Capability support check BEFORE `descriptor.isConfigured`,
-    // `descriptor.create`, Adapter access, operation validation/
-    // cacheIdentity, credential use, cache, or transport. Unsupported
-    // MiniMax (explicit or environment) returns UNSUPPORTED_CAPABILITY
-    // with no fallback to Z.AI; zero selected-Provider work occurs.
-    if (!descriptor.capabilities().has("reader")) {
-        throw new UnsupportedCapabilityError(providerId, "reader");
-    }
-    // FR-003: selection returns the default zai even when unconfigured.
-    // Supported-but-unconfigured Z.AI surfaces a missing credential as
-    // ConfigurationError (exit 3) AFTER the support metadata check and
-    // BEFORE `descriptor.create`.
-    if (!descriptor.isConfigured(deps.env)) {
-        throw new ConfigurationError(`Provider "${providerId}" is not configured. Set the required API key.`);
-    }
-    const adapter = descriptor.create({ env: deps.env });
-    const capability = adapter.reader;
-    // Defensive fail-closed: the descriptor advertised support but the
-    // Adapter omitted the handle. Treat as unsupported so a registry
-    // mismatch can never reach transport.
-    if (!capability) {
-        throw new UnsupportedCapabilityError(providerId, "reader");
-    }
-    // Shared Reader execution dependencies. The cache/sleep/random
-    // default to the same production values as Search and Repository
-    // but are kept as separate optional MainDependencies so reader
-    // tests can inject isolated in-memory doubles.
-    const executionDeps = {
-        cache: deps.readerCache,
-        sleep: deps.readerSleep,
-        random: deps.readerRandom,
-    };
-    return invokeCommand(deps.invocation, (context) => read(url, {
+    const readOptions = {
         format: flags.format,
         noImages: flags["no-images"] === true,
         noCache: flags["no-cache"] === true,
@@ -505,7 +516,39 @@ async function handleRead(args, outputMode, deps) {
         maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
         fullEnvelope: flags["full-envelope"] === true,
         extract,
-    }, { capability, execution: executionDeps }, context), outputMode, deps.now, deps.secrets);
+    };
+    // Shared Reader execution dependencies. The cache/sleep/random
+    // default to the same production values as Search and Repository
+    // but are kept as separate optional MainDependencies so reader
+    // tests can inject isolated in-memory doubles.
+    const executionDeps = {
+        cache: deps.readerCache,
+        sleep: deps.readerSleep,
+        random: deps.readerRandom,
+    };
+    // Provider-fallback Ticket 02: route the call through the shared
+    // fallback executor. Capability + configured + adapter-handle
+    // agreement preflight now lives in the executor (FR-023/024
+    // preserved). Under --no-fallback the same preflight runs on the
+    // effective Provider only.
+    return invokeCommand(deps.invocation, async (context) => {
+        const outcome = await executeWithFallback({
+            capabilityId: "reader",
+            commandLabel: "read",
+            effectiveProvider: providerId,
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            fallbackEnabled: deps.fallbackEnabled,
+            writeStderr: (s) => deps.invocation.writeStderr(s),
+        }, async (descriptor) => {
+            const adapter = descriptor.create({ env: deps.env });
+            return read(url, readOptions, {
+                capability: adapter.reader,
+                execution: executionDeps,
+            }, context);
+        });
+        return outcome.result;
+    }, outputMode, deps.now, deps.secrets);
 }
 async function handleCrawl(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
@@ -524,21 +567,6 @@ async function handleCrawl(args, outputMode, deps) {
     // Resolve the effective Provider (DESIGN.md §6, FR-001–FR-005):
     // explicit --provider > SCOUTLINE_PROVIDER > default zai.
     const providerId = resolveProviderId(deps.provider, deps.env);
-    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
-    // Capability support check BEFORE descriptor.isConfigured, descriptor.create,
-    // or any Adapter work. Unsupported Z.AI/MiniMax returns
-    // UNSUPPORTED_CAPABILITY with no fallback to Tavily.
-    if (!descriptor.capabilities().has("crawl")) {
-        throw new UnsupportedCapabilityError(providerId, "crawl");
-    }
-    if (!descriptor.isConfigured(deps.env)) {
-        throw new ConfigurationError(`Provider "${providerId}" is not configured. Set the required API key.`);
-    }
-    const adapter = descriptor.create({ env: deps.env });
-    const capability = adapter.crawl;
-    if (!capability) {
-        throw new UnsupportedCapabilityError(providerId, "crawl");
-    }
     // Shared Crawl execution dependencies. The cache/sleep/random default
     // to the same production values as Search/Repository/Reader but are
     // kept as separate optional MainDependencies so crawl tests can inject
@@ -548,19 +576,40 @@ async function handleCrawl(args, outputMode, deps) {
         sleep: deps.crawlSleep,
         random: deps.crawlRandom,
     };
-    return invokeCommand(deps.invocation, (context) => crawl(url, {
-        depth: flags.depth ? parseInt(flags.depth, 10) : undefined,
-        breadth: flags.breadth ? parseInt(flags.breadth, 10) : undefined,
-        limit: flags.limit ? parseInt(flags.limit, 10) : undefined,
-        selectPaths: flags["select-paths"],
-        excludePaths: flags["exclude-paths"],
-        instructions: flags.instructions,
-        format: flags.format,
-        contentSize: flags["content-size"],
-        timeout: flags.timeout ? parseInt(flags.timeout, 10) : undefined,
-        noCache: flags["no-cache"] === true,
-        maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
-    }, { capability, execution: executionDeps }, context), outputMode, deps.now, deps.secrets);
+    // Provider-fallback Ticket 03: route the call through the shared
+    // fallback executor. Capability + configured + adapter-handle
+    // preflight lives in the executor (FR-023/024 preserved). The
+    // async cost-bearing accepted-risk path (Tech Plan §"Accepted
+    // risk"): a runtime failure on crawl may fall back to another
+    // Provider even if the failed Provider had already accepted
+    // the job. `--no-fallback` eliminates this risk.
+    return invokeCommand(deps.invocation, async (context) => {
+        const outcome = await executeWithFallback({
+            capabilityId: "crawl",
+            commandLabel: "crawl",
+            effectiveProvider: providerId,
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            fallbackEnabled: deps.fallbackEnabled,
+            writeStderr: (s) => deps.invocation.writeStderr(s),
+        }, async (descriptor) => {
+            const adapter = descriptor.create({ env: deps.env });
+            return crawl(url, {
+                depth: flags.depth ? parseInt(flags.depth, 10) : undefined,
+                breadth: flags.breadth ? parseInt(flags.breadth, 10) : undefined,
+                limit: flags.limit ? parseInt(flags.limit, 10) : undefined,
+                selectPaths: flags["select-paths"],
+                excludePaths: flags["exclude-paths"],
+                instructions: flags.instructions,
+                format: flags.format,
+                contentSize: flags["content-size"],
+                timeout: flags.timeout ? parseInt(flags.timeout, 10) : undefined,
+                noCache: flags["no-cache"] === true,
+                maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
+            }, { capability: adapter.crawl, execution: executionDeps }, context);
+        });
+        return outcome.result;
+    }, outputMode, deps.now, deps.secrets);
 }
 async function handleMap(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
@@ -579,21 +628,6 @@ async function handleMap(args, outputMode, deps) {
     // Resolve the effective Provider (DESIGN.md §6, FR-001–FR-005):
     // explicit --provider > SCOUTLINE_PROVIDER > default zai.
     const providerId = resolveProviderId(deps.provider, deps.env);
-    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
-    // Capability support check BEFORE descriptor.isConfigured, descriptor.create,
-    // or any Adapter work. Unsupported Z.AI/MiniMax returns
-    // UNSUPPORTED_CAPABILITY with no fallback to Tavily.
-    if (!descriptor.capabilities().has("map")) {
-        throw new UnsupportedCapabilityError(providerId, "map");
-    }
-    if (!descriptor.isConfigured(deps.env)) {
-        throw new ConfigurationError(`Provider "${providerId}" is not configured. Set the required API key.`);
-    }
-    const adapter = descriptor.create({ env: deps.env });
-    const capability = adapter.map;
-    if (!capability) {
-        throw new UnsupportedCapabilityError(providerId, "map");
-    }
     // Shared Map execution dependencies. The cache/sleep/random default
     // to the same production values as Search/Repository/Reader/Crawl but
     // are kept as separate optional MainDependencies so map tests can
@@ -603,15 +637,34 @@ async function handleMap(args, outputMode, deps) {
         sleep: deps.mapSleep,
         random: deps.mapRandom,
     };
-    return invokeCommand(deps.invocation, (context) => map(url, {
-        depth: flags.depth ? parseInt(flags.depth, 10) : undefined,
-        breadth: flags.breadth ? parseInt(flags.breadth, 10) : undefined,
-        limit: flags.limit ? parseInt(flags.limit, 10) : undefined,
-        selectPaths: flags["select-paths"],
-        excludePaths: flags["exclude-paths"],
-        instructions: flags.instructions,
-        noCache: flags["no-cache"] === true,
-    }, { capability, execution: executionDeps }, context), outputMode, deps.now, deps.secrets);
+    // Provider-fallback Ticket 03: route the call through the shared
+    // fallback executor. Map retries once per Provider today, so the
+    // documented worst-case charged request count under retry+fallback
+    // is `2 × N candidates` — see the troubleshooting entry added in
+    // Ticket 04. `--no-fallback` is the strict-mode opt-out.
+    return invokeCommand(deps.invocation, async (context) => {
+        const outcome = await executeWithFallback({
+            capabilityId: "map",
+            commandLabel: "map",
+            effectiveProvider: providerId,
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            fallbackEnabled: deps.fallbackEnabled,
+            writeStderr: (s) => deps.invocation.writeStderr(s),
+        }, async (descriptor) => {
+            const adapter = descriptor.create({ env: deps.env });
+            return map(url, {
+                depth: flags.depth ? parseInt(flags.depth, 10) : undefined,
+                breadth: flags.breadth ? parseInt(flags.breadth, 10) : undefined,
+                limit: flags.limit ? parseInt(flags.limit, 10) : undefined,
+                selectPaths: flags["select-paths"],
+                excludePaths: flags["exclude-paths"],
+                instructions: flags.instructions,
+                noCache: flags["no-cache"] === true,
+            }, { capability: adapter.map, execution: executionDeps }, context);
+        });
+        return outcome.result;
+    }, outputMode, deps.now, deps.secrets);
 }
 async function handleResearch(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
@@ -629,40 +682,73 @@ async function handleResearch(args, outputMode, deps) {
     // Resolve the effective Provider (DESIGN.md §6, FR-001–FR-005):
     // explicit --provider > SCOUTLINE_PROVIDER > default zai.
     const providerId = resolveProviderId(deps.provider, deps.env);
-    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
-    // Capability support check BEFORE descriptor.isConfigured,
-    // descriptor.create, or any Adapter work. Unsupported Z.AI/MiniMax
-    // returns UNSUPPORTED_CAPABILITY with no fallback to Tavily.
-    if (!descriptor.capabilities().has("research")) {
-        throw new UnsupportedCapabilityError(providerId, "research");
-    }
-    if (!descriptor.isConfigured(deps.env)) {
-        throw new ConfigurationError(`Provider "${providerId}" is not configured. Set the required API key.`);
-    }
-    const adapter = descriptor.create({ env: deps.env });
-    const capability = adapter.research;
-    if (!capability) {
-        throw new UnsupportedCapabilityError(providerId, "research");
-    }
     // Shared Research execution dependencies.
     const executionDeps = {
         cache: deps.researchCache,
         sleep: deps.researchSleep,
         random: deps.researchRandom,
     };
-    // Wait disclaimer — shown BEFORE invoke because research is
-    // credit-intensive and may take several minutes. Written to stderr so
-    // it never corrupts data-mode stdout.
-    deps.invocation.writeStderr("Research in progress — this is a credit-intensive operation that may take several minutes.\n");
-    return invokeCommand(deps.invocation, (context) => research(query, {
-        model,
-        outputLength,
-        citationFormat,
-        domain: flags.domain,
-        maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
-        timeout: flags.timeout ? parseInt(flags.timeout, 10) : undefined,
-        noCache: flags["no-cache"] === true,
-    }, { capability, execution: executionDeps }, context), outputMode, deps.now, deps.secrets);
+    // Provider-fallback Ticket 03: route the call through the shared
+    // fallback executor. The research command is the riskiest piece
+    // of the async set: the SIGINT handler, the polling-timeout
+    // controller, and the on-disk state-file identity/timeout must
+    // RE-BIND to the Provider that actually wins the candidate loop
+    // (Tech Plan §"Handler non-uniformity" — research bullet). The
+    // `research` command accepts a `registerInterrupt` injection on
+    // its handler dependencies; the executor's per-attempt callback
+    // builds the descriptor's `capability.run` and re-registers the
+    // SIGINT handler under THAT provider's identity before invoke,
+    // tearing it down on throw so the next candidate installs its
+    // own. The one-time credit warning is emitted ONCE, before the
+    // first attempt, so it is not duplicated across candidate
+    // switches.
+    return invokeCommand(deps.invocation, async (context) => {
+        const options = {
+            model,
+            outputLength,
+            citationFormat,
+            domain: flags.domain,
+            maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
+            timeout: flags.timeout ? parseInt(flags.timeout, 10) : undefined,
+            noCache: flags["no-cache"] === true,
+        };
+        // Closure-guarded one-time credit warning (Review Fix 7). The
+        // flag is captured INSIDE the attempt closure, so the line is
+        // written exactly once — the first time the executor actually
+        // visits a candidate. When the executor's preflight rejects
+        // every plan entry before invoking `attempt` (capability-
+        // mismatch, no candidates configured), the closure is never
+        // entered and the warning stays silent. Strict mode
+        // (`--no-fallback`) already runs the same preflight on the
+        // single remaining candidate so an ineligible effective also
+        // stays silent.
+        let warned = false;
+        const creditWarning = `Research in progress — this is a credit-intensive operation that may take several minutes.\n`;
+        const emitCreditWarning = () => {
+            if (warned)
+                return;
+            warned = true;
+            deps.invocation.writeStderr(creditWarning);
+        };
+        const outcome = await executeWithFallback({
+            capabilityId: "research",
+            commandLabel: "research",
+            effectiveProvider: providerId,
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            fallbackEnabled: deps.fallbackEnabled,
+            writeStderr: (s) => deps.invocation.writeStderr(s),
+        }, async (descriptor) => {
+            emitCreditWarning();
+            const adapter = descriptor.create({ env: deps.env });
+            return research(query, options, {
+                capability: adapter.research,
+                execution: executionDeps,
+                registerInterrupt: deps.researchRegisterInterrupt,
+            }, context);
+        });
+        return outcome.result;
+    }, outputMode, deps.now, deps.secrets);
 }
 /**
  * Validate a research enum flag (--model, --output-length,
@@ -725,30 +811,6 @@ async function handleRepo(args, outputMode, deps) {
     // never consults credentials (FR-003) and never branches on Provider
     // ID; an unknown explicit/env value throws VALIDATION_ERROR here.
     const providerId = resolveProviderId(deps.provider, deps.env);
-    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
-    // Capability support check BEFORE `descriptor.isConfigured`,
-    // `descriptor.create`, Adapter access, operation validation/
-    // cacheIdentity, credential use, cache, or transport. Unsupported
-    // MiniMax (explicit or environment) returns UNSUPPORTED_CAPABILITY
-    // with no fallback to Z.AI; zero selected-Provider work occurs.
-    if (!descriptor.capabilities().has("repository-exploration")) {
-        throw new UnsupportedCapabilityError(providerId, "repository-exploration");
-    }
-    // FR-003: selection returns the default zai even when unconfigured.
-    // Supported-but-unconfigured Z.AI surfaces a missing credential as
-    // ConfigurationError (exit 3) AFTER the support metadata check and
-    // BEFORE `descriptor.create`.
-    if (!descriptor.isConfigured(deps.env)) {
-        throw new ConfigurationError(`Provider "${providerId}" is not configured. Set the required API key.`);
-    }
-    const adapter = descriptor.create({ env: deps.env });
-    const capability = adapter.repository;
-    // Defensive fail-closed: the descriptor advertised support but the
-    // Adapter omitted the handle. Treat as unsupported so a registry
-    // mismatch can never reach transport.
-    if (!capability) {
-        throw new UnsupportedCapabilityError(providerId, "repository-exploration");
-    }
     // Shared Repository execution dependencies. The cache/sleep/random
     // default to the same production values as Search but are kept as
     // separate optional MainDependencies so repository tests can inject
@@ -758,30 +820,43 @@ async function handleRepo(args, outputMode, deps) {
         sleep: deps.repositorySleep,
         random: deps.repositoryRandom,
     };
-    switch (command) {
-        case "search": {
-            const language = flags.language;
-            const maxChars = flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined;
-            const noCache = flags["no-cache"] === true;
-            return invokeCommand(deps.invocation, () => repoSearch(repo, searchQuery, { language, maxChars, noCache }, { capability, execution: executionDeps }), outputMode, deps.now, deps.secrets);
-        }
-        case "tree": {
-            const treePath = flags.path;
-            const depth = flags.depth ? parseInt(flags.depth, 10) : undefined;
-            const noCache = flags["no-cache"] === true;
-            return invokeCommand(deps.invocation, () => repoTree(repo, { path: treePath, depth, noCache }, { capability, execution: executionDeps }), outputMode, deps.now, deps.secrets);
-        }
-        case "read": {
-            const maxChars = flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined;
-            const noCache = flags["no-cache"] === true;
-            return invokeCommand(deps.invocation, () => repoRead(repo, readPath, { maxChars, noCache }, { capability, execution: executionDeps }), outputMode, deps.now, deps.secrets);
-        }
-        default:
-            // Unreachable: the parse-level validation above already rejected
-            // unknown subcommands. Keep a defensive throw so the dispatch
-            // table stays total.
-            throw new ValidationError(`Unknown repo command: ${command}`, 'Run "scoutline repo --help" for available commands');
-    }
+    const language = flags.language;
+    const maxChars = flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined;
+    const noCache = flags["no-cache"] === true;
+    const treePath = flags.path;
+    const depth = flags.depth ? parseInt(flags.depth, 10) : undefined;
+    // Provider-fallback Ticket 02: route every subcommand through the
+    // shared executor. All three projections (search/tree/read) share
+    // the `repository-exploration` Capability, so a single executor
+    // invocation wraps the chosen subcommand.
+    return invokeCommand(deps.invocation, async (context) => {
+        const outcome = await executeWithFallback({
+            capabilityId: "repository-exploration",
+            commandLabel: "repo",
+            effectiveProvider: providerId,
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            fallbackEnabled: deps.fallbackEnabled,
+            writeStderr: (s) => deps.invocation.writeStderr(s),
+        }, async (descriptor) => {
+            const adapter = descriptor.create({ env: deps.env });
+            const capability = adapter.repository;
+            switch (command) {
+                case "search":
+                    return repoSearch(repo, searchQuery, { language, maxChars, noCache }, { capability, execution: executionDeps }, context);
+                case "tree":
+                    return repoTree(repo, { path: treePath, depth, noCache }, { capability, execution: executionDeps }, context);
+                case "read":
+                    return repoRead(repo, readPath, { maxChars, noCache }, { capability, execution: executionDeps }, context);
+                default:
+                    // Unreachable: the parse-level validation above already
+                    // rejected unknown subcommands. Keep a defensive throw so
+                    // the dispatch table stays total.
+                    throw new ValidationError(`Unknown repo command: ${command}`, 'Run "scoutline repo --help" for available commands');
+            }
+        });
+        return outcome.result;
+    }, outputMode, deps.now, deps.secrets);
 }
 async function handleTools(args, outputMode, deps) {
     const { flags } = parseArgs(args);
@@ -986,7 +1061,18 @@ export async function main(args, dependencies) {
     // redaction follows the same environment the handlers see — a secret
     // that exists only in MainDependencies.env is still redacted from output.
     const secrets = configuredSecrets(env);
-    const { outputFormat, forcePretty, forceRaw, provider, rest } = extractGlobalOptions([...args]);
+    const { outputFormat, forcePretty, forceRaw, provider, noFallback, rest } = extractGlobalOptions([...args]);
+    // Provider-fallback kill-switch. The flag and the env are both
+    // opt-outs; either is sufficient to disable the cross-Provider
+    // candidate loop. The flag wins when both are present (the user
+    // is being explicit). `SCOUTLINE_NO_FALLBACK` is read from the
+    // injected `env` (B3) so redaction and executor preflight see
+    // the same environment the user actually configured. Truthy
+    // values include any non-empty string, so `SCOUTLINE_NO_FALLBACK=1`
+    // and `SCOUTLINE_NO_FALLBACK=true` both opt out; an empty string
+    // is the conventional "unset" form.
+    const envDisablesFallback = typeof env.SCOUTLINE_NO_FALLBACK === "string" && env.SCOUTLINE_NO_FALLBACK.length > 0;
+    const fallbackEnabled = !(noFallback || envDisablesFallback);
     // Fixup C — B10: resolve the output mode BEFORE the dispatch try/catch.
     // An invalid explicit mode still surfaces as a typed ValidationError,
     // but the surface formatter uses the user's REQUESTED mode (or the
@@ -1021,6 +1107,7 @@ export async function main(args, dependencies) {
         now,
         provider,
         providerDescriptors,
+        fallbackEnabled,
         searchCache,
         searchSleep,
         searchRandom,
@@ -1039,6 +1126,7 @@ export async function main(args, dependencies) {
         researchCache,
         researchSleep,
         researchRandom,
+        researchRegisterInterrupt: dependencies.researchRegisterInterrupt,
     };
     try {
         switch (command) {