Skip to content

Commit 091e060

Browse files
committed
docs(forklog): record the -s hang fix for a locked database at startup
A new feature record covers the TUI worker's error replies (c50b736, upstream issue anomalyco#54934 and PR anomalyco#54936 against v1). The session maintenance record gains the bounded write-lock retry at startup (22e6326) in its safety contract and timeline. The 2026-10-12 session record has the cause, the reproduction on vt-243 against vt-248 with several opencode processes starting on a locked database, and the installs on both hosts. AI-Tool: opencode 1.18.34-vt-128-907b3bc518 AI-Model: anthropic/claude-opus-5-5 AI-Variant: max AI-Platform: linux AI-Harness: Vibeterm a2d1757 AI-Session-ID: ses_eebf9a83fffeIQQwW9gVFo5jaO
1 parent c50b736 commit 091e060

4 files changed

Lines changed: 267 additions & 0 deletions

File tree

‎.vibeterm/forklog/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,9 +96,16 @@ carries every feature forward unchanged. That commit includes the full
9696
- [Log which process holds the SQLite write lock too long](./features/2026-10-11-sqlite-write-hold-log.md)
9797
- [Machine provenance on messages and session execution](./features/2026-10-10-machine-provenance.md)
9898
- [Syntax coloring in tool calls: bash, heredocs, file languages, tool input](./features/2026-10-11-tool-syntax-coloring.md)
99+
- [Answer a failed TUI worker request instead of hanging](./features/2026-10-12-tui-worker-error-reply.md)
99100

100101
## Session records
101102

103+
- [2026-10-12 `ses_eebf9a83fffeIQQwW9gVFo5jaO`](./sessions/2026-10-12-tui-worker-hang.md)
104+
- `opencode -s` hung forever when a busy database failed session
105+
maintenance at startup: maintenance now retries the lock for up to 60 s,
106+
and a failed TUI worker request is answered (issue #54934, PR #54936
107+
against `v1`); build and install on both hosts.
108+
102109
- [2026-10-12 `ses_ed1e2b932ffe6tTqhsOiGuYXRE`](./sessions/2026-10-12-tool-input-compact.md)
103110
- Tool input block: one row per value while collapsed, compact YAML lists;
104111
PR #54707 amended; build and install on both hosts.
Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Answer a failed TUI worker request instead of hanging
2+
3+
## Identity
4+
5+
- Status: active
6+
- Integration branch: `dev-nowaker`
7+
- Development branch(es): `rpc-error-reply` (off upstream `v1` `dfb56f76c7`; also the upstream PR head `2cef65ac7a`)
8+
- First local commit: `c50b7366df` (cherry-pick of `2cef65ac7a`)
9+
- Current local commit(s): `c50b7366df`
10+
- Upstream base when introduced: `dfb56f76c7` (upstream `v1`, `v1.19.0`)
11+
- Last checked against upstream: `dfb56f76c7`
12+
- Upstream: issue [#54934](https://github.com/anomalyco/opencode/issues/54934), PR [#54936](https://github.com/anomalyco/opencode/pull/54936) against `v1`
13+
14+
## Original request
15+
16+
Prompted by a hang report from 19b `ses_eeadda349ffep0Jwwis5g1DJXi`:
17+
18+
> From ses_eeadda349ffep0Jwwis5g1DJXi (19b/19c): an opencode
19+
> instant-session-screen HANG in the fork, live and inspectable right now on
20+
> desktop.
21+
22+
and the coordinator `ses_ef8235798ffejGr4sa22eXmVNv`:
23+
24+
> Fork regression rule: find the fork commit that introduced the missing reply
25+
> (`git log -p -S '<unique substring>'` on dev-nowaker) and fix it on that
26+
> feature's branch/PR, not as an unrelated new branch. If it traces to upstream
27+
> code we never touched, it's a fresh upstreamable fix: new branch off
28+
> github/v1, issue + PR against v1 (v1 note first, attribution last, no AI
29+
> trailers), then onto dev-nowaker. Data-loss/hang fixes may skip the v1 note.
30+
31+
## Goals
32+
33+
- A request to the TUI's server worker that throws gets an answer: the TUI's
34+
call rejects with the error's message instead of waiting forever.
35+
- An error with an empty message is reported by its cause's message, as
36+
`Server.listen`'s `ServeError` for a taken port needs.
37+
38+
## Non-goals
39+
40+
- A worker that dies with calls pending (upstream #34981, #42885) is not
41+
handled.
42+
- RPC calls get no timeout: a handler that never settles still leaves its
43+
caller waiting.
44+
45+
## Rationale and constraints
46+
47+
- `Rpc.listen` in `packages/opencode/src/util/rpc.ts` replied only when the
48+
method returned, and the worker's `unhandledRejection` handler is a no-op, so
49+
a throwing handler left the caller's promise pending forever. The TUI waits
50+
on the worker before it draws (the `--port` listener, `validateSession` for
51+
`-s`), so the screen stayed blank or on "Loading session…".
52+
- In the fork, the trigger was session maintenance failing the database layer
53+
at startup under a locked database; see
54+
[Session replacement maintenance](./session-maintenance.md) (`22e6326a61`).
55+
Upstream `v1` hangs the same way on `opencode --port <taken port>`.
56+
- The reply carries the message as a string and the client rejects with
57+
`new Error(message)`, so the failure reaches the TUI's existing error
58+
handling, which prints it and exits 1.
59+
60+
## Changes
61+
62+
| Commit | Workday | Change | Stable seam |
63+
|---|---|---|---|
64+
| `c50b7366df` | 2026-10-12 | `Rpc.listen` answers a failed request with `error` (its message, or the cause's when it has none); `Rpc.client` rejects the pending call with it | `listen` and `client` in `packages/opencode/src/util/rpc.ts`; `test/util/rpc.test.ts` with `test/fixture/rpc-worker.ts` |
65+
66+
## Verification
67+
68+
- `bun test test/util/rpc.test.ts` in `packages/opencode` on tree
69+
`dfb56f76c7`: with the original `rpc.ts` 1 pass, 3 fail (no reply within
70+
2 s); with the change 4 pass.
71+
- `bun typecheck` in `packages/opencode` on the `v1` base and on the landing
72+
branch: clean. `test/util/rpc.test.ts` with `test/cli/tui/thread.test.ts`:
73+
14 pass on both.
74+
- `opencode --port 47913` from the `v1` source while another process holds the
75+
port (`tmp/repro-port.sh` in the session's scratch): original, a blank screen
76+
20 s after launch; fixed, exit 1 with
77+
`Failed to start server. Is port 47913 in use?`.
78+
- Installed `1.19.0-vt-248`: with a write lock held longer than session
79+
maintenance's 60 s retry window, three `opencode -s` exit 1 with
80+
`Error: Failed to execute statement` instead of staying on
81+
"Loading session…"; see the session record.
82+
83+
## Timeline
84+
85+
- 2026-10-12 [`ses_eebf9a83fffeIQQwW9gVFo5jaO`](../sessions/2026-10-12-tui-worker-hang.md) -
86+
introduce; upstream issue #54934 and PR #54936 against `v1`; build and
87+
install on desktop and m4max (`1.19.0-vt-248-dfb56f76c7`).
88+
89+
## Current maintenance notes
90+
91+
- Drop the fork commit once PR #54936, or an equivalent, is in the upstream
92+
`v1` the fork is based on.
93+
- A failed SQL statement reaches the user as the `SqlError`'s generic
94+
`Failed to execute statement`; its cause, such as `database is locked`, is
95+
not sent.
96+
97+
### Upstream integration checklist
98+
99+
- Locate each stable seam in the new upstream tree.
100+
- Classify the customization as preserved, conflicted, superseded, or removed.
101+
- Reverse any deliberate uncommitted patch before merging, then reapply its
102+
canonical patch afterward.
103+
- Regenerate derived clients or schemas instead of editing generated files.
104+
- Run the feature's focused tests and affected package typechecks.
105+
- Build through the host's canonical installer and verify the installed binary.
106+
- Confirm protected services kept the same PID and start timestamp.
107+
- Link a new timeline row to the current session record.
108+
- Update `Last checked against upstream`.

‎.vibeterm/forklog/features/session-maintenance.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@
2323
- Existing connections retain their TEMP guards until refreshed. Installation
2424
of a binary alone does not upgrade their capability.
2525
- Unknown expression or partial unique indexes fail closed during installation.
26+
- Registration and guard repair take the write lock through
27+
`DatabaseTransaction.immediate`, retrying for up to 60 s while another
28+
process holds it. A lock held longer still fails startup.
2629
- Tests cover REPLACE, UPDATE collisions, composite NOCASE/RTRIM keys, migration
2730
rollback/idempotence, emergency activation, and unrelated-session writes.
2831
- A 500,000-row fixture executes 195 update / 134 insert VM steps with both
@@ -49,4 +52,12 @@
4952
- 2026-10-11 [`ses_ed5f9f826ffeno6fI51rL96d5Q`](../sessions/2026-10-11-upstream-v1-19.md) -
5053
rebased unchanged onto upstream `v1` `dfb56f76c7` (`v1.19.0`).
5154
Evidence: patch-identical in `git range-diff`; that session's gates.
55+
- 2026-10-12 [`ses_eebf9a83fffeIQQwW9gVFo5jaO`](../sessions/2026-10-12-tui-worker-hang.md) -
56+
`22e6326a61`: registration and guard repair retry the write lock for up to
57+
60 s instead of failing the database layer after the 5 s busy timeout, which
58+
left `opencode -s` hanging when processes started on a locked database
59+
(single `BEGIN IMMEDIATE` since `1eccd8068e`). Evidence: new lock-holder test
60+
in `session-maintenance-startup.test.ts` (red before, green after); 60
61+
maintenance and transaction tests pass; installed `1.19.0-vt-248` repro in
62+
the session record.
5263

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
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

Comments
 (0)