pi-advisor-flow 0.3.6 → 0.5.0

package/src/tools.ts

@@ -24,7 +24,6 @@ import {
   advisorGitContextMaxCharsRef,
   advisorGitContextRef,
   advisorLoopThresholdRef,
-  advisorMaxCallsPerSessionRef,
   advisorOutcomeLoggingRef,
   advisorPlanGateRef,
   advisorRedactSecretsRef,
@@ -35,6 +34,8 @@ import {
   advisorUntrackedContentRef,
   contextMaxCharsRef,
   executorRef,
+  getAdvisorMaxCallsPerSession,
+  getAdvisorSettings,
   isSimpleMode,
   loadConfig,
 } from "./config.js";
@@ -57,7 +58,12 @@ import {
   herdrAdvisorBlock,
   notifyHerdrAdvisorFailure,
 } from "./herdr.js";
-import { collectTextStream, resolveConfiguredModel } from "./model-stream.js";
+import {
+  ADVISOR_STREAM_UPDATE_INTERVAL_MS,
+  collectTextStream,
+  createCoalescedUpdate,
+  resolveConfiguredModel,
+} from "./model-stream.js";
 import { ADOPTIONS, appendOutcome, VALIDATIONS } from "./outcomes.js";
 import { readProjectPreferences } from "./preferences.js";
 import {
@@ -68,6 +74,7 @@ import {
 import {
   buildScoutManifest,
   reconstructScoutConversation,
+  SCOUT_MANIFEST_MAX_BYTES,
 } from "./scout-context.js";
 import {
   AdvisorSessionState,
@@ -75,8 +82,13 @@ import {
   type GateDecision,
   type GateTrigger,
 } from "./session-state.js";
-import type { BenchmarkTelemetry } from "./telemetry.js";
 import { readTrackedFiles, readUntrackedFiles } from "./untracked.js";
+import {
+  advisorUsageCost,
+  advisorUsageForPi,
+  formatAdvisorUsage,
+  snapshotAdvisorUsage,
+} from "./usage.js";
 
 export type {
   AdvisorInvocationRecord,
@@ -302,6 +314,7 @@ export interface AdvisorGateFailure {
   markdown?: string;
   message: string;
   ok: false;
+  usage?: unknown;
 }
 export interface AdvisorConsultationResult {
   adviceId: string;
@@ -327,14 +340,6 @@ export interface AdvisorGateResult {
 }
 export type AdvisorGateOutcome = AdvisorGateResult | AdvisorGateFailure;
 
-export const advisorUsageCost = (usage: unknown): number | undefined => {
-  const value = usage as
-    | { cost?: { total?: unknown }; totalCost?: unknown }
-    | undefined;
-  const cost = value?.cost?.total ?? value?.totalCost;
-  return typeof cost === "number" ? cost : undefined;
-};
-
 const DECISION_LINE = /^Decision\s*:\s*(proceed|revise|blocked)\s*$/i;
 const CODE_FENCE = /^(?:```|~~~)/;
 const LINE_BREAK = /\r?\n/;
@@ -431,8 +436,7 @@ export const curateAdvisorConversation = async (
   enabled = advisorScoutEnabledRef,
   runScout: typeof runAdvisorScout = runAdvisorScout,
   currentInvocationId?: string,
-  maxChars?: number,
-  telemetry?: BenchmarkTelemetry
+  maxChars?: number
 ): Promise<{
   conversation: string;
   scout?: Exclude<ScoutOutcome, { cancelled: true }>;
@@ -445,7 +449,8 @@ export const curateAdvisorConversation = async (
   }
   const built = buildScoutManifest(ctx, {
     currentInvocationId,
-    maxBytes: maxChars,
+    maxConversationChars: maxChars,
+    maxManifestBytes: SCOUT_MANIFEST_MAX_BYTES,
   });
   if (!built.ok) {
     const scout: Exclude<ScoutOutcome, { cancelled: true }> = {
@@ -470,8 +475,7 @@ export const curateAdvisorConversation = async (
     signal,
     onScout,
     undefined,
-    undefined,
-    telemetry
+    undefined
   );
   if (!outcome.ok && outcome.cancelled) {
     throw signal?.reason instanceof Error
@@ -504,8 +508,7 @@ const collectAdvisorResponse = async (
   includeUntracked?: string[],
   includeTracked?: string[],
   onScout?: (event: ScoutLifecycleEvent) => void,
-  currentInvocationId?: string,
-  telemetry?: BenchmarkTelemetry
+  currentInvocationId?: string
 ) => {
   loadConfig(ctx);
   const resolved = await resolveConfiguredModel(ctx, advisorRef, "Advisor");
@@ -551,8 +554,7 @@ const collectAdvisorResponse = async (
     advisorScoutEnabledRef,
     runAdvisorScout,
     currentInvocationId,
-    conversationBudget,
-    telemetry
+    conversationBudget
   );
   const { conversation, scout } = curated;
   const preferences = await readProjectPreferences(
@@ -643,43 +645,22 @@ export const consultAdvisor = async (
   includeUntracked?: string[],
   includeTracked?: string[],
   onScout?: (event: ScoutLifecycleEvent) => void,
-  currentInvocationId?: string,
-  telemetry?: BenchmarkTelemetry
+  currentInvocationId?: string
 ): Promise<AdvisorConsultationResult> => {
-  telemetry?.advisorStart({ model: advisorRef, question, trigger });
-  try {
-    const result = await collectAdvisorResponse(
-      ctx,
-      ADVISOR_SYSTEM,
-      question,
-      signal,
-      onChunk,
-      gitContext,
-      draft,
-      includeUntracked,
-      includeTracked,
-      onScout,
-      currentInvocationId,
-      telemetry
-    );
-    telemetry?.advisorEnd({
-      model: result.model,
-      outcome: "completed",
-      question,
-      response: result.markdown,
-      trigger,
-      usage: result.usage,
-    });
-    return { ...result, adviceId: randomUUID(), trigger };
-  } catch (error) {
-    telemetry?.advisorError({
-      category: signal?.aborted ? "cancelled" : "provider-error",
-      model: advisorRef,
-      question,
-      trigger,
-    });
-    throw error;
-  }
+  const result = await collectAdvisorResponse(
+    ctx,
+    ADVISOR_SYSTEM,
+    question,
+    signal,
+    onChunk,
+    gitContext,
+    draft,
+    includeUntracked,
+    includeTracked,
+    onScout,
+    currentInvocationId
+  );
+  return { ...result, adviceId: randomUUID(), trigger };
 };
 
 export const runAdvisorGate = async (
@@ -689,10 +670,8 @@ export const runAdvisorGate = async (
   signal?: AbortSignal,
   onChunk?: (thinking: string, text: string) => void,
   onScout?: (event: ScoutLifecycleEvent) => void,
-  currentInvocationId?: string,
-  telemetry?: BenchmarkTelemetry
+  currentInvocationId?: string
 ): Promise<AdvisorGateOutcome> => {
-  telemetry?.advisorStart({ model: advisorRef, question, trigger });
   try {
     const result = await collectAdvisorResponse(
       ctx,
@@ -705,20 +684,11 @@ export const runAdvisorGate = async (
       undefined,
       undefined,
       onScout,
-      currentInvocationId,
-      telemetry
+      currentInvocationId
     );
     const parsed = parseAutomaticDecision(result.markdown);
-    telemetry?.advisorEnd({
-      model: result.model,
-      outcome: parsed.ok ? `decision:${parsed.decision}` : parsed.category,
-      question,
-      response: result.markdown,
-      trigger,
-      usage: result.usage,
-    });
     if (!parsed.ok) {
-      return parsed;
+      return { ...parsed, usage: result.usage };
     }
     return {
       ...parsed,
@@ -728,12 +698,6 @@ export const runAdvisorGate = async (
       usage: result.usage,
     };
   } catch (error) {
-    telemetry?.advisorError({
-      category: signal?.aborted ? "cancelled" : "provider-error",
-      model: advisorRef,
-      question,
-      trigger,
-    });
     if (signal?.aborted) {
       throw error;
     }
@@ -749,6 +713,18 @@ export const runAdvisorGate = async (
   }
 };
 
+const updateAdvisorUsageStatus = (
+  ctx: ExtensionContext,
+  session: AdvisorSessionState
+) => {
+  if (ctx.hasUI) {
+    ctx.ui.setStatus(
+      "advisor-usage",
+      getAdvisorSettings().showUsageFooter ? session.usageStatus() : undefined
+    );
+  }
+};
+
 const notifyLocalFailure = (
   ctx: ExtensionContext,
   message: string,
@@ -773,12 +749,15 @@ export const gateFailureEffectForMode = (
     : ("session-blocked" as const);
 };
 
-const gateDecisionEffect = (decision: GateDecision) => {
+const gateDecisionEffect = (
+  decision: GateDecision,
+  failureMode: "block-session" | "block-tool" | "warn-and-continue"
+) => {
   if (decision === "proceed") {
     return "continued" as const;
   }
   return decision === "blocked"
-    ? ("session-blocked" as const)
+    ? gateFailureEffectForMode(failureMode)
     : ("tool-blocked" as const);
 };
 
@@ -786,15 +765,42 @@ const failureEffect = (
   category: GateFailureCategory,
   message: string,
   ctx: ExtensionContext,
-  session: AdvisorSessionState
+  session: AdvisorSessionState,
+  failureMode: "block-session" | "block-tool" | "warn-and-continue"
 ) => {
   const reason = `Advisor gate ${category}: ${message}`;
-  notifyLocalFailure(ctx, message, advisorFailureModeRef === "block-session");
+  notifyLocalFailure(ctx, message, failureMode === "block-session");
   notifyHerdrAdvisorFailure("Advisor gate failure", reason);
-  if (advisorFailureModeRef === "warn-and-continue") {
+  if (failureMode === "warn-and-continue") {
+    return { block: false, effect: "continued" as const, reason };
+  }
+  if (failureMode === "block-tool") {
+    return { block: true, effect: "tool-blocked" as const, reason };
+  }
+  session.block(reason);
+  herdrAdvisorBlock.set(reason);
+  if (advisorBlockOnBlockedRef) {
+    ctx.abort();
+  }
+  return { block: true, effect: "session-blocked" as const, reason };
+};
+
+const blockedDecisionEffect = (
+  reason: string,
+  ctx: ExtensionContext,
+  session: AdvisorSessionState,
+  failureMode: "block-session" | "block-tool" | "warn-and-continue"
+) => {
+  if (failureMode === "warn-and-continue") {
+    if (ctx.hasUI) {
+      ctx.ui.notify(
+        "Advisor gate returned blocked; continuing by configuration.",
+        "warning"
+      );
+    }
     return { block: false, effect: "continued" as const, reason };
   }
-  if (advisorFailureModeRef === "block-tool") {
+  if (failureMode === "block-tool") {
     return { block: true, effect: "tool-blocked" as const, reason };
   }
   session.block(reason);
@@ -814,7 +820,7 @@ const reserveAdvisorCall = (
   if (event.toolName !== "ask_advisor" || isSimpleMode()) {
     return;
   }
-  if (!session.canConsult(advisorMaxCallsPerSessionRef)) {
+  if (!session.canConsult(getAdvisorMaxCallsPerSession())) {
     const message = "Advisor call budget exhausted for this session.";
     if (ctx.hasUI) {
       ctx.ui.notify(message, "warning");
@@ -840,12 +846,20 @@ const sendAutomaticGateCall = (pi: ExtensionAPI, event: ToolCallEvent) => {
   );
 };
 
-const sendAutomaticGateFailure = (pi: ExtensionAPI, markdown: string) => {
+const sendAutomaticGateFailure = (
+  pi: ExtensionAPI,
+  markdown: string,
+  usage?: unknown
+) => {
+  const normalizedUsage = snapshotAdvisorUsage(usage);
   pi.sendMessage(
     {
       content: markdown,
       customType: "advisor-loop-result",
-      details: { text: markdown },
+      details: {
+        text: markdown,
+        ...(normalizedUsage ? { usage: normalizedUsage } : {}),
+      },
       display: true,
     },
     { deliverAs: "steer" }
@@ -864,6 +878,9 @@ const sendAutomaticGateResult = (
         advisor: result.model,
         decision: result.decision,
         text: result.markdown,
+        ...(snapshotAdvisorUsage(result.usage)
+          ? { usage: snapshotAdvisorUsage(result.usage) }
+          : {}),
       },
       display: true,
     },
@@ -877,8 +894,7 @@ const handleAutomaticGate = async (
   ctx: ExtensionContext,
   session: AdvisorSessionState,
   runGate: typeof runAdvisorGate,
-  scoutStatus: ScoutStatusManager,
-  telemetry?: BenchmarkTelemetry
+  scoutStatus: ScoutStatusManager
 ): Promise<ToolCallEventResult | undefined> => {
   if (
     isSimpleMode() ||
@@ -893,12 +909,14 @@ const handleAutomaticGate = async (
     return;
   }
   const reason = `Advisor loop gate: normalized signature for ${event.toolName} repeated ${advisorLoopThresholdRef} times without a materially different tool action.`;
-  if (!session.canConsult(advisorMaxCallsPerSessionRef)) {
+  const failureMode = advisorFailureModeRef;
+  if (!session.canConsult(getAdvisorMaxCallsPerSession())) {
     const failure = failureEffect(
       "budget-exhausted",
       "Advisor gate call budget is exhausted.",
       ctx,
-      session
+      session,
+      failureMode
     );
     return failure.block ? { block: true, reason: failure.reason } : undefined;
   }
@@ -931,27 +949,30 @@ const handleAutomaticGate = async (
           ensureGateCall();
         }
       },
-      event.toolCallId,
-      telemetry
+      event.toolCallId
     );
     ensureGateCall();
     if (!result.ok) {
       session.recordInvocation({
-        executionEffect: gateFailureEffectForMode(advisorFailureModeRef),
+        executionEffect: gateFailureEffectForMode(failureMode),
         failure: result.category,
         kind: "gate",
         model: advisorRef,
         trigger: "repeated-tool-call",
+        usage: result.usage,
       });
+      updateAdvisorUsageStatus(ctx, session);
       const failure = failureEffect(
         result.category,
         result.message,
         ctx,
-        session
+        session,
+        failureMode
       );
       sendAutomaticGateFailure(
         pi,
-        `**Advisor gate failure (${result.category}):** ${result.message}`
+        `**Advisor gate failure (${result.category}):** ${result.message}`,
+        result.usage
       );
       return failure.block
         ? { block: true, reason: `${reason}\n${failure.reason}` }
@@ -960,12 +981,13 @@ const handleAutomaticGate = async (
     session.recordInvocation({
       cost: advisorUsageCost(result.usage),
       decision: result.decision,
-      executionEffect: gateDecisionEffect(result.decision),
+      executionEffect: gateDecisionEffect(result.decision, failureMode),
       kind: "gate",
       model: result.model,
       trigger: result.trigger,
       usage: result.usage,
     });
+    updateAdvisorUsageStatus(ctx, session);
     sendAutomaticGateResult(pi, result);
     if (result.decision === "proceed") {
       session.resetRepetition();
@@ -973,11 +995,13 @@ const handleAutomaticGate = async (
     }
     const gateReason = `Advisor loop review: ${result.markdown}`;
     if (result.decision === "blocked") {
-      session.block(gateReason);
-      herdrAdvisorBlock.set(gateReason);
-      if (advisorBlockOnBlockedRef) {
-        ctx.abort();
-      }
+      const effect = blockedDecisionEffect(
+        gateReason,
+        ctx,
+        session,
+        failureMode
+      );
+      return effect.block ? { block: true, reason: effect.reason } : undefined;
     }
     return { block: true, reason: gateReason };
   } finally {
@@ -1011,6 +1035,7 @@ interface AdvisorToolDetails {
   thinking?: string;
   trackedBytes?: number;
   untrackedBytes?: number;
+  usage?: unknown;
 }
 interface AdvisorRenderState {
   phase?: string;
@@ -1059,7 +1084,7 @@ export const scoutDetailsFromEvent = (
         selectedLabels: outcome.selectedLabels,
         status: "curated",
         synthesis: outcome.selection.synthesis,
-        usage: outcome.metrics.usage,
+        usage: snapshotAdvisorUsage(outcome.metrics.usage),
       }
     : {
         availableCount: outcome.metrics.availableCount,
@@ -1069,7 +1094,7 @@ export const scoutDetailsFromEvent = (
         omittedBeforeScout: outcome.metrics.omittedBeforeScout,
         selectedCount: 0,
         status: "fallback",
-        usage: outcome.metrics.usage,
+        usage: snapshotAdvisorUsage(outcome.metrics.usage),
       };
 };
 
@@ -1093,6 +1118,11 @@ export class ScoutStatusManager {
   readonly #active = new Set<symbol>();
   readonly #known = new Set<symbol>();
   readonly #retired = new Set<symbol>();
+  private readonly showStatus: boolean;
+
+  constructor(showStatus = true) {
+    this.showStatus = showStatus;
+  }
 
   register(token: symbol) {
     if (!this.#retired.has(token)) {
@@ -1107,7 +1137,9 @@ export class ScoutStatusManager {
     this.#known.add(token);
     if (event.type === "call" || event.type === "chunk") {
       this.#active.add(token);
-      ctx.ui.setStatus("advisor-scout", "Scout curating…");
+      if (this.showStatus) {
+        ctx.ui.setStatus("advisor-scout", "Scout curating…");
+      }
       return;
     }
     this.release(ctx, token);
@@ -1117,7 +1149,7 @@ export class ScoutStatusManager {
     this.#active.delete(token);
     this.#known.delete(token);
     this.#retired.add(token);
-    if (!ctx.hasUI) {
+    if (!(ctx.hasUI && this.showStatus)) {
       return;
     }
     ctx.ui.setStatus(
@@ -1132,7 +1164,7 @@ export class ScoutStatusManager {
     }
     this.#known.clear();
     this.#active.clear();
-    if (ctx.hasUI) {
+    if (ctx.hasUI && this.showStatus) {
       ctx.ui.setStatus("advisor-scout", undefined);
     }
   }
@@ -1173,6 +1205,12 @@ export const renderScoutDetails = (
       `  ${scout.model}${scout.selectedCount === undefined ? "" : ` · ${scout.selectedCount} kept / ${Math.max(0, (scout.availableCount ?? 0) - scout.selectedCount)} omitted`}${scout.latencyMs === undefined ? "" : ` · ${(scout.latencyMs / 1000).toFixed(1)}s`}`
     ),
   ];
+  if (getAdvisorSettings().showUsageDetails) {
+    const usage = formatAdvisorUsage(scout.usage);
+    if (usage) {
+      lines.push(theme.fg("dim", `  Usage: ${usage}`));
+    }
+  }
   if (scout.fallbackReason) {
     lines.push(theme.fg("warning", `  ${scout.fallbackReason}`));
   }
@@ -1293,6 +1331,12 @@ const renderFinalAdvisorResult = (
   if (details?.advisor) {
     lines.push(theme.fg("dim", `  ${details.advisor}`));
   }
+  if (getAdvisorSettings().showUsageDetails) {
+    const usage = formatAdvisorUsage(details?.usage);
+    if (usage) {
+      lines.push(theme.fg("dim", `  Usage: ${usage}`));
+    }
+  }
   const attachments = [
     details?.draftBytes
       ? `Draft attached · ${details.draftBytes} B`
@@ -1355,11 +1399,14 @@ export const registerAdvisorTool = (
   pi: ExtensionAPI,
   session: AdvisorSessionState = advisorSessionState,
   dependencies: {
+    appendOutcome?: typeof appendOutcome;
+    consult?: typeof consultAdvisor;
     runGate?: typeof runAdvisorGate;
     statusManager?: ScoutStatusManager;
-    telemetry?: BenchmarkTelemetry;
   } = {}
 ) => {
+  const appendAdvisorOutcome = dependencies.appendOutcome ?? appendOutcome;
+  const requestAdvisor = dependencies.consult ?? consultAdvisor;
   const reservedCalls = new Set<string>();
   const scoutStatus = dependencies.statusManager ?? new ScoutStatusManager();
 
@@ -1385,7 +1432,12 @@ export const registerAdvisorTool = (
     "advisor-loop-result",
     (message, { expanded }, theme) => {
       const details = message.details as
-        | { decision?: GateDecision; text?: string; advisor?: string }
+        | {
+            advisor?: string;
+            decision?: GateDecision;
+            text?: string;
+            usage?: unknown;
+          }
         | undefined;
       const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
       box.addChild(
@@ -1401,6 +1453,12 @@ export const registerAdvisorTool = (
       if (details?.advisor) {
         box.addChild(new Text(theme.fg("dim", `  ${details.advisor}`), 0, 0));
       }
+      if (getAdvisorSettings().showUsageDetails) {
+        const usage = formatAdvisorUsage(details?.usage);
+        if (usage) {
+          box.addChild(new Text(theme.fg("dim", `  Usage: ${usage}`), 0, 0));
+        }
+      }
       if (details?.text) {
         box.addChild(
           new Markdown(
@@ -1428,10 +1486,13 @@ export const registerAdvisorTool = (
     }
   );
 
-  pi.on("session_start", () => {
+  pi.on("session_start", (_event, ctx) => {
     session.resetTask();
     reservedCalls.clear();
     herdrAdvisorBlock.clear();
+    if (ctx?.hasUI) {
+      ctx.ui.setStatus("advisor-usage", undefined);
+    }
   });
 
   pi.on("before_agent_start", (_event, ctx) => {
@@ -1442,7 +1503,7 @@ export const registerAdvisorTool = (
     const guidelines = advisorInvocationGuidelines();
     const budget = isSimpleMode()
       ? undefined
-      : session.remainingCalls(advisorMaxCallsPerSessionRef);
+      : session.remainingCalls(getAdvisorMaxCallsPerSession());
     if (budget !== undefined) {
       guidelines.push(
         `Advisor calls remaining this session: ${budget}.\nReserve calls for material decisions, repeated failures, or final review.`
@@ -1476,8 +1537,7 @@ export const registerAdvisorTool = (
       ctx,
       session,
       dependencies.runGate ?? runAdvisorGate,
-      scoutStatus,
-      dependencies.telemetry
+      scoutStatus
     );
   });
 
@@ -1488,7 +1548,7 @@ export const registerAdvisorTool = (
     if (isSimpleMode() || session.blocked || !advisorSessionSummaryRef) {
       return;
     }
-    const summary = session.summary(advisorMaxCallsPerSessionRef);
+    const summary = session.summary(getAdvisorMaxCallsPerSession());
     if (summary && ctx.hasUI) {
       ctx.ui.notify(summary, "info");
     }
@@ -1498,6 +1558,9 @@ export const registerAdvisorTool = (
     reservedCalls.clear();
     scoutStatus.clear(ctx);
     herdrAdvisorBlock.clear();
+    if (ctx?.hasUI) {
+      ctx.ui.setStatus("advisor-usage", undefined);
+    }
   });
 
   pi.registerTool({
@@ -1514,20 +1577,31 @@ export const registerAdvisorTool = (
         );
       }
       if (!isSimpleMode()) {
-        if (!session.canConsult(advisorMaxCallsPerSessionRef)) {
+        if (!session.canConsult(getAdvisorMaxCallsPerSession())) {
           throw new Error("Advisor call budget exhausted for this session.");
         }
         session.consumeCall();
       }
       herdrAdvisorActivity.start();
       let scoutDetails: ScoutToolDetails | undefined;
+      const coalescedUpdate = createCoalescedUpdate(
+        (update: Parameters<NonNullable<typeof onUpdate>>[0]) =>
+          onUpdate?.(update),
+        ADVISOR_STREAM_UPDATE_INTERVAL_MS
+      );
+      const flushUpdate = () => {
+        const result = coalescedUpdate.flush();
+        if (result.failed) {
+          throw result.error;
+        }
+      };
       try {
-        const result = await consultAdvisor(
+        const result = await requestAdvisor(
           ctx,
           resolveAdvisorRequest(params.question),
           signal,
           (t, tx) =>
-            onUpdate?.({
+            coalescedUpdate.update({
               content: [{ text: tx, type: "text" }],
               details: {
                 advisor: advisorRef,
@@ -1545,7 +1619,7 @@ export const registerAdvisorTool = (
           params.includeTrackedFiles,
           (event) => {
             scoutDetails = scoutDetailsFromEvent(event, scoutDetails);
-            onUpdate?.({
+            coalescedUpdate.update({
               content: [{ text: scoutDetails.text ?? "", type: "text" }],
               details: {
                 advisor: advisorRef,
@@ -1554,9 +1628,9 @@ export const registerAdvisorTool = (
               },
             });
           },
-          _id,
-          dependencies.telemetry
+          _id
         );
+        flushUpdate();
         session.issueAdvice(
           result.adviceId,
           result.markdown,
@@ -1571,6 +1645,9 @@ export const registerAdvisorTool = (
           trigger: "executor-requested",
           usage: result.usage,
         });
+        const usage = snapshotAdvisorUsage(result.usage);
+        const piUsage = advisorUsageForPi(result.usage);
+        updateAdvisorUsageStatus(ctx, session);
         return {
           content: [
             {
@@ -1589,9 +1666,15 @@ export const registerAdvisorTool = (
             thinking: result.thinkingText,
             trackedBytes: result.trackedBytes,
             untrackedBytes: result.untrackedBytes,
+            ...(usage ? { usage } : {}),
           },
+          ...(piUsage ? { usage: piUsage } : {}),
         };
       } catch (error) {
+        // Publish the latest partial state before surfacing a provider or
+        // execution error. A failure from the UI sink must not replace the
+        // original error because this path is also used for provider failures.
+        coalescedUpdate.flush();
         const message = error instanceof Error ? error.message : String(error);
         session.recordInvocation({
           executionEffect: "continued",
@@ -1600,10 +1683,12 @@ export const registerAdvisorTool = (
           model: advisorRef,
           trigger: "executor-requested",
         });
+        updateAdvisorUsageStatus(ctx, session);
         notifyLocalFailure(ctx, message);
         notifyHerdrAdvisorFailure("Advisor consultation failed", message);
         throw error;
       } finally {
+        coalescedUpdate.cancel();
         herdrAdvisorActivity.finish();
       }
     },
@@ -1680,18 +1765,19 @@ export const registerAdvisorTool = (
           details: { recorded: false },
         };
       }
-      const advice = session.claimAdvice(params.adviceId);
+      const advice = session.reserveAdvice(params.adviceId);
       if (!advice) {
-        throw new Error("Unknown or already recorded adviceId.");
+        throw new Error("Unknown, already recorded, or pending adviceId.");
       }
       try {
-        await appendOutcome({
+        await appendAdvisorOutcome({
           adoption: params.adoption as (typeof ADOPTIONS)[number],
           advice: advice.advice,
           trigger: advice.trigger,
           validationStatus:
             params.validationStatus as (typeof VALIDATIONS)[number],
         });
+        session.commitAdvice(params.adviceId);
         return {
           content: [
             { text: "Advisor outcome recorded locally.", type: "text" },
@@ -1699,6 +1785,7 @@ export const registerAdvisorTool = (
           details: { recorded: true },
         };
       } catch {
+        session.releaseAdvice(params.adviceId);
         if (ctx.hasUI) {
           ctx.ui.notify(
             "Advisor outcome could not be recorded locally.",