From 3543e07779b2bfda2b51dff8f113a66eda762d38 Mon Sep 17 00:00:00 2001 From: Kevin Janssen Date: Sat, 14 Nov 2026 16:27:22 +0100 Subject: [PATCH] docs: bind updater health design to preserved pending handoff --- docs/agent-updater-native-contracts.md | 6 ++- docs/agent-updater-proposal.md | 66 ++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 2 deletions(-) diff --git a/docs/agent-updater-native-contracts.md b/docs/agent-updater-native-contracts.md index 2afbf04..8a70ede 100644 --- a/docs/agent-updater-native-contracts.md +++ b/docs/agent-updater-native-contracts.md @@ -82,8 +82,10 @@ Manifest-/Artefakthashes und alle neun Testnamen geprüft. Proof-SHA256: Die tatsächliche VM-Ausführung erfolgte durch Root; der Verifier-Subagent führte weiterhin keine eigene SSH-/VM-Aktion aus. -Damit ist der **reine Linux-Prüfkern nativ qualifiziert**. Windows-Build und -native Windows-Units sind getrennt noch offen. Selbstupdateinstallation, +Damit ist der **reine Linux-Prüfkern nativ qualifiziert**. Der danach getrennt +ausgeführte Windows-GNU-Schritt bestand ebenfalls9/9; tatsächlicher Beleg und +Grenzen stehen in [Windows-Kernqualifikation](agent-updater-windows-contracts.md). +Selbstupdateinstallation, Releasekatalog/Streamingtransport, feste Plan-/Grant-/WebUI-Bindung, Updaterprozess und Code-/Pin-Aktivierung/Health/Rollback bleiben unverändert offen. Dieser Erfolg bescheinigt keinen vollständigen Agent-Autoupdater. diff --git a/docs/agent-updater-proposal.md b/docs/agent-updater-proposal.md index 1aa96e2..dcbf2a3 100644 --- a/docs/agent-updater-proposal.md +++ b/docs/agent-updater-proposal.md @@ -449,3 +449,69 @@ Updateversuch zu entscheiden. Diese Liste enthält keine neue Terminalengine, generischen Paketprovider, Keyrotationplattform, Restorefunktion oder weiteren Produktumfang. Alle genannten Dateien/Befehle/Abnahmen dieses Abschnitts sind **geplant, nicht ausgeführt**. + +## Geprüftes Runtimegate: eigener offener Versuch und Health + +Sourcebefund, **Entwurf ohne Produktänderung**: `HelperSync::apply` in +`crates/agent-core/src/helper_reconcile.rs:482` darf einen gültigen negativen +signierten Abgleich dauerhaft übernehmen. Die Startlease bleibt geschlossen: +`apply_inner` verlangt definitive Outcomes für sämtliche Zeilen und +`can_start` zusätzlich null offene `consumed.result IS NULL`-Zeilen +(`:575`, `:666`, `:696`). Deshalb darf Update-Health niemals allgemeines +`ready=true` voraussetzen oder trotz eigener offener Zeile erzeugen. + +Der normale Wiederabgleich macht gestartete unvollständige Versuche bewusst +unknown (`agent-core/src/reconcile.rs:233`, `server/src/synchronization.rs:717`) +und `ClientSync::confirm_helper` verweigert offene Helperwirkungen (`:127`). +Dies zu ignorieren wäre keine Healthimplementierung. Benötigt wird ein neuer, +ausdrücklicher **dauerhafter `pending/inflight`-Handoffvertrag** des genau +genehmigten Updateversuchs. Er muss kontrollierte Eigentümer-/Prozessübergaben +von einer tatsächlich unklaren Wirkung unterscheiden, ohne frühere Unknown- +Events, definitive Unknown-Outcomes, Startzeugen oder Deadlines umzuschreiben. +Fehlender Owner-/Handoff-/Zeitnachweis bleibt unknown und geschlossen; ein +späterer Healthbeleg heilt ihn nicht und berechtigt keinen erneuten Start. + +Windows hält `LedgerGuard` während der gesamten Helper-Dienstlebensdauer +(`agent-windows/src/helper_system.rs:222`, `:822`). Der separate Updater kann +denselben echten Lock daher nicht gleichzeitig erwerben und über den neuen +Helperstart halten. Empfohlener enger Pfad: alter Helper prüft Originalgrant +und verbraucht genau einmal, speichert immutable Delegations-/Ownerintent; +stabiler Updater übernimmt denselben Ledger ausschließlich während bestätigtem +Helperstop, prüft/tauscht Code+Pins und gibt die Ownership vor dem neuen +Helperstart ausdrücklich zurück. Der neue Helper hält danach wieder seinen +bestehenden Guard. Kein globaler Umbau zu schwächeren Locks pro Einzelrequest. + +Vorhandene IPC vertraut ausschließlich dem Netzwerkagenten: Linux verweigert +Root-Peers ausdrücklich (`privileged-helper/src/main.rs:92`), Windows bindet +Agent-Service-SID/SCM-PID/Peerimage (`agent-windows/src/helper_ipc.rs:227`). +Ein Updater darf sich nicht als dieser Agent ausgeben. Er benötigt eine neue +eng typisierte **lokale Participantbindung** mit festem eigenem Dienst, +UID/SID, tatsächlichem PID-/Image-/Prozessgeburts-/Policybeleg und ausschließlich +Original-Handoff, Healthbezug und Finalisierung dieses einen Versuchs. Root +oder SYSTEM allein sind kein ausreichender Peerbeleg. Bestehende ACL-/FileID- +Prüfungen dürfen dabei nicht stillschweigend gelockert werden. + +Gemeinsames erhaltenes Helperledger und aktueller Sync-Wirevertrag reichen für +die Historie grundsätzlich; eine zweite ungebundene Server-Journal-ID ist +für diesen Pfad nicht erforderlich. Ein negativer aktueller SignedSync ist +nur Kontrollkettennachweis. Zusätzlich vorgeschlagen: ein **evidenz-only** +signierter `UpdateHealthReceipt` mit eigener Domäne, Originalplan/Job/Versuch/ +Grant, Manifest/Codepaar/Pins, Ownernonce, Boot/Verbindung, tatsächlich +angewandtem SignedSync und frisch serverseitig gespeicherten Inventarbelegen. +Er ist weder ExecutionPermit noch Startlease, reaktiviert keine Genehmigung +und verlängert weder Originalstart- noch Health-/Gesamtdeadline. + +Erst nach unabhängigem lokalem Code-/Peer-/Intenterhaltungsnachweis und gültigem +Receipt dürfte der neue Helper das **noch ausstehende ursprüngliche** definitive +Outcome create-once speichern. Originale Signaturen/Events bleiben erhalten; +generisches Ersetzen eines vorhandenen Unknown-Outcomes ist ausdrücklich +ausgeschlossen (`ledger::persist_outcome`/Completion-CAS). Anschließend sollen +vorhandene Helper→Agent-Spiegelung und normaler signierter Abgleich die gleiche +Outcome-Bytefolge übernehmen und gezielt entsperren +(`agent-core/src/reconcile.rs:898`, `helper_reconcile.rs:616`). Die vorhandenen +Reboot-Sonderregeln für geänderte Outcomebytes werden nicht auf Updates +verallgemeinert (`helper_reconcile.rs:1312`, `reconcile.rs:1237`). + +Vor Applycode sind Pending-/Inflight-Lebenszyklus, Ownershipwechsel, neue lokale +IPC-/ACLbindung und die rein beweisende Receiptsemantik normativ zu prüfen. +Dieser Befund ist **keine Freigabe oder Implementierung** dieser Erweiterungen.