Skip to content

Calm sidebar part 1: threadRoles and calmSidebarEnabled settings - #928

Open
scuttletoby wants to merge 2 commits into
mainfrom
fork/calm-sidebar-1
Open

scuttletoby wants to merge 2 commits into
mainfrom
fork/calm-sidebar-1

Conversation

@scuttletoby

Copy link
Copy Markdown
Owner

What and why

The calm sidebar shows the threads that matter (one assistant, one orchestrator per project) at the top. It folds every other top-level thread into one closed group. This PR adds only the settings and the server's save check. Nothing reads them yet, and both are off by default, so a machine behaves exactly as upstream's.

  • server.threadRoles (new, person-only) has two parts:

    • assistant: a thread id, or null.
    • orchestrators: one thread id per project id.

    A role is a pointer stored in the settings, not a tag on the thread. That keeps each project to at most one orchestrator, and only the person can change it.

  • client.calmSidebarEnabled (new, per device, off) is the switch the sidebar PR will read. It is per device, so a phone can be calm while a desktop shows the full list.

  • Server save check (apps/server/src/fork/threadRoleTargets.ts). A save that sets a role pointer anew is refused unless the thread:

    • exists and is not deleted;
    • is a top-level thread, not a sub-agent, a side chat or a task delegated from a linked machine;
    • for an orchestrator, belongs to the project its entry names.

    The check reads threads through a small service that the runtime layer provides (threadRoleTargetsLayer.ts, wired in forkLayers.ts), so the settings file imports no orchestration code. Where that service is missing, a new pointer is refused (fail closed). A refusal is upstream's ServerSettingsError (normalize) with a ForkSettingsWriteError that says what to fix. It is the same path the other fork save checks use.

  • Per-entry patch. A new fork patch rule, fields, changes each field by its own rule:

    • assistant is replaced.
    • orchestrators is changed per entry; null removes one entry.
  • Person-only. FORK_PERSON_ONLY_KEYS is derived from every fork key, so threadRoles joins it with no extra line. A test pins it, and the managed policy can lock it only as a whole.

  • Docs. docs/fork/README.md has the setting rows and sections, and FORK_CHANGES.md has a new line.

Owner decisions used

  • #138: roles are a setting. That is what this PR builds.
  • #139: the calm view folds the other threads, with a waiting count. The toggle is here; the view comes in a later PR.
  • #140: yes, an orchestrator may pass its own role to a new thread without a click. This PR does not open that door: threadRoles stays person-only, so the settings tool refuses it for agents. The handoff comes later, through its own dedicated path with its own checks, not through the settings tool.

Seams

  • No new upstream line is added. settings.ts already spreads ForkServerSettingsFields, ForkServerSettingsPatchFields and ForkClientSettingsFields.
  • Upstream's ClientSettingsPatch has no fork spread yet, and nothing saves a client fork setting yet. So this PR announces ...ForkSettings.ForkClientSettingsPatchFields, for packages/contracts/src/settings.ts in .github/fork-seams.json. The sidebar PR that saves the toggle adds the line (announce, then add).

Upstream fit

  • This builds on upstream's own mechanisms:
    • upstream's settings file, patch and ServerSettingsError;
    • upstream's isListedThreadLineage, which already keeps sub-agents and side chats out of the sidebar;
    • upstream's OrchestratorV2.getThreadShell, which returns null for a missing or deleted thread.
  • No upstream file changes in this PR: every line is in fork files (forkSettings.ts, threadRoles.ts, forkSettingsPatch.ts, apps/server/src/fork/…, fork docs) or in the seam config.
  • No upstream issue or PR offers thread roles or a folded sidebar today.

General vs project

  • General: roles are project ids and thread ids from T3's own data. No project name, repo or path is built in.
  • Project-specific: nothing. Which thread is which project's orchestrator is the person's setting on their machine.

State question

  • Old settings file with no roles. It reads as no roles ({"assistant":null,"orchestrators":{}}). A later save of any other setting leaves the key out of the file, as before. A client settings file without calmSidebarEnabled reads as off. Tested: contracts decode, and a load-then-save through the settings service.

  • A bad entry (hand edit). It drops alone:

    • a bad assistant reads as none;
    • an orchestrator entry whose project or thread is not an id is dropped;
    • a value that is not an object reads as no roles.

    The other settings are never reset. A save with a bad id is refused (strict patch).

  • An old pointer to a thread deleted since. It is not checked again when a save leaves it as it was, so it blocks no other save. Whoever reads the roles (a later PR) checks the thread and treats a failing one as "no role". Tested.

  • Settings written half-way. The check runs before anything is written, inside upstream's one-writer semaphore. A refused save writes nothing (tested: the file is unchanged). A save that passes is written with upstream's atomic write (writeFileStringAtomically, temp file then rename), so a crash leaves the old file or the new one, never a half-written roles state.

  • Two writers at once. Saves are serialised by upstream's semaphore, and each patch is applied to the file as it is then. Two people setting different projects' orchestrators both keep theirs; two saves for the same project, the last one wins. Tested.

  • Runs again. Saving the same roles again sets no new pointer, so nothing is read or refused.

  • Server path without thread access. A new pointer is refused ("cannot be checked here"), never let through. Tested. If reading a thread fails, the save is refused with "try again". Tested.

Tests

  • packages/contracts/src/threadRoles.test.ts: old file, good value round trip, bad entries drop alone, bad assistant, non-object, strict patch, person-only, calmSidebarEnabled default.
  • packages/shared/src/forkSettingsThreadRoles.test.ts: per-entry patch (two projects kept, null removes one, assistant replaced, left-out or empty keeps).
  • apps/server/src/fork/threadRoleTargets.test.ts:
    • each refusal: missing or deleted, sub-agent or side chat, delegated, other project;
    • an unchanged or removed pointer is never read;
    • fail closed with no service, and on a read error;
    • through the settings service: old file, an accepted save, a refused save that writes nothing, a refusal with no service.

Tests fail without the change (shown before opening)

  • Save check call removed from ForkSettingsWrite.check: 2 server tests fail ("refuses a role for a sub-agent, and writes nothing", "refuses a new role where the server cannot read threads").
  • threadRoles patch rule set to plain replace instead of per entry: 4 shared patch tests fail (two projects kept, null removes one, and the keep cases).
  • ThreadRoles fields without their decoding defaults: the settings-service test fails on the sparse write ("Missing key assistant"); this was a real bug the test found and the fix is in.

Checks run

  • Typecheck (effect-tsgo): contracts, shared, server, web: 0 errors.
  • Vitest: contracts 50, shared 75, server 68 (changed and neighbouring files), all pass.
  • Seam check against origin/main: exit 0. vp fmt --check on the 15 touched files: clean. Pre-commit (fmt, lint, knip): pass.

Part of the calm sidebar design (PR 1 of N)

  1. This PR: settings and the save check.
  2. Client state: resolve roles, calm partition.
  3. Web: badge, the "Other threads (N)" group with the waiting count, the toggle (adds the announced seam line), docs.
  4. Thread menu and Settings panel for roles.

Later, the owner-approved handoff of an orchestrator's role (#140) comes through its own path.

🤖 Generated with Claude Code

scuttletoby and others added 2 commits November 22, 2026 09:59
Adds the person-only server setting threadRoles (one assistant thread,
one orchestrator thread per project) and the per-device client setting
calmSidebarEnabled, both off by default and read by nothing yet.

- Lenient read: a bad hand-edited entry drops alone; an old file reads
  as no roles.
- Per-entry patch: a new "fields" fork patch rule; orchestrators are
  set or removed (null) one project at a time.
- Server save check: a new pointer must name an existing top-level
  thread (not a sub-agent, side chat or delegated task) of the right
  project. Fails closed where threads cannot be read.
- Seam config announces the client settings patch spread for the
  sidebar PR that saves the toggle.

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

Copy link
Copy Markdown
Owner Author

lens: code · reviewer: lens agent (Opus 5.5) · read at: da45995
verdict: safe to merge
covered: the whole diff against main (threadRoles.ts, forkSettings.ts, forkDefaults.ts, forkSettingsPatch.ts, threadRoleTargets.ts, threadRoleTargetsLayer.ts, serverSettingsWriteCheck.ts, forkLayers.ts, forkManagedSettings.ts, fork-seams.json, docs, the three test files); issue #878; how serverSettings.ts runs the check (inside the write semaphore, before vetting and the atomic write); server.ts wiring (layerRuntimeServices sits in layerRuntimeCoreDependenciesBase, the same place SlotGate is read by serviceOption); upstream's isListedThreadLineage, getThreadShell and the thread payload decode; the agent settings tool (t3_environment_preferences_update) and the personOnlySettings test.
checks: ran the PR's three test files on the head: contracts threadRoles.test.ts 10/10, shared forkSettingsThreadRoles.test.ts 5/5, server threadRoleTargets.test.ts 13/13. Mutation: with the project-match test removed from threadRoleTargets.ts, "refuses an orchestrator from another project" fails (restored after). Traced by reading: null delegatedFrom on a server shell (cannot pass the payload decode), a hand-edited id with outer spaces (dropped by the lenient read), a defect from the lookup.
state: runs again: saving the same roles sets no new pointer, so nothing is read or refused. Stopped half-way: the check runs before anything is written, inside upstream's semaphore, and a passing save uses upstream's temp-file-then-rename write; a refused save leaves the file as it was. Old or empty state: a file with no threadRoles (or null, or not an object) reads as no roles; a bad entry drops alone and the next save writes the file without it; an old pointer to a thread deleted since is never re-checked, so it blocks no other save. Other settings writers (theme, project sweep, speech) that may run without the thread lookup never touch threadRoles, so they set no new pointer and are never refused.
blocker: none
major: none
minor: apps/server/src/fork/threadRoleTargetsLayer.ts:23 tests shell.delegatedFrom !== undefined; upstream's isDelegatedAppThread uses != null because MCP-launched threads can carry delegatedFrom: null in memory. Server shells come from the schema decode, where null cannot get through, so this is right today; != null would match upstream's helper and stay right if the shell source changes (a null there would wrongly refuse an MCP-launched top-level thread as "delegated").
minor: the real lookup (threadRoleTargetsLayer.ts, shell to {projectId, listed, delegated}) has no test: every server test provides a fake ThreadRoleTargets. A slip in the mapping or the wiring would refuse every new role ("cannot be checked here") or misjudge one. That fails closed, but the Settings UI in a later PR would be the first to find it. One test of the layer over a stub OrchestratorV2 (null shell, side chat, sub-agent, delegated, project id) would pin it.
minor: apps/server/src/fork/threadRoleTargets.ts:92 Effect.option turns a typed read failure into "try again", but a defect from the lookup escapes and fails the save as an internal error. Nothing is written either way, so only the message differs.
minor: the seam announcement (since 2026-11-22) lasts 14 days (docs/fork/updates.md): if this merges later than today, refresh since to the merge day; the sidebar PR that adds the line must land before it runs out, or announce it again.
minor: an archived thread can take a role (only missing or deleted ones are refused). Fine for a pointer, but the reader in part 2 should decide what an archived role thread shows.

Answers to the brief's questions:

  • Save check complete: yes. Top-level only (sub-agent and side chat through upstream's isListedThreadLineage; a "fork" lineage thread is listed and may hold a role, as upstream lists it), delegated tasks refused, an orchestrator must be in the project its key names, a missing service or a failed read refuses (fail closed). Only pointers a save sets anew are read.
  • Who can set threadRoles: only a person (the app's settings write). It is in the derived FORK_PERSON_ONLY_KEYS; the only agent settings tool takes a fixed list of upstream fields, and the personOnlySettings test fails if any T3 tool's input names a fork key. Managed policy can lock it only as a whole.
  • Lenient read: drops only bad entries (a bad assistant reads as none; an orchestrator entry with a bad key or value is dropped; the other entries and the rest of the file stay). Its id test (non-empty, no outer spaces) matches ThreadId/ProjectId (trimmed, non-blank), so a kept entry can never fail the strict decode after it.
  • Patch: the new fields rule applies assistant by replace and orchestrators by replaceEntries (null removes one entry); a left-out or undefined field keeps its value. No other code switches on the rule kinds.
  • Upstream fit: no upstream file changed (all lines in fork files and the seam config). The seam entry announces ...ForkSettings.ForkClientSettingsPatchFields, for packages/contracts/src/settings.ts before any PR adds it: announce, then add, as docs/fork/updates.md asks.
  • Nothing reads the new settings yet: outside the PR's own files and tests, no code in apps/ or packages/ names threadRoles or calmSidebarEnabled.

@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: code · reviewer: lens agent (Opus 5.5) · read at: da45995
verdict: not safe to merge
note: replaces this lens's earlier report on the same head, which missed the red CI test below.
covered: the whole diff against main (threadRoles.ts, forkSettings.ts, forkDefaults.ts, forkSettingsPatch.ts, threadRoleTargets.ts, threadRoleTargetsLayer.ts, serverSettingsWriteCheck.ts, forkLayers.ts, forkManagedSettings.ts, fork-seams.json, docs, the three test files); issue #878; how serverSettings.ts runs the check (inside the write semaphore, before vetting and the atomic write); server.ts wiring (layerRuntimeServices sits in layerRuntimeCoreDependenciesBase, the same place SlotGate is read by serviceOption); upstream's isListedThreadLineage, getThreadShell and the thread payload decode; the agent settings tool (t3_environment_preferences_update) and the personOnlySettings test.
checks: CI's Test Server 4 on this head fails (fork-ci-result red); ran the PR's three test files on the head: contracts threadRoles.test.ts 10/10, shared forkSettingsThreadRoles.test.ts 5/5, server threadRoleTargets.test.ts 13/13. Mutation: with the project-match test removed from threadRoleTargets.ts, "refuses an orchestrator from another project" fails (restored after). Traced by reading: null delegatedFrom on a server shell (cannot pass the payload decode), a hand-edited id with outer spaces (dropped by the lenient read), a defect from the lookup.
state: runs again: saving the same roles sets no new pointer, so nothing is read or refused. Stopped half-way: the check runs before anything is written, inside upstream's semaphore, and a passing save uses upstream's temp-file-then-rename write; a refused save leaves the file as it was. Old or empty state: a file with no threadRoles (or null, or not an object) reads as no roles; a bad entry drops alone and the next save writes the file without it; an old pointer to a thread deleted since is never re-checked, so it blocks no other save. Other settings writers (theme, project sweep, speech) that may run without the thread lookup never touch threadRoles, so they set no new pointer and are never refused.
blocker: none
major: the PR turns CI red: apps/server/src/golive/forkReport.test.ts:1131 "counts every fork setting as a feature or names why it is not a switch" fails with expected [ 'threadRoles' ] to deeply equal [] (Test Server 4). Every fork server setting must be a counted report feature or sit in NOT_A_SWITCH (forkReport.test.ts:1115) with a reason. Fix like placement/placementNeeds: add a threadRoles row there (settings only so far; nothing reads them yet). calmSidebarEnabled is a client key, which this test does not list.
minor: apps/server/src/fork/threadRoleTargetsLayer.ts:23 tests shell.delegatedFrom !== undefined; upstream's isDelegatedAppThread uses != null because MCP-launched threads can carry delegatedFrom: null in memory. Server shells come from the schema decode, where null cannot get through, so this is right today; != null would match upstream's helper and stay right if the shell source changes (a null there would wrongly refuse an MCP-launched top-level thread as "delegated").
minor: the real lookup (threadRoleTargetsLayer.ts, shell to {projectId, listed, delegated}) has no test: every server test provides a fake ThreadRoleTargets. A slip in the mapping or the wiring would refuse every new role ("cannot be checked here") or misjudge one. That fails closed, but the Settings UI in a later PR would be the first to find it. One test of the layer over a stub OrchestratorV2 (null shell, side chat, sub-agent, delegated, project id) would pin it.
minor: apps/server/src/fork/threadRoleTargets.ts:92 Effect.option turns a typed read failure into "try again", but a defect from the lookup escapes and fails the save as an internal error. Nothing is written either way, so only the message differs.
minor: the seam announcement (since 2026-11-22) lasts 14 days (docs/fork/updates.md): if this merges later than today, refresh since to the merge day; the sidebar PR that adds the line must land before it runs out, or announce it again.
minor: an archived thread can take a role (only missing or deleted ones are refused). Fine for a pointer, but the reader in part 2 should decide what an archived role thread shows.

Answers to the brief's questions:

  • Save check complete: yes. Top-level only (sub-agent and side chat through upstream's isListedThreadLineage; a "fork" lineage thread is listed and may hold a role, as upstream lists it), delegated tasks refused, an orchestrator must be in the project its key names, a missing service or a failed read refuses (fail closed). Only pointers a save sets anew are read.
  • Who can set threadRoles: only a person (the app's settings write). It is in the derived FORK_PERSON_ONLY_KEYS; the only agent settings tool takes a fixed list of upstream fields, and the personOnlySettings test fails if any T3 tool's input names a fork key. Managed policy can lock it only as a whole.
  • Lenient read: drops only bad entries (a bad assistant reads as none; an orchestrator entry with a bad key or value is dropped; the other entries and the rest of the file stay). Its id test (non-empty, no outer spaces) matches ThreadId/ProjectId (trimmed, non-blank), so a kept entry can never fail the strict decode after it.
  • Patch: the new fields rule applies assistant by replace and orchestrators by replaceEntries (null removes one entry); a left-out or undefined field keeps its value. No other code switches on the rule kinds.
  • Upstream fit: no upstream file changed (all lines in fork files and the seam config). The seam entry announces ...ForkSettings.ForkClientSettingsPatchFields, for packages/contracts/src/settings.ts before any PR adds it: announce, then add, as docs/fork/updates.md asks.
  • Nothing reads the new settings yet: outside the PR's own files and tests, no code in apps/ or packages/ names threadRoles or calmSidebarEnabled.

@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: state · reviewer: lens agent · read at: da45995
verdict: safe to merge
covered: the whole diff (contracts threadRoles.ts and forkSettings.ts, shared forkSettingsPatch.ts, server fork/threadRoleTargets.ts, threadRoleTargetsLayer.ts, serverSettingsWriteCheck.ts, forkLayers.ts, forkManagedSettings.ts, docs), against serverSettings.ts (updateAndPersistSettings, stripDefaultServerSettings, writeSettingsAtomically), the projection store's getThreadShell and the RPC handler context, and issue #878
checks: ran the 3 changed test files (contracts 10, shared 5, server 13: all pass). Mutation: the assistant decoding default removed turns "saves a role for a thread that can hold it" red with "Missing key"; the orchestrators default removed turns the contracts test "writes a value sparse" red. Checked that the RPC handlers run with a context that holds ThreadRoleTargets (RpcGroup captures the build context; the layer is merged above the routes), so a real save is not refused as "cannot be checked here". Checked that no stored thread carries delegatedFrom: null and that the strict thread decode would refuse one.
state: old file with no threadRoles: reads as no roles, and a save of another setting leaves the key out (tested). Hand-edited bad entry: drops alone, never resets other settings; the lenient reader's output always passes the strict ThreadRoles decode, so no whole-settings reset. Stopped half-way: the check runs before any write inside the one-writer semaphore, a refusal writes nothing (tested), a passing save uses upstream's temp-file-and-rename write. Two writers: serialised, each patch applied to the file as it then is; different projects both kept, same project last wins, null removes one entry (tested). Runs again: the same roles set no new pointer and read nothing. A role thread later deleted, archived or moved: the pointer stays, is not re-checked when left as it was, so it blocks no other save; readers must check it. Project removed: its entry stays. Older web build: it sends only changed server fields, so threadRoles is kept; its client-settings write drops calmSidebarEnabled, which reads as off. Missing-key sibling: both ThreadRoles fields have their default and each is pinned by a test; nothing else decodes a sparse ThreadRoles.
blocker: none
major: none
minor: apps/server/src/fork/threadRoleTargetsLayer.ts:18 an archived thread passes the save check (getThreadShell returns it); say in the docs whether a reader treats an archived role thread as no role, or refuse it here
minor: apps/server/src/fork/threadRoleTargetsLayer.ts:23 delegatedFrom !== undefined, where upstream's isDelegatedAppThread uses != null for the same question; not reachable today (strict decode), but != null matches upstream
minor: packages/contracts/src/threadRoles.ts:49 a hand-edited entry that is dropped on read (for example an id with a trailing space, which a save would trim) is removed from the file by the next unrelated save; the docs say "drops alone" but not that the text is erased
minor: an orchestrator entry for a removed project stays in the file (ProjectSettingsOverrideSweep sweeps only projectSettingsOverrides); fine while readers check, and CAL4's Settings list should show such entries as missing
minor: apps/web/src/clientPersistenceStorage.ts:24 an older web build open on the same device rewrites the whole client settings without calmSidebarEnabled, so the toggle falls back to off (the safe side); worth one line in the docs once the toggle ships

@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: state · reviewer: lens agent · read at: da45995
verdict: not safe to merge
covered: as in this lens's earlier report on this head, plus the PR's CI result, read after posting it; this report replaces that one's verdict
checks: the 3 changed test files pass locally (contracts 10, shared 5, server 13), and both decoding-default mutations turn a test red; CI job Test Server 4 fails on this head in src/golive/forkReport.test.ts, "counts every fork setting as a feature or names why it is not a switch", with "expected [ 'threadRoles' ] to deeply equal []"
state: unchanged from the earlier report on this head: old file reads as no roles; a bad hand edit drops alone; a refused save writes nothing, a passing one is an atomic rename inside the one-writer semaphore; two writers keep both projects' entries; a pointer to a thread deleted, archived or moved since is not re-checked and blocks no other save; an older web build keeps threadRoles and drops calmSidebarEnabled to off; both ThreadRoles field defaults are pinned by tests
blocker: none
major: the fork report does not know the new setting threadRoles, so fork-ci-result fails (apps/server/src/golive/forkReport.test.ts:1135); add it to NOT_A_SWITCH beside placementNeeds (forkReport.test.ts:1115, "calm sidebar: settings only so far; nothing reads them yet"), or count it as a feature in apps/server/src/golive/forkReport.ts:516
minor: apps/server/src/fork/threadRoleTargetsLayer.ts:18 an archived thread passes the save check; say whether a reader treats it as no role, or refuse it here
minor: apps/server/src/fork/threadRoleTargetsLayer.ts:23 delegatedFrom !== undefined where upstream's isDelegatedAppThread uses != null; not reachable today, but != null matches upstream
minor: packages/contracts/src/threadRoles.ts:49 a hand-edited entry dropped on read is erased from the file by the next unrelated save; the docs say "drops alone" but not that
minor: an orchestrator entry for a removed project stays in the file (the override sweep does not cover it); fine while readers check
minor: apps/web/src/clientPersistenceStorage.ts:24 an older web build on the same device rewrites client settings without calmSidebarEnabled, so the toggle falls back to off (the safe side)

This branch has not been deployed

No deployments
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