refactor(webapp): one presenter for all watch and view-block wording

Every watch sentence (card, banner, toast, email, Slack, webhook) now comes from
app/presenters/v3/dashboardAgent. The condition is written once per kind in four
registers instead of in four switches across three files, and a plain-text block
renderer lets the non-React surfaces say what the card says.

Author: kathiekiwi

apps/webapp/app/components/dashboard-agent/WakeBanner.tsx

@@ -2,7 +2,7 @@
  * The banner above a wake narration.
  *
  * This component holds no kind-specific wording: tone, semantic icon and headline
- * come from contracts and `watch-presentation.ts`. All it decides is which glyph a
+ * come from contracts and `app/presenters/v3/dashboardAgent`. All it decides is which glyph a
  * semantic icon draws and which frame a tone paints.
  *
  * A wake is identified by its message id, `wake:watch:{watchId}:{fired|expired}`.
@@ -23,7 +23,11 @@ import type {
 } from "@internal/dashboard-agent-contracts";
 import { cn } from "~/utils/cn";
 import { type AgentTone, TONE_ICON_COLOR } from "./agent-badges";
-import { presentResolvedWatch, WATCH_PRESENTATION_FALLBACK } from "./watch-presentation";
+import {
+  presentResolvedWatch,
+  watchSubline,
+  WATCH_PRESENTATION_FALLBACK,
+} from "~/presenters/v3/dashboardAgent";
 
 const WAKE_ID_PREFIX = "wake:watch:";
 
@@ -121,15 +125,6 @@ const TONE_FRAME: Record<AgentTone, string> = {
   error: "border-l-error bg-error/10",
 };
 
-/** What the watch was for: the user's own words, else whatever names it. */
-function subline(watch: WakeWatch | undefined): string | null {
-  const note = watch?.note.trim();
-  if (note) return note;
-  if (watch?.identity) return watch.identity;
-  if (watch?.kind) return watch.kind;
-  return null;
-}
-
 export function WakeBanner({
   outcome,
   watch,
@@ -142,7 +137,7 @@ export function WakeBanner({
   const presentation = wakePresentation(outcome, watch);
   const tone = presentation.tone as AgentTone;
   const Icon = SEMANTIC_ICON[presentation.semanticIcon];
-  const note = subline(watch);
+  const note = watchSubline(watch);
 
   return (
     <div

apps/webapp/app/components/dashboard-agent/WatchButton.tsx

@@ -2,7 +2,7 @@ import { EyeIcon } from "@heroicons/react/20/solid";
 import type { WatchSpec } from "@internal/dashboard-agent-contracts";
 import { Button } from "~/components/primitives/Buttons";
 import { useDashboardAgent } from "./dashboardAgentLauncher";
-import { watchTooltipLabel } from "./watch-presentation";
+import { watchTooltipLabel } from "~/presenters/v3/dashboardAgent";
 
 /**
  * The universal Watch action, used by runs, queues, errors and health.

apps/webapp/app/components/dashboard-agent/WatchCard.tsx

@@ -8,7 +8,7 @@
  * and never become a radio group.
  *
  * Pure component: draft in, markup and callbacks out. Draft rules live in
- * `watch-card.ts` and wording in `watch-presentation.ts`.
+ * `watch-card.ts` and wording in `app/presenters/v3/dashboardAgent`.
  */
 import { EyeIcon } from "@heroicons/react/20/solid";
 import {
@@ -41,7 +41,7 @@ import {
   watchConditionLabel,
   watchDurationLabel,
   watchSubjectLabel,
-} from "./watch-presentation";
+} from "~/presenters/v3/dashboardAgent";
 
 /** How the condition variants are named in the picker. Short, not sentences. */
 const VARIANT_LABEL: Record<WatchKind, string> = {

apps/webapp/app/components/dashboard-agent/WatchResultBlock.tsx

@@ -7,7 +7,7 @@
  * cancel.
  *
  * Pure component: the wording is not computed here, it was frozen into the block at
- * append time by `watch-presentation.ts`, so a later copy change never rewrites what
+ * append time by `app/presenters/v3/dashboardAgent`, so a later copy change never rewrites what
  * a user was already told.
  */
 import { CheckCircleIcon, EyeIcon, InformationCircleIcon } from "@heroicons/react/20/solid";

apps/webapp/app/components/dashboard-agent/WatchWakeToast.tsx

@@ -11,7 +11,7 @@ import { Button } from "~/components/primitives/Buttons";
 import { ToastUI } from "~/components/primitives/Toast";
 import type { WatchObservedOutcome, WatchResolution } from "@internal/dashboard-agent-contracts";
 import { wakeResolution } from "./WakeBanner";
-import { presentResolvedWatch, WATCH_PRESENTATION_FALLBACK } from "./watch-presentation";
+import { presentResolvedWatch, WATCH_PRESENTATION_FALLBACK } from "~/presenters/v3/dashboardAgent";
 
 /** Matches sonner's default toast width, same as the app's other toasts. */
 const TOAST_WIDTH = 356;
@@ -41,7 +41,7 @@ export type WatchWake = {
 
 /**
  * The toast's title: the fact, or the neutral fallback when this wake predates the
- * resolution model. The wording is `watch-presentation.ts`'s; this only decides
+ * resolution model. The wording is `app/presenters/v3/dashboardAgent`'s; this only decides
  * which watch to ask it about.
  */
 export function watchWakeToastTitle(wake: WatchWake): string {

apps/webapp/app/components/dashboard-agent/watch-card.test.ts

@@ -25,7 +25,7 @@ import {
   watchDurationLabel,
   watchOneShotBlockBody,
   watchSubjectLabel,
-} from "./watch-presentation";
+} from "~/presenters/v3/dashboardAgent";
 import {
   errorWatchRecommendation,
   healthWatchRecommendation,
@@ -145,9 +145,11 @@ describe("condition variants (§3)", () => {
 
   it("restates the note when the threshold number changes", () => {
     const above = withThreshold(withVariant(queueDraft(), "queue_depth_above"), 500);
-    expect(above.spec.note).toBe("tell me if the email-sends queue grows above 500");
+    // Same verb and same SLA format as the card's condition line: both come from
+    // the presenter's one wording record.
+    expect(above.spec.note).toBe("tell me if the email-sends queue goes above 500");
     const age = withAgeMinutes(withVariant(queueDraft(), "queue_oldest_age"), 90);
-    expect(age.spec.note).toBe("tell me if runs in email-sends wait longer than 90 minutes");
+    expect(age.spec.note).toBe("tell me if runs in email-sends wait longer than 1h 30m");
   });
 
   it("gives the threshold variant a usable default", () => {

apps/webapp/app/components/dashboard-agent/watch-card.ts

@@ -24,6 +24,7 @@ import {
   type WatchKind,
   type WatchSpec,
 } from "@internal/dashboard-agent-contracts";
+import { noteFor } from "~/presenters/v3/dashboardAgent";
 
 /** A brand-new draft: the recommendation, with both opt-ins off. */
 export function watchDraftFor(spec: WatchSpec): WatchDraft {
@@ -40,36 +41,6 @@ export function clampCadence(kind: WatchKind, minutes: number): number {
   return options.find((option) => option >= minutes) ?? options[options.length - 1]!;
 }
 
-/**
- * The note, restated from the spec. The wake narration quotes the note, so
- * changing the condition or its number must rewrite it. Edits that keep the
- * condition (window, cadence) keep the user's own words.
- */
-export function noteFor(spec: WatchSpec): string {
-  switch (spec.kind) {
-    case "run_start":
-      return `tell me when run ${spec.runId} starts`;
-    case "run_finished":
-      return `tell me when run ${spec.runId} finishes`;
-    case "run_failed":
-      return `tell me if run ${spec.runId} fails`;
-    case "backlog_drain":
-      return `tell me when the ${spec.queue} queue drains`;
-    case "queue_depth_above":
-      return `tell me if the ${spec.queue} queue grows above ${spec.threshold}`;
-    case "queue_depth_below":
-      return `tell me when the ${spec.queue} queue is back below ${spec.threshold}`;
-    case "queue_stalled":
-      return `tell me if the ${spec.queue} queue stops moving`;
-    case "queue_oldest_age":
-      return `tell me if runs in ${spec.queue} wait longer than ${spec.thresholdMinutes} minutes`;
-    case "error_recurrence":
-      return `ping me if error ${spec.fingerprint} happens again`;
-    case "health_recovery":
-      return "tell me when health is back to normal";
-  }
-}
-
 /**
  * Swap the condition for its sibling variant, carrying everything else except the
  * note, which is restated to describe the new condition.

apps/webapp/app/components/dashboard-agent/watch-chips.ts

@@ -10,9 +10,9 @@ import type { WatchStatus } from "@internal/dashboard-agent-contracts";
 
 // The immediate-check wording lives in the presenter with the rest of the
 // user-facing copy. Re-exported here for chip callers.
-export { immediateWatchMessage } from "./watch-presentation";
+export { immediateWatchMessage } from "~/presenters/v3/dashboardAgent";
 
-import { formatWatchCadence, watchIdentityValue } from "./watch-presentation";
+import { formatWatchCadence, watchIdentityValue } from "~/presenters/v3/dashboardAgent";
 
 export const WATCH_STATUS_LABEL: Record<WatchStatus, string> = {
   active: "watching",

apps/webapp/app/components/dashboard-agent/watch-recommendations.ts

@@ -12,19 +12,28 @@ import {
   type WatchSpec,
 } from "@internal/dashboard-agent-contracts";
 import { OLDEST_WAIT_WARNING_MS } from "~/components/queues/queue-thresholds";
+import { noteFor } from "~/presenters/v3/dashboardAgent";
+
+/** Distributes over the spec union, so the kind stays discriminated. */
+type WithoutNote<T> = T extends unknown ? Omit<T, "note"> : never;
+
+/** The note comes from the presenter, so a recommendation reads like an edited one. */
+function withNote(spec: WithoutNote<WatchSpec>): WatchSpec {
+  const draft = { ...spec, note: "" } as WatchSpec;
+  return { ...draft, note: noteFor(draft) };
+}
 
 /**
  * A run is the one object worth checking every minute: it is a single row read, and
  * a run that lands in ninety seconds should not be reported five minutes late.
  */
 export function runWatchRecommendation(runFriendlyId: string): WatchSpec {
-  return {
+  return withNote({
     kind: "run_finished",
     runId: runFriendlyId,
     checkEveryMinutes: 1,
     maxHours: 1,
-    note: `tell me when run ${runFriendlyId} finishes`,
-  };
+  });
 }
 
 /**
@@ -42,13 +51,12 @@ export function queueWatchRecommendation(
 ): WatchSpec {
   const oldestWaitMs = context?.oldestWaitMs ?? null;
   if (oldestWaitMs !== null && oldestWaitMs >= OLDEST_WAIT_WARNING_MS) {
-    return {
+    return withNote({
       kind: "backlog_drain",
       queue: queueName,
       checkEveryMinutes: 5,
       maxHours: 1,
-      note: `tell me when the ${queueName} queue drains`,
-    };
+    });
   }
 
   return queueAgeWatchRecommendation(queueName);
@@ -59,41 +67,38 @@ export function queueAgeWatchRecommendation(
   queueName: string,
   thresholdMinutes: number = WATCH_DEFAULT_QUEUE_AGE_MINUTES
 ): WatchSpec {
-  return {
+  return withNote({
     kind: "queue_oldest_age",
     queue: queueName,
     thresholdMinutes,
     checkEveryMinutes: 5,
     maxHours: 1,
-    note: `tell me if runs in ${queueName} wait longer than ${thresholdMinutes} minutes`,
-  };
+  });
 }
 
 /**
  * A recurrence needs room to happen, so the window is longer than the other three:
  * plenty of errors come back within the working day rather than in ten minutes.
  */
 export function errorWatchRecommendation(errorFriendlyId: string): WatchSpec {
-  return {
+  return withNote({
     kind: "error_recurrence",
     fingerprint: errorFriendlyId,
     checkEveryMinutes: 5,
     maxHours: 6,
-    note: `ping me if error ${errorFriendlyId} happens again`,
-  };
+  });
 }
 
 /**
  * Only offered on a degraded report: a recovery watch is meaningless while
  * everything is fine. `fromSeverity` is the state the recovery is measured from.
  */
 export function healthWatchRecommendation(fromSeverity: "warn" | "crit"): WatchSpec {
-  return {
+  return withNote({
     kind: "health_recovery",
     report: "health",
     fromSeverity,
     checkEveryMinutes: 5,
     maxHours: 2,
-    note: "tell me when health is back to normal",
-  };
+  });
 }

apps/webapp/app/presenters/v3/dashboardAgent/block-text.ts

@@ -0,0 +1,98 @@
+/**
+ * A view block or a resolved watch as plain text.
+ *
+ * The panel renders blocks as React; an email, a Slack message, a webhook body or
+ * a log line cannot. Rather than each of those re-saying the block's contents in
+ * its own words, they render it here. Pure, no React, no request context.
+ */
+import type { ViewBlock } from "@internal/dashboard-agent-contracts";
+import { presentResolvedWatch, watchNoteLine, type WatchResolvedInput } from "./watch-wording";
+
+/** A labelled scalar the check observed. */
+export type TextFact = { label: string; value: string };
+
+/** Facts as one `Label: value` line each. */
+export function renderFactLines(facts: readonly TextFact[]): string[] {
+  return facts.map((fact) => `${fact.label}: ${fact.value}`);
+}
+
+function lines(...parts: Array<string | null | undefined | false>): string {
+  return parts
+    .filter((part): part is string => typeof part === "string" && part.length > 0)
+    .join("\n");
+}
+
+/**
+ * One view block as plain text. Says what the card says and nothing more — no
+ * surface may add a sentence of its own on top.
+ */
+export function renderBlockAsText(block: ViewBlock): string {
+  switch (block.type) {
+    case "watch_result":
+      return lines(block.headline, block.lifetime, block.detail, ...block.followUp);
+
+    case "diagnosis":
+      return lines(
+        block.summary,
+        `Likely cause: ${block.likelyCause}`,
+        `Confidence: ${block.confidence}`,
+        block.impact ? `Impact: ${block.impact}` : null,
+        ...block.evidence.map(
+          (item) =>
+            `Evidence (${item.type}): ${item.detail}${item.reference ? ` — ${item.reference}` : ""}`
+        ),
+        ...block.nextSteps.map((step, index) => `${index + 1}. ${step}`)
+      );
+
+    case "investigation": {
+      const state = block.investigation;
+      return lines(
+        state.title,
+        state.headline,
+        `Outcome: ${state.outcome} · severity ${state.severity} · confidence ${state.confidence}`,
+        ...state.hypotheses.map(
+          (hypothesis) =>
+            `${hypothesis.statement} — ${hypothesis.verdict}${
+              hypothesis.finding ? `: ${hypothesis.finding}` : ""
+            }`
+        ),
+        state.remediation ? `Fix: ${state.remediation}` : null,
+        ...(state.checkNext ?? []).map((step) => `Check next: ${step}`),
+        state.caveat ? `Caveat: ${state.caveat.message}` : null
+      );
+    }
+
+    case "report": {
+      const { vm } = block;
+      return lines(
+        `${vm.title} report for ${vm.scope} (${vm.period}): ${vm.summary.severity}`,
+        ...vm.findings.map((finding) => `${finding.type} — ${finding.severity}: ${finding.reason}`)
+      );
+    }
+
+    // A chart is its shape, not its rows: the rows come from running the query.
+    case "chart":
+      return lines(`Chart: ${block.title ?? "untitled"} (${block.chartType})`, block.query);
+
+    case "actions":
+      return lines(...block.actions.map((action) => `- ${action.label}`));
+
+    default: {
+      const unreachable: never = block;
+      throw new Error(`Unhandled view block: ${JSON.stringify(unreachable)}`);
+    }
+  }
+}
+
+/**
+ * A resolved watch as plain text: the fact, why it was being watched, then what the
+ * resolving check saw. What the email body and the Slack message both say.
+ */
+export function renderResolvedWatchAsText(args: {
+  resolved: WatchResolvedInput;
+  note: string;
+  facts: readonly TextFact[];
+}): string {
+  const { headline } = presentResolvedWatch(args.resolved);
+  return lines(headline, watchNoteLine(args.note), ...renderFactLines(args.facts));
+}