@canonry/canonry 5.11.0 → 5.13.0

package/dist/{chunk-UYSTNPTX.js → chunk-TDHRUXN3.js}

@@ -17,12 +17,12 @@ import {
   resolveOperatorApiKeyIds,
   runWithUsageTags,
   saveConfigPatch
-} from "./chunk-JW5DCORY.js";
+} from "./chunk-IPGBK7XR.js";
 import {
   deleteSiteCrawlGraphLayout,
   persistSiteCrawlGraphLayout,
   prepareSiteCrawlGraphLayout
-} from "./chunk-JNU6GLAV.js";
+} from "./chunk-IDZQ5H3J.js";
 import {
   PACKAGE_VERSION
 } from "./chunk-AOJU5LKX.js";
@@ -134,7 +134,10 @@ import {
   loadDuckdb,
   markSessionFailed,
   measurementRunCompleteness,
+  measurementRunSlotState,
+  measurementSlotKey,
   migrate,
+  newerFullSweep,
   nextRunFromCron,
   nextRunFromSchedule,
   notifications,
@@ -164,6 +167,7 @@ import {
   resolveVercelSyncDeadlineMs,
   resolveWebhookTarget,
   runChecks,
+  runFills,
   runs,
   schedules,
   serializeUserSessionCookie,
@@ -179,7 +183,7 @@ import {
   siteLivenessState,
   toAlertView,
   usageCounters
-} from "./chunk-SMYBGUVV.js";
+} from "./chunk-Q35D2R2P.js";
 import {
   AGENT_MEMORY_VALUE_MAX_BYTES,
   AGENT_NONE,
@@ -211,6 +215,7 @@ import {
   ONBOARDING_FLOW_VERSION,
   ProviderNames,
   ROUTE_CAPABLE_CITED_URL_PROVIDERS,
+  RUN_FILL_PROVIDER_BREAKER,
   ResearchQueryStatuses,
   ResearchRunStatuses,
   RunKinds,
@@ -272,6 +277,7 @@ import {
   filterCapturedCitedUrls,
   forbidden,
   formatIsoDateInTimeZone,
+  formatRunErrorOneLine,
   frameAncestorsHeaderValue,
   googleAdsAccessibleCustomerDtoSchema,
   googleAdsAccessibleCustomersResponseSchema,
@@ -300,6 +306,7 @@ import {
   isVertexGroundingRedirect,
   mapWithConcurrency,
   maskTelemetryAnonymousId,
+  missingDependency,
   nextScheduleUpdatedAt,
   normalizeAgentSlug,
   normalizeIdTokens,
@@ -312,6 +319,7 @@ import {
   observeTemplateLinkEdges,
   parseMeasurementRunManifestV1,
   parseOriginList,
+  parseRunError,
   providerError,
   providerSupportsLocationContext,
   registrableDomain,
@@ -336,7 +344,7 @@ import {
   visibilityReportRequestSchema,
   winnabilityClassLabel,
   withRetry
-} from "./chunk-MQMJJZ6W.js";
+} from "./chunk-UWJAATGC.js";
 
 // src/runtime-context.ts
 function cliRuntimeContext(env = process.env, stdio = process) {
@@ -6482,7 +6490,7 @@ function nonBlank(value) {
   return trimmed ? trimmed : void 0;
 }
 function resolveBuildCommit(env = process.env) {
-  const embedded = true ? "d2370877dec1d1e40b88e6c56803b3eea6af4eb8" : void 0;
+  const embedded = true ? "894086f6a60be75c0ade892884adf57ef7a38291" : void 0;
   return nonBlank(embedded) ?? nonBlank(env.CANONRY_COMMIT);
 }
 function resolveInstanceIdentity(env = process.env) {
@@ -6830,6 +6838,8 @@ var JobRunner = class {
     this.registry = registry;
   }
   recoverStaleRuns() {
+    const staleFills = this.db.update(runFills).set({ status: "failed", finishedAt: (/* @__PURE__ */ new Date()).toISOString(), error: "Server restarted while the fill was in progress" }).where(inArray(runFills.status, ["queued", "running"])).run();
+    if (staleFills.changes > 0) log2.warn("fill.recovered-stale", { count: staleFills.changes });
     const stale = this.db.select({
       id: runs.id,
       projectId: runs.projectId,
@@ -7155,146 +7165,19 @@ var JobRunner = class {
           }
         }
       };
-      const processNodeForProvider = async (registeredProvider, unit) => {
-        const { adapter, config: providerConfig } = registeredProvider;
-        const providerName = adapter.name;
-        const gate = executionGates.get(providerName);
-        if (!gate) {
-          throw new Error(`Missing execution gate for provider ${providerName}`);
-        }
-        const config = unit.requestedModel ? { ...providerConfig, model: unit.requestedModel } : providerConfig;
-        const requestedContext = unit.context;
-        const supportedContext = requestedContext && providerSupportsLocationContext(adapter) ? { status: "applied", resolved: requestedContext } : null;
-        try {
-          await gate.run(async () => {
-            this.throwIfRunCancelled(runId);
-            providerDispatchCounts.set(providerName, (providerDispatchCounts.get(providerName) ?? 0) + 1);
-            const raw = await adapter.executeTrackedQuery(
-              {
-                query: unit.queryText,
-                canonicalDomains: allDomains,
-                competitorDomains,
-                location: requestedContext ?? void 0
-              },
-              config
-            );
-            this.throwIfRunCancelled(runId);
-            const providerResult = adapter.normalizeResult(raw);
-            const rawGroundingSources = providerResult.groundingSources;
-            const normalized = {
-              ...providerResult,
-              groundingSources: Array.isArray(rawGroundingSources) ? rawGroundingSources : []
-            };
-            let citedUrlCapture;
-            try {
-              citedUrlCapture = await captureCitedUrls(providerName, rawGroundingSources);
-            } catch (err) {
-              citedUrlCapture = {
-                citedUrls: [],
-                captureStatus: "failed",
-                sourceCount: normalized.groundingSources.length,
-                resolvedCount: 0,
-                captureVersion: CITED_URL_CAPTURE_VERSION
-              };
-              log2.warn("query.cited-url-capture-failed", {
-                runId,
-                provider: providerName,
-                query: unit.queryText,
-                error: describeError(err)
-              });
-            }
-            this.throwIfRunCancelled(runId);
-            const citationState = determineCitationState(normalized, allDomains);
-            const answerMentioned = determineAnswerMentioned(
-              normalized.answerText,
-              allBrandNames,
-              allDomains
-            );
-            const overlap = computeCompetitorOverlap(normalized, competitorDomains);
-            const extractedCompetitors = extractRecommendedCompetitors(
-              normalized.answerText,
-              allDomains,
-              normalized.citedDomains,
-              competitorDomains,
-              allBrandNames
-            );
-            const snapshotId = crypto6.randomUUID();
-            let screenshotRelPath = null;
-            if (raw.screenshotPath && fs3.existsSync(raw.screenshotPath)) {
-              const screenshotDir = path3.join(os3.homedir(), ".canonry", "screenshots", runId);
-              if (!fs3.existsSync(screenshotDir)) fs3.mkdirSync(screenshotDir, { recursive: true });
-              const destPath = path3.join(screenshotDir, `${snapshotId}.png`);
-              fs3.renameSync(raw.screenshotPath, destPath);
-              screenshotRelPath = `${runId}/${snapshotId}.png`;
-            }
-            this.db.insert(querySnapshots).values({
-              id: snapshotId,
-              runId,
-              queryId: unit.queryId,
-              queryText: unit.queryText,
-              provider: providerName,
-              // `model` is what was REQUESTED and `served_model` is what
-              // answered. The manifest froze the request, so it is the
-              // authority here: an adapter that reports its own default rather
-              // than what it was handed would otherwise overwrite the identity
-              // the revision recorded, and nothing would show that it moved.
-              model: unit.requestedModel ?? raw.model,
-              servedModel: raw.servedModel ?? null,
-              citationState,
-              answerMentioned,
-              answerText: normalized.answerText,
-              citedDomains: normalized.citedDomains,
-              citedUrls: citedUrlCapture.citedUrls,
-              captureStatus: citedUrlCapture.captureStatus,
-              sourceCount: citedUrlCapture.sourceCount,
-              resolvedCount: citedUrlCapture.resolvedCount,
-              captureVersion: citedUrlCapture.captureVersion,
-              retrievalStatus: normalized.retrievalStatus,
-              retrievalContract: raw.retrievalContract,
-              competitorOverlap: overlap,
-              recommendedCompetitors: extractedCompetitors,
-              // Only claim the geography the provider actually honoured. A
-              // requested-but-unsupported context stores `location: null` —
-              // "no claim" — rather than the label we asked for, mirroring
-              // `supportedContext` itself: this field is never non-null when
-              // that one is null.
-              location: supportedContext ? requestedContext?.label ?? null : null,
-              measurementExecutionId: unit.executionId,
-              requestedContext,
-              supportedContext,
-              screenshotPath: screenshotRelPath,
-              rawResponse: JSON.stringify({
-                model: raw.model,
-                servedModel: raw.servedModel ?? null,
-                groundingSources: normalized.groundingSources,
-                searchQueries: normalized.searchQueries,
-                apiResponse: raw.rawResponse
-              }),
-              createdAt: (/* @__PURE__ */ new Date()).toISOString()
-            }).run();
-            totalSnapshotsInserted++;
-            log2.info("query.citation", {
-              runId,
-              provider: providerName,
-              query: unit.queryText,
-              executionId: unit.executionId,
-              location: requestedContext?.label ?? null,
-              citationState,
-              answerMentioned
-            });
-          });
-        } catch (err) {
-          if (err instanceof RunCancelledError) {
-            throw err;
-          }
-          const msg = describeError(err);
-          const stack = err instanceof Error ? err.stack : void 0;
-          log2.error("query.failed", { runId, provider: providerName, query: unit.queryText, executionId: unit.executionId, error: msg, stack });
-          if (!providerErrors.has(providerName)) {
-            providerErrors.set(providerName, msg);
-          }
+      const slotContext = {
+        runId,
+        allDomains,
+        competitorDomains,
+        allBrandNames,
+        executionGates,
+        providerDispatchCounts,
+        providerErrors,
+        onInserted: () => {
+          totalSnapshotsInserted++;
         }
       };
+      const processNodeForProvider = (registeredProvider, unit) => this.executePlanSlot(slotContext, registeredProvider, unit);
       if (existingRun.kind === RunKinds["answer-visibility"] && existingRun.trigger !== RunTriggers.probe && existingRun.measurementPlanVersionId === null) {
         const definition = buildSimpleMeasurementDefinition({
           capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -7441,7 +7324,7 @@ var JobRunner = class {
         status: "failed",
         finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
         error: errorMessage
-      }).where(eq2(runs.id, runId)).run();
+      }).where(and2(eq2(runs.id, runId), inArray(runs.status, ["queued", "running"]))).run();
       this.flushProviderUsage(providerDispatchCounts, providerReservations);
       const abortReason2 = classifyRunAbortReason(errorMessage);
       const phases = buildPhases({ startTime, providerCallStart, providerCallEnd });
@@ -7482,6 +7365,363 @@ var JobRunner = class {
       }
     }
   }
+  /**
+   * Complete a partial plan run in place: record only the expected slots it
+   * never answered, under the same run id, then finalize the run once.
+   *
+   * The parent run is never written from an error path and only ever leaves
+   * `partial` through the completion compare-and-set, so a failed or
+   * interrupted fill leaves the run as the sweep left it, plus any answers the
+   * fill did record. Its timestamps, manifest and identity are never touched:
+   * it stays the same sweep, with the same place in every history.
+   */
+  async executeRunFill(fillId) {
+    const claim = this.db.update(runFills).set({ status: "running", startedAt: (/* @__PURE__ */ new Date()).toISOString() }).where(and2(eq2(runFills.id, fillId), eq2(runFills.status, "queued"))).run();
+    if (claim.changes !== 1) {
+      log2.warn("fill.not-claimed", { fillId });
+      return;
+    }
+    try {
+      await this.runClaimedFill(fillId);
+    } catch (err) {
+      const error = describeError(err);
+      log2.error("fill.aborted", { fillId, error });
+      this.db.update(runFills).set({ status: "failed", finishedAt: (/* @__PURE__ */ new Date()).toISOString(), error }).where(and2(eq2(runFills.id, fillId), eq2(runFills.status, "running"))).run();
+    }
+  }
+  async runClaimedFill(fillId) {
+    const fill = this.db.select().from(runFills).where(eq2(runFills.id, fillId)).get();
+    if (!fill) return;
+    const { runId, projectId } = fill;
+    const requested = new Set(parseJsonColumn(fill.providers, []).map((provider) => provider.trim().toLocaleLowerCase("en")));
+    const providerDispatchCounts = /* @__PURE__ */ new Map();
+    const providerReservations = /* @__PURE__ */ new Map();
+    const providerErrors = /* @__PURE__ */ new Map();
+    let filled = 0;
+    let fatal = null;
+    let superseded = false;
+    try {
+      const run = this.getRunState(runId);
+      if (!run) throw new Error(`Run ${runId} not found`);
+      if (run.status !== "partial") throw new Error(`Run ${runId} is ${run.status}; only a partial run can be filled`);
+      const runCreatedAt = this.db.select({ createdAt: runs.createdAt }).from(runs).where(eq2(runs.id, runId)).get().createdAt;
+      const project = this.db.select().from(projects).where(eq2(projects.id, projectId)).get();
+      if (!project) throw new Error(`Project ${projectId} not found`);
+      const projectQueries = this.db.select().from(queries).where(eq2(queries.projectId, projectId)).all();
+      const plan = resolvePlanExecution(run, projectQueries);
+      if (!plan) throw new Error(`Run ${runId} did not measure a published plan`);
+      const recorded = new Set(
+        this.db.select({ executionId: querySnapshots.measurementExecutionId, provider: querySnapshots.provider }).from(querySnapshots).where(eq2(querySnapshots.runId, runId)).all().flatMap((row) => row.executionId ? [measurementSlotKey(row.executionId, row.provider)] : [])
+      );
+      const unitsByProvider = /* @__PURE__ */ new Map();
+      for (const [provider, units] of plan.unitsByProvider) {
+        if (requested.size > 0 && !requested.has(provider)) continue;
+        const missing = units.filter((unit) => !recorded.has(measurementSlotKey(unit.executionId, provider)));
+        if (missing.length > 0) unitsByProvider.set(provider, missing);
+      }
+      const activeProviders = [];
+      for (const provider of unitsByProvider.keys()) {
+        const registered = this.registry.get(provider);
+        if (registered) activeProviders.push(registered);
+        else providerErrors.set(provider, `No ${provider} provider is configured on this instance, so its missing answers did not run.`);
+      }
+      const projectCompetitors = this.db.select().from(competitors).where(eq2(competitors.projectId, projectId)).all();
+      const competitorDomains = projectCompetitors.map((c) => c.domain);
+      const allDomains = effectiveDomains({ canonicalDomain: project.canonicalDomain, ownedDomains: project.ownedDomains });
+      const allBrandNames = effectiveBrandNames({ displayName: project.displayName, aliases: project.aliases });
+      const todayPeriod = getCurrentUsageDay();
+      const dispatchable = [];
+      for (const registered of activeProviders) {
+        const name = registered.adapter.name;
+        const count = unitsByProvider.get(name)?.length ?? 0;
+        const scope = `${projectId}:${name}`;
+        const limit = registered.config.quotaPolicy.maxRequestsPerDay;
+        const quota = reserveDailyQueryQuota(this.db, { scope, period: todayPeriod, count, limit });
+        if (!quota.reserved) {
+          providerErrors.set(name, `Daily quota exceeded for ${name}: ${quota.used} queries used today, limit is ${limit}. This fill needs ${count} more.`);
+          continue;
+        }
+        providerReservations.set(name, { scope, period: todayPeriod, reserved: count });
+        dispatchable.push(registered);
+      }
+      const executionGates = /* @__PURE__ */ new Map();
+      for (const registered of dispatchable) {
+        executionGates.set(
+          registered.adapter.name,
+          getSharedProviderExecutionGate(
+            registered.adapter.name,
+            registered.config.quotaPolicy.maxConcurrency,
+            registered.config.quotaPolicy.maxRequestsPerMinute
+          )
+        );
+      }
+      const consecutiveFailures = /* @__PURE__ */ new Map();
+      const stopped = /* @__PURE__ */ new Set();
+      const newerSweepExists = () => {
+        if (!superseded && newerFullSweep(this.db, { id: runId, projectId, createdAt: runCreatedAt })) {
+          superseded = true;
+          log2.warn("fill.superseded", { fillId, runId });
+        }
+        return superseded;
+      };
+      let removed = false;
+      const attemptRemoved = () => {
+        if (!removed && this.db.select({ status: runFills.status }).from(runFills).where(eq2(runFills.id, fillId)).get()?.status !== "running") {
+          removed = true;
+          log2.warn("fill.attempt-removed", { fillId, runId });
+        }
+        return removed;
+      };
+      const slotRecorded = (provider, executionId) => this.db.select({ id: querySnapshots.id }).from(querySnapshots).where(and2(
+        eq2(querySnapshots.runId, runId),
+        eq2(querySnapshots.measurementExecutionId, executionId),
+        eq2(querySnapshots.provider, provider)
+      )).get() !== void 0;
+      const ctx = {
+        runId,
+        allDomains,
+        competitorDomains,
+        allBrandNames,
+        executionGates,
+        providerDispatchCounts,
+        providerErrors,
+        onInserted: () => {
+          filled++;
+        },
+        fill: {
+          shouldSkip: (provider, executionId) => stopped.has(provider) || attemptRemoved() || newerSweepExists() || slotRecorded(provider, executionId),
+          onOutcome: (provider, ok) => {
+            if (ok) {
+              consecutiveFailures.set(provider, 0);
+              return;
+            }
+            const failures = (consecutiveFailures.get(provider) ?? 0) + 1;
+            consecutiveFailures.set(provider, failures);
+            if (failures >= RUN_FILL_PROVIDER_BREAKER && !stopped.has(provider)) {
+              stopped.add(provider);
+              log2.warn("fill.provider-stopped", { fillId, runId, provider, failures });
+            }
+          }
+        }
+      };
+      log2.info("fill.dispatch", {
+        fillId,
+        runId,
+        missing: Object.fromEntries([...unitsByProvider].map(([provider, units]) => [provider, units.length]))
+      });
+      const unitsFor = (registered) => unitsByProvider.get(registered.adapter.name) ?? [];
+      const apiProviders = dispatchable.filter((p) => !isBrowserProvider(p.adapter.name));
+      const browserProviders = dispatchable.filter((p) => isBrowserProvider(p.adapter.name));
+      await runWithConcurrency(apiProviders, resolveProviderFanout(), async (registered) => {
+        await runWithConcurrency(
+          unitsFor(registered),
+          Math.max(1, registered.config.quotaPolicy.maxConcurrency),
+          (unit) => this.executePlanSlot(ctx, registered, unit)
+        );
+      });
+      for (const registered of browserProviders) {
+        for (const unit of unitsFor(registered)) await this.executePlanSlot(ctx, registered, unit);
+      }
+    } catch (err) {
+      fatal = describeError(err);
+      log2.error("fill.failed", { fillId, runId, error: fatal });
+    } finally {
+      this.flushProviderUsage(providerDispatchCounts, providerReservations);
+    }
+    const outcome = this.finalizeRunFill({ fillId, runId, filled, fatal, providerErrors, superseded });
+    log2.info("fill.finished", { fillId, runId, filled, ...outcome });
+    if (outcome.justCompleted && !outcome.superseded && this.onRunCompleted) {
+      this.onRunCompleted(runId, projectId, { origin: "fill" }).catch((err) => {
+        log2.error("notification.callback-failed", { runId, error: describeError(err) });
+      });
+    }
+  }
+  /** Record the fill's outcome and, if the run is now whole, complete it exactly once. */
+  finalizeRunFill(input) {
+    const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return this.db.transaction((tx) => {
+      const txDb = tx;
+      const parent = txDb.select({ projectId: runs.projectId, createdAt: runs.createdAt, error: runs.error }).from(runs).where(eq2(runs.id, input.runId)).get();
+      const superseded = input.superseded || parent !== void 0 && newerFullSweep(txDb, { id: input.runId, projectId: parent.projectId, createdAt: parent.createdAt }) !== void 0;
+      const state = measurementRunSlotState(txDb, input.runId);
+      const complete3 = state.planned && state.readable && state.missing.length === 0 && !state.hasUnboundSnapshot;
+      let justCompleted = false;
+      if (complete3) {
+        justCompleted = txDb.update(runs).set({ status: "completed", error: null }).where(and2(eq2(runs.id, input.runId), eq2(runs.status, "partial"))).run().changes === 1;
+      } else if (state.readable && !input.fatal) {
+        const previous = parseRunError(parent?.error)?.providers ?? {};
+        const fresh = buildRunErrorFromMessages(input.providerErrors).providers ?? {};
+        const remaining = /* @__PURE__ */ new Map();
+        for (const slot of state.missing) remaining.set(slot.provider, (remaining.get(slot.provider) ?? 0) + 1);
+        const providers = {};
+        for (const [provider, count] of remaining) {
+          providers[provider] = fresh[provider] ?? previous[provider] ?? { message: `${count} expected measurement(s) have not run.` };
+        }
+        txDb.update(runs).set({ error: serializeRunError({ providers }) }).where(and2(eq2(runs.id, input.runId), eq2(runs.status, "partial"))).run();
+      }
+      const status = complete3 ? "completed" : input.filled > 0 ? "partial" : "failed";
+      const reason = input.fatal ?? (superseded ? "Stopped because a newer sweep started; no answers were added behind it." : null) ?? (input.providerErrors.size > 0 ? formatRunErrorOneLine(buildRunErrorFromMessages(input.providerErrors)) : null);
+      txDb.update(runFills).set({ status, filled: input.filled, error: complete3 ? null : reason, finishedAt }).where(eq2(runFills.id, input.fillId)).run();
+      return { justCompleted, superseded };
+    });
+  }
+  /**
+   * The plan-aware unit of work: one execution node, one provider.
+   *
+   * Deliberately a separate worker from the legacy query-by-query path rather
+   * than a generalization of it. The legacy path is the behaviour every
+   * planless project already depends on; leaving its body alone is what
+   * makes "planless is byte-identical" a fact rather than a hope.
+   *
+   * A method rather than a closure inside `executeRun` so a sweep and a fill
+   * record a slot through the same code: a filled answer is indistinguishable
+   * from one the sweep recorded itself, which is what lets it count.
+   */
+  async executePlanSlot(ctx, registeredProvider, unit) {
+    const { adapter, config: providerConfig } = registeredProvider;
+    const providerName = adapter.name;
+    const gate = ctx.executionGates.get(providerName);
+    if (!gate) {
+      throw new Error(`Missing execution gate for provider ${providerName}`);
+    }
+    const config = unit.requestedModel ? { ...providerConfig, model: unit.requestedModel } : providerConfig;
+    const requestedContext = unit.context;
+    const supportedContext = requestedContext && providerSupportsLocationContext(adapter) ? { status: "applied", resolved: requestedContext } : null;
+    if (ctx.fill?.shouldSkip(providerName, unit.executionId)) return;
+    try {
+      await gate.run(async () => {
+        this.throwIfRunCancelled(ctx.runId);
+        if (ctx.fill?.shouldSkip(providerName, unit.executionId)) return;
+        ctx.providerDispatchCounts.set(providerName, (ctx.providerDispatchCounts.get(providerName) ?? 0) + 1);
+        const raw = await adapter.executeTrackedQuery(
+          {
+            query: unit.queryText,
+            canonicalDomains: ctx.allDomains,
+            competitorDomains: ctx.competitorDomains,
+            location: requestedContext ?? void 0
+          },
+          config
+        );
+        this.throwIfRunCancelled(ctx.runId);
+        const providerResult = adapter.normalizeResult(raw);
+        const rawGroundingSources = providerResult.groundingSources;
+        const normalized = {
+          ...providerResult,
+          groundingSources: Array.isArray(rawGroundingSources) ? rawGroundingSources : []
+        };
+        let citedUrlCapture;
+        try {
+          citedUrlCapture = await captureCitedUrls(providerName, rawGroundingSources);
+        } catch (err) {
+          citedUrlCapture = {
+            citedUrls: [],
+            captureStatus: "failed",
+            sourceCount: normalized.groundingSources.length,
+            resolvedCount: 0,
+            captureVersion: CITED_URL_CAPTURE_VERSION
+          };
+          log2.warn("query.cited-url-capture-failed", {
+            runId: ctx.runId,
+            provider: providerName,
+            query: unit.queryText,
+            error: describeError(err)
+          });
+        }
+        this.throwIfRunCancelled(ctx.runId);
+        const citationState = determineCitationState(normalized, ctx.allDomains);
+        const answerMentioned = determineAnswerMentioned(
+          normalized.answerText,
+          ctx.allBrandNames,
+          ctx.allDomains
+        );
+        const overlap = computeCompetitorOverlap(normalized, ctx.competitorDomains);
+        const extractedCompetitors = extractRecommendedCompetitors(
+          normalized.answerText,
+          ctx.allDomains,
+          normalized.citedDomains,
+          ctx.competitorDomains,
+          ctx.allBrandNames
+        );
+        const snapshotId = crypto6.randomUUID();
+        let screenshotRelPath = null;
+        if (raw.screenshotPath && fs3.existsSync(raw.screenshotPath)) {
+          const screenshotDir = path3.join(os3.homedir(), ".canonry", "screenshots", ctx.runId);
+          if (!fs3.existsSync(screenshotDir)) fs3.mkdirSync(screenshotDir, { recursive: true });
+          const destPath = path3.join(screenshotDir, `${snapshotId}.png`);
+          fs3.renameSync(raw.screenshotPath, destPath);
+          screenshotRelPath = `${ctx.runId}/${snapshotId}.png`;
+        }
+        const insert = this.db.insert(querySnapshots).values({
+          id: snapshotId,
+          runId: ctx.runId,
+          queryId: unit.queryId,
+          queryText: unit.queryText,
+          provider: providerName,
+          // `model` is what was REQUESTED and `served_model` is what
+          // answered. The manifest froze the request, so it is the
+          // authority here: an adapter that reports its own default rather
+          // than what it was handed would otherwise overwrite the identity
+          // the revision recorded, and nothing would show that it moved.
+          model: unit.requestedModel ?? raw.model,
+          servedModel: raw.servedModel ?? null,
+          citationState,
+          answerMentioned,
+          answerText: normalized.answerText,
+          citedDomains: normalized.citedDomains,
+          citedUrls: citedUrlCapture.citedUrls,
+          captureStatus: citedUrlCapture.captureStatus,
+          sourceCount: citedUrlCapture.sourceCount,
+          resolvedCount: citedUrlCapture.resolvedCount,
+          captureVersion: citedUrlCapture.captureVersion,
+          retrievalStatus: normalized.retrievalStatus,
+          retrievalContract: raw.retrievalContract,
+          competitorOverlap: overlap,
+          recommendedCompetitors: extractedCompetitors,
+          // Only claim the geography the provider actually honoured. A
+          // requested-but-unsupported context stores `location: null` —
+          // "no claim" — rather than the label we asked for, mirroring
+          // `supportedContext` itself: this field is never non-null when
+          // that one is null.
+          location: supportedContext ? requestedContext?.label ?? null : null,
+          measurementExecutionId: unit.executionId,
+          requestedContext,
+          supportedContext,
+          screenshotPath: screenshotRelPath,
+          rawResponse: JSON.stringify({
+            model: raw.model,
+            servedModel: raw.servedModel ?? null,
+            groundingSources: normalized.groundingSources,
+            searchQueries: normalized.searchQueries,
+            apiResponse: raw.rawResponse
+          }),
+          createdAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        const written = ctx.fill ? insert.onConflictDoNothing().run() : insert.run();
+        if (written.changes > 0) ctx.onInserted();
+        ctx.fill?.onOutcome(providerName, true);
+        log2.info("query.citation", {
+          runId: ctx.runId,
+          provider: providerName,
+          query: unit.queryText,
+          executionId: unit.executionId,
+          location: requestedContext?.label ?? null,
+          citationState,
+          answerMentioned
+        });
+      });
+    } catch (err) {
+      if (err instanceof RunCancelledError) {
+        throw err;
+      }
+      const msg = describeError(err);
+      const stack = err instanceof Error ? err.stack : void 0;
+      log2.error("query.failed", { runId: ctx.runId, provider: providerName, query: unit.queryText, executionId: unit.executionId, error: msg, stack });
+      if (!ctx.providerErrors.has(providerName)) {
+        ctx.providerErrors.set(providerName, msg);
+      }
+      ctx.fill?.onOutcome(providerName, false);
+    }
+  }
   incrementUsage(scope, metric, count) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const period = now.slice(0, 10);
@@ -11776,7 +12016,7 @@ function readStoredGroundingSources(rawResponse) {
   return result2;
 }
 async function backfillInsightsCommand(project, opts) {
-  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-KF5WWPGR.js");
+  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-PM7MC5VC.js");
   const config = loadConfig();
   const db = createClient(config.database);
   migrate(db);
@@ -13023,8 +13263,8 @@ var Notifier = class {
     this.serverUrl = serverUrl;
   }
   /** Called after a run completes (success, partial, or failed). */
-  async onRunCompleted(runId, projectId) {
-    log17.info("run.completed", { runId, projectId });
+  async onRunCompleted(runId, projectId, opts) {
+    log17.info("run.completed", { runId, projectId, origin: opts?.origin ?? "sweep" });
     const notifs = this.db.select().from(notifications).where(eq17(notifications.projectId, projectId)).all().filter((n) => n.enabled);
     if (notifs.length === 0) {
       log17.info("notifications.none-enabled", { projectId });
@@ -13044,7 +13284,7 @@ var Notifier = class {
     const transitions = this.computeTransitions(runId, projectId);
     const events = [];
     log17.info("run.status", { runId: run.id, status: run.status, projectId });
-    if (run.status === "completed" || run.status === "partial") {
+    if ((run.status === "completed" || run.status === "partial") && opts?.origin !== "fill") {
       events.push("run.completed");
     }
     if (run.status === "failed") {
@@ -13495,7 +13735,7 @@ var RunCoordinator = class {
   intelligenceService;
   onInsightsGenerated;
   onAeroEvent;
-  async onRunCompleted(runId, projectId) {
+  async onRunCompleted(runId, projectId, opts) {
     const runRow = this.db.select().from(runs).where(eq18(runs.id, runId)).get();
     const kind = runRow?.kind ?? RunKinds["answer-visibility"];
     if (runRow?.trigger === RunTriggers.probe) {
@@ -13557,7 +13797,7 @@ var RunCoordinator = class {
       }
     }
     try {
-      await this.notifier.onRunCompleted(runId, projectId);
+      await (opts ? this.notifier.onRunCompleted(runId, projectId, opts) : this.notifier.onRunCompleted(runId, projectId));
     } catch (err) {
       log18.error("notifier.failed", { runId, error: describeError(err) });
     }
@@ -13865,13 +14105,15 @@ function resolveAgentId(providerOrPiAi) {
   return void 0;
 }
 function buildAgentProvidersResponse(config) {
+  const pinned = coerceAgentProvider(config.agent?.provider ?? void 0);
+  const pinnedModel = pinned ? config.agent?.model ?? void 0 : void 0;
   const providers = listAgentProviders().map((id) => {
     const entry = AGENT_PROVIDERS[id];
     const source = resolveApiKeySource(id, config);
     return {
       id,
       label: entry.label,
-      defaultModel: entry.defaultModel,
+      defaultModel: id === pinned && pinnedModel ? pinnedModel : entry.defaultModel,
       configured: source !== void 0,
       keySource: source?.source ?? null
     };
@@ -13879,7 +14121,7 @@ function buildAgentProvidersResponse(config) {
   const firstConfigured = agentProvidersByPriority().find((p) => resolveApiKeySource(p, config));
   return {
     providers,
-    defaultProvider: firstConfigured ?? null
+    defaultProvider: pinned ?? firstConfigured ?? null
   };
 }
 
@@ -14845,6 +15087,27 @@ function missingProviderMessage() {
   const envHints = agentProvidersByPriority().map(agentProviderApiKeyEnvVar).join(" / ");
   return `No agent LLM provider configured. Add an API key for one of: ${configHints} in ~/.canonry/config.yaml, or export ${envHints}.`;
 }
+function resolveConfiguredAgentProvider(config) {
+  return coerceAgentProvider(config.agent?.provider);
+}
+function describeAgentPin(config) {
+  const provider = resolveConfiguredAgentProvider(config);
+  if (!provider) return null;
+  const model = config.agent?.model ?? getAgentProvider(provider).defaultModel;
+  let modelError = null;
+  try {
+    resolveAeroModel(provider, model);
+  } catch (err) {
+    modelError = err instanceof Error ? err.message : String(err);
+  }
+  return {
+    provider,
+    model,
+    configured: Boolean(resolveApiKeyFor(provider, config)),
+    envVar: agentProviderApiKeyEnvVar(provider),
+    modelError
+  };
+}
 function detectAgentProvider(config) {
   for (const provider of agentProvidersByPriority()) {
     if (resolveApiKeyFor(provider, config)) return provider;
@@ -14915,9 +15178,11 @@ function createAeroSession(opts) {
   return agent;
 }
 function resolveSessionProviderAndModel(config, opts) {
-  const provider = opts?.provider ?? detectAgentProvider(config);
+  const pinned = resolveConfiguredAgentProvider(config);
+  const provider = opts?.provider ?? pinned ?? detectAgentProvider(config);
   if (!provider) throw new Error(missingProviderMessage());
-  const modelId = opts?.modelId ?? getAgentProvider(provider).defaultModel;
+  const pinnedModelId = provider === pinned ? config.agent?.model : void 0;
+  const modelId = opts?.modelId ?? pinnedModelId ?? getAgentProvider(provider).defaultModel;
   return { provider, modelId };
 }
 
@@ -15346,9 +15611,8 @@ var SessionRegistry = class {
       if (row.systemPrompt !== systemPrompt) {
         this.persistPromptSnapshot(projectId, systemPrompt);
       }
-      const effectiveProvider = preferences?.provider ?? row.modelProvider;
-      const effectiveModelId = preferences?.modelId ?? row.modelId;
-      if (preferences?.provider || preferences?.modelId) {
+      const { provider: effectiveProvider, modelId: effectiveModelId } = this.resolveTurnModel(preferences, { provider: row.modelProvider, modelId: row.modelId });
+      if (effectiveProvider !== row.modelProvider || effectiveModelId !== row.modelId) {
         this.opts.db.update(agentSessions).set({
           modelProvider: effectiveProvider,
           modelId: effectiveModelId,
@@ -15481,17 +15745,19 @@ ${lines.join("\n")}
    *   - align `state.tools` to the requested scope/profile (CLI full vs
    *     dashboard read-only share the same cached Agent; each request
    *     re-scopes it).
-   *   - align `state.model` when the caller passes `provider` or `modelId`,
-   *     honoring `--provider` / `--model` on hot sessions (not just on
-   *     fresh/hydrated construction).
+   *   - align `state.model` on every turn (see `resolveTurnModel`): an
+   *     explicit `provider` / `modelId` wins for this turn, then the
+   *     `agent.provider` pin, then the session's stored model.
+   *   - refuse, naming `agent.provider`, a pinned provider that has no key.
    *
-   * Persists the new model choice to the DB row so subsequent invocations
-   * stay on it unless overridden again.
+   * Persists the resolved model to the DB row as provenance. Without a pin an
+   * override therefore sticks, as it always has; with a pin, the next turn
+   * that names no provider returns to it.
    */
   async acquireForTurn(projectName, preferences) {
     preferences?.signal?.throwIfAborted();
     if (this.acquisitions.has(projectName)) throw agentBusy(projectName);
-    const agent = this.getOrCreate(projectName);
+    const agent = this.getOrCreate(projectName, preferences);
     if (agent.state.isStreaming) {
       throw agentBusy(projectName);
     }
@@ -15508,9 +15774,8 @@ ${lines.join("\n")}
         scope: preferences?.toolScope ?? AeroToolScopes.all,
         profile: preferences?.toolProfile ?? AeroToolProfiles.default
       });
-      if (preferences?.provider || preferences?.modelId) {
-        this.alignModel(projectName, agent, preferences);
-      }
+      this.alignModel(projectName, agent, preferences ?? {});
+      this.assertTurnProviderUsable(projectId);
       await this.mergeExternalTools(agent);
       const view = { client: this.opts.client, projectName, basePath: this.opts.config.basePath, context: preferences?.context };
       const evidence = preferences?.context ? await readAeroViewEvidence(view) : void 0;
@@ -15589,15 +15854,56 @@ ${lines.join("\n")}
     this.scopes.set(projectName, want.scope);
     this.profiles.set(projectName, want.profile);
   }
+  /**
+   * Throw a named, actionable error when the `agent.provider` pin chose this
+   * turn's provider and that provider has no key. Auto-detection only ever
+   * picks a keyed provider, so the pin is the one path that can land a turn on
+   * a keyless one without anything saying so. An explicitly requested provider
+   * keeps its existing behaviour: the caller named it, and the provider's own
+   * error reports the missing key when the prompt is sent.
+   */
+  assertTurnProviderUsable(projectId) {
+    const provider = coerceAgentProvider(this.loadRow(projectId)?.modelProvider ?? void 0);
+    if (!provider || provider !== resolveConfiguredAgentProvider(this.opts.config)) return;
+    if (resolveApiKeyFor(provider, this.opts.config)) return;
+    throw missingDependency(
+      `Aero is pinned to ${provider} by agent.provider, but no key is configured for it. Set providers.${provider}.apiKey in config.yaml or export ${agentProviderApiKeyEnvVar(provider)}, or change agent.provider.`,
+      { provider, pinned: true }
+    );
+  }
+  /**
+   * Resolve the provider/model a turn should use: an explicit request outranks
+   * the `agent.provider` pin, which outranks whatever the row last recorded.
+   *
+   * The row is provenance (what answered), not policy (what answers next), so
+   * a configured pin reasserts itself every turn instead of being frozen at
+   * whatever the first session happened to pick -- and survives the
+   * conversation-delete path, which drops the row entirely. With a pin, an
+   * explicit request therefore lasts one turn.
+   *
+   * The model is a function of the request and the config, never of which
+   * provider ran last: naming the pinned provider gets `agent.model` whether or
+   * not the session just came back from another one. The row's model is used
+   * only when nothing is pinned and nothing was requested, which keeps an
+   * unpinned install's override sticky as it always was. A model id is never
+   * forwarded across providers: any other case takes the provider's default.
+   */
+  resolveTurnModel(preferences, current) {
+    const pinned = resolveConfiguredAgentProvider(this.opts.config);
+    const provider = preferences?.provider ?? pinned ?? current.provider ?? AgentProviderIds.claude;
+    const carried = !preferences?.provider && !pinned && provider === current.provider ? current.modelId ?? void 0 : void 0;
+    const pinnedModelId = provider === pinned ? this.opts.config.agent?.model ?? void 0 : void 0;
+    const modelId = preferences?.modelId ?? pinnedModelId ?? carried ?? getAgentProvider(provider).defaultModel;
+    return { provider, modelId };
+  }
   alignModel(projectName, agent, preferences) {
     const projectId = this.tryResolveProjectId(projectName);
     if (!projectId) return;
     const row = this.loadRow(projectId);
-    const currentProvider = row?.modelProvider ?? AgentProviderIds.claude;
-    const currentModelId = row?.modelId;
-    const nextProvider = preferences.provider ?? currentProvider;
-    const nextModelId = preferences.modelId ?? (preferences.provider ? getAgentProvider(nextProvider).defaultModel : currentModelId);
-    if (!nextModelId) return;
+    if (!row) return;
+    const currentProvider = row.modelProvider;
+    const currentModelId = row.modelId;
+    const { provider: nextProvider, modelId: nextModelId } = this.resolveTurnModel(preferences, { provider: row.modelProvider, modelId: row.modelId });
     if (nextProvider === currentProvider && nextModelId === currentModelId) return;
     agent.state.model = resolveAeroModel(nextProvider, nextModelId);
     this.opts.db.update(agentSessions).set({
@@ -17923,7 +18229,7 @@ async function createServer(opts) {
       void sessionRegistry.drainNow(project.name);
     }
   );
-  jobRunner.onRunCompleted = (runId, projectId) => runCoordinator.onRunCompleted(runId, projectId);
+  jobRunner.onRunCompleted = (runId, projectId, opts2) => opts2 ? runCoordinator.onRunCompleted(runId, projectId, opts2) : runCoordinator.onRunCompleted(runId, projectId);
   const snapshotService = new SnapshotService(registry);
   const liveProjectIds = new Set(
     opts.db.select({ id: projects.id }).from(projects).all().map((project) => project.id)
@@ -18981,6 +19287,7 @@ async function createServer(opts) {
     // Resolved fresh each call so a key added at runtime (settings API) shows
     // up immediately in the `config.agent-providers` doctor check.
     getAgentProviderSummary: () => buildAgentProvidersResponse(opts.config).providers,
+    getAgentPin: () => describeAgentPin(opts.config),
     getGoogleMarketingDoctorInput: (ctx) => {
       if (!ctx.project) return null;
       const googleAds = opts.db.select().from(googleAdsConnections).where(eq25(googleAdsConnections.projectId, ctx.project.id)).get();
@@ -19279,6 +19586,14 @@ async function createServer(opts) {
         app.log.error({ runId, err }, "Job runner failed");
       });
     },
+    getProviderDailyLimits: () => Object.fromEntries(
+      registry.getAll().map((provider) => [provider.adapter.name, provider.config.quotaPolicy.maxRequestsPerDay])
+    ),
+    onRunFillCreated: (fillId, runId) => {
+      jobRunner.executeRunFill(fillId).catch((err) => {
+        app.log.error({ fillId, runId, err: describeError(err) }, "Run fill failed");
+      });
+    },
     onRunCancelled: (runId) => {
       const controller = siteAuditAbortControllers.get(runId);
       if (controller && !controller.signal.aborted) {