@ozzylabs/feedradar 0.1.4 → 0.1.5

package/dist/cli/research.js

@@ -21,7 +21,18 @@ import { getAgentAdapter } from "../agents/index.js";
 import { getDefaultAgent, loadRadarConfig, RadarConfigError } from "../core/config.js";
 import { loadItems, saveItems } from "../core/items.js";
 import { loadTemplate } from "../core/templates.js";
-import { AgentIdSchema, ResearchFrontmatterSchema } from "../schemas/index.js";
+import { AgentIdSchema, ItemStatusSchema, ResearchFrontmatterSchema } from "../schemas/index.js";
+import { buildAgentProgressCallback, buildReporter, ProgressFlagError, parseProgressFlags, pollOutputFileSize, } from "./_progress.js";
+/**
+ * Default hard-cap for `radar research --batch`.
+ *
+ * ADR-0014 D3a pins the default to 10: 2-10x the empirical detection rate
+ * (1-5 items per cron tick) while keeping LLM cost-per-tick bounded
+ * (~$0.01/item * 10 ~= $0.1). Generated workflow YAML embeds this same
+ * literal via `combined.template.yaml`, but the CLI re-enforces it so the
+ * cap also applies when the YAML is hand-edited.
+ */
+export const RESEARCH_BATCH_DEFAULT_MAX_ITEMS = 10;
 function parseArgs(args) {
     const out = { itemIds: [] };
     for (let i = 0; i < args.length; i++) {
@@ -34,6 +45,10 @@ function parseArgs(args) {
             out.digest = true;
             continue;
         }
+        if (a === "--batch") {
+            out.batch = true;
+            continue;
+        }
         if (a === "--agent") {
             out.agent = args[++i];
             continue;
@@ -42,6 +57,18 @@ function parseArgs(args) {
             out.template = args[++i];
             continue;
         }
+        if (a === "--status") {
+            out.status = args[++i];
+            continue;
+        }
+        if (a === "--max-items") {
+            out.maxItems = args[++i];
+            continue;
+        }
+        if (a === "--filter-tags") {
+            out.filterTags = args[++i];
+            continue;
+        }
         if (a?.startsWith("--")) {
             throw new Error(`unknown option: ${a}`);
         }
@@ -55,19 +82,34 @@ function printHelp(log) {
     log("Usage:");
     log("  radar research <item-id> [--agent <agent-id>] [--template <template-id>]");
     log("  radar research --digest <item-id> <item-id> ... [--agent <agent-id>] [--template <id>]");
+    log(`  radar research --batch [--status <status>] [--max-items N] [--filter-tags <list>] [--agent <id>]`);
     log("");
     log("Arguments:");
     log("  <item-id>             Item id (matches items/<sourceId>/<item-id>.yaml)");
     log("                        Pass 2 or more ids together with --digest to bundle them.");
+    log("                        Omit positional ids with --batch — items are discovered.");
     log("");
     log("Options:");
     log("  --agent <agent-id>    claude-code | codex-cli | gemini-cli | copilot (default: claude-code)");
     log("  --template <id>       Template id under templates/ (default: default; digest: digest)");
     log("  --digest              Bundle multiple items into a single digest report (ADR-0011)");
+    log("  --batch               Research every item matching --status (and --filter-tags)");
+    log("                        respecting the --max-items hard-cap (ADR-0014 D3a).");
+    log("  --status <status>     Batch-mode filter: detected | researched | reviewed | dismissed");
+    log("                        (default: detected).");
+    log(`  --max-items N         Batch-mode hard-cap on processed items (default: ${RESEARCH_BATCH_DEFAULT_MAX_ITEMS}).`);
+    log("                        Excess items are dropped and announced via warn() so a runaway");
+    log("                        detection cannot blow the cap from inside a workflow.");
+    log("  --filter-tags <list>  Batch-mode comma-separated allow-list matched against");
+    log("                        each item's matchedKeywords (case-insensitive). Default: all.");
+    log("  --verbose             Stream the agent CLI's stdout/stderr in addition to phase markers.");
+    log("  --quiet               Suppress phase markers and spinner; print only the completion line.");
+    log("                        Equivalent to setting RADAR_NO_PROGRESS=1 (ADR-0015 D2).");
     log("");
     log("Output:");
     log("  single-item:  research/<YYYYMMDD>_<slug>_v1.md (ADR-0003)");
     log("  digest:       research/<YYYYMMDD>_digest_<slug>_v1.md (ADR-0011)");
+    log("  batch:        one single-item report per matched item (no digest aggregation).");
 }
 async function pathExists(p) {
     try {
@@ -78,14 +120,6 @@ async function pathExists(p) {
         return false;
     }
 }
-/**
- * Slug an Item into the `<sourceId>-<short-slug>` form used by the research
- * filename (`research/<YYYYMMDD>_<slug>_v1.md`).
- *
- * Falls back to the item id when the title is empty/unicode-only. We trim to
- * 60 chars so the resulting filename stays inside typical filesystem limits
- * after adding date prefix and version suffix.
- */
 function buildSlug(item) {
     const baseSource = item.sourceId.toLowerCase().replace(/[^a-z0-9]+/g, "-");
     const titleSlug = item.title
@@ -100,39 +134,19 @@ function buildSlug(item) {
             .slice(0, 60);
     return `${baseSource}-${tail}`;
 }
-/**
- * Pick `YYYYMMDD` from the item's `publishedAt`, falling back to today (UTC)
- * when the source feed did not provide a publish date.
- */
 function buildDatePrefix(item, now) {
     const iso = item.publishedAt ?? now.toISOString();
     return iso.slice(0, 10).replace(/-/g, "");
 }
-/**
- * Pick `YYYYMMDD` for digest output. Per ADR-0011 §1, digest filenames use the
- * **generation date** (UTC, CLI invocation time) rather than any item's
- * `publishedAt`. Constituent items rarely share a publish date and the digest
- * is a synthesis artifact, so the generation date is the only stable key.
- */
 function buildDigestDatePrefix(now) {
     return now.toISOString().slice(0, 10).replace(/-/g, "");
 }
-/**
- * Kebab-case helper used by both digest slug derivation and the clamp routine.
- * Mirrors the algorithm pinned in ADR-0011 §2: lowercase, non-alphanumerics
- * collapse to a single hyphen, leading/trailing hyphens are stripped.
- */
 function kebabCase(s) {
     return s
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
 }
-/**
- * Trim a slug to `max` characters, but never end mid-word: cut at the last
- * hyphen boundary inside the limit so the slug stays readable when truncated
- * (ADR-0011 §2). When no hyphen is present we fall back to a hard cut.
- */
 function clampSlug(s, max = 60) {
     if (s.length <= max)
         return s;
@@ -140,26 +154,6 @@ function clampSlug(s, max = 60) {
     const lastHyphen = cut.lastIndexOf("-");
     return lastHyphen > 0 ? cut.slice(0, lastHyphen) : cut;
 }
-/**
- * Derive the digest slug from the constituent items' `matchedKeywords`
- * (ADR-0011 §2).
- *
- * Algorithm:
- *   1. Aggregate every item's `matchedKeywords` into a frequency map keyed by
- *      the normalized (lowercased, trimmed) keyword. Empty strings are
- *      ignored so a noisy `[""]` entry cannot dominate the ranking.
- *   2. Sort by frequency descending, ties broken by lexicographic ascending so
- *      the output is deterministic regardless of input item order.
- *   3. Take the top 1-2 entries, kebab-case each, and join with `-`. If no
- *      keywords are present we fall back to the literal `"digest"` so the
- *      ADR-0011 filename pattern (`<date>_digest_<slug>_v<n>.md`) still
- *      produces a recognizable `<date>_digest_digest_v1.md` artifact.
- *   4. Clamp to 60 chars on hyphen boundaries (`clampSlug`).
- *
- * Stable ordering matters because the digest id is content-addressed: the
- * same item set must always yield the same filename so re-runs can detect
- * collisions deterministically.
- */
 function deriveDigestSlug(items) {
     const freq = new Map();
     for (const item of items) {
@@ -178,14 +172,6 @@ function deriveDigestSlug(items) {
         return "digest";
     return clampSlug(top.map(kebabCase).join("-"));
 }
-/**
- * Locate `items/<sourceId>/<item-id>.yaml` across all source directories,
- * since the CLI only takes `<item-id>` (sourceId is not on the command line).
- *
- * `loadItems` already walks every source subdir, so we delegate to it and
- * then match by id. Returning the full Item (rather than just the path) lets
- * the caller compute slug / date without a second read.
- */
 async function findItem(cwd, itemId) {
     const itemsDir = join(cwd, "items");
     if (!(await pathExists(itemsDir)))
@@ -196,15 +182,6 @@ async function findItem(cwd, itemId) {
         return null;
     return { item: match };
 }
-/**
- * Locate multiple items at once. We do a single `loadItems` walk and then
- * map the requested ids against the result, preserving the caller's order
- * for the eventual `itemIds` frontmatter array (ADR-0011 keeps no constraint
- * on order, but stable user-supplied order is the least surprising default).
- *
- * Returns `null` for the first missing id so the caller can emit a targeted
- * error rather than walking `items/` repeatedly.
- */
 async function findItems(cwd, itemIds) {
     const itemsDir = join(cwd, "items");
     if (!(await pathExists(itemsDir)))
@@ -220,145 +197,41 @@ async function findItems(cwd, itemIds) {
     }
     return { items: matched };
 }
-/**
- * Implementation of `radar research <item-id>` (single-item) and
- * `radar research --digest <id1> <id2> ...` (multi-item digest, ADR-0011).
- *
- * High-level flow (Phase 1):
- *   1. Parse + validate args (agent defaults to `claude-code`, template to
- *      `default` for single-item or `digest` for `--digest`).
- *   2. Locate `items/<sourceId>/<item-id>.yaml` for each id and parse it.
- *   3. Load `templates/<template-id>.md` (empty body when default is absent).
- *   4. Compute the output path:
- *        - single-item: `research/<YYYYMMDD>_<slug>_v1.md` (ADR-0003)
- *        - digest:      `research/<YYYYMMDD>_digest_<slug>_v1.md` (ADR-0011)
- *      Refuse to overwrite an existing file — re-runs go through `update`.
- *   5. Invoke the registered agent adapter; the agent writes the report.
- *   6. Validate the report's frontmatter against `ResearchFrontmatterSchema`.
- *   7. Transition every included item: `status` → `researched` and persist.
- *
- * Any step from 4 onward that fails surfaces a non-zero exit code with a
- * targeted message so the user can debug without re-reading the source.
- */
-export async function runResearch(args, options = {}) {
-    const cwd = options.cwd ?? process.cwd();
-    const log = options.io?.log ?? ((m) => console.log(m));
-    const warn = options.io?.warn ?? ((m) => console.warn(m));
-    const error = options.io?.error ?? ((m) => console.error(m));
-    let parsed;
-    try {
-        parsed = parseArgs(args);
-    }
-    catch (e) {
-        error(`research: ${e instanceof Error ? e.message : String(e)}`);
-        return 2;
-    }
-    if (parsed.help) {
-        printHelp(log);
-        return 0;
-    }
-    if (parsed.itemIds.length === 0) {
-        error("research: missing <item-id>");
-        printHelp(error);
-        return 2;
-    }
-    // Single-item mode: enforce exactly one positional id so the existing
-    // behavior of `radar research <id>` is unambiguous. The user must opt into
-    // multi-item mode via `--digest`.
-    if (!parsed.digest && parsed.itemIds.length > 1) {
-        error(`research: multiple <item-id> arguments require --digest (got ${parsed.itemIds.length}: ${parsed.itemIds.join(", ")})`);
-        return 2;
-    }
-    // Digest mode: must bundle 2+ items per ADR-0011 §1 (a single-item digest
-    // is indistinguishable from a regular research run and would muddy the ID
-    // space). Reject early with exit 2 (argument error).
-    if (parsed.digest && parsed.itemIds.length < 2) {
-        error(`research: --digest requires 2 or more <item-id> arguments (got ${parsed.itemIds.length})`);
-        return 2;
-    }
-    // Resolve the agent honoring the priority chain:
-    //   explicit --agent > radar.config.yaml defaultResearchAgent > "claude-code"
-    // The explicit value is validated against AgentIdSchema first so a bogus
-    // --agent never reaches the config / fallback path.
+async function resolveAgent(cwd, rawAgent, error) {
     let explicitAgent;
-    if (parsed.agent !== undefined) {
-        const agentResult = AgentIdSchema.safeParse(parsed.agent);
+    if (rawAgent !== undefined) {
+        const agentResult = AgentIdSchema.safeParse(rawAgent);
         if (!agentResult.success) {
-            error(`research: invalid --agent '${parsed.agent}' (expected: claude-code | codex-cli | gemini-cli | copilot)`);
-            return 2;
+            error(`research: invalid --agent '${rawAgent}' (expected: claude-code | codex-cli | gemini-cli | copilot)`);
+            return { exitCode: 2 };
         }
         explicitAgent = agentResult.data;
     }
-    let agent;
     try {
         const config = await loadRadarConfig(cwd);
-        agent = await getDefaultAgent("research", { explicit: explicitAgent, configOverride: config });
+        const agent = await getDefaultAgent("research", {
+            explicit: explicitAgent,
+            configOverride: config,
+        });
+        return { agent };
     }
     catch (e) {
         if (e instanceof RadarConfigError) {
             error(`research: ${e.message}`);
-            return 2;
+            return { exitCode: 2 };
         }
         throw e;
     }
-    // Phase 2 sub-issues B / C / D / E ship all four adapters. AgentIdSchema
-    // already rejected invalid `--agent` values upstream, so any value that
-    // reaches here is supported.
-    // Default template depends on mode: ADR-0011 §6 pins `digest` as the digest
-    // templateId so the bundled `templates/digest.md` is picked up automatically
-    // when the user doesn't pass `--template`.
-    const templateId = parsed.template ?? (parsed.digest ? "digest" : "default");
-    // Locate the item(s). Digest mode collects every id up front so a missing id
-    // fails before we invoke the agent (cheap fail-fast vs. burning tokens).
-    let items;
-    if (parsed.digest) {
-        const result = await findItems(cwd, parsed.itemIds);
-        if ("missing" in result) {
-            error(`research: item '${result.missing}' not found under items/`);
-            return 1;
-        }
-        items = result.items;
-        // ADR-0011 §5: a `dismissed` item must not appear in a digest. Validate
-        // up-front so the user can either remove the id or re-detect the source
-        // before re-running.
-        const dismissed = items.filter((i) => i.status === "dismissed");
-        if (dismissed.length > 0) {
-            error(`research: cannot include dismissed items in a digest: ${dismissed.map((i) => i.id).join(", ")}`);
-            return 1;
-        }
-    }
-    else {
-        const found = await findItem(cwd, parsed.itemIds[0]);
-        if (!found) {
-            error(`research: item '${parsed.itemIds[0]}' not found under items/`);
-            return 1;
-        }
-        items = [found.item];
-    }
-    // Surface any prompt-injection pre-filter hits recorded by the watcher
-    // (ADR-0009 M1a / M5a — Adopt). Audit-only: the agent still runs against
-    // the original content, but the user gets an explicit warning so they can
-    // `radar dismiss` and re-evaluate before committing tokens.
+}
+async function processResearchInvocation(params) {
+    const { cwd, items, digest, agent, templateId, template, now, log, warn, error, progress } = params;
     for (const item of items) {
         if (item.injectionFlags.length > 0) {
             warn(`research: item '${item.id}' has ${item.injectionFlags.length} injection flag(s): ${item.injectionFlags.join(", ")} (audit-only; use \`radar dismiss\` to skip)`);
         }
     }
-    // Load template.
-    const templatesDir = join(cwd, "templates");
-    let template;
-    try {
-        template = await loadTemplate(templateId, templatesDir);
-    }
-    catch (e) {
-        error(`research: ${e instanceof Error ? e.message : String(e)}`);
-        return 1;
-    }
-    // Compute output path. Refuse to overwrite an existing file — re-runs go
-    // through `radar update` per ADR-0003 / ADR-0011 (immutable history).
-    const now = new Date();
     let filename;
-    if (parsed.digest) {
+    if (digest) {
         const datePrefix = buildDigestDatePrefix(now);
         const slug = deriveDigestSlug(items);
         filename = `${datePrefix}_digest_${slug}_v1.md`;
@@ -374,14 +247,26 @@ export async function runResearch(args, options = {}) {
         error(`research: ${outputPath} already exists (use \`radar update\` to re-research)`);
         return 1;
     }
-    const itemDescription = parsed.digest
+    const itemDescription = digest
         ? `${items.length} items (${items.map((i) => i.id).join(", ")})`
         : `item '${items[0].id}'`;
+    // Phase marker: items resolved (ADR-0015 D4 "Loaded <noun>"). One marker
+    // per invocation regardless of digest cardinality so the progress stream
+    // stays uniform between single / digest / batch modes.
+    progress.phase(digest ? `Loaded ${items.length} items` : `Loaded item: ${items[0].id}`, items.map((i) => i.id).join(", "));
+    // Phase marker: template resolved. Echoes the actual template id so a
+    // user running `--template deep-dive` sees the value flow through.
+    progress.phase(`Loaded template: ${templateId}.md`);
     log(`research: invoking ${agent} adapter for ${itemDescription} -> ${filename}`);
-    // Invoke adapter. The multi-item signature lands via #140; the adapter
-    // already handles `items.length === 1` byte-equivalently for single-item
-    // callers so no branching is needed here.
     const adapter = getAgentAdapter(agent);
+    // Phase marker + spinner: agent spawn. We pair `phase("Spawning …")` with
+    // `start("Agent running…")` so the marker is printed once for scrollback
+    // and the spinner row carries the live `[mm:ss]` heartbeat + metrics.
+    progress.phase(`Spawning ${agent}`, `cwd: ${cwd}`);
+    progress.start("Agent running");
+    const adapterStartedAt = Date.now();
+    const polling = pollOutputFileSize({ path: outputPath, reporter: progress });
+    let adapterExitCode = 0;
     try {
         await adapter.research({
             agent,
@@ -390,13 +275,22 @@ export async function runResearch(args, options = {}) {
             items,
             outputPath,
             cwd,
+            onProgress: buildAgentProgressCallback(progress),
         });
     }
     catch (e) {
+        adapterExitCode = 1;
+        polling.stop();
+        progress.fail("Agent failed", e instanceof Error ? e.message : String(e));
         error(`research: adapter failed: ${e instanceof Error ? e.message : String(e)}`);
         return 1;
     }
-    // Validate the produced file: frontmatter must parse and match schema.
+    finally {
+        polling.stop();
+    }
+    if (adapterExitCode === 0) {
+        progress.succeed(`Agent completed (exit ${adapterExitCode})`, Date.now() - adapterStartedAt);
+    }
     if (!(await pathExists(outputPath))) {
         error(`research: adapter completed but did not write ${outputPath} (agent ignored the output path?)`);
         return 1;
@@ -425,11 +319,10 @@ export async function runResearch(args, options = {}) {
         }
         return 1;
     }
-    // Phase 1 contract: review fields must be null. The schema permits null;
-    // we additionally enforce that the agent did not jump ahead and stamp them.
-    // Phase 5 contract: `supersedes` is null on v1 by definition (no predecessor
-    // exists). Defensive reset applies if a misbehaving agent populates it; the
-    // `update` command (Sub-issue B / #41) is the only writer that may set it.
+    // Phase marker: schema check passed. Emitted before the status transition
+    // so the user sees the validation outcome separately from the items.yaml
+    // write that follows.
+    progress.phase("Frontmatter validated");
     const reviewedDrift = fmResult.data.reviewedAt !== null || fmResult.data.reviewedBy !== null;
     const supersedesDrift = fmResult.data.supersedes !== null;
     if (reviewedDrift || supersedesDrift) {
@@ -439,8 +332,8 @@ export async function runResearch(args, options = {}) {
         if (supersedesDrift) {
             warn("research: agent populated supersedes; resetting to null (Phase 5 contract — v1 has no predecessor; `update` writes supersedes)");
         }
-        const parsed = matter(body, matterOptions);
-        const rewritten = matter.stringify(parsed.content, {
+        const parsedReport = matter(body, matterOptions);
+        const rewritten = matter.stringify(parsedReport.content, {
             ...fmResult.data,
             reviewedAt: null,
             reviewedBy: null,
@@ -448,14 +341,8 @@ export async function runResearch(args, options = {}) {
         }, matterOptions);
         await writeFile(outputPath, rewritten, "utf8");
     }
-    // Transition item status. ADR-0011 §5: every included item transitions
-    // `detected` → `researched`; terminal states (`researched` / `reviewed`)
-    // are protected and pass through unchanged so a digest that re-includes
-    // an already-researched item does not regress its status.
     const updated = items.map((item) => item.status === "detected" ? { ...item, status: "researched" } : item);
     try {
-        // saveItems writes by sourceId+id, so it will overwrite the existing file
-        // in place. We rely on this rather than constructing the path manually.
         await saveItems(join(cwd, "items"), updated);
     }
     catch (e) {
@@ -466,11 +353,239 @@ export async function runResearch(args, options = {}) {
     log(`research: wrote ${outputPath}`);
     for (const item of updated) {
         if (item.status === "researched") {
+            // Phase marker: status transition. We emit one phase per item rather
+            // than collapsing them so the digest case stays explicit about what
+            // moved. The arrow uses U+2192 (→) per ADR-0015 D4 examples.
+            progress.phase(`Status: detected → researched`, `items/${item.sourceId}/${item.id}.yaml`);
             log(`research: items/${item.sourceId}/${item.id}.yaml status -> researched`);
         }
     }
     return 0;
 }
+function parseMaxItems(raw, error) {
+    if (raw === undefined)
+        return RESEARCH_BATCH_DEFAULT_MAX_ITEMS;
+    if (!/^[0-9]+$/.test(raw)) {
+        error(`research: invalid --max-items '${raw}' (expected positive integer)`);
+        return null;
+    }
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0) {
+        error(`research: invalid --max-items '${raw}' (must be > 0)`);
+        return null;
+    }
+    return n;
+}
+function parseFilterTags(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return [];
+    return [
+        ...new Set(raw
+            .split(",")
+            .map((s) => s.trim().toLowerCase())
+            .filter((s) => s.length > 0)),
+    ];
+}
+async function runResearchBatch(parsed, cwd, log, warn, error, progress) {
+    if (parsed.itemIds.length > 0) {
+        error(`research: --batch is incompatible with positional <item-id> arguments (got ${parsed.itemIds.length})`);
+        return 2;
+    }
+    if (parsed.digest) {
+        error("research: --batch is incompatible with --digest");
+        return 2;
+    }
+    const rawStatus = parsed.status ?? "detected";
+    const statusResult = ItemStatusSchema.safeParse(rawStatus);
+    if (!statusResult.success) {
+        error(`research: invalid --status '${rawStatus}' (expected: detected | dismissed | researched | reviewed)`);
+        return 2;
+    }
+    const status = statusResult.data;
+    const maxItems = parseMaxItems(parsed.maxItems, error);
+    if (maxItems === null)
+        return 2;
+    const filterTags = parseFilterTags(parsed.filterTags);
+    const agentResult = await resolveAgent(cwd, parsed.agent, error);
+    if ("exitCode" in agentResult)
+        return agentResult.exitCode;
+    const agent = agentResult.agent;
+    const templateId = parsed.template ?? "default";
+    const templatesDir = join(cwd, "templates");
+    let template;
+    try {
+        template = await loadTemplate(templateId, templatesDir);
+    }
+    catch (e) {
+        error(`research: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+    const itemsDir = join(cwd, "items");
+    const all = await loadItems(itemsDir);
+    const lowerFilterTags = filterTags;
+    const matches = all
+        .filter((it) => it.status === status)
+        .filter((it) => {
+        if (lowerFilterTags.length === 0)
+            return true;
+        const haystack = new Set(it.matchedKeywords.map((k) => k.toLowerCase()));
+        return lowerFilterTags.some((t) => haystack.has(t));
+    })
+        .sort((a, b) => {
+        const ap = a.publishedAt ?? a.fetchedAt;
+        const bp = b.publishedAt ?? b.fetchedAt;
+        if (ap !== bp)
+            return ap < bp ? -1 : 1;
+        return a.id.localeCompare(b.id);
+    });
+    if (matches.length === 0) {
+        log(`research: no items matched --batch filters (status=${status}${filterTags.length > 0 ? `, tags=${filterTags.join(",")}` : ""})`);
+        return 0;
+    }
+    let selected = matches;
+    if (matches.length > maxItems) {
+        const dropped = matches.length - maxItems;
+        warn(`research: --max-items ${maxItems} cap reached; dropping ${dropped} excess item(s) (matched ${matches.length})`);
+        selected = matches.slice(0, maxItems);
+    }
+    log(`research: --batch will process ${selected.length} item(s) (status=${status}${filterTags.length > 0 ? `, tags=${filterTags.join(",")}` : ""}, agent=${agent}, cap=${maxItems})`);
+    const now = new Date();
+    for (const item of selected) {
+        const exitCode = await processResearchInvocation({
+            cwd,
+            items: [item],
+            digest: false,
+            agent,
+            templateId,
+            template,
+            now,
+            log,
+            warn,
+            error,
+            progress,
+        });
+        if (exitCode !== 0) {
+            error(`research: --batch halted on item '${item.id}' (exit ${exitCode})`);
+            return exitCode;
+        }
+    }
+    log(`research: --batch completed ${selected.length} item(s)`);
+    return 0;
+}
+export async function runResearch(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const log = options.io?.log ?? ((m) => console.log(m));
+    const warn = options.io?.warn ?? ((m) => console.warn(m));
+    const error = options.io?.error ?? ((m) => console.error(m));
+    // Strip the global --verbose / --quiet flags BEFORE the command-specific
+    // parser sees argv. This keeps `parseArgs` ignorant of progress concerns
+    // (and means a future `radar review --verbose` works the same way without
+    // duplicating flag plumbing per command).
+    let progressState;
+    try {
+        progressState = parseProgressFlags(args);
+    }
+    catch (e) {
+        if (e instanceof ProgressFlagError) {
+            error(`research: ${e.message}`);
+            return 2;
+        }
+        throw e;
+    }
+    // Tests inject a reporter directly; production constructs one from the
+    // flag state. Either way the per-invocation state stays local — there is
+    // no shared global reporter, so concurrent CLI invocations are isolated.
+    const progress = options.progress ?? buildReporter({ level: progressState.level });
+    let parsed;
+    try {
+        parsed = parseArgs(progressState.rest);
+    }
+    catch (e) {
+        error(`research: ${e instanceof Error ? e.message : String(e)}`);
+        return 2;
+    }
+    if (parsed.help) {
+        printHelp(log);
+        return 0;
+    }
+    if (parsed.batch) {
+        return runResearchBatch(parsed, cwd, log, warn, error, progress);
+    }
+    if (parsed.status !== undefined) {
+        error("research: --status requires --batch");
+        return 2;
+    }
+    if (parsed.maxItems !== undefined) {
+        error("research: --max-items requires --batch");
+        return 2;
+    }
+    if (parsed.filterTags !== undefined) {
+        error("research: --filter-tags requires --batch");
+        return 2;
+    }
+    if (parsed.itemIds.length === 0) {
+        error("research: missing <item-id>");
+        printHelp(error);
+        return 2;
+    }
+    if (!parsed.digest && parsed.itemIds.length > 1) {
+        error(`research: multiple <item-id> arguments require --digest (got ${parsed.itemIds.length}: ${parsed.itemIds.join(", ")})`);
+        return 2;
+    }
+    if (parsed.digest && parsed.itemIds.length < 2) {
+        error(`research: --digest requires 2 or more <item-id> arguments (got ${parsed.itemIds.length})`);
+        return 2;
+    }
+    const agentResult = await resolveAgent(cwd, parsed.agent, error);
+    if ("exitCode" in agentResult)
+        return agentResult.exitCode;
+    const agent = agentResult.agent;
+    const templateId = parsed.template ?? (parsed.digest ? "digest" : "default");
+    let items;
+    if (parsed.digest) {
+        const result = await findItems(cwd, parsed.itemIds);
+        if ("missing" in result) {
+            error(`research: item '${result.missing}' not found under items/`);
+            return 1;
+        }
+        items = result.items;
+        const dismissed = items.filter((i) => i.status === "dismissed");
+        if (dismissed.length > 0) {
+            error(`research: cannot include dismissed items in a digest: ${dismissed.map((i) => i.id).join(", ")}`);
+            return 1;
+        }
+    }
+    else {
+        const found = await findItem(cwd, parsed.itemIds[0]);
+        if (!found) {
+            error(`research: item '${parsed.itemIds[0]}' not found under items/`);
+            return 1;
+        }
+        items = [found.item];
+    }
+    const templatesDir = join(cwd, "templates");
+    let template;
+    try {
+        template = await loadTemplate(templateId, templatesDir);
+    }
+    catch (e) {
+        error(`research: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+    return processResearchInvocation({
+        cwd,
+        items,
+        digest: parsed.digest ?? false,
+        agent,
+        templateId,
+        template,
+        now: new Date(),
+        log,
+        warn,
+        error,
+        progress,
+    });
+}
 export const researchCommand = {
     name: "research",
     summary: "Generate Markdown research reports from items via an AI agent",