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. Transient HTTP failures still retain the existing socket-snapshot fallback.

Delay detail synchronization for known local drafts 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.
• Suppress server-detail subscriptions for known local drafts until their thread shell is created.
• 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 and evicts the stale persisted detail. Because a brand-new local draft also legitimately has no server thread before its first send, draft detail synchronization 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.
• 3 focused web entity-hook lifecycle tests passed.
• Client-runtime typecheck passed.
• Targeted formatting and lint checks passed.
• Integrated browser verification confirmed that a local draft issued no pre-creation detail request, promoted on first send, then loaded its created thread successfully 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 for HTTP 404s and draft routes; wrong classification could delete live threads or leave stale subscriptions, though behavior is covered by new tests.

Overview
Stops stale thread-detail sync from retrying forever when the server says the thread is gone, and avoids treating a pre-creation draft as deleted.

HTTP thread_not_found is authoritative. ThreadSnapshotLoader no longer maps a decoded 404 into Option.none for socket fallback; it keeps EnvironmentResourceNotFoundError in the error channel. In makeEnvironmentThreadState, that path clears persisted detail, sets status deleted, logs diagnostics, and interrupts before opening or retrying the WebSocket subscription. Other HTTP snapshot failures still become Option.none and use the existing socket path.

Local drafts wait for a server shell. useThread gates detail subscription through shouldSubscribeToThreadDetail: known composer drafts do not subscribe to server detail until threadShell exists, so the expected pre-creation 404 cannot mark the draft deleted.

Adds focused tests for the HTTP loader, thread sync harness, and web hook lifecycle, plus BRANCH_DETAILS.md documenting the contract.

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

Note

Treat missing thread HTTP snapshots as terminal by marking threads deleted

• When ThreadSnapshotLoader.load receives an authoritative HTTP 404 (thread_not_found), the effect now fails with EnvironmentResourceNotFoundError instead of returning Option.none and falling back to a WebSocket subscription.
• EnvironmentThreadState.make catches this error, marks the thread as deleted, and interrupts the subscription workflow, skipping the WebSocket entirely.
• useThread now gates detail subscription via a new shouldSubscribeToThreadDetail function, delaying subscription for local draft threads until a server shell is observed.
• Behavioral Change: threads that previously fell back to socket snapshots on 404 will now be marked deleted immediately.

^{Macroscope summarized 8b86c84.}

[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

Run ID: f7a7d99c-05b7-4682-95d9-e30b7317085c

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 how missing thread snapshots are handled from transient (retry) to terminal (mark deleted), affecting thread subscription lifecycle and state management. The behavioral change to error handling in critical synchronization code warrants human review.

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