[josephfeleke]

What was broken

Plugin 0.2.1 shipped on ClawHub with only the macOS arm64 CLI binary (vendor/agentmail/darwin-arm64/agentmail). On Linux and Windows the bundled CLI failed with "Exec format error", so the CLI-backed skill could not run (support tickets T-1919, T-1777).

The vendor tree is only complete when prepack runs cli:prepare -- --all during npm pack / npm publish. If a publish skips lifecycle scripts (--ignore-scripts) or packs a host-only build, npm pack still succeeds and silently ships one platform. Nothing failed a platform-incomplete pack.

The channel README also documented a SecretRef apiKey that only resolves on 0.2.2+. On 0.2.1 the channel fails to start with unresolved SecretRef "env:default:AGENTMAIL_API_KEY".

What changed

• scripts/assert-cli-targets-packed.mjs (npm run pack:verify): runs npm pack --dry-run --json --ignore-scripts and fails if any of the 8 CLI targets in src/cli/agentmail-cli-release.json is missing from the tarball that would publish. Added as a CI step after plugin:validate. --ignore-scripts is deliberate so the guard inspects the on-disk tree that will ship, instead of re-running prepack and masking the gap.
• src/cli/pack-targets.ts + src/cli/pack-targets.test.ts: small pure helpers (findMissingCliTargets, expectedCliVendorPaths, normalizePackPath) with unit tests.
• README: notes that AGENTMAIL_API_KEY in the Gateway environment works on every version and is the simplest channel credential, and that the SecretRef apiKey form needs 0.2.2+.

Not in this PR

• The provenance-invalid / "trusted-official" blocker in the same tickets is an OpenClaw-side change: the package must be in OpenClaw's official plugin catalog (openclaw/openclaw). No change in this repo fixes it, so this PR does not by itself restore the crash-looping inbound channel.
• A tagged release / publish workflow is intentionally left out. The package is not on public npm today (npm view returns E404) and is distributed as a ClawHub artifact, so how a provenance-signed release should publish (npm vs ClawHub, token vs OIDC) is an ops decision rather than something to guess in CI. Whatever workflow is added should gate on npm run plugin:validate then npm run pack:verify before publishing. See follow-ups.
• The SecretRef channel bug itself is already fixed on main (0.2.2, commit d85426f) and just needs to ship.

How it was tested

• tsc -p tsconfig.json --noEmit: clean.
• vitest run src/cli/pack-targets.test.ts: 5/5 pass; removing the helper makes the test fail to collect, confirming it exercises the new code.
• Guard demonstrated end to end: fails on a darwin-arm64-only tree (1/8, the exact 0.2.1 state) and an empty tree (0/8), passes on a complete 8-target tree, exits non-zero on failure.
• The full vitest suite could not run in the dev environment because its Node (23.11.0) fails OpenClaw's runtime SQLite gate; the added test and guard do not depend on the Node version, and CI runs on Node 24.15.0.

Support tickets: T-1919, T-1777

Update after review: plugin:validate (run by prepack and CI) already fails when a CLI target is missing on disk, so the CI step alone cannot catch a release that skipped prepack, which is what happened with 0.2.1. pack:verify now also takes a tarball path (npm run pack:verify -- <package>.tgz), and the README tells release owners to run it on the exact file they upload. A CI release workflow that always does this is still the proper long-term fix.

🤖 Generated with Claude Code