mulmoterminal 4.4.0 → 4.5.0

package/README.md

@@ -343,8 +343,8 @@ The launcher detects it and prints the exact, OS-appropriate removal command; ru
 ┌──────────────────────────────────────┐         ┌─────────────────────────────────────────────┐
 │ Browser (Vue 3 + xterm.js)            │         │ Server (Express + Node)                       │
 │                                       │         │                                               │
-│  Sidebar.vue ──subscribe("sessions")──┼──SIO───►│  socket.io  /ws/pubsub   ── publish ──┐       │
-│      ▲  refetch on any push           │         │                                       │       │
+│  App.vue ──────subscribe("sessions")──┼──SIO───►│  socket.io  /ws/pubsub   ── publish ──┐       │
+│      ▲  refetch on any push (favicon) │         │                                       │       │
 │      └──── GET /api/sessions ─────────┼──HTTP──►│  Express   /api/sessions              │       │
 │                                       │         │            /api/hook  ◄──curl── hooks │       │
 │  Terminal.vue ── ws JSON msgs ────────┼──WS────►│  ws        /ws  ──► node-pty ─► `claude`──hooks┘
@@ -353,7 +353,8 @@ The launcher detects it and prints the exact, OS-appropriate removal command; ru
 ```
 
 - **Terminal I/O** flows over a raw WebSocket (`/ws`), one PTY per session.
-- **Session list** is fetched over HTTP (`/api/sessions`).
+- **Session list** is fetched over HTTP (`/api/sessions`) — by `App.vue` for the tab favicon,
+  and by an empty cell's launch form (`?cwd=`) for its resume rows.
 - **Live activity** is pushed over a Socket.IO pub/sub channel (`/ws/pubsub`);
   the server learns of activity from **Claude hooks** that POST to `/api/hook`.
 - **Other terminals** run on their own raw WebSockets: **Codex** sessions on `/ws/codex`,
@@ -385,12 +386,12 @@ SDK; we drive the real interactive CLI and relay its TTY over the WebSocket.
 
 ---
 
-## Agents: Claude, Codex & Antigravity
+## Agents: Claude, Codex, Antigravity & Grok
 
 MulmoTerminal drives **interactive coding-agent CLIs**, not just Claude. An
 `AgentAdapter` seam abstracts the per-agent bits (which binary to spawn, how it resumes)
-so the PTY, grid, persistence, and GUI-panel plumbing stay shared. Three adapters ship
-today — **Claude Code** (the default), **Codex**, and **Antigravity** (`agy`).
+so the PTY, grid, persistence, and GUI-panel plumbing stay shared. Four adapters ship
+today — **Claude Code** (the default), **Codex**, **Antigravity** (`agy`), and **Grok**.
 
 - **Claude** — spawned as `claude` (override with `CLAUDE_BIN`). The server passes
   `--session-id <uuid>`, so it knows the live session's id even before its transcript
@@ -403,18 +404,22 @@ today — **Claude Code** (the default), **Codex**, and **Antigravity** (`agy`).
   cockpit roster next to Claude's. Because Codex only mints its rollout id **after** the first
   turn, the server watches `~/.codex/sessions/**/rollout-*.jsonl` (home overridable via
   `CODEX_HOME`) and maps the new rollout to the session — attributed only when it's
-  unambiguous, never by "newest wins". Resume reattaches a live PTY, adopts a surviving
-  tmux session, or cold-resumes the rollout id.
+  unambiguous, never by "newest wins". That mapping is appended to
+  `~/.mulmoterminal/codex-rollouts.jsonl`, so a conversation is still resumable after the server
+  restarts — without it a session whose tmux is also gone came back as a fresh codex. Resume
+  reattaches a live PTY, adopts a surviving tmux session, or cold-resumes the rollout id.
 - **Antigravity** — spawned as `agy` (override with `ANTIGRAVITY_BIN`; `ANTIGRAVITY_MODEL` sets
   `--model`). Antigravity runs on its own WebSocket (`/ws/antigravity`). Like Codex it mints its
   own conversation id, so the server watches `~/.gemini/antigravity-cli/brain/` (home overridable
   via `ANTIGRAVITY_HOME`) for the directory the new conversation creates — attributed only when
   unambiguous — and cold-resumes it with `--conversation <id>`. That mapping is appended to
   `~/.mulmoterminal/antigravity-conversations.jsonl`, so a conversation is still resumable after
-  the server restarts.
+  the server restarts — the same log Codex keeps, in the same format.
 
-  Its **GUI tools work differently**, because `agy` takes no MCP flag: it reads its servers from
-  `.agents/mcp_config.json` in the working directory. MulmoTerminal writes that file from the
+  Its **GUI tools work differently — in the workspace too**, because `agy` takes no MCP flag: it
+  reads its servers from `.agents/mcp_config.json` in the working directory. So it never gets the
+  workspace's "every tool automatically"; register what it needs with the Canvas switches, wherever
+  it runs (see [MCP server ids](#mcp-server-ids-why-a-workspace-cell-and-a-project-cell-disagree)). MulmoTerminal writes that file from the
   directory's [Canvas switches](#wiki-collections--the-gui-panel) — the same switches Claude's cells read — so
   one switch serves every agent, and rewrites it whenever a switch flips or an agy session starts.
   Servers in it that MulmoTerminal did not write are left alone, the file is removed once no group
@@ -424,9 +429,29 @@ today — **Claude Code** (the default), **Codex**, and **Antigravity** (`agy`).
   per directory and shared by every session running there — and reaches the bridge through the agy
   process's own environment instead.
 
-**Choosing an agent.** Each grid cell's launch form carries a **Claude / Codex /
-Antigravity / Shell** toggle, and the Collections browser a **Claude / Codex /
-Antigravity** one (your choice is remembered).
+- **Grok** — spawned as `grok` (override with `GROK_BIN`; `GROK_MODEL` sets `--model`), on its own
+  WebSocket (`/ws/grok`). It resumes the way **Claude** does rather than the way Codex and
+  Antigravity do: `grok --session-id <uuid>` starts a conversation under an id MulmoTerminal minted,
+  so there is no watcher, no attribution guess, and no mapping log — the id the browser holds is
+  grok's own. A reconnect passes `--resume <id>` instead, but only once a conversation by that name
+  exists on disk: grok writes one under `~/.grok/sessions/<url-encoded cwd>/<id>/` (home overridable
+  via `GROK_HOME`) after the first turn, and re-using a `--session-id` that already exists is a hard
+  error, which is why the two flags are never sent together.
+
+  Its **GUI tools work like Antigravity's — in the workspace too** and for the same reason: `grok`
+  takes no MCP flag, so it never gets the workspace's "every tool automatically" either, and
+  MulmoTerminal registers the bridge in `.grok/config.toml` (grok's project-scope config) from the
+  directory's [Canvas switches](#wiki-collections--the-gui-panel), wherever it runs (see
+  [MCP server ids](#mcp-server-ids-why-a-workspace-cell-and-a-project-cell-disagree)). That file is TOML and yours, so —
+  unlike agy's JSON — MulmoTerminal never rewrites it directly: it drives `grok mcp add -s project` /
+  `grok mcp remove -s project`, and only for the server ids it wrote itself. Nothing else in the file
+  is touched, a directory already in the right state runs no command at all, and the file is added to
+  `.git/info/exclude` only when MulmoTerminal created it. As with agy, the **session id is never
+  written into that file** — it reaches the bridge through the grok process's own environment.
+
+**Choosing an agent.** Each grid cell's launch form carries the **Agent Picker** — a
+**Claude / Codex / Antigravity / Grok / Shell** toggle — and the Collections browser a **Claude /
+Codex / Antigravity / Grok** one (your choice is remembered).
 **Shell** is not an agent: it runs your OS default shell (`$SHELL`, or `/bin/sh`) in the
 chosen directory, with nothing to install and nothing to configure. It starts a launcher
 cell, so it has no model, no MCP registration, and no worktree — those rows disappear
@@ -520,6 +545,9 @@ the `claude` / `codex` sessions themselves.
 | `ANTIGRAVITY_BIN` | `agy`     | The Antigravity CLI binary to spawn. |
 | `ANTIGRAVITY_MODEL` | agy default | Model passed to Antigravity as `--model` (unset = agy's own default). |
 | `ANTIGRAVITY_HOME` | `~/.gemini/antigravity-cli` | Antigravity home directory containing session brain storage. |
+| `GROK_BIN` | `grok`    | The Grok CLI binary to spawn. |
+| `GROK_MODEL` | grok default | Model passed to Grok as `--model` (unset = grok's own default). |
+| `GROK_HOME` | `~/.grok` | Grok home directory containing its per-directory session store. |
 | `MULMOTERMINAL_HOME` | `~/.mulmoterminal` | Root for managed **git worktrees**. |
 | `CLAUDE_CONFIG_DIR` | `~` | Claude Code's own config directory. `.claude.json` lives **inside** it, so relocating your Claude Code config moves that file too — MulmoTerminal reads it to tell whether the per-project GUI MCP server is registered (`server/infra/gui-mcp-registration.ts`). Leave it unset and `~/.claude.json` is used. |
 | `MULMOCLAUDE_WORKSPACE_PATH` | `~/mulmoclaude` | Where the managed MulmoClaude workspace lives. MulmoTerminal seeds presets/helps **only** into this directory, so launching in an arbitrary project never writes them there (`server/backends/workspaceSetup.ts`). Set it to the same value MulmoClaude uses. |
@@ -543,7 +571,7 @@ The Settings modal (⚙) persists per-user UI choices to `~/.mulmoterminal/confi
 
 ![The Settings modal — theme, notification sound, PR repos, launch commands, and MCP servers](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/settings.png)
 
-*Open it from the ⚙ button in the toolbar. Pick a **theme**, set the **terminal font size** and **scroll speed**, set a custom **attention sound**, list the repos the cross-repo **PRs & Issues** view should aggregate, add **launch commands** for grid cells, and register your own **MCP servers** — no need to hand-edit the config file. Note that **theme, font size and scroll speed are stored per browser** (they're display preferences, so a phone and a desktop keep their own); the rest live in `~/.mulmoterminal/config.json` and are shared by every client.*
+*Open it from the ⚙ button in the toolbar. Pick a **theme**, set the **terminal font size**, **font** and **scroll speed**, set a custom **attention sound**, list the repos the cross-repo **PRs & Issues** view should aggregate, add **launch commands** for grid cells, register your own **MCP servers**, and turn on the switches for what this app writes on your behalf — **issue work comments**, the **PR clone footer**, the **closing summary**, the **decision digest**, the **dev worklog** — no need to hand-edit the config file. Four settings stay with their skill because a form would be the wrong tool for them (`keymap`, `themes`, `providers`, `buttons`/`chips`); Settings shows what each is doing now and launches that skill. Note that **theme, font size and scroll speed are stored per browser** (they're display preferences, so a phone and a desktop keep their own); the rest live in `~/.mulmoterminal/config.json` and are shared by every client.*
 
 | Field        | Meaning |
 | ------------ | ------- |
@@ -552,24 +580,27 @@ The Settings modal (⚙) persists per-user UI choices to `~/.mulmoterminal/confi
 | `soundKinds` | Which moments beep — see [Notification sounds](#notification-sounds). Defaults to `["finished","waiting"]`; the other kinds are opt-in. |
 | `sounds`     | Per-kind sound: `{ "waiting": "preset:coin" }`. A `preset:<id>` reference or an absolute path; a kind with no entry falls back to `soundFile`. |
 | `prRepos`    | `owner/repo` entries whose open PRs/issues the cross-repo **PRs & Issues** view aggregates, using whichever CLI the host needs — your own `gh` or `glab` login, so no token is stored here. An entry may name its host — `gitlab.com/group/project` is read with `glab`, and work can be started on it, commented on and turned into a merge request. A host that is neither shows a row saying so. |
-| `gitlabHosts` | Hosts that run a **self-hosted GitLab**, e.g. `["gitlab.example.com"]`. Nothing in a URL says which forge a host runs, so declaring it is what lets `prRepos` entries on that host be read with `glab` — everything gitlab.com can do, it can do. Needs `glab auth login --hostname <host>`. config.json only (no Settings control), so a hand edit takes effect on the next server start. |
+| `gitlabHosts` | Hosts that run a **self-hosted GitLab**, e.g. `["gitlab.example.com"]`. Nothing in a URL says which forge a host runs, so declaring it is what lets `prRepos` entries on that host be read with `glab` — everything gitlab.com can do, it can do. Needs `glab auth login --hostname <host>`. Editable in Settings → **GitHub and GitLab**; either way it takes effect on the next server start. |
 | `repoDirs`   | `{ "owner/repo": "/abs/path" }` — which local clone work on a repo starts in, when you keep several side by side. Only the *choice* is stored; which clones exist is re-derived from `cwdPresets` on every read, and an entry that no longer names a clone of that repo is ignored. |
-| `launchers`  | `{ label, command }` entries offered in a grid cell's launcher besides the agents — any interactive command. A plain shell needs no entry: the launch form's **Shell** toggle opens `$SHELL` unconfigured. |
+| `launchers`  | `{ label, command }` entries offered in a grid cell's launcher besides the agents — any interactive command. A plain shell needs no entry: the Agent Picker's **Shell** option opens `$SHELL` unconfigured. |
+| `customAgents` | `{ id, label, agent, command }` entries offered in the **Agent Picker** — your own way of starting Claude Code (`ollama launch claude --model … --`, a wrapper script). Unlike a launcher, Claude Code's own argv is **appended** to `command`, so the cell is a real session: resume, cost, context, GUI tools. `agent` says which agent's arguments to append and is required (`"claude"` is the only value today); `command` must stop taking arguments where Claude Code's begin — hence the trailing `--` above. Up to 8. |
 | `quickCommands` | `{ label, text, agents? }` phrases the **phone** offers as chips on a session's terminal view. Tapping one puts `text` in the input box; it is not sent until you press send. `agents` (`"claude"` / `"codex"` / `"shell"`) scopes a chip to session kinds — omit it to offer the chip everywhere. Empty by default. |
-| `userMcpServers` | `{ id, url }` HTTP MCP servers merged into the `--mcp-config` of the Claude sessions that carry the full GUI MCP — a cell whose working directory is the **workspace**, and a session the server starts itself (the phone, a scheduled task) unless it asks for a grid cell's shape, as an issue's seed session does (`issueSpawnOptions`). A cell in a project directory loads its own MCP config instead. Takes effect on the next session. |
+| `userMcpServers` | `{ id, url }` HTTP MCP servers merged into the `--mcp-config` of the **Claude** sessions that carry the full GUI MCP (codex is handed the GUI server alone, `codexGuiMcpServers`) — a cell whose working directory is the **workspace**, and a session the server starts itself (the phone, a scheduled task) unless it asks for a grid cell's shape, as an issue's seed session does (`issueSpawnOptions`). A cell in a project directory does not get this merge; the MCP config the user wrote is read either way. Takes effect on the next session. |
 | `buttons`    | Header action buttons — see [Header buttons](#header-buttons). Omit to keep the defaults; set to replace them. |
-| `chips`      | Header info chips (`dir` / `git` / `work` / `diff` / `ctx` / `usage` / `status` / `tools`, or custom text). Omit to keep the default set; `[]` hides all built-ins. `work` shows which PR / issue the cell is on (`#977 → #966`) and clears itself when the PR merges — see the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#work-chip). |
+| `chips`      | Header info chips (`dir` / `git` / `work` / `diff` / `ctx` / `usage` / `status` / `tools` / `env`, or custom text). `env` shows what this working tree was reserved by [`worktreeEnv`](#per-directory-settings-projectmulmoterminaljson) (`:3010`, clickable) and draws nothing where none is declared. Omit to keep the default set; `[]` hides all built-ins. `work` shows which PR / issue the cell is on (`#977 → #966`) and clears itself when the PR merges — see the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#work-chip). |
 | `pushEnabled` | `true` to send a **Web Push** to your registered devices. Off by default; only sends while the **RemoteHost** channel is connected (see below). The master switch — `pushKinds` picks which moments. |
 | `pushKinds` | Which moments push: `"finished"` (a turn ended, ✅) and/or `"waiting"` (the agent stopped to ask — a permission prompt or a question, ❓, **once per prompt**). Omit to keep both; `[]` for none. A kind added in a later version stays off until you tick it. |
-| `worklogEnabled` | `true` to run the built-in **dev worklog** batch (see below). Off by default (each run spawns an LLM session, so it costs tokens). |
-| `worklogIntervalHours` | Worklog cadence in hours (default `6`, clamped to `1`–`168`). |
-| `terminalSubmit` | Which bytes Claude reads as **submit** vs **newline**: `"cr"` (default — Enter submits, Shift+Enter makes a newline) or `"esc-cr"` (for a Claude Code rebound the other way). Applies to the keyboard **and** the phone remote-view submit, for **Claude sessions only** (shell/codex keep plain Enter). See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#terminal-submit). |
-| `copyOnSelect` | `true` puts a **mouse selection on the clipboard the moment it settles**, with no key pressed (the PuTTY / iTerm2 behaviour). **Off by default** — it changes the clipboard when you may only have meant to highlight something. No Settings UI: edit the file and reload the tab. Composes with the `copy` keymap action rather than replacing it. Over plain `http://` the browser gives a page no clipboard access, so a fallback asks xterm to copy instead; see the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#copy-on-select). |
-| `decisionDigest` | Keep a **Markdown digest of the decisions this project's sessions asked for**, refreshed at startup and every few hours, so an agent can read what has already been decided before asking something similar. Written to `~/.mulmoterminal/decisions/<project>.md` (never into your repository) and served to agents by the bundled `mulmoterminal-decisions` skill. **Off by default** — it is a vision-stage idea, and it writes a file that would otherwise not exist. The digest holds dated facts, never inferred rules. |
-| `issueWorkComments` | Let a cell **comment on the issue it is working on**: **one comment**, posted when the work starts and then **edited** as the PR opens and merges (closing the issue if GitHub has not already), each milestone stamped in UTC. The comment names the working **directory** it happened in — the folder name only, never the path — so a reader can tell which clone, and two terminals do not start the same issue twice. It says it came from MulmoTerminal. CI is deliberately not reported: it is on the PR already, and it flaps. When it **cannot** write — no `gh`, not logged in, or a login without write access — the cell says so next to the work chip rather than doing nothing silently; the work is unaffected either way. **Off by default**; it writes to GitHub, often on somebody else's issue. Needs `gh` logged in **with write access**. See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#issue-work-comments). |
-| `prWorkdirFooter` | Ends a PR body with `work in <clone>` — the directory name of the clone the work happened in, so a PR says which of several side-by-side checkouts produced it. Applies to **both** paths that open PRs here: **⧉ Open PR** appends it to the PR it creates, and every Claude session is told to end the bodies it writes with the same line (the name is resolved by the server, so a session inside a managed worktree still names the main checkout). **On by default**; set `false` to opt out — read per PR and per session spawn, so no restart is needed (there is no Settings control for it). Appending is idempotent: an existing PR never gets a second copy. |
-| `appendSystemPrompt` | Whether a spawned Claude session is asked to end a reply with a **closing summary** — what was asked, what was achieved, what was not (see [Closing summary](#closing-summary)). **On by default**; set `false` to opt out, and a directory's `.mulmoterminal.json` outranks this. Read per spawn, so no restart is needed (there is no Settings control for it), though a session already running keeps what it was launched with. `true` / `false` only. |
-| `fontFamily` | The **terminal font** every session renders in — a CSS font-family stack, e.g. `"'Cica', 'MS Gothic', monospace"`. No Settings UI: edit the file, then **restart** (this config is read once at startup). Unset uses the built-in stack (JetBrains Mono / Fira Code / Menlo / Consolas, then CJK faces for Japanese, Korean and Chinese). Unlike the per-browser font **size**, this is one value for the whole host — it names fonts, and which fonts exist is a property of the machine. A directory can override it. See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#font-family). |
+| `worklogEnabled` | `true` to run the built-in **dev worklog** batch (see below). Off by default (each run spawns an LLM session, so it costs tokens). Editable in Settings → **Sessions and background tasks**. |
+| `worklogIntervalHours` | Worklog cadence in hours (default `6`, clamped to `1`–`168`). A stepper in the same Settings section covers the range. |
+| `terminalSubmit` | Which bytes Claude reads as **submit** vs **newline**: `"cr"` (default — Enter submits, Shift+Enter makes a newline) or `"esc-cr"` (for a Claude Code rebound the other way). Applies to the keyboard **and** the phone remote-view submit, for **Claude sessions only** (shell/codex keep plain Enter). See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#terminal-submit). Settings → **Terminal keys** offers both, worded as behaviour. |
+| `copyOnSelect` | `true` puts a **mouse selection on the clipboard the moment it settles**, with no key pressed (the PuTTY / iTerm2 behaviour). **Off by default** — it changes the clipboard when you may only have meant to highlight something. There is a checkbox in Settings → **Terminal keys**, applied at once; a hand edit of the file needs a **server restart, then a tab reload** (the server reads this file once at startup, and the browser reads the value from it on load). Composes with the `copy` keymap action rather than replacing it. Over plain `http://` the browser gives a page no clipboard access, so a fallback asks xterm to copy instead; see the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#copy-on-select). |
+| `decisionDigest` | Keep a **Markdown digest of the decisions this project's sessions asked for**, refreshed at startup and every few hours, so an agent can read what has already been decided before asking something similar. Written to `~/.mulmoterminal/decisions/<project>.md` (never into your repository) and served to agents by the bundled `mulmoterminal-decisions` skill. **Off by default** — it is a vision-stage idea, and it writes a file that would otherwise not exist. The digest holds dated facts, never inferred rules. Settings → **Sessions and background tasks** has the switch. |
+| `issueWorkComments` | Let a cell **comment on the issue it is working on**: **one comment**, posted when the work starts and then **edited** as the PR opens and merges (closing the issue if the forge has not already), each milestone stamped in UTC. The comment names the working **directory** it happened in — the folder name only, never the path — so a reader can tell which clone, and two terminals do not start the same issue twice. It says it came from MulmoTerminal. CI is deliberately not reported: it is on the PR already, and it flaps. **Off by default**; it writes to the forge, often on somebody else's issue. Needs the matching CLI logged in — `gh` for GitHub, `glab` for gitlab.com and any host declared in `gitlabHosts`. See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#issue-work-comments). Editable in Settings → **GitHub and GitLab**. |
+| `prWorkdirFooter` | Ends a PR body with `work in <clone>` — the directory name of the clone the work happened in, so a PR says which of several side-by-side checkouts produced it. Applies to **both** paths that open PRs here: **⧉ Open PR** appends it to the PR it creates, and every Claude session is told to end the bodies it writes with the same line (the name is resolved by the server, so a session inside a managed worktree still names the main checkout). **On by default**; set `false` to opt out, from Settings → **GitHub and GitLab** or the file — read per PR and per session spawn, so no restart is needed, and a second MulmoTerminal beside this one sees the change too. Appending is idempotent: an existing PR never gets a second copy. |
+| `appendSystemPrompt` | Whether a spawned Claude session is asked to end a reply with a **closing summary** — what was asked, what was achieved, what was not (see [Closing summary](#closing-summary)). **On by default**; set `false` to opt out, and a directory's `.mulmoterminal.json` outranks this. Settings → **Sessions and background tasks** has the switch. Read per spawn, so no restart is needed, though a session already running keeps what it was launched with. `true` / `false` only. |
+| `autoDirIcon` | Whether a project that sets no `icon` shows the favicon its repository already ships (`public/favicon.svg`, `apple-touch-icon.png`, a web manifest — first hit wins, ordered by how the image survives at 14px). **On by default**; Settings → **Directory appearance** has the switch. A single project opts out with `"icon": false` in its own `.mulmoterminal.json`, which this does not override. A key that was written and got it wrong shows nothing rather than falling back — a broken setting has to look broken. `true` / `false` only. |
+| `cockpitLines` | `{ summary, prompt, response }` — how many lines each **cockpit-roster** row shows before it clamps (default `2` / `2` / `3`, each clamped to `1`–`20`). Raising them trades how many sessions fit on screen for reading a long one in place. Three steppers in Settings → **Waiting rows**. |
+| `fontFamily` | The **terminal font** every session renders in — a CSS font-family stack, e.g. `"'Cica', 'MS Gothic', monospace"`. Set it in Settings → **Terminal font**, applied at once; editing the file instead needs a **restart** (this config is read once at startup). Unset uses the built-in stack (JetBrains Mono / Fira Code / Menlo / Consolas, then CJK faces for Japanese, Korean and Chinese). Unlike the per-browser font **size**, this is one value for the whole host — it names fonts, and which fonts exist is a property of the machine. A directory can override it. See the [Configuration guide](https://receptron.github.io/mulmoterminal/guide/en/config.html#font-family). |
 
 Every MulmoTerminal on the machine shares this one file, so an older build could save over a key a
 newer one wrote. It doesn't: a **top-level key this version doesn't recognise is written back
@@ -681,6 +712,7 @@ malformed file is ignored.
 ```jsonc
 {
   "name": "PROD · payments",            // badge shown on this directory's terminals
+  "icon": "docs/logo.png",              // image on this dir's cells (path here, URL, or data:); omit to use the repo's favicon
   "badgeColor": "#cf222e",              // badge color (hex #rrggbb)
   "headerColor": "#190a23",             // cell header background (hex #rrggbb)
   "headerTextColor": "#ffffff",         // cell header text color (hex #rrggbb)
@@ -695,10 +727,46 @@ malformed file is ignored.
   "orderPriority": 10,                  // rank in the grid's "priority" order and the launcher chips (lowest first)
   "sound": "./.mulmoterminal/alert.mp3", // attention sound, RELATIVE to this directory
   "sounds": { "command-failed": "preset:gong" }, // per-notification-kind override
-  "appendSystemPrompt": false           // no closing summary here; omit to follow the global setting
+  "appendSystemPrompt": false,          // no closing summary here; omit to follow the global setting
+  "worktreeEnv": {                      // a port / database name of its own per git worktree
+    "PORT": { "kind": "port", "base": 3000 },
+    "DB_NAME": { "kind": "slug", "prefix": "myapp_" }
+  }
 }
 ```
 
+**Already have a `repo.json`?** MulmoTerminal reads it. It is an
+[open repository-metadata format](https://receptron.github.io/mulmoterminal/repo-json.html) — one
+small file any tool can read — and a project that ships one gets a coloured, named, icon-bearing
+cell without knowing this app exists:
+
+```json
+{ "name": "diffusion-lab", "icon": "docs/logo.png", "color": "#7c3aed" }
+```
+
+One colour becomes all seven: the header is it exactly, the badge/border/dot/button/body are
+derived from its hue, and the header text is derived for contrast. Anything this app understands
+but the open format doesn't goes under `extensions.mulmoterminal`.
+
+The three files layer, general to specific — **`repo.json` → `.mulmoterminal.json` →
+`.mulmoterminal.local.json`** — replacing whatever keys the one below it set.
+
+**Several clones of one repository?** Drop a `.mulmoterminal.local.json` beside it. It is read
+after `.mulmoterminal.json` and **replaces whatever keys it names**, so the shared file holds what
+the project is — name, theme, a colour — and each checkout's local file holds only what makes it
+recognisable:
+
+```jsonc
+// .mulmoterminal.json — the project. Complete on its own, so one clone needs nothing else.
+{ "name": "acme-web", "theme": "nord", "badgeColor": "#1b3479", "headerColor": "#2d4ea9", "orderPriority": 30 }
+
+// .mulmoterminal.local.json — this checkout only. Gitignore it.
+{ "badgeColor": "#27b4a8", "headerColor": "#4ed0c5", "orderPriority": 65 }
+```
+
+Whole keys, not a deep merge: a `colors` block in the local file replaces the shared one entirely.
+Settings → Directory settings names both files and lists which keys the local one took over.
+
 ![Four projects color-coded in the grid, each in its own palette](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-colors.png)
 
 *As cells pile up it gets hard to tell which project is which. Give each repo a **name badge** and its own colors in `.mulmoterminal.json` and they're unmistakable — `headerColor`/`badgeColor` tint the frame, while `colors` reaches all the way into the **terminal's own background and text**. (The example above dresses four repos in Mondrian / van Gogh / Picasso / Matisse palettes.)*
@@ -706,6 +774,7 @@ malformed file is ignored.
 | Field        | Meaning |
 | ------------ | ------- |
 | `name`       | Label shown as a badge in the terminal/cell header. |
+| `icon`       | An **image** marking this directory — shown in the cell header, the cockpit roster, the filmstrip thumbnails and the launcher's directory chips. Either a path **relative to this directory** (an absolute path, or a `../` that escapes it, is rejected), an `http(s)://` URL, or a `data:image/…` URI. PNG / JPEG / **GIF (animated plays)** / WebP / AVIF / SVG / ICO / BMP. Not to be confused with a header **button's** `icon`, which is a Material Symbols name. **Omit it and the repository's own favicon is used** (`public/favicon.svg`, `apple-touch-icon.png`, a web manifest — see `autoDirIcon`); `false` means no icon here and stops that search. |
 | `badgeColor` | Badge background color (`#rrggbb`); text auto-contrasts. |
 | `headerColor` | Header **background** color (`#rrggbb`) — the grid cell's header row and the terminal's own header row (grid row 2). While a terminal is working/blocked the status tint still shows; the custom color applies when idle. |
 | `headerTextColor` | Header **text** color (`#rrggbb`) — the dir path, title, and prompt. |
@@ -716,11 +785,12 @@ malformed file is ignored.
 | `theme`      | xterm palette for terminals in this directory (one of the built-in theme ids). |
 | `colors`     | Per-key xterm palette overrides applied on top of `theme` (or the app theme when `theme` is unset). Keys are xterm `ITheme` names (`background`, `foreground`, `cursor`, `selectionBackground`, the 16 ANSI colors, …); values are hex (`#rgb` / `#rrggbb` / `#rrggbbaa`). Unknown keys / bad values are dropped. |
 | `fontSize`   | Terminal font size in px for this directory (8–32), overriding the Settings value. A size outside the range is clamped; a non-number is ignored. Changing it re-fits the terminal, so the PTY learns the new width — unlike browser zoom, which leaves the two disagreeing. |
-| `orderPriority` | This directory's rank in the grid's **priority** ordering — the third mode on the toolbar's ordering button, next to auto (attention-first) and manual (the move buttons). Any integer, **lowest first**; negatives are allowed. Directories that set nothing sort last, keeping their existing order, so adding the key to one project doesn't shuffle the rest. The grid reads it in **priority** mode only; the launcher's directory chips sort by it, so a project sits in the same place on both. The one exception is the **workspace** chip, which always leads the launcher's row regardless of any rank — it is not one of the directories being ranked against each other, and it is the one place every GUI tool is reachable (see [MCP server ids](#mcp-server-ids-why-a-workspace-cell-and-a-project-cell-disagree)). |
+| `orderPriority` | This directory's rank in the grid's **priority** ordering — the third mode on the toolbar's ordering button, next to auto (attention-first) and manual (the move buttons). Any integer, **lowest first**; negatives are allowed. Directories that set nothing sort last, keeping their existing order, so adding the key to one project doesn't shuffle the rest. The grid reads it in **priority** mode only; the launcher's directory chips sort by it, so a project sits in the same place on both. The one exception is the **workspace** chip, which always leads the launcher's row regardless of any rank — it is not one of the directories being ranked against each other, and it is the one place a claude or codex session reaches every GUI tool without registering anything (agy and grok get what the directory registered wherever they run — see [MCP server ids](#mcp-server-ids-why-a-workspace-cell-and-a-project-cell-disagree)). |
 | `fontFamily` | CSS font-family stack for this directory's terminals, overriding the global `fontFamily`. Use the names as your OS lists them (`"'Cica', 'MS Gothic', monospace"`). An unusable stack is ignored whole rather than half-applied; `monospace` is appended if you name no generic family. Prefer fonts whose fullwidth glyphs are exactly twice the Latin width, or box-drawing frames tear. |
 | `sound`      | Attention sound for this directory's sessions, a path **relative to the directory** (served at `GET /api/dir-sound`). The fallback for every kind. |
 | `sounds`     | Per-kind override of `sound`: `{ "command-failed": "preset:gong" }`. Each value is a `preset:<id>` or a directory-relative path, under the same confinement. |
 | `appendSystemPrompt` | Whether this directory's Claude sessions are asked to end a reply with a **closing summary** (see [Closing summary](#closing-summary)). Omit to follow the global `appendSystemPrompt`, which is on; `true` / `false` here outranks it. Read per spawn, so a new session in this directory picks up an edit without a restart. |
+| `worktreeEnv` | Values every working tree of this project needs its **own** of — the port its dev server binds, the database its migrations touch. A worktree isolates files, not ports: two trees running `yarn dev` both reach for 3000 and the second one dies. Each variable is `{ "kind": "port", "base": <1024–65215> }` (a free port, `base` + a multiple of 10 — the checkout keeps `base`, its worktrees take the numbers above it) or `{ "kind": "slug", "prefix": "…" }` (a `[a-z0-9_]` name from the tree's task name, ≤ 63 chars, for a database / schema / container). Up to 16, under whatever names the project reads (`PORT`, `VITE_PORT`, …). A value is **reserved once and kept** (`~/.mulmoterminal/worktree-env.jsonl`) for as long as its declaration is unchanged, so a running dev server's port never moves under it; editing `base` re-allocates, renaming or dropping a variable releases what it held, and removing the worktree releases all of them. Set on every terminal in the directory — agent cell, Shell, launcher, Run command — and shown on the header's `env` chip, where a port is a link to `http://localhost:<port>`. MulmoTerminal hands out the name; creating the database is the project's own job. |
 | `addDirs`    | Extra directories this project's Claude sessions may read and edit — the terminal-side equivalent of opening several folders in one VS Code workspace, via Claude Code's `--add-dir`. Relative entries resolve against **this file's directory** (`"../shared-lib"`), a path that doesn't exist is dropped, max 16. Claude only: codex has no equivalent flag and ignores the key. |
 
 **Security.** `sound` and every `sounds` entry are directory-relative paths only — absolute
@@ -778,7 +848,9 @@ An empty grid cell's launcher sets the **Working directory** by typing, by a pre
 chip, or with the **📁 folder button** (a native OS folder dialog). The preset chips are
 the directories you have launched in; the **workspace** leads them always, labelled
 **WORKSPACE** and marked with an icon, whether or not you have ever launched there — it is
-the one directory where a session reaches every GUI tool, so it is never a click you can
+the one directory where a claude or codex session reaches every GUI tool (agy and grok get
+what the directory registered, there as anywhere — see
+[MCP server ids](#mcp-server-ids-why-a-workspace-cell-and-a-project-cell-disagree)), so it is never a click you can
 lose. It has no remove button for the same reason. It is named for its role rather than its
 folder, because the folder name (`~/mulmoclaude` by default, or wherever `CLAUDE_CWD`
 points) says the least interesting true thing about it; the real path is on its hover.
@@ -786,7 +858,12 @@ points) says the least interesting true thing about it; the real path is on its
 **The launcher is shorter in the workspace**, because two of its choices do not apply
 there. The per-directory **Canvas switches** are replaced by a line saying every GUI tool
 is already available — a session there is handed the whole GUI MCP at spawn, so a switch
-would register a group URL that then has nothing left to serve. And the **worktree**
+would register a group URL that then has nothing left to serve. **With Antigravity or Grok
+picked they stay**, in the workspace as everywhere else: neither is handed anything at spawn
+and both read their servers from the directory's file, so the switches are their only route
+to a GUI tool and hiding them would leave the session with none (see
+[MCP server ids](#mcp-server-ids-why-a-workspace-cell-and-a-project-cell-disagree)).
+And the **worktree**
 section is hidden: a worktree isolates work on one codebase onto a branch, while the
 workspace is what a session works *from* (the shared wiki, collections and accounting
 live there), which is precisely what a detached branch would cut it off from. Both come
@@ -803,7 +880,7 @@ different projects' scripts.
 The same launcher also has an **or launch** row for your configured **launch commands**
 — any interactive command — set in Settings (⚙) → **Launch commands** as
 `{ label, command }` (e.g. `htop` → `htop`, `Codex` → `codex`). A plain shell needs no
-entry here: the launch form's **Shell** toggle already opens `$SHELL`. Unlike
+entry here: the Agent Picker's **Shell** option already opens `$SHELL`. Unlike
 a one-shot script, a launcher runs as a **persistent terminal in the cell's directory**:
 it survives grid page switches and reconnects, and its dot shows running vs. exited (it
 has no Claude hooks, so no blocked/done states).
@@ -946,16 +1023,20 @@ separate working tree that shares the repo's `.git`, so several agents can work
 repo without colliding. Worktrees live under `~/.mulmoterminal/worktrees/` (override with
 `MULMOTERMINAL_HOME`), and existing ones are listed below the field.
 
-**A worktree inherits the project's settings.** `.mulmoterminal.json` is normally gitignored,
-so a fresh worktree used to have none — no colours, no name, no model, no grid rank. It is now
-given its own copy derived from the project's: `name` / `theme` / `colors` / `fontSize` /
-`fontFamily` / `provider` / `model` as written, the seven chrome colours **rotated 12 degrees
-further around the hue wheel per worktree** (so a project's trees read as a gradient; a grey like
-`#ffffff` has no hue to move and stays put), and `orderPriority` at the project's rank **+ 1**, so
-the worktree sorts directly after it. `sound` / `sounds` / `addDirs` are not carried — they name
-paths inside the project directory. Written only where git would **ignore** it: an untracked file
-in a worktree's `git status` would make it count as dirty, and a dirty worktree is one
-MulmoTerminal refuses to remove. An existing config in the worktree is never overwritten.
+**A worktree inherits the project's settings.** A fresh worktree used to have none — no colours,
+no name, no model, no grid rank. It is now given its own copy derived from the project's, written
+to **`.mulmoterminal.local.json`** so it layers over whatever the repository committed: `name` /
+`theme` / `colors` / `fontSize` / `fontFamily` / `provider` / `model` / `worktreeEnv` as written
+(the last is a declaration rather than a value — the worktree resolves its own values from it), the
+seven chrome colours **rotated 12 degrees further around the hue wheel per worktree** (so a
+project's trees read as a gradient; a grey like `#ffffff` has no hue to move and stays put), and
+`orderPriority` at the project's rank **+ 1**, so the worktree sorts directly after it. `sound` /
+`sounds` / `addDirs` are not carried — they name paths inside the project directory. Written only
+where git would **ignore what it writes**: an untracked file in a worktree's `git status` would
+make it count as dirty, and a dirty worktree is one MulmoTerminal refuses to remove. The local
+override is preferred; a repo that ignores `.mulmoterminal.json` instead (the setup this feature
+shipped with) still gets its colours there. A committed shared config is never written to. A local
+file the worktree already has is never overwritten.
 
 **One worktree, one session.** A worktree is tied to a branch, so it is never started
 twice: a listed row **resumes** that worktree's session when it has one, and **starts** one
@@ -965,10 +1046,13 @@ the same worktree reached by pasting its path into **WORKING DIRECTORY**, or by
 chip, will not launch either — and the **server** refuses the spawn whichever client asks,
 so a path spelled another way (a trailing slash, a symlink) does not slip past.
 
-What the limit covers is an **agent**: Claude, Codex or Antigravity, including an **OR
+What the limit covers is an **agent**: Claude, Codex, Antigravity or Grok, including an **OR
 LAUNCH** command that runs one of them. A **Shell**, and a launcher that runs anything else
 (`yarn dev`, `lazygit`, `htop`), stays free — a worktree an agent is working in is exactly
-where you want those.
+where you want those. A project that declares `worktreeEnv` also gets **its own value per
+worktree** for each variable it declares there — so two dev servers given a port of their own do
+not both reach for 3000 (see
+[`worktreeEnv`](https://receptron.github.io/mulmoterminal/guide/en/config.html#worktree-env)).
 
 The same holds for **OR RESUME HERE**: a session someone is holding is listed with `● open`
 and refused, where before it could be confirmed away — which detached whoever had it.
@@ -998,7 +1082,7 @@ Typing a task name yourself keeps the local base it has always used, with no fet
 
 ![An empty cell's launch form — choose the agent, working directory, or a worktree](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-launch-form.png)
 
-*Every empty grid cell shows this launch form: toggle **Claude / Codex / Antigravity / Shell**, type a **working directory** (frequent ones autocomplete from your presets), or — in a git repo — name a task under **OR ISOLATE IN A WORKTREE** and hit **＋ New worktree** to start the agent on its own isolated branch. **Shell** runs your OS default shell there instead of an agent; **OR LAUNCH** runs one of your configured launch commands.*
+*Every empty grid cell shows this launch form: pick an agent in the **Agent Picker** (**Claude / Codex / Antigravity / Grok / Shell**), type a **working directory** (frequent ones autocomplete from your presets), or — in a git repo — name a task under **OR ISOLATE IN A WORKTREE** and hit **＋ New worktree** to start the agent on its own isolated branch. **Shell** runs your OS default shell there instead of an agent; **OR LAUNCH** runs one of your configured launch commands.*
 
 A worktree cell's header carries a **diff badge** (`+<commits> ●<dirty>`); click it for a
 **Changes vs `<base>`** panel (file list + patch) with actions:
@@ -1106,27 +1190,44 @@ Which route a session takes is decided by `carriesFullGuiMcp()` in
 `server/session/mcp-config.ts` — the single view, a cell-less chat, or anything whose cwd **is**
 the workspace take the first; anything in a project directory takes the second.
 
-**The workspace is agent-agnostic, and so is the way you start a terminal there.** All three
-agents and the launcher chips ask the same predicate, so two terminals in the workspace reach
-the same tools no matter how they were started:
+**The workspace is agent-agnostic for the agents that can RECEIVE a per-spawn config** — claude and
+codex ask the same predicate, so two terminals in the workspace reach the same tools no matter which
+of the two started them. **Antigravity and Grok cannot, and that is the exception you will meet
+first:**
 
 | Started as | In the workspace | In a project directory |
 |---|---|---|
 | claude cell (including `?gui=0`) | `mt`, every tool | the directory's registered groups |
 | codex cell | `mt`, every tool | the directory's registered groups |
-| launcher chip running `claude` | `mt`, every tool — flags inserted into the command line | nothing injected; its own `.mcp.json` loads |
-| launcher chip running `codex` | `mt`, every tool — `-c` overrides inserted | the directory's registered groups |
-| launcher chip running anything else | untouched | untouched |
-
-A chip is a command line the user wrote, so the injection is a **rewrite of their text** and is
-deliberately narrow: only a bare `claude` or `codex` is recognised, and anything else — a wrapper
-script, `FOO=1 claude` — is passed through unchanged.
-
-A `claude` chip in the workspace is handed the all-tools URL, same as the cell, and like the cell it
-**does not** isolate the session: your own MCP servers and claude.ai connectors load as usual. Where
-a directory also registered per-group URLs in its `.mcp.json`, those groups stand down for that
-session rather than serving a second copy of the same tools — the session already reaches all of
-them under `mt`.
+| antigravity cell | **the directory's registered groups** — nothing registered means **no GUI tools at all** | the directory's registered groups |
+| grok cell | **the directory's registered groups** — nothing registered means **no GUI tools at all** | the directory's registered groups |
+| any launcher chip | untouched | untouched |
+
+Neither takes an MCP flag: `agy` reads `.agents/mcp_config.json` and `grok` reads `.grok/config.toml`
+in the working directory, and a file shared by every session in a directory cannot be handed to one
+session and not another — so there is nothing for "this cwd is the workspace" to change. The
+membership is `FULL_GUI_MCP_AGENTS` in `common/guiMcpAgents.ts`, in `common/` precisely so the
+launcher form and the spawn cannot disagree about it
+([#1423](https://github.com/receptron/mulmoterminal/issues/1423)).
+
+The consequence is easy to hit and hard to guess: `presentDocument` works in a project you once
+flipped **Canvas** on for, and is missing in the workspace where everything else is automatic. Fix it
+the same way anywhere — pick **Antigravity** or **Grok**, point WORKING DIRECTORY at that directory,
+flip the **Canvas** switch (it stays visible for both), and start a **new** session; the switch
+registers the directory, never a session already running. Full procedure:
+[Antigravity and Grok register everywhere](https://receptron.github.io/mulmoterminal/guide/en/basics.html#antigravity-gui-tools)
+· [日本語](https://receptron.github.io/mulmoterminal/guide/ja/basics.html#antigravity-gui-tools).
+
+**A launcher chip is not an agent session — it is a command.** Whatever the command line names,
+it runs exactly as written: nothing is inserted, and no GUI MCP is attached. A chip running
+`claude` therefore reads only its directory's own `.mcp.json`, and a chip running `codex` has no
+Canvas. If you want a chip to reach the GUI tools, put the flags in the command yourself.
+
+Earlier releases did rewrite a `claude` or `codex` chip to match the cell beside it. That was
+removed: a chip that silently runs something other than what it says is indistinguishable from
+the Agent Picker, which is the confusion the two controls exist on either side of. Use the Agent
+Picker for an agent session — it is also the only one of the two that gives you a resumable
+transcript, cost and context, and a "waiting for you" status.
 
 **The asymmetry is deliberate.** `mt` is ours to name: nothing on disk holds it, it is
 regenerated on every spawn, so it was shortened to stop paying 17 characters per tool name. The
@@ -1266,7 +1367,7 @@ quietly answering about the **default workspace** (#1151):
 
 | Where | What happens |
 | --- | --- |
-| `/ws`, `/ws/codex`, `/ws/antigravity`, `/ws/launch`, `/ws/run` | The socket is closed with `{ type: "error", message }`, which the terminal shows as a red banner and does not retry. |
+| `/ws`, `/ws/codex`, `/ws/antigravity`, `/ws/grok`, `/ws/launch`, `/ws/run` | The socket is closed with `{ type: "error", message }`, which the terminal shows as a red banner and does not retry. |
 | A session that is still running (`?session=` names a live PTY or a surviving tmux session) | **Attaches anyway**, with a warning in the server log. Moving or renaming a directory must not shut you out of an agent that is still working in it — and the cwd reported back comes from the running PTY, not from the request. |
 | `GET /api/scripts`, `/api/skills`, `/api/dir-config`, `/api/dir-sound`, `/api/git-status`, `/api/pr-phase`, `/api/header`, `/api/sessions`, `/api/codex/sessions`, `/api/antigravity/sessions`, `/api/session/:id`, `/api/transcript/*`, `/api/cost` | `404 { error, cwd }` — a directory that is not there. |
 | A `?cwd=` that cannot name a directory at all (relative, or repeated as `?cwd=a&cwd=b`) | `400 { error, cwd }`. |
@@ -1767,16 +1868,15 @@ server/
                   -header, -keys, -model, -notify, -bug-report, -decisions
   fix-pty-perms.js              postinstall: fixes node-pty binary permissions
 src/
-  App.vue                       Layout; owns the active session + single/grid view
+  App.vue                       Layout; owns the grid, the overlays and the tab favicon
   router/                       Vue Router routes (/, /terminals, /collections,
                                 /accounting, /prs, /files, /wiki, …)
   components/
-    Sidebar.vue, SessionTabBar.vue           session list + tab bar (pub/sub driven)
     Terminal.vue                             xterm.js terminal; /ws, /ws/codex, /ws/run
     AppToolbar.vue                           shared header + toolbar buttons
     GridView.vue, TerminalGrid.vue, TerminalCell.vue, CommandCell.vue, LauncherCell.vue
-    CellLaunchForm.vue                       what an EMPTY cell shows: dir + target + resume /
-                                             scripts / worktrees / tool groups
+    CellLaunchForm.vue                       what an EMPTY cell shows: Agent Picker + dir +
+                                             resume / scripts / worktrees / tool groups
     GuiPanel.vue, PluginFrame.vue            GUI panel (Canvas) + Shadow-DOM plugin host
     FilesOverlay.vue                         file browser + CodeMirror editor
     GitBranchChip.vue, ModelContextBadge.vue header chips / badges

package/common/chromeFromColor.ts

@@ -0,0 +1,121 @@
+// One brand colour to the seven chrome colours a cell is painted with (#1442).
+//
+// `repo.json` gives a project one colour; MulmoTerminal paints seven. Rather than ask a repository
+// to describe this app's chrome, the other six are derived — and the derivation is measured, not
+// invented. Against eleven hand-tuned palettes in this author's own projects, deriving from
+// `primary` alone lands within ΔE76 2.5, median 1.9. The median is under 2.3, the threshold where a
+// colour difference becomes noticeable at all; the worst single role sits just above it. One
+// derived value came out byte-identical to the hand-picked one.
+//
+// The measurement's real finding is that ONE rule does not fit every role:
+//
+//   - the badge sits RELATIVE to the brand colour — a fixed darkening of whatever it is
+//   - the surfaces sit at ABSOLUTE lightness, the same pale values whatever the brand colour is
+//
+// Snapping every role to absolute values drifts by ΔE 20 at the dark end of the hue wheel; making
+// every role a relative offset drifts by ΔE 15 at the pale end. Both were tried; this is the mix
+// that fits. Anyone retuning these numbers should re-measure rather than reason about them.
+import { readableTextColor } from "./contrast.js";
+
+export interface ChromeColors {
+  badgeColor: string;
+  headerColor: string;
+  headerTextColor: string;
+  cellColor: string;
+  cellBorderColor: string;
+  dotColor: string;
+  buttonColor: string;
+}
+
+// Saturation/lightness offsets FROM the brand colour.
+const BADGE_OFFSET = { s: 0.061, l: -0.129 };
+// Absolute saturation/lightness, at the brand colour's hue.
+const SURFACE = { s: 0.53, l: 0.96 };
+const EDGE = { s: 0.6, l: 0.58 };
+const BUTTON = { s: 0.67, l: 0.89 };
+
+const clamp01 = (n: number): number => Math.min(1, Math.max(0, n));
+
+/** The seven colours for a brand colour, or null when it isn't a colour we can read. */
+export function chromeFromColor(primary: string, background?: string | null): ChromeColors | null {
+  const rgb = parseHex(primary);
+  if (!rgb) return null;
+  const [hue, saturation, lightness] = rgbToHsl(rgb);
+  // A grey has no hue to move, so tinting it would INVENT one — every derived role would come out
+  // red, since an achromatic colour reports hue 0. Keep an achromatic brand colour achromatic.
+  const achromatic = saturation === 0;
+  const at = (s: number, l: number): string => hslToHex(hue, achromatic ? 0 : clamp01(s), clamp01(l));
+  return {
+    badgeColor: at(saturation + BADGE_OFFSET.s, lightness + BADGE_OFFSET.l),
+    headerColor: normalizeHex(primary),
+    // Never taken from the file — see the spec's "text colour is never declared". Deriving it is
+    // also what makes two conforming tools agree.
+    headerTextColor: readableTextColor(rgb[0], rgb[1], rgb[2]) === "#000" ? "#1b2430" : "#ffffff",
+    // `background` is the surface the brand colour sits on, which is exactly what a cell body is.
+    // Gated on it PARSING, not on it being present: an unusable value here used to win the branch,
+    // survive as a non-colour, and then be dropped downstream — leaving no surface at all, neither
+    // the declared one nor the derived one (Codex on #1445). The spec says a consumer must be able
+    // to work from `primary` alone, and a role that didn't parse is a role that wasn't declared.
+    cellColor: (background && parseHex(background) && normalizeHex(background)) || at(SURFACE.s, SURFACE.l),
+    cellBorderColor: at(EDGE.s, EDGE.l),
+    dotColor: at(EDGE.s, EDGE.l),
+    buttonColor: at(BUTTON.s, BUTTON.l),
+  };
+}
+
+// `#rgb` and `#rrggbb` — the two forms the specification allows, and nothing else. Accepting more
+// here would mean this app renders files another conforming tool would reject.
+const HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+export function parseHex(value: string): [number, number, number] | null {
+  const hex = value.trim();
+  if (!HEX_RE.test(hex)) return null;
+  const body = hex.slice(1);
+  const full = body.length === 3 ? [...body].map((c) => c + c).join("") : body;
+  const channel = (i: number): number => parseInt(full.slice(i, i + 2), 16);
+  return [channel(0), channel(2), channel(4)];
+}
+
+/** `#rgb` widened to `#rrggbb`, lowercased — the shape the rest of the config expects. */
+export function normalizeHex(value: string): string {
+  const rgb = parseHex(value);
+  return rgb ? `#${rgb.map((c) => c.toString(16).padStart(2, "0")).join("")}` : value.trim().toLowerCase();
+}
+
+// Which sixth of the wheel the colour sits in, given which channel is the largest.
+function hueSextant(rn: number, gn: number, bn: number, max: number, delta: number): number {
+  if (max === rn) return (gn - bn) / delta + (gn < bn ? 6 : 0);
+  if (max === gn) return (bn - rn) / delta + 2;
+  return (rn - gn) / delta + 4;
+}
+
+function rgbToHsl([r, g, b]: [number, number, number]): [number, number, number] {
+  const [rn, gn, bn] = [r / 255, g / 255, b / 255];
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const lightness = (max + min) / 2;
+  if (max === min) return [0, 0, lightness];
+  const delta = max - min;
+  const saturation = lightness > 0.5 ? delta / (2 - max - min) : delta / (max + min);
+  return [hueSextant(rn, gn, bn, max, delta) / 6, saturation, lightness];
+}
+
+function hslToHex(h: number, s: number, l: number): string {
+  const channel = (t: number): number => {
+    const shifted = ((t % 1) + 1) % 1;
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    if (shifted < 1 / 6) return p + (q - p) * 6 * shifted;
+    if (shifted < 1 / 2) return q;
+    if (shifted < 2 / 3) return p + (q - p) * (2 / 3 - shifted) * 6;
+    return p;
+  };
+  const rgb = s === 0 ? [l, l, l] : [channel(h + 1 / 3), channel(h), channel(h - 1 / 3)];
+  return `#${rgb
+    .map((c) =>
+      Math.round(c * 255)
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("")}`;
+}