Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

fix(tracking): hold a run's stamp until Cloro's late answers are in (#856)

Gökhan Geyikdc4a5af82baa
diff --git a/server/src/lib/job-runner.js b/server/src/lib/job-runner.js
index 06f9bb325..ec0836159 100644
--- a/server/src/lib/job-runner.js
+++ b/server/src/lib/job-runner.js
@@ -71,7 +71,9 @@ export async function runTrackingJob(jobId, io) {
job: proxy,
});
- await completeJob(jobId, result);
+ // The late-stamp promise is not job state; only the counts are stored.
+ const { lateStamp, ...stored } = result;
+ await completeJob(jobId, stored);
if (io) {
io.emit('tracking:complete', {
@@ -81,17 +83,17 @@ export async function runTrackingJob(jobId, io) {
});
}
- // Daily Pulse (#540): fire-and-forget after a full daily run — never
- // for immediate/manual runs or single-prompt refreshes. The engine is
- // self-contained: eligibility checks, dedup and error handling inside.
- //
- // Skipped when the run wasn't stamped (#702). An unstamped run left the
- // 24h anchor on the previous run, so the pulse would recompute that same
- // window and mail figures the recipient already received — which is
- // exactly what happened for three days on the largest brand. The catch-up
- // sweep picks the day back up once a run does stamp.
- if (!immediate && !promptId && !promptIds?.length) {
- if (result?.stamped) {
+ const fullRun = !promptId && !promptIds?.length;
+
+ // What a full run's stamp sets off. The run may stamp now, or later once
+ // Cloro's late answers arrive (lib/run-settlement) — either way this runs
+ // exactly once, after the stamp, so it reads the finished window.
+ const afterStamp = () => {
+ if (!fullRun) return;
+ if (!immediate) {
+ // Daily Pulse (#540): after a full daily run only — never for manual
+ // runs or single-prompt refreshes. The engine is self-contained:
+ // eligibility checks, dedup and error handling inside.
generatePulseForBrand(brandId).catch((err) => {
logger.error({ err, brandId }, 'daily pulse trigger failed');
});
@@ -107,21 +109,37 @@ export async function runTrackingJob(jobId, io) {
logger.error({ err, brandId }, '[signals] pass failed — catch-up will retry');
});
} else {
- logger.warn(
- { brandId, resultCount: result?.resultCount },
- 'skipping daily pulse — tracking run was not stamped, window would be stale',
- );
+ // A new brand's first run is a manual one, and passes otherwise wait
+ // for the night. It gets one now so the Action Center is not empty
+ // until tomorrow; the function is a no-op for a brand that already
+ // had one.
+ runFirstSignalPass(brandId).catch((err) => {
+ logger.error(
+ { err, brandId },
+ '[signals] first pass failed — the nightly pass will cover it',
+ );
+ });
}
- } else if (immediate && !promptId && !promptIds?.length && result?.stamped) {
- // A new brand's first run is a manual one, and passes otherwise wait for
- // the night. It gets one now so the Action Center is not empty until
- // tomorrow; the function is a no-op for a brand that already had one.
- runFirstSignalPass(brandId).catch((err) => {
- logger.error(
- { err, brandId },
- '[signals] first pass failed — the nightly pass will cover it',
- );
+ };
+
+ // Skipped when the run never stamps (#702). An unstamped run left the 24h
+ // anchor on the previous run, so the pulse would recompute that same
+ // window and mail figures the recipient already received. The catch-up
+ // sweep picks the day back up once a run does stamp.
+ if (result?.stamped) {
+ afterStamp();
+ } else if (lateStamp) {
+ lateStamp.then((stamped) => {
+ if (stamped) afterStamp();
+ else if (fullRun && !immediate) {
+ logger.warn({ brandId }, 'skipping daily pulse — tracking run never stamped');
+ }
});
+ } else if (fullRun && !immediate) {
+ logger.warn(
+ { brandId, resultCount: result?.resultCount },
+ 'skipping daily pulse — tracking run was not stamped, window would be stale',
+ );
}
} catch (err) {
if (abortController.signal.aborted) {
diff --git a/server/src/lib/pulse/email.js b/server/src/lib/pulse/email.js
index 3a710478f..578780bb2 100644
--- a/server/src/lib/pulse/email.js
+++ b/server/src/lib/pulse/email.js
@@ -135,7 +135,7 @@ export function renderPulseEmail({ brandName, metrics, insightsUrl, settingsUrl
</tr>
<tr>
${kpiCell('Positive sentiment', `${kpis.sentimentPct}%`, kpis.sentimentChange)}
- ${kpiCell('Prompts covered', `${kpis.visiblePrompts}/${kpis.promptCount}`, null)}
+ ${kpiCell('Prompts you appear in', `${kpis.visiblePrompts}/${kpis.promptCount}`, null)}
</tr>
</table>
diff --git a/server/src/lib/run-settlement.js b/server/src/lib/run-settlement.js
new file mode 100644
index 000000000..905ac5006
--- /dev/null
+++ b/server/src/lib/run-settlement.js
@@ -0,0 +1,177 @@
+/**
+ * Closing a full tracking run's ledger row (00044) — "stamping" it.
+ *
+ * The stamp is what everything downstream waits on: the 24h window the
+ * dashboard and the Daily Pulse read ends at it, and the pulse, signal pass
+ * and Insights rollup refresh all fire when it lands. Stamping while Cloro is
+ * still delivering freezes a half-answered run into those windows: on the
+ * largest brand the drain deadline passed with 54% of answers in, the run
+ * stamped anyway (the old bar was 50%), and the pulse reported 495 of 709
+ * prompts. The rest arrived over the next 37 minutes.
+ *
+ * So a run that ends its drain short of COMPLETE_RATIO is not stamped yet.
+ * The worker hands back a promise instead and moves on — its concurrency slot
+ * freed — while this module keeps counting in the background. The run stamps
+ * as soon as it is complete, when nothing it submitted is pending any more,
+ * or at the late deadline — then only if it reached MIN_STAMP_RATIO, the bar
+ * that keeps a near-empty run from ever becoming the window.
+ *
+ * A restart during the wait loses it: the row stays unstamped, that day's
+ * pulse is skipped, and the next run clears the row — the same outcome an
+ * unstamped run always had.
+ */
+
+import supabaseAdmin from '../config/supabase.js';
+import { refreshForCompletedRun } from './insights-rollups.js';
+import { logger } from './logger.js';
+
+export const COMPLETE_RATIO = 0.95;
+export const MIN_STAMP_RATIO = 0.5;
+const LATE_POLL_MS = 2 * 60_000;
+const LATE_WAIT_MS = (Number(process.env.CLORO_LATE_WAIT_MIN) || 120) * 60_000;
+
+/**
+ * What to do with a run's ledger row given how many results it has.
+ * `final` is true once waiting longer cannot help: the late deadline passed,
+ * or nothing the run submitted is still pending.
+ *
+ * @returns {'stamp' | 'wait' | 'discard'}
+ */
+export function settleDecision({ resultCount, plannedTasks, final }) {
+ if (resultCount <= 0) return final ? 'discard' : 'wait';
+ if (plannedTasks <= 0 || resultCount >= plannedTasks * COMPLETE_RATIO) return 'stamp';
+ if (!final) return 'wait';
+ return resultCount >= plannedTasks * MIN_STAMP_RATIO ? 'stamp' : 'discard';
+}
+
+/**
+ * The run's result count comes from the DB, not from the worker's counter:
+ * in webhook mode the /cloro/callback handler inserts the scraper results,
+ * so the worker only ever sees its own API-model phase.
+ */
+async function countRunResults(brandId, startedAt) {
+ const { count, error } = await supabaseAdmin
+ .from('prompt_results')
+ .select('id', { count: 'exact', head: true })
+ .eq('brand_id', brandId)
+ .gte('created_at', startedAt);
+ return error ? null : (count ?? 0);
+}
+
+/** Cloro tasks this run submitted that have not been answered yet. */
+async function countRunPending(brandId, startedAt) {
+ const { count, error } = await supabaseAdmin
+ .from('cloro_pending_tasks')
+ .select('task_id', { count: 'exact', head: true })
+ .eq('brand_id', brandId)
+ .gte('submitted_at', startedAt);
+ return error ? null : (count ?? 0);
+}
+
+/**
+ * Stamp the row, unless it is gone — a later run for the brand clears
+ * unstamped rows, and a run that was superseded must not fire a pulse.
+ */
+async function stampRun(brandId, runId, startedAt, resultCount) {
+ const { data, error } = await supabaseAdmin
+ .from('tracking_runs')
+ .update({ completed_at: new Date().toISOString(), result_count: resultCount })
+ .eq('id', runId)
+ .is('completed_at', null)
+ .select('id');
+ if (error) {
+ logger.error({ err: error, brandId, runId }, 'failed to stamp tracking run');
+ return false;
+ }
+ if (!data?.length) {
+ logger.warn({ brandId, runId }, 'tracking run row gone before it stamped — superseded');
+ return false;
+ }
+ logger.info({ brandId, runId, resultCount }, 'tracking run stamped');
+
+ // Fold the run's days into the Insights rollups (00066). Anchored to the
+ // stamp on purpose: a day enters the wide-window aggregates only once its
+ // run completed, so mid-run partial counts never show. Best-effort inside —
+ // a refresh failure never unstamps the run.
+ await refreshForCompletedRun(brandId, startedAt);
+ return true;
+}
+
+async function discardRun(brandId, runId, resultCount, plannedTasks) {
+ logger.warn(
+ { brandId, runId, resultCount, plannedTasks },
+ 'tracking run below stamp ratio — row removed; window stays on previous run',
+ );
+ await supabaseAdmin.from('tracking_runs').delete().eq('id', runId);
+}
+
+async function act(decision, { brandId, runId, startedAt, plannedTasks }, resultCount) {
+ if (decision === 'stamp') return stampRun(brandId, runId, startedAt, resultCount);
+ await discardRun(brandId, runId, resultCount, plannedTasks);
+ return false;
+}
+
+async function awaitLateResults(run, { pollMs, waitMs }) {
+ const deadline = Date.now() + waitMs;
+ for (;;) {
+ await new Promise((r) => setTimeout(r, pollMs));
+ const [resultCount, pending] = await Promise.all([
+ countRunResults(run.brandId, run.startedAt),
+ countRunPending(run.brandId, run.startedAt),
+ ]);
+ const pastDeadline = Date.now() >= deadline;
+ if (resultCount === null) {
+ // A failed count must not be read as "no results". Keep waiting; past
+ // the deadline, leave the row for the next run to clear.
+ if (pastDeadline) return false;
+ continue;
+ }
+ const decision = settleDecision({
+ resultCount,
+ plannedTasks: run.plannedTasks,
+ final: pastDeadline || pending === 0,
+ });
+ if (decision === 'wait') continue;
+ logger.info(
+ { brandId: run.brandId, runId: run.runId, resultCount, plannedTasks: run.plannedTasks },
+ 'late results settled the tracking run',
+ );
+ return act(decision, run, resultCount);
+ }
+}
+
+/**
+ * Settle a full run's ledger row at the end of its drain.
+ *
+ * @returns {Promise<{ stamped: boolean, lateStamp: Promise<boolean> | null }>}
+ * `stamped` when the row stamped now; otherwise `lateStamp` resolves true
+ * if and when it stamps later, false if it never does.
+ */
+export async function settleTrackingRun(
+ { brandId, runId, startedAt, plannedTasks },
+ { pollMs = LATE_POLL_MS, waitMs = LATE_WAIT_MS } = {},
+) {
+ const run = { brandId, runId, startedAt, plannedTasks };
+ const resultCount = await countRunResults(brandId, startedAt);
+ if (resultCount === null) {
+ // Leave the row uncompleted: the dashboard keeps the previous completed
+ // run and the next run clears the dangling row.
+ logger.error({ brandId, runId }, 'failed to count run results');
+ return { stamped: false, lateStamp: null };
+ }
+
+ const pending = await countRunPending(brandId, startedAt);
+ const decision = settleDecision({ resultCount, plannedTasks, final: pending === 0 });
+ if (decision !== 'wait')
+ return { stamped: await act(decision, run, resultCount), lateStamp: null };
+
+ logger.info(
+ { brandId, runId, resultCount, plannedTasks, pending },
+ 'tracking run short of complete — waiting for late results before stamping',
+ );
+ const lateStamp = awaitLateResults(run, { pollMs, waitMs }).catch((err) => {
+ logger.error({ err, brandId, runId }, 'waiting for late results failed');
+ return false;
+ });
+ return { stamped: false, lateStamp };
+}
diff --git a/server/src/lib/run-settlement.test.js b/server/src/lib/run-settlement.test.js
new file mode 100644
index 000000000..24e38defc
--- /dev/null
+++ b/server/src/lib/run-settlement.test.js
@@ -0,0 +1,141 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// A stand-in for the few PostgREST chains run-settlement uses. Each table
+// answers from `db`, which a test rewrites between polls.
+const db = { results: 0, pending: 0, rowExists: true, stamped: null, deleted: false };
+
+function builder(table) {
+ const q = { table, op: 'select' };
+ const chain = {
+ select: () => chain,
+ eq: () => chain,
+ gte: () => chain,
+ is: () => chain,
+ update: (values) => {
+ q.op = 'update';
+ q.values = values;
+ return chain;
+ },
+ delete: () => {
+ q.op = 'delete';
+ return chain;
+ },
+ then: (resolve) => resolve(answer(q)),
+ };
+ return chain;
+}
+
+function answer(q) {
+ if (q.table === 'prompt_results') return { count: db.results, error: null };
+ if (q.table === 'cloro_pending_tasks') return { count: db.pending, error: null };
+ if (q.table === 'tracking_runs' && q.op === 'update') {
+ if (!db.rowExists) return { data: [], error: null };
+ db.stamped = q.values;
+ return { data: [{ id: 'run-1' }], error: null };
+ }
+ if (q.table === 'tracking_runs' && q.op === 'delete') {
+ db.deleted = true;
+ return { error: null };
+ }
+ throw new Error(`unexpected query on ${q.table}`);
+}
+
+vi.mock('../config/supabase.js', () => ({ default: { from: (t) => builder(t) } }));
+vi.mock('./insights-rollups.js', () => ({ refreshForCompletedRun: vi.fn(async () => {}) }));
+vi.mock('./logger.js', () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+const { settleDecision, settleTrackingRun } = await import('./run-settlement.js');
+
+const run = { brandId: 'b1', runId: 'run-1', startedAt: '2026-09-30T03:09:50Z', plannedTasks: 100 };
+const fast = { pollMs: 1, waitMs: 50 };
+
+beforeEach(() => {
+ Object.assign(db, { results: 0, pending: 0, rowExists: true, stamped: null, deleted: false });
+});
+
+describe('settleDecision', () => {
+ it('stamps a complete run', () => {
+ expect(settleDecision({ resultCount: 95, plannedTasks: 100, final: false })).toBe('stamp');
+ });
+
+ it('waits on a run that is only half in', () => {
+ expect(settleDecision({ resultCount: 54, plannedTasks: 100, final: false })).toBe('wait');
+ });
+
+ it('stamps a half-in run once waiting cannot help', () => {
+ expect(settleDecision({ resultCount: 54, plannedTasks: 100, final: true })).toBe('stamp');
+ });
+
+ it('discards a near-empty run once waiting cannot help', () => {
+ expect(settleDecision({ resultCount: 30, plannedTasks: 100, final: true })).toBe('discard');
+ expect(settleDecision({ resultCount: 0, plannedTasks: 100, final: true })).toBe('discard');
+ });
+
+ it('waits on a run with nothing in yet while answers are pending', () => {
+ expect(settleDecision({ resultCount: 0, plannedTasks: 100, final: false })).toBe('wait');
+ });
+
+ it('stamps any results when nothing was planned', () => {
+ expect(settleDecision({ resultCount: 3, plannedTasks: 0, final: false })).toBe('stamp');
+ });
+});
+
+describe('settleTrackingRun', () => {
+ it('stamps at once when the run is complete', async () => {
+ db.results = 98;
+ db.pending = 2;
+ const out = await settleTrackingRun(run, fast);
+ expect(out).toEqual({ stamped: true, lateStamp: null });
+ expect(db.stamped.result_count).toBe(98);
+ });
+
+ it('holds a short run and stamps it once the late answers arrive', async () => {
+ db.results = 54;
+ db.pending = 46;
+ const out = await settleTrackingRun(run, { pollMs: 5, waitMs: 1000 });
+ expect(out.stamped).toBe(false);
+ expect(db.stamped).toBeNull();
+
+ db.results = 97;
+ db.pending = 3;
+ await expect(out.lateStamp).resolves.toBe(true);
+ expect(db.stamped.result_count).toBe(97);
+ });
+
+ it('stamps a short run early when nothing is pending any more', async () => {
+ db.results = 80;
+ db.pending = 20;
+ const out = await settleTrackingRun(run, { pollMs: 5, waitMs: 60_000 });
+ db.pending = 0;
+ await expect(out.lateStamp).resolves.toBe(true);
+ expect(db.stamped.result_count).toBe(80);
+ });
+
+ it('stamps what arrived at the deadline when it clears the minimum', async () => {
+ db.results = 60;
+ db.pending = 40;
+ const out = await settleTrackingRun(run, fast);
+ await expect(out.lateStamp).resolves.toBe(true);
+ expect(db.stamped.result_count).toBe(60);
+ });
+
+ it('removes the row at the deadline when too little arrived', async () => {
+ db.results = 20;
+ db.pending = 80;
+ const out = await settleTrackingRun(run, fast);
+ await expect(out.lateStamp).resolves.toBe(false);
+ expect(db.deleted).toBe(true);
+ expect(db.stamped).toBeNull();
+ });
+
+ it('does not stamp a run whose row a later run already cleared', async () => {
+ db.results = 54;
+ db.pending = 46;
+ const out = await settleTrackingRun(run, { pollMs: 5, waitMs: 1000 });
+ db.rowExists = false;
+ db.results = 99;
+ await expect(out.lateStamp).resolves.toBe(false);
+ });
+});
diff --git a/server/src/workers/tracking-worker.js b/server/src/workers/tracking-worker.js
index 0bb9a6537..5163c1105 100644
--- a/server/src/workers/tracking-worker.js
+++ b/server/src/workers/tracking-worker.js
@@ -13,7 +13,7 @@ import { generateContentOpportunities } from '../lib/opportunity-generator.js';
import { updateTargetUrlStats } from '../lib/target-url-stats.js';
import { persistCitationRows } from '../lib/citation-rows.js';
import { parseLocation, locationsForScraper } from '../lib/locations.js';
-import { refreshForCompletedRun } from '../lib/insights-rollups.js';
+import { settleTrackingRun } from '../lib/run-settlement.js';
import logger from '../lib/logger.js';
function resolveModelPlatform(model) {
@@ -855,71 +855,24 @@ export async function processTrackingJob({ brandId, promptId, promptIds, source,
logger.error({ err, brandId }, 'failed to check opportunity generation eligibility');
}
- // Stamp the ledger row. The run's result count MUST come from the DB, not
- // from `insertedCount`: in webhook mode the scraper results are inserted by
- // the /cloro/callback handler, so the worker's own counter only sees the
- // API-model phase — on scraper-only brands it stays 0 even after a fully
- // successful run, and the first deploy of this ledger deleted every real
- // run's row because of it. Zero results in the DB (every task genuinely
- // failed) still deletes the row: completing it would swing the 24h anchor
- // onto an empty window. On a count error we leave the row uncompleted —
- // the dashboard keeps the previous completed run and the next run clears
- // the dangling row.
- let runStamped = false;
-
- if (trackingRunId) {
- const { count: runResultCount, error: countErr } = await supabaseAdmin
- .from('prompt_results')
- .select('id', { count: 'exact', head: true })
- .eq('brand_id', brandId)
- .gte('created_at', trackingRunStartedAt);
-
- // Partial-run guard: a run that produced far fewer results than it
- // planned tasks (Cloro delivered late/never) must not become the 24h
- // anchor — a half-empty window reads as a visibility crash in the
- // dashboard and the pulse mail. The ratio compares against THIS run's
- // own planned task count, never against history, so a brand that
- // legitimately shrinks its prompt set can't wedge the guard. Late
- // results that land after the previous anchor stay visible in the next
- // stamped window — nothing is lost, the anchor just refuses to move
- // onto partial data.
- const MIN_STAMP_RATIO = 0.5;
- const isPartial = totalTasks > 0 && (runResultCount ?? 0) < totalTasks * MIN_STAMP_RATIO;
-
- if (countErr) {
- logger.error({ err: countErr, brandId, trackingRunId }, 'failed to count run results');
- } else if ((runResultCount ?? 0) > 0 && !isPartial) {
- const { error: stampErr } = await supabaseAdmin
- .from('tracking_runs')
- .update({ completed_at: new Date().toISOString(), result_count: runResultCount })
- .eq('id', trackingRunId);
- if (stampErr) {
- logger.error({ err: stampErr, brandId, trackingRunId }, 'failed to stamp tracking run');
- } else {
- runStamped = true;
- logger.info({ brandId, trackingRunId, runResultCount }, 'tracking run stamped');
-
- // Fold the run's days into the Insights rollups (00066). Anchored to
- // the stamp on purpose: a day enters the wide-window aggregates only
- // once its run completed, so mid-run partial counts never show. Runs
- // that never reach this point are picked up by the daily sweep.
- // Best-effort inside — a refresh failure never unstamps the run.
- await refreshForCompletedRun(brandId, trackingRunStartedAt);
- }
- } else if ((runResultCount ?? 0) > 0) {
- logger.warn(
- { brandId, trackingRunId, runResultCount, totalTasks },
- 'tracking run partial — below stamp ratio, row removed; window stays on previous run',
- );
- await supabaseAdmin.from('tracking_runs').delete().eq('id', trackingRunId);
- } else {
- logger.warn({ brandId, trackingRunId }, 'tracking run produced no results — row removed');
- await supabaseAdmin.from('tracking_runs').delete().eq('id', trackingRunId);
- }
- }
-
- // `stamped` gates the Daily Pulse (#702): a run whose ledger row was
- // refused never moved the 24h anchor, so its pulse would recompute the
- // previous run's window and mail numbers the recipient already has.
- return { resultCount: insertedCount, stamped: runStamped };
+ // Stamp the ledger row — or, when Cloro is still delivering, hand back a
+ // promise that stamps it once the late answers are in (lib/run-settlement).
+ // `stamped` / `lateStamp` gate the Daily Pulse and signal pass (#702): a
+ // run whose row never stamped did not move the 24h anchor, so its pulse
+ // would recompute the previous run's window and mail numbers the recipient
+ // already has.
+ const settlement = trackingRunId
+ ? await settleTrackingRun({
+ brandId,
+ runId: trackingRunId,
+ startedAt: trackingRunStartedAt,
+ plannedTasks: totalTasks,
+ })
+ : { stamped: false, lateStamp: null };
+
+ return {
+ resultCount: insertedCount,
+ stamped: settlement.stamped,
+ lateStamp: settlement.lateStamp,
+ };
}