scoutline 0.16.0 → 0.17.0

package/dist/index.js

@@ -13,23 +13,32 @@ import { doctor, buildDiagnosticsReport, DOCTOR_HELP } from "./commands/doctor.j
 import { quota, buildQuotaDashboard, QUOTA_HELP } from "./commands/quota.js";
 import { cacheStatsCommand, cacheClearCommand, cachePruneCommand, formatDoctorCacheSummary, CACHE_HELP, } from "./commands/cache.js";
 import { CONFIG_HELP, configGetCommand, configSetCommand, configUnsetCommand, } from "./commands/config.js";
+import { usageCommand, USAGE_HELP, DEFAULT_USAGE_WINDOW_DAYS, MAX_USAGE_WINDOW_DAYS, } from "./commands/usage.js";
 import { cacheStats, clearAllCaches, parsePruneDuration, pruneCaches } from "./lib/cache.js";
+import { parseBatchManifest } from "./lib/batch-manifest.js";
+import { assignBatchProviders } from "./lib/batch-assign.js";
+import { BATCH_MAX_CONCURRENCY, runBatch, } from "./lib/batch-runner.js";
 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 { ValidationError, UnsupportedCapabilityError, getErrorExitCode, } from "./lib/errors.js";
 import * as os from "node:os";
-import { invokeCommand } from "./command-invocation.js";
+import * as fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { invokeCommand, } from "./command-invocation.js";
 import { defaultResponseCache } from "./lib/cache.js";
+import { MAX_SUBQUERIES, parseContextText, readContextSource } from "./lib/context-file.js";
 import { configuredSecrets } from "./lib/redact.js";
 import { configFilePath, readConfig, resolveConfigRootPure, resolveEnvFromConfig, setConfigValue, unsetConfigValue, } 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 { 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 { BUILT_IN_PROVIDER_DESCRIPTORS } from "./providers/registry.js";
+import { PROVIDER_IDS } from "./providers/types.js";
 import { executeWithFallback } from "./lib/provider-fallback.js";
 import { visionOperationToCapability } from "./capabilities/vision.js";
 import { handleInitWithHelp, createInquirerPrompts, createDefaultConfigStore, } from "./commands/init.js";
@@ -56,11 +65,15 @@ Commands:
            MiniMax and Tavily return UNSUPPORTED_CAPABILITY)
   quota    Provider-aware plan usage (calls remaining, reset time; default
            reports every configured Provider)
+  batch    Run a manifest of capability operations across Providers
+           (distribution is the default; pin per op or globally to opt out)
   tools    List available MCP tools (Z.AI)
   tool     Show a tool schema (Z.AI)
   call     Call a tool directly (Z.AI)
   doctor   Provider-aware environment + connectivity checks
   cache    Inspect or clear the local cache (stats / clear)
+  usage    Report local call-usage history (usage.json ledger,
+           credential-free)
   code     Execute TypeScript tool chains (Code Mode, Z.AI)
   init     Interactive onboarding wizard (writes ~/.scoutline/config.json)
 
@@ -98,10 +111,12 @@ Help:
   scoutline map --help
   scoutline research --help
   scoutline repo --help
+  scoutline batch --help
   scoutline tools --help
   scoutline call --help
   scoutline code --help
   scoutline cache --help
+  scoutline usage --help
   scoutline init --help
 `.trim();
 function parseArgs(args) {
@@ -322,6 +337,15 @@ async function handleVision(args, outputMode, deps) {
     const command = positional[0] ?? "";
     const source = positional[1] ?? "";
     const prompt = positional[2];
+    // batch-runner Ticket 7 (DESIGN D10): `vision batch` is a WRAPPER over
+    // the shared manifest runner. The branch sits BEFORE
+    // `visionOperationForCommand` (which raises VALIDATION_ERROR for
+    // "batch") and before ANY provider resolution or `descriptor.create()`
+    // — per-op provider assignment happens inside the runner (D1, D4),
+    // never at this seam.
+    if (command === "batch") {
+        return vision.handleVisionBatch(positional.slice(1), flags, outputMode, deps, BATCH_HANDLERS);
+    }
     // Map the subcommand to its Vision operation. Unknown subcommands are
     // a parse-time VALIDATION_ERROR and are rejected before any Provider
     // resolution, support check, or media access.
@@ -531,6 +555,26 @@ export function parseAndValidateType(raw) {
 }
 async function handleSearch(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
+    // Local-context plan, Ticket 4 (DESIGN D1 placement pin): the
+    // `--context` value-shape check runs BEFORE the help-gate below —
+    // parseArgs records `true` for a valueless flag and leaves positional
+    // empty, so without this check `search --context` would short-circuit
+    // to HELP + exit 0 with the malformed flag silently swallowed.
+    // Mirrors the `validateModel` shape (`commands/research.ts`) and the
+    // identical pre-gate check in `handleResearch`. The post-gate enum
+    // validators below do NOT move.
+    if (flags.context === true) {
+        throw new ValidationError("--context requires a value.", "Pass a file path: --context <path>, or pipe the context with --context-stdin.");
+    }
+    // Local-context plan, Ticket 5 (DESIGN D1): `--context-stdin` accepts
+    // no value — parseArgs greedily consumes the next non-dash token as a
+    // flag's value, so `search --context-stdin "<q>"` yields a string flag
+    // value and an empty positional. A string value is a VALIDATION_ERROR
+    // (never a silent drop through a `=== true` identity test), placed
+    // BEFORE the help-gate for the same reason as `--context` above.
+    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.');
+    }
     if (flags.help || flags.h || positional.length === 0) {
         deps.invocation.writeStdout(SEARCH_HELP);
         return 0;
@@ -551,6 +595,29 @@ 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.");
     }
+    // Local-context plan, Ticket 5 (DESIGN D1): the two context-source
+    // spellings are mutually exclusive — a file path and a pipe cannot
+    // both be the source. Parse-level gate beside the Ticket 4 mutex
+    // below. `contextKind` resolves the active source for the D7 block
+    // (Ticket 5 extends it beyond the file source to `--context-stdin`).
+    const contextKind = typeof flags.context === "string"
+        ? { file: flags.context }
+        : flags["context-stdin"] === true
+            ? { stdin: true }
+            : undefined;
+    if (typeof flags.context === "string" && flags["context-stdin"] === true) {
+        throw new ValidationError("--context and --context-stdin are mutually exclusive.", "Pass one context source: --context <path> or --context-stdin, not both.");
+    }
+    // Local-context plan, Ticket 4 (DESIGN D7): an explicit `--merge`
+    // together with a context source is an ambiguous combination — the
+    // user's manual `|` sub-queries and the derived stream would fight
+    // over the same query string. Parse-level gate, same shape as the
+    // type/topic mutex above (before Provider resolution); Ticket 5
+    // extends it to the `--context-stdin` spelling (same feature, other
+    // source).
+    if (contextKind !== undefined && flags.merge === true) {
+        throw new ValidationError("--merge and --context are mutually exclusive.", "--context derives and joins sub-queries itself; pass one of the two, not both.");
+    }
     // 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
@@ -636,11 +703,99 @@ async function handleSearch(args, outputMode, deps) {
         if (fanoutPlan.suppress) {
             context.notice(fanoutPlan.suppress);
         }
+        // Local-context plan, Ticket 4 (DESIGN D7): read the context
+        // source ONCE here in the handler, derive the sub-query stream
+        // (D2.4), and build the dispatch query BEFORE either dispatch
+        // path — the executors split sub-queries from the raw query
+        // string themselves (`splitMergeSubQueries`), so only this
+        // handler-side join reaches both the single-pin path and the
+        // fan-out grid. The user's query is kept FIRST; every stream
+        // member is trim-then-escaped with pipe-only escaping so the
+        // join/split round-trip is lossless. Ticket 5 routes the
+        // `--context-stdin` spelling through the same block: stdin is
+        // read once via the injected io seam (`context.readStdin()`,
+        // drained by the Node adapter on first read), so the join and
+        // the D6 wrapper below are source-agnostic.
+        let dispatchQuery = query;
+        let contextInfo;
+        if (contextKind !== undefined) {
+            const content = await readContextSource(contextKind, {
+                readFile: (filePath) => fs.readFile(filePath),
+                readStdin: (maxBytes) => context.readStdin(maxBytes),
+            });
+            const parsed = parseContextText(content.text);
+            const derived = parsed.subQueries;
+            // Drop notice (D2.4/D7): the parser caps the stream at
+            // MAX_SUBQUERIES; the pre-cap count is recomputed here with the
+            // same qualification rules (headings within the 60-char bound,
+            // backslash-trimmed non-empty) purely for the notice — the
+            // capped stream itself is authoritative for the join.
+            const uncappedSet = new Set([
+                ...parsed.headings.filter((h) => h.length <= 60),
+                ...parsed.questions,
+            ]
+                .map((value) => value.replace(/\\+$/, ""))
+                .filter((value) => value.length > 0));
+            const uncapped = uncappedSet.size;
+            if (uncapped > MAX_SUBQUERIES) {
+                context.notice(`context: derived ${uncapped} sub-queries; dropped ${uncapped - derived.length} (cap ${MAX_SUBQUERIES})`);
+            }
+            if (derived.length === 0) {
+                // Zero-derivation fallback (D7): the original query runs
+                // alone, merge NOT engaged — a literal `|` in the user's
+                // query must not split. The context wrapper below still
+                // applies.
+                context.notice("context: derived 0 sub-queries; using original query");
+            }
+            else {
+                // Join site (D7): the user query gets the D2.4
+                // trailing-backslash trim here (derived members are already
+                // trimmed by the parser), then EVERY member is escaped
+                // pipe-only — no backslash doubling, `splitMergeSubQueries`
+                // never unescapes `\\`.
+                dispatchQuery = [query.replace(/\\+$/, ""), ...derived]
+                    .map((s) => s.replace(/\|/g, "\\|"))
+                    .join("|");
+                searchOptions.merge = true;
+                // Fan-out cost disclosure (D7): when the resolved plan is
+                // fan-out AND the joined stream holds more than one
+                // sub-query, the (arm × sub-query) grid is a cost
+                // multiplication the user must see. N counts the whole
+                // joined stream, user query included.
+                if (fanoutPlan.mode === "fanout") {
+                    const n = derived.length + 1;
+                    const m = fanoutPlan.arms.length;
+                    context.notice(`context: ${n} sub-queries × ${m} arms = ${n * m} billable searches`);
+                }
+            }
+            // D6 privacy boundary: counts, hashes, and the path only —
+            // never content. `subQueries` is the post-cap stream length.
+            contextInfo = {
+                source: content.source,
+                ...(content.path !== undefined ? { path: content.path } : {}),
+                sha256: content.sha256,
+                derived: {
+                    headings: parsed.headings.length,
+                    questions: parsed.questions.length,
+                    terms: parsed.terms.length,
+                    subQueries: derived.length,
+                },
+            };
+        }
+        // Flags-gated wrapper (D7): under `--context` (only then) the
+        // dispatch result's DATA payload is wrapped as
+        // `{context: {...}, results: [...]}`; text-mode presentations
+        // stay unwrapped (they are built inside dispatch from the bare
+        // results). Without the flag the result passes through
+        // byte-identically.
+        const applyContextWrapper = (result) => contextInfo === undefined || result.kind !== "data"
+            ? result
+            : { ...result, data: { context: contextInfo, results: result.data } };
         if (fanoutPlan.mode === "fanout") {
-            return executeFanoutPlan(fanoutPlan, {
+            return applyContextWrapper(await executeFanoutPlan(fanoutPlan, {
                 descriptors: deps.providerDescriptors,
                 env: deps.env,
-                query,
+                query: dispatchQuery,
                 searchOptions,
                 dependencies: {
                     cache: deps.searchCache,
@@ -654,7 +809,7 @@ async function handleSearch(args, outputMode, deps) {
                     ...(deps.now !== undefined ? { now: deps.now } : {}),
                 },
                 secrets: deps.secrets,
-            }, context);
+            }, context));
         }
         const outcome = await executeWithFallback({
             capabilityId: "search",
@@ -670,14 +825,20 @@ async function handleSearch(args, outputMode, deps) {
         }, async (descriptor) => {
             const adapter = descriptor.create({ env: deps.env });
             const capability = adapter.search;
-            return search(query, searchOptions, {
+            return search(dispatchQuery, searchOptions, {
                 capability,
                 cache: deps.searchCache,
                 sleep: deps.searchSleep,
                 random: deps.searchRandom,
+                // 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
+                // records through it.
+                ...(deps.consume !== undefined ? { consume: deps.consume } : {}),
+                ...(deps.now !== undefined ? { now: deps.now } : {}),
             }, context);
         });
-        return outcome.result;
+        return applyContextWrapper(outcome.result);
     }, outputMode, deps.now, deps.secrets);
 }
 async function handleRead(args, outputMode, deps) {
@@ -738,6 +899,10 @@ async function handleRead(args, outputMode, deps) {
         cache: deps.readerCache,
         sleep: deps.readerSleep,
         random: deps.readerRandom,
+        // PB-T2 (usage-ledger DESIGN D7): thread the configured consumption
+        // sink + clock so every billable reader-fetch attempt records.
+        ...(deps.consume !== undefined ? { consume: deps.consume } : {}),
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
     };
     // Provider-fallback Ticket 02: route the call through the shared
     // fallback executor. Capability + configured + adapter-handle
@@ -796,6 +961,10 @@ async function handleCrawl(args, outputMode, deps) {
         cache: deps.crawlCache,
         sleep: deps.crawlSleep,
         random: deps.crawlRandom,
+        // PB-T2 (usage-ledger DESIGN D7): thread the configured consumption
+        // sink + clock so every billable crawl-fetch attempt records.
+        ...(deps.consume !== undefined ? { consume: deps.consume } : {}),
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
     };
     // Provider-fallback Ticket 03: route the call through the shared
     // fallback executor. Capability + configured + adapter-handle
@@ -868,6 +1037,10 @@ async function handleMap(args, outputMode, deps) {
         cache: deps.mapCache,
         sleep: deps.mapSleep,
         random: deps.mapRandom,
+        // PB-T2 (usage-ledger DESIGN D7): thread the configured consumption
+        // sink + clock so every billable map-fetch attempt records.
+        ...(deps.consume !== undefined ? { consume: deps.consume } : {}),
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
     };
     // Provider-fallback Ticket 03: route the call through the shared
     // fallback executor. Map retries once per Provider today, so the
@@ -903,6 +1076,26 @@ async function handleMap(args, outputMode, deps) {
 }
 async function handleResearch(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
+    // Local-context plan, Ticket 2 (DESIGN D1 placement pin): the
+    // `--context` value-shape check runs BEFORE the help-gate below —
+    // parseArgs records `true` for a valueless flag and leaves positional
+    // empty, so without this check `research --context` would
+    // short-circuit to HELP + exit 0 with the malformed flag silently
+    // swallowed. Mirrors the `validateModel` shape (commands/research.ts).
+    // The post-gate enum validators below do NOT move.
+    if (flags.context === true) {
+        throw new ValidationError("--context requires a value.", "Pass a file path: --context <path>, or pipe the context with --context-stdin.");
+    }
+    // Local-context plan, Ticket 5 (DESIGN D1): `--context-stdin` accepts
+    // no value — parseArgs greedily consumes the next non-dash token as a
+    // flag's value, so `research --context-stdin "<q>"` yields a string
+    // flag value and an empty positional. A string value is a
+    // VALIDATION_ERROR (never a silent drop through a `=== true` identity
+    // test), placed BEFORE the help-gate for the same reason as
+    // `--context` above.
+    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 research "<query>" --context-stdin.');
+    }
     if (flags.help || flags.h || positional.length === 0) {
         deps.invocation.writeStdout(RESEARCH_HELP);
         return 0;
@@ -914,6 +1107,17 @@ async function handleResearch(args, outputMode, deps) {
     const model = validateResearchEnum(flags.model, ["mini", "pro", "auto"], "--model");
     const outputLength = validateResearchEnum(flags["output-length"], ["short", "standard", "long"], "--output-length");
     const citationFormat = validateResearchEnum(flags["citation-format"], ["numbered", "mla", "apa", "chicago"], "--citation-format");
+    // Local-context plan, Ticket 5 (DESIGN D1): the two context-source
+    // spellings are mutually exclusive — a file path and a pipe cannot
+    // both be the source. Parse-level gate before Provider resolution,
+    // same region as the enum validators.
+    if (typeof flags.context === "string" && flags["context-stdin"] === true) {
+        throw new ValidationError("--context and --context-stdin are mutually exclusive.", "Pass one context source: --context <path> or --context-stdin, not both.");
+    }
+    // Local-context plan, Ticket 2 (DESIGN D1): research-only mode enum,
+    // defaulting to `organize` at the read site below. Same parse-level
+    // gate shape as the research enums above.
+    const contextMode = validateResearchEnum(flags["context-mode"], ["organize", "bias", "both"], "--context-mode");
     // Resolve the effective Provider (DESIGN.md §6, FR-001–FR-005):
     // explicit --provider > SCOUTLINE_PROVIDER > quota-ranked pick.
     // (PB-T4.)
@@ -930,6 +1134,11 @@ async function handleResearch(args, outputMode, deps) {
         cache: deps.researchCache,
         sleep: deps.researchSleep,
         random: deps.researchRandom,
+        // PB-T2 (usage-ledger DESIGN D7): thread the configured consumption
+        // sink + clock so every billable research-fetch attempt records
+        // (research is maxRetries 0 by policy — exactly one event per run).
+        ...(deps.consume !== undefined ? { consume: deps.consume } : {}),
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
     };
     // Provider-fallback Ticket 03: route the call through the shared
     // fallback executor. The research command is the riskiest piece
@@ -946,6 +1155,17 @@ async function handleResearch(args, outputMode, deps) {
     // first attempt, so it is not duplicated across candidate
     // switches.
     return invokeCommand(deps.invocation, async (context) => {
+        // Local-context plan, Ticket 3 (DESIGN D5): resume-bearing view
+        // of the context flags, threaded through ResearchOptions into
+        // `buildResearchResumeCommand`. `mode` records ONLY an
+        // explicitly-set --context-mode (undefined stays omitted — the
+        // function's set-values-only convention), so an organize-default
+        // resume command carries `--context <path>` alone.
+        const resumeContext = typeof flags.context === "string"
+            ? { source: "file", path: flags.context, mode: contextMode }
+            : flags["context-stdin"] === true
+                ? { source: "stdin", mode: contextMode }
+                : undefined;
         const options = {
             model,
             outputLength,
@@ -954,7 +1174,34 @@ async function handleResearch(args, outputMode, deps) {
             maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
             timeout: flags.timeout ? parseInt(flags.timeout, 10) : undefined,
             noCache: flags["no-cache"] === true,
+            context: resumeContext,
         };
+        // Local-context plan, Ticket 2 (DESIGN D3/D5): read + parse the
+        // context source exactly ONCE, here in the handler and BEFORE
+        // `executeWithFallback`. The Node invocation adapter drains
+        // process.stdin on the first `readStdin()`, so a per-attempt read
+        // inside `research()` would hand a fallback retry an empty
+        // string, silently mutate the request, and hash to a different
+        // async-job state file (D5's second-paid-job trap). `research()`
+        // consumes the threaded result only (D4 remap + envelope field) —
+        // it never re-reads the source.
+        const contextKind = typeof flags.context === "string"
+            ? { file: flags.context }
+            : flags["context-stdin"] === true
+                ? { stdin: true }
+                : undefined;
+        let researchContext;
+        if (contextKind !== undefined) {
+            const content = await readContextSource(contextKind, {
+                readFile: (filePath) => fs.readFile(filePath),
+                readStdin: (maxBytes) => context.readStdin(maxBytes),
+            });
+            researchContext = {
+                mode: contextMode ?? "organize",
+                content,
+                parsed: parseContextText(content.text),
+            };
+        }
         // 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
@@ -988,6 +1235,7 @@ async function handleResearch(args, outputMode, deps) {
                 capability: adapter.research,
                 execution: executionDeps,
                 registerInterrupt: deps.researchRegisterInterrupt,
+                context: researchContext,
             }, context);
         });
         return outcome.result;
@@ -1123,6 +1371,13 @@ async function handleRepo(args, outputMode, deps) {
         cache: deps.repositoryCache,
         sleep: deps.repositorySleep,
         random: deps.repositoryRandom,
+        // PB-T2 (usage-ledger DESIGN D7): thread the configured consumption
+        // sink + clock so every billable repository operation attempt
+        // records (one deps object per handler is correct across fallback
+        // candidates — each candidate's cache identity supplies its own
+        // provider at emission time).
+        ...(deps.consume !== undefined ? { consume: deps.consume } : {}),
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
     };
     const language = flags.language;
     const maxChars = flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined;
@@ -1170,6 +1425,193 @@ async function handleRepo(args, outputMode, deps) {
         return outcome.result;
     }, outputMode, deps.now, deps.secrets);
 }
+// ---------------------------------------------------------------------------
+// Batch manifest runner (batch-runner DESIGN D1, D8)
+// ---------------------------------------------------------------------------
+const BATCH_HELP = `
+Batch - Run a manifest of capability operations across Providers
+
+Usage: scoutline batch <manifest.json|-> [options]
+
+Executes every manifest operation through the SAME handlers a direct
+call uses, forced to data mode, through a bounded worker pool. Provider
+distribution is the DEFAULT (DESIGN D4): unpinned operations are
+assigned round-robin across configured, capable Providers per
+capability group, in registry order. Pin an operation with its manifest
+"provider" field, or the whole batch with the global --provider flag,
+to opt out. routing.<capability> preferences are ignored inside batch
+(all eligible providers participate; pin to opt out), and search
+fan-out is suppressed: every operation runs on exactly its assigned
+Provider. Results[] keeps manifest order; per-op notices and errors
+are captured per operation, never re-emitted live. Process stdout
+carries exactly ONE write: the summary envelope.
+
+Manifest (schema v1, strict parse - unknown fields reject):
+  {
+    "schemaVersion": 1,
+    "operations": [
+      { "name": "op-1", "command": "search", "input": { "query": "..." } }
+    ]
+  }
+
+  commands: search, read, research, repo, vision, crawl, map
+  op fields: name (unique), command, input, provider? (pin), output?
+  - reads the manifest JSON from stdin (the ops themselves never can)
+
+Options:
+  --concurrency <n>  Parallel operations (integer 1-8; default 4)
+  --fail-fast        Stop scheduling after the first failed operation
+  --dry-run          Validate the manifest and preview the full
+                     assignment without contacting any provider
+  --help             Show this help
+
+Dry run boundary (--dry-run): every operation still gets its resolved
+provider (pin or distribution) and its pre-dispatch gates — configured
+AND capability-advertised, reason: ready | provider not configured |
+capability not advertised — but nothing executes: no transport, no
+cache reads or writes, no per-op output files. Per-handler flag
+semantics (post-compiler) are not validated in a dry run.
+
+Examples:
+  scoutline batch manifest.json
+  scoutline batch manifest.json --concurrency 2 --fail-fast
+  cat manifest.json | scoutline batch -
+`.trim();
+/** Flags `scoutline batch` itself accepts (strict surface; D1). */
+const BATCH_FLAGS = new Set([
+    "help",
+    "h",
+    "concurrency",
+    "fail-fast",
+    "dry-run",
+]);
+/**
+ * The real 7-entry handler map (D5): each allowed batch command runs
+ * the same handler the main dispatch switch calls, with the runner's
+ * per-op spread overriding `provider` (the assignment pin) and
+ * `invocation` (the capture adapter).
+ */
+const BATCH_HANDLERS = {
+    search: handleSearch,
+    read: handleRead,
+    research: handleResearch,
+    repo: handleRepo,
+    vision: handleVision,
+    crawl: handleCrawl,
+    map: handleMap,
+};
+/**
+ * `scoutline batch` handler (batch-runner plan Ticket 4, DESIGN D1).
+ *
+ * Order of operations: strict flag surface -> help short-circuit ->
+ * `--concurrency` gate (D8: integer 1..8, validation never clamping;
+ * the runner re-validates the number before the pool) -> manifest read
+ * (file, or `-` via the GLOBAL invocation's readStdin, exactly once,
+ * before the pool starts - the per-op adapters throw on readStdin so
+ * the manifest can never be consulted from an op) -> strict D2 parse
+ * -> D4 assignment -> shared runner.
+ *
+ * Every whole-batch failure (unknown flag, bad concurrency, unreadable
+ * manifest, parse/assignment rejection) throws ValidationError BEFORE
+ * any stdout write, so the main dispatch catch owns the process-level
+ * error envelope (AC1: stderr JSON contract, no summary envelope).
+ */
+async function handleBatch(args, outputMode, deps) {
+    const { flags, positional } = parseArgs(args);
+    // Unknown flags reject BEFORE the help short-circuit: parseArgs
+    // assigns the next non-dash argument as a flag's value, so
+    // `batch --frobnicate manifest.json` would otherwise swallow the
+    // manifest into the unknown flag, leave `positional` empty, and
+    // render help instead of naming the offender.
+    for (const key of Object.keys(flags)) {
+        if (!BATCH_FLAGS.has(key)) {
+            throw new ValidationError(`unknown batch flag "--${key}"`, 'Run "scoutline batch --help" for the accepted flags.');
+        }
+    }
+    // Boolean-only flags never take a value: `--dry-run false` would
+    // otherwise silently disable the safety boundary and RUN providers,
+    // because the flag value never equals `true`. Same for --fail-fast.
+    for (const key of ["fail-fast", "dry-run"]) {
+        const value = flags[key];
+        if (value !== undefined && value !== true) {
+            throw new ValidationError(`--${key} is a boolean flag and takes no value`, `Pass the bare --${key} to enable it, or omit it.`);
+        }
+    }
+    if (flags.help || flags.h || positional.length === 0) {
+        deps.invocation.writeStdout(BATCH_HELP);
+        return 0;
+    }
+    if (positional.length > 1) {
+        throw new ValidationError("batch takes exactly one manifest argument (a file path or '-')", "Pass the manifest path, or '-' to read it from stdin.");
+    }
+    // D8 gate at the command seam: the flag arrives as a string (or
+    // `true` when valueless); convert and let the runner's own
+    // normalizeConcurrency own the integer/range VALIDATION_ERROR, which
+    // fires before the pool and before any stdout write.
+    let concurrency;
+    if (flags.concurrency !== undefined) {
+        if (typeof flags.concurrency !== "string") {
+            throw new ValidationError(`batch concurrency must be an integer between 1 and ${BATCH_MAX_CONCURRENCY}`, "Omit --concurrency for the default of 4, or pass an integer in 1..8.");
+        }
+        concurrency = Number(flags.concurrency);
+    }
+    // Manifest source (D1): a file path, or `-` for stdin through the
+    // GLOBAL invocation adapter (the tools.ts `context.readStdin()`
+    // precedent) — read exactly once, before the pool starts. The read
+    // happens outside invokeCommand (the runner owns its process
+    // effects), directly on the adapter the switch handed in.
+    const manifestArg = positional[0] ?? "";
+    let manifestText;
+    if (manifestArg === "-") {
+        try {
+            manifestText = await deps.invocation.readStdin();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ValidationError(`failed to read batch manifest from stdin: ${message}`);
+        }
+    }
+    else {
+        try {
+            manifestText = await fs.readFile(manifestArg, "utf8");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ValidationError(`failed to read batch manifest file "${manifestArg}": ${message}`);
+        }
+    }
+    let rawManifest;
+    try {
+        rawManifest = JSON.parse(manifestText);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ValidationError(`batch manifest is not valid JSON: ${message}`);
+    }
+    const manifest = parseBatchManifest(rawManifest, {
+        descriptors: deps.providerDescriptors,
+        dirExists: (dir) => existsSync(dir),
+    });
+    // D4 precedence: per-op pin > global --provider > distribution. The
+    // global pin was already extracted from argv by the switch layer.
+    const assignments = assignBatchProviders(manifest, {
+        descriptors: deps.providerDescriptors,
+        env: deps.env,
+        globalProvider: deps.provider,
+    });
+    const { exitCode } = await runBatch(manifest, assignments, {
+        handlerDeps: deps,
+        handlers: BATCH_HANDLERS,
+        invocation: deps.invocation,
+        outputMode,
+        now: deps.now,
+    }, {
+        ...(concurrency !== undefined ? { concurrency } : {}),
+        failFast: flags["fail-fast"] === true,
+        dryRun: flags["dry-run"] === true,
+    });
+    return exitCode;
+}
 async function handleTools(args, outputMode, deps) {
     const { flags } = parseArgs(args);
     if (flags.help || flags.h) {
@@ -1438,6 +1880,83 @@ export async function handleCache(args, outputMode, deps) {
             throw new ValidationError(`Unknown cache command: ${subcommand}`, 'Run "scoutline cache --help" for available commands');
     }
 }
+/**
+ * `scoutline usage [--days N] [--provider <id>]` — report the local
+ * usage ledger (usage-ledger plan, Ticket 5). Credential-free and
+ * read-only: like `cache` it bypasses Provider resolution entirely, and
+ * like `handleCache` it keeps the injection-free posture — the ledger
+ * path resolves at handler time via
+ * `resolveConfigRootPure(deps.env, ...)` (no new `MainDependencies`
+ * field, no injected reader object). Production reads
+ * `readUsageLedger(resolveUsageLedgerPath(...))` with DEFAULT deps
+ * (real reader, no `onWarning`) so DESIGN D8's silent-on-corrupt
+ * contract holds: a missing, corrupt, or wrong-version ledger yields an
+ * empty window with exit 0 and no stderr noise.
+ *
+ * Flag contract (DESIGN D8): `--days` must be an integer ≥ 1 (unlike
+ * `--count`, 0 is invalid) and defaults to 7; `--provider` must be a
+ * known registry id (unknown ids are a VALIDATION_ERROR listing the
+ * accepted ids; a known-but-unrecorded id is an empty result, exit 0).
+ * `--provider` may appear before or after the command token —
+ * `extractGlobalOptions` strips it either way, so the handler recovers
+ * it from `deps.provider` (same recovery as `cache prune`).
+ */
+export async function handleUsage(args, outputMode, deps) {
+    const { flags } = parseArgs(args);
+    if (flags.help || flags.h) {
+        deps.invocation.writeStdout(USAGE_HELP);
+        return 0;
+    }
+    // `--days`: positive integer >= 1 (DESIGN D8). parseArgs yields `true`
+    // for a valueless flag, so the bare case is guarded separately.
+    let windowDays = DEFAULT_USAGE_WINDOW_DAYS;
+    const rawDays = flags.days;
+    if (rawDays !== undefined) {
+        if (rawDays === true) {
+            throw new ValidationError("--days requires a value.", "Pass a positive integer, e.g. --days 7.");
+        }
+        const str = typeof rawDays === "string" ? rawDays : String(rawDays);
+        // Strict decimal gate (same class as parseAndValidateCount's /^\d+$/):
+        // Number() alone would coerce "1e3", "0x0A", " 7", and "7.0" into
+        // integers, accepting spellings the documented contract (USAGE_HELP,
+        // DESIGN D8 — a decimal integer 1..MAX) does not include.
+        if (!/^\d+$/.test(str)) {
+            throw new ValidationError(`Invalid --days value "${rawDays}"`, `--days must be an integer between 1 and ${MAX_USAGE_WINDOW_DAYS}. Examples: --days 7, --days 30.`);
+        }
+        const parsed = Number(str);
+        // Upper bound (review P2): values far beyond the window the ledger
+        // can ever hold (retention is 90 days) would otherwise pass and
+        // crash the cutoff computation — JS Dates only span ~±100,000,000
+        // days, so e.g. --days 1000000000 throws RangeError in usageDayKey.
+        if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_USAGE_WINDOW_DAYS) {
+            throw new ValidationError(`Invalid --days value "${rawDays}"`, `--days must be an integer between 1 and ${MAX_USAGE_WINDOW_DAYS}. Examples: --days 7, --days 30.`);
+        }
+        windowDays = parsed;
+    }
+    // `--provider` selector: command-local flag wins over the
+    // `deps.provider` fallback (extractGlobalOptions already stripped the
+    // global spelling from the rest stream).
+    const rawProvider = flags.provider;
+    if (rawProvider === true) {
+        throw new ValidationError("--provider requires a value.", "Pass a Provider id after --provider, e.g. --provider zai.");
+    }
+    const providerSelector = typeof rawProvider === "string" ? rawProvider : deps.provider;
+    if (providerSelector !== undefined &&
+        !PROVIDER_IDS.includes(providerSelector)) {
+        throw new ValidationError(`Unknown provider "${providerSelector}".`, `Accepted provider IDs: ${PROVIDER_IDS.join(", ")}.`);
+    }
+    // Read the ledger with default deps — real reader, no `onWarning`
+    // (silent-on-corrupt, DESIGN D8).
+    const configRoot = resolveConfigRootPure(deps.env, { homedir: os.homedir() });
+    const ledgerPath = resolveUsageLedgerPath(configRoot);
+    const now = deps.now ?? Date.now;
+    return invokeCommand(deps.invocation, () => usageCommand({
+        readLedger: () => readUsageLedger(ledgerPath),
+        windowDays,
+        ...(providerSelector !== undefined ? { provider: providerSelector } : {}),
+        now,
+    }), outputMode, deps.now, deps.secrets);
+}
 async function handleQuota(args, outputMode, deps) {
     const { flags } = parseArgs(args);
     if (flags.help || flags.h) {
@@ -1659,9 +2178,26 @@ export async function main(args, dependencies) {
     // surviving the bin's immediate `process.exit(status)`.
     const quotaRefreshEnabled = !dependencies.loadScoutlineConfig && !dependencies.providerDescriptors;
     const quotaStore = dependencies.quotaStore ?? createDefaultQuotaStore();
+    // Production records consumption through BOTH sinks (usage-ledger
+    // DESIGN D3): the PB-T1 quota-store snapshot store (unchanged,
+    // including its no-op-before-snapshot posture) and the usage ledger
+    // (sibling `usage.json` under the same config root, resolved through
+    // the pure `resolveUsageLedgerPath()`; warnings default to stderr
+    // like the quota sink). The composite isolates each side — one
+    // sink's failure becomes one redacted warning and never blocks or
+    // fails the other.
     const consume = dependencies.consume ??
         (quotaRefreshEnabled
-            ? createQuotaStoreConsumptionSink({ store: quotaStore, now: now ?? Date.now })
+            ? createCompositeConsumptionSink(createQuotaStoreConsumptionSink({ store: quotaStore, now: now ?? Date.now }), 
+            // The ledger path resolves from the SAME injected-env config
+            // root `handleUsage` reads through (resolveConfigRootPure over
+            // MainDependencies.env) — not from ambient process.env — so an
+            // embedded caller or hermetic run that injects
+            // SCOUTLINE_CONFIG_DIR sees its recorded usage in the root the
+            // `usage` command reports from (review P2).
+            createUsageLedgerSink({
+                filePath: resolveUsageLedgerPath(resolveConfigRootPure(env, { homedir: os.homedir() })),
+            }))
             : undefined);
     // PB-T4: quota snapshot for selection. Declared here so
     // `buildHandlerDeps` closes over the binding; assigned AFTER the
@@ -1758,6 +2294,21 @@ export async function main(args, dependencies) {
             return getErrorExitCode(error);
         }
     }
+    // `usage` is credential-free (reads only <config-root>/usage.json; no
+    // Provider resolution, no Adapter, no transport — the same
+    // short-circuit class as `cache`). Dispatching before config load
+    // keeps a corrupt config.json from blocking the usage report and
+    // keeps trigger detection unreached. Fail-open ledger reads mean a
+    // missing/corrupt file still exits 0 with an empty window (DESIGN D8).
+    if (command === "usage") {
+        try {
+            return await handleUsage(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
@@ -1974,6 +2525,10 @@ export async function main(args, dependencies) {
     // earlier alongside `buildHandlerDeps` so the sink closes over a
     // defined binding — see PB-T2 above.)
     const isQuotaObservationalCommand = command === "quota" || command === "doctor";
+    // Dry-run batches (`batch --dry-run`, `vision batch --dry-run`) promise
+    // a no-transport preview (batch DESIGN D7/D10) — the due-refresh below
+    // must not live-probe stale providers for them (review fix).
+    const isDryRunBatch = isDryRunBatchInvocation(command, commandArgs);
     const refreshOnError = (_providerId, _error) => {
         // Silent: quota-refresh failures are best-effort. Writing to stderr
         // would violate the JSON error contract (stderr is reserved for the
@@ -2041,6 +2596,10 @@ export async function main(args, dependencies) {
                 commandRecognized = true;
                 exitCode = await handleRepo(commandArgs, outputMode, handlerDepsWithSelection);
                 break;
+            case "batch":
+                commandRecognized = true;
+                exitCode = await handleBatch(commandArgs, outputMode, handlerDepsWithSelection);
+                break;
             case "tools":
                 commandRecognized = true;
                 exitCode = await handleTools(commandArgs, outputMode, handlerDepsWithSelection);
@@ -2084,6 +2643,8 @@ export async function main(args, dependencies) {
     //   - `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)
+    //   - dry-run batch invocations — the preview contract promises no
+    //     transport, and this refresh live-probes stale providers
     // 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
@@ -2093,7 +2654,8 @@ export async function main(args, dependencies) {
     if (quotaRefreshEnabled &&
         commandRecognized &&
         !isQuotaObservationalCommand &&
-        !isHelpInvocation) {
+        !isHelpInvocation &&
+        !isDryRunBatch) {
         await refreshQuotaSnapshots({
             descriptors: providerDescriptors,
             env: resolvedEnv,