Treat missing thread snapshots as terminal

[Quicksaver]

Summary

Treat authoritative missing-thread snapshot responses as terminal client state instead of falling through to a repeatedly failing WebSocket subscription, including after session replacement or application-foreground resubscription. Transient HTTP failures still retain the existing socket-snapshot fallback.

Delay detail synchronization for known local drafts across every detail consumer until the server shell observes thread creation, preserving the legitimate pre-creation flow while preventing a missing-resource response from deleting the draft.

What Changed

• Preserve decoded HTTP thread_not_found errors through the thread snapshot loader while mapping transient failures to socket fallback.
• Clear persisted thread detail, mark the client state deleted, emit structured diagnostics, and terminate before opening or retrying the WebSocket subscription for an authoritative miss or later resubscription signal.
• Share the local-draft detail gate between merged thread reads and the server-thread route so every known draft waits for its thread shell.
• Add direct HTTP-loader, thread synchronization, and web hook lifecycle regression coverage.
• Document the branch-owned synchronization contract in BRANCH_DETAILS.md.

Why

While investigating renderer memory growth from roughly 300 MB after launch to nearly 2 GB after extended use and idle time, stale thread details were observed being prewarmed after their server resources no longer existed. Each HTTP lookup returned authoritative thread_not_found, but the client treated that as a transient miss, opened a WebSocket subscription that also failed, and retried the cycle every 250 ms. Multiple stale subscriptions made this a concrete source of sustained allocation, retained state, and background CPU pressure, though it should not be assumed to explain every byte of renderer memory growth by itself.

The terminal handling stops that loop, evicts the stale persisted detail, and prevents later session or foreground events from reopening the socket. Because a brand-new local draft also legitimately has no server thread before its first send, every draft detail consumer now waits for the shell's creation signal so the fix does not turn that expected pre-creation 404 into a deleted draft.

Validation

• 17 focused client-runtime tests passed across thread synchronization and HTTP snapshot loading.
• 4 focused web entity-hook lifecycle tests passed.
• Client-runtime typecheck passed.
• Web typecheck passed.
• Targeted formatting and lint checks passed.
• Integrated Playwright verification confirmed that a local draft issued no pre-creation detail request, promoted on first send, then requested only its created server thread and completed the response.

Proof

No additional proof artifacts are required; the focused automated coverage and integrated browser flow exercise the affected lifecycle directly.

---

Note

Medium Risk
Changes core thread sync and deletion semantics across HTTP and WebSocket paths; incorrect 404 handling or draft gating could wrongly delete threads or block legitimate sync, though behavior is covered by new tests.

Overview
Authoritative HTTP thread_not_found responses now end thread-detail sync instead of being treated like transient misses that fall through to a WebSocket subscription and retry loop.

ThreadSnapshotLoader propagates EnvironmentResourceNotFoundError on 404 while other HTTP failures still map to socket fallback. The thread state machine marks the thread deleted, clears persisted detail, and interrupts before opening or resubscribing the WebSocket stream (including on application-foreground wakeups).

Local drafts no longer subscribe to server detail until a server shell exists: shouldSubscribeToThreadDetail, useThreadDetailWhenReady, and useThreadStatusWhenReady gate subscriptions so pre-creation 404s cannot delete a draft. The chat thread route and useThread use this gate.

Adds regression tests for the HTTP loader, sync lifecycle, and web hook gating, plus BRANCH_DETAILS.md documenting the contract.

^{Reviewed by Cursor Bugbot for commit 45dac5e. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Treat missing thread snapshots as terminal by marking 404 responses as deleted

• ThreadSnapshotLoader.load in threadSnapshotHttp.ts now propagates EnvironmentResourceNotFoundError (404 thread_not_found) as a failure instead of mapping it to Option.none.
• threads.ts catches this error during the HTTP snapshot phase, marks the thread state as deleted, and interrupts the subscription — preventing socket subscription and any retry on wakeup.
• New useThreadDetailWhenReady and useThreadStatusWhenReady hooks in entities.ts gate detail/status subscriptions for draft threads until a server shell exists.
• Behavioral Change: deleted threads no longer initiate or resume socket subscriptions across session replacement or app-active wakeups; previously a 404 would fall through to socket subscription via Option.none.

^{Macroscope summarized 2d25d20.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 271ef083-c92d-4e13-88a0-a294d5f02cde

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[macroscopeapp]

Effect service review: one convention violation found. The new HTTP thread_not_found handling uses Effect.catchTag, but the conventions require Effect.catchTags for statically known tagged failures — including when handling a single tag.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR changes subscription termination behavior for missing threads, which is a significant runtime behavior modification. Additionally, an unresolved review comment identifies a potential hydration race condition that could cause draft threads to be incorrectly marked as deleted.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2d25d20. Configure here.}