chore: add Amp orb setup script

[rmems]

What

Adds .agents/setup, the script Amp runs on a fresh orb before it saves the snapshot (docs). It's an executable bash script with set -euo pipefail that runs from the repo root. It's idempotent: on a re-run, anything already installed is skipped. It installs only what this repo's CI and manifests need, and ends with a dependency fetch or prebuild, not a test run, so it stays well under the 20-minute setup limit.

What it installs

• apt: build-essential, cmake (Debian 12: 3.25), shellcheck
• CPU-only configure: cmake -S kernels -B build/kernels-cpu -DBKL_ENABLE_CUDA=OFF

Pins and notes

• Pins: cmake_minimum_required(3.24) (Debian 12 has 3.25.1); CPU path -DBKL_ENABLE_CUDA=OFF and the python3 tools/check_*.py / test_*.py checks from ci-cpu.yml use only the orb's system python3.
• GPU: everything with -DBKL_ENABLE_CUDA=ON (kernel builds, benches, compute-sanitizer) needs the self-hosted [self-hosted, Linux, X64, CUDA] runner. On an orb, only the CPU checks and docs/tools work.
• Not installed: actionlint 1.7.12 (ci-lint.yml downloads it per run).

No GPU on orbs

Amp orbs are Debian 12 cloud VMs with no GPU. The GPU-gated parts of this repo can't run on an orb; the notes above give the CPU path.

Testing

• bash -n and shellcheck 0.10.0: clean.
• Not run end to end. Only five of the scripts in this batch were run in a Debian 12 chroot (Limen-Capital, SynapticDistill.jl, combine-for-AI, Dioscuri-Cloud, silicon-hdl). This one has only been syntax-checked and linted.
• Not run on a real Amp orb.

Things to double-check

• rustup, juliaup and uv install into ~/.cargo/bin, ~/.juliaup/bin and ~/.local/bin and add those to the login profile. The script exports them for its own run. In a non-login, non-interactive shell they weren't on PATH, so check that Amp's agent shell finds cargo/julia/uv.
• apt-get uses Acquire::Retries=5, but a deb.debian.org 500 can still fail the setup. Amp doesn't save a snapshot from a failed setup, so a retry fixes it.
• Editing this script later doesn't rebuild existing orb snapshots. Delete it with amp projects snapshots delete <project> to force a fresh setup, or wait for it to expire (Amp reuses a snapshot for up to 72 hours).

Propose-only: please review before merging.

---

Summary by cubic

Adds .agents/setup, the bash script Amp runs on a fresh orb before saving a snapshot (Debian 12, CPU only). It installs only the packages this repo's CI needs — build-essential, cmake, shellcheck — and ends with the CPU-only CMake configure (-DBKL_ENABLE_CUDA=OFF), which skips every kernel target so no nvcc is required.

• Idempotent: packages already installed are skipped on re-runs.
• GPU-gated targets can't run on orbs, so setup stays on the CPU path.
• Only syntax-checked and shellcheck-linted so far, not run end to end.

^{Written for commit 50128b1. Summary will update on new commits.}

[codeant-ai]

🤖 CodeAnt AI — Review Status

Status	Commit	Started (UTC)	Finished (UTC)
✅ Reviewed your PR	50128b1	Oct 02, 2026 · 01:12	01:13

[codeant-ai]

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-02T01:13:12.991489Z	50128b1	PR opened
🔒 Security Review	✅ Completed 2026-10-02T01:14:40.784784Z	50128b1	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: d928faab-171e-42ca-88b3-e0f31258f30f

📥 Commits

Reviewing files that changed from the base of the PR and between 22cc4f3 and 50128b1.

📒 Files selected for processing (1)

• .agents/setup

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (3)

• GitHub Check: Blocks PR Review
• GitHub Check: Host GPU probe + kernel smoke
• GitHub Check: Codacy Static Code Analysis

🧰 Additional context used

🔍 Remote MCP Linear

Linear

• The parent BKL epic assigns GPU CI and CUDA validation to this repository; its release acceptance requires PR, CPU, and conditional GPU checks to pass. (Source: Linear · get_issue)
• Linear’s PR record contains no linked issues, so no PR-specific acceptance criteria were available. (Source: Linear · get_diff)
• Codex, CodeAnt, and CodeRabbit reviews were still running for commit 50128b1; no completed findings were present in the retrieved threads. (Source: Linear · get_diff_threads)

Retrieval limitations

Some requested queries to Linear were not sent; their results are unavailable.

🔇 Additional comments (1)

.agents/setup (1)

1-43: LGTM!

---

📝 Summary

Summary by CodeRabbit

• Chores
  • Added a repeatable Debian 12 setup script that installs required build tools and configures CPU-only builds.

Walkthrough

Adds a repeatable Debian 12 setup script. It installs missing build and lint packages, configures the kernels project for CPU-only builds, and prints a completion message. The script does not run tests.

Changes

Debian setup

Layer / File(s)	Summary
Execution setup and package installation .agents/setup	The script enables strict Bash behavior, changes to the repository root, and uses sudo for privileged commands when needed. It installs build-essential, cmake, and shellcheck only when missing.
CPU-only kernel configuration .agents/setup	The script configures kernels in build/kernels-cpu with BKL_ENABLE_CUDA=OFF and prints a completion message.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 50128

The setup flow is ready to merge; normal host prerequisites such as sudo access and apt repository availability remain environmental requirements.

Architecture Summary

Architecture risk: 🔵 Low · up to 50128

The changed surface does not map to a changed system, dependency edge, entrypoint, or external dependency.

Changed systems: None identified.

Architecture concerns
No architecture-level concerns identified.

Review details

Before / after behavior

• observed — Modified behavior in .agents/setup: Adds a strict-mode Bash setup script that changes to the repository root and uses sudo for privileged commands when the current user is not root.
• observed — Modified behavior in .agents/setup: Adds apt_install, which checks package installation status and, only when packages are missing, updates apt metadata and installs them noninteractively with retries. It is invoked for build-essential, cmake, and shellcheck.
• observed — Modified behavior in .agents/setup: Adds a CPU-only CMake configure for kernels in build/kernels-cpu with BKL_ENABLE_CUDA=OFF, followed by a completion message; no test run is added.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding an Amp orb setup script.
Description check	✅ Passed	The description explains the Amp orb setup script, its dependencies, CPU-only configuration, limitations, and testing status. It is directly related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit checks the tools in place
Then readies kernels for a build
With CUDA off, the CPU waits
The setup script completes its task
And leaves the test run for another day}

_{Comment @coderabbitai help to get the list of available commands.}

[amazon-q-developer]

This PR adds a well-structured Amp orb setup script with proper bash safety practices (set -euo pipefail), idempotent package installation, and appropriate error handling. The script correctly handles sudo detection and package management for the CPU-only build path. No blocking issues identified.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

[gitar-bot]

Important

You are using the Gitar free plan. Upgrade to unlock code review, CI analysis, auto-apply, custom automations, and more.

_Gitar

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}