mulmoterminal 4.8.1 → 4.8.3

package/README.md

@@ -595,6 +595,7 @@ The Settings modal (the gear button) persists per-user UI choices to `~/.mulmote
 | `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). |
+| `questionPaneEnabled` | `true` offers a Claude session's **`AskUserQuestion` choices as buttons** in a pane beside the enlarged terminal. **The terminal's own dialog stays** and the pane drives it — a click presses the arrow keys and Enter in the real dialog, so either end can answer and the first one wins. Claude sessions only (the choices arrive on Claude Code's hooks). A **single** question can also be answered in your own words — a text box under the buttons writes into the dialog's own `Type something` row; several questions at once, or a multi-select one, get buttons only, and `Chat about this` stays in the terminal. **Off by default** — it lets a pane type into your terminal. Checkbox in Settings → **Terminal keys**, applied at once (the server re-reads the file per question). See the [Feature reference](https://receptron.github.io/mulmoterminal/guide/en/features.html#question-pane). |
 | `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. |
@@ -724,7 +725,13 @@ malformed file is ignored.
   "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)
+  "headerTextColor": "#ffffff",         // cell header text color while idle (hex #rrggbb)
+  "headerStatusColors": {               // what the header shows once a status takes the background over
+    "working": "#6d28d9",               //   just the background — the text colour is derived from it
+    "done": { "background": "#166534" },
+    "blocked": { "background": "#7c2d12", "text": "#ffe8a3" }
+  },
+  "headerStatusTint": "background",     // "none" keeps headerColor while working/done (not blocked)
   "cellColor": "#101014",               // cell body background (hex #rrggbb)
   "cellBorderColor": "#2a2a4e",         // cell border color (hex #rrggbb)
   "dotColor": "#00e676",                // idle status dot (hex #rrggbb)
@@ -786,7 +793,9 @@ Settings → Directory settings names both files and lists which keys the local
 | `icon`       | An **image** marking this directory — shown in the cell header, the cockpit roster, the filmstrip thumbnails, the launcher's directory chips, and the phone's terminal list and terminal screen. 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`) — everything written on the header: the dir path, title and prompt, plus the model/context badge, the token counts and any custom chip. **Omit it and a readable colour is derived from `headerColor`**, while that colour is what shows (a working/blocked cell paints its own header tint, so its text returns to the theme's). |
+| `headerTextColor` | Header **text** color (`#rrggbb`) — everything written on the header: the dir path, title and prompt, plus the model/context badge, the token counts and any custom chip. **Omit it and a readable colour is derived from `headerColor`.** It applies while that colour is what shows: a working/done/blocked cell paints the theme's own status tint, so its text returns to the theme's too — an ink chosen for your header colour is not readable on a tint the theme mixed. Recolour those states with `headerStatusColors` instead. |
+| `headerStatusColors` | What the header shows once a **status** owns the background: an object keyed by `working` / `done` / `blocked` (there is no `idle` — `headerColor` is idle). Each value is a background `#rrggbb`, or `{ "background": …, "text": … }`. **Omit `text` and a readable one is derived from the background**, so naming one colour can never come out unreadable. A status you don't name keeps the theme's tint. |
+| `headerStatusTint` | `"background"` (default) lets a status replace the header background. `"none"` keeps `headerColor` while **working** and **done** — the status still reads from the cell border, the status dot and the pill. It deliberately does **not** reach `blocked`, the one state where nothing proceeds until you answer; give that state a colour of its own in `headerStatusColors` if you want one. |
 | `cellColor` | Cell **body background** color (`#rrggbb`) — the frame around the terminal. |
 | `cellBorderColor` | Cell **border** color (`#rrggbb`). The status frame (working/blocked) still overrides it while active. |
 | `dotColor` | **Idle** status-dot color (`#rrggbb`). The working/waiting colors are unchanged so the activity signal stays intact. |

package/common/askQuestion.ts

@@ -0,0 +1,217 @@
+import { isRecord } from "./isRecord.js";
+
+// The pub/sub channel carrying "this session is asking the user a question". Both sides decide
+// from it — the server publishes what the PreToolUse hook reported, the pane listens to know a
+// dialog is up and what it offers — so the name and the payload shape live here.
+export const ASK_QUESTION_CHANNEL = "ask-question";
+
+/** The tool name whose input this module reads. Claude Code's built-in question dialog. */
+export const ASK_QUESTION_TOOL = "AskUserQuestion";
+
+export interface AskOption {
+  label: string;
+  description?: string;
+}
+
+export interface AskQuestion {
+  question: string;
+  header: string;
+  options: AskOption[];
+  multiSelect: boolean;
+}
+
+export interface AskQuestionEvent {
+  sessionId: string;
+  toolUseId: string;
+  questions: AskQuestion[];
+}
+
+/** The same dialog, now answered — in the terminal, in the pane, or cancelled with Esc. The pane
+ *  drops its buttons on this: keys aimed at a dialog that has closed would reach the prompt
+ *  underneath, where Down walks the input history and Enter would re-submit what it found. */
+export interface AskQuestionDone {
+  sessionId: string;
+  toolUseId: string;
+  done: true;
+}
+
+const parseOption = (value: unknown): AskOption | null => {
+  if (!isRecord(value) || typeof value.label !== "string" || !value.label) return null;
+  return typeof value.description === "string" ? { label: value.label, description: value.description } : { label: value.label };
+};
+
+const isOption = (value: AskOption | null): value is AskOption => value !== null;
+
+const parseQuestion = (value: unknown): AskQuestion | null => {
+  if (!isRecord(value) || typeof value.question !== "string" || !Array.isArray(value.options)) return null;
+  const options = value.options.map(parseOption).filter(isOption);
+  // Length mismatch means one option failed to parse: answering by index against a list we
+  // could not read whole would pick the wrong row, so the whole question is rejected instead.
+  if (options.length === 0 || options.length !== value.options.length) return null;
+  return { question: value.question, header: typeof value.header === "string" ? value.header : "", options, multiSelect: value.multiSelect === true };
+};
+
+const isQuestion = (value: AskQuestion | null): value is AskQuestion => value !== null;
+
+/** Read a PreToolUse `tool_input` for AskUserQuestion. Null when it is not one, or not whole. */
+export const parseAskQuestions = (toolInput: unknown): AskQuestion[] | null => {
+  if (!isRecord(toolInput) || !Array.isArray(toolInput.questions)) return null;
+  const questions = toolInput.questions.map(parseQuestion).filter(isQuestion);
+  if (questions.length === 0 || questions.length !== toolInput.questions.length) return null;
+  return questions;
+};
+
+const identifiesADialog = (data: unknown): data is Record<string, unknown> & { sessionId: string; toolUseId: string } =>
+  isRecord(data) && typeof data.sessionId === "string" && typeof data.toolUseId === "string";
+
+export const isAskQuestionEvent = (data: unknown): data is AskQuestionEvent =>
+  identifiesADialog(data) && data.done !== true && parseAskQuestions(data) !== null;
+
+export const isAskQuestionDone = (data: unknown): data is AskQuestionDone => identifiesADialog(data) && data.done === true;
+
+// The close is published even while the pane is switched OFF, and only the offer is gated.
+// Turning the switch off mid-dialog would otherwise strand a pane that is already showing
+// buttons: the dialog closes, nothing says so, and the next click sends Down/Enter into the
+// prompt underneath — the exact stale-input case the close exists to prevent. A close for a
+// question that was never offered is a no-op in the pane, so this costs nothing when the switch
+// was off all along, and it carries no question text either way.
+export const shouldPublishQuestion = (event: AskQuestionEvent | AskQuestionDone, paneEnabled: boolean): boolean => isAskQuestionDone(event) || paneEnabled;
+
+/** As much of a recorded tool call as picking the open dialog out of a history needs. */
+export interface RecordedCall {
+  toolUseId?: string | undefined;
+  toolName?: string | undefined;
+  toolInput?: unknown;
+  status?: string | undefined;
+}
+
+// The dialog a session is blocked on right now, rebuilt from its tool-call history. The pane's
+// channel is event-only and replays nothing on reconnect, so a browser that reloads between the
+// question and its answer would otherwise never learn about a session that is waiting — and with
+// no button to open the pane, that question becomes unanswerable from the browser entirely.
+//
+// The LAST call, not the last one that happens to still say `running`. A session blocked on a
+// question runs nothing else until it is answered, so a later call is proof the question is over —
+// however it ended. Scanning back instead would keep offering a dialog whose close never arrived
+// (an interrupted turn, a `/clear`, a hook that did not land) long after the agent moved on, and
+// the buttons would type into whatever the screen became.
+export const openQuestionOf = (calls: readonly RecordedCall[], sessionId: string): AskQuestionEvent | null => {
+  const last = calls[calls.length - 1];
+  if (last?.toolName !== ASK_QUESTION_TOOL || last.status !== "running" || !last.toolUseId) return null;
+  const questions = parseAskQuestions(last.toolInput);
+  return questions ? { sessionId, toolUseId: last.toolUseId, questions } : null;
+};
+
+/** Why an answer did not reach the dialog. Serialized by the host, rendered by every client, so
+ *  the values live here rather than once per layer — a drift between them is a client showing the
+ *  wrong explanation, or none. */
+export type AnswerFailure =
+  /** The dialog was answered (in the terminal, or by another client) before this arrived. */
+  | "closed"
+  /** picks do not fit the questions — wrong count, out of range, or not ascending. */
+  | "bad-picks"
+  /** No PTY in this process to type into: the session outlived a server restart. */
+  | "unwritable"
+  /** Some keys reached the dialog before the rest were abandoned. Its cursor has moved and its
+   *  boxes may be ticked, so where it stands is no longer knowable from here — a fresh sequence
+   *  would be computed from a state the dialog left behind and could commit a different answer. */
+  | "partial";
+
+export type AnswerResult = { ok: true } | { ok: false; reason: AnswerFailure };
+
+/** The body of `POST /api/question/:sessionId/answer`. The session comes from the route path, not
+ *  from here — a client names the dialog it is answering, never the session it belongs to. */
+export interface AnswerRequestBody {
+  toolUseId: string;
+  /** Chosen option indexes, one entry per question. */
+  picks?: number[][];
+  /** Or the user's own words, for the dialog's text row. */
+  text?: string;
+}
+
+/** Read a request body's SHAPE. Whether the picks or the words fit the dialog is decided against
+ *  the questions the host itself recorded — see server/session/answerQuestion.ts. */
+export const readAnswerRequest = (body: unknown): AnswerRequestBody | null => {
+  if (!isRecord(body) || typeof body.toolUseId !== "string") return null;
+  const text = typeof body.text === "string" ? { text: body.text } : {};
+  return { toolUseId: body.toolUseId, ...(body.picks === undefined ? {} : { picks: readPickRows(body.picks) }), ...text };
+};
+
+// Rows of numbers, or nothing. A row that is not that is dropped to `[]` rather than coerced: the
+// host then refuses it as bad-picks, and a coerced pick is a keystroke aimed at a row nobody chose.
+const readPickRows = (picks: unknown): number[][] =>
+  Array.isArray(picks) ? picks.map((row) => (Array.isArray(row) ? row.filter((idx): idx is number => typeof idx === "number") : [])) : [];
+
+export const isAnswerFailure = (value: unknown): value is AnswerFailure =>
+  value === "closed" || value === "bad-picks" || value === "unwritable" || value === "partial";
+
+const KEY_DOWN = "\x1b[B";
+const KEY_ENTER = "\r";
+
+// The dialog lists MORE rows than `options`: a "Type something" row follows them, and a
+// multi-select question puts its Submit row after that. So Submit sits at options.length + 1.
+// Measured against claude 2.1.231, not inferred from the tool schema — the extra rows exist
+// only on screen, and reading the schema alone would aim every multi-select Enter one row short.
+const submitRow = (options: readonly AskOption[]): number => options.length + 1;
+
+const moveDown = (from: number, to: number): string[] => Array.from({ length: Math.max(0, to - from) }, () => KEY_DOWN);
+
+// Enter TOGGLES a multi-select row and leaves the cursor where it is, so each pick is
+// "walk down to it, toggle", and the walk starts from the previous pick rather than the top.
+const toggleEach = (picks: readonly number[]): { keys: string[]; cursor: number } =>
+  picks.reduce<{ keys: string[]; cursor: number }>(({ keys, cursor }, idx) => ({ keys: [...keys, ...moveDown(cursor, idx), KEY_ENTER], cursor: idx }), {
+    keys: [],
+    cursor: 0,
+  });
+
+const keysForOne = (question: AskQuestion, picks: readonly number[]): string[] => {
+  if (!question.multiSelect) return [...moveDown(0, picks[0] ?? 0), KEY_ENTER];
+  const { keys, cursor } = toggleEach(picks);
+  return [...keys, ...moveDown(cursor, submitRow(question.options)), KEY_ENTER];
+};
+
+// Ascending and distinct, because the walk above only ever moves DOWN: an out-of-order pick
+// would silently toggle the wrong row rather than fail.
+const picksValid = (question: AskQuestion, picks: readonly number[]): boolean => {
+  const inRange = picks.every((idx) => Number.isInteger(idx) && idx >= 0 && idx < question.options.length);
+  const ascending = picks.every((idx, i) => i === 0 || idx > (picks[i - 1] ?? -1));
+  return inRange && ascending && (question.multiSelect || picks.length === 1);
+};
+
+// The review screen ("Ready to submit your answers?", with Submit preselected) appears for every
+// shape EXCEPT a lone single-select question, which commits on the option's own Enter. All four
+// shapes were measured; guessing here either leaves the dialog open or drops a stray Enter into
+// the prompt once it has closed.
+const needsReview = (questions: readonly AskQuestion[]): boolean => questions.length > 1 || questions.some((question) => question.multiSelect);
+
+// Answering in the user's own words, through the dialog's own `Type something` row.
+//
+// That row IS a text field, and the way in is to highlight it and type: the row then reads back what
+// was typed, and Enter commits it as the ANSWER — `answers` carries the words, not a decline.
+// Measured against claude 2.1.231. (Enter on the row while it is still empty declines instead,
+// which is what a first reading of it mistook for its whole behaviour.)
+//
+// It sits directly after that question's options.
+export const keysToAnswerInWords = (questions: readonly AskQuestion[], text: string): string[] | null => {
+  const only = questions.length === 1 ? questions[0] : undefined;
+  // The one shape this was measured on: a lone SINGLE-select question, where the text row's Enter
+  // is the whole answer. The others each end somewhere this sequence does not reach — a wizard
+  // moves on to its next question, and a multi-select dialog stops at its review screen — and the
+  // host would claim the dialog while the terminal still waits for something the pane cannot send.
+  if (!only || only.multiSelect || !text) return null;
+  return [...moveDown(0, only.options.length), text, KEY_ENTER];
+};
+
+/**
+ * The keystrokes that answer a live AskUserQuestion dialog. `picks[i]` holds the chosen option
+ * indexes of `questions[i]` — exactly one for a single-select question, any ascending set for a
+ * multi-select one. Null when the picks do not fit the questions, so a caller cannot half-drive
+ * a dialog it has misread.
+ */
+export const keysForAnswers = (questions: readonly AskQuestion[], picks: readonly (readonly number[])[]): string[] | null => {
+  if (questions.length === 0 || picks.length !== questions.length) return null;
+  const paired = questions.map((question, i) => ({ question, picks: picks[i] ?? [] }));
+  if (!paired.every(({ question, picks: chosen }) => picksValid(question, chosen))) return null;
+  const keys = paired.flatMap(({ question, picks: chosen }) => keysForOne(question, chosen));
+  return needsReview(questions) ? [...keys, KEY_ENTER] : keys;
+};

package/common/bundledSkills.ts

@@ -22,6 +22,7 @@ export const BUNDLED_SKILL_NAMES = [
   "mulmoterminal-notify",
   "mulmoterminal-bug-report",
   "mulmoterminal-decisions",
+  "mulmoterminal-shared-app",
 ] as const;
 
 export type BundledSkillName = (typeof BUNDLED_SKILL_NAMES)[number];

package/common/collectionPortability.ts

@@ -22,7 +22,10 @@ export type SelfContainmentCode =
   /** No `primaryKey`, so ids are 4 random bytes and two machines can mint the same one. */
   | "no-primary-key"
   /** The project is not a git repo, so there is nothing to clone and most checks do not apply. */
-  | "not-a-repo";
+  | "not-a-repo"
+  /** Records live in the app's Firestore, not in the repository — by design for a SHARED
+   *  collection, and the reason it clones differently from every other kind. */
+  | "shared-store";
 
 /** `blocker` stops the clone working; `warning` costs something on the other machine; `info` is
  *  context. Only a blocker makes `portable` false. */

package/common/dirChrome.ts

@@ -3,6 +3,8 @@
 // all extend this, so a field added on one side can't go missing on the other.
 // `theme` and `colors` stay out of it — each side declares them with its own type
 // (the server keeps the validated strings, the client narrows them to xterm's ITheme).
+import type { HeaderStatusColors, HeaderStatusTint } from "./headerStatusColors.js";
+
 export interface DirChrome {
   name: string | null;
   badgeColor: string | null;
@@ -11,6 +13,11 @@ export interface DirChrome {
   // palette) — these tint the chrome around the terminal, not the terminal itself.
   headerColor: string | null;
   headerTextColor: string | null;
+  // What the header shows once a status REPLACES that background — working / done / blocked
+  // (common/headerStatusColors.ts). null means "not configured here", so a directory that says
+  // nothing falls through to the global default rather than asserting the built-in over it.
+  headerStatusColors: HeaderStatusColors | null;
+  headerStatusTint: HeaderStatusTint | null;
   // The cell frame + accents (grid cell): body background, border, the idle status
   // dot, and the header's icon buttons. Hex #rrggbb or null for the theme default.
   cellColor: string | null;
@@ -40,6 +47,8 @@ export const EMPTY_DIR_CHROME: Readonly<DirChrome> = {
   badgeColor: null,
   headerColor: null,
   headerTextColor: null,
+  headerStatusColors: null,
+  headerStatusTint: null,
   cellColor: null,
   cellBorderColor: null,
   dotColor: null,

package/common/dirConfigSource.ts

@@ -14,6 +14,8 @@ export const DIR_CONFIG_KEYS = [
   "badgeColor",
   "headerColor",
   "headerTextColor",
+  "headerStatusColors",
+  "headerStatusTint",
   "cellColor",
   "cellBorderColor",
   "dotColor",

package/common/githubPaneOrder.ts

@@ -0,0 +1,83 @@
+// Which repository's section the GitHub pane leads with.
+//
+// The pane is opened beside a CELL, and the cell names a directory — so the list is most useful
+// with that directory's repository first. Reordering rather than scrolling to it: a scroll that
+// lands slightly off looks like nothing happened, it has to re-run on every reload, and a repo
+// with no open PRs and no open issues has nothing to scroll to at all, where an empty section at
+// the top still answers "yours: none".
+//
+// Pure and shared so it can be tested without mounting the pane, and so the PR list and the issue
+// list cannot drift into ordering themselves differently.
+import { dirPathKey } from "./dirPathKey.js";
+
+/** The only field either list is ordered by. Both `RepoPrs` and `RepoIssues` carry it. */
+export interface RepoGrouped {
+  repo: string;
+}
+
+/** Case-insensitively, the way GitHub itself treats `owner/repo`. */
+const sameRepo = (a: string, b: string): boolean => a.toLowerCase() === b.toLowerCase();
+
+/**
+ * Whether `cwd` is the clone at `base`, or anywhere inside it.
+ *
+ * CONTAINMENT, not equality: a cell is very often somewhere under the clone rather than at its
+ * root — the user cd'd into `src/`, or the cell was started there — and an exact match left every
+ * one of those leading with the wrong repo (Codex review).
+ *
+ * Through `dirPathKey` because the browser has no filesystem: it folds both separators, a trailing
+ * slash, `.` and `..` into one spelling. Lexical only, so it cannot see through a symlink — which
+ * is right here, where the answer decides presentation. (server/infra/path-within.ts carries the
+ * strict rule for the places where it is a boundary.) Case-folded on top: Windows and the default
+ * macOS volume both treat two spellings of one directory as the same one.
+ */
+const isWithinDir = (base: string, cwd: string): boolean => {
+  const root = dirPathKey(base).toLowerCase();
+  const target = dirPathKey(cwd).toLowerCase();
+  if (root === "" || target === "") return false;
+  if (target === root) return true;
+  // A prefix is NOT containment — `/srv/project-old` starts with `/srv/project`. The separator is
+  // what makes it a boundary. `dirPathKey` leaves one only on a filesystem root ("/", "C:/").
+  return target.startsWith(root.endsWith("/") ? root : `${root}/`);
+};
+
+/**
+ * `owner/repo` for the directory a cell is in, from the reverse map `/api/repo-dirs` already
+ * serves — no extra request and no `git` subprocess, since the view fetches it anyway for the
+ * issue rows' start control.
+ *
+ * `null` for a directory that names no repository — not a git repo, no `origin`, a forge we cannot
+ * act on, or simply a clone the user never registered in Settings. All four are ordinary, and the
+ * caller leaves the order alone.
+ */
+export function repoForCwd(cwd: string | null | undefined, repoDirs: readonly { repo: string; dirs: readonly { path: string }[] }[]): string | null {
+  if (!cwd) return null;
+  // The DEEPEST match wins. Clones nest here — a worktree under a repo's managed root, or a repo
+  // vendored inside another — and the innermost one is the repository the cell is actually in.
+  let best: { repo: string; depth: number } | null = null;
+  for (const entry of repoDirs) {
+    for (const dir of entry.dirs) {
+      if (!isWithinDir(dir.path, cwd)) continue;
+      const depth = dirPathKey(dir.path).length;
+      if (!best || depth > best.depth) best = { repo: entry.repo, depth };
+    }
+  }
+  return best?.repo ?? null;
+}
+
+/**
+ * `rows` with `repo`'s entry first, everything else in the order it arrived.
+ *
+ * A stable move, not a sort: the server's order is meaningful (it follows the configured repo
+ * list) and only one element is being promoted. Returns the input unchanged when there is no repo
+ * to lead with, or when it has no section — which is why a cell in an unregistered clone simply
+ * gets the conventional order.
+ */
+export function leadWithRepo<T extends RepoGrouped>(rows: readonly T[], repo: string | null): T[] {
+  if (!repo) return [...rows];
+  const at = rows.findIndex((row) => sameRepo(row.repo, repo));
+  if (at <= 0) return [...rows];
+  const lead = rows[at];
+  if (lead === undefined) return [...rows]; // unreachable: findIndex answered a real index
+  return [lead, ...rows.slice(0, at), ...rows.slice(at + 1)];
+}

package/common/gitlabHosts.ts

@@ -10,7 +10,18 @@ import { GITHUB_HOST, GITLAB_HOST } from "./repoEntry.js";
 // A hostname, lower case, with at least one dot. The dot is not cosmetic: `parseRepoEntry` reads a
 // leading segment as a host ONLY when it contains one, so a dotless declaration could never match
 // an entry and would sit in the config doing nothing.
-const HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+// Tested per label rather than as one hostname pattern: the single-regex form nested `[a-z0-9-]*`
+// inside the repeated dotted group, which is the shape that goes exponential on input that almost
+// matches. Measured, this one did not — but the per-label form removes the class instead of
+// depending on that, and reads as the rule it enforces.
+const LABEL_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+const isLabel = (label: string): boolean => LABEL_RE.test(label) && !label.endsWith("-");
+
+const isHostname = (host: string): boolean => {
+  const labels = host.split(".");
+  return labels.length > 1 && labels.every(isLabel);
+};
 
 const SCHEME_RE = /^https?:\/\//;
 
@@ -26,7 +37,7 @@ const GITLAB_HOSTS_MAX = 20;
 export function normalizeGitlabHost(input: unknown): string | null {
   if (typeof input !== "string") return null;
   const host = input.trim().toLowerCase().replace(SCHEME_RE, "").replace(/\/$/, "");
-  return HOSTNAME_RE.test(host) ? host : null;
+  return isHostname(host) ? host : null;
 }
 
 /** The declared hosts, de-duplicated and capped. Anything unusable is dropped rather than failing

package/common/headerStatusColors.ts

@@ -0,0 +1,122 @@
+// What a cell header is painted with while a session is working / done / blocked, and who decides.
+//
+// A header has two layers that were designed together and can drift apart: the DIRECTORY's colour
+// (`headerColor` plus its ink) and the STATUS wash the theme mixes over it. #1591 is what the drift
+// looks like — a `headerTextColor` chosen against a dark purple, still applied while a light theme
+// paints the pale `--bg-selected` a running session gets: white on #d6e4fb, measured at 1.15:1 off
+// the reporter's own screenshot.
+//
+// So both layers are resolved HERE, once, and every caller asks rather than combining the pieces
+// itself. That is also what lets a directory recolour a status: the same function answers "what
+// shows now", whether the answer came from the theme or from a config file.
+//
+// `idle` is deliberately not a configurable status. `headerColor` / `headerTextColor` ARE the idle
+// state, and a second way to say the same thing is how one directory ends up written in two
+// different colours.
+import { headerTextColorFor } from "./chromeFromColor.js";
+import { isHexColor } from "./hexColor.js";
+import { isRecord } from "./isRecord.js";
+
+/** The states whose header background the theme replaces, and which a config may therefore claim. */
+export const HEADER_STATUS_KEYS = ["working", "done", "blocked"] as const;
+export type HeaderStatusKey = (typeof HEADER_STATUS_KEYS)[number];
+
+/** Every state a header paints — the three above plus the directory's own. */
+export type HeaderPaintStatus = HeaderStatusKey | "idle";
+
+export interface HeaderStatusColor {
+  background: string | null;
+  /** Omitted derives an AA ink from `background`. Naming it without a background is honoured
+   *  as-is: that is a statement about a wash the author can see, unlike `headerTextColor`, which
+   *  is a statement about the directory's own colour and is what #1591 misapplied. */
+  text: string | null;
+}
+
+export type HeaderStatusColors = Partial<Record<HeaderStatusKey, HeaderStatusColor>>;
+
+/** `background`: the theme washes the header while a session works (today's behaviour).
+ *  `none`: the directory's own `headerColor` stays, and the status reads from the cell border,
+ *  the dot and the status pill instead. */
+export const HEADER_STATUS_TINTS = ["background", "none"] as const;
+export type HeaderStatusTint = (typeof HEADER_STATUS_TINTS)[number];
+export const DEFAULT_HEADER_STATUS_TINT: HeaderStatusTint = "background";
+
+// `none` says "keep my palette", and `blocked` is the one state where nothing proceeds until the
+// user answers. A switch aimed at colour consistency taking the amber off THAT is an accident, so
+// it doesn't reach it — a directory that wants a different blocked colour says so outright with a
+// `headerStatusColors.blocked` entry, which is honoured below.
+const TINT_NONE_APPLIES_TO: readonly HeaderStatusKey[] = ["working", "done"];
+
+/** What a header paints in one state. `null` means "the theme decides" — the caller emits no
+ *  custom property and the theme's own wash / ink shows through the CSS fallback. */
+export interface HeaderPaint {
+  background: string | null;
+  text: string | null;
+}
+
+const NOTHING: HeaderPaint = { background: null, text: null };
+
+export interface HeaderChrome {
+  headerColor: string | null;
+  headerTextColor: string | null;
+  // Both nullable so "nothing configured" is expressible without every caller spreading a default
+  // in first — the shape a DirChrome already carries.
+  statusColors: HeaderStatusColors | null;
+  tint: HeaderStatusTint | null;
+}
+
+// A hex background always yields a readable ink, so `background` set and `text` unset cannot
+// produce an unreadable header — the point of letting a config name one colour.
+function paintFor(background: string | null, text: string | null): HeaderPaint {
+  if (isHexColor(text)) return { background: isHexColor(background) ? background : null, text };
+  if (isHexColor(background)) return { background, text: headerTextColorFor(background) };
+  return NOTHING;
+}
+
+export function resolveHeaderPaint(status: HeaderPaintStatus, chrome: HeaderChrome): HeaderPaint {
+  if (status === "idle") return paintFor(chrome.headerColor, chrome.headerTextColor);
+  const declared = chrome.statusColors?.[status];
+  if (declared && (isHexColor(declared.background) || isHexColor(declared.text))) return paintFor(declared.background, declared.text);
+  // `none` means "keep the colour I chose", so it needs a colour to keep. A directory with a
+  // `headerTextColor` and no usable `headerColor` has nothing for the ink to have been chosen
+  // against — carrying the ink alone would leave it on the theme's wash, which is the bug this
+  // whole file exists to stop (Codex review on #1619).
+  const keepsDirectoryColour = chrome.tint === "none" && TINT_NONE_APPLIES_TO.includes(status) && isHexColor(chrome.headerColor);
+  return keepsDirectoryColour ? paintFor(chrome.headerColor, chrome.headerTextColor) : NOTHING;
+}
+
+// ---- config parsing -------------------------------------------------------------------------
+
+const oneEntry = (input: unknown): HeaderStatusColor | null => {
+  if (isHexColor(input)) return { background: input, text: null };
+  if (!isRecord(input)) return null;
+  const background = isHexColor(input.background) ? input.background : null;
+  const text = isHexColor(input.text) ? input.text : null;
+  return background || text ? { background, text } : null;
+};
+
+/** Per status, so one bad entry can't discard the two that are right. A bare hex string is
+ *  accepted for a status as shorthand for `{ background: … }` — the common case is one colour. */
+export function sanitizeHeaderStatusColors(input: unknown): HeaderStatusColors {
+  if (!isRecord(input)) return {};
+  const out: HeaderStatusColors = {};
+  for (const key of HEADER_STATUS_KEYS) {
+    const entry = oneEntry(input[key]);
+    if (entry) out[key] = entry;
+  }
+  return out;
+}
+
+/** `null` for anything that isn't one of the two modes, which is what "unset here" has to look
+ *  like: a directory that says nothing must fall through to the global default rather than
+ *  asserting the built-in one over it. */
+export function sanitizeHeaderStatusTint(input: unknown): HeaderStatusTint | null {
+  return HEADER_STATUS_TINTS.find((mode) => mode === input) ?? null;
+}
+
+/** The directory's answer, else the global one. WHOLE-key, not a per-status merge: the same rule
+ *  `mergedDirConfigRaw` states for the three config files, and for its reason — a block a reader
+ *  has to assemble from two places is harder to predict than one they can see entire. */
+export function mergeHeaderStatusColors(global: HeaderStatusColors | null, dir: HeaderStatusColors | null): HeaderStatusColors | null {
+  return dir && Object.keys(dir).length > 0 ? dir : global;
+}

package/common/hexColor.ts

@@ -0,0 +1,12 @@
+// What counts as a colour anywhere a directory's .mulmoterminal.json supplies one. Only
+// 6-digit hex: the server's schema accepts nothing else, and the UI drops what it can't
+// parse rather than handing an unknown string to a style binding.
+//
+// In common/ because both sides decide from it: the server validates a config file with this
+// rule and the browser drops what it can't paint, and a third copy of the regex is how the two
+// answers start differing.
+const HEX_COLOR_RE = /^#[0-9a-fA-F]{6}$/;
+
+// `unknown` rather than `string | null | undefined`: this is what a config parser asks about a
+// value straight out of JSON, and narrowing the parameter would make every such site cast first.
+export const isHexColor = (color: unknown): color is string => typeof color === "string" && HEX_COLOR_RE.test(color);

package/common/terminalReplies.ts

@@ -0,0 +1,66 @@
+// What a terminal emulator sends back on the INPUT channel without anyone typing.
+//
+// xterm.js answers the application's own queries there: device attributes, the foreground and
+// background colours, the cursor position. It also says when the terminal gained or lost focus.
+// All of it arrives exactly as a keystroke does, and none of it is the user answering anything.
+//
+// That matters to anything asking "has the user typed since this question appeared?"
+// (server/session/write-to-session.ts). Counting these replies meant an answer from the question
+// pane was refused after any attach, resize or theme read — measured, not guessed: a single button
+// press was preceded by `ESC[?1;2c`, `ESC[>0;276;0c` and two OSC colour replies (#1693).
+//
+// MOUSE reports are deliberately absent. They look the same on the wire, but a click can select an
+// option in the dialog — that is the user answering, and an answer already being typed must yield
+// to it exactly as it yields to a keystroke.
+//
+// The forms are spelled out rather than generalised — no "any OSC", no "any CSI". This list decides
+// what CANNOT interrupt an answer, so a pattern wider than the replies actually queried would hand
+// that exemption to input nobody has looked at.
+const ESC = "\u001b";
+const BEL = "\u0007";
+const ST = `(?:${BEL}|${ESC}\\\\)`;
+
+const REPLIES = [
+  `${ESC}\\[[IO]`, // focus in / out
+  `${ESC}\\[\\?[\\d;]*c`, // primary device attributes
+  `${ESC}\\[>[\\d;]*c`, // secondary / tertiary device attributes
+  `${ESC}\\[\\d+;\\d+R`, // cursor position report
+  `${ESC}\\]1[0-9];rgb:[\\da-fA-F/]*${ST}`, // colour queries — foreground, background, cursor
+].join("|");
+
+const ANY_REPLY = new RegExp(REPLIES, "g");
+
+// A chunk can END mid-sequence: the socket splits where it likes, so `ESC[?1` and `;2c` can arrive
+// separately. Neither half matches, and both would read as "the user typed" — the very false alarm
+// this module exists to stop. A tail that could still GROW into a reply is held instead of judged.
+//
+// It stops before the terminating letter, which is what keeps a real key out of the holding pen:
+// `ESC[B` (Down) carries its `B` already and cannot be waiting for anything.
+//
+// A LONE Escape is never held. It is how the user cancels the dialog, and holding it would let a
+// paced answer carry on typing into a question they had just dismissed — while the reply it might
+// theoretically have grown into is written whole by the emulator, in one frame, every time.
+const STILL_GROWING = new RegExp(`^${ESC}(?:\\[[?>]?[\\d;]*|\\][\\d;]*(?:rgb:[\\da-fA-F/]*)?)$`);
+
+/** The longest tail worth holding. Bounded so a stream of junk cannot accumulate. */
+const MAX_PENDING = 64;
+
+export interface InputScan {
+  /** Did anything in this chunk come from the user? */
+  fromUser: boolean;
+  /** The unfinished tail, to be carried into the next chunk. */
+  pending: string;
+}
+
+/**
+ * Classify one chunk of terminal input, carrying `pending` from the chunk before it.
+ *
+ * `fromUser` is false only when everything is a reply the emulator produced by itself. A trailing
+ * sequence that is still growing is neither — it waits in `pending` until it finishes.
+ */
+export const scanForUserInput = (pending: string, data: string): InputScan => {
+  const chunk = `${pending}${data}`;
+  const rest = chunk.replace(ANY_REPLY, "");
+  if (rest.length > 0 && rest.length <= MAX_PENDING && STILL_GROWING.test(rest)) return { fromUser: false, pending: rest };
+  return { fromUser: rest.length > 0, pending: "" };
+};