gemcatch 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,114 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-08
+
+### Added
+
+- **Research agents.** `-a, --agent <id>` on `research` and `batch` submits to a
+  Gemini Deep Research agent instead of a model — `interactions.create` is sent
+  `agent` *instead of* `model` (they are mutually exclusive, and passing both is
+  a clean error). Aliases resolve through one table: `deep-research` →
+  `deep-research-preview-04-2026`, `deep-research-max` →
+  `deep-research-max-preview-04-2026`; any other value passes through unchanged,
+  so a future agent id works without a gemcatch release. Agents *require*
+  background execution, which gemcatch has always set — and on the free tier the
+  finished report is dropped after 1 day, which is exactly the race the daemon
+  exists to win. The agent is recorded per task, shown in `list` (the AGENT
+  column appears when a listing contains agent runs) and tallied in `stats`.
+- **Spend guard.** Deep Research is documented at $1.00–$3.00 per task and Deep
+  Research Max at $3.00–$7.00 (estimates based on preview rates, per the docs,
+  and subject to change). Every agent submission prints its band first —
+  `batch` prints N × the band as a total — and asks for an interactive `y/N`
+  confirmation. When stdin is not a TTY, `--yes` is required and anything else
+  is refused before a row is written; declining writes nothing and exits
+  non-zero. `--dry-run` (now on `research` too) prints the full projected spend
+  and submits nothing.
+- **Citations.** Agent runs return citations alongside the report; the docs say
+  to review them to verify the sources, so they are persisted (new `citations`
+  column, JSON) rather than discarded, printed under the result as a `Sources:`
+  list, and carried in `--json` output.
+- Result extraction now takes the **final answer-bearing step** — where the
+  docs place an agent's completed report (`steps[-1].content[0].text`) and
+  where a model run's `model_output` already sits — with a fall-back to the old
+  collect-everything behaviour if that step carries no text, so an unexpected
+  shape can never silently blank a result. No special-casing on the agent id.
+- Additive schema migration: `agent` and `citations` columns. A pre-0.4.0
+  `tasks.db` upgrades in place, keeps every row, and reports `agent` as NULL
+  for them.
+
+### Changed
+
+- The default model is now **`gemini-3.5-flash-lite`** (GA on 2026-07-21),
+  replacing the older `gemini-3.1-flash-lite`. Override with `GEMCATCH_MODEL`
+  or `--model` as before.
+
+## [0.3.0] - 2026-07-19
+
+### Added
+
+- `gemcatch export [--tag <t>] [--status <s>] [--format md|json] [-o <file>]` —
+  concatenate finished results into one document, each under a heading with its
+  prompt, id and date. Markdown by default (or JSON for `jq`), to stdout or a
+  file. This is the "gather" step that pairs with `batch`'s "scatter": where
+  `get` prints one result at a time, `export` collects a whole tag at once.
+- `gemcatch digest --tag <t>` — feed a tag's completed results back through a
+  single Gemini call to synthesise one summary. Submits like `research` and
+  watches to completion; the summary lands under `<tag>-digest`.
+- `GEMCATCH_WATCH_MAX_FAILS` (default 10) — the consecutive-poll-failure bound
+  at which `watch` and `batch -w` give up rather than loop forever.
+
+### Fixed
+
+- `research --watch` no longer marks a **successfully submitted, server-running**
+  task `failed` when a poll errors during the watch. A transient poll failure (a
+  5xx past its retries, a network blip) or an expiry mid-watch would propagate to
+  the submit handler and overwrite the status to `failed`, dropping the task from
+  the active set so the daemon abandoned it and the result was lost. The watch
+  loop now rides out poll errors (retrying on the next interval), and only a
+  failed *submit* — a task with no `interaction_id` yet — is ever marked `failed`.
+- A wedged or expired interaction no longer keeps a task in flight forever. When a
+  poll returns **404** (the free tier drops interactions after 24h, or one was
+  deleted), the task is retired locally to `incomplete` with a recorded reason, so
+  it leaves the active set and `daemon --exit-when-idle` converges. `watch` and
+  `batch -w` additionally stop after `GEMCATCH_WATCH_MAX_FAILS` consecutive poll
+  failures (or a stalled batch), with a clear message and a non-zero exit, instead
+  of spinning.
+- A **completed-but-empty** result is now served from the local cache. `get` and
+  `watch` gated the cache hit on the result being truthy, so a task that completed
+  with empty text (`''`) skipped the cache, re-polled, and 404'd after 24h — the
+  exact loss the daemon exists to prevent. The gate is now on presence
+  (`result != null`), not truthiness.
+- `prune -d <negative>` (or a non-numeric `--days`) is rejected instead of putting
+  the cutoff in the future and deleting **every** finished task. `--days` must now
+  be a non-negative number.
+- `batch` no longer silently drops a prompt line that starts with `#`. A `#` is a
+  comment only when followed by whitespace (`# like this`); a line such as
+  `#1 cause of X?` is a real prompt and survives. When comment or blank lines are
+  skipped, a one-line count is noted on stderr.
+- `watch -i` / `daemon -i` reject a non-positive interval (`-i -5` busy-looped,
+  `-i 0` silently fell back to the default). `list -n 0` now returns zero rows
+  instead of all of them, and `-n` rejects negatives (which SQLite reads as "no
+  limit").
+- A second `Ctrl-C` to the daemon now force-exits (130) instead of doing nothing
+  while a long paced pass finishes.
+- One-shot commands close the SQLite store on exit, so they no longer leave
+  `-wal`/`-shm` sidecar files lingering next to `tasks.db`.
+- Colour written to **stderr** (the status chatter from `watch`, `daemon` and
+  `research -w`) is now keyed to `process.stderr.isTTY`, not stdout's. Redirecting
+  one stream no longer strips colour from the other, nor leaks raw ANSI into a
+  redirected file.
+
+### Notes
+
+- The default `@google/genai` SDK transport is now covered by the offline suite
+  (previously every test forced `GEMCATCH_FORCE_REST=1`): a stubbed client drives
+  submit → poll → completed and one unwrapped SDK error, confirming `shape()`
+  reads an SDK-shaped response and `friendly()` surfaces Google's real message.
+- `GEMCATCH_RPM` pacing is **per process**. Two concurrent `gemcatch` processes
+  each keep their own counter and can together exceed the ceiling; run a single
+  daemon if the limit must hold. Documented in the README.
+
 ## [0.2.0] - 2026-07-19
 
 ### Added
@@ -96,7 +204,9 @@ seen a task complete, the text is cached locally and survives that expiry — bu
 something has to poll inside that window for it to be seen at all, which is what
 `gemcatch daemon` exists to do.
 
-[Unreleased]: https://github.com/Booyaka101/gemcatch/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/Booyaka101/gemcatch/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/Booyaka101/gemcatch/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/Booyaka101/gemcatch/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Booyaka101/gemcatch/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/Booyaka101/gemcatch/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Booyaka101/gemcatch/releases/tag/v0.1.0

package/README.md

@@ -24,7 +24,7 @@ The EU AI Act's high-risk obligations phase in from August 2026, whereas...
 
 ## Setup
 
-Needs Node.js 22+ and a Gemini API key. **Getting a key needs no billing account and no card.** `gemini-3.1-flash-lite` runs free within the [free tier's](https://ai.google.dev/gemini-api/docs/pricing) daily quota; past that, paid rates apply.
+Needs Node.js 22+ and a Gemini API key. **Getting a key needs no billing account and no card.** `gemini-3.5-flash-lite` (the default model, GA since July 2026) runs free within the [free tier's](https://ai.google.dev/gemini-api/docs/pricing) daily quota; past that, paid rates apply.
 
 1. Get a key at **<https://aistudio.google.com/apikey>**
 2. Put it in your environment:
@@ -83,6 +83,8 @@ This week in AI: ...
 | `gemcatch status <id>` | Polls the API and prints the current state. |
 | `gemcatch get <id>` | Prints the full response if complete, otherwise the current status. |
 | `gemcatch list` | All tasks, newest first: id, age, status, prompt. |
+| `gemcatch export` | Concatenates finished results, each under its prompt, to stdout or a file (Markdown or JSON). |
+| `gemcatch digest` | Feeds a tag's completed results through one Gemini call into a single summary. |
 | `gemcatch watch <id>` | Polls until the task finishes, then prints the result. |
 | `gemcatch sync` | Refreshes every in-flight task in one pass. |
 | `gemcatch daemon` | Keeps polling in-flight tasks on a loop, so results are cached before they expire. |
@@ -97,15 +99,20 @@ Useful flags:
 | --- | --- | --- |
 | `--json` | most commands | Machine-readable output. |
 | `-m, --model <id>` | `research`, `batch` | Override the model. |
+| `-a, --agent <id>` | `research`, `batch` | Submit to a [research agent](#research-agents) instead of a model. Mutually exclusive with `--model`. |
+| `--yes` | `research`, `batch` | Confirm the agent cost without asking. Required for `--agent` when stdin is not a TTY. |
 | `-s, --system <text>` | `research`, `batch` | Set a system instruction. |
 | `-f, --file <path>` | `research` | Read the prompt from a file. |
 | `-t, --tag <tag>` | `research`, `batch`, `list` | Label tasks and filter them. |
 | `-w, --watch` | `research`, `batch` | Submit and wait, in one command. |
 | `--separator <str>` | `batch` | Split the file on this delimiter line for multi-line prompts. |
-| `-i, --interval <s>` | `watch`, `daemon` | Poll rate. Default 10s for `watch`, 300s for `daemon`. |
+| `-i, --interval <s>` | `watch`, `daemon` | Poll rate in seconds; must be > 0. Default 10s for `watch`, 300s for `daemon`. |
 | `--exit-when-idle` | `daemon` | Stop once nothing is left in flight. |
-| `-n, --limit <n>` | `list` | Cap the rows. |
-| `--dry-run` | `batch`, `prune` | Show what would go; submit/delete nothing. |
+| `--status <s>` | `list`, `export` | Only tasks in this status. |
+| `-n, --limit <n>` | `list` | Cap the rows (non-negative; `0` shows none). |
+| `--format <md\|json>` | `export` | Output format. Default `md`. |
+| `-o, --out <file>` | `export` | Write to a file instead of stdout. |
+| `--dry-run` | `research`, `batch`, `prune` | Show what would go — including the projected agent spend; submit/delete nothing. |
 | `--raw` | `get` | Dump the raw interaction JSON. |
 
 IDs are the first 8 characters of a UUID. Any unique prefix works, so `gemcatch get 8f3a` is fine.
@@ -117,10 +124,15 @@ Statuses come straight from the API: `in_progress`, `requires_action`, `complete
 ```bash
 # Fire off a whole file of prompts in one command, then collect later.
 # Every task shares one auto-generated tag (batch-xxxxxx), printed on submit.
-$ gemcatch batch questions.txt        # one prompt per line; # and blanks skipped
+$ gemcatch batch questions.txt        # one prompt per line; "# " and blanks skipped
 $ gemcatch daemon --exit-when-idle    # keep polling until they're all in
 $ gemcatch list --tag batch-1a2b3c --status completed
 
+# Collect a whole batch into one document (the "gather" for batch's "scatter").
+$ gemcatch export --tag batch-1a2b3c -o results.md   # Markdown, one section per prompt
+$ gemcatch export --tag batch-1a2b3c --format json | jq -r '.[].result'
+$ gemcatch digest --tag batch-1a2b3c                 # or synthesize them into one summary
+
 # Multi-line prompts: split the file on a delimiter line instead of per-line
 $ gemcatch batch briefs.md --separator ---
 $ gemcatch batch - < questions.txt    # or pipe the list in on stdin
@@ -143,6 +155,46 @@ $ id=$(gemcatch research "..." --json | jq -r .id)
 $ gemcatch watch "$id" --json | jq -r .result
 ```
 
+## Research agents
+
+The [Gemini Deep Research agents](https://ai.google.dev/gemini-api/docs/deep-research) are reachable only through the Interactions API, and the docs are explicit: *"You must use background execution (set `background=true`) to run the agent asynchronously and poll for results or stream updates."* That is precisely the half of the job `gemcatch` already does — it always sets `background: true`, owns the polling, and its daemon collects results before the free tier drops interactions after **1 day** (paid tier: 55 days). A Deep Research run takes minutes and you were never going to sit there holding the connection; submit it, and let the daemon catch it.
+
+```console
+$ gemcatch research "map the EU AI Act high-risk obligations against the UK approach" --agent deep-research
+Agent deep-research-preview-04-2026 — estimated $1.00–$3.00 for this task (preview rates, subject to change).
+Submit? [y/N] y
+Task 8f3a1c04 submitted. Run: gemcatch get 8f3a1c04 when ready.
+```
+
+`--agent` takes an alias or a raw agent id:
+
+| You type | Sent to the API |
+| --- | --- |
+| `deep-research` | `deep-research-preview-04-2026` |
+| `deep-research-max` | `deep-research-max-preview-04-2026` |
+| anything else | passed through unchanged (future agent ids work without a gemcatch release; a bad id fails fast with the API's own 4xx) |
+
+An agent is sent **instead of** a model — the agent picks its own models — so `--model` and `--agent` together is an error, and nothing is submitted.
+
+**These agents cost real money, per task.** The docs put Deep Research at **$1.00–$3.00 per task** and Deep Research Max at **$3.00–$7.00 per task** — with their own hedge attached: *"These figures are estimates based on preview rates and are subject to change."* Because `gemcatch batch` fires a whole file at once, a 20-line file against `deep-research-max` is a **$60–$140 command**, so every agent submission shows its band and asks first. In a script (stdin not a TTY) you must pass `--yes`; `--dry-run` prints the full projected spend and submits nothing:
+
+```console
+$ gemcatch batch questions.txt --agent deep-research-max --dry-run
+20 prompts × deep-research-max-preview-04-2026 — estimated $60.00–$140.00 total. Nothing submitted (--dry-run).
+```
+
+The report lands like any other result — final answer only, none of the agent's interim plan — and its **citations** come with it. The docs tell you to review them to verify the sources, so `gemcatch get` prints them under the report as a `Sources:` list, `--json` carries them as an array, and they live in the store alongside the result.
+
+An agent run can also come back `incomplete` — that is what a `max_total_tokens` budget cap produces when the run "safely pauses" — which `gemcatch` treats as terminal, exactly like the API does: the daemon retires it and moves on.
+
+The agent recipe, end to end:
+
+```bash
+$ gemcatch batch questions.txt --agent deep-research --yes   # bands shown, N × total quoted
+$ gemcatch daemon --exit-when-idle                           # catch reports before the 1-day expiry
+$ gemcatch export --tag batch-1a2b3c -o reports.md           # every report, with its sources
+```
+
 ## How it works
 
 Tasks live in SQLite at `~/.gemcatch/tasks.db` (override with `GEMCATCH_HOME`):
@@ -150,7 +202,7 @@ Tasks live in SQLite at `~/.gemcatch/tasks.db` (override with `GEMCATCH_HOME`):
 ```sql
 CREATE TABLE tasks (id TEXT PRIMARY KEY, prompt TEXT, interaction_id TEXT,
                     status TEXT DEFAULT 'pending', result TEXT, created_at INTEGER);
--- plus model, system_instruction, tag, error, usage, updated_at
+-- plus model, system_instruction, tag, error, usage, updated_at, agent, citations
 ```
 
 `research` calls `interactions.create({model, input, background: true})` via [`@google/genai`](https://www.npmjs.com/package/@google/genai) and keeps the returned `id`. The polling commands call `interactions.get(id)` and write the status back. Once a task completes, the text is cached in the `result` column — `gemcatch get` then answers from disk without touching the network.
@@ -182,10 +234,14 @@ $ gemcatch daemon --exit-when-idle -i 30
 $ gemcatch list --tag batch1 --status completed
 ```
 
+If a task's interaction has vanished server-side — the free tier dropped it after 24h, or it was deleted — polling it returns a 404. Rather than chase a task that can never resolve, `gemcatch` retires it locally to `incomplete`, so it leaves the in-flight set and `--exit-when-idle` still converges. `watch` and `batch -w` also give up after a bounded run of consecutive poll failures (`GEMCATCH_WATCH_MAX_FAILS`, default 10) instead of looping forever.
+
 ## Rate limits and retries
 
 The free tier allows roughly 15 requests a minute, which a wide `gemcatch sync` or a busy daemon would otherwise blow straight through. Every outbound call is paced to `GEMCATCH_RPM` (default 15) — set it higher on a paid key, or `0` to disable pacing entirely.
 
+Pacing is **per process**: each `gemcatch` invocation keeps its own counter, so two running at once (a `daemon` in one terminal and a one-off `sync` in another) can together exceed the ceiling. If you need the limit to hold, run a single daemon and let it do the polling.
+
 Transient failures are retried with exponential backoff and full jitter, honouring `Retry-After` when the server sends it. A rate limit, a timeout or a 5xx gets `GEMCATCH_MAX_RETRIES` more attempts (default 4); a 4xx does not, because a bad key or a bad model id fails identically forever and retrying it only burns your quota.
 
 ## Environment variables
@@ -194,11 +250,12 @@ Transient failures are retried with exponential backoff and full jitter, honouri
 | --- | --- |
 | `GEMINI_API_KEY` | Your API key. `GOOGLE_API_KEY` also works. |
 | `GEMCATCH_HOME` | Where `tasks.db` lives. Default `~/.gemcatch`. |
-| `GEMCATCH_MODEL` | Default model. Default `gemini-3.1-flash-lite`. |
+| `GEMCATCH_MODEL` | Default model. Default `gemini-3.5-flash-lite`. |
 | `GEMCATCH_POLL_MS` | `watch` poll interval in ms. Default `10000`. |
 | `GEMCATCH_DAEMON_S` | `daemon` interval in seconds. Default `300`. |
 | `GEMCATCH_RPM` | Requests/minute ceiling. Default `15` (the free tier). `0` disables pacing. |
 | `GEMCATCH_MAX_RETRIES` | Extra attempts on a transient failure. Default `4`. `0` disables retries. |
+| `GEMCATCH_WATCH_MAX_FAILS` | Consecutive poll failures before `watch`/`batch -w` give up. Default `10`. |
 | `GEMCATCH_BASE_URL` | Override the API endpoint (proxy/gateway/testing). |
 | `GEMCATCH_FORCE_REST` | `1` bypasses the SDK and uses raw `fetch`. |
 | `NO_COLOR` | Disable colour output. |

package/db.js

@@ -26,6 +26,11 @@ const MIGRATIONS = [
   ['error', 'TEXT'],
   ['usage', 'TEXT'],
   ['updated_at', 'INTEGER'],
+  // 0.4.0: agent runs. `agent` is the resolved agent id the task was submitted
+  // with (NULL for model runs, including every pre-0.4.0 row); `citations` is
+  // the JSON array of sources an agent run returned alongside its report.
+  ['agent', 'TEXT'],
+  ['citations', 'TEXT'],
 ];
 
 let _db = null;
@@ -59,8 +64,8 @@ function createTask(fields) {
   const now = Date.now();
   db()
     .prepare(
-      'INSERT INTO tasks (id, prompt, status, created_at, updated_at, model, system_instruction, tag) ' +
-        'VALUES (@id, @prompt, @status, @now, @now, @model, @system_instruction, @tag)'
+      'INSERT INTO tasks (id, prompt, status, created_at, updated_at, model, system_instruction, tag, agent) ' +
+        'VALUES (@id, @prompt, @status, @now, @now, @model, @system_instruction, @tag, @agent)'
     )
     .run({
       id,
@@ -70,6 +75,7 @@ function createTask(fields) {
       model: t.model || null,
       system_instruction: t.systemInstruction || null,
       tag: t.tag || null,
+      agent: t.agent || null,
     });
   return id;
 }
@@ -101,7 +107,7 @@ function setStatus(id, status, extra) {
   const e = extra || {};
   const sets = ['status = @status', 'updated_at = @now'];
   const params = { id, status, now: Date.now() };
-  for (const key of ['result', 'error', 'usage']) {
+  for (const key of ['result', 'error', 'usage', 'citations']) {
     if (e[key] !== undefined) {
       sets.push(`${key} = @${key}`);
       params[key] = e[key];
@@ -125,7 +131,10 @@ function listTasks(opts) {
   let sql = 'SELECT * FROM tasks';
   if (where.length) sql += ` WHERE ${where.join(' AND ')}`;
   sql += ' ORDER BY created_at DESC';
-  if (o.limit) {
+  // Presence, not truthiness: `--limit 0` is a real cap (return nothing), so it
+  // must not be treated the same as "no limit given". The caller validates that
+  // it is a non-negative integer before we get here.
+  if (o.limit != null) {
     sql += ' LIMIT @limit';
     params.limit = o.limit;
   }
@@ -164,6 +173,14 @@ function counts() {
   return db().prepare('SELECT status, COUNT(*) AS n FROM tasks GROUP BY status').all();
 }
 
+// Per-agent totals for `stats`. Model runs (agent IS NULL) are not a row here;
+// they are already accounted for in counts().
+function agentCounts() {
+  return db()
+    .prepare('SELECT agent, COUNT(*) AS n FROM tasks WHERE agent IS NOT NULL GROUP BY agent')
+    .all();
+}
+
 function close() {
   if (_db) _db.close();
   _db = null;
@@ -182,5 +199,6 @@ module.exports = {
   removeMany,
   prunableTasks,
   counts,
+  agentCounts,
   close,
 };

package/gemini.js

@@ -3,7 +3,41 @@
 const { isDone, isSuccess } = require('./status');
 
 // Free of charge on the Gemini free tier; override per-call with --model.
-const DEFAULT_MODEL = process.env.GEMCATCH_MODEL || 'gemini-3.1-flash-lite';
+// gemini-3.5-flash-lite went GA on 2026-07-21 (it replaced 3.1 as the
+// low-latency free-tier workhorse in the same release that deprecated the
+// sampling parameters).
+const DEFAULT_MODEL = process.env.GEMCATCH_MODEL || 'gemini-3.5-flash-lite';
+
+// --- agents ---------------------------------------------------------------
+
+// The Deep Research agents are reachable ONLY through the Interactions API,
+// and only with background execution -- which gemcatch always sets. An agent
+// is sent as `agent` on create, INSTEAD of `model`: the two are mutually
+// exclusive, and the CLI rejects the combination before anything is written.
+//
+// This table is the ONE place the full preview ids live. They are preview ids
+// and will be superseded; call sites must resolve through here (or pass an
+// unknown id straight through, so a future agent works without a release).
+const AGENT_ALIASES = Object.freeze({
+  'deep-research': 'deep-research-preview-04-2026',
+  'deep-research-max': 'deep-research-max-preview-04-2026',
+});
+
+// Documented per-task price bands, in dollars, keyed by the RESOLVED id.
+// The docs' own hedge applies -- "These figures are estimates based on
+// preview rates and are subject to change" -- so the spend guard quotes
+// them as estimates, never as authoritative.
+const AGENT_PRICE_BANDS = Object.freeze({
+  'deep-research-preview-04-2026': Object.freeze([1, 3]),
+  'deep-research-max-preview-04-2026': Object.freeze([3, 7]),
+});
+
+// A known alias resolves to its full preview id; anything else passes through
+// unchanged so a new or newer agent id works without a gemcatch release (a
+// genuinely bad id fails fast: the API 4xxes, and a 4xx never retries).
+function resolveAgent(id) {
+  return AGENT_ALIASES[id] || id;
+}
 
 // Overridable for tests and for routing via a proxy/gateway.
 const REST_BASE =
@@ -163,7 +197,11 @@ function collectText(node, acc) {
     return acc;
   }
   if (typeof node.text === 'string' && node.text.trim()) acc.push(node.text);
-  for (const v of Object.values(node)) {
+  for (const [k, v] of Object.entries(node)) {
+    // Citations are sources *about* the answer, not answer text: an agent step
+    // carries them alongside its content, and a citation's own title/snippet
+    // must not be concatenated into the result. They are collected separately.
+    if (k === 'citations') continue;
     if (v && typeof v === 'object') collectText(v, acc);
   }
   return acc;
@@ -173,21 +211,65 @@ function collectText(node, acc) {
 // internal reasoning with the actual answer, each tagged by `type`:
 //   [ {type:'user_input', ...}, {type:'thought', ...}, {type:'model_output', ...} ]
 // Collecting text indiscriminately prepends the prompt (and any reasoning) to
-// the result, so those step types are skipped. Anything else -- model_output,
-// an untyped step, a future answer-bearing type -- still contributes, so a
-// renamed step never silently blanks the result.
+// the result, so those step types are skipped.
+//
+// Both kinds of run put the deliverable in the FINAL answer-bearing step. A
+// model run ends [user_input, thought, model_output]; an agent run's steps
+// additionally interleave its plan, searches and interim drafts, and the docs
+// place the finished report at `interaction.steps[-1].content[0].text`. So one
+// rule serves both, with no special-casing on the agent id: take the last step
+// that is not user_input/thought. If that step somehow carries no text -- an
+// unexpected shape, a renamed type -- fall back to collecting across every
+// answer-bearing step, so the failure mode is "too much text", never a
+// silently blank result.
 const NON_ANSWER_STEP = new Set(['user_input', 'thought']);
 
 function textFromSteps(steps) {
   if (!Array.isArray(steps)) return '';
+  const candidates = steps.filter((s) => !(s && NON_ANSWER_STEP.has(s.type)));
+  if (!candidates.length) return '';
+  const last = collectText(candidates[candidates.length - 1], []).join('\n').trim();
+  if (last) return last;
   const acc = [];
-  for (const step of steps) {
-    if (step && NON_ANSWER_STEP.has(step.type)) continue;
-    collectText(step, acc);
-  }
+  for (const step of candidates) collectText(step, acc);
   return acc.join('\n').trim();
 }
 
+// Agent runs carry citations -- the docs explicitly tell users to review them
+// to verify the sources -- so they are gathered rather than discarded. The
+// walk is shape-agnostic (any `citations` array anywhere in the interaction),
+// because the docs do not pin down where they attach; duplicates are dropped.
+function collectCitations(node, acc) {
+  if (!node || typeof node !== 'object') return acc;
+  if (Array.isArray(node)) {
+    for (const n of node) collectCitations(n, acc);
+    return acc;
+  }
+  for (const [k, v] of Object.entries(node)) {
+    if (k === 'citations' && Array.isArray(v)) {
+      for (const c of v) if (c && typeof c === 'object') acc.push(c);
+      continue;
+    }
+    if (v && typeof v === 'object') collectCitations(v, acc);
+  }
+  return acc;
+}
+
+function citationsOf(interaction) {
+  const all = collectCitations(interaction, []);
+  if (!all.length) return null;
+  const seen = new Set();
+  const out = [];
+  for (const c of all) {
+    const key = JSON.stringify(c);
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(c);
+    }
+  }
+  return out;
+}
+
 function textOf(interaction) {
   if (interaction && typeof interaction.output_text === 'string' && interaction.output_text) {
     return interaction.output_text;
@@ -200,6 +282,7 @@ function shape(r) {
     interactionId: r.id,
     status: r.status,
     text: textOf(r),
+    citations: citationsOf(r),
     usage: r.usage || null,
     raw: r,
   };
@@ -269,7 +352,13 @@ function restHeaders() {
 
 async function submit(prompt, opts) {
   const o = opts || {};
-  const body = { model: o.model || DEFAULT_MODEL, input: prompt, background: true };
+  // `agent` and `model` are mutually exclusive on create: an agent run is sent
+  // with `agent` INSTEAD of `model` (the agent picks its own models). `input`
+  // stays a plain string and `background` stays true either way -- agents
+  // *require* background execution, which gemcatch has always set.
+  const body = o.agent
+    ? { agent: o.agent, input: prompt, background: true }
+    : { model: o.model || DEFAULT_MODEL, input: prompt, background: true };
   if (o.systemInstruction) body.system_instruction = o.systemInstruction;
   const r = await call(() => {
     const api = sdkInteractions();
@@ -323,6 +412,9 @@ module.exports = {
   REST_BASE,
   RPM,
   MAX_RETRIES,
+  AGENT_ALIASES,
+  AGENT_PRICE_BANDS,
+  resolveAgent,
   submit,
   poll,
   cancel,
@@ -330,6 +422,7 @@ module.exports = {
   apiKey,
   textOf,
   collectText,
+  citationsOf,
   // Exported for the suite: the retry policy is behaviour worth pinning.
   shouldRetry,
   // Re-exported so callers need only one require.

package/index.js

@@ -13,20 +13,41 @@ const DEFAULT_POLL_MS = Number(process.env.GEMCATCH_POLL_MS) || 10000;
 // comfortably faster than that. Five minutes is far inside the margin and
 // costs a handful of requests an hour.
 const DEFAULT_DAEMON_S = Number(process.env.GEMCATCH_DAEMON_S) || 300;
+// A watch loop must not spin forever on a task the server can no longer resolve
+// -- a wedged in_progress, or transient poll errors that never clear. `watch`
+// and `batch -w` give up after this many *consecutive* poll failures (a clean
+// poll resets the run), surfacing a clear message and a non-zero exit instead
+// of hanging. The daemon, meant to run for days, is bounded differently: a 404
+// retires the task locally (see refresh) so it simply leaves the active set.
+const WATCH_MAX_FAILS = Number(process.env.GEMCATCH_WATCH_MAX_FAILS) || 10;
 const ALL_STATUSES = [PENDING].concat(ACTIVE, TERMINAL);
 
 // --- output ---------------------------------------------------------------
 
-const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
-const paint = (code, s) => (useColor ? `[${code}m${s}` : s);
+// Colour is decided per stream. Progress and status chatter go to stderr
+// (watch/daemon/research -w); results and tables go to stdout. Each stream keys
+// its ANSI on its *own* TTY-ness, so redirecting one (`gemcatch watch x > out.txt`)
+// neither strips colour from the other nor leaks raw escape codes into the
+// redirected file. NO_COLOR disables both.
+const NO_COLOR = !!process.env.NO_COLOR;
+const useColor = process.stdout.isTTY && !NO_COLOR; // stdout-bound colour
+const useColorErr = process.stderr.isTTY && !NO_COLOR; // stderr-bound colour
+
+const wrap = (on) => (code, s) => (on ? `[${code}m${s}` : s);
+const paint = wrap(useColor); // paints for stdout
+const epaint = wrap(useColorErr); // paints for stderr
 const dim = (s) => paint('2', s);
-
-function colorStatus(s) {
-  if (isSuccess(s)) return paint('32', s); // green
-  if (s === 'in_progress' || s === PENDING) return paint('36', s); // cyan
-  if (s === 'requires_action') return paint('33', s); // yellow
-  return paint('31', s); // red: failed/cancelled/incomplete/budget_exceeded
+const edim = (s) => epaint('2', s);
+
+// Status colour keyed to a given painter, so one rule set serves both streams.
+function tint(pnt, s) {
+  if (isSuccess(s)) return pnt('32', s); // green
+  if (s === 'in_progress' || s === PENDING) return pnt('36', s); // cyan
+  if (s === 'requires_action') return pnt('33', s); // yellow
+  return pnt('31', s); // red: failed/cancelled/incomplete/budget_exceeded
 }
+const colorStatus = (s) => tint(paint, s); // for stdout
+const ecolorStatus = (s) => tint(epaint, s); // for stderr
 
 const hhmmss = () => new Date().toISOString().slice(11, 19);
 
@@ -68,6 +89,104 @@ function needTask(id) {
   return task;
 }
 
+// Citations ride along with an agent's report -- the docs tell users to review
+// them to verify the sources, so they are printed under the result rather than
+// left in the database. A run without citations prints exactly as before.
+function withSources(text, citations) {
+  const body = text || '(empty response)';
+  if (!Array.isArray(citations) || !citations.length) return body;
+  const lines = citations.map((c, i) => {
+    const title = (c && (c.title || c.text)) || '';
+    const url = (c && (c.url || c.uri)) || '';
+    return `  [${i + 1}] ${[title, url].filter(Boolean).join(' — ') || JSON.stringify(c)}`;
+  });
+  return `${body}\n\nSources:\n${lines.join('\n')}`;
+}
+
+// The citations column holds JSON (or NULL). Parsed defensively: a corrupt row
+// degrades to "no sources", never a crash in the middle of printing a result.
+function parseCitations(raw) {
+  if (!raw) return null;
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) && v.length ? v : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// --- spend guard ----------------------------------------------------------
+
+// Deep Research agents are billed PER TASK, not per token -- the docs put
+// Deep Research at $1.00-$3.00 and Deep Research Max at $3.00-$7.00 -- and
+// gemcatch's whole ergonomic is firing a file of prompts at once, which turns
+// one careless `batch --agent` into a three-figure command. So no agent
+// submission happens without the cost being shown and confirmed: interactively
+// on a TTY, via --yes otherwise, and --dry-run previews without submitting.
+// The bands are quoted with the docs' own hedge ("estimates based on preview
+// rates and subject to change"), never as authoritative.
+
+function bandText(agentId, count) {
+  const band = gemini.AGENT_PRICE_BANDS[agentId];
+  if (!band) return 'no published price band for this agent';
+  const money = (n) => `$${(n * count).toFixed(2)}`;
+  return count > 1
+    ? `estimated ${money(band[0])}–${money(band[1])} total`
+    : `estimated ${money(band[0])}–${money(band[1])} for this task`;
+}
+
+function spendLine(agentId, count) {
+  const head = count > 1 ? `${count} prompts × ${agentId}` : `Agent ${agentId}`;
+  return `${head} — ${bandText(agentId, count)}`;
+}
+
+function askYesNo(question) {
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test((answer || '').trim()));
+    });
+  });
+}
+
+// Returns only when the submission is confirmed; otherwise it exits (declined)
+// or throws (no way to ask). Runs BEFORE any row is written, so a declined or
+// refused submission leaves the tasks table untouched.
+async function confirmSpend(agentId, count, opts) {
+  console.error(`${spendLine(agentId, count)} (preview rates, subject to change).`);
+  if (opts.yes) return;
+  // GEMCATCH_ASSUME_TTY lets the offline suite drive the interactive branch
+  // through a pipe; real non-TTY callers (cron, CI, scripts) must say --yes.
+  const interactive = process.stdin.isTTY || process.env.GEMCATCH_ASSUME_TTY === '1';
+  if (!interactive) {
+    throw new Error(
+      'stdin is not a TTY, so this agent submission cannot be confirmed interactively.\n' +
+        '  Pass --yes to confirm the cost above, or --dry-run to preview without submitting.'
+    );
+  }
+  if (!(await askYesNo('Submit? [y/N] '))) {
+    console.error('Nothing submitted.');
+    process.exit(1);
+  }
+}
+
+// Shared by research and batch: resolve the agent alias and reject the
+// ambiguous combination before anything is stored or sent. `--model` counts
+// only when the user actually typed it -- commander fills in the default
+// otherwise, and the default must not poison every agent run.
+function resolveAgentOpts(opts, cmd) {
+  if (!opts.agent) return null;
+  if (cmd.getOptionValueSource('model') === 'cli') {
+    throw new Error(
+      '--model and --agent are mutually exclusive: an agent run is submitted with `agent` ' +
+        'instead of `model`, and the agent picks its own models. Drop one of the two.'
+    );
+  }
+  return gemini.resolveAgent(opts.agent);
+}
+
 // --- input ----------------------------------------------------------------
 
 function readStdin() {
@@ -100,11 +219,30 @@ async function resolvePrompt(arg, opts) {
 // Poll one task and persist whatever came back.
 async function refresh(task) {
   if (!task.interaction_id) return { status: task.status, text: null, usage: null };
-  const r = await gemini.poll(task.interaction_id);
+  let r;
+  try {
+    r = await gemini.poll(task.interaction_id);
+  } catch (err) {
+    // A 404 is genuine and permanent: the interaction is gone -- dropped after
+    // the free tier's 24h retention, or deleted -- and it will 404 identically
+    // forever (a 4xx never retries). Retire the task locally so it leaves the
+    // active set, instead of the daemon or a watch loop polling a ghost until
+    // the end of time. Any other error (5xx, network) is transient and is
+    // re-thrown for the caller to retry on its next pass.
+    if (err && err.httpStatus === 404) {
+      store.setStatus(task.id, 'incomplete', { error: 'interaction not found (expired or deleted)' });
+      return { status: 'incomplete', text: null, usage: null, raw: null };
+    }
+    throw err;
+  }
   const extra = {};
   if (isDone(r.status)) {
-    if (isSuccess(r.status)) extra.result = r.text;
-    else if (r.text) extra.error = r.text;
+    if (isSuccess(r.status)) {
+      extra.result = r.text;
+      // Agent runs return citations with the report; the docs tell users to
+      // review them to verify the sources, so they are persisted, not dropped.
+      if (r.citations && r.citations.length) extra.citations = JSON.stringify(r.citations);
+    } else if (r.text) extra.error = r.text;
   }
   if (r.usage) extra.usage = JSON.stringify(r.usage);
   store.setStatus(task.id, r.status, extra);
@@ -141,28 +279,41 @@ program
   .argument('[prompt]', 'what you want researched; "-" reads stdin')
   .option('-f, --file <path>', 'read the prompt from a file')
   .option('-m, --model <id>', 'model to use', gemini.DEFAULT_MODEL)
+  .option('-a, --agent <id>', 'submit to a research agent instead of a model (e.g. deep-research)')
   .option('-s, --system <text>', 'system instruction')
   .option('-t, --tag <tag>', 'label for filtering with `gemcatch list --tag`')
   .option('-w, --watch', 'wait for the result instead of exiting')
+  .option('--yes', 'confirm the agent cost without asking (required when stdin is not a TTY)')
+  .option('--dry-run', 'show what would be submitted (and what it would cost); submit nothing')
   .option('--json', 'machine-readable output')
   .description('submit a background task and exit immediately')
-  .action(async (promptArg, opts) => {
+  .action(async (promptArg, opts, cmd) => {
     let id;
     try {
+      const agent = resolveAgentOpts(opts, cmd);
       const prompt = await resolvePrompt(promptArg, opts);
+      if (opts.dryRun) {
+        emit(opts.json, { dry_run: true, agent: agent || null, model: agent ? null : opts.model, prompt }, () => {
+          if (agent) console.log(`${spendLine(agent, 1)}. Nothing submitted (--dry-run).`);
+          else console.log(`Would submit to ${opts.model}: ${snippet(prompt)}. Nothing submitted (--dry-run).`);
+        });
+        return;
+      }
+      if (agent) await confirmSpend(agent, 1, opts);
       id = store.createTask({
         prompt,
-        model: opts.model,
+        model: agent ? null : opts.model,
+        agent,
         systemInstruction: opts.system,
         tag: opts.tag,
       });
-      const r = await gemini.submit(prompt, { model: opts.model, systemInstruction: opts.system });
+      const r = await gemini.submit(prompt, { model: opts.model, agent, systemInstruction: opts.system });
       store.setInteraction(id, r.interactionId, r.status);
       if (opts.watch) {
         // Under --watch the submit line is progress, not the answer, so it
         // goes to stderr -- `gemcatch research -w "..." > out.txt` then captures
         // only the result.
-        if (!opts.json) console.error(dim(`Task ${id} submitted.`));
+        if (!opts.json) console.error(edim(`Task ${id} submitted.`));
         await watchTask(store.getTask(id), DEFAULT_POLL_MS, opts.json);
         return;
       }
@@ -170,16 +321,29 @@ program
         console.log(`Task ${id} submitted. Run: gemcatch get ${id} when ready.`)
       );
     } catch (err) {
-      if (id) store.setStatus(id, 'failed', { error: err.message });
+      // Only a failed *submit* should mark the task failed. Once it has an
+      // interaction_id it is live on the server, and a later watch/poll error
+      // must never overwrite it to failed -- that would drop it from the active
+      // set and the daemon would abandon a task whose result is still coming.
+      // Leave it active; the daemon (or a later `get`) collects it.
+      if (id) {
+        const t = store.getTask(id);
+        if (!t || !t.interaction_id) store.setStatus(id, 'failed', { error: err.message });
+      }
       die(err);
     }
   });
 
 // --- batch ----------------------------------------------------------------
 
-// Turn a prompts file into a list of prompts. Default: one per line, skipping
-// blank lines and `#` comments. With --separator, split the whole file on that
+// Turn a prompts file into a list of prompts, plus a count of the lines it
+// dropped so the caller can note them. Default: one per line, skipping blank
+// lines and `#` comments. With --separator, split the whole file on that
 // delimiter line instead, so a single prompt can span multiple lines.
+//
+// A `#` is a comment only when followed by whitespace (`# like this`). A line
+// such as `#1 cause of X?` is a real prompt, not a comment, and must survive --
+// treating every leading `#` as a comment silently swallowed those.
 function parsePrompts(text, separator) {
   if (separator) {
     const blocks = [];
@@ -193,12 +357,20 @@ function parsePrompts(text, separator) {
       }
     }
     blocks.push(cur.join('\n').trim());
-    return blocks.filter(Boolean);
+    const prompts = blocks.filter(Boolean);
+    return { prompts, skipped: blocks.length - prompts.length };
+  }
+  // The file almost always ends in a newline; that trailing empty line is not a
+  // blank the user wrote, so it does not count towards the skipped tally.
+  const lines = text.split(/\r?\n/).map((l) => l.trim());
+  while (lines.length && lines[lines.length - 1] === '') lines.pop();
+  const prompts = [];
+  let skipped = 0;
+  for (const l of lines) {
+    if (!l || /^#\s/.test(l)) skipped += 1;
+    else prompts.push(l);
   }
-  return text
-    .split(/\r?\n/)
-    .map((l) => l.trim())
-    .filter((l) => l && !l.startsWith('#'));
+  return { prompts, skipped };
 }
 
 // Poll just this batch until nothing tagged with it is still in flight, then
@@ -207,11 +379,25 @@ function parsePrompts(text, separator) {
 async function watchBatch(tag, intervalMs, json) {
   const inFlight = () => store.listTasks({ tag }).filter((t) => t.interaction_id && !isDone(t.status));
   let pending = inFlight();
+  let stalls = 0; // consecutive passes that resolved nothing
   while (pending.length) {
     // A poll that throws keeps the task's old status; the next pass retries it.
+    // A 404 retires the task inside refresh, so it drops out of `inFlight`.
     await mapLimit(pending, 4, (t) => refresh(t).catch(() => {}));
-    pending = inFlight();
-    if (pending.length) await new Promise((r) => setTimeout(r, intervalMs));
+    const next = inFlight();
+    // Forward progress = the in-flight set shrank. A pass that resolves nothing
+    // -- every poll erroring, or a wedged in_progress that never moves -- is a
+    // stall; enough of those in a row means give up rather than loop forever.
+    stalls = next.length < pending.length ? 0 : stalls + 1;
+    pending = next;
+    if (!pending.length) break;
+    if (stalls >= WATCH_MAX_FAILS) {
+      const msg = `Batch ${tag}: gave up after ${stalls} passes with no progress; ${pending.length} task(s) unresolved.`;
+      emit(json, { tag, error: msg, unresolved: pending.length }, () => console.error(edim(msg)));
+      process.exitCode = 1;
+      return;
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
   }
   const tasks = store.listTasks({ tag });
   const completed = tasks.filter((t) => isSuccess(t.status)).length;
@@ -225,35 +411,52 @@ program
   .command('batch')
   .argument('<file>', 'prompts file — one per line, or "-" to read stdin')
   .option('-m, --model <id>', 'model to use', gemini.DEFAULT_MODEL)
+  .option('-a, --agent <id>', 'submit every prompt to a research agent instead of a model')
   .option('-s, --system <text>', 'system instruction')
   .option('-t, --tag <tag>', 'tag the whole batch (default: batch-<hex>)')
   .option('--separator <str>', 'split the file on this delimiter line for multi-line prompts')
   .option('-w, --watch', 'submit all, then poll until the whole batch finishes')
+  .option('--yes', 'confirm the agent cost without asking (required when stdin is not a TTY)')
   .option('--dry-run', 'parse and list what would be submitted; submit nothing')
   .option('--json', 'machine-readable output')
   .description('submit many background tasks from a file, tagged as one batch')
-  .action(async (file, opts) => {
+  .action(async (file, opts, cmd) => {
     try {
+      const agent = resolveAgentOpts(opts, cmd);
       const text = file === '-' ? await readStdin() : fs.readFileSync(file, 'utf8');
-      const prompts = parsePrompts(text, opts.separator);
+      const { prompts, skipped } = parsePrompts(text, opts.separator);
       if (!prompts.length) throw new Error(`no prompts found in ${file === '-' ? 'stdin' : file}`);
+      // A one-line heads-up so a swallowed prompt (or a stray comment) is never a
+      // silent mystery. Goes to stderr so it can't corrupt --json on stdout.
+      if (skipped) {
+        console.error(edim(`(skipped ${skipped} blank/comment line${skipped === 1 ? '' : 's'})`));
+      }
       // Auto-tag so the batch is collectable as a unit; a user tag wins.
       const tag = opts.tag || `batch-${crypto.randomUUID().slice(0, 6)}`;
 
       if (opts.dryRun) {
-        emit(opts.json, { tag, dry_run: true, prompts }, () => {
-          console.log(`Batch ${tag}: ${prompts.length} prompt(s) would be submitted:`);
-          for (const p of prompts) console.log(`  ${snippet(p)}`);
+        emit(opts.json, { tag, dry_run: true, agent: agent || null, prompts }, () => {
+          if (agent) {
+            // The whole point of the guard: N × the per-task band, up front.
+            console.log(`${spendLine(agent, prompts.length)}. Nothing submitted (--dry-run).`);
+          } else {
+            console.log(`Batch ${tag}: ${prompts.length} prompt(s) would be submitted:`);
+            for (const p of prompts) console.log(`  ${snippet(p)}`);
+          }
         });
         return;
       }
 
+      // An agent batch multiplies a per-task dollar band by the whole file, so
+      // it is confirmed as one total before a single row is written.
+      if (agent) await confirmSpend(agent, prompts.length, opts);
+
       // One failed submit must not sink the batch: mark that task failed and
       // keep going. mapLimit preserves input order, so the report is stable.
       const results = await mapLimit(prompts, 4, async (prompt) => {
-        const id = store.createTask({ prompt, model: opts.model, systemInstruction: opts.system, tag });
+        const id = store.createTask({ prompt, model: agent ? null : opts.model, agent, systemInstruction: opts.system, tag });
         try {
-          const r = await gemini.submit(prompt, { model: opts.model, systemInstruction: opts.system });
+          const r = await gemini.submit(prompt, { model: opts.model, agent, systemInstruction: opts.system });
           store.setInteraction(id, r.interactionId, r.status);
           return { id, interaction_id: r.interactionId, status: r.status, prompt };
         } catch (err) {
@@ -321,18 +524,22 @@ program
     const task = needTask(id);
     try {
       // Completed tasks are served from SQLite -- no network, and it still
-      // works after the free tier drops the interaction at 24h.
-      if (isSuccess(task.status) && task.result && !opts.raw) {
-        emit(opts.json, { id: task.id, status: task.status, result: task.result }, () =>
-          console.log(task.result)
+      // works after the free tier drops the interaction at 24h. Gate on the
+      // result being *present*, not truthy: a task that completes with empty
+      // text stores `''`, which is exactly the case the cache must still serve
+      // -- re-polling it would 404 after 24h, the very thing we cache to avoid.
+      if (isSuccess(task.status) && task.result != null && !opts.raw) {
+        const cits = parseCitations(task.citations);
+        emit(opts.json, { id: task.id, status: task.status, result: task.result, citations: cits }, () =>
+          console.log(withSources(task.result, cits))
         );
         return;
       }
       const r = await refresh(task);
       if (opts.raw) return console.log(JSON.stringify(r.raw, null, 2));
       if (isSuccess(r.status)) {
-        emit(opts.json, { id: task.id, status: r.status, result: r.text }, () =>
-          console.log(r.text || '(empty response)')
+        emit(opts.json, { id: task.id, status: r.status, result: r.text, citations: r.citations || null }, () =>
+          console.log(withSources(r.text, r.citations))
         );
       } else if (isDone(r.status)) {
         emit(opts.json, { id: task.id, status: r.status, error: r.text || null }, () =>
@@ -360,21 +567,144 @@ program
   .option('--json', 'machine-readable output')
   .description('all tasks, newest first')
   .action((opts) => {
+    // `-n 0` is a valid cap (show nothing); a negative would become SQLite's
+    // "no limit" (LIMIT -1 = all rows), so reject anything but a non-negative int.
+    if (opts.limit != null && (!Number.isInteger(opts.limit) || opts.limit < 0)) {
+      return die(new Error(`--limit must be a non-negative integer (got ${opts.limit})`));
+    }
     const tasks = store.listTasks({ status: opts.status, tag: opts.tag, limit: opts.limit });
     if (opts.json) return console.log(JSON.stringify(tasks, null, 2));
     if (!tasks.length) {
       console.log('No tasks yet. Submit one:  gemcatch research "your question"');
       return;
     }
-    console.log(dim('ID        AGE   STATUS           PROMPT'));
+    // The AGENT column only appears when something in the listing used one, so
+    // a pure-model store keeps the compact four-column layout it always had.
+    // Agent ids are shown compact -- the "-preview-MM-YYYY" suffix is version
+    // noise in a table (the full id is in --json and in stats).
+    const showAgent = tasks.some((t) => t.agent);
+    const shortAgent = (a) => (a ? a.replace(/-preview-\d{2}-\d{4}$/, '') : '-');
+    console.log(dim(`ID        AGE   STATUS           ${showAgent ? 'AGENT              ' : ''}PROMPT`));
     for (const t of tasks) {
       const snip = snippet(t.prompt);
       const status = t.status || PENDING;
       // Pad before colouring: ANSI codes would break the column width.
       const pad = ' '.repeat(Math.max(0, 16 - status.length));
+      const agentCol = showAgent ? `${shortAgent(t.agent).padEnd(18)} ` : '';
       console.log(
-        `${t.id}  ${age(t.created_at).padEnd(4)}  ${colorStatus(status)}${pad} ${snip}`
+        `${t.id}  ${age(t.created_at).padEnd(4)}  ${colorStatus(status)}${pad} ${agentCol}${snip}`
+      );
+    }
+  });
+
+// --- export ---------------------------------------------------------------
+
+// Collect many finished results into one document -- the "gather" that pairs
+// with `batch`'s "scatter". Where `get` prints one result at a time, `export`
+// concatenates a whole tag (or status) under prompt headings, to stdout or a
+// file, as Markdown (default) or JSON.
+program
+  .command('export')
+  .option('-t, --tag <tag>', 'only this tag')
+  .addOption(new Option('--status <status>', 'only this status').choices(ALL_STATUSES).default('completed'))
+  .addOption(new Option('--format <fmt>', 'output format').choices(['md', 'json']).default('md'))
+  .option('-o, --out <file>', 'write to a file instead of stdout')
+  .description('concatenate finished results, each under its prompt, to stdout or a file')
+  .action((opts) => {
+    const tasks = store.listTasks({ tag: opts.tag, status: opts.status });
+    // Newest-first suits a listing, but an export reads top-to-bottom like a
+    // document, so oldest-first is the natural order here.
+    tasks.reverse();
+    // Only rows that actually carry a result are worth exporting: a status
+    // filter other than `completed` can match tasks that never stored text.
+    const rows = tasks.filter((t) => t.result != null);
+    if (!rows.length) {
+      // Nothing to write isn't an error, but say why so an empty -o file (or an
+      // empty pipe) isn't a mystery. The note goes to stderr, never the output.
+      console.error(`No ${opts.status} results to export${opts.tag ? ` for tag '${opts.tag}'` : ''}.`);
+      return;
+    }
+
+    let output;
+    if (opts.format === 'json') {
+      output = JSON.stringify(
+        rows.map((t) => ({
+          id: t.id,
+          tag: t.tag,
+          status: t.status,
+          prompt: t.prompt,
+          result: t.result,
+          created_at: t.created_at,
+        })),
+        null,
+        2
       );
+    } else {
+      output = rows
+        .map((t) => {
+          const when = new Date(t.created_at).toISOString().replace('T', ' ').slice(0, 16);
+          const head = (t.prompt || '(no prompt)').replace(/\s+/g, ' ').trim();
+          const body = t.result && t.result.trim() ? t.result : '_(empty result)_';
+          return `## ${head}\n\n\`${t.id}\` · ${t.status} · ${when} UTC\n\n${body}`;
+        })
+        .join('\n\n---\n\n');
+    }
+
+    if (opts.out) {
+      fs.writeFileSync(opts.out, output.endsWith('\n') ? output : `${output}\n`);
+      console.error(`Wrote ${rows.length} result(s) to ${opts.out}.`);
+    } else {
+      console.log(output);
+    }
+  });
+
+// --- digest ---------------------------------------------------------------
+
+// One step past `export`: instead of concatenating a tag's results, feed them
+// back through a single Gemini call and synthesise one summary. It is `research`
+// with a prompt built from what you have already collected, so it submits, then
+// watches to completion just like `research -w`.
+program
+  .command('digest')
+  .requiredOption('-t, --tag <tag>', 'synthesize the completed results under this tag')
+  .option('-m, --model <id>', 'model to use', gemini.DEFAULT_MODEL)
+  .option('-s, --system <text>', 'system instruction for the synthesis')
+  .option('--json', 'machine-readable output')
+  .description("feed a tag's completed results through one Gemini call into a single summary")
+  .action(async (opts) => {
+    let id;
+    try {
+      const done = store
+        .listTasks({ tag: opts.tag, status: 'completed' })
+        .filter((t) => t.result != null && t.result.trim());
+      if (!done.length) {
+        throw new Error(
+          `no completed results tagged '${opts.tag}' to digest.` +
+            ' Collect them first: gemcatch daemon --exit-when-idle'
+        );
+      }
+      done.reverse(); // oldest first, so the sources read in submission order
+      const sources = done
+        .map((t, i) => `## Source ${i + 1}: ${(t.prompt || '').replace(/\s+/g, ' ').trim()}\n\n${t.result}`)
+        .join('\n\n');
+      const prompt =
+        `Synthesize the following ${done.length} research result(s) into one coherent summary.` +
+        ' Note where they agree and disagree, and do not simply repeat each verbatim.\n\n' +
+        sources;
+      // The digest is itself a task, tagged so it is findable but kept out of
+      // the source tag so a later digest never digests its own output.
+      id = store.createTask({ prompt, model: opts.model, systemInstruction: opts.system, tag: `${opts.tag}-digest` });
+      const r = await gemini.submit(prompt, { model: opts.model, systemInstruction: opts.system });
+      store.setInteraction(id, r.interactionId, r.status);
+      if (!opts.json) console.error(edim(`Digesting ${done.length} result(s) tagged ${opts.tag} -> task ${id}.`));
+      await watchTask(store.getTask(id), DEFAULT_POLL_MS, opts.json);
+    } catch (err) {
+      // Same rule as `research`: only a failed *submit* marks the task failed.
+      if (id) {
+        const t = store.getTask(id);
+        if (!t || !t.interaction_id) store.setStatus(id, 'failed', { error: err.message });
+      }
+      die(err);
     }
   });
 
@@ -422,12 +752,18 @@ program
   .option('--json', 'newline-delimited JSON events on stdout')
   .description('poll in-flight tasks on a loop so results are cached before they expire')
   .action(async (opts) => {
-    const intervalMs = Math.max(1000, (opts.interval || DEFAULT_DAEMON_S) * 1000);
+    if (!Number.isFinite(opts.interval) || opts.interval <= 0) {
+      return die(new Error(`--interval must be a positive number of seconds (got ${opts.interval})`));
+    }
+    const intervalMs = Math.max(1000, opts.interval * 1000);
     let stopping = false;
     let wake = null;
     // Finish the pass in progress, then exit cleanly -- never leave a polled
-    // result unwritten because someone hit Ctrl-C.
+    // result unwritten because someone hit Ctrl-C. A *second* signal, though,
+    // means "I don't want to wait for this pass" -- force-exit immediately with
+    // the conventional 130 (128 + SIGINT) so a long paced pass can't trap you.
     const stop = () => {
+      if (stopping) process.exit(130);
       stopping = true;
       if (wake) wake();
     };
@@ -440,7 +776,7 @@ program
 
     if (!opts.json) {
       console.error(
-        dim(`gemcatch daemon: polling every ${intervalMs / 1000}s. Store: ${store.DB_PATH}. Ctrl-C to stop.`)
+        edim(`gemcatch daemon: polling every ${intervalMs / 1000}s. Store: ${store.DB_PATH}. Ctrl-C to stop.`)
       );
     }
     event({ event: 'start', interval_s: intervalMs / 1000, db: store.DB_PATH });
@@ -455,7 +791,7 @@ program
         // the next pass may well succeed, and a daemon that dies silently is
         // worse than one that complains.
         if (opts.json) event({ event: 'error', error: err.message });
-        else console.error(`${dim(`[${hhmmss()}]`)} Error: ${err.message}`);
+        else console.error(`${edim(`[${hhmmss()}]`)} Error: ${err.message}`);
       }
 
       // Quiet by default: only transitions and failures are worth a line.
@@ -465,7 +801,7 @@ program
           event({ event: r.error ? 'error' : 'update', id: r.id, status: r.status, error: r.error || null });
         } else {
           console.error(
-            dim(`[${hhmmss()}] ${r.id}: `) + colorStatus(r.status) + (r.error ? `  ${dim(r.error)}` : '')
+            edim(`[${hhmmss()}] ${r.id}: `) + ecolorStatus(r.status) + (r.error ? `  ${edim(r.error)}` : '')
           );
         }
       }
@@ -488,7 +824,7 @@ program
     }
 
     event({ event: 'stop' });
-    if (!opts.json) console.error(dim('gemcatch daemon: stopped.'));
+    if (!opts.json) console.error(edim('gemcatch daemon: stopped.'));
     store.close();
   });
 
@@ -496,23 +832,43 @@ program
 
 async function watchTask(task, intervalMs, json) {
   let last = null;
+  let fails = 0;
   for (;;) {
-    const r = await refresh(task);
+    let r;
+    try {
+      r = await refresh(task);
+      fails = 0; // a clean poll resets the failure run
+    } catch (err) {
+      // A poll error must not sink a live task: keep its old status and try
+      // again next interval, exactly like watchBatch. Give up only once the
+      // failures pile up, so a task the server can't answer for can't hang the
+      // watch forever. (A 404 doesn't reach here -- refresh retires it and
+      // returns a terminal status, handled below.)
+      fails += 1;
+      if (fails >= WATCH_MAX_FAILS) {
+        const msg = `Gave up watching ${task.id} after ${fails} consecutive poll failures: ${err.message}`;
+        emit(json, { id: task.id, status: task.status, error: msg }, () => console.error(edim(msg)));
+        process.exitCode = 1;
+        return;
+      }
+      await new Promise((r2) => setTimeout(r2, intervalMs));
+      continue;
+    }
     // Status chatter goes to stderr so `gemcatch watch x > out.txt` captures only
     // the result.
     if (r.status !== last && !json) {
-      console.error(dim(`[${new Date().toISOString().slice(11, 19)}] ${task.id}: `) + colorStatus(r.status));
+      console.error(edim(`[${new Date().toISOString().slice(11, 19)}] ${task.id}: `) + ecolorStatus(r.status));
       last = r.status;
     }
     if (isSuccess(r.status)) {
-      emit(json, { id: task.id, status: r.status, result: r.text }, () =>
-        console.log(r.text || '(empty response)')
+      emit(json, { id: task.id, status: r.status, result: r.text, citations: r.citations || null }, () =>
+        console.log(withSources(r.text, r.citations))
       );
       return;
     }
     if (isDone(r.status)) {
       emit(json, { id: task.id, status: r.status, error: r.text || null }, () => {
-        console.error(`Task ${task.id} ended: ${colorStatus(r.status)}`);
+        console.error(`Task ${task.id} ended: ${ecolorStatus(r.status)}`);
         if (r.text) console.log(r.text);
       });
       process.exitCode = 1;
@@ -531,12 +887,18 @@ program
   .action(async (id, opts) => {
     const task = needTask(id);
     try {
-      if (isSuccess(task.status) && task.result) {
-        emit(opts.json, { id: task.id, status: task.status, result: task.result }, () =>
-          console.log(task.result)
+      // Serve a completed result from cache -- present, not merely truthy, so an
+      // empty-text completion is served instead of re-polled (and lost at 24h).
+      if (isSuccess(task.status) && task.result != null) {
+        const cits = parseCitations(task.citations);
+        emit(opts.json, { id: task.id, status: task.status, result: task.result, citations: cits }, () =>
+          console.log(withSources(task.result, cits))
         );
         return;
       }
+      if (opts.interval != null && (!Number.isFinite(opts.interval) || opts.interval <= 0)) {
+        return die(new Error(`--interval must be a positive number of seconds (got ${opts.interval})`));
+      }
       await watchTask(task, opts.interval ? opts.interval * 1000 : DEFAULT_POLL_MS, opts.json);
     } catch (err) {
       die(err);
@@ -579,7 +941,7 @@ program
         } catch (err) {
           // Free-tier interactions vanish after 24h, so a missing remote is
           // normal -- never block the local delete on it.
-          console.error(dim(`  (remote delete failed for ${task.id}: ${err.message})`));
+          console.error(edim(`  (remote delete failed for ${task.id}: ${err.message})`));
         }
       }
       if (store.removeTask(task.id)) removed += 1;
@@ -595,6 +957,12 @@ program
   .option('--dry-run', 'list what would go, delete nothing')
   .description('drop old finished tasks (in-flight work is never touched)')
   .action((opts) => {
+    // A negative (or non-numeric) --days puts the cutoff in the *future*, which
+    // would match every finished task and quietly wipe the lot. Refuse it: the
+    // cutoff must be at or before now.
+    if (!Number.isFinite(opts.days) || opts.days < 0) {
+      return die(new Error(`--days must be a non-negative number (got ${opts.days})`));
+    }
     const cutoff = Date.now() - opts.days * 86400000;
     const doomed = store.prunableTasks(cutoff);
     if (!doomed.length) {
@@ -618,12 +986,29 @@ program
   .description('where the store lives and what is in it')
   .action((opts) => {
     const rows = store.counts();
+    const agents = store.agentCounts();
     const total = rows.reduce((n, r) => n + r.n, 0);
-    emit(opts.json, { db: store.DB_PATH, total, by_status: rows }, () => {
+    emit(opts.json, { db: store.DB_PATH, total, by_status: rows, by_agent: agents }, () => {
       console.log(`Store: ${store.DB_PATH}`);
       console.log(`Tasks: ${total}`);
       for (const r of rows) console.log(`  ${colorStatus(r.status).padEnd(useColor ? 26 : 17)} ${r.n}`);
+      if (agents.length) {
+        console.log('Agent runs:');
+        for (const a of agents) console.log(`  ${a.agent.padEnd(34)} ${a.n}`);
+      }
     });
   });
 
+// Close the store on the way out so a one-shot command doesn't leave the
+// SQLite -wal/-shm sidecars lingering. The store opens lazily, so if a command
+// never touched it this is a no-op; the daemon closes explicitly too, and a
+// second close is harmless.
+process.on('exit', () => {
+  try {
+    store.close();
+  } catch (_) {
+    /* best effort on the way out */
+  }
+});
+
 program.parseAsync(process.argv).catch(die);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemcatch",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Fire-and-forget CLI for Gemini's Interactions API background execution. Submit long-running research prompts, close your laptop, collect results later.",
   "main": "index.js",
   "bin": {
@@ -29,6 +29,7 @@
     "background",
     "async",
     "agents",
+    "deep-research",
     "cli",
     "research",
     "daemon",
@@ -46,7 +47,11 @@
   "homepage": "https://github.com/Booyaka101/gemcatch#readme",
   "dependencies": {
     "@google/genai": "^2.12.0",
-    "better-sqlite3": "^12.11.1",
+    "better-sqlite3": "^13.0.3",
     "commander": "^15.0.0"
+  },
+  "allowScripts": {
+    "@google/genai@2.15.0": true,
+    "protobufjs@7.6.5": true
   }
 }