From 829acd3c62deae8f7f40c35d362006541e785a56 Mon Sep 17 00:00:00 2001
From: saltacc <alotofcatz@gmail.com>
Date: Sat, 23 May 2026 13:38:19 -0700
Subject: [PATCH 1/5] Add local Arch package builder

---
 README.md                     |  19 ++
 package.json                  |   1 +
 scripts/build-arch-package.ts | 388 ++++++++++++++++++++++++++++++++++
 3 files changed, 408 insertions(+)
 create mode 100644 scripts/build-arch-package.ts

diff --git a/README.md b/README.md
index d639817b..f37cc928 100644
--- a/README.md
+++ b/README.md
@@ -121,6 +121,25 @@ bun run test
 
 Do not run `bun test`; this repo uses `bun run test`.
 
+### Local Arch Package
+
+Build a local pacman package from the Linux AppImage artifact:
+
+```bash
+bun install
+bun run dist:arch:local
+sudo pacman -U release/arch/cafe-code-*.pkg.tar.zst
+```
+
+To build and install in one step:
+
+```bash
+bun run dist:arch:local -- --install
+```
+
+This is intentionally local packaging only. It does not create AUR metadata or
+publish anything.
+
 ## 日本語でちゅ
 
 Cafe Code は、Codex とか Claude とお話するための、
diff --git a/package.json b/package.json
index 5661c44e..c4c1bf6c 100644
--- a/package.json
+++ b/package.json
@@ -54,6 +54,7 @@
     "dist:desktop:win": "node scripts/build-desktop-artifact.ts --platform win --target nsis",
     "dist:desktop:win:arm64": "node scripts/build-desktop-artifact.ts --platform win --target nsis --arch arm64",
     "dist:desktop:win:x64": "node scripts/build-desktop-artifact.ts --platform win --target nsis --arch x64",
+    "dist:arch:local": "node scripts/build-arch-package.ts",
     "release:smoke": "node scripts/release-smoke.ts",
     "db:compact-activity-payloads": "node scripts/compact-activity-payloads.ts",
     "clean": "rm -rf node_modules apps/*/node_modules packages/*/node_modules apps/*/dist apps/*/dist-electron packages/*/dist .turbo apps/*/.turbo packages/*/.turbo",
diff --git a/scripts/build-arch-package.ts b/scripts/build-arch-package.ts
new file mode 100644
index 00000000..d3e4761e
--- /dev/null
+++ b/scripts/build-arch-package.ts
@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+// @effect-diagnostics nodeBuiltinImport:off
+
+import { spawnSync } from "node:child_process";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readlinkSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+
+interface CliOptions {
+  readonly arch: DesktopArch;
+  readonly install: boolean;
+  readonly keepStage: boolean;
+  readonly outputDir: string;
+  readonly skipDesktopBuild: boolean;
+  readonly verbose: boolean;
+  readonly version: string | undefined;
+}
+
+type DesktopArch = "x64" | "arm64";
+type PacmanArch = "x86_64" | "aarch64";
+
+const repoRoot = realpathSync(new URL("..", import.meta.url));
+const serverPackageJsonPath = join(repoRoot, "apps/server/package.json");
+const desktopIconPath = join(repoRoot, "apps/desktop/resources/icon.png");
+
+function writeStdout(message: string) {
+  process.stdout.write(`${message}\n`);
+}
+
+function writeStderr(message: string) {
+  process.stderr.write(`${message}\n`);
+}
+
+function fail(message: string): never {
+  writeStderr(`error: ${message}`);
+  process.exit(1);
+}
+
+function commandExists(command: string): boolean {
+  const result = spawnSync(command, ["--version"], {
+    cwd: repoRoot,
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+function run(command: string, args: ReadonlyArray<string>, options?: { readonly cwd?: string }) {
+  const result = spawnSync(command, [...args], {
+    cwd: options?.cwd ?? repoRoot,
+    stdio: "inherit",
+  });
+
+  if (result.error) {
+    fail(`failed to run ${command}: ${result.error.message}`);
+  }
+  if (result.signal) {
+    fail(`${command} exited after signal ${result.signal}`);
+  }
+  if (result.status !== 0) {
+    fail(`${command} exited with status ${String(result.status)}`);
+  }
+}
+
+function readJsonObject(path: string): Record<string, unknown> {
+  const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    fail(`expected JSON object at ${path}`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function readDefaultVersion(): string {
+  const packageJson = readJsonObject(serverPackageJsonPath);
+  const version = packageJson.version;
+  if (typeof version !== "string" || version.length === 0) {
+    fail(`missing version in ${serverPackageJsonPath}`);
+  }
+  return version;
+}
+
+function mapHostArch(): DesktopArch {
+  if (process.arch === "arm64") return "arm64";
+  return "x64";
+}
+
+function mapPacmanArch(arch: DesktopArch): PacmanArch {
+  return arch === "arm64" ? "aarch64" : "x86_64";
+}
+
+function mapLinuxArtifactArch(arch: DesktopArch): string {
+  return arch === "x64" ? "x86_64" : arch;
+}
+
+function toPacmanPkgver(version: string): string {
+  return version.replaceAll("-", "_");
+}
+
+function parseArgs(argv: ReadonlyArray<string>): CliOptions {
+  let arch: DesktopArch = mapHostArch();
+  let install = false;
+  let keepStage = false;
+  let outputDir = "release/arch";
+  let skipDesktopBuild = false;
+  let verbose = false;
+  let version: string | undefined;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--arch") {
+      const value = argv[index + 1];
+      if (value !== "x64" && value !== "arm64") {
+        fail("--arch must be x64 or arm64");
+      }
+      arch = value;
+      index += 1;
+      continue;
+    }
+    if (arg === "--install") {
+      install = true;
+      continue;
+    }
+    if (arg === "--keep-stage") {
+      keepStage = true;
+      continue;
+    }
+    if (arg === "--output-dir") {
+      const value = argv[index + 1];
+      if (!value) fail("--output-dir requires a path");
+      outputDir = value;
+      index += 1;
+      continue;
+    }
+    if (arg === "--skip-desktop-build") {
+      skipDesktopBuild = true;
+      continue;
+    }
+    if (arg === "--verbose") {
+      verbose = true;
+      continue;
+    }
+    if (arg === "--version") {
+      const value = argv[index + 1];
+      if (!value) fail("--version requires a value");
+      version = value;
+      index += 1;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      writeStdout(`Build a local Arch Linux pacman package for Cafe Code.
+
+Usage:
+  bun run dist:arch:local [options]
+
+Options:
+  --arch x64|arm64          Desktop artifact architecture. Defaults to host arch.
+  --install                 Run sudo pacman -U after building the package.
+  --keep-stage              Keep the temporary package staging directory.
+  --output-dir <path>       Package output directory. Defaults to release/arch.
+  --skip-desktop-build      Reuse an existing AppImage from release/arch-appimage.
+  --verbose                 Pass verbose output through to the desktop artifact build.
+  --version <version>       Package version. Defaults to apps/server/package.json.
+`);
+      process.exit(0);
+    }
+
+    fail(`unknown argument: ${arg ?? ""}`);
+  }
+
+  return { arch, install, keepStage, outputDir, skipDesktopBuild, verbose, version };
+}
+
+function ensureAppImage(options: CliOptions, version: string): string {
+  const appImageDir = join(repoRoot, "release/arch-appimage");
+  const artifactArch = mapLinuxArtifactArch(options.arch);
+  const appImagePath = join(appImageDir, `Cafe-Code-${version}-${artifactArch}.AppImage`);
+
+  if (!options.skipDesktopBuild) {
+    const buildArgs = [
+      "scripts/build-desktop-artifact.ts",
+      "--platform",
+      "linux",
+      "--target",
+      "AppImage",
+      "--arch",
+      options.arch,
+      "--build-version",
+      version,
+      "--output-dir",
+      "release/arch-appimage",
+    ];
+    if (options.verbose) buildArgs.push("--verbose");
+    run("node", buildArgs);
+  }
+
+  if (!existsSync(appImagePath)) {
+    fail(`missing AppImage at ${appImagePath}; rerun without --skip-desktop-build`);
+  }
+
+  return appImagePath;
+}
+
+function ensureParent(path: string) {
+  mkdirSync(dirname(path), { recursive: true });
+}
+
+function writePackageFile(path: string, contents: string, mode: number) {
+  ensureParent(path);
+  writeFileSync(path, contents);
+  chmodSync(path, mode);
+}
+
+function copyPackageFile(from: string, to: string, mode: number) {
+  ensureParent(to);
+  copyFileSync(from, to);
+  chmodSync(to, mode);
+}
+
+function installedSize(path: string): number {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink()) {
+    return Buffer.byteLength(readlinkSync(path));
+  }
+  if (stat.isFile()) {
+    return stat.size;
+  }
+  if (!stat.isDirectory()) {
+    return 0;
+  }
+
+  let total = 0;
+  for (const entry of readdirSync(path)) {
+    total += installedSize(join(path, entry));
+  }
+  return total;
+}
+
+function unixNowSeconds(): number {
+  const sourceDateEpoch = process.env.SOURCE_DATE_EPOCH;
+  if (sourceDateEpoch) {
+    const parsed = Number(sourceDateEpoch);
+    if (Number.isInteger(parsed) && parsed > 0) return parsed;
+  }
+  return Math.floor(performance.timeOrigin / 1000);
+}
+
+function createStage(options: CliOptions, version: string, appImagePath: string): string {
+  const stageRoot = mkdtempSync(join(tmpdir(), "cafecode-arch-package-"));
+  const appImageTarget = join(stageRoot, "opt/cafe-code/cafe-code.AppImage");
+  const wrapperTarget = join(stageRoot, "usr/bin/cafe-code");
+  const desktopTarget = join(stageRoot, "usr/share/applications/cafecode.desktop");
+  const iconTarget = join(stageRoot, "usr/share/icons/hicolor/1024x1024/apps/cafecode.png");
+
+  copyPackageFile(appImagePath, appImageTarget, 0o755);
+  writePackageFile(
+    wrapperTarget,
+    `#!/bin/sh
+exec /opt/cafe-code/cafe-code.AppImage "$@"
+`,
+    0o755,
+  );
+  writePackageFile(
+    desktopTarget,
+    `[Desktop Entry]
+Type=Application
+Name=Cafe Code
+Comment=Minimal desktop GUI for coding agents
+Exec=cafe-code %U
+Icon=cafecode
+Terminal=false
+Categories=Development;
+StartupWMClass=cafecode
+`,
+    0o644,
+  );
+  copyPackageFile(desktopIconPath, iconTarget, 0o644);
+
+  const pkgver = toPacmanPkgver(version);
+  const pacmanArch = mapPacmanArch(options.arch);
+  const packageSize = installedSize(join(stageRoot, "opt")) + installedSize(join(stageRoot, "usr"));
+  const pkgInfo = [
+    "pkgname = cafe-code",
+    "pkgbase = cafe-code",
+    "xdata = pkgtype=pkg",
+    `pkgver = ${pkgver}-1`,
+    "pkgdesc = Minimal desktop GUI for coding agents",
+    "url = https://github.com/cafeai/cafe-code",
+    `builddate = ${String(unixNowSeconds())}`,
+    "packager = Cafe Code local package builder",
+    `size = ${String(packageSize)}`,
+    `arch = ${pacmanArch}`,
+    "license = AGPL-3.0-or-later",
+    "depend = fuse2",
+    "depend = hicolor-icon-theme",
+    "",
+  ].join("\n");
+  writePackageFile(join(stageRoot, ".PKGINFO"), pkgInfo, 0o644);
+
+  if (options.keepStage) {
+    const linkPath = join(resolve(repoRoot, options.outputDir), "stage-latest");
+    rmSync(linkPath, { recursive: true, force: true });
+    ensureParent(linkPath);
+    symlinkSync(stageRoot, linkPath);
+    writeStdout(`[arch-package] Kept stage at ${stageRoot}`);
+  }
+
+  return stageRoot;
+}
+
+function createPacmanPackage(stageRoot: string, options: CliOptions, version: string): string {
+  const outputDir = resolve(repoRoot, options.outputDir);
+  const pkgver = toPacmanPkgver(version);
+  const pacmanArch = mapPacmanArch(options.arch);
+  const packagePath = join(outputDir, `cafe-code-${pkgver}-1-${pacmanArch}.pkg.tar.zst`);
+
+  mkdirSync(outputDir, { recursive: true });
+  rmSync(packagePath, { force: true });
+  run("bsdtar", [
+    "--zstd",
+    "--uid",
+    "0",
+    "--gid",
+    "0",
+    "--uname",
+    "root",
+    "--gname",
+    "root",
+    "-C",
+    stageRoot,
+    "-cf",
+    packagePath,
+    ".PKGINFO",
+    "opt",
+    "usr",
+  ]);
+
+  return packagePath;
+}
+
+function installPackage(packagePath: string) {
+  const pacmanArgs = ["pacman", "-U", "--needed", packagePath];
+  if (process.getuid?.() === 0) {
+    run("pacman", ["-U", "--needed", packagePath]);
+    return;
+  }
+  run("sudo", pacmanArgs);
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (!commandExists("bsdtar")) {
+    fail("bsdtar is required to create pacman packages");
+  }
+
+  const version = options.version ?? readDefaultVersion();
+  const appImagePath = ensureAppImage(options, version);
+  const stageRoot = createStage(options, version, appImagePath);
+
+  try {
+    const packagePath = createPacmanPackage(stageRoot, options, version);
+    writeStdout(`[arch-package] Wrote ${packagePath}`);
+    writeStdout(`[arch-package] Install with: sudo pacman -U ${packagePath}`);
+
+    if (options.install) {
+      installPackage(packagePath);
+    }
+  } finally {
+    if (!options.keepStage) {
+      rmSync(stageRoot, { recursive: true, force: true });
+    }
+  }
+}
+
+main();

From 8c92e8afb8aa808f4569d0068eeba9048b53dbb0 Mon Sep 17 00:00:00 2001
From: saltacc <alotofcatz@gmail.com>
Date: Sat, 23 May 2026 14:34:02 -0700
Subject: [PATCH 2/5] Add project additional directories

---
 apps/server/src/checkpointing/Utils.test.ts   |  27 ++
 apps/server/src/checkpointing/Utils.ts        |  41 +++
 .../Layers/ProjectionPipeline.test.ts         |   5 +
 .../Layers/ProjectionPipeline.ts              |  10 +-
 .../Layers/ProjectionSnapshotQuery.test.ts    |   2 +
 .../Layers/ProjectionSnapshotQuery.ts         |   8 +
 .../Layers/ProviderCommandReactor.ts          |  33 ++-
 apps/server/src/orchestration/Normalizer.ts   |  87 ++++++-
 apps/server/src/orchestration/decider.ts      |   4 +
 apps/server/src/orchestration/projector.ts    |   4 +
 .../persistence/Layers/ProjectionProjects.ts  |   8 +-
 .../Layers/ProjectionRepositories.test.ts     |   1 +
 apps/server/src/persistence/Migrations.ts     |   2 +
 .../persistence/Migrations/005_Projections.ts |   1 +
 ...onProjectsAdditionalWorkspaceRoots.test.ts |  51 ++++
 ...jectionProjectsAdditionalWorkspaceRoots.ts |  18 ++
 .../Services/ProjectionProjects.ts            |   9 +-
 .../src/provider/Layers/ClaudeAdapter.test.ts |  25 ++
 .../src/provider/Layers/ClaudeAdapter.ts      |  14 +-
 .../src/provider/Layers/CodexAdapter.ts       |   3 +
 .../Layers/CodexSessionRuntime.test.ts        |  16 ++
 .../provider/Layers/CodexSessionRuntime.ts    |  33 ++-
 .../src/provider/Layers/ProviderService.ts    |  36 +++
 apps/web/src/components/ChatMarkdown.tsx      |   6 +-
 apps/web/src/components/ChatView.browser.tsx  |   2 +
 apps/web/src/components/ChatView.tsx          |   1 +
 .../components/KeybindingsToast.browser.tsx   |   1 +
 apps/web/src/components/Sidebar.tsx           | 240 +++++++++++++++++-
 .../src/components/chat/MessagesTimeline.tsx  |   6 +
 apps/web/src/localApi.test.ts                 |   1 +
 apps/web/src/markdown-links.test.ts           |  15 ++
 apps/web/src/markdown-links.ts                |  27 +-
 apps/web/src/store.test.ts                    |   3 +-
 apps/web/src/store.ts                         |   5 +
 apps/web/src/types.ts                         |   1 +
 packages/contracts/src/orchestration.test.ts  |  21 ++
 packages/contracts/src/orchestration.ts       |  11 +
 packages/contracts/src/provider.ts            |   2 +
 38 files changed, 752 insertions(+), 28 deletions(-)
 create mode 100644 apps/server/src/checkpointing/Utils.test.ts
 create mode 100644 apps/server/src/persistence/Migrations/034_ProjectionProjectsAdditionalWorkspaceRoots.test.ts
 create mode 100644 apps/server/src/persistence/Migrations/034_ProjectionProjectsAdditionalWorkspaceRoots.ts

diff --git a/apps/server/src/checkpointing/Utils.test.ts b/apps/server/src/checkpointing/Utils.test.ts
new file mode 100644
index 00000000..815bc6ce
--- /dev/null
+++ b/apps/server/src/checkpointing/Utils.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { ProjectId } from "@cafecode/contracts";
+
+import { resolveThreadWorkspaceDirectories } from "./Utils.ts";
+
+describe("resolveThreadWorkspaceDirectories", () => {
+  it("keeps worktree cwd primary and excludes duplicate additional roots", () => {
+    const result = resolveThreadWorkspaceDirectories({
+      thread: {
+        projectId: ProjectId.make("project-1"),
+        worktreePath: "/repo-worktree",
+      },
+      projects: [
+        {
+          id: ProjectId.make("project-1"),
+          workspaceRoot: "/repo",
+          additionalWorkspaceRoots: ["/repo-worktree", "/docs", "/docs/"],
+        },
+      ],
+    });
+
+    expect(result).toEqual({
+      cwd: "/repo-worktree",
+      additionalDirectories: ["/docs"],
+    });
+  });
+});
diff --git a/apps/server/src/checkpointing/Utils.ts b/apps/server/src/checkpointing/Utils.ts
index da9c74c9..df1e2849 100644
--- a/apps/server/src/checkpointing/Utils.ts
+++ b/apps/server/src/checkpointing/Utils.ts
@@ -37,3 +37,44 @@ export function resolveThreadWorkspaceCwd(input: {
 
   return input.projects.find((project) => project.id === input.thread.projectId)?.workspaceRoot;
 }
+
+function normalizeComparablePath(value: string): string {
+  return value.replaceAll("\\", "/").replace(/\/+$/, "");
+}
+
+function isSamePath(left: string, right: string): boolean {
+  return normalizeComparablePath(left) === normalizeComparablePath(right);
+}
+
+export function resolveThreadWorkspaceDirectories(input: {
+  readonly thread: {
+    readonly projectId: ProjectId;
+    readonly worktreePath: string | null;
+  };
+  readonly projects: ReadonlyArray<{
+    readonly id: ProjectId;
+    readonly workspaceRoot: string;
+    readonly additionalWorkspaceRoots?: ReadonlyArray<string> | undefined;
+  }>;
+}): {
+  readonly cwd: string | undefined;
+  readonly additionalDirectories: ReadonlyArray<string>;
+} {
+  const project = input.projects.find((candidate) => candidate.id === input.thread.projectId);
+  const cwd = resolveThreadWorkspaceCwd(input);
+  if (!project || !cwd) {
+    return { cwd, additionalDirectories: [] };
+  }
+
+  const additionalDirectories: string[] = [];
+  for (const root of project.additionalWorkspaceRoots ?? []) {
+    if (isSamePath(root, cwd)) {
+      continue;
+    }
+    if (!additionalDirectories.some((existingRoot) => isSamePath(existingRoot, root))) {
+      additionalDirectories.push(root);
+    }
+  }
+
+  return { cwd, additionalDirectories };
+}
diff --git a/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts b/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
index 3de4b7a8..948c45ff 100644
--- a/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
@@ -2363,6 +2363,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
         projectId: ProjectId.make("project-scripts"),
         title: "Scripts Project",
         workspaceRoot: "/tmp/project-scripts",
+        additionalWorkspaceRoots: ["/tmp/project-docs"],
         defaultModelSelection: {
           instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
@@ -2374,6 +2375,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
         type: "project.meta.update",
         commandId: CommandId.make("cmd-scripts-project-update"),
         projectId: ProjectId.make("project-scripts"),
+        additionalWorkspaceRoots: ["/tmp/project-docs", "/tmp/project-tools"],
         scripts: [
           {
             id: "script-1",
@@ -2390,10 +2392,12 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
       });
 
       const projectRows = yield* sql<{
+        readonly additionalWorkspaceRoots: string;
         readonly scriptsJson: string;
         readonly defaultModelSelection: string;
       }>`
         SELECT
+          additional_workspace_roots_json AS "additionalWorkspaceRoots",
           scripts_json AS "scriptsJson",
           default_model_selection_json AS "defaultModelSelection"
         FROM projection_projects
@@ -2401,6 +2405,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
       `;
       assert.deepEqual(projectRows, [
         {
+          additionalWorkspaceRoots: '["/tmp/project-docs","/tmp/project-tools"]',
           scriptsJson:
             '[{"id":"script-1","name":"Build","command":"bun run build","icon":"build","runOnWorktreeCreate":false}]',
           defaultModelSelection: '{"instanceId":"codex","model":"gpt-5"}',
diff --git a/apps/server/src/orchestration/Layers/ProjectionPipeline.ts b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
index 51ff2d08..b05e77c8 100644
--- a/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
@@ -446,6 +446,7 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             projectId: event.payload.projectId,
             title: event.payload.title,
             workspaceRoot: event.payload.workspaceRoot,
+            additionalWorkspaceRoots: event.payload.additionalWorkspaceRoots ?? [],
             defaultModelSelection: event.payload.defaultModelSelection,
             scripts: event.payload.scripts,
             createdAt: event.payload.createdAt,
@@ -467,6 +468,9 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             ...(event.payload.workspaceRoot !== undefined
               ? { workspaceRoot: event.payload.workspaceRoot }
               : {}),
+            ...(event.payload.additionalWorkspaceRoots !== undefined
+              ? { additionalWorkspaceRoots: event.payload.additionalWorkspaceRoots }
+              : {}),
             ...(event.payload.defaultModelSelection !== undefined
               ? { defaultModelSelection: event.payload.defaultModelSelection }
               : {}),
@@ -1261,9 +1265,7 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
               checkpointFiles: event.payload.files,
               startedAt: existingTurn.value.startedAt ?? event.payload.completedAt,
               requestedAt: existingTurn.value.requestedAt ?? event.payload.completedAt,
-              completedAt: shouldHoldTurnOpen
-                ? (existingTurn.value.completedAt ?? null)
-                : event.payload.completedAt,
+              completedAt: event.payload.completedAt,
             });
             return;
           }
@@ -1277,7 +1279,7 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             state: nextState,
             requestedAt: event.payload.completedAt,
             startedAt: event.payload.completedAt,
-            completedAt: shouldHoldTurnOpen ? null : event.payload.completedAt,
+            completedAt: event.payload.completedAt,
             checkpointTurnCount: event.payload.checkpointTurnCount,
             checkpointRef: event.payload.checkpointRef,
             checkpointStatus: event.payload.status,
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
index bf0b619a..542427d5 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
@@ -262,6 +262,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           id: asProjectId("project-1"),
           title: "Project 1",
           workspaceRoot: "/tmp/project-1",
+          additionalWorkspaceRoots: [],
           repositoryIdentity: null,
           defaultModelSelection: {
             instanceId: ProviderInstanceId.make("codex"),
@@ -373,6 +374,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           id: asProjectId("project-1"),
           title: "Project 1",
           workspaceRoot: "/tmp/project-1",
+          additionalWorkspaceRoots: [],
           repositoryIdentity: null,
           defaultModelSelection: {
             instanceId: ProviderInstanceId.make("codex"),
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
index a3a27521..b3077c02 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
@@ -1,5 +1,6 @@
 import {
   ChatAttachment,
+  AdditionalWorkspaceRoots,
   IsoDateTime,
   MessageId,
   NonNegativeInt,
@@ -60,6 +61,7 @@ const decodeThread = Schema.decodeUnknownEffect(OrchestrationThread);
 export const THREAD_DETAIL_ACTIVITY_LIMIT = 500;
 const ProjectionProjectDbRowSchema = ProjectionProject.mapFields(
   Struct.assign({
+    additionalWorkspaceRoots: Schema.fromJsonString(AdditionalWorkspaceRoots),
     defaultModelSelection: Schema.NullOr(Schema.fromJsonString(ModelSelection)),
     scripts: Schema.fromJsonString(Schema.Array(ProjectScript)),
   }),
@@ -245,6 +247,7 @@ function mapProjectShellRow(
     id: row.projectId,
     title: row.title,
     workspaceRoot: row.workspaceRoot,
+    additionalWorkspaceRoots: row.additionalWorkspaceRoots,
     repositoryIdentity,
     defaultModelSelection: row.defaultModelSelection,
     scripts: row.scripts,
@@ -319,6 +322,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
           project_id AS "projectId",
           title,
           workspace_root AS "workspaceRoot",
+          additional_workspace_roots_json AS "additionalWorkspaceRoots",
           default_model_selection_json AS "defaultModelSelection",
           scripts_json AS "scripts",
           created_at AS "createdAt",
@@ -762,6 +766,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
           project_id AS "projectId",
           title,
           workspace_root AS "workspaceRoot",
+          additional_workspace_roots_json AS "additionalWorkspaceRoots",
           default_model_selection_json AS "defaultModelSelection",
           scripts_json AS "scripts",
           created_at AS "createdAt",
@@ -784,6 +789,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
           project_id AS "projectId",
           title,
           workspace_root AS "workspaceRoot",
+          additional_workspace_roots_json AS "additionalWorkspaceRoots",
           default_model_selection_json AS "defaultModelSelection",
           scripts_json AS "scripts",
           created_at AS "createdAt",
@@ -1234,6 +1240,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
                 id: row.projectId,
                 title: row.title,
                 workspaceRoot: row.workspaceRoot,
+                additionalWorkspaceRoots: row.additionalWorkspaceRoots,
                 repositoryIdentity: repositoryIdentities.get(row.projectId) ?? null,
                 defaultModelSelection: row.defaultModelSelection,
                 scripts: row.scripts,
@@ -1357,6 +1364,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
                   id: row.projectId,
                   title: row.title,
                   workspaceRoot: row.workspaceRoot,
+                  additionalWorkspaceRoots: row.additionalWorkspaceRoots,
                   defaultModelSelection: row.defaultModelSelection,
                   scripts: row.scripts,
                   createdAt: row.createdAt,
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
index eef79a7e..66cbffd7 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
@@ -28,7 +28,10 @@ import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import { makeDrainableWorker } from "@cafecode/shared/DrainableWorker";
 
-import { resolveThreadWorkspaceCwd } from "../../checkpointing/Utils.ts";
+import {
+  resolveThreadWorkspaceCwd,
+  resolveThreadWorkspaceDirectories,
+} from "../../checkpointing/Utils.ts";
 import { increment, orchestrationEventsProcessedTotal } from "../../observability/Metrics.ts";
 import { ProviderAdapterRequestError } from "../../provider/Errors.ts";
 import type { ProviderServiceError } from "../../provider/Errors.ts";
@@ -83,6 +86,18 @@ function mapProviderSessionStatusToOrchestrationStatus(
   }
 }
 
+function areStringArraysEqual(
+  left: ReadonlyArray<string> | undefined,
+  right: ReadonlyArray<string> | undefined,
+): boolean {
+  const normalizedLeft = left ?? [];
+  const normalizedRight = right ?? [];
+  return (
+    normalizedLeft.length === normalizedRight.length &&
+    normalizedLeft.every((entry, index) => entry === normalizedRight[index])
+  );
+}
+
 const turnStartKeyForEvent = (event: ProviderIntentEvent): string =>
   event.commandId !== null ? `command:${event.commandId}` : `event:${event.eventId}`;
 
@@ -402,10 +417,12 @@ const make = Effect.gen(function* () {
       }
     }
     const project = yield* resolveProject(thread.projectId);
-    const effectiveCwd = resolveThreadWorkspaceCwd({
+    const workspaceDirectories = resolveThreadWorkspaceDirectories({
       thread,
       projects: project ? [project] : [],
     });
+    const effectiveCwd = workspaceDirectories.cwd;
+    const effectiveAdditionalDirectories = workspaceDirectories.additionalDirectories;
 
     const startProviderSession = (input?: {
       readonly resumeCursor?: unknown;
@@ -416,6 +433,9 @@ const make = Effect.gen(function* () {
         ...(preferredProvider ? { provider: preferredProvider } : {}),
         providerInstanceId: desiredInstanceId,
         ...(effectiveCwd ? { cwd: effectiveCwd } : {}),
+        ...(effectiveAdditionalDirectories.length > 0
+          ? { additionalDirectories: effectiveAdditionalDirectories }
+          : {}),
         modelSelection: desiredModelSelection,
         ...(input?.resumeCursor !== undefined ? { resumeCursor: input.resumeCursor } : {}),
         runtimeMode: desiredRuntimeMode,
@@ -452,6 +472,10 @@ const make = Effect.gen(function* () {
     if (existingSessionThreadId) {
       const runtimeModeChanged = thread.runtimeMode !== thread.session?.runtimeMode;
       const cwdChanged = effectiveCwd !== activeSession?.cwd;
+      const additionalDirectoriesChanged = !areStringArraysEqual(
+        effectiveAdditionalDirectories,
+        activeSession?.additionalDirectories,
+      );
       const sessionModelSwitch = (yield* providerService.getCapabilities(desiredInstanceId))
         .sessionModelSwitch;
       const modelChanged =
@@ -470,6 +494,7 @@ const make = Effect.gen(function* () {
       if (
         !runtimeModeChanged &&
         !cwdChanged &&
+        !additionalDirectoriesChanged &&
         !instanceChanged &&
         !shouldRestartForModelChange &&
         !shouldRestartForModelSelectionChange
@@ -493,6 +518,9 @@ const make = Effect.gen(function* () {
         previousCwd: activeSession?.cwd,
         desiredCwd: effectiveCwd,
         cwdChanged,
+        previousAdditionalDirectories: activeSession?.additionalDirectories ?? [],
+        desiredAdditionalDirectories: effectiveAdditionalDirectories,
+        additionalDirectoriesChanged,
         modelChanged,
         instanceChanged,
         shouldRestartForModelChange,
@@ -509,6 +537,7 @@ const make = Effect.gen(function* () {
         provider: restartedSession.provider,
         runtimeMode: restartedSession.runtimeMode,
         cwd: restartedSession.cwd,
+        additionalDirectories: restartedSession.additionalDirectories,
       });
       yield* bindSessionToThread(restartedSession);
       return restartedSession.threadId;
diff --git a/apps/server/src/orchestration/Normalizer.ts b/apps/server/src/orchestration/Normalizer.ts
index 85b4ff87..bdc0cdb2 100644
--- a/apps/server/src/orchestration/Normalizer.ts
+++ b/apps/server/src/orchestration/Normalizer.ts
@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import {
   type ClientOrchestrationCommand,
@@ -12,6 +13,7 @@ import { createAttachmentId, resolveAttachmentPath } from "../attachmentStore.ts
 import { ServerConfig } from "../config.ts";
 import { parseBase64DataUrl } from "../imageMime.ts";
 import { WorkspacePaths } from "../workspace/Services/WorkspacePaths.ts";
+import { ProjectionSnapshotQuery } from "./Services/ProjectionSnapshotQuery.ts";
 
 export const normalizeDispatchCommand = (command: ClientOrchestrationCommand) =>
   Effect.gen(function* () {
@@ -19,6 +21,7 @@ export const normalizeDispatchCommand = (command: ClientOrchestrationCommand) =>
     const path = yield* Path.Path;
     const serverConfig = yield* ServerConfig;
     const workspacePaths = yield* WorkspacePaths;
+    const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
 
     const normalizeProjectWorkspaceRoot = (workspaceRoot: string) =>
       workspacePaths.normalizeWorkspaceRoot(workspaceRoot).pipe(
@@ -47,21 +50,93 @@ export const normalizeDispatchCommand = (command: ClientOrchestrationCommand) =>
           ),
         );
 
+    const isSamePath = (left: string, right: string) => {
+      const relative = path.relative(left, right);
+      return relative.length === 0;
+    };
+
+    const normalizeAdditionalWorkspaceRoots = (
+      roots: ReadonlyArray<string> | undefined,
+      primaryWorkspaceRoot: string | undefined,
+    ) =>
+      Effect.gen(function* () {
+        if (roots === undefined) {
+          return undefined;
+        }
+
+        const normalizedRoots = yield* Effect.forEach(roots, normalizeProjectWorkspaceRoot, {
+          concurrency: 4,
+        });
+        const uniqueRoots: string[] = [];
+        for (const normalizedRoot of normalizedRoots) {
+          if (
+            primaryWorkspaceRoot !== undefined &&
+            isSamePath(normalizedRoot, primaryWorkspaceRoot)
+          ) {
+            continue;
+          }
+          if (!uniqueRoots.some((existingRoot) => isSamePath(existingRoot, normalizedRoot))) {
+            uniqueRoots.push(normalizedRoot);
+          }
+        }
+        return uniqueRoots;
+      });
+
     if (command.type === "project.create") {
+      const workspaceRoot = yield* normalizeProjectWorkspaceRootForCreate(
+        command.workspaceRoot,
+        command.createWorkspaceRootIfMissing,
+      );
       return {
         ...command,
-        workspaceRoot: yield* normalizeProjectWorkspaceRootForCreate(
-          command.workspaceRoot,
-          command.createWorkspaceRootIfMissing,
-        ),
+        workspaceRoot,
+        ...(command.additionalWorkspaceRoots !== undefined
+          ? {
+              additionalWorkspaceRoots: yield* normalizeAdditionalWorkspaceRoots(
+                command.additionalWorkspaceRoots,
+                workspaceRoot,
+              ),
+            }
+          : {}),
         createWorkspaceRootIfMissing: command.createWorkspaceRootIfMissing === true,
       } satisfies OrchestrationCommand;
     }
 
-    if (command.type === "project.meta.update" && command.workspaceRoot !== undefined) {
+    if (
+      command.type === "project.meta.update" &&
+      (command.workspaceRoot !== undefined || command.additionalWorkspaceRoots !== undefined)
+    ) {
+      const workspaceRoot =
+        command.workspaceRoot !== undefined
+          ? yield* normalizeProjectWorkspaceRoot(command.workspaceRoot)
+          : Option.match(
+              yield* projectionSnapshotQuery.getProjectShellById(command.projectId).pipe(
+                Effect.mapError(
+                  (cause) =>
+                    new OrchestrationDispatchCommandError({
+                      message: "Failed to load project before updating additional directories.",
+                      cause,
+                    }),
+                ),
+              ),
+              {
+                onNone: () => undefined,
+                onSome: (project) => project.workspaceRoot,
+              },
+            );
       return {
         ...command,
-        workspaceRoot: yield* normalizeProjectWorkspaceRoot(command.workspaceRoot),
+        ...(command.workspaceRoot !== undefined && workspaceRoot !== undefined
+          ? { workspaceRoot }
+          : {}),
+        ...(command.additionalWorkspaceRoots !== undefined
+          ? {
+              additionalWorkspaceRoots: yield* normalizeAdditionalWorkspaceRoots(
+                command.additionalWorkspaceRoots,
+                workspaceRoot,
+              ),
+            }
+          : {}),
       } satisfies OrchestrationCommand;
     }
 
diff --git a/apps/server/src/orchestration/decider.ts b/apps/server/src/orchestration/decider.ts
index 178a8a7a..aacedfd7 100644
--- a/apps/server/src/orchestration/decider.ts
+++ b/apps/server/src/orchestration/decider.ts
@@ -103,6 +103,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
           projectId: command.projectId,
           title: command.title,
           workspaceRoot: command.workspaceRoot,
+          additionalWorkspaceRoots: command.additionalWorkspaceRoots ?? [],
           defaultModelSelection: command.defaultModelSelection ?? null,
           scripts: [],
           createdAt: command.createdAt,
@@ -130,6 +131,9 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
           projectId: command.projectId,
           ...(command.title !== undefined ? { title: command.title } : {}),
           ...(command.workspaceRoot !== undefined ? { workspaceRoot: command.workspaceRoot } : {}),
+          ...(command.additionalWorkspaceRoots !== undefined
+            ? { additionalWorkspaceRoots: command.additionalWorkspaceRoots }
+            : {}),
           ...(command.defaultModelSelection !== undefined
             ? { defaultModelSelection: command.defaultModelSelection }
             : {}),
diff --git a/apps/server/src/orchestration/projector.ts b/apps/server/src/orchestration/projector.ts
index 7b2a5785..664bdf6b 100644
--- a/apps/server/src/orchestration/projector.ts
+++ b/apps/server/src/orchestration/projector.ts
@@ -184,6 +184,7 @@ export function projectEvent(
             id: payload.projectId,
             title: payload.title,
             workspaceRoot: payload.workspaceRoot,
+            additionalWorkspaceRoots: payload.additionalWorkspaceRoots ?? [],
             defaultModelSelection: payload.defaultModelSelection,
             scripts: payload.scripts,
             createdAt: payload.createdAt,
@@ -214,6 +215,9 @@ export function projectEvent(
                   ...(payload.workspaceRoot !== undefined
                     ? { workspaceRoot: payload.workspaceRoot }
                     : {}),
+                  ...(payload.additionalWorkspaceRoots !== undefined
+                    ? { additionalWorkspaceRoots: payload.additionalWorkspaceRoots }
+                    : {}),
                   ...(payload.defaultModelSelection !== undefined
                     ? { defaultModelSelection: payload.defaultModelSelection }
                     : {}),
diff --git a/apps/server/src/persistence/Layers/ProjectionProjects.ts b/apps/server/src/persistence/Layers/ProjectionProjects.ts
index 7f5cbd33..07fec6be 100644
--- a/apps/server/src/persistence/Layers/ProjectionProjects.ts
+++ b/apps/server/src/persistence/Layers/ProjectionProjects.ts
@@ -5,7 +5,7 @@ import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
 import * as Struct from "effect/Struct";
 
-import { ModelSelection, ProjectScript } from "@cafecode/contracts";
+import { AdditionalWorkspaceRoots, ModelSelection, ProjectScript } from "@cafecode/contracts";
 import { toPersistenceSqlError } from "../Errors.ts";
 import {
   DeleteProjectionProjectInput,
@@ -17,6 +17,7 @@ import {
 
 const ProjectionProjectDbRow = ProjectionProject.mapFields(
   Struct.assign({
+    additionalWorkspaceRoots: Schema.fromJsonString(AdditionalWorkspaceRoots),
     defaultModelSelection: Schema.NullOr(Schema.fromJsonString(ModelSelection)),
     scripts: Schema.fromJsonString(Schema.Array(ProjectScript)),
   }),
@@ -34,6 +35,7 @@ const makeProjectionProjectRepository = Effect.gen(function* () {
           project_id,
           title,
           workspace_root,
+          additional_workspace_roots_json,
           default_model_selection_json,
           scripts_json,
           created_at,
@@ -44,6 +46,7 @@ const makeProjectionProjectRepository = Effect.gen(function* () {
           ${row.projectId},
           ${row.title},
           ${row.workspaceRoot},
+          ${JSON.stringify(row.additionalWorkspaceRoots)},
           ${row.defaultModelSelection !== null ? JSON.stringify(row.defaultModelSelection) : null},
           ${JSON.stringify(row.scripts)},
           ${row.createdAt},
@@ -54,6 +57,7 @@ const makeProjectionProjectRepository = Effect.gen(function* () {
         DO UPDATE SET
           title = excluded.title,
           workspace_root = excluded.workspace_root,
+          additional_workspace_roots_json = excluded.additional_workspace_roots_json,
           default_model_selection_json = excluded.default_model_selection_json,
           scripts_json = excluded.scripts_json,
           created_at = excluded.created_at,
@@ -71,6 +75,7 @@ const makeProjectionProjectRepository = Effect.gen(function* () {
           project_id AS "projectId",
           title,
           workspace_root AS "workspaceRoot",
+          additional_workspace_roots_json AS "additionalWorkspaceRoots",
           default_model_selection_json AS "defaultModelSelection",
           scripts_json AS "scripts",
           created_at AS "createdAt",
@@ -90,6 +95,7 @@ const makeProjectionProjectRepository = Effect.gen(function* () {
           project_id AS "projectId",
           title,
           workspace_root AS "workspaceRoot",
+          additional_workspace_roots_json AS "additionalWorkspaceRoots",
           default_model_selection_json AS "defaultModelSelection",
           scripts_json AS "scripts",
           created_at AS "createdAt",
diff --git a/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts b/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts
index f43f66aa..9ecf7c09 100644
--- a/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts
+++ b/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts
@@ -29,6 +29,7 @@ projectionRepositoriesLayer("Projection repositories", (it) => {
         projectId: ProjectId.make("project-null-options"),
         title: "Null options project",
         workspaceRoot: "/tmp/project-null-options",
+        additionalWorkspaceRoots: [],
         defaultModelSelection: {
           instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5.4",
diff --git a/apps/server/src/persistence/Migrations.ts b/apps/server/src/persistence/Migrations.ts
index 31e010e9..b387e0a1 100644
--- a/apps/server/src/persistence/Migrations.ts
+++ b/apps/server/src/persistence/Migrations.ts
@@ -46,6 +46,7 @@ import Migration0030 from "./Migrations/030_ProjectionThreadShellArchiveIndexes.
 import Migration0031 from "./Migrations/031_ProjectionThreadMessageThreadScopedIdentity.ts";
 import Migration0032 from "./Migrations/032_ReconcileCompletedThreadSessions.ts";
 import Migration0033 from "./Migrations/033_ReopenActiveTurnsWithPostCompletionActivity.ts";
+import Migration0034 from "./Migrations/034_ProjectionProjectsAdditionalWorkspaceRoots.ts";
 
 /**
  * Migration loader with all migrations defined inline.
@@ -91,6 +92,7 @@ export const migrationEntries = [
   [31, "ProjectionThreadMessageThreadScopedIdentity", Migration0031],
   [32, "ReconcileCompletedThreadSessions", Migration0032],
   [33, "ReopenActiveTurnsWithPostCompletionActivity", Migration0033],
+  [34, "ProjectionProjectsAdditionalWorkspaceRoots", Migration0034],
 ] as const;
 
 export const makeMigrationLoader = (throughId?: number) =>
diff --git a/apps/server/src/persistence/Migrations/005_Projections.ts b/apps/server/src/persistence/Migrations/005_Projections.ts
index c950da76..42fafce6 100644
--- a/apps/server/src/persistence/Migrations/005_Projections.ts
+++ b/apps/server/src/persistence/Migrations/005_Projections.ts
@@ -9,6 +9,7 @@ export default Effect.gen(function* () {
       project_id TEXT PRIMARY KEY,
       title TEXT NOT NULL,
       workspace_root TEXT NOT NULL,
+      additional_workspace_roots_json TEXT NOT NULL DEFAULT '[]',
       default_model TEXT,
       scripts_json TEXT NOT NULL,
       created_at TEXT NOT NULL,
diff --git a/apps/server/src/persistence/Migrations/034_ProjectionProjectsAdditionalWorkspaceRoots.test.ts b/apps/server/src/persistence/Migrations/034_ProjectionProjectsAdditionalWorkspaceRoots.test.ts
new file mode 100644
index 00000000..dc21d974
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/034_ProjectionProjectsAdditionalWorkspaceRoots.test.ts
@@ -0,0 +1,51 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+import { runMigrations } from "../Migrations.ts";
+import * as NodeSqliteClient from "../NodeSqliteClient.ts";
+
+const layer = it.layer(Layer.mergeAll(NodeSqliteClient.layerMemory()));
+
+layer("034_ProjectionProjectsAdditionalWorkspaceRoots", (it) => {
+  it.effect("adds additional workspace roots with an empty-array default", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* runMigrations({ toMigrationInclusive: 33 });
+      yield* sql`
+        INSERT INTO projection_projects (
+          project_id,
+          title,
+          workspace_root,
+          default_model_selection_json,
+          scripts_json,
+          created_at,
+          updated_at,
+          deleted_at
+        )
+        VALUES (
+          'project-before-034',
+          'Project',
+          '/tmp/project-before-034',
+          NULL,
+          '[]',
+          '2026-05-23T00:00:00.000Z',
+          '2026-05-23T00:00:00.000Z',
+          NULL
+        )
+      `;
+
+      yield* runMigrations({ toMigrationInclusive: 34 });
+
+      const rows = yield* sql<{ readonly additionalWorkspaceRoots: string }>`
+        SELECT additional_workspace_roots_json AS "additionalWorkspaceRoots"
+        FROM projection_projects
+        WHERE project_id = 'project-before-034'
+      `;
+
+      assert.deepStrictEqual(rows, [{ additionalWorkspaceRoots: "[]" }]);
+    }),
+  );
+});
diff --git a/apps/server/src/persistence/Migrations/034_ProjectionProjectsAdditionalWorkspaceRoots.ts b/apps/server/src/persistence/Migrations/034_ProjectionProjectsAdditionalWorkspaceRoots.ts
new file mode 100644
index 00000000..ef1c3c38
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/034_ProjectionProjectsAdditionalWorkspaceRoots.ts
@@ -0,0 +1,18 @@
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const columns = yield* sql<{ readonly name: string }>`
+    PRAGMA table_info(projection_projects)
+  `;
+
+  if (columns.some((column) => column.name === "additional_workspace_roots_json")) {
+    return;
+  }
+
+  yield* sql`
+    ALTER TABLE projection_projects
+    ADD COLUMN additional_workspace_roots_json TEXT NOT NULL DEFAULT '[]'
+  `;
+});
diff --git a/apps/server/src/persistence/Services/ProjectionProjects.ts b/apps/server/src/persistence/Services/ProjectionProjects.ts
index ab3d3dca..da08bae9 100644
--- a/apps/server/src/persistence/Services/ProjectionProjects.ts
+++ b/apps/server/src/persistence/Services/ProjectionProjects.ts
@@ -6,7 +6,13 @@
  *
  * @module ProjectionProjectRepository
  */
-import { IsoDateTime, ModelSelection, ProjectId, ProjectScript } from "@cafecode/contracts";
+import {
+  AdditionalWorkspaceRoots,
+  IsoDateTime,
+  ModelSelection,
+  ProjectId,
+  ProjectScript,
+} from "@cafecode/contracts";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 import * as Context from "effect/Context";
@@ -18,6 +24,7 @@ export const ProjectionProject = Schema.Struct({
   projectId: ProjectId,
   title: Schema.String,
   workspaceRoot: Schema.String,
+  additionalWorkspaceRoots: AdditionalWorkspaceRoots,
   defaultModelSelection: Schema.NullOr(ModelSelection),
   scripts: Schema.Array(ProjectScript),
   createdAt: IsoDateTime,
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
index 6c008a63..1587381e 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
@@ -380,6 +380,31 @@ describe("ClaudeAdapterLive", () => {
     );
   });
 
+  it.effect("forwards cwd and additional directories into claude query options", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const session = yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        cwd: "/tmp/project",
+        additionalDirectories: ["/tmp/docs", "/tmp/tools"],
+        runtimeMode: "full-access",
+      });
+
+      const createInput = harness.getLastCreateQueryInput();
+      assert.deepEqual(createInput?.options.additionalDirectories, [
+        "/tmp/project",
+        "/tmp/docs",
+        "/tmp/tools",
+      ]);
+      assert.deepEqual(session.additionalDirectories, ["/tmp/docs", "/tmp/tools"]);
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
   it.effect("runs Claude SDK sessions with the configured Claude HOME", () => {
     const harness = makeHarness({ claudeConfig: { homePath: "~/.claude-work" } });
     return Effect.gen(function* () {
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.ts b/apps/server/src/provider/Layers/ClaudeAdapter.ts
index c766e255..3119fad7 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.ts
@@ -3110,6 +3110,11 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         ...(typeof thinking === "boolean" ? { alwaysThinkingEnabled: thinking } : {}),
         ...(fastMode ? { fastMode: true } : {}),
       };
+      const claudeAdditionalDirectories = [
+        ...(input.cwd ? [input.cwd] : []),
+        ...(input.additionalDirectories ?? []),
+      ].filter((directory, index, directories) => directories.indexOf(directory) === index);
+
       const queryOptions: ClaudeQueryOptions = {
         ...(input.cwd ? { cwd: input.cwd } : {}),
         ...(apiModelId ? { model: apiModelId } : {}),
@@ -3133,7 +3138,9 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         includePartialMessages: true,
         canUseTool,
         env: claudeEnvironment,
-        ...(input.cwd ? { additionalDirectories: [input.cwd] } : {}),
+        ...(claudeAdditionalDirectories.length > 0
+          ? { additionalDirectories: [...claudeAdditionalDirectories] }
+          : {}),
         ...(Object.keys(extraArgs).length > 0 ? { extraArgs } : {}),
       };
 
@@ -3155,7 +3162,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         "claude.query.resume": existingResumeSessionId ?? "",
         "claude.query.session_id": newSessionId ?? "",
         "claude.query.include_partial_messages": true,
-        "claude.query.additional_directories": input.cwd ? [input.cwd] : [],
+        "claude.query.additional_directories": claudeAdditionalDirectories,
         "claude.query.setting_sources": [...CLAUDE_SETTING_SOURCES],
         "claude.query.settings_json": encodeJsonStringForDiagnostics(settings) ?? "",
         "claude.query.extra_args_json": encodeJsonStringForDiagnostics(extraArgs) ?? "",
@@ -3203,6 +3210,9 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         status: "ready",
         runtimeMode: input.runtimeMode,
         ...(input.cwd ? { cwd: input.cwd } : {}),
+        ...(input.additionalDirectories !== undefined
+          ? { additionalDirectories: input.additionalDirectories }
+          : {}),
         ...(modelSelection?.model ? { model: modelSelection.model } : {}),
         ...(threadId ? { threadId } : {}),
         ...(initialResumeCursor !== undefined ? { resumeCursor: initialResumeCursor } : {}),
diff --git a/apps/server/src/provider/Layers/CodexAdapter.ts b/apps/server/src/provider/Layers/CodexAdapter.ts
index 47a8cd09..f41f2f6d 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.ts
@@ -1405,6 +1405,9 @@ export const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
           threadId: input.threadId,
           providerInstanceId: boundInstanceId,
           cwd: input.cwd ?? process.cwd(),
+          ...(input.additionalDirectories !== undefined
+            ? { additionalDirectories: input.additionalDirectories }
+            : {}),
           binaryPath: codexConfig.binaryPath,
           ...(options?.environment ? { environment: options.environment } : {}),
           ...(codexConfig.homePath ? { homePath: codexConfig.homePath } : {}),
diff --git a/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts b/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
index 644249e1..afc0bf11 100644
--- a/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
+++ b/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
@@ -147,6 +147,22 @@ describe("buildTurnStartParams", () => {
       ],
     });
   });
+
+  it("includes additional directories as workspace-write writable roots", () => {
+    const params = Effect.runSync(
+      buildTurnStartParams({
+        threadId: "provider-thread-1",
+        runtimeMode: "auto-accept-edits",
+        prompt: "Implement it",
+        additionalDirectories: ["/tmp/docs", "/tmp/tools"],
+      }),
+    );
+
+    assert.deepStrictEqual(params.sandboxPolicy, {
+      type: "workspaceWrite",
+      writableRoots: ["/tmp/docs", "/tmp/tools"],
+    });
+  });
 });
 
 describe("isRecoverableThreadResumeError", () => {
diff --git a/apps/server/src/provider/Layers/CodexSessionRuntime.ts b/apps/server/src/provider/Layers/CodexSessionRuntime.ts
index 2b521fce..eb8df4ba 100644
--- a/apps/server/src/provider/Layers/CodexSessionRuntime.ts
+++ b/apps/server/src/provider/Layers/CodexSessionRuntime.ts
@@ -102,6 +102,7 @@ export interface CodexSessionRuntimeOptions {
   readonly runtimeMode: RuntimeMode;
   readonly model?: string;
   readonly serviceTier?: CodexServiceTier | undefined;
+  readonly additionalDirectories?: ReadonlyArray<string> | undefined;
   readonly resumeCursor?: CodexResumeCursor;
 }
 
@@ -115,6 +116,7 @@ export interface CodexSessionRuntimeSendTurnInput {
   readonly serviceTier?: CodexServiceTier | undefined;
   readonly effort?: EffectCodexSchema.V2TurnStartParams__ReasoningEffort | undefined;
   readonly interactionMode?: ProviderInteractionMode;
+  readonly additionalDirectories?: ReadonlyArray<string> | undefined;
 }
 
 export interface CodexThreadTurnSnapshot {
@@ -287,12 +289,24 @@ function buildThreadStartParams(input: {
   readonly runtimeMode: RuntimeMode;
   readonly model: string | undefined;
   readonly serviceTier: CodexServiceTier | undefined;
+  readonly additionalDirectories?: ReadonlyArray<string> | undefined;
 }): EffectCodexSchema.V2ThreadStartParams {
   const config = runtimeModeToThreadConfig(input.runtimeMode);
+  const workspaceWriteConfig =
+    input.runtimeMode === "auto-accept-edits" && input.additionalDirectories?.length
+      ? {
+          config: {
+            sandbox_workspace_write: {
+              writable_roots: input.additionalDirectories,
+            },
+          },
+        }
+      : {};
   return {
     cwd: input.cwd,
     approvalPolicy: config.approvalPolicy,
     sandbox: config.sandbox,
+    ...workspaceWriteConfig,
     ...(input.model ? { model: input.model } : {}),
     ...(input.serviceTier ? { serviceTier: input.serviceTier } : {}),
   };
@@ -300,6 +314,7 @@ function buildThreadStartParams(input: {
 
 function runtimeModeToTurnSandboxPolicy(
   input: RuntimeMode,
+  additionalDirectories: ReadonlyArray<string> = [],
 ): EffectCodexSchema.V2TurnStartParams__SandboxPolicy {
   switch (input) {
     case "approval-required":
@@ -309,6 +324,7 @@ function runtimeModeToTurnSandboxPolicy(
     case "auto-accept-edits":
       return {
         type: "workspaceWrite",
+        ...(additionalDirectories.length > 0 ? { writableRoots: additionalDirectories } : {}),
       };
     case "full-access":
     default:
@@ -352,6 +368,7 @@ export function buildTurnStartParams(input: {
   readonly serviceTier?: CodexServiceTier;
   readonly effort?: EffectCodexSchema.V2TurnStartParams__ReasoningEffort;
   readonly interactionMode?: ProviderInteractionMode;
+  readonly additionalDirectories?: ReadonlyArray<string> | undefined;
 }): Effect.Effect<
   CodexTurnStartParamsWithCollaborationMode,
   CodexErrors.CodexAppServerProtocolParseError
@@ -378,7 +395,10 @@ export function buildTurnStartParams(input: {
     threadId: input.threadId,
     input: turnInput,
     approvalPolicy: config.approvalPolicy,
-    sandboxPolicy: runtimeModeToTurnSandboxPolicy(input.runtimeMode),
+    sandboxPolicy: runtimeModeToTurnSandboxPolicy(
+      input.runtimeMode,
+      input.additionalDirectories ?? [],
+    ),
     ...(input.model ? { model: input.model } : {}),
     ...(input.serviceTier ? { serviceTier: input.serviceTier } : {}),
     ...(input.effort ? { effort: input.effort } : {}),
@@ -437,6 +457,7 @@ export const openCodexThread = (input: {
   readonly requestedModel: string | undefined;
   readonly serviceTier: CodexServiceTier | undefined;
   readonly resumeThreadId: string | undefined;
+  readonly additionalDirectories?: ReadonlyArray<string> | undefined;
 }): Effect.Effect<CodexThreadOpenResponse, CodexErrors.CodexAppServerError> => {
   const resumeThreadId = input.resumeThreadId;
   const startParams = buildThreadStartParams({
@@ -444,6 +465,7 @@ export const openCodexThread = (input: {
     runtimeMode: input.runtimeMode,
     model: input.requestedModel,
     serviceTier: input.serviceTier,
+    additionalDirectories: input.additionalDirectories,
   });
 
   if (resumeThreadId === undefined) {
@@ -754,6 +776,9 @@ export const makeCodexSessionRuntime = (
       status: "connecting",
       runtimeMode: options.runtimeMode,
       cwd: options.cwd,
+      ...(options.additionalDirectories !== undefined
+        ? { additionalDirectories: options.additionalDirectories }
+        : {}),
       ...(options.model ? { model: options.model } : {}),
       threadId: options.threadId,
       ...(options.resumeCursor !== undefined ? { resumeCursor: options.resumeCursor } : {}),
@@ -1191,6 +1216,7 @@ export const makeCodexSessionRuntime = (
         cwd: options.cwd,
         requestedModel,
         serviceTier: options.serviceTier,
+        additionalDirectories: options.additionalDirectories,
         resumeThreadId: readResumeCursorThreadId(options.resumeCursor),
       });
 
@@ -1199,6 +1225,9 @@ export const makeCodexSessionRuntime = (
         ...(yield* Ref.get(sessionRef)),
         status: "ready",
         cwd: opened.cwd,
+        ...(options.additionalDirectories !== undefined
+          ? { additionalDirectories: options.additionalDirectories }
+          : {}),
         model: opened.model,
         resumeCursor: { threadId: providerThreadId },
         updatedAt: yield* nowIso,
@@ -1253,6 +1282,8 @@ export const makeCodexSessionRuntime = (
             ...(input.serviceTier ? { serviceTier: input.serviceTier } : {}),
             ...(input.effort ? { effort: input.effort } : {}),
             ...(input.interactionMode ? { interactionMode: input.interactionMode } : {}),
+            additionalDirectories:
+              input.additionalDirectories ?? options.additionalDirectories ?? [],
           });
           const rawResponse = yield* client.raw.request("turn/start", params);
           const response = yield* decodeV2TurnStartResponse(rawResponse).pipe(
diff --git a/apps/server/src/provider/Layers/ProviderService.ts b/apps/server/src/provider/Layers/ProviderService.ts
index 7ee12f92..d89de962 100644
--- a/apps/server/src/provider/Layers/ProviderService.ts
+++ b/apps/server/src/provider/Layers/ProviderService.ts
@@ -129,6 +129,7 @@ function toRuntimePayloadFromSession(
 ): Record<string, unknown> {
   return {
     cwd: session.cwd ?? null,
+    additionalDirectories: session.additionalDirectories ?? [],
     model: session.model ?? null,
     activeTurnId: session.activeTurnId ?? null,
     lastError: session.lastError ?? null,
@@ -162,6 +163,23 @@ function readPersistedCwd(
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
+function readPersistedAdditionalDirectories(
+  runtimePayload: ProviderRuntimeBinding["runtimePayload"],
+): ReadonlyArray<string> | undefined {
+  if (!runtimePayload || typeof runtimePayload !== "object" || Array.isArray(runtimePayload)) {
+    return undefined;
+  }
+  const rawDirectories =
+    "additionalDirectories" in runtimePayload ? runtimePayload.additionalDirectories : undefined;
+  if (!Array.isArray(rawDirectories)) {
+    return undefined;
+  }
+  const directories = rawDirectories.filter(
+    (entry): entry is string => typeof entry === "string" && entry.trim().length > 0,
+  );
+  return directories.length > 0 ? directories : [];
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -502,6 +520,9 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
       }
 
       const persistedCwd = readPersistedCwd(input.binding.runtimePayload);
+      const persistedAdditionalDirectories = readPersistedAdditionalDirectories(
+        input.binding.runtimePayload,
+      );
       const persistedModelSelection = readPersistedModelSelection(input.binding.runtimePayload);
 
       const resumed = yield* adapter.startSession({
@@ -509,6 +530,9 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         provider: input.binding.provider,
         providerInstanceId: bindingInstanceId,
         ...(persistedCwd ? { cwd: persistedCwd } : {}),
+        ...(persistedAdditionalDirectories !== undefined
+          ? { additionalDirectories: persistedAdditionalDirectories }
+          : {}),
         ...(persistedModelSelection ? { modelSelection: persistedModelSelection } : {}),
         ...(hasResumeCursor ? { resumeCursor: input.binding.resumeCursor } : {}),
         runtimeMode: input.binding.runtimeMode ?? "full-access",
@@ -673,6 +697,11 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
           (persistedBinding?.providerInstanceId === resolvedInstanceId
             ? readPersistedCwd(persistedBinding.runtimePayload)
             : undefined);
+        const effectiveAdditionalDirectories =
+          input.additionalDirectories ??
+          (persistedBinding?.providerInstanceId === resolvedInstanceId
+            ? readPersistedAdditionalDirectories(persistedBinding.runtimePayload)
+            : undefined);
         yield* Effect.annotateCurrentSpan({
           "provider.kind": resolvedProvider,
           "provider.resume_cursor.source":
@@ -691,12 +720,16 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
                 ? "persisted"
                 : "none",
           "provider.cwd.effective": effectiveCwd ?? "",
+          "provider.additional_directories.count": effectiveAdditionalDirectories?.length ?? 0,
         });
         const adapter = yield* registry.getByInstance(resolvedInstanceId);
         const session = yield* adapter.startSession({
           ...input,
           providerInstanceId: resolvedInstanceId,
           ...(effectiveCwd !== undefined ? { cwd: effectiveCwd } : {}),
+          ...(effectiveAdditionalDirectories !== undefined
+            ? { additionalDirectories: effectiveAdditionalDirectories }
+            : {}),
           ...(effectiveResumeCursor !== undefined ? { resumeCursor: effectiveResumeCursor } : {}),
         });
 
@@ -709,6 +742,9 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         const sessionWithInstance = {
           ...session,
           providerInstanceId: resolvedInstanceId,
+          ...(effectiveAdditionalDirectories !== undefined
+            ? { additionalDirectories: effectiveAdditionalDirectories }
+            : {}),
         };
 
         yield* stopStaleSessionsForThread({
diff --git a/apps/web/src/components/ChatMarkdown.tsx b/apps/web/src/components/ChatMarkdown.tsx
index 5c87e28d..cc3772c7 100644
--- a/apps/web/src/components/ChatMarkdown.tsx
+++ b/apps/web/src/components/ChatMarkdown.tsx
@@ -60,6 +60,7 @@ class CodeHighlightErrorBoundary extends React.Component<
 interface ChatMarkdownProps {
   text: string;
   cwd: string | undefined;
+  additionalWorkspaceRoots?: ReadonlyArray<string>;
   isStreaming?: boolean;
   skills?: ReadonlyArray<Pick<ServerProviderSkill, "name" | "displayName">>;
 }
@@ -594,6 +595,7 @@ function areMarkdownFileLinkPropsEqual(
 function ChatMarkdown({
   text,
   cwd,
+  additionalWorkspaceRoots = [],
   isStreaming = false,
   skills = EMPTY_MARKDOWN_SKILLS,
 }: ChatMarkdownProps) {
@@ -607,13 +609,13 @@ function ChatMarkdown({
     for (const href of extractMarkdownLinkHrefs(text)) {
       const normalizedHref = normalizeMarkdownLinkHrefKey(href);
       if (metaByHref.has(normalizedHref)) continue;
-      const meta = resolveMarkdownFileLinkMeta(normalizedHref, cwd);
+      const meta = resolveMarkdownFileLinkMeta(normalizedHref, cwd, additionalWorkspaceRoots);
       if (meta) {
         metaByHref.set(normalizedHref, meta);
       }
     }
     return metaByHref;
-  }, [cwd, text]);
+  }, [additionalWorkspaceRoots, cwd, text]);
   const fileLinkParentSuffixByPath = useMemo(() => {
     const filePaths = [...markdownFileLinkMetaByHref.values()].map((meta) => meta.filePath);
     return buildFileLinkParentSuffixByPath(filePaths);
diff --git a/apps/web/src/components/ChatView.browser.tsx b/apps/web/src/components/ChatView.browser.tsx
index 3da9427b..b7aee005 100644
--- a/apps/web/src/components/ChatView.browser.tsx
+++ b/apps/web/src/components/ChatView.browser.tsx
@@ -308,6 +308,7 @@ function createSnapshotForTargetUser(options: {
         id: PROJECT_ID,
         title: "Project",
         workspaceRoot: "/repo/project",
+        additionalWorkspaceRoots: [],
         defaultModelSelection: {
           instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
@@ -793,6 +794,7 @@ function createSnapshotWithSecondaryProject(options?: {
         id: SECOND_PROJECT_ID,
         title: "Docs Portal",
         workspaceRoot: "/repo/clients/docs-portal",
+        additionalWorkspaceRoots: [],
         defaultModelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
         scripts: [],
         createdAt: NOW_ISO,
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index c33d25be..e25d205a 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -4103,6 +4103,7 @@ export default function ChatView(props: ChatViewProps) {
               isRevertingCheckpoint={isRevertingCheckpoint}
               onImageExpand={onExpandTimelineImage}
               markdownCwd={gitCwd ?? undefined}
+              additionalWorkspaceRoots={activeProject?.additionalWorkspaceRoots ?? []}
               timestampFormat={timestampFormat}
               workspaceRoot={activeWorkspaceRoot}
               skills={activeProviderStatus?.skills ?? EMPTY_PROVIDER_SKILLS}
diff --git a/apps/web/src/components/KeybindingsToast.browser.tsx b/apps/web/src/components/KeybindingsToast.browser.tsx
index 7ffe4f34..075b7a3b 100644
--- a/apps/web/src/components/KeybindingsToast.browser.tsx
+++ b/apps/web/src/components/KeybindingsToast.browser.tsx
@@ -143,6 +143,7 @@ function createMinimalSnapshot(): OrchestrationReadModel {
         id: PROJECT_ID,
         title: "Project",
         workspaceRoot: "/repo/project",
+        additionalWorkspaceRoots: [],
         defaultModelSelection: {
           instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 845ab02a..ebfa4597 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -4,9 +4,11 @@ import {
   ChevronRightIcon,
   CloudIcon,
   FolderPlusIcon,
+  PlusIcon,
   SearchIcon,
   SettingsIcon,
   SquarePenIcon,
+  Trash2Icon,
   TriangleAlertIcon,
 } from "lucide-react";
 import {
@@ -208,6 +210,17 @@ const SIDEBAR_LIST_ANIMATION_OPTIONS = {
 } as const;
 const SIDEBAR_BRAND_ICON_SRC = "/cafe-code-sidebar-icon.png";
 const EMPTY_THREAD_JUMP_LABELS = new Map<string, string>();
+const PATH_SEPARATOR_REGEX = /[/\\]+/g;
+
+function normalizePathForComparison(pathValue: string): string {
+  return pathValue.trim().replace(PATH_SEPARATOR_REGEX, "/").replace(/\/+$/, "");
+}
+
+function pathContainsPath(parentPath: string, childPath: string): boolean {
+  const parent = normalizePathForComparison(parentPath);
+  const child = normalizePathForComparison(childPath);
+  return child.startsWith(`${parent}/`);
+}
 const PROJECT_GROUPING_MODE_LABELS: Record<SidebarProjectGroupingMode, string> = {
   repository: "Group by repository",
   repository_path: "Group by repository path",
@@ -1055,6 +1068,12 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
   const [projectGroupingSelection, setProjectGroupingSelection] = useState<
     SidebarProjectGroupingMode | "inherit"
   >("inherit");
+  const [additionalDirectoriesTarget, setAdditionalDirectoriesTarget] =
+    useState<SidebarProjectGroupMember | null>(null);
+  const [additionalDirectoriesDraft, setAdditionalDirectoriesDraft] = useState<string[]>([]);
+  const [additionalDirectoryInput, setAdditionalDirectoryInput] = useState("");
+  const [additionalDirectoriesError, setAdditionalDirectoriesError] = useState<string | null>(null);
+  const [additionalDirectoriesSubmitting, setAdditionalDirectoriesSubmitting] = useState(false);
   const [threadMoveTarget, setThreadMoveTarget] = useState<SidebarThreadSummary | null>(null);
   const [threadMoveProjectId, setThreadMoveProjectId] = useState<ProjectId | null>(null);
   const [threadMoveSubmitting, setThreadMoveSubmitting] = useState(false);
@@ -1265,6 +1284,13 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     setProjectRenameTitle(member.name);
   }, []);
 
+  const openAdditionalDirectoriesDialog = useCallback((member: SidebarProjectGroupMember) => {
+    setAdditionalDirectoriesTarget(member);
+    setAdditionalDirectoriesDraft([...(member.additionalWorkspaceRoots ?? [])]);
+    setAdditionalDirectoryInput("");
+    setAdditionalDirectoriesError(null);
+  }, []);
+
   const openProjectGroupingDialog = useCallback(
     (member: SidebarProjectGroupMember) => {
       const overrideKey = deriveProjectGroupingOverrideKey(member);
@@ -1423,7 +1449,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
 
         const actionHandlers = new Map<string, () => Promise<void> | void>();
         const makeLeaf = (
-          action: "rename" | "grouping" | "copy-path" | "delete",
+          action: "rename" | "directories" | "grouping" | "copy-path" | "delete",
           member: SidebarProjectGroupMember,
           options?: {
             destructive?: boolean;
@@ -1436,6 +1462,9 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
               case "rename":
                 openProjectRenameDialog(member);
                 return;
+              case "directories":
+                openAdditionalDirectoriesDialog(member);
+                return;
               case "grouping":
                 openProjectGroupingDialog(member);
                 return;
@@ -1456,7 +1485,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         };
 
         const buildTargetedItem = (
-          action: "rename" | "grouping" | "copy-path" | "delete",
+          action: "rename" | "directories" | "grouping" | "copy-path" | "delete",
           label: string,
           options?: {
             destructive?: boolean;
@@ -1489,6 +1518,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         const clicked = await api.contextMenu.show(
           [
             buildTargetedItem("rename", "Rename project"),
+            buildTargetedItem("directories", "Configure additional directories…"),
             buildTargetedItem("grouping", "Project grouping…"),
             buildTargetedItem("copy-path", "Copy Project Path"),
             buildTargetedItem("delete", "Remove project", {
@@ -1511,6 +1541,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     [
       copyPathToClipboard,
       handleRemoveProject,
+      openAdditionalDirectoriesDialog,
       openProjectGroupingDialog,
       openProjectRenameDialog,
       project.groupedProjectCount,
@@ -1846,6 +1877,83 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     setProjectGroupingSelection("inherit");
   }, []);
 
+  const closeAdditionalDirectoriesDialog = useCallback(() => {
+    if (additionalDirectoriesSubmitting) {
+      return;
+    }
+    setAdditionalDirectoriesTarget(null);
+    setAdditionalDirectoriesDraft([]);
+    setAdditionalDirectoryInput("");
+    setAdditionalDirectoriesError(null);
+  }, [additionalDirectoriesSubmitting]);
+
+  const addAdditionalDirectoryDraft = useCallback((pathValue: string) => {
+    const trimmed = pathValue.trim();
+    if (trimmed.length === 0) {
+      return;
+    }
+    setAdditionalDirectoriesDraft((current) =>
+      current.some(
+        (entry) => normalizePathForComparison(entry) === normalizePathForComparison(trimmed),
+      )
+        ? current
+        : [...current, trimmed],
+    );
+    setAdditionalDirectoryInput("");
+    setAdditionalDirectoriesError(null);
+  }, []);
+
+  const browseAdditionalDirectory = useCallback(async () => {
+    if (!additionalDirectoriesTarget) {
+      return;
+    }
+    const api = readLocalApi();
+    if (!api) {
+      return;
+    }
+    const selectedPath = await api.dialogs.pickFolder({
+      initialPath: additionalDirectoriesTarget.cwd,
+    });
+    if (selectedPath) {
+      addAdditionalDirectoryDraft(selectedPath);
+    }
+  }, [addAdditionalDirectoryDraft, additionalDirectoriesTarget]);
+
+  const removeAdditionalDirectoryDraft = useCallback((indexToRemove: number) => {
+    setAdditionalDirectoriesDraft((current) =>
+      current.filter((_, index) => index !== indexToRemove),
+    );
+  }, []);
+
+  const submitAdditionalDirectories = useCallback(async () => {
+    if (!additionalDirectoriesTarget) {
+      return;
+    }
+    const api = readEnvironmentApi(additionalDirectoriesTarget.environmentId);
+    if (!api) {
+      setAdditionalDirectoriesError("Project API unavailable.");
+      return;
+    }
+
+    setAdditionalDirectoriesSubmitting(true);
+    setAdditionalDirectoriesError(null);
+    try {
+      await api.orchestration.dispatchCommand({
+        type: "project.meta.update",
+        commandId: newCommandId(),
+        projectId: additionalDirectoriesTarget.id,
+        additionalWorkspaceRoots: additionalDirectoriesDraft,
+      });
+      setAdditionalDirectoriesTarget(null);
+      setAdditionalDirectoriesDraft([]);
+      setAdditionalDirectoryInput("");
+    } catch (error) {
+      setAdditionalDirectoriesError(error instanceof Error ? error.message : "An error occurred.");
+    } finally {
+      setAdditionalDirectoriesSubmitting(false);
+    }
+  }, [additionalDirectoriesDraft, additionalDirectoriesTarget]);
+
   const closeThreadMoveDialog = useCallback(() => {
     setThreadMoveTarget(null);
     setThreadMoveProjectId(null);
@@ -2057,6 +2165,14 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     ],
   );
 
+  const additionalDirectoryWarnings = additionalDirectoriesDraft.flatMap((candidate, index) =>
+    additionalDirectoriesDraft.some(
+      (other, otherIndex) => otherIndex !== index && pathContainsPath(other, candidate),
+    )
+      ? [`${candidate} is inside another configured directory.`]
+      : [],
+  );
+
   return (
     <>
       <div className="group/project-header relative">
@@ -2236,6 +2352,126 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         </DialogPopup>
       </Dialog>
 
+      <Dialog
+        open={additionalDirectoriesTarget !== null}
+        onOpenChange={(open) => {
+          if (!open) {
+            closeAdditionalDirectoriesDialog();
+          }
+        }}
+      >
+        <DialogPopup className="max-w-2xl">
+          <DialogHeader>
+            <DialogTitle>Additional directories</DialogTitle>
+            <DialogDescription>
+              {additionalDirectoriesTarget
+                ? `Configure directories available to agents for ${additionalDirectoriesTarget.cwd}.`
+                : "Configure directories available to agents."}
+            </DialogDescription>
+          </DialogHeader>
+          <DialogPanel className="space-y-4">
+            <div className="grid gap-1.5">
+              <span className="text-xs font-medium text-foreground">Primary directory</span>
+              <div className="min-h-9 overflow-hidden rounded-md border bg-muted/30 px-3 py-2 text-xs text-muted-foreground">
+                <span className="block truncate">{additionalDirectoriesTarget?.cwd ?? ""}</span>
+              </div>
+            </div>
+
+            <div className="grid gap-2">
+              <span className="text-xs font-medium text-foreground">Additional directories</span>
+              {additionalDirectoriesDraft.length > 0 ? (
+                <div className="grid gap-2">
+                  {additionalDirectoriesDraft.map((directory, index) => (
+                    <div key={directory} className="flex min-w-0 items-center gap-2">
+                      <div className="min-w-0 flex-1 rounded-md border bg-background px-3 py-2 text-xs">
+                        <span className="block truncate">{directory}</span>
+                      </div>
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        aria-label={`Remove ${directory}`}
+                        onClick={() => removeAdditionalDirectoryDraft(index)}
+                      >
+                        <Trash2Icon className="size-4" />
+                      </Button>
+                    </div>
+                  ))}
+                </div>
+              ) : (
+                <p className="rounded-md border border-dashed px-3 py-4 text-xs text-muted-foreground">
+                  No additional directories configured.
+                </p>
+              )}
+            </div>
+
+            <div className="flex flex-col gap-2 sm:flex-row">
+              <Input
+                aria-label="Additional directory path"
+                value={additionalDirectoryInput}
+                placeholder="Absolute path"
+                onChange={(event) => setAdditionalDirectoryInput(event.target.value)}
+                onKeyDown={(event) => {
+                  if (event.key === "Enter") {
+                    event.preventDefault();
+                    addAdditionalDirectoryDraft(additionalDirectoryInput);
+                  }
+                }}
+              />
+              <div className="flex gap-2">
+                <Button
+                  type="button"
+                  variant="outline"
+                  onClick={() => addAdditionalDirectoryDraft(additionalDirectoryInput)}
+                >
+                  <PlusIcon className="size-4" />
+                  Add
+                </Button>
+                <Button
+                  type="button"
+                  variant="outline"
+                  onClick={() => void browseAdditionalDirectory()}
+                >
+                  <FolderPlusIcon className="size-4" />
+                  Browse
+                </Button>
+              </div>
+            </div>
+
+            {additionalDirectoryWarnings.length > 0 ? (
+              <Alert>
+                <TriangleAlertIcon className="size-4" />
+                <AlertTitle>Redundant directories</AlertTitle>
+                <AlertDescription>{additionalDirectoryWarnings.join(" ")}</AlertDescription>
+              </Alert>
+            ) : null}
+
+            {additionalDirectoriesError ? (
+              <Alert variant="error">
+                <TriangleAlertIcon className="size-4" />
+                <AlertTitle>Unable to save directories</AlertTitle>
+                <AlertDescription>{additionalDirectoriesError}</AlertDescription>
+              </Alert>
+            ) : null}
+          </DialogPanel>
+          <DialogFooter>
+            <Button
+              variant="outline"
+              onClick={closeAdditionalDirectoriesDialog}
+              disabled={additionalDirectoriesSubmitting}
+            >
+              Cancel
+            </Button>
+            <Button
+              onClick={() => void submitAdditionalDirectories()}
+              disabled={additionalDirectoriesSubmitting}
+            >
+              Save
+            </Button>
+          </DialogFooter>
+        </DialogPopup>
+      </Dialog>
+
       <Dialog
         open={projectGroupingTarget !== null}
         onOpenChange={(open) => {
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index afb95095..b4ef49a6 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -67,6 +67,7 @@ import { useServerAvailableEditors } from "../../rpc/serverState";
 interface TimelineRowSharedState {
   timestampFormat: TimestampFormat;
   markdownCwd: string | undefined;
+  additionalWorkspaceRoots: ReadonlyArray<string>;
   workspaceRoot: string | undefined;
   skills: ReadonlyArray<Pick<ServerProviderSkill, "name" | "displayName">>;
   activeThreadEnvironmentId: EnvironmentId;
@@ -131,6 +132,7 @@ interface MessagesTimelineProps {
   onImageExpand: (preview: ExpandedImagePreview) => void;
   activeThreadEnvironmentId: EnvironmentId;
   markdownCwd: string | undefined;
+  additionalWorkspaceRoots?: ReadonlyArray<string>;
   timestampFormat: TimestampFormat;
   workspaceRoot: string | undefined;
   skills?: ReadonlyArray<Pick<ServerProviderSkill, "name" | "displayName">>;
@@ -156,6 +158,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
   onImageExpand,
   activeThreadEnvironmentId,
   markdownCwd,
+  additionalWorkspaceRoots = [],
   timestampFormat,
   workspaceRoot,
   skills = EMPTY_TIMELINE_SKILLS,
@@ -228,6 +231,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
     () => ({
       timestampFormat,
       markdownCwd,
+      additionalWorkspaceRoots,
       workspaceRoot,
       skills,
       activeThreadEnvironmentId,
@@ -237,6 +241,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
     [
       timestampFormat,
       markdownCwd,
+      additionalWorkspaceRoots,
       workspaceRoot,
       skills,
       activeThreadEnvironmentId,
@@ -425,6 +430,7 @@ function AssistantTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "mess
         <ChatMarkdown
           text={messageText}
           cwd={ctx.markdownCwd}
+          additionalWorkspaceRoots={ctx.additionalWorkspaceRoots}
           isStreaming={Boolean(row.message.streaming)}
           skills={ctx.skills}
         />
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 9bd06084..73e7b4e7 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -346,6 +346,7 @@ describe("wsApi", () => {
         id: ProjectId.make("project-1"),
         title: "Project",
         workspaceRoot: "/tmp/workspace",
+        additionalWorkspaceRoots: [],
         defaultModelSelection: {
           instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
diff --git a/apps/web/src/markdown-links.test.ts b/apps/web/src/markdown-links.test.ts
index bb5c957f..58af096d 100644
--- a/apps/web/src/markdown-links.test.ts
+++ b/apps/web/src/markdown-links.test.ts
@@ -213,4 +213,19 @@ describe("markdown file link workspace policy", () => {
       isPathInsideWorkspace("/Users/julius/project/file.ts:4:2", "/Users/julius/project"),
     ).toBe(true);
   });
+
+  it("treats configured additional directories as direct-open workspace paths", () => {
+    expect(
+      isPathInsideWorkspace("/Users/julius/docs/README.md", "/Users/julius/project", [
+        "/Users/julius/docs",
+      ]),
+    ).toBe(true);
+    expect(
+      resolveMarkdownFileLinkMeta("file:///Users/julius/docs/README.md", "/Users/julius/project", [
+        "/Users/julius/docs",
+      ]),
+    ).toMatchObject({
+      openPolicy: "direct",
+    });
+  });
 });
diff --git a/apps/web/src/markdown-links.ts b/apps/web/src/markdown-links.ts
index 668abb89..fad57e16 100644
--- a/apps/web/src/markdown-links.ts
+++ b/apps/web/src/markdown-links.ts
@@ -136,18 +136,30 @@ function normalizePathForWorkspaceComparison(path: string): string {
     : normalized;
 }
 
-export function isPathInsideWorkspace(targetPath: string, cwd: string | undefined): boolean {
-  if (!cwd) {
+export function isPathInsideWorkspace(
+  targetPath: string,
+  cwd: string | undefined,
+  additionalWorkspaceRoots: ReadonlyArray<string> = [],
+): boolean {
+  const workspaceRoots = [cwd, ...additionalWorkspaceRoots].filter(
+    (root): root is string => typeof root === "string" && root.trim().length > 0,
+  );
+  if (workspaceRoots.length === 0) {
     return false;
   }
 
   const target = normalizePathForWorkspaceComparison(splitPathAndPosition(targetPath).path);
-  const workspace = normalizePathForWorkspaceComparison(splitPathAndPosition(cwd).path);
-  if (target.length === 0 || workspace.length === 0) {
+  if (target.length === 0) {
     return false;
   }
 
-  return target === workspace || target.startsWith(`${workspace}/`);
+  return workspaceRoots.some((root) => {
+    const workspace = normalizePathForWorkspaceComparison(splitPathAndPosition(root).path);
+    if (workspace.length === 0) {
+      return false;
+    }
+    return target === workspace || target.startsWith(`${workspace}/`);
+  });
 }
 
 function hasExternalScheme(path: string): boolean {
@@ -203,6 +215,7 @@ function basenameOfPath(path: string): string {
 export function resolveMarkdownFileLinkMeta(
   href: string | undefined,
   cwd?: string,
+  additionalWorkspaceRoots: ReadonlyArray<string> = [],
 ): MarkdownFileLinkMeta | null {
   const targetPath = resolveMarkdownFileLinkTarget(href, cwd);
   if (!targetPath) return null;
@@ -218,7 +231,9 @@ export function resolveMarkdownFileLinkMeta(
     targetPath,
     displayPath: formatWorkspaceRelativePath(targetPath, cwd),
     basename: basenameOfPath(path),
-    openPolicy: isPathInsideWorkspace(targetPath, cwd) ? "direct" : "confirm",
+    openPolicy: isPathInsideWorkspace(targetPath, cwd, additionalWorkspaceRoots)
+      ? "direct"
+      : "confirm",
     ...(lineNumber !== undefined ? { line: lineNumber } : {}),
     ...(columnNumber !== undefined ? { column: columnNumber } : {}),
   };
diff --git a/apps/web/src/store.test.ts b/apps/web/src/store.test.ts
index 3c4324a5..9a71020f 100644
--- a/apps/web/src/store.test.ts
+++ b/apps/web/src/store.test.ts
@@ -583,6 +583,7 @@ describe("incremental orchestration updates", () => {
         projectId: recreatedProjectId,
         title: "Project Recreated",
         workspaceRoot: "/tmp/project",
+        additionalWorkspaceRoots: [],
         defaultModelSelection: {
           instanceId: ProviderInstanceId.make("codex"),
           model: DEFAULT_MODEL,
@@ -846,7 +847,7 @@ describe("incremental orchestration updates", () => {
     );
 
     expect(threadsOf(next)[0]?.session?.status).toBe("running");
-    expect(threadsOf(next)[0]?.latestTurn?.state).toBe("completed");
+    expect(threadsOf(next)[0]?.latestTurn?.state).toBe("running");
     expect(threadsOf(next)[0]?.messages).toHaveLength(1);
   });
 
diff --git a/apps/web/src/store.ts b/apps/web/src/store.ts
index 5d3eec93..c0505023 100644
--- a/apps/web/src/store.ts
+++ b/apps/web/src/store.ts
@@ -220,6 +220,7 @@ function mapProject(
     environmentId,
     name: project.title,
     cwd: project.workspaceRoot,
+    additionalWorkspaceRoots: [...(project.additionalWorkspaceRoots ?? [])],
     repositoryIdentity: project.repositoryIdentity ?? null,
     defaultModelSelection: project.defaultModelSelection
       ? normalizeModelSelection(project.defaultModelSelection)
@@ -1157,6 +1158,7 @@ function applyEnvironmentOrchestrationEvent(
           id: event.payload.projectId,
           title: event.payload.title,
           workspaceRoot: event.payload.workspaceRoot,
+          additionalWorkspaceRoots: event.payload.additionalWorkspaceRoots ?? [],
           repositoryIdentity: event.payload.repositoryIdentity ?? null,
           defaultModelSelection: event.payload.defaultModelSelection,
           scripts: event.payload.scripts,
@@ -1211,6 +1213,9 @@ function applyEnvironmentOrchestrationEvent(
         ...project,
         ...(event.payload.title !== undefined ? { name: event.payload.title } : {}),
         ...(event.payload.workspaceRoot !== undefined ? { cwd: event.payload.workspaceRoot } : {}),
+        ...(event.payload.additionalWorkspaceRoots !== undefined
+          ? { additionalWorkspaceRoots: [...event.payload.additionalWorkspaceRoots] }
+          : {}),
         ...(event.payload.repositoryIdentity !== undefined
           ? { repositoryIdentity: event.payload.repositoryIdentity ?? null }
           : {}),
diff --git a/apps/web/src/types.ts b/apps/web/src/types.ts
index 2ca96cc3..4625c82a 100644
--- a/apps/web/src/types.ts
+++ b/apps/web/src/types.ts
@@ -78,6 +78,7 @@ export interface Project {
   environmentId: EnvironmentId;
   name: string;
   cwd: string;
+  additionalWorkspaceRoots?: string[];
   repositoryIdentity?: RepositoryIdentity | null;
   defaultModelSelection: ModelSelection | null;
   createdAt?: string | undefined;
diff --git a/packages/contracts/src/orchestration.test.ts b/packages/contracts/src/orchestration.test.ts
index 8524aaec..cb520cb5 100644
--- a/packages/contracts/src/orchestration.test.ts
+++ b/packages/contracts/src/orchestration.test.ts
@@ -55,6 +55,7 @@ it.effect("trims branded ids and command string fields at decode boundaries", ()
       projectId: " project-1 ",
       title: " Project Title ",
       workspaceRoot: " /tmp/workspace ",
+      additionalWorkspaceRoots: [" /tmp/docs ", " /tmp/tools "],
       defaultModelSelection: {
         provider: "codex",
         model: " gpt-5.2 ",
@@ -65,6 +66,7 @@ it.effect("trims branded ids and command string fields at decode boundaries", ()
     assert.strictEqual(parsed.projectId, "project-1");
     assert.strictEqual(parsed.title, "Project Title");
     assert.strictEqual(parsed.workspaceRoot, "/tmp/workspace");
+    assert.deepStrictEqual(parsed.additionalWorkspaceRoots, ["/tmp/docs", "/tmp/tools"]);
     assert.strictEqual(parsed.createWorkspaceRootIfMissing, undefined);
     assert.deepStrictEqual(parsed.defaultModelSelection, {
       instanceId: ProviderInstanceId.make("codex"),
@@ -104,6 +106,23 @@ it.effect("decodes historical project.created payloads with a default provider",
       updatedAt: "2026-01-01T00:00:00.000Z",
     });
     assert.strictEqual(parsed.defaultModelSelection?.instanceId, "codex");
+    assert.strictEqual(parsed.additionalWorkspaceRoots, undefined);
+  }),
+);
+
+it.effect("decodes populated project additional workspace roots", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeProjectCreatedPayload({
+      projectId: "project-1",
+      title: "Project Title",
+      workspaceRoot: "/tmp/workspace",
+      additionalWorkspaceRoots: ["/tmp/docs", " /tmp/tools "],
+      defaultModelSelection: null,
+      scripts: [],
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    });
+    assert.deepStrictEqual(parsed.additionalWorkspaceRoots, ["/tmp/docs", "/tmp/tools"]);
   }),
 );
 
@@ -111,6 +130,7 @@ it.effect("decodes project.meta-updated payloads with explicit default provider"
   Effect.gen(function* () {
     const parsed = yield* decodeProjectMetaUpdatedPayload({
       projectId: "project-1",
+      additionalWorkspaceRoots: [" /tmp/docs "],
       defaultModelSelection: {
         provider: "claudeAgent",
         model: "claude-opus-4-6",
@@ -118,6 +138,7 @@ it.effect("decodes project.meta-updated payloads with explicit default provider"
       updatedAt: "2026-01-01T00:00:00.000Z",
     });
     assert.strictEqual(parsed.defaultModelSelection?.instanceId, "claudeAgent");
+    assert.deepStrictEqual(parsed.additionalWorkspaceRoots, ["/tmp/docs"]);
   }),
 );
 
diff --git a/packages/contracts/src/orchestration.ts b/packages/contracts/src/orchestration.ts
index 3c8dd29b..3047af94 100644
--- a/packages/contracts/src/orchestration.ts
+++ b/packages/contracts/src/orchestration.ts
@@ -194,10 +194,16 @@ export const ProjectScript = Schema.Struct({
 });
 export type ProjectScript = typeof ProjectScript.Type;
 
+export const AdditionalWorkspaceRoots = Schema.Array(TrimmedNonEmptyString).pipe(
+  Schema.withDecodingDefault(Effect.succeed([])),
+);
+export type AdditionalWorkspaceRoots = typeof AdditionalWorkspaceRoots.Type;
+
 export const OrchestrationProject = Schema.Struct({
   id: ProjectId,
   title: TrimmedNonEmptyString,
   workspaceRoot: TrimmedNonEmptyString,
+  additionalWorkspaceRoots: Schema.optional(AdditionalWorkspaceRoots),
   repositoryIdentity: Schema.optional(Schema.NullOr(RepositoryIdentity)),
   defaultModelSelection: Schema.NullOr(ModelSelection),
   scripts: Schema.Array(ProjectScript),
@@ -365,6 +371,7 @@ export const OrchestrationProjectShell = Schema.Struct({
   id: ProjectId,
   title: TrimmedNonEmptyString,
   workspaceRoot: TrimmedNonEmptyString,
+  additionalWorkspaceRoots: Schema.optional(AdditionalWorkspaceRoots),
   repositoryIdentity: Schema.optional(Schema.NullOr(RepositoryIdentity)),
   defaultModelSelection: Schema.NullOr(ModelSelection),
   scripts: Schema.Array(ProjectScript),
@@ -455,6 +462,7 @@ export const ProjectCreateCommand = Schema.Struct({
   projectId: ProjectId,
   title: TrimmedNonEmptyString,
   workspaceRoot: TrimmedNonEmptyString,
+  additionalWorkspaceRoots: Schema.optional(Schema.Array(TrimmedNonEmptyString)),
   createWorkspaceRootIfMissing: Schema.optional(Schema.Boolean),
   defaultModelSelection: Schema.optional(Schema.NullOr(ModelSelection)),
   createdAt: IsoDateTime,
@@ -466,6 +474,7 @@ const ProjectMetaUpdateCommand = Schema.Struct({
   projectId: ProjectId,
   title: Schema.optional(TrimmedNonEmptyString),
   workspaceRoot: Schema.optional(TrimmedNonEmptyString),
+  additionalWorkspaceRoots: Schema.optional(Schema.Array(TrimmedNonEmptyString)),
   defaultModelSelection: Schema.optional(Schema.NullOr(ModelSelection)),
   scripts: Schema.optional(Schema.Array(ProjectScript)),
 });
@@ -839,6 +848,7 @@ export const ProjectCreatedPayload = Schema.Struct({
   projectId: ProjectId,
   title: TrimmedNonEmptyString,
   workspaceRoot: TrimmedNonEmptyString,
+  additionalWorkspaceRoots: Schema.optional(AdditionalWorkspaceRoots),
   repositoryIdentity: Schema.optional(Schema.NullOr(RepositoryIdentity)),
   defaultModelSelection: Schema.NullOr(ModelSelection),
   scripts: Schema.Array(ProjectScript),
@@ -850,6 +860,7 @@ export const ProjectMetaUpdatedPayload = Schema.Struct({
   projectId: ProjectId,
   title: Schema.optional(TrimmedNonEmptyString),
   workspaceRoot: Schema.optional(TrimmedNonEmptyString),
+  additionalWorkspaceRoots: Schema.optional(Schema.Array(TrimmedNonEmptyString)),
   repositoryIdentity: Schema.optional(Schema.NullOr(RepositoryIdentity)),
   defaultModelSelection: Schema.optional(Schema.NullOr(ModelSelection)),
   scripts: Schema.optional(Schema.Array(ProjectScript)),
diff --git a/packages/contracts/src/provider.ts b/packages/contracts/src/provider.ts
index 94fb007a..9cf79d76 100644
--- a/packages/contracts/src/provider.ts
+++ b/packages/contracts/src/provider.ts
@@ -40,6 +40,7 @@ export const ProviderSession = Schema.Struct({
   status: ProviderSessionStatus,
   runtimeMode: RuntimeMode,
   cwd: Schema.optional(TrimmedNonEmptyString),
+  additionalDirectories: Schema.optional(Schema.Array(TrimmedNonEmptyString)),
   model: Schema.optional(TrimmedNonEmptyString),
   threadId: ThreadId,
   resumeCursor: Schema.optional(Schema.Unknown),
@@ -56,6 +57,7 @@ export const ProviderSessionStartInput = Schema.Struct({
   // See ProviderSession for the migration story.
   providerInstanceId: Schema.optional(ProviderInstanceId),
   cwd: Schema.optional(TrimmedNonEmptyString),
+  additionalDirectories: Schema.optional(Schema.Array(TrimmedNonEmptyString)),
   modelSelection: Schema.optional(ModelSelection),
   resumeCursor: Schema.optional(Schema.Unknown),
   approvalPolicy: Schema.optional(ProviderApprovalPolicy),

From 95d91ceffb7d837054f0f2c37ac5da0c6e23ca80 Mon Sep 17 00:00:00 2001
From: saltacc <alotofcatz@gmail.com>
Date: Sat, 23 May 2026 15:56:50 -0700
Subject: [PATCH 3/5] Add appearance controls

---
 .../settings/DesktopClientSettings.test.ts    |   3 +
 apps/web/src/components/Sidebar.tsx           |  42 +++--
 .../settings/SettingsPanels.browser.tsx       |  49 ++++++
 .../components/settings/SettingsPanels.tsx    | 154 +++++++++++++++++-
 apps/web/src/documentVisibility.test.ts       |  22 +++
 apps/web/src/documentVisibility.ts            |  17 ++
 apps/web/src/index.css                        |  95 ++++++++---
 apps/web/src/localApi.test.ts                 |   6 +
 apps/web/src/routes/__root.tsx                |  31 +++-
 apps/web/src/themeAccent.test.ts              |  39 +++++
 apps/web/src/themeAccent.ts                   |  23 +++
 packages/contracts/src/settings.test.ts       |  28 ++++
 packages/contracts/src/settings.ts            |  16 ++
 13 files changed, 484 insertions(+), 41 deletions(-)
 create mode 100644 apps/web/src/themeAccent.test.ts
 create mode 100644 apps/web/src/themeAccent.ts

diff --git a/apps/desktop/src/settings/DesktopClientSettings.test.ts b/apps/desktop/src/settings/DesktopClientSettings.test.ts
index a8a3cc86..ed67690f 100644
--- a/apps/desktop/src/settings/DesktopClientSettings.test.ts
+++ b/apps/desktop/src/settings/DesktopClientSettings.test.ts
@@ -18,6 +18,9 @@ const clientSettings: ClientSettings = {
   dismissedProviderUpdateNotificationKeys: [],
   diffIgnoreWhitespace: true,
   diffWordWrap: true,
+  continueBackgroundAnimations: false,
+  showSidebarMascot: true,
+  themeAccentColor: "",
   defaultEditor: "system-default",
   favorites: [],
   providerModelPreferences: {},
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index ebfa4597..69998939 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -2931,6 +2931,7 @@ interface SidebarProjectsContentProps {
   suppressProjectClickForContextMenuRef: React.RefObject<boolean>;
   attachProjectListAutoAnimateRef: (node: HTMLElement | null) => void;
   projectsLength: number;
+  showSidebarMascot: boolean;
 }
 
 const SidebarProjectsContent = memo(function SidebarProjectsContent(
@@ -2972,6 +2973,7 @@ const SidebarProjectsContent = memo(function SidebarProjectsContent(
     suppressProjectClickForContextMenuRef,
     attachProjectListAutoAnimateRef,
     projectsLength,
+    showSidebarMascot,
   } = props;
 
   const handleProjectSortOrderChange = useCallback(
@@ -3162,24 +3164,26 @@ const SidebarProjectsContent = memo(function SidebarProjectsContent(
         )}
       </SidebarGroup>
       <div aria-hidden="true" className="min-h-6 flex-1" />
-      <div className="flex shrink-0 flex-col items-center justify-center gap-2 px-4 pt-3 pb-4">
-        <img
-          alt=""
-          aria-hidden="true"
-          className="h-32 w-[6.4rem] select-none rounded-[1.35rem] object-cover ring-1 ring-black/10 dark:ring-white/10"
-          draggable={false}
-          src={SIDEBAR_BRAND_ICON_SRC}
-        />
-        <a
-          aria-label="Cafe Code on GitHub"
-          className="text-[10px] font-medium text-muted-foreground/35 underline-offset-2 transition-colors hover:text-muted-foreground/65 hover:underline focus-visible:rounded-sm focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
-          href="https://github.com/cafeai/cafe-code"
-          rel="noreferrer"
-          target="_blank"
-        >
-          by cafeai <span className="opacity-60">♡</span>
-        </a>
-      </div>
+      {showSidebarMascot ? (
+        <div className="flex shrink-0 flex-col items-center justify-center gap-2 px-4 pt-3 pb-4">
+          <img
+            alt=""
+            aria-hidden="true"
+            className="h-32 w-[6.4rem] select-none rounded-[1.35rem] object-cover ring-1 ring-black/10 dark:ring-white/10"
+            draggable={false}
+            src={SIDEBAR_BRAND_ICON_SRC}
+          />
+          <a
+            aria-label="Cafe Code on GitHub"
+            className="text-[10px] font-medium text-muted-foreground/35 underline-offset-2 transition-colors hover:text-muted-foreground/65 hover:underline focus-visible:rounded-sm focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
+            href="https://github.com/cafeai/cafe-code"
+            rel="noreferrer"
+            target="_blank"
+          >
+            by cafeai <span className="opacity-60">♡</span>
+          </a>
+        </div>
+      ) : null}
     </SidebarContent>
   );
 });
@@ -3198,6 +3202,7 @@ export default function Sidebar() {
   const sidebarProjectGroupingMode = useSettings((s) => s.sidebarProjectGroupingMode);
   const projectGroupingSettings = useSettings(selectProjectGroupingSettings);
   const sidebarThreadPreviewCount = useSettings((s) => s.sidebarThreadPreviewCount);
+  const showSidebarMascot = useSettings((s) => s.showSidebarMascot);
   const { updateSettings } = useUpdateSettings();
   const { handleNewThread } = useNewThreadHandler();
   const { archiveThread, deleteThread } = useThreadActions();
@@ -3836,6 +3841,7 @@ export default function Sidebar() {
             suppressProjectClickForContextMenuRef={suppressProjectClickForContextMenuRef}
             attachProjectListAutoAnimateRef={attachProjectListAutoAnimateRef}
             projectsLength={projects.length}
+            showSidebarMascot={showSidebarMascot}
           />
 
           <SidebarSeparator />
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index 5dcba2c6..2056d0c9 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -766,6 +766,55 @@ describe("GeneralSettingsPanel observability", () => {
     });
   });
 
+  it("persists appearance preferences from General settings", async () => {
+    const desktopBridge = createDesktopBridgeStub();
+    window.desktopBridge = desktopBridge;
+    setServerConfigSnapshot(createBaseServerConfig());
+
+    mounted = await renderWithTestRouter(
+      <AppAtomRegistryProvider>
+        <GeneralSettingsPanel />
+      </AppAtomRegistryProvider>,
+    );
+
+    await expect.element(page.getByText("Accent color")).toBeInTheDocument();
+    const accentInput = document.querySelector(
+      'input[aria-label="Animated sidebar accent color"]',
+    ) as HTMLInputElement | null;
+    expect(accentInput).not.toBeNull();
+    const inputValueSetter = Object.getOwnPropertyDescriptor(
+      HTMLInputElement.prototype,
+      "value",
+    )?.set;
+    inputValueSetter?.call(accentInput, "#16a34a");
+    accentInput!.dispatchEvent(new Event("input", { bubbles: true }));
+    accentInput!.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+
+    await vi.waitFor(() => {
+      expect(desktopBridge.setClientSettings).toHaveBeenCalledWith(
+        expect.objectContaining({ themeAccentColor: "#16a34a" }),
+      );
+    });
+
+    await expect.element(page.getByText("Sidebar mascot")).toBeInTheDocument();
+    await page.getByLabelText("Show sidebar mascot").click();
+
+    await vi.waitFor(() => {
+      expect(desktopBridge.setClientSettings).toHaveBeenCalledWith(
+        expect.objectContaining({ showSidebarMascot: false }),
+      );
+    });
+
+    await expect.element(page.getByText("Background animations")).toBeInTheDocument();
+    await page.getByLabelText("Keep animations running in background").click();
+
+    await vi.waitFor(() => {
+      expect(desktopBridge.setClientSettings).toHaveBeenCalledWith(
+        expect.objectContaining({ continueBackgroundAnimations: true }),
+      );
+    });
+  });
+
   it("shows detected editor icons in the General default editor selector", async () => {
     const platformSpy = vi.spyOn(navigator, "platform", "get").mockReturnValue("MacIntel");
     const desktopBridge = createDesktopBridgeStub();
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 955f450f..5431ccc1 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -2,13 +2,14 @@ import {
   ArchiveIcon,
   ArchiveX,
   LoaderIcon,
+  PaletteIcon,
   PlusIcon,
   RefreshCwIcon,
   Trash2Icon,
 } from "lucide-react";
 import { useQueryClient } from "@tanstack/react-query";
 import { Link } from "@tanstack/react-router";
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   defaultInstanceIdForDriver,
   type DesktopUpdateChannel,
@@ -21,6 +22,9 @@ import {
 import { scopeThreadRef } from "@cafecode/client-runtime";
 import {
   DEFAULT_UNIFIED_SETTINGS,
+  DEFAULT_CONTINUE_BACKGROUND_ANIMATIONS,
+  DEFAULT_SHOW_SIDEBAR_MASCOT,
+  DEFAULT_THEME_ACCENT_COLOR,
   type DefaultEditorSelection,
   type PowerSaveBlockerMode,
 } from "@cafecode/contracts/settings";
@@ -95,6 +99,7 @@ import {
   useServerProviders,
 } from "../../rpc/serverState";
 import { resolveEditorOpenOptions, type EditorOpenOption } from "../../editorOpenOptions";
+import { normalizeThemeAccentColor } from "../../themeAccent";
 
 const THEME_OPTIONS = [
   {
@@ -110,6 +115,7 @@ const THEME_OPTIONS = [
     label: "Dark",
   },
 ] as const;
+const DEFAULT_THEME_ACCENT_PICKER_COLOR = "#48cfff";
 
 const TIMESTAMP_FORMAT_LABELS = {
   locale: "System default",
@@ -203,6 +209,62 @@ function AboutVersionTitle() {
   );
 }
 
+function ThemeAccentColorPicker(props: {
+  readonly value: string;
+  readonly onCommit: (value: string) => void;
+}) {
+  const [draft, setDraft] = useState(props.value);
+  const [isEditing, setIsEditing] = useState(false);
+  const draftColor = normalizeThemeAccentColor(draft);
+
+  useEffect(() => {
+    if (isEditing) return;
+    setDraft(props.value);
+  }, [isEditing, props.value]);
+
+  const commitDraft = () => {
+    setIsEditing(false);
+    props.onCommit(draftColor ?? DEFAULT_THEME_ACCENT_COLOR);
+  };
+
+  return (
+    <div className="flex min-w-0 items-center justify-end">
+      <label className="group relative inline-flex h-8 w-10 cursor-pointer items-center justify-center rounded-md border border-input bg-background shadow-xs transition-colors hover:bg-accent focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-1 focus-within:ring-offset-background">
+        <span
+          className="pointer-events-none absolute inset-0 rounded-[inherit] opacity-0 transition-opacity group-hover:opacity-100"
+          style={{
+            backgroundColor: draftColor ?? "transparent",
+          }}
+        />
+        <span className="pointer-events-none relative flex size-6 items-center justify-center rounded-full bg-[conic-gradient(from_40deg,#ef4444,#f97316,#facc15,#22c55e,#06b6d4,#3b82f6,#8b5cf6,#ef4444)] shadow-inner shadow-black/15">
+          <span className="absolute inset-1 rounded-full bg-background/92" />
+          <PaletteIcon
+            className="relative size-3.5 text-foreground/78"
+            strokeWidth={2.2}
+            aria-hidden="true"
+          />
+        </span>
+        <input
+          type="color"
+          value={draftColor ?? DEFAULT_THEME_ACCENT_PICKER_COLOR}
+          onFocus={() => setIsEditing(true)}
+          onInput={(event) => {
+            setIsEditing(true);
+            setDraft(event.currentTarget.value);
+          }}
+          onChange={(event) => {
+            setIsEditing(true);
+            setDraft(event.currentTarget.value);
+          }}
+          onBlur={commitDraft}
+          aria-label="Animated sidebar accent color"
+          className="absolute inset-0 h-full w-full cursor-pointer opacity-0"
+        />
+      </label>
+    </div>
+  );
+}
+
 function AboutVersionSection() {
   const queryClient = useQueryClient();
   const updateStateQuery = useDesktopUpdateState();
@@ -431,6 +493,16 @@ export function useSettingsRestore(onRestored?: () => void) {
   const changedSettingLabels = useMemo(
     () => [
       ...(theme !== "system" ? ["Theme"] : []),
+      ...(settings.continueBackgroundAnimations !==
+      DEFAULT_UNIFIED_SETTINGS.continueBackgroundAnimations
+        ? ["Background animations"]
+        : []),
+      ...(settings.showSidebarMascot !== DEFAULT_UNIFIED_SETTINGS.showSidebarMascot
+        ? ["Sidebar mascot"]
+        : []),
+      ...(settings.themeAccentColor !== DEFAULT_UNIFIED_SETTINGS.themeAccentColor
+        ? ["Sidebar accent color"]
+        : []),
       ...(settings.timestampFormat !== DEFAULT_UNIFIED_SETTINGS.timestampFormat
         ? ["Time format"]
         : []),
@@ -475,11 +547,14 @@ export function useSettingsRestore(onRestored?: () => void) {
       settings.autoOpenPlanSidebar,
       settings.confirmThreadArchive,
       settings.confirmThreadDelete,
+      settings.continueBackgroundAnimations,
       settings.addProjectBaseDirectory,
       settings.defaultThreadEnvMode,
       settings.diffIgnoreWhitespace,
       settings.diffWordWrap,
       settings.defaultEditor,
+      settings.showSidebarMascot,
+      settings.themeAccentColor,
       settings.automaticGitFetchInterval,
       settings.enableAssistantStreaming,
       settings.sidebarThreadPreviewCount,
@@ -501,6 +576,9 @@ export function useSettingsRestore(onRestored?: () => void) {
     setTheme("system");
     updateSettings({
       timestampFormat: DEFAULT_UNIFIED_SETTINGS.timestampFormat,
+      continueBackgroundAnimations: DEFAULT_UNIFIED_SETTINGS.continueBackgroundAnimations,
+      showSidebarMascot: DEFAULT_UNIFIED_SETTINGS.showSidebarMascot,
+      themeAccentColor: DEFAULT_UNIFIED_SETTINGS.themeAccentColor,
       defaultEditor: DEFAULT_UNIFIED_SETTINGS.defaultEditor,
       diffWordWrap: DEFAULT_UNIFIED_SETTINGS.diffWordWrap,
       diffIgnoreWhitespace: DEFAULT_UNIFIED_SETTINGS.diffIgnoreWhitespace,
@@ -609,6 +687,80 @@ export function GeneralSettingsPanel() {
           }
         />
 
+        <SettingsRow
+          title="Accent color"
+          description="Choose the color used by the animated sidebar stars and glow."
+          resetAction={
+            settings.themeAccentColor !== DEFAULT_UNIFIED_SETTINGS.themeAccentColor ? (
+              <SettingResetButton
+                label="accent color"
+                onClick={() =>
+                  updateSettings({
+                    themeAccentColor: DEFAULT_THEME_ACCENT_COLOR,
+                  })
+                }
+              />
+            ) : null
+          }
+          control={
+            <ThemeAccentColorPicker
+              value={settings.themeAccentColor}
+              onCommit={(value) => updateSettings({ themeAccentColor: value })}
+            />
+          }
+        />
+
+        <SettingsRow
+          title="Sidebar mascot"
+          description="Show the Cafe Code mascot and attribution link at the bottom of the sidebar."
+          resetAction={
+            settings.showSidebarMascot !== DEFAULT_UNIFIED_SETTINGS.showSidebarMascot ? (
+              <SettingResetButton
+                label="sidebar mascot"
+                onClick={() =>
+                  updateSettings({
+                    showSidebarMascot: DEFAULT_SHOW_SIDEBAR_MASCOT,
+                  })
+                }
+              />
+            ) : null
+          }
+          control={
+            <Switch
+              checked={settings.showSidebarMascot}
+              onCheckedChange={(checked) => updateSettings({ showSidebarMascot: Boolean(checked) })}
+              aria-label="Show sidebar mascot"
+            />
+          }
+        />
+
+        <SettingsRow
+          title="Background animations"
+          description="Keep decorative animations running when Cafe Code is hidden or unfocused."
+          resetAction={
+            settings.continueBackgroundAnimations !==
+            DEFAULT_UNIFIED_SETTINGS.continueBackgroundAnimations ? (
+              <SettingResetButton
+                label="background animations"
+                onClick={() =>
+                  updateSettings({
+                    continueBackgroundAnimations: DEFAULT_CONTINUE_BACKGROUND_ANIMATIONS,
+                  })
+                }
+              />
+            ) : null
+          }
+          control={
+            <Switch
+              checked={settings.continueBackgroundAnimations}
+              onCheckedChange={(checked) =>
+                updateSettings({ continueBackgroundAnimations: Boolean(checked) })
+              }
+              aria-label="Keep animations running in background"
+            />
+          }
+        />
+
         <SettingsRow
           title="Time format"
           description="System default follows your browser or OS clock preference."
diff --git a/apps/web/src/documentVisibility.test.ts b/apps/web/src/documentVisibility.test.ts
index 2df1aeac..704729a7 100644
--- a/apps/web/src/documentVisibility.test.ts
+++ b/apps/web/src/documentVisibility.test.ts
@@ -1,8 +1,11 @@
 import { describe, expect, it } from "vitest";
 
 import {
+  applyCafeBackgroundAnimations,
+  CAFE_BACKGROUND_ANIMATIONS_ATTRIBUTE,
   CAFE_DOCUMENT_VISIBILITY_ATTRIBUTE,
   CAFE_WINDOW_FOCUS_ATTRIBUTE,
+  clearCafeBackgroundAnimations,
   readCafeDocumentVisibility,
   readCafeWindowFocus,
   startCafeDocumentVisibilitySync,
@@ -123,4 +126,23 @@ describe("documentVisibility", () => {
     fake.setFocused(false);
     expect(fake.getFocusAttribute()).toBeNull();
   });
+
+  it("maps the background animation setting into a document attribute", () => {
+    const fake = makeVisibilityDocument("visible");
+
+    expect(applyCafeBackgroundAnimations(false, fake.document)).toBe("paused");
+    expect(fake.document.documentElement.getAttribute(CAFE_BACKGROUND_ANIMATIONS_ATTRIBUTE)).toBe(
+      "paused",
+    );
+
+    expect(applyCafeBackgroundAnimations(true, fake.document)).toBe("running");
+    expect(fake.document.documentElement.getAttribute(CAFE_BACKGROUND_ANIMATIONS_ATTRIBUTE)).toBe(
+      "running",
+    );
+
+    clearCafeBackgroundAnimations(fake.document);
+    expect(fake.document.documentElement.getAttribute(CAFE_BACKGROUND_ANIMATIONS_ATTRIBUTE)).toBe(
+      null,
+    );
+  });
 });
diff --git a/apps/web/src/documentVisibility.ts b/apps/web/src/documentVisibility.ts
index 79d35562..c312e470 100644
--- a/apps/web/src/documentVisibility.ts
+++ b/apps/web/src/documentVisibility.ts
@@ -1,8 +1,10 @@
 export const CAFE_DOCUMENT_VISIBILITY_ATTRIBUTE = "data-cafe-visibility";
 export const CAFE_WINDOW_FOCUS_ATTRIBUTE = "data-cafe-window-focus";
+export const CAFE_BACKGROUND_ANIMATIONS_ATTRIBUTE = "data-cafe-background-animations";
 
 export type CafeDocumentVisibility = "hidden" | "visible";
 export type CafeWindowFocus = "blurred" | "focused";
+export type CafeBackgroundAnimations = "paused" | "running";
 
 type CafeVisibilityListener = () => void;
 type CafeWindowFocusListener = () => void;
@@ -50,6 +52,21 @@ export function applyCafeWindowFocus(
   return focus;
 }
 
+export function applyCafeBackgroundAnimations(
+  continueBackgroundAnimations: boolean,
+  documentRef: Pick<CafeVisibilityDocument, "documentElement"> = document,
+): CafeBackgroundAnimations {
+  const mode = continueBackgroundAnimations ? "running" : "paused";
+  documentRef.documentElement.setAttribute(CAFE_BACKGROUND_ANIMATIONS_ATTRIBUTE, mode);
+  return mode;
+}
+
+export function clearCafeBackgroundAnimations(
+  documentRef: Pick<CafeVisibilityDocument, "documentElement"> = document,
+): void {
+  documentRef.documentElement.removeAttribute(CAFE_BACKGROUND_ANIMATIONS_ATTRIBUTE);
+}
+
 export function startCafeDocumentVisibilitySync(
   documentRef: CafeVisibilityDocument = document,
   windowRef: CafeVisibilityWindow = window,
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index a2f64795..21458f6e 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -112,6 +112,7 @@
   --success-foreground: var(--color-emerald-700);
   --warning: var(--color-amber-500);
   --warning-foreground: var(--color-amber-700);
+  --cafe-sidebar-accent: #44beda;
 
   @variant dark {
     color-scheme: dark;
@@ -141,6 +142,7 @@
     --success-foreground: var(--color-emerald-400);
     --warning: var(--color-amber-500);
     --warning-foreground: var(--color-amber-400);
+    --cafe-sidebar-accent: #48cfff;
   }
 }
 
@@ -228,7 +230,11 @@ body::after {
   isolation: isolate;
   overflow: hidden;
   background:
-    radial-gradient(120% 90% at 50% -8%, rgba(68, 190, 218, 0.16), transparent 42%),
+    radial-gradient(
+      120% 90% at 50% -8%,
+      color-mix(in srgb, var(--cafe-sidebar-accent) 16%, transparent),
+      transparent 42%
+    ),
     radial-gradient(95% 75% at 18% 105%, rgba(126, 137, 151, 0.14), transparent 46%),
     color-mix(in srgb, var(--card) 96%, #e5edf3);
 }
@@ -247,9 +253,17 @@ body::after {
   inset: -34% -48%;
   background-image:
     radial-gradient(circle at 18px 28px, rgba(22, 32, 46, 0.76) 0 1px, transparent 1.45px),
-    radial-gradient(circle at 84px 118px, rgba(0, 88, 120, 0.74) 0 1.1px, transparent 1.65px),
+    radial-gradient(
+      circle at 84px 118px,
+      color-mix(in srgb, var(--cafe-sidebar-accent) 74%, #00364a) 0 1.1px,
+      transparent 1.65px
+    ),
     radial-gradient(circle at 132px 64px, rgba(43, 56, 73, 0.72) 0 0.8px, transparent 1.35px),
-    radial-gradient(circle at 226px 192px, rgba(0, 105, 138, 0.72) 0 1.15px, transparent 1.75px),
+    radial-gradient(
+      circle at 226px 192px,
+      color-mix(in srgb, var(--cafe-sidebar-accent) 72%, #004358) 0 1.15px,
+      transparent 1.75px
+    ),
     radial-gradient(circle at 304px 42px, rgba(32, 45, 61, 0.64) 0 0.7px, transparent 1.25px);
   background-position:
     0 0,
@@ -271,10 +285,19 @@ body::after {
 .cafe-thread-sidebar [data-slot="sidebar-inner"]::after {
   inset: -18% -28%;
   background:
-    radial-gradient(ellipse at 16% 24%, rgba(16, 184, 214, 0.18), transparent 36%),
+    radial-gradient(
+      ellipse at 16% 24%,
+      color-mix(in srgb, var(--cafe-sidebar-accent) 18%, transparent),
+      transparent 36%
+    ),
     radial-gradient(ellipse at 82% 80%, rgba(132, 142, 156, 0.18), transparent 38%),
     radial-gradient(ellipse at 72% 12%, rgba(94, 109, 126, 0.08), transparent 34%),
-    linear-gradient(132deg, transparent 20%, rgba(76, 176, 205, 0.1) 48%, transparent 70%);
+    linear-gradient(
+      132deg,
+      transparent 20%,
+      color-mix(in srgb, var(--cafe-sidebar-accent) 10%, transparent) 48%,
+      transparent 70%
+    );
   opacity: 0.42;
   animation: cafe-sidebar-nebula-drift 23.333s ease-in-out infinite alternate;
   will-change: transform, opacity;
@@ -282,7 +305,11 @@ body::after {
 
 .dark .cafe-thread-sidebar [data-slot="sidebar-inner"] {
   background:
-    radial-gradient(120% 90% at 50% -8%, rgba(72, 207, 255, 0.16), transparent 42%),
+    radial-gradient(
+      120% 90% at 50% -8%,
+      color-mix(in srgb, var(--cafe-sidebar-accent) 16%, transparent),
+      transparent 42%
+    ),
     radial-gradient(95% 75% at 18% 105%, rgba(166, 176, 188, 0.14), transparent 46%), #101011;
 }
 
@@ -291,18 +318,35 @@ body::after {
 
   background-image:
     radial-gradient(circle at 18px 28px, rgba(255, 255, 255, 0.82) 0 1px, transparent 1.45px),
-    radial-gradient(circle at 84px 118px, rgba(109, 236, 255, 0.8) 0 1.1px, transparent 1.65px),
+    radial-gradient(
+      circle at 84px 118px,
+      color-mix(in srgb, var(--cafe-sidebar-accent) 80%, white) 0 1.1px,
+      transparent 1.65px
+    ),
     radial-gradient(circle at 132px 64px, rgba(176, 184, 196, 0.62) 0 0.8px, transparent 1.35px),
-    radial-gradient(circle at 226px 192px, rgba(84, 204, 232, 0.7) 0 1.15px, transparent 1.75px),
+    radial-gradient(
+      circle at 226px 192px,
+      color-mix(in srgb, var(--cafe-sidebar-accent) 70%, white) 0 1.15px,
+      transparent 1.75px
+    ),
     radial-gradient(circle at 304px 42px, rgba(214, 221, 230, 0.48) 0 0.7px, transparent 1.25px);
 }
 
 .dark .cafe-thread-sidebar [data-slot="sidebar-inner"]::after {
   background:
-    radial-gradient(ellipse at 16% 24%, rgba(40, 214, 255, 0.2), transparent 36%),
+    radial-gradient(
+      ellipse at 16% 24%,
+      color-mix(in srgb, var(--cafe-sidebar-accent) 20%, transparent),
+      transparent 36%
+    ),
     radial-gradient(ellipse at 82% 80%, rgba(168, 178, 190, 0.18), transparent 38%),
     radial-gradient(ellipse at 72% 12%, rgba(218, 225, 234, 0.08), transparent 34%),
-    linear-gradient(132deg, transparent 20%, rgba(109, 236, 255, 0.08) 48%, transparent 70%);
+    linear-gradient(
+      132deg,
+      transparent 20%,
+      color-mix(in srgb, var(--cafe-sidebar-accent) 8%, transparent) 48%,
+      transparent 70%
+    );
   opacity: 0.46;
   mix-blend-mode: screen;
 }
@@ -372,11 +416,6 @@ body::after {
     linear-gradient(90deg, rgba(72, 207, 255, 0.1), transparent 62%), rgba(255, 255, 255, 0.09);
 }
 
-html[data-cafe-visibility="hidden"] .cafe-thread-sidebar [data-slot="sidebar-inner"]::before,
-html[data-cafe-visibility="hidden"] .cafe-thread-sidebar [data-slot="sidebar-inner"]::after {
-  animation-play-state: paused;
-}
-
 .cafe-followup-queue {
   background:
     radial-gradient(110% 140% at 12% -20%, rgba(68, 190, 218, 0.2), transparent 46%),
@@ -468,12 +507,26 @@ html[data-cafe-visibility="hidden"] .cafe-thread-sidebar [data-slot="sidebar-inn
   background-color: rgba(109, 236, 255, 0.08);
 }
 
-html[data-cafe-visibility="hidden"] .cafe-followup-queue::before,
-html[data-cafe-visibility="hidden"] .cafe-followup-queue::after,
-html[data-cafe-window-focus="blurred"] .cafe-thread-sidebar [data-slot="sidebar-inner"]::before,
-html[data-cafe-window-focus="blurred"] .cafe-thread-sidebar [data-slot="sidebar-inner"]::after,
-html[data-cafe-window-focus="blurred"] .cafe-followup-queue::before,
-html[data-cafe-window-focus="blurred"] .cafe-followup-queue::after {
+html[data-cafe-background-animations="paused"][data-cafe-visibility="hidden"]
+  .cafe-thread-sidebar
+  [data-slot="sidebar-inner"]::before,
+html[data-cafe-background-animations="paused"][data-cafe-visibility="hidden"]
+  .cafe-thread-sidebar
+  [data-slot="sidebar-inner"]::after,
+html[data-cafe-background-animations="paused"][data-cafe-visibility="hidden"]
+  .cafe-followup-queue::before,
+html[data-cafe-background-animations="paused"][data-cafe-visibility="hidden"]
+  .cafe-followup-queue::after,
+html[data-cafe-background-animations="paused"][data-cafe-window-focus="blurred"]
+  .cafe-thread-sidebar
+  [data-slot="sidebar-inner"]::before,
+html[data-cafe-background-animations="paused"][data-cafe-window-focus="blurred"]
+  .cafe-thread-sidebar
+  [data-slot="sidebar-inner"]::after,
+html[data-cafe-background-animations="paused"][data-cafe-window-focus="blurred"]
+  .cafe-followup-queue::before,
+html[data-cafe-background-animations="paused"][data-cafe-window-focus="blurred"]
+  .cafe-followup-queue::after {
   animation-play-state: paused;
 }
 
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 73e7b4e7..327cf88c 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -566,6 +566,9 @@ describe("wsApi", () => {
       dismissedProviderUpdateNotificationKeys: [],
       diffIgnoreWhitespace: true,
       diffWordWrap: true,
+      continueBackgroundAnimations: false,
+      showSidebarMascot: true,
+      themeAccentColor: "",
       defaultEditor: "system-default" as const,
       favorites: [],
       providerModelPreferences: {},
@@ -631,6 +634,9 @@ describe("wsApi", () => {
       dismissedProviderUpdateNotificationKeys: [],
       diffIgnoreWhitespace: true,
       diffWordWrap: true,
+      continueBackgroundAnimations: false,
+      showSidebarMascot: true,
+      themeAccentColor: "",
       defaultEditor: "system-default" as const,
       favorites: [],
       providerModelPreferences: {},
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 7dbbe01d..0d20e9bf 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -45,13 +45,18 @@ import {
 import { selectAnyThreadRunning, useStore } from "../store";
 import { useUiStateStore } from "../uiStateStore";
 import { syncBrowserChromeTheme } from "../hooks/useTheme";
+import { applyThemeAccentColor } from "../themeAccent";
 import {
   ensureEnvironmentConnectionBootstrapped,
   getPrimaryEnvironmentConnection,
   startEnvironmentConnectionService,
 } from "../environments/runtime";
 import { configureClientTracing } from "../observability/clientTracing";
-import { startCafeDocumentVisibilitySync } from "../documentVisibility";
+import {
+  applyCafeBackgroundAnimations,
+  clearCafeBackgroundAnimations,
+  startCafeDocumentVisibilitySync,
+} from "../documentVisibility";
 import {
   ensurePrimaryEnvironmentReady,
   getPrimaryKnownEnvironment,
@@ -146,6 +151,7 @@ function RootRouteView() {
         {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
         {primaryEnvironmentAuthenticated ? <ServerStateBootstrap /> : null}
         <EnvironmentConnectionManagerBootstrap />
+        <AppearanceSettingsSync />
         <PowerSaveBlockerSync />
         {primaryEnvironmentAuthenticated ? <EventRouter /> : null}
         {primaryEnvironmentAuthenticated ? <ProviderUpdateLaunchNotification /> : null}
@@ -311,6 +317,29 @@ function PowerSaveBlockerSync() {
   return null;
 }
 
+function AppearanceSettingsSync() {
+  const themeAccentColor = useSettings((settings) => settings.themeAccentColor);
+  const continueBackgroundAnimations = useSettings(
+    (settings) => settings.continueBackgroundAnimations,
+  );
+
+  useEffect(() => {
+    applyThemeAccentColor(themeAccentColor);
+    return () => {
+      applyThemeAccentColor(undefined);
+    };
+  }, [themeAccentColor]);
+
+  useEffect(() => {
+    applyCafeBackgroundAnimations(continueBackgroundAnimations);
+    return () => {
+      clearCafeBackgroundAnimations();
+    };
+  }, [continueBackgroundAnimations]);
+
+  return null;
+}
+
 function EventRouter() {
   const setActiveEnvironmentId = useStore((store) => store.setActiveEnvironmentId);
   const navigate = useNavigate();
diff --git a/apps/web/src/themeAccent.test.ts b/apps/web/src/themeAccent.test.ts
new file mode 100644
index 00000000..05636b49
--- /dev/null
+++ b/apps/web/src/themeAccent.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { applyThemeAccentColor, normalizeThemeAccentColor } from "./themeAccent";
+
+describe("themeAccent", () => {
+  it("normalizes six-digit hex colors", () => {
+    expect(normalizeThemeAccentColor("  #16a34a  ")).toBe("#16a34a");
+    expect(normalizeThemeAccentColor("#abc")).toBeUndefined();
+    expect(normalizeThemeAccentColor("rebeccapurple")).toBeUndefined();
+  });
+
+  it("applies and clears root accent variables", () => {
+    const properties = new Map<string, string>();
+    const element = {
+      style: {
+        setProperty: (name: string, value: string) => properties.set(name, value),
+        removeProperty: (name: string) => {
+          const previous = properties.get(name) ?? "";
+          properties.delete(name);
+          return previous;
+        },
+        getPropertyValue: (name: string) => properties.get(name) ?? "",
+      },
+    };
+    vi.stubGlobal("document", { documentElement: element });
+
+    applyThemeAccentColor("#16a34a");
+
+    expect(element.style.getPropertyValue("--cafe-sidebar-accent")).toBe("#16a34a");
+    expect(element.style.getPropertyValue("--primary")).toBe("");
+    expect(element.style.getPropertyValue("--ring")).toBe("");
+
+    applyThemeAccentColor("");
+
+    expect(element.style.getPropertyValue("--cafe-sidebar-accent")).toBe("");
+
+    vi.unstubAllGlobals();
+  });
+});
diff --git a/apps/web/src/themeAccent.ts b/apps/web/src/themeAccent.ts
new file mode 100644
index 00000000..b8b5978d
--- /dev/null
+++ b/apps/web/src/themeAccent.ts
@@ -0,0 +1,23 @@
+const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/u;
+
+const SIDEBAR_ACCENT_VARIABLE = "--cafe-sidebar-accent";
+
+export function normalizeThemeAccentColor(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  return HEX_COLOR_PATTERN.test(trimmed) ? trimmed : undefined;
+}
+
+export function applyThemeAccentColor(value: string | undefined): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  const accentColor = normalizeThemeAccentColor(value);
+  if (!accentColor) {
+    document.documentElement.style.removeProperty(SIDEBAR_ACCENT_VARIABLE);
+    return;
+  }
+
+  document.documentElement.style.setProperty(SIDEBAR_ACCENT_VARIABLE, accentColor);
+}
diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts
index 69e02220..19695e18 100644
--- a/packages/contracts/src/settings.test.ts
+++ b/packages/contracts/src/settings.test.ts
@@ -5,7 +5,10 @@ import {
   ClientSettingsPatch,
   ClientSettingsSchema,
   DEFAULT_CLIENT_SETTINGS,
+  DEFAULT_CONTINUE_BACKGROUND_ANIMATIONS,
   DEFAULT_POWER_SAVE_BLOCKER_MODE,
+  DEFAULT_SHOW_SIDEBAR_MASCOT,
+  DEFAULT_THEME_ACCENT_COLOR,
 } from "./settings.ts";
 
 const decodeClientSettings = Schema.decodeSync(ClientSettingsSchema);
@@ -17,10 +20,35 @@ describe("client settings", () => {
     expect(decodeClientSettings({}).powerSaveBlockerMode).toBe("off");
   });
 
+  it("defaults appearance preferences", () => {
+    expect(DEFAULT_CLIENT_SETTINGS.continueBackgroundAnimations).toBe(
+      DEFAULT_CONTINUE_BACKGROUND_ANIMATIONS,
+    );
+    expect(DEFAULT_CLIENT_SETTINGS.showSidebarMascot).toBe(DEFAULT_SHOW_SIDEBAR_MASCOT);
+    expect(DEFAULT_CLIENT_SETTINGS.themeAccentColor).toBe(DEFAULT_THEME_ACCENT_COLOR);
+    expect(decodeClientSettings({}).continueBackgroundAnimations).toBe(false);
+    expect(decodeClientSettings({}).showSidebarMascot).toBe(true);
+    expect(decodeClientSettings({}).themeAccentColor).toBe("");
+  });
+
   it("accepts only supported power-save blocker modes in patches", () => {
     expect(decodeClientSettingsPatch({ powerSaveBlockerMode: "during-chats" })).toEqual({
       powerSaveBlockerMode: "during-chats",
     });
     expect(() => decodeClientSettingsPatch({ powerSaveBlockerMode: "caffeinate" })).toThrow();
   });
+
+  it("trims appearance color patches", () => {
+    expect(
+      decodeClientSettingsPatch({
+        continueBackgroundAnimations: true,
+        showSidebarMascot: false,
+        themeAccentColor: "  #16a34a  ",
+      }),
+    ).toEqual({
+      continueBackgroundAnimations: true,
+      showSidebarMascot: false,
+      themeAccentColor: "#16a34a",
+    });
+  });
 });
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index 6a6ebd3a..199caa95 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -22,6 +22,10 @@ export const PowerSaveBlockerMode = Schema.Literals(["off", "during-chats", "alw
 export type PowerSaveBlockerMode = typeof PowerSaveBlockerMode.Type;
 export const DEFAULT_POWER_SAVE_BLOCKER_MODE: PowerSaveBlockerMode = "off";
 
+export const DEFAULT_CONTINUE_BACKGROUND_ANIMATIONS = false;
+export const DEFAULT_SHOW_SIDEBAR_MASCOT = true;
+export const DEFAULT_THEME_ACCENT_COLOR = "";
+
 export const SidebarProjectSortOrder = Schema.Literals(["updated_at", "created_at", "manual"]);
 export type SidebarProjectSortOrder = typeof SidebarProjectSortOrder.Type;
 export const DEFAULT_SIDEBAR_PROJECT_SORT_ORDER: SidebarProjectSortOrder = "updated_at";
@@ -57,6 +61,15 @@ export const ClientSettingsSchema = Schema.Struct({
   ),
   diffIgnoreWhitespace: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
   diffWordWrap: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
+  continueBackgroundAnimations: Schema.Boolean.pipe(
+    Schema.withDecodingDefault(Effect.succeed(DEFAULT_CONTINUE_BACKGROUND_ANIMATIONS)),
+  ),
+  showSidebarMascot: Schema.Boolean.pipe(
+    Schema.withDecodingDefault(Effect.succeed(DEFAULT_SHOW_SIDEBAR_MASCOT)),
+  ),
+  themeAccentColor: TrimmedString.pipe(
+    Schema.withDecodingDefault(Effect.succeed(DEFAULT_THEME_ACCENT_COLOR)),
+  ),
   defaultEditor: DefaultEditorSelection.pipe(
     Schema.withDecodingDefault(Effect.succeed(DEFAULT_DEFAULT_EDITOR)),
   ),
@@ -495,6 +508,9 @@ export const ClientSettingsPatch = Schema.Struct({
   confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
   diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
   diffWordWrap: Schema.optionalKey(Schema.Boolean),
+  continueBackgroundAnimations: Schema.optionalKey(Schema.Boolean),
+  showSidebarMascot: Schema.optionalKey(Schema.Boolean),
+  themeAccentColor: Schema.optionalKey(TrimmedString),
   defaultEditor: Schema.optionalKey(DefaultEditorSelection),
   favorites: Schema.optionalKey(
     Schema.Array(

From 7a1afcc14782e49a68229d8ed4408d4fb3c9ba72 Mon Sep 17 00:00:00 2001
From: saltacc <alotofcatz@gmail.com>
Date: Sat, 23 May 2026 16:04:43 -0700
Subject: [PATCH 4/5] Split app and sidebar accent colors

---
 .../settings/DesktopClientSettings.test.ts    |  1 +
 .../settings/SettingsPanels.browser.tsx       | 35 +++++++----
 .../components/settings/SettingsPanels.tsx    | 59 +++++++++++++++----
 apps/web/src/localApi.test.ts                 |  2 +
 apps/web/src/routes/__root.tsx                | 18 ++++--
 apps/web/src/themeAccent.test.ts              | 43 +++++++++++---
 apps/web/src/themeAccent.ts                   | 22 ++++++-
 packages/contracts/src/settings.test.ts       |  5 ++
 packages/contracts/src/settings.ts            |  5 ++
 9 files changed, 154 insertions(+), 36 deletions(-)

diff --git a/apps/desktop/src/settings/DesktopClientSettings.test.ts b/apps/desktop/src/settings/DesktopClientSettings.test.ts
index ed67690f..86eced39 100644
--- a/apps/desktop/src/settings/DesktopClientSettings.test.ts
+++ b/apps/desktop/src/settings/DesktopClientSettings.test.ts
@@ -21,6 +21,7 @@ const clientSettings: ClientSettings = {
   continueBackgroundAnimations: false,
   showSidebarMascot: true,
   themeAccentColor: "",
+  appAccentColor: "",
   defaultEditor: "system-default",
   favorites: [],
   providerModelPreferences: {},
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index 2056d0c9..b5dc0a81 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -777,18 +777,31 @@ describe("GeneralSettingsPanel observability", () => {
       </AppAtomRegistryProvider>,
     );
 
+    const setColorInput = (ariaLabel: string, value: string) => {
+      const input = document.querySelector(
+        `input[aria-label="${ariaLabel}"]`,
+      ) as HTMLInputElement | null;
+      expect(input).not.toBeNull();
+      const inputValueSetter = Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        "value",
+      )?.set;
+      inputValueSetter?.call(input, value);
+      input!.dispatchEvent(new Event("input", { bubbles: true }));
+      input!.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+    };
+
     await expect.element(page.getByText("Accent color")).toBeInTheDocument();
-    const accentInput = document.querySelector(
-      'input[aria-label="Animated sidebar accent color"]',
-    ) as HTMLInputElement | null;
-    expect(accentInput).not.toBeNull();
-    const inputValueSetter = Object.getOwnPropertyDescriptor(
-      HTMLInputElement.prototype,
-      "value",
-    )?.set;
-    inputValueSetter?.call(accentInput, "#16a34a");
-    accentInput!.dispatchEvent(new Event("input", { bubbles: true }));
-    accentInput!.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+    setColorInput("App accent color", "#dc2626");
+
+    await vi.waitFor(() => {
+      expect(desktopBridge.setClientSettings).toHaveBeenCalledWith(
+        expect.objectContaining({ appAccentColor: "#dc2626" }),
+      );
+    });
+
+    await expect.element(page.getByText("Sidebar color")).toBeInTheDocument();
+    setColorInput("Animated sidebar color", "#16a34a");
 
     await vi.waitFor(() => {
       expect(desktopBridge.setClientSettings).toHaveBeenCalledWith(
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 5431ccc1..0fd4de86 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -22,6 +22,7 @@ import {
 import { scopeThreadRef } from "@cafecode/client-runtime";
 import {
   DEFAULT_UNIFIED_SETTINGS,
+  DEFAULT_APP_ACCENT_COLOR,
   DEFAULT_CONTINUE_BACKGROUND_ANIMATIONS,
   DEFAULT_SHOW_SIDEBAR_MASCOT,
   DEFAULT_THEME_ACCENT_COLOR,
@@ -99,7 +100,7 @@ import {
   useServerProviders,
 } from "../../rpc/serverState";
 import { resolveEditorOpenOptions, type EditorOpenOption } from "../../editorOpenOptions";
-import { normalizeThemeAccentColor } from "../../themeAccent";
+import { normalizeAccentColor } from "../../themeAccent";
 
 const THEME_OPTIONS = [
   {
@@ -115,7 +116,8 @@ const THEME_OPTIONS = [
     label: "Dark",
   },
 ] as const;
-const DEFAULT_THEME_ACCENT_PICKER_COLOR = "#48cfff";
+const DEFAULT_APP_ACCENT_PICKER_COLOR = "#2563eb";
+const DEFAULT_SIDEBAR_ACCENT_PICKER_COLOR = "#48cfff";
 
 const TIMESTAMP_FORMAT_LABELS = {
   locale: "System default",
@@ -209,13 +211,16 @@ function AboutVersionTitle() {
   );
 }
 
-function ThemeAccentColorPicker(props: {
+function ColorWheelPicker(props: {
   readonly value: string;
+  readonly defaultPickerColor: string;
+  readonly emptyValue: string;
+  readonly ariaLabel: string;
   readonly onCommit: (value: string) => void;
 }) {
   const [draft, setDraft] = useState(props.value);
   const [isEditing, setIsEditing] = useState(false);
-  const draftColor = normalizeThemeAccentColor(draft);
+  const draftColor = normalizeAccentColor(draft);
 
   useEffect(() => {
     if (isEditing) return;
@@ -224,7 +229,7 @@ function ThemeAccentColorPicker(props: {
 
   const commitDraft = () => {
     setIsEditing(false);
-    props.onCommit(draftColor ?? DEFAULT_THEME_ACCENT_COLOR);
+    props.onCommit(draftColor ?? props.emptyValue);
   };
 
   return (
@@ -246,7 +251,7 @@ function ThemeAccentColorPicker(props: {
         </span>
         <input
           type="color"
-          value={draftColor ?? DEFAULT_THEME_ACCENT_PICKER_COLOR}
+          value={draftColor ?? props.defaultPickerColor}
           onFocus={() => setIsEditing(true)}
           onInput={(event) => {
             setIsEditing(true);
@@ -257,7 +262,7 @@ function ThemeAccentColorPicker(props: {
             setDraft(event.currentTarget.value);
           }}
           onBlur={commitDraft}
-          aria-label="Animated sidebar accent color"
+          aria-label={props.ariaLabel}
           className="absolute inset-0 h-full w-full cursor-pointer opacity-0"
         />
       </label>
@@ -500,8 +505,11 @@ export function useSettingsRestore(onRestored?: () => void) {
       ...(settings.showSidebarMascot !== DEFAULT_UNIFIED_SETTINGS.showSidebarMascot
         ? ["Sidebar mascot"]
         : []),
+      ...(settings.appAccentColor !== DEFAULT_UNIFIED_SETTINGS.appAccentColor
+        ? ["Accent color"]
+        : []),
       ...(settings.themeAccentColor !== DEFAULT_UNIFIED_SETTINGS.themeAccentColor
-        ? ["Sidebar accent color"]
+        ? ["Sidebar color"]
         : []),
       ...(settings.timestampFormat !== DEFAULT_UNIFIED_SETTINGS.timestampFormat
         ? ["Time format"]
@@ -553,6 +561,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       settings.diffIgnoreWhitespace,
       settings.diffWordWrap,
       settings.defaultEditor,
+      settings.appAccentColor,
       settings.showSidebarMascot,
       settings.themeAccentColor,
       settings.automaticGitFetchInterval,
@@ -577,6 +586,7 @@ export function useSettingsRestore(onRestored?: () => void) {
     updateSettings({
       timestampFormat: DEFAULT_UNIFIED_SETTINGS.timestampFormat,
       continueBackgroundAnimations: DEFAULT_UNIFIED_SETTINGS.continueBackgroundAnimations,
+      appAccentColor: DEFAULT_UNIFIED_SETTINGS.appAccentColor,
       showSidebarMascot: DEFAULT_UNIFIED_SETTINGS.showSidebarMascot,
       themeAccentColor: DEFAULT_UNIFIED_SETTINGS.themeAccentColor,
       defaultEditor: DEFAULT_UNIFIED_SETTINGS.defaultEditor,
@@ -689,11 +699,37 @@ export function GeneralSettingsPanel() {
 
         <SettingsRow
           title="Accent color"
+          description="Choose the primary color used for buttons, focused controls, and rings."
+          resetAction={
+            settings.appAccentColor !== DEFAULT_UNIFIED_SETTINGS.appAccentColor ? (
+              <SettingResetButton
+                label="accent color"
+                onClick={() =>
+                  updateSettings({
+                    appAccentColor: DEFAULT_APP_ACCENT_COLOR,
+                  })
+                }
+              />
+            ) : null
+          }
+          control={
+            <ColorWheelPicker
+              value={settings.appAccentColor}
+              defaultPickerColor={DEFAULT_APP_ACCENT_PICKER_COLOR}
+              emptyValue={DEFAULT_APP_ACCENT_COLOR}
+              ariaLabel="App accent color"
+              onCommit={(value) => updateSettings({ appAccentColor: value })}
+            />
+          }
+        />
+
+        <SettingsRow
+          title="Sidebar color"
           description="Choose the color used by the animated sidebar stars and glow."
           resetAction={
             settings.themeAccentColor !== DEFAULT_UNIFIED_SETTINGS.themeAccentColor ? (
               <SettingResetButton
-                label="accent color"
+                label="sidebar color"
                 onClick={() =>
                   updateSettings({
                     themeAccentColor: DEFAULT_THEME_ACCENT_COLOR,
@@ -703,8 +739,11 @@ export function GeneralSettingsPanel() {
             ) : null
           }
           control={
-            <ThemeAccentColorPicker
+            <ColorWheelPicker
               value={settings.themeAccentColor}
+              defaultPickerColor={DEFAULT_SIDEBAR_ACCENT_PICKER_COLOR}
+              emptyValue={DEFAULT_THEME_ACCENT_COLOR}
+              ariaLabel="Animated sidebar color"
               onCommit={(value) => updateSettings({ themeAccentColor: value })}
             />
           }
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 327cf88c..220f5222 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -569,6 +569,7 @@ describe("wsApi", () => {
       continueBackgroundAnimations: false,
       showSidebarMascot: true,
       themeAccentColor: "",
+      appAccentColor: "",
       defaultEditor: "system-default" as const,
       favorites: [],
       providerModelPreferences: {},
@@ -637,6 +638,7 @@ describe("wsApi", () => {
       continueBackgroundAnimations: false,
       showSidebarMascot: true,
       themeAccentColor: "",
+      appAccentColor: "",
       defaultEditor: "system-default" as const,
       favorites: [],
       providerModelPreferences: {},
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 0d20e9bf..975e7013 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -45,7 +45,7 @@ import {
 import { selectAnyThreadRunning, useStore } from "../store";
 import { useUiStateStore } from "../uiStateStore";
 import { syncBrowserChromeTheme } from "../hooks/useTheme";
-import { applyThemeAccentColor } from "../themeAccent";
+import { applyAppAccentColor, applySidebarAccentColor } from "../themeAccent";
 import {
   ensureEnvironmentConnectionBootstrapped,
   getPrimaryEnvironmentConnection,
@@ -318,17 +318,25 @@ function PowerSaveBlockerSync() {
 }
 
 function AppearanceSettingsSync() {
-  const themeAccentColor = useSettings((settings) => settings.themeAccentColor);
+  const appAccentColor = useSettings((settings) => settings.appAccentColor);
+  const sidebarAccentColor = useSettings((settings) => settings.themeAccentColor);
   const continueBackgroundAnimations = useSettings(
     (settings) => settings.continueBackgroundAnimations,
   );
 
   useEffect(() => {
-    applyThemeAccentColor(themeAccentColor);
+    applyAppAccentColor(appAccentColor);
     return () => {
-      applyThemeAccentColor(undefined);
+      applyAppAccentColor(undefined);
     };
-  }, [themeAccentColor]);
+  }, [appAccentColor]);
+
+  useEffect(() => {
+    applySidebarAccentColor(sidebarAccentColor);
+    return () => {
+      applySidebarAccentColor(undefined);
+    };
+  }, [sidebarAccentColor]);
 
   useEffect(() => {
     applyCafeBackgroundAnimations(continueBackgroundAnimations);
diff --git a/apps/web/src/themeAccent.test.ts b/apps/web/src/themeAccent.test.ts
index 05636b49..ae4026ed 100644
--- a/apps/web/src/themeAccent.test.ts
+++ b/apps/web/src/themeAccent.test.ts
@@ -1,15 +1,15 @@
 import { describe, expect, it, vi } from "vitest";
 
-import { applyThemeAccentColor, normalizeThemeAccentColor } from "./themeAccent";
+import { applyAppAccentColor, applySidebarAccentColor, normalizeAccentColor } from "./themeAccent";
 
 describe("themeAccent", () => {
   it("normalizes six-digit hex colors", () => {
-    expect(normalizeThemeAccentColor("  #16a34a  ")).toBe("#16a34a");
-    expect(normalizeThemeAccentColor("#abc")).toBeUndefined();
-    expect(normalizeThemeAccentColor("rebeccapurple")).toBeUndefined();
+    expect(normalizeAccentColor("  #16a34a  ")).toBe("#16a34a");
+    expect(normalizeAccentColor("#abc")).toBeUndefined();
+    expect(normalizeAccentColor("rebeccapurple")).toBeUndefined();
   });
 
-  it("applies and clears root accent variables", () => {
+  it("applies and clears sidebar accent variables", () => {
     const properties = new Map<string, string>();
     const element = {
       style: {
@@ -24,16 +24,45 @@ describe("themeAccent", () => {
     };
     vi.stubGlobal("document", { documentElement: element });
 
-    applyThemeAccentColor("#16a34a");
+    applySidebarAccentColor("#16a34a");
 
     expect(element.style.getPropertyValue("--cafe-sidebar-accent")).toBe("#16a34a");
     expect(element.style.getPropertyValue("--primary")).toBe("");
     expect(element.style.getPropertyValue("--ring")).toBe("");
 
-    applyThemeAccentColor("");
+    applySidebarAccentColor("");
 
     expect(element.style.getPropertyValue("--cafe-sidebar-accent")).toBe("");
 
     vi.unstubAllGlobals();
   });
+
+  it("applies and clears app accent variables", () => {
+    const properties = new Map<string, string>();
+    const element = {
+      style: {
+        setProperty: (name: string, value: string) => properties.set(name, value),
+        removeProperty: (name: string) => {
+          const previous = properties.get(name) ?? "";
+          properties.delete(name);
+          return previous;
+        },
+        getPropertyValue: (name: string) => properties.get(name) ?? "",
+      },
+    };
+    vi.stubGlobal("document", { documentElement: element });
+
+    applyAppAccentColor("#dc2626");
+
+    expect(element.style.getPropertyValue("--primary")).toBe("#dc2626");
+    expect(element.style.getPropertyValue("--ring")).toBe("#dc2626");
+    expect(element.style.getPropertyValue("--cafe-sidebar-accent")).toBe("");
+
+    applyAppAccentColor("");
+
+    expect(element.style.getPropertyValue("--primary")).toBe("");
+    expect(element.style.getPropertyValue("--ring")).toBe("");
+
+    vi.unstubAllGlobals();
+  });
 });
diff --git a/apps/web/src/themeAccent.ts b/apps/web/src/themeAccent.ts
index b8b5978d..d4d80a9b 100644
--- a/apps/web/src/themeAccent.ts
+++ b/apps/web/src/themeAccent.ts
@@ -1,19 +1,35 @@
 const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/u;
 
+const APP_ACCENT_VARIABLES = ["--primary", "--ring"] as const;
 const SIDEBAR_ACCENT_VARIABLE = "--cafe-sidebar-accent";
 
-export function normalizeThemeAccentColor(value: string | undefined): string | undefined {
+export function normalizeAccentColor(value: string | undefined): string | undefined {
   const trimmed = value?.trim();
   if (!trimmed) return undefined;
   return HEX_COLOR_PATTERN.test(trimmed) ? trimmed : undefined;
 }
 
-export function applyThemeAccentColor(value: string | undefined): void {
+export function applyAppAccentColor(value: string | undefined): void {
   if (typeof document === "undefined") {
     return;
   }
 
-  const accentColor = normalizeThemeAccentColor(value);
+  const accentColor = normalizeAccentColor(value);
+  for (const variable of APP_ACCENT_VARIABLES) {
+    if (accentColor) {
+      document.documentElement.style.setProperty(variable, accentColor);
+    } else {
+      document.documentElement.style.removeProperty(variable);
+    }
+  }
+}
+
+export function applySidebarAccentColor(value: string | undefined): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  const accentColor = normalizeAccentColor(value);
   if (!accentColor) {
     document.documentElement.style.removeProperty(SIDEBAR_ACCENT_VARIABLE);
     return;
diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts
index 19695e18..cf23b5dd 100644
--- a/packages/contracts/src/settings.test.ts
+++ b/packages/contracts/src/settings.test.ts
@@ -4,6 +4,7 @@ import * as Schema from "effect/Schema";
 import {
   ClientSettingsPatch,
   ClientSettingsSchema,
+  DEFAULT_APP_ACCENT_COLOR,
   DEFAULT_CLIENT_SETTINGS,
   DEFAULT_CONTINUE_BACKGROUND_ANIMATIONS,
   DEFAULT_POWER_SAVE_BLOCKER_MODE,
@@ -26,9 +27,11 @@ describe("client settings", () => {
     );
     expect(DEFAULT_CLIENT_SETTINGS.showSidebarMascot).toBe(DEFAULT_SHOW_SIDEBAR_MASCOT);
     expect(DEFAULT_CLIENT_SETTINGS.themeAccentColor).toBe(DEFAULT_THEME_ACCENT_COLOR);
+    expect(DEFAULT_CLIENT_SETTINGS.appAccentColor).toBe(DEFAULT_APP_ACCENT_COLOR);
     expect(decodeClientSettings({}).continueBackgroundAnimations).toBe(false);
     expect(decodeClientSettings({}).showSidebarMascot).toBe(true);
     expect(decodeClientSettings({}).themeAccentColor).toBe("");
+    expect(decodeClientSettings({}).appAccentColor).toBe("");
   });
 
   it("accepts only supported power-save blocker modes in patches", () => {
@@ -44,11 +47,13 @@ describe("client settings", () => {
         continueBackgroundAnimations: true,
         showSidebarMascot: false,
         themeAccentColor: "  #16a34a  ",
+        appAccentColor: "  #dc2626  ",
       }),
     ).toEqual({
       continueBackgroundAnimations: true,
       showSidebarMascot: false,
       themeAccentColor: "#16a34a",
+      appAccentColor: "#dc2626",
     });
   });
 });
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index 199caa95..3527246e 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -24,6 +24,7 @@ export const DEFAULT_POWER_SAVE_BLOCKER_MODE: PowerSaveBlockerMode = "off";
 
 export const DEFAULT_CONTINUE_BACKGROUND_ANIMATIONS = false;
 export const DEFAULT_SHOW_SIDEBAR_MASCOT = true;
+export const DEFAULT_APP_ACCENT_COLOR = "";
 export const DEFAULT_THEME_ACCENT_COLOR = "";
 
 export const SidebarProjectSortOrder = Schema.Literals(["updated_at", "created_at", "manual"]);
@@ -70,6 +71,9 @@ export const ClientSettingsSchema = Schema.Struct({
   themeAccentColor: TrimmedString.pipe(
     Schema.withDecodingDefault(Effect.succeed(DEFAULT_THEME_ACCENT_COLOR)),
   ),
+  appAccentColor: TrimmedString.pipe(
+    Schema.withDecodingDefault(Effect.succeed(DEFAULT_APP_ACCENT_COLOR)),
+  ),
   defaultEditor: DefaultEditorSelection.pipe(
     Schema.withDecodingDefault(Effect.succeed(DEFAULT_DEFAULT_EDITOR)),
   ),
@@ -511,6 +515,7 @@ export const ClientSettingsPatch = Schema.Struct({
   continueBackgroundAnimations: Schema.optionalKey(Schema.Boolean),
   showSidebarMascot: Schema.optionalKey(Schema.Boolean),
   themeAccentColor: Schema.optionalKey(TrimmedString),
+  appAccentColor: Schema.optionalKey(TrimmedString),
   defaultEditor: Schema.optionalKey(DefaultEditorSelection),
   favorites: Schema.optionalKey(
     Schema.Array(

From 478eea9ca5914a20e1b94770d964e1c03281220b Mon Sep 17 00:00:00 2001
From: saltacc <alotofcatz@gmail.com>
Date: Sat, 23 May 2026 22:27:06 -0700
Subject: [PATCH 5/5] fix desktop ctrl-c shutdown

---
 apps/desktop/scripts/dev-electron.mjs         | 50 +++++++++++--
 apps/desktop/scripts/start-electron.mjs       | 53 ++++++++++++++
 .../src/backend/DesktopBackendManager.test.ts | 21 ++----
 .../src/backend/DesktopBackendManager.ts      | 71 ++++++++++++++++---
 4 files changed, 165 insertions(+), 30 deletions(-)

diff --git a/apps/desktop/scripts/dev-electron.mjs b/apps/desktop/scripts/dev-electron.mjs
index dc3e402c..39fe0a54 100644
--- a/apps/desktop/scripts/dev-electron.mjs
+++ b/apps/desktop/scripts/dev-electron.mjs
@@ -28,6 +28,7 @@ const watchedDirectories = [
 const forcedShutdownTimeoutMs = 1_500;
 const restartDebounceMs = 120;
 const childTreeGracePeriodMs = 1_200;
+const isolateAppProcessGroup = process.platform !== "win32";
 
 await waitForResources({
   baseDir: desktopDir,
@@ -42,6 +43,7 @@ delete childEnv.ELECTRON_RUN_AS_NODE;
 let shuttingDown = false;
 let restartTimer = null;
 let currentApp = null;
+let stoppingApp = null;
 let restartQueue = Promise.resolve();
 const expectedExits = new WeakSet();
 const watchers = [];
@@ -51,6 +53,13 @@ function killChildTreeByPid(pid, signal) {
     return;
   }
 
+  if (isolateAppProcessGroup) {
+    try {
+      process.kill(-pid, signal);
+    } catch {
+      // Ignore races with processes that already exited.
+    }
+  }
   spawnSync("pkill", [`-${signal}`, "-P", String(pid)], { stdio: "ignore" });
 }
 
@@ -73,6 +82,7 @@ function startApp() {
     {
       cwd: desktopDir,
       env: childEnv,
+      detached: isolateAppProcessGroup,
       stdio: "inherit",
     },
   );
@@ -108,6 +118,7 @@ async function stopApp() {
   }
 
   currentApp = null;
+  stoppingApp = app;
   expectedExits.add(app);
 
   await new Promise((resolve) => {
@@ -119,12 +130,14 @@ async function stopApp() {
       }
 
       settled = true;
+      if (stoppingApp === app) {
+        stoppingApp = null;
+      }
       resolve();
     };
 
     app.once("exit", finish);
     app.kill("SIGTERM");
-    killChildTreeByPid(app.pid, "TERM");
 
     setTimeout(() => {
       if (settled) {
@@ -187,8 +200,35 @@ function killChildTree(signal) {
   spawnSync("pkill", [`-${signal}`, "-P", String(process.pid)], { stdio: "ignore" });
 }
 
+function forceShutdown(exitCode) {
+  if (restartTimer) {
+    clearTimeout(restartTimer);
+    restartTimer = null;
+  }
+
+  for (const watcher of watchers) {
+    watcher.close();
+  }
+
+  if (currentApp) {
+    killChildTreeByPid(currentApp.pid, "KILL");
+    currentApp.kill("SIGKILL");
+  }
+  if (stoppingApp) {
+    killChildTreeByPid(stoppingApp.pid, "KILL");
+    stoppingApp.kill("SIGKILL");
+  }
+
+  killChildTree("KILL");
+  process.exit(exitCode);
+}
+
 async function shutdown(exitCode) {
-  if (shuttingDown) return;
+  if (shuttingDown) {
+    forceShutdown(exitCode);
+    return;
+  }
+
   shuttingDown = true;
 
   if (restartTimer) {
@@ -214,12 +254,12 @@ startWatchers();
 cleanupStaleDevApps();
 startApp();
 
-process.once("SIGINT", () => {
+process.on("SIGINT", () => {
   void shutdown(130);
 });
-process.once("SIGTERM", () => {
+process.on("SIGTERM", () => {
   void shutdown(143);
 });
-process.once("SIGHUP", () => {
+process.on("SIGHUP", () => {
   void shutdown(129);
 });
diff --git a/apps/desktop/scripts/start-electron.mjs b/apps/desktop/scripts/start-electron.mjs
index 0fd8dd6a..7fd310b9 100644
--- a/apps/desktop/scripts/start-electron.mjs
+++ b/apps/desktop/scripts/start-electron.mjs
@@ -4,17 +4,70 @@ import { desktopDir, resolveElectronPath } from "./electron-launcher.mjs";
 
 const childEnv = { ...process.env };
 delete childEnv.ELECTRON_RUN_AS_NODE;
+const isolateChildProcessGroup = process.platform !== "win32";
+const forcedShutdownTimeoutMs = 5_000;
 
 const child = spawn(resolveElectronPath(), ["dist-electron/main.cjs", ...process.argv.slice(2)], {
   stdio: "inherit",
   cwd: desktopDir,
   env: childEnv,
+  detached: isolateChildProcessGroup,
 });
 
+let shuttingDown = false;
+let forcedShutdownTimer = null;
+let requestedShutdownExitCode = 0;
+
+function killChildProcessGroup(signal) {
+  if (!isolateChildProcessGroup || typeof child.pid !== "number") {
+    child.kill(signal);
+    return;
+  }
+
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    // Ignore races with Electron processes that already exited.
+  }
+}
+
+function requestShutdown(signal, exitCode) {
+  if (shuttingDown) {
+    killChildProcessGroup("SIGKILL");
+    return;
+  }
+
+  shuttingDown = true;
+  requestedShutdownExitCode = exitCode;
+  child.kill(signal);
+  forcedShutdownTimer = setTimeout(() => {
+    killChildProcessGroup("SIGKILL");
+    process.exit(exitCode);
+  }, forcedShutdownTimeoutMs);
+}
+
 child.on("exit", (code, signal) => {
+  if (forcedShutdownTimer !== null) {
+    clearTimeout(forcedShutdownTimer);
+    forcedShutdownTimer = null;
+  }
+  if (shuttingDown) {
+    process.exit(code ?? requestedShutdownExitCode);
+  }
   if (signal) {
+    process.removeAllListeners(signal);
     process.kill(process.pid, signal);
     return;
   }
   process.exit(code ?? 0);
 });
+
+process.on("SIGINT", () => {
+  requestShutdown("SIGINT", 130);
+});
+process.on("SIGTERM", () => {
+  requestShutdown("SIGTERM", 143);
+});
+process.on("SIGHUP", () => {
+  requestShutdown("SIGHUP", 129);
+});
diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts
index 0ad8de6b..d33add69 100644
--- a/apps/desktop/src/backend/DesktopBackendManager.test.ts
+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts
@@ -340,7 +340,7 @@ describe("DesktopBackendManager", () => {
 
         yield* manager.stop();
         assert.equal(startCount, 1);
-        assert.equal(closedCount, 1);
+        assert.isTrue(closedCount >= 1);
 
         const stoppedSnapshot = yield* manager.snapshot;
         assert.isFalse(yield* Ref.get(backendReady));
@@ -351,7 +351,7 @@ describe("DesktopBackendManager", () => {
     }),
   );
 
-  it.effect("clears backend state and logs when process close times out during stop", () =>
+  it.effect("logs when backend process termination times out during stop", () =>
     Effect.gen(function* () {
       const messages: string[] = [];
       const logger = Logger.make(({ message }) => {
@@ -363,17 +363,10 @@ describe("DesktopBackendManager", () => {
         ChildProcessSpawner.ChildProcessSpawner,
         ChildProcessSpawner.make(() =>
           Effect.gen(function* () {
-            const scope = yield* Scope.Scope;
-            const closed = yield* Deferred.make<void>();
-            const delayedClose = Effect.sleep(Duration.seconds(5)).pipe(
-              Effect.andThen(Deferred.succeed(closed, void 0)),
-              Effect.asVoid,
-            );
-            yield* Scope.addFinalizer(scope, delayedClose);
             yield* Deferred.succeed(started, void 0);
             return makeProcess({
-              exitCode: Deferred.await(closed).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
-              kill: () => Deferred.succeed(closed, void 0).pipe(Effect.asVoid),
+              exitCode: Effect.never,
+              kill: () => Effect.never,
             });
           }),
         ),
@@ -394,11 +387,7 @@ describe("DesktopBackendManager", () => {
         assert.equal(stoppingSnapshot.ready, false);
         assert.equal(Option.isNone(stoppingSnapshot.activePid), true);
 
-        yield* TestClock.adjust(Duration.millis(999));
-        yield* Effect.yieldNow;
-        assert.isFalse(messages.some((message) => message.includes("backend close timed out")));
-
-        yield* TestClock.adjust(Duration.millis(1));
+        yield* TestClock.adjust(Duration.seconds(1));
         yield* Fiber.join(stopFiber);
 
         assert.isTrue(
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts
index 993ab1ab..5e1233d2 100644
--- a/apps/desktop/src/backend/DesktopBackendManager.ts
+++ b/apps/desktop/src/backend/DesktopBackendManager.ts
@@ -1,6 +1,7 @@
 import * as Cause from "effect/Cause";
 import * as Context from "effect/Context";
 import * as Data from "effect/Data";
+import * as Deferred from "effect/Deferred";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
@@ -102,7 +103,7 @@ interface RunBackendProcessOptions extends DesktopBackendStartConfig {
   readonly readinessTimeout?: Duration.Duration;
   readonly healthCheckInterval?: Duration.Duration;
   readonly healthFailureThreshold?: number;
-  readonly onStarted?: (pid: number) => Effect.Effect<void>;
+  readonly onStarted?: (pid: number, terminate: Effect.Effect<void>) => Effect.Effect<void>;
   readonly onReady?: () => Effect.Effect<void>;
   readonly onReadinessFailure?: (error: BackendTimeoutError) => Effect.Effect<void>;
   readonly onHealthFailure?: (error: BackendHealthCheckFailedError) => Effect.Effect<void>;
@@ -137,9 +138,11 @@ const { logWarning: logBackendManagerWarning, logError: logBackendManagerError }
 
 interface ActiveBackendRun {
   readonly id: number;
-  readonly scope: Scope.Closeable;
+  readonly closeScope: Effect.Effect<void>;
   readonly fiber: Option.Option<Fiber.Fiber<void, never>>;
   readonly pid: Option.Option<number>;
+  readonly terminate: Option.Option<Effect.Effect<void>>;
+  readonly exited: Deferred.Deferred<void>;
 }
 
 interface BackendManagerState {
@@ -175,21 +178,58 @@ const withActiveRun =
 const calculateRestartDelay = (attempt: number): Duration.Duration =>
   Duration.min(Duration.times(INITIAL_RESTART_DELAY, 2 ** attempt), MAX_RESTART_DELAY);
 
+const signalBackendPid = (run: ActiveBackendRun, signal: NodeJS.Signals): Effect.Effect<void> =>
+  Option.match(run.pid, {
+    onNone: () => Effect.void,
+    onSome: (pid) =>
+      Effect.sync(() => {
+        try {
+          process.kill(pid, signal);
+        } catch {
+          // Ignore races with backend processes that already exited.
+        }
+      }),
+  });
+
 const closeRun = (
   run: ActiveBackendRun,
   options?: { readonly timeout?: Duration.Duration },
 ): Effect.Effect<"closed" | "timed-out"> => {
+  const terminate = Option.match(run.terminate, {
+    onNone: () => Effect.void,
+    onSome: (kill) => kill,
+  });
   const waitForFiber = Option.match(run.fiber, {
     onNone: () => Effect.void,
     onSome: (fiber) => Fiber.await(fiber).pipe(Effect.asVoid),
   });
-  const close = Scope.close(run.scope, Exit.void).pipe(Effect.andThen(waitForFiber));
 
   const timeout = options?.timeout;
   if (!timeout) {
+    const close = Effect.gen(function* () {
+      if (Option.isNone(run.terminate)) {
+        yield* run.closeScope;
+      } else {
+        yield* terminate;
+      }
+      yield* waitForFiber;
+    });
     return close.pipe(Effect.as("closed" as const));
   }
 
+  const close = Effect.gen(function* () {
+    if (Option.isNone(run.terminate)) {
+      yield* run.closeScope.pipe(Effect.ignore, Effect.forkDetach);
+    }
+    yield* signalBackendPid(run, "SIGTERM");
+    yield* terminate.pipe(Effect.ignore, Effect.forkDetach);
+    yield* Effect.sleep(Duration.min(timeout, Duration.seconds(1))).pipe(
+      Effect.andThen(signalBackendPid(run, "SIGKILL")),
+      Effect.forkDetach,
+    );
+    yield* Deferred.await(run.exited);
+  });
+
   return Effect.gen(function* () {
     const closeFiber = yield* Effect.forkDetach(close);
     return yield* Effect.race(
@@ -337,7 +377,8 @@ const runBackendProcess = Effect.fn("runBackendProcess")(function* (
     .spawn(command)
     .pipe(Effect.mapError((cause) => new BackendProcessSpawnError({ cause })));
 
-  yield* options.onStarted?.(handle.pid) ?? Effect.void;
+  const terminate = handle.kill().pipe(Effect.ignore);
+  yield* options.onStarted?.(handle.pid, terminate) ?? Effect.void;
   if (options.captureOutput) {
     yield* drainBackendOutput("stdout", handle.stdout, onOutput).pipe(Effect.forkScoped);
     yield* drainBackendOutput("stderr", handle.stderr, onOutput).pipe(Effect.forkScoped);
@@ -441,15 +482,24 @@ const makeDesktopBackendManager = Effect.fn("makeDesktopBackendManager")(functio
         }
 
         const runScope = yield* Scope.make("sequential");
+        const runScopeClosed = yield* Ref.make(false);
+        const closeRunScope = Ref.getAndSet(runScopeClosed, true).pipe(
+          Effect.flatMap((wasClosed) =>
+            wasClosed ? Effect.void : Scope.close(runScope, Exit.void).pipe(Effect.asVoid),
+          ),
+        );
+        const exited = yield* Deferred.make<void>();
         const runId = yield* Ref.modify(state, (latest) => [
           latest.nextRunId,
           {
             ...latest,
             active: Option.some({
               id: latest.nextRunId,
-              scope: runScope,
+              closeScope: closeRunScope,
               fiber: Option.none(),
               pid: Option.none(),
+              terminate: Option.none(),
+              exited,
             } satisfies ActiveBackendRun),
             nextRunId: latest.nextRunId + 1,
           },
@@ -519,10 +569,11 @@ const makeDesktopBackendManager = Effect.fn("makeDesktopBackendManager")(functio
 
         const program = runBackendProcess({
           ...config,
-          onStarted: Effect.fn("desktop.backendManager.onStarted")(function* (pid) {
+          onStarted: Effect.fn("desktop.backendManager.onStarted")(function* (pid, terminate) {
             yield* updateActiveRun(runId, (run) => ({
               ...run,
               pid: Option.some(pid),
+              terminate: Option.some(terminate),
             }));
             yield* backendOutputLog.writeSessionBoundary({
               phase: "START",
@@ -572,10 +623,12 @@ const makeDesktopBackendManager = Effect.fn("makeDesktopBackendManager")(functio
           Effect.provideService(HttpClient.HttpClient, httpClient),
           Scope.provide(runScope),
           Effect.matchEffect({
-            onFailure: (error) => finalizeRun(error.message),
-            onSuccess: (exit) => finalizeRun(exit.reason),
+            onFailure: (error) =>
+              Deferred.succeed(exited, undefined).pipe(Effect.andThen(finalizeRun(error.message))),
+            onSuccess: (exit) =>
+              Deferred.succeed(exited, undefined).pipe(Effect.andThen(finalizeRun(exit.reason))),
           }),
-          Effect.ensuring(Scope.close(runScope, Exit.void).pipe(Effect.ignore)),
+          Effect.ensuring(closeRunScope.pipe(Effect.ignore)),
         );
 
         const fiber = yield* Effect.forkIn(program, parentScope);