chore(webapp): trim comments to the essential why across the agent PR

Author: kathiekiwi

apps/webapp/app/components/code/StreamdownRenderer.test.ts

@@ -120,9 +120,8 @@ describe("retryImport", () => {
 
 describe("loadStreamdownRenderer", () => {
   it("resolves to a plain-text fallback when the chunk load keeps failing", async () => {
-    // The fallback path deliberately re-raises the original error as a process-level
-    // unhandled rejection (for StaleAssetRecovery). Swap in our own listener so that
-    // expected rejection is asserted on, not reported as a test-runner failure.
+    // The fallback path re-raises as an unhandled rejection (for StaleAssetRecovery); swap
+    // in our own listener so it's asserted on, not reported as a test-runner failure.
     const priorListeners = process.listeners("unhandledRejection");
     process.removeAllListeners("unhandledRejection");
     const caught = new Promise<Error>((resolve) => {

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

@@ -229,14 +229,11 @@ export function DashboardAgentChat({
 
   const messages = orderTranscript(rawMessages, orderRef.current);
 
-  // Bounded waits so a stalled turn says so instead of leaving the panel on a progress
-  // line forever. Independent of the SDK's own `error`: both drive the same live-error
-  // callout, but a deadline firing never touches the server turn or `status`.
+  // Independent of the SDK's own `error`: both drive the live-error callout, but a
+  // deadline firing never touches the server turn or `status`.
   const [deadlineError, setDeadlineError] = useState<TurnDeadlineError | null>(null);
-  // A retry can resend under `status: "submitted"` again — the same status the previous
-  // turn was already in when it fired, so the first-event effect wouldn't otherwise re-run.
-  // Bumped in `retry` to force it to. `dismissError` never bumps it: dismiss means "stop
-  // telling me", not "start a new wait".
+  // Bumped in `retry` to force the first-event effect to re-run when a resend reuses the
+  // same `status: "submitted"`. `dismissError` never bumps it.
   const [attempt, setAttempt] = useState(0);
   const firstEventDeadline = useRef(
     createKeyedDeadline<"submitted">({

apps/webapp/app/components/dashboard-agent/turn-deadlines.test.ts

@@ -121,12 +121,8 @@ describe("turnDeadlineErrorMessage", () => {
 });
 
 /**
- * These do NOT exercise `DashboardAgentChat` itself — this repo has no DOM/render test setup
- * (see `wake-poll.test.ts` for the same pattern: the extracted logic is what's tested). They
- * prove the extracted predicate (`activeToolPendingKey`) gates correctly, and that an explicit
- * `sync(null)` reset — which the component makes in `retry`/`dismissError` — is what lets a
- * deadline re-arm on a retry that reproduces the same condition; without that reset, `sync`
- * with an unchanged key is a no-op and the deadline never fires again.
+ * Tests the extracted predicate, not `DashboardAgentChat` (no DOM/render setup here). The
+ * component's explicit `sync(null)` reset is required to re-arm on retry: an unchanged key is a no-op.
  */
 describe("the tool-pending gate and retry re-arm, standing in for DashboardAgentChat", () => {
   beforeEach(() => {
@@ -158,9 +154,8 @@ describe("the tool-pending gate and retry re-arm, standing in for DashboardAgent
     await vi.advanceTimersByTimeAsync(120_000);
     expect(timeouts).toEqual(["get_run"]);
 
-    // Retry's explicit reset (DashboardAgentChat.tsx) before the retried turn's effect
-    // re-syncs the same key — without it, `sync("get_run")` while still `currentKey`
-    // would be a no-op and the deadline would never fire again.
+    // Retry's explicit reset (DashboardAgentChat.tsx): without it, re-syncing the same
+    // key while still `currentKey` would be a no-op and the deadline would never re-fire.
     deadline.sync(null);
     deadline.sync(activeToolPendingKey("streaming", inFlightToolName(dangling)));
 

apps/webapp/app/components/dashboard-agent/turn-deadlines.ts

@@ -1,11 +1,6 @@
 /**
- * Bounded waits during a live turn, so a stalled agent says so instead of leaving the
- * panel on a progress line forever. Two independent deadlines:
- *  - "first event": nothing has streamed back since the message was sent.
- *  - "tool pending": a single tool call has stayed pending too long.
- * Both drive the same live-error affordance the SDK's own errors use (`turn-error.ts`),
- * and both clear the moment the condition they're watching changes — including late
- * recovery after they've already fired.
+ * Bounded waits during a live turn: "first event" (nothing streamed yet) and "tool
+ * pending" (one tool call stuck). Both clear the moment the watched condition changes.
  */
 
 export const FIRST_EVENT_DEADLINE_MS = 45_000;
@@ -14,9 +9,8 @@ export const TOOL_PENDING_DEADLINE_MS = 120_000;
 export type TurnDeadlineError = { kind: "first-event" } | { kind: "tool-pending"; tool: string };
 
 /**
- * The tool-pending deadline's key: null unless a turn is actually live. A dangling
- * `input-available` part on an idle chat — a stopped turn, a reload of old history — is
- * not a pending call, and arming a timer for it would fire with nothing able to clear it.
+ * Null unless a turn is live. A dangling `input-available` part on an idle chat isn't a
+ * pending call, and arming a timer for it would fire with nothing able to clear it.
  */
 export function activeToolPendingKey(status: string, inFlightTool: string | null): string | null {
   const inFlight = status === "streaming" || status === "submitted";
@@ -51,9 +45,8 @@ export type KeyedDeadline<K extends string> = {
 };
 
 /**
- * Watches one condition across successive `sync` calls: the timer starts the moment `sync`
- * sees a key it wasn't already watching, fires `onTimeout` if that same key is still active
- * after `deadlineMs`, and clears (`onClear`) whenever the key changes away, fired or not.
+ * Timer starts when `sync` sees a new key, fires `onTimeout` if it's still active after
+ * `deadlineMs`, and clears (`onClear`) whenever the key changes away, fired or not.
  */
 export function createKeyedDeadline<K extends string>(
   options: KeyedDeadlineOptions<K>

apps/webapp/app/presenters/v3/QueueRetrievePresenter.server.ts

@@ -49,9 +49,8 @@ export type SlotHolderFacts = {
   consistency: SlotHolderConsistency;
 };
 
-// A run can only hold a slot before it reaches a final status. PENDING counts: Redis
-// membership is written at admission, before the Postgres status moves on. DELAYED runs
-// are not queued at all, so holding a slot is drift.
+// A run can only hold a slot before its final status. PENDING counts because Redis
+// membership is written at admission, ahead of the Postgres status; DELAYED never queues.
 const NON_HOLDING_STATUSES = new Set<TaskRunStatus>([
   "DELAYED",
   "CANCELED",

apps/webapp/app/routes/api.v1.dashboard-agent.alerts.ts

@@ -21,9 +21,8 @@ import { logger } from "~/services/logger.server";
 import { authenticateUatOrApiRequest } from "~/services/uatRoutePreamble.server";
 
 /**
- * `GET` lists this chat's project's watch alerts; `POST` subscribes the user's email. Only the
- * agent's delegated user-actor token is accepted. An environment-pinned token fixes the
- * environment; an org-wide one lets the request name any environment in its org.
+ * `GET` lists this chat's watch alerts, `POST` subscribes the user's email. User-actor
+ * token only; org-wide tokens let the request name any environment in the org.
  */
 
 const ListQuerySchema = z.object({

apps/webapp/app/routes/api.v1.dashboard-agent.watches.ts

@@ -13,10 +13,8 @@ import {
 import { authenticateUatOrApiRequest } from "~/services/uatRoutePreamble.server";
 
 /**
- * Programmatic watch creation (MCP). Only the agent's delegated user-actor token is accepted.
- * An environment-pinned token fixes the environment; an org-wide one lets the body name any
- * environment in its org, re-authorized against the user's membership, and falls back to the
- * token's own environment when the body names none. Never the chat's stored context.
+ * Programmatic watch creation (MCP). User-actor token only; org-wide tokens let the body
+ * name any environment in the org, re-authorized against membership. Never the chat's stored context.
  */
 
 const BodySchema = z.object({

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.dashboard-agent.ts

@@ -406,13 +406,8 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
           );
         }
       } catch (error) {
-        // Both starts are one create-session-and-trigger round trip, so a rejection usually
-        // means no handover was dispatched and no message was sent: a session the call did
-        // create in spite of the error idles out having done nothing. The `withTimeout` above
-        // is the exception — its trigger can still land after we've given up and soft-deleted
-        // the chat below, orphaning a live session on a chat the user never sees again; the
-        // run is otherwise harmless and the `in` proxy's chat lookup treats it as missing.
-        // Swallowed so the start's own error is what surfaces and gets logged.
+        // A rejection usually means nothing was dispatched, except `withTimeout`'s trigger
+        // can still land after the soft-delete below; the `in` proxy just treats it as missing.
         await softDeleteChat(dashboardAgentDb, {
           chatId,
           userId,

apps/webapp/app/services/dashboardAgentTokenScope.ts

@@ -1,13 +1,6 @@
 /**
- * Which environment a dashboard-agent turn may act in, from the token's claims alone.
- *
- * An org-wide token draws the boundary at its organization: the request may name any
- * environment inside it, and the token's own environment is only the default when it names
- * none. `organizationId` comes back with the target, for the caller to check the resolved
- * environment against — a request id is never authorization on its own.
- *
- * A token with no organization is the legacy environment-pinned form: its one environment,
- * which the request can echo but never replace.
+ * Org-wide tokens allow any environment in their org (default: the token's own); legacy
+ * tokens are pinned to one. `organizationId` comes back so the caller still checks it.
  */
 
 export type AgentTokenScope =

apps/webapp/app/services/dashboardAgentWatchRunChecks.ts

@@ -30,10 +30,8 @@ const FINAL_STATUSES = new Set([
 ]);
 
 /**
- * Statuses whose `queuedAt` is a leftover from the first enqueue, since resume/retry
- * re-enqueues don't restamp it, so a wait computed from it isn't this attempt's. Exported
- * so other run-facing readers can derive the same reliability signal from the raw status
- * instead of re-deriving it.
+ * Statuses whose `queuedAt` is a leftover from the first enqueue (re-enqueues don't restamp
+ * it). Exported so other run-facing readers can derive the same reliability signal.
  */
 export const STALE_QUEUED_AT_STATUSES = new Set([
   "WAITING_TO_RESUME",