|
| 1 | +# `opencode -s` hang on a locked database: maintenance retry and worker error replies |
| 2 | + |
| 3 | +## Identity |
| 4 | + |
| 5 | +- Workday: 2026-10-12 |
| 6 | +- Session: `ses_eebf9a83fffeIQQwW9gVFo5jaO` |
| 7 | +- Agent/platform: `Sisyphus` on `anthropic/claude-opus-5-5` (variant max) / linux, Vibeterm |
| 8 | +- Repository: `~/projekty/webapps/opencode` |
| 9 | +- Integration branch: `dev-nowaker` |
| 10 | +- Development branch(es): `rpc-error-reply` (off upstream `v1` `dfb56f76c7`, upstream PR head `2cef65ac7a`); `session-maintenance-retry` (off `dev-nowaker`, also the landing branch); `rpc-hang-fork-probe` (throwaway diagnosis worktree) |
| 11 | +- Upstream base: `dfb56f76c7` (upstream `v1`, `v1.19.0`); unchanged |
| 12 | +- Source result commit(s): `22e6326a61` (maintenance retry), `c50b7366df` (cherry-pick of `2cef65ac7a`) |
| 13 | +- Forklog commit: this file's introducing commit |
| 14 | + |
| 15 | +## User requests |
| 16 | + |
| 17 | +19b `ses_eeadda349ffep0Jwwis5g1DJXi` reported the hang: |
| 18 | + |
| 19 | +> From ses_eeadda349ffep0Jwwis5g1DJXi (19b/19c): an opencode |
| 20 | +> instant-session-screen HANG in the fork, live and inspectable right now on |
| 21 | +> desktop. |
| 22 | +
|
| 23 | +The coordinator `ses_ef8235798ffejGr4sa22eXmVNv` asked for the fix and report; |
| 24 | +the regression rule is quoted in the |
| 25 | +[feature record](../features/2026-10-12-tui-worker-error-reply.md#original-request): |
| 26 | + |
| 27 | +> Report to me when done, with: the cause in plain words, the introducing |
| 28 | +> commit, the dev-nowaker commits on both remotes, the installed vt version on |
| 29 | +> desktop AND m4max (build.sh with the v2 guard gate), any PR, a real |
| 30 | +> reproduction before/after (locked DB while several opencodes start), and |
| 31 | +> try-steps for the user. Also correct what you told 19b |
| 32 | +> (ses_eeadda349ffep0Jwwis5g1DJXi) with a vibeterm_notify_session queue note. |
| 33 | +
|
| 34 | +## Goals |
| 35 | + |
| 36 | +- Find why a restarted `opencode -s` tab (pid 4182609, `1.19.0-vt-241`) sat on |
| 37 | + "Loading session…" for 9.8 h, and make a busy database at startup delay |
| 38 | + opencode or end it with an error, never hang it. |
| 39 | + |
| 40 | +## Constraints and non-goals |
| 41 | + |
| 42 | +- The hung process was inspected read-only, then released to 19b. |
| 43 | +- Isolation: scratch `XDG_*`, `OPENCODE_TOOLS_DATA_DIR`, |
| 44 | + `OPENCODE_PLUGINS_DATA_DIR` and `OPENCODE_DB`, throwaway tmux socket |
| 45 | + `iso19hang`, provider pointed at a closed port. |
| 46 | +- No TUI tab, service or vibeterm tmux server restarted. |
| 47 | + |
| 48 | +## Cause |
| 49 | + |
| 50 | +- `opencode -s` checks the session through the in-process server worker |
| 51 | + before it shows anything (`validateSession`, then `Rpc` `fetch`). |
| 52 | +- Session maintenance registers itself while the database layer is built, in |
| 53 | + one `BEGIN IMMEDIATE` (introduced in `1eccd8068e`). When another process |
| 54 | + held the write lock past the 5 s busy timeout, the registration failed, the |
| 55 | + database layer died with it, and `app.fetch` threw instead of returning an |
| 56 | + error response. |
| 57 | +- Upstream's `Rpc.listen` answers only a request that returns, and the worker |
| 58 | + swallows the rejection, so the TUI waited forever. Under the same 20 s lock, |
| 59 | + upstream `v1` answers in about 7 s with a 500, and opencode exits with an |
| 60 | + error. |
| 61 | + |
| 62 | +## Branch and upstream movement |
| 63 | + |
| 64 | +| Repository | Branch | Before | After | Action | |
| 65 | +|---|---|---|---|---| |
| 66 | +| `opencode` | `rpc-error-reply` | - | `2cef65ac7a` | new branch on upstream `v1` `dfb56f76c7`; pushed to `nowaker-github` and `origin`; issue #54934, PR #54936 against `v1` | |
| 67 | +| `opencode` | `dev-nowaker` | `185940b77b` | `c50b7366df` + this forklog commit | `22e6326a61` and the cherry-pick `c50b7366df` on `session-maintenance-retry`, rebased onto the `.scm` typecheck fix; fast-forward; pushed to both remotes | |
| 68 | + |
| 69 | +## Features touched |
| 70 | + |
| 71 | +| Feature | Outcome | Evidence | |
| 72 | +|---|---|---| |
| 73 | +| [Answer a failed TUI worker request instead of hanging](../features/2026-10-12-tui-worker-error-reply.md) | introduced | `c50b7366df`; same-test red/green; port and lock repros | |
| 74 | +| [Session replacement maintenance](../features/session-maintenance.md) | fixed | `22e6326a61`; lock-holder test red/green; maintenance suites | |
| 75 | + |
| 76 | +## Other delivered work |
| 77 | + |
| 78 | +- The opencode package had not typechecked on `dev-nowaker` since |
| 79 | + `60edf2a182`: 5 TS2307 errors on its `.scm` imports. The pre-push hook |
| 80 | + replayed a cached turbo pass for `opencode#typecheck`, whose hash ignores |
| 81 | + tui files, so the first push touching `packages/opencode` was going to be |
| 82 | + refused. Its owner `ses_ed1e2b932ffe6tTqhsOiGuYXRE` landed the fix tested |
| 83 | + here (`8e3a183698`, `*.scm` declared in `packages/opencode/src/audio.d.ts`) |
| 84 | + and amended PR #54706. |
| 85 | +- 19b got the cause by a queued note; an earlier note from this session had |
| 86 | + wrongly called the hang an upstream `v1` bug. |
| 87 | + |
| 88 | +## Verification |
| 89 | + |
| 90 | +- `bun test test/session-maintenance-startup.test.ts -t "another process holding the write lock"` |
| 91 | + in `packages/core` on `bfc03b0daf`: without the change exit 1 |
| 92 | + (`database is locked`); with it 1 pass. |
| 93 | +- `packages/core` maintenance, transaction, acquisition and event-contention |
| 94 | + suites: 60 pass, 0 fail. After the rebase: startup and acquisition suites |
| 95 | + 14 pass. |
| 96 | +- `bun typecheck` in `packages/core` and `packages/opencode` on the landing |
| 97 | + branch: clean. |
| 98 | +- RPC change: see the feature record. |
| 99 | +- Source repro on the landing branch (`tmp/repro-hang.sh`): with a 30 s write |
| 100 | + lock while `opencode -s` starts, it loads within 10 s of the release; the |
| 101 | + unfixed fork stays blank. |
| 102 | +- Installed binaries, three `opencode -s` started at once while another |
| 103 | + process holds the write lock (`tmp/repro-many.sh`), checked 10, 30 and 60 s |
| 104 | + after the release: |
| 105 | + |
| 106 | + | Binary | Lock | Result | |
| 107 | + |---|---|---| |
| 108 | + | desktop `1.19.0-vt-243` | 30 s | all three still on "Loading session…" 60 s after the release | |
| 109 | + | desktop `1.19.0-vt-248` | 30 s | all three loaded within 10 s | |
| 110 | + | desktop `1.19.0-vt-248` | 90 s | all three exit 1 with `Error: Failed to execute statement` | |
| 111 | + | m4max `1.19.0-vt-248` | 30 s | all three loaded within 10 s | |
| 112 | + |
| 113 | +## Build and install |
| 114 | + |
| 115 | +- Build command: `.vibeterm/build.sh` on both hosts, with `VIBETERM_V2_GUARD` |
| 116 | + set to opencode-tools' `vibeterm-v2-guard`; the v2 migration guard gate |
| 117 | + passed on both. |
| 118 | +- Installed artifact: desktop `1.19.0-vt-248-dfb56f76c7` (inode `49962236`), |
| 119 | + m4max `1.19.0-vt-248-dfb56f76c7` (inode `31147540`); the retry marker and |
| 120 | + the instant-screen strings are present on both. |
| 121 | +- Retry-header cap: the dirty diff matched the canonical patch on both hosts |
| 122 | + before the build. |
| 123 | +- Running services: none restarted; `opencode-serve-tailscale` PID `4038768` |
| 124 | + and `opencode-serve-lan` PID `4040905` unchanged across the build. |
| 125 | + |
| 126 | +## Commit provenance |
| 127 | + |
| 128 | +- `22e6326a61` - session maintenance waits for a busy database before failing |
| 129 | + startup. |
| 130 | +- `c50b7366df` - a failed TUI worker request gets an answer; cherry-pick of |
| 131 | + upstream PR commit `2cef65ac7a`, which carries no AI trailers. |
| 132 | +- Required trailer: `AI-Session-ID: ses_eebf9a83fffeIQQwW9gVFo5jaO` |
| 133 | + |
| 134 | +## Unknowns and blocked verification |
| 135 | + |
| 136 | +- What held the desktop database's write lock during the 03:54 restart of |
| 137 | + three tabs is not established; session `ses_ed0dd417cffec7Cd7k2Zu2yCWi` |
| 138 | + was mid-turn then, and the other two restarted processes were starting. |
| 139 | +- Upstream CI for PR #54936 has not run; fork PRs await maintainer approval. |
| 140 | +- A database locked longer than 60 s at startup still ends startup, with the |
| 141 | + generic message `Failed to execute statement`. |
0 commit comments