Skip to content

Calm sidebar part 2: thread roles and the calm grouping - #952

Merged
scuttletoby merged 3 commits into
mainfrom
fork/calm-sidebar-pr2
Nov 22, 2026
Merged

scuttletoby merged 3 commits into
mainfrom
fork/calm-sidebar-pr2

Conversation

@scuttletoby

@scuttletoby scuttletoby commented Nov 22, 2026 •

Copy link
Copy Markdown
Owner

Calm sidebar PR 2 of 5.

What and why

The shared logic of the calm sidebar, in one new file the web and phone lists can both read: packages/client-runtime/src/state/threadRoles.ts. Nothing reads it yet, so nothing a user can see changes. PR 3 adds the sidebar.

  • resolveThreadRoles(roles, threads): the threadRoles pointers (Calm sidebar part 1: threadRoles and calmSidebarEnabled settings #928) whose thread can hold the role now. A pointer to a thread that is missing, deleted, archived, a sub-agent, a side chat, a task delegated from a linked machine or (orchestrator) in another project counts as no role. The pointer itself is left alone, so unarchiving brings the role back. Read leniently: a bad hand-edited entry (non-id value, blank key, wrong shape) is skipped alone.
  • threadRole(thread, roles): assistant, orchestrator, child or plain. The row is checked again, so roles read a moment before the list never lift an archived, moved or child thread. A thread that is both assistant and orchestrator is the assistant.
  • calmPartition(threads, rolesByEnvironment, enabled):
    • off: the same array as given (upstream's list): calm is off, or there are no threads at all.
    • no-roles: calm is on but no listed thread holds a role. The full list plus a hint; it never folds everything away.
    • calm: role rows on top (assistants, then orchestrators), every other thread folded in list order, plus how many of those wait on the person (approval, question or user-only card, child request, guest message: the sidebar's own pills). A usage-limit stop is not counted on purpose: it clears without the person. This is the owner's "fold them, with a waiting count" (Owner question: calm sidebar - fold other threads with a waiting count, or hide them? #139).
      It only groups: every thread comes back exactly once, so search, drafts and links are untouched.
  • createThreadRolesAtom(...): the one atom. It holds the resolved roles of every enabled server, follows settings pushes and thread changes, and keeps the same map while the result is equal. It reads threads only on servers that name a role, so streaming costs nothing while none do. Its inputs are atoms upstream already exports (catalogValueAtom, settingsValueAtom, environmentThreadIndexAtom), so PR 3 wires it with one call.

Seam list (.github/fork-seams.json):

  • forkFiles gains packages/client-runtime/src/state/threadRoles* and packages/contracts/src/threadRoles*. Without these entries, a later PR that edits either file is refused as an upstream file. PR 1's contracts file was missing: a probe commit that adds one line to it on top of main fails the seam check today.
  • PR 3 will need a one-line export in packages/client-runtime/package.json. This PR announces it: "./state/thread-roles": "./src/state/threadRoles.ts",. It has to be one line because the usual four-line form ends in },, a line upstream already has, so it cannot be announced. If PR 3 is more than 14 days away, the announcement expires harmlessly.

Not here: #946 point 2 (no test fails if ThreadRoleTargets.layer leaves forkLayers.ts). That is server wiring and does not fit a client-runtime PR, so it stays with the later Settings PR as #946 says. The owner's #140 answer (an orchestrator may pass its role on by itself) is a server write path and does not touch this reader.

Tests

threadRoles.test.ts: 35 tests, one or more for each row of the design's state table that a reader sees, plus the atom. Without the change the module does not exist and the test file fails to load; with one rule broken on purpose, its tests catch it (both shown below).

State question

"What happens when this runs again, stops half-way, or meets existing, old or empty state?"

Case Answer (and the test)
No roles at all resolveThreadRoles gives none. With calm on, no-roles: the full list and the hint, never an empty sidebar. New install with no threads: off, the empty list as upstream, with no hint
A role on a missing thread No role. The pointer stays in settings (PR 4's Settings panel shows it as missing)
A role on an archived or deleted thread No role. After unarchive the role is back, since the pointer was kept. Covered both in the pure function and in the atom when a thread is archived and then unarchived
A role on a thread moved to another project, a sub-agent, side chat or delegated task No role. Checked again on the row itself, too
Two roles for one project One map key holds one orchestrator. An assistant and an orchestrator of the same project are both on top. One thread named as both is listed once, as the assistant. A duplicate key in a hand edit: JSON keeps the last one
Settings change while the sidebar is open The atom follows each push (set, add assistant, clear: four values seen in order). The same roles pushed again (a resave or a server restart) keep the same map, so nothing redraws
Older server without the setting Its settings decode to no roles, or have no threadRoles key at all; that server is left out of the map. An old settings file reads as no roles
Runs again Pure functions; the same input gives the same output and the same map instance
Stops half-way Nothing is stored. Roles and grouping are worked out fresh from settings and threads each time
Handoff to a new thread Move the pointer: the new thread goes on top and the old one is folded
Fork of the orchestrator A new thread id, so it is plain
Settled or snoozed orchestrator Still on top; only archive or delete removes a role row
Delegated task whose parent is archived (linked machine) Folded, counted as waiting if it waits, and never a role
Linked server turned off or offline Turned off: its roles leave the map and come back with it (tested). Offline but still on: its roles follow its last thread snapshot, the same one the list shows, so role rows and listed rows always agree. Each server's roles apply only to its own threads

Upstream fit

New fork file only. It uses upstream's isListedThreadLineage, upstream's delegatedFrom != null rule (the same as #928's server check) and upstream's existing atoms. It does not change upstream's navigation list: calm groups that list and never hides from it. No upstream file changes, apart from the seam list.

General vs project

All general. No project, machine, account or thread id is in the code; the ids live only in each user's own settings. Works for web and phone alike (client-runtime).

Review

One Opus lens (read-only, state question asked for each part): no blocking findings; types fit PR 3's real atoms and rows without casts. Its three minor points are settled in the second commit and this text: an empty list no longer gets the hint, the usage-limit choice is written down, and the offline row above is worded to what the tests prove.

Checks

  • client-runtime typecheck (effect-tsgo tsrs --noEmit): pass.
  • web typecheck (the same checker on apps/web; the app has no script of its own): pass, 0 errors.
  • vp test run src/state/threadRoles.test.ts: 35 passed (again on the second commit).
  • Without the module: Error: Cannot find module './threadRoles.ts', test file failed.
  • With the archive rule removed from canHoldRole on purpose: 4 failed, 31 passed (the archived pointer, unarchive brings it back, the row checked again, and the atom's archive then unarchive).
  • vp lint --report-unused-disable-directives on the changed files: 0 errors. Pre-commit vp fmt, vp lint and knip:check: pass.
  • vp fmt --check: all files formatted.
  • node .github/scripts/fork-seam-check.cjs --config-ref origin/main origin/main HEAD: exit 0.

🤖 Generated with Claude Code

scuttletoby and others added 2 commits November 22, 2026 12:02
Adds packages/client-runtime/src/state/threadRoles.ts, read by nothing
yet (the sidebar comes in part 3):

- resolveThreadRoles: the threadRoles pointers whose thread can hold
  the role now. A pointer to a missing, deleted or archived thread, a
  sub-agent, a side chat, a delegated task or (orchestrator) a thread
  of another project counts as no role; the pointer is left alone. Read
  leniently: a bad entry is skipped alone.
- threadRole: a row's role, checking the row again.
- calmPartition: off (the list as given), no-roles (the list plus a
  hint) or calm (assistants, then orchestrators on top; the rest folded,
  with how many wait on the person).
- createThreadRolesAtom: the resolved roles of every enabled server;
  reads threads only where a role is named; stable while equal.

Seam list: forkFiles gains threadRoles* in client-runtime and in
contracts (part 1's file was missing, so any later edit of it was
refused), and the one-line client-runtime export part 3 adds is
announced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…re not counted

Review follow-up. A new install with no threads now gets the list as given
(kind "off"), as the design's empty-state row says, so the sidebar never
shows the pick-a-role hint on an empty list. The waiting count leaves out a
usage-limit stop on purpose (it clears without the person); the doc comment
now says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: code · reviewer: lens agent (Opus, read-only) · read at: 2f06950
verdict: safe to merge
covered: the whole diff (threadRoles.ts, threadRoles.test.ts, .github/fork-seams.json); the atoms it builds on (threadShell.ts environmentThreadIndexAtom and navigationThreadShellsAtom, server.ts settingsValueAtom, connections.ts enabledEnvironmentIds); the sidebar's status pills (Sidebar.logic.ts resolveSidebarThreadStatus, resolveThreadStatusPill); PR 1's contracts file; the calm sidebar design (PR 2 section, role table, state table) and the owner answers on #138 (a setting), #139 (fold, with a waiting count) and #140 (an orchestrator may hand on its role).
checks: ran threadRoles.test.ts: 35 passed. Broke one rule at a time on purpose; every one below fails at least one test: the archive check (4 fail), the delete check (2), the project check for an orchestrator (1), the child check by lineage (3), the delegatedFrom check (3), the re-check of the row in threadRole (1), assistant before orchestrator (6), assistants before orchestrators in the role rows (3), each waiting input (approval 2, subagent request 2, guest 1), calm off and the empty list (1 each), the atom's "same map" (1) and its "read no threads without a pointer" (1). Ran the kit's plan on this PR's paths: weight normal, lens code only, also for .github/fork-seams.json, so this one lens is enough. Ran the seam check against main's list: exit 0. Checked the announced line: one line, dated today, so it expires after 2026-12-06 (14 days).
state: runs again: pure functions, same input gives the same output and the same map instance (tested). Stops half-way: nothing is stored; roles and grouping are worked out fresh each read. Old state: an older server or settings file without threadRoles leaves that server out of the map; a pointer to a missing, deleted, archived, child, delegated or moved thread reads as no role and the pointer is kept, so unarchive brings it back (tested in the pure function and the atom). Empty state: no threads gives upstream's list without the hint; threads but no roles gives the full list and the hint, never all folded.
blocker: none
major: none
minor: threadRoles.ts:128 says a usage-limit stop "clears without the person", but that is only true with autoResumeLimitedThreads on, and it defaults to off (packages/contracts/src/settings.ts:1486). With the default, a limited thread stays stopped until the person resumes it, and the sidebar shows it as "limited". The design and #139 say "count the threads that need you" and do not decide usage limits either way. Not counting them is a fair choice (the person cannot act before the reset), but the reason should be reworded; or PR 3, which first shows the count, counts limited threads while auto-resume is off.
minor: threadRoles.ts:186: when every role thread is missing from the list it is given (for example hidden by hideTaggedThreads), the result is no-roles, so PR 3 would show "Pick an orchestrator" although one is set. PR 3 can show the hint only when the roles map is empty, or word it so it is true in both cases.
minor: threadRoles.ts:50: the trim check in isIdText never decides anything: a padded id matches no thread or project id anyway, and PR 1's decode already drops it (removing it leaves all 35 tests green). Harmless as a guard; keep or drop.
notes (not findings): the role rules match the design's role table: deleted, archived, sub-agent or side chat (upstream's isListedThreadLineage) and delegatedFrom (upstream's rule) give no role; an orchestrator must be in its map key's project; a thread that is both is the assistant. The atom imports only contracts and connections.ts, and takes upstream's existing atoms as inputs; no upstream file is edited apart from the seam list. #140 (an orchestrator may hand on its role) is a server write path and does not change this reader. The new forkFiles entries are right: both globs cover the PR 1 and PR 2 files and their tests.

@scuttletoby
scuttletoby merged commit d06b554 into main Nov 22, 2026
40 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant