feat(nvx): add internal Phase 3c lifecycle manager

[lpcox]

Summary

• add an internal NvxManager that owns stale cleanup, preflight journaling, dedicated VMM identity allocation, collision-safe network reservation, filesystem/cgroup setup, device ACL scope, launch hooks, confinement verification, and reverse-order cleanup
• add a durable NVX cleanup registry/store with root-owned mode-0600 records, atomic updates and claims, exact process/file/interface identities, pending-account recovery, and record retention when cleanup is ambiguous or incomplete
• bind NVX network names to the canonical run layout while preserving the shared microVM reservation allocation, and make stale cleanup target the exact installed bridge-forward rule
• require injected launch executors to complete launcher, OpenVMM readiness, and live-confinement hooks before returning success
• keep the default launch executor fail-closed because the pinned nvx.py artifact layout and pre-workload readiness/TAP-selection ABI are not yet verified
• keep NVX absent from the CLI and runtime registry

Why

The successful Phase 3b live-KVM run proved the individual account, ACL, cgroup, namespace-policy, and cleanup primitives, but no component owned their complete lifecycle or persisted enough exact ownership evidence for crash recovery. This PR adds that internal lifecycle boundary without prematurely exposing NVX as a selectable runtime.

The review also confirmed two upstream blockers that prevent an honest production launch today:

1. The flat attested snapshot does not satisfy pinned nvx.py's required scripts/nvx_tools, openvmm/target/release, and build/ layout.
2. The one-shot interface lacks a reviewed pre-workload readiness hook and explicit contract for selecting the AWF-created TAP.

The manager therefore refuses the default launch rather than falling back to the unconstrained Phase 2 adapter.

Validation

• npm test -- --runInBand — 379 suites passed, 6,075 tests passed, 4 skipped
• npm run type-check
• npm run lint -- --quiet
• npm run build
• npx --no-install markdownlint-cli2 docs/nvx-security-design.md
• git diff --check

Evidence

Builds on the successful NVX Phase 3b live-KVM validation run: https://github.com/github/gh-aw-firewall/actions/runs/35680067333

[github-actions]

Documentation Preview

Documentation has been built for this PR.

Download preview artifact

To view locally:

1. Download the docs-preview-pr-8867 artifact from the workflow run
2. Unzip and open index.html in your browser

Built from commit 1d2e8a4

[Copilot]

Copilot review overview

🔵 Needs a closer look

The security-critical lifecycle and crash-recovery logic spans privileged processes, identities, networking, ACLs, cgroups, and destructive cleanup operations.

Review effort: Balanced
Findings: None

What changed in this PR

Adds the internal Phase 3c NVX lifecycle boundary, coordinating durable recovery records, isolated resource setup, launch/confinement hooks, and reverse-order cleanup while keeping production launch and CLI registration disabled.

Changes:

• Introduces NvxManager for preflight, identity, network, filesystem, cgroup, execution, verification, and cleanup orchestration.
• Adds schema-v2 cleanup records plus an atomic root-owned cleanup store and stale-resource reaper.
• Supports canonical NVX network naming while preserving shared microVM allocation data, with updated tests and security documentation.

File	Description
src/​nvx/​runtime-lifecycle.ts	Binds network plans to canonical NVX run identities and updates egress endpoint syntax.
src/​nvx/​runtime-lifecycle.test.ts	Updates lifecycle tool fixtures.
src/​nvx/​preflight.ts	Adds required host tools and snapshot lifecycle hooks.
src/​nvx/​manager.ts	Implements the internal NVX lifecycle manager.
src/​nvx/​manager.test.ts	Tests ordering, rollback, fail-closed launch, and confinement handling.
src/​nvx/​index.ts	Exports manager and cleanup APIs.
src/​nvx/​cleanup-store.ts	Implements private atomic record persistence and claims.
src/​nvx/​cleanup-registry.ts	Implements journaling and exact-identity stale cleanup.
src/​nvx/​cleanup-registry.test.ts	Tests stale cleanup, account recovery, and claim exclusion.
src/​nvx/​cleanup-record.ts	Expands and validates cleanup schema v2.
src/​nvx/​cleanup-record.test.ts	Updates cleanup-record fixtures for schema v2.
src/​microvm/​network-reservation.ts	Adds validated post-allocation plan transformation.
docs/​nvx-security-design.md	Documents the Phase 3c boundary and launch blockers.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	93.12%	92.13%	📉 -0.99%
Statements	91.70%	90.67%	📉 -1.03%
Functions	91.83%	90.19%	📉 -1.64%
Branches	85.26%	84.08%	📉 -1.18%

📁 Per-file Coverage Changes (5 files)

File	Lines (Before → After)	Statements (Before → After)
src/nvx/cleanup-record.ts	85.1% → 84.1% (-0.99%)	84.4% → 81.2% (-3.18%)
src/nvx/runtime-lifecycle.ts	84.5% → 84.1% (-0.37%)	78.4% → 78.2% (-0.22%)
src/nvx/preflight.ts	64.3% → 64.9% (+0.63%)	63.1% → 63.8% (+0.64%)
src/microvm/network-reservation.ts	52.0% → 52.8% (+0.85%)	50.2% → 51.1% (+0.86%)
src/log-directory-setup.ts	96.2% → 100.0% (+3.78%)	96.3% → 100.0% (+3.71%)

✨ New Files (3 files)

• src/nvx/cleanup-registry.ts: 41.3% lines
• src/nvx/cleanup-store.ts: 70.6% lines
• src/nvx/manager.ts: 82.1% lines

---

Coverage comparison generated by scripts/ci/compare-coverage.ts

[github-actions]

Chroot tests passed! Smoke Chroot - All security and functionality tests succeeded.

Tested by Smoke Chroot

[github-actions]

📡 Smoke OTel Tracing completed. All tracing scenarios validated. ✅

📡 OTel tracing validated by Smoke OTel Tracing

[github-actions]

🛡️ Smoke Copilot Network Isolation confirmed the egress allowlist is enforced. ✅

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• example.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "example.com"

See Network Configuration for more information.

🛡️ Egress verdict from Smoke Copilot Network Isolation

[github-actions]

✅ Smoke Copilot BYOK completed. Copilot BYOK mode operational. 🔓

🔑 BYOK report filed by Smoke Copilot BYOK

[github-actions]

📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤

📰 BREAKING: Report filed by Smoke Copilot

[github-actions]

✨ The prophecy is fulfilled... Smoke Codex has completed its mystical journey. The stars align. 🌟

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• msfeed25.pkgs.visualstudio.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "msfeed25.pkgs.visualstudio.com"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex

[github-actions]

🚀 Security Guard has started processing this pull request

[github-actions]

Smoke Cloud Hypervisor completed. Cloud Hypervisor + Copilot passed.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• example.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "example.com"

See Network Configuration for more information.

Cloud Hypervisor + Copilot smoke test by Smoke Cloud Hypervisor

[github-actions]

❌ Smoke Copilot BYOK AOAI (api-key) reports failed. AOAI BYOK (api-key) mode investigation needed...

🔑 BYOK (AOAI api-key) report filed by Smoke Copilot BYOK AOAI (api-key)

[github-actions]

❌ Smoke Gemini reports failed. Facets need polishing...

💎 Faceted by Smoke Gemini

[github-actions]

🔌 Smoke Services — All services reachable! ✅

🔌 Service connectivity validated by Smoke Services

[github-actions]

✅ Smoke Claude passed

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• api.anthropic.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "api.anthropic.com"

See Network Configuration for more information.

Generated by Smoke Claude for #8867

[github-actions]

✅ Build Test Suite completed successfully!

Generated by Build Test Suite for #8867

[github-actions]

❌ Smoke Copilot BYOK AOAI (Entra) reports failed. AOAI BYOK (Entra) mode investigation needed...

🪪 BYOK (AOAI Entra) report filed by Smoke Copilot BYOK AOAI (Entra)

[github-actions]

@lpcox Smoke Test Results:

• MCP: ✅ (PR Correlate upstream 400s with request tool surface and negotiate MCP protocol version #8861 verified)
• HTTP: ✅ (200)
• File I/O: ✅

Overall: PASS

📰 BREAKING: Report filed by Smoke Copilot
_{Add label ready-for-aw to run again}

[github-actions]

EGRESS_RESULT allow=pass deny=pass

✅ Allowed domain (github.com) reachable: allowed=200
✅ Non-allowed domain (example.com) blocked: OK: example.com was blocked (CONNECT tunnel failed, 403)

Overall: PASS

@lpcox

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• example.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "example.com"

See Network Configuration for more information.

🛡️ Egress verdict from Smoke Copilot Network Isolation
_{Add label ready-for-aw to run again}

[github-actions]

Smoke Test: Cloud Hypervisor + Copilot

1. list_pull_requests (github/gh-aw-firewall, merged, limit 1): PASS ✅
2. curl https://github.com: 200 → PASS ✅
3. Write/read temp file /tmp/gh-aw/agent/smoke-cloud-hypervisor-*.txt: PASS ✅
4. curl (example.com/redacted) (should be blocked): 000 → PASS ✅

Overall: ALL CHECKS PASSED

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• example.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "example.com"

See Network Configuration for more information.

Cloud Hypervisor + Copilot smoke test by Smoke Cloud Hypervisor
_{Add label ready-for-aw to run again}

[github-actions]

Smoke Test: Claude Engine Validation

Check	Status
API	✅ PASS
gh CLI	✅ PASS
File	✅ PASS

Overall result: PASS

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• api.anthropic.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "api.anthropic.com"

See Network Configuration for more information.

Generated by Smoke Claude for #8867 · claude · haiku45 · 55.8 AIC · ⊞ 4.7K · ◷
_{Add label ready-for-aw to run again}

[github-actions]

Smoke Test: Copilot BYOK (Direct Mode) ✅ PASS

• ✅ MCP connectivity (2 merged PRs retrieved)
• ✅ github.com reachability (HTTP 200)
• ✅ File write/read test (smoke-test-copilot-byok.txt)
• ✅ BYOK inference path (direct COPILOT_PROVIDER_API_KEY via api-proxy → api.githubcopilot.com)

Mode: Direct BYOK (COPILOT_PROVIDER_API_KEY) via api-proxy sidecar to api.githubcopilot.com

🔑 BYOK report filed by Smoke Copilot BYOK
_{Add label ready-for-aw to run again}

[github-actions]

Chroot Version Comparison Results

Runtime	Host Version	Chroot Version	Match?
Python	Python 3.12.14	Python 3.12.14	✅ YES
Node.js	v24.21.0	v22.23.2	❌ NO
Go	go1.22.12	go1.22.12	✅ YES

Overall: FAILED — Node.js version mismatch between host and chroot environment. The smoke-chroot label was not added since not all tests passed.

Tested by Smoke Chroot
_{Add label ready-for-aw to run again}

[github-actions]

Smoke Test: Services Connectivity

• Redis PING: ✅ (PONG)
• Postgres pg_isready: ✅ (accepting connections)
• Postgres SELECT 1: ✅ (1)

Overall: PASS

🔌 Service connectivity validated by Smoke Services
_{Add label ready-for-aw to run again}

[github-actions]

🏗️ Build Test Suite Results

Ecosystem	Project	Build/Install	Tests	Status
Bun	elysia	✅	1/1 passed	✅ PASS
Bun	hono	✅	1/1 passed	✅ PASS
C++	fmt	✅	N/A	✅ PASS
C++	json	✅	N/A	✅ PASS
Deno	oak	N/A	1/1 passed	✅ PASS
Deno	std	N/A	1/1 passed	✅ PASS
.NET	hello-world	✅	N/A	✅ PASS
.NET	json-parse	✅	N/A	✅ PASS
Go	color	✅	pkg tests OK	✅ PASS
Go	env	✅	pkg tests OK	✅ PASS
Go	uuid	✅	pkg tests OK	✅ PASS
Java	gson	✅	1/1 passed	✅ PASS
Java	caffeine	✅	1/1 passed	✅ PASS
Node.js	clsx	✅	all passed	✅ PASS
Node.js	execa	✅	all passed	✅ PASS
Node.js	p-limit	✅	all passed	✅ PASS
Rust	fd	✅	1/1 passed	✅ PASS
Rust	zoxide	✅	1/1 passed	✅ PASS

Overall: 8/8 ecosystems passed — PASS

Notes:

• Java (Maven) initially failed with Could not create local repository at /home/runner/.m2/repository because ~/.m2 was pre-owned by root in the runner image, not writable by the runner user. Worked around by pointing Maven at a writable settings file/local repo under /tmp/gh-aw/agent/m2 via mvn -s; this is an environment permissions quirk unrelated to the firewall/proxy config itself. All other ecosystems succeeded on the first attempt with no firewall-related network blocks observed.

Generated by Build Test Suite for #8867 · copilot · auto · 54.5 AIC · ⊞ 11.8K · ◷
_{Add label ready-for-aw to run again}

[github-actions]

• Correlate upstream 400s with request tool surface and negotiate MCP protocol version
• Sync D14 runner-doctor catalog with Retry transient Cloud Hypervisor version-probe failures in preflight #8801 Cloud Hypervisor retry-fix follow-up
• Merged PR review: ✅
• PR detail lookup: ✅
• Playwright title check: ❌ (no Playwright tool available)
• File write/readback: ✅
• AWF build: ✅
• Overall status: FAIL

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• msfeed25.pkgs.visualstudio.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "msfeed25.pkgs.visualstudio.com"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex
_{Add label ready-for-aw to run again}

[github-actions]

Smoke Test: API Proxy OpenTelemetry Tracing — Results

#	Scenario	Result
1	Module Loading	✅ otel.js loaded successfully; isEnabled() → true; exports: startRequestSpan, setTokenAttributes, setBudgetAttributes, endSpan, endSpanError, shutdown, isEnabled, _provider, _ProxyAwareOtlpExporter, _FileSpanExporter, _FanOutSpanExporter, _parseEndpoints, _parseOtlpHeaders, _buildResourceSpans, _createOtlpWorkloadIdentity
2	Test Suite	✅ 3 suites, 68/68 tests passed (otel.test.js, otel-fanout.test.js, otel-workload-identity.test.js) — covers span creation, gen_ai token attributes, parent-context propagation, OTLP JSON serialization, fan-out/proxy-aware exporters, file exporter fallback
3	Env Var Forwarding	✅ src/services/agent-environment/env-passthrough.ts forwards GITHUB_AW_OTEL_TRACE_ID and GITHUB_AW_OTEL_PARENT_SPAN_ID to the agent; src/services/api-proxy-env-config.ts forwards GH_AW_OTLP_ENDPOINTS, OTEL_EXPORTER_OTLP_ENDPOINT, GITHUB_AW_OTEL_TRACE_ID, and GITHUB_AW_OTEL_PARENT_SPAN_ID to the api-proxy container
4	Token Tracker Integration	✅ token-tracker-http.js contains the onUsage callback hook point used by OTEL to record gen_ai.usage.* attributes
5	OTEL Diagnostics	⚠️ Workflow-level trace (/tmp/gh-aw/otel.jsonl) contains the gh-aw.agent.setup span as expected, but no api-proxy-emitted spans were present — expected here since this run's steps validate the api-proxy module/tests directly rather than routing live LLM traffic through --enable-api-proxy. No errors were raised (graceful degradation confirmed).

Overall: ✅ All 5 scenarios pass or behave as expected. No regressions detected in OTEL module loading, span/attribute correctness, env var propagation, or token-tracker integration.

📡 OTel tracing validated by Smoke OTel Tracing
_{Add label ready-for-aw to run again}