From 8deb1e076e24aaed95b56c869640026b5c261f86 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 09:59:05 +0000 Subject: [PATCH 1/3] Calm sidebar part 1: threadRoles and calmSidebarEnabled settings 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 --- .github/fork-seams.json | 8 +- FORK_CHANGES.md | 1 + apps/server/src/fork/forkLayers.ts | 9 +- .../src/fork/serverSettingsWriteCheck.ts | 34 +-- .../server/src/fork/threadRoleTargets.test.ts | 266 ++++++++++++++++++ apps/server/src/fork/threadRoleTargets.ts | 101 +++++++ .../server/src/fork/threadRoleTargetsLayer.ts | 28 ++ apps/server/src/policy/forkManagedSettings.ts | 1 + docs/fork/README.md | 99 +++++-- packages/contracts/src/forkDefaults.ts | 16 ++ packages/contracts/src/forkSettings.ts | 30 +- packages/contracts/src/threadRoles.test.ts | 126 +++++++++ packages/contracts/src/threadRoles.ts | 77 +++++ packages/shared/src/forkSettingsPatch.ts | 9 + .../src/forkSettingsThreadRoles.test.ts | 69 +++++ 15 files changed, 814 insertions(+), 60 deletions(-) create mode 100644 apps/server/src/fork/threadRoleTargets.test.ts create mode 100644 apps/server/src/fork/threadRoleTargets.ts create mode 100644 apps/server/src/fork/threadRoleTargetsLayer.ts create mode 100644 packages/contracts/src/threadRoles.test.ts create mode 100644 packages/contracts/src/threadRoles.ts create mode 100644 packages/shared/src/forkSettingsThreadRoles.test.ts diff --git a/.github/fork-seams.json b/.github/fork-seams.json index 2c327ecde16df..d28893619d73e 100644 --- a/.github/fork-seams.json +++ b/.github/fork-seams.json @@ -2,7 +2,7 @@ "//": "Upstream files with fork lines, and every line the fork may add to each (indentation and blank lines ignored). Checked by .github/scripts/fork-seam-check.cjs against the base branch's copy of this file; see docs/fork/updates.md. A new line is first announced in its entry (\"announced\": {\"since\": day, \"added\": [lines]}), then added by a later pull request that moves it to \"added\" (docs/fork/updates.md, Adding a seam line).", "files": { "packages/contracts/src/settings.ts": { - "why": "Fork settings live in forkSettings.ts; settings.ts takes them with one spread per struct. automaticUpdates stays inline: upstream's pending setting has the same name and place.", + "why": "Fork settings live in forkSettings.ts; settings.ts takes them with one spread per struct (the client settings patch's spread is announced for the calm sidebar's toggle, which saves the first client fork setting). automaticUpdates stays inline: upstream's pending setting has the same name and place.", "added": [ "import * as ForkSettings from \"./forkSettings.ts\";", "export * from \"./forkSettings.ts\";", @@ -19,7 +19,11 @@ "*/", "automaticUpdates: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),", "automaticUpdates: Schema.optionalKey(Schema.Boolean)," - ] + ], + "announced": { + "since": "2026-11-22", + "added": ["...ForkSettings.ForkClientSettingsPatchFields,"] + } }, "packages/shared/src/serverSettings.ts": { "why": "A settings patch's fork fields are applied by forkSettingsPatch.ts, by the rules in forkSettings.ts.", diff --git a/FORK_CHANGES.md b/FORK_CHANGES.md index a9428efb90e13..4c03658cf69f9 100644 --- a/FORK_CHANGES.md +++ b/FORK_CHANGES.md @@ -48,6 +48,7 @@ setting is missing here or a setting named here does not exist. | Run records: one line per agent run that ends (model, effort, role, kind, estimate, times, end status, provider-reported tokens) in `/run-records/runs.jsonl`, append-only, and a weekly summary command. | Later choices of model, effort and task size need what earlier runs cost and took. | none | always (writes only its own files) | [#588](https://github.com/scuttletoby/t3code/pull/588) | | Model policy: the setting for which models (and efforts) agents may pick, per provider driver: off, advise or enforce, and the allowed rows. The server checks an agent's pick (`delegate_task`, `create_threads`, `t3_thread_launch`, `t3_thread_configure`, here, and both before and after it goes to linked machines): a model in no row, a call that names no model, or an effort off its row is refused in enforce, only noted in advise. A person's own pick is never refused; Settings marks one outside the rows. A bad hand edit, or a settings file that does not parse, refuses every agent pick (a warning if the value says advise). Settings offers the fork's start rows (Opus 5.5 and Fable 5.2) while none are saved. While it is on, a child whose call names its model keeps only the options it names. | Agents should use the models the person chose for each kind of work. | `server.modelPolicy` | off | [#268](https://github.com/scuttletoby/t3code/pull/268), [#731](https://github.com/scuttletoby/t3code/issues/731) | | Placement, part 1: the settings only. `placement` (off, advise or enforce; this machine's labels, an optional facts command, label groups that must never meet on one machine, and a weight per linked machine) and `placementNeeds` (labels a project's work needs). Person-only; a bad `placement` reads as off and a bad `placementNeeds` fits no machine, each kept as written. Nothing reads them yet. | Delegated work should go to a machine that has what it needs, and never where it must not run. | `server.placement`, `server.placementNeeds`, `projectOverride.placementNeeds` | off | [#134](https://github.com/scuttletoby/t3code/issues/134) | +| Calm sidebar, part 1: the settings. `threadRoles` names the assistant thread and one orchestrator per project; the server refuses a role for a thread that is missing, deleted, a sub-agent, a side chat, delegated from a linked machine or in another project. `calmSidebarEnabled` is the per-device switch. Nothing shows them yet. | A short sidebar: the threads that matter on top, the rest folded. | `server.threadRoles`, `client.calmSidebarEnabled` | off | (this pull request) | ## Repository, CI and releases diff --git a/apps/server/src/fork/forkLayers.ts b/apps/server/src/fork/forkLayers.ts index 9d236fb0e4f8a..4cff921a71e7a 100644 --- a/apps/server/src/fork/forkLayers.ts +++ b/apps/server/src/fork/forkLayers.ts @@ -27,6 +27,7 @@ import * as PullRequestWatchSlot from "./pullRequestWatchSlot.ts"; import * as RemoteTaskPrompts from "./remoteTaskPrompts.ts"; import * as RemoteTaskPromptWakes from "./remoteTaskPromptWakes.ts"; import * as RunRecorder from "./runRecords/RunRecorder.ts"; +import * as ThreadRoleTargets from "./threadRoleTargetsLayer.ts"; import * as WorkerWakeSlots from "./workerWakeSlots.ts"; /** @@ -47,10 +48,9 @@ export const holdWorkCloudLink = ( ) => HoldWorkConnect.layer(cloudLinkLayer).pipe(Layer.provideMerge(reachabilityLayer)); /** - * In the runtime's core dependencies (server.ts's `layerRuntimeCoreDependenciesBase`, not its local - * `layerRuntimeServices`): usage pacer (and its history), slot gate, usage refresher, the handoff - * service (fork/handoff), which upstream's own `mergeAll` builds concurrently beside its idle - * compaction worker, the run records follower (fork/runRecords) and the delegated result reminder. + * In server.ts's `layerRuntimeCoreDependenciesBase`: usage pacer and history, slot gate, usage + * refresher, handoff service (built beside upstream's idle compaction worker), run records, result + * reminder, and the `threadRoles` save check's thread lookup, which every settings write reaches. */ export const layerRuntimeServices = Layer.mergeAll( UsagePacer.layer.pipe(Layer.provideMerge(UsageReadingsHistory.layer)), @@ -59,6 +59,7 @@ export const layerRuntimeServices = Layer.mergeAll( HandoffService.layer, RunRecorder.layer, DelegatedResultReminder.layer, + ThreadRoleTargets.layer, ); /** diff --git a/apps/server/src/fork/serverSettingsWriteCheck.ts b/apps/server/src/fork/serverSettingsWriteCheck.ts index c49509e4c6938..89af4b206baa9 100644 --- a/apps/server/src/fork/serverSettingsWriteCheck.ts +++ b/apps/server/src/fork/serverSettingsWriteCheck.ts @@ -13,28 +13,28 @@ import { import * as HostProcess from "@t3tools/shared/HostProcess"; import { Effect } from "effect"; +import { threadRolesSaveProblem } from "./threadRoleTargets.ts"; + /** Fails when saving `next` over `current` would bring in a fork setting or interval that cannot apply. */ -export function check( +export const check = Effect.fn("ForkSettingsWrite.check")(function* ( current: ServerSettings, next: ServerSettings, settingsPath: string, -): Effect.Effect { - return Effect.flatMap(HostProcess.Platform, (platform) => { - const problem = - forkSettingsWriteProblem(current, next) ?? - playtestProgramProblem(current, next, platform) ?? - placementFactsCommandSaveProblem(current, next, platform); - return problem === undefined - ? Effect.void - : Effect.fail( - new ServerSettingsError({ - settingsPath, - operation: "normalize", - cause: new ForkSettingsWriteError({ problem }), - }), - ); +) { + const platform = yield* HostProcess.Platform; + const problem = + forkSettingsWriteProblem(current, next) ?? + playtestProgramProblem(current, next, platform) ?? + placementFactsCommandSaveProblem(current, next, platform) ?? + // Reads the threads a new role pointer names, so it runs last (fork/threadRoleTargets.ts). + (yield* threadRolesSaveProblem(current, next)); + if (problem === undefined) return; + return yield* new ServerSettingsError({ + settingsPath, + operation: "normalize", + cause: new ForkSettingsWriteError({ problem }), }); -} +}); /** `update`, then {@link check} on what it returns. */ export const withCheck = diff --git a/apps/server/src/fork/threadRoleTargets.test.ts b/apps/server/src/fork/threadRoleTargets.test.ts new file mode 100644 index 0000000000000..93f6dd6ef3f4d --- /dev/null +++ b/apps/server/src/fork/threadRoleTargets.test.ts @@ -0,0 +1,266 @@ +// Fork (calm sidebar): the server's save check for `threadRoles`. Each refusal, the pointers it +// leaves alone, and that it fails closed where threads cannot be read. +import * as NodeCrypto from "@effect/platform-node/NodeCrypto"; +import * as NodeServices from "@effect/platform-node/NodeServices"; +import { + DEFAULT_SERVER_SETTINGS, + ServerSettingsError, + ServerSettingsPatch, + type ThreadId, + type ThreadRoles, +} from "@t3tools/contracts"; +import { ForkSettingsWriteError } from "@t3tools/shared/forkSettingsPatch"; +import { assert, describe, it } from "@effect/vitest"; +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; + +import * as ServerSecretStore from "../auth/ServerSecretStore.ts"; +import * as ServerConfig from "../config.ts"; +import * as SqlitePersistence from "../persistence/Sqlite.ts"; +import * as ManagedPolicy from "../policy/ManagedPolicy.ts"; +import * as ServerSettingsModule from "../serverSettings.ts"; + +import { + newThreadRolePointers, + type ThreadRoleTarget, + ThreadRoleTargets, + threadRolesSaveProblem, +} from "./threadRoleTargets.ts"; + +class DatabaseBusy extends Schema.TaggedError()("DatabaseBusy", {}) {} + +const id = (value: string) => value as ThreadId; +const roles = ( + assistant: string | null, + orchestrators: Record = {}, +): { readonly threadRoles: ThreadRoles } => ({ + threadRoles: { + assistant: assistant === null ? null : id(assistant), + orchestrators: orchestrators as ThreadRoles["orchestrators"], + }, +}); +const NONE = roles(null); + +const top = (projectId: string): ThreadRoleTarget => ({ + projectId, + listed: true, + delegated: false, +}); + +/** Threads by id; a missing id is a thread that does not exist or is deleted. */ +const THREADS: Record = { + "thread-top": top("project-1"), + "thread-other-project": top("project-2"), + "thread-subagent": { ...top("project-1"), listed: false }, + "thread-delegated": { ...top("project-1"), delegated: true }, +}; + +const targets = (reads: Array = []) => + Layer.succeed( + ThreadRoleTargets, + ThreadRoleTargets.of({ + find: (threadId) => + Effect.sync(() => { + reads.push(threadId); + return THREADS[threadId] ?? null; + }), + }), + ); + +const problemOf = ( + current: { readonly threadRoles: ThreadRoles }, + next: { readonly threadRoles: ThreadRoles }, +) => threadRolesSaveProblem(current, next).pipe(Effect.provide(targets())); + +describe("threadRoles save check", () => { + it("is off by default: the default settings set no pointer", () => { + assert.deepStrictEqual( + newThreadRolePointers( + DEFAULT_SERVER_SETTINGS.threadRoles, + DEFAULT_SERVER_SETTINGS.threadRoles, + ), + [], + ); + }); + + it.effect("lets a top-level thread take the assistant role and its project's orchestrator", () => + Effect.gen(function* () { + assert.isUndefined(yield* problemOf(NONE, roles("thread-top"))); + assert.isUndefined(yield* problemOf(NONE, roles(null, { "project-1": "thread-top" }))); + assert.isUndefined(yield* problemOf(NONE, roles("thread-other-project"))); + }), + ); + + it.effect("refuses a thread that does not exist or is deleted", () => + Effect.gen(function* () { + const problem = yield* problemOf(NONE, roles("thread-gone")); + assert.match( + problem ?? "", + /threadRoles\.assistant names thread thread-gone, which does not exist or is deleted/u, + ); + }), + ); + + it.effect("refuses a sub-agent or side chat", () => + Effect.gen(function* () { + const problem = yield* problemOf(NONE, roles(null, { "project-1": "thread-subagent" })); + assert.match( + problem ?? "", + /threadRoles\.orchestrators\["project-1"\] names thread thread-subagent, which is a sub-agent or side chat/u, + ); + }), + ); + + it.effect("refuses a task delegated from a linked machine", () => + Effect.gen(function* () { + const problem = yield* problemOf(NONE, roles("thread-delegated")); + assert.match(problem ?? "", /which is a task delegated from a linked machine/u); + }), + ); + + it.effect("refuses an orchestrator from another project", () => + Effect.gen(function* () { + const problem = yield* problemOf(NONE, roles(null, { "project-1": "thread-other-project" })); + assert.match( + problem ?? "", + /which belongs to project project-2: a project's orchestrator must be one of its own threads/u, + ); + }), + ); + + it.effect("never refuses or reads a pointer the save leaves as it was, nor a removal", () => + Effect.gen(function* () { + const reads: Array = []; + // An old pointer to a thread deleted since, kept by a save that changes something else. + const old = roles("thread-gone", { "project-1": "thread-gone" }); + const keep = threadRolesSaveProblem(old, old).pipe(Effect.provide(targets(reads))); + assert.isUndefined(yield* keep); + const remove = threadRolesSaveProblem(old, roles(null)).pipe(Effect.provide(targets(reads))); + assert.isUndefined(yield* remove); + // Adding another project reads only the new thread. + const add = threadRolesSaveProblem( + old, + roles("thread-gone", { "project-1": "thread-gone", "project-2": "thread-other-project" }), + ).pipe(Effect.provide(targets(reads))); + assert.isUndefined(yield* add); + assert.deepStrictEqual(reads, ["thread-other-project"]); + }), + ); + + it.effect("fails closed where threads cannot be read", () => + Effect.gen(function* () { + // No ThreadRoleTargets service at all. + const problem = yield* threadRolesSaveProblem(NONE, roles("thread-top")); + assert.match(problem ?? "", /cannot be checked here/u); + // A save that sets no new pointer needs no service. + assert.isUndefined(yield* threadRolesSaveProblem(NONE, NONE)); + }), + ); + + it.effect("refuses when a thread read fails", () => + Effect.gen(function* () { + const failing = Layer.succeed( + ThreadRoleTargets, + ThreadRoleTargets.of({ find: () => Effect.fail(new DatabaseBusy()) }), + ); + const problem = yield* threadRolesSaveProblem(NONE, roles("thread-top")).pipe( + Effect.provide(failing), + ); + assert.match( + problem ?? "", + /thread thread-top could not be read, so the role was not saved/u, + ); + }), + ); +}); + +// Through the settings service, as a client's save reaches it: a refusal writes nothing. +it.layer(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))( + "threadRoles saves through the settings service", + (it) => { + const layerServerSettings = () => + ServerSettingsModule.layer.pipe( + Layer.provide(ServerSecretStore.layer), + Layer.provide(ManagedPolicy.layerTest()), + Layer.provideMerge(Layer.fresh(SqlitePersistence.layerMemory)), + Layer.provideMerge( + Layer.fresh( + ServerConfig.layerTest(process.cwd(), { prefix: "t3code-thread-roles-test-" }), + ), + ), + ); + + const decodePatch = Schema.decodeUnknownSync(ServerSettingsPatch); + + const readFile = Effect.gen(function* () { + const config = yield* ServerConfig.ServerConfig; + const fs = yield* FileSystem.FileSystem; + return JSON.parse(yield* fs.readFileString(config.settingsPath)) as Record; + }); + + /** Writes `start` as the settings file, loads it, then saves `patch`. */ + const loadThenSave = (start: unknown, patch: unknown) => + Effect.gen(function* () { + const config = yield* ServerConfig.ServerConfig; + const fs = yield* FileSystem.FileSystem; + yield* fs.writeFileString(config.settingsPath, JSON.stringify(start)); + const service = yield* ServerSettingsModule.ServerSettingsService; + yield* service.getSettings; + return yield* service.updateSettings(decodePatch(patch)); + }); + + it.effect("loads an old file with no roles and saves other settings as before", () => + Effect.gen(function* () { + const saved = yield* loadThenSave( + { enableAgentBrowserAccess: false }, + { enableAgentBrowserAccess: true }, + ); + assert.deepStrictEqual(saved.threadRoles, { assistant: null, orchestrators: {} }); + assert.isFalse("threadRoles" in (yield* readFile)); + }).pipe(Effect.provide(Layer.merge(layerServerSettings(), targets()))), + ); + + it.effect("saves a role for a thread that can hold it", () => + Effect.gen(function* () { + const saved = yield* loadThenSave( + {}, + { threadRoles: { orchestrators: { "project-1": "thread-top" } } }, + ); + assert.deepStrictEqual(saved.threadRoles, { + assistant: null, + orchestrators: { "project-1": "thread-top" }, + }); + // Saved sparse, as every setting is: the assistant at its default is left out. + assert.deepStrictEqual((yield* readFile).threadRoles, { + orchestrators: { "project-1": "thread-top" }, + }); + }).pipe(Effect.provide(Layer.merge(layerServerSettings(), targets()))), + ); + + it.effect("refuses a role for a sub-agent, and writes nothing", () => + Effect.gen(function* () { + const error = yield* loadThenSave( + { enableAgentBrowserAccess: false }, + { threadRoles: { assistant: "thread-subagent" }, enableAgentBrowserAccess: true }, + ).pipe(Effect.flip); + assert.instanceOf(error, ServerSettingsError); + assert.strictEqual(error.operation, "normalize"); + assert.instanceOf(error.cause, ForkSettingsWriteError); + assert.match((error.cause as Error).message, /sub-agent or side chat/u); + assert.deepStrictEqual(yield* readFile, { enableAgentBrowserAccess: false }); + }).pipe(Effect.provide(Layer.merge(layerServerSettings(), targets()))), + ); + + it.effect("refuses a new role where the server cannot read threads", () => + Effect.gen(function* () { + const error = yield* loadThenSave({}, { threadRoles: { assistant: "thread-top" } }).pipe( + Effect.flip, + ); + assert.instanceOf(error.cause, ForkSettingsWriteError); + assert.match((error.cause as Error).message, /cannot be checked here/u); + }).pipe(Effect.provide(layerServerSettings())), + ); + }, +); diff --git a/apps/server/src/fork/threadRoleTargets.ts b/apps/server/src/fork/threadRoleTargets.ts new file mode 100644 index 0000000000000..e248f3461f733 --- /dev/null +++ b/apps/server/src/fork/threadRoleTargets.ts @@ -0,0 +1,101 @@ +/** + * Fork (calm sidebar): the `threadRoles` save check. Only pointers a save sets anew are checked. + * Threads come from {@link ThreadRoleTargets} (threadRoleTargetsLayer.ts); this file imports no + * orchestration code. Without that service a new pointer is refused: fail closed. + */ +import type { ServerSettings, ThreadId, ThreadRoles } from "@t3tools/contracts"; +import { Context, Effect, Option } from "effect"; + +/** What the check needs to know about a thread. */ +export interface ThreadRoleTarget { + readonly projectId: string; + /** False for a sub-agent or side chat (upstream's `isListedThreadLineage`). */ + readonly listed: boolean; + /** True for a task a linked machine delegated here. */ + readonly delegated: boolean; +} + +export interface ThreadRoleTargetsShape { + /** The thread, or `null` when it does not exist or is deleted. Fails when it cannot be read. */ + readonly find: (threadId: ThreadId) => Effect.Effect; +} + +export class ThreadRoleTargets extends Context.Service()( + "t3/fork/threadRoleTargets", +) {} + +/** A role pointer a save sets anew. */ +export type NewThreadRolePointer = + | { readonly role: "assistant"; readonly threadId: ThreadId } + | { readonly role: "orchestrator"; readonly projectId: string; readonly threadId: ThreadId }; + +/** The pointers `next` sets that `current` did not hold (a removal sets none). */ +export function newThreadRolePointers( + current: ThreadRoles, + next: ThreadRoles, +): ReadonlyArray { + const pointers: Array = []; + if (next.assistant !== null && next.assistant !== current.assistant) { + pointers.push({ role: "assistant", threadId: next.assistant }); + } + for (const [projectId, threadId] of Object.entries(next.orchestrators)) { + const before = Object.hasOwn(current.orchestrators, projectId) + ? current.orchestrators[projectId as keyof ThreadRoles["orchestrators"]] + : undefined; + if (threadId !== before) pointers.push({ role: "orchestrator", projectId, threadId }); + } + return pointers; +} + +const describe = (pointer: NewThreadRolePointer): string => + pointer.role === "assistant" + ? "threadRoles.assistant" + : `threadRoles.orchestrators["${pointer.projectId}"]`; + +/** Why `target` cannot hold the role `pointer` gives it, or `undefined`. */ +function threadRolePointerProblem( + pointer: NewThreadRolePointer, + target: ThreadRoleTarget | null, +): string | undefined { + const where = describe(pointer); + if (target === null) { + return `${where} names thread ${pointer.threadId}, which does not exist or is deleted: pick a thread that exists.`; + } + if (!target.listed) { + return `${where} names thread ${pointer.threadId}, which is a sub-agent or side chat: only a top-level thread can hold a role.`; + } + if (target.delegated) { + return `${where} names thread ${pointer.threadId}, which is a task delegated from a linked machine: only a top-level thread can hold a role.`; + } + if (pointer.role === "orchestrator" && target.projectId !== pointer.projectId) { + return `${where} names thread ${pointer.threadId}, which belongs to project ${target.projectId}: a project's orchestrator must be one of its own threads.`; + } + return undefined; +} + +/** + * Why this save of `threadRoles` must be refused, or `undefined`. Reads only the threads the save + * points at anew; a save that sets no new pointer reads nothing. + */ +export function threadRolesSaveProblem( + current: Pick, + next: Pick, +): Effect.Effect { + const pointers = newThreadRolePointers(current.threadRoles, next.threadRoles); + if (pointers.length === 0) return Effect.undefined; + return Effect.gen(function* () { + const targets = yield* Effect.serviceOption(ThreadRoleTargets); + if (Option.isNone(targets)) { + return `${describe(pointers[0]!)} cannot be checked here (this server path cannot read threads): set roles from the app's settings.`; + } + for (const pointer of pointers) { + const target = yield* targets.value.find(pointer.threadId).pipe(Effect.option); + if (Option.isNone(target)) { + return `${describe(pointer)}: thread ${pointer.threadId} could not be read, so the role was not saved: try again.`; + } + const problem = threadRolePointerProblem(pointer, target.value); + if (problem !== undefined) return problem; + } + return undefined; + }); +} diff --git a/apps/server/src/fork/threadRoleTargetsLayer.ts b/apps/server/src/fork/threadRoleTargetsLayer.ts new file mode 100644 index 0000000000000..45a41ce2ac410 --- /dev/null +++ b/apps/server/src/fork/threadRoleTargetsLayer.ts @@ -0,0 +1,28 @@ +/** + * Fork (calm sidebar): {@link ThreadRoleTargets} read from upstream's orchestrator, for the + * `threadRoles` save check (threadRoleTargets.ts). Kept apart from that file so the settings file + * never imports orchestration code. Wired in forkLayers.ts (`layerRuntimeServices`). + */ +import { isListedThreadLineage, type ThreadId } from "@t3tools/contracts"; +import { Effect, Layer } from "effect"; + +import * as Orchestrator from "../orchestration-v2/Orchestrator.ts"; +import { ThreadRoleTargets } from "./threadRoleTargets.ts"; + +export const layer = Layer.effect( + ThreadRoleTargets, + Effect.map(Orchestrator.OrchestratorV2, (orchestrator) => + ThreadRoleTargets.of({ + find: Effect.fn("ThreadRoleTargets.find")(function* (threadId: ThreadId) { + const shell = yield* orchestrator.getThreadShell(threadId); + return shell === null + ? null + : { + projectId: shell.projectId, + listed: isListedThreadLineage(shell.lineage), + delegated: shell.delegatedFrom !== undefined, + }; + }), + }), + ), +); diff --git a/apps/server/src/policy/forkManagedSettings.ts b/apps/server/src/policy/forkManagedSettings.ts index 01873ac8215e1..fd2202bcd2904 100644 --- a/apps/server/src/policy/forkManagedSettings.ts +++ b/apps/server/src/policy/forkManagedSettings.ts @@ -17,6 +17,7 @@ const WHOLE_ONLY = [ "placementNeeds", "playtest", "reviewRules", + "threadRoles", ] as const satisfies ReadonlyArray; export const FORK_WHOLE_MANAGED_SETTINGS: ReadonlySet = new Set(WHOLE_ONLY); diff --git a/docs/fork/README.md b/docs/fork/README.md index 8351c0fe1dd8e..a669db6465962 100644 --- a/docs/fork/README.md +++ b/docs/fork/README.md @@ -43,36 +43,38 @@ The defaults, "off" and "decided in" below come from one table in the code, (`packages/shared/src/forkDocs.test.ts`) fails when this table and that one differ, or a setting has no section below. "Off" means the default leaves the machine as upstream's would be. -| Setting | Default | Off | Decided in | -| ---------------------------------------------------------------------------- | --------------------------- | --- | -------------------------------------------------------- | -| [`server.automaticUpdates`](#serverautomaticupdates) | `false` | yes | [#41](https://github.com/scuttletoby/t3code/issues/41) | -| [`server.automaticUpdatesQuietCommand`](#serverautomaticupdatesquietcommand) | `""` | yes | [#5](https://github.com/scuttletoby/t3code/issues/5) | -| [`server.activityProbe`](#serveractivityprobe) | `false` | yes | [#509](https://github.com/scuttletoby/t3code/issues/509) | -| [`server.usagePacing`](#serverusagepacing) | `{}` | yes | [#52](https://github.com/scuttletoby/t3code/issues/52) | -| [`server.usagePacingGate`](#serverusagepacinggate) | `"off"` | yes | [#73](https://github.com/scuttletoby/t3code/issues/73) | -| [`server.usagePacingLowerEffort`](#serverusagepacinglowereffort) | `{}` | yes | [#73](https://github.com/scuttletoby/t3code/issues/73) | -| [`server.waitFor`](#serverwaitfor) | `{"enabled":false}` | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | -| [`server.waitChecks`](#serverwaitchecks) | `{}` | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | -| [`server.playtest`](#serverplaytest) | `{"enabled":false}` | yes | [#260](https://github.com/scuttletoby/t3code/issues/260) | -| [`server.reviewRules`](#serverreviewrules) | `{"preset":"off"}` | yes | [#291](https://github.com/scuttletoby/t3code/issues/291) | -| [`server.modelPolicy`](#servermodelpolicy) | `{"mode":"off","allow":[]}` | yes | [#268](https://github.com/scuttletoby/t3code/issues/268) | -| [`server.placement`](#serverplacement) | `{"mode":"off"}` | yes | [#134](https://github.com/scuttletoby/t3code/issues/134) | -| [`server.placementNeeds`](#serverplacementneeds) | `[]` | yes | [#134](https://github.com/scuttletoby/t3code/issues/134) | -| [`server.agentSlots`](#serveragentslots) | `{"enabled":false}` | no | [#84](https://github.com/scuttletoby/t3code/issues/84) | -| [`server.headlessUsageRefreshInterval`](#serverheadlessusagerefreshinterval) | `600000` | no | [#42](https://github.com/scuttletoby/t3code/issues/42) | -| [`server.mcpProfiles`](#servermcpprofiles) | `{}` | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | -| [`server.mcpProfile`](#servermcpprofile) | `"all"` | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | -| [`server.mcpSubagentProfile`](#servermcpsubagentprofile) | `"inherit"` | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | -| [`server.mcpThreadProfiles`](#servermcpthreadprofiles) | `{}` | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | -| [`server.mcpCarriedProfiles`](#servermcpcarriedprofiles) | `"apply"` | yes | [#640](https://github.com/scuttletoby/t3code/issues/640) | -| [`server.handoff`](#serverhandoff) | `{"mode":"off"}` | yes | [#215](https://github.com/scuttletoby/t3code/issues/215) | -| [`projectOverride.waitChecks`](#projectoverridewaitchecks) | not set | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | -| [`projectOverride.playtest`](#projectoverrideplaytest) | not set | yes | [#260](https://github.com/scuttletoby/t3code/issues/260) | -| [`projectOverride.reviewRules`](#projectoverridereviewrules) | not set | yes | [#291](https://github.com/scuttletoby/t3code/issues/291) | -| [`projectOverride.mcpProfile`](#projectoverridemcpprofile) | not set | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | -| [`projectOverride.mcpSubagentProfile`](#projectoverridemcpsubagentprofile) | not set | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | -| [`projectOverride.handoff`](#projectoverridehandoff) | not set | yes | [#215](https://github.com/scuttletoby/t3code/issues/215) | -| [`projectOverride.placementNeeds`](#projectoverrideplacementneeds) | not set | yes | [#134](https://github.com/scuttletoby/t3code/issues/134) | +| Setting | Default | Off | Decided in | +| ---------------------------------------------------------------------------- | --------------------------------------- | --- | -------------------------------------------------------- | +| [`server.automaticUpdates`](#serverautomaticupdates) | `false` | yes | [#41](https://github.com/scuttletoby/t3code/issues/41) | +| [`server.automaticUpdatesQuietCommand`](#serverautomaticupdatesquietcommand) | `""` | yes | [#5](https://github.com/scuttletoby/t3code/issues/5) | +| [`server.activityProbe`](#serveractivityprobe) | `false` | yes | [#509](https://github.com/scuttletoby/t3code/issues/509) | +| [`server.usagePacing`](#serverusagepacing) | `{}` | yes | [#52](https://github.com/scuttletoby/t3code/issues/52) | +| [`server.usagePacingGate`](#serverusagepacinggate) | `"off"` | yes | [#73](https://github.com/scuttletoby/t3code/issues/73) | +| [`server.usagePacingLowerEffort`](#serverusagepacinglowereffort) | `{}` | yes | [#73](https://github.com/scuttletoby/t3code/issues/73) | +| [`server.waitFor`](#serverwaitfor) | `{"enabled":false}` | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | +| [`server.waitChecks`](#serverwaitchecks) | `{}` | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | +| [`server.playtest`](#serverplaytest) | `{"enabled":false}` | yes | [#260](https://github.com/scuttletoby/t3code/issues/260) | +| [`server.reviewRules`](#serverreviewrules) | `{"preset":"off"}` | yes | [#291](https://github.com/scuttletoby/t3code/issues/291) | +| [`server.modelPolicy`](#servermodelpolicy) | `{"mode":"off","allow":[]}` | yes | [#268](https://github.com/scuttletoby/t3code/issues/268) | +| [`server.placement`](#serverplacement) | `{"mode":"off"}` | yes | [#134](https://github.com/scuttletoby/t3code/issues/134) | +| [`server.placementNeeds`](#serverplacementneeds) | `[]` | yes | [#134](https://github.com/scuttletoby/t3code/issues/134) | +| [`server.agentSlots`](#serveragentslots) | `{"enabled":false}` | no | [#84](https://github.com/scuttletoby/t3code/issues/84) | +| [`server.headlessUsageRefreshInterval`](#serverheadlessusagerefreshinterval) | `600000` | no | [#42](https://github.com/scuttletoby/t3code/issues/42) | +| [`server.mcpProfiles`](#servermcpprofiles) | `{}` | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | +| [`server.mcpProfile`](#servermcpprofile) | `"all"` | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | +| [`server.mcpSubagentProfile`](#servermcpsubagentprofile) | `"inherit"` | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | +| [`server.mcpThreadProfiles`](#servermcpthreadprofiles) | `{}` | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | +| [`server.mcpCarriedProfiles`](#servermcpcarriedprofiles) | `"apply"` | yes | [#640](https://github.com/scuttletoby/t3code/issues/640) | +| [`server.handoff`](#serverhandoff) | `{"mode":"off"}` | yes | [#215](https://github.com/scuttletoby/t3code/issues/215) | +| [`server.threadRoles`](#serverthreadroles) | `{"assistant":null,"orchestrators":{}}` | yes | [#138](https://github.com/scuttletoby/t3code/issues/138) | +| [`projectOverride.waitChecks`](#projectoverridewaitchecks) | not set | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | +| [`projectOverride.playtest`](#projectoverrideplaytest) | not set | yes | [#260](https://github.com/scuttletoby/t3code/issues/260) | +| [`projectOverride.reviewRules`](#projectoverridereviewrules) | not set | yes | [#291](https://github.com/scuttletoby/t3code/issues/291) | +| [`projectOverride.mcpProfile`](#projectoverridemcpprofile) | not set | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | +| [`projectOverride.mcpSubagentProfile`](#projectoverridemcpsubagentprofile) | not set | yes | [#145](https://github.com/scuttletoby/t3code/issues/145) | +| [`projectOverride.handoff`](#projectoverridehandoff) | not set | yes | [#215](https://github.com/scuttletoby/t3code/issues/215) | +| [`projectOverride.placementNeeds`](#projectoverrideplacementneeds) | not set | yes | [#134](https://github.com/scuttletoby/t3code/issues/134) | +| [`client.calmSidebarEnabled`](#clientcalmsidebarenabled) | `false` | yes | [#139](https://github.com/scuttletoby/t3code/issues/139) | For `waitFor`, `agentSlots` and `playtest` only the `enabled` switch is pinned, and for `handoff` and `placement` only `mode`; their other fields are tuning that does nothing while the switch is off. @@ -1123,6 +1125,35 @@ there keeps it as stored. { "handoff": { "mode": "handoff", "threads": { "": "compact" } } } ``` +### `server.threadRoles` + +Which threads hold a role, for the calm sidebar: the `assistant` thread (or `null`), and in +`orchestrators` one thread per project (project id to thread id). A role is a pointer in the +settings, not a tag on the thread, so a project has at most one orchestrator and the roles are a +setting the person changes ([#138](https://github.com/scuttletoby/t3code/issues/138)). The default, +no roles, changes nothing. This setting alone shows nothing: the calm sidebar +(`client.calmSidebarEnabled`) reads it. + +Only the person can change it; agents cannot (the settings tool refuses it as person-only). A save +that sets a 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) and, for an +orchestrator, belongs to the project its entry names. Where the server cannot read threads, such a +save is refused too, never let through. A pointer the save leaves as it was is not checked again, +so an old pointer to a thread deleted since blocks no other save; whoever reads the roles checks the +thread and treats a failing one as no role. + +A save changes the roles field by field: a left-out field keeps its value, `assistant: null` +removes the assistant, and each `orchestrators` entry is set or (`null`) removed on its own, so two +saves for different projects keep both. A save with a bad id is refused. The file is read leniently: +a missing or non-object value reads as no roles, a bad `assistant` as none, and a bad orchestrator +entry drops alone, so a hand edit never resets the other settings. + +```json +{ + "threadRoles": { "assistant": "", "orchestrators": { "": "" } } +} +``` + ### `projectOverride.waitChecks` A project's own list of wait checks. It replaces the server's list for that project as a whole (a @@ -1191,6 +1222,14 @@ server's needs, never none), and its text is kept. A project save that leaves th client) keeps the stored value, and one that sends back the kept text unchanged keeps it too (other text is refused); only `null` clears it, as for `playtest`. +### `client.calmSidebarEnabled` + +Turns on the calm sidebar on this device: the threads in `server.threadRoles` go to the top, and the +other top-level threads fold into one closed group with a count of those waiting for you +([#139](https://github.com/scuttletoby/t3code/issues/139)). Off (the default): upstream's sidebar. +It is a client setting, so each device chooses: calm on a phone, the full list on a desktop. A +client settings file without it reads as off. + ### A setting the fork removed An early draft had a client setting for one "anchor machine" for new work. It was removed before it diff --git a/packages/contracts/src/forkDefaults.ts b/packages/contracts/src/forkDefaults.ts index 761d2f87d7875..75915a307c719 100644 --- a/packages/contracts/src/forkDefaults.ts +++ b/packages/contracts/src/forkDefaults.ts @@ -212,6 +212,14 @@ export const FORK_SETTING_DEFAULTS: ReadonlyArray = [ "A task a linked machine delegates here is cut down to the profile it carries, which with no profiles set anywhere is `all`: nothing changes.", decidedIn: "#640", }, + { + scope: "server", + key: "threadRoles", + default: { assistant: null, orchestrators: {} }, + off: true, + reason: "No thread holds a role, so every thread is shown as upstream shows it.", + decidedIn: "#138", + }, { scope: "projectOverride", key: "mcpProfile", @@ -268,6 +276,14 @@ export const FORK_SETTING_DEFAULTS: ReadonlyArray = [ reason: "A project without its own needs uses the server's.", decidedIn: "#134", }, + { + scope: "client", + key: "calmSidebarEnabled", + default: false, + off: true, + reason: "Each device shows upstream's thread list until its owner turns the calm view on.", + decidedIn: "#139", + }, ]; const FIELDS: Readonly>>> = { diff --git a/packages/contracts/src/forkSettings.ts b/packages/contracts/src/forkSettings.ts index c64e08aa9904c..ee1d4b6338ca5 100644 --- a/packages/contracts/src/forkSettings.ts +++ b/packages/contracts/src/forkSettings.ts @@ -42,6 +42,7 @@ import { ReviewRulesPatch, ReviewRulesProjectPatch, } from "./reviewRules.ts"; +import { ThreadRolesFromSettingsFile, ThreadRolesPatch } from "./threadRoles.ts"; import { DEFAULT_USAGE_PACING_INSTANCE_SETTINGS, UsagePacingGateMode, @@ -66,6 +67,7 @@ export * from "./modelPolicy.ts"; export * from "./placement.ts"; export * from "./playtest.ts"; export * from "./reviewRules.ts"; +export * from "./threadRoles.ts"; export * from "./usagePacing.ts"; /** How often usage limits refresh while no client watches; 0 turns it off. */ @@ -134,6 +136,8 @@ export const ForkServerSettingsFields = { placementNeeds: PlacementNeedsFromSettingsFile.pipe( Schema.withDecodingDefault(Effect.succeed([])), ), + /** Which thread is the assistant and each project's orchestrator; none. A bad entry drops alone. */ + threadRoles: ThreadRolesFromSettingsFile, }; /** A key of {@link ForkServerSettingsFields}. */ @@ -177,19 +181,21 @@ export const ForkServerSettingsPatchFields = { placement: Schema.optionalKey(PlacementSettingsPatch), /** Strict: a save refuses a bad label; it replaces a kept bad value. */ placementNeeds: Schema.optionalKey(PlacementNeedsPatch), + /** Strict ids; the server also refuses a pointer to a thread that cannot hold the role. */ + threadRoles: Schema.optionalKey(ThreadRolesPatch), } satisfies Record; /** - * How a patch field changes the stored value: `replace` whole; `merge-fields` only the named fields. - * Per entry (`null` removes it): `mergeEntries` merges fields, a new entry starting from its - * defaults; `replaceEntries` replaces the entry whole and makes it newest. A save that would leave - * more than `maxEntries` (and more than before) is refused; no entry is dropped to make room. + * `replace` whole; `merge-fields` the named fields; `fields` each named field by its own rule. Per + * entry (`null` removes): `mergeEntries` merges, starting from defaults; `replaceEntries` replaces + * whole, newest last. A save leaving more than `maxEntries` (and more than before) is refused. */ export type ForkPatchRule = | "replace" | "merge-fields" | { readonly mergeEntries: Readonly> } - | { readonly replaceEntries: { readonly maxEntries?: number } }; + | { readonly replaceEntries: { readonly maxEntries?: number } } + | { readonly fields: Readonly> }; /** One rule per fork patch field. */ export const FORK_PATCH_RULES: { readonly [K in ForkServerSettingKey]: ForkPatchRule } = { @@ -225,10 +231,20 @@ export const FORK_PATCH_RULES: { readonly [K in ForkServerSettingKey]: ForkPatch // taken (it replaces the text); the save check refuses a partial one (forkSettingsPatch.ts). placement: "merge-fields", placementNeeds: "replace", + // One orchestrator per project entry, so two people setting different projects keep both; two + // saves of the same project, the last one wins. + threadRoles: { fields: { assistant: "replace", orchestrators: { replaceEntries: {} } } }, }; -/** The client settings' fork fields (stored in the browser); none yet. */ -export const ForkClientSettingsFields = {}; +/** + * The client settings' fork fields (stored on each device, not on the server). Their patch fields + * (`ForkClientSettingsPatchFields`, spread into upstream's `ClientSettingsPatch`; the line is + * announced in .github/fork-seams.json) come with the first change that saves one. + */ +export const ForkClientSettingsFields = { + /** Calm sidebar: role threads on top, every other thread folded into one group; off. */ + calmSidebarEnabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))), +}; /** Fork settings a project may override; listed in `PROJECT_SCOPED_SERVER_SETTING_KEYS`. */ export const FORK_PROJECT_SCOPED_KEYS = [ diff --git a/packages/contracts/src/threadRoles.test.ts b/packages/contracts/src/threadRoles.test.ts new file mode 100644 index 0000000000000..fa5d0ff3fe571 --- /dev/null +++ b/packages/contracts/src/threadRoles.test.ts @@ -0,0 +1,126 @@ +// Fork (calm sidebar): `threadRoles` and `calmSidebarEnabled` as the settings files hold them. An old +// file reads as no roles and the calm view off; a bad entry drops alone; a save's patch is strict. +import * as Schema from "effect/Schema"; +import { describe, expect, it } from "vite-plus/test"; + +import { FORK_AGENT_WRITABLE_KEYS, FORK_PERSON_ONLY_KEYS } from "./forkSettings.ts"; +import { ClientSettingsSchema, ServerSettings, ServerSettingsPatch } from "./settings.ts"; +import { EMPTY_THREAD_ROLES, ThreadRolesFromSettingsFile } from "./threadRoles.ts"; + +const decodeServer = Schema.decodeUnknownSync(ServerSettings); +const encodeServer = Schema.encodeSync(ServerSettings); +const decodeClient = Schema.decodeUnknownSync(ClientSettingsSchema); +const decodePatch = Schema.decodeUnknownSync(ServerSettingsPatch); +const decodeRoles = Schema.decodeUnknownSync(ThreadRolesFromSettingsFile); + +describe("threadRoles in the server's settings file", () => { + it("reads an old file without the key as no roles", () => { + expect(decodeServer({}).threadRoles).toEqual(EMPTY_THREAD_ROLES); + expect(decodeServer({ enableAgentBrowserAccess: false }).threadRoles).toEqual({ + assistant: null, + orchestrators: {}, + }); + }); + + it("reads a good value as written, and writes it back the same", () => { + const roles = { assistant: "thread-a", orchestrators: { "project-1": "thread-o" } }; + const settings = decodeServer({ threadRoles: roles }); + expect(settings.threadRoles).toEqual(roles); + expect(encodeServer(settings).threadRoles).toEqual(roles); + }); + + it("drops a bad entry alone and keeps the rest of the file", () => { + const settings = decodeServer({ + enableAgentBrowserAccess: false, + threadRoles: { + assistant: "thread-a", + orchestrators: { + "project-1": "thread-o", + "project-2": 42, + "project-3": "", + "project-4": " padded ", + "": "thread-x", + "project-5": null, + }, + }, + }); + expect(settings.enableAgentBrowserAccess).toBe(false); + expect(settings.threadRoles).toEqual({ + assistant: "thread-a", + orchestrators: { "project-1": "thread-o" }, + }); + }); + + it("reads a bad assistant as none and keeps the orchestrators", () => { + for (const assistant of [7, "", " ", { id: "thread-a" }, ["thread-a"]]) { + expect(decodeRoles({ assistant, orchestrators: { "project-1": "thread-o" } })).toEqual({ + assistant: null, + orchestrators: { "project-1": "thread-o" }, + }); + } + }); + + it("reads a value that is not an object, or a bad orchestrators map, as no roles there", () => { + for (const raw of [null, "thread-a", 3, [], true]) { + expect(decodeRoles(raw)).toEqual(EMPTY_THREAD_ROLES); + } + expect(decodeRoles({ assistant: "thread-a", orchestrators: ["thread-o"] })).toEqual({ + assistant: "thread-a", + orchestrators: {}, + }); + }); +}); + +describe("threadRoles in a save's patch", () => { + it("takes a field at a time, and null removes", () => { + expect(decodePatch({ threadRoles: { assistant: null } }).threadRoles).toEqual({ + assistant: null, + }); + expect( + decodePatch({ + threadRoles: { orchestrators: { "project-1": "thread-o", "project-2": null } }, + }).threadRoles, + ).toEqual({ orchestrators: { "project-1": "thread-o", "project-2": null } }); + }); + + it("refuses a bad id instead of dropping it", () => { + for (const threadRoles of [ + { assistant: "" }, + { assistant: 7 }, + { orchestrators: { "project-1": "" } }, + { orchestrators: { "project-1": 7 } }, + { orchestrators: { "": "thread-o" } }, + "thread-a", + ]) { + expect(() => decodePatch({ threadRoles })).toThrow(); + } + }); + + it("is person-only: agents cannot change it with the settings tool", () => { + expect(FORK_PERSON_ONLY_KEYS).toContain("threadRoles"); + expect(FORK_AGENT_WRITABLE_KEYS).not.toContain("threadRoles"); + }); +}); + +describe("calmSidebarEnabled in a client's settings", () => { + it("is off in an old file and reads as written", () => { + expect(decodeClient({}).calmSidebarEnabled).toBe(false); + expect(decodeClient({ calmSidebarEnabled: true }).calmSidebarEnabled).toBe(true); + }); +}); + +describe("threadRoles as the settings writer saves it", () => { + it("writes a value sparse, with a field at its default left out", () => { + // The writer strips defaults before it encodes; each field alone must still encode and read back. + const encodeRoles = Schema.encodeUnknownSync(ThreadRolesFromSettingsFile); + for (const sparse of [ + { orchestrators: { "project-1": "thread-o" } }, + { assistant: "thread-a" }, + {}, + ]) { + const encoded = encodeRoles(sparse); + expect(encoded).toEqual(sparse); + expect(decodeRoles(encoded)).toEqual({ ...EMPTY_THREAD_ROLES, ...sparse }); + } + }); +}); diff --git a/packages/contracts/src/threadRoles.ts b/packages/contracts/src/threadRoles.ts new file mode 100644 index 0000000000000..5652f21c75acd --- /dev/null +++ b/packages/contracts/src/threadRoles.ts @@ -0,0 +1,77 @@ +/** + * Fork (calm sidebar): which thread holds a role, as a person-only settings pointer (one orchestrator + * per project). A pointer can outlive its thread: readers check the thread and treat a failing one + * as "no role". Docs: docs/fork/README.md, `server.threadRoles`. + */ +import * as Effect from "effect/Effect"; +import * as Schema from "effect/Schema"; +import * as SchemaTransformation from "effect/SchemaTransformation"; + +import { ProjectId, ThreadId } from "./baseSchemas.ts"; + +/** + * The role pointers: the assistant thread, and one orchestrator thread per project. Each field has + * its default, since the settings writer saves the value sparse (a field at its default left out). + */ +export const ThreadRoles = Schema.Struct({ + assistant: Schema.NullOr(ThreadId).pipe(Schema.withDecodingDefault(Effect.succeed(null))), + orchestrators: Schema.Record(ProjectId, ThreadId).pipe( + Schema.withDecodingDefault(Effect.succeed({})), + ), +}); +export type ThreadRoles = typeof ThreadRoles.Type; + +/** No roles: upstream's behaviour, and what an old settings file reads as. */ +export const EMPTY_THREAD_ROLES: ThreadRoles = { assistant: null, orchestrators: {} }; + +const isRecord = (value: unknown): value is Readonly> => + typeof value === "object" && value !== null && !Array.isArray(value); + +/** A text a thread or project id may be: non-blank, without outer spaces. */ +const isIdText = (value: unknown): value is string => + typeof value === "string" && value.length > 0 && value.trim() === value; + +/** + * The settings file's `threadRoles`, read leniently like `hiddenThreadTags`: a bad entry drops + * alone, so a hand edit never resets the other settings. Not an object (or missing): no roles. A bad + * `assistant` reads as none; an orchestrator entry whose key or value is not an id is dropped. + */ +function readThreadRoles(raw: unknown): { + readonly assistant: string | null; + readonly orchestrators: { readonly [projectId: string]: string }; +} { + if (!isRecord(raw)) return { assistant: null, orchestrators: {} }; + const orchestrators = isRecord(raw.orchestrators) ? raw.orchestrators : {}; + return { + assistant: isIdText(raw.assistant) ? raw.assistant : null, + orchestrators: Object.fromEntries( + Object.entries(orchestrators).filter( + (entry): entry is [string, string] => isIdText(entry[0]) && isIdText(entry[1]), + ), + ), + }; +} + +/** {@link ThreadRoles} as the settings file holds it: read by {@link readThreadRoles}. */ +export const ThreadRolesFromSettingsFile = Schema.Unknown.pipe( + Schema.decodeTo( + ThreadRoles, + SchemaTransformation.transform({ + decode: (raw: unknown): typeof ThreadRoles.Encoded => readThreadRoles(raw), + encode: (roles: typeof ThreadRoles.Encoded): unknown => roles, + }), + ), + Schema.withDecodingDefault(Effect.succeed(EMPTY_THREAD_ROLES)), +); + +/** + * A save's change to the roles. A field left out keeps its value. `assistant: null` removes the + * assistant; an orchestrator entry is set or (`null`) removed on its own, so two people changing + * different projects at once keep both. Strict: a bad id is refused. The server also refuses a + * pointer to a thread that cannot hold the role (fork/threadRoleTargets.ts). + */ +export const ThreadRolesPatch = Schema.Struct({ + assistant: Schema.optionalKey(Schema.NullOr(ThreadId)), + orchestrators: Schema.optionalKey(Schema.Record(ProjectId, Schema.NullOr(ThreadId))), +}); +export type ThreadRolesPatch = typeof ThreadRolesPatch.Type; diff --git a/packages/shared/src/forkSettingsPatch.ts b/packages/shared/src/forkSettingsPatch.ts index c1c5726632113..03394c6a56661 100644 --- a/packages/shared/src/forkSettingsPatch.ts +++ b/packages/shared/src/forkSettingsPatch.ts @@ -104,6 +104,15 @@ function applyRule(rule: ForkPatchRule, stored: unknown, patch: unknown): unknow } return next; } + if ("fields" in rule) { + // Each named field by its own rule; a field the patch leaves out keeps its value. + const next: Record = isRecord(stored) ? { ...stored } : {}; + for (const [field, value] of Object.entries(isRecord(patch) ? patch : {})) { + if (value === undefined) continue; + next[field] = applyRule(rule.fields[field] ?? "replace", next[field], value); + } + return next; + } const next = new Map(Object.entries(isRecord(stored) ? stored : {})); if ("replaceEntries" in rule) { for (const [id, entry] of Object.entries(patch as Record)) { diff --git a/packages/shared/src/forkSettingsThreadRoles.test.ts b/packages/shared/src/forkSettingsThreadRoles.test.ts new file mode 100644 index 0000000000000..a5bde5acbe125 --- /dev/null +++ b/packages/shared/src/forkSettingsThreadRoles.test.ts @@ -0,0 +1,69 @@ +/// + +// Fork (calm sidebar): a save's `threadRoles` patch changes the roles field by field, and each +// project's orchestrator entry on its own, so two saves for different projects keep both. +import { + DEFAULT_SERVER_SETTINGS, + ServerSettingsPatch, + type ServerSettings, +} from "@t3tools/contracts"; +import * as Schema from "effect/Schema"; +import { describe, expect, it } from "vite-plus/test"; + +import { applyServerSettingsPatch } from "./serverSettings.ts"; + +const decodePatch = Schema.decodeUnknownSync(ServerSettingsPatch); +const save = (current: ServerSettings, json: unknown): ServerSettings => + applyServerSettingsPatch(current, decodePatch(json)); + +const withRoles = (threadRoles: unknown): ServerSettings => + save(DEFAULT_SERVER_SETTINGS, { threadRoles }); + +describe("threadRoles patch", () => { + const start = withRoles({ + assistant: "thread-a", + orchestrators: { "project-1": "thread-1", "project-2": "thread-2" }, + }); + + it("starts from no roles", () => { + expect(DEFAULT_SERVER_SETTINGS.threadRoles).toEqual({ assistant: null, orchestrators: {} }); + expect(start.threadRoles).toEqual({ + assistant: "thread-a", + orchestrators: { "project-1": "thread-1", "project-2": "thread-2" }, + }); + }); + + it("keeps both of two saves for different projects", () => { + const first = save(start, { threadRoles: { orchestrators: { "project-3": "thread-3" } } }); + // The second save was made from the same start; it names only its own project. + const second = save(first, { threadRoles: { orchestrators: { "project-1": "thread-9" } } }); + expect(second.threadRoles).toEqual({ + assistant: "thread-a", + orchestrators: { "project-1": "thread-9", "project-2": "thread-2", "project-3": "thread-3" }, + }); + }); + + it("removes one entry with null and leaves the others", () => { + const next = save(start, { threadRoles: { orchestrators: { "project-2": null } } }); + expect(next.threadRoles).toEqual({ + assistant: "thread-a", + orchestrators: { "project-1": "thread-1" }, + }); + }); + + it("replaces or removes the assistant without touching the orchestrators", () => { + expect(save(start, { threadRoles: { assistant: "thread-b" } }).threadRoles).toEqual({ + ...start.threadRoles, + assistant: "thread-b", + }); + expect(save(start, { threadRoles: { assistant: null } }).threadRoles).toEqual({ + ...start.threadRoles, + assistant: null, + }); + }); + + it("changes nothing when the patch leaves it out, or sends it empty", () => { + expect(save(start, { enableAgentBrowserAccess: false }).threadRoles).toEqual(start.threadRoles); + expect(save(start, { threadRoles: {} }).threadRoles).toEqual(start.threadRoles); + }); +}); From da45995f04c1d0de318dd17fa6c004ff963a1f7a Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 10:00:42 +0000 Subject: [PATCH 2/3] Link the calm sidebar line in FORK_CHANGES to its pull request Co-Authored-By: Claude Opus 5.5 --- FORK_CHANGES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FORK_CHANGES.md b/FORK_CHANGES.md index 4c03658cf69f9..9c9fc3317b840 100644 --- a/FORK_CHANGES.md +++ b/FORK_CHANGES.md @@ -48,7 +48,7 @@ setting is missing here or a setting named here does not exist. | Run records: one line per agent run that ends (model, effort, role, kind, estimate, times, end status, provider-reported tokens) in `/run-records/runs.jsonl`, append-only, and a weekly summary command. | Later choices of model, effort and task size need what earlier runs cost and took. | none | always (writes only its own files) | [#588](https://github.com/scuttletoby/t3code/pull/588) | | Model policy: the setting for which models (and efforts) agents may pick, per provider driver: off, advise or enforce, and the allowed rows. The server checks an agent's pick (`delegate_task`, `create_threads`, `t3_thread_launch`, `t3_thread_configure`, here, and both before and after it goes to linked machines): a model in no row, a call that names no model, or an effort off its row is refused in enforce, only noted in advise. A person's own pick is never refused; Settings marks one outside the rows. A bad hand edit, or a settings file that does not parse, refuses every agent pick (a warning if the value says advise). Settings offers the fork's start rows (Opus 5.5 and Fable 5.2) while none are saved. While it is on, a child whose call names its model keeps only the options it names. | Agents should use the models the person chose for each kind of work. | `server.modelPolicy` | off | [#268](https://github.com/scuttletoby/t3code/pull/268), [#731](https://github.com/scuttletoby/t3code/issues/731) | | Placement, part 1: the settings only. `placement` (off, advise or enforce; this machine's labels, an optional facts command, label groups that must never meet on one machine, and a weight per linked machine) and `placementNeeds` (labels a project's work needs). Person-only; a bad `placement` reads as off and a bad `placementNeeds` fits no machine, each kept as written. Nothing reads them yet. | Delegated work should go to a machine that has what it needs, and never where it must not run. | `server.placement`, `server.placementNeeds`, `projectOverride.placementNeeds` | off | [#134](https://github.com/scuttletoby/t3code/issues/134) | -| Calm sidebar, part 1: the settings. `threadRoles` names the assistant thread and one orchestrator per project; the server refuses a role for a thread that is missing, deleted, a sub-agent, a side chat, delegated from a linked machine or in another project. `calmSidebarEnabled` is the per-device switch. Nothing shows them yet. | A short sidebar: the threads that matter on top, the rest folded. | `server.threadRoles`, `client.calmSidebarEnabled` | off | (this pull request) | +| Calm sidebar, part 1: the settings. `threadRoles` names the assistant thread and one orchestrator per project; the server refuses a role for a thread that is missing, deleted, a sub-agent, a side chat, delegated from a linked machine or in another project. `calmSidebarEnabled` is the per-device switch. Nothing shows them yet. | A short sidebar: the threads that matter on top, the rest folded. | `server.threadRoles`, `client.calmSidebarEnabled` | off | [#928](https://github.com/scuttletoby/t3code/pull/928) | ## Repository, CI and releases From 2586f596715855e99ace175ae7e2d65772dee834 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 10:39:20 +0000 Subject: [PATCH 3/3] Calm sidebar part 1: review fixes (fork report row, lookup layer test) - forkReport.test.ts: threadRoles is a NOT_A_SWITCH row (settings only so far; nothing reads them yet), so the fork report test is green again. - threadRoleTargetsLayer.ts: `delegatedFrom != null`, as upstream's isDelegatedAppThread (an MCP-launched thread may carry null). - threadRoleTargets.ts: an unexpected crash in the thread lookup also gives the "try again" refusal (Effect.exit instead of Effect.option). - New threadRoleTargetsLayer.test.ts: the real lookup layer over a stand-in orchestrator, through the settings service: sub-agent, side chat, delegated task, another project's thread and a missing one refused; a top-level own-project thread (also one with delegatedFrom null) saved. - Docs: a dropped hand-edited entry is gone after the next save; an archived or deleted role thread counts as no role for readers; a removed project's entry stays until a save clears it. Co-Authored-By: Claude Opus 5.5 --- .../server/src/fork/threadRoleTargets.test.ts | 13 ++ apps/server/src/fork/threadRoleTargets.ts | 8 +- .../src/fork/threadRoleTargetsLayer.test.ts | 200 ++++++++++++++++++ .../server/src/fork/threadRoleTargetsLayer.ts | 4 +- apps/server/src/golive/forkReport.test.ts | 1 + docs/fork/README.md | 7 +- 6 files changed, 227 insertions(+), 6 deletions(-) create mode 100644 apps/server/src/fork/threadRoleTargetsLayer.test.ts diff --git a/apps/server/src/fork/threadRoleTargets.test.ts b/apps/server/src/fork/threadRoleTargets.test.ts index 93f6dd6ef3f4d..c00f60e5d2bab 100644 --- a/apps/server/src/fork/threadRoleTargets.test.ts +++ b/apps/server/src/fork/threadRoleTargets.test.ts @@ -174,6 +174,19 @@ describe("threadRoles save check", () => { ); }), ); + + it.effect("gives the same try-again refusal when the lookup crashes unexpectedly", () => + Effect.gen(function* () { + const crashing = Layer.succeed( + ThreadRoleTargets, + ThreadRoleTargets.of({ find: () => Effect.die(new Error("lookup crashed")) }), + ); + const problem = yield* threadRolesSaveProblem(NONE, roles("thread-top")).pipe( + Effect.provide(crashing), + ); + assert.match(problem ?? "", /could not be read, so the role was not saved: try again/u); + }), + ); }); // Through the settings service, as a client's save reaches it: a refusal writes nothing. diff --git a/apps/server/src/fork/threadRoleTargets.ts b/apps/server/src/fork/threadRoleTargets.ts index e248f3461f733..17d665027d3c3 100644 --- a/apps/server/src/fork/threadRoleTargets.ts +++ b/apps/server/src/fork/threadRoleTargets.ts @@ -4,7 +4,7 @@ * orchestration code. Without that service a new pointer is refused: fail closed. */ import type { ServerSettings, ThreadId, ThreadRoles } from "@t3tools/contracts"; -import { Context, Effect, Option } from "effect"; +import { Context, Effect, Exit, Option } from "effect"; /** What the check needs to know about a thread. */ export interface ThreadRoleTarget { @@ -89,8 +89,10 @@ export function threadRolesSaveProblem( return `${describe(pointers[0]!)} cannot be checked here (this server path cannot read threads): set roles from the app's settings.`; } for (const pointer of pointers) { - const target = yield* targets.value.find(pointer.threadId).pipe(Effect.option); - if (Option.isNone(target)) { + // `Effect.exit`, not `Effect.option`: an unexpected crash in the lookup (a defect) also gives + // "try again" instead of failing the save as an internal error. Nothing is written either way. + const target = yield* Effect.exit(targets.value.find(pointer.threadId)); + if (Exit.isFailure(target)) { return `${describe(pointer)}: thread ${pointer.threadId} could not be read, so the role was not saved: try again.`; } const problem = threadRolePointerProblem(pointer, target.value); diff --git a/apps/server/src/fork/threadRoleTargetsLayer.test.ts b/apps/server/src/fork/threadRoleTargetsLayer.test.ts new file mode 100644 index 0000000000000..94145372f2b58 --- /dev/null +++ b/apps/server/src/fork/threadRoleTargetsLayer.test.ts @@ -0,0 +1,200 @@ +// Fork (calm sidebar): the real thread lookup for the `threadRoles` save check +// (threadRoleTargetsLayer.ts) over upstream's orchestrator, reached through the settings service as +// a client's save reaches it. Only the orchestrator's `getThreadShell` is a stand-in. +import * as NodeCrypto from "@effect/platform-node/NodeCrypto"; +import * as NodeServices from "@effect/platform-node/NodeServices"; +import { + type OrchestrationV2ThreadShell, + ServerSettingsError, + ServerSettingsPatch, + type ThreadId, +} from "@t3tools/contracts"; +import { ForkSettingsWriteError } from "@t3tools/shared/forkSettingsPatch"; +import { assert, it } from "@effect/vitest"; +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; + +import * as ServerSecretStore from "../auth/ServerSecretStore.ts"; +import * as ServerConfig from "../config.ts"; +import * as Orchestrator from "../orchestration-v2/Orchestrator.ts"; +import * as SqlitePersistence from "../persistence/Sqlite.ts"; +import * as ManagedPolicy from "../policy/ManagedPolicy.ts"; +import * as ServerSettingsModule from "../serverSettings.ts"; +import { ThreadRoleTargets } from "./threadRoleTargets.ts"; +import * as ThreadRoleTargetsLayer from "./threadRoleTargetsLayer.ts"; + +/** Only the fields the lookup reads; the rest of a shell is never touched. */ +const shell = ( + projectId: string, + extra: Partial> & { delegatedFrom?: unknown } = {}, +): OrchestrationV2ThreadShell => + ({ + projectId, + lineage: { + parentThreadId: null, + relationshipToParent: null, + rootThreadId: "root" as ThreadId, + }, + ...extra, + }) as unknown as OrchestrationV2ThreadShell; + +const SHELLS: Record = { + "thread-top": shell("project-1"), + // An MCP-launched thread can carry `delegatedFrom: null` in memory; it is not delegated. + "thread-mcp-launched": shell("project-1", { delegatedFrom: null }), + // A "fork" lineage thread is listed, as upstream lists it. + "thread-forked": shell("project-1", { + lineage: { + parentThreadId: "thread-top" as ThreadId, + relationshipToParent: "fork", + rootThreadId: "thread-top" as ThreadId, + }, + }), + "thread-other-project": shell("project-2"), + "thread-subagent": shell("project-1", { + lineage: { + parentThreadId: "thread-top" as ThreadId, + relationshipToParent: "subagent", + rootThreadId: "thread-top" as ThreadId, + }, + }), + "thread-side-chat": shell("project-1", { + lineage: { + parentThreadId: "thread-top" as ThreadId, + relationshipToParent: null, + rootThreadId: "thread-top" as ThreadId, + sideChat: true, + }, + }), + "thread-delegated": shell("project-1", { + delegatedFrom: { environmentId: "env-1", threadId: "thread-x", title: "Task" }, + }), +}; + +const orchestrator = Layer.mock(Orchestrator.OrchestratorV2)({ + getThreadShell: (threadId: ThreadId) => Effect.succeed(SHELLS[threadId] ?? null), +}); + +/** The real lookup layer, built over the stand-in orchestrator. */ +const realTargets = ThreadRoleTargetsLayer.layer.pipe(Layer.provide(orchestrator)); + +it.layer(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))( + "threadRoles save check over the real thread lookup", + (it) => { + const layerServerSettings = () => + ServerSettingsModule.layer.pipe( + Layer.provide(ServerSecretStore.layer), + Layer.provide(ManagedPolicy.layerTest()), + Layer.provideMerge(Layer.fresh(SqlitePersistence.layerMemory)), + Layer.provideMerge( + Layer.fresh( + ServerConfig.layerTest(process.cwd(), { prefix: "t3code-thread-roles-layer-test-" }), + ), + ), + ); + const withLookup = () => Layer.merge(layerServerSettings(), realTargets); + + const decodePatch = Schema.decodeUnknownSync(ServerSettingsPatch); + + const readFile = Effect.gen(function* () { + const config = yield* ServerConfig.ServerConfig; + const fs = yield* FileSystem.FileSystem; + return JSON.parse(yield* fs.readFileString(config.settingsPath)) as Record; + }); + + const loadThenSave = (patch: unknown) => + Effect.gen(function* () { + const config = yield* ServerConfig.ServerConfig; + const fs = yield* FileSystem.FileSystem; + yield* fs.writeFileString(config.settingsPath, "{}"); + const service = yield* ServerSettingsModule.ServerSettingsService; + yield* service.getSettings; + return yield* service.updateSettings(decodePatch(patch)); + }); + + const refusal = (patch: unknown) => + Effect.gen(function* () { + const error = yield* loadThenSave(patch).pipe(Effect.flip); + assert.instanceOf(error, ServerSettingsError); + assert.instanceOf(error.cause, ForkSettingsWriteError); + assert.deepStrictEqual(yield* readFile, {}); + return (error.cause as Error).message; + }); + + it.effect("maps each shell as the check needs it", () => + Effect.gen(function* () { + const targets = yield* ThreadRoleTargets; + const find = (threadId: string) => targets.find(threadId as ThreadId); + assert.isNull(yield* find("thread-gone")); + assert.deepStrictEqual(yield* find("thread-top"), { + projectId: "project-1", + listed: true, + delegated: false, + }); + assert.deepStrictEqual(yield* find("thread-mcp-launched"), { + projectId: "project-1", + listed: true, + delegated: false, + }); + assert.isTrue((yield* find("thread-forked"))?.listed); + assert.isFalse((yield* find("thread-subagent"))?.listed); + assert.isFalse((yield* find("thread-side-chat"))?.listed); + assert.isTrue((yield* find("thread-delegated"))?.delegated); + assert.strictEqual((yield* find("thread-other-project"))?.projectId, "project-2"); + }).pipe(Effect.provide(realTargets)), + ); + + it.effect("saves a top-level thread of the project as its orchestrator", () => + Effect.gen(function* () { + const saved = yield* loadThenSave({ + threadRoles: { + assistant: "thread-mcp-launched", + orchestrators: { "project-1": "thread-top" }, + }, + }); + assert.deepStrictEqual(saved.threadRoles, { + assistant: "thread-mcp-launched", + orchestrators: { "project-1": "thread-top" }, + }); + assert.deepStrictEqual((yield* readFile).threadRoles, { + assistant: "thread-mcp-launched", + orchestrators: { "project-1": "thread-top" }, + }); + }).pipe(Effect.provide(withLookup())), + ); + + it.effect("refuses a sub-agent, a side chat and a delegated task, and writes nothing", () => + Effect.gen(function* () { + assert.match( + yield* refusal({ threadRoles: { orchestrators: { "project-1": "thread-subagent" } } }), + /sub-agent or side chat/u, + ); + assert.match( + yield* refusal({ threadRoles: { assistant: "thread-side-chat" } }), + /sub-agent or side chat/u, + ); + assert.match( + yield* refusal({ threadRoles: { assistant: "thread-delegated" } }), + /delegated from a linked machine/u, + ); + }).pipe(Effect.provide(withLookup())), + ); + + it.effect("refuses another project's thread and a missing one, and writes nothing", () => + Effect.gen(function* () { + assert.match( + yield* refusal({ + threadRoles: { orchestrators: { "project-1": "thread-other-project" } }, + }), + /belongs to project project-2/u, + ); + assert.match( + yield* refusal({ threadRoles: { assistant: "thread-gone" } }), + /does not exist or is deleted/u, + ); + }).pipe(Effect.provide(withLookup())), + ); + }, +); diff --git a/apps/server/src/fork/threadRoleTargetsLayer.ts b/apps/server/src/fork/threadRoleTargetsLayer.ts index 45a41ce2ac410..290168d8c9a3f 100644 --- a/apps/server/src/fork/threadRoleTargetsLayer.ts +++ b/apps/server/src/fork/threadRoleTargetsLayer.ts @@ -20,7 +20,9 @@ export const layer = Layer.effect( : { projectId: shell.projectId, listed: isListedThreadLineage(shell.lineage), - delegated: shell.delegatedFrom !== undefined, + // `!= null` as upstream's `isDelegatedAppThread`: an MCP-launched thread may carry + // `delegatedFrom: null`, and that thread is not delegated. + delegated: shell.delegatedFrom != null, }; }), }), diff --git a/apps/server/src/golive/forkReport.test.ts b/apps/server/src/golive/forkReport.test.ts index e018ba29cbd47..2723fa4902fdd 100644 --- a/apps/server/src/golive/forkReport.test.ts +++ b/apps/server/src/golive/forkReport.test.ts @@ -1126,6 +1126,7 @@ describe("__fork-report settings", () => { placement: "placement: settings only so far; nothing reads them yet (later placement rows)", placementNeeds: "placement: settings only so far; nothing reads them yet (later placement rows)", + threadRoles: "calm sidebar: settings only so far; nothing reads them yet", }; it("counts every fork setting as a feature or names why it is not a switch", () => { diff --git a/docs/fork/README.md b/docs/fork/README.md index a669db6465962..0120d9e6c22da 100644 --- a/docs/fork/README.md +++ b/docs/fork/README.md @@ -1140,13 +1140,16 @@ thread (not a sub-agent, a side chat or a task delegated from a linked machine) orchestrator, belongs to the project its entry names. Where the server cannot read threads, such a save is refused too, never let through. A pointer the save leaves as it was is not checked again, so an old pointer to a thread deleted since blocks no other save; whoever reads the roles checks the -thread and treats a failing one as no role. +thread and treats a failing one as no role. An archived thread can take a role, but readers treat an +archived or deleted thread with a role as no role. An entry for a project removed since stays in the +file (no sweep clears it) until a save removes it; readers skip it. A save changes the roles field by field: a left-out field keeps its value, `assistant: null` removes the assistant, and each `orchestrators` entry is set or (`null`) removed on its own, so two saves for different projects keep both. A save with a bad id is refused. The file is read leniently: a missing or non-object value reads as no roles, a bad `assistant` as none, and a bad orchestrator -entry drops alone, so a hand edit never resets the other settings. +entry drops alone, so a hand edit never resets the other settings. A dropped entry is gone from the +file after the next save of any setting, since the save writes the settings as read. ```json {