chore: restore the comments an off-by-one over-trimmed

Author: kathiekiwi

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

@@ -43,8 +43,10 @@ const SEMANTIC_ICON: Record<WatchSemanticIcon, (props: { className?: string }) =
   info: InformationCircleIcon,
 };
 
-// A terminal chip wears the resolved result's icon, not its lifecycle status: a
-// `run_finished` watch on a failed run resolves `condition_met`.
+/**
+ * A terminal chip wears the resolved result's icon, not its lifecycle status: a
+ * `run_finished` watch on a failed run resolves `condition_met`. Cancellation has none.
+ */
 function StatusIcon({ watch }: { watch: WatchChip }) {
   if (watch.status === "active") return <AgentSpinner size={14} />;
 

apps/webapp/app/components/dashboard-agent/suggested-prompts/page-mappers.ts

@@ -1,4 +1,7 @@
-// A mapper may not cause a query, and signals are emitted only for abnormal state.
+/**
+ * Route `handle` mappers: loader data in, `AgentPageContext` out. A mapper may
+ * not cause a query, and signals are emitted only for abnormal state.
+ */
 import type { AgentPageContext, AgentPageSignal } from "@internal/dashboard-agent-contracts";
 import { z } from "zod";
 

apps/webapp/app/components/dashboard-agent/suggested-prompts/registry.ts

@@ -1,4 +1,7 @@
-// Pure: no React, no server imports, no clock beyond the `now` passed in.
+/**
+ * The chips the panel can offer. `resolver.ts` orders the slots and applies the
+ * cap. Pure: no React, no server imports, no clock beyond the `now` passed in.
+ */
 import type {
   AgentPage,
   AgentPageContext,
@@ -14,8 +17,10 @@ import {
 } from "../investigate-prompts";
 import { isFailedBatchStatus } from "./page-mappers";
 
-// Chip ids must stay stable and carry no run/queue identity: dismissals are stored by id,
-// so `fresh-failure:run_abc` would scope the dismissal to a single run.
+/**
+ * Chip ids must stay stable and carry no run/queue identity: dismissals are stored
+ * by id, so `fresh-failure:run_abc` would scope the dismissal to a single run.
+ */
 const ID_PREFIX = "sp";
 
 function make(

apps/webapp/app/components/dashboard-agent/suggested-prompts/resolver.ts

@@ -1,5 +1,7 @@
-// Order: the promoted slot, then `PROMPT_SLOTS`, signal chips ahead of the page-kind
-// default within each slot.
+/**
+ * Turns a page context into the chips the panel shows: the promoted slot, then
+ * `PROMPT_SLOTS` in order, signal chips ahead of the page-kind default per slot.
+ */
 import {
   SUGGESTED_PROMPT_CAP,
   type AgentPageContext,

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

@@ -23,8 +23,10 @@ export function runWatchRecommendation(runFriendlyId: string): WatchSpec {
   });
 }
 
-// The recommendation must be a condition that isn't true yet: an already-true watch
-// one-shots instead of watching.
+/**
+ * The recommendation must be a condition that isn't true yet: an already-true watch
+ * one-shots instead of watching. Past the wait threshold that means the drain, not the SLA.
+ */
 export function queueWatchRecommendation(
   queueName: string,
   context?: { oldestWaitMs?: number | null }

apps/webapp/app/hooks/useAgentPageContext.ts

@@ -2,8 +2,10 @@ import { useLocation, useMatches } from "@remix-run/react";
 import type { AgentPageContext } from "~/components/dashboard-agent/page-context-types";
 import type { Handle } from "~/utils/handle";
 
-// The deepest `handle.agentPageContext` mapper that returns something wins; pages with no
-// mapper fall back to the path.
+/**
+ * The page context the dashboard agent sees. Routes opt in with `handle = { agentPageContext }`.
+ * The deepest mapper that returns something wins; pages with no mapper fall back to the path.
+ */
 export function useAgentPageContext(): AgentPageContext {
   const matches = useMatches();
   const location = useLocation();

apps/webapp/app/hooks/useThemeMode.ts

@@ -2,8 +2,10 @@ import { useEffect, useState } from "react";
 
 export type ThemeMode = "dark" | "light";
 
-// Resolved in an effect so server and hydration renders agree; `root.tsx` can flip
-// `data-theme` pre-paint.
+/**
+ * The active theme's mode, for colors that can't come from a CSS variable. Resolved in an
+ * effect so server and hydration renders agree; `root.tsx` can flip `data-theme` pre-paint.
+ */
 export function useThemeMode(): ThemeMode {
   const [mode, setMode] = useState<ThemeMode>("dark");
   useEffect(() => {

apps/webapp/app/presenters/v3/reports/ReportPresenter.server.ts

@@ -32,8 +32,10 @@ export function createReportCache(ttlMs: number = REPORT_CACHE_TTL_MS): ReportCa
 
 const defaultReportCache = createReportCache();
 
-// The cache only helps once a load has finished, so without this collapsing every caller of a
-// cold key hits the query-concurrency limit at once.
+/**
+ * Collapses concurrent identical requests into one computation: the cache only helps once a load has
+ * finished, so all callers of a cold key would otherwise hit the query-concurrency limit at once.
+ */
 const inFlight = new Map<string, Promise<ReportViewModel | undefined>>();
 
 export class ReportPresenter {

apps/webapp/app/presenters/v3/reports/health/health-core.ts

@@ -8,8 +8,10 @@ export type HealthInput = {
   windowMinutes: number;
   /** Provenance. Drives caveat text, not logic. */
   flowSource: "snapshot+runs" | "queue_metrics_v1";
-  // `normal` is the 7d baseline, omitted on the snapshot path. `availability: "unknown"` means the
-  // depth was not measured and `now` is a placeholder, not a confident 0.
+  /**
+   * `normal` is the 7d baseline, omitted on the snapshot path. `availability: "unknown"` means the
+   * depth was not measured and `now` is a placeholder, not a confident 0.
+   */
   pending: {
     now: number;
     normal?: number;
@@ -34,8 +36,10 @@ export type HealthInput = {
     runningSeries: number[];
     /** Epoch ms per `runningSeries` bucket. Absent means contiguity falls back to index adjacency. */
     runningBucketsMs?: number[];
-    // `runningSeries` is not gap-filled. Absent cadence means received buckets are assumed to
-    // spread evenly over the window.
+    /**
+     * Cadence and expected bucket count of `runningSeries`, which is not gap-filled. Absent means
+     * the cadence is unknown and received buckets are assumed to spread evenly over the window.
+     */
     sampling?: { bucketMinutes: number; expectedBuckets: number } | null;
     envLimit: number;
     throttledShare: number;

apps/webapp/app/presenters/v3/reports/health/health-data.ts

@@ -198,8 +198,10 @@ function envScalarQuery(): string {
 FROM env_metrics`;
 }
 
-// `argMax(max_queued, bucket_start)` is point-in-time depth, not a peak. Rows stop at 20, so
-// the share's denominator comes from `queueTotalsQuery`.
+/**
+ * `argMax(max_queued, bucket_start)` is a point-in-time depth, not a peak. These rows stop at 20, so
+ * the share's denominator comes from `queueTotalsQuery`.
+ */
 function queueWorstQuery(): string {
   return `SELECT
   queue AS name,
@@ -210,8 +212,10 @@ ORDER BY latest_queued DESC
 LIMIT 20`;
 }
 
-// `dlq_delta` is merged per queue then summed, never across queues. `total_queued` must be
-// computed here, not by summing the top-20 `queueWorstQuery` rows.
+/**
+ * `dlq_delta` must be merged per queue then summed, never merged across queues. `total_queued` must
+ * be computed here, not by summing the top-20 `queueWorstQuery` rows.
+ */
 function queueTotalsQuery(): string {
   return `SELECT sum(dlq) AS dlq_total, sum(latest_queued) AS total_queued
 FROM (
@@ -272,8 +276,10 @@ const EMPTY_EVIDENCE: HealthInput["flowEvidence"] = {
 
 type RunsContext = { liveScalar: Row; liveSeries: Row[]; baselineScalar: Row };
 
-// "unavailable" lets the next source down substitute. "failed" must make the flow verdict
-// unassessable, never fall through.
+/**
+ * "unavailable" is a recognized rollout state, so the next source down is a legitimate substitute.
+ * "failed" is anything else and must make the flow verdict unassessable, never fall through to it.
+ */
 export type FlowLoadResult =
   | { status: "ok"; data: FlowData }
   | { status: "unavailable" }
@@ -288,8 +294,10 @@ export interface FlowSource {
   ): Promise<FlowLoadResult>;
 }
 
-// The only failures the measured source may fall back on. Matched on error text because the
-// client collapses the error into a message. Codes: 60, 47, 81.
+/**
+ * The only failures the measured source may treat as a benign fallback. Matched on error text
+ * because the client collapses the error into a message. Codes: 60, 47, 81.
+ */
 const ROLLOUT_ERROR_PATTERNS = [
   /\bUNKNOWN_(?:TABLE|IDENTIFIER|DATABASE)\b/,
   /\bCode:\s*(?:60|47|81)\b/,
@@ -470,8 +478,10 @@ function buildQueueMetricsFlow(args: {
   };
 }
 
-// The `runs` backlog proxy is shape-only: it starts at 0 within the window and can't see backlog
-// that predates it.
+/**
+ * Fallback: live Redis depth plus a backlog proxy from `runs` (triggered minus finished). The proxy
+ * is shape-only: it starts at 0 within the window and can't see backlog that predates it.
+ */
 export const SnapshotFlowSource: FlowSource = {
   async loadFlow(env, _period, ctx, deps) {
     // Last-resort source, so a Redis failure must not break the report.