fix(OMN-12755): preserve workspace root in deploy-runtime

[jonahgabriel]

Summary

• preserve operator-supplied OMNI_HOME after sourcing ~/.omnibase/.env so workspace staging/ref capture use the requested root
• validate BUILD_SOURCE / EXPECTED_BUILD_SOURCE before staging or build
• stage workspace sibling repos during deploy-runtime.sh --execute when BUILD_SOURCE=workspace
• pass BUILD_SOURCE, EXPECTED_BUILD_SOURCE, and OMNI_HOME as explicit Docker build args and print the resolved args via --print-compose-cmd

Evidence

• bash -n scripts/deploy-runtime.sh
• uv run pytest tests/scripts/test_deploy_runtime_build_context.py tests/scripts/test_deploy_runtime_no_env_file.py -q
• uv run ruff check tests/scripts/test_deploy_runtime_build_context.py
• uv run validate-yaml contracts/OMN-12755.yaml
• git diff --check

Deploy note

Post-merge workspace-mode runtime validation should run BUILD_SOURCE=workspace OMNI_HOME=/data/omninode/omni_home bash scripts/deploy-runtime.sh --execute --force and inspect image provenance/build args for the operator workspace root.

No dashboard changes.

Summary by CodeRabbit

• New Features

  • Deployment script now supports configurable build sources (workspace and release modes), allowing operators to deploy from workspace using BUILD_SOURCE=workspace.

• Tests

  • Added test coverage for workspace deployment validation and build source configuration handling.

• Chores

  • Added deployment contract specifying requirements and validation steps for the new build source workflow.

Evidence-Source: OCC#2244

Evidence-Ticket: OMN-12755

[coderabbitai]

Warning

Review limit reached

@jonahgabriel, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 32 minutes and 46 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: be2fc1eb-2c21-4b95-b87b-4821757e3c92

📥 Commits

Reviewing files that changed from the base of the PR and between 6b32520 and a0a14ae.

📒 Files selected for processing (1)

• scripts/deploy-runtime.sh

📝 Walkthrough

Walkthrough

The PR implements workspace build source support for deploy-runtime.sh, enabling operators to override OMNI_HOME and select workspace-based Docker image builds. A deployment contract specifies evidence requirements; the script adds build-source resolution/validation helpers, operator OMNI_HOME override in environment loading, workspace staging integration, and Docker build arg passing with corresponding validation tests.

Changes

Workspace Build Source and OMNI_HOME Override

Layer / File(s)	Summary
Deployment contract and evidence specification contracts/OMN-12755.yaml	Defines OMN-12755 contract schema and structured evidence requirements for build-source workspace OMNI_HOME propagation, with manual validation steps for staging and image provenance.
Operator OMNI_HOME override in environment loading scripts/deploy-runtime.sh	Enables operator to pass OPERATOR_OMNI_HOME which temporarily overrides the environment variable during .env sourcing, then is unset after policy/home config loading.
Build-source helper functions scripts/deploy-runtime.sh	Adds resolve_build_source(), resolve_expected_build_source(), validate_build_source_config(), and stage_workspace_if_needed() functions that resolve/validate build source, handle workspace staging via scripts/runtime_build/stage_workspace.sh, and enforce required OMNI_HOME presence.
Build-source validation and workspace staging integration scripts/deploy-runtime.sh	Main flow calls validate_build_source_config before prod promotion guard; sync phase invokes stage_workspace_if_needed to stage sibling repositories when BUILD_SOURCE=workspace.
Docker build args for build source parameters scripts/deploy-runtime.sh	Image building phase computes build_source and expected_build_source from resolver functions, then passes BUILD_SOURCE, EXPECTED_BUILD_SOURCE, and OMNI_HOME as explicit Docker build arguments along with updated logging.
Compose command printing with build-source and ref values scripts/deploy-runtime.sh	Compose command printer resolves omni_home, build_source, expected_build_source, and computes ref values (compat_ref, omnimarket_ref, occ_ref) based on operator OMNI_HOME; final printed command includes all build-source args explicitly.
Test coverage with helper utilities tests/scripts/test_deploy_runtime_build_context.py	Adds os and subprocess imports, introduces _init_git_repo and _write_fake_docker test helpers, and implements two validation tests: operator OMNI_HOME precedence in compose output, and workspace staging with Docker build args passing.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A rabbit's build song to the scripting spree:

Workspace builds bloom with operator's key,
OMNI_HOME dancing through the staging tree,
Build args flowing like a river free,
Docker commands now perfectly agree—
A workspace feast for all to see! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: preserving the operator-supplied OMNI_HOME workspace root in the deploy-runtime script, which is the primary objective addressed across all file modifications.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jonah/omn-12755-workspace-deploy-omni-home-arg

---

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