Add Platform-Aware Installation And Launch - #29
Merged
Conversation
|
Warning Review limit reached
Next review available in: 43 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (24)
📝 WalkthroughWalkthroughThis PR adds native release packaging, checksum verification, installation, smoke testing, attestation, and release publication. It introduces the Sequence Diagram(s)sequenceDiagram
participant User
participant HeartwoodCLI
participant PlatformAdapter
participant Slurm
participant vLLM
User->>HeartwoodCLI: launch --dry-run or launch
HeartwoodCLI->>PlatformAdapter: detect platform and build plan
PlatformAdapter->>Slurm: request approved Carina allocation
Slurm->>HeartwoodCLI: enter allocation
HeartwoodCLI->>vLLM: verify model and start local runtime
vLLM->>HeartwoodCLI: report readiness
HeartwoodCLI->>User: open Heartwood chat
Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR introduces a platform-aware “native install + launch” workflow so researchers can install Heartwood from verified GitHub Release assets and run heartwood launch to plan/obtain compute (Slurm on Carina) and start a supervised local vLLM runtime + CLI session in a single, consistent flow.
Changes:
- Add checksum-verified native release assets (bundle + installer) plus a GitHub Actions workflow to build/test/attest/publish them.
- Add
heartwood launchwith platform detection (Carina/Terra/generic), dry-run planning, explicit Slurm consent, staged-model verification, runtime supervision, setup, chat, and cleanup. - Extend Carina policy to allow both action confirmation modes (“always-confirm” and “confirm-risky”) and add a minimal Terra platform adapter.
Reviewed changes
Copilot reviewed 24 out of 24 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Documents release installer + heartwood launch entrypoint and dry-run behavior. |
| packages/gateway/tests/test_readiness.py | Updates readiness/setup tests for expanded confirmation modes and inheritance. |
| packages/gateway/src/heartwood/gateway/_readiness.py | Makes Stanford setup inherit platform confirmation modes via adapter policy. |
| packages/compliance/tests/test_container_assets.py | Updates compliance assertions to reflect new launch/model verification + native asset workflow. |
| packages/cli/tests/test_launch.py | Adds extensive launch/model snapshot verification and runtime supervision tests. |
| packages/cli/src/heartwood/cli/_model_snapshot.py | Introduces shared SHA256SUMS snapshot verifier for staged local models. |
| packages/cli/src/heartwood/cli/_launch.py | Implements platform-aware launch planning, allocation consent, staging, supervision, and cleanup. |
| packages/cli/src/heartwood/cli/init.py | Adds launch subcommand wiring and makes CLI version read from HEARTWOOD_VERSION. |
| packages/adapters/tests/test_generic_adapters.py | Extends adapter conformance tests for Terra + updated Carina confirmation modes. |
| packages/adapters/src/heartwood/adapters/platform/terra.py | Adds minimal Terra adapter reporting provisioned compute + conservative local policy. |
| packages/adapters/src/heartwood/adapters/platform/carina.py | Expands allowed action confirmation modes and clarifies policy notes. |
| packages/adapters/src/heartwood/adapters/platform/init.py | Selects Terra adapter based on detector evidence and exports it. |
| docs/platform-support.md | Updates platform-support matrix to reflect verified native install + launch contracts. |
| docs/container-images.md | Clarifies how native release assets relate to image-based deployments. |
| docs/carina-cli.md | Updates Carina CLI pilot workflow to tagged release install + heartwood launch. |
| design/09-implementation-plan.md | Records heartwood launch, Terra adapter, and native release assets in the implementation plan. |
| design/08-development.md | Adds native release asset supply-chain notes (build, verify, restricted-network support). |
| design/03-architecture.md | Adds installer/launch lifecycle ownership boundaries and constraints. |
| deploy/tests/native_installer_smoke.sh | Adds smoke test for native installer layout and checksum rejection. |
| deploy/package-native.sh | Packages fixed-name native bundle and generates SHA256SUMS. |
| deploy/install.sh | Adds standalone installer for bundle verification + versioned installation layout. |
| deploy/carina/verify_model_snapshot.py | Delegates snapshot verification to the shared CLI verifier. |
| deploy/carina/launch-interactive.sh | Makes Carina wrapper delegate to heartwood launch --inside-allocation. |
| .github/workflows/native-release.yml | Adds CI workflow to build/test/upload native assets and publish+attest on releases. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
packages/cli/src/heartwood/cli/_launch.py (1)
241-257: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winHardcoded loopback port with no collision handling.
Port 8765 is fixed in both
_vllm_commandand_wait_for_runtime. A stale process (e.g., from a prior crashed launch that skipped cleanup) or a concurrently-running launch on a shared node would produce a confusing readiness timeout rather than a clear bind-conflict error.Also applies to: 282-289
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/cli/src/heartwood/cli/_launch.py` around lines 241 - 257, Replace the hardcoded port 8765 with a dynamically selected, available port for each launch, and pass that same port through both _vllm_command and _wait_for_runtime. Ensure stale or concurrent processes cause the launch to use another available port instead of waiting on a conflicting endpoint and timing out.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@deploy/install.sh`:
- Around line 95-98: Update the checksum verification block in deploy/install.sh
to require exactly one manifest entry for heartwood-native.tar.gz and validate
only that archive, rejecting manifests containing other or missing targets.
Ensure the archive is verified before extraction and execution.
In `@packages/cli/src/heartwood/cli/_launch.py`:
- Around line 282-294: Update _wait_for_runtime so every unsuccessful readiness
check, including a successful HTTP response with empty or missing payload data,
waits before retrying. Preserve immediate success for status 200 responses with
populated data, and retain the existing failure handling and timeout behavior.
- Around line 260-279: Update _runtime_environment to construct the child
environment from an explicit allowlist of required runtime variables instead of
copying env and removing selected secrets. Preserve the HEARTWOOD_AGENT_BACKEND,
HEARTWOOD_LOCAL_RUNTIME_HOST, and HEARTWOOD_LOCAL_RUNTIME_PORT values, and
include only the small set of variables needed by the spawned vLLM, chat, and
setup processes.
---
Nitpick comments:
In `@packages/cli/src/heartwood/cli/_launch.py`:
- Around line 241-257: Replace the hardcoded port 8765 with a dynamically
selected, available port for each launch, and pass that same port through both
_vllm_command and _wait_for_runtime. Ensure stale or concurrent processes cause
the launch to use another available port instead of waiting on a conflicting
endpoint and timing out.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 1a7cec09-6e2c-4fbc-8364-b7e538903038
📒 Files selected for processing (24)
.github/workflows/native-release.ymlREADME.mddeploy/carina/launch-interactive.shdeploy/carina/verify_model_snapshot.pydeploy/install.shdeploy/package-native.shdeploy/tests/native_installer_smoke.shdesign/03-architecture.mddesign/08-development.mddesign/09-implementation-plan.mddocs/carina-cli.mddocs/container-images.mddocs/platform-support.mdpackages/adapters/src/heartwood/adapters/platform/__init__.pypackages/adapters/src/heartwood/adapters/platform/carina.pypackages/adapters/src/heartwood/adapters/platform/terra.pypackages/adapters/tests/test_generic_adapters.pypackages/cli/src/heartwood/cli/__init__.pypackages/cli/src/heartwood/cli/_launch.pypackages/cli/src/heartwood/cli/_model_snapshot.pypackages/cli/tests/test_launch.pypackages/compliance/tests/test_container_assets.pypackages/gateway/src/heartwood/gateway/_readiness.pypackages/gateway/tests/test_readiness.py
PSchmiedmayer
force-pushed
the
feature/platform-aware-installation
branch
from
July 12, 2026 23:39
9c7daf4 to
4006bb6
Compare
PSchmiedmayer
force-pushed
the
feature/platform-aware-installation
branch
from
July 12, 2026 23:45
4006bb6 to
533f29a
Compare
This was referenced Jul 13, 2026
PSchmiedmayer
added a commit
that referenced
this pull request
Jul 18, 2026
### ♻️ Current Situation & Problem The native Carina pilot in #25 requires a repository checkout and direct use of bootstrap, Slurm, and runtime scripts. Installation, compute acquisition, model staging, and runtime supervision are therefore exposed as separate operator steps instead of one approachable Heartwood workflow. Carina also restricts action confirmation to Ask Every Time even though the shared OpenHands integration supports low-risk auto-approval. ### ⚙️ Release Notes - Add checksum-verified native installation assets for GitHub Releases, with online and approved local-bundle installation paths. - Add `heartwood launch` with platform detection, dry-run planning, explicit Carina Slurm consent, model verification, scratch staging, vLLM supervision, setup, conversation launch, and cleanup. - Add a minimal Terra adapter so already-provisioned Terra and generic environments reuse the direct launch path without Slurm. - Allow researchers to explicitly select Auto-Approve Low Risk on Carina while retaining Ask Every Time as the setup default and keeping unconditional auto-approval unavailable. ```bash ./heartwood-installer --root /projects/<group>/<project>/heartwood-pilot --platform carina --version <release-tag> export PATH="/projects/<group>/<project>/heartwood-pilot/bin:${PATH}" heartwood launch --model-root /projects/<group>/<project>/heartwood-pilot/models/<model> ``` ### 📚 Documentation The architecture and development documents define the installer and platform launch ownership boundaries. The delivery roadmap records the implemented baseline and remaining live-validation gate. The README, Carina pilot, container reference, and platform-support matrix document installation, launch consent, action confirmation, and current limitations. ### ✅ Testing - 410 Python tests pass with 90.09% aggregate branch coverage. - Strict mypy, Ruff formatting and lint, actionlint, shell syntax, Markdown whitespace, and REUSE 3.3 compliance pass locally. - Native assets are packaged from the committed tree, verified by SHA-256, installed with a hermetic dependency substitute, and rejected with corrupted archives or malformed checksum manifests. - Launch tests cover Carina allocation planning, denial, explicit consent, dry-run, no-allocation mode, Terra direct execution, model and runtime failures, runtime supervision, credential scrubbing, setup invocation, staged-model integrity, and cleanup. - Live Carina GPU allocation, tagged release installation, and Terra control-plane execution remain explicit post-merge validation gates and do not support controlled-data claims. ### Code of Conduct & Contributing Guidelines By creating and submitting this pull request, you agree to follow our [Code of Conduct](https://github.com/SchmiedmayerLab/.github/blob/main/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/SchmiedmayerLab/.github/blob/main/CONTRIBUTING.md): - [x] I agree to follow the [Code of Conduct](https://github.com/SchmiedmayerLab/.github/blob/main/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/SchmiedmayerLab/.github/blob/main/CONTRIBUTING.md).
This was referenced Jul 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
♻️ Current Situation & Problem
The native Carina pilot in #25 requires a repository checkout and direct use of bootstrap, Slurm, and runtime scripts. Installation, compute acquisition, model staging, and runtime supervision are therefore exposed as separate operator steps instead of one approachable Heartwood workflow. Carina also restricts action confirmation to Ask Every Time even though the shared OpenHands integration supports low-risk auto-approval.
⚙️ Release Notes
heartwood launchwith platform detection, dry-run planning, explicit Carina Slurm consent, model verification, scratch staging, vLLM supervision, setup, conversation launch, and cleanup.📚 Documentation
The architecture and development documents define the installer and platform launch ownership boundaries. The delivery roadmap records the implemented baseline and remaining live-validation gate. The README, Carina pilot, container reference, and platform-support matrix document installation, launch consent, action confirmation, and current limitations.
✅ Testing
Code of Conduct & Contributing Guidelines
By creating and submitting this pull request, you agree to follow our Code of Conduct and Contributing Guidelines: