mulmoterminal 4.18.0 → 4.19.0

package/README.md

@@ -598,7 +598,7 @@ the `claude` / `codex` sessions themselves.
 | `PORT`        | `34567`        | Backend HTTP/WebSocket port (prod: the URL you open). |
 | `CLIENT_PORT` | `6856`         | Vite dev-server port (dev only: the URL you open with `yarn dev`). |
 | `CLAUDE_BIN` | `claude`       | The Claude Code binary to spawn. On Windows a bare name is resolved on `PATH` before it reaches the PTY layer (which matches file names exactly): to the `.exe` when there is one, otherwise to the `.cmd` shim an npm-global install leaves, run through `cmd.exe`. |
-| `CLAUDE_CWD` | current dir    | Working directory each `claude` PTY runs in; determines which project's sessions are listed. Via `npx mulmoterminal@latest` it defaults to the directory you ran the command from (override with `--cwd <dir>`, relative allowed); when the server is run directly it falls back to `~/mulmoclaude`. A value read from `.env` must be an absolute path (`~` is not expanded). |
+| `CLAUDE_CWD` | current dir    | Working directory each `claude` PTY runs in; determines which project's sessions are listed. Via `npx mulmoterminal@latest` it defaults to the directory you ran the command from (override with `--cwd <dir>`, relative allowed); when the server is run directly it falls back to `~/mulmoclaude`. A value read from `.env` must be an absolute path (`~` is not expanded). Running in one of your own project directories does **not** litter it — see the note under the table. |
 | `CLAUDE_PERMISSION_MODE` | `auto` | Permission mode passed to each `claude` spawn. |
 | `MT_TITLE_SOURCE` | `transcript` | Where the cell header's AI title comes from. `transcript` reads the title Claude Code writes into its own transcript — no extra process. `headless` restores the old behaviour of summarizing the recent turns with `claude -p`, which costs a model call but follows a session whose topic drifts (Claude's own title is written once and never revised). |
 | `MT_TITLE_MODEL` | `haiku` | Model used for the cell header's AI title. Only read when `MT_TITLE_SOURCE=headless`. Accepts a `--model` alias or a full model id. |
@@ -613,11 +613,30 @@ the `claude` / `codex` sessions themselves.
 | `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. |
+| `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`), and it is what decides where MulmoTerminal's own runtime state goes — see the note under the table. Set it to the same value MulmoClaude uses. |
 | `MULMOTERMINAL_NO_SKILL_INSTALL` | unset | Set to any value to skip installing the bundled skills (`mulmoterminal-config` and the `-dirs` / `-theme` / `-header` / `-keys` / `-model` / `-notify` / `-bug-report` / `-decisions` family) into `~/.claude/skills/` and the Codex skills root on startup. |
 | `GEMINI_IMAGE_MODEL` | `gemini-3.1-flash-image-preview` | Model used for image generation (needs `GEMINI_API_KEY`). The default is a **preview** model Google schedules for retirement around mid-2026, so pin a stable one here (e.g. `gemini-2.5-flash-image`) rather than waiting for a code change. |
 | `WAIT_REAP_GRACE_MS` | `1800000` | How long a **waiting** background session is kept before it's auto-reaped (`0` or negative = never). |
 
+**Where MulmoTerminal's own runtime state goes.** The launcher defaults the workspace to the
+directory you ran it from, which is usually one of your own projects — so the state MulmoTerminal
+keeps for itself does not go there. The scheduler's execution state and logs
+(`config/scheduler/state.json`, `data/scheduler/logs/`) and the notifier's
+(`data/notifier/`) live under `~/.mulmoterminal/workspaces/<workspace-key>/` instead, one
+directory per workspace — `<workspace-key>` is the workspace's path folded to a safe name plus a
+short digest of it, so two workspaces never share one. What you made stays in the workspace either way: collections, feeds, and the
+scheduled tasks you write in `config/scheduler/tasks.json`.
+
+The one exception is the **managed** workspace named by `MULMOCLAUDE_WORKSPACE_PATH`
+(`~/mulmoclaude` by default), where that state stays in the workspace — MulmoClaude reads the
+same files there, and splitting them would give the two apps different answers.
+
+If you ran an older version in a project directory, what it left behind is inert and nothing
+recreates it — but delete the generated files, **not** the whole directory:
+`config/scheduler/state.json`, `data/scheduler/`, `data/notifier/`. Leave
+`config/scheduler/tasks.json` alone; that one is yours, it is still read from the workspace, and
+deleting it deletes your scheduled tasks.
+
 The update-check opt-outs (`MULMOTERMINAL_NO_UPDATE_CHECK`, `NO_UPDATE_NOTIFIER`) are
 covered in [Install & run](#install--run).
 
@@ -655,6 +674,8 @@ The Settings modal (the gear button) persists per-user UI choices to `~/.mulmote
 | `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). 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. |
+| `feedRefreshEnabled` | `false` stops the hourly **collection/feed refresh** (one scheduled task per root — the workspace and every saved project directory). **On by default**; only an explicit `false` turns it off, so an existing config keeps the behaviour it has. Takes effect at the next server start — the scheduler registers once at boot. Feeds still refresh on demand. Checkbox in Settings → **Sessions**. |
+| `calendarSyncEnabled` | `false` stops the hourly **Google Calendar sync** (pulls changed events into collections that declare a calendar). Same default and the same restart rule as `feedRefreshEnabled`; calendar collections still sync on demand. Checkbox in the same Settings section. With both off and `worklogEnabled` off, no **built-in** task is registered. Your own tasks in `config/scheduler/tasks.json` are unaffected — these switches do not touch them, and an enabled one still registers and still runs the tick loop. Only when there is no enabled user task either does the scheduler stop writing its state file and run logs. |
 | `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). |
@@ -855,7 +876,7 @@ Settings → Directory settings names both files and lists which keys the local
 | 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, 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. |
+| `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, or with the small glyph a chat started from a **collection** wears beside its status dot — that one is the collection's own `icon`, and it says which collection the cell was opened for while this one says which directory it runs in. **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`.** 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. |
@@ -1434,6 +1455,16 @@ prompt and spawns a fresh agent session for it — the **Launch with Claude / Co
 decides which agent (and whether the seed auto-runs or drops in as an editable draft).
 Favorited collections get their own toolbar buttons.
 
+That session is an ordinary **grid cell**, and starting it no longer takes the screen to the
+grid: while the collection is open, the grid **teleports that cell into a pane below it**, so
+the same terminal is driven from whichever view you have open — no hand-off, no reconnect, and
+nothing to move back. Several chats under one collection become tabs, each with the grid's own
+attention dot and a line of what the shown one is doing; the **Collections** button carries how
+many are running behind it. Which collection a chat belongs to survives a reload, and a chat
+whose cell is gone drops out rather than sitting over an empty pane. A button in the tab strip
+moves the pane **under the collection or beside it** — wide and short for a list you are scanning,
+narrow and tall for one record you are discussing — and each position keeps its own size.
+
 ---
 
 ## More features
@@ -2117,6 +2148,8 @@ src/
     GitBranchChip.vue, ModelContextBadge.vue header chips / badges
     PrsOverlay.vue                           cross-repo PRs & Issues
     Wiki*View.vue, Collections*.vue, AccountingOverlay.vue   workspace views
+    CollectionChatPane.vue                   the pane under an open collection: tabs, and the
+                                             receptacle the grid teleports a chat's cell into
     TimelineOverlay.vue, ToolsPane.vue, NotificationBell.vue, RemoteHostControl.vue
     SettingsModal.vue                        settings — the dialog shell + section order
     settings/                                one file per settings section (theme, sounds,

package/common/sessionCollection.ts

@@ -0,0 +1,37 @@
+// Which collection a session was started from (#2020), as BOTH sides agree it should look.
+//
+// The server records it at spawn and answers it on `/api/session/:id`; the grid draws it beside
+// the cell's status dot. In common/ because that response shape is decided by both — the wire type
+// mirrored into `server/` and `src/` is exactly the drift this directory exists to prevent.
+//
+// The DISPLAY fields travel with the slug rather than being looked up per render, and that is a
+// snapshot on purpose: resolving `slug -> icon` needs a collection discovery pass, and
+// `/api/session/:id` is polled once per cell. A collection that later changes its icon leaves the
+// sessions started before it wearing the old glyph, which is the right answer for a historical
+// record anyway.
+import { isRecord } from "./isRecord";
+
+export interface SessionCollection {
+  slug: string;
+  /** The schema's `icon`: a Material Symbols ligature name OR a single emoji. Never an image —
+   *  that is the DIRECTORY's icon, a different question the cell answers separately. Draw it with
+   *  `IconGlyph` from `@mulmoclaude/core/plugin-vue`, which is the one renderer that classifies
+   *  the two and contains a value it cannot resolve. May be "" when the schema names none. */
+  icon: string;
+  /** What the collection calls itself, falling back to its slug. Never empty, and never absent:
+   *  the producer normalizes it (`resolveSpawnCollection`) because the package's own summary type
+   *  promises a string and hands back `undefined` for a schema that names no title. */
+  title: string;
+}
+
+/** Read a session's collection off an untrusted body, or null when there is none / it is unusable.
+ *
+ *  A missing key and a malformed one answer the same way on purpose: the field is decoration, and
+ *  the cell that renders nothing is correct in both cases. */
+export function asSessionCollection(value: unknown): SessionCollection | null {
+  if (!isRecord(value)) return null;
+  const { slug, icon, title } = value;
+  if (typeof slug !== "string" || slug.length === 0) return null;
+  if (typeof icon !== "string" || typeof title !== "string") return null;
+  return { slug, icon, title };
+}