[lpcox]

Root cause

Both release v0.28.71 jobs in run 39538048055 pass initialize and notifications/initialized, then fail tools/list with tools-mismatch. The common smoke arguments configure --max-num-tool-calls 16. The real broker appends that trusted limit's advisory to each tool description, but host readiness expected only the static uncapped description. This diagnosis follows the release-equivalent source; the logs do not contain a captured tool-list payload.

Changes

• Reuse the existing broker advisory formatter when deriving the exact expected routed tool description for a configured cap.
• Keep exact names, executor set, schemas, descriptions and gateway-origin prefix validation unchanged; do not relax readiness or budget enforcement.
• Add deterministic coverage using the real broker dispatcher/budget, actual CI gateway fixture and actual host readiness handshake: script-only/agent-only/combined × uncapped/1/16, plus seven rejected contract mutations.
• Document the cap-aware exact contract. No workflow source/lock, release, runtime, storage/network, authentication or admission configuration changes.

Review and validation

Exact-source read-only review passed for this patch and reachable dependencies; no confirmed vulnerability or blocking correctness defect was reported. Review includes shared formatter, actual dispatcher, strict comparison, bundling/configs and hooks.

Normal PR CI verified head b1b5eb2d8b233a4a48903c110323e5bf79515d35: deterministic enclave conformance passed 45 suites / 1,817 tests, including explicit passes for src/enclave/gateway.test.ts and scripts/ci/cloud-hypervisor-enclave-gateway.test.ts. Build/Lint on Node 20 and 22, TypeScript type-check, ESLint, Markdown lint and link checks also passed. Broader root-unit/coverage/chroot/security jobs were still pending at that observation; no failed check was reported. Live/environment/privileged VM jobs were skipped, not validated.

Local validation was blocked, not passed: clean-env npm run build failed because tsc was missing. One approved unchanged-lock npm ci --ignore-scripts --no-audit --no-fund --fetch-retries=0 --fetch-timeout=15000 attempt failed with package GET ENOTCONN and npm's Exit handler never called!. No retries, alternate registry/cache, copied dependencies, auth variables or lifecycle installation scripts. Manifests, lockfile and tracked .npmrc stayed unchanged. Targeted Jest and ESLint were therefore not run locally. Configured generated Husky wrappers were absent; ordinary commit behavior was not bypassed, and silent hooks are not claimed as validation. git diff --check passed. Owned partial installation/cache files were cleaned up; raw evidence was retained privately outside the repository.

No manual dispatch/rerun/cancellation, KVM/live acceptance, secrets access or inference was performed. New test fixtures use synthetic credentials and listing-only requests; existing budget tests use in-process fake tool calls.

Source and scope

Based on current origin/main c915e89f470bba946b76c16203b6692c87b68208; fetched and merged current main before publication (already up to date). No inherited branch changes. GitHub's release comparison shows v0.28.71's release commit differs from this base only in package version fields and the artifact compatibility release tag. This is a new follow-up, not a repurposing of merged #10383.

Authored documentation annotation: docs/enclaves-architecture.md:495–500 changes the generic exact-contract explanation to explicitly account for the configured cap advisory. Security impact: unchanged exact matching of schemas, enabled names, gateway-origin prefix and every other description character; no credential, recipient, permission, persistence or approval changes.

[github-actions]

Documentation Preview

Documentation has been built for this PR.

Download preview artifact

To view locally:

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

Built from commit ed98cb4

[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.40%	93.39%	📉 -0.01%
Statements	91.84%	91.83%	📉 -0.01%
Functions	90.98%	90.98%	➡️ +0.00%
Branches	85.86%	85.87%	📈 +0.01%

📁 Per-file Coverage Changes (1 files)

File	Lines (Before → After)	Statements (Before → After)
src/nvx/one-shot-adapter.ts	83.4% → 82.9% (-0.56%)	80.7% → 80.2% (-0.52%)

---

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

[Copilot]

🟢 Approval recommended

The localized fix preserves strict validation, has targeted regression coverage, and has no identified blocking issues.

No open issues 🎉

What changed in this PR

Fixes AWF enclave gateway readiness for configured tool-call caps while preserving exact tool-contract validation.

Changes:

• Reuse the broker’s advisory formatter for expected capped descriptions.
• Add readiness coverage across executor profiles, cap values, and invalid contracts.
• Document the cap-aware matching requirements.

File	Description
src/​enclave/​gateway.ts	Match descriptions containing the configured cap advisory.
scripts/​ci/​cloud-hypervisor-enclave-gateway.test.ts	Test real broker listings through the gateway readiness handshake.
docs/​enclaves-architecture.md	Clarify exact matching for capped tool descriptions.

_{Review effort: Max}