adispatchd 0.0.0-stage → 0.1.0

package/docs/cron-semantics.md

@@ -0,0 +1,96 @@
+# Cron-Semantik (Spec §5.5, §7, §24.7)
+
+Gilt für Workflows mit `trigger: { type: schedule, cron, timezone }` (Default-Zeitzone `UTC`). Implementiert in
+`src/scheduler/cron.ts` (Slot-Berechnung, croner 10.0.1) und `src/scheduler/scheduler.ts` (Auslösung, Protokoll).
+Das DST-Verhalten ist durch Tests festgenagelt (`src/scheduler/cron.test.ts`); ein croner-Update, das es ändert,
+fällt dort auf.
+
+## Grundregeln
+
+- **Slot** = von croner berechneter Zeitpunkt (UTC-Instant, Sekundengenauigkeit). Syntax: croner (5 Felder, optional
+  6 mit Sekunden); Validierung in `config validate` (WI-02).
+- **Höchstens ein automatischer Run pro Slot.** Absicherung doppelt: Primärschlüssel `cron_firings(workflow_id,
+  scheduled_for)` und Lock-Key `cron:<slot>` des Runs. Eintrag und Reservierung erfolgen in **einer** Transaktion.
+- **Jeder behandelte Slot bekommt höchstens einen `cron_firings`-Eintrag** mit `decision`. Ausnahme Serien:
+  `skipped_disabled`, `skipped_paused`, `skipped_not_ready`, `skipped_draining` werden nur für den **ersten Slot
+  einer Serie** geschrieben (Grund endet mit „further slots are not recorded while this state lasts“); weitere Slots
+  desselben Zustands schreiben nur `lastHandled` im Speicher fort. Jede andere Entscheidung (auch ein Start) beendet
+  die Serie, danach wird ein erneuter Zustand wieder einmal protokolliert:
+
+| decision | Bedeutung |
+|---|---|
+| `started` | Run reserviert und gestartet (`run_id` gesetzt) |
+| `skipped_missed` | Slot verpasst (Downtime oder zu spät behandelt) – **wird nicht nachgeholt** |
+| `skipped_limit` | globales oder Workflow-`max_concurrent` erreicht (aktive Runs inkl. manueller und `recovery_pending`) |
+| `skipped_condition` / `skipped_condition_unknown` | Workflow-Condition `false` (Exit 1) / `unknown` (Exit ≥ 2, Timeout, Fehler) |
+| `skipped_blocked` | aktiver Retry-Block im Workflow-Scope |
+| `skipped_disabled` | Workflow deaktiviert (Config oder Runtime-Override) |
+| `skipped_paused` / `skipped_not_ready` / `skipped_draining` | Controller pausiert / Recovery läuft noch / Drain bzw. Shutdown |
+| `skipped_lock` | Slot-Lock bereits belegt (defensiv, sollte nicht vorkommen) |
+| `start_failed` | Reservierung oder Start unerwartet fehlgeschlagen (`reason`) |
+
+- **Kein Rückstau:** Ein übersprungener Slot (egal warum) wird nie nachgeholt; der nächste Run entsteht frühestens
+  zum nächsten Slot. Überlappung verschiedener Slots desselben Workflows regelt `max_concurrent` (Default 1).
+
+## Verpasste Slots
+
+- **Toleranz** (`cronMisfireToleranceMs`, Default 60 s): Wird ein Slot spätestens so lange nach seinem Zeitpunkt
+  behandelt (Timer-Latenz, kurzer Neustart), wird er normal entschieden. Ist er älter, gilt er als `skipped_missed`.
+- **Nach einem Neustart** sucht der Scheduler pro Workflow ab dem jüngsten persistierten Slot (`cron_firings.latest`)
+  alle Slots bis „jetzt“: der jüngste wird – falls innerhalb der Toleranz – normal entschieden, alle älteren werden
+  `skipped_missed` mit Grund „slot passed while the orchestrator was not running“.
+- Gibt es noch keinen persistierten Slot (erster Start, neu angelegter Workflow), beginnt die Planung bei „jetzt“ –
+  es wird nichts rückwirkend protokolliert.
+- Wird ein Cron-Ausdruck/eine Zeitzone per Reload **geändert**, beginnt die Planung ebenfalls bei „jetzt“.
+- Begrenzung: pro Nachhol-Prüfung werden höchstens `maxRecordedMissedSlots` (Default 100) Slots einzeln
+  protokolliert; ältere werden nur gezählt und im Grund des ältesten protokollierten Eintrags genannt
+  („+N older missed slot(s) not recorded“). Die Suche ist auf 100 000 Slots begrenzt (danach nur noch die jüngsten).
+- Timer werden höchstens 1 h im Voraus gestellt und danach neu berechnet; damit wirken auch Systemzeit-Sprünge
+  (NTP, Suspend) spätestens nach 1 h, und übersprungene Slots werden als `skipped_missed` protokolliert.
+
+## Sommerzeit (DST) – beobachtetes und festgelegtes Verhalten
+
+Beispiel `Europe/Berlin` 2026: Umstellung auf Sommerzeit 29.03. 02:00 CET → 03:00 CEST (01:00Z),
+zurück auf Winterzeit 25.10. 03:00 CEST → 02:00 CET (01:00Z).
+
+**Fehlende Lokalzeit (Frühjahr, Lücke 02:00–02:59):**
+
+| Ausdruck | Verhalten am Umstellungstag |
+|---|---|
+| `30 2 * * *` (täglich, Zeitpunkt in der Lücke) | läuft **genau einmal**, um 03:30 CEST (= 01:30Z; um die Lückenlänge verschoben) |
+| `0 2 * * *` | läuft einmal um 03:00 CEST (01:00Z) |
+| `0 3 * * *` | läuft einmal um 03:00 CEST (01:00Z) – also zum selben Zeitpunkt wie `0 2` |
+| `*/30 * * * *` | 01:30 CET, dann 03:00 CEST, 03:30 … – die nicht existierenden 02:00/02:30 entfallen ersatzlos, keine Duplikate |
+
+Regel: Tägliche (und seltenere) Jobs mit einer Uhrzeit in der Lücke fallen **nicht** aus, sondern laufen einmal,
+verschoben um die Lückenlänge. Sub-stündliche/stündliche Jobs verlieren die Slots in der Lücke (die verschobene Zeit
+existiert ohnehin als regulärer Slot und läuft nur einmal).
+
+**Doppelte Lokalzeit (Herbst, 02:00–02:59 zweimal):**
+
+| Ausdruck | Verhalten am Umstellungstag |
+|---|---|
+| `30 2 * * *` | läuft **genau einmal**, beim ersten Durchlauf (02:30 CEST = 00:30Z); die zweite 02:30 (CET) läuft nicht |
+| `0 * * * *` | 02:00 CEST (00:00Z), dann 03:00 CET (02:00Z) – die zweite 02:00 (CET, 01:00Z) entfällt |
+| `*/30 * * * *` | 02:00, 02:30 CEST, dann 03:00 CET – Lücke von 1,5 h, die wiederholten 02:00/02:30 CET entfallen |
+
+Regel: Jede **Wanduhrzeit** wird höchstens einmal ausgelöst – beim ersten Auftreten. Es gibt nie zwei Runs für
+„02:30“ an einem Tag. Wer exakte Intervalle braucht, verwendet `timezone: UTC`.
+
+**UTC** hat keine Umstellung; Slots sind unverändert.
+
+## Zusammenspiel mit anderen Regeln
+
+- Conditions werden pro Slot ausgewertet (Workflow-Conditions mit `cache` über den TTL-Cache, sonst neu);
+  Item-Conditions/Filter gibt es für Schedule-Workflows nicht.
+- Retry-Blocks für Schedule-Workflows sind workflowbezogen (`itemKey = null`); ein aktiver Block führt zu
+  `skipped_blocked`, bis er entfernt wird.
+- Manuelle Starts eines Schedule-Workflows haben eigene Lock-Keys (`manual:<runId>`), erzeugen keinen
+  `cron_firings`-Eintrag, zählen aber zur Auslastung und können dadurch einen Slot zu `skipped_limit` machen.
+- Deaktivierte Workflows werden weiter getaktet; protokolliert wird nur der erste Slot einer
+  `skipped_disabled`-Serie (gleiches gilt für Pause/Not-ready/Drain) – keine Zeilenflut bei `* * * * *`.
+- Folge für die Downtime-Erkennung: Startet der Orchestrator neu, während bzw. nachdem eine solche Serie lief, sind
+  die nicht protokollierten Slots nach dem letzten Eintrag nicht von Downtime unterscheidbar; sie werden (begrenzt)
+  als `skipped_missed` mit Grund „… not running (or while still skipped_disabled)“ protokolliert.
+- Fehler bei der Behandlung eines Slots (z. B. DB-Fehler) werden geloggt; der Timer wird **immer** neu gestellt, der
+  nächste Slot wird normal entschieden (der fehlgeschlagene Slot bleibt ohne Eintrag).

package/docs/manual-tests/github-fixture/config.yaml

@@ -0,0 +1,30 @@
+# Test-Konfiguration für docs/manual-tests/github.md (manuelle Tests gegen echtes GitHub).
+# NICHT produktiv verwenden: kurze Intervalle und Retry-Pausen, damit die Testfälle schnell beobachtbar sind.
+# Wird von src/sources/github/manual-fixture.test.ts mit dem echten Loader validiert.
+
+server:
+  host: 127.0.0.1
+  port: 8791               # eigener Port, kollidiert nicht mit einer produktiven Instanz (8787)
+  allowed_hosts: []
+
+scheduler:
+  polling_interval: 20s    # kurz, damit „nächster Poll“ (Szenario 3) schnell sichtbar ist
+  max_concurrent: 4        # global; Workflow-Limit von coder-test (2) greift zuerst (Szenario 1)
+
+workspace:
+  cleanup: never           # Workspaces zur Analyse behalten (liegen unter <data-dir>/workspaces)
+
+lifecycle:
+  action_retry:
+    max_attempts: 3
+    delay: 20s             # Default 30 s; kürzer für Szenario 6
+
+retention:
+  completed_runs: 7d
+  failed_runs: 7d
+  blocked_runs: 7d
+  cleanup_interval: 24h
+
+notifications:
+  on: [retry_block_created, lifecycle_action_failed, recovery_failed]
+  channels: []             # optional: Webhook (z. B. https://webhook.site) für Block-/Action-Fehler eintragen

package/docs/manual-tests/github-fixture/helpers.sh

@@ -0,0 +1,93 @@
+# Shell-Helfer für docs/manual-tests/github.md – NICHT vom Orchestrator ausgeführt, sondern in der eigenen
+# Shell geladen (bash oder zsh), im Repo-Root:
+#
+#   export ADISPATCH_TEST_OWNER=<account-oder-org>
+#   source docs/manual-tests/github-fixture/helpers.sh
+#
+# Benötigt: gh (angemeldet als Maintainer-Mensch, Zugriff auf alle drei Test-Repos), curl, jq, openssl, npx.
+
+: "${ADISPATCH_TEST_OWNER:?ADISPATCH_TEST_OWNER setzen (GitHub-Account oder Org der Test-Repos)}"
+export ADISPATCH_CFG="${ADISPATCH_CFG:-$PWD/tmp/orch-cfg}"
+export ADISPATCH_DATA="${ADISPATCH_DATA:-$PWD/tmp/orch-data}"
+export API="${API:-http://127.0.0.1:8791/api/v1}"
+export GH_API_VERSION="${GH_API_VERSION:-2026-03-10}"   # = GITHUB_API_VERSION in src/sources/github/http.ts
+
+# --- Orchestrator ------------------------------------------------------------------------------------------
+orch() { npx tsx src/cli/main.ts "$@"; }                                   # CLI aus dem Checkout
+api() { curl -sS "$API$1"; }                                               # GET gegen die API
+post() {                                                                   # POST mit CSRF-Header
+  local body="${2:-}"
+  [ -n "$body" ] || body='{}'
+  curl -sS -X POST -H 'X-Adispatch-Request: 1' -H 'Content-Type: application/json' -d "$body" "$API$1"
+}
+runs() {                                                                   # runs <workflow> [limit]
+  api "/runs?workflow=$1&limit=${2:-10}" |
+    jq -r '.runs[] | [.id, .sourceItemKey, .status, .outcome, (.businessResult // "-"), .lifecycleStatus, (.finalReason // "")] | @tsv'
+}
+run_of() {                                                                 # run_of <source> <nr> → neueste Run-ID
+  api "/runs?item=$1:$2&limit=1" | jq -r '.runs[0].id // empty'
+}
+diag() {                                                                   # diag <workflow> → letzte Planungsdiagnose
+  api "/workflows/$1" | jq -r '.diagnosis // {} | "status=\(.status) polled=\(.polled) error=\(.error) pushdown=\(.pushdown | tojson)",
+    (.candidates // [] | .[] | [.itemKey, .decision, (.reason // "")] | @tsv)'
+}
+actions() {                                                                # actions <run-id> → Action-Journal
+  api "/runs/$1" | jq -r '.actions[] | [.id, .hook, .ordinal, .type, .status, "attempts=\(.attempts)", (.externalKey // "-"), (.lastError.message // "")] | @tsv'
+}
+events() { api "/runs/$1/events?limit=1000" | jq -c '.events[] | {type, payload}'; }   # events <run-id>
+view() {                                                                   # view <view-id> → Tabelle (frisch, ohne Cache)
+  api "/views/$1/items?refresh=true" |
+    jq -r '(.columns | map(.label) | @tsv), (.rows[] | .cells | map(if .known then (.value | tostring) else "?" end) | @tsv), (.errors[] | "ERROR \(.sourceId): \(.message)")'
+}
+
+# --- GitHub (als Mensch über gh) ---------------------------------------------------------------------------
+repo() { printf '%s/%s' "$ADISPATCH_TEST_OWNER" "$1"; }                         # repo orch-test-a → owner/orch-test-a
+issue_url() { printf 'https://github.com/%s/issues/%s' "$(repo "$1")" "$2"; }
+mkissue() {                                                                # mkissue <repo> <titel> [label ...] → Nummer
+  local r="$1" title="$2" l
+  shift 2
+  local args=()
+  for l in "$@"; do args+=(--label "$l"); done
+  gh issue create -R "$(repo "$r")" --title "$title" --body "adispatchd manual test: $title" "${args[@]}" | sed 's#.*/##'
+}
+blockedby() {                                                              # blockedby <repo> <nr> <blocker-repo> <blocker-nr>
+  gh issue edit "$2" -R "$(repo "$1")" --add-blocked-by "$(issue_url "$3" "$4")"
+}
+blockedby_api() {                                                          # wie blockedby, über REST (issue_id = Datenbank-ID!)
+  local id
+  id="$(gh api "repos/$(repo "$3")/issues/$4" --jq .id)" || return 1
+  gh api -X POST "repos/$(repo "$1")/issues/$2/dependencies/blocked_by" -H "X-GitHub-Api-Version: $GH_API_VERSION" \
+    -F issue_id="$id" --jq '"blocked_by added: #\(.number)"'
+}
+unblock_api() {                                                            # unblock_api <repo> <nr> <blocker-repo> <blocker-nr>
+  local id
+  id="$(gh api "repos/$(repo "$3")/issues/$4" --jq .id)" || return 1
+  gh api -X DELETE "repos/$(repo "$1")/issues/$2/dependencies/blocked_by/$id" -H "X-GitHub-Api-Version: $GH_API_VERSION" --jq '.number'
+}
+labels() { gh issue view "$2" -R "$(repo "$1")" --json labels --jq '[.labels[].name] | sort | join(",")'; }   # labels <repo> <nr>
+comments() {                                                               # comments <repo> <nr> → id, Autor, Typ, App-ID, letzte Zeile
+  gh api --paginate "repos/$(repo "$1")/issues/$2/comments" \
+    --jq '.[] | [.id, .user.login, .user.type, (.performed_via_github_app.id // "-" | tostring), (.body | split("\n") | last)] | @tsv'
+}
+
+# --- GitHub (als App) --------------------------------------------------------------------------------------
+probe() { npx tsx tmp/probe.ts "$@"; }                                      # siehe github.md, Abschnitt 2.4
+ghraw() {                                                                  # ghraw <identity> <pfad> [curl-Optionen] → Rohantwort als App
+  local identity="$1" path="$2" token
+  shift 2
+  token="$(probe token "$identity" 2>/dev/null)" || { echo "kein Token für $identity" >&2; return 1; }
+  curl -sS -H "Authorization: Bearer $token" -H 'Accept: application/vnd.github+json' \
+    -H "X-GitHub-Api-Version: $GH_API_VERSION" "$@" "https://api.github.com$path"
+}
+app_jwt() {                                                                # app_jwt <app-id> <pem-datei> → JWT (9 min)
+  local now h p s
+  now="$(date +%s)"
+  h="$(printf '{"alg":"RS256","typ":"JWT"}' | openssl base64 -A | tr '+/' '-_' | tr -d '=')"
+  p="$(printf '{"iat":%d,"exp":%d,"iss":"%s"}' "$((now - 60))" "$((now + 540))" "$1" | openssl base64 -A | tr '+/' '-_' | tr -d '=')"
+  s="$(printf '%s.%s' "$h" "$p" | openssl dgst -sha256 -sign "$2" -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')"
+  printf '%s.%s.%s' "$h" "$p" "$s"
+}
+installation_id() {                                                        # installation_id <app-id> <pem-datei> <repo>
+  curl -sS -H "Authorization: Bearer $(app_jwt "$1" "$2")" -H 'Accept: application/vnd.github+json' \
+    -H "X-GitHub-Api-Version: $GH_API_VERSION" "https://api.github.com/repos/$(repo "$3")/installation" | jq '{id, app_id, app_slug, repository_selection, permissions}'
+}

package/docs/manual-tests/github-fixture/identities.yaml

@@ -0,0 +1,18 @@
+# Drei GitHub Apps (eine pro Rolle). Die Zahlen sind Platzhalter und werden beim Kopieren durch die echten
+# App-IDs und Installation-IDs ersetzt (siehe github.md, Abschnitt 2). Private Keys NUR als Env-Variablen.
+identities:
+  maintainer:
+    type: github_app
+    app_id: 9000001
+    installation_id: 9100001
+    private_key_env: ADISPATCH_TEST_MAINTAINER_KEY
+  coder:
+    type: github_app
+    app_id: 9000002
+    installation_id: 9100002
+    private_key_env: ADISPATCH_TEST_CODER_KEY
+  reviewer:
+    type: github_app
+    app_id: 9000003
+    installation_id: 9100003
+    private_key_env: ADISPATCH_TEST_REVIEWER_KEY

package/docs/manual-tests/github-fixture/scripts/test-worker.sh

@@ -0,0 +1,100 @@
+#!/bin/sh
+# Test-Worker für docs/manual-tests/github.md. Simuliert je nach Issue-Label das Worker-Verhalten
+# (Worker-Protokoll: docs/worker-protocol.md, Spec §8.2):
+#
+#   (kein test:*-Label)  Exit 0 + Ergebnis success                → on_success
+#   test:slow            vorher TEST_SLOW_SECONDS (Default 90) schlafen, alle 10 s ein progress-Event
+#   test:failure         Exit 0 + Ergebnis failure (fachlich)     → on_failure, kein Retry-Zähler
+#   test:crash           Ergebnis success schreiben, dann Exit 1  → crashed (Datei wird ignoriert), on_crash
+#   test:invalid-result  Exit 0 + ungültige Ergebnisdatei         → crashed (Protokollfehler)
+#   test:token           GH_TOKEN (execute.secrets) gegen die API prüfen; Exit 1, falls nicht HTTP 200
+#   test:revoke-token    GH_TOKEN per DELETE /installation/token widerrufen (erzwingt Token-Erneuerung im
+#                        Orchestrator: nächster Aufruf der Identity → 401 → invalidate → neues Token)
+#
+# Labels kombinierbar (z. B. test:slow + test:failure). Argumente: $1 = Issue-Nummer, $2 = owner/repo.
+set -eu
+
+number="${1:-?}"
+repo="${2:-?}"
+slow="${TEST_SLOW_SECONDS:-90}"
+
+# Labels aus der Kontextdatei lesen (source.attributes.labels). node ist vorhanden, weil der Orchestrator
+# damit läuft; Fallback grep (Labels stehen als JSON-Strings in der Datei).
+labels=""
+if command -v node >/dev/null 2>&1; then
+  labels="$(node -e '
+    const c = JSON.parse(require("fs").readFileSync(process.env.ADISPATCH_CONTEXT_FILE, "utf8"));
+    const l = (c.source && c.source.attributes && c.source.attributes.labels) || [];
+    process.stdout.write(l.join("\n"));
+  ')"
+else
+  labels="$(grep -o '"test:[a-z-]*"' "${ADISPATCH_CONTEXT_FILE}" | tr -d '"' || true)"
+fi
+has() { printf '%s\n' "${labels}" | grep -qx "$1"; }
+
+# Ergebnis atomar schreiben (temporäre Datei im selben Verzeichnis + mv).
+write_result() { # $1 = success|failure, $2 = message
+  tmp="${ADISPATCH_RESULT_FILE}.tmp.$$"
+  msg="$(printf '%s' "$2" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+  printf '{"schema_version":1,"result":"%s","message":"%s","details":{"repo":"%s","number":"%s"}}\n' \
+    "$1" "${msg}" "${repo}" "${number}" > "${tmp}"
+  mv "${tmp}" "${ADISPATCH_RESULT_FILE}"
+}
+
+echo "test-worker: run ${ADISPATCH_RUN_ID} workflow ${ADISPATCH_WORKFLOW_ID} item ${repo}#${number}"
+echo "test-worker: labels: $(printf '%s' "${labels}" | tr '\n' ' ')"
+echo "test-worker: workspace ${ADISPATCH_WORKSPACE}"
+echo '@@ADISPATCH_EVENT {"type":"status","message":"test-worker gestartet"}'
+
+if has test:token; then
+  code="$(curl -s -o /dev/null -w '%{http_code}' \
+    -H "Authorization: Bearer ${GH_TOKEN:-missing}" \
+    -H 'Accept: application/vnd.github+json' \
+    -H 'X-GitHub-Api-Version: 2026-03-10' \
+    "https://api.github.com/repos/${repo}/issues/${number}")"
+  echo "test-worker: GET issue with GH_TOKEN → HTTP ${code}"
+  [ "${code}" = "200" ] || { echo "test-worker: GH_TOKEN rejected" >&2; exit 1; }
+fi
+
+if has test:revoke-token; then
+  code="$(curl -s -o /dev/null -w '%{http_code}' -X DELETE \
+    -H "Authorization: Bearer ${GH_TOKEN:-missing}" \
+    -H 'Accept: application/vnd.github+json' \
+    -H 'X-GitHub-Api-Version: 2026-03-10' \
+    "https://api.github.com/installation/token")"
+  echo "test-worker: DELETE /installation/token → HTTP ${code} (expected 204)"
+fi
+
+if has test:slow; then
+  elapsed=0
+  while [ "${elapsed}" -lt "${slow}" ]; do
+    printf '@@ADISPATCH_EVENT {"type":"progress","value":%s}\n' "$((elapsed * 100 / slow))"
+    echo "test-worker: working ${elapsed}/${slow}s"
+    sleep 10
+    elapsed=$((elapsed + 10))
+  done
+fi
+
+if has test:crash; then
+  write_result success "wird ignoriert, weil Exit != 0"
+  echo "test-worker: simulating crash (exit 1)" >&2
+  exit 1
+fi
+
+if has test:invalid-result; then
+  tmp="${ADISPATCH_RESULT_FILE}.tmp.$$"
+  printf '%s\n' '{"schema_version":1,"result":"maybe"}' > "${tmp}"
+  mv "${tmp}" "${ADISPATCH_RESULT_FILE}"
+  echo "test-worker: wrote invalid result file"
+  exit 0
+fi
+
+if has test:failure; then
+  write_result failure "Simulierter fachlicher Fehler fuer ${repo}#${number}"
+  echo '@@ADISPATCH_EVENT {"type":"question","message":"Anforderungen unklar (simuliert)"}'
+  exit 0
+fi
+
+write_result success "Simulierter Erfolg fuer ${repo}#${number}"
+echo '@@ADISPATCH_EVENT {"type":"progress","value":100}'
+exit 0

package/docs/manual-tests/github-fixture/sources.yaml

@@ -0,0 +1,13 @@
+# Zwei Test-Repos im selben Account/Org. ADISPATCH_TEST_OWNER wird beim Kopieren ersetzt (siehe github.md, Abschnitt 2).
+# Das dritte Repo (orch-test-hidden) ist bewusst KEINE Source und für keine App installiert.
+sources:
+  test_a:
+    type: github
+    owner: ADISPATCH_TEST_OWNER
+    repository: orch-test-a
+    identity: maintainer    # Lesen (Polling, Dependencies, Views) mit der Maintainer-App
+  test_b:
+    type: github
+    owner: ADISPATCH_TEST_OWNER
+    repository: orch-test-b
+    identity: maintainer

package/docs/manual-tests/github-fixture/views/dependencies.yaml

@@ -0,0 +1,17 @@
+# views/dependencies.yaml – Beobachtungswerkzeug für die Dependency-Fälle (github.md: T11–T14), ohne Runs zu starten.
+# Zeigt für alle offenen Items mit Label deps-test, wie der Adapter "blocked by" auflöst.
+id: dependencies
+title: Dependencies (Test)
+sources: [test_a, test_b]
+filter:
+  all:
+    - { field: labels, operator: contains, value: deps-test }
+fields:
+  - { field: repository, label: Repository }
+  - { field: number, label: Nr. }
+  - { field: title, label: Titel, link: url }
+  - { field: dependencies.status, label: Status }
+  - { field: dependencies.blocked_by_total, label: Blocker gesamt }
+  - { field: dependencies.blocked_by_open, label: Blocker offen }
+  - { field: dependencies.blocked, label: Blockiert }
+sort: { field: number, direction: asc }

package/docs/manual-tests/github-fixture/views/needs-maintainer.yaml

@@ -0,0 +1,17 @@
+# views/needs-maintainer.yaml – Szenario 10: kombiniert beide Test-Repos (github.md: T21).
+id: needs-maintainer
+title: Needs Maintainer (Test)
+sources: [test_a, test_b]
+filter:
+  all:
+    - { field: labels, operator: contains, value: needs-maintainer }
+fields:
+  - { field: repository, label: Repository }
+  - { field: number, label: Nr. }
+  - { field: title, label: Titel, link: url }
+  - { field: is_pull_request, label: PR }
+  - { field: run.last_workflow, label: Letzter Agent }
+  - { field: run.last_status, label: Status }
+  - { field: run.last_result.message, label: Ergebnis }
+  - { field: updated_at, label: Aktualisiert }
+sort: { field: updated_at, direction: desc }

package/docs/manual-tests/github-fixture/workflows/coder-test.yaml

@@ -0,0 +1,76 @@
+# workflows/coder-test.yaml – Coder-Rolle gegen orch-test-a (github.md: T3–T9, T13–T17, T20).
+# Startet Issues/PRs mit Label ready-for-coding, deren native "blocked by"-Abhängigkeiten alle geschlossen sind.
+# Das Verhalten des Test-Workers steuern die Labels test:* (siehe scripts/test-worker.sh).
+id: coder-test
+name: Coder-Test (orch-test-a)
+enabled: true
+priority: 50
+max_concurrent: 2           # Szenario 1: zwei parallel, der dritte wartet (workflow_limit)
+identity: coder             # schreibende Aktionen (Labels, Kommentare) als Coder-App
+
+trigger:
+  type: source
+  source: test_a
+
+filter:
+  all:
+    - { field: labels, operator: contains, value: ready-for-coding }      # Pushdown: ?labels=ready-for-coding
+    - { field: dependencies.blocked_by_open, operator: equals, value: 0 } # teuer, unknown → kein Start
+
+item_priority:
+  rules:
+    - when: { field: labels, operator: contains, value: 'priority:high' }
+      value: 50
+  default: 0
+
+execute:
+  type: shell
+  command: scripts/test-worker.sh       # relativ zum config-dir
+  args: ['{item.number}', '{source.repository}']
+  env:
+    TEST_SLOW_SECONDS: '90'             # Dauer bei Label test:slow
+  secrets:
+    GH_TOKEN: { identity: coder }       # nur für Label test:token (Token-Prüfung im Worker)
+  timeout:
+    max_duration: 10m
+    idle_timeout: 5m
+  cancel_grace: 10s
+
+retry:
+  max_technical_failures: 3             # Szenario 5: dritter Crash → Retry-Block
+
+on_start:
+  - id: on_start-labels
+    type: source.update
+    labels: { add: [coding], remove: [ready-for-coding] }
+on_success:
+  - id: on_success-labels
+    type: source.update
+    labels: { add: [ready-for-review], remove: [coding] }
+  - id: on_success-comment
+    type: source.comment
+    message: 'Coder-Test erfolgreich: {result.message}'
+    continue_on_error: true
+on_failure:                             # fachliches failure (Ergebnisdatei) → Needs Maintainer, kein Retry-Zähler
+  - id: on_failure-labels
+    type: source.update
+    labels: { add: [needs-maintainer], remove: [coding] }
+  - id: on_failure-comment
+    type: source.comment
+    message: 'Needs maintainer: {result.message}'
+on_crash:                               # technischer Fehler → zurück in die Warteschlange (Block stoppt nach 3×)
+  - id: on_crash-labels
+    type: source.update
+    labels: { add: [ready-for-coding], remove: [coding] }
+on_start_error:
+  - id: on_start_error-labels
+    type: source.update
+    labels: { add: [ready-for-coding], remove: [coding] }
+on_timeout:
+  - id: on_timeout-labels
+    type: source.update
+    labels: { add: [ready-for-coding], remove: [coding] }
+on_cancel:
+  - id: on_cancel-labels
+    type: source.update
+    labels: { add: [ready-for-coding], remove: [coding] }

package/docs/manual-tests/github-fixture/workflows/commenter-test.yaml

@@ -0,0 +1,63 @@
+# workflows/commenter-test.yaml – Kommentar-Actions gegen orch-test-b (github.md: T6, T7, T18, T19).
+# on_start kommentiert als REVIEWER (Action-Identity überschreibt die Workflow-Identity),
+# on_success als CODER mit großzügigem Retry, damit ein kurzer Netzwerkausfall überbrückt wird (Szenario 6).
+id: commenter-test
+name: Kommentar-Test (orch-test-b)
+enabled: true
+priority: 30
+max_concurrent: 1
+identity: coder
+
+trigger:
+  type: source
+  source: test_b
+
+filter:
+  all:
+    - { field: labels, operator: contains, value: ready-for-comment }
+
+execute:
+  type: shell
+  command: scripts/test-worker.sh
+  args: ['{item.number}', '{source.repository}']
+  env:
+    TEST_SLOW_SECONDS: '60'
+  timeout:
+    max_duration: 10m
+
+on_start:
+  - id: on_start-labels
+    type: source.update
+    labels: { add: [commenting], remove: [ready-for-comment] }
+  - id: start-comment
+    type: source.comment
+    identity: reviewer
+    message: 'Kommentar-Test gestartet (Run {run.id}, Item {item.key}).'
+on_success:
+  - id: done-comment
+    type: source.comment
+    message: 'Kommentar-Test fertig: {result.message}'
+    retry: { max_attempts: 6, delay: 20s }   # ~100 s Fenster für einen Netzwerkausfall
+  - id: on_success-labels
+    type: source.update
+    labels: { add: [commented], remove: [commenting] }
+on_failure:
+  - id: on_failure-labels
+    type: source.update
+    labels: { add: [needs-maintainer], remove: [commenting] }
+on_crash:
+  - id: on_crash-labels
+    type: source.update
+    labels: { add: [ready-for-comment], remove: [commenting] }
+on_start_error:
+  - id: on_start_error-labels
+    type: source.update
+    labels: { add: [ready-for-comment], remove: [commenting] }
+on_timeout:
+  - id: on_timeout-labels
+    type: source.update
+    labels: { add: [ready-for-comment], remove: [commenting] }
+on_cancel:
+  - id: on_cancel-labels
+    type: source.update
+    labels: { add: [ready-for-comment], remove: [commenting] }

package/docs/manual-tests/github-fixture/workflows/reviewer-test.yaml

@@ -0,0 +1,60 @@
+# workflows/reviewer-test.yaml – Reviewer-Rolle gegen orch-test-a (github.md: T10).
+# Nur Pull Requests mit Label ready-for-review und ohne offene Blocker. Ein Issue mit demselben Label
+# (z. B. nach coder-test-Erfolg) wird über is_pull_request herausgefiltert.
+id: reviewer-test
+name: Reviewer-Test (orch-test-a, nur PRs)
+enabled: true
+priority: 40
+max_concurrent: 1
+identity: reviewer
+
+trigger:
+  type: source
+  source: test_a
+
+filter:
+  all:
+    - { field: labels, operator: contains, value: ready-for-review }
+    - { field: is_pull_request, operator: equals, value: true }
+    - { field: dependencies.blocked_by_open, operator: equals, value: 0 }
+
+execute:
+  type: shell
+  command: scripts/test-worker.sh
+  args: ['{item.number}', '{source.repository}']
+  env:
+    TEST_SLOW_SECONDS: '60'
+  timeout:
+    max_duration: 10m
+
+on_start:
+  - id: on_start-labels
+    type: source.update
+    labels: { add: [reviewing], remove: [ready-for-review] }
+on_success:
+  - id: on_success-labels
+    type: source.update
+    labels: { add: [reviewed], remove: [reviewing] }
+  - id: on_success-comment
+    type: source.comment
+    message: 'Reviewer-Test ok: {result.message}'
+on_failure:
+  - id: on_failure-labels
+    type: source.update
+    labels: { add: [needs-maintainer], remove: [reviewing] }
+on_crash:
+  - id: on_crash-labels
+    type: source.update
+    labels: { add: [ready-for-review], remove: [reviewing] }
+on_start_error:
+  - id: on_start_error-labels
+    type: source.update
+    labels: { add: [ready-for-review], remove: [reviewing] }
+on_timeout:
+  - id: on_timeout-labels
+    type: source.update
+    labels: { add: [ready-for-review], remove: [reviewing] }
+on_cancel:
+  - id: on_cancel-labels
+    type: source.update
+    labels: { add: [ready-for-review], remove: [reviewing] }