brand-manager-worker 0.2.0 → 0.3.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "brand-manager-worker",
-  "version": "0.2.0",
-  "description": "The Goose Tools brand-deal worker \u2014 your computer reads your brand email and drafts replies in your voice for goosetools.com, using your own Claude account. Drafts only; it never sends.",
+  "version": "0.3.2",
+  "description": "The Goose Tools brand-deal worker — your computer reads your brand email and drafts replies in your voice for goosetools.com, using your own Claude account. Drafts only; it never sends.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ernkerr/brand-manager-worker.git"

package/worker/compact.js

@@ -37,6 +37,48 @@ export const COMPACTABLE = [
 
 const ARCHIVE_DIR = join(BRAND_DIR, "archive");
 
+/**
+ * A free filename. The stamp used to be the date alone, so a second
+ * compaction on the same day overwrote the first archive — replacing the true
+ * original with an already-compacted copy and quietly destroying the only
+ * record of what was dropped.
+ */
+function archivePathFor(target) {
+  const stamp = new Date().toISOString().slice(0, 10);
+  let candidate = join(ARCHIVE_DIR, `${target}-${stamp}.md`);
+  for (let n = 2; existsSync(candidate); n += 1) {
+    candidate = join(ARCHIVE_DIR, `${target}-${stamp}-${n}.md`);
+  }
+  return candidate;
+}
+
+// Compaction can land a file just above the threshold — negotiation.md came
+// out at 48KB against a 40KB line. Without a memory of that, every scan
+// forever would re-compact it: an agent call each time, for a file that is
+// already as small as it gets. So a file is left alone after a compaction
+// until it has actually grown again.
+const STATE_PATH = () => join(ARCHIVE_DIR, ".compact-state.json");
+const REGROWTH = 1.15;
+
+function readState() {
+  try {
+    return JSON.parse(readFileSync(STATE_PATH(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function noteCompaction(target, size) {
+  try {
+    const state = readState();
+    state[target] = { size, at: new Date().toISOString() };
+    mkdirSync(ARCHIVE_DIR, { recursive: true });
+    writeFileSync(STATE_PATH(), JSON.stringify(state, null, 2));
+  } catch {
+    // A missing note only costs one redundant compaction; never fail over it.
+  }
+}
+
 export function sizeOf(path) {
   try {
     return statSync(path).size;
@@ -46,7 +88,14 @@ export function sizeOf(path) {
 }
 
 export function oversized() {
-  return COMPACTABLE.filter(({ path }) => sizeOf(path) > COMPACT_THRESHOLD);
+  const state = readState();
+  return COMPACTABLE.filter(({ target, path }) => {
+    const size = sizeOf(path);
+    if (size <= COMPACT_THRESHOLD) return false;
+    const last = state[target];
+    // Already squeezed and hasn't meaningfully regrown — nothing left to win.
+    return !last?.size || size > last.size * REGROWTH;
+  });
 }
 
 const prompt = (label, body) =>
@@ -100,33 +149,36 @@ export async function compactFile({ target, path }) {
   );
   const after = typeof out?.markdown === "string" ? out.markdown.trim() : "";
 
+  // A transient failure (bad output, timeout) must stay retryable — the file
+  // is over budget and we want another go. Only the deterministic refusals
+  // below get remembered, because re-asking would refuse identically.
   if (!after) return { target, ok: false, error: "no parseable rewrite" };
 
   // Guards. An agent asked to shrink a file can decide to summarize it, and a
   // 3KB precis of 66KB of learned voice is a catastrophic, silent loss — the
   // archive would be the only copy and nobody would notice for weeks.
   if (after.length < before.length * 0.25) {
-    return {
+    return refuse(
       target,
-      ok: false,
-      error: `refused: ${before.length} -> ${after.length} bytes looks like a summary, not a rewrite`,
-    };
+      before.length,
+      `${before.length} -> ${after.length} bytes looks like a summary, not a rewrite`,
+    );
   }
   if (after.length >= before.length) {
-    return { target, ok: false, error: "refused: no smaller than the original" };
+    return refuse(target, before.length, "no smaller than the original");
   }
   // The headings are the file's skeleton; losing most of them means it was
   // restructured rather than compacted.
   const headingsBefore = (before.match(/^##\s/gm) ?? []).length;
   const headingsAfter = (after.match(/^##\s/gm) ?? []).length;
   if (headingsBefore >= 4 && headingsAfter < 2) {
-    return { target, ok: false, error: "refused: lost the section structure" };
+    return refuse(target, before.length, "lost the section structure");
   }
 
   mkdirSync(ARCHIVE_DIR, { recursive: true });
-  const stamp = new Date().toISOString().slice(0, 10);
-  writeFileSync(join(ARCHIVE_DIR, `${target}-${stamp}.md`), before);
+  writeFileSync(archivePathFor(target), before);
   writeFileSync(path, `${after}\n`);
+  noteCompaction(target, after.length);
 
   return {
     target,
@@ -139,6 +191,16 @@ export async function compactFile({ target, path }) {
   };
 }
 
+/**
+ * A refusal the agent would repeat verbatim if asked again. Remember the size
+ * so the file isn't re-attempted every scan — it becomes eligible again only
+ * once it has genuinely regrown.
+ */
+function refuse(target, size, why) {
+  noteCompaction(target, size);
+  return { target, ok: false, error: `refused: ${why}` };
+}
+
 /**
  * Compact anything over the threshold. Called at the END of a scan, once —
  * not per thread, so a scan pays for at most one of these and only on the day

package/worker/context.js

@@ -9,6 +9,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { BASE_DIR, DEALS_DIR, PLAYBOOK_DIR, STATS_DIR, VOICE_DIR } from "./paths.js";
+import { currentScreenshots, screenshotsBlock } from "./screenshots.js";
 
 const readIf = (p) => {
   try {
@@ -51,6 +52,11 @@ export function loadContext() {
     if (c) parts.push(`### ${label}\n${c}`);
   }
 
+  // Which screenshots exist, worked out here: the drafting agent has no tools
+  // and can't look in the folder, so a file it isn't told about can't be
+  // attached, and a file it guesses at is silently dropped.
+  parts.push(screenshotsBlock(currentScreenshots()));
+
   // All deal ledgers (per-brand context + exclusivity-conflict checks).
   if (existsSync(DEALS_DIR)) {
     for (const name of readdirSync(DEALS_DIR).filter((n) => n.endsWith(".md")).sort()) {

package/worker/gmail.js

@@ -16,15 +16,45 @@ const BRAND_TERMS = [
   '"paid partnership"', "whitelisting", '"rate card"', "UGC", "gifting", "deliverables",
 ];
 
+/**
+ * Where "you got paid" actually shows up.
+ *
+ * A brand saying "already processed" is not money landing, and the difference
+ * between those two is the whole point of the payment confidence score. But
+ * the confirmation lands in a notification from the payment rail, which never
+ * matches BRAND_TERMS and so was never fetched — leaving the agent to score
+ * payments off the brand's own word, and rate every real payment as a guess.
+ */
+const PAYMENT_SENDERS = [
+  "mercury.com", "stripe.com", "paypal.com", "wise.com", "payoneer.com",
+  "bill.com", "tipalti.com", "squareup.com", "intuit.com", "remitly.com",
+];
+
+const PAYMENT_TERMS = [
+  '"payment received"', '"you\'ve been paid"', '"has been paid"', '"payment sent"',
+  '"deposit"', '"funds available"', '"invoice paid"', '"transfer complete"',
+];
+
 /** Gmail search query. Brand inbox = broad; personal inbox = brand-terms only. */
 export function queryFor(brandOnly) {
   // in:spam is opt-in for Gmail search — without it, misfiled brand outreach is
   // invisible and never gets a draft (real misses found 2026-07-30).
-  if (brandOnly)
-    return `${LOOKBACK} (${BRAND_TERMS.join(" OR ")}) (in:anywhere OR in:spam) -in:chats -in:trash`;
+  const payments = `(${PAYMENT_SENDERS.map((d) => `from:${d}`).join(" OR ")} OR ${PAYMENT_TERMS.join(" OR ")})`;
+  if (brandOnly) {
+    return (
+      `${LOOKBACK} ((${BRAND_TERMS.join(" OR ")}) OR ${payments})` +
+      ` (in:anywhere OR in:spam) -in:chats -in:trash`
+    );
+  }
   return `${LOOKBACK} (in:inbox OR category:promotions OR in:spam) -in:chats`;
 }
 
+/** Longer reach for a payment sweep — an invoice can sit well past 14 days. */
+export function paymentQuery(days = 120) {
+  const senders = PAYMENT_SENDERS.map((d) => `from:${d}`).join(" OR ");
+  return `newer_than:${days}d (${senders} OR ${PAYMENT_TERMS.join(" OR ")}) -in:chats -in:trash`;
+}
+
 async function gmailGet(accessToken, path, params = {}) {
   const url = new URL(`${API}/${path}`);
   for (const [k, v] of Object.entries(params)) {

package/worker/handlers.js

@@ -20,6 +20,7 @@ import { createReplyDraft } from "./gmail-draft.js";
 import { fetchThreads, getThread } from "./gmail.js";
 import { buildMirror } from "./mirror.js";
 import { applyPaymentConfirmation, applyRecordUpdates, resolveSlug } from "./record-write.js";
+import { rederiveAll } from "./rederive.js";
 import {
   BRAND_DIR,
   DEALS_DIR,
@@ -28,6 +29,7 @@ import {
   STATS_DIR,
   VOICE_DIR,
 } from "./paths.js";
+import { archiveScreenshots, currentScreenshots, listScreenshots } from "./screenshots.js";
 import * as state from "./state.js";
 
 const FOLLOWUP_DAYS = 3;
@@ -150,6 +152,21 @@ export async function runScan(job) {
 
   const lines = [];
   const flags = [];
+
+  // Surfaced once per scan, not per draft: she cannot fix it from a draft, and
+  // it is the reason a brand that asked for proof got numbers alone.
+  try {
+    if (currentScreenshots().length === 0) {
+      const newest = listScreenshots()[0]?.date;
+      flags.push(
+        `Stat screenshots are ${newest ? `out of date (newest ${newest})` : "missing"}, so brands asking ` +
+          `for proof get numbers only. Upload fresh ones on the Brand Manager page.`,
+      );
+    }
+  } catch {
+    // Never let the screenshots folder stop a scan.
+  }
+
   for (const thread of threads) {
     // Learn from the creator's edits to a sent reply (independent of drafting).
     try {
@@ -219,6 +236,37 @@ export async function runScan(job) {
   };
 }
 
+/**
+ * kind: rederive — rebuild the records from the email rather than from the
+ * journal they were first summarized out of. One-shot correction pass; see
+ * rederive.js for why it exists.
+ */
+export async function runRederive(job) {
+  if (!job.gmailAccessToken) return noGmail();
+
+  const lines = [];
+  const results = await rederiveAll(job.gmailAccessToken, job.accountEmail, {
+    write: true,
+    onProgress: (r) => {
+      if (r.changed) lines.push(`${r.slug}: ${r.changed}`);
+      if (r.brandCorrection) lines.push(`${r.slug}: ${r.brandCorrection}`);
+    },
+  });
+  invalidateContext();
+
+  const corrected = results.filter((r) => r.changed || r.brandCorrection).length;
+  const failed = results.filter((r) => r.error);
+
+  return {
+    ok: true,
+    summary: corrected
+      ? `Corrected ${corrected} of ${results.length} records. ${lines.join(" · ")}`.slice(0, 1900)
+      : `Checked ${results.length} records against your email; nothing needed correcting.`,
+    flags: failed.map((r) => `${r.slug}: ${r.error}`),
+    mirror: buildMirror({ threads: [] }),
+  };
+}
+
 /** kind: compact — squeeze the learned layer on demand. */
 export async function runCompact() {
   const results = await compactIfNeeded();
@@ -405,24 +453,32 @@ export async function runStats(job) {
   const urls = job.payload?.photoUrls ?? [];
   if (urls.length === 0) return { ok: false, error: "stats job has no photoUrls" };
 
-  mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+  // Download first, archive second: a failed download must not leave the
+  // folder empty when the old set was still usable.
   const stamp = new Date().toISOString().slice(0, 10);
-  const saved = [];
+  const downloads = [];
   for (let i = 0; i < urls.length; i++) {
     const res = await fetch(urls[i]);
     if (!res.ok) continue;
     const ext = (new URL(urls[i]).pathname.match(/\.(png|jpe?g|webp)$/i)?.[0] ?? ".png").toLowerCase();
-    const dest = join(SCREENSHOTS_DIR, `${stamp}-${i}${ext}`);
-    writeFileSync(dest, Buffer.from(await res.arrayBuffer()));
-    saved.push(dest);
+    downloads.push({ ext, bytes: Buffer.from(await res.arrayBuffer()) });
   }
-  if (saved.length === 0) return { ok: false, error: "could not download any screenshots" };
+  if (downloads.length === 0) return { ok: false, error: "could not download any screenshots" };
+
+  // A new upload replaces the set a brand gets; the old one goes to archive/.
+  mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+  archiveScreenshots();
+  const saved = downloads.map((d, i) => {
+    const dest = join(SCREENSHOTS_DIR, `${stamp}-${i}${d.ext}`);
+    writeFileSync(dest, d.bytes);
+    return dest;
+  });
 
   const prompt = [
     `You are brand-manager. Follow base/modes/stats-intake.md.`,
     `Read these stat screenshots and update stats/latest.md with the current numbers (followers, reel`,
-    `views, reach, engagement, audience demographics). Keep the screenshots referenced for attaching`,
-    `to brand replies. Screenshots:\n${saved.join("\n")}`,
+    `views, reach, engagement, audience demographics). Which screenshots a brand gets is worked out`,
+    `from the folder automatically; you don't need to list them. Screenshots:\n${saved.join("\n")}`,
     `Report one line summarizing what changed.`,
   ].join("\n");
 

package/worker/ig-stats.js

@@ -15,6 +15,7 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { GOOSE_DIR, STATS_DIR } from "./paths.js";
+import { currentScreenshots, listScreenshots } from "./screenshots.js";
 
 export const IG_TOKEN_FILE = join(GOOSE_DIR, "ig-token");
 const LATEST_MD = join(STATS_DIR, "latest.md");
@@ -142,7 +143,7 @@ const AGE_ORDER = ["13-17", "18-24", "25-34", "35-44", "45-54", "55-64", "65+"];
 
 /** The media kit the agent reads. Keeps the same headings the screenshot
  *  reader wrote, so anything that learned the old layout still works. */
-export function renderLatestMd(s, { screenshotsSection = "" } = {}) {
+export function renderLatestMd(s) {
   const captured = s.capturedAt.slice(0, 10);
   const staleOn = new Date(Date.parse(s.capturedAt) + 30 * DAY).toISOString().slice(0, 10);
   const g = s.demographics.gender ?? [];
@@ -196,9 +197,9 @@ engagement by reach. Audience is mostly developers, engineers, and tech workers.
 Use these exact figures, never ones from older drafts or the voice file. Never use this framing
 unprompted, to justify a rate, or to correct a brand's benchmark.
 
-${screenshotsSection.trim() || `## Screenshots to attach on request
-Screenshots live in \`screenshots/\`; newest by date prefix is current. If none are newer than this
-snapshot's window, say the numbers come from Instagram's own insights and offer a screenshot on request.`}
+## Screenshots
+Which screenshot files you may attach is listed in the SCREENSHOTS YOU CAN ATTACH block. Attach them
+only when a brand asks.
 `;
 }
 
@@ -223,14 +224,15 @@ export async function refreshStats() {
   token = await maybeRefreshToken(token);
   const stats = await fetchIgStats(token);
 
-  // Keep the screenshot list only if it has a capture inside this window;
-  // June screenshots next to September numbers would contradict the kit.
-  const prior = existsSync(LATEST_MD) ? readFileSync(LATEST_MD, "utf8") : "";
-  const shotsSection = prior.match(/## Screenshots to attach on request[\s\S]*$/)?.[0] ?? "";
-  const shotDates = [...shotsSection.matchAll(/screenshots\/(\d{4}-\d{2}-\d{2})/g)].map((m) => m[1]);
-  const shots = shotDates.some((d) => d >= stats.windowStart) ? shotsSection : "";
-  writeFileSync(LATEST_MD, renderLatestMd(stats, { screenshotsSection: shots }));
+  // Which screenshots may go to a brand is worked out from the files
+  // themselves (screenshots.js) and handed to the drafting agent directly, so
+  // latest.md no longer carries a list that a refresh could wipe.
+  writeFileSync(LATEST_MD, renderLatestMd(stats));
   writeFileSync(LATEST_JSON, JSON.stringify(stats, null, 2));
+
+  const current = currentScreenshots();
+  stats.screenshotsStale = current.length === 0 && listScreenshots().length > 0;
+  stats.newestScreenshot = listScreenshots()[0]?.date ?? null;
   return stats;
 }
 

package/worker/index.js

@@ -18,6 +18,7 @@ import {
   runChat,
   runDraft,
   runCompact,
+  runRederive,
   runEdit,
   runLearn,
   runScan,
@@ -78,6 +79,8 @@ async function handle(job) {
       return runEdit(job);
     case "compact":
       return runCompact(job);
+    case "rederive":
+      return runRederive(job);
     // Brand Outreach (its own tool on the site; same worker, same token).
     case "outreach-chat":
       return runOutreachChat(job);

package/worker/rederive.js

@@ -0,0 +1,272 @@
+// Rebuilding a record from the email, instead of from a story about the email.
+//
+// The records were first derived by reading each ledger — a chronological
+// journal the agent had written over months. That journal never contained the
+// payment-rail mail (nothing fetched it until now), and it inherited whatever
+// the ledger had got wrong. The result looked authoritative and was not:
+// finished deals showing as in-flight, a $14,000 payment scored 40% confident,
+// a campaign filed under the wrong brand name.
+//
+// This goes back to the source. For each brand: its current record, its real
+// threads, and any payment mail that plausibly settles its invoices. The agent
+// corrects only what the email actually evidences, and says what changed.
+//
+// It is deliberately narrow. It does not touch voice, decisions, or anything
+// the creator confirmed by hand — only the facts that email can settle.
+
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { oneShot, parseJson } from "./claude.js";
+import { fetchThreads, paymentQuery, searchThreads } from "./gmail.js";
+import { BRAND_DIR, DEALS_DIR } from "./paths.js";
+import { mergeRecord, parseRecord, sanitizeInvoice, serializeRecord } from "./record.js";
+
+/** Threads per brand handed to the agent. Newest first; older ones add noise. */
+const MAX_THREADS = 6;
+const MAX_BODY = 2_500;
+
+const renderThread = (t) =>
+  [
+    `--- ${t.subject} (${t.last?.date ?? "?"}) ---`,
+    ...(t.messages ?? []).slice(-3).map((m) => {
+      const who = m.fromMe ? "HER" : m.from;
+      return `[${who}] ${String(m.body ?? "").slice(0, MAX_BODY)}`;
+    }),
+  ].join("\n");
+
+const prompt = ({ record, threads, payments }) =>
+  [
+    `You are correcting one brand record against the creator's actual email.`,
+    `The record was built by summarizing an old journal, so it may be wrong about`,
+    `what stage the deal is at, whether it was paid, or even which brand it is.`,
+    ``,
+    `Correct ONLY what the email below evidences. If the email is silent on a`,
+    `field, leave it out of your answer entirely — do not restate it, and do not`,
+    `guess. Returning nothing is a valid and common answer.`,
+    ``,
+    `STAGE, what the words mean here:`,
+    `  negotiating  in conversation, nothing signed`,
+    `  contract     signed, work not started or in progress`,
+    `  producing    actively making the deliverables`,
+    `  posted       the content is live and delivered`,
+    `  awaiting_pay delivered, invoice outstanding`,
+    `  paid         delivered AND the money has landed`,
+    `  declined     she or they said no`,
+    `A deal where the work is done and the money arrived is "paid", not "posted".`,
+    ``,
+    `PAYMENT. A payment-rail email (Mercury, Stripe, PayPal, a bank) confirming an`,
+    `amount that matches an invoice is the strongest evidence there is — score it`,
+    `0.9 and mark the invoice paid. A brand saying "processed" or "sent" without a`,
+    `rail confirmation is 0.6 and NOT paid. Never write the "confirmed" field; that`,
+    `is the creator's own answer and yours would silence her being asked.`,
+    ``,
+    `BRAND IDENTITY. If the email shows this record is actually a different brand,`,
+    `or a campaign belonging to another brand, say so in "brandCorrection" — do not`,
+    `quietly rename it.`,
+    ``,
+    `CURRENT RECORD`,
+    `=====`,
+    JSON.stringify(record, null, 2).slice(0, 6_000),
+    `=====`,
+    ``,
+    `HER THREADS WITH THIS BRAND (newest last)`,
+    `=====`,
+    threads.length ? threads.map(renderThread).join("\n\n") : "(no threads matched this brand)",
+    `=====`,
+    ``,
+    `PAYMENT MAIL THAT MIGHT SETTLE THIS DEAL`,
+    `=====`,
+    payments.length ? payments.map(renderThread).join("\n\n") : "(none found)",
+    `=====`,
+    ``,
+    `Output ONLY a fenced \`\`\`json block. Omit any field the email does not settle:`,
+    `{"stage":"…","whoseMove":"you|them",`,
+    ` "money":{"invoices":[{"id":"inv-1","amount":0,"status":"paid|unpaid","paidAt":"YYYY-MM-DD",`,
+    `           "confidence":0.0,"evidence":"<quote the line that proves it>"}]},`,
+    ` "brandCorrection":"<only if this is the wrong brand entirely>",`,
+    ` "changed":"<one line: what you corrected and why, or 'nothing'>"}`,
+  ].join("\n");
+
+/** Payment mail plausibly about this brand: names it, or matches an amount. */
+function paymentsFor(record, allPayments) {
+  const name = String(record.brand ?? "").toLowerCase();
+  const amounts = (record.money?.invoices ?? [])
+    .map((i) => i.amount)
+    .filter((n) => typeof n === "number")
+    .flatMap((n) => [String(n), n.toLocaleString("en-US")]);
+
+  return allPayments.filter((t) => {
+    const hay = `${t.subject ?? ""} ${(t.messages ?? []).map((m) => m.body ?? "").join(" ")}`.toLowerCase();
+    if (name.length > 3 && hay.includes(name)) return true;
+    return amounts.some((a) => hay.includes(a));
+  });
+}
+
+/**
+ * Re-derive every record we have evidence for.
+ *
+ * `onProgress` is called per brand so a long run is visible rather than silent.
+ * Brands with no threads and no payment mail are skipped outright — there is
+ * nothing to correct against, and asking anyway would invite invention.
+ */
+export async function rederiveAll(accessToken, accountEmail, { onProgress, write = false } = {}) {
+  const [brandThreads, paymentThreads] = await Promise.all([
+    fetchThreads(accessToken, accountEmail, { brandOnly: true }),
+    searchThreads(accessToken, accountEmail, paymentQuery()),
+  ]);
+
+  const files = existsSync(DEALS_DIR)
+    ? readdirSync(DEALS_DIR).filter((n) => n.endsWith(".md")).sort()
+    : [];
+
+  // Every brand we know about, so a thread from an agency contact can be
+  // assigned to the one it actually names rather than all of them.
+  setKnownBrands(
+    files
+      .map((f) => parseRecord(readFileSync(join(DEALS_DIR, f), "utf8")).record?.brand)
+      .filter(Boolean),
+  );
+
+  const results = [];
+
+  for (const file of files) {
+    const slug = file.replace(/\.md$/, "");
+    const path = join(DEALS_DIR, file);
+    const md = readFileSync(path, "utf8");
+    const { record, decisions } = parseRecord(md);
+    if (!record) continue;
+
+    const mine = threadsForRecord(record, brandThreads).slice(-MAX_THREADS);
+    const payments = paymentsFor(record, paymentThreads);
+
+    if (!mine.length && !payments.length) {
+      results.push({ slug, skipped: "no email evidence" });
+      onProgress?.(results.at(-1));
+      continue;
+    }
+
+    let out = null;
+    try {
+      out = parseJson(
+        await oneShot(prompt({ record, threads: mine, payments }), {
+          cwd: BRAND_DIR,
+          timeoutMs: 6 * 60 * 1000,
+        }),
+      );
+    } catch (err) {
+      results.push({ slug, error: err?.message ?? String(err) });
+      onProgress?.(results.at(-1));
+      continue;
+    }
+
+    const changed = out?.changed && !/^nothing/i.test(out.changed) ? out.changed : null;
+    if (!changed && !out?.stage && !out?.money) {
+      results.push({ slug, skipped: "email confirms the record" });
+      onProgress?.(results.at(-1));
+      continue;
+    }
+
+    const { changed: _c, brandCorrection, ...updates } = out ?? {};
+    // Invoices from the agent get scrubbed of any `confirmed` it invented.
+    if (updates.money?.invoices) {
+      updates.money.invoices = updates.money.invoices.map(sanitizeInvoice).map((i) => {
+        const { confirmed, confirmedAt, ...rest } = i;
+        return rest;
+      });
+    }
+
+    const next = mergeRecord(record, updates);
+    const result = {
+      slug,
+      changed,
+      brandCorrection: brandCorrection ?? null,
+      from: { stage: record.stage, paid: paidCount(record) },
+      to: { stage: next.stage, paid: paidCount(next) },
+    };
+
+    if (write) {
+      writeFileSync(
+        path,
+        serializeRecord({
+          record: next,
+          decisions,
+          archiveRef: existsSync(join(DEALS_DIR, "..", "archive", file)) ? `archive/${file}` : null,
+        }),
+      );
+    }
+
+    results.push(result);
+    onProgress?.(result);
+  }
+
+  return results;
+}
+
+const paidCount = (r) => (r.money?.invoices ?? []).filter((i) => i.status === "paid").length;
+
+/**
+ * Threads belonging to this record.
+ *
+ * Address first, then the brand's own name in the text, then the domain.
+ *
+ * The name check is what makes agency deals work at all. Rebekah Greene at
+ * Freeman & Forrest brokers Atlassian, Microsoft, MongoDB and Radar, so her
+ * address belongs to four different brands and her domain resolves to none of
+ * them unambiguously — matching on sender alone left all four with no threads
+ * and skipped them outright. But the brand is named in the mail: that is what
+ * the thread is about. So the name decides which of an agency's deals a thread
+ * belongs to, and the domain is only a last resort for a brand that nothing
+ * else claimed.
+ */
+export function threadsForRecord(record, threads) {
+  const emails = new Set(
+    [...(record.contacts ?? []), record.agency?.contact ?? ""]
+      .map((c) => String(c).match(/<([^>]+)>/)?.[1]?.toLowerCase() ?? String(c).toLowerCase())
+      .filter((e) => e.includes("@")),
+  );
+  const domains = new Set([...emails].map((e) => e.split("@")[1]).filter(Boolean));
+  const name = String(record.brand ?? "").trim().toLowerCase();
+  // Two characters would match half the inbox; "X1" style names lose out here,
+  // and that is the right way round — a false match corrects a record against
+  // somebody else's deal.
+  const nameUsable = name.length >= 3;
+
+  const namedIn = (t) => {
+    if (!nameUsable) return false;
+    const hay = [t.subject ?? "", ...(t.messages ?? []).map((m) => m.body ?? "")]
+      .join(" ")
+      .toLowerCase();
+    return hay.includes(name);
+  };
+
+  return threads.filter((t) => {
+    const from = String(t.last?.from ?? "").toLowerCase();
+    const addr = from.match(/<([^>]+)>/)?.[1] ?? from;
+    const domain = addr.split("@")[1];
+
+    // From a known contact: theirs, unless the mail names a different brand of
+    // the same agency — then it belongs to that one instead.
+    if (emails.has(addr)) return nameUsable ? namedIn(t) || !mentionsAnotherBrand(t, record) : true;
+    if (namedIn(t)) return true;
+    return domain ? domains.has(domain) : false;
+  });
+}
+
+/**
+ * Does this thread name some brand other than this record's? Used to stop an
+ * agency contact's mail about Microsoft being folded into the Atlassian record
+ * just because it came from the same person.
+ */
+let knownBrandNames = null;
+export function setKnownBrands(names) {
+  knownBrandNames = names.map((n) => String(n).trim().toLowerCase()).filter((n) => n.length >= 3);
+}
+
+function mentionsAnotherBrand(t, record) {
+  if (!knownBrandNames?.length) return false;
+  const mine = String(record.brand ?? "").trim().toLowerCase();
+  const hay = [t.subject ?? "", ...(t.messages ?? []).map((m) => m.body ?? "")]
+    .join(" ")
+    .toLowerCase();
+  return knownBrandNames.some((n) => n !== mine && hay.includes(n));
+}

package/worker/screenshots.js

@@ -0,0 +1,78 @@
+// The stat screenshots a brand gets when it asks to see insights.
+//
+// They're uploaded on the Brand Manager page, and runStats saves each batch
+// here as <YYYY-MM-DD>-<n>.<ext>. Deciding which ones are current is done in
+// code, not left to the drafting agent: that agent runs without tools and
+// can't list a folder, so it only ever attaches files it's been told about.
+//
+// A new upload moves the previous batch into archive/, so the folder holds
+// one set, and "current" also means "recent enough": older than
+// MAX_AGE_DAYS and they'd contradict the live numbers they sit beside.
+
+import { existsSync, mkdirSync, readdirSync, renameSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { SCREENSHOTS_DIR } from "./paths.js";
+
+export const MAX_AGE_DAYS = 30;
+const DAY = 24 * 60 * 60 * 1000;
+const IMAGE = /\.(png|jpe?g|webp)$/i;
+
+/** The date a screenshot was saved: its YYYY-MM-DD prefix, else the file's mtime. */
+function fileDate(dir, name) {
+  const m = name.match(/^(\d{4}-\d{2}-\d{2})/);
+  if (m) return m[1];
+  return statSync(join(dir, name)).mtime.toISOString().slice(0, 10);
+}
+
+/** Every screenshot in the folder (not the archive), newest first. */
+export function listScreenshots(dir = SCREENSHOTS_DIR) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && IMAGE.test(e.name))
+    .map((e) => ({ name: e.name, date: fileDate(dir, e.name) }))
+    .sort((a, b) => (a.date === b.date ? a.name.localeCompare(b.name) : b.date.localeCompare(a.date)));
+}
+
+/**
+ * The screenshots that may go to a brand: saved within MAX_AGE_DAYS. Paths
+ * are relative to the brand-manager folder, the form a draft's
+ * `attachments` uses.
+ */
+export function currentScreenshots({ dir = SCREENSHOTS_DIR, now = new Date(), maxAgeDays = MAX_AGE_DAYS } = {}) {
+  const cutoff = new Date(now.getTime() - maxAgeDays * DAY).toISOString().slice(0, 10);
+  return listScreenshots(dir)
+    .filter((s) => s.date >= cutoff)
+    .map((s) => ({ ...s, path: `stats/screenshots/${s.name}` }));
+}
+
+/** Move the whole current set into archive/, before a new upload lands. */
+export function archiveScreenshots(dir = SCREENSHOTS_DIR) {
+  const shots = listScreenshots(dir);
+  if (shots.length === 0) return 0;
+  const archive = join(dir, "archive");
+  mkdirSync(archive, { recursive: true });
+  for (const s of shots) {
+    let dest = join(archive, s.name);
+    // Two uploads on the same day reuse names; keep both rather than overwrite.
+    for (let n = 1; existsSync(dest); n++) dest = join(archive, s.name.replace(IMAGE, `~${n}$&`));
+    renameSync(join(dir, s.name), dest);
+  }
+  return shots.length;
+}
+
+/** The block the drafting agent reads: exactly which files it may attach. */
+export function screenshotsBlock(current) {
+  if (current.length === 0) {
+    return [
+      "### SCREENSHOTS YOU CAN ATTACH",
+      "None are current. Attach nothing. If a brand asks for screenshots, say you'll send current ones",
+      'over, and add the flag "stat screenshots out of date: upload fresh ones on the Brand Manager page".',
+    ].join("\n");
+  }
+  return [
+    "### SCREENSHOTS YOU CAN ATTACH",
+    `Current (saved ${current[0].date}). Attach these, and only these, when a brand asks for stats,`,
+    "screenshots or proof of reach. Never attach them unprompted.",
+    ...current.map((s) => `- ${s.path}`),
+  ].join("\n");
+}