scoutline 0.22.0 → 0.24.0

package/dist/index.js

@@ -20,6 +20,8 @@ import { handleFetch } from "./commands/fetch.js";
 import { handleArchive, parseArchiveArgs } from "./commands/archive.js";
 import { handleWatch } from "./commands/watch.js";
 import { handleScience } from "./commands/science.js";
+import { investigate, INVESTIGATE_HELP, } from "./commands/investigate.js";
+import { ZaiApiClient } from "./lib/api-client.js";
 import { buildProviderCacheKey, cacheStats, clearAllCaches, parsePruneDuration, pruneCaches, } from "./lib/cache.js";
 import { parseBatchManifest } from "./lib/batch-manifest.js";
 import { assignBatchProviders } from "./lib/batch-assign.js";
@@ -33,7 +35,7 @@ import { buildJournalEntry, buildNoteEntry, buildSearchSkeleton, buildReadSkelet
 import { buildJournalRepeatMarker } from "./lib/journal.js";
 import { applyBudget } from "./lib/output-budget.js";
 import { persistCompaction } from "./lib/output-budget-persistence.js";
-import { FileError, ValidationError, UnsupportedCapabilityError, CommandOptionUnsupportedError, getErrorExitCode, } from "./lib/errors.js";
+import { ApiError, FileError, ValidationError, UnsupportedCapabilityError, CommandOptionUnsupportedError, getErrorExitCode, } from "./lib/errors.js";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as fs from "node:fs/promises";
@@ -42,15 +44,17 @@ import { invokeCommand, } from "./command-invocation.js";
 import { createFileResponseCache, defaultResponseCache, isIsolatedEnv, responseCacheDir, } from "./lib/cache.js";
 import { MAX_SUBQUERIES, parseContextText, readContextSource } from "./lib/context-file.js";
 import { configuredSecrets, redactSecrets } from "./lib/redact.js";
-import { configFilePath, readConfig, resolveConfigRoot, resolveConfigRootPure, resolveEnvFromConfig, setConfigValue, unsetConfigValue, } from "./lib/config-store.js";
+import { configFilePath, readConfig, resolveConfigRoot, resolveConfigRootPure, resolveEnvFromConfig, setConfigValue, unsetConfigValue, resolveFusionMode, } from "./lib/config-store.js";
 import { inspectConfig, createDefaultVerificationPromoter, createDefaultHintShownStore, } from "./lib/config-store.js";
 import { createDefaultQuotaStore, refreshQuotaSnapshots, } from "./lib/quota-store.js";
 import { createCompositeConsumptionSink, createQuotaStoreConsumptionSink, } from "./lib/consumption.js";
 import { createUsageLedgerSink, readUsageLedger, resolveUsageLedgerPath, } from "./lib/usage-ledger.js";
 import { classifyCredentialState, formatEnvOnlyHint, isCommandHelpInvocation, isDryRunBatchInvocation, OBSERVATIONAL_COMMANDS, } from "./lib/trigger-detection.js";
-import { resolveProviderId, resolveEffectiveProvider } from "./providers/selection.js";
+import { resolveProviderId, resolveEffectiveProvider, parseProviderId, } from "./providers/selection.js";
 import { BUILT_IN_PROVIDER_DESCRIPTORS } from "./providers/registry.js";
+import { createZaiDescriptor } from "./providers/zai/adapter.js";
 import { PROVIDER_IDS } from "./providers/types.js";
+import { SHARED_PROVIDER_FLAG_IDS, SHARED_PROVIDER_IDS } from "./providers/catalog.js";
 import { executeWithFallback } from "./lib/provider-fallback.js";
 import { visionOperationToCapability } from "./capabilities/vision.js";
 import { handleInitWithHelp, createInquirerPrompts, createDefaultConfigStore, } from "./commands/init.js";
@@ -64,7 +68,7 @@ Usage: scoutline <command> [args] [options]
 
 Commands:
   vision   Image and video analysis (Z.AI; MiniMax for interpret-image)
-  search   Real-time web search (shared: all 12 Providers; --topic
+  search   Real-time web search (shared: all ${SHARED_PROVIDER_IDS.length} Providers; --topic
            honored by every Provider)
   read     Fetch and parse web pages (Provider Capability; Z.AI, Tavily,
            Exa, Firecrawl, Parallel, Jina, You.com, Linkup, and Spider.cloud supply it)  crawl    Crawl a website from a starting URL (Provider Capability;
@@ -100,12 +104,16 @@ Commands:
            DOI, PMID, arXiv ids; keyless scholarly suppliers:
            openalex, arxiv, crossref, pubmed, europepmc)
   code     Execute TypeScript tool chains (Code Mode, Z.AI)
+  investigate Local investigation pipeline: plan sub-queries, fan out
+           search, read top sources, extract passages into an
+           EvidencePack (search+reader supplier union; the pack is data,
+           text modes fall back to JSON)
   init     Interactive onboarding wizard (writes ~/.scoutline/config.json)
   config   Manage ~/.scoutline/config.json keys (get / set / unset,
            credential-free)
 
 Provider selection (precedence: --provider, then SCOUTLINE_PROVIDER, then zai):
-  --provider <zai|minimax|tavily|exa|brave|firecrawl|parallel|perplexity|jina|you|linkup|spider>   Select the active Provider for shared capabilities (science suppliers pin only within "scoutline science ...")  SCOUTLINE_PROVIDER=<id>    Fallback when --provider is not passed
+  --provider <${SHARED_PROVIDER_FLAG_IDS}>   Select the active Provider for shared capabilities (science suppliers pin only within "scoutline science ...")  SCOUTLINE_PROVIDER=<id>    Fallback when --provider is not passed
 
 Shared capabilities accept --provider. The 'repo', 'read', 'crawl', 'map',
 and 'research' commands participate in Provider selection: Z.AI
@@ -115,8 +123,10 @@ advertises and supplies search, reader, and research; Parallel AI
 advertises search, research, and reader; Perplexity advertises search
 and research; Jina AI advertises search, reader, and research (keyless
 supported); You.com advertises search, reader, and research; Linkup advertises search, reader, and research; Spider.cloud
-advertises search, reader, crawl, and map; MiniMax advertises and supplies none of those
-Provider-only Capabilities.
+advertises search, reader, crawl, and map; Bocha AI advertises and
+supplies search; SearchApi advertises and supplies search; Kagi
+advertises and supplies search; MiniMax 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
@@ -125,6 +135,16 @@ 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.
 
+Merged-search ranking: fan-out and --merge results rank by reciprocal
+rank fusion (SCOUTLINE_FUSION=<rrf|occurrence>; default rrf; also the
+config \`fusion\` key, env wins). \`occurrence\` restores the legacy
+ordering byte-for-byte. See \`scoutline search --help\`.
+
+Flag strictness: unknown command flags are silently ignored by default
+(a typo like --fusio runs as if the flag were absent). Set
+SCOUTLINE_STRICT_FLAGS=1 to reject unknown flags on every command with
+a VALIDATION_ERROR naming the offender.
+
 Global Options:
   --output-format <data|json|pretty|compact|markdown|refs|tty>  Output mode (default: data)
   -O <mode>                                                     Alias for --output-format
@@ -153,6 +173,7 @@ Help:
   scoutline archive --help
   scoutline watch --help
   scoutline science --help
+  scoutline investigate --help
   scoutline init --help
 `.trim();
 function parseArgs(args) {
@@ -165,6 +186,16 @@ function parseArgs(args) {
             break;
         if (arg.startsWith("--")) {
             const key = arg.slice(2);
+            // TWO-SPELLING CONTRACT (#242): this branch maps `--no-X` to BOTH
+            // `flags.X = false` AND `flags["no-X"] = true`. A feature that
+            // must reject a flag therefore has to reject BOTH spellings — a
+            // handler checking only `flags.X` silently accepts `--no-X`, and
+            // one checking only `flags["no-X"]` misses the plain form. Use
+            // `rejectFlagPair(flags, name, makeError)` (below) for every
+            // flag-forbidden surface; the fusion rejection is the reference
+            // retrofit. (A structural fix — making `--no-X` set a single
+            // `flags.noX` key — would break every existing `--no-*`
+            // consumer.)
             if (key.startsWith("no-")) {
                 flags[key.slice(3)] = false;
                 flags[key] = true;
@@ -200,6 +231,20 @@ function parseArgs(args) {
     }
     return { flags, positional };
 }
+/**
+ * Guard for flag-forbidden features (#242): parseArgs maps `--no-X` to
+ * BOTH `flags.X = false` AND `flags["no-X"] = true`, so a feature that
+ * must reject a flag has to reject both spellings — checking one
+ * silently accepts the other (the footgun the fusion lane hit when its
+ * `--fusion` rejection had to know to test both). Throws the CALLER's
+ * error (built lazily, so the no-reject path allocates nothing) when
+ * either spelling of `--<name>` / `--no-<name>` is present.
+ */
+export function rejectFlagPair(flags, name, makeError) {
+    if (flags[name] !== undefined || flags[`no-${name}`] !== undefined) {
+        throw makeError();
+    }
+}
 /**
  * Collect every occurrence of a long `--<name>` flag in argv order,
  * mirroring parseArgs' value-consumption rule (the next argument is the
@@ -226,6 +271,290 @@ function collectLongFlagValues(args, name) {
     return values;
 }
 // ---------------------------------------------------------------------------
+// Strict flag mode (#241). Outside `batch` (and `vision batch` /
+// `history clear`, which carry their own gates) unknown CLI flags are
+// silently ignored — `search "q" --fusio rrf` runs as if the flag were
+// absent and parseArgs swallows the value into flag state. Global
+// strictness would break users passing redundant flags, so rejection is
+// OPT-IN: SCOUTLINE_STRICT_FLAGS set to any non-empty value (the
+// SCOUTLINE_NO_FALLBACK idiom) makes the dispatcher reject every flag
+// token the command's allowlist does not name, with the batch-style
+// error naming the offender.
+//
+// Semantics of the scan (deliberate rulings):
+//   - Exact spellings: `--no-journal` is accepted only as the literal
+//     `no-journal` row; it does NOT license a bare `--journal`. The
+//     parseArgs `--no-X` double-map never participates — the scan reads
+//     raw argv tokens, not parsed flag state.
+//   - Short flags are checked too (`-h` everywhere; fetch's `-A/-X/-H`).
+//     A multi-dash-letter token like `-ab` (which parseArgs would treat
+//     as positional) rejects under strict mode — strict means strict.
+//   - Global flags (`--provider`, `--output-format`, `--save*`, ...) are
+//     stripped by extractGlobalOptions BEFORE this gate, so they are not
+//     listed; a few commands (cache/usage) keep `provider` rows anyway
+//     for direct in-process callers whose argv was never extracted.
+//   - Flags a command's handler REJECTS with a specific error (e.g.
+//     search's `--fusion`, map's `--max-chars`) are absent from the set
+//     on purpose: under strict mode the generic rejection fires first;
+//     under the lenient default the handler's specific error still does.
+//   - When you add a flag to a command, add its spelling here — a miss
+//     only bites strict-mode users, but it bites them loudly.
+// ---------------------------------------------------------------------------
+/**
+ * Per-command accepted flag spellings for SCOUTLINE_STRICT_FLAGS mode
+ * (#241). Keys are post-dash spellings (`no-journal`, not
+ * `--no-journal`); sets are the UNION across a command's subcommands.
+ * Exported for the strict-mode tests and the DISPATCHED_COMMANDS
+ * coverage pin.
+ */
+export const STRICT_FLAG_ALLOWLIST = {
+    vision: new Set([
+        "help",
+        "h",
+        "context",
+        "focus",
+        "language",
+        "output",
+        "type",
+        // `vision batch` wrapper (the VISION_BATCH_FLAGS surface)
+        "out",
+        "prompt",
+        "concurrency",
+        "dry-run",
+    ]),
+    search: new Set([
+        "help",
+        "h",
+        "count",
+        "domain",
+        "fields",
+        "recency",
+        "topic",
+        "type",
+        "location",
+        "content-size",
+        "merge",
+        "max-summary",
+        "no-cache",
+        "max-chars",
+        "context",
+        "context-stdin",
+        "no-journal",
+    ]),
+    read: new Set([
+        "help",
+        "h",
+        "extract",
+        "format",
+        "full-envelope",
+        "keep-img-data-url",
+        "no-cache",
+        "no-gfm",
+        "no-images",
+        "timeout",
+        "with-images-summary",
+        "with-links",
+        "max-chars",
+        "no-journal",
+    ]),
+    crawl: new Set([
+        "help",
+        "h",
+        "breadth",
+        "content-size",
+        "depth",
+        "exclude-paths",
+        "format",
+        "instructions",
+        "limit",
+        "no-cache",
+        "select-paths",
+        "timeout",
+        "max-chars",
+    ]),
+    map: new Set([
+        "help",
+        "h",
+        "breadth",
+        "depth",
+        "exclude-paths",
+        "instructions",
+        "limit",
+        "no-cache",
+        "select-paths",
+    ]),
+    research: new Set([
+        "help",
+        "h",
+        "citation-format",
+        "context",
+        "context-mode",
+        "context-stdin",
+        "domain",
+        "model",
+        "no-cache",
+        "output-length",
+        "timeout",
+        "max-chars",
+        "no-journal",
+    ]),
+    repo: new Set([
+        "help",
+        "h",
+        "depth",
+        "focus",
+        "lang",
+        "language",
+        "max-chars",
+        "no-cache",
+        "no-focus",
+        "path",
+    ]),
+    batch: new Set(["help", "h", "concurrency", "fail-fast", "dry-run"]),
+    tools: new Set(["help", "h", "filter", "full", "ts", "typescript", "vision", "no-vision"]),
+    tool: new Set(["help", "h", "vision", "no-vision"]),
+    call: new Set(["help", "h", "dry-run", "file", "json", "stdin", "vision", "no-vision"]),
+    doctor: new Set(["help", "h", "available", "health", "no-tools"]),
+    quota: new Set(["help", "h", "all-providers"]),
+    code: new Set(["help", "h", "logs", "timeout"]),
+    cache: new Set(["help", "h", "capability", "older-than", "provider"]),
+    usage: new Set(["help", "h", "days", "provider"]),
+    history: new Set([
+        "help",
+        "h",
+        "all",
+        "as-of",
+        "capability",
+        "command",
+        "kind",
+        "limit",
+        "repeats",
+        "since",
+        "tags",
+        // `history note` consumes --url/--title pairs through its own
+        // raw-argv scan (repeatable rows, not parseArgs flag state) — the
+        // final-review false-reject probe.
+        "url",
+        "title",
+    ]),
+    init: new Set(["help", "h", "unregister"]),
+    config: new Set(["help", "h"]),
+    fetch: new Set([
+        "help",
+        "h",
+        "md5",
+        "sha256",
+        "raw",
+        "out",
+        "ua",
+        "user-agent",
+        "A",
+        "method",
+        "X",
+        "data",
+        "header",
+        "H",
+        "pdf",
+        "pdf-repair",
+        "timeout",
+    ]),
+    archive: new Set(["help", "h", "at", "from", "limit", "raw", "since", "status", "timeout", "to"]),
+    watch: new Set(["help", "h", "all", "format", "keep", "name", "purge", "timeout"]),
+    science: new Set([
+        "help",
+        "h",
+        "author",
+        "year",
+        "venue",
+        "type",
+        "provider",
+        "no-cache",
+        "max-chars",
+        "no-journal",
+    ]),
+    // investigate-pipeline T6: the documented control surface only
+    // (PRD AC-1). The rejected trio (depth/arms/budget-tokens) and
+    // --context-stdin are deliberately ABSENT — under strict flags they
+    // reject here, and the lenient default rejects them inside
+    // handleInvestigate (the rejection IS the feature).
+    investigate: new Set([
+        "help",
+        "h",
+        "provider",
+        "context",
+        "sources",
+        "max-chars",
+        "no-cache",
+        "no-journal",
+        "synthesize",
+        // investigate-verify lane (DESIGN D5): claim-corroboration mode
+        // flag. Pair-rejected with --context below (verify owns planning).
+        "verify",
+    ]),
+};
+/**
+ * The strict-flag gate (#241): scan a command's argv (the tokens AFTER
+ * the command name — global options were already extracted) and return
+ * the first flag token the command's allowlist does not name, or
+ * `undefined` when every token is accepted. Pure; throws never; the
+ * caller owns the error envelope. Commands without an allowlist row
+ * (unknown commands — the dispatcher's own `Unknown command` path) scan
+ * nothing.
+ */
+export function findUnknownStrictFlag(command, args) {
+    const allowed = STRICT_FLAG_ALLOWLIST[command];
+    if (allowed === undefined)
+        return undefined;
+    for (const arg of args) {
+        if (typeof arg !== "string" || !arg.startsWith("-") || arg.length < 2)
+            continue;
+        const key = arg.startsWith("--") ? arg.slice(2) : arg.slice(1);
+        if (key.length === 0)
+            continue; // a bare `--` token: never a flag name
+        if (!allowed.has(key))
+            return arg;
+    }
+    return undefined;
+}
+/**
+ * One early resolution pass over the known env doors (#244), so a bad
+ * value fails identically on EVERY command — previously
+ * SCOUTLINE_FUSION=bogus failed `quota` (the credentialed path
+ * resolves the door unconditionally) but silently succeeded on
+ * early-return commands (`config get` never read it).
+ *
+ *   - SCOUTLINE_FUSION — strict enum via {@link resolveFusionMode}
+ *     (config passed as undefined: this pass validates the ENV door
+ *     only; the file value arrives at the later resolution already
+ *     leniently parsed). Empty string is unset.
+ *   - SCOUTLINE_PROVIDER — a single shared Provider id via
+ *     {@link parseProviderId}, the exact validation the shared-capability
+ *     paths already run — except on `science`, whose env-door grammar
+ *     is the science supplier ids + "all" and is validated inside
+ *     handleScience against the D5 arm order. The `--provider` FLAG is
+ *     out of scope: it is extracted globally and still surfaces its
+ *     per-command errors where it is consumed.
+ *   - SCOUTLINE_NO_FALLBACK — boolean kill-switch: any non-empty value
+ *     disables fallback, so there is nothing to validate (listed here
+ *     because the door set is the contract, not just the checks).
+ *
+ * Pure; throws ValidationError on a bad door. `main` runs this
+ * pre-dispatch for every command (help/version bare short-circuits have
+ * already returned) and owns the error envelope.
+ */
+export function validateEnvDoors(env, command, explicitProvider) {
+    resolveFusionMode(env, undefined);
+    // PR #253 round 1: a present --provider flag (any value — id, comma
+    // list, or "all") wins the precedence chain, so SCOUTLINE_PROVIDER is
+    // a dead value on a pinned run and must not fail it. The flag's own
+    // value is validated downstream, where the consuming command reads it.
+    if (command !== "science" &&
+        explicitProvider === undefined &&
+        env.SCOUTLINE_PROVIDER !== undefined) {
+        parseProviderId(env.SCOUTLINE_PROVIDER);
+    }
+}
+// ---------------------------------------------------------------------------
 // Save-artifacts flag surface (batch ticket T3). `--save [<path>]`,
 // `--save-format <json|markdown>`, and `--save-force` are global options:
 // extracted for every command, removed from the rest stream, and consumed
@@ -252,6 +581,7 @@ const SAVE_CAPABLE_COMMANDS = new Set([
     "research",
     "repo",
     "vision",
+    "investigate",
 ]);
 /**
  * ADR-0007 D5 — every command the dispatcher routes (below): the
@@ -286,6 +616,7 @@ export const DISPATCHED_COMMANDS = new Set([
     "archive",
     "watch",
     "science",
+    "investigate",
 ]);
 /**
  * ADR-0007 D5 — commands WITHOUT an Output Budget ladder. They reject
@@ -330,6 +661,11 @@ export const ACCEPT_NO_JOURNAL_COMMANDS = new Set([
     // Science verticals (T7): the science noun journals (skeleton entries,
     // PRD AC-5c), so its --no-journal per-call escape must exist too.
     "science",
+    // investigate-pipeline T6 (PRD AC-10): the run journals its
+    // UNDERLYING search/read ops exactly as running them standalone
+    // would (umbrella capability "search" — see the journalWiring map),
+    // so its --no-journal per-call escape exists on the same seam.
+    "investigate",
 ]);
 /**
  * Review N10 (fix-round F-6) — the dispatch surface, extracted from
@@ -716,7 +1052,19 @@ async function handleVision(args, outputMode, deps) {
                 // 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 } : {}),
+                // glm-ocr lane (ADR-0014 D7): extract-text on zai counts
+                // usage-ledger attempts at the ADAPTER (the OCR cache is
+                // adapter-internal; an 1113+fallback run is two attempts
+                // inside one executor invoke; a cache hit is zero). The
+                // adapter's seam receives the sink through the zai
+                // descriptor's layoutParsingConsume dep (threaded at
+                // registry construction below); the executor emission is
+                // suppressed here so attempts are counted exactly once.
+                ...((deps.consume !== undefined &&
+                    !(descriptor.zaiOcrLedgerSeam === true &&
+                        operation === "extract-text"))
+                    ? { consume: deps.consume }
+                    : {}),
                 ...(deps.consume !== undefined ? { provider: descriptor.id } : {}),
                 ...(deps.now !== undefined ? { now: deps.now } : {}),
             };
@@ -871,6 +1219,14 @@ async function handleSearch(args, outputMode, deps) {
     if (typeof flags["context-stdin"] === "string") {
         throw new ValidationError("--context-stdin does not take a value.", 'Pipe the context on standard input: cat notes.md | scoutline search "<query>" --context-stdin.');
     }
+    // Fusion seed-24 AC-1 pin: search takes NO --fusion flag — the
+    // algorithm is a standing setting, not a per-query option — so a
+    // query flag could never exist. rejectFlagPair (#242) guards BOTH
+    // spellings (parseArgs maps `--no-fusion` to flags.fusion=false AND
+    // flags["no-fusion"]=true); rejection runs BEFORE the help-gate for
+    // the same reason as `--context` above (parseArgs swallows the value
+    // into flag state, and help would exit 0).
+    rejectFlagPair(flags, "fusion", () => new ValidationError("search has no --fusion flag; the ranking algorithm is a standing setting, not a per-query option.", "Use `scoutline config set fusion <rrf|occurrence>` or the SCOUTLINE_FUSION environment variable."));
     if (flags.help || flags.h || positional.length === 0) {
         deps.invocation.writeStdout(SEARCH_HELP);
         return 0;
@@ -1227,6 +1583,9 @@ async function handleSearch(args, outputMode, deps) {
                 env: deps.env,
                 query: dispatchQuery,
                 searchOptions,
+                // Seed-24 T3: the resolved ranking mode (env > config >
+                // "rrf") — the executor's merge names it explicitly.
+                fusionMode: deps.fusionMode ?? "rrf",
                 dependencies: {
                     cache: deps.searchCache,
                     sleep: deps.searchSleep,
@@ -1268,6 +1627,10 @@ async function handleSearch(args, outputMode, deps) {
                 cache: deps.searchCache,
                 sleep: deps.searchSleep,
                 random: deps.searchRandom,
+                // Seed-24 T3: the resolved ranking mode (env > config >
+                // "rrf") reaches the single-provider --merge seam too, so
+                // one merge implementation serves both paths.
+                fusionMode: deps.fusionMode ?? "rrf",
                 // PB-T2 parity with the fan-out path above (usage-ledger
                 // DESIGN D7): thread the configured consumption sink +
                 // clock so every billable sub-query on the single-pin path
@@ -3224,6 +3587,273 @@ async function handleHistoryExport(args, outputMode, deps) {
         ...(since !== undefined ? { since } : {}),
     }), outputMode, now, deps.secrets);
 }
+// ---------------------------------------------------------------------------
+// investigate-pipeline T6 (ADR-0013): the CLI wiring for the local
+// investigation pipeline. Mirrors handleSearch's ORDER — valueless-flag
+// guards BEFORE the help-gate, count-class validation BEFORE provider
+// resolution — and hands the parsed controls to commands/investigate.ts
+// (T4/T5), which owns the plan → fan-out → merge → read → pack
+// orchestration. The command is NOT routed through executeWithFallback:
+// it owns its provider grid through resolveFanoutPlan tiers (D3).
+// ---------------------------------------------------------------------------
+/**
+ * Strict positive-integer parse for `--sources` (the parseAndValidateCount
+ * class — not the lax parseInt idiom). Parse-level, before the help-gate
+ * is bypassed and before provider resolution, so a bad value is
+ * VALIDATION_ERROR regardless of credentials or provider state.
+ */
+export function parseAndValidateSources(raw) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    if (raw === true) {
+        throw new ValidationError("--sources requires a value.", "Use a positive integer (e.g. --sources 5).");
+    }
+    const str = typeof raw === "string" ? raw : String(raw);
+    if (!/^\d+$/.test(str)) {
+        throw new ValidationError(`Invalid --sources value "${str}": must be a positive integer`, "Use a positive integer (e.g. --sources 5).");
+    }
+    const parsed = Number(str);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new ValidationError(`Invalid --sources value "${str}": must be a positive safe integer`, "Use a positive integer (e.g. --sources 5).");
+    }
+    return parsed;
+}
+async function handleInvestigate(args, outputMode, deps) {
+    const { flags, positional } = parseArgs(args);
+    // Valueless --context guard BEFORE the help-gate (the handleSearch
+    // D1 placement pin): parseArgs records `true` for a valueless flag,
+    // so without this check `investigate --context` would short-circuit
+    // to HELP + exit 0 with the malformed flag silently swallowed.
+    if (flags.context === true) {
+        throw new ValidationError("--context requires a value.", "Pass a file path: --context <path>.");
+    }
+    // PRD AC-1 pins the accepted controls exactly; --context-stdin is NOT
+    // investigate's (search-only spelling — the question's pipes and
+    // --context cover the sub-query sources). Rejected explicitly, never
+    // accepted-and-dropped; before the help-gate like every other
+    // valueless/malformed-flag guard here.
+    if (flags["context-stdin"] !== undefined) {
+        throw new ValidationError("investigate has no --context-stdin flag.", "Pipe sub-queries with | in the question, or pass --context <path> (see `scoutline investigate --help`).");
+    }
+    // investigate-verify lane (DESIGN D5, PRD AC-1): --verify owns
+    // planning — the claims ARE the grid — so a --context file is a
+    // mode conflict. Both spellings of --context carry; the valueless
+    // --context guard above already fired for the true case.
+    if (flags.verify !== undefined && flags.context !== undefined) {
+        throw new ValidationError("--verify and --context cannot be combined: --verify splits the statement into claims (verify owns planning).", "Drop --context, or run without --verify to plan from the notes file.");
+    }
+    // Valueless/malformed --verify guards (the --synthesize pattern):
+    // parseArgs would swallow a following token as the value.
+    for (const token of args) {
+        if (typeof token === "string" && token.startsWith("--verify=")) {
+            throw new ValidationError(`Invalid flag "${token}": the --flag=value form is not supported; --verify takes no value.`, "Pass the bare --verify to enable claim-corroboration mode, or omit it.");
+        }
+    }
+    if (flags.verify !== undefined && flags.verify !== true) {
+        throw new ValidationError("--verify is a boolean flag and takes no value", "Pass the bare --verify to enable claim-corroboration mode, or omit it.");
+    }
+    const verify = flags.verify === true;
+    // PRD AC-1 / ADR-0013 rejected extensions: --depth, --arms, and
+    // --budget-tokens DO NOT EXIST (the parser rejecting them IS the
+    // feature — no accept-and-drop). rejectFlagPair guards BOTH
+    // spellings (#242); before the help-gate for the same reason as
+    // --context above.
+    rejectFlagPair(flags, "depth", () => new ValidationError("investigate has no --depth flag; planning is deterministic (pipes > --context > template).", "Structure the question with | sub-queries or --context <path> instead."));
+    rejectFlagPair(flags, "arms", () => new ValidationError("investigate has no --arms flag; the arm set IS the provider pin.", "Use --provider <tavily,exa|all> to fan out, or a single --provider id for one arm."));
+    rejectFlagPair(flags, "budget-tokens", () => new ValidationError("investigate has no --budget-tokens flag; --max-chars is the budget.", "Use --max-chars <n> (characters, not tokens)."));
+    // T7 (PRD AC-7): --synthesize is VALUELESS. parseArgs assigns the
+    // next non-dash token as a flag value, so `--synthesize foo` would
+    // swallow the value; the =-form parses as a garbage key and is
+    // silently dropped (#172 review F6). Both reject here, before the
+    // help-gate, like every other malformed-flag guard in this handler.
+    for (const token of args) {
+        if (typeof token === "string" && token.startsWith("--synthesize=")) {
+            throw new ValidationError(`Invalid flag "${token}": the --flag=value form is not supported; --synthesize takes no value.`, "Pass the bare --synthesize to enable it, or omit it.");
+        }
+    }
+    if (flags.synthesize !== undefined && flags.synthesize !== true) {
+        throw new ValidationError("--synthesize is a boolean flag and takes no value", "Pass the bare --synthesize to enable it, or omit it.");
+    }
+    const synthesize = flags.synthesize === true;
+    if (flags.help || flags.h || positional.length === 0) {
+        deps.invocation.writeStdout(INVESTIGATE_HELP);
+        return 0;
+    }
+    // Z.AI-only (PRD AC-7, the Code Mode precedent): the escape hatch
+    // is Z.AI chat regardless of the provider pin. The handler is the
+    // seam where the RAW pin is visible — the command cannot see it —
+    // so the notice fires here, before any billable work.
+    if (synthesize && deps.provider !== undefined && deps.provider.trim().length > 0) {
+        const pinned = deps.provider.trim().toLowerCase();
+        if (pinned !== "zai") {
+            deps.invocation.writeStderr(`investigate: --synthesize is Z.AI-only; ignoring the --provider ${pinned} pin for the brief (the pack still uses it).`);
+        }
+    }
+    // The synthesis dep (T7): a Z.AI chat completion through the
+    // in-repo /chat/completions surface. Built HERE, at the handler
+    // seam, exactly like every other capability — the command holds no
+    // transport. `visionComplete` is the only chat-completions method
+    // on ZaiApiClient; the transport is fetch-per-call (no client to
+    // close), and nothing is constructed when the flag is absent.
+    const synthesizeDep = !synthesize
+        ? undefined
+        : deps.synthesize ??
+            (async (prompt) => {
+                const client = new ZaiApiClient(undefined, deps.env);
+                const response = await client.visionComplete([
+                    {
+                        role: "system",
+                        content: "You are given an evidence pack assembled from web sources: a question, " +
+                            "its planned sub-queries, and verbatim passage quotes extracted from the " +
+                            "read sources. Write a short, direct brief answering the question using " +
+                            "ONLY the quoted evidence. Do not invent facts, do not add citations that " +
+                            "are not in the quotes, and say plainly when the evidence is insufficient.",
+                    },
+                    {
+                        role: "user",
+                        // Deterministic serialization: fixed key order, compact JSON.
+                        content: JSON.stringify({
+                            question: prompt.question,
+                            subQueries: [...prompt.subQueries],
+                            quotes: [...prompt.quotes],
+                        }),
+                    },
+                ]);
+                const content = response.choices?.[0]?.message?.content;
+                if (typeof content !== "string") {
+                    throw new ApiError("synthesis returned no brief text", 502);
+                }
+                return content;
+            });
+    // Count-class validation BEFORE provider resolution (Fixup D order):
+    // a bad --sources is VALIDATION_ERROR even with no credentials, and
+    // --max-chars rides the strict parseMaxCharsFlag (parseBriefMaxChars
+    // class). Both are re-validated inside the command's trust boundary.
+    const sources = parseAndValidateSources(flags.sources);
+    const maxChars = parseMaxCharsFlag(flags);
+    const question = positional.join(" ");
+    // Resolve the fan-out activation plan once HERE (pure — the same
+    // inputs handleSearch passes) so the journal hook can stamp per-arm
+    // serving cells BEFORE any arm runs; the command resolves its own
+    // plan identically from the same inputs (the tiers are deterministic,
+    // so the two resolutions agree by construction).
+    const fanoutPlan = resolveFanoutPlan({
+        explicitProviderRaw: deps.provider,
+        env: deps.env,
+        configFanout: deps.configFanout === true,
+        ...(deps.routing !== undefined ? { routing: deps.routing } : {}),
+        descriptors: deps.providerDescriptors,
+    });
+    // Save wiring (D7): the pack is a first-class saveable result. The
+    // provider routing mirrors the in-code vocabulary — fan-out records
+    // the arm list with no single effective; single records the resolved
+    // arm (the resolver's single-mode arm, not a quota-ranked pick — the
+    // command runs exactly that arm). Args carry the
+    // provider-influencing allow-list only.
+    const investigateSaveArgs = {
+        ...(deps.provider !== undefined ? { provider: deps.provider } : {}),
+        ...(sources !== undefined ? { sources } : {}),
+        ...(flags["no-cache"] === true ? { "no-cache": true } : {}),
+        ...(synthesize ? { synthesize: true } : {}),
+        ...(verify ? { verify: true } : {}),
+    };
+    const investigateProviderRouting = fanoutPlan.mode === "fanout"
+        ? {
+            mode: "fanout",
+            ...(deps.provider !== undefined ? { requested: deps.provider } : {}),
+            arms: fanoutPlan.arms.map((arm) => String(arm)),
+        }
+        : {
+            mode: "single",
+            ...(deps.provider !== undefined ? { requested: deps.provider } : {}),
+            effective: String(fanoutPlan.arms[0]),
+        };
+    const save = createSaveArtifactHook(deps, {
+        command: "investigate",
+        outputMode,
+        args: investigateSaveArgs,
+        provider: investigateProviderRouting,
+    });
+    // Journal wiring (PRD AC-10): investigate journals its UNDERLYING
+    // search/read ops exactly as running them standalone would. The
+    // umbrella capability is "search" — JournalableCapability is closed
+    // over {search, read, research, science} and lib/journal.ts is a
+    // read-only seam for this lane; a literal "investigate" entry fails
+    // asJournalEntry validation and would poison the whole log
+    // (fail-open drop + corruption notice). Entry shape: query = the
+    // question, skeleton rows = the pack sources (url/title) — fed via
+    // the resultRows thunk read after dispatch resolves. Fan-out runs
+    // stamp per-arm cells on the shared capture first (the arm-race fix),
+    // exactly like handleSearch.
+    let journalRows;
+    if (fanoutPlan.mode === "fanout" && deps.journal !== undefined) {
+        installFanoutArmCells(deps.journal.capture, fanoutPlan.arms);
+    }
+    const journal = deps.journal === undefined
+        ? undefined
+        : createJournalHook(deps, {
+            journal: deps.journal,
+            query: question,
+            resultRows: () => journalRows,
+            fanoutRouting: fanoutPlan.mode === "fanout"
+                ? {
+                    mode: "fanout",
+                    ...(deps.provider !== undefined ? { requested: deps.provider } : {}),
+                    arms: fanoutPlan.arms,
+                }
+                : undefined,
+        });
+    return invokeCommand(deps.invocation, async (context) => {
+        const result = await investigate(question, {
+            ...(deps.provider !== undefined ? { provider: deps.provider } : {}),
+            ...(typeof flags.context === "string" ? { contextFile: flags.context } : {}),
+            ...(sources !== undefined ? { sources } : {}),
+            ...(maxChars !== undefined ? { maxChars } : {}),
+            noCache: flags["no-cache"] === true,
+            noJournal: collectLongFlagValues(args, "no-journal").length > 0,
+            ...(synthesize ? { synthesize: true } : {}),
+            ...(verify ? { verify: true } : {}),
+        }, {
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            configFanout: deps.configFanout === true,
+            ...(deps.routing !== undefined ? { routing: deps.routing } : {}),
+            // One shared cache for the search arms AND the reads — the
+            // production defaultCache aliases every capability triple to
+            // the same root, and the command's warm-cacheHit accounting
+            // (search + reader partitions) assumes the one store.
+            cache: deps.searchCache,
+            sleep: deps.searchSleep,
+            random: deps.searchRandom,
+            ...(deps.consume !== undefined ? { consume: deps.consume } : {}),
+            ...(deps.now !== undefined ? { now: deps.now } : {}),
+            fusionMode: deps.fusionMode ?? "rrf",
+            ...(deps.now !== undefined ? { nowWall: () => new Date(deps.now()) } : {}),
+            loadContextText: async (filePath) => (await readContextSource({ file: filePath }, {
+                readFile: (f) => fs.readFile(f),
+                readStdin: () => {
+                    throw new Error("stdin context is not investigate's flag");
+                },
+            })).text,
+            readerCapabilityFor: (descriptor) => descriptor.create({ env: deps.env }).reader,
+            ...(deps.secrets !== undefined ? { secrets: deps.secrets } : {}),
+            ...(synthesizeDep !== undefined ? { synthesize: synthesizeDep } : {}),
+        }, context);
+        // Feed the journal skeleton from the pack BEFORE the result
+        // leaves the behavior — url/title identities of the read
+        // sources, the same row shape search journals.
+        if (result.kind === "data") {
+            const pack = result.data;
+            if (Array.isArray(pack.sources)) {
+                journalRows = pack.sources.map((source) => ({
+                    url: typeof source.url === "string" ? source.url : undefined,
+                    title: typeof source.title === "string" ? source.title : undefined,
+                }));
+            }
+        }
+        return result;
+    }, outputMode, deps.now, deps.secrets, save, journal);
+}
 export { handleFetch, fetchCommand, executeFetch, FETCH_HELP } from "./commands/fetch.js";
 export { handleArchive, archiveCdxCommand, archiveGetCommand, ARCHIVE_HELP, } from "./commands/archive.js";
 async function handleQuota(args, outputMode, deps) {
@@ -3786,7 +4416,34 @@ export async function main(args, dependencies) {
     const depsConfig = dependencies.config;
     const loadScoutlineConfig = dependencies.loadScoutlineConfig ??
         (depsConfig !== undefined ? async () => depsConfig : undefined);
+    // glm-ocr lane (ADR-0014 D7): in full production mode (no injected
+    // descriptor list), rebuild the zai entry with the shared consumption
+    // sink threaded into its layoutParsingConsume seam so the extract-text
+    // OCR arm counts ledger attempts at the adapter (cache hits = zero
+    // rows; 1113+fallback = two rows). The sink binding exists BELOW this
+    // point (main body order), so this is a lazy rebuild: the array holds
+    // a descriptor whose create() closes over a sink REFERENCE resolved
+    // at first vision dispatch. Tests injecting providerDescriptors keep
+    // full control (their descriptor carries their own seams).
     const providerDescriptors = dependencies.providerDescriptors ?? BUILT_IN_PROVIDER_DESCRIPTORS;
+    const productionZaiLedgerDescriptors = dependencies.providerDescriptors
+        ? providerDescriptors
+        : providerDescriptors.map((descriptor) => descriptor.id === "zai"
+            ? Object.assign(createZaiDescriptor({
+                notice: (line) => process.stderr.write(`${line}\n`),
+                layoutParsingConsume: {
+                    record: (event) => {
+                        if (zaiLedgerSink === undefined)
+                            return Promise.resolve();
+                        return zaiLedgerSink.record(event);
+                    },
+                },
+            }), 
+            // Marker: this descriptor's zai adapter owns extract-text
+            // ledger rows through its seam (checked in handleVision
+            // to suppress the executor emission exactly once).
+            { zaiOcrLedgerSeam: true })
+            : descriptor);
     // 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.
@@ -3891,6 +4548,39 @@ export async function main(args, dependencies) {
     }
     const command = rest[0] ?? "";
     const commandArgs = rest.slice(1);
+    // #244: validate the env doors ONCE, pre-dispatch, for ALL command
+    // RUNS — a typo'd env value used to fail only on the paths that
+    // happened to resolve it first (quota yes, config get no). Help
+    // invocations stay exempt (documentation, not a run — the same
+    // doctrine as the --max-chars/--no-journal gates and the existing
+    // "<cmd> --help succeeds with an invalid SCOUTLINE_PROVIDER" pins:
+    // rendering help must never require a valid environment). Runs before
+    // the strict-flags gate and every command-specific gate, and before
+    // any disk or network work (the agent-registration check below), so a
+    // doomed run costs nothing. Bare `--help`/`--version` already
+    // returned above.
+    if (!isCommandHelpInvocation(commandArgs)) {
+        try {
+            validateEnvDoors(env, command, provider);
+        }
+        catch (error) {
+            invocation.writeStderr(formatErrorOutput(error, outputMode, envSecrets));
+            return getErrorExitCode(error);
+        }
+    }
+    // #241: opt-in strict flag mode. Fires before every other pre-dispatch
+    // gate (and before the agent-registration disk check) so a doomed run
+    // costs nothing: with SCOUTLINE_STRICT_FLAGS set to any non-empty
+    // value, a flag token the command's allowlist does not name rejects
+    // with the batch-style error. The lenient default (unset/empty env)
+    // stays byte-identical — unknown flags are accepted and dropped.
+    if (typeof env.SCOUTLINE_STRICT_FLAGS === "string" && env.SCOUTLINE_STRICT_FLAGS.length > 0) {
+        const unknownFlag = findUnknownStrictFlag(command, commandArgs);
+        if (unknownFlag !== undefined) {
+            invocation.writeStderr(formatErrorOutput(new ValidationError(`unknown flag "${unknownFlag}" for command "${command}" (SCOUTLINE_STRICT_FLAGS is enabled)`, `Run "scoutline ${command} --help" for the accepted flags, or unset SCOUTLINE_STRICT_FLAGS to restore lenient flag handling.`), outputMode, envSecrets));
+            return 1;
+        }
+    }
     // Lazy agent-registration stamp check (agent registration D5/D6):
     // fires exactly once per CLI run, before command dispatch. Stamp-absent
     // runs are zero-cost no-ops; drift refreshes the registered tools. A
@@ -3979,6 +4669,9 @@ export async function main(args, dependencies) {
     // like the quota sink). The composite isolates each side — one
     // sink's failure becomes one redacted warning and never blocks or
     // fails the other.
+    // glm-ocr lane: late-bound sink reference for the rebuilt zai
+    // descriptor (assigned immediately after `consume` below).
+    let zaiLedgerSink;
     const consume = dependencies.consume ??
         // ADR-0006 §5: --isolated runs skip local state persistence
         // entirely — no usage-ledger writes, no quota-snapshot writes — so
@@ -3996,6 +4689,7 @@ export async function main(args, dependencies) {
                 filePath: resolveUsageLedgerPath(resolveConfigRootPure(env, { homedir: os.homedir() })),
             }))
             : undefined);
+    zaiLedgerSink = consume;
     // 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
@@ -4010,16 +4704,18 @@ export async function main(args, dependencies) {
     // 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, credRouting = undefined, credFanout = undefined) => ({
+    const buildHandlerDeps = (credEnv, credSecrets, credFallback, credRouting = undefined, credFanout = undefined, credFusion = undefined) => ({
         invocation,
+        synthesize: dependencies.synthesize,
         env: credEnv,
         secrets: credSecrets,
         now,
         provider,
-        providerDescriptors,
+        providerDescriptors: productionZaiLedgerDescriptors,
         fallbackEnabled: credFallback,
         routing: credRouting,
         configFanout: credFanout,
+        fusionMode: credFusion,
         searchCache,
         searchSleep,
         searchRandom,
@@ -4541,9 +5237,14 @@ export async function main(args, dependencies) {
     // Ticket 4. Read leniently: an absent or non-boolean field simply means
     // fan-out stays off.
     const configFanout = dependencies.configFanout ?? config.fanout === true;
+    // Fusion seed-24: resolve the effective ranking mode ONCE per
+    // invocation, injectable-wins exactly like configFanout above.
+    // Strict: a non-enum SCOUTLINE_FUSION throws here (exit 1) — typos
+    // never silently fall back to rrf.
+    const fusionMode = dependencies.fusionMode ?? resolveFusionMode(env, config);
     const handlerDeps = buildHandlerDeps(resolvedEnv, secrets, fallbackEnabled, 
     // #72: injectable-wins, mirroring configFanout above.
-    dependencies.routing ?? config.routing, configFanout);
+    dependencies.routing ?? config.routing, configFanout, fusionMode);
     // 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
@@ -4660,12 +5361,27 @@ export async function main(args, dependencies) {
         config.journal !== false
         ? {}
         : undefined;
+    // M1 (glm-ocr review): journal/save chains build from the ledger-
+    // rebuilt list so --save vision runs keep the adapter-owned
+    // extract-text seam (marker survives the capture spread).
     const journalingDescriptors = journalCapture === undefined
-        ? providerDescriptors
-        : captureServingDescriptors(providerDescriptors, journalCapture);
+        ? productionZaiLedgerDescriptors
+        : captureServingDescriptors(productionZaiLedgerDescriptors, journalCapture);
     const journalWiring = journalCapture === undefined
         ? undefined
-        : { capability: command, capture: journalCapture };
+        : {
+            // investigate-pipeline T6: the run journals its UNDERLYING
+            // search/read ops under the umbrella capability "search" —
+            // JournalableCapability is closed over
+            // {search,read,research,science} (lib/journal.ts is a
+            // read-only seam for this lane) and a literal "investigate"
+            // entry would fail asJournalEntry validation and poison the
+            // whole log (fail-open drop + corruption notice). The
+            // underlying ops ARE search/read; running them standalone
+            // journals exactly so (orchestrator ruling 2026-09-20).
+            capability: (command === "investigate" ? "search" : command),
+            capture: journalCapture,
+        };
     const saveWiring = saveRequest === undefined || isHelpInvocation
         ? undefined
         : buildSaveWiring(saveRequest, journalingDescriptors, journalCapture);
@@ -4770,6 +5486,13 @@ export async function main(args, dependencies) {
                 commandRecognized = true;
                 exitCode = await handleQuota(commandArgs, outputMode, handlerDepsWithSelection);
                 break;
+            case "investigate":
+                commandRecognized = true;
+                // PRD AC-9: --isolated is ACCEPTED (never rejected — investigate
+                // has no stateful dir; resumability is pure cache replay, and the
+                // isolated/<pid> cache segment is exactly the right namespace).
+                exitCode = await handleInvestigate(commandArgs, outputMode, handlerDepsWithSave);
+                break;
             case "code":
                 commandRecognized = true;
                 exitCode = await handleCode(commandArgs, outputMode, handlerDepsWithSelection);