@yansigit/opencodex 2.31.2 → 2.32.0

package/src/types.ts

@@ -5,6 +5,7 @@ export type { OcxTool, OcxToolChoice } from "./types/tools";
 export {
   namespacedToolName,
   toolChoiceAliases,
+  createToolChoiceResolver,
   toolChoiceCandidates,
   toolAllowedByChoice,
   resolveToolChoiceWireName,
@@ -103,4 +104,3 @@ export type {
   CodexAccountCredentials,
   CodexAccountCredentialRecord,
 } from "./types/accounts";
-

package/src/update/index.ts

@@ -2,7 +2,8 @@ import { spawn, spawnSync } from "node:child_process";
 import { readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { getConfigDir, loadConfig, readPid, readRuntimePort } from "../config";
+import { getConfigDir, loadConfig } from "../config";
+import { readPid, readRuntimePort } from "../config/process-state";
 import { npmInvocation } from "./npm-invocation.mjs";
 import {
   npmCachePreflightFailureMessage,
@@ -279,9 +280,9 @@ export async function runUpdate(): Promise<void> {
     }
     if (historyRestoreIncomplete()) {
       console.warn(
-        "⚠️  Codex resume history was NOT restored (history DB locked — Codex app/IDE open?).\n" +
-        "    Your routed threads stay hidden in the native Codex app until restored.\n" +
-        "    After the update: close the Codex app, then run 'ocx stop' once to restore.",
+        "⚠️  Codex resume-history metadata restore is incomplete (a backup manifest remains).\n" +
+        "    The DB may be busy or the manifest/target may need review; untracked routed history is intentionally unchanged.\n" +
+        "    After the update: close the Codex app, run 'ocx doctor', then run 'ocx stop' once to retry.",
       );
     }
   }

package/src/update/job.ts

@@ -6,12 +6,14 @@ import {
   atomicWriteFile,
   getConfigDir,
   loadConfig,
+} from "../config";
+import {
   readPid,
   readRuntimePort,
   removePid,
   removeRuntimePort,
   verifyPidIdentity,
-} from "../config";
+} from "../config/process-state";
 import { isProcessAlive, killProxy } from "../lib/process-control";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
 import { killWindowsSchedulerWrappers } from "../lib/windows-service-wrappers";

package/src/update/transactional-install.mjs

@@ -176,7 +176,14 @@ export function transactionalNpmUpdate({
   }
   const spec = pkgName + "@" + (targetVersion || tag);
   log("Staging " + spec + " into " + stageRoot);
-  const install = runNpm(["install", "-g", "--prefix", stageRoot, "--no-audit", "--no-fund", spec]);
+  // npm 12 blocks lifecycle scripts by default. Bun's postinstall copies the selected
+  // @oven/bun-* executable into bun/bin, so a successful npm exit without this narrow
+  // approval leaves the staged tree intentionally incomplete. Allow only the package
+  // whose executable the manifest verifies below; never broaden this to all scripts.
+  const install = runNpm([
+    "install", "-g", "--prefix", stageRoot,
+    "--allow-scripts=bun", "--no-audit", "--no-fund", spec,
+  ]);
   if (install.status !== 0) {
     try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
     return { ok: false, phase: "stage", error: "npm staging install failed (" + (install.status ?? "?") + ")" };

package/src/usage/log.ts

@@ -931,6 +931,10 @@ async function readUsageEntriesIncrementally(
     // A shrink means truncation or replacement-in-place; the retained rows may no
     // longer correspond to file contents, so refuse to extend them.
     if (size < retained.coveredThroughBytes) return null;
+    // Retained-state reuse is only an optimization. A burst larger than the configured
+    // window must re-anchor through the bounded full-tail reader instead of reading and
+    // parsing every byte appended since the previous poll.
+    if (size - retained.coveredThroughBytes > maxReadBytes) return null;
     // Verify the retained REGION is unchanged before anything is reused. Identity keeps
     // dev/ino/birthtime, and an append and an in-place rewrite both move mtime/ctime
     // forward, so only the bytes themselves settle it.
@@ -1142,6 +1146,14 @@ export async function readUsageEntriesForManagement(): Promise<PersistedUsageEnt
   return (await readUsageSnapshotForManagement()).entries;
 }
 
+/** Keep legacy optional fields permissive, but reject rows that cannot be safely attributed. */
+function normalizePersistedUsageRow(value: unknown): PersistedUsageEntry | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const row = value as Record<string, unknown>;
+  if (typeof row.requestId !== "string" || typeof row.provider !== "string") return undefined;
+  return normalizeUsageEntry(row as unknown as PersistedUsageEntry);
+}
+
 export function readUsageEntries(): PersistedUsageEntry[] {
   const path = usageLogPath();
   if (!existsSync(path)) return [];
@@ -1150,10 +1162,8 @@ export function readUsageEntries(): PersistedUsageEntry[] {
   for (const line of lines) {
     if (!line.trim()) continue;
     try {
-      const parsed = JSON.parse(line) as PersistedUsageEntry;
-      if (parsed && typeof parsed === "object" && typeof parsed.requestId === "string") {
-        entries.push(normalizeUsageEntry(parsed));
-      }
+      const parsed = normalizePersistedUsageRow(JSON.parse(line));
+      if (parsed) entries.push(parsed);
     } catch {
       /* keep reading after a partially written or hand-edited line */
     }
@@ -1166,10 +1176,8 @@ function parseUsageLines(lines: string[]): PersistedUsageEntry[] {
   for (const line of lines) {
     if (!line.trim()) continue;
     try {
-      const parsed = JSON.parse(line) as PersistedUsageEntry;
-      if (parsed && typeof parsed === "object" && typeof parsed.requestId === "string") {
-        entries.push(normalizeUsageEntry(parsed));
-      }
+      const parsed = normalizePersistedUsageRow(JSON.parse(line));
+      if (parsed) entries.push(parsed);
     } catch {
       /* skip partial / hand-edited lines */
     }

package/src/usage/summary.ts

@@ -4,8 +4,17 @@ import { usageDisplayTotalTokens } from "./totals";
 import { isCodexUsageAccountLogLabel, type PersistedUsageEntry, type UsageStatus } from "./log";
 import { estimateAttemptCost, estimateComboCost, estimateRequestCost, serviceTierContext } from "./cost";
 
-export type UsageRange = "7d" | "30d" | "all";
-export type UsageSurface = "all" | "codex" | "claude" | "grok";
+/**
+ * Canonical range members. The warm-up loop in the management usage route
+ * iterates this constant rather than its own literal: the two used to be
+ * written separately, and a subset literal type-checks perfectly happily, so a
+ * range added to the union but forgotten in the loop was never warmed and
+ * never invalidated alongside its siblings.
+ */
+export const USAGE_RANGES = ["today", "7d", "30d", "all"] as const;
+export type UsageRange = typeof USAGE_RANGES[number];
+export const USAGE_SURFACES = ["all", "codex", "claude", "grok"] as const;
+export type UsageSurface = typeof USAGE_SURFACES[number];
 
 export interface UsageSummaryTotals {
   requests: number;
@@ -40,6 +49,8 @@ export interface UsageDay {
   measuredRequests: number;
   reportedRequests: number;
   totalTokens: number;
+  /** Display-time estimated cost for this local day, summed from its model rows. */
+  estimatedCostUsd: number;
   models: UsageDayModel[];
 }
 
@@ -49,6 +60,8 @@ export interface UsageDayModel {
   requests: number;
   attemptCount: number;
   totalTokens: number;
+  /** Display-time estimated cost attributed to this provider/model on this day. */
+  estimatedCostUsd: number;
 }
 
 export interface UsageModel {
@@ -113,6 +126,26 @@ export interface UsageSummary {
   accounts: UsageAccount[];
 }
 
+/**
+ * Echo of an applied provider/model projection.
+ *
+ * Present only on a filtered response so a consumer can distinguish "no rows
+ * matched" from "no traffic in this window", and can tell that the totals it
+ * is reading are a projection rather than the whole window.
+ */
+export interface UsageFilterEcho {
+  provider: string | null;
+  model: string | null;
+  matched: boolean;
+  /**
+   * True when a retained row came from a combo attribution. Cost partitions
+   * cleanly across attempts, but a combo request is counted once per
+   * participating model, so a filtered REQUEST count can exceed the number of
+   * distinct requests. Cost is unaffected.
+   */
+  comboOverlap: boolean;
+}
+
 const DAY_MS = 86_400_000;
 export const MAX_USAGE_MODEL_BREAKDOWN_ROWS = 256;
 
@@ -127,6 +160,10 @@ function retainedBreakdownRows<T>(
 }
 
 export function parseRange(input: string | null | undefined): UsageRange {
+  // `1d` normalises here rather than becoming a second union member: a second
+  // member would need its own cache slot, its own grid arm and its own test
+  // matrix for no user-visible gain.
+  if (input === "today" || input === "1d") return "today";
   if (input === "7d" || input === "30d" || input === "all") return input;
   return "30d";
 }
@@ -143,6 +180,11 @@ function startOfLocalDay(ts: number): number {
 }
 
 export function rangeWindow(range: UsageRange, now: number): { since: number | null; days: number } {
+  // Handled before the others because the fallthrough below is the `all`
+  // window: a range that reaches it is silently reported as all-time history,
+  // which for a cost surface is a plausible-looking wrong answer rather than a
+  // visible failure.
+  if (range === "today") return { since: startOfLocalDay(now), days: 1 };
   if (range === "7d") {
     const start = new Date(startOfLocalDay(now));
     start.setDate(start.getDate() - 6);
@@ -335,6 +377,33 @@ function addEstimatedCost(
   totals.estimatedCostUsd += estimate.cost.total;
 }
 
+/**
+ * Per-attribution cost for one entry, keyed by `provider/model`.
+ *
+ * Mirrors the attribution branch in {@link buildModels}: a combo request is
+ * priced per attempt and each attempt's cost belongs to its own model, so cost
+ * partitions across models rather than being counted once per participant. A
+ * single-target request contributes its whole cost to the entry's own model.
+ */
+function dayAttributionCosts(entry: PersistedUsageEntry): Map<string, number> {
+  const costs = new Map<string, number>();
+  const tier = serviceTierContext(entry);
+  const estimate = entry.attempts?.length
+    ? estimateComboCost(entry.attempts, undefined, tier)
+    : estimateRequestCost({ provider: entry.provider, model: entry.model, usage: entry.usage, usageStatus: entry.usageStatus, serviceTier: tier });
+  if (!estimate) return costs;
+  const add = (provider: string, model: string, amount: number): void => {
+    const key = usageModelKey(baseProviderLabel(provider), antigravityUsageModel(provider, model));
+    costs.set(key, (costs.get(key) ?? 0) + amount);
+  };
+  if (entry.attempts?.length && estimate.attempts) {
+    for (const attempt of estimate.attempts) add(attempt.provider, attempt.model, attempt.cost.total);
+  } else {
+    add(entry.provider, entry.model, estimate.cost.total);
+  }
+  return costs;
+}
+
 function buildDayGrid(range: UsageRange, since: number | null, now: number, entries: PersistedUsageEntry[]): UsageDay[] {
   const window = rangeWindow(range, now);
   const days = range === "all" ? dayCountForAllRange(entries, now) : window.days;
@@ -343,14 +412,14 @@ function buildDayGrid(range: UsageRange, since: number | null, now: number, entr
   // render a per-model stacked bar with a hover tooltip without a second pass over the entries.
   const dayModels = new Map<string, Map<string, UsageDayModel>>();
   const dayModelRequests = new Map<string, Set<string>>();
-  const bumpDayModel = (dayKey: string, attribution: UsageAttribution): void => {
+  const bumpDayModel = (dayKey: string, attribution: UsageAttribution, costUsd: number): void => {
     let models = dayModels.get(dayKey);
     if (!models) { models = new Map(); dayModels.set(dayKey, models); }
     const providerKey = baseProviderLabel(attribution.provider);
     const mKey = usageModelKey(providerKey, attribution.model);
     let m = models.get(mKey);
     if (!m) {
-      m = { model: attribution.model, provider: providerKey, requests: 0, attemptCount: 0, totalTokens: 0 };
+      m = { model: attribution.model, provider: providerKey, requests: 0, attemptCount: 0, totalTokens: 0, estimatedCostUsd: 0 };
       models.set(mKey, m);
     }
     const requestKey = `${dayKey}\0${mKey}`;
@@ -360,26 +429,44 @@ function buildDayGrid(range: UsageRange, since: number | null, now: number, entr
     m.requests = requests.size;
     m.attemptCount += 1;
     m.totalTokens += usageDisplayTotalTokens(attribution.usage, attribution.totalTokens) ?? 0;
+    m.estimatedCostUsd += costUsd;
   };
   const startOfToday = startOfLocalDay(now);
   for (let i = days - 1; i >= 0; i--) {
     const d = new Date(startOfToday);
     d.setDate(d.getDate() - i);
     const key = localDateKey(d.getTime());
-    grid.set(key, { date: key, requests: 0, measuredRequests: 0, reportedRequests: 0, totalTokens: 0, models: [] });
+    grid.set(key, { date: key, requests: 0, measuredRequests: 0, reportedRequests: 0, totalTokens: 0, estimatedCostUsd: 0, models: [] });
   }
   for (const entry of entries) {
     const key = localDateKey(entry.timestamp);
     let day = grid.get(key);
     if (!day) {
-      day = { date: key, requests: 0, measuredRequests: 0, reportedRequests: 0, totalTokens: 0, models: [] };
+      day = { date: key, requests: 0, measuredRequests: 0, reportedRequests: 0, totalTokens: 0, estimatedCostUsd: 0, models: [] };
       grid.set(key, day);
     }
     day.requests += 1;
     if (isMeasuredStatus(entry.usageStatus)) day.measuredRequests += 1;
     if (entry.usageStatus === "reported") day.reportedRequests += 1;
     day.totalTokens += usageDisplayTotalTokens(entry.usage, entry.totalTokens) ?? 0;
-    for (const attribution of usageAttributions(entry)) bumpDayModel(key, attribution);
+    // Price through the same seam buildModels uses: combo attempts are priced
+    // per attempt and attributed to their own model, everything else to the
+    // entry's model. Re-deriving a price here would make days[] disagree with
+    // models[] for exactly the combo traffic where nobody would notice.
+    const attributionCosts = dayAttributionCosts(entry);
+    for (const attribution of usageAttributions(entry)) {
+      const attributionKey = usageModelKey(baseProviderLabel(attribution.provider), attribution.model);
+      // Spend each key's cost ONCE. `attributionCosts` already holds the SUM of every
+      // attempt that shares a provider/model key, while `usageAttributions` yields one
+      // entry per attempt — so a retry onto the same model would otherwise add that
+      // pair's total twice and double the day against `summary.estimatedCostUsd`.
+      // Deleting on read keeps the first attribution carrying the group's cost and gives
+      // its siblings zero, which is what `buildModels` already does per attempt.
+      const costUsd = attributionCosts.get(attributionKey) ?? 0;
+      attributionCosts.delete(attributionKey);
+      bumpDayModel(key, attribution, costUsd);
+      day.estimatedCostUsd += costUsd;
+    }
   }
   void since;
   const out = [...grid.values()].sort((a, b) => a.date.localeCompare(b.date));
@@ -391,13 +478,15 @@ function buildDayGrid(range: UsageRange, since: number | null, now: number, entr
         const requests = new Set<string>();
         let attemptCount = 0;
         let totalTokens = 0;
+        let estimatedCostUsd = 0;
         for (const model of overflow) {
           attemptCount += model.attemptCount;
           totalTokens += model.totalTokens;
+          estimatedCostUsd += model.estimatedCostUsd;
           const requestKey = `${day.date}\0${usageModelKey(model.provider, model.model)}`;
           for (const requestId of dayModelRequests.get(requestKey) ?? []) requests.add(requestId);
         }
-        return { model: "other", provider: "other", requests: requests.size, attemptCount, totalTokens };
+        return { model: "other", provider: "other", requests: requests.size, attemptCount, totalTokens, estimatedCostUsd };
       });
     }
   }
@@ -751,3 +840,107 @@ export function summarizeUsage(
     accounts: buildAccounts(filteredEntries),
   };
 }
+
+function normalizeFilterValue(input: string | null | undefined): string | null {
+  const trimmed = typeof input === "string" ? input.trim() : "";
+  return trimmed === "" ? null : trimmed.toLowerCase();
+}
+
+/**
+ * Narrow an already-summarised window to one provider and/or model.
+ *
+ * Deliberately a projection over a finished summary rather than a parameter to
+ * {@link summarizeUsage}. The management route caches summaries under
+ * `range:surface` and warms that key space as a cross-product; a filtered
+ * summary that reached either would be served to the next UNFILTERED caller,
+ * the dashboard included. Keeping the filter outside the producer makes that
+ * mistake unrepresentable rather than merely discouraged.
+ *
+ * Totals are recomputed from the retained rows. For combo traffic a request is
+ * counted once per participating model, so a filtered request count can exceed
+ * the number of distinct requests; `comboOverlap` reports when that is
+ * possible. Cost is unaffected — combo cost is attributed per attempt, so it
+ * partitions across models rather than repeating.
+ *
+ * `accounts` is emptied whenever a filter is active: account rows are not
+ * provider-partitioned in a way this projection could honestly re-derive, and
+ * unfiltered account totals sitting beside filtered model totals would invite
+ * exactly the wrong reading.
+ */
+export function projectUsageSummary<T extends UsageSummary>(
+  summary: T,
+  filter: { provider?: string | null; model?: string | null },
+  entries?: PersistedUsageEntry[],
+): T & { filter?: UsageFilterEcho } {
+  const provider = normalizeFilterValue(filter.provider);
+  const model = normalizeFilterValue(filter.model);
+  if (provider === null && model === null) return summary;
+
+  // Re-summarise from the entries the summary was built from, rather than
+  // projecting over its rows.
+  //
+  // Projecting rows looked cheaper and was wrong in three ways that only show
+  // up together: breakdown rows past MAX_USAGE_MODEL_BREAKDOWN_ROWS are
+  // collapsed into a synthetic "other" row, so a provider living only in that
+  // tail is unfindable and reports matched:false despite real usage; a
+  // provider row is a whole-provider aggregate, so a model filter kept the
+  // provider's OTHER models in providers[] while models[] and the totals
+  // excluded them, contradicting itself inside one response; and a model row
+  // carries a single optional cost, so priced/unpriced/unmetered counts could
+  // only be guessed per model rather than counted per request.
+  //
+  // The entries are already in hand on every path that filters, so the honest
+  // computation is also the simple one.
+  const matches = (rowProvider: string, rowModel: string): boolean => {
+    if (provider !== null && baseProviderLabel(rowProvider).toLowerCase() !== provider) return false;
+    if (model !== null && rowModel.toLowerCase() !== model) return false;
+    return true;
+  };
+
+  // Narrow to matching ATTRIBUTIONS, not matching entries.
+  //
+  // Keeping a whole combo entry because one of its attempts matched drags the
+  // other attempts' tokens and cost into the filtered totals: a two-attempt
+  // combo filtered to its cheap model reported the expensive model's spend
+  // too. Rewriting the entry down to its matching attempts is what makes the
+  // filtered numbers mean what the flag says.
+  const source = entries ?? [];
+  let comboOverlap = false;
+  const filtered: PersistedUsageEntry[] = [];
+  for (const entry of source) {
+    if (!entry.attempts?.length) {
+      if (matches(entry.provider, antigravityUsageModel(entry.provider, entry.model))) filtered.push(entry);
+      continue;
+    }
+    const attempts = entry.attempts.filter(a => matches(a.provider, antigravityUsageModel(a.provider, a.model)));
+    if (attempts.length === 0) continue;
+    // A combo is still counted once per participating model, so a filtered
+    // request count can exceed the number of distinct requests. That is the
+    // documented overlap, and it is why comboOverlap exists.
+    if (entry.attempts.length > 1) comboOverlap = true;
+    filtered.push({ ...entry, attempts });
+  }
+
+  const projected = summarizeUsage(filtered, summary.range, summary.generatedAt, summary.surface);
+  // matched reflects usage inside the requested WINDOW, not anywhere in the
+  // log: summarizeUsage applies the range and surface predicates, and the CLI
+  // uses this flag to decide between a table and "no usage recorded".
+  const matched = projected.summary.requests > 0;
+  // A combo entry survives the entry filter as a whole, so its non-matching
+  // attributions can still appear as rows. Drop those so every row in the
+  // response satisfies the filter the caller asked for.
+  const models = projected.models.filter(row => matches(row.provider, row.model));
+  const retainedProviders = new Set(models.map(row => row.provider));
+  return {
+    ...summary,
+    summary: projected.summary,
+    days: projected.days.map(day => ({ ...day, models: day.models.filter(row => matches(row.provider, row.model)) })),
+    models,
+    providers: projected.providers.filter(row => retainedProviders.has(row.provider)),
+    // Account rows are not provider-partitioned in a way this projection could
+    // honestly re-derive, and unfiltered account totals sitting beside filtered
+    // model totals would invite exactly the wrong reading.
+    accounts: [],
+    filter: { provider, model, matched, comboOverlap },
+  };
+}

package/src/vision/describe.ts

@@ -102,26 +102,31 @@ export async function describeImage(
       }),
       { abortSignal: linkedSignal.signal, label: "vision-sidecar" },
     );
-    recordOutcome?.(res.status);
-    if (!res.ok) {
-      const t = await res.text().catch(() => "");
-      console.warn(`[vision] sidecar HTTP ${res.status} (${Date.now() - t0}ms)`);
-      return { text: "", error: `vision sidecar HTTP ${res.status}: ${redactSecretString(t.slice(0, 200))}` };
-    }
     const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
-    let parsed;
     try {
-      parsed = await parseSidecarSSE(res);
+      if (!res.ok) {
+        recordOutcome?.(res.status);
+        const t = await res.text().catch(() => "");
+        console.warn(`[vision] sidecar HTTP ${res.status} (${Date.now() - t0}ms)`);
+        return { text: "", error: `vision sidecar HTTP ${res.status}: ${redactSecretString(t.slice(0, 200))}` };
+      }
+      const parsed = await parseSidecarSSE(res);
+      if (linkedSignal.signal.aborted) throw linkedSignal.signal.reason;
+      recordOutcome?.(res.status);
+      // The backend can return HTTP 200 then stream a `response.failed`/`error` event with no text;
+      // surface that as a describe error instead of an empty (silently-blank) description.
+      if (!parsed.text.trim() && parsed.error) return { text: "", error: parsed.error };
+      return { text: parsed.text };
     } finally {
       detachBodyGuard();
     }
-    // The backend can return HTTP 200 then stream a `response.failed`/`error` event with no text;
-    // surface that as a describe error instead of an empty (silently-blank) description.
-    if (!parsed.text.trim() && parsed.error) return { text: "", error: parsed.error };
-    return { text: parsed.text };
   } catch (e) {
-    recordOutcome?.(e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error");
     const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
+    const callerAborted = abortSignal?.aborted === true
+      && linkedSignal.signal.aborted
+      && linkedSignal.signal.reason === abortSignal.reason
+      && e === linkedSignal.signal.reason;
+    recordOutcome?.(callerAborted ? "connect_neutral" : kind);
     console.warn(`[vision] sidecar ${kind} (${Date.now() - t0}ms)`);
     return { text: "", error: e instanceof Error ? e.message : String(e) };
   } finally {

package/src/web-search/executor.ts

@@ -85,25 +85,32 @@ export async function runWebSearch(
       }),
       { abortSignal: linkedSignal.signal, label: "web-search-sidecar" },
     );
-    recordOutcome?.(res.status);
     // Attach the body guard before ANY branch reads it. The success path guarded itself below,
     // but the failure branch's `res.text()` runs first, so a cancel landing between fetch
     // resolution and reader attach orphaned the internal rejection (found investigating #1419).
     const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
     if (!res.ok) {
+      recordOutcome?.(res.status);
       const t = await res.text().catch(() => "");
       detachBodyGuard();
       console.warn(`[web-search] sidecar HTTP ${res.status} for query "${query.slice(0, 80)}" (${Date.now() - t0}ms)`);
       return { text: "", sources: [], error: `sidecar HTTP ${res.status}: ${redactSecretString(t.slice(0, 200))}` };
     }
     try {
-      return await parseSidecarSSE(res);
+      const parsed = await parseSidecarSSE(res);
+      if (linkedSignal.signal.aborted) throw linkedSignal.signal.reason;
+      recordOutcome?.(res.status);
+      return parsed;
     } finally {
       detachBodyGuard();
     }
   } catch (e) {
-    recordOutcome?.(e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error");
     const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
+    const callerAborted = abortSignal?.aborted === true
+      && linkedSignal.signal.aborted
+      && linkedSignal.signal.reason === abortSignal.reason
+      && e === linkedSignal.signal.reason;
+    recordOutcome?.(callerAborted ? "connect_neutral" : kind);
     console.warn(`[web-search] sidecar ${kind} for query "${query.slice(0, 80)}" (${Date.now() - t0}ms)`);
     return { text: "", sources: [], error: e instanceof Error ? e.message : String(e) };
   } finally {

package/src/web-search/gemini-executor.ts

@@ -19,6 +19,7 @@ import { ANTIGRAVITY_REQUEST_UA } from "../adapters/google-antigravity-wire";
 import { resolveAntigravityEffortWireModel } from "../providers/antigravity-models";
 import { getProviderRegistryEntry } from "../providers/registry";
 import { MAX_SIDECAR_RESPONSE_BYTES, type WebSearchSource } from "./parse";
+import { appendSafeWebSearchSource } from "./sources";
 import { BASE_INSTRUCTION, IMAGE_INSTRUCTION, type SidecarOutcome, type SidecarSettings } from "./executor";
 
 const CCA_FALLBACK_BASE = "https://daily-cloudcode-pa.googleapis.com";
@@ -117,25 +118,46 @@ export async function runGeminiWebSearch(
 }
 
 /** Map a CCA generateContent payload (possibly wrapped in {response}) to text + grounding sources. */
+export function extractCcaGroundingSources(groundingMetadata: unknown): WebSearchSource[] {
+  const sources: WebSearchSource[] = [];
+  const gm = isRec(groundingMetadata) ? groundingMetadata : undefined;
+  if (!gm || !Array.isArray(gm.groundingChunks)) return sources;
+  for (const chunk of gm.groundingChunks) {
+    const web = isRec(chunk) && isRec(chunk.web) ? chunk.web : undefined;
+    if (!web) continue;
+    // Route through the shared safe-source validator: enforces http(s) scheme,
+    // control-character filtering, dedup, and per-message count/byte budgets.
+    appendSafeWebSearchSource(sources, { url: web.uri, title: web.title });
+  }
+  return sources;
+}
+
+/** Skip search-suggestion HTML widgets Google may attach alongside grounded answers. */
+export function isCcaSearchSuggestionHtml(text: string): boolean {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("<")) return false;
+  return /<style[\s>]/i.test(trimmed) || /search[_-]?suggest/i.test(trimmed) || /grounding-widget/i.test(trimmed);
+}
+
+export function formatCcaGroundingSourcesAppendix(sources: readonly WebSearchSource[]): string {
+  if (sources.length === 0) return "";
+  const lines = ["", "Sources:"];
+  sources.slice(0, 8).forEach((s, i) => {
+    lines.push(`[${i + 1}] ${s.title ? `${s.title} — ` : ""}${s.url}`);
+  });
+  return lines.join("\n");
+}
+
 export function mapCcaGroundedResponse(payload: unknown): SidecarOutcome {
   const root = isRec(payload) && isRec(payload.response) ? payload.response : payload;
   if (!isRec(root)) return { text: "", sources: [], error: "gemini sidecar returned a non-JSON or empty body" };
   const candidate = Array.isArray(root.candidates) && isRec(root.candidates[0]) ? root.candidates[0] : undefined;
   if (!candidate) return { text: "", sources: [], error: "gemini sidecar returned no candidates" };
   const parts = isRec(candidate.content) && Array.isArray(candidate.content.parts) ? candidate.content.parts : [];
-  const text = parts.map(p => (isRec(p) && typeof p.text === "string" ? p.text : "")).join("");
-  const sources: WebSearchSource[] = [];
-  const seen = new Set<string>();
-  const gm = isRec(candidate.groundingMetadata) ? candidate.groundingMetadata : undefined;
-  if (gm && Array.isArray(gm.groundingChunks)) {
-    for (const chunk of gm.groundingChunks) {
-      const web = isRec(chunk) && isRec(chunk.web) ? chunk.web : undefined;
-      const uri = web && typeof web.uri === "string" ? web.uri : undefined;
-      if (!uri || seen.has(uri)) continue;
-      seen.add(uri);
-      sources.push({ url: uri, ...(typeof web?.title === "string" && web.title.length > 0 ? { title: web.title } : {}) });
-    }
-  }
+  const text = parts
+    .map(p => (isRec(p) && typeof p.text === "string" && !isCcaSearchSuggestionHtml(p.text) ? p.text : ""))
+    .join("");
+  const sources = extractCcaGroundingSources(candidate.groundingMetadata);
   if (text.length === 0) return { text: "", sources, error: "gemini sidecar returned no text" };
   return { text, sources };
 }