feat(concurrency): configurable cooldown + adaptive-headroom auto-reduce banner

Consumes the backend's concurrency-fixes (commit 2d27666) — additive to
[email protected], NO version bump. ConcurrencyStatusEntry gains
cooldownMs / autoReduced / autoReducedFrom? / notice?; new
ConcurrencyCooldownResponse / SetConcurrencyCooldownRequest + GET/PUT
/concurrency/cooldown/:providerId.

FE:
- Pure core (logic/view-model.ts): DEFAULT_COOLDOWN_MS; parseCooldownInput
  (non-negative int — 0 is valid, unlike the limit); normalizeCooldown;
  cooldownLabel ("350ms"/"1.2s"/"0ms (off)"); viewConcurrencyStatus extended
  (cooldown + autoReduce fields; auto-reduce → warning badge, not busy);
  viewAutoReduce/autoReduceNotices (banner view — prefers backend notice,
  synthesizes a fallback); summarizeStatus "N auto-reduced" fragment;
  normalizeConcurrencyStatus coerces new fields (immutable readonly build;
  autoReducedFrom/notice only when autoReduced===true); normalizeConcurrencyCooldown.
- Types (logic/types.ts): re-export the 2 new contract types +
  ConcurrencyCooldownResult + Get/SaveConcurrencyCooldown ports.
- UI: ConcurrencyCooldownRow.svelte (inline-edit cooldown + Save → PUT, seeded
  via the ChatLimitField pattern); AutoReduceBanner.svelte (dismissible banner —
  backend notice + "Was N, now M." + "Restore to N"); ConcurrencyView renders
  the cooldown per status card + the banner section. The banner persists while
  autoReduced===true, is dismissible, and clears automatically once a poll shows
  autoReduced===false after a restore PUT.
- Store (store.svelte.ts): getConcurrencyCooldown + setConcurrencyCooldown
  (surface 400/404/503 as ok:false; normalize at the seam) + interface decls.
- App.svelte: saveConcurrencyCooldown adapter → ConcurrencyView.
- Tests: +47 (view-model cooldown/auto-reduce/normalizers; component banner
  render, cooldown PUT, restore clears banner, dismiss; store cooldown GET/PUT).

Re-synced the file: dep (bun install) + re-mirrored .dispatch/transport-contract.
reference.md. typecheck 0/0, 1048 tests green (run twice), biome clean, build OK.

Worktree env: an untracked dispatch-backend → backend symlink was created in the
worktree parent so the canonical file:../dispatch-backend/... paths resolve
(NOT committed — per the §2d/§2j worktree convention).

1 files changed, 193 insertions, 18 deletions

diff --git a/src/features/concurrency/logic/view-model.ts b/src/features/concurrency/logic/view-model.ts
index 7a4fe0e..e05423b 100644
--- a/src/features/concurrency/logic/view-model.ts
+++ b/src/features/concurrency/logic/view-model.ts
@@ -1,12 +1,16 @@
-import type { ConcurrencyStatusEntry } from "@dispatch/transport-contract";
+import type {
+  ConcurrencyCooldownResponse,
+  ConcurrencyStatusEntry,
+} from "@dispatch/transport-contract";
 import type { ConcurrencyLimitEntry } from "./types";
 
 /**
  * Pure view-models for the concurrency feature — zero DOM, zero effects, zero
  * Svelte. Maps backend `ConcurrencyLimitEntry` / `ConcurrencyStatusEntry` to
- * display shapes (badges, "2/4" in-flight labels, pause countdowns, summaries),
- * holds the limit-input parsing, and the network-seam normalizers the composition
- * root coerces the untyped JSON with.
+ * display shapes (badges, "2/4" in-flight labels, pause countdowns, cooldown
+ * labels, auto-reduce banners, summaries), holds the limit/cooldown-input
+ * parsing, and the network-seam normalizers the composition root coerces the
+ * untyped JSON with.
  */
 
 export type Badge = "success" | "warning" | "error" | "neutral";
@@ -36,6 +40,29 @@ export interface ConcurrencyStatusView {
   readonly badge: Badge;
   /** True when paused or at capacity (show a spinner). */
   readonly busy: boolean;
+  /** Per-slot release cooldown in ms (defensive default 350 on garbage). */
+  readonly cooldownMs: number;
+  /** "350ms" / "1.2s" / "0ms (off)" — display label for the cooldown. */
+  readonly cooldownLabel: string;
+  /** Whether the limit was auto-reduced by a 429 (one-way; user restores manually). */
+  readonly autoReduced: boolean;
+  /** The original limit before auto-reduction; null when not auto-reduced. */
+  readonly autoReducedFrom: number | null;
+}
+
+/**
+ * A view-model for the auto-reduce banner — derived from a status entry whose
+ * `autoReduced` is `true`. `message` is the backend's `notice` when present, else
+ * a synthesized fallback. `viewAutoReduce` returns this (or null) so the banner
+ * section renders without reaching into the raw entry.
+ */
+export interface AutoReduceNotice {
+  readonly providerId: string;
+  readonly message: string;
+  /** The original limit before reduction — the value "Restore to N" PUTs. */
+  readonly fromLimit: number;
+  /** The current (reduced) limit. */
+  readonly currentLimit: number;
 }
 
 // ── Limit input parsing ───────────────────────────────────────────────────────
@@ -63,6 +90,53 @@ export function normalizeLimit(value: unknown): number {
   return int >= 1 ? int : 1;
 }
 
+// ── Cooldown input parsing ────────────────────────────────────────────────────
+//
+// The per-slot release cooldown (ms) is a NON-NEGATIVE integer (0 = no cooldown,
+// instant re-admission) — unlike the limit, 0 is a VALID value. The default is
+// 350ms (the backend's server default when a limit is set but no explicit
+// cooldown was configured). It is configurable + persisted per provider via
+// `PUT /concurrency/cooldown/:providerId`.
+
+/** The server's default cooldown (ms) — used when none is explicitly set. */
+export const DEFAULT_COOLDOWN_MS = 350;
+
+/**
+ * Parse a raw cooldown input into a non-negative integer, or `null` when it is
+ * not valid. Accepts "0" → 0, "350" → 350; rejects "-1", "4.5", "", "abc".
+ * Drives the cooldown Save button's disabled state so an invalid value never
+ * reaches the backend (the backend 400s a non-negative-integer body).
+ */
+export function parseCooldownInput(value: string): number | null {
+  const trimmed = value.trim();
+  if (trimmed === "" || !/^[0-9]+$/.test(trimmed)) return null;
+  const n = Number.parseInt(trimmed, 10);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+/**
+ * Coerce an untrusted cooldown value into a non-negative integer (default
+ * {@link DEFAULT_COOLDOWN_MS}). Used when normalizing backend responses so a
+ * malformed `cooldownMs` can never be negative/non-finite.
+ */
+export function normalizeCooldown(value: unknown): number {
+  const n = typeof value === "number" && Number.isFinite(value) ? value : DEFAULT_COOLDOWN_MS;
+  const int = Math.floor(n);
+  return int >= 0 ? int : DEFAULT_COOLDOWN_MS;
+}
+
+/**
+ * Format a cooldown (ms) as a short display label:
+ * 0 → "0ms (off)" · <1000 → "350ms" · ≥1000 → "1.2s" (trailing ".0" trimmed).
+ */
+export function cooldownLabel(ms: number): string {
+  if (ms <= 0) return "0ms (off)";
+  if (ms < 1000) return `${ms}ms`;
+  const secs = ms / 1000;
+  const fixed = secs.toFixed(1);
+  return `${fixed.endsWith(".0") ? fixed.slice(0, -2) : fixed}s`;
+}
+
 // ── Provider options (the Add-form dropdown) ───────────────────────────────────
 //
 // A concurrency `providerId` is the credential name that prefixes a model name
@@ -140,6 +214,10 @@ export function pauseLabel(
  * Build a display view for a status entry. `now` is injectable for tests
  * (defaults to `Date.now()`); the composition-root component passes nothing in
  * production (it recomputes on each poll).
+ *
+ * `autoReduced` does NOT flip `busy` (a reduced limit still admits agents; it is
+ * a degraded-but-active state surfaced via the banner, not a spinner) — it only
+ * nudges the badge to `warning` so the row signals attention.
  */
 export function viewConcurrencyStatus(
   entry: ConcurrencyStatusEntry,
@@ -149,12 +227,21 @@ export function viewConcurrencyStatus(
   const inFlight = clampCount(entry.inFlight);
   const queued = clampCount(entry.queued);
   const paused = entry.paused === true;
+  const autoReduced = entry.autoReduced === true;
   const atCapacity = inFlight >= limit;
   let badge: Badge;
   if (paused) badge = "warning";
+  else if (autoReduced) badge = "warning";
   else if (atCapacity && queued > 0) badge = "warning";
   else if (inFlight > 0) badge = "success";
   else badge = "neutral";
+  const cooldownMs = normalizeCooldown(entry.cooldownMs);
+  const autoReducedFrom =
+    autoReduced &&
+    typeof entry.autoReducedFrom === "number" &&
+    Number.isFinite(entry.autoReducedFrom)
+      ? normalizeLimit(entry.autoReducedFrom)
+      : null;
   return {
     providerId: entry.providerId,
     limit,
@@ -166,9 +253,53 @@ export function viewConcurrencyStatus(
     pausedLabel: pauseLabel(paused, entry.pausedUntil, now),
     badge,
     busy: paused || (atCapacity && queued > 0),
+    cooldownMs,
+    cooldownLabel: cooldownLabel(cooldownMs),
+    autoReduced,
+    autoReducedFrom,
   };
 }
 
+/**
+ * The auto-reduce banner view for a status entry, or `null` when it is not
+ * auto-reduced. `message` prefers the backend's `notice` (verbatim, when present
+ * + non-empty); otherwise a synthesized fallback is built from
+ * `autoReducedFrom` → `limit`. `fromLimit` is the value "Restore to N" PUTs back.
+ */
+export function viewAutoReduce(entry: ConcurrencyStatusEntry): AutoReduceNotice | null {
+  if (entry.autoReduced !== true) return null;
+  const currentLimit = normalizeLimit(entry.limit);
+  const fromLimit =
+    typeof entry.autoReducedFrom === "number" && Number.isFinite(entry.autoReducedFrom)
+      ? normalizeLimit(entry.autoReducedFrom)
+      : currentLimit + 1;
+  const notice =
+    typeof entry.notice === "string" && entry.notice.length > 0
+      ? entry.notice
+      : `Concurrency limit auto-reduced to ${currentLimit} after a 429 — restore manually when ready.`;
+  return {
+    providerId: entry.providerId,
+    message: notice,
+    fromLimit,
+    currentLimit,
+  };
+}
+
+/**
+ * All auto-reduce banners across a status list (one per auto-reduced provider),
+ * in input order. Empty when none are auto-reduced.
+ */
+export function autoReduceNotices(
+  entries: readonly ConcurrencyStatusEntry[],
+): readonly AutoReduceNotice[] {
+  const out: AutoReduceNotice[] = [];
+  for (const e of entries) {
+    const n = viewAutoReduce(e);
+    if (n !== null) out.push(n);
+  }
+  return out;
+}
+
 export function viewConcurrencyStatuses(
   entries: readonly ConcurrencyStatusEntry[],
   now: number = Date.now(),
@@ -197,8 +328,8 @@ export function summarizeLimits(limits: readonly ConcurrencyLimitEntry[]): strin
 
 /**
  * A one-line summary of the live status, e.g.
- * "2 providers · 6/10 in flight · 1 queued · 1 paused". Only the queued / paused
- * fragments appear when non-zero.
+ * "2 providers · 6/10 in flight · 1 queued · 1 paused · 1 auto-reduced". Only the
+ * queued / paused / auto-reduced fragments appear when non-zero.
  */
 export function summarizeStatus(
   providers: readonly ConcurrencyStatusEntry[],
@@ -209,12 +340,14 @@ export function summarizeStatus(
   let limitTotal = 0;
   let queued = 0;
   let paused = 0;
+  let autoReduced = 0;
   for (const p of providers) {
     const limit = normalizeLimit(p.limit);
     inFlight += clampCount(p.inFlight);
     limitTotal += limit;
     queued += clampCount(p.queued);
     if (p.paused === true) paused += 1;
+    if (p.autoReduced === true) autoReduced += 1;
   }
   const parts: string[] = [];
   parts.push(
@@ -223,6 +356,7 @@ export function summarizeStatus(
   );
   if (queued > 0) parts.push(`${queued} queued`);
   if (paused > 0) parts.push(`${paused} paused`);
+  if (autoReduced > 0) parts.push(`${autoReduced} auto-reduced`);
   // Touch `now` so the summary recomputes alongside the per-row pause countdown.
   void now;
   return parts.join(" · ");
@@ -274,7 +408,9 @@ export function normalizeConcurrencyLimit(data: unknown): ConcurrencyLimitEntry
 /**
  * Coerce an untrusted `GET /concurrency/status` body into a typed status list.
  * `pausedUntil` is included only when it is a finite number (it is absent when
- * not paused).
+ * not paused). `cooldownMs` (default 350) + `autoReduced` are always coerced;
+ * `autoReducedFrom` + `notice` are included only when `autoReduced` is true (and
+ * well-formed), mirroring the backend's "present only when auto-reduced" contract.
  */
 export function normalizeConcurrencyStatus(data: unknown): readonly ConcurrencyStatusEntry[] {
   if (!isRecord(data) || !Array.isArray(data.providers)) return [];
@@ -282,18 +418,57 @@ export function normalizeConcurrencyStatus(data: unknown): readonly ConcurrencyS
   return providers
     .filter((r): r is Record<string, unknown> => isRecord(r))
     .map((r): ConcurrencyStatusEntry => {
-      const base = {
-        providerId: asString(r.providerId) ?? "",
-        limit: normalizeLimit(r.limit),
-        inFlight: clampCount(r.inFlight),
-        queued: clampCount(r.queued),
-        paused: r.paused === true,
+      const providerId = asString(r.providerId) ?? "";
+      const limit = normalizeLimit(r.limit);
+      const inFlight = clampCount(r.inFlight);
+      const queued = clampCount(r.queued);
+      const paused = r.paused === true;
+      const cooldownMs = normalizeCooldown(r.cooldownMs);
+      const autoReduced = r.autoReduced === true;
+      // Build immutably (the contract fields are readonly): start with the always-
+      // present fields, then layer the optional `pausedUntil` (finite number only)
+      // + the auto-reduce-only `autoReducedFrom`/`notice` (present only when true).
+      let entry: ConcurrencyStatusEntry = {
+        providerId,
+        limit,
+        inFlight,
+        queued,
+        paused,
+        cooldownMs,
+        autoReduced,
       };
-      const pausedUntil =
-        typeof r.pausedUntil === "number" && Number.isFinite(r.pausedUntil)
-          ? r.pausedUntil
-          : undefined;
-      return pausedUntil !== undefined ? { ...base, pausedUntil } : base;
+      if (typeof r.pausedUntil === "number" && Number.isFinite(r.pausedUntil)) {
+        entry = { ...entry, pausedUntil: r.pausedUntil };
+      }
+      if (autoReduced) {
+        // Accumulate the auto-reduce-only optionals into a plain record (the
+        // contract fields are readonly, so we can't mutate a typed partial —
+        // collect then spread into a fresh entry).
+        const patch: { autoReducedFrom?: number; notice?: string } = {};
+        if (typeof r.autoReducedFrom === "number" && Number.isFinite(r.autoReducedFrom)) {
+          patch.autoReducedFrom = normalizeLimit(r.autoReducedFrom);
+        }
+        if (typeof r.notice === "string" && r.notice.length > 0) {
+          patch.notice = r.notice;
+        }
+        if (patch.autoReducedFrom !== undefined || patch.notice !== undefined) {
+          entry = { ...entry, ...patch };
+        }
+      }
+      return entry;
     })
     .filter((r) => r.providerId !== "");
 }
+
+/**
+ * Coerce an untrusted `GET`/`PUT /concurrency/cooldown/:providerId` body into a
+ * typed cooldown response, or `null` when it is malformed (missing/malformed
+ * `providerId` or `cooldownMs`). The composition root surfaces a 404/400/503 as
+ * `ok: false` separately; this only defends the success body.
+ */
+export function normalizeConcurrencyCooldown(data: unknown): ConcurrencyCooldownResponse | null {
+  if (!isRecord(data)) return null;
+  const providerId = asString(data.providerId);
+  if (providerId === null) return null;
+  return { providerId, cooldownMs: normalizeCooldown(data.cooldownMs) };
+}