mulmoterminal 4.1.0 → 4.2.0

package/README.md

@@ -39,7 +39,7 @@ npx mulmoterminal@latest        # starts on http://localhost:34567 and opens you
 
 ![MulmoTerminal's grid view — four live Claude sessions running side by side, each in its own color-coded project](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-2x2-live.png)
 
-*The grid is a **cockpit for parallel agents** — here, four live Claude sessions, each in its own color-coded project. Every cell's header carries what you need to triage at a glance: **model · context %**, **token counts** (`⇡in ⇣out`), the **git branch / changes** chip, and an AI summary of what the agent is doing. A cell's **border color signals state** — working / done (blue), needs-you (amber — e.g. waiting on a permission), idle — with an attention chime so a stuck cell off-screen still pulls you back. Supervise many; only step in where you're called.*
+*The grid is a **cockpit for parallel agents** — here, four live Claude sessions, each in its own color-coded project. Every cell's header carries what you need to triage at a glance: **model · context %**, **token counts** (`⇡in ⇣out`), the **git branch / changes** chip, and an AI summary of what the agent is doing. A cell's **border color signals state** — working (blue), done (green), needs-you (amber — e.g. waiting on a permission), idle — with an attention chime so a stuck cell off-screen still pulls you back. Supervise many; only step in where you're called.*
 
 ## Why you'll want it
 
@@ -88,9 +88,9 @@ question — an amber dot; nothing proceeds until you answer) and which are **fi
 you haven't seen** (a green dot) — driven by Claude/Codex activity hooks the server injects per
 spawn. The horizontal tab bar carries the same two dots.
 
-![One agent enlarged, with the cockpit roster beside it](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/cockpit-roster.png)
+![One agent zoomed, with the GUI panel beside it](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/zoom-canvas.png)
 
-*To focus on one agent, **zoom its cell**: it takes the window, and a pane opens beside it — the **cockpit roster** above, or the **GUI panel** ("Canvas"), where that agent's tool calls render as documents, forms, charts, images, and HTML rather than printed text. **The app opens on the grid** (`/`, settling on `/terminals`), which is the only view; 3.x had a separate single view at `/chat` and 4.0.0 removed it, so that URL now lands on the grid like any other.*
+*To focus on one agent, **zoom its cell**: it takes the window, and the **GUI panel** ("Canvas") opens beside it, where that agent's tool calls render as documents, forms, charts, images, and HTML rather than printed text. **The app opens on the grid** (`/`, settling on `/terminals`), which is the only view; 3.x had a separate single view at `/chat` and 4.0.0 removed it, so that URL now lands on the grid like any other.*
 
 **Inserting a file path** — like a native terminal, you can put a file's absolute path into
 the prompt: **drag a file** onto the terminal, or click the **file button** in the terminal
@@ -204,11 +204,17 @@ more.
 
 Needs **Node ≥ 22.9**, plus these CLIs on your `PATH`:
 
+> **Never installed any of this before?** The guide walks it end to end, macOS and Windows,
+> assuming no command-line experience:
+> [Getting started](https://receptron.github.io/mulmoterminal/guide/en/getting-started.html) ·
+> [はじめに — 起動するまで](https://receptron.github.io/mulmoterminal/guide/ja/getting-started.html)
+
 | | Tool | What it gives you | Install |
 | --- | --- | --- | --- |
 | **Required** | [`claude`](https://claude.com/claude-code) | every Claude session — this app is a cockpit for it | `npm i -g @anthropic-ai/claude-code`, then run `claude` once to log in |
 | **Required** | `git` | [worktree isolation](#git-worktrees--pull-requests), each cell's branch / unsaved-dot / diff readout, the PR footer | `brew install git` · `sudo apt install git` · `sudo dnf install git` · Windows: [git-scm.com](https://git-scm.com/download/win) |
 | **Required** | `gh` | the cross-repo **PRs & Issues** view and one-click PR creation — it uses your `gh` login, so no token is stored | [cli.github.com](https://cli.github.com), then `gh auth login` |
+| Optional | `glab` | the same for **GitLab** projects (#981) — gitlab.com, and a self-hosted instance you declare in `gitlabHosts` (#1332). Same arrangement: the CLI holds the credentials, this app stores no token | `brew install glab`, then `glab auth login` (self-hosted: `glab auth login --hostname gitlab.example.com`) |
 | Recommended | `tmux` | [session persistence](#session-persistence-tmux) — terminals survive a server restart | `brew install tmux` · `sudo apt install tmux` · `sudo dnf install tmux` · no native Windows build (falls back to plain PTYs) |
 | Optional | `codex` | [Codex sessions](#agents-claude--codex) in a cell, alongside Claude | `npm i -g @openai/codex` |
 | Optional | `ffmpeg` | video rendering from the [mulmo-script panel](#wiki-collections--the-gui-panel) (its plugin ships enabled) | `brew install ffmpeg` · `sudo apt install ffmpeg` · `sudo dnf install ffmpeg` |
@@ -536,7 +542,8 @@ The Settings modal (⚙) persists per-user UI choices to `~/.mulmoterminal/confi
 | `soundFile`  | Absolute path to a custom **attention sound**, the fallback for every kind. Empty/unset uses the built-in synthesized chime. |
 | `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 (via your `gh` login). An entry may name its host (`gitlab.com/group/project`); only github.com is read today, and other hosts show a row saying so. |
+| `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. |
 | `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. |
 | `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. |
@@ -734,22 +741,21 @@ yarn dev                # backend (:34567) + Vite UI (:6856), concurrently — o
 yarn dev:server         # backend only  (node --import tsx --env-file-if-exists=.env server/index.ts)
 yarn dev:client         # Vite dev server only
 
-yarn build              # type-check (vue-tsc) + vite build -> dist/
-yarn typecheck:server   # type-check the server (tsconfig.server.json)
-yarn typecheck:test     # type-check the specs (tsconfig.test*.json)
+yarn typecheck          # type-check everything (vue-tsc -b)
+yarn build              # type-check + vite build -> dist/
 yarn server             # run backend; serves dist/ + the APIs on :34567
 yarn test               # vitest run
 ```
 
-The backend is TypeScript run directly via `tsx` (no build step); `server/` is
-type-checked separately through `tsconfig.server.json` (`strict`), kept out of
-the main `build` so the two type-check independently.
-
-Specs sit outside both of those projects, and vitest strips types rather than
-checking them — so `yarn typecheck:test` is what keeps them honest. It mirrors
-the same split: `tsconfig.test.json` (client specs, DOM + `.vue`) and
-`tsconfig.test-server.json` (server specs, node). CI runs it alongside the
-other two.
+`yarn typecheck` covers the whole repo. The root `tsconfig.json` is a solution
+file that references all five projects, so one `vue-tsc -b` builds them:
+`tsconfig.app.json` (client), `tsconfig.node.json` (vite config),
+`tsconfig.server.json` (backend, run directly via `tsx` with no build step),
+plus `tsconfig.test.json` and `tsconfig.test-server.json` for the specs — which
+need checking of their own because vitest strips types rather than checking
+them. They exist as separate projects because each has its own compiler options
+(the client ones DOM + `.vue`, the server ones node, the specs with
+`noUncheckedIndexedAccess` off).
 
 In dev, open the Vite URL; its proxy forwards `/ws`, `/ws/pubsub`, and `/api` to
 `:34567`. In production, run `yarn build` then `yarn server` and open
@@ -914,6 +920,17 @@ 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.
+
 **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
 only when it has none. A row whose session is open in another terminal reads `in use` and
@@ -962,7 +979,7 @@ Closing a worktree cell asks whether to **keep** the worktree or **discard & rem
 
 **PRs & Issues (cross-repo).** The toolbar's **Pull requests** button opens a full-screen
 view that aggregates open PRs **and** issues across the repos listed in Settings →
-**Pull request repos** (`prRepos`, `owner/repo` entries) via your server-side `gh` login.
+**Pull request repos** (`prRepos`, `owner/repo` entries, or `gitlab.com/group/project` — plus any host declared in `gitlabHosts`) via your server-side `gh` / `glab` login.
 PRs show a CI-rollup / review-decision / draft badge; each repo lists its latest open
 issues. Rows are real links, per-repo errors don't sink the view, and the two lists load
 independently. Backed by `GET /api/prs` and `GET /api/issues`.
@@ -1303,7 +1320,7 @@ same-origin-guarded.
 | `POST /api/git-remote` | The dir's GitHub repo URL (for the header GitHub menu). |
 | `GET /api/worktrees?cwd=` · `GET /api/worktrees/diff?cwd=` | List managed worktrees / diff one vs its base. |
 | `POST /api/worktrees/create` · `/remove` · `/push` · `/pr` | Create on `agent/<slug>` — or, with `issue: <N>`, on `issue/<N>-<slug>` forked from a freshly fetched `origin/<base>`; remove (managed root only), push, open a PR (`gh`, else compare URL). |
-| `GET /api/prs` · `GET /api/issues` | Open PRs / issues across the configured `prRepos` (via `gh`). |
+| `GET /api/prs` · `GET /api/issues` | Open PRs / issues across the configured `prRepos` — `gh` for github.com entries, `glab` for gitlab.com and any host declared in `gitlabHosts`. |
 | `GET /api/repo-dirs` | Which saved directories clone which GitHub repo, ordered, with the recorded choice per repo. |
 | `POST /api/issues/start` | Cut an issue's worktree in one of that repo's known clones and spawn a session there, seeded with the issue as a draft. |
 | `GET /api/github/star` · `POST /api/github/star` | Whether you have starred MulmoTerminal, and star it (via `gh`). `starred: null` means `gh` could not answer, and hides the button. |
@@ -1652,7 +1669,7 @@ server/
   session/        per-session transcript/activity/cost: transcript.ts,
                   session-resolve.ts, activity-*.ts, cost.ts,
                   command-summary.ts, terminal-replay.ts, file-cache.ts
-  git/            git & GitHub (via gh) + worktrees: git-status.ts, gitRemote.ts,
+  git/            git, GitHub (gh) and GitLab (glab) + worktrees: git-status.ts, gitRemote.ts,
                   gh.ts, prs.ts, issues.ts, pr-for-branch.ts, worktrees.ts, worktree-*.ts
   files/          files-browse.ts (contained tree read/write), pick-file.ts,
                   open-dir.ts, scripts.ts (Run-menu script.json loader)

package/bin/mulmoterminal.js

@@ -85,6 +85,15 @@ function claudeInstalled() {
 const PATH_TOOLS = [
   { cmd: "git", versionArg: "--version", required: true, why: "worktrees, per-cell branch/diff, PR footer", hint: "brew install git  ·  apt install git" },
   { cmd: "gh", versionArg: "--version", required: true, why: "PRs & Issues view + one-click PRs", hint: "https://cli.github.com  (then: gh auth login)" },
+  // Optional rather than a second required tool: github.com is what the app is built around, and a
+  // user with no GitLab project should not be told they are missing something (#981).
+  {
+    cmd: "glab",
+    versionArg: "--version",
+    required: false,
+    why: "the PRs & Issues view for gitlab.com projects",
+    hint: "brew install glab  (then: glab auth login)",
+  },
   { cmd: "tmux", versionArg: "-V", required: false, why: "sessions survive a restart", hint: "brew install tmux  ·  apt install tmux" },
   { cmd: "codex", versionArg: "--version", required: false, why: "run OpenAI Codex as an agent", hint: "npm install -g @openai/codex" },
   {

package/common/byCodeUnit.ts

@@ -0,0 +1,11 @@
+// Sort filenames and directory names deterministically.
+//
+// `.sort()` with no comparator is flagged (sonarjs/no-alphabetical-sort) because the default is
+// implementation-defined for non-ASCII. The rule suggests `localeCompare`, which would be WRONG
+// here: these are filenames — zero-padded date directories and ISO-stamped rollout files — and
+// ordering them by the user's locale makes the answer depend on who is running the app. Code-unit
+// order is what the callers actually mean, and it is the same everywhere.
+export function byCodeUnit(a: string, b: string): number {
+  if (a < b) return -1;
+  return a > b ? 1 : 0;
+}

package/common/codeBlocks.ts

@@ -59,8 +59,12 @@ export function fencedBlocks(markdown: string): FencedBlock[] {
   const lines = markdown.split("\n");
   const blocks: FencedBlock[] = [];
   let i = 0;
+  // Each line is read into a const before use: with noUncheckedIndexedAccess, `lines[i]` is
+  // `string | undefined` even inside `i < lines.length`, and the loop condition is what actually
+  // rules the undefined out.
   while (i < lines.length) {
-    const open = fenceOf(lines[i]);
+    const line = lines[i];
+    const open = line === undefined ? null : fenceOf(line);
     if (!open) {
       i++;
       continue;
@@ -69,12 +73,12 @@ export function fencedBlocks(markdown: string): FencedBlock[] {
     const info = open.info.trim();
     const body: string[] = [];
     i++;
-    while (i < lines.length && !closes(lines[i], fence)) {
-      body.push(lines[i]);
+    for (let next = lines[i]; next !== undefined && !closes(next, fence); next = lines[i]) {
+      body.push(next);
       i++;
     }
     i++; // step over the closing fence (or past the end, for an unclosed block)
-    blocks.push({ lang: info ? (info.split(/\s+/)[0].toLowerCase() ?? null) : null, body: body.join("\n") });
+    blocks.push({ lang: info ? (info.split(/\s+/)[0]?.toLowerCase() ?? null) : null, body: body.join("\n") });
   }
   return blocks;
 }
@@ -84,5 +88,5 @@ export function fencedBlocks(markdown: string): FencedBlock[] {
  *  exactly like a copy that silently failed. */
 export function lastFencedBlock(markdown: string): FencedBlock | null {
   const withBody = fencedBlocks(markdown).filter((b) => b.body.trim() !== "");
-  return withBody.length ? withBody[withBody.length - 1] : null;
+  return withBody[withBody.length - 1] ?? null;
 }

package/common/gitlabHosts.ts

@@ -0,0 +1,60 @@
+// Which hosts are a GitLab this app can talk to (#1332). `gitlab.com` is known from its name; a
+// self-hosted instance at `gitlab.hogefuga.com` is indistinguishable from any other host, so the
+// user DECLARES it in `gitlabHosts` — the config mechanism #981 said this would need.
+//
+// In `common/` because both sides decide from it: the server picks a CLI from it, and the browser
+// says why a control is off. Two copies would drift, and disagreeing is the failure the forge
+// abstraction exists to undo.
+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])?)+$/;
+
+const SCHEME_RE = /^https?:\/\//;
+
+const GITLAB_HOSTS_MAX = 20;
+
+/** One declared host, or null when the string does not name one.
+ *
+ *  A pasted `https://gitlab.example.com/` is accepted and reduced to its hostname: this value is
+ *  hand-typed into config.json with no UI to validate it, and the browser's address bar is where
+ *  the user is copying from. Anything else with a slash is rejected rather than truncated — a
+ *  project path here is a different mistake, and silently keeping its host would hide it.
+ */
+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;
+}
+
+/** The declared hosts, de-duplicated and capped. Anything unusable is dropped rather than failing
+ *  the whole config — one typo must not cost the user the hosts they spelled correctly. */
+export function sanitizeGitlabHosts(input: unknown): string[] {
+  if (!Array.isArray(input)) return [];
+  const hosts = new Set<string>();
+  for (const value of input) {
+    const host = normalizeGitlabHost(value);
+    if (host) hosts.add(host);
+    if (hosts.size >= GITLAB_HOSTS_MAX) break;
+  }
+  return [...hosts];
+}
+
+/** Whether `host` is a GitLab: gitlab.com, or one the user declared.
+ *
+ *  `github.com` is refused whatever the config says. A declaration is a hand-typed line with no UI
+ *  behind it, and the one that would do real damage — every GitHub repo suddenly addressed with
+ *  `glab` — is also the easiest to write by accident.
+ */
+export const isGitlabHost = (host: string, declared: readonly string[]): boolean => host === GITLAB_HOST || (host !== GITHUB_HOST && declared.includes(host));
+
+/** Why a host is not handled, and what to do about it.
+ *
+ *  ONE sentence, shared by the PRs/Issues row and the start-work refusal: #1332 was filed by a user
+ *  who read "is not supported yet" and could not tell whether their setup was wrong, whether the
+ *  feature was coming, or what to try — so the reason has to carry the fix.
+ */
+export const unknownForgeReason = (host: string): string =>
+  `${host} is not supported yet — MulmoTerminal reads github.com and gitlab.com; if ${host} is a self-hosted GitLab, add it to "gitlabHosts" in ~/.mulmoterminal/config.json and restart`;

package/common/isRecord.ts

@@ -11,3 +11,9 @@ import { isObject } from "graphai";
 // graphai's own `isPlainObject` is exactly this (it also rejects Map/Date/class instances), but
 // it is not exported from the package root, so the array check stays here.
 export const isRecord = (value: unknown): value is Record<string, unknown> => isObject(value) && !Array.isArray(value);
+
+// "Absent, or of this type" — what an OPTIONAL field on a wire shape has to satisfy. A guard that
+// skips these asserts a type it has not seen: absent is meaningful (an older server never said the
+// field), but a present one of the wrong type is a lie the rest of the code then reads.
+export const optionalString = (value: unknown): boolean => value === undefined || typeof value === "string";
+export const optionalBoolean = (value: unknown): boolean => value === undefined || typeof value === "boolean";

package/common/isUnknownArray.ts

@@ -0,0 +1,8 @@
+// The array counterpart to isRecord, and it exists for a reason that is easy to miss:
+// `Array.isArray(value)` on an `unknown` narrows it to **`any[]`**, not `unknown[]`. So the
+// obvious `Array.isArray(x) ? x : []` hands back an array whose elements are outside the type
+// checker entirely, and every read off them type-checks against anything.
+//
+// Declaring the guard's result as `unknown[]` keeps the elements unverified-but-visible, which is
+// what the callers want: they check each element before using it.
+export const isUnknownArray = (value: unknown): value is unknown[] => Array.isArray(value);

package/common/issueStartPlan.ts

@@ -8,15 +8,17 @@
 // docs/remote-host-protocol.md), so it refuses `choose` where the desktop opens it.
 import type { RepoDirs } from "./repoDirs";
 import { GITHUB_HOST, GITLAB_HOST, parseRepoEntry } from "./repoEntry";
+import { isGitlabHost, unknownForgeReason } from "./gitlabHosts";
 
 // Where work can be STARTED — the issue is read and a worktree cut. A host that is merely listable
-// still refuses, and says which host it is rather than blaming a missing clone (#981).
-const STARTABLE_HOSTS: ReadonlySet<string> = new Set([GITHUB_HOST, GITLAB_HOST]);
+// still refuses, and says which host it is rather than blaming a missing clone (#981). A host the
+// user declared as self-hosted GitLab starts work like gitlab.com does (#1332).
+const isStartableHost = (host: string, gitlabHosts: readonly string[]): boolean => host === GITHUB_HOST || isGitlabHost(host, gitlabHosts);
 
-/** The hosts named in a refusal, read off the set rather than written out beside it — a hardcoded
- *  "github.com only" survived GitLab becoming startable and told users the opposite of the truth
- *  (Codex review). Exported so the phone's refusal says the same thing. */
-export const startableHosts = (): string => [...STARTABLE_HOSTS].join(" and ");
+/** The hosts named in a refusal, built from the same rule rather than written out beside it — a
+ *  hardcoded "github.com only" survived GitLab becoming startable and told users the opposite of
+ *  the truth (Codex review). Exported so the phone's refusal says the same thing. */
+export const startableHosts = (gitlabHosts: readonly string[]): string => [...new Set([GITHUB_HOST, GITLAB_HOST, ...gitlabHosts])].join(" and ");
 
 export type IssueStartPlan =
   /** No clone of this repo on this machine, so there is nowhere for the work to happen. */
@@ -35,24 +37,29 @@ export type BlockedIssueStartPlan = Exclude<IssueStartPlan, { kind: "ready" }>;
 
 // `repo` is REQUIRED, not optional, even though only one branch reads it: a caller that omitted it
 // would get `no-clone` for a GitLab repo, which is the exact wrong answer this parameter was added
-// to fix. Making the compiler ask for it is what stops that coming back.
-export function issueStartPlan(entry: RepoDirs | undefined, repo: string): IssueStartPlan {
+// to fix. Making the compiler ask for it is what stops that coming back. `gitlabHosts` is required
+// for the same reason — defaulted to empty, a caller that forgot it would refuse the user's own
+// self-hosted GitLab and blame the host (#1332).
+export function issueStartPlan(entry: RepoDirs | undefined, repo: string, gitlabHosts: readonly string[]): IssueStartPlan {
   // Checked before the clone list, because a GitLab repo has no entry there and would otherwise
   // read as "no clone" — a reason that is not true and points at the wrong fix.
   const parsed = parseRepoEntry(repo);
-  if (parsed && !STARTABLE_HOSTS.has(parsed.host)) return { kind: "unsupported-forge", host: parsed.host };
+  if (parsed && !isStartableHost(parsed.host, gitlabHosts)) return { kind: "unsupported-forge", host: parsed.host };
   const dirs = entry?.dirs ?? [];
   if (dirs.length === 0) return { kind: "no-clone" };
   // A recording wins even when the repo has one clone: it is still the same answer, and treating
   // the two cases the same keeps "recorded" from being a state the UI has to distinguish.
   const recorded = entry?.primary;
   if (recorded) return { kind: "ready", dir: recorded };
-  if (dirs.length === 1) return { kind: "ready", dir: dirs[0].path };
+  const only = dirs.length === 1 ? dirs[0] : undefined;
+  if (only) return { kind: "ready", dir: only.path };
   return { kind: "choose", dirs };
 }
 
 /** Why the control is disabled, for the row's title text. Null when it is not disabled. */
 export function issueStartBlockedReason(plan: IssueStartPlan, repo: string): string | null {
-  if (plan.kind === "unsupported-forge") return `Starting work supports ${startableHosts()} — ${plan.host} issues are listed here, not started from`;
+  // The same sentence the row's own error carries: the host is not one this app knows, and the fix
+  // is a config line rather than anything about this issue or this clone (#1332).
+  if (plan.kind === "unsupported-forge") return unknownForgeReason(plan.host);
   return plan.kind === "no-clone" ? `No local clone of ${repo} — add one to your directory presets to start work here` : null;
 }

package/common/keymap.ts

@@ -87,6 +87,7 @@ export function parseKeyBinding(input: string): KeyBinding | null {
   const parts = input.split("+").map((part) => part.trim());
   if (parts.length === 0 || parts.some((part) => part === "")) return null;
   const key = parts[parts.length - 1];
+  if (key === undefined) return null; // unreachable: parts.length was checked above
   const binding: KeyBinding = { key, shift: false, alt: false, ctrl: false, meta: false };
   for (const part of parts.slice(0, -1)) {
     const flag = MODIFIERS[part.toLowerCase()];
@@ -226,6 +227,7 @@ function duplicateWarnings(bound: Map<string, Claim[]>): KeymapProblem[] {
   return [...bound.values()].flatMap((claims) => {
     if (claims.length < 2) return [];
     const [winner, ...losers] = [...claims].sort((a, b) => a.rank - b.rank);
+    if (!winner) return []; // unreachable: claims.length >= 2 was checked above
     return losers.map(({ label, binding }) => ({
       action: label,
       binding,

package/common/median.ts

@@ -8,6 +8,11 @@ export const median = (values: number[]): number | null => {
   if (values.length === 0) return null;
   const sorted = [...values].sort((a, b) => a - b);
   const mid = Math.floor(sorted.length / 2);
-  if (sorted.length % 2 === 1) return sorted[mid];
-  return (sorted[mid - 1] + sorted[mid]) / 2;
+  // Read once each: `sorted[mid]` is `number | undefined` under noUncheckedIndexedAccess, and the
+  // length checks above are what actually rule that out.
+  const middle = sorted[mid];
+  if (middle === undefined) return null;
+  if (sorted.length % 2 === 1) return middle;
+  const below = sorted[mid - 1];
+  return below === undefined ? middle : (below + middle) / 2;
 };

package/common/prPhase.ts

@@ -24,9 +24,26 @@ export interface WorkItem {
   // list above all, where "#987" alone says nothing about which request is running (#1014).
   prTitle: string | null;
   issueTitle: string | null;
+  // WHY a request that is open and not obviously failing still cannot merge. GitLab collapses into
+  // one `detailed_merge_status` what GitHub splits across `isDraft`, `reviewDecision` and the check
+  // rollup, and three of its values — approvals outstanding, unresolved discussions, blocked by
+  // another request — have no home in `PrPhase`. Forcing them into `ready` would call something
+  // unmergeable ready, and into `changes-requested` would invent a review nobody left.
+  //
+  // Always null on GitHub, whose phases say everything there is to say (#981).
+  blockedReason: string | null;
 }
 
-export const EMPTY_WORK_ITEM: Readonly<WorkItem> = { phase: "none", pr: null, prUrl: null, issue: null, issueUrl: null, prTitle: null, issueTitle: null };
+export const EMPTY_WORK_ITEM: Readonly<WorkItem> = {
+  phase: "none",
+  pr: null,
+  prUrl: null,
+  issue: null,
+  issueUrl: null,
+  prTitle: null,
+  issueTitle: null,
+  blockedReason: null,
+};
 
 // One line for a surface with room for one: what the work is FOR beats what was done about it, so
 // the issue's title wins when there is one. Null when neither side has a title to show.
@@ -66,7 +83,7 @@ function toIssueNumber(digits: string): number | null {
 // shown next to this cell's PR has to belong to the same repo to be clickable and true.
 export function issueRefFromPrBody(body: string | null | undefined): number | null {
   const found = typeof body === "string" ? CLOSING_KEYWORD.exec(body) : null;
-  return found ? toIssueNumber(found[1]) : null;
+  return found?.[1] === undefined ? null : toIssueNumber(found[1]);
 }
 
 // Whether the body ALREADY states what merging it closes, in either form GitHub honours. Broader
@@ -88,7 +105,7 @@ const BRANCH_ISSUE = /^[a-z][a-z-]*\/([1-9]\d*)-/;
 // somebody else's issue. Named for the doubt so a call site can't forget it.
 export function issueCandidateFromBranch(branch: string | null | undefined): number | null {
   const found = typeof branch === "string" ? BRANCH_ISSUE.exec(branch) : null;
-  return found ? toIssueNumber(found[1]) : null;
+  return found?.[1] === undefined ? null : toIssueNumber(found[1]);
 }
 
 // The prefix this app gives a branch it creates FOR an issue (#1171). Shared because the two
@@ -104,5 +121,5 @@ const ANCHORED_ISSUE = new RegExp(`^${ISSUE_BRANCH_PREFIX}([1-9]\\d*)-`);
 // else's issue the moment the PR merges, which no amount of confirming afterwards undoes.
 export function issueFromAnchoredBranch(branch: string | null | undefined): number | null {
   const found = typeof branch === "string" ? ANCHORED_ISSUE.exec(branch) : null;
-  return found ? toIssueNumber(found[1]) : null;
+  return found?.[1] === undefined ? null : toIssueNumber(found[1]);
 }

package/common/readString.ts

@@ -0,0 +1,28 @@
+// Reading a string out of untrusted JSON — a phone's command params, a transcript line, a `gh`
+// response — without `String()`.
+//
+// `String(value)` answers for ANY input, and that is the problem: an object becomes the literal
+// text "[object Object]" and an array becomes "1,2". Nothing throws, so the bad value travels —
+// as a collection slug that matches nothing, or as a session title on screen. The rule that
+// catches this is @typescript-eslint/no-base-to-string.
+//
+// Reading returns "" (or null) instead, which the callers already handle: they were written
+// against `String(x ?? "")`, so an absent field was always the empty string.
+
+/** The value when it is a string, else `""`. For a field the caller then validates or defaults. */
+export const readString = (value: unknown): string => (typeof value === "string" ? value : "");
+
+/**
+ * A value rendered for a HUMAN — an error message naming what was rejected.
+ *
+ * Here the input is bad by definition, so there is something to say about any of it; `String()` is
+ * wrong only because "[object Object]" tells the reader nothing. JSON keeps the shape visible.
+ */
+export const describeValue = (value: unknown): string => {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return "[unserializable]"; // a circular structure, which JSON.stringify throws on
+  }
+};

package/common/repoEntry.ts

@@ -30,8 +30,9 @@ export interface RepoEntry {
 export function parseRepoEntry(entry: string): RepoEntry | null {
   const segments = entry.trim().split("/");
   if (segments.some((segment) => segment === "")) return null;
-  const declared = segments.length > 1 && HOST_SEGMENT.test(segments[0]);
-  return declared ? { host: segments[0].toLowerCase(), path: segments.slice(1), declared } : { host: GITHUB_HOST, path: segments, declared };
+  const first = segments[0];
+  const host = segments.length > 1 && first !== undefined && HOST_SEGMENT.test(first) ? first : null;
+  return host === null ? { host: GITHUB_HOST, path: segments, declared: false } : { host: host.toLowerCase(), path: segments.slice(1), declared: true };
 }
 
 /** The identity a repository is known by ON ITS OWN HOST — `owner/repo` for GitHub, the group path

package/common/themeVars.ts

@@ -69,7 +69,9 @@ export interface CustomThemeInput {
 
 /** The full variable set for a theme: the base it extends, with its own colours on top.
  *  `builtins` supplies the base sets so this stays pure — the client reads them from the
- *  stylesheet's source of truth, the specs from a fixture. */
+ *  stylesheet's source of truth, the specs from a fixture. PARTIAL because a base can genuinely be
+ *  missing (a stylesheet read that found no block for that id), and the `?? {}` below has always
+ *  handled that — the map only ever needed one key, never all of them. */
 // Every variable present, which is what separates a set we can paint with from one we cannot.
 // A guard rather than a length check on the missing keys: both ask the same question, but only
 // this one hands the answer to the compiler.
@@ -77,7 +79,7 @@ function isCompleteThemeVars(vars: Partial<ThemeVars>): vars is ThemeVars {
   return THEME_VAR_KEYS.every((key) => !!vars[key]);
 }
 
-export function resolveThemeVars(theme: CustomThemeInput, builtins: Record<ThemeId, ThemeVars>): ThemeVars | null {
+export function resolveThemeVars(theme: CustomThemeInput, builtins: Partial<Record<ThemeId, ThemeVars>>): ThemeVars | null {
   const base = theme.extends ? builtins[theme.extends] : null;
   const merged: Partial<ThemeVars> = { ...(base ?? {}), ...theme.colors };
   // No base and an incomplete list is the one case we cannot paint: report it rather than

package/dist/assets/{abnfDiagram-VRR7QNED-RjiYivmv-BCXxUk19.js → abnfDiagram-VRR7QNED-RjiYivmv-Ko4XgYrQ.js}

@@ -1 +1 @@
-import{n as e}from"./chunk-Y2CYZVJY-Bdt8pFDJ-DsF7k-Jl.js";import{f as t}from"./src-Brzfja-q-ch1VcTiG.js";import{_ as n,g as r}from"./mermaid-parser.core-DxEa8E3F-XDB5rg1G.js";import"./chunk-WYO6CB5R-BlzOfotS-D5Vl4QYq.js";import"./chunk-VAUOI2AC-CS9QJ4yz-DW0Tgecw.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CMZRaeqt-pTxGJtb7.js";import{t as s}from"./chunk-JWPE2WC7-BQ3zXr2k-DSd3Ct95.js";var c=r().RailroadAbnf.parser.LangiumParser,l=e(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=e(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=e(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=e(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=e(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=e(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=e(e=>{s(e,a),e.title&&a.setTitle(e.title),e.rules.map(e=>a.addRule(m(e)))},`populateDb`),g={parser:{parse:e(e=>{a.clear(),t.debug(`[ABNF Parser] Starting Langium parse`);let r=c.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new n(r);let i=r.value;t.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),t.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:a}},db:a,renderer:o,styles:i};export{g as diagram};
+import{n as e}from"./chunk-Y2CYZVJY-Bdt8pFDJ-DsF7k-Jl.js";import{f as t}from"./src-Brzfja-q-ch1VcTiG.js";import{_ as n,g as r}from"./mermaid-parser.core-DxEa8E3F-C7Z349Pq.js";import"./chunk-WYO6CB5R-BlzOfotS-CbdIi1Rx.js";import"./chunk-VAUOI2AC-CS9QJ4yz-o20b35Qf.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CMZRaeqt-BwgEBlFh.js";import{t as s}from"./chunk-JWPE2WC7-BQ3zXr2k-DSd3Ct95.js";var c=r().RailroadAbnf.parser.LangiumParser,l=e(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=e(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=e(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=e(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=e(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=e(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=e(e=>{s(e,a),e.title&&a.setTitle(e.title),e.rules.map(e=>a.addRule(m(e)))},`populateDb`),g={parser:{parse:e(e=>{a.clear(),t.debug(`[ABNF Parser] Starting Langium parse`);let r=c.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new n(r);let i=r.value;t.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),t.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:a}},db:a,renderer:o,styles:i};export{g as diagram};

package/dist/assets/architecture-TIHT7OUA-0NsD2xW1-C_A3J6UT.js

@@ -0,0 +1 @@
+import{f as e}from"./mermaid-parser.core-DxEa8E3F-C7Z349Pq.js";export{e as createArchitectureServices};