[lavaman131]

Fix six flaky or stale-reading follow-ups from the last reviews

Six items the last reviews left open (commit hashes are those of the branch rebased onto origin/main): a stale record a click could still open, three tests that failed now and then in CI (the PostgreSQL saved Planner requests, the lease peek, the hand-over test), two browser specs that broke on the clock (the planner picker across midnight, the restart test's 4 s bound), and a catalogue read that document-navigation counted as a switch's. Each is fixed at its cause, in its own signed commit, with a run that failed before and one that passes after. Only one is a product change (document-intent.ts); the other five are test faults, and the commit messages say what in the product was checked and left alone.

Nothing was widened to pass: no assertion was loosened, no wait lengthened without a reason from the design or from what is measured below, and every changed test keeps what it asserted (the hand-over test gained one assertion).

The six, with the cause of each

1. A change notice after the click (2d0ad2b8 and f38dc40c, product)

Cause. A click takes the read started on hover out of the table of reads (reads) and waits on it. A notice that the document was renamed, updated or deleted came to forget, which only searched that table, so an opening already waiting on a slow hover read was given the record from before the change.

Fix. apps/web/src/document-intent.ts keeps the openings that wait on a handed-out read in a used set, each with a drop signal. forget fires the signal of every opening of the changed document, and read races the hover read against that signal, so the opening makes its own read at once instead of waiting for the stale read to settle (2d0ad2b8 marked the read stale, which still left the opening waiting for it; a read that was slow, or never answered, held it back). The opening makes its own read exactly once: what the dropped read answers or fails with afterwards is ignored, a second notice does nothing more, and the entry leaves used as soon as the race ends. A read of another document is left as it was. The prefetched read itself is dropped from reads at use, as the brief also asked.

Evidence. bun test src/document-intent.test.ts in apps/web: with the old module restored the new held-read test (a read that never resolves; forget after the click) fails with Expected: "Own" Received: "still waiting" (26 pass, 1 fail); with the fix 27 of 27, and the whole apps/web suite 1118 pass, 2 skip, 0 fail. Three of the new tests are guards that pass either way (a change to another document; a change after the opening has its record; a second notice, or the dropped read failing afterwards, does not make the opening read twice). Browser: with a client built from the fix, e2e/document-intent.e2e.ts and document-navigation.e2e.ts ran 43 of 44; the one failure, "a pointer-dismissed navigation dialog releases focus while it exits", fails the same way on a client built from the commit before the fix (on a machine another project's browser tests were loading), so it is not this change's. A second run, with two workers, also lost "a long description card stays inside the window beside a bottom row" (a tooltip that stayed hidden), another motion check; it is not in what this change touches and was not re-run alone.

2. The flaky PostgreSQL saved Planner requests and lease peek tests (f9e50f9d, 8cafbe45, 598fa152, tests only)

Cause: not a product race. Three separate faults:

• "timed out waiting for 5 prompts" and the test after it. The fixture's waitFor looked 200 times with a setTimeout(0) between, about 0.2 s of an idle event loop. Against the memory storage a turn finishes in loop turns, so that was ample. Against PostgreSQL every step of a turn is a round trip and a commit: after the kill the four queued requests need about a hundred loop turns on a quick machine, so a runner whose database answers about half as fast runs out. CI failed exactly this way on main (run 42476309048, at deferred-restart.test.ts:71), and "mark a row a dead process had started as interrupted" waits the same way before it queues its second message.
• "PostgresError: Connection closed". A cascade, not a second failure. The test registered its storage's cleanup after the world's, and cleanups run last to first, so the database was closed before the Chat; turns still saving then logged [chat] could not save a finished turn ... Connection closed beside the real timeout.
• "postgres lease peek > shows a released or expired lease as free". The contract took a 20 ms lease and asserted it was not yet free after one more query. The database stamps the expiry when the lease is taken, and the commit and the next query come after that, so the assertion held only while the database answered within 20 ms. It was never a fact about peek.

Fixes.

• f9e50f9d (lease-peek-contract.ts): a 20 ms lease and a 60 s lease are read after the same 60 ms wait; the short one must be free and the long one still held. The claim (only a lease whose time is up is free) is kept, and what separates the two is time alone, so no read has to land inside a window. Nothing loosened, no wait lengthened.
• 8cafbe45 (deferred-restart.test.ts): the storage cleanup is registered first, so the Chat closes before its database. It changes when the tests pass or fail by nothing; it stops a failure from burying its cause.
• 598fa152 (deferred.test-fixtures.ts): waitFor gives its condition four seconds of wall clock, as the remote Planner tests' until does (three or four), which ends before bun's five-second limit on a test, so a condition that never holds is still named. No assertion changed.

Evidence. A TCP proxy in front of the disposable PostgreSQL (chopin-stage1-pg, port 5442) passes each chunk on N ms after it arrived, in both directions and in order, as a database further away than this machine's would; every series ran on a fresh database.

	Before	After
Saved-requests file, +2 ms each way, --rerun-each 10	"keep a message ..." failed 10 of 10, timed out waiting for 5 prompts (CI's message)	150 of 150 (--rerun-each 50, three tests)
Same, +5 ms each way	"keep a message" and "mark a row" each failed 5 of 5	"mark a row" and the third test pass; "keep a message" still fails by bun's 5 s limit (10 ms round trips, not a realistic CI service container)
Same, directly (no proxy)	passed	150 of 150
Same, two busy loops pinned to the test's two cores	passed	150 of 150; 150 of 150 with the +2 ms proxy as well
Lease peek contract, +5 ms each way	"shows a released or expired lease as free" failed 10 of 10, Expected: false, Received: true	100 of 100 (--rerun-each 50, both tests)
Same, with busy loops / directly		100 of 100 / 100 of 100
Lease peek on the memory adapter		100 of 100 (re-run on the final tree)
apps/server/src/chat/deferred.test.ts (memory storage, same waitFor)		1100 of 1100 (--rerun-each 20)
Teardown order, file behind +2 ms, five runs	Connection closed logged 5 times	0 times (the first test timed out in all five runs of each series, as before: same timeouts, no cascade)

Also checked, not part of this change. bun test apps/server/src/storage/postgres: 178 of 178 directly and behind a +1 ms proxy; under load 177 of 178, the one failure startup.test.ts "recovers one missed terminal Chat notice across repeated server starts", which takes 3.6 s idle and hits bun's 5 s limit under load. It is not in the brief and was not touched. There is no in-repo regression test for this item: reproducing it needs injected database latency and the repository has no such harness; the proxy runs above are the repeatable check.

3. The planner-picker "Last seen" tests across midnight (02d7738d, test only)

Cause. The page words a machine's last-seen time as a time of day when it falls today and as a date and time on another day, in the browser's time zone. The test marked the machine as seen an hour before the real clock and expected a time of day, so a run in the first hour after local midnight read "Nov 9, 11:40 PM" and failed, on a desktop and on a phone.

Fix. The test's context sets timezoneId: "UTC" and installs page.clock at noon, and the machine was seen an hour before that. What the test asserts is unchanged.

Evidence. The real spec on a disposable server with TZ=Etc/GMT-9 at 00:40 local failed for both desktop and phone ("Runs on studio. studio is offline. Last seen Nov 9, 11:40 PM."); the same run after the fix passes 2 of 2; in the machine's own zone 6 of 6 (--repeat-each=3). Re-run on the final tree with TZ=Etc/GMT-9: 2 of 2, and the whole file 41 of 41.

4. document-navigation.e2e.ts:621 (an extra GET /channels) (b5cce96c, test only)

Cause: the request is not a duplicate in the product. The test makes its second document with New document, and a created document is announced on the sidebar socket to every sidebar watching the repository, its author's included (Sidebar.Catalogue in packages/protocol/index.d.ts: "Sent to every socket watching the repository, the change's author's included"; tested in sidebar-decision-counts.e2e.ts). Each sidebar reads the catalogue once the burst has been quiet for 250 ms. A trace of one creation shows exactly one such read, 250 ms after the frame, and nothing else asking for the catalogue. The frame names the document and no revision, so a client cannot tell a change it already applied from someone else's: removing the read would be a protocol change, so the product is left as it is. The test cleared its request log about when that read fired, so it was counted as a switch's roughly one run in four. The main CI run 42596408116 failed the same way (expected 0, received 1) and passed on retry.

Fix. The test registers waitForResponse for that read before clicking New document and, once it has seen the creation's visit, awaits the response and waits for "Loading more…" to go, then clears the log and counts. The zero-reads assertion is unchanged: a read a switch caused still fails it.

Evidence. --workers=1 --repeat-each=20 on a client built before the change: 6 of 20 failed (5 with one extra GET /channels, 1 with the header staying on the new document after the click on the first). After: 20 of 20, then 25 of 25 and 25 of 25 on two fresh databases at once, 70 of 70 in all. On the final head the whole file passes (44 of 44 with document-intent).

5. The restart test's 4 s bound (b1aafa3a and 5b38e9c2, test only)

What the outage is made of (the server's own cut log and the page's socket timeline):

Part	Quick machine	Two cores shared with busy loops
The old process's cut, SIGTERM to exit (300 ms of it HANDOVER_UNREADY_MS; the page still has its socket)	0.37 to 0.43 s	0.39 to 0.43 s
The test's own gap before the new process starts	1.0 s, fixed	1.0 s, fixed
The new process's start, spawn to /api/health/ready	1.3 to 1.4 s	2.6 to 2.9 s
Total from SIGTERM	about 2.8 s	4.03 to 4.28 s

The new server says ready 27 ms after it takes the lease; the rest is loading its module graph (most of a second of it in a CPU profile), by the command the image runs. That is not changed here.

The bound is the design's, and the test applied it wrongly. The page is quiet for RESTART_QUIET_MS (5 s) from the 1012 and, once that has come, tries again within RESTART_JITTER_MS (1 s), so a server back within 4 s of the 1012 is found with the quiet still running. The test counted from SIGTERM, though the page hears nothing until the release, so the cut's 0.4 s was charged to a window it is not in. It also added a fixed second to a start time that varies by about 2x across runners, which cannot stay between the 1.5 s a blip is waited out in and 4 s everywhere. In the loaded runs whose page timeline was complete, the page reconnected 3.8 to 4.0 s after its 1012, inside the quiet, while the test failed on 4034 to 4284.

Fix. b1aafa3a bounded the outage by RESTART_QUIET_MS - RESTART_JITTER_MS taken from the constants, kept the 1.5 s blip as its lower bound, and sized the gap to aim at about 2.5 s (max(0, 2500 - the first server's measured start); the next start takes about what the first did). It counted from the old process's exit, which the test learns of through the child's close event, later than the page saw its 1012 on a slow runner. 5b38e9c2 counts from the 1012 the page sees: the page's probe stamps the first 1012 with Date.now() (lostAtWall), and the main case and both message-retry cases take the time the new server is ready and compute the outage through one helper, outageFrom1012, which fails the test if the page saw no 1012. The bounds are not changed: the upper one is the design's RESTART_QUIET_MS - RESTART_JITTER_MS (4 s) and the lower one the 1.5 s it was; only the comments that counted from the exit now count from the 1012. The 1012 comes as the process exits, so the 2.5 s aim is unchanged.

Evidence. Under two shared cores with two busy loops, at the commit before: the restart under an open tab failed 3 of 3 (Expected: < 4000, received 4001 to 4304), and 4 of 4 in an instrumented copy (4034 to 4284). After: the three restart cases passed 15 of 15 idle (outage 2.48 to 2.58 s) and 12 of 12 under the same load (2.78 to 3.34 s). On the final tree the whole file passes, 8 of 8. For 5b38e9c2: on a scratch copy of the spec in which the test sees the old process's exit 2 s late (a slow runner reaping the child), the exit-based timing passed the main case at 2492 ms and the two message-retry cases at 2458 and 2501 ms, while counting from the 1012 failed all three (Expected: < 4000, received 4506, 4553 and 4520; the exit-based figure in the same run was 2455 ms); with no lateness the two agree (2486 and 2498 ms). After it, the whole file passes 8 of 8 idle (main case 2498 ms from the 1012, 2446 ms from the exit), and the main case and both message-retry cases 9 of 9 (three repeats each) under two busy loops pinned to the test's two cores: 3122 to 3465 ms and 2454 to 3098 ms, all under 4000. The late-exit instrumentation is on a scratch copy, not in the suite. The sandboxed "two cores plus busy loops" load is a stand-in for a CI runner; no CI log with the 4.4 s figure could be recovered.

6. handover.e2e.ts:1337 "never marked Couldn't send" (8b408c04, test only)

Cause: not a listener-stop bug, not a wait that is too short. The test held the lock every fenced write takes (a PostgreSQL advisory lock), so the old process would stand at the commit of its cut, and took it 300 ms after the last message was answered, before SIGTERM. After SIGTERM the old process first settles while still serving: it commits and checkpoints every document, and a commit's checkpoint is scheduled 500 ms after it (scheduleCheckpoint in apps/server/src/plan/service.ts). Whenever the last message's checkpoint was still owed at SIGTERM, that write stopped on the held lock ahead of the listener, so the process never stopped listening, and no longer wait could help because the lock is only let go after that wait ends. On a runner that spaces commits more than 500 ms apart a checkpoint is always owed when the test locks; the CI timing itself could not be observed, so that part is inferred from the shape of the failure (the same error on three attempts in one shard on #803, and on #796, #798). The product behaved as designed: a process whose storage will not take a write does not cut.

Fix. The lock is taken when GET /api/health/ready on the old process answers draining, which is the cut's first step: it comes after every write made before the cut, with the 300 ms unready window still to run, so the next write the process makes is the cut's own. holdWrites opens its connection first, so taking the lock is one round trip, and the Bun.sleep(300) it replaces is gone. One assertion was added: before the lock is let go, the lease must not have been released, so a lock taken too late fails with that reason instead of passing without having held the cut. What the test asserts of the page and the Planner is unchanged.

Evidence. The test is non-deterministic, so the red evidence is a failure rate on the unmodified spec on a disposable server and database: 2 of 12 alone (in each, a commit landed just after a checkpoint, and the old process's backend waited on pg_advisory_xact_lock for the whole 5 s wait), 3 of 4 in a first load run that was stopped early and 1 of 8 in a second (8 busy loops on 4 cores), with timed out waiting for the old process to stop listening; setting the old 300 ms idle wait to zero made the same wait time out. After: 50 of 50 alone (--repeat-each=50) and 50 of 50 under the same load. On the final tree, 10 of 10 more (--repeat-each=10) and the whole file 13 of 13.

Commits

#	Commit	Item
1	2d0ad2b8 Give an opening that already waits on a read the document's own read when a change notice arrives	1
1b	f38dc40c Make an opening that waits on a hover read stop waiting when its document changes	1
2	02d7738d Fix the clock and time zone of the planner picker's "last seen" test, so it does not fail just after local midnight	3
3	f9e50f9d Stop the lease peek test from racing the clock of a database slower than its short lease	2
4	8cafbe45 Close a saved-request test's Chat before the database it saves to	2
5	b5cce96c Count a document switch's catalogue reads only after the read its own creation causes has finished	4
6	b1aafa3a Measure a restart's outage from the release, and make its length independent of how slow the runner is to start	5
6b	5b38e9c2 Time a restart's outage from the 1012 the page sees, not from the old process's exit	5
7	598fa152 Wait for a saved Planner request's turns by time, not by a count of event-loop turns	2
8	8b408c04 Take the write lock of the hand-over test when the old process's cut begins, not before it is told to stop	6

Files: apps/web/src/document-intent.ts and its test; apps/server/src/chat/deferred.test-fixtures.ts, apps/server/src/storage/lease-peek-contract.ts, apps/server/src/storage/postgres/deferred-restart.test.ts; e2e/planner-picker.e2e.ts, e2e/document-navigation.e2e.ts, e2e/restart.e2e.ts, e2e/handover.e2e.ts (157 insertions, 35 deletions). All eight are signed. Two commit messages (f9e50f9d, 8cafbe45) were reworded after a first proxy build was found to delay chunks one after another; their figures were re-measured with the corrected proxy. A third (598fa152) was reworded to name the earlier commit it refers to. The trees were checked identical before and after each rewrite.

Verification on the final head

Base 341a2b33. Head 8b408c04. The commands below ran on the tree of 521925d0, which has the same tree as 8b408c04 (verified with git log --format=%T: the commit rewrites changed only messages). PostgreSQL was the chopin-stage1-pg container on 5442 with a fresh database for each run, dropped afterwards (5432 and bun run db:up were not used). Browser runs had GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false in their own environment only, and used ports 9300 and up with their own databases.

• bun run fix: no change to any file.
• bun run types: passed (connector, editor, server and web, then tsgo -p e2e).
• bun run ci: passed (dprint, oxlint 74 warnings and 0 errors, tokens, design contract 1158 sources and 331 exact reviewed exceptions, design record, Impeccable no new findings).
• Full bun test with TEST_DATABASE_URL on a fresh database: 7957 pass, 17 skip, 2 fail. Both failures are environmental: the two tests commit in a throwaway repository with the developer's global commit.gpgsign=true and no signing key there (fatal: either user.signingkey or gpg.ssh.defaultKeyCommand needs to be configured): the connector's "a spike's agent cannot push ..." and the server's "a waiting connector registers again ...". Re-run with the browser runs' GIT_CONFIG_* override: both files pass, 58 of 58.
• bun test apps/server/src/storage/postgres (what bun run test:postgres runs, pointed at 5442 instead of its hard-wired 5432) on a fresh database: 178 of 178.
• Browser specs, on a client built from the tree (VITE_CHILD_MOTION_TOGGLE=on VITE_MESSAGE_ANALYSIS=on), --retries=0: document-navigation.e2e.ts and document-intent.e2e.ts together 44 of 44 (plain project, a configuration of its own on port 9300); planner-picker.e2e.ts 41 of 41; restart.e2e.ts 8 of 8; handover.e2e.ts 13 of 13; handover "never marked Couldn't send" alone --repeat-each=10 10 of 10; planner-picker "last seen" under TZ=Etc/GMT-9 2 of 2. planner-picker, restart and handover hard-wire ports 8794, 8796 and 8801 to 8803, so they ran as copies (under a git-ignored scratch directory, since removed) with only the import paths, the ports (9394, 9396, 9401 to 9403) and the database names changed, checked by diff.
• Not run: the full browser suite, the Docker image build (no workspace, dependency or Dockerfile change), and CI's own twelve-way sharding.

Review follow-up

Two findings from the last review are fixed in f38dc40c (item 1: an opening waiting on a hover read no longer waits for it once its document has changed, even if that read never answers) and 5b38e9c2 (item 5: the outage is counted from the 1012 the page sees, with the design's bound unchanged). On this head, bun run fix changed nothing, bun run types and bun run ci pass (oxlint 74 warnings, 0 errors), and the apps/web suite passes (1118 pass, 2 skip, 0 fail). restart.e2e.ts passes 8 of 8; the browser evidence is in items 1 and 5. Browser runs had GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false in their own environment only, PostgreSQL chopin-stage1-pg on 5442 with a fresh database each, and ports 9000 and up (the specs hard-wire lower ones, so they ran as copies under a git-ignored scratch directory, since removed, with only the imports, ports and databases changed).

Open points

• The restart's start time is not sped up. The new process spends about a second loading its module graph before it can answer; making that faster is a larger piece of work, and the test no longer depends on it.
• Slug probing, not fixed. #reserveSlug in apps/server/src/storage/postgres/adapter.ts probes slug candidates one at a time, so creating a document with the same title as N earlier ones in a repository costs about 2N round trips. It made repeated runs on one database slow; each series above used a fresh one.
• The hand-over settle is unbounded. A process whose storage will not take a write stays in its settle step and never stops listening. That is the design (it must not cut with writes it cannot commit), and it is left as it is; the hand-over test no longer provokes it by accident.
• One unexplained run in document-navigation. One of the 6 failures before the fix was the header staying on the new document after the click on the first; it did not recur in the 70 runs after the fix, its cause was not established, and the commit does not claim one.
• startup.test.ts under load. "recovers one missed terminal Chat notice across repeated server starts" takes 3.6 s idle and hit bun's 5 s limit once under heavy CPU load. Not in the brief, not touched; it passed in the full run above.
• The "+5 ms each way" ceiling. With the fix, the saved-requests "keep a message" test still fails at 10 ms database round trips by bun's 5 s test limit. That is far above a CI service container's latency; it is stated so it does not read as 5 ms being covered.
• Red evidence for items 2 and 6 is statistical or injected, not a deterministic failing test in the repository.

Assistant-model: Claude Sonnet 5.5
Assistant-workflow: goal (run faf72526-b6af-4985-b325-7ebb55272d7e)
Assistant-duration: unmeasured converged (the run's clock readings were about 07:36 to 09:30 PST on 2026-11-09; no time was recorded as a measurement)
Assistant-verification: bun run fix made no change, and bun run types and bun run ci passed on the tree of 521925d0, which is the tree of 8b408c0 (oxlint 74 warnings, 0 errors; design contract 1158 sources and 331 exact reviewed exceptions)
Assistant-verification: full bun test with TEST_DATABASE_URL on a fresh PostgreSQL database on 5442: 7957 pass, 17 skip, 2 fail, both failures from the developer's global commit.gpgsign=true with no signing key in a throwaway repository, and both files passing 58 of 58 with the GIT_CONFIG_* override
Assistant-verification: bun test apps/server/src/storage/postgres on a fresh database on 5442 passed 178 of 178
Assistant-verification: playwright through a configuration of my own on ports 9300 and up, with their own databases, --retries=0: document-navigation and document-intent 44 of 44, planner-picker 41 of 41, restart 8 of 8, handover 13 of 13, handover "never marked Couldn't send" alone 10 of 10, planner-picker "last seen" under TZ=Etc/GMT-9 2 of 2
Assistant-verification: bun test --rerun-each 50 apps/server/src/storage/memory/adapter.test.ts -t "lease peek" passed 100 of 100, and the saved-requests teardown order, re-measured behind a 2 ms proxy for five runs on a fresh database each, logged "Connection closed" 5 times before and 0 times after
Assistant-verification: the eight commits are signed (git log %G? shows G for each), and git log --format=%T shows the same trees before and after rewording three commit messages
Assistant-workflow: goal (run 9218171a-973c-468a-a0e6-2528103ba79f)
Assistant-verification: after the last review's two P2s were fixed (an opening stops waiting on a hover read its document's change invalidated; the restart outage is timed from the 1012 the page sees), the held-read unit test failed on the module before the fix (26 pass, 1 fail, "still waiting") and passed after (27 of 27); bun run types, bun run ci and apps/web bun test (1118 pass, 0 fail) passed on 5b38e9c
Assistant-verification: e2e/restart.e2e.ts passed 8 of 8 on a fresh database, outage from the 1012 of 2473 ms (main case) and 2494 and 2584 ms (the two retry cases) against 4000; a scratch probe that delayed the old process's exit by 2 s passed the old measurement (2407 ms from exit) and failed the new one (4511 ms from the 1012), showing the new measurement counts the time the old one left out; that probe was not kept in the suite
Assistant-verification: document-intent and document-navigation passed 44 of 44 with one worker on a fresh database, the client built as scripts/e2e.ts builds it
Co-authored-by: Alex Lavaee lavaman131@github.com