[P2] Provide a supported package-bound install entry so consumers do not bundle private installer source

[ScriptedAlchemy]

Consumer evidence / scope

Follow-up to #252/#555/#656/#673, not a request to reopen the completed npm-root layout work. Audited framework 72a8857ebe968636ac44dfc7ce4eba30664a8445 and public cargo-hauler dfd2a9a50067c9e600e2d7b96b07bd4b937a9c4a. GitHub source review only.

Cargo Hauler has reimplemented the package-local installation boundary:

• src/cargo-hauler-install.ts: argument grammar, artifact-root probing, raw manifest identity lookup, a local plan response, result formatting and pre-validation mode restoration.
• src/install-api.mjs: imports implementation files through agent-bundle-src/packages/agent-bundle/src/install/*.

The framework already owns validation, native installation, receipts, replacement, uninstall, mode normalization and purge safeguards. The consumer is not implementing a new lifecycle product; it is reconstructing how to call the existing one from an installed package.

Public API gap, not a fictional existing helper

The inspected package export map and public API do not expose installBundle/uninstallBundle as a supported consumer programming API. Do not tell the consumer to switch to a nonexistent runPluginInstaller export. The public framework CLI and generated host-specific installation surfaces do exist.

Establish one supported choice for a source-free, package-bound entry: reuse the generated lifecycle entry where appropriate, make delegation to the existing public CLI viable/documented, or expose a minimal stable wrapper around the existing implementation if a self-contained branded installer is required. Choose the smallest option that lets the consumer delete its private-source shim. Do not require authors to know internal receipt types, host caches or output-root heuristics.

Acceptance / deletion proof

• Demonstrate the supported operator journey from an actual installed consumer tarball, with the source checkout and build-time AB monorepo alias absent.
• Bind the package's own canonical artifact root without guessing sibling artifact/, nested host directories, or the current working directory.
• Reuse existing install/uninstall/doctor/plan semantics, native host identifiers, consent and receipt ownership; no second lifecycle implementation.
• Requested unselected hosts fail before mutation. --plan is truly read-only and reports the real framework plan, not a consumer approximation.
• Preserve mode handling from fix: validate published bins and npm modes #674. No pre-validation chmod of attacker-/operator-edited manifest paths and no global weakening of hashes/containment.
• Cover replacement, foreign directory refusal, keep-data and safe purge using current framework tests plus one clean consumer process fixture.
• Remove the corresponding cargo install-api source imports and handwritten installer paths as the consumer proof, or link the exact follow-up accomplishing that deletion.
• Existing native-only distributions may use native host commands; do not generate an unnecessary installer process for a static plugin.
• Exported types/declarations, if added, resolve from the packed public package and do not leak private source/devDependencies.

Boundaries

No new installer registry, public exposure of every internal lifecycle helper, automatic host mutation during npm installation, permission bypass, daemon lifecycle ownership, or requirement that all users install a branded CLI. Keep this independent from private consumer internals and #411 release automation. Safe removal of Cargo Hauler's mode-repair workaround can proceed before the public entry decision.

[ScriptedAlchemy]

Consumer follow-ups are now filed in the public Cargo Hauler repository:

• [P1] Delete pre-validation manifest chmod; use Agent Bundle's installed-package mode handling cargo-hauler#151 (P1): delete the pre-validation manifest-driven chmod pass and rely on the already-landed fix: validate published bins and npm modes #674 mode handling. This removal can proceed independently of a new public entry point.
• [P2] Replace the private-source installer facade and artifact-root probing with the supported AB lifecycle entry cargo-hauler#152 (P2): remove install-api.mjs private-source imports and the handwritten host/scope parser, artifact-root probes and approximate plan once a supported package-bound delegation path is selected here.

Use those deletions as the consumer acceptance proof. A documented existing public CLI/native-host journey is preferable to adding an export solely to preserve a branded facade that the product does not need. If the branded source-free installer is retained, expose only the smallest supported seam over the existing lifecycle implementation; do not publish the internal installer module graph.