scoutline 0.23.0 → 0.24.1

package/dist/index.js

@@ -17,9 +17,11 @@ import { CONFIG_HELP, configGetCommand, configSetCommand, configUnsetCommand, }
 import { usageCommand, USAGE_HELP, DEFAULT_USAGE_WINDOW_DAYS, MAX_USAGE_WINDOW_DAYS, } from "./commands/usage.js";
 import { historyCommand, historyClearCommand, historyRecallCommand, historyExportCommand, HISTORY_HELP, HISTORY_NOTE_HELP, HISTORY_RECALL_HELP, HISTORY_CLEAR_HELP, HISTORY_EXPORT_HELP, } from "./commands/history.js";
 import { handleFetch } from "./commands/fetch.js";
-import { handleArchive, parseArchiveArgs } from "./commands/archive.js";
+import { handleArchive, parseArchiveTokens } 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,8 @@ 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 { normalizeEqualsFormFlags } from "./lib/equals-form.js";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as fs from "node:fs/promises";
@@ -50,6 +53,7 @@ import { createUsageLedgerSink, readUsageLedger, resolveUsageLedgerPath, } from
 import { classifyCredentialState, formatEnvOnlyHint, isCommandHelpInvocation, isDryRunBatchInvocation, OBSERVATIONAL_COMMANDS, } from "./lib/trigger-detection.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";
@@ -101,6 +105,10 @@ 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)
@@ -166,6 +174,7 @@ Help:
   scoutline archive --help
   scoutline watch --help
   scoutline science --help
+  scoutline investigate --help
   scoutline init --help
 `.trim();
 function parseArgs(args) {
@@ -237,6 +246,8 @@ export function rejectFlagPair(flags, name, makeError) {
         throw makeError();
     }
 }
+// #263: re-exported for the parser-level tests.
+export { normalizeEqualsFormFlags };
 /**
  * Collect every occurrence of a long `--<name>` flag in argv order,
  * mirroring parseArgs' value-consumption rule (the next argument is the
@@ -464,6 +475,25 @@ export const STRICT_FLAG_ALLOWLIST = {
         "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
@@ -554,6 +584,7 @@ const SAVE_CAPABLE_COMMANDS = new Set([
     "research",
     "repo",
     "vision",
+    "investigate",
 ]);
 /**
  * ADR-0007 D5 — every command the dispatcher routes (below): the
@@ -588,6 +619,7 @@ export const DISPATCHED_COMMANDS = new Set([
     "archive",
     "watch",
     "science",
+    "investigate",
 ]);
 /**
  * ADR-0007 D5 — commands WITHOUT an Output Budget ladder. They reject
@@ -632,6 +664,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
@@ -1018,7 +1055,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 } : {}),
             };
@@ -3541,6 +3590,264 @@ 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 --verify guard: parseArgs would swallow a following
+    // token as the value. (The `--verify=` equals-form check is GONE:
+    // #263 normalizes `--verify=foo` to `--verify foo` upstream, and this
+    // existing boolean guard rejects it with the same error.)
+    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` (and the
+    // #263-normalized `--synthesize=foo`) rejects here, before the
+    // help-gate, like every other malformed-flag guard in this handler.
+    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) {
@@ -4103,7 +4410,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.
@@ -4116,12 +4450,20 @@ export async function main(args, dependencies) {
     // envelope in the output mode the argv requested (re-derived from the
     // raw argv via `bestEffortOutputMode` because the partially parsed
     // result never escapes the throw) and the error's exit code.
+    // #263: central `--flag=value` ≡ `--flag value` normalization. Runs
+    // before EVERY argv consumer below (extractGlobalOptions, the
+    // strict-flag gate, help/version checks, command handlers' parseArgs)
+    // so all token walks observe space-form tokens only. Pure and
+    // total-length-preserving plus at most the split tokens; the only
+    // behavior change is where a `--flag=value` used to be a garbage
+    // boolean key.
+    const normalizedArgs = normalizeEqualsFormFlags(args);
     let extracted;
     try {
-        extracted = extractGlobalOptions([...args]);
+        extracted = extractGlobalOptions(normalizedArgs);
     }
     catch (error) {
-        invocation.writeStderr(formatErrorOutput(error, bestEffortOutputMode(args, invocation), envSecrets));
+        invocation.writeStderr(formatErrorOutput(error, bestEffortOutputMode(normalizedArgs, invocation), envSecrets));
         return getErrorExitCode(error);
     }
     const { outputFormat, forcePretty, forceRaw, provider, noFallback, isolated, rest } = extracted;
@@ -4329,6 +4671,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
@@ -4346,6 +4691,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
@@ -4362,11 +4708,12 @@ export async function main(args, dependencies) {
     // env/secrets/fallbackEnabled depend on whether config has been loaded.
     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,
@@ -4598,7 +4945,7 @@ export async function main(args, dependencies) {
             // the human table was never the flag's contract.
             // Determine the subcommand through the parser (not positional
             // assumption): options may precede `get`/`cdx`.
-            const archiveSubcommand = parseArchiveArgs(commandArgs).subcommand;
+            const archiveSubcommand = parseArchiveTokens(commandArgs).subcommand;
             const archiveOutputMode = forceRaw && outputFormat === undefined && archiveSubcommand === "get"
                 ? "compact"
                 : outputMode;
@@ -5016,12 +5363,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);
@@ -5126,6 +5488,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);