Skip to content

docs(sandbox): document opencode.db image-upgrade remediation - #2663

Merged
Seluj78 merged 2 commits into
agent-of-empires:mainfrom
jerome-benoit:docs/sandbox-opencode-db-image-upgrade
Jul 6, 2026
Merged

Seluj78 merged 2 commits into
agent-of-empires:mainfrom
jerome-benoit:docs/sandbox-opencode-db-image-upgrade

Conversation

@jerome-benoit

@jerome-benoit jerome-benoit commented Jul 5, 2026 •

Copy link
Copy Markdown
Collaborator

Description

Follow-up to #2650 (which fixed #2605). Adds a Troubleshooting entry to docs/guides/sandbox.md documenting how to recover when a sandbox container-image upgrade ships an OpenCode release with a schema change that is not forward-compatible with the persisted sandbox DB.

Context

Reviewer @Seluj78 flagged this as an acknowledged trade-off on #2650:

Emptying clean_files also drops the container-image-update reset the struct doc originally described. If a future container bumps opencode past a non-forward-migratable schema, an old sandbox DB could hit a drizzle migration failure instead of being wiped. The PR leans on drizzle forward-migration owning that path, which is the designed behavior and the lesser evil versus destroying session identity on every kill. Acknowledged in the issue thread; accept as-is.

This PR does not change the trade-off; it just makes the recovery path discoverable in the docs.

Cross-validation

Before writing, I ran an Oracle cross-validation pass on the claim (opencode uses drizzle → drizzle migrations forward-only → sandbox DB path is ~/.local/share/opencode/sandbox/opencode.db* → failure mode is real). All six substantive points came back VALID, including that the exact same failure class is already observed upstream on standalone OpenCode CLI upgrades (anomalyco/opencode#31119 documents remediation via rm ~/.local/share/opencode/opencode.db; anomalyco/opencode#16678 documents the drizzle name-vs-hash migration cutover breaking pre-existing DBs). The sandbox-image bump is mechanically the same migrator hitting the same problem, just via a different version-change vector.

Shape

New Troubleshooting subsection follows the existing Symptoms / Cause / Fix layout of the OOM entry directly above it:

  • Symptoms: concrete error strings a user will actually see (no such column, CREATE TABLE ... already exists, Failed to run the query).
  • Cause: ~/.local/share/opencode/sandbox/opencode.db* persists post-bug(session): sandboxed opencode --session resume fails; opencode.db wiped on every launch by unconditional clean_files #2605 for ses_* resume identity → drizzle is forward-only → incompatible new migrations abort boot. Upstream issue refs for evidence.
  • Fix: one-line rm -f on the three DB files. Scoped to the sandbox subdir, host OpenCode state untouched.
  • Note: reactive framing — rare, most upgrades migrate cleanly, escalate upstream if repeated.

PR Type

  • New Feature
  • Bug Fix
  • Refactor
  • Documentation
  • Infrastructure / CI

Checklist

  • New and existing tests pass (docs-only, no code impact)
  • Documentation was updated where necessary (this PR)
  • For UI changes: included screenshot or recording (n/a)

Test Coverage Analysis

Web dashboard / structured view (Playwright user story)

  • N/A: this PR doesn't change a user-facing dashboard flow

TUI / CLI (e2e test)

  • N/A: this PR doesn't change TUI rendering, a CLI subcommand, or session lifecycle

AI Usage

  • No AI was used
  • AI was used

AI Model/Tool used: claude-opus-4-7

Any Additional AI Details you'd like to share:

Drafting, cross-validation, and wording were assisted by claude-opus-4-7. The follow-up direction (docs vs. code change) was proposed by @Seluj78's review of #2650 explicitly acknowledging the trade-off as-is. An Oracle cross-validation pass verified six substantive points (opencode uses drizzle-orm/bun-sqlite, drizzle migrations are forward-only, the sandbox DB path is correct, the failure class is observed upstream, no pre-fix behavior would have handled schema bumps more gracefully than auto-wipe, and this codebase's docs style supports documenting observed failures reactively) before any file was written.

  • I am an AI Agent filling out this form (check box if true)

Added a new troubleshooting entry to docs/guides/sandbox.md for a rare sandbox startup failure after an OpenCode container image upgrade.

The update:

  • explains the visible error symptoms and root cause
  • documents that sandbox OpenCode database files now persist between sessions
  • gives a targeted recovery step to delete only the sandbox OpenCode DB files
  • clarifies that host OpenCode data is unaffected

Benefit: this helps users quickly recover from upgrade-related schema incompatibilities without losing their main OpenCode state.

Follow-up to agent-of-empires#2650 (fix agent-of-empires#2605). Reviewer Seluj78 flagged an acknowledged
trade-off in the merged fix: emptying clean_files for the opencode
data-dir mount also drops the container-image-update reset the struct
doc originally described. If a future image bump ships an opencode
release whose drizzle migrations are not forward-compatible with the
pre-existing sandbox DB, opencode aborts on boot. This is not
hypothetical - the same failure class is observed upstream on
standalone opencode CLI upgrades (anomalyco/opencode#31119, #16678).

Add a Troubleshooting entry to docs/guides/sandbox.md following the
existing Symptoms/Cause/Fix shape (matches the OOM entry), with:

- The failing scenario symptoms
- Root cause chain: sandbox DB persists (agent-of-empires#2605) -> drizzle forward-only
  -> incompatible migration on old DB -> boot abort
- One-line remediation: rm -f ~/.local/share/opencode/sandbox/opencode.db{,-wal,-shm}
- Reactive framing (rare event, most upgrades migrate cleanly)
- Upstream anomalyco/opencode issue references so the entry ages with
  evidence rather than speculation

Docs-only, no code impact, no test impact.
@coderabbitai

coderabbitai Bot commented Jul 5, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c14bef6a-b18f-4e7a-8123-43c7ca4379f6

📥 Commits

Reviewing files that changed from the base of the PR and between 83d110c and c4b5c57.

📒 Files selected for processing (1)
  • docs/guides/sandbox.md

Walkthrough

Adds a troubleshooting subsection to the sandbox guide documentation explaining why sandboxed OpenCode may fail to start after a container image upgrade, describing the symptom, cause (stale SQLite DB schema), and the manual fix of deleting sandbox DB files before restarting.

Changes

Sandbox Troubleshooting Documentation

Layer / File(s) Summary
Add DB migration troubleshooting guidance
docs/guides/sandbox.md
New subsection documents symptoms, cause (incompatible persisted sandbox SQLite DB/schema migrations after image upgrade), and the fix of deleting sandbox DB files under sandbox/ before restarting the session.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Suggested reviewers: Seluj78

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Title check ⚠️ Warning The title is related, but it misses the required Conventional Commit prefix format (docs: etc.), so it doesn't meet the repository title rule. Change it to a Conventional Commit title like docs: document opencode.db image-upgrade remediation and keep it imperative.
Linked Issues check ⚠️ Warning This PR documents the recovery path, but it does not implement the #2605 requirement to stop wiping sandbox opencode.db files or preserve resume capability. If compliance with #2605 is required, add the session-resume fix; otherwise remove the issue link and keep this as documentation-only follow-up.
✅ Passed checks (3 passed)
Check name Status Explanation
Description check ✅ Passed The description matches the template with Description, PR Type, Checklist, Test Coverage Analysis, and AI Usage sections filled out.
Out of Scope Changes check ✅ Passed The change stays focused on sandbox OpenCode recovery docs and adds no unrelated code or behavior changes.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
✨ Simplify code
  • Create PR with simplified code

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

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

Two micro-fixes surfaced by a self-review pass on PR agent-of-empires#2663:

- Fix code block: replace bash-only brace expansion
  `opencode.db{,-wal,-shm}` with POSIX-portable glob `opencode.db*`.
  Brace expansion fails in dash/sh (Debian /bin/sh, cron, Alpine)
  and fish; the glob works on all POSIX shells and is safe here
  because skip_entries guarantees no unrelated file matches that
  prefix in the sandbox subdir.

- Escalation note: drop backticks around `anomalyco/opencode` and
  turn it into an explicit Markdown link. It's an org/repo path,
  not a code identifier; the link maximizes affordance for users
  who actually hit the failure and need to escalate upstream.

Zero content change beyond usability.
@jerome-benoit
jerome-benoit marked this pull request as ready for review July 5, 2026 13:34
@jerome-benoit
jerome-benoit requested a review from njbrake as a code owner July 5, 2026 13:34
@coderabbitai
coderabbitai Bot requested a review from Seluj78 July 5, 2026 13:35
@codecov

codecov Bot commented Jul 6, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.02%. Comparing base (83d110c) to head (c4b5c57).
✅ All tests successful. No failed tests found.

@@            Coverage Diff             @@
##             main    #2663      +/-   ##
==========================================
- Coverage   85.04%   85.02%   -0.02%     
==========================================
  Files         272      272              
  Lines       16451    16451              
  Branches     4872     4872              
==========================================
- Hits        13990    13988       -2     
- Misses       2083     2084       +1     
- Partials      378      379       +1     

see 2 files with indirect coverage changes

Components Coverage Δ
Structured View UI 83.73% <ø> (ø)
Diff Viewer 90.61% <ø> (ø)
Session Wizard 85.54% <ø> (ø)
Settings 88.46% <ø> (ø)
Auth 97.93% <ø> (ø)
Dashboard + Sidebar 83.81% <ø> (ø)
Right Panel + Terminal 79.01% <ø> (ø)
Directory Browser, Devices, Connectivity 87.68% <ø> (ø)
Modals 81.08% <ø> (ø)
Command Palette 96.42% <ø> (ø)
App Shell 54.34% <ø> (ø)
Hooks 87.51% <ø> (-0.05%) ⬇️
Lib (API client + utils) 93.39% <ø> (-0.03%) ⬇️

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 83d110c...c4b5c57. Read the comment docs.

@Seluj78
Seluj78 merged commit 1f496dd into agent-of-empires:main Jul 6, 2026
29 checks passed
@njbrake njbrake mentioned this pull request Jul 8, 2026
4 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug(session): sandboxed opencode --session resume fails; opencode.db wiped on every launch by unconditional clean_files

2 participants