Correct sealed OCI load, observe host check, and Ubuntu npm

packages/vantio-install/artifacts/IMPLEMENTATION-REPORT.json

@@ -91,9 +91,9 @@
     "optics_cli_sha256": "82fe13ad6fc916ac67a670bd95fbf18b24389ecb383d81246e1d52cb96712a1f",
     "agent_sdk_npm": "0.2.4",
     "agent_sdk_py": "3.1.0",
-    "pe_source_commit": "fab81efc08110506ff90847495197e7051a253b5",
-    "pe_archive_sha256": "72719cf4c590805378188da38a0d43c540e6722328268bde3955f07d2c3a9128",
-    "pe_manifest_digest": "sha256:4d932b93bf4c20983142d5f9bff1ea060d9407a19a5e8c9f59db29f7a4122553",
+    "pe_source_commit": "06696d5020700693b0154c59d0e072a24f648378",
+    "pe_archive_sha256": "e0b19d557891b1ee8bbd20e702df11669d175e4083ef5bbe2f7077cf30093b5e",
+    "pe_manifest_digest": "sha256:8b40aec5c125043ec4278a14170677474c9ca31a7ae78e8496c40dffa69d0e19",
     "cli_package_tree_mutated": false
   },
   "tests": {

packages/vantio-install/docs/ARTIFACT-PATH.md

@@ -37,23 +37,25 @@ Optional Python sdist (only if included):
 - Path: `artifacts/optics/vantio_agent_sdk-3.1.0.tar.gz`
 - SHA-256: `9f991291d5e44a23e17a9b0d7db24f6e7048d4c76cf0a9c37e35ccbcfe999c4f`
 
-## Sealed Phantom Engine archive (customer staging name)
+## Sealed Phantom Engine archive
 
-Use a **customer staging** filename that does **not** embed internal lab aliases:
+Place the sealed tar under this basename. Apply opens that path and checks this SHA-256.
 
-- Path: `artifacts/phantom-engine/vantio-phantom-engine-customer-staging-fab81efc0811-linux-amd64.oci.tar`
-- SHA-256: `72719cf4c590805378188da38a0d43c540e6722328268bde3955f07d2c3a9128`
-- Source commit: `fab81efc08110506ff90847495197e7051a253b5`
-- Manifest digest: `sha256:4d932b93bf4c20983142d5f9bff1ea060d9407a19a5e8c9f59db29f7a4122553`
+- Path: `artifacts/phantom-engine/vantio-phantom-engine-pe-residuals-06696d5-linux-amd64.oci.tar`
+- SHA-256: `e0b19d557891b1ee8bbd20e702df11669d175e4083ef5bbe2f7077cf30093b5e`
+- Source commit: `06696d5020700693b0154c59d0e072a24f648378`
+- Manifest digest: `sha256:8b40aec5c125043ec4278a14170677474c9ca31a7ae78e8496c40dffa69d0e19`
 
-**Naming rule (GAP-CB-DEP-002):** the customer-visible archive basename is locked to the staging name above. Customer docs and checksums use that basename only. Do not substitute an internal lab alias, a shorter untagged alias, or any absolute path.
+That manifest digest is the digest inside the sealed tar. On Ubuntu 24.04, apply writes a temporary load archive when a layer is gzip and the manifest calls it an uncompressed tar, then `docker load` records the corrected manifest. The sealed file hash stays `e0b19d557891b1ee8bbd20e702df11669d175e4083ef5bbe2f7077cf30093b5e`.
+
+**Naming rule:** customer docs and checksums use the basename above. Do not substitute a shorter untagged alias or any absolute path.
 
 `artifacts/phantom-engine/PHANTOM-ARTIFACT-MANIFEST.json` must record the same commit, archive hash, and manifest digest. `SHA256SUMS` lists every file in the bundle. A mismatch stops `plan`.
 
 ### Example SHA256SUMS line
 
 ```
-72719cf4c590805378188da38a0d43c540e6722328268bde3955f07d2c3a9128  artifacts/phantom-engine/vantio-phantom-engine-customer-staging-fab81efc0811-linux-amd64.oci.tar
+e0b19d557891b1ee8bbd20e702df11669d175e4083ef5bbe2f7077cf30093b5e  artifacts/phantom-engine/vantio-phantom-engine-pe-residuals-06696d5-linux-amd64.oci.tar
 ```
 
 ## GHCR / registries
@@ -78,7 +80,7 @@ Rollback, uninstall, status, and verify-removal semantics remain as documented i
 
 | Field | Value |
 | --- | --- |
-| pe_source_commit | `fab81efc08110506ff90847495197e7051a253b5` |
-| pe_archive_sha256 | `72719cf4c590805378188da38a0d43c540e6722328268bde3955f07d2c3a9128` |
+| pe_source_commit | `06696d5020700693b0154c59d0e072a24f648378` |
+| pe_archive_sha256 | `e0b19d557891b1ee8bbd20e702df11669d175e4083ef5bbe2f7077cf30093b5e` |
 | published | `false` |
 | claim_ceiling | `INTERNAL_CLEAN_HOST_PROOF` |

packages/vantio-install/docs/INSTALL.md

@@ -22,4 +22,8 @@ A customer apply on the host that will keep the node uses both gates and the pla
 
 `<hex>` is the SHA-256 of that `PLAN.json` file. The installer recomputes the hash, checks the transaction id, and checks the artifact bytes again before each change. A mismatch stops the command. The sealed Phantom Engine tip, archive hash, and manifest digest stay the ones recorded for this package.
 
-Apply is finished only when `state` is `HEALTHY` or `DEGRADED` and `HEALTH.json` records that result. `APPLIED` means the steps ran and health is not confirmed yet. A process exit of 0 from Docker, npm, or pip is not that result. After the Optics npm install, the host check requires `<prefix>/bin/vantio` and the pinned CLI version (`vantio --version`, or the installed package manifest when the binary does not print a version). After the Agent SDK npm install, the host check requires `<prefix>/lib/node_modules/@vantio/agent-sdk` and the pinned version in that package manifest. After the Agent SDK pip install, the host check requires the `vantio` module under the prefix and the pinned version. Debian and Ubuntu pip write that module at `local/lib/python3.X/dist-packages`. An upstream prefix layout writes it at `lib/python3.X/site-packages`. When the module does not declare a version, the check reads the matching dist-info metadata. `install_agent_sdks` is checkpointed only after both SDK checks pass. Before the observe-only Phantom Engine container starts, the installer loads AppArmor profile `vantio-pe-observe` and passes `--security-opt apparmor=vantio-pe-observe`. The same start bind-mounts host `/sys/fs/bpf` and host `/sys/kernel/tracing`. Preflight records the tracing mount as PF-TRACEFS and blocks when that directory is missing or empty. The host check for that container requires the process to be running under that profile.
+Apply loads the sealed Phantom Engine OCI tar with `docker load`. On Ubuntu 24.04 the default Docker image store reads the layer media type and unpacks from that. When the manifest says a layer is an uncompressed tar and the bytes are gzip, that unpack stops with `archive/tar: invalid tar header`, and `docker load` can still exit 0. Apply writes a temporary archive in the stage directory with the media type set to match the bytes, then loads that file. The sealed file you checked stays the file you hashed. Docker keeps the storage driver Ubuntu installed. Preflight records this as `PF-OCI-LOAD`. A `docker load` that prints an unpack error fails the install, even when docker exits 0.
+
+Apply is finished only when `state` is `HEALTHY` or `DEGRADED` and `HEALTH.json` records that result. `APPLIED` means the steps ran and health is not confirmed yet. A process exit of 0 from Docker, npm, or pip is not that result. After the Optics npm install, the host check requires `<prefix>/bin/vantio` and the pinned CLI version (`vantio --version`, or the installed package manifest when the binary does not print a version). After the Agent SDK npm install, the host check requires `<prefix>/lib/node_modules/@vantio/agent-sdk` and the pinned version in that package manifest. After the Agent SDK pip install, the host check requires the `vantio` module under the prefix and the pinned version. Debian and Ubuntu pip write that module at `local/lib/python3.X/dist-packages`. An upstream prefix layout writes it at `lib/python3.X/site-packages`. When the module does not declare a version, the check reads the matching dist-info metadata. `install_agent_sdks` is checkpointed only after both SDK checks pass. Before the observe-only Phantom Engine container starts, the installer loads AppArmor profile `vantio-pe-observe` and passes `--security-opt apparmor=vantio-pe-observe`. The same start bind-mounts host `/sys/fs/bpf` and host `/sys/kernel/tracing`. Preflight records the tracing mount as PF-TRACEFS and blocks when that directory is missing or empty. The host check for that container reads the container after `docker run -d` returns. That command exits 0 when the daemon accepts the container, including when the process has already stopped. A stopped container is not verified. A detached container that is still starting is read again until the loader process is visible, the known bpffs pins are present, and clsact is on the interface, or until that wait ends. A detached container that reaches that state is verified. A container that stays up without those facts is not verified.
+
+On Ubuntu 24.04 the `nodejs` package does not include npm. When npm is already on `PATH`, `ensure_node` runs `npm --version`. When npm is missing and the installer is root, `ensure_node` installs the Ubuntu `npm` package before the Optics CLI install. When npm is missing and the installer is not root, `plan` stops and `PLAN.json` names that package.

packages/vantio-install/docs/LIMITATIONS.md

@@ -20,7 +20,7 @@ The sealed Phantom Engine archive, manifest digest, and Optics package versions
 
 Phantom Engine media are sealed-byte placement only, as `ARTIFACT-PATH.md` describes. They are not fetched, and they are not published. `published` stays false. GHCR is not a Phantom Engine source. The claim ceiling stays `INTERNAL_CLEAN_HOST_PROOF`.
 
-Live changes on a host run only when you set `VANTIO_INSTALL_ALLOW_LIVE=1` and pass `--i-accept-live-mutations` on `apply`, `rollback`, or `uninstall`. Either one alone stops before any host change and the command returns `FAILED_SAFE`. With both set, the command still stops unless the plan hash matches, the sealed artifacts match, the host is x86_64 with kernel BTF, the mode is observe-only, and rollback and residual checks are in the plan. The command runs an allowlisted argv list. It does not use a shell string. Exit 0 from one of those commands is not enough; the installer reads the host again before it records the step as verified.
+Live changes on a host run only when you set `VANTIO_INSTALL_ALLOW_LIVE=1` and pass `--i-accept-live-mutations` on `apply`, `rollback`, or `uninstall`. Either one alone stops before any host change and the command returns `FAILED_SAFE`. With both set, the command still stops unless the plan hash matches, the sealed artifacts match, the host is x86_64 with kernel BTF, the mode is observe-only, and rollback and residual checks are in the plan. The command runs an allowlisted argv list. It does not use a shell string. Exit 0 from one of those commands is not enough; the installer reads the host again before it records the step as verified. For the observe container, that read distinguishes a stopped process from a detached container that is still starting. The check waits until the loader is running with the known bpffs pins and clsact on the interface, or until the wait ends. A stopped process is not verified. On Ubuntu 24.04, `ensure_node` installs the Ubuntu `npm` package when Node.js 18 or newer is present, npm is missing, and the process is root. Otherwise a missing npm binary stops the plan and the plan names that package. The allowlist adds `apt-get` only for `apt-get install -y --no-install-recommends npm`.
 
 The live privilege check accepts effective uid 0 only. `privilege_mode` `sudo` with `sudo` on `PATH`, and `privilege_mode` `docker_group` with write access to `/var/run/docker.sock`, are recorded facts and are not a live grant. `privilege_mode` `UNKNOWN` blocks `PF-DOCKER-PERM`. When the effective uid is not 0, the live command returns `FAILED_SAFE` and the message `Live mutations need effective root. sudo on PATH is not privilege.` `PREFLIGHT.md` records the symptoms. `sudo` is not an allowlisted executable. Raw `docker` and raw `sudo docker` outside the installer argv list are forbidden. The installer does not insert `sudo` in front of `docker`. A live residual check reports `RESIDUAL_FOUND` when something from that scope is still on the host. From that state, the same dual-gated rollback, or uninstall with `--scope optics` or `--scope all`, removes a leftover Optics CLI or Agent SDK tree under the prefix. Rollback, or uninstall with `--scope pe` or `--scope all`, also unlinks the known bpffs pin names when they are still present. Apply stays refused until `verify-removal` reports an empty residual list.