Harden Zeus security, reliability, and maintainability

.coveragerc

@@ -4,7 +4,7 @@ source =
     zeus
 
 [report]
-fail_under = 70
+fail_under = 79
 precision = 2
 show_missing = True
 skip_covered = True

.env.example

@@ -36,6 +36,10 @@ ZEUS_API_LOG_ENABLED=1
 # Optional workspace-local runtime path.
 ZEUS_STATE_DIR=.zeus
 
+# SQLite commit durability. NORMAL is the compatibility/default local setting;
+# FULL adds power-loss durability at the cost of higher commit latency.
+ZEUS_SQLITE_SYNCHRONOUS=NORMAL
+
 # Optional: send SIGKILL if SIGTERM does not stop Hermes before the grace timeout.
 # Disabled by default to avoid interrupting a still-shutting-down gateway.
 ZEUS_STOP_KILL_AFTER_TIMEOUT=0
@@ -50,7 +54,12 @@ ZEUS_ALLOW_LEGACY_PID_MARKERS=1
 # Keep empty unless required for proxies or certificate bundles.
 ZEUS_ENV_PASSTHROUGH=
 
-# Provider and gateway secrets referenced by bundled templates.
+# Provider and gateway secrets referenced by bundled templates. Copy this file
+# to the trusted workspace ./.env, then import only the names a bot needs with
+# `zeus bot create ... --env-from NAME`. A process environment value takes
+# precedence over ./.env. Do not pass secrets with legacy `--env NAME=VALUE`;
+# command arguments may be exposed in shell history and process listings. After
+# copying this file, run `chmod 0600 .env` before adding real secrets.
 OPENROUTER_API_KEY=
 NOUS_API_KEY=
 OPENAI_API_KEY=

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -7,7 +7,7 @@ body:
     id: zeus-version
     attributes:
       label: Zeus version
-      description: Output from `zeus --version` or the installed package version.
+      description: Run `zeus --version` and paste the complete output.
     validations:
       required: true
   - type: input

.github/workflows/ci.yml

@@ -14,7 +14,8 @@ concurrency:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
@@ -50,8 +51,23 @@ jobs:
           coverage run -m unittest discover -s tests
           coverage report
 
+  python-3-14:
+    continue-on-error: true
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.14"
+      - name: Install package and test tools
+        run: python -m pip install -e ".[dev]"
+      - name: Run Zeus test suite
+        run: sh scripts/test.sh
+
   lifecycle-subprocess:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
@@ -62,20 +78,74 @@ jobs:
       - name: Run subprocess lifecycle tests
         run: python -m unittest tests.test_subprocess_lifecycle
 
+  macos-process-lifecycle:
+    runs-on: macos-26
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.13"
+      - name: Install package and test tools
+        run: python -m pip install -e ".[dev]"
+      - name: Run focused process lifecycle tests
+        run: |
+          python -m unittest -v \
+            tests.test_subprocess_lifecycle \
+            tests.test_fake_hermes_integration \
+            tests.test_crash_recovery.GatewayLauncherTests
+
+  real-hermes:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.11"
+      - name: Prepare sanitized failure evidence
+        run: |
+          mkdir -p .tmp/real-hermes-evidence
+          printf '%s\n' 'result=failed' 'failure_stage=ci_setup' > .tmp/real-hermes-evidence/summary.txt
+      - name: Install pinned Hermes compatibility environment
+        run: |-
+          python -m pip install --require-hashes --only-binary=:all: -r requirements-hermes-ci.txt
+      - name: Install Zeus
+        run: python -m pip install -e .
+      - name: Check installed dependencies
+        run: python -m pip check
+      - name: Verify real Hermes without provider credentials
+        run: |
+          ZEUS_VERIFY_START_GATEWAY=1 \
+          ZEUS_VERIFY_EXPECTED_HERMES_VERSION=0.19.0 \
+          ZEUS_VERIFY_EVIDENCE_DIR=.tmp/real-hermes-evidence \
+          sh scripts/verify_real_hermes.sh
+      - name: Upload sanitized failure evidence
+        if: failure()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: real-hermes-failure-evidence
+          path: .tmp/real-hermes-evidence/summary.txt
+          if-no-files-found: error
+          retention-days: 7
+
   package:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
       - name: Install package build tools
         run: python -m pip install -e ".[dev]"
+      - name: Check installed dependencies
+        run: python -m pip check
       - name: Build package
         run: |
           rm -rf dist
           python -m build
-      - name: Smoke test built wheel
+      - name: Verify installed wheel behavior
         run: ZEUS_WHEEL_SMOKE_BUILD=0 sh scripts/wheel_smoke.sh
       - name: Check package metadata
         run: twine check dist/*

.github/workflows/release.yml

@@ -31,6 +31,10 @@ jobs:
             exit 1
           }
           python scripts/check_version_tag.py "${GITHUB_REF_NAME}" --require-changelog
+      - name: Require GitHub-verified release ref
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: python scripts/check_verified_release_ref.py
       - name: Install shellcheck
         run: |
           sudo apt-get update

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- Added descriptive CLI help and a state-free `zeus --version` command backed by the package
+  version.
+- Required future release tags and their referenced commits to be signed and GitHub-verified
+  before the privileged publishing job can run.
+
 ## 0.3.0
 
 - Relaunched the public repository from an audited, single-root history on the `main` branch while

CONTRIBUTING.md

@@ -7,10 +7,15 @@ Zeus is intentionally small and workspace-local. Changes should keep the project
 ```bash
 python3 -m venv .venv
 . .venv/bin/activate
-pip install -e .
-sh scripts/test.sh
+python -m pip install -e ".[dev]"
+make check
 ```
 
+See the [compatibility policy](docs/COMPATIBILITY.md) for the operating systems,
+Python versions, and Hermes boundary covered by committed automation. The
+committed Ubuntu/Python 3.11 gate uses the hash-locked Hermes Agent 0.19.0
+environment; the manual check below covers the operator's installed version.
+
 ## Quality Bar
 
 - Keep the core runtime dependency-free unless there is a clear operational reason.
@@ -25,7 +30,8 @@ sh scripts/test.sh
 
 ## Real Hermes Verification
 
-The default test suite uses a fake Hermes executable to verify Zeus process handling. Before release, run:
+The default test suite uses a fake Hermes executable to verify Zeus process handling.
+Before release, separately run:
 
 ```bash
 sh scripts/verify_real_hermes.sh

Makefile

@@ -25,8 +25,10 @@ check:
 	ruff check .
 	mypy zeus
 	bandit -r zeus
+	shellcheck scripts/*.sh
 
 build:
+	python -m pip check
 	python -m build
 	twine check dist/*
 
@@ -44,6 +46,7 @@ release-check:
 	mypy zeus
 	bandit -r zeus
 	shellcheck scripts/*.sh
+	python -m pip check
 	rm -rf dist
 	python -m build
 	ZEUS_WHEEL_SMOKE_BUILD=0 sh scripts/wheel_smoke.sh

README.md

@@ -48,18 +48,59 @@ run summaries at that boundary.
 
 ## Quick Start
 
+### 1. Credential-free offline demo
+
+The fastest first success needs neither Hermes nor provider credentials. From a
+checkout:
+
 ```bash
 python3 -m venv .venv
 . .venv/bin/activate
-pip install -e .
+python -m pip install -e .
+
+zeus demo up
+zeus demo status
+zeus demo down
+```
+
+The demo uses Zeus' packaged fake-Hermes executable and stores its disposable
+runtime under `ZEUS_STATE_DIR` (the workspace-local `.zeus/` directory by
+default). It exercises real profile rendering and process lifecycle behavior
+without contacting a provider.
+
+### 2. Real Hermes setup
+
+Check the installed Hermes version, then prepare a private workspace secret
+file:
+
+```bash
+hermes version
 cp .env.example .env
+chmod 0600 .env
+```
+
+`.env.example` contains empty placeholders and is not ready to import. Stop here
+until `.env` contains a real, non-empty provider key required by the selected
+template, such as `OPENROUTER_API_KEY` for `coding-bot`. As an alternative,
+provide the same named secret through a secure process-environment mechanism.
+
+Then validate Zeus and render the real Hermes profile:
 
+```bash
 zeus doctor
 zeus template list
-zeus bot create coder --template coding-bot
+zeus bot create coder --template coding-bot --env-from OPENROUTER_API_KEY
 zeus bot doctor coder
 ```
 
+`--env-from NAME` imports a named value from the process environment first and
+then the trusted workspace `./.env`; the value never enters the Zeus argument
+list or command output. A present but empty process value is an error and does
+not fall back to `.env`. Keep the workspace `.env` private with `chmod 0600 .env`.
+The legacy `--env NAME=VALUE` form remains available
+for non-secret compatibility values, but is unsafe for secrets because command
+arguments can be retained in shell history and exposed in process listings.
+
 Safety model: Zeus is a local process orchestrator, not a sandbox. Use Docker or
 another Hermes terminal backend for untrusted tasks. Do not expose the API
 directly to a network; keep it on loopback or behind a separately hardened
@@ -74,8 +115,10 @@ ZEUS_API_KEY=change-me sh scripts/start.sh
 
 ## 60-Second Demo
 
-The asciinema recording in [docs/assets/demo.cast](docs/assets/demo.cast) mirrors the local
-operator flow:
+The pre-recorded asciinema cast in [docs/assets/demo.cast](docs/assets/demo.cast)
+illustrates the local operator flow. It is not evidence that the current Zeus
+checkout is compatible with whichever Hermes version is installed today; use
+the live verification steps below for that evidence.
 
 ```bash
 zeus doctor
@@ -98,6 +141,7 @@ zeus bot stop coder
 - [Operations](docs/OPERATIONS.md)
 - [Reconcile scheduling](docs/RECONCILE.md)
 - [Release process](docs/RELEASE.md)
+- [Compatibility policy](docs/COMPATIBILITY.md)
 - [Roadmap](docs/ROADMAP.md)
 - [Contributing](CONTRIBUTING.md)
 - [Code of conduct](CODE_OF_CONDUCT.md)
@@ -112,16 +156,10 @@ Zeus is maintained by [BrainX](https://github.com/brainx). See [Credits](CREDITS
 - Hermes Agent installed as `hermes` for real bot startup
 - Optional Docker or another Hermes terminal backend for stronger execution isolation
 
-No Python package dependencies are required for the current MVP.
-
-## Setup
-
-```bash
-python3 -m venv .venv
-. .venv/bin/activate
-pip install -e .
-cp .env.example .env
-```
+Zeus has no required third-party Python runtime dependencies. Development and
+build tools are available separately through the optional `dev` dependency
+group; see [Contributing](CONTRIBUTING.md). The exact automated platform and
+Python matrix is recorded in the [compatibility policy](docs/COMPATIBILITY.md).
 
 ## Install Modes
 
@@ -197,12 +235,17 @@ ZEUS_VERIFY_START_GATEWAY=1 sh scripts/verify_real_hermes.sh
 ```
 
 The gateway check enables Hermes' local `api_server` platform on loopback,
-passes a random per-run API key, probes `/health`, and then stops the bot.
+passes an isolated local API key, starts with readiness waiting, verifies process
+ownership, probes `/health`, and then stops the bot. Committed CI runs this flow
+without provider credentials against the fully hash-locked Hermes Agent 0.19.0
+environment documented in the compatibility policy.
 
 For a clean Debian/Ubuntu host, use the fresh VPS harness:
 
 ```bash
-ZEUS_VPS_INSTALL_PACKAGES=1 ZEUS_VPS_INSTALL_HERMES=1 bash scripts/fresh_vps_verify.sh
+ZEUS_VPS_HERMES_INSTALLER_SHA256='<64-hex SHA-256 of the reviewed installer>' \
+ZEUS_VPS_INSTALL_PACKAGES=1 ZEUS_VPS_INSTALL_HERMES=1 \
+bash scripts/fresh_vps_verify.sh
 ```
 
 See [Fresh VPS test](docs/FRESH_VPS_TEST.md) for gateway and async-delegation probes.
@@ -286,6 +329,20 @@ source tree.
 Rendered `.env` values are serialized with quoting when needed so whitespace, `#`,
 quotes, and backslashes cannot create extra assignments.
 
+Import template secrets by name instead of placing their values in argv:
+
+```bash
+zeus bot create coder \
+  --template coding-bot \
+  --env-from OPENROUTER_API_KEY
+```
+
+Zeus looks for each imported name in the process environment and then the
+trusted workspace `./.env`. Process values take precedence. Missing and empty
+values fail bot creation without printing the value. Keep `./.env` mode `0600`;
+Zeus also writes the imported values only to the selected profile's mode-`0600`
+`.env` file.
+
 Built-in templates include OpenRouter-backed bots and `deepseek-coding-bot`, which uses Hermes' native DeepSeek provider with `DEEPSEEK_API_KEY`. Example templates also cover gateway operations, log triage, and documentation writing.
 
 Each template should set a bounded async delegation cap: