gemcatch 0.4.0 → 0.6.0

package/index.js

@@ -2,10 +2,13 @@
 'use strict';
 
 const fs = require('fs');
+const path = require('path');
+const { pathToFileURL } = require('url');
 const crypto = require('crypto');
 const { Command, Option } = require('commander');
 const store = require('./db');
 const gemini = require('./gemini');
+const sources = require('./sources');
 const { TERMINAL, ACTIVE, PENDING, isDone, isSuccess } = require('./status');
 
 const DEFAULT_POLL_MS = Number(process.env.GEMCATCH_POLL_MS) || 10000;
@@ -90,22 +93,26 @@ function needTask(id) {
 }
 
 // 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')}`;
+// them to verify the sources -- so they are printed under the result, and so are
+// the paths of any charts it drew.
+function withSources(text, citations, images) {
+  const parts = [text || '(empty response)'];
+  if (Array.isArray(citations) && citations.length) {
+    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)}`;
+    });
+    parts.push(`Sources:\n${lines.join('\n')}`);
+  }
+  if (images && images.length) parts.push(`Images:\n${images.map((p) => `  ${p}`).join('\n')}`);
+  return parts.join('\n\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) {
+// The citations and images_json columns hold JSON arrays (or NULL). Parsed
+// defensively: a corrupt row degrades to "none", never a crash in the middle of
+// printing a result.
+function parseList(raw) {
   if (!raw) return null;
   try {
     const v = JSON.parse(raw);
@@ -115,6 +122,40 @@ function parseCitations(raw) {
   }
 }
 
+// --- images ---------------------------------------------------------------
+
+const IMAGE_DIR = path.join(store.HOME, 'images');
+function imageExt(mime) {
+  if (mime === 'image/jpeg') return '.jpg';
+  const sub = /^image\/([a-z0-9]+)/i.exec(mime || '');
+  return sub ? `.${sub[1].toLowerCase()}` : '.png';
+}
+
+// A --visualize run's charts arrive as base64 in the result, which the store
+// keeps as text only, so they are written out as <task-id>-<n>.<ext>. They can
+// chart private data, so they get the store's permissions.
+function saveImages(task, images) {
+  fs.mkdirSync(IMAGE_DIR, { recursive: true, mode: 0o700 });
+  return images.map((img, i) => {
+    const file = path.join(IMAGE_DIR, `${task.id}-${i + 1}${imageExt(img.mime_type)}`);
+    fs.writeFileSync(file, Buffer.from(img.data, 'base64'), { mode: 0o600 });
+    return file;
+  });
+}
+
+// Only files named for this task go: a digest lists its sources' images too,
+// and forgetting the digest must not take them with it.
+function removeImages(task) {
+  for (const p of parseList(task.images_json) || []) {
+    if (!path.basename(p).startsWith(`${task.id}-`)) continue;
+    try {
+      fs.rmSync(p, { force: true });
+    } catch (err) {
+      console.error(`Note: could not delete ${p} (${err.message}).`);
+    }
+  }
+}
+
 // --- spend guard ----------------------------------------------------------
 
 // Deep Research agents are billed PER TASK, not per token -- the docs put
@@ -126,6 +167,12 @@ function parseCitations(raw) {
 // The bands are quoted with the docs' own hedge ("estimates based on preview
 // rates and subject to change"), never as authoritative.
 
+// A planning turn is a task and is billed as one. The docs publish ONE band per
+// task and price no planning turn separately, so it is quoted at the same band
+// and the line says so outright. Planning buys you a look at the plan before you
+// commit to the research run; it does not buy you a discount.
+const PLAN_NOTE = 'the docs price per task and do not price a planning turn separately';
+
 function bandText(agentId, count) {
   const band = gemini.AGENT_PRICE_BANDS[agentId];
   if (!band) return 'no published price band for this agent';
@@ -135,9 +182,53 @@ function bandText(agentId, count) {
     : `estimated ${money(band[0])}–${money(band[1])} for this task`;
 }
 
-function spendLine(agentId, count) {
+function spendLine(agentId, count, planning) {
   const head = count > 1 ? `${count} prompts × ${agentId}` : `Agent ${agentId}`;
-  return `${head} — ${bandText(agentId, count)}`;
+  return `${head}${planning ? ' (planning turn)' : ''} — ${bandText(agentId, count)}`;
+}
+
+// The parenthetical after the band. `hedge` is the docs' "preview rates" caveat,
+// which the confirmation carries; --dry-run already reads as a projection.
+function spendNote(planning, hedge) {
+  const parts = [];
+  if (hedge) parts.push('preview rates, subject to change');
+  if (planning) parts.push(PLAN_NOTE);
+  return parts.length ? ` (${parts.join('; ')})` : '';
+}
+
+// What the agent runs in the store have plausibly cost, from the same per-task
+// bands the guard quotes before each one. A plan chain bills per turn, so this
+// counts plans and refinements alongside reports -- that is the number worth
+// knowing. Agents with no published band are counted separately rather than
+// silently priced at zero. Null when nothing has been billed at all.
+function estimatedSpend(agentRows) {
+  let low = 0;
+  let high = 0;
+  let tasks = 0;
+  let unpriced = 0;
+  for (const a of agentRows) {
+    const band = gemini.AGENT_PRICE_BANDS[a.agent];
+    if (!band) {
+      unpriced += a.n;
+      continue;
+    }
+    low += band[0] * a.n;
+    high += band[1] * a.n;
+    tasks += a.n;
+  }
+  if (!tasks && !unpriced) return null;
+  // Nothing priced means the total is unknown, NOT zero. Reporting $0.00 for
+  // runs that cost real money is the exact dishonesty this guard exists to
+  // avoid, so low/high are null and the caller says "unknown" instead.
+  if (!tasks) return { low: null, high: null, tasks: 0, unpriced };
+  return { low, high, tasks, unpriced };
+}
+
+// A --dry-run's lines: the sources it would have sent, then the band, the
+// honesty note and that nothing went, in the confirmation's order.
+function dryRunSpend(agentId, count, planning, src) {
+  const line = `${spendLine(agentId, count, planning)}${spendNote(planning, false)}. Nothing submitted (--dry-run).`;
+  return [...sources.describe(src), line].join('\n');
 }
 
 function askYesNo(question) {
@@ -154,8 +245,9 @@ function askYesNo(question) {
 // 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).`);
+async function confirmSpend(agentId, count, opts, planning, src) {
+  for (const line of sources.describe(src)) console.error(line);
+  console.error(`${spendLine(agentId, count, planning)}${spendNote(planning, true)}.`);
   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.
@@ -177,7 +269,18 @@ async function confirmSpend(agentId, count, opts) {
 // 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 (!opts.agent) {
+    // Collaborative planning is an agent_config field on an agent run. A model
+    // run has no plan turn at all, so --plan without --agent is a mistake worth
+    // naming rather than a flag that quietly does nothing.
+    if (opts.plan) {
+      throw new Error(
+        '--plan is a research-agent feature: collaborative planning applies to an agent, not a model, ' +
+          'and a model run has no plan turn.\n  Try: --agent deep-research --plan'
+      );
+    }
+    return null;
+  }
   if (cmd.getOptionValueSource('model') === 'cli') {
     throw new Error(
       '--model and --agent are mutually exclusive: an agent run is submitted with `agent` ' +
@@ -187,6 +290,271 @@ function resolveAgentOpts(opts, cmd) {
   return gemini.resolveAgent(opts.agent);
 }
 
+// --- sources --------------------------------------------------------------
+
+// --mcp, --file-search, --no-web, --attach and --visualize, on research and
+// batch alike. Each command gets its own MCP parsers: the modifier flags attach
+// to the --mcp before them, which only works if they share one list.
+function addSourceOptions(cmd) {
+  const mcp = sources.mcpOptionParsers();
+  const collect = (v, list) => (list || []).concat(v);
+  return cmd
+    .optionsGroup('Your own data (needs --agent):')
+    .option('--mcp <url>', 'let the agent call this remote MCP server (repeatable)', mcp.mcp)
+    .option('--mcp-name <name>', 'name for the --mcp before it (default: its host)', mcp.name)
+    .option('--mcp-header <header>', "'Name: value' header for the --mcp before it; ${VAR} reads the environment", mcp.header)
+    .option('--mcp-allow <tools>', 'comma-separated tools the --mcp before it may call', mcp.allow)
+    .option('--file-search <store>', 'let the agent search this File Search store (repeatable)', collect)
+    .option('--no-web', 'drop Google Search and URL Context; needs --mcp, --file-search or --attach')
+    .option('--attach <path|url>', 'attach a PDF, CSV or image to the first turn (repeatable)', collect)
+    .option('--visualize', 'let the agent draw charts; they are saved as image files');
+}
+
+// Reads the inline attachments and uploads the rest. Runs after the spend is
+// confirmed and before any row is written, so a failed upload costs nothing.
+// A plan is continued later, so it is told when its uploads expire.
+async function attachFiles(files, planning) {
+  const attached = await sources.materialize(files, gemini.upload, (a) => {
+    console.error(edim(`Uploading ${a.source} (${sources.size(a.bytes)}) to the Files API...`));
+  });
+  const expiry = Math.min(...attached.record.map((a) => a.expires_at || Infinity));
+  if (planning && expiry !== Infinity) {
+    const when = new Date(expiry).toLocaleString(undefined, { dateStyle: 'medium', timeStyle: 'short' });
+    console.error(`Note: the uploaded files expire at ${when}; a refine or approve after that will probably fail.`);
+  }
+  return attached;
+}
+
+// What a submitted turn records about its sources. Tools are stored with their
+// header values because a later turn of the chain has to send them again.
+function sourceColumns(src, record) {
+  return {
+    toolsJson: src.tools ? JSON.stringify(src.tools) : null,
+    attachmentsJson: record && record.length ? JSON.stringify(record) : null,
+    visualization: src.visualization || null,
+  };
+}
+
+// The source fields of a gemini.submit call, with ${VAR} header values filled in.
+function sourceArgs(src, items) {
+  return { tools: sources.withEnv(src.tools), attachments: items, visualization: src.visualization };
+}
+
+// The sources a later turn inherits from the row it continues. Attachments went
+// with the first turn and are already in the conversation, so none are resent.
+function storedSources(task) {
+  let tools;
+  try {
+    tools = task.tools_json ? JSON.parse(task.tools_json) : undefined;
+  } catch (_) {
+    throw new Error(`task ${task.id} has an unreadable tools_json column, so its tools can't be sent again`);
+  }
+  sources.withEnv(tools);
+  return { tools, files: [], visualization: task.visualization || undefined };
+}
+
+// Server text about a task can quote its MCP headers or attachment URLs back.
+function redactFor(task, text) {
+  const urls = (parseList(chainRoot(task).attachments_json) || []).filter((a) => a.via === 'url').map((a) => a.source);
+  return sources.redactText(text, parseList(task.tools_json), urls);
+}
+
+function maskRaw(raw, task) {
+  const shown = raw && raw.tools ? { ...raw, tools: sources.redactTools(raw.tools) } : raw;
+  return redactFor(task, JSON.stringify(shown, null, 2));
+}
+
+// --- plan chains ----------------------------------------------------------
+
+// `collaborative_planning: true` makes the agent return a research plan instead
+// of a report. That plan is a decision point, not a deliverable: you read it,
+// optionally `refine` it, and `approve` it to spend on the research run itself.
+// Each turn is its own task row, linked to the one it continues by parent_id
+// locally and by previous_interaction_id on the wire.
+
+// What the approval turn sends as `input`. The plan is already in the
+// conversation via previous_interaction_id, so this turn only has to say yes --
+// the docs' own example sends a one-line confirmation, not the question again.
+const APPROVE_INPUT = 'Plan looks good, proceed with the research.';
+
+// The reason refresh() records when a poll 404s. Named because `approve` reads
+// it back to tell an expired plan apart from any other terminal one.
+const EXPIRED_ERROR = 'interaction not found (expired or deleted)';
+
+const RETENTION_NOTE =
+  'The Interactions API retains interactions for 1 day on the free tier (55 days on paid).';
+
+// A finished plan is a decision point, so the next command is spelled out under
+// it. Guidance, so it goes to stderr like the rest -- `gemcatch get <plan> >
+// plan.md` still captures only the plan.
+function planFooter(task) {
+  return `Approve with: gemcatch approve ${task.id}   ·   Refine with: gemcatch refine ${task.id} "..."`;
+}
+
+// The result payload for `get`/`watch`. The plan-chain fields ride along only on
+// a plan row, so a model run's --json shape is exactly what it always was.
+function resultPayload(task, status, result, citations, images) {
+  const p = { id: task.id, status, result, citations: citations || null };
+  if (images && images.length) p.images = images;
+  if (task.kind === 'plan') {
+    p.kind = 'plan';
+    p.approve = `gemcatch approve ${task.id}`;
+    p.refine = `gemcatch refine ${task.id} "<instruction>"`;
+  }
+  return p;
+}
+
+function cachedResult(task) {
+  return { status: task.status, text: task.result, citations: parseList(task.citations), imagePaths: parseList(task.images_json) };
+}
+
+function printResult(task, r, json) {
+  emit(json, resultPayload(task, r.status, r.text, r.citations, r.imagePaths), () => {
+    console.log(withSources(r.text, r.citations, r.imagePaths));
+    if (task.kind === 'plan') console.error(planFooter(task));
+  });
+}
+
+// Both continuation commands need the same thing: a plan row that completed and
+// whose interaction the server can still resolve. Anything else exits here,
+// before a row is written or a request is sent.
+function needPlan(id, verb) {
+  const task = needTask(id);
+  if (task.kind !== 'plan') {
+    die(
+      new Error(
+        `Task ${task.id} is not a plan (kind: ${task.kind || 'task'}), so there is nothing to ${verb}.\n` +
+          '  Plans come from: gemcatch research "<prompt>" --agent deep-research --plan'
+      )
+    );
+  }
+  if (task.status === 'incomplete' && task.error === EXPIRED_ERROR) {
+    die(
+      new Error(
+        `Plan ${task.id}'s interaction was dropped server-side, so it can no longer be continued.\n` +
+          `  ${RETENTION_NOTE}\n` +
+          `  Submit a fresh plan: gemcatch research "<prompt>" --agent ${task.agent || '<agent>'} --plan`
+      )
+    );
+  }
+  // A plan that finished any way other than `completed` is never coming back, so
+  // "wait for it" would be wrong advice. Only a plan still in flight gets
+  // pointed at `watch`.
+  if (isDone(task.status) && !isSuccess(task.status)) {
+    die(
+      new Error(
+        `Plan ${task.id} ended ${task.status}, so there is nothing to ${verb}.\n` +
+          `  Submit a fresh plan: gemcatch research "<prompt>" --agent ${task.agent || '<agent>'} --plan`
+      )
+    );
+  }
+  if (!isSuccess(task.status)) {
+    die(
+      new Error(
+        `Plan ${task.id} has not completed yet (status: ${task.status}), so there is nothing to ${verb}.\n` +
+          `  Wait for it: gemcatch watch ${task.id}`
+      )
+    );
+  }
+  if (!task.interaction_id) die(new Error(`Plan ${task.id} was never submitted.`));
+  return task;
+}
+
+// A plan can complete locally and still expire server-side before you approve
+// it, in which case the continuation 404s on an id the user never typed. Name
+// the retention window instead of passing that through raw.
+function expiredHint(err, plan) {
+  if (!err || err.httpStatus !== 404) return err;
+  const e = new Error(
+    `the plan's interaction (${plan.interaction_id}) is gone server-side, so it cannot be continued.\n` +
+      `  ${RETENTION_NOTE}\n` +
+      `  Submit a fresh plan: gemcatch research "<prompt>" --agent ${plan.agent || '<agent>'} --plan`
+  );
+  e.code = 'API_ERROR';
+  e.httpStatus = 404;
+  return e;
+}
+
+// The first turn of a plan chain. A report row is displayed under the question
+// that started the chain rather than the "plan looks good" line actually sent --
+// that is what keeps `list` and `export` reading as research instead of as
+// protocol chatter.
+function chainRoot(task) {
+  let cur = task;
+  const seen = new Set([task.id]);
+  while (cur.parent_id && !seen.has(cur.parent_id)) {
+    seen.add(cur.parent_id);
+    const parent = store.getTask(cur.parent_id);
+    if (!parent) break;
+    cur = parent;
+  }
+  return cur;
+}
+
+// `refine` (another plan) and `approve` (the report) are the same submission --
+// same agent, same tag, linked to the plan by previous_interaction_id --
+// differing only in the collaborative_planning flag they send, the kind they
+// store and the line they print. So they share one path, and the spend guard is
+// on it exactly once.
+async function continuePlan(plan, opts, turn) {
+  let id;
+  try {
+    const src = storedSources(plan);
+    if (opts.dryRun) {
+      emit(
+        opts.json,
+        {
+          dry_run: true,
+          agent: plan.agent,
+          kind: turn.kind,
+          parent_id: plan.id,
+          previous_interaction_id: plan.interaction_id,
+          input: turn.input,
+          ...sources.preview(src),
+        },
+        () => console.log(dryRunSpend(plan.agent, 1, turn.planning, src))
+      );
+      return;
+    }
+    // Warned, not refused: whether the server still needs the files once the
+    // conversation has read them is not documented.
+    const expired = (parseList(chainRoot(plan).attachments_json) || []).filter(
+      (a) => a.expires_at && a.expires_at < Date.now()
+    );
+    if (expired.length) {
+      console.error(
+        `Note: ${expired.map((a) => a.source).join(', ')} expired from the Files API, so this turn will probably fail.`
+      );
+    }
+    await confirmSpend(plan.agent, 1, opts, turn.planning, src);
+    id = store.createTask({
+      prompt: turn.prompt,
+      agent: plan.agent,
+      tag: plan.tag,
+      kind: turn.kind,
+      parentId: plan.id,
+      collaborativePlanning: turn.planning,
+      previousInteractionId: plan.interaction_id,
+      ...sourceColumns(src),
+    });
+    const r = await gemini.submit(turn.input, {
+      agent: plan.agent,
+      collaborativePlanning: turn.planning,
+      previousInteractionId: plan.interaction_id,
+      ...sourceArgs(src),
+    });
+    store.setInteraction(id, r.interactionId, r.status);
+    emit(
+      opts.json,
+      { id, interaction_id: r.interactionId, status: r.status, kind: turn.kind, parent_id: plan.id },
+      () => console.log(turn.line(id))
+    );
+  } catch (err) {
+    markSubmitFailure(id, err);
+    die(expiredHint(err, plan));
+  }
+}
+
 // --- input ----------------------------------------------------------------
 
 function readStdin() {
@@ -230,25 +598,49 @@ async function refresh(task) {
     // 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)' });
+      store.setStatus(task.id, 'incomplete', { error: EXPIRED_ERROR });
       return { status: 'incomplete', text: null, usage: null, raw: null };
     }
     throw err;
   }
   const extra = {};
   if (isDone(r.status)) {
+    if (r.text) r.text = redactFor(task, 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.citations && r.citations.length) {
+        r.citations = JSON.parse(redactFor(task, JSON.stringify(r.citations)));
+        extra.citations = JSON.stringify(r.citations);
+      }
+      if (r.images.length) {
+        r.imagePaths = saveImages(task, r.images);
+        extra.images_json = JSON.stringify(r.imagePaths);
+      }
+    } else if (r.text) {
+      extra.error = r.text;
+    }
   }
   if (r.usage) extra.usage = JSON.stringify(r.usage);
   store.setStatus(task.id, r.status, extra);
+  // A digest has no images of its own but lists its sources' (see digest).
+  if (!r.imagePaths) r.imagePaths = parseList(task.images_json);
   return r;
 }
 
+// Only a failed *submit* should mark a 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. Every command that submits calls this
+// on its way out, so the rule cannot drift between them.
+function markSubmitFailure(id, err) {
+  if (!id) return;
+  const t = store.getTask(id);
+  if (!t || !t.interaction_id) store.setStatus(id, 'failed', { error: err.message });
+}
+
 // Bounds how many polls are open at once. The *rate* limit is enforced in
 // gemini.js (GEMCATCH_RPM), which is the part that keeps a wide fan-out inside the
 // free tier's requests-per-minute allowance.
@@ -270,66 +662,88 @@ const program = new Command();
 program
   .name('gemcatch')
   .description("Fire-and-forget research tasks on Gemini's Interactions API (background execution).")
-  .version(require('./package.json').version);
+  .version(require('./package.json').version)
+  // An unknown `--flag=value` is echoed whole, and the value may be a token.
+  .configureOutput({ outputError: (str, write) => write(str.replace(/(unknown option '[^'=]*)=[^']*'/g, "$1=...'")) });
 
 // --- research -------------------------------------------------------------
 
-program
+const research = program
   .command('research')
   .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('--plan', 'ask the agent for a research plan first, to refine and approve (needs --agent)')
   .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')
+  .option('--json', 'machine-readable output');
+addSourceOptions(research)
   .description('submit a background task and exit immediately')
   .action(async (promptArg, opts, cmd) => {
     let id;
     try {
       const agent = resolveAgentOpts(opts, cmd);
+      const src = await sources.resolve(opts, agent);
+      for (const w of src.warnings) console.error(`Note: ${w}`);
       const prompt = await resolvePrompt(promptArg, opts);
+      // undefined, not false: an ordinary run must keep sending no agent_config
+      // at all, exactly as it did before collaborative planning existed.
+      const planning = opts.plan ? true : undefined;
       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).`);
-        });
+        emit(
+          opts.json,
+          {
+            dry_run: true,
+            agent: agent || null,
+            model: agent ? null : opts.model,
+            plan: !!opts.plan,
+            prompt,
+            ...sources.preview(src),
+          },
+          () => {
+            if (agent) console.log(dryRunSpend(agent, 1, opts.plan, src));
+            else console.log(`Would submit to ${opts.model}: ${snippet(prompt)}. Nothing submitted (--dry-run).`);
+          }
+        );
         return;
       }
-      if (agent) await confirmSpend(agent, 1, opts);
+      if (agent) await confirmSpend(agent, 1, opts, opts.plan, src);
+      const attached = await attachFiles(src.files, opts.plan);
       id = store.createTask({
         prompt,
         model: agent ? null : opts.model,
         agent,
         systemInstruction: opts.system,
         tag: opts.tag,
+        kind: opts.plan ? 'plan' : 'task',
+        collaborativePlanning: planning,
+        ...sourceColumns(src, attached.record),
+      });
+      const r = await gemini.submit(prompt, {
+        model: opts.model,
+        agent,
+        systemInstruction: opts.system,
+        collaborativePlanning: planning,
+        ...sourceArgs(src, attached.items),
       });
-      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(edim(`Task ${id} submitted.`));
+        if (!opts.json) console.error(edim(`${opts.plan ? 'Plan task' : 'Task'} ${id} submitted.`));
         await watchTask(store.getTask(id), DEFAULT_POLL_MS, opts.json);
         return;
       }
-      emit(opts.json, { id, interaction_id: r.interactionId, status: r.status }, () =>
-        console.log(`Task ${id} submitted. Run: gemcatch get ${id} when ready.`)
+      emit(opts.json, { id, interaction_id: r.interactionId, status: r.status, kind: opts.plan ? 'plan' : 'task' }, () =>
+        console.log(`${opts.plan ? 'Plan task' : 'Task'} ${id} submitted. Run: gemcatch get ${id} when ready.`)
       );
     } catch (err) {
-      // 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 });
-      }
+      markSubmitFailure(id, err);
       die(err);
     }
   });
@@ -407,22 +821,26 @@ async function watchBatch(tag, intervalMs, json) {
   );
 }
 
-program
+const batch = 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('--plan', 'ask the agent for a research plan per prompt, to refine and approve (needs --agent)')
   .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')
+  .option('--json', 'machine-readable output');
+addSourceOptions(batch)
   .description('submit many background tasks from a file, tagged as one batch')
   .action(async (file, opts, cmd) => {
     try {
       const agent = resolveAgentOpts(opts, cmd);
+      const src = await sources.resolve(opts, agent);
+      for (const w of src.warnings) console.error(`Note: ${w}`);
       const text = file === '-' ? await readStdin() : fs.readFileSync(file, 'utf8');
       const { prompts, skipped } = parsePrompts(text, opts.separator);
       if (!prompts.length) throw new Error(`no prompts found in ${file === '-' ? 'stdin' : file}`);
@@ -431,14 +849,19 @@ program
       if (skipped) {
         console.error(edim(`(skipped ${skipped} blank/comment line${skipped === 1 ? '' : 's'})`));
       }
+      if (prompts.length > 1) src.files = sources.uploadAll(src.files);
       // Auto-tag so the batch is collectable as a unit; a user tag wins.
       const tag = opts.tag || `batch-${crypto.randomUUID().slice(0, 6)}`;
 
+      // undefined, not false: an ordinary run must keep sending no agent_config.
+      const planning = opts.plan ? true : undefined;
+
       if (opts.dryRun) {
-        emit(opts.json, { tag, dry_run: true, agent: agent || null, prompts }, () => {
+        const payload = { tag, dry_run: true, agent: agent || null, plan: !!opts.plan, prompts, ...sources.preview(src) };
+        emit(opts.json, payload, () => {
           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).`);
+            console.log(dryRunSpend(agent, prompts.length, opts.plan, src));
           } else {
             console.log(`Batch ${tag}: ${prompts.length} prompt(s) would be submitted:`);
             for (const p of prompts) console.log(`  ${snippet(p)}`);
@@ -449,14 +872,31 @@ program
 
       // 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);
+      if (agent) await confirmSpend(agent, prompts.length, opts, opts.plan, src);
+      // Uploaded once (see uploadAll) and attached to every prompt in the file.
+      const attached = await attachFiles(src.files, opts.plan);
 
       // 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: agent ? null : opts.model, agent, systemInstruction: opts.system, tag });
+        const id = store.createTask({
+          prompt,
+          model: agent ? null : opts.model,
+          agent,
+          systemInstruction: opts.system,
+          tag,
+          kind: opts.plan ? 'plan' : 'task',
+          collaborativePlanning: planning,
+          ...sourceColumns(src, attached.record),
+        });
         try {
-          const r = await gemini.submit(prompt, { model: opts.model, agent, systemInstruction: opts.system });
+          const r = await gemini.submit(prompt, {
+            model: opts.model,
+            agent,
+            systemInstruction: opts.system,
+            collaborativePlanning: planning,
+            ...sourceArgs(src, attached.items),
+          });
           store.setInteraction(id, r.interactionId, r.status);
           return { id, interaction_id: r.interactionId, status: r.status, prompt };
         } catch (err) {
@@ -484,9 +924,16 @@ program
           const pad = ' '.repeat(Math.max(0, 16 - status.length));
           console.log(`${r.id}  ${colorStatus(status)}${pad} ${snippet(r.prompt)}`);
         }
-        console.log(dim('\nCollect them:'));
-        console.log(dim('  gemcatch daemon --exit-when-idle'));
-        console.log(dim(`  gemcatch list --tag ${tag} --status completed`));
+        if (opts.plan) {
+          console.log(dim('\nCollect the plans, then approve the ones worth running:'));
+          console.log(dim('  gemcatch daemon --exit-when-idle'));
+          console.log(dim(`  gemcatch list --tag ${tag}`));
+          console.log(dim('  gemcatch get <id>   # prints the plan and the approve command'));
+        } else {
+          console.log(dim('\nCollect them:'));
+          console.log(dim('  gemcatch daemon --exit-when-idle'));
+          console.log(dim(`  gemcatch list --tag ${tag} --status completed`));
+        }
       });
     } catch (err) {
       die(err);
@@ -528,19 +975,11 @@ program
       // 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;
-      }
+      if (isSuccess(task.status) && task.result != null && !opts.raw) return printResult(task, cachedResult(task), opts.json);
       const r = await refresh(task);
-      if (opts.raw) return console.log(JSON.stringify(r.raw, null, 2));
+      if (opts.raw) return console.log(maskRaw(r.raw, task));
       if (isSuccess(r.status)) {
-        emit(opts.json, { id: task.id, status: r.status, result: r.text, citations: r.citations || null }, () =>
-          console.log(withSources(r.text, r.citations))
-        );
+        printResult(task, r, opts.json);
       } else if (isDone(r.status)) {
         emit(opts.json, { id: task.id, status: r.status, error: r.text || null }, () =>
           console.log(`Task ${task.id}: ${colorStatus(r.status)}${r.text ? `\n${r.text}` : ''}`)
@@ -556,8 +995,94 @@ program
     }
   });
 
+// --- refine / approve -----------------------------------------------------
+
+program
+  .command('refine')
+  .argument('<id>', 'plan task id')
+  .argument('<instruction>', 'what the plan should do differently')
+  .option('--yes', 'confirm the agent cost without asking (required when stdin is not a TTY)')
+  .option('--dry-run', 'show what it would cost; submit nothing')
+  .option('--json', 'machine-readable output')
+  .description('send an instruction back to a plan and get a revised plan')
+  .action(async (id, instruction, opts) => {
+    const text = (instruction || '').trim();
+    if (!text) {
+      return die(new Error('provide an instruction, e.g. gemcatch refine 8f3a1c04 "focus on enforcement dates"'));
+    }
+    const plan = needPlan(id, 'refine');
+    await continuePlan(plan, opts, {
+      planning: true,
+      kind: 'plan',
+      input: text,
+      prompt: text,
+      line: (newId) => `Plan task ${newId} submitted (refines ${plan.id}). Run: gemcatch get ${newId} when ready.`,
+    });
+  });
+
+program
+  .command('approve')
+  .argument('<id>', 'plan task id')
+  .option('--yes', 'confirm the agent cost without asking (required when stdin is not a TTY)')
+  .option('--dry-run', 'show what it would cost; submit nothing')
+  .option('--json', 'machine-readable output')
+  .description('approve a plan and submit the research run it describes')
+  .action(async (id, opts) => {
+    const plan = needPlan(id, 'approve');
+    await continuePlan(plan, opts, {
+      planning: false,
+      kind: 'report',
+      input: APPROVE_INPUT,
+      prompt: chainRoot(plan).prompt,
+      line: (newId) => `Task ${newId} submitted (approves plan ${plan.id}).`,
+    });
+  });
+
 // --- list -----------------------------------------------------------------
 
+// A plan chain is one piece of work, so it is listed as one: the root in its
+// normal newest-first position, its continuations indented under it in the order
+// they were submitted. A row whose parent is filtered out of this listing (by
+// --status, --tag or -n) is rendered as its own root rather than dropped.
+function chainOrder(tasks) {
+  const present = new Set(tasks.map((t) => t.id));
+  const kids = new Map();
+  for (const t of tasks) {
+    if (!t.parent_id || !present.has(t.parent_id)) continue;
+    if (!kids.has(t.parent_id)) kids.set(t.parent_id, []);
+    kids.get(t.parent_id).push(t);
+  }
+  for (const list of kids.values()) list.sort((a, b) => a.created_at - b.created_at);
+  const out = [];
+  const seen = new Set();
+  const walk = (t, depth) => {
+    if (seen.has(t.id)) return;
+    seen.add(t.id);
+    out.push({ task: t, depth });
+    for (const c of kids.get(t.id) || []) walk(c, depth + 1);
+  };
+  for (const t of tasks) if (!t.parent_id || !present.has(t.parent_id)) walk(t, 0);
+  // A listing must never lose a row. Nothing the CLI writes can put a cycle in
+  // parent_id, but a row that is unreachable from any root would otherwise
+  // vanish silently, so anything left over is rendered flat.
+  for (const t of tasks) walk(t, 0);
+  return out;
+}
+
+// A word per kind of source a row used, for the list's SOURCES column.
+function sourcesUsed(t) {
+  const tools = parseList(t.tools_json) || [];
+  const files = parseList(t.attachments_json) || [];
+  const mcp = tools.filter((x) => x && x.type === 'mcp_server').length;
+  const words = [];
+  if (mcp) words.push(mcp > 1 ? `${mcp} mcp` : 'mcp');
+  if (tools.some((x) => x && x.type === 'file_search')) words.push('store');
+  if (tools.length && !tools.some((x) => x && x.type === 'google_search')) words.push('no-web');
+  if (files.length) words.push(files.length > 1 ? `${files.length} files` : 'file');
+  if (t.visualization) words.push('charts');
+  return words.join(',');
+}
+
 program
   .command('list')
   .alias('ls')
@@ -573,26 +1098,39 @@ program
       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 (opts.json) {
+      const masked = tasks.map((t) => (t.tools_json ? { ...t, tools_json: sources.redactToolsJson(t.tools_json) } : t));
+      return console.log(JSON.stringify(masked, null, 2));
+    }
     if (!tasks.length) {
       console.log('No tasks yet. Submit one:  gemcatch research "your question"');
       return;
     }
-    // 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).
+    // The AGENT, KIND and SOURCES columns only appear when something in the
+    // listing uses them, 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 showKind = tasks.some((t) => t.kind && t.kind !== 'task');
     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 used = new Map(tasks.map((t) => [t.id, sourcesUsed(t)]));
+    const srcWidth = Math.max(...[...used.values()].map((u) => u.length));
+    const srcHead = srcWidth ? `${'SOURCES'.padEnd(Math.max(7, srcWidth))} ` : '';
+    console.log(
+      dim(`ID        AGE   STATUS           ${showKind ? 'KIND    ' : ''}${showAgent ? 'AGENT              ' : ''}${srcHead}PROMPT`)
+    );
+    for (const { task: t, depth } of chainOrder(tasks)) {
       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 kindCol = showKind ? `${(t.kind || 'task').padEnd(7)} ` : '';
       const agentCol = showAgent ? `${shortAgent(t.agent).padEnd(18)} ` : '';
+      const srcCol = srcWidth ? `${(used.get(t.id) || '-').padEnd(Math.max(7, srcWidth))} ` : '';
+      // Indent the prompt, not the id: the fixed-width columns stay aligned and
+      // the chain still reads as one thing.
+      const branch = depth ? `${'  '.repeat(depth - 1)}└─ ` : '';
       console.log(
-        `${t.id}  ${age(t.created_at).padEnd(4)}  ${colorStatus(status)}${pad} ${agentCol}${snip}`
+        `${t.id}  ${age(t.created_at).padEnd(4)}  ${colorStatus(status)}${pad} ${kindCol}${agentCol}${srcCol}${branch}${snippet(t.prompt)}`
       );
     }
   });
@@ -609,6 +1147,7 @@ program
   .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')
+  .option('--include-plans', 'also export the plan turns of a chain, not just its report')
   .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 });
@@ -617,25 +1156,54 @@ program
     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);
+    // A chain's plan turns are working notes on the way to its report, so an
+    // export of a tag follows the chain to the report and leaves them out
+    // unless they were asked for.
+    const rows = tasks.filter((t) => t.result != null && (opts.includePlans || t.kind !== 'plan'));
     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}'` : ''}.`);
+      // A chain with no approved run yet has plans and nothing else, which would
+      // otherwise read as "there is nothing here".
+      if (!opts.includePlans && tasks.some((t) => t.result != null && t.kind === 'plan')) {
+        console.error('  Only plan turns matched. Approve one (gemcatch approve <id>), or pass --include-plans.');
+      }
       return;
     }
 
+    // Images go next to the export file so its links still resolve when the
+    // file is moved with them; on stdout they point into the data dir.
+    const exportImages = (t) =>
+      (parseList(t.images_json) || []).map((p) => {
+        if (!opts.out) return p;
+        const name = path.basename(p);
+        try {
+          fs.copyFileSync(p, path.join(path.dirname(path.resolve(opts.out)), name));
+          return name;
+        } catch (err) {
+          console.error(`Note: could not copy ${p} next to the export (${err.message}).`);
+          return p;
+        }
+      });
+
     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,
-        })),
+        rows.map((t) => {
+          const row = {
+            id: t.id,
+            tag: t.tag,
+            status: t.status,
+            kind: t.kind || 'task',
+            prompt: t.prompt,
+            result: t.result,
+            created_at: t.created_at,
+          };
+          const images = exportImages(t);
+          if (images.length) row.images = images;
+          return row;
+        }),
         null,
         2
       );
@@ -645,7 +1213,10 @@ program
           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}`;
+          const kind = t.kind && t.kind !== 'task' ? ` · ${t.kind}` : '';
+          const link = (p) => (path.isAbsolute(p) ? pathToFileURL(p).href : p);
+          const images = exportImages(t).map((p, i) => `\n\n![${t.id} image ${i + 1}](${link(p)})`);
+          return `## ${head}\n\n\`${t.id}\` · ${t.status}${kind} · ${when} UTC\n\n${body}${images.join('')}`;
         })
         .join('\n\n---\n\n');
     }
@@ -684,26 +1255,30 @@ program
         );
       }
       done.reverse(); // oldest first, so the sources read in submission order
-      const sources = done
+      const results = 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;
+        results;
       // 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` });
+      // A model can't carry the sources' charts forward, so the digest lists them.
+      const images = done.flatMap((t) => parseList(t.images_json) || []);
+      id = store.createTask({
+        prompt,
+        model: opts.model,
+        systemInstruction: opts.system,
+        tag: `${opts.tag}-digest`,
+        imagesJson: images.length ? JSON.stringify(images) : null,
+      });
       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 });
-      }
+      markSubmitFailure(id, err);
       die(err);
     }
   });
@@ -860,12 +1435,7 @@ async function watchTask(task, intervalMs, json) {
       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, citations: r.citations || null }, () =>
-        console.log(withSources(r.text, r.citations))
-      );
-      return;
-    }
+    if (isSuccess(r.status)) return printResult(task, r, json);
     if (isDone(r.status)) {
       emit(json, { id: task.id, status: r.status, error: r.text || null }, () => {
         console.error(`Task ${task.id} ended: ${ecolorStatus(r.status)}`);
@@ -889,13 +1459,7 @@ program
     try {
       // 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 (isSuccess(task.status) && task.result != null) return printResult(task, cachedResult(task), opts.json);
       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})`));
       }
@@ -944,7 +1508,10 @@ program
           console.error(edim(`  (remote delete failed for ${task.id}: ${err.message})`));
         }
       }
-      if (store.removeTask(task.id)) removed += 1;
+      if (store.removeTask(task.id)) {
+        removeImages(task);
+        removed += 1;
+      }
     }
     console.log(`Removed ${removed} task${removed === 1 ? '' : 's'}.`);
   });
@@ -975,6 +1542,7 @@ program
       return;
     }
     const n = store.removeMany(doomed.map((t) => t.id));
+    for (const t of doomed) removeImages(t);
     console.log(`Pruned ${n} task${n === 1 ? '' : 's'}.`);
   });
 
@@ -983,20 +1551,44 @@ program
 program
   .command('stats')
   .option('--json', 'machine-readable output')
-  .description('where the store lives and what is in it')
+  .description('where the store lives, what is in it, and what the agent runs have plausibly cost')
   .action((opts) => {
     const rows = store.counts();
     const agents = store.agentCounts();
+    const kinds = store.kindCounts();
     const total = rows.reduce((n, r) => n + r.n, 0);
-    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}`);
+    // Priced from the runs that actually reached the server, not from every
+    // attempt: a submit that failed before it left the machine cost nothing.
+    const spend = estimatedSpend(store.billedAgentCounts());
+    emit(
+      opts.json,
+      { db: store.DB_PATH, total, by_status: rows, by_agent: agents, by_kind: kinds, estimated_spend: spend },
+      () => {
+        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}`);
+        }
+        if (kinds.length) {
+          console.log(`Plan chains: ${kinds.map((k) => `${k.n} ${k.kind}`).join(', ')}`);
+        }
+        if (spend && !spend.tasks) {
+          console.log(
+            `Estimated spend: unknown for ${spend.unpriced} agent task(s) on an agent with no published price band.`
+          );
+        } else if (spend) {
+          const rest = spend.unpriced
+            ? `, plus ${spend.unpriced} on an agent with no published band`
+            : '';
+          console.log(
+            `Estimated spend: $${spend.low.toFixed(2)}–$${spend.high.toFixed(2)} across ${spend.tasks} billed task(s)` +
+              ` (preview rates, subject to change)${rest}.`
+          );
+        }
       }
-    });
+    );
   });
 
 // Close the store on the way out so a one-shot command doesn't leave the