# Handoff — Stand 2026-05-20 > **Historical snapshot only (2026-05-25 cleanup).** This file is preserved > for audit/history. Do not treat its "start", "push", "deploy" or operator > instructions as current work. Use `PROGRESS.md`, `OPERATOR-CHECKLIST.md` > and the latest session notes for live status. **Vorgänger-Agent:** Claude Opus 4.7 (1M context) **Letzte aktive Session:** Phase 06 Plugin-System — von "audit-package zusammenstellen" bis "fast alle internen Findings remediated" **Ziel des Handoffs:** Nachfolge-Agent soll in **3 Minuten** wissen wo wir stehen, was gerade kein Code-Problem sondern Operator-Arbeit ist, und welche Tracks Code-Arbeit brauchen. --- ## 1. Was die letzte Session bewegt hat (29 commits auf `main`) Phase 06 (Plugin-System) #23 von `pending` → `in_progress (operator-audit-pending)`. Audit-Package-Layer + 12 interne Findings remediated mit Tests. Schlüssel-Artefakte: - `docs/security/plugin-threat-model.md` — 14 Assets × STRIDE, jede Mitigation per `file:line` an Code gehängt - `docs/security/plugin-attack-surface.md` — 9 Capabilities, Manifest-Felder, DB-Tabellen, Routes, Env - `docs/security/plugin-internal-findings.md` — 24 F-NNN Findings, 23 davon disposed (closed / accepted-residual / blocked-on-precondition / blocked-architecturally) - `docs/security/plugin-audit-rfp.md` — RFP mit Vendor-Empfehlung Cure53 (Alternates: Trail of Bits / NCC Group / SySS / secfault), 25k EUR Cap - `docs/security/plugin-runtime-signoff.md` — Joint Sign-Off-Template - `scripts/build-plugin-audit-package.sh` — bündelt In-Scope-Code + Docs + SHA-256-Manifest in ein tar.gz (smoke-getestet ~209 KB) - `docs/improvement-plan/06-plugin-system/security-findings/README.md` — Folder-Convention für künftige Findings-Files Code-Remediations diese Session (alle mit Tests + grünem Lefthook-Pre-Commit): - F-015 Critical (worker bootstrap unwired) — `handlePluginInvokeJob` jetzt wirklich an BullMQ angeschlossen - F-005 Phase A + B — Install-Path Trust-Store-Gate + binary-on-disk verify - F-017 — Manifest-Schema um `minHostVersion`/`maxHostVersion` erweitert - F-010 — CSRF-body-consumption immunity verifiziert - F-014 — sanitize total-size budget - F-011 — install-route per-tenant rate limit - F-008/F-009/F-021/F-023 — Medium-Sweep (statement cap, install cap, tenantId regex, circular-ref WeakSet) - F-007/F-020 — per-stmt migration audit + audit-table-size warning - F-006 — Token-aware migration scan (ersetzt substring-only Forbidden-Token-Check) - F-003 — `PluginCapabilityUse` per-tenant hash chain (Prisma migration + verifier) - F-001 backend — `TenantPluginCapabilityGrant` Modell + enable-time consent-gate (UI deferred) - F-013/F-016/F-018/F-019/F-012 — als accepted-residual / documented / blocked-on-precondition geschlossen Nur **F-002** bleibt offen — per-instruction fuel braucht Wasmtime-Swap (multi-week, architektur). Konkrete Two-Track-Remediation steht in der Findings-Datei. --- ## 2. Gesamt-Projekt-Status ``` Total Tasks: 63 aktiv + 7 Backlog Completed: 35 / 63 (56%) In Progress: 28 / 63 Pending: 0 Backlog: 7 Blocked-hart: 0 (siehe BLOCKERS.md für Operator-Anfragen) ``` Die "In Progress: 28" zerfallen in drei sehr unterschiedliche Buckets — das ist das wichtigste was der nächste Agent verstehen muss. ### Bucket A — Operator-Pending (~14 Tasks, KEINE Code-Arbeit) Code ist fertig + getestet, was fehlt ist eine Operator-Aktion (env flip, deploy, account setup, store submission, live E2E test). **Nicht anpacken ohne klaren Operator-Auftrag.** | Task | Operator-Aktion | | --------------------------------- | ------------------------------------------------------------------------ | | #16 / #17 AV-Layer 1+2 | Erste echte EICAR-Upload-Smoke auf staging | | #19 / #20 Magic-Link / Invitation | Live E2E-Flow auf staging | | #23 Phase 06 #23 | **External pen-test dispatch** (B-006) — siehe Section 4 | | #26 TOTP | Live MFA enroll/challenge E2E | | #29 / #30 / #32 Sentry | Workflow-Smoke + Project-Setup | | #40 PgBouncer | App `DATABASE_URL` flip | | #41 R/W-Split | Replica deploy + connection-string flip | | #51 Asset-CDN | CDN-Zone provisionieren | | #56 AI-Cost Phase 3 | Stripe-Account Meter-Setup (siehe `docs/ops/stripe-meters-migration.md`) | | #65 Mobile | Native-builds + App Store / Play Store submission | | #27 Password-Policy | Login-Soft-Banner (Code-Stub existiert, UI-Polish deferred) | ### Bucket B — Code-Sprint-Deferred (~13 Tasks, ECHTE Code-Arbeit) Foundation ist da, Feature-Vervollständigung steht aus. Diese sind die echten "weitermachen"-Kandidaten. | Task | Was zu tun ist | Aufwand | | ------------------------------ | --------------------------------------------------------------------------------------------------------- | ---------- | | **#21 / #22 Plugin Phase 1+2** | Hot-reload, marketplace, sandboxed iframe, output-hooks, 13 zusätzliche hook-points, global crash counter | 2-3 Wochen | | **#38 Shared-Store** | 3 von 6 Stores migriert; idempotency + subscription-cache + session offen | 1 Woche | | **#42 Outbox** | Foundation shipped; call-site migrations, admin UI, CLI re-queue, e2e tests offen | 1 Woche | | **#39 Pub/Sub** | feature-flag invalidation in Phase 05 wired-up | 2-3 Tage | | **#53 Feature-Flags** | Visual rule builder UI | 3-5 Tage | | **#55 AI-Cost Quota** | Admin + tenant UI + CLI | 3-5 Tage | | **#59 Realtime-Collab** | Andere Editoren als Novel anbinden (Hocuspocus) | 1 Woche | | **#62 Storybook** | a11y / visual-regression / test-runner | 3-5 Tage | | **#72 i18n** | 200+ jsx-text + prop-literal extractions (`/72 i18n migration sprint` in D1) | 3-5 Tage | | **#73 WCAG** | Axe-violation Backlog abarbeiten | 5-7 Tage | | **#76 Test-Coverage** | Per-Module-Gates ratchet | 5-10 Tage | | **#78 Marketing-Funnel** | Admin-Sidebar wiring + Turnstile staging-verify | 1-2 Tage | | **F-002 (Phase 06)** | Per-instruction fuel via Wasmtime-Swap ODER worker-thread + wall-clock kill | multi-week | ### Bucket C — Backlog (7 Tasks, on-demand) #24 (Marketplace), #52, #57, #64, #66, #74, #77 — explizit "nur wenn jemand fragt", nicht auf der aktiven Roadmap. --- ## 3. Offene Operator-Blocker (BLOCKERS.md) > **Superseded blocker status (2026-05-28):** this section is preserved as > the 2026-05-20 snapshot. Current truth: B-006 remains the external plugin > production gate; B-008 is closed by operator disk-pressure alerting; B-012 > is a mitigated runner-host recurrence risk, not an active deploy/code > blocker. Use `../../OPERATOR-CHECKLIST.md` and `../../BLOCKERS.md`. ### Aktuell **open**: - **B-006 — External Security Review of WASM Sandbox** (Phase 06 production rollout gate) - Audit-Package + RFP + Vendor-Memo + Sign-Off-Template alle ready (siehe Section 4) - Operator: Cure53 (oder einer der 4 Alternates) engagieren, 3-5 Tage Pen-Test, ~15-25k EUR - **B-008 — Disk-pressure monitoring** (Aftermath: containers wieder up, prevention pending) - Operator: Grafana-Alert + automated `docker system prune` cron - **B-012 — Gitea-runner Docker default-address-pool** (mitigated 2026-05-18, permanent fix operator-owed) - Operator: `/etc/docker/daemon.json` auf `homeserver` editieren + dockerd restart ### Resolved (siehe BLOCKERS.md für Archiv): B-001 (Stripe 13→19), B-002 (Staging-Access), B-003 (Push-Strategie), B-005 (Sentry OTLP), B-007 (Authentik blueprints), B-009 (Lighthouse session-cookie), B-010 (pgvector + migrations), B-011 (Worker Dockerfile), B-013 (Vite node:crypto) --- ## 4. Phase 06 — Production-Rollout-Path (konkrete Schritte) > **Archived superseded notes:** this rollout path predates later plugin > readiness and worker-topology docs. Use `docs/operations/plugin-lifecycle.md`, > `docs/worker.md`, `docs/ops/worker-queues.md`, and > `docs/security/plugin-runtime-signoff.md` for current runtime gates. In > particular, the production gate is now `PLUGIN_RUNTIME_PRODUCTION_ENABLED`, > not the older `PLUGIN_RUNTIME_ENABLED` wording below. Phase 06 ist der einzige Track der gerade "audit-ready" ist und auf eine externe Operator-Aktion wartet. Der Pfad zur completed-Markierung: 1. **`git push`** — die 29 lokalen commits auf `main` müssen nach `origin` (Pre-Push-Hook ist grün seit `3afbb257`) 2. **`bash scripts/build-plugin-audit-package.sh`** — erzeugt `artifacts/plugin-audit/2026-05-20/plugin-audit-.tar.gz` 3. **RFP + Archive an Cure53 verschicken** per `docs/security/plugin-audit-rfp.md` § 9 (E-Mail-Template am Ende der RFP-Datei) 4. **Während des Audits (~3 Wochen):** Findings werden unter `docs/improvement-plan/06-plugin-system/security-findings/F-NNN-….md` abgelegt. Pro Critical/High einen eigenen File mit Reproduction + Remediation-Plan. 5. **Fixes pushen → Re-Test anfragen** (Cure53 macht typischerweise 1× Re-Test im Engagement) 6. **`docs/security/plugin-runtime-signoff.md`** ausgefüllt + von Operator + Lead Auditor signiert 7. **Production-Env-Vars setzen** _bevor_ `PLUGIN_RUNTIME_ENABLED=true`: - `PLUGIN_TRUSTED_PUBLIC_KEYS=` (Operator-Aktion) - `PLUGIN_INSTALL_SKIP_BINARY_VERIFY=false` (Default — NICHT auf true setzen in Prod) - `PLUGIN_REQUIRE_CAPABILITY_CONSENT=true` (Default — NICHT auf false setzen in Prod) - `PLUGIN_BINARY_BASE_PATH=/app/var/plugins` (oder operator-gewählt) - `WORKER_QUEUE_GROUP=plugin` Container provisionieren (separates `worker-plugin` deploy) 8. **PROGRESS.md** Status für #23 von `in_progress (operator-audit-pending)` → `completed` 9. **F-002** bleibt nach Audit als deferred — entweder direkt im selben Rollout angegangen ODER als Phase-06-follow-up --- ## 5. Was der nächste Agent zuerst tun sollte **Lies in dieser Reihenfolge (max 15 Minuten):** 1. Dieses Handoff-Dokument (bis hierhin) 2. `docs/improvement-plan/PROGRESS.md` Aggregat-Sektion (Zeilen 1-50) 3. `docs/improvement-plan/BLOCKERS.md` (alle `Open` Einträge) 4. `docs/improvement-plan/OPERATOR-CHECKLIST.md` § A (operator-env-flip-pending Items) 5. `docs/security/plugin-internal-findings.md` Summary-Tabelle (Section "Summary") 6. `.claude/CLAUDE.md` (React Router v7 conventions — die werden im Repo strikt enforced) 7. `AGENTS.md` im Repo-Root (Workflow + Branch-Strategie) **Dann sprich mit dem User über die Richtung:** > "Vorgänger hat Phase 06 audit-ready übergeben. Open Bucket-B Tracks sind A, B, C, D — welcher davon ist priorität, oder gibt es einen anderen Track der dich gerade interessiert?" **NICHT** einfach in Phase-06-Follow-Up-Code reingehen ohne expliziten Auftrag — F-002 ist Multi-Wochen-Architektur (Wasmtime), nichts zum "kurz mal machen". Auch nicht in Bucket-A-Operator-Tracks reinarbeiten ohne klaren Anlass — der Code ist fertig, das Warten ist beabsichtigt. --- ## 6. Workflow-Konventionen (NICHT vergessen) > **Archived superseded notes:** these workflow conventions were session-local > for 2026-05-20. They do not override current repository instructions, > conversation constraints, branch policy, verification scope, or commit/push > decisions. Aus `AGENTS.md` + Session-Erfahrung: 1. **Alle Commits direkt auf `main`** — keine Branches, Coolify deployed auto auf staging 2. **`git pull --rebase` vor Workflow-Start** — andere Agenten arbeiten parallel 3. **Lefthook Pre-Commit ist hart** — `test-density`, `eslint-baseline`, `secrets`, `lint-staged` müssen grün 4. **Lefthook Pre-Push ist hart** — full `pnpm typecheck`. Bricht den Push wenn TS-Fehler. Diese Session hatte einen Push-Fail wegen F-001 Set-Type — fix in `3afbb257`. 5. **React Router v7** — Route-Type-Imports IMMER als `./+types/`, nie relativ. Nach Route-Add `npm run typecheck` ausführen. 6. **Niemals `git add -A`** — nur explizite Paths. Parallel-Agenten-Disziplin. 7. **Co-Author-Trailer:** `Co-Authored-By: Claude Opus 4.7 (1M context) ` 8. **`pnpm`, nicht npm** — pnpm-workspace-Setup, `pnpm -F ` für package-scoped scripts 9. **Tests via `npx vitest run `**, NICHT `pnpm test` (zu breit für TDD) --- ## 7. Push-Status (jetzt-aktuell) > **Archived superseded notes:** the push status below is a point-in-time > snapshot from 2026-05-20, not current repository state. ``` HEAD: 3afbb257 fix(plugins): widen capability-name Set type in F-001 grant check local-main vs origin/main: 29 commits ahead worktree: nur auto-generated Prisma client modifications (packages/db/generated/prisma/*) ``` **Operator sollte als allererstes `git push` durchziehen.** Die 29 Commits sind lokal, getestet, hooks-grün, aber noch nicht auf `origin`. Bis die nicht oben sind ist nichts deployed. Wenn der Push erneut scheitert: Pre-Push-Hook Output lesen, das ist ein neuer Bug, kein bekannter Fehler. --- ## 8. Was diese Session NICHT geleistet hat (ehrlich) - **F-002 nicht angegangen** — Wasmtime-Swap ist multi-week, nicht session-scoped. Konkrete Two-Path-Remediation in `plugin-internal-findings.md` F-002 dokumentiert. - **Phase 06 UI** — Capability-Consent-Dialog, Sandboxed-iframe-Settings, Audit-Trail-Filter-UI sind alle deferred (#22 Deviations + F-001 backend-only) - **13 weitere Hook-Points** — Phase 06 #22 hat 5/18 wired; 13 deferred - **Marketplace** — Phase 11 Backlog #24, nicht aktiv - **Andere Tracks außerhalb Phase 06** — diese Session war Phase-06-fokussiert. Bucket B (Sprint-Deferred) Items sind unverändert seit vor 2026-05-19. --- ## 9. Sofort-Sanity-Check für nächsten Agent ```bash # Im Repo-Root git log --oneline -5 # sollte mit 3afbb257 starten git status -s # sollte nur Prisma-generated zeigen pnpm -F @toolctrl/plugin-runtime test 2>&1 | tail -5 # sollte 168 tests passing bash scripts/build-plugin-audit-package.sh # sollte tar.gz erzeugen ``` Wenn alle 4 grün: Repo ist in dem Zustand der diesem Handoff entspricht. --- **Ende des Handoffs.** Bei Unklarheit den User fragen, nicht raten.