Keep node workloads running across Runtime generations

CONTRIBUTING.md

@@ -790,10 +790,9 @@ read.
 
 All sandbox writes require the observed generation, including initial POST at
 zero; reject stale state before provider preparation, reset or no-op checks, and
-repeat it under the committing row lock. Same-provider PUT currently requires no
-reset. Node PUT keeps the zero-held-resource guard until the complete multi-generation
-node protocol ships. E2B changes apply online without retiring nodes, tokens or the
-owner epoch. A different backend, E2B team or unspecified old selection requires reset.
+repeat it under the committing row lock. Same-provider PUT advances the target
+without draining execution or retiring nodes, tokens or the owner epoch. Node
+providers prepare independently and keep their old qualified serving pin. A different backend, E2B team or unspecified old selection requires reset.
 Preserve historical allocation ownership and placement, never migrate a Session.
 
 Persist immutable allocation and placement deployment generations, distinct from
@@ -802,8 +801,38 @@ Keep superseded specification/build rows without credentials while current, owne
 an unreleased allocation/placement, or pinned by any nonremoved node. A durable node
 serving pin survives offline state and zero resources. GC uses the deployment lock
 and bounded pages; reset clears pins only after release. Never downgrade facts needed
-for generation routing. Node readiness and no-gap placement remain PR-N work; do not
-relax the node PUT guard or introduce half a protocol.
+for generation routing. Bind node readiness to exact generation, current connection
+and owner epoch. Promote a durable pin only for readiness of the then-current target
+under deployment serialization. Late superseded readiness cannot acquire a pin.
+Filter online/readiness/address/capacity before preferring the newest eligible pin;
+newest-full must not mask older-free. Route Create, restore and cleanup through the
+immutable allocation/placement generation. V1 keeps its qualified enrolled fallback.
+
+Use sparse v2 control batches of at most eight entries with no lifetime cap. Omitted
+facts never authorize deletion. Correlate whole retention grants to connection,
+epoch, sequence, generation and digest; recheck queued/inflight/helper references.
+Permanent generation flock files survive updates and GC. Before any helper starts,
+the installer durably binds the original inode to installation/generation/specification
+identity; Python and Go openers verify it after every restart and never adopt a
+replacement or missing record. Preparation plans stay distinct from write-once final
+provider configurations: pending-only entries may recover or collect under Core
+authority, never serve. Resolve Docker's supported local image ID before publication.
+Only transfer/checksum/provenance errors report runtime_download_failed; preserve
+other fixed causes without parsing native error text. Retained Runtime bytes and
+the console's exact-release HTTP allowlist must agree. See
+`contracts/agents-api/node-generation-protocol.md` for recovery, immutable artifacts
+and the conservative v1 legacy-helper retention boundary.
+Interrupted node collection keeps an exact private generation journal and immutable
+configuration. Restart treats it only as a candidate for a fresh correlated Core
+drop grant, never as preparation or serving readiness. Persist native cleanup
+before removing its executable and durable file cleanup before the dropped marker;
+CLI errors and unknown native ownership cannot establish absence. Docker daemon
+images are shared host content, so automatic node GC retains them; only the host
+administrator can establish whole-host authority to remove them. Microsandbox
+image GC remains scoped to the installation-private store. Fresh nodes persist
+verified original Runtime file ownership separately from the host program; collect
+only exact unreferenced Runtime paths, keeping program, identity, base configuration
+and manifests readable across interrupted cleanup and restart.
 
 Use one E2B classifier. Omitted key preserves the current key; identical selection
 with omitted key is a no-op. Explicit key submission, including identical bytes,
@@ -829,9 +858,9 @@ Project rollout and reset from the same database snapshot. Old retained resource
 alone never imply preparation or high-frequency polling. Rollout state is settled
 unless actual target preparation is active. Offline/unconfirmed nodes are unknown;
 only exact current connection/epoch/generation readiness is ready. A durable pin is
-not connectivity. Fixed diagnostics alone may explain failed preparation. PR-G reports
-no synthetic preparing state; old online v1 nodes can be update_required while their
-valid pin remains available to the eventual PR-N placement contract.
+not connectivity. Fixed diagnostics alone may explain failed preparation. Report
+preparing only from an actual target observation; an online v1 node can be
+update_required while its valid pin remains available for admission.
 
 Reset is durable execution state, advanced by the existing manager outside its
 counted work. Serialize start, escalation, cancel, setup, update and finalization

apps/docs/content/docs/hosted-providers.mdx

@@ -266,14 +266,36 @@ WebSocket doesn't pass the reverse proxy.
 
 ## Change the sandbox backend or size
 
-Changing backend type requires an explicit reset. Docker and microsandbox size or
-Runtime edits currently require zero held resources; node online updates are not
-available yet. These changes retire every node. Retired nodes drop out of the list, so there is nothing to
-remove in Web: on each host, run the [uninstall command](#remove-a-node) (Core no longer
-accepts the node, so it needs no `--force`), then add the host again with a new command.
+Changing backend type requires an explicit reset. Same-provider Docker and
+microsandbox size or Runtime edits advance the target generation without retiring
+nodes or moving existing Sessions. Version 2 nodes prepare the target independently;
+existing allocations and suspended VMs keep their original generation. A qualified
+older serving generation can still accept new Sessions when it has capacity,
+including while a newer target is preparing or has failed.
+
+Version 1 nodes report `update_required` for a newer target while retaining their
+qualified original serving generation. Run the verified current installer with
+`--update`, the same installation ID, Core/source URLs and original installation
+user (or sudo mode); do not provide another enrollment token. The update preserves
+node identity, retained Runtime files and running VMs. Its original v1 generation
+is conservatively retained locally because old helpers were not protected by the
+new generation lock. This retained disk usage is not reported as completed GC.
+
+Fresh v2 preparation keeps a private recovery plan until the actual provider image
+identity is resolved and its final configuration is published. Restart does not
+serve a pending or partly collected generation. Generation lock identity is durable:
+if a lease or its identity record is missing or replaced, preserve the installation
+for inspection. Do not delete records, recreate lock files or re-enroll to bypass
+that refusal; a process restart does not prove that older helpers have stopped.
+
+Automatic Docker generation GC removes only installation-owned generation/release
+files. Shared daemon images remain; a host administrator may remove them only after
+confirming no installation still needs them. Microsandbox image cleanup remains
+scoped to the installation's private native store and verified ownership receipts.
+
 The [operator reference](https://github.com/MiniMax-AI/parsar-core/blob/f36ac3592bfe9f77a2172680aa52b14c6f525062/services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-reset)
-describes today's procedure and API. Same-team E2B edits have a separate online
-Core API path and do not involve node installation.
+describes reset and API behavior. Same-team E2B edits have a separate online Core
+API path and do not involve node installation.
 
 
 ## Remove a node added before the rename

apps/docs/content/docs/public-api.mdx

@@ -84,8 +84,8 @@ the Core key or a Project API key.
 - [Core OpenAPI](https://github.com/MiniMax-AI/parsar-core/blob/f36ac3592bfe9f77a2172680aa52b14c6f525062/contracts/agents-api/core.openapi.yaml): generated `/core/v1`
   routes, all authenticated by the Core key.
 - [Machine connection OpenAPI](https://github.com/MiniMax-AI/parsar-core/blob/f36ac3592bfe9f77a2172680aa52b14c6f525062/contracts/agents-api/runtime.openapi.yaml):
-  generated `/api/v1` sandbox node routes. The node WebSocket and the private
-  daemon transport are described in the node and Runtime credential guides.
+  generated `/api/v1` sandbox node routes. The node WebSocket is described in the [generation protocol](https://github.com/MiniMax-AI/parsar-core/blob/f36ac3592bfe9f77a2172680aa52b14c6f525062/contracts/agents-api/node-generation-protocol.md); the private
+  daemon transport is described in the Runtime credential guide.
 - [Administrator contract](https://github.com/MiniMax-AI/parsar-core/blob/f36ac3592bfe9f77a2172680aa52b14c6f525062/contracts/agents-api/admin-api.md): Project/key
   lifecycle, resources, explicit hosted Session archive, summary,
   errors/deletion preconditions, audit and historical copy provenance.

apps/docs/content/guide-sources.json

@@ -8,11 +8,11 @@
     "docs/configuration.md": "e911757a03fbce4b803a284c8bb40bdb7000ca2f70e27938706dcdcd74bc7f9a",
     "docs/web/core-connection.md": "46f86520e70bf41079708e2c398655aa9087ad9488c8e661d9a73035d11098c4",
     "docs/getting-started/quickstart.md": "5effeffcfb343f7939910f0c1758e1492d49e7bd66c409b1819cefe67af592d7",
-    "docs/api/README.md": "b2b4c7fdf9fbde62d2169014180698a77c671f85c1c68c2e5de0e73bbdf3b13c",
+    "docs/api/README.md": "3c590ca05a07b2bea5ab88ab67719741f8a73a28056ec7d943a5912eb5f9052f",
     "contracts/agents-api/execution-tools.md": "e0b61f6c0c236c362186c5f6d0ad69a16dd8a8d9afabe1329a1fe22e5f4a71e9",
     "docs/api/public-agent-api.md": "18829b366bd2e49fe5beb76dc8a709bc1aa8e35d4fbfd2484a0c52b46cf75417",
     "contracts/agents-api/environments.md": "89ffc903ee44d00ee87c16950202a3ca4c8345160780dcdd4ed2a71b25b1c2dc",
-    "docs/getting-started/nodes.md": "71c422ba23b274b038a841dfdc960649c29a4409454f49f8916044fa88041458",
+    "docs/getting-started/nodes.md": "fd858830647e16554f7fef1381a0329e1b020f37fb7e826204e3ac5816e050c7",
     "docs/getting-started/self-hosted.md": "3f1b402cf28bb320ba414eaf36110e9df4d792b81da0456a3c42d469357d8d99",
     "apps/web/public/onboarding/monitor-en.webp": "29dc220cb1250c7016b7c4bf7f30e9510b07c07b814a48c3aa9303b2d76f20b2",
     "docs/web/README.md": "9fce295f6f6ff04acefe338679c1e54723e123dd0027a778202adfa9ab95b6c4",
@@ -36,15 +36,15 @@
     "content/docs/bootstrap-projects-keys.zh.mdx": "509b4dcea4c865d6834bcaef78baa681180d48274931230f958a39e46011c88f",
     "content/docs/quickstart.mdx": "4ebc8ac16df66042e816ff51cf6672d8a85f44e119211efba584025666dce845",
     "content/docs/quickstart.zh.mdx": "c5f119b100b102918a45763834d0ed7fd436479fb411e16a62a408411dbcb3e1",
-    "content/docs/public-api.mdx": "ee1be51bf72bc48809efc0af8a460c26ae1cbf962771e132ec521447b89d5479",
+    "content/docs/public-api.mdx": "da6aa71753cc84081fba9ae03491717042369a12ea94037fc532f5f1f69d2319",
     "content/docs/public-api.zh.mdx": "fb0efb9be2fba3f4a3dc71bf053d2c7eddffbfe010f59fa5a1ae60a3f068545b",
     "content/docs/agents-and-tools.mdx": "b8cc50792e579cbf66bcc597685b745d8721266970b75e928d8edee2ce11b08b",
     "content/docs/agents-and-tools.zh.mdx": "cc8d4e0ef0ea894f068f3bbd143d5ee70c6346bf98f425b1d5fe07ec3931f128",
     "content/docs/sessions.mdx": "8dba8c2a94ef5e95fde6f53e7af3cc481e4d3c5db71815372f01ddd1bf729316",
     "content/docs/sessions.zh.mdx": "b1b1a7f8aacd9a902320f9692173ede24036124f85761cf02f23ef3ef2bcc4c1",
     "content/docs/environments-and-files.mdx": "0fce7c8806d532d64eff6319bba7d0a8e44da46f888d224644b3ab5c23428c41",
     "content/docs/environments-and-files.zh.mdx": "ee64577220a798f023b330c65302c14438f25a34a78c4e36144bfdb4304a3ae5",
-    "content/docs/hosted-providers.mdx": "02a39c9fd07c7adfc065ca9510136362503c791334d8b084b7b9dc0958eec81b",
+    "content/docs/hosted-providers.mdx": "3a0560420c7564acb273c4accf278cee466ded577ab6b98909cd5f1f9127380e",
     "content/docs/hosted-providers.zh.mdx": "f54d80d6e65596dca6b20262abaa3dcb5af245227ffad146fcaed4bd69454dee",
     "content/docs/self-hosted-execution.mdx": "34877624962b24c22e8371ebd2e2f83bbf5a0d004c74d5d9b5db57f5133b692c",
     "content/docs/self-hosted-execution.zh.mdx": "f11d34ce30d48039376256474bc9509a508a2f6b9906f49b5cf6e396707ae5c0",

apps/docs/openapi/core-api.yaml

@@ -5010,6 +5010,7 @@ components:
             - provider_unavailable
             - docker_unavailable
             - docker_limits_unsupported
+            - runtime_download_failed
             - runtime_image_unavailable
             - kvm_unavailable
             - microsandbox_artifacts_unavailable
@@ -5102,6 +5103,7 @@ components:
             - provider_unavailable
             - docker_unavailable
             - docker_limits_unsupported
+            - runtime_download_failed
             - runtime_image_unavailable
             - kvm_unavailable
             - microsandbox_artifacts_unavailable
@@ -5211,6 +5213,15 @@ components:
     store.SandboxNodeRollout:
       properties:
         diagnostic:
+          enum:
+            - provider_unavailable
+            - docker_unavailable
+            - docker_limits_unsupported
+            - runtime_download_failed
+            - runtime_image_unavailable
+            - kvm_unavailable
+            - microsandbox_artifacts_unavailable
+            - capacity_insufficient
           type: string
         ready_generation:
           anyOf:

apps/docs/openapi/runtime-api.yaml

@@ -17,6 +17,11 @@ paths:
           description: Retained node UUID
           in: header
           name: X-OAC-Node-ID
+        - schema:
+            type: integer
+          description: Exact kept generation (registered nodes only); omitted reads the current target
+          in: query
+          name: generation
       responses:
         '200':
           description: OK

apps/docs/openapi/sources.json

@@ -1,8 +1,8 @@
 {
   "sources": {
     "contracts/agents-api/openapi.yaml": "a8896e8b67d78ed0608c7cc5636077ec33f4b4895a04bd6cfb8b038afe941e01",
-    "contracts/agents-api/core.openapi.yaml": "e9b159a84afef28d086f5c285d298834b9f647ae8e7c14457117572ee01cc3ab",
-    "contracts/agents-api/runtime.openapi.yaml": "b3fb025b20a0bcf4635d60339479b2b07f6dbed80f51e72f40a63b31e42b5f4a"
+    "contracts/agents-api/core.openapi.yaml": "5594e256e06a608d0be4232e395acbe0bb1d258ff4749112d2f5d85ff05e3c54",
+    "contracts/agents-api/runtime.openapi.yaml": "23852205d3b45892f2de9ecf3d52518c0dd0808962c0c512f219b565aa7ccef2"
   },
   "outputs": {
     "content/docs/api-reference/agents.mdx": "1f7697959e9c52c9d24fbe70e116e807f49912b9a27ac638b86782e2f326af44",
@@ -40,11 +40,11 @@
     "content/docs/api-reference/core/vaults.mdx": "12d0aac96cd4a3472ef4eaa287f7945f78862017956e79bfc3ed0ef8e772e78a",
     "content/docs/api-reference/core/credentials.mdx": "27d586b9a8fd738b9947802f32c80458195370252886bc26abedccf2125ee981",
     "content/docs/api-reference/core/sandbox-manager.mdx": "6be7c52e057365949f0247c18c710561d680847a955f78f1bbe57825d4d5f549",
-    "openapi/core-api.yaml": "f6ba52edeb5c70c11f230da401e60cc442e7ac6760f63013b2293ba045786b5b",
+    "openapi/core-api.yaml": "d0fcaa48655905f72d7f8a0a58208e56d88570ebd882b08795625ebc8c4308d3",
     "content/docs/api-reference/core/meta.json": "588b163ed2de2100b0f8376688274f80698a6bf6ac037eef56d17c93fa8a5062",
     "content/docs/api-reference/core/index.mdx": "ddf0a8d87a6c21761beac703a32f2a40486a1c74abb341bd726f40c44a866405",
     "content/docs/api-reference/machine/sandbox-node.mdx": "5b367a08d43cea82686345d2ba1c75cc90627a7b2970fe42a0df9d77fb3e1e80",
-    "openapi/runtime-api.yaml": "bca127037ffb1e132e7f26bffada5e3da70f4b2534926a04e1e65029d885afe9",
+    "openapi/runtime-api.yaml": "32adc347bfa8effd501b9c0089a2a4d114cab43d5c26c7947b3a79fdc6ae1f1a",
     "content/docs/api-reference/machine/meta.json": "12a1a6534c1cae32918282da2110e4b64c43f17abb868486b5eff50ceb0b01c1",
     "content/docs/api-reference/machine/index.mdx": "792c1ce86a6653943021eb5cd03a2c6b5c604f7f012da5ef06f3ffa027b12973"
   }

contracts/agents-api/core.openapi.yaml

@@ -976,6 +976,7 @@ definitions:
           - provider_unavailable
           - docker_unavailable
           - docker_limits_unsupported
+          - runtime_download_failed
           - runtime_image_unavailable
           - kvm_unavailable
           - microsandbox_artifacts_unavailable
@@ -1066,6 +1067,7 @@ definitions:
           - provider_unavailable
           - docker_unavailable
           - docker_limits_unsupported
+          - runtime_download_failed
           - runtime_image_unavailable
           - kvm_unavailable
           - microsandbox_artifacts_unavailable
@@ -1167,6 +1169,15 @@ definitions:
   store.SandboxNodeRollout:
     properties:
       diagnostic:
+        enum:
+          - provider_unavailable
+          - docker_unavailable
+          - docker_limits_unsupported
+          - runtime_download_failed
+          - runtime_image_unavailable
+          - kvm_unavailable
+          - microsandbox_artifacts_unavailable
+          - capacity_insufficient
         type: string
       ready_generation:
         description: Durable serving-generation pin; online and provider_ready still gate placement.