From e5261401feb3c39ba2a9b4ddd6839072b03f6176 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dominik=20Sch=C3=B6n?= Date: Fri, 30 Oct 2026 16:58:17 +0000 Subject: [PATCH] feat(runbook): Notfall-Runbook + Inline-Hints an Alarm-Flaechen (CHO tower-notfall-runbook) DATEI 1: public/runbook/runbook-tower-notfall.md (statisch, Anker #deadman/#spool/#deadletter/#health) DATEI 2: /runbook-Route (Server Component, Mini-MD-Renderer, CSP-konform, force-static) DATEI 3: runbookHints.ts (LAMP_HINTS/buildView/renderHintHtml 1:1 aus runbook_hints.py) + RunbookHint.tsx eingebunden an 4 Alarm-Flaechen: - EscalationHistory (Deadman, Szenario A) - TaskBrowser Spool-Tab (Szenario B) + Dead-Letter-Tab (B3) - TaskBrowser/OpsPanels Degraded/Error (Health, Szenario C) Keine Ampelfarben/Deadman-Logik/Degraded-Banner/Datenpfade angefasst (CHO-NICHT ANFASSEN erfuellt). Build verifiziert: tsc --noEmit clean, next build gruen (/runbook static). --- app/components/fleet/EscalationHistory.tsx | 3 + app/components/fleet/OpsPanels.tsx | 3 + app/components/fleet/RunbookHint.tsx | 39 +++++ app/components/fleet/TaskBrowser.tsx | 17 +++ app/lib/fleet/runbookHints.ts | 161 +++++++++++++++++++++ app/runbook/page.tsx | 100 +++++++++++++ public/runbook/runbook-tower-notfall.md | 131 +++++++++++++++++ 7 files changed, 454 insertions(+) create mode 100644 app/components/fleet/RunbookHint.tsx create mode 100644 app/lib/fleet/runbookHints.ts create mode 100644 app/runbook/page.tsx create mode 100644 public/runbook/runbook-tower-notfall.md diff --git a/app/components/fleet/EscalationHistory.tsx b/app/components/fleet/EscalationHistory.tsx index 6c676a8..df630af 100644 --- a/app/components/fleet/EscalationHistory.tsx +++ b/app/components/fleet/EscalationHistory.tsx @@ -1,6 +1,8 @@ "use client" import { useEffect, useState } from "react" +import RunbookHint from "./RunbookHint" +import { hintByKey } from "@/app/lib/fleet/runbookHints" /** * EscalationHistory — Kernfeature 4: HITL-/Escalation-Historie. @@ -93,6 +95,7 @@ export default function EscalationHistory() {

HITL-Alarme (type=escalation)

+ {esc.length === 0 ? (

Keine Alarme — alles ruhig diff --git a/app/components/fleet/OpsPanels.tsx b/app/components/fleet/OpsPanels.tsx index 7ec70ed..fad1d0d 100644 --- a/app/components/fleet/OpsPanels.tsx +++ b/app/components/fleet/OpsPanels.tsx @@ -14,6 +14,8 @@ * Keine Mutation, keine Netz-Grants, 30 s Auto-Refresh. */ import { useCallback, useEffect, useState } from 'react' +import RunbookHint from './RunbookHint' +import { hintByKey } from '@/app/lib/fleet/runbookHints' const REFRESH_MS = 30_000 @@ -190,6 +192,7 @@ export default function OpsPanels() { Datenquelle eingeschraenkt: {err}

)} + {err && } {tab === 'nar' && ( diff --git a/app/components/fleet/RunbookHint.tsx b/app/components/fleet/RunbookHint.tsx new file mode 100644 index 0000000..c877481 --- /dev/null +++ b/app/components/fleet/RunbookHint.tsx @@ -0,0 +1,39 @@ +"use client" + +/** + * RunbookHint.tsx — statischer Inline-Hint an den Alarm-Flaechen des Towers. + * Portierung der render_hint_html()-Semantik als React-Komponente + * (Karte tower-notfall-runbook, DATEI 3). Rein statisch: kein Polling, + * kein Egress, keine Secrets — nur interner Deep-Link auf /runbook#. + */ + +import type { LampHint } from "@/app/lib/fleet/runbookHints" + +export default function RunbookHint({ hint }: { hint: LampHint }) { + return ( +
+ + Notfall {hint.scenario} — {hint.title} + +
    + {hint.kurzschritte.map((s: string) => ( +
  1. {s}
  2. + ))} +
+
+ Eskalation: {hint.eskalation} +
+ + Vollständiges Runbook → + +
+ ) +} diff --git a/app/components/fleet/TaskBrowser.tsx b/app/components/fleet/TaskBrowser.tsx index e43dc73..3b82d6b 100644 --- a/app/components/fleet/TaskBrowser.tsx +++ b/app/components/fleet/TaskBrowser.tsx @@ -13,6 +13,8 @@ * Polt 30 s; degradierte Quelle -> Banner statt Leeranzeige. */ import { useCallback, useEffect, useRef, useState } from "react" +import RunbookHint from "./RunbookHint" +import { hintByKey } from "@/app/lib/fleet/runbookHints" type TaskEnvelope = { task_id: string @@ -253,11 +255,26 @@ export default function TaskBrowser() { Tasks nicht ladbar: {loadError} )} + {tab === "spool" && ( +
+ +
+ )} + {tab === "dead-letter" && ( +
+ +
+ )} {data?.degraded && (
DEGRADED: {data.degraded_reason || "Quelle gestoert"} — Anzeige evtl. unvollstaendig.
)} + {(loadError || data?.degraded) && ( +
+ +
+ )}
{tab === "alarm" ? ( diff --git a/app/lib/fleet/runbookHints.ts b/app/lib/fleet/runbookHints.ts new file mode 100644 index 0000000..f63443b --- /dev/null +++ b/app/lib/fleet/runbookHints.ts @@ -0,0 +1,161 @@ +/** + * runbookHints.ts — 1:1-Portierung von /sandbox/fleet-change-orders/ + * tower-notfall-runbook/runbook_hints.py (Karte tower-notfall-runbook, devops). + * + * Zweck: Kurzschritte + Eskalationskontakt fuer den Owner direkt an den + * Alarm-Ampeln des Towers (10.0.30.213, tcp/8099) als kontextueller + * Inline-Hint mit Deep-Link auf das Notfall-Runbook (/runbook#). + * + * Rein statisch — KEINE Datenquelle, KEIN Polling, KEIN Egress, KEINE + * Secrets. LAMP_HINTS + buildView() + renderHintHtml() entsprechen + * LAMP_HINTS + build_view() + render_hint_html() der Referenz 1:1. + */ + +export const RUNBOOK_URL = "/runbook" + +export type LampHint = { + key: "deadman" | "spool" | "health" | "deadletter" + component: string + badge_id: string | null + anchor: string + scenario: string + title: string + core: boolean + kurzschritte: string[] + eskalation: string +} + +// Reihenfolge = Anzeige-Reihenfolge im Tower-Header/Panel. +// core=true -> Pflicht-Ampel laut Karte (Deadman-Blockade, Spool-Stau, Panel-Ausfall). +export const LAMP_HINTS: LampHint[] = [ + { + key: "deadman", + component: "Deadman-Status", + badge_id: "dm-badge", + anchor: "#deadman", + scenario: "A", + title: "Deadman-Blockade", + core: true, + kurzschritte: [ + "Owner-Queue oeffnen: blockierenden Task (ID, Typ, Alter) an der Deadman-Ampel ablesen.", + "Task in der Queue entscheiden (Abnahme/Review/NAR) oder mit reply_to + Kommentar zurueckgeben.", + "Deadman-Ampel auf 'progress' pruefen (Auto-Refresh 30 s).", + ], + eskalation: + "Bleibt 'blocked' > 5400 s oder ist der Task unklar: Owner ueber die Owner-Queue informieren (Grund + Task-ID nennen).", + }, + { + key: "spool", + component: "Spool-Aging (Reife)", + badge_id: "sp-badge", + anchor: "#spool", + scenario: "B", + title: "Spool-Stau", + core: true, + kurzschritte: [ + "Spool-Aging: aeltesten roten Envelope (> 5400 s) + Empfaenger ablesen.", + "Empfaenger gruen: Task an denselben Empfaenger erneut submitten (reply_to setzen).", + "Empfaenger rot: zuerst Szenario A/C loesen; Failed-Tasks ueber die Dead-Letter-Ansicht (#deadletter) pruefen.", + ], + eskalation: + "Envelope > 5400 s ohne roten Empfaenger (Ursache unklar): an tower-owner ueber den CISO-Kanal melden (Envelope-IDs); ab 2 betroffenen Agents zusaetzlich Owner informieren.", + }, + { + key: "health", + component: "Health-Ampel / Panel", + badge_id: null, + anchor: "#health", + scenario: "C", + title: "Panel-Ausfall", + core: true, + kurzschritte: [ + "/healthz pruefen: 200 = Server lebt, Problem liegt bei Datenquelle/UI.", + "/api/status + Degraded-Banner: Quelle down = Degraded (60 s-Cache laeuft weiter), KEIN Totalausfall.", + "Kein 200 / Verbindung abgelehnt = Totalausfall: Neustart/Deploy nur ueber Aenderungsauftrag, nicht selbst am Host.", + ], + eskalation: + "healthz-Ausfall oder Deploy-Bedarf: sofort P1 an tower-owner ueber den CISO-Kanal; parallel Owner informieren (ohne Panel ist die Lage nur ueber die Agenten-Boards sichtbar).", + }, + { + key: "deadletter", + component: "Dead-Letter-Ansicht", + badge_id: null, + anchor: "#deadletter", + scenario: "B3", + title: "Verlorene Tasks", + core: false, + kurzschritte: [ + "Dead-Letter: failed-Tasks (7 Tage) mit from->to + Alter pruefen.", + "Wiederholbar: erneut submitten (reply_to); unloesbar: Task mit Grund neu aufsetzen, nicht still verwerfen.", + ], + eskalation: + "Gehaeufte Failed-Tasks eines Empfaengers: Empfaenger-Health pruefen (#health), dann wie Szenario B eskalieren.", + }, +] + +/** Hint per key (statisch, wirft bei unbekanntem key). */ +export function hintByKey(key: LampHint["key"]): LampHint { + const h = LAMP_HINTS.find((x) => x.key === key) + if (!h) throw new Error(`unknown runbook hint: ${key}`) + return h +} + +export type HintView = { + key: string + component: string + badge_id: string | null + scenario: string + title: string + core: boolean + anchor: string + url: string + kurzschritte: string[] + eskalation: string + html: string +} + +/** Statische Hint-Ansicht (JSON-faehig) — entspricht build_view(). */ +export function buildView(now: string | null = null, source = "static") { + const hints: HintView[] = LAMP_HINTS.map((h) => ({ + key: h.key, + component: h.component, + badge_id: h.badge_id, + scenario: h.scenario, + title: h.title, + core: h.core, + anchor: h.anchor, + url: RUNBOOK_URL + h.anchor, + kurzschritte: [...h.kurzschritte], + eskalation: h.eskalation, + html: renderHintHtml(h), + })) + return { + generated_at: now, + source, + runbook_url: RUNBOOK_URL, + refresh_seconds: 0, // statisch + hint_count: hints.length, + core_count: hints.filter((h) => h.core).length, + hints, + } +} + +function escapeHtml(s: string): string { + return s + .replace(/&/g, "&") + .replace(//g, ">") + .replace(/"/g, """) +} + +/** Kompakter Inline-Hint als HTML-String (rein Text + interner Link). */ +export function renderHintHtml(h: LampHint): string { + const esc = escapeHtml + const stepLis = h.kurzschritte.map((s) => `
  • ${esc(s)}
  • `).join("") + return `
    ` + + `Notfall ${esc(h.scenario)} — ${esc(h.title)}` + + `
      ${stepLis}
    ` + + `
    Eskalation: ${esc(h.eskalation)}
    ` + + `Vollstaendiges Runbook →` + + `
    ` +} diff --git a/app/runbook/page.tsx b/app/runbook/page.tsx new file mode 100644 index 0000000..7cdea19 --- /dev/null +++ b/app/runbook/page.tsx @@ -0,0 +1,100 @@ +/** + * /runbook — Statische Notfall-Runbook-Seite des Towers (Server Component). + * Karte tower-notfall-runbook, DATEI 2: rendert die Runbook-Datei als + * schlichte Markdown-/Textseite — rein statisch, kein Script, keine + * externen URLs, keine Secrets. Anker (#deadman etc.) kommen aus der MD. + */ + +import { readFile } from "node:fs/promises" +import path from "node:path" + +export const dynamic = "force-static" +export const metadata = { title: "Notfall-Runbook Tower" } + +const MD_PATH = path.join(process.cwd(), "public", "runbook", "runbook-tower-notfall.md") + +/** Minimaler Markdown->HTML-Renderer (keine Dep, kein Script-Output). */ +function renderMarkdown(md: string): string { + const esc = (s: string) => + s.replace(/&/g, "&").replace(//g, ">").replace(/"/g, """) + const lines = md.split(/\r?\n/) + const out: string[] = [] + let inCode = false + let listOpen = false + const closeList = () => { + if (listOpen) { + out.push("") + listOpen = false + } + } + for (const raw of lines) { + const line = raw + // Bekannt-sichere Anker-Tags aus der Runbook-MD unverändert durchreichen + // (Deep-Link-Ziele #deadman/#spool/#deadletter/#health). + const anchor = line.match(/^<\/a>$/) + if (anchor && !inCode) { + out.push(``) + continue + } + if (/^```/.test(line)) { + closeList() + out.push(inCode ? "" : '
    ')
    +      inCode = !inCode
    +      continue
    +    }
    +    if (inCode) {
    +      out.push(esc(line))
    +      continue
    +    }
    +    const h = line.match(/^(#{1,4})\s+(.*)$/)
    +    if (h) {
    +      closeList()
    +      const lvl = Math.min(h[1].length + 1, 5) // h1->h2 (Seitenh1 ist der Titel)
    +      out.push(`${esc(h[2])}`)
    +      continue
    +    }
    +    if (/^\s*[-*]\s+/.test(line)) {
    +      if (!listOpen) {
    +        out.push('
      ') + listOpen = true + } + out.push(`
    • ${esc(line.replace(/^\s*[-*]\s+/, ""))}
    • `) + continue + } + if (line.trim() === "") { + closeList() + continue + } + out.push(`

      ${esc(line)}

      `) + } + closeList() + return out.join("\n") +} + +export default async function RunbookPage() { + let md = "" + try { + md = await readFile(MD_PATH, "utf8") + } catch { + md = "# Runbook nicht gefunden\n\nDie Runbook-Datei ist im Image nicht vorhanden (public/runbook/runbook-tower-notfall.md)." + } + const html = renderMarkdown(md) + return ( +
      +

      + Notfall-Runbook Tower +

      +

      + Statisch · Deep-Link-Ziele der Alarm-Ampeln:{" "} + #deadman ·{" "} + #spool ·{" "} + #deadletter ·{" "} + #health +

      +
      +
      + ) +} diff --git a/public/runbook/runbook-tower-notfall.md b/public/runbook/runbook-tower-notfall.md new file mode 100644 index 0000000..67d1fe5 --- /dev/null +++ b/public/runbook/runbook-tower-notfall.md @@ -0,0 +1,131 @@ +# Notfall-Runbook Tower (Fleet vs-fleet-rebuild) + +Stand: 2026-10-30 · Autor: devops · Karte: tower-notfall-runbook +Geltung: Owner am Tower-Panel (10.0.30.213, tcp/8099). Ziel: in <5 min +entscheiden und handeln, ohne zu raetseln. + +## Anker (Deep-Link-Ziele fuer die Alarm-Ampeln) +Die Inline-Hints/Links an den Tower-Ampeln springen genau auf einen dieser +Anker (nur interne Links, kein aktiver Inhalt/Script, keine Secrets): +- **#deadman** -> Deadman-Status / Szenario A +- **#spool** -> Spool-Aging / Szenario B +- **#deadletter** -> Dead-Letter-Ansicht / Szenario B (Punkt 3) +- **#health** -> Health-Ampel / Degraded-Banner / Szenario C +Diese Datei ist reiner Text (Markdown); die Hints rendern daraus nur +Ueberschrift + Link, nichts Ausfuehrbares. + +## 0. Grundlagen (immer zuerst lesen) +- Heartbeat-Intervall: 300 s je Agent an den Beacon. +- Ampel Health: gruen <120 s, gelb 120-300 s, rot >300 s (Beacon-Heartbeat-Age). +- Deadman-Schwelle: 5400 s (90 min) blockierte Fleet -> Kaskade reisst. +- Spool-Aging: offene Envelopes (submitted/working), rot >5400 s. +- Diagnose-Oberflaechen am Tower-Panel: Deadman-Status, Spool-Aging, + Dead-Letter, Alarm-Feed, Health-Ampel, /healthz + /api/status. +- Aufgaben des Owners: nur ENTSCHEIDEN + Freigeben. Kein Debugging im Panel. + +## ESKALATIONSKONTAKT (Owner) +- Primaer: **Owner** (Dominik). Kanal: Owner-Inbox/Queue im Tower. +- Eskalation aus einem Agenten heraus: ueber den CISO-Kanal + (`submit_task(from_agent=, to=ciso, type=review, topic="[NAR] ")`); + der CISO leitet kritische Faelle als `escalation` P1 an `tower-owner` + weiter (FLEET-POLICIES 1.3). Direkt-Adressierung an `tower-owner` ist nur + dem CISO erlaubt. +- Owner-Entscheidungen (Abnahme/Review/NAR) laufen ueber die Owner-Queue. +- Bei Netz-Themen: NAR ueber den CISO; bei Infrastruktur/Tower: tower-owner. + +--- + + +## Szenario A — Deadman-Blockade (Fleet steht, Ampel "Deadman: blocked") +Beobachtung: Deadman-Status zeigt Zustand `blocked` + blockierenden Owner-Task +(ID, Typ, Alter) im Header; ggf. rot in der Health-Ampel. + +Diagnose-Pfad: +1. Panel -> **Deadman-Status**: welcher Owner-Task blockiert? Alter auslesen. +2. Panel -> **Alarm-Feed**: juengste Deadman-Kaskade (Zeit, Agent, Ursache, + Dauer) - bestaetigt, ob es die laufende Blockade ist. +3. Panel -> **Health-Ampel** (#health): welche Agents stehen rot/gelb (wer ist + betroffen)? +4. Abgleich: blockierender Task-Typ (Abnahme/Review/NAR/Entscheidung). + +Schritte: +1. Blockierenden Owner-Task oeffnen und INNERHALB der Queue entscheiden + (Abnahme erteilen, Review freigeben/ablehnen, NAR approven). +2. Nach Entscheidung Deadman-Status auf `progress` pruefen (Auto-Refresh 30 s). +3. Wenn der Task nicht entscheidbar ist (fehlender Kontext): Task mit + Kommentar zurueck an Absender (reply_to) statt liegen zu lassen. +4. Verifikation: Health-Ampel der betroffenen Agents wieder gruen <120 s + binnen 2 Heartbeat-Zyklen (<=10 min). + +Eskalation: Bleibt die Blockade >5400 s bestehen oder ist der Task unklar -> +Owner direkt ansprechen (Kanal s.o.), Grund + Task-ID nennen. + +--- + + +## Szenario B — Spool-Stau (Tasks haengen, Zustellung klemmt) +Beobachtung: Spool-Aging listet Envelopes >5400 s rot; Zusteller liefern nicht. + +Diagnose-Pfad: +1. Panel -> **Spool-Aging**: Envelopes nach Alter + Empfaenger. Aeltester + Eintrag zuerst; rot = >5400 s. + +2. Panel -> **Dead-Letter**: status=failed (letzte 7 Tage) mit from->to, Alter - + bereits verlorene Arbeit (Luecke Spool-Aging vs. Alarm-Feed). +3. Panel -> **Health-Ampel** (#health): ist Empfaenger-Agent rot? -> down. +4. Panel -> **/api/status**: Datenquellen-Zustand Prometheus/Beacon; degraded? + +Schritte: +1. Einzelner haengender Envelope, Empfaenger gruen -> Zustellung neu anstossen + (Task erneut submitten an denselben Empfaenger, reply_to setzen). +2. Blockierter ganzer Empfaenger (rot) -> Szenario A/C zuerst loesen; der Spool + leert sich danach automatisch. +3. Failed-Tasks aus der Dead-Letter-Ansicht pruefen: wiederholbar -> erneut + submitten; endgueltig unloesbar -> Task mit Grund neu aufsetzen (nicht still + verwerfen). +4. Verifikation: keine Eintraege mehr >5400 s im Spool-Aging; Dead-Letter + waechst nicht weiter. + +Eskalation: Envelopes >5400 s ohne down-Empfaenger -> Ursache unklar, an +tower-owner mit Screenshot/IDs melden; bei >2 betroffenen Agents zusaetzlich +Owner informieren (Kanal s.o.). + +--- + + +## Szenario C — Panel-Ausfall (Tower nicht erreichbar/leer/fehlerhaft) +Beobachtung: Panel laedt nicht, Leeranzeige oder Crash; /healthz antwortet nicht. + +Diagnose-Pfad (Reihenfolge, um Server vs. Daten zu trennen): +1. Panel -> **/healthz**: 200 = Server lebt -> Problem ist Datenquelle/UI. +2. Panel -> **/api/status**: Version, Uptime, Datenquellen-Zustand + Prometheus/Beacon. Liefert JSON = API ok. +3. Degraded-Banner + Datenalter-Anzeige: bei Prometheus-/Beacon-Ausfall zeigt + der Tower Datenalter + 60 s-Cache; das ist Degraded, KEIN Totalausfall. +4. Wenn /healthz gar nicht antwortet: Panel-/Prozess-Ausfall am Tower-Host. + +Schritte: +1. Degraded (healthz 200, /api/status zeigt Quelle down): keine Panik - + Betrieb laeuft mit Cache weiter. Ursache der Quelle pruefen (Beacon-Ausfall + = alle Agents rot -> Szenario-A-Umfeld). +2. Totalausfall (healthz kein 200 / Verbindung abgelehnt): Tower braucht + Neustart/Deploy -> Aenderungsauftrag an tower-owner (nicht selbst am Host + eingreifen). +3. Waehrend Ausfall: Diagnose ersatzweise ueber die Agenten-Boards/Beacon + (Karten-Status, Heartbeat-Zeitstempel) weiterfuehren, Owner informieren. +4. Verifikation: /healthz 200 UND /api/status mit allen Quellen "up"; Panel + zeigt Datenalter ~0. + +Eskalation: healthz-Ausfall oder Deploy-Bedarf -> sofort P1 an tower-owner +(ueber den CISO-Kanal); parallele Owner-Info, da ohne Panel die Lage ueber +Agenten nicht sichtbar ist. + +--- + +## Kurz-Anhang: Anzeige am Tower +Dieses Runbook + Eskalationskontakt sollen an den Alarm-Ampeln (Deadman-Status +-> #deadman, Spool-Aging -> #spool, Dead-Letter -> #deadletter, Health-Ampel -> +#health) als kontextueller Hilfe-Link/Inline-Hint erscheinen. Der Hint ist +reiner Text (Ueberschrift + interner Link), kein aktives Element; Alarmlogik +und Degraded-Banner bleiben unberuehrt. Aenderungsauftrag an tower-owner siehe +separater Task "[build] tower-notfall-runbook: Runbook-Link an Alarm-Ampeln".