fix(orchestrator): Keep Home and settle honest when work ends

[mwolson]

Summary

Keeps the home list and thread cards honest when work finishes, archives, or
wakes back up. Users should not see archived threads reappear on Home, settle
a thread that is still Waiting on background work, or lose an explicit settle
when a delayed provider event races the pin.

Also stops the client from spinning forever on a thread that is already gone
(HTTP 404), so deleted or never-created threads do not keep the UI in a loading
retry loop.

Why this matters

Without these lifecycle fixes, day-to-day product failures look like:

• Home list lies: an archived thread sits on the active list after reconnect
  or a dropped archive delta, so the inbox feels "sticky" and hard to clean up.
• Settle is unsafe or ineffective: settle can park a thread that still has a
  queued turn or background Waiting work, or can leave a pin in place so the
  card never looks truly put away.
• Delayed activity undoes the user: a late provider event can clear a fresh
  settle or rewind thread ordering after a rename, so the list jumps and settle
  state flickers.
• Dead threads never finish loading: a definitive missing snapshot keeps
  retrying on the socket path, leaving empty detail views that never settle.

Problem and Fix

What the user sees	Why it happened	Fix
Opening a deleted or never-created thread spins or retries forever.	HTTP 404 snapshots were treated as soft failures and fell through to socket retry.	Treat 404 as definitive missing: mark the thread deleted and stop the subscription attempt; only fall back to the socket when HTTP is merely unavailable.
Archived threads reappear on Home after refresh or reconnect.	Full shell snapshots could mis-partition active vs archive when the same id showed up in both lists or a delta was dropped.	Normalize membership from archivedAt, and on dual-list conflicts prefer the fresher updatedAt copy so a stale archive cannot beat a newer unarchive.
Settle parks a thread that is still working, or settle does not stick.	Settle allowed queued runs / background Waiting through; activity unsettle races could restore title/archive/model or skip clearing the pin; settle-only merge dropped pin clear.	Block settle on queued runs, pending requests, and the background roster; always emit activity-unsettle candidates with ordering; merge only settlement fields (and clear pinnedAt on settle); do not rewind updatedAt behind a newer metadata bump.
Waiting and settled state disagree between sidebar and actions.	Client settle eligibility ignored the background roster and Waiting invariants the server already had to enforce.	Align canSettle / effectiveSettled with pending background work and the same lifecycle signals the server uses.

Defensive Fixes

Risk	Fix
Archive/delete must not leave MCP credentials usable on a shared provider process.	Keep revokeMcpCredential: true on terminal provider-session detaches.
Transient projection read failures during activity-unsettle prep either vanished or crashed the stream.	Only treat a definitive missing thread as absent; other prep failures surface as ProviderEventPublishError so callers can retry.

Validation

• Focused suites for settle, projection, archive membership, and missing-snapshot paths.
• vp check and vp run typecheck clean on the published head.
• Review findings on pin clear, activity updatedAt rewind, runs filter, and typed unsettle prep errors fixed on the branch.

Out of scope

• fix(orchestrator): Keep agent output attached after a mid-turn steer #4547 orphaned-output-after-early-settle mid-turn steer contract
• Known-start projection-fetch skips
• Mobile / Home empty state / iOS remainder

---

Note

Medium Risk
Touches orchestration settle/unsettle, projection persistence, and provider ingest ordering—user-visible inbox and thread state—with broad test coverage but non-trivial concurrency edge cases.

Overview
Keeps the home list and settle/unsettle behavior aligned with real thread work, and stops dead threads from retrying forever.

Settlement and provider activity: New shared reduceThreadSettlementEvent merges only settlement fields (and clears pinnedAt on explicit settle) on server projection, client projection, and durable SQL writes—so stale full-thread unsettle payloads cannot rewind title, archive, or other metadata. ProviderEventIngestorV2 prepends synthetic thread.unsettled before qualifying provider activity (pending approvals/user input, live session states), orders clears with provider payload time so delayed events cannot beat a newer pin, and stamps ordinary provider events at ingestion time.

Settle guards: thread.settle rejects archived threads, queued runs (isSettleBlockingRun), pending runtime requests, and pending provider background tasks (via derivePendingBackgroundWork), with specific error messages.

Client shell and threads: canSettle / effectiveSettled block on pendingBackgroundTasks; shell snapshots use normalizeShellThreadMembership and trust archivedAt over stream location so archived threads do not stick on Home. HTTP thread snapshot loads return present / missing / unavailable; a definitive 404 marks the thread deleted and skips socket subscribe/retry.

Tests cover settle invariants, ingest races, projection merge, shell membership, legacy null settlement columns, and thread sync paths.

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

Note

Fix settlement state to reject stale overrides and block on active work in the orchestrator

• thread.settled and thread.unsettled events now merge only settlement fields (settledOverride, settledAt, pinnedAt, updatedAt) with activity-ordering guards, preventing stale payloads from overwriting unrelated thread metadata on both client (orchestrationV2Projection.ts) and server (ProjectionStore.ts).
• thread.settle is now rejected when a run is queued, a runtime request is pending, the thread is archived, or the active provider thread has pending background tasks.
• ProviderEventIngestor prepends a synthetic thread.unsettled event before qualifying provider activity batches, using the activity timestamp for ordering so delayed events cannot clear a newer pin.
• An HTTP 404 from the snapshot loader now definitively marks the thread as deleted and skips WebSocket subscription and retries; transient failures fall back to socket-only seeding.
• Shell snapshots are normalized via normalizeShellThreadMembership to place threads in the correct active/archived list, resolving duplicates by preferring the fresher copy.

^{Macroscope summarized 5908b04.}

[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: e833b6dd-b8a9-469f-8d5b-9770617a5322

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

---

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]

One convention issue found in the new provider-ingest settlement code: a statically known tagged failure is recovered with Effect.catchTag instead of Effect.catchTags.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant runtime behavior changes to thread settlement lifecycle across server orchestration, projection stores, provider event ingestor, and client runtime. The changes control when threads settle/unsettle based on provider activity and background tasks, affecting user-visible thread state. The cross-cutting scope and behavioral nature warrant human review.

^{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 5908b04. Configure here.}

[cursor]

Keep-active pin clock drifts on metadata

Medium Severity

settledOverrideTimestampMs treats updatedAt as the keep-active pin time, but later renames and other metadata writes advance that same field. Provider activity that lands after the pin can then lose the ordering check and leave settledOverride: "active" in place, so auto-settle stays suppressed even though the server intended to clear the pin on real activity.

Additional Locations (1)

• packages/shared/src/orchestrationV2Settled.ts#L106-L119

 

^{Reviewed by Cursor Bugbot for commit 5908b04. Configure here.}