feat(web): drag pinned threads into your own order

[t3dotgg]

Pinned threads were stuck in creation order — pinning says "keep this on top" but you couldn't say which one goes first. Now you can drag pinned cards in the v2 sidebar into whatever order you want, and that order holds everywhere: every client, every platform, even with multiple servers connected at once.

How it syncs

Each pinned thread stores an optional fractional-index pinOrderKey (lexorank-style string) on its own server, next to pinnedAt. Clients sort the merged pinned list by plain string comparison of keys, so:

• A drag computes one key that sorts between the drop position's neighbors and writes it to one thread on one server — neighbors on other servers are never touched.
• Order converges across clients through the existing event/projection stream, the same way pinnedAt already does. Concurrent drags of the same thread are last-write-wins; equal keys fall back to a deterministic id tiebreak.
• Version skew degrades cleanly via a new threadPinReorder capability: threads on older servers aren't draggable and keep today's creation order below the arranged run.

Changes

• contracts: thread.pin.reorder command, thread.pin-reordered event, optional orderKey on thread.pin, pinOrderKey on thread shells, capability flag
• server: decider case (rejects unpinned threads, idempotent no-op re-emission), projection column + migration 038, key cleared on unpin/settle so re-pinning starts fresh
• web: dnd-kit sortable on the pinned block (same pattern as v1 project reordering, 6px activation so clicks still work), optimistic order until the confirming event lands, fresh pins keyed to the top of the arranged run
• mobile: read-side sort by the same keys (no drag UI yet), so phones show the order you arranged on web

Threads pinned before this ships stay keyless and get a key materialized on their first drag — no backfill. A pinned thread's key survives snooze, so it wakes back into its exact slot.

Tests: fractional key math (incl. 100-deep insertion churn), reorder planning, pinned sort, decider cases. Full typecheck/lint/test suites green across contracts, client-runtime, server, web, and mobile.

---

Built by Claude Fable 5 via Claude Code.
🤖 Generated with Claude Code

---

Note

Medium Risk
Touches orchestration, persistence, and multi-client ordering with optimistic UI; failures are mostly localized, but partial multi-write materialization and version skew across environments need careful rollout.

Overview
Adds user-arranged pinned thread order synced through the server using fractional pinOrderKey strings, gated by a new threadPinReorder capability.

Backend & contracts: New thread.pin.reorder / thread.pin-reordered, optional orderKey on pin, pin_order_key column (migration 038), and decider/projector rules (fresh pins accept a key, re-pins preserve placement, unpin clears the key).

Shared client logic: thread-sort helpers (pinOrderKeyBetween, planPinnedReorder, planPinnedMove, sortPinnedThreadsByOrderKey) so web and mobile render the same merged pinned order; keyless legacy pins stay below keyed ones.

Web: dnd-kit drag on the pinned block with optimistic order until events land; new pins get a key at the top of the arranged run.

Mobile: Move up / Move down in the thread menu (canonical order, not filtered list), with in-flight guards like snooze.

User docs added for organizing pinned threads.

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

Note

Add drag-to-reorder pinned threads in the sidebar

• Introduces a pinOrderKey fractional index on pinned threads, persisted via a new thread.pin.reorder command, thread.pin-reordered event, and DB migration adding pin_order_key to projection_threads.
• On web, wraps pinned sidebar rows in @dnd-kit/sortable with optimistic reordering, released when canonical server state converges or membership changes.
• On mobile, adds Move up/Move down context menu items for pinned threads, computing move bounds from the full canonical pinned order across all shells.
• New planPinnedReorder and pinOrderKeyBetween utilities in threadSort.ts minimize key writes (single write when neighbors are keyed, full spread otherwise).
• The threadPinReorder capability flag gates all reorder UI; environments that don't advertise it show pins in legacy creation-time order without drag handles.

^{Macroscope summarized cec4a57.}

Summary by CodeRabbit

• New Features
  • Reorder pinned threads by drag-and-drop on web and desktop.
  • Move pinned threads up or down on mobile.
  • Pinned ordering syncs across connected devices and remains consistent after snoozing.
  • Older servers continue supporting pinning with the default ordering.
• Documentation
  • Added guidance for organizing and reordering pinned threads.

[coderabbitai]

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.85% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the primary change: drag-to-reorder support for pinned threads in the web sidebar.
Description check	✅ Passed	The description clearly explains the problem, implementation, platform behavior, compatibility handling, documentation, and test coverage.

---

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.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.3 KiB	11.3 KiB	−29 B (−0.2%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+8 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	−37 B (−0.6%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.3 KiB	11.3 KiB	+25 B (+0.2%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+14 B (+0.3%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.8 KiB	5.9 KiB	+11 B (+0.2%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: be1a836 · PR result: cec4a57 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Needs human review

New feature adding drag-to-reorder for pinned threads, including database schema changes, new server capabilities, new UI interactions, and substantial new sorting logic across web and mobile platforms. Warrants human review due to scope.

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

[f-trycua]

Hey @t3dotgg — quick heads-up that I opened #5528 yesterday for the same request, after comparing against Codex’s pinned-task sidebar.

That PR is rebased on current main and covers synced ordering across web/desktop/mobile, including keyboard drag plus Move up/down actions on web and mobile, mixed-version capability gating, optimistic rollback/compaction, hidden or snoozed pin guards, docs/screenshots, and focused tests. The storage model differs (exact rational positions vs. this PR’s fractional string keys), so I wanted to flag the overlap before either path lands.

Happy for you to take whichever implementation or pieces fit best; the mobile actions and edge-case fixes/tests in #5528 may be useful even if #5581 is the preferred base.

[t3dotgg]

[CLAUDE-FABLE-5] RESPONDING ON BEHALF OF THEO

Rebased onto latest main and pushed a follow-up commit addressing the comparison review against #5528:

• Optimistic-order release bug (blocking finding): the drag override now releases on any pinned-membership change (new pin, unpin, snooze/wake), not only on exact sequence match. A pin landing mid-drag can no longer freeze the override or launder a stale order into subsequent drags.
• Consistent pin placement: every pin path (sidebar, chat header, mobile) now sends a top-of-run orderKey; the sidebar anchors against the displayed order.
• Cherry-picked from feat(sidebar): sync pinned thread order #5528: mobile Move up / Move down menu actions on pinned rows, and the user docs page. Mobile move computes against the canonical arranged order, so search or project scoping never disables a valid move (avoids the visibility-guard issue found in 5528's approach).
• Key math now lives in client-runtime/state/thread-sort, shared by web and mobile.

[macroscopeapp]

Reviewed the Effect-side changes (contracts schemas, decider/projector cases, migration 038, client-runtime command atoms, and the web/mobile call sites) against the service conventions. Imports, Effect.fn/Effect.gen usage, and the new migration module follow the existing patterns, and no Layer.succeed/ManagedRuntime.make/runPromise misuse was introduced. One error-modeling violation found.

^{Posted via Macroscope — Effect Service Conventions}

[coderabbitai]

Caution

CodeRabbit couldn't update its existing comment. The review summary may be out of date.

Error details

putComment timed out

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

apps/web/src/hooks/useThreadActions.ts (1)

102-112: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Comment states Null but the function returns undefined.

The doc comment at Line 103 says the helper returns "Null (keyless, ...)". The function returns undefined so the caller can omit the field via the spread at Line 563. Align the comment with the return type.

📝 Proposed comment fix

 /** Key that sorts before every arranged pinned thread, so a fresh pin lands
-    at the top of the run. Null (keyless, sorts with the legacy block) when
+    at the top of the run. Undefined (keyless, sorts with the legacy block) when
     key math can't produce one — pinning must never fail on placement. */

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/web/src/hooks/useThreadActions.ts` around lines 102 - 112, Update the
documentation for topOfPinnedRunOrderKey to state that it returns undefined when
key generation fails, matching its return type and caller behavior; leave the
implementation unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/server/src/orchestration/Layers/ProjectionPipeline.ts`:
- Line 615: Add focused projection-layer tests for the thread pin event handlers
covering `thread.pinned`, `thread.unpinned`, and `thread.pin-reordered`. Assert
absent `pinOrderKey` initializes correctly, legacy `thread.pinned` retains the
existing value, unpinning clears it, and reordering persists the updated value.

In `@apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts`:
- Line 321: Extend the tests around the existing snapshot and detail assertions
in ProjectionSnapshotQuery to cover a persisted non-null pinOrderKey. Add a
fixture with a specific order key, then assert every changed snapshot and detail
surface propagates that exact value while retaining the existing null-path
coverage.

In `@apps/web/src/components/SidebarV2.tsx`:
- Around line 411-429: Add keyboard reordering to SortablePinnedThreadRow by
registering KeyboardSensor with sortableKeyboardCoordinates in pinnedDndSensors,
exposing dnd-kit attributes and setActivatorNodeRef, and applying them to a
dedicated drag handle so the card’s existing handleKeyDown remains unaffected.
Update docs/user/thread-sidebar.md lines 7-9 to document both dragging and
keyboard-based reordering for web and desktop users.

---

Nitpick comments:
In `@apps/web/src/hooks/useThreadActions.ts`:
- Around line 102-112: Update the documentation for topOfPinnedRunOrderKey to
state that it returns undefined when key generation fails, matching its return
type and caller behavior; leave the implementation unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 315d0920-dd14-4208-8135-9af03ec689cf

📥 Commits

Reviewing files that changed from the base of the PR and between be1a836 and 64c0f77.

📒 Files selected for processing (33)

• apps/mobile/src/features/home/HomeRouteScreen.tsx
• apps/mobile/src/features/home/HomeScreen.tsx
• apps/mobile/src/features/home/useThreadListActions.ts
• apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx
• apps/mobile/src/features/threads/thread-list-v2-items.tsx
• apps/mobile/src/features/threads/threadListV2.ts
• apps/server/src/environment/ServerEnvironment.ts
• apps/server/src/orchestration/Layers/ProjectionPipeline.ts
• apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
• apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
• apps/server/src/orchestration/Schemas.ts
• apps/server/src/orchestration/decider.pinned.test.ts
• apps/server/src/orchestration/decider.ts
• apps/server/src/orchestration/projector.ts
• apps/server/src/persistence/Layers/ProjectionThreads.ts
• apps/server/src/persistence/Migrations.ts
• apps/server/src/persistence/Migrations/038_ProjectionThreadsPinOrderKey.ts
• apps/server/src/persistence/Services/ProjectionThreads.ts
• apps/web/src/components/Sidebar.logic.test.ts
• apps/web/src/components/Sidebar.logic.ts
• apps/web/src/components/SidebarV2.tsx
• apps/web/src/hooks/useThreadActions.ts
• apps/web/src/state/entities.ts
• docs/README.md
• docs/user/thread-sidebar.md
• packages/client-runtime/src/operations/commands.ts
• packages/client-runtime/src/state/threadCommands.ts
• packages/client-runtime/src/state/threadDetail.ts
• packages/client-runtime/src/state/threadReducer.ts
• packages/client-runtime/src/state/threadSort.test.ts
• packages/client-runtime/src/state/threadSort.ts
• packages/contracts/src/environment.ts
• packages/contracts/src/orchestration.ts