Fix Railway template runtime claim bootstrap

[squaeragent]

Summary

• install the public zero-engine==0.1.6 PyPI package in the Railway root Dockerfile instead of rebuilding the stale in-repo 0.1.5 engine
• keep the Railway wrapper paper-first while defaulting ZERO_DEPLOYMENT_VERSION=engine-v0.1.6 and ZERO_FOUNDATION_STATE_DIR=/data/.zero
• update the Railway template docs and distribution packet so CI catches regressions away from the claim-capable package

Why

Operator-connected Railway services were healthy but still lacked /deployment/claim runtime.foundation_bootstrap_* and claim_token_consumed readbacks because the public template source repo remained on the stale 0.1.5 engine code. Installing zero-engine==0.1.6 from public PyPI makes the public template consume the claim-capable runtime without copying hosted app code into this repo.

Validation

• scripts/railway_template_packet.py --check
• bash -n scripts/railway_start.sh
• python3 -m json.tool contracts/distribution/railway-template.json >/dev/null
• git diff --check
• python3 -m pip index versions zero-engine confirmed 0.1.6 is public
• temp venv install of zero-engine==0.1.6 confirmed version 0.1.6 and foundation_bootstrap_from_env import

Docker build was not run locally because the Docker daemon is unavailable in this environment.

AI-assisted change: yes

Co-authored-by: Codex codex@openai.com

Summary by CodeRabbit

• New Features

  • Added support for the zero-engine runtime package version 0.1.6 in deployment templates and container setup.
  • Expanded deployment configuration with additional runtime and state-directory settings.

• Bug Fixes

  • Improved startup reliability by persisting runtime state in a dedicated data directory.
  • Added container health checks and startup validation for better service readiness detection.

• Documentation

  • Updated Railway deployment docs to reflect the new runtime package, configuration variables, and expected boot output.

[coderabbitai]

Warning

Review limit reached

@squaeragent, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 46 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

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.

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 configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6f6274df-0091-4a8c-aea9-bb926fa22f22

📥 Commits

Reviewing files that changed from the base of the PR and between a383602 and 900b400.

📒 Files selected for processing (9)

• Dockerfile
• contracts/distribution/railway-template.json
• docs/llms-full.txt
• docs/railway-template.md
• scripts/hardening_gate.sh
• scripts/public_readiness_gate.sh
• scripts/railway_smoke.sh
• scripts/railway_start.sh
• scripts/railway_template_packet.py

📝 Walkthrough

Walkthrough

The Dockerfile, startup script, Railway template contract, packet generator, and documentation are updated to install the zero-engine==0.1.6 package from PyPI instead of building from local engine sources. New environment variables (deployment version, foundation state directory), a zero user, healthcheck, and expanded template variables/checks/docs are added accordingly.

Changes

Runtime Package Pin and Railway Template Updates

Layer / File(s)	Summary
Dockerfile: package install, env vars, healthcheck Dockerfile	Replaces local engine source copy/install with pinned zero-engine==0.1.6 PyPI install, adds zero user creation, /data/.zero setup with ownership adjustments, EXPOSE 8765, and a HEALTHCHECK querying /health.
Startup script: version and state dir env vars scripts/railway_start.sh	Adds ZERO_DEPLOYMENT_VERSION and ZERO_FOUNDATION_STATE_DIR defaults, creates the state directory, and exports both new variables alongside ZERO_REPO_ROOT.
Template packet generator: constants and checks scripts/railway_template_packet.py	Introduces RUNTIME_PACKAGE/RUNTIME_VERSION constants, reworks validation checks for Dockerfile/docs/start script content, adds runtime_package to autodeploy config, and adds new template variable placeholders.
Railway template contract: checks and variables contracts/distribution/railway-template.json	Adds new check flags for package installation, runtime version naming, journal/state directory usage, and expanded docs-name checks; adds runtime_package to autodeploy config; adds new template_variables entries.
Documentation: runtime package and variables docs/railway-template.md	Documents the pinned zero-engine==0.1.6 package, adds a runtime package row, extends the Template Variables section, and documents required runtime.foundation_bootstrap_* fields with rebuild instructions.

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

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: restoring Railway template claim bootstrap behavior for the runtime.
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)

• Create PR with unit tests
• Commit unit tests in branch codex/railway-claim-image

---

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

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a383602c08

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@Dockerfile`:
- Around line 26-27: The Dockerfile HEALTHCHECK is hardcoding 8765, which can
diverge from the runtime PORT used by scripts/railway_start.sh. Update the
HEALTHCHECK command to probe the same port source as the app (use the PORT
environment variable with the existing fallback behavior), and keep the check
aligned with the health endpoint in the Dockerfile so it works when Railway
assigns a non-default port.
- Around line 13-15: The Dockerfile still launches as root and the later COPY
steps overwrite the earlier ownership changes on /app. Update the build so the
final runtime user is switched to zero with USER zero before CMD, and ensure any
files copied into /app after the chown are re-owned appropriately; use the
existing useradd and chown setup to keep the container running with dropped
privileges.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8cac758c-7c7c-4084-850f-11372fe43efd

📥 Commits

Reviewing files that changed from the base of the PR and between dcb391e and a383602.

📒 Files selected for processing (5)

• Dockerfile
• contracts/distribution/railway-template.json
• docs/railway-template.md
• scripts/railway_start.sh
• scripts/railway_template_packet.py

[squaeragent]

All review threads are resolved, all checks are green, and auto-merge is enabled. GitHub still requires one approving review from a non-author with write access; after that, this PR will squash-merge automatically.\n\nValidation on head 900b400:\n- CI: engine, docs, registry-readiness, examples, cli, paper-api-smoke, fresh-clone-rehearsal, railway-smoke, container-smoke all passed\n- CodeQL and trufflehog passed\n- Local gates passed: scripts/railway_template_packet.py --check, scripts/public_readiness_gate.sh, scripts/hardening_gate.sh, git diff --check\n\nRuntime fix: public Railway Dockerfile installs zero-engine==0.1.6 from PyPI; /deployment/claim and /deployment/heartbeat expose runtime.foundation_bootstrap_* fields; Railway smoke now runs with the non-root runtime user against a writable /data volume.