Configure startup VACUUM timeout

[laurenceputra]

Summary

• add persistent OPENCODE_WEB_STARTUP_VACUUM_TERM_TIMEOUT_SECONDS configuration with a 300-second default
• validate and propagate the timeout through Docker, entrypoint, health, and dry-run output
• update runtime contracts, operator documentation, release metadata, and deterministic coverage

Validation

• bash tests/run.sh
• bash -n on touched shell scripts
• git diff --check

Notes

• SQLite busy timeout remains 5000 ms
• KILL escalation remains fixed at 5 seconds
• shellcheck and Docker build were unavailable in the execution environment

[Copilot]

Copilot review overview

🔵 Needs a closer look

The change modifies the container entrypoint startup path—a non-negotiable product contract area treated as a first-class regression class—and the author could not run shellcheck or a Docker build, so container-image behavior warrants final human verification.

Review effort: Balanced
Findings: None

What changed in this PR

This PR makes the startup SQLite VACUUM GNU timeout TERM deadline configurable via a new persistent OPENCODE_WEB_STARTUP_VACUUM_TERM_TIMEOUT_SECONDS setting (default 300s), replacing the previously hardcoded 300-second constant. It fits into the runtime/entrypoint contract by validating the value (positive integer bounded to INT_MAX), propagating it through Docker into the container, and surfacing it in health/--dry-run output, while keeping the SQLite 5000 ms busy timeout and fixed 5-second KILL escalation unchanged.

Changes:

• Adds the new persistent setting with bounded positive-integer validation in both the wrapper (validate_positive_integer) and the entrypoint, plus a config default and Docker -e propagation.
• Surfaces the effective value in health and --dry-run output and uses it in the entrypoint's timeout invocation and timeout-warning message.
• Updates runtime contracts (TECHNICAL.md, skills, references), operator docs (README), release metadata (VERSION 0.5.0, CHANGELOG), and deterministic tests.

File	Description
.opencode_web_yolo.sh	Validates, echoes (health/dry-run), and propagates the new timeout env var into Docker.
.opencode_web_yolo_entrypoint.sh	Reads/validates the configurable TERM timeout and uses it in timeout and the timeout warning.
.opencode_web_yolo_config.sh	Defaults the setting to 300 only when unset (preserves empty for rejection).
VERSION	Bumps to 0.5.0.
CHANGELOG.md	Documents the 0.5.0 change.
README.md	Documents the new operator setting and updated VACUUM behavior.
TECHNICAL.md	Updates entrypoint/test contract wording for the configurable timeout.
skills/​opencode-web-runtime/​SKILL.md	Updates runtime contract #7 for the new setting.
skills/​opencode-web-runtime/​references/​runtime-checklist.md	Updates the VACUUM checklist item.
skills/​opencode-web-quality-docs/​references/​test-acceptance-matrix.md	Updates the startup VACUUM test acceptance criteria.
tests/​test_startup_vacuum.sh	Adds custom-timeout, timeout-warning, and invalid-value coverage.
tests/​test_runtime_defaults.sh	Asserts config default comment and dry-run propagation.
tests/​test_health.sh	Asserts the health output shows the default timeout.
tests/​test_dry_run.sh	Asserts default/custom/max/invalid dry-run behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.