scoutline 0.10.2 → 0.12.0

package/dist/index.js

@@ -17,13 +17,20 @@ 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 { resolveEnvFromConfig } from "./lib/config-store.js";
+import { inspectConfig, createDefaultVerificationPromoter, createDefaultHintShownStore, } from "./lib/config-store.js";
+import { createDefaultQuotaStore, refreshQuotaSnapshots, } from "./lib/quota-store.js";
+import { createQuotaStoreConsumptionSink } from "./lib/consumption.js";
+import { classifyCredentialState, formatEnvOnlyHint, isCommandHelpInvocation, OBSERVATIONAL_COMMANDS, } from "./lib/trigger-detection.js";
+import { resolveProviderId, resolveEffectiveProvider } from "./providers/selection.js";
+import { BUILT_IN_PROVIDER_DESCRIPTORS } from "./providers/registry.js";
+import { executeWithFallback } from "./lib/provider-fallback.js";
 import { visionOperationToCapability } from "./capabilities/vision.js";
+import { handleInitWithHelp, createInquirerPrompts, createDefaultConfigStore, } from "./commands/init.js";
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require("../package.json");
@@ -54,6 +61,7 @@ Commands:
   doctor   Provider-aware environment + connectivity checks
   cache    Inspect or clear the local cache (stats / clear)
   code     Execute TypeScript tool chains (Code Mode, Z.AI)
+  init     Interactive onboarding wizard (writes ~/.scoutline/config.json)
 
 Provider selection (precedence: --provider, then SCOUTLINE_PROVIDER, then zai):
   --provider <zai|minimax|tavily|exa|brave|firecrawl>   Select the active Provider for shared capabilities
@@ -64,11 +72,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)
@@ -87,6 +98,7 @@ Help:
   scoutline call --help
   scoutline code --help
   scoutline cache --help
+  scoutline init --help
 `.trim();
 function parseArgs(args) {
     const flags = {};
@@ -137,6 +149,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 +174,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) {
@@ -197,66 +220,107 @@ async function handleVision(args, outputMode, deps) {
     // a parse-time VALIDATION_ERROR and are rejected before any Provider
     // resolution, support check, or media access.
     const operation = visionOperationForCommand(command);
+    // 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. Computed
+    // before selection so PB-T4 can rank providers against the exact
+    // sub-operation being dispatched.
+    const capabilityId = visionOperationToCapability(operation);
     // 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.
-    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.
-    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);
-    }
+    // beyond the descriptor `isConfigured` metadata check (FR-003); the
+    // configured check below is the executor's responsibility (Provider
+    // Fallback Tech Plan §"Per-handler refactor pattern"). PB-T4: when
+    // no pin is present, the effective provider is the highest-scored
+    // configured+capable provider for this vision operation against the
+    // injected quota snapshot; pin input still bypasses ranking.
+    const providerId = resolveEffectiveProvider({
+        explicitProvider: deps.provider,
+        env: deps.env,
+        capabilityId,
+        descriptors: deps.providerDescriptors,
+        quotaSnapshot: deps.quotaState,
+    });
     // 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,
+                // PB-T2: thread the actual attempted descriptor ID + sink
+                // through so vision emits one consumption event per
+                // billable invoke attempt at the execution seam. The
+                // descriptor ID is the *attempted* provider (not the
+                // registry-derived effective provider) so fallback attempts
+                // record the actual descriptor that invoked transport.
+                ...(deps.consume !== undefined ? { consume: deps.consume } : {}),
+                ...(deps.consume !== undefined ? { provider: descriptor.id } : {}),
+                ...(deps.now !== undefined ? { now: deps.now } : {}),
+            };
+            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 +444,23 @@ 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).
-    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");
-    }
+    // 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 beyond the descriptor `isConfigured` metadata
+    // check (FR-003); the configured check is the executor's
+    // responsibility (Provider Fallback Tech Plan §"Per-handler refactor
+    // pattern"). PB-T4: when no pin is present, the effective provider is
+    // the highest-scored configured+capable provider for `search` against
+    // the injected quota snapshot; pin input still bypasses ranking.
+    const providerId = resolveEffectiveProvider({
+        explicitProvider: deps.provider,
+        env: deps.env,
+        capabilityId: "search",
+        descriptors: deps.providerDescriptors,
+        quotaSnapshot: deps.quotaState,
+    });
     const query = positional.join(" ");
     const fieldsRaw = flags.fields;
     const fields = fieldsRaw
@@ -411,7 +469,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,
@@ -419,18 +477,40 @@ async function handleSearch(args, outputMode, deps) {
         location: flags.location,
         topic,
         type,
-        maxSummary: flags["max-summary"]
-            ? parseInt(flags["max-summary"], 10)
-            : undefined,
+        maxSummary: flags["max-summary"] ? parseInt(flags["max-summary"], 10) : undefined,
         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);
@@ -456,44 +536,19 @@ async function handleRead(args, outputMode, deps) {
     }
     const extract = extractFlag !== undefined ? extractFlag : undefined;
     // Resolve the effective Provider (DESIGN.md §6, FR-001–FR-005):
-    // explicit --provider > SCOUTLINE_PROVIDER > default zai. Selection
-    // 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, {
+    // explicit --provider > SCOUTLINE_PROVIDER > quota-ranked pick.
+    // Selection never consults credentials beyond the descriptor
+    // `isConfigured` metadata check (FR-003) and never branches on
+    // Provider ID; an unknown explicit/env value throws
+    // VALIDATION_ERROR here. (PB-T4.)
+    const providerId = resolveEffectiveProvider({
+        explicitProvider: deps.provider,
+        env: deps.env,
+        capabilityId: "reader",
+        descriptors: deps.providerDescriptors,
+        quotaSnapshot: deps.quotaState,
+    });
+    const readOptions = {
         format: flags.format,
         noImages: flags["no-images"] === true,
         noCache: flags["no-cache"] === true,
@@ -505,7 +560,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);
@@ -522,23 +609,15 @@ async function handleCrawl(args, outputMode, deps) {
         throw new ValidationError("URL must start with http:// or https://");
     }
     // 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");
-    }
+    // explicit --provider > SCOUTLINE_PROVIDER > quota-ranked pick.
+    // (PB-T4.)
+    const providerId = resolveEffectiveProvider({
+        explicitProvider: deps.provider,
+        env: deps.env,
+        capabilityId: "crawl",
+        descriptors: deps.providerDescriptors,
+        quotaSnapshot: deps.quotaState,
+    });
     // 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 +627,43 @@ 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);
@@ -577,23 +680,15 @@ async function handleMap(args, outputMode, deps) {
         throw new ValidationError("URL must start with http:// or https://");
     }
     // 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");
-    }
+    // explicit --provider > SCOUTLINE_PROVIDER > quota-ranked pick.
+    // (PB-T4.)
+    const providerId = resolveEffectiveProvider({
+        explicitProvider: deps.provider,
+        env: deps.env,
+        capabilityId: "map",
+        descriptors: deps.providerDescriptors,
+        quotaSnapshot: deps.quotaState,
+    });
     // 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 +698,37 @@ 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);
@@ -627,42 +744,82 @@ async function handleResearch(args, outputMode, deps) {
     const outputLength = validateResearchEnum(flags["output-length"], ["short", "standard", "long"], "--output-length");
     const citationFormat = validateResearchEnum(flags["citation-format"], ["numbered", "mla", "apa", "chicago"], "--citation-format");
     // 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");
-    }
+    // explicit --provider > SCOUTLINE_PROVIDER > quota-ranked pick.
+    // (PB-T4.)
+    const providerId = resolveEffectiveProvider({
+        explicitProvider: deps.provider,
+        env: deps.env,
+        capabilityId: "research",
+        descriptors: deps.providerDescriptors,
+        quotaSnapshot: deps.quotaState,
+    });
     // 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,
@@ -721,34 +878,18 @@ async function handleRepo(args, outputMode, deps) {
         throw new ValidationError(`Unknown repo command: ${command}`, 'Run "scoutline repo --help" for available commands');
     }
     // Resolve the effective Provider (DESIGN.md §6, FR-001–FR-005):
-    // explicit --provider > SCOUTLINE_PROVIDER > default zai. Selection
-    // 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");
-    }
+    // explicit --provider > SCOUTLINE_PROVIDER > quota-ranked pick.
+    // Selection never consults credentials beyond the descriptor
+    // `isConfigured` metadata check (FR-003) and never branches on
+    // Provider ID; an unknown explicit/env value throws
+    // VALIDATION_ERROR here. (PB-T4.)
+    const providerId = resolveEffectiveProvider({
+        explicitProvider: deps.provider,
+        env: deps.env,
+        capabilityId: "repository-exploration",
+        descriptors: deps.providerDescriptors,
+        quotaSnapshot: deps.quotaState,
+    });
     // 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 +899,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);
@@ -794,6 +948,7 @@ async function handleTools(args, outputMode, deps) {
         full: flags.full === true,
         typescript: flags.typescript === true || flags.ts === true,
         enableVision: flags.vision !== false,
+        env: deps.env,
     }, context), outputMode, deps.now, deps.secrets);
 }
 async function handleTool(args, outputMode, deps) {
@@ -802,7 +957,7 @@ async function handleTool(args, outputMode, deps) {
         deps.invocation.writeStdout(TOOLS_HELP);
         return 0;
     }
-    return invokeCommand(deps.invocation, (context) => showTool(positional[0], { enableVision: flags.vision !== false }, context), outputMode, deps.now, deps.secrets);
+    return invokeCommand(deps.invocation, (context) => showTool(positional[0], { enableVision: flags.vision !== false, env: deps.env }, context), outputMode, deps.now, deps.secrets);
 }
 async function handleCall(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
@@ -816,6 +971,7 @@ async function handleCall(args, outputMode, deps) {
         stdin: flags.stdin === true,
         dryRun: flags["dry-run"] === true,
         enableVision: flags.vision !== false,
+        env: deps.env,
     }, context), outputMode, deps.now, deps.secrets);
 }
 async function handleDoctor(args, outputMode, deps) {
@@ -845,6 +1001,29 @@ async function handleDoctor(args, outputMode, deps) {
             sleep: deps.searchSleep,
             random: deps.searchRandom,
             cacheSummary,
+            // T3b: thread the injected promoter + clock through to the
+            // report builder so a successful probe can flip the matching
+            // record from `unverified` to `verified`. When the promoter
+            // is absent (hermetic test path), Doctor runs without
+            // promotion. The write-failure sink surfaces promotion
+            // errors as a stderr notice without affecting the exit code.
+            verificationPromoter: deps.verificationPromoter,
+            now: deps.now ?? Date.now,
+            onPromotionError: (providerId, error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                deps.invocation.writeStderr(`scoutline: verification promotion failed for "${providerId}": ${message}\n`);
+            },
+            // PB-T5: thread the snapshot + verification records through
+            // to the report builder so each Provider entry carries a
+            // `quota` summary (source/freshness) and a `verification`
+            // summary. Both are pure state reads; Doctor never
+            // live-probes quota. The snapshot appears even under
+            // --no-tools (a snapshot read is local state, not
+            // transport).
+            ...(deps.quotaState !== undefined ? { quotaSnapshot: deps.quotaState } : {}),
+            ...(deps.verificationRecords !== undefined
+                ? { verificationRecords: deps.verificationRecords }
+                : {}),
         }),
     }), outputMode, deps.now, deps.secrets);
 }
@@ -904,6 +1083,17 @@ async function handleQuota(args, outputMode, deps) {
             env: deps.env,
             sleep: deps.searchSleep,
             random: deps.searchRandom,
+            // PB-T5: thread the snapshot + store + clock through so the
+            // dashboard reads each Provider's snapshot first, labels
+            // source/freshness, and persists a live-probe fallback via
+            // the awaited write-through. When `quotaState` is absent
+            // (test path that didn't opt in), the snapshot path is
+            // disabled and every configured Provider is live-probed
+            // (byte-for-byte pre-PB-T5 behavior — no `quotaSource`
+            // field attached).
+            ...(deps.quotaState !== undefined ? { quotaSnapshot: deps.quotaState } : {}),
+            ...(deps.quotaStore !== undefined ? { quotaStore: deps.quotaStore } : {}),
+            now: deps.now ?? Date.now,
         }),
         writeStderr: (value) => deps.invocation.writeStderr(value),
         secrets: deps.secrets,
@@ -924,17 +1114,17 @@ async function handleCode(args, outputMode, deps) {
             if (!filePath) {
                 throw new ValidationError("Missing code file", "Usage: scoutline code run <file>");
             }
-            return invokeCommand(deps.invocation, (context) => runCodeFile(filePath, { timeout, includeLogs }, context), outputMode, deps.now, deps.secrets);
+            return invokeCommand(deps.invocation, (context) => runCodeFile(filePath, { timeout, includeLogs, env: deps.env }, context), outputMode, deps.now, deps.secrets);
         }
         case "eval": {
             const code = positional.slice(1).join(" ");
             if (!code) {
                 throw new ValidationError("Missing code string", "Usage: scoutline code eval <code>");
             }
-            return invokeCommand(deps.invocation, (context) => evalCode(code, { timeout, includeLogs }, context), outputMode, deps.now, deps.secrets);
+            return invokeCommand(deps.invocation, (context) => evalCode(code, { timeout, includeLogs, env: deps.env }, context), outputMode, deps.now, deps.secrets);
         }
         case "interfaces":
-            return invokeCommand(deps.invocation, (context) => printInterfaces(context), outputMode, deps.now, deps.secrets);
+            return invokeCommand(deps.invocation, (context) => printInterfaces({ env: deps.env }, context), outputMode, deps.now, deps.secrets);
         case "prompt":
             return invokeCommand(deps.invocation, async (context) => printPromptTemplate(context), outputMode, deps.now, deps.secrets);
         default:
@@ -942,6 +1132,37 @@ async function handleCode(args, outputMode, deps) {
     }
 }
 const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Map Plan A's `ProviderVerification` records (config-store shape) to
+ * the capability contract's `ProviderVerificationSummary` (PB-T5). The
+ * shapes are structurally identical; the indirection exists only so
+ * `capabilities/diagnostics.ts` does not import `lib/config-store.ts`
+ * (the capability contract keeps a strict import boundary). Returns
+ * `undefined` when no Provider has a verification record, so the
+ * dispatcher can omit the dependency entirely (Doctor's report builder
+ * leaves the `verification` field off in that case).
+ *
+ * When the caller injected its own `verificationRecords` (test path),
+ * that injection wins — the test owns the verification view.
+ */
+function loadVerificationRecords(config, dependencies) {
+    if (dependencies.verificationRecords !== undefined)
+        return dependencies.verificationRecords;
+    const out = {};
+    let hasAny = false;
+    for (const id of Object.keys(config.providers)) {
+        const record = config.providers[id]?.verification;
+        if (!record)
+            continue;
+        out[id] = {
+            status: record.status,
+            checkedAt: record.checkedAt,
+            ...(record.reason !== undefined ? { reason: record.reason } : {}),
+        };
+        hasAny = true;
+    }
+    return hasAny ? out : undefined;
+}
 export async function main(args, dependencies) {
     const { invocation, env, now } = dependencies;
     const providerDescriptors = dependencies.providerDescriptors ?? BUILT_IN_PROVIDER_DESCRIPTORS;
@@ -985,8 +1206,13 @@ export async function main(args, dependencies) {
     // Resolve configured Provider credentials from the INJECTED env (B3) so
     // 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]);
+    // T2a: this env-only view is used by credential-free commands that
+    // short-circuit before config load; the full resolvedEnv (env + file keys)
+    // is computed below for credentialed paths.
+    const envSecrets = configuredSecrets(env);
+    const { outputFormat, forcePretty, forceRaw, provider, noFallback, rest } = extractGlobalOptions([
+        ...args,
+    ]);
     // 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
@@ -1001,9 +1227,12 @@ export async function main(args, dependencies) {
     catch (error) {
         // The explicit mode is invalid — fall back to a deterministic
         // compact form so we can still surface a structured error envelope.
-        invocation.writeStderr(formatErrorOutput(error, "data", secrets));
+        invocation.writeStderr(formatErrorOutput(error, "data", envSecrets));
         return getErrorExitCode(error);
     }
+    // Credential-free commands: --help / --version short-circuit before any
+    // config-file load so a corrupt or unreadable config.json never blocks
+    // them (T2a — command classification).
     if (rest.length === 0 || rest[0] === "--help" || rest[0] === "-h") {
         invocation.writeStdout(MAIN_HELP);
         return 0;
@@ -1014,13 +1243,53 @@ export async function main(args, dependencies) {
     }
     const command = rest[0];
     const commandArgs = rest.slice(1);
-    const handlerDeps = {
+    // PB-T1/PB-T2 — Quota snapshot store + consumption sink.
+    //
+    // Constructed once here so `buildHandlerDeps` can close over
+    // `consume` and thread it through every handler. The hermeticity
+    // gate (`quotaRefreshEnabled`, mirroring trigger-detection): the
+    // PRODUCTION sink is built ONLY in full production mode (no
+    // injected `loadScoutlineConfig` AND no injected `providerDescriptors`).
+    // Either injection signals a test that owns its own descriptor/config
+    // construction; without this gate, the production sink would silently
+    // reach the user's real `~/.scoutline/state.json` during a test run
+    // that did not inject `quotaStore` either. Tests that need to assert
+    // on consumption inject `MainDependencies.consume` directly.
+    //
+    // The sink is the *where* of consumption recording; shared execution
+    // (`lib/execution.ts`) is the *when* (one event per billable invoke
+    // attempt, after the cache-miss check, around each `invoke()` call).
+    // Shared execution awaits `record()` per invoke attempt, so the write
+    // is on the critical path before the result returns outward —
+    // surviving the bin's immediate `process.exit(status)`.
+    const quotaRefreshEnabled = !dependencies.loadScoutlineConfig && !dependencies.providerDescriptors;
+    const quotaStore = dependencies.quotaStore ?? createDefaultQuotaStore();
+    const consume = dependencies.consume ??
+        (quotaRefreshEnabled
+            ? createQuotaStoreConsumptionSink({ store: quotaStore, now: now ?? Date.now })
+            : undefined);
+    // PB-T4: quota snapshot for selection. Declared here so
+    // `buildHandlerDeps` closes over the binding; assigned AFTER the
+    // PB-T1 pre-command refresh so observational commands' fresh data is
+    // reflected. The seven shared handlers consume this via
+    // `resolveEffectiveProvider`; Doctor/quota/cache/init/raw-tools
+    // ignore it. Hermeticity gate mirrors `consume`: the PRODUCTION read
+    // runs only in full production mode; tests inject `quotaState`
+    // directly when they assert a specific selection outcome, and
+    // otherwise leave it undefined so the resolver degrades to
+    // first-eligible (pre-PB-T4 behaviour).
+    let quotaState = dependencies.quotaState;
+    // Build HandlerDependencies for a given credential view. The
+    // cache/sleep/random fields are always available (resolved above); only
+    // env/secrets/fallbackEnabled depend on whether config has been loaded.
+    const buildHandlerDeps = (credEnv, credSecrets, credFallback) => ({
         invocation,
-        env,
-        secrets,
+        env: credEnv,
+        secrets: credSecrets,
         now,
         provider,
         providerDescriptors,
+        fallbackEnabled: credFallback,
         searchCache,
         searchSleep,
         searchRandom,
@@ -1039,40 +1308,342 @@ export async function main(args, dependencies) {
         researchCache,
         researchSleep,
         researchRandom,
+        researchRegisterInterrupt: dependencies.researchRegisterInterrupt,
+        // Promoter wiring (T3b). When the caller explicitly injects a
+        // promoter, use it (tests assert behavior this way). Otherwise, in
+        // PRODUCTION (no injected config reader), construct the default
+        // real-file promoter. When a test injects `loadScoutlineConfig`
+        // (hermetic in-memory config), promotion is DISABLED so the
+        // default promoter never reaches the user's real
+        // ~/.scoutline/config.json during a test run.
+        verificationPromoter: dependencies.verificationPromoter ??
+            (dependencies.loadScoutlineConfig ? undefined : createDefaultVerificationPromoter()),
+        // PB-T2: thread the production consumption sink through. `consume`
+        // is constructed once in `main` (below) and shared by every
+        // handler; tests inject their own through `MainDependencies.consume`.
+        // When undefined (test path that didn't opt in), no events fire.
+        consume,
+        // PB-T4: thread the quota snapshot for selection. `quotaState` is
+        // resolved once in `main` (below) after the PB-T1 pre-command
+        // refresh and shared by every handler; tests inject their own
+        // through `MainDependencies.quotaState`. When undefined (test path
+        // or no-snapshot production run), `resolveEffectiveProvider`
+        // degrades to first-eligible in registry order.
+        quotaState,
+        // PB-T5: thread the quota store for `quota`'s live-probe
+        // write-through. Doctor ignores this field (it never live-probes
+        // quota). Tests inject an in-memory double; production wires the
+        // singleton constructed in `main`.
+        quotaStore: dependencies.quotaStore ?? (quotaRefreshEnabled ? quotaStore : undefined),
+        // PB-T5: verification records are NOT threaded here. They are
+        // derived from `config` AFTER it is loaded (the credentialed
+        // path); `buildHandlerDeps` runs once BEFORE config load (the
+        // cache short-circuit), so referencing `config` here would be a
+        // use-before-initialization error. The post-config
+        // `handlerDepsWithVerification` spread below threads the resolved
+        // records in for Doctor.
+    });
+    // Cache is credential-free (no Provider resolution, no descriptor lookup,
+    // no transport). Short-circuit before config load so a corrupt
+    // config.json never blocks cache inspection or clearing. Env-only
+    // secrets suffice: the stats/clear output carries no credentials.
+    if (command === "cache") {
+        try {
+            return await handleCache(commandArgs, outputMode, buildHandlerDeps(env, envSecrets, true));
+        }
+        catch (error) {
+            invocation.writeStderr(formatErrorOutput(error, outputMode, envSecrets));
+            return getErrorExitCode(error);
+        }
+    }
+    // `init` manages config itself (it inspects + writes via the T1
+    // primitives, never reads the resolvedEnv the credentialed path
+    // produces). Short-circuit before the credentialed config load so a
+    // corrupt or unreadable config.json never blocks the wizard that is
+    // documented to repair it. The wizard is presented-only; it does not
+    // dispatch through the credentialed handler boundary. Release gate
+    // (T3a ticket): the command's code lands now, but its public docs
+    // (MAIN_HELP Commands list, README setup, skills/) wait for T3b.
+    if (command === "init") {
+        const initDeps = {
+            descriptors: providerDescriptors,
+            prompts: dependencies.initPrompts ?? createInquirerPrompts(),
+            configStore: dependencies.initConfigStore ?? createDefaultConfigStore(),
+            env,
+            now: now ?? Date.now,
+            stdinIsTTY: invocation.stdinIsTTY,
+            writeStderr: (value) => invocation.writeStderr(value),
+            writeStdout: (value) => invocation.writeStdout(value),
+        };
+        try {
+            return await handleInitWithHelp(commandArgs, initDeps);
+        }
+        catch (error) {
+            invocation.writeStderr(formatErrorOutput(error, outputMode, envSecrets));
+            return getErrorExitCode(error);
+        }
+    }
+    // Credentialed path: load the config file (T2a — Plan A). T3b makes
+    // the load TOLERANT so command help remains usable under a corrupt
+    // config (review item 9: "do not force a credential check merely to
+    // render help"). The injected reader (when provided) is still strict
+    // for backward compatibility with existing tests; the production
+    // path uses `inspectConfig`.
+    //
+    // Classification of the corrupt case:
+    //   - command help (`<cmd> --help`): proceed with an empty config so
+    //     the handler can render its help. The handler's own help
+    //     short-circuit never touches config.
+    //   - everything else (including observational `doctor`/`quota`):
+    //     refuse with the existing CONFIGURATION_ERROR (exit 3). The
+    //     error's help points at `init` as the recovery path.
+    // Observational commands do NOT bypass the corrupt refuse — they
+    // still need `resolvedEnv` (which needs config) to probe/report.
+    const isHelpInvocation = isCommandHelpInvocation(commandArgs);
+    const isObservational = OBSERVATIONAL_COMMANDS.has(command);
+    let config;
+    if (dependencies.loadScoutlineConfig) {
+        try {
+            config = await dependencies.loadScoutlineConfig();
+        }
+        catch (error) {
+            if (isHelpInvocation) {
+                config = { version: 1, providers: {} };
+            }
+            else {
+                invocation.writeStderr(formatErrorOutput(error, outputMode, envSecrets));
+                return getErrorExitCode(error);
+            }
+        }
+    }
+    else {
+        const inspection = await inspectConfig();
+        if (inspection.status === "corrupt") {
+            if (isHelpInvocation) {
+                config = { version: 1, providers: {} };
+            }
+            else {
+                invocation.writeStderr(formatErrorOutput(inspection.error, outputMode, envSecrets));
+                return getErrorExitCode(inspection.error);
+            }
+        }
+        else if (inspection.status === "absent") {
+            config = { version: 1, providers: {} };
+        }
+        else {
+            config = inspection.config;
+        }
+    }
+    // Build resolvedEnv: the injected env with file-configured API keys
+    // layered in for any Provider NOT already configured via env (env
+    // overrides file; alias precedence preserved). process.env is never
+    // mutated — the returned object is a fresh shallow copy owned by this
+    // invocation.
+    const resolvedEnv = resolveEnvFromConfig(env, config, providerDescriptors);
+    const secrets = configuredSecrets(resolvedEnv);
+    // Trigger detection (T3b — Option B). The ONLY interception here is
+    // the env-only one-time hint: when the user is running on
+    // environment-variable credentials and has never been through
+    // `scoutline init`, we emit a single stderr hint pointing at the
+    // wizard and persist `config.json.hintShown` so it never repeats.
+    // The command then runs normally and preserves its natural output/exit.
+    //
+    // The "missing credential everywhere" case is NOT intercepted here:
+    // the handler's own preflight already surfaces the existing
+    // `CONFIGURATION_ERROR` exit 3 (see
+    // {@link missingCredentialError} in trigger-detection.ts for the
+    // shared error contract). Intercepting it pre-dispatch would break
+    // the locked validation-before-configuration ordering (an invalid
+    // `--count` must exit 1 with VALIDATION_ERROR even when no credential
+    // is present — see search.test.js "count validation ordering").
+    //
+    // Hermeticity: trigger detection runs ONLY in full production mode
+    // (no injected `loadScoutlineConfig` AND no injected
+    // `providerDescriptors`). Either injection signals a test that owns
+    // its own config/descriptor construction; fake descriptors routinely
+    // lie about `isConfigured`, so trusting them here would mis-classify.
+    // Dedicated trigger-detection tests run via subprocess (the real
+    // binary) or via `main()` without injecting either, optionally
+    // pointed at a temp `SCOUTLINE_CONFIG_DIR`.
+    const triggerDetectionEnabled = !dependencies.loadScoutlineConfig && !dependencies.providerDescriptors;
+    if (triggerDetectionEnabled && !isHelpInvocation && !isObservational) {
+        const state = classifyCredentialState({
+            descriptors: providerDescriptors,
+            env,
+            resolvedEnv,
+            config,
+        });
+        if (state.kind === "env-only" && config.hintShown !== true) {
+            invocation.writeStderr(formatEnvOnlyHint());
+            // Persist hintShown best-effort. A write failure is isolated: the
+            // hint simply does not repeat within this process; the next run
+            // tries again. The injected store keeps tests hermetic.
+            const hintStore = dependencies.hintShownStore ?? createDefaultHintShownStore();
+            try {
+                await hintStore.setHintShown();
+            }
+            catch {
+                // Best-effort: do not turn a hint into a failure.
+            }
+        }
+    }
+    // Provider-fallback resolution (T2a — review blocker 5). Precedence:
+    //   1. Invocation opt-out (`--no-fallback` flag or `SCOUTLINE_NO_FALLBACK`
+    //      env non-empty) — either disables the cross-Provider candidate
+    //      loop, matching the 0.11.0 kill-switch contract.
+    //   2. `config.fallbackEnabled` — the wizard's Step-5 preference, so the
+    //      onboarding answer is no longer write-only.
+    //   3. Default `true` (the 0.11.0 always-on contract).
+    const envDisablesFallback = typeof env.SCOUTLINE_NO_FALLBACK === "string" && env.SCOUTLINE_NO_FALLBACK.length > 0;
+    const fallbackEnabled = noFallback || envDisablesFallback ? false : (config.fallbackEnabled ?? true);
+    const handlerDeps = buildHandlerDeps(resolvedEnv, secrets, fallbackEnabled);
+    // PB-T5 — derive Plan A verification records from the loaded config
+    // AFTER `config` is in scope. `buildHandlerDeps` runs once BEFORE
+    // config load (the cache short-circuit), so this derivation cannot
+    // live inside it (TDZ on `config`). Returned as a fresh spread so
+    // the cache/init paths that already returned are unaffected; only
+    // the credentialed handler chain sees the verification records.
+    // Returns `undefined` when no Provider has a verification record,
+    // leaving the field absent (Doctor's report builder omits the
+    // `verification` field in that case — backward-compatible).
+    const verificationRecords = loadVerificationRecords(config, dependencies);
+    const handlerDepsWithVerification = verificationRecords === undefined ? handlerDeps : { ...handlerDeps, verificationRecords };
+    // PB-T1 — Quota snapshot refresh lifecycle.
+    //
+    // The refresh is awaited and bounded (review blocker 3): every
+    // refresh and store write is awaited before `main` returns so it
+    // survives the bin's immediate `process.exit(status)`. There is no
+    // fire-and-forget tail.
+    //
+    // Two triggers:
+    //   1. Explicit `quota`/`doctor` refresh (force) — runs BEFORE the
+    //      handler so the dashboard/report reflects fresh data. The
+    //      cadence gate is bypassed (the user asked for fresh data); the
+    //      per-provider transport timeout + single-attempt contract
+    //      still applies.
+    //   2. After-command due-refresh (cadence-gated) — runs AFTER every
+    //      other recognized credentialed command. A provider whose
+    //      `observedAt` is within the staleness threshold is skipped
+    //      (Tavily's 10/10min is the floor). This keeps the snapshot
+    //      live between explicit refreshes without excessive polling.
+    //
+    // Failure policy: best-effort. A per-provider refresh failure is
+    // routed to a stderr notice and never rejects the outer promise. The
+    // snapshot stays stale; the next due-refresh retries.
+    //
+    // Lock scope: each provider's `capability.invoke()` runs in parallel
+    // (Promise.all). Store writes are serialized within the process by
+    // the per-file async mutex in `createDefaultQuotaStore`. Cross-process
+    // concurrency is last-write-wins (acceptable for an observational
+    // heuristic; the atomic rename keeps the final state crash-safe).
+    //
+    // Hermeticity gate: the refresh runs ONLY in full production mode
+    // (no injected `loadScoutlineConfig` AND no injected
+    // `providerDescriptors`). Either injection signals a test that owns
+    // its own descriptor/config construction; fake descriptors routinely
+    // count `invoke()` calls and would see the refresh as a stray
+    // invocation. Dedicated refresh lifecycle tests run via subprocess
+    // (the real binary) or through `refreshQuotaSnapshots` directly.
+    // This mirrors the trigger-detection gate (T3b).
+    //
+    // (`quotaRefreshEnabled`, `quotaStore`, and `consume` are declared
+    // earlier alongside `buildHandlerDeps` so the sink closes over a
+    // defined binding — see PB-T2 above.)
+    const isQuotaObservationalCommand = command === "quota" || command === "doctor";
+    const refreshOnError = (providerId, error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        invocation.writeStderr(`scoutline: quota refresh failed for "${providerId}": ${message}\n`);
     };
+    if (quotaRefreshEnabled && isQuotaObservationalCommand) {
+        await refreshQuotaSnapshots({
+            descriptors: providerDescriptors,
+            env: resolvedEnv,
+            store: quotaStore,
+            now: now ?? Date.now,
+            force: true,
+            onError: refreshOnError,
+        });
+    }
+    // PB-T4: read the quota snapshot once for selection, AFTER any
+    // pre-command refresh so observational commands' fresh data is
+    // reflected. `quotaStore.read()` is fail-open (a corrupt or absent
+    // `state.json` yields an empty state + warning, never a throw), so
+    // this can never block dispatch. Tests that need a specific
+    // selection outcome inject `MainDependencies.quotaState` directly,
+    // which short-circuits this read. The snapshot is observational; the
+    // resolver never writes or decrements it.
+    if (dependencies.quotaState === undefined && quotaRefreshEnabled) {
+        quotaState = await quotaStore.read();
+    }
+    // Thread the resolved snapshot into the handler deps. When undefined
+    // (test path that didn't opt in, or non-production mode without an
+    // injected snapshot), `resolveEffectiveProvider` degrades to
+    // first-eligible — the pre-PB-T4 behaviour. Built on top of
+    // `handlerDepsWithVerification` so PB-T5's verification records also
+    // reach every handler.
+    const handlerDepsWithSelection = quotaState === undefined
+        ? handlerDepsWithVerification
+        : { ...handlerDepsWithVerification, quotaState };
+    let exitCode;
+    let commandRecognized = false;
     try {
         switch (command) {
             case "vision":
-                return await handleVision(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleVision(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "search":
-                return await handleSearch(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleSearch(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "read":
-                return await handleRead(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleRead(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "crawl":
-                return await handleCrawl(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleCrawl(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "map":
-                return await handleMap(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleMap(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "research":
-                return await handleResearch(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleResearch(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "repo":
-                return await handleRepo(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleRepo(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "tools":
-                return await handleTools(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleTools(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "tool":
-                return await handleTool(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleTool(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "call":
-                return await handleCall(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleCall(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "doctor":
-                return await handleDoctor(commandArgs, outputMode, handlerDeps);
-            case "cache":
-                return await handleCache(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleDoctor(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "quota":
-                return await handleQuota(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleQuota(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "code":
-                return await handleCode(commandArgs, outputMode, handlerDeps);
+                commandRecognized = true;
+                exitCode = await handleCode(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             default:
                 invocation.writeStderr(formatErrorOutput(new ValidationError(`Unknown command: ${command}`, 'Run "scoutline --help" for available commands'), outputMode, secrets));
-                return 1;
+                exitCode = 1;
+                break;
         }
     }
     catch (error) {
@@ -1081,7 +1652,32 @@ export async function main(args, dependencies) {
         // formatted in the resolved output mode — they used to be hardcoded
         // to "data" regardless of what the user asked for.
         invocation.writeStderr(formatErrorOutput(error, outputMode, secrets));
-        return getErrorExitCode(error);
-    }
+        exitCode = getErrorExitCode(error);
+        commandRecognized = true;
+    }
+    // After-command due-refresh (cadence-gated). Skip for:
+    //   - `quota`/`doctor` (already force-refreshed before the handler)
+    //   - help invocations (`<cmd> --help` exits 0 but did no real work)
+    //   - unrecognized commands (the default case above)
+    // Run even when the handler threw (commandRecognized + caught):
+    // the refresh is independent of the command's outcome and the
+    // snapshot stays live regardless. The staleness check inside
+    // `refreshQuotaSnapshots` skips providers whose `observedAt` is
+    // within the threshold, so the common case (fresh snapshot) is a
+    // single state-file read + no transport calls.
+    if (quotaRefreshEnabled &&
+        commandRecognized &&
+        !isQuotaObservationalCommand &&
+        !isHelpInvocation) {
+        await refreshQuotaSnapshots({
+            descriptors: providerDescriptors,
+            env: resolvedEnv,
+            store: quotaStore,
+            now: now ?? Date.now,
+            force: false,
+            onError: refreshOnError,
+        });
+    }
+    return exitCode;
 }
 //# sourceMappingURL=index.js.map