Repository navigation
Commit 6f6c0e5
authored
t2174: feat(opencode): weekly DB maintenance routine (r913) for SQLite lock mitigation (#19630)
* t2174: feat(opencode): weekly DB maintenance routine (r913) for SQLite lock mitigation
Recurring "database is locked" errors in opencode sessions even with a single
active TUI. Live log shows `+5015ms database is locked` from session.processor,
confirming busy_timeout=5000ms IS honored but writers hold the lock longer —
typically on large bash-tool output writes (see anomalyco/opencode#21000).
Diagnostic found 10 opencode processes holding 20+ FDs on a 1.3 GB DB.
The architectural fixes (sharding, retry-with-backoff) live upstream in
anomalyco/opencode#21215, #21000, #20935, #21579 — all open. Until those land,
smaller DB = shorter lock windows. This adds a weekly SQLite maintenance
routine that runs wal_checkpoint(TRUNCATE), PRAGMA optimize, and a conditional
VACUUM (size > 500 MB OR free-page fraction > 10%).
- NEW .agents/scripts/opencode-db-maintenance-helper.sh — check/report/maintain/
auto/help subcommands. Silent no-op if opencode not installed. Refuses
maintain when opencode processes are active unless --force. Auto mode
throttled to 6-day cadence via last-run.json state. State under
~/.aidevops/.agent-workspace/work/opencode-maintenance/.
- NEW .agents/scripts/tests/test-opencode-db-maintenance.sh — 11 sandbox
assertions via XDG_DATA_HOME + HOME redirect. All 11 pass.
- EDIT .agents/scripts/routines/core-routines.sh — register r913 in
get_core_routine_entries and add describe_r913() (mirrors r906 calendar-
scheduled pattern). Sunday 04:00 weekly. Ships to all users via
aidevops update's _create_core_routine_issues.
- NEW .agents/advisories/opencode-db-maintenance-2026-04.advisory — for
existing users whose routines repos predate r913.
- NEW .agents/reference/opencode-maintenance.md — user docs covering the
problem, routine, subcommands, and architectural boundary (why we can't
fix busy_timeout, mmap_size, or retry-with-backoff from outside opencode).
Resolves #19629
* t2174: drop redundant advisory — aidevops update already seeds new core routines
The advisory was added under the mistaken assumption that existing users'
routines repos needed manual intervention to pick up r913. They don't.
aidevops update runs setup.sh --non-interactive, which invokes
_setup_run_non_interactive → setup_routines → detect_and_create_all →
init_personal → _create_core_routine_issues. That function iterates over
EVERY entry in get_core_routine_entries and idempotently creates a
tracking issue for each one (routine-log-helper.sh create-issue is
idempotent per t1964).
So on the next auto-update after this PR merges, every existing user's
routines repo automatically gets r913's tracking issue seeded. No
advisory, no manual step, nothing for the user to notice or dismiss.
Advisories are for changes that require manual user action (credentials,
config edits, new permissions). Adding a new core routine that ships
with everything it needs is not one of those.
Brief and TODO.md updated to reflect the simpler flow.
* t2174: refactor cmd_maintain into helper functions to clear complexity gate
CI's shell function complexity check flagged cmd_maintain at 126 body
lines (threshold 100). Split it into four focused functions:
- _maintain_preflight: args validation, opencode/sqlite check, process refusal
- _maintain_should_vacuum: threshold evaluation (size + freelist fraction)
- _maintain_run_steps: the three sqlite operations (checkpoint/optimize/vacuum)
- _maintain_write_state: last-run.json write and summary output
- cmd_maintain: orchestrator (~50 lines)
All four helpers communicate via return codes and stdout lines (print_* go
to stderr so they don't contaminate command substitution). Return code 100
from _maintain_preflight signals "clean no-op" (opencode not installed) so
the orchestrator can distinguish it from actual errors.
Behaviour unchanged — 11/11 tests still pass. No new complexity violations
per complexity-regression-helper.sh.
* t2174: address CodeRabbit review — ordering, dead var, fence lang, polish bundle
Six findings from CodeRabbit on PR #19630:
Actionable:
- _opencode_process_count: broaden pgrep regex from "opencode-ai/bin/\.opencode"
to "(^|/)\.?opencode($|[[:space:]])" + add lsof fallback on DB file.
Covers Homebrew, manual, and npm installs; dedups by PID.
- cmd_auto: translate cmd_maintain exit 2 (opencode active) to exit 0 so
scheduler doesn't flag expected "busy" skips as failures.
Nitpicks:
- describe_r913 moved from between r911 and r912 to after r912, restoring
strict numeric ordering of describe_rNNN functions.
- Removed unused HOME_BACKUP export in test-opencode-db-maintenance.sh
(HOME is set per-invocation via _run_helper subprocess, never mutated
in the parent shell).
- _db_size_human: replaced bc-dependent printf floats with pure-bash
integer fixed-point math. Fixes the "536870912.0 MB" failure mode on
bc-less hosts.
- VACUUM: capture stderr into a variable before print_error so SQLite
error text doesn't spam the terminal ahead of our own message.
- cmd_auto throttle parsing: jq-first with grep/sed fallback, matching
the existing pattern in cmd_report.
- opencode-maintenance.md: added "text" language tag to sample-output
fence for markdownlint MD040.
All 11 tests still pass; ShellCheck clean.
For #196291 parent dc529d8 commit 6f6c0e5
6 files changed
Lines changed: 1276 additions & 0 deletions
File tree
- .agents
- reference
- scripts
- routines
- tests
- todo/tasks
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
0 commit comments