feat: add weekly session retention

[laurenceputra]

Summary

• add opt-in --retention-days / OPENCODE_WEB_RETENTION_DAYS configuration for weekly inactive-session cleanup
• run a mapped-user, health-gated scheduler with persistent success markers and tini lifecycle supervision
• prune through authenticated OpenCode APIs with hierarchy/activity checks, direct deletion verification, timeouts, version gating, and fail-closed behavior
• update installer, self-update assets, docs/specs, skills/contracts, release metadata, and CI coverage

Safety

• disabled by default
• preserves projects, accounts, provider auth, and configuration
• never mutates SQLite or WAL/SHM files directly
• supports OPENCODE_WEB_RETENTION_DRY_RUN=1
• documents the residual non-atomic status-to-delete race in OpenCode's current API

Validation

• bash tests/run.sh
• bash tests/version_guard.sh
• bash -n for changed shell scripts
• node --check .opencode_web_yolo_retention.js
• git diff --check

ShellCheck and Docker were unavailable locally and remain covered by CI.

[Copilot]

🔵 Needs a closer look

It introduces an automated scheduler that irreversibly deletes user sessions via an experimental API with a self-acknowledged residual status-to-delete race, and touches PID 1/signal handling and auth, warranting human review.

Pull request overview

This PR adds an opt-in weekly cleanup of inactive OpenCode root sessions to the opencode_web_yolo wrapper. When OPENCODE_WEB_RETENTION_DAYS/--retention-days is enabled, the container starts OpenCode, waits for authenticated /global/health, then runs a mapped-user, tini-supervised scheduler that prunes old, inactive sessions through the authenticated OpenCode HTTP APIs. The feature is disabled by default and is heavily guarded (version gating, fetch/verify timeouts, hierarchy/status validation, direct-404 delete verification, persistent success marker, and fail-closed behavior) to preserve projects, accounts, provider auth, and configuration. It fits into the existing wrapper/entrypoint/runtime contract and is accompanied by matching installer, self-update, docs, spec, skills, release metadata, and CI/test coverage.

Changes:

• New Node retention worker (.opencode_web_yolo_retention.js) and shell supervisor (.opencode_web_yolo_runtime.sh), wired into the entrypoint behind tini -s -g PID 1.
• Wrapper flag/config/health/dry-run integration (--retention-days, timeouts, poll interval), plus a security hardening that passes OPENCODE_SERVER_PASSWORD by reference instead of inline.
• Extensive deterministic tests (tests/test_session_retention.sh), CI additions, and synchronized docs/spec/changelog/version bump to 0.2.1.

File summaries

File	Description
.opencode_web_yolo_retention.js	New authenticated worker: list/paginate, hierarchy mapping, status checks, serial delete with 404 verification, fail-closed validation.
.opencode_web_yolo_runtime.sh	New app/scheduler supervisor: health-gated start, signal forwarding, app-exit passthrough.
.opencode_web_yolo_entrypoint.sh	Validates retention days and routes to the supervisor when enabled; unchanged direct exec when disabled.
.opencode_web_yolo.sh	Flag parsing/validation, health & dry-run output, docker env wiring, password-by-reference.
.opencode_web_yolo_config.sh	Default retention env values sourced before config override.
.opencode_web_yolo.Dockerfile	Adds tini, copies new runtime/worker assets, tini-based ENTRYPOINT.
.opencode_web_yolo_completion.bash/.zsh	Adds --retention-days completion.
install.sh / tests/test_helpers.sh / tests/version_guard.sh	Register the two new managed runtime files.
tests/test_session_retention.sh + other test files	New integration/coverage plus registrations in the suite and CI.
.github/workflows/ci.yml	Adds syntax/shellcheck/node --check/tini presence checks.
README.md / TECHNICAL.md / docs/specs/... / skills	Operator + contract documentation of the feature.
VERSION / CHANGELOG.md	Release metadata bumped to 0.2.1.

Review details

• Files reviewed: 29/29 changed files
• Comments generated: 1
• Review effort level: Balanced

---

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