chore: version packages

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -1,5 +1,52 @@
 # aicodeman
 
+## 1.2.2
+
+### Patch Changes
+
+- Centralize terminal history/scrollback/buffer retention limits into config (PR #137, COD-80).
+
+  New `src/config/terminal-history.ts` is now the single source of truth for the terminal scrollback lines, tmux `history-limit`, and server PTY buffer byte caps that were previously scattered as hardcoded literals across `buffer-limits.ts`, `tmux-manager.ts`, and `session.ts`. Each value is overridable (env var or the settings object) and bounds-clamped via a pure `resolveTerminalHistoryConfig()`.
+
+  This change is behavior-neutral: the defaults intentionally match the prior hardcoded values (tmux history-limit 50,000; terminal scrollback 50,000; PTY buffer max 2 MB; trim 1.5 MB) and the existing `CODEMAN_MAX_TERMINAL_BUFFER` / `CODEMAN_TRIM_TERMINAL_TO` env overrides are preserved, so runtime behavior is unchanged on its own. It is the mechanism half of a stacked change; a follow-up raises the defaults.
+  - `buffer-limits.ts` sources `MAX_TERMINAL_BUFFER_SIZE` / `TRIM_TERMINAL_TO` from the resolver.
+  - `tmux-manager.ts` uses `DEFAULT_TMUX_HISTORY_LIMIT` in place of the hardcoded `history-limit 50000`, gains `setHistoryLimit()` (mux-interface + impl) so a settings change applies to live sessions, and re-applies the limit on `respawnPane` so it survives a respawn.
+  - `session.ts` threads a per-session `tmuxHistoryLimit` into the tmux spawn calls; `server.ts` exposes `getTerminalHistoryConfig()` on the route ctx and `system-routes.ts` applies a changed `tmuxHistoryLimit` to live sessions immediately.
+  - `schemas.ts` adds four optional, bounds-clamped settings keys (`terminalScrollbackLines`, `tmuxHistoryLimit`, `terminalBufferMaxBytes`, `terminalBufferTrimBytes`) with a `trim <= max` cross-field check.
+  - New tests: `test/terminal-history.test.ts` (resolver defaults / clamping / trim<=max / non-number fallback) and `test/terminal-history-schema.test.ts` (settings-schema validation).
+
+## 1.2.1
+
+### Patch Changes
+
+- Fix local echo on iOS Safari when switching into a tab whose session already has output. The on-screen-keyboard "heal" (refit + scroll-to-bottom + overlay re-render + one-shot resize) only ran on a keyboard visibility transition, so switching into a tab while the keyboard was already up never triggered it — leaving the local-echo overlay rendering against stale, off-bottom terminal state. Typed characters were invisible (or mispositioned at the cursor row, far below the actual `❯` prompt) until the user manually hid and re-showed the keyboard. `selectSession` now replicates that heal when the keyboard is already visible, so local echo paints correctly on the first keystroke after a keyboard-up tab switch.
+
+## 1.2.0
+
+### Minor Changes
+
+- Merge four feature PRs and harden them for release.
+
+  **Gemini run mode (PR #134, COD-36)** — a third external-CLI backend alongside Codex and OpenCode (`SessionMode` adds `'gemini'`). New `gemini-cli-resolver.ts`, `buildGeminiCommand()` (`--skip-trust`, `--approval-mode {default|auto_edit|yolo|plan}` defaulting to `yolo`, `--model`, `--resume`), `setGeminiEnvVars()` (socket-scoped `tmux setenv` of `GEMINI_*`/`GOOGLE_*` auth incl. Vertex AI), `GET /api/gemini/status` with an install hint (`npm install -g @google/gemini-cli`), run-mode dropdown + welcome "Run Gemini" button + "Run GM" label, `GeminiConfigSchema`, and `GEMINI_*`/`GOOGLE_*` added to the env-override allowlist. Requires tmux (no PTY fallback), like Codex.
+
+  **Cross-session search (PR #133, COD-113)** — `GET /api/search?q=&types=&limit=` federates an in-memory search across session metadata, run-summary events, and attachment-history file entries (substring match, hard caps, no FS reads); history-panel search box in the frontend.
+
+  **Away digest (PR #136, COD-41)** — `GET /api/away-digest` aggregates "what happened while you were away" (lifecycle log, run summaries, live sessions, daily token stats, recent subagents) into categorized sections behind a header-button modal (hidden on phones).
+
+  **Ralph todo-config (PR #135, COD-79)** — per-session `maxTodos` and `todoExpirationMinutes` via `POST /api/sessions/:id/ralph-config`; now persisted in `RalphTrackerState` and read back into the Session Options modal (mirrors `maxIterations` round-trip).
+
+  **Review fixes applied on merge:**
+  - Gemini: fixed two `{success,data}` envelope bugs in `runGemini()` (status check and new-session selection) that made the Run-Gemini button non-functional; fixed `setGeminiEnvVars()` to use the socket-scoped tmux command so Google-auth env injection actually reaches the session.
+  - Gemini parity: tab-mode badge, kill-dialog label, `codeman doctor` registry entry, `isGeminiAvailable` barrel export, `COLORTERM=truecolor`, and alt-screen/scrollback stripping (Ink TUI, like Codex/Claude).
+  - Restored four envelope-shape test assertions weakened during the Gemini PR; added a `runGemini()` regression test covering the envelope path.
+  - Ralph todo-config values now persist across restart and read back correctly instead of always reverting to defaults.
+
+## 1.1.17
+
+### Patch Changes
+
+- Fix the connection indicator flashing "Sending 1B…" on every keystroke. The reliable input-delivery layer (1.1.16) marks each keystroke as briefly pending until its ACK arrives a few milliseconds later, which made the indicator flash on every character while typing on a healthy connection. The indicator is now hidden whenever the connection is healthy and only appears for an actual problem (reconnecting/offline), where it still shows the queued byte count so you know buffered input will be sent.
+
 ## 1.1.16
 
 ### Patch Changes

CLAUDE.md

@@ -56,13 +56,13 @@ When user says "COM":
 
 CI runs `npm run check:lockfile` on every push/PR, so lockfile drift fails the build even if the `version-packages` script is bypassed.
 
-**Version**: 1.1.16 (must match `package.json`)
+**Version**: 1.2.2 (must match `package.json`)
 
 ## Project Overview
 
 Codeman is a Claude Code session manager with web interface and autonomous Ralph Loop. Spawns Claude CLI via PTY, streams via SSE, supports respawn cycling for 24+ hour autonomous runs.
 
-**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, and Codex (OpenAI) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex'`).
+**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, Codex (OpenAI), and Gemini (Google) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini'`).
 
 **TypeScript Strictness** (see `tsconfig.json`): `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `allowUnreachableCode: false`, `allowUnusedLabels: false`.
 
@@ -100,12 +100,12 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **ESM only** — Never `require()`, use `await import()`. `tsx` masks CJS/ESM issues in dev but production breaks
 - **Package ≠ product name** — npm: `aicodeman`, product: **Codeman**. Release renames tags accordingly. Both `aicodeman` and `codeman` bin aliases are installed (`package.json` `bin`)
 - **Global regex `lastIndex`** — Shared `g`-flag patterns in loops must reset `lastIndex = 0` first, or use the `execPattern()` helper in `utils/regex-patterns.ts` (resets automatically)
-- **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` env vars** — Set via `POST /api/sessions { envOverrides }`, stored on `Session._envOverrides`, exported by `tmux-manager.buildEnvExports()` at spawn time, persisted in `SessionState.envOverrides`. **Do NOT** write these to `<case>/.claude/settings.local.json` — that's the old path and creates UI/disk drift
+- **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` env vars** — Set via `POST /api/sessions { envOverrides }`, stored on `Session._envOverrides`, exported by `tmux-manager.buildEnvExports()` at spawn time, persisted in `SessionState.envOverrides`. **Do NOT** write these to `<case>/.claude/settings.local.json` — that's the old path and creates UI/disk drift. (`GOOGLE_*` is the deliberately-broad Vertex-AI namespace for Gemini — see Multi-CLI prefix discipline.)
 - **Effort is NOT an env var** — never carry effort as `CLAUDE_CODE_EFFORT_LEVEL`: the env var hard-locks effort and blocks in-session `/effort` switching (incl. ultracode). It flows as the dedicated `effort` payload field → `Session._effort` → `claude --effort <level>` for regular levels incl. `max` (the settings `effortLevel` key is `enum(["low","medium","high","xhigh"]).catch(undefined)` — `max` gets SILENTLY dropped there), or `claude --settings '{"ultracode":true}'` for ultracode (rejected by `--effort`). Both are soft defaults the user can override anytime. Legacy env-var entries are auto-migrated by the Session constructor and unset from tmux sessions in `applyEnvOverrides()`. See `buildEffortCliArgs()` in `session-cli-builder.ts`, tests in `test/effort-injection.test.ts`
 - **Model choice flows via `settings.local.json`, NOT `--model` or env** — the App Settings **Claude Model** picker (`claudeModel` in `settings.json`) is read by `session-ui.js` at session create (wins over the legacy 1M-Opus toggles `opusContext1m`/`opusContext1mEnabled`), sent as the `modelOverride` payload field, and `updateCaseModel()` (`hooks-config.ts`) writes/deletes the `model` key in `<case>/.claude/settings.local.json`. This is the intended exception to the envOverrides rule above: model legitimately lives in `settings.local.json` (a soft default — in-session `/model` still works); env vars do not
-- **Multi-CLI prefix discipline** — Codeman supports Claude Code, OpenCode, and Codex (`claude-cli-resolver.ts` / `opencode-cli-resolver.ts` / `codex-cli-resolver.ts`); env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*`) and the allowlist in `schemas.ts` enforces this. When adding settings, decide which CLI(s) it applies to and gate the env export accordingly — don't blindly forward all prefixes. See `docs/opencode-integration.md` for the OpenCode resolver design
+- **Multi-CLI prefix discipline** — Codeman supports Claude Code, OpenCode, Codex, and Gemini (`claude-cli-resolver.ts` / `opencode-cli-resolver.ts` / `codex-cli-resolver.ts` / `gemini-cli-resolver.ts`); env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*`) and the `ALLOWED_ENV_PREFIXES` allowlist in `schemas.ts` enforces this. Gemini additionally allowlists the **broad `GOOGLE_*`** namespace (intentional — Vertex AI auth uses `GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI` etc.; it's the loosest allowlist entry, affecting only the user's own spawned CLI). When adding settings, decide which CLI(s) it applies to and gate the env export accordingly — don't blindly forward all prefixes. See `docs/opencode-integration.md` for the resolver design pattern
 - **Zod `.optional()` rejects `null`** — accepts `undefined` only. When the frontend builds a request body with `JSON.stringify`, an explicit `null` field is preserved on the wire and fails validation with `INVALID_INPUT`. Convert `null` → `undefined` before stringifying (e.g. `field: value ?? undefined`), or declare the schema `.nullish()`. Real bugs caused: 0.6.4 (`durationMinutes` for ∞ respawn), and the same shape pattern hit `opusContext1mEnabled` in 0.6.3
-- **`xterm-zerolag-input` is single-source — edit the package, then rebuild the bundle** — the local-echo overlay source lives ONLY in `packages/xterm-zerolag-input/src/` (`zerolag-input-addon.ts`; also published to npm as a standalone library — see README "Published Packages"). It is bundled (esbuild → IIFE, with appended `window.LocalEchoOverlay` aliases) into the **gitignored** `src/web/public/vendor/xterm-zerolag-input.js` by `scripts/postinstall.js` (for dev/`tsx`) and into `dist/.../vendor/` by `scripts/build.mjs:50` (for prod). `app.js` only **consumes** it via `new LocalEchoOverlay(terminal)` — there is NO inline copy to keep in sync. So: change behavior in the package source, then re-run the bundle step (`npm install` reruns postinstall; `npm run build` for prod); **never hand-edit `app.js` for overlay behavior or commit the gitignored vendor bundle**. A public-API break in the package still warrants a separate `xterm-zerolag-input` version bump in the changeset. Always test on mobile after touching it. See `docs/local-echo-overlay-plan.md`.
+- **`xterm-zerolag-input` is single-source — edit the package, then rebuild the bundle** — the local-echo overlay source lives ONLY in `packages/xterm-zerolag-input/src/` (`zerolag-input-addon.ts`; also published to npm as a standalone library — see README "Published Packages"). It is bundled (esbuild → IIFE, with appended `window.LocalEchoOverlay` aliases) into the **gitignored** `src/web/public/vendor/xterm-zerolag-input.js` by `scripts/postinstall.js` (for dev/`tsx`) and into `dist/.../vendor/` by `scripts/build.mjs` (the `xterm-zerolag-input` esbuild step, for prod). `app.js` only **consumes** it via `new LocalEchoOverlay(terminal)` — there is NO inline copy to keep in sync. So: change behavior in the package source, then re-run the bundle step (`npm install` reruns postinstall; `npm run build` for prod); **never hand-edit `app.js` for overlay behavior or commit the gitignored vendor bundle**. A public-API break in the package still warrants a separate `xterm-zerolag-input` version bump in the changeset. Always test on mobile after touching it. See `docs/local-echo-overlay-plan.md`.
 - **Default bind is loopback-only; non-loopback without a password starts but warns** — since COD-29 (PR #107) the web server defaults to `--host 127.0.0.1` (was `0.0.0.0`). As of **0.9.0** binding a non-loopback host (`--host`/`-H`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` **no longer refuses to start — it starts and prints a loud warning** listing the fixes (set `CODEMAN_PASSWORD`, bind loopback + tunnel/`tailscale serve`, or `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` to acknowledge → terser note). Host classification is `isLoopbackBindHost()` in `network-auth-policy.ts`; the warn-vs-start logic is in `server.ts` `start()`; flags wired in `cli.ts`. ⚠️ Operational note: the production systemd unit runs `node dist/index.js web --https` with no `--host`, so it binds **localhost only** — reach it remotely via `tailscale serve`/tunnel to `127.0.0.1`, or add `Environment=CODEMAN_HOST=0.0.0.0` + `Environment=CODEMAN_PASSWORD=…` to `~/.config/systemd/user/codeman-web.service`. A loopback bind is reachable through a same-host tunnel (cloudflared/tailscale → `127.0.0.1`) but NOT by a browser hitting the box's LAN IP. Auth user defaults to `admin`. **Full model: `docs/security-architecture.md`.**
 - **Instance isolation / multi-instance attach danger** — data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts` (`getDataDir()`/`dataPath()`/`DEFAULT_TMUX_SOCKET`). ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions** (`tmux -L codeman attach-session …`), resizing/mutating them — `$HOME` isolation is NOT enough (tmux is system-global). To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes BOTH dir+socket: `~/.codeman-<name>` + `-L codeman-<name>`), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually. **`CODEMAN_INSTANCE` defaults to empty = the production layout (`~/.codeman`, `-L codeman`, port 3000)**, so this branch is safe to ship to master without disturbing existing installs. To run THIS beta alongside prod, launch with `scripts/run-beta.sh` (`CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`) — it never collides with prod's data dir/socket/port. Any new `~/.codeman/...` path MUST go through `dataPath()`, never `join(homedir(), '.codeman', …)`.
 - **Headless screenshots: `deviceScaleFactor` MUST be 1, and write unique filenames** — `scripts/capture-real-overview.mjs` (drives a live session in headless Chromium → overview PNG). Two traps, both observed 2026-06-14: **(1) DSF=2 doubles the console font.** xterm's WebGL renderer draws terminal glyphs at ~2× their nominal size under `deviceScaleFactor: 2`, while STILL reporting nominal cell dims (`terminal.cols`/`_renderService.dimensions.css.cell` say 8px/187cols — they lie), so it's invisible to any internal measurement and only the pixels reveal it. The HTML chrome (header/toolbar) is unaffected → ONLY the console font looks comically large. Default to **DSF=1** (script does); the image is 1× res but the font is true-to-browser. **(2) Stable filenames → stale renders.** Overwriting a fixed path (`claude-overview.png`) in place leaves OS image viewers (eog/feh) — and any HTTP client behind a long/`immutable` cache — showing the OLD render; the user reads it as "the fix didn't work". The script now mints a timestamped `claude-overview-<ts>.png` per run. ⚠️ This was a LOCAL image-viewer cache, NOT a Codeman serving bug: `file-routes` previews send `Cache-Control: no-cache` and `/api/screenshots/:name` sends none. The one real Codeman-side footgun: `server.ts` serves non-content-hashed static assets `public, max-age=31536000, immutable`, and `cacheBustAssets()` only rewrites `.js`/`.css` refs — a stable-named **image** referenced from public/ would go stale on overwrite. Reflect the per-device UI to match a real device when capturing: seed `localStorage` `codeman:skin`, `codeman-font-size`, and the desktop `codeman-app-settings` blob (the plan-usage chip is a per-device display key deleted from the server payload — a fresh browser hides it unless seeded; close side panels for a full-width terminal).
@@ -131,9 +131,9 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **Infra** | `src/hooks-config.ts`, `src/push-store.ts`, `src/tunnel-manager.ts`, `src/image-watcher.ts`, `src/file-stream-manager.ts` | |
 | **Attachments** | `src/attachment-registry.ts`, `src/attachment-magic.ts`, `src/session-attachment-history.ts`, `src/document-preview-cache.ts`, `src/document-thumbnailer.ts`, `src/document-conversion-limiter.ts`, `src/config/attachment-guard.ts` | See Key Patterns |
 | **Plan** | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/` (`claude-md.ts` + `case-template.md`, the CLAUDE.md scaffold generated into new cases) | |
-| **Web** | `src/web/server.ts` ★, `src/web/sse-events.ts`, `src/web/routes/*.ts` (16 route modules + barrel; `session-routes.ts` ★), `src/web/route-helpers.ts`, `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts`, `src/web/self-update.ts`, `src/web/plan-usage-latest.ts` | |
+| **Web** | `src/web/server.ts` ★, `src/web/sse-events.ts`, `src/web/routes/*.ts` (17 route modules + barrel; `session-routes.ts` ★), `src/web/route-helpers.ts`, `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts`, `src/web/self-update.ts`, `src/web/plan-usage-latest.ts` | |
 | **Frontend** | `src/web/public/app.js` (~4K lines, core) + 6 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`, `sanitize-html.js` — DOMPurify mXSS allowlist, COD-56) + 8 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `ultracode-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 6 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `ultracode-windows.js`, `input-cjk.js`, `image-input.js`) + `sw.js` | `ultracode-windows.js` = floating run windows w/ tab connector lines (additional to the dock panel) |
-| **Types** | `src/types/index.ts` (barrel) → 16 domain files (incl. `workflow-run.ts`); also `src/types.ts` root re-export | See `@fileoverview` in index.ts |
+| **Types** | `src/types/index.ts` (barrel) → 17 domain files (incl. `workflow-run.ts`, `search.ts`); also `src/types.ts` root re-export | See `@fileoverview` in index.ts |
 
 ★ = Large, central file (>50KB) — read its `@fileoverview` first. All files have `@fileoverview` JSDoc — read that before diving in. Discovery aid: `grep -l '@fileoverview' src/web/routes/*.ts` lists all route modules; same grep works for `src/types/`, `src/web/public/*.js`.
 
@@ -152,7 +152,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 ### Key Patterns
 
-**Input**: `session.writeViaMux()` for programmatic input — tmux `send-keys -l` (literal) + `send-keys Enter`. Single-line only.
+**Input**: `session.writeViaMux()` for programmatic/curl input — tmux `send-keys -l` (literal) + `send-keys Enter`. Single-line only (fire-and-once). Interactive **browser** input goes through a durable **exactly-once** layer: each frame carries a stable `clientId` + monotonic per-session `seq`, persisted to localStorage until the server ACKs (`{t:'ia',seq}` over WS, or HTTP 2xx), so a dropped link/reconnect can't lose or double-deliver a prompt.
 
 **Idle detection**: Multi-layer (completion message → AI check → output silence → token stability). See `docs/respawn-state-machine.md`.
 
@@ -162,7 +162,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Orchestrator**: State machine that turns a user goal into a phased plan and drives it to completion: `idle → planning → approval → executing → verifying → (replanning) → completed/failed`. `OrchestratorLoop` (engine) delegates plan generation to `orchestrator-planner` and per-phase verification gates to `orchestrator-verifier`, executing phases via team agents/`task-queue`. State persists under the `orchestrator` key in `state.json`. Distinct from Ralph (single-session autonomous loop) — orchestrator coordinates multi-phase, multi-agent execution. See `docs/orchestrator-loop-architecture.md`.
 
-**External CLI modes (OpenCode, Codex)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior — Ralph tracker, BashToolParser, token/CLI-info parsing, and ❯-prompt readiness detection are all skipped (these CLIs render their own TUIs; readiness = output stabilization instead). Both modes **require tmux — no direct PTY fallback** — because secrets are injected via `tmux setenv`, never on the spawn command line: OpenCode gets `OPENCODE_CONFIG_CONTENT` etc., Codex gets `OPENAI_API_KEY`/`CODEX_API_KEY`/`CODEX_HOME` (`setCodexEnvVars` in `tmux-manager.ts`). Codex specifics: command built by `buildCodexCommand()` (`--model`, `resume <id>`, `--dangerously-bypass-approvals-and-sandbox` from the `codexConfig` payload / `codexDangerouslyBypassApprovals` app setting; `renderMode` is schema-coerced to `'hybrid'`, the only supported mode); tmux exports `COLORTERM=truecolor` + unsets `NO_COLOR` (other modes unset `COLORTERM`); availability via `GET /api/codex/status` — session/quick-start routes fail with `OPERATION_FAILED` and an install hint (`npm install -g @openai/codex`) when the binary is missing. Frontend: run-mode dropdown → `runCodex()` in `session-ui.js` ("Run CX" label), App Settings → Codex CLI tab; Respawn/Ralph options are Claude-only, so session options open on the Summary tab for external CLI sessions. Tests: `test/run-mode-ui.test.ts` (vm-sandbox harness, no real DOM).
+**External CLI modes (OpenCode, Codex, Gemini)**: `isExternalCliMode()` in `session.ts` (`mode === 'opencode' || 'codex' || 'gemini'`) gates Claude-specific behavior — Ralph tracker, BashToolParser, token/CLI-info parsing, and ❯-prompt readiness detection are all skipped (these CLIs render their own TUIs; readiness = output stabilization instead). All three modes **require tmux — no direct PTY fallback** — because secrets are injected via `tmux setenv` (socket-scoped `${this.tmux()} setenv`, never on the spawn command line): OpenCode gets `OPENCODE_CONFIG_CONTENT` etc., Codex gets `OPENAI_API_KEY`/`CODEX_API_KEY`/`CODEX_HOME` (`setCodexEnvVars`), Gemini gets `GEMINI_API_KEY`/`GOOGLE_API_KEY`/`GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI` etc. (`setGeminiEnvVars`, all in `tmux-manager.ts`). Codex specifics: command built by `buildCodexCommand()` (`--model`, `resume <id>`, `--dangerously-bypass-approvals-and-sandbox` from the `codexConfig` payload / `codexDangerouslyBypassApprovals` app setting; `renderMode` is schema-coerced to `'hybrid'`, the only supported mode). Gemini specifics: command built by `buildGeminiCommand()` (`--skip-trust` always, `--approval-mode <default|auto_edit|yolo|plan>` defaulting to `yolo` for parity with Claude's `--dangerously-skip-permissions`, `--model`, `--resume` from the `geminiConfig` payload); availability via `GET /api/gemini/status` — session/quick-start routes fail with `OPERATION_FAILED` + install hint (`npm install -g @google/gemini-cli`) when missing. Codex AND Gemini export `COLORTERM=truecolor` + unset `NO_COLOR` (other modes unset `COLORTERM`); Gemini joins `isAltScreenStripMode()` (Codex/Claude/Gemini are Ink TUIs that repaint inline → strip alt-screen/`3J` so scrollback survives). Codex availability via `GET /api/codex/status`. Frontend: run-mode dropdown → `runCodex()`/`runGemini()` in `session-ui.js` ("Run CX"/"Run GM" labels), App Settings → Codex CLI tab; Respawn/Ralph options are Claude-only, so session options open on the Summary tab for external CLI sessions. ⚠️ `run*()` MUST unwrap the `{success,data}` envelope (`(await res.json()).data.available` / `data.data.sessionId`) — reading the raw shape silently breaks the run. Tests: `test/run-mode-ui.test.ts` + `test/gemini-mode.test.ts` (vm-sandbox harness, no real DOM).
 
 **Hook events**: Claude Code hooks trigger via `/api/hook-event`. Key events: `permission_prompt`, `elicitation_dialog`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`. See `src/hooks-config.ts`; upstream hook semantics mirrored in `docs/claude-code-hooks-reference.md`.
 
@@ -174,7 +174,13 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Attachments** (live external document references; COD-37/#119 core, COD-38/#120 previews, COD-39/#121 history): all wiring in `file-routes.ts`. **Registry** (`attachment-registry.ts`): an **in-memory** map of a stable `attachmentId` → an absolute, `realpath`-resolved, extension-allowlisted file path, so browser requests (`GET /api/sessions/:id/attachments/:attachmentId/raw`) never carry arbitrary absolute paths; `POST /api/sessions/:id/attachments` registers one. **Magic links** (`attachment-magic.ts`): parses `codeman://attach?...` out of terminal output — ⚠️ this scanner is prompt-injectable, so the scan path is **force-confined to the session workspace** (a hostile prompt could otherwise make it read arbitrary host files over SSE); emits the `attachment:detected` SSE event. Security gate is an extension **allowlist** (`isSupportedAttachmentExtension`, in the registry/magic modules), not a blocklist; a separate path layer (`config/attachment-guard.ts`) confines reads to the workspace (`attachmentConfineToWorkspace`) and blocks sensitive trees (`/root`, `/etc`). **Previews + thumbnails** (COD-38): `:attachmentId/preview` + `:attachmentId/thumbnail` (and the workspace-file equivalents `file-preview`/`file-thumbnail`) render Office docs/PDFs via external converters (`pdftoppm` / LibreOffice `soffice` / Word-COM `powershell`); `document-preview-cache.ts` is a shared disk cache (de-dups *identical* in-flight inputs), `document-thumbnailer.ts` does best-effort first-page images, and `document-conversion-limiter.ts` is a **global converter-spawn concurrency cap** (`runWithConversionLimit`) — without it, N distinct large docs detected at once fork N multi-minute converter processes = a localhost fork-bomb-shaped resource-exhaustion vector. **History drawer** (COD-39): `session-attachment-history.ts` tracks the last `ATTACHMENT_HISTORY_LIMIT` (100) attachments per session (`Session._attachmentHistory`, persisted via `SessionState.attachmentHistory`, replayed so externals re-register on reconnect); `GET /api/sessions/:id/attachments` is the list endpoint. ⚠️ The history drawer's launcher button is desktop-only — hidden on phones (regression-guarded; see `mobile-header-buttons-policy` test). Session-local files keep using the existing workspace-scoped `file-routes` paths; the registry is only for explicit live externals.
 
-**Ultracode / Workflow-run visualization** (opt-in `showUltracodeAgents`, default OFF; released 1.1.2): the Workflow tool ("ultracode") writes a run-state JSON per run at `~/.claude/projects/<projHash>/<sessionUuid>/workflows/wf_*.json`. `workflow-run-watcher.ts` (STANDALONE — deliberately never imports/touches `subagent-watcher.ts`; disjoint directory tree, separate singleton) globs that tree via periodic poll + per-run chokidar watcher with per-file mtime skip, and broadcasts SSE `workflow:run_discovered`/`run_updated`/`run_removed`. The watcher is only started when the setting is on (`server.ts` gates on `showUltracodeAgents`). Served via `GET /api/workflows` (optional `?minutes=` filter) and `GET /api/workflows/:runId`. Frontend `ultracode-panel.js` renders a docked master-detail view (LEFT: runs + phases; RIGHT: per-agent tokens + tool-calls; click an agent card → its live transcript via client-side `agentId` join). **Additionally**, `ultracode-windows.js` auto-pops a draggable **floating window per active run** (gated on the same `showUltracodeAgents` setting), connected by a glowing line to the originating session tab (resolved by `session.claudeSessionId === run.sessionUuid`) — same line idiom as subagent windows, drawn into the shared `#connectionLines` SVG from the tail of `_updateConnectionLinesImmediate`. The window auto-closes ~8s after its run finishes; explicit dismissals are remembered. Types: `src/types/workflow-run.ts`. Config: `src/config/workflow-config.ts`.
+**Ultracode / Workflow-run visualization** (opt-in `showUltracodeAgents`, default OFF; released 1.1.2): the Workflow tool ("ultracode") writes a run-state JSON per run at `~/.claude/projects/<projHash>/<sessionUuid>/workflows/wf_*.json`. `workflow-run-watcher.ts` (STANDALONE — deliberately never imports/touches `subagent-watcher.ts`; disjoint directory tree, separate singleton) globs that tree via periodic poll + per-run chokidar watcher with per-file mtime skip, and broadcasts SSE `workflow:run_discovered`/`run_updated`/`run_removed`. The watcher is started when **either** `showUltracodeAgents` **or** `ultracodeFloatingWindows` is on (`server.ts` `_updateWorkflowWatcher` returns `(showUltracodeAgents ?? false) || (ultracodeFloatingWindows ?? false)`). Served via `GET /api/workflows` (optional `?minutes=` filter) and `GET /api/workflows/:runId`. Frontend `ultracode-panel.js` renders a docked master-detail view (LEFT: runs + phases; RIGHT: per-agent tokens + tool-calls; click an agent card → its live transcript via client-side `agentId` join). **Additionally**, `ultracode-windows.js` auto-pops a draggable **floating window per active run** (gated on a **DEDICATED** `ultracodeFloatingWindows` toggle, default OFF — independent of the dock panel's `showUltracodeAgents`; see `_ultracodeFloatingEnabled()`), connected by a glowing line to the originating session tab (resolved by `session.claudeSessionId === run.sessionUuid`) — same line idiom as subagent windows, drawn into the shared `#connectionLines` SVG from the tail of `_updateConnectionLinesImmediate`. The window auto-closes ~8s after its run finishes; explicit dismissals are remembered. Clicking an agent card opens an **in-page** connected transcript window (not a browser popup); both run and transcript windows minimize **into** the originating session tab as a merged `ULTRA` badge (🧬 runs / 📄 transcripts) with a restore/dismiss dropdown — minimized runs are skipped by auto-pop. Gesture beta: floating subagent/ultracode windows are pinch-draggable (a `window` grab kind in `entry.ts`). Types: `src/types/workflow-run.ts`. Config: `src/config/workflow-config.ts`.
+
+**Cross-session search** (COD-113/#133): `GET /api/search?q=&types=&limit=` federates an **in-memory** search across all live sessions — session metadata (name/workingDir/id), run-summary events, and per-session attachment-history file entries (workspace-relative path only; the server-private `externalPath` is never read). Pure core in `search-service.ts` (`harvestSources()` gathers, `searchSources()` substring-matches with hard per-type caps — no regex, so no ReDoS; no filesystem reads, so no traversal). `SearchQuerySchema` bounds `q` (1–200), allowlists `types` (`session,event,file`), clamps `limit` (1–60). Returns the `{success,data}` envelope. Frontend: history-panel search box in `terminal-ui.js`. Types: `src/types/search.ts`.
+
+**Away digest** (COD-41/#136): `GET /api/away-digest?range=&since=&until=&lastViewed=` aggregates "what happened while you were away" from the lifecycle log + run-summary events + live sessions + daily token stats + recently-completed subagents into needs-attention/completed/still-running/idle/informational sections. Pure aggregator in `web/away-digest.ts` (`resolveAwayDigestRange()` validates the window — `since-last-visit`/`1h`/`today`/`24h`/`custom`, server-local TZ; `buildAwayDigest()` classifies). Header-button modal in `panels-ui.js` (button hidden on phones — regression-guarded). ⚠️ Returns `{success:true,digest}` (a legacy raw-ish shape, consistent with the other raw GET handlers in `system-routes.ts` — `{entries}`/`{config}`/`{files}`/`getSystemStats()`); frontend + tests read `.digest`. Subagent lookback is a fixed 60-min window regardless of range.
+
+**Ralph todo-config** (COD-79/#135): per-session `maxTodos` (FIFO-eviction cap, default 500 = `MAX_TODOS_PER_SESSION`) + `todoExpirationMinutes` (auto-expiry, default 60) set via `POST /api/sessions/:id/ralph-config` (`RalphConfigSchema`, both `.int().positive()`). Stored on the tracker (`setMaxTodos`/`setTodoExpirationMinutes`) and **persisted/read-back via `RalphTrackerState`** (surfaced in the `loopState` getter → `toState()` + SSE broadcast → modal `populateRalphForm`), mirroring how `maxIterations` round-trips. Claude-only (skipped by `isExternalCliMode`).
 
 **Port interfaces**: Routes declare dependencies via port interfaces (`src/web/ports/`). Routes use intersection types (e.g., `SessionPort & EventPort`).
 
@@ -222,7 +228,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ### API Routes
 
-~147 handlers across 16 route files in `src/web/routes/`: system (41, incl. self-update `check`/`status`/`POST /api/system/update`, `POST /api/system/span-displays` → spawns `scripts/span-codeman.sh`, and `GET /api/codex/status`), sessions (29), orchestrator (10), cases (9), ralph (9), plan (8), files (14, incl. attachment register + list/history + `:attachmentId/raw`/`preview`/`thumbnail` + workspace `file-preview`/`file-thumbnail`), respawn (7), mux (5), push (4), scheduled (4), teams (2), hooks (1), clipboard (1), status-telemetry (1, `POST /api/status-telemetry` ← statusLine exporter), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+~150 handlers across 17 route files in `src/web/routes/`: system (45, incl. self-update `check`/`status`/`POST /api/system/update`, `POST /api/system/span-displays` → spawns `scripts/span-codeman.sh`, `GET /api/codex/status`, `GET /api/gemini/status`, and `GET /api/away-digest`), sessions (29), orchestrator (10), cases (9), ralph (9), plan (8), files (14, incl. attachment register + list/history + `:attachmentId/raw`/`preview`/`thumbnail` + workspace `file-preview`/`file-thumbnail`), respawn (7), mux (5), push (4), scheduled (4), teams (2), search (1, `GET /api/search`), hooks (1), clipboard (1), status-telemetry (1, `POST /api/status-telemetry` ← statusLine exporter), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
 
 **HTTP contract** (stable since 0.9.x, see `docs/versioning-policy.md`; full envelope/status/error-code/SSE spec in `docs/api-reference.md`): responses use the `ApiResponse<T>` envelope — `{ success: true, data? }` or `{ success: false, error, errorCode }` (`src/types/api.ts`). `/api/v1/*` is a versioned alias of `/api/*` (URL rewrite in `server.ts`).
 
@@ -262,7 +268,7 @@ Raw `npx vitest` skips `config/vitest.config.ts`; always use `npm test --` or pa
 
 **Ports**: Pick unique ports manually. Search `const PORT =` before adding new tests.
 
-**Respawn tests**: Use `MockSession` from `test/respawn-test-utils.ts`. **Route tests**: `app.inject({ method, url, payload })` in `test/routes/` — no live port needed. **Mobile tests**: Playwright suite in `test/mobile/` (135 device profiles). Browser-testing infra and practices: `docs/browser-testing-guide.md`.
+**Respawn tests**: Use `MockSession` from `test/mocks/index.ts` (defined in `test/mocks/mock-session.ts`). **Route tests**: `app.inject({ method, url, payload })` in `test/routes/` — no live port needed. **Mobile tests**: Playwright suite in `test/mobile/` (135 device profiles). Browser-testing infra and practices: `docs/browser-testing-guide.md`.
 
 ## Debugging
 
@@ -278,7 +284,7 @@ Mobile screenshots: `~/.codeman/screenshots/`, accessed via `GET/POST /api/scree
 
 ## Performance & Limits
 
-Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 2MB, text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
+Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 2MB, text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. **Image upload** (`image-input.js` / `config/buffer-limits.ts`): up to `_maxBatchImages` 20 images/batch (bounded concurrency 3), per-file `MAX_PASTE_IMAGE_BYTES` 50MB (env `CODEMAN_MAX_PASTE_IMAGE_BYTES`); the mobile camera-roll picker auto-downscales to fit before upload. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
 
 **Memory leaks (24+ hour sessions)**: use `CleanupManager`, clear Maps in `stop()`, guard async with `if (this.cleanup.isStopped) return`. Frontend: store handler refs, clean in `close*()`. Verify: `npm test -- test/memory-leak-prevention.test.ts`.
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "aicodeman",
-  "version": "1.1.16",
+  "version": "1.2.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "aicodeman",
-      "version": "1.1.16",
+      "version": "1.2.2",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.1.16",
+  "version": "1.2.2",
   "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",

src/config/buffer-limits.ts

@@ -9,11 +9,13 @@
  * - Terminal buffer: 2MB max × 20 = 40MB worst case
  * - Text output: 1MB max × 20 = 20MB worst case
  * - Messages: ~1KB each × 1000 × 20 = 20MB worst case
- * - Total buffer overhead: ~80MB (acceptable for long-running server)
+ * - Total buffer overhead: ~80MB (acceptable for a long-running server)
  *
  * @module config/buffer-limits
  */
 
+import { DEFAULT_TERMINAL_BUFFER_MAX_BYTES, DEFAULT_TERMINAL_BUFFER_TRIM_BYTES } from './terminal-history.js';
+
 // ============================================================================
 // Terminal Buffer Limits
 // ============================================================================
@@ -21,17 +23,17 @@
 /**
  * Maximum terminal buffer size in characters.
  * Contains raw terminal output with ANSI escape sequences.
- * Reduced from 5MB to 2MB for better render performance.
+ * Sourced from terminal-history config (env/settings overridable).
  * Override: CODEMAN_MAX_TERMINAL_BUFFER (bytes)
  */
-export const MAX_TERMINAL_BUFFER_SIZE = parseInt(process.env.CODEMAN_MAX_TERMINAL_BUFFER || '') || 2 * 1024 * 1024;
+export const MAX_TERMINAL_BUFFER_SIZE = DEFAULT_TERMINAL_BUFFER_MAX_BYTES;
 
 /**
  * Size to trim terminal buffer to when max is exceeded.
  * Keeps the most recent portion to preserve context.
  * Override: CODEMAN_TRIM_TERMINAL_TO (bytes)
  */
-export const TRIM_TERMINAL_TO = parseInt(process.env.CODEMAN_TRIM_TERMINAL_TO || '') || 1.5 * 1024 * 1024;
+export const TRIM_TERMINAL_TO = DEFAULT_TERMINAL_BUFFER_TRIM_BYTES;
 
 // ============================================================================
 // Text Output Buffer Limits

src/config/dependency-registry.ts

@@ -90,6 +90,14 @@ export const DEPENDENCY_REGISTRY: ToolDependency[] = [
     usedBy: ['Codex sessions'],
     resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['codex'], versionArg: '--version' } }],
   },
+  {
+    id: 'gemini',
+    label: 'Gemini CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['Gemini sessions'],
+    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['gemini'], versionArg: '--version' } }],
+  },
   {
     id: 'libreoffice',
     label: 'LibreOffice',

src/config/terminal-history.ts

@@ -0,0 +1,65 @@
+/**
+ * Defaults, bounds, and resolution for terminal history retention.
+ *
+ * Centralizes the terminal scrollback, tmux history-limit, and server PTY buffer
+ * byte caps that were previously scattered as hardcoded literals. Each value is
+ * overridable (env var or the settings object) and clamped to a sane range via
+ * resolveTerminalHistoryConfig(). Defaults intentionally match the prior
+ * hardcoded values, so introducing this module is behavior-neutral.
+ */
+
+export const DEFAULT_TERMINAL_SCROLLBACK_LINES = 50_000;
+export const DEFAULT_TMUX_HISTORY_LIMIT = 50_000;
+export const DEFAULT_TERMINAL_BUFFER_MAX_BYTES =
+  parseInt(process.env.CODEMAN_MAX_TERMINAL_BUFFER || '', 10) || 2 * 1024 * 1024;
+export const DEFAULT_TERMINAL_BUFFER_TRIM_BYTES =
+  parseInt(process.env.CODEMAN_TRIM_TERMINAL_TO || '', 10) || 1.5 * 1024 * 1024;
+
+export const MIN_TERMINAL_SCROLLBACK_LINES = 1_000;
+export const MAX_TERMINAL_SCROLLBACK_LINES = 1_000_000;
+export const MIN_TERMINAL_BUFFER_BYTES = 1024 * 1024;
+export const MAX_TERMINAL_BUFFER_BYTES = 128 * 1024 * 1024;
+
+export interface TerminalHistoryConfig {
+  terminalScrollbackLines: number;
+  tmuxHistoryLimit: number;
+  terminalBufferMaxBytes: number;
+  terminalBufferTrimBytes: number;
+}
+
+function boundedInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+
+export function resolveTerminalHistoryConfig(settings: Record<string, unknown> = {}): TerminalHistoryConfig {
+  const terminalBufferMaxBytes = boundedInt(
+    settings.terminalBufferMaxBytes,
+    DEFAULT_TERMINAL_BUFFER_MAX_BYTES,
+    MIN_TERMINAL_BUFFER_BYTES,
+    MAX_TERMINAL_BUFFER_BYTES
+  );
+  const terminalBufferTrimBytes = boundedInt(
+    settings.terminalBufferTrimBytes,
+    Math.min(DEFAULT_TERMINAL_BUFFER_TRIM_BYTES, terminalBufferMaxBytes),
+    MIN_TERMINAL_BUFFER_BYTES,
+    terminalBufferMaxBytes
+  );
+
+  return {
+    terminalScrollbackLines: boundedInt(
+      settings.terminalScrollbackLines,
+      DEFAULT_TERMINAL_SCROLLBACK_LINES,
+      MIN_TERMINAL_SCROLLBACK_LINES,
+      MAX_TERMINAL_SCROLLBACK_LINES
+    ),
+    tmuxHistoryLimit: boundedInt(
+      settings.tmuxHistoryLimit,
+      DEFAULT_TMUX_HISTORY_LIMIT,
+      MIN_TERMINAL_SCROLLBACK_LINES,
+      MAX_TERMINAL_SCROLLBACK_LINES
+    ),
+    terminalBufferMaxBytes,
+    terminalBufferTrimBytes,
+  };
+}

src/mux-interface.ts

@@ -16,6 +16,7 @@ import type {
   OpenCodeConfig,
   CodexConfig,
   EffortLevel,
+  GeminiConfig,
 } from './types.js';
 
 /**
@@ -64,12 +65,15 @@ export interface CreateSessionOptions {
   allowedTools?: string;
   openCodeConfig?: OpenCodeConfig;
   codexConfig?: CodexConfig;
+  geminiConfig?: GeminiConfig;
   /** When restoring after reboot, resume a previous Claude conversation by its session ID */
   resumeSessionId?: string;
   /** Extra env vars exported before launching the CLI (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Ephemeral — not written to disk. */
   envOverrides?: Record<string, string>;
   /** Claude CLI effort level, injected as a `--settings` soft default (overridable via /effort in-session) */
   effort?: EffortLevel;
+  /** tmux history-limit (scrollback lines) to set for this session. */
+  historyLimit?: number;
 }
 
 /** Options for respawning a dead pane. */
@@ -83,12 +87,15 @@ export interface RespawnPaneOptions {
   allowedTools?: string;
   openCodeConfig?: OpenCodeConfig;
   codexConfig?: CodexConfig;
+  geminiConfig?: GeminiConfig;
   /** Resume a previous Claude conversation when respawning */
   resumeSessionId?: string;
   /** Extra env vars exported before launching the CLI (preserved across respawns). */
   envOverrides?: Record<string, string>;
   /** Claude CLI effort level (preserved across respawns, injected via `--settings`) */
   effort?: EffortLevel;
+  /** tmux history-limit (scrollback lines) to set for this session after respawn. */
+  historyLimit?: number;
 }
 
 /**
@@ -167,6 +174,9 @@ export interface TerminalMultiplexer extends EventEmitter {
   /** Update Ralph enabled state for a session */
   updateRalphEnabled(sessionId: string, enabled: boolean): void;
 
+  /** Apply a tmux history-limit to all tracked sessions. */
+  setHistoryLimit(limit: number): Promise<void>;
+
   // ========== Discovery ==========
 
   /**

src/ralph-tracker.ts

@@ -467,6 +467,12 @@ export class RalphTracker extends EventEmitter {
   /** Timestamp of last cleanup check for throttling */
   private _lastCleanupTime: number = 0;
 
+  /** Maximum number of todos retained for this session (defaults to global cap) */
+  private _maxTodos: number = MAX_TODOS_PER_SESSION;
+
+  /** Todo auto-expiry duration in milliseconds (defaults to global constant) */
+  private _todoExpiryMs: number = TODO_EXPIRY_MS;
+
   /** Debouncer for todoUpdate events */
   private _todoDeb = new Debouncer(EVENT_DEBOUNCE_MS);
 
@@ -1053,6 +1059,10 @@ export class RalphTracker extends EventEmitter {
       planVersion: this.planTracker.planVersion,
       planHistoryLength: this.planTracker.getPlanHistory().length,
       completionConfidence: this._lastCompletionConfidence,
+      // Surface the live todo-config so it persists (toState) and reads back into
+      // the Session Options modal (broadcast) — mirrors maxIterations round-trip.
+      maxTodos: this._maxTodos,
+      todoExpirationMinutes: this.todoExpirationMinutes,
     };
   }
 
@@ -1840,7 +1850,7 @@ export class RalphTracker extends EventEmitter {
         return;
       }
 
-      while (this._todos.size >= MAX_TODOS_PER_SESSION) {
+      while (this._todos.size >= this._maxTodos) {
         const oldest = this.findOldestTodo();
         if (oldest) {
           this._todos.delete(oldest.id);
@@ -2164,14 +2174,14 @@ export class RalphTracker extends EventEmitter {
   }
 
   /**
-   * Remove todo items older than TODO_EXPIRY_MS.
+   * Remove todo items older than the configured expiry duration.
    */
   private cleanupExpiredTodos(): void {
     const now = Date.now();
     const toDelete: string[] = [];
 
     for (const [id, todo] of this._todos) {
-      if (now - todo.detectedAt > TODO_EXPIRY_MS) {
+      if (now - todo.detectedAt > this._todoExpiryMs) {
         toDelete.push(id);
       }
     }
@@ -2211,6 +2221,34 @@ export class RalphTracker extends EventEmitter {
     this.emit('loopUpdate', this.loopState);
   }
 
+  /** Maximum number of todos retained for this session. */
+  get maxTodos(): number {
+    return this._maxTodos;
+  }
+
+  /** Todo auto-expiry duration in minutes for this session. */
+  get todoExpirationMinutes(): number {
+    return Math.round(this._todoExpiryMs / 60000);
+  }
+
+  /**
+   * Update the maximum number of retained todos (external API).
+   * Ignores non-positive values.
+   */
+  setMaxTodos(maxTodos: number): void {
+    if (!Number.isFinite(maxTodos) || maxTodos <= 0) return;
+    this._maxTodos = Math.floor(maxTodos);
+  }
+
+  /**
+   * Update the todo auto-expiry duration (external API), specified in minutes.
+   * Converts to milliseconds internally. Ignores non-positive values.
+   */
+  setTodoExpirationMinutes(minutes: number): void {
+    if (!Number.isFinite(minutes) || minutes <= 0) return;
+    this._todoExpiryMs = Math.floor(minutes) * 60000;
+  }
+
   /**
    * Configure the tracker from external state.
    */
@@ -2311,6 +2349,12 @@ export class RalphTracker extends EventEmitter {
       ...loopState,
       enabled: loopState.enabled ?? false,
     };
+    // Restore the per-session todo-config into the live fields used by the hot
+    // paths (eviction cap + expiry). Setters ignore non-positive values.
+    if (typeof loopState.maxTodos === 'number') this.setMaxTodos(loopState.maxTodos);
+    if (typeof loopState.todoExpirationMinutes === 'number') {
+      this.setTodoExpirationMinutes(loopState.todoExpirationMinutes);
+    }
     this._todos.clear();
     for (const todo of todos) {
       this._todos.set(todo.id, {

src/search-service.ts

@@ -0,0 +1,207 @@
+/**
+ * @fileoverview Pure cross-session federated search core (COD-9).
+ *
+ * `searchSources()` is the testable heart of `GET /api/search`: it takes a
+ * normalized query plus already-collected, in-memory source data and returns
+ * grouped, ranked, and capped results. It performs NO I/O — the route wrapper
+ * (`src/web/routes/search-routes.ts`) is responsible for harvesting the source
+ * arrays from the live server stores (sessions, run-summary trackers, attachment
+ * histories) in a bounded way before calling this.
+ *
+ * v1 scope (do not expand here): three sources — sessions/cases, run-summary
+ * events, file paths. Terminal-buffer scanning and any persisted index are
+ * explicitly deferred.
+ *
+ * Ranking: results are grouped by source type in the fixed order
+ * sessions → events → files. Within each group, exact (case-insensitive)
+ * name/path matches come first, then recency (newest timestamp first) as the
+ * tiebreak. There is no relevance-scoring pass in v1.
+ *
+ * Safety: file results only ever expose a workspace-relative path — server-
+ * private absolute paths are never placed in a result. Per-group and total caps
+ * bound the output so a broad query cannot return an unbounded payload.
+ *
+ * Key exports:
+ * - searchSources() — the pure core.
+ * - SEARCH_TOTAL_CAP / SEARCH_PER_GROUP_CAP — the output bounds.
+ * - SearchSources and the *Input row types — the source-data contract.
+ */
+
+import type { SearchResult, SearchResultGroup, SearchResponseData, SearchSourceType } from './types/search.js';
+
+/** Maximum results returned across all groups combined. */
+export const SEARCH_TOTAL_CAP = 60;
+/** Maximum results returned within any single source group. */
+export const SEARCH_PER_GROUP_CAP = 25;
+/** Maximum characters in a result snippet. */
+export const SEARCH_SNIPPET_MAX = 200;
+
+/** A live-session row harvested for the session/case source. */
+export interface SessionSearchInput {
+  sessionId: string;
+  sessionName: string;
+  workingDir: string;
+  /** Recency timestamp (e.g. lastActivityAt or createdAt). */
+  timestamp: number;
+}
+
+/** A run-summary timeline event harvested for the event source. */
+export interface EventSearchInput {
+  sessionId: string;
+  sessionName: string;
+  eventId: string;
+  title: string;
+  details: string;
+  timestamp: number;
+}
+
+/** A per-session attachment harvested for the file source. */
+export interface FileSearchInput {
+  sessionId: string;
+  sessionName: string;
+  fileName: string;
+  /** Workspace-relative path, if known. Absolute/external paths are never passed in. */
+  relativePath: string | undefined;
+  timestamp: number;
+  /** Attachment history item id, used as the jump-to target. */
+  itemId: string;
+}
+
+/** The full set of in-memory source data the pure core searches over. */
+export interface SearchSources {
+  sessions: SessionSearchInput[];
+  events: EventSearchInput[];
+  files: FileSearchInput[];
+}
+
+/** Fixed group/render order. */
+const GROUP_ORDER: SearchSourceType[] = ['session', 'event', 'file'];
+
+function truncate(text: string, max = SEARCH_SNIPPET_MAX): string {
+  const trimmed = text.trim().replace(/\s+/g, ' ');
+  return trimmed.length > max ? trimmed.slice(0, max - 1) + '…' : trimmed;
+}
+
+/**
+ * Sort a group's results: exact matches first, then newest timestamp first.
+ * Stable for equal keys.
+ */
+function sortGroup(rows: SearchResult[]): SearchResult[] {
+  return rows
+    .map((result, index) => ({ result, index }))
+    .sort((a, b) => {
+      if (a.result.exactMatch !== b.result.exactMatch) {
+        return a.result.exactMatch ? -1 : 1;
+      }
+      if (a.result.timestamp !== b.result.timestamp) {
+        return b.result.timestamp - a.result.timestamp;
+      }
+      return a.index - b.index;
+    })
+    .map((r) => r.result);
+}
+
+/**
+ * Search the provided in-memory sources for `query`.
+ *
+ * @param query Raw query string (already length-validated by the route). Blank
+ *   queries return an empty result set.
+ * @param sources Harvested, bounded source arrays.
+ */
+export function searchSources(query: string, sources: SearchSources): SearchResponseData {
+  const needle = query.trim().toLowerCase();
+  if (needle.length === 0) {
+    return { query: query.trim(), groups: [], totalResults: 0, truncated: false };
+  }
+
+  const contains = (s: string | undefined): boolean => !!s && s.toLowerCase().includes(needle);
+  const isExact = (s: string | undefined): boolean => !!s && s.toLowerCase() === needle;
+
+  // -- Source: sessions/cases --
+  const sessionRows: SearchResult[] = [];
+  for (const s of sources.sessions) {
+    if (contains(s.sessionName) || contains(s.workingDir) || contains(s.sessionId)) {
+      sessionRows.push({
+        type: 'session',
+        sessionId: s.sessionId,
+        sessionName: s.sessionName,
+        timestamp: s.timestamp,
+        snippet: truncate(s.workingDir ? `${s.sessionName} — ${s.workingDir}` : s.sessionName),
+        exactMatch: isExact(s.sessionName),
+        jumpTo: { kind: 'session', sessionId: s.sessionId },
+      });
+    }
+  }
+
+  // -- Source: run-summary events --
+  const eventRows: SearchResult[] = [];
+  for (const e of sources.events) {
+    if (contains(e.title) || contains(e.details)) {
+      const snippetBase = e.details && contains(e.details) ? `${e.title}: ${e.details}` : e.title;
+      eventRows.push({
+        type: 'event',
+        sessionId: e.sessionId,
+        sessionName: e.sessionName,
+        timestamp: e.timestamp,
+        snippet: truncate(snippetBase),
+        exactMatch: isExact(e.title),
+        jumpTo: { kind: 'run-summary', sessionId: e.sessionId, targetId: e.eventId },
+      });
+    }
+  }
+
+  // -- Source: file paths --
+  const fileRows: SearchResult[] = [];
+  for (const f of sources.files) {
+    if (contains(f.fileName) || contains(f.relativePath)) {
+      fileRows.push({
+        type: 'file',
+        sessionId: f.sessionId,
+        sessionName: f.sessionName,
+        timestamp: f.timestamp,
+        snippet: truncate(f.relativePath ?? f.fileName),
+        // Exact match keys off the safe path (or filename) — never an absolute path.
+        exactMatch: isExact(f.relativePath) || isExact(f.fileName),
+        jumpTo: {
+          kind: 'file-preview',
+          sessionId: f.sessionId,
+          targetId: f.itemId,
+          // Only ever expose a relative path; absolute/external paths are not passed in.
+          relativePath: f.relativePath,
+        },
+      });
+    }
+  }
+
+  const byType: Record<SearchSourceType, SearchResult[]> = {
+    session: sortGroup(sessionRows),
+    event: sortGroup(eventRows),
+    file: sortGroup(fileRows),
+  };
+
+  const groups: SearchResultGroup[] = [];
+  let total = 0;
+  let truncated = false;
+
+  for (const type of GROUP_ORDER) {
+    const all = byType[type];
+    if (all.length === 0) continue;
+
+    // Per-group cap.
+    let capped = all.slice(0, SEARCH_PER_GROUP_CAP);
+    if (all.length > capped.length) truncated = true;
+
+    // Total cap (never exceed the global budget).
+    const remaining = SEARCH_TOTAL_CAP - total;
+    if (capped.length > remaining) {
+      capped = capped.slice(0, Math.max(0, remaining));
+      truncated = true;
+    }
+    if (capped.length === 0) continue;
+
+    groups.push({ type, results: capped });
+    total += capped.length;
+  }
+
+  return { query: query.trim(), groups, totalResults: total, truncated };
+}

src/session.ts

@@ -48,6 +48,7 @@ import {
   type OpenCodeConfig,
   type CodexConfig,
   type EffortLevel,
+  type GeminiConfig,
 } from './types.js';
 import type { TerminalMultiplexer, MuxSession } from './mux-interface.js';
 import { TaskTracker, type BackgroundTask } from './task-tracker.js';
@@ -69,6 +70,7 @@ import {
   MAX_MESSAGES,
   MAX_LINE_BUFFER_SIZE,
 } from './config/buffer-limits.js';
+import { DEFAULT_TMUX_HISTORY_LIMIT } from './config/terminal-history.js';
 import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
 import {
   buildInteractiveArgs,
@@ -133,7 +135,22 @@ const NEWLINE_SPLIT_PATTERN = /\r?\n/;
 
 /** True for external-CLI run modes (non-Claude) that use their own TUI and output format. */
 export function isExternalCliMode(mode: SessionMode): boolean {
-  return mode === 'opencode' || mode === 'codex';
+  return mode === 'opencode' || mode === 'codex' || mode === 'gemini';
+}
+
+function getModeLabel(mode: SessionMode): string {
+  switch (mode) {
+    case 'opencode':
+      return 'OpenCode';
+    case 'codex':
+      return 'Codex';
+    case 'gemini':
+      return 'Gemini';
+    case 'shell':
+      return 'Shell';
+    case 'claude':
+      return 'Claude';
+  }
 }
 
 /**
@@ -141,14 +158,15 @@ export function isExternalCliMode(mode: SessionMode): boolean {
  * that we strip so the browser keeps everything in the main buffer with scrollback
  * reachable (the strip runs on both the live stream and the buffer replay).
  *
- * Codex and Claude Code are known, controlled TUIs that repaint via cursor
- * positioning, so dropping the alt-screen switch is safe — content stays in the
- * normal buffer. Excluded: `shell` (arbitrary programs like vim/less/htop
- * legitimately need the alt screen) and `opencode` (renders its own TUI that
- * may rely on it). Keep parity with the replay-side strip in session-routes.ts.
+ * Codex, Claude Code, and Gemini are known, controlled (Ink/React) TUIs that
+ * repaint via cursor positioning, so dropping the alt-screen switch is safe —
+ * content stays in the normal buffer. Excluded: `shell` (arbitrary programs like
+ * vim/less/htop legitimately need the alt screen) and `opencode` (renders its own
+ * TUI that may rely on it). Keep parity with the replay-side strip in
+ * session-routes.ts.
  */
 export function isAltScreenStripMode(mode: SessionMode): boolean {
-  return mode === 'codex' || mode === 'claude';
+  return mode === 'codex' || mode === 'claude' || mode === 'gemini';
 }
 
 // Note: Claude CLI PATH resolution moved to session-cli-builder.ts (buildClaudeEnv)
@@ -351,6 +369,8 @@ export class Session extends EventEmitter {
   private _openCodeConfig: OpenCodeConfig | undefined;
   // Codex configuration (only for mode === 'codex')
   private _codexConfig: CodexConfig | undefined;
+  // Gemini configuration (only for mode === 'gemini')
+  private _geminiConfig: GeminiConfig | undefined;
   private _resumeSessionId: string | undefined;
 
   // Ephemeral env overrides (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Exported by tmux
@@ -362,6 +382,9 @@ export class Session extends EventEmitter {
   // the CLAUDE_CODE_EFFORT_LEVEL env var, which would hard-lock the session.
   private _effort: EffortLevel | undefined;
 
+  // tmux history-limit (scrollback lines) applied to this session's pane.
+  private readonly _tmuxHistoryLimit: number;
+
   // Session color for visual differentiation
   private _color: import('./types.js').SessionColor = 'default';
 
@@ -421,12 +444,16 @@ export class Session extends EventEmitter {
       openCodeConfig?: OpenCodeConfig;
       /** Codex configuration (only for mode === 'codex') */
       codexConfig?: CodexConfig;
+      /** Gemini configuration (only for mode === 'gemini') */
+      geminiConfig?: GeminiConfig;
       /** Resume a previous Claude conversation (used after server reboot) */
       resumeSessionId?: string;
       /** Extra env vars exported to the CLI at spawn time (no disk persistence) */
       envOverrides?: Record<string, string>;
       /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
       effort?: EffortLevel;
+      /** tmux history-limit (scrollback lines) for this session's pane. */
+      tmuxHistoryLimit?: number;
       /** Restored per-session attachment history. May include server-private external paths. */
       attachmentHistory?: SessionAttachmentHistoryItem[];
     }
@@ -481,6 +508,11 @@ export class Session extends EventEmitter {
       this._codexConfig = config.codexConfig;
     }
 
+    // Apply Gemini configuration
+    if (config.geminiConfig) {
+      this._geminiConfig = config.geminiConfig;
+    }
+
     // Apply env overrides (exported at spawn, not persisted to disk).
     // Legacy migration: pre-0.7.2 carried effort as the CLAUDE_CODE_EFFORT_LEVEL env var,
     // which hard-locks /effort switching. Extract it into _effort (--settings soft default)
@@ -495,6 +527,7 @@ export class Session extends EventEmitter {
     if (config.effort && isEffortLevel(config.effort)) {
       this._effort = config.effort;
     }
+    this._tmuxHistoryLimit = config.tmuxHistoryLimit ?? DEFAULT_TMUX_HISTORY_LIMIT;
     if (config.attachmentHistory && config.attachmentHistory.length > 0) {
       this.restoreAttachmentHistory(config.attachmentHistory);
     }
@@ -985,6 +1018,7 @@ export class Session extends EventEmitter {
       cliLatestVersion: this._cliLatestVersion || undefined,
       openCodeConfig: this._openCodeConfig,
       codexConfig: this._codexConfig,
+      geminiConfig: this._geminiConfig,
       resumeSessionId: this._resumeSessionId,
       effort: this._effort,
       attachmentHistory: this.attachmentHistory.length > 0 ? this.attachmentHistory : undefined,
@@ -1224,7 +1258,7 @@ export class Session extends EventEmitter {
 
     this._resetBuffers();
 
-    const modeLabel = this.mode === 'opencode' ? 'OpenCode' : this.mode === 'codex' ? 'Codex' : 'Claude';
+    const modeLabel = getModeLabel(this.mode);
     console.log(
       `[Session] Starting interactive ${modeLabel} session` + (this._useMux ? ` (with ${this._mux!.backend})` : '')
     );
@@ -1243,9 +1277,11 @@ export class Session extends EventEmitter {
             allowedTools: this._allowedTools,
             openCodeConfig: this._openCodeConfig,
             codexConfig: this._codexConfig,
+            geminiConfig: this._geminiConfig,
             resumeSessionId: this._resumeSessionId,
             envOverrides: this._envOverrides,
             effort: this._effort,
+            historyLimit: this._tmuxHistoryLimit,
           },
           createSessionOptions: {
             sessionId: this.id,
@@ -1258,9 +1294,11 @@ export class Session extends EventEmitter {
             allowedTools: this._allowedTools,
             openCodeConfig: this._openCodeConfig,
             codexConfig: this._codexConfig,
+            geminiConfig: this._geminiConfig,
             resumeSessionId: this._resumeSessionId,
             envOverrides: this._envOverrides,
             effort: this._effort,
+            historyLimit: this._tmuxHistoryLimit,
           },
           spawnErrLabel: 'mux attachment',
         });
@@ -1331,6 +1369,10 @@ export class Session extends EventEmitter {
       if (this.mode === 'codex') {
         throw new Error('Codex sessions require tmux. Direct PTY fallback is not supported.');
       }
+      // Gemini sessions require tmux for Gemini/Google auth env injection via setenv
+      if (this.mode === 'gemini') {
+        throw new Error('Gemini sessions require tmux. Direct PTY fallback is not supported.');
+      }
       try {
         // Pass --session-id to use the SAME ID as the Codeman session
         // This ensures subagents can be directly matched to the correct tab
@@ -1594,6 +1636,7 @@ export class Session extends EventEmitter {
             mode: 'shell',
             niceConfig: this._niceConfig,
             envOverrides: this._envOverrides,
+            historyLimit: this._tmuxHistoryLimit,
           },
           createSessionOptions: {
             sessionId: this.id,
@@ -1602,6 +1645,7 @@ export class Session extends EventEmitter {
             name: this._name,
             niceConfig: this._niceConfig,
             envOverrides: this._envOverrides,
+            historyLimit: this._tmuxHistoryLimit,
           },
           spawnErrLabel: 'shell mux attachment',
         });

src/tmux-manager.ts

@@ -41,9 +41,17 @@ import {
   type OpenCodeConfig,
   type CodexConfig,
   type EffortLevel,
+  type GeminiConfig,
 } from './types.js';
 import { buildEffortCliArgs } from './session-cli-builder.js';
-import { wrapWithNice, SAFE_PATH_PATTERN, findClaudeDir, resolveOpenCodeDir, resolveCodexDir } from './utils/index.js';
+import {
+  wrapWithNice,
+  SAFE_PATH_PATTERN,
+  findClaudeDir,
+  resolveOpenCodeDir,
+  resolveCodexDir,
+  resolveGeminiDir,
+} from './utils/index.js';
 import type {
   TerminalMultiplexer,
   MuxSession,
@@ -57,6 +65,7 @@ import type {
 // ============================================================================
 
 import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
+import { DEFAULT_TMUX_HISTORY_LIMIT } from './config/terminal-history.js';
 
 /** Delay after tmux session creation — enough for detached tmux to be queryable */
 const TMUX_CREATION_WAIT_MS = 100;
@@ -571,6 +580,35 @@ export function buildCodexCommand(config?: CodexConfig): string {
   return parts.join(' ');
 }
 
+/**
+ * Build the Gemini CLI command with appropriate flags.
+ *
+ * `--skip-trust` avoids a first-run workspace trust prompt inside Codeman.
+ * Approval mode defaults to `yolo` for parity with Codeman's Claude default
+ * of `--dangerously-skip-permissions`; users can override it later through
+ * Gemini config once Codeman exposes richer Gemini settings.
+ */
+function buildGeminiCommand(config?: GeminiConfig): string {
+  const parts = ['gemini', '--skip-trust'];
+
+  const approvalMode = config?.approvalMode || 'yolo';
+  if (['default', 'auto_edit', 'yolo', 'plan'].includes(approvalMode)) {
+    parts.push('--approval-mode', approvalMode);
+  }
+
+  if (config?.model) {
+    const safeModel = /^[a-zA-Z0-9._\-/]+$/.test(config.model) ? config.model : undefined;
+    if (safeModel) parts.push('--model', safeModel);
+  }
+
+  if (config?.resumeSession) {
+    const safeId = /^[a-zA-Z0-9._-]+$/.test(config.resumeSession) ? config.resumeSession : undefined;
+    if (safeId) parts.push('--resume', safeId);
+  }
+
+  return parts.join(' ');
+}
+
 /**
  * Build the spawn command for any session mode.
  * Shared by createSession() and respawnPane() to avoid duplication.
@@ -597,6 +635,7 @@ function buildSpawnCommand(options: {
   allowedTools?: string;
   openCodeConfig?: OpenCodeConfig;
   codexConfig?: CodexConfig;
+  geminiConfig?: GeminiConfig;
   resumeSessionId?: string;
   effort?: EffortLevel;
 }): string {
@@ -624,6 +663,9 @@ function buildSpawnCommand(options: {
   if (options.mode === 'codex') {
     return buildCodexCommand(options.codexConfig);
   }
+  if (options.mode === 'gemini') {
+    return buildGeminiCommand(options.geminiConfig);
+  }
   return '$SHELL';
 }
 
@@ -674,6 +716,38 @@ function setCodexEnvVars(tmuxCmd: string, muxName: string): void {
   }
 }
 
+/**
+ * Set sensitive environment variables for Gemini on a tmux session via setenv.
+ * Gemini Pro/Ultra users usually authenticate via cached Google login; these
+ * variables cover API-key and Vertex AI paths without putting secrets in ps.
+ */
+function setGeminiEnvVars(tmuxCmd: string, muxName: string): void {
+  const sensitiveVars = [
+    'GEMINI_API_KEY',
+    'GEMINI_MODEL',
+    'GOOGLE_API_KEY',
+    'GOOGLE_CLOUD_PROJECT',
+    'GOOGLE_CLOUD_LOCATION',
+    'GOOGLE_APPLICATION_CREDENTIALS',
+    'GOOGLE_GENAI_USE_VERTEXAI',
+  ];
+  for (const key of sensitiveVars) {
+    const val = process.env[key];
+    if (val) {
+      const escaped = val.replace(/'/g, "'\\''");
+      try {
+        execSync(`${tmuxCmd} setenv -t '${muxName}' ${key} '${escaped}'`, {
+          encoding: 'utf8',
+          timeout: EXEC_TIMEOUT_MS,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+      } catch {
+        /* Non-critical — key may not be needed */
+      }
+    }
+  }
+}
+
 /**
  * Set OPENCODE_CONFIG_CONTENT on a tmux session via setenv.
  * Uses tmux setenv to avoid shell metacharacter injection from user-supplied JSON.
@@ -856,8 +930,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const exports = [
       'export LANG=en_US.UTF-8',
       'export LC_ALL=en_US.UTF-8',
-      mode === 'codex' ? 'export COLORTERM=truecolor' : 'unset COLORTERM',
-      ...(mode === 'codex' ? ['unset NO_COLOR'] : []),
+      mode === 'codex' || mode === 'gemini' ? 'export COLORTERM=truecolor' : 'unset COLORTERM',
+      ...(mode === 'codex' || mode === 'gemini' ? ['unset NO_COLOR'] : []),
       'export CODEMAN_MUX=1',
       `export CODEMAN_SESSION_ID=${sessionId}`,
       `export CODEMAN_MUX_NAME=${muxName}`,
@@ -930,6 +1004,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       const dir = resolveCodexDir();
       return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
     }
+    if (mode === 'gemini') {
+      const dir = resolveGeminiDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
     return { pathExport: '', dir: null };
   }
 
@@ -953,6 +1031,13 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     setCodexEnvVars(this.tmux(), muxName);
   }
 
+  /**
+   * Configure Gemini-specific environment on a tmux session.
+   */
+  private _configureGemini(muxName: string): void {
+    setGeminiEnvVars(this.tmux(), muxName);
+  }
+
   /**
    * Creates a new tmux session wrapping Claude CLI or a shell.
    * In test mode: creates an in-memory session only (no real tmux session).
@@ -969,9 +1054,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       allowedTools,
       openCodeConfig,
       codexConfig,
+      geminiConfig,
       resumeSessionId,
       envOverrides,
       effort,
+      historyLimit = DEFAULT_TMUX_HISTORY_LIMIT,
     } = options;
     const muxName = `codeman-${sessionId.slice(0, 8)}`;
 
@@ -1007,6 +1094,12 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     if (mode === 'opencode' && !cliDir) {
       throw new Error('OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash');
     }
+    if (mode === 'codex' && !cliDir) {
+      throw new Error('Codex CLI not found. Install with: npm install -g @openai/codex');
+    }
+    if (mode === 'gemini' && !cliDir) {
+      throw new Error('Gemini CLI not found. Install with: npm install -g @google/gemini-cli');
+    }
 
     const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
 
@@ -1018,6 +1111,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       allowedTools,
       openCodeConfig,
       codexConfig,
+      geminiConfig,
       resumeSessionId,
       effort,
     });
@@ -1067,6 +1161,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       } else if (mode === 'codex') {
         this._configureCodex(muxName);
       }
+      // For Gemini: set Gemini/Google auth env vars via tmux setenv
+      if (mode === 'gemini') {
+        this._configureGemini(muxName);
+      }
 
       // Apply user-supplied env overrides (e.g., CLAUDE_CODE_EFFORT_LEVEL) via tmux setenv
       // so secret values stay off the bash command line. Must run before respawn-pane.
@@ -1105,7 +1203,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
           }),
         // Raise tmux scrollback from its 2000-line default so re-attach preserves
         // more context. Matches the xterm-side default in constants.js.
-        execAsync(`${this.tmux()} set-option -t "${muxName}" history-limit 50000`, { timeout: EXEC_TIMEOUT_MS })
+        execAsync(`${this.tmux()} set-option -t "${muxName}" history-limit ${historyLimit}`, {
+          timeout: EXEC_TIMEOUT_MS,
+        })
           .then(() => {})
           .catch(() => {
             /* Non-critical — falls back to tmux default */
@@ -1224,9 +1324,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       allowedTools,
       openCodeConfig,
       codexConfig,
+      geminiConfig,
       resumeSessionId,
       envOverrides,
       effort,
+      historyLimit = DEFAULT_TMUX_HISTORY_LIMIT,
     } = options;
     const session = this.sessions.get(sessionId);
     if (!session) return null;
@@ -1234,6 +1336,16 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
 
     if (!isValidMuxName(muxName) || !isValidPath(workingDir)) return null;
 
+    // Re-apply the configured tmux history-limit after respawn (kept in sync
+    // with the live setting via setHistoryLimit()).
+    if (!IS_TEST_MODE) {
+      await execAsync(`${this.tmux()} set-option -t ${shellescape(muxName)} history-limit ${historyLimit}`, {
+        timeout: EXEC_TIMEOUT_MS,
+      }).catch(() => {
+        /* Non-critical — keeps existing tmux history-limit */
+      });
+    }
+
     // Resolve CLI binary directory based on mode
     const { pathExport } = this.buildPathExport(mode);
 
@@ -1247,6 +1359,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       allowedTools,
       openCodeConfig,
       codexConfig,
+      geminiConfig,
       resumeSessionId,
       effort,
     });
@@ -1261,6 +1374,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       } else if (mode === 'codex') {
         this._configureCodex(muxName);
       }
+      // For Gemini: set Gemini/Google auth env vars via tmux setenv before respawn
+      if (mode === 'gemini') {
+        this._configureGemini(muxName);
+      }
 
       // Re-apply user env overrides before respawn so the new shell inherits them.
       this.applyEnvOverrides(muxName, envOverrides);
@@ -1833,6 +1950,26 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
   }
 
+  /**
+   * Apply a tmux history-limit to all tracked sessions (e.g. when the user
+   * changes the terminal-history setting). Invalid limits fall back to the
+   * default. Best-effort per session.
+   */
+  async setHistoryLimit(limit: number): Promise<void> {
+    const safeLimit = Number.isSafeInteger(limit) && limit > 0 ? Math.trunc(limit) : DEFAULT_TMUX_HISTORY_LIMIT;
+
+    if (IS_TEST_MODE) {
+      return;
+    }
+
+    const updates = Array.from(this.sessions.values()).map((session) =>
+      execAsync(`${this.tmux()} set-option -t ${shellescape(session.muxName)} history-limit ${safeLimit}`, {
+        timeout: EXEC_TIMEOUT_MS,
+      })
+    );
+    await Promise.allSettled(updates);
+  }
+
   /**
    * Send input directly to a tmux session using `send-keys`.
    *

src/types/index.ts

@@ -68,3 +68,4 @@ export * from './plan.js';
 export * from './orchestrator.js';
 export * from './update.js';
 export * from './workflow-run.js';
+export * from './search.js';

src/types/ralph.ts

@@ -90,6 +90,10 @@ export interface RalphTrackerState {
   cycleCount: number;
   /** Maximum iterations if detected */
   maxIterations: number | null;
+  /** Max todos retained for this session before FIFO eviction (persisted; default = global cap) */
+  maxTodos?: number;
+  /** Todo auto-expiry in minutes (persisted; default = global TODO_EXPIRY_MS) */
+  todoExpirationMinutes?: number;
   /** Timestamp of last activity */
   lastActivity: number;
   /** Elapsed hours if detected */

src/types/search.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Cross-session federated search types (COD-9).
+ *
+ * Defines the typed shapes for `GET /api/search` — a bounded, in-memory
+ * federated search across three v1 sources: live sessions/cases, run-summary
+ * timeline events, and per-session attachment file paths. Terminal-buffer scans
+ * and any persisted index are explicitly out of scope for v1.
+ *
+ * Key exports:
+ * - SearchSourceType — the federated source kinds, also the group order key.
+ * - SearchResult — a single typed result card (source, session id/name,
+ *   timestamp, snippet, jump-to action target).
+ * - SearchJumpTarget — where the frontend should navigate when a card is opened.
+ * - SearchResponseData — grouped result payload returned in the ApiResponse envelope.
+ *
+ * No I/O, no dependencies on other domain modules. The pure search core lives
+ * in `src/search-service.ts`; the route wrapper in `src/web/routes/search-routes.ts`.
+ */
+
+/** Federated source kinds. Group/render order is sessions → events → files. */
+export type SearchSourceType = 'session' | 'event' | 'file';
+
+/** Where the frontend should jump when a result card is activated. */
+export interface SearchJumpTarget {
+  /** Kind of navigation target. */
+  kind: 'session' | 'run-summary' | 'file-preview';
+  /** Owning Codeman session id (always present — every result is session-scoped). */
+  sessionId: string;
+  /**
+   * Secondary identifier for the target:
+   * - kind 'run-summary': the run-summary event id
+   * - kind 'file-preview': the attachment history item id
+   * - kind 'session': undefined (the sessionId is sufficient)
+   */
+  targetId?: string;
+  /**
+   * Workspace-relative path for file-preview targets. Never an absolute path —
+   * server-private external paths are intentionally omitted to avoid leakage.
+   */
+  relativePath?: string;
+}
+
+/** A single typed search result card. */
+export interface SearchResult {
+  /** Which federated source produced this result. */
+  type: SearchSourceType;
+  /** Owning Codeman session id. */
+  sessionId: string;
+  /** Display name of the owning session / case. */
+  sessionName: string;
+  /** Millisecond timestamp used for recency ranking and display. */
+  timestamp: number;
+  /** Short, already-truncated snippet describing the match. */
+  snippet: string;
+  /** True when the query matched the primary name/path exactly (case-insensitive). */
+  exactMatch: boolean;
+  /** Navigation target for the jump-to action. */
+  jumpTo: SearchJumpTarget;
+}
+
+/** A group of results for one source type, in render order. */
+export interface SearchResultGroup {
+  type: SearchSourceType;
+  results: SearchResult[];
+}
+
+/** Payload returned as `data` inside the standard ApiResponse envelope. */
+export interface SearchResponseData {
+  /** The normalized query that was executed. */
+  query: string;
+  /** Results grouped by source type, ordered sessions → events → files. */
+  groups: SearchResultGroup[];
+  /** Total number of results across all groups (after caps applied). */
+  totalResults: number;
+  /** True if any group or the total was capped (more matches existed). */
+  truncated: boolean;
+}

src/types/session.ts

@@ -8,10 +8,12 @@
  * - SessionConfig — creation-time config (id, workingDir, createdAt)
  * - SessionOutput — captured stdout/stderr/exitCode
  * - SessionStatus — 'idle' | 'busy' | 'stopped' | 'error'
- * - SessionMode — 'claude' | 'shell' | 'opencode' | 'codex' (which CLI backend)
+ * - SessionMode — 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' (which CLI backend)
  * - ClaudeMode — CLI permission mode ('dangerously-skip-permissions' | 'normal' | 'allowedTools')
  * - SessionColor — visual differentiation color
  * - OpenCodeConfig — OpenCode-specific settings (model, autoAllowTools, continueSession)
+ * - CodexConfig — Codex (OpenAI CLI)-specific settings (model, resumeSessionId)
+ * - GeminiConfig — Gemini CLI-specific settings (model, approvalMode, resumeSession)
  *
  * Cross-domain relationships:
  * - SessionState.respawnConfig embeds RespawnConfig (respawn domain)
@@ -39,7 +41,7 @@ export type SessionStatus = 'idle' | 'busy' | 'stopped' | 'error';
 export type ClaudeMode = 'dangerously-skip-permissions' | 'normal' | 'allowedTools';
 
 /** Session mode: which CLI backend a session runs */
-export type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex';
+export type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini';
 
 /**
  * Valid Claude CLI effort levels (claude >= 2.1.154).
@@ -85,6 +87,16 @@ export interface CodexConfig {
   renderMode?: CodexRenderMode;
 }
 
+/** Gemini CLI session configuration */
+export interface GeminiConfig {
+  /** Model identifier (e.g., "gemini-2.5-pro"). Passed via --model. */
+  model?: string;
+  /** Gemini approval mode for tool calls. */
+  approvalMode?: 'default' | 'auto_edit' | 'yolo' | 'plan';
+  /** Resume a previous Gemini session ("latest", index, or session id). */
+  resumeSession?: string;
+}
+
 /**
  * Configuration for creating a new session
  */
@@ -214,6 +226,8 @@ export interface SessionState {
   openCodeConfig?: OpenCodeConfig;
   /** Codex-specific configuration (only for mode === 'codex') */
   codexConfig?: CodexConfig;
+  /** Gemini-specific configuration (only for mode === 'gemini') */
+  geminiConfig?: GeminiConfig;
   /** Claude conversation session ID to resume after reboot (set by restore script) */
   resumeSessionId?: string;
   /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */

src/utils/gemini-cli-resolver.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Resolve the Gemini CLI binary across common install paths.
+ *
+ * Mirrors codex-cli-resolver.ts and opencode-cli-resolver.ts. Finds the
+ * `gemini` binary and provides an augmented PATH directory for tmux sessions.
+ *
+ * @module utils/gemini-cli-resolver
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+
+/** Common directories where the Gemini CLI binary may be installed */
+const GEMINI_SEARCH_DIRS = [
+  join(homedir(), '.gemini', 'bin'),
+  join(homedir(), '.local', 'bin'),
+  '/usr/local/bin',
+  join(homedir(), '.bun', 'bin'),
+  join(homedir(), '.npm-global', 'bin'),
+  join(homedir(), 'bin'),
+];
+
+/** Cached directory containing the gemini binary (empty string = searched but not found) */
+let _geminiDir: string | null = null;
+
+/**
+ * Finds the directory containing the `gemini` binary.
+ * Checks `which gemini` first, then falls back to common install locations.
+ *
+ * @returns Directory path, or null if not found
+ */
+export function resolveGeminiDir(): string | null {
+  if (_geminiDir !== null) return _geminiDir || null;
+
+  try {
+    const result = execSync('which gemini', {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT_MS,
+    }).trim();
+    if (result && existsSync(result)) {
+      _geminiDir = dirname(result);
+      return _geminiDir;
+    }
+  } catch {
+    // Gemini not in PATH, will check common locations
+  }
+
+  for (const dir of GEMINI_SEARCH_DIRS) {
+    if (existsSync(join(dir, 'gemini'))) {
+      _geminiDir = dir;
+      return _geminiDir;
+    }
+  }
+
+  _geminiDir = '';
+  return null;
+}
+
+/**
+ * Check if Gemini CLI is available on the system.
+ */
+export function isGeminiAvailable(): boolean {
+  return resolveGeminiDir() !== null;
+}

src/utils/index.ts

@@ -29,3 +29,4 @@ export { wrapWithNice } from './nice-wrapper.js';
 export { findClaudeDir, getAugmentedPath } from './claude-cli-resolver.js';
 export { resolveOpenCodeDir } from './opencode-cli-resolver.js';
 export { resolveCodexDir, isCodexAvailable } from './codex-cli-resolver.js';
+export { resolveGeminiDir, isGeminiAvailable } from './gemini-cli-resolver.js';

src/web/away-digest.ts

@@ -0,0 +1,379 @@
+import type { LifecycleEntry, RunSummary, RunSummaryEvent, TokenUsageEntry } from '../types.js';
+
+export type AwayDigestRangeName = 'since-last-visit' | '1h' | 'today' | '24h' | 'custom';
+export type AwayDigestCategory = 'needs_attention' | 'completed' | 'still_running' | 'idle' | 'informational';
+export type AwayDigestSectionName = 'needsAttention' | 'completed' | 'stillRunning' | 'idle' | 'informational';
+export type AwayDigestSeverity = 'info' | 'success' | 'warning' | 'error';
+export type AwayDigestSource = 'lifecycle' | 'run_summary' | 'status' | 'token_stats' | 'subagent';
+export type AwayDigestTokenWindowPrecision = 'day' | 'none';
+
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+const VALID_RANGES = new Set<AwayDigestRangeName>(['since-last-visit', '1h', 'today', '24h', 'custom']);
+
+export interface AwayDigestRange {
+  range: AwayDigestRangeName;
+  since: number;
+  until: number;
+}
+
+export interface AwayDigestRangeInput {
+  range?: string;
+  since?: number;
+  until?: number;
+  lastViewed?: number;
+  now?: number;
+}
+
+export interface AwayDigestSession {
+  id: string;
+  name?: string;
+  status?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  totalCost?: number;
+}
+
+export interface AwayDigestSubagent {
+  id?: string;
+  agentId?: string;
+  sessionId?: string;
+  description?: string;
+  status?: string;
+  lastUpdated?: number;
+  updatedAt?: number;
+  completedAt?: number;
+  modifiedAt?: number;
+  lastActivityAt?: number;
+}
+
+export interface AwayDigestItem {
+  id: string;
+  sessionId?: string;
+  sessionName?: string;
+  timestamp: number;
+  category: AwayDigestCategory;
+  severity: AwayDigestSeverity;
+  title: string;
+  detail?: string;
+  source: AwayDigestSource;
+  link?: {
+    type: 'session' | 'run_summary' | 'lifecycle' | 'notification';
+    sessionId?: string;
+  };
+}
+
+export interface AwayDigestTotals {
+  sessionsCreated: number;
+  sessionsExited: number;
+  activeSessions: number;
+  needsAttention: number;
+  completed: number;
+  errors: number;
+  warnings: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  estimatedCost?: number;
+  tokenWindowPrecision: AwayDigestTokenWindowPrecision;
+}
+
+export interface AwayDigestResponse {
+  range: AwayDigestRange;
+  generatedAt: number;
+  dataFreshness: {
+    lifecyclePersisted: true;
+    tokenStatsPersisted: true;
+    runSummariesLiveOnly: true;
+    subagentsLiveOnly: true;
+  };
+  totals: AwayDigestTotals;
+  sections: Record<AwayDigestSectionName, AwayDigestItem[]>;
+}
+
+export interface AwayDigestInput {
+  range: AwayDigestRange;
+  lifecycleEntries: LifecycleEntry[];
+  runSummaries: RunSummary[];
+  sessions: AwayDigestSession[];
+  dailyTokenStats: TokenUsageEntry[];
+  subagents: AwayDigestSubagent[];
+  now?: number;
+}
+
+export function resolveAwayDigestRange(input: AwayDigestRangeInput): AwayDigestRange {
+  const now = input.now ?? Date.now();
+  const range = (input.range ?? 'since-last-visit') as AwayDigestRangeName;
+  if (!VALID_RANGES.has(range)) {
+    throw new Error(`Invalid away digest range: ${input.range}`);
+  }
+
+  let since: number;
+  const until = finiteOrDefault(input.until, now);
+
+  switch (range) {
+    case 'since-last-visit':
+      since = finiteOrDefault(input.lastViewed, now - DAY_MS);
+      break;
+    case '1h':
+      since = now - HOUR_MS;
+      break;
+    case 'today': {
+      const start = new Date(now);
+      start.setHours(0, 0, 0, 0);
+      since = start.getTime();
+      break;
+    }
+    case '24h':
+      since = now - DAY_MS;
+      break;
+    case 'custom':
+      if (!Number.isFinite(input.since)) {
+        throw new Error('Custom away digest range requires a finite since timestamp');
+      }
+      since = input.since as number;
+      break;
+  }
+
+  if (until < since) {
+    throw new Error('Away digest until timestamp must be greater than or equal to since');
+  }
+
+  return { range, since, until };
+}
+
+export function buildAwayDigest(input: AwayDigestInput): AwayDigestResponse {
+  const now = input.now ?? Date.now();
+  const sections: Record<AwayDigestSectionName, AwayDigestItem[]> = {
+    needsAttention: [],
+    completed: [],
+    stillRunning: [],
+    idle: [],
+    informational: [],
+  };
+
+  const sessionsById = new Map(input.sessions.map((session) => [session.id, session]));
+  const lifecycleEntries = input.lifecycleEntries.filter((entry) => isInRange(entry.ts, input.range));
+
+  for (const entry of lifecycleEntries) {
+    addItem(sections, lifecycleEntryToItem(entry));
+  }
+
+  for (const summary of input.runSummaries) {
+    for (const event of summary.events) {
+      if (!isInRange(event.timestamp, input.range)) continue;
+      addItem(sections, runSummaryEventToItem(summary, event));
+    }
+  }
+
+  for (const session of input.sessions) {
+    const item = sessionToItem(session, now);
+    addItem(sections, item);
+  }
+
+  for (const subagent of input.subagents) {
+    const timestamp = subagentTimestamp(subagent, now);
+    if (!isInRange(timestamp, input.range) || subagent.status !== 'completed') continue;
+    addItem(sections, subagentToItem(subagent, sessionsById, timestamp));
+  }
+
+  const tokenTotals = aggregateTokenStats(input.dailyTokenStats, input.range);
+  const totals = calculateTotals(sections, lifecycleEntries, input.sessions, tokenTotals);
+
+  return {
+    range: input.range,
+    generatedAt: now,
+    dataFreshness: {
+      lifecyclePersisted: true,
+      tokenStatsPersisted: true,
+      runSummariesLiveOnly: true,
+      subagentsLiveOnly: true,
+    },
+    totals,
+    sections,
+  };
+}
+
+function finiteOrDefault(value: number | undefined, fallback: number): number {
+  return Number.isFinite(value) ? (value as number) : fallback;
+}
+
+function isInRange(timestamp: number, range: AwayDigestRange): boolean {
+  return timestamp >= range.since && timestamp <= range.until;
+}
+
+function addItem(sections: Record<AwayDigestSectionName, AwayDigestItem[]>, item: AwayDigestItem): void {
+  sections[sectionNameForCategory(item.category)].push(item);
+}
+
+function sectionNameForCategory(category: AwayDigestCategory): AwayDigestSectionName {
+  switch (category) {
+    case 'needs_attention':
+      return 'needsAttention';
+    case 'still_running':
+      return 'stillRunning';
+    case 'completed':
+    case 'idle':
+    case 'informational':
+      return category;
+  }
+}
+
+function lifecycleEntryToItem(entry: LifecycleEntry): AwayDigestItem {
+  const needsAttention = entry.event === 'mux_died' || (entry.event === 'exit' && (entry.exitCode ?? 0) !== 0);
+  return {
+    id: `lifecycle-${entry.ts}-${entry.event}-${entry.sessionId}`,
+    sessionId: entry.sessionId,
+    sessionName: entry.name,
+    timestamp: entry.ts,
+    category: needsAttention ? 'needs_attention' : 'informational',
+    severity: needsAttention ? 'error' : entry.event === 'exit' ? 'info' : 'info',
+    title: lifecycleTitle(entry),
+    detail: lifecycleDetail(entry),
+    source: 'lifecycle',
+    link: { type: 'lifecycle', sessionId: entry.sessionId },
+  };
+}
+
+function lifecycleTitle(entry: LifecycleEntry): string {
+  if (entry.event === 'exit') {
+    return (entry.exitCode ?? 0) === 0 ? 'Session exited' : 'Session exited with error';
+  }
+  if (entry.event === 'mux_died') return 'Tmux session died';
+  return `Session ${entry.event.replaceAll('_', ' ')}`;
+}
+
+function lifecycleDetail(entry: LifecycleEntry): string | undefined {
+  if (entry.reason) return entry.reason;
+  if (entry.event === 'exit' && entry.exitCode !== undefined && entry.exitCode !== null) {
+    return `Exit code ${entry.exitCode}`;
+  }
+  return undefined;
+}
+
+function runSummaryEventToItem(summary: RunSummary, event: RunSummaryEvent): AwayDigestItem {
+  const category = runSummaryCategory(event);
+  return {
+    id: `run-summary-${summary.sessionId}-${event.id}`,
+    sessionId: summary.sessionId,
+    sessionName: summary.sessionName,
+    timestamp: event.timestamp,
+    category,
+    severity: runSummarySeverity(event, category),
+    title: event.title,
+    detail: event.details,
+    source: 'run_summary',
+    link: { type: 'run_summary', sessionId: summary.sessionId },
+  };
+}
+
+function runSummaryCategory(event: RunSummaryEvent): AwayDigestCategory {
+  if (event.type === 'ralph_completion') return 'completed';
+  if (event.severity === 'error' || event.severity === 'warning' || event.type === 'state_stuck') {
+    return 'needs_attention';
+  }
+  return 'informational';
+}
+
+function runSummarySeverity(event: RunSummaryEvent, category: AwayDigestCategory): AwayDigestSeverity {
+  if (category === 'completed') return 'success';
+  return event.severity;
+}
+
+function sessionToItem(session: AwayDigestSession, now: number): AwayDigestItem {
+  const isIdle = session.status === 'idle';
+  return {
+    id: `status-${session.id}`,
+    sessionId: session.id,
+    sessionName: session.name,
+    timestamp: now,
+    category: isIdle ? 'idle' : 'still_running',
+    severity: isIdle ? 'info' : 'success',
+    title: isIdle ? 'Session idle' : 'Session still running',
+    detail: session.status ? `Status: ${session.status}` : undefined,
+    source: 'status',
+    link: { type: 'session', sessionId: session.id },
+  };
+}
+
+function subagentToItem(
+  subagent: AwayDigestSubagent,
+  sessionsById: Map<string, AwayDigestSession>,
+  timestamp: number
+): AwayDigestItem {
+  const session = subagent.sessionId ? sessionsById.get(subagent.sessionId) : undefined;
+  const agentId = subagent.id ?? subagent.agentId ?? 'unknown';
+  return {
+    id: `subagent-${agentId}`,
+    sessionId: subagent.sessionId,
+    sessionName: session?.name,
+    timestamp,
+    category: 'informational',
+    severity: 'success',
+    title: 'Subagent completed',
+    detail: subagent.description,
+    source: 'subagent',
+    link: subagent.sessionId ? { type: 'session', sessionId: subagent.sessionId } : undefined,
+  };
+}
+
+function subagentTimestamp(subagent: AwayDigestSubagent, fallback: number): number {
+  return (
+    subagent.completedAt ??
+    subagent.lastUpdated ??
+    subagent.updatedAt ??
+    subagent.modifiedAt ??
+    subagent.lastActivityAt ??
+    fallback
+  );
+}
+
+function aggregateTokenStats(
+  dailyTokenStats: TokenUsageEntry[],
+  range: AwayDigestRange
+): { inputTokens: number; outputTokens: number; estimatedCost: number; precision: AwayDigestTokenWindowPrecision } {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let estimatedCost = 0;
+
+  for (const day of dailyTokenStats) {
+    if (!dayOverlapsRange(day.date, range)) continue;
+    inputTokens += day.inputTokens;
+    outputTokens += day.outputTokens;
+    estimatedCost += day.estimatedCost;
+  }
+
+  return {
+    inputTokens,
+    outputTokens,
+    estimatedCost,
+    precision: inputTokens > 0 || outputTokens > 0 || estimatedCost > 0 ? 'day' : 'none',
+  };
+}
+
+function dayOverlapsRange(date: string, range: AwayDigestRange): boolean {
+  const dayStart = new Date(`${date}T00:00:00`).getTime();
+  const dayEnd = dayStart + DAY_MS - 1;
+  return dayStart <= range.until && dayEnd >= range.since;
+}
+
+function calculateTotals(
+  sections: Record<AwayDigestSectionName, AwayDigestItem[]>,
+  lifecycleEntries: LifecycleEntry[],
+  sessions: AwayDigestSession[],
+  tokenTotals: ReturnType<typeof aggregateTokenStats>
+): AwayDigestTotals {
+  const allItems = Object.values(sections).flat();
+  return {
+    sessionsCreated: lifecycleEntries.filter((entry) => entry.event === 'created').length,
+    sessionsExited: lifecycleEntries.filter((entry) => entry.event === 'exit').length,
+    activeSessions: sessions.length,
+    needsAttention: sections.needsAttention.length,
+    completed: sections.completed.length,
+    errors: allItems.filter((item) => item.severity === 'error').length,
+    warnings: allItems.filter((item) => item.severity === 'warning').length,
+    inputTokens: tokenTotals.inputTokens,
+    outputTokens: tokenTotals.outputTokens,
+    estimatedCost: tokenTotals.estimatedCost,
+    tokenWindowPrecision: tokenTotals.precision,
+  };
+}

src/web/ports/config-port.ts

@@ -5,6 +5,7 @@
 
 import type { ClaudeMode, NiceConfig } from '../../types.js';
 import type { StateStore } from '../../state-store.js';
+import type { TerminalHistoryConfig } from '../../config/terminal-history.js';
 
 export interface ConfigPort {
   readonly store: StateStore;
@@ -15,6 +16,7 @@ export interface ConfigPort {
   getGlobalNiceConfig(): Promise<NiceConfig | undefined>;
   getModelConfig(): Promise<{ defaultModel?: string; agentTypeOverrides?: Record<string, string> } | null>;
   getClaudeModeConfig(): Promise<{ claudeMode?: ClaudeMode; allowedTools?: string }>;
+  getTerminalHistoryConfig(): Promise<TerminalHistoryConfig>;
   getDefaultClaudeMdPath(): Promise<string | undefined>;
   getLightState(): unknown;
   getLightSessionsState(): unknown[];

src/web/public/app.js

@@ -2358,26 +2358,27 @@ class CodemanApp {
     const text = this.$('connectionText');
     if (!indicator || !dot || !text) return;
 
-    const { bytes: totalBytes, count } = this._pendingBytes();
     const status = this._connectionStatus;
-    const hasQueue = count > 0;
 
-    // Connected with empty queue — hide
-    if ((status === 'connected' || status === 'connecting') && !hasQueue) {
+    // While the connection is healthy, never surface the input queue. With the
+    // reliable-delivery layer every keystroke is briefly "pending" until its ACK
+    // lands a few ms later — showing that flashed "Sending 1B…" on every single
+    // character. The indicator is only meaningful for an actual connection
+    // problem (reconnecting / offline), where the queued byte count reassures
+    // the user their typing is safely buffered and will be sent.
+    if (status === 'connected' || status === 'connecting') {
       indicator.style.display = 'none';
       return;
     }
 
+    const { bytes: totalBytes, count } = this._pendingBytes();
+    const hasQueue = count > 0;
     indicator.style.display = 'flex';
     dot.className = 'connection-dot';
 
-    const formatBytes = (b) => b < 1024 ? `${b}B` : `${(b / 1024).toFixed(1)}KB`;
+    const formatBytes = (b) => (b < 1024 ? `${b}B` : `${(b / 1024).toFixed(1)}KB`);
 
-    if (status === 'connected' && hasQueue) {
-      // Draining
-      dot.classList.add('draining');
-      text.textContent = `Sending ${formatBytes(totalBytes)}...`;
-    } else if (status === 'reconnecting') {
+    if (status === 'reconnecting') {
       dot.classList.add('reconnecting');
       text.textContent = hasQueue ? `Reconnecting (${formatBytes(totalBytes)} queued)` : 'Reconnecting...';
     } else {
@@ -3003,7 +3004,7 @@ class CodemanApp {
           <span class="tab-status ${status}" aria-hidden="true"></span>
           <span class="tab-info">
             <span class="tab-name-row">
-              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : mode === 'codex' ? '<span class="tab-mode codex" aria-hidden="true">cx</span>' : ''}
+              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : mode === 'codex' ? '<span class="tab-mode codex" aria-hidden="true">cx</span>' : mode === 'gemini' ? '<span class="tab-mode gemini" aria-hidden="true">gm</span>' : ''}
               <span class="tab-name" data-session-id="${id}">${(() => { const p = parseSessionPrefix(name); return p && p.suffix ? '<span class="tab-prefix">' + escapeHtml(p.prefix) + '</span><span class="tab-suffix">: ' + escapeHtml(p.suffix) + '</span>' : escapeHtml(name); })()}</span>
               <span class="tab-detached-badge" aria-hidden="true">detached</span>
             </span>
@@ -3869,6 +3870,17 @@ class CodemanApp {
       _crashDiag.log('FOCUS');
       if (shouldFocusTerminal && this.terminal) this.terminal.focus();
       this.scrollToLastNonEmptyLine();
+      // If we switched INTO this tab while the soft keyboard is already up, no
+      // viewport-resize transition fires (handleViewportResize only runs
+      // onKeyboardShow on a hidden→visible change), so the newly-active
+      // session never gets that heal: fit() + scrollToBottom() + local-echo
+      // overlay rerender() + one-shot SIGWINCH. Without it the overlay renders
+      // against stale, off-bottom state and typed input stays INVISIBLE until
+      // the user manually toggles the keyboard. Replicate the heal here so
+      // local echo paints on the first keystroke after a keyboard-up tab switch.
+      if (typeof KeyboardHandler !== 'undefined' && KeyboardHandler.keyboardVisible) {
+        KeyboardHandler.onKeyboardShow();
+      }
       this._clearTerminalLoadState(sessionId, selectGen);
       _crashDiag.log(`SELECT_DONE: ${(performance.now() - _selStart).toFixed(0)}ms`);
       console.log(`[CRASH-DIAG] selectSession DONE: ${sessionId.slice(0,8)} in ${(performance.now() - _selStart).toFixed(0)}ms`);
@@ -3987,7 +3999,9 @@ class CodemanApp {
         ? 'Kill Tmux & OpenCode'
         : session.mode === 'codex'
           ? 'Kill Tmux & Codex'
-          : 'Kill Tmux & Claude Code';
+          : session.mode === 'gemini'
+            ? 'Kill Tmux & Gemini'
+            : 'Kill Tmux & Claude Code';
     }
 
     document.getElementById('closeConfirmModal').classList.add('active');

src/web/public/index.html

@@ -118,6 +118,7 @@
         </div>
         <button class="btn-icon-header btn-redraw-terminal btn-redraw-terminal--hidden" onclick="app.restoreTerminalSize()" title="Redraw terminal to fit current screen (Ctrl+Shift+R)" aria-label="Redraw terminal"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="1 4 1 10 7 10"/><polyline points="23 20 23 14 17 14"/><path d="M20.49 9A9 9 0 0 0 5.64 5.64L1 10m22 4l-4.64 4.36A9 9 0 0 1 3.51 15"/></svg></button>
         <button class="btn-icon-header btn-response-viewer-header btn-response-viewer-header--hidden" onclick="app.toggleResponseViewer()" title="View last response" aria-label="View last response"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg></button>
+        <button class="btn-icon-header btn-away-digest" onclick="app.openAwayDigest()" title="Away Digest" aria-label="Open away digest"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M8 6h13"/><path d="M8 12h13"/><path d="M8 18h13"/><path d="M3 6h.01"/><path d="M3 12h.01"/><path d="M3 18h.01"/></svg></button>
         <button class="btn-icon-header btn-attachments-history btn-attachments-history--hidden" id="attachmentsHistoryBtn" onclick="app.toggleAttachmentHistory()" title="Attachments" aria-label="Open attachment history" aria-expanded="false">
           <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>
           <span class="attachment-history-badge" id="attachmentHistoryBadge" style="display:none;">0</span>
@@ -305,13 +306,56 @@
               <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
               Run OpenCode
             </button>
+            <button class="welcome-btn welcome-btn-gemini" onclick="app.setRunMode('gemini'); app.runGemini()">
+              <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
+              Run Gemini
+            </button>
           </div>
           <div class="welcome-qr" id="welcomeQr" onclick="app.toggleWelcomeQrSize()">
             <div class="welcome-qr-inner" id="welcomeQrInner"></div>
             <div class="welcome-qr-url" id="welcomeQrUrl"></div>
           </div>
           <div class="history-sessions" id="historySessions" style="display:none">
-            <h3 class="history-title">Resume Conversation</h3>
+            <div class="search-panel" id="searchPanel">
+              <div class="search-input-row">
+                <input
+                  type="search"
+                  id="searchInput"
+                  class="search-input"
+                  placeholder="Search sessions, events, files…"
+                  autocomplete="off"
+                  spellcheck="false"
+                  maxlength="200"
+                  aria-label="Search across sessions"
+                />
+                <button type="button" id="searchClearBtn" class="search-clear-btn" aria-label="Clear search" hidden>×</button>
+              </div>
+              <div class="search-filters" id="searchFilters">
+                <div class="search-filter-group" role="group" aria-label="Source type filter">
+                  <button type="button" class="search-filter-chip active" data-type-filter="session">Sessions</button>
+                  <button type="button" class="search-filter-chip active" data-type-filter="event">Events</button>
+                  <button type="button" class="search-filter-chip active" data-type-filter="file">Files</button>
+                </div>
+                <div class="search-filter-group search-filter-secondary">
+                  <select id="searchCaseFilter" class="search-select" aria-label="Filter by case">
+                    <option value="">All cases</option>
+                  </select>
+                  <select id="searchStatusFilter" class="search-select" aria-label="Filter by session status">
+                    <option value="">Any status</option>
+                    <option value="active">Active</option>
+                    <option value="history">History</option>
+                  </select>
+                  <select id="searchDateFilter" class="search-select" aria-label="Filter by date range">
+                    <option value="">Any time</option>
+                    <option value="1">Past 24h</option>
+                    <option value="7">Past 7 days</option>
+                    <option value="30">Past 30 days</option>
+                  </select>
+                </div>
+              </div>
+              <div class="search-results" id="searchResults" hidden></div>
+            </div>
+            <h3 class="history-title" id="historyTitle">Resume Conversation</h3>
             <div class="history-list" id="historyList"></div>
           </div>
           <p class="welcome-hint">Or press <kbd>Ctrl</kbd>+<kbd>Enter</kbd> to start</p>
@@ -400,6 +444,9 @@
               <button class="run-mode-option" data-mode="codex" onclick="app.setRunMode('codex')">
                 <span class="run-mode-dot codex"></span>Codex
               </button>
+              <button class="run-mode-option" data-mode="gemini" onclick="app.setRunMode('gemini')">
+                <span class="run-mode-dot gemini"></span>Gemini
+              </button>
               <div class="run-mode-sep"></div>
               <div class="run-mode-header">Recent Sessions</div>
               <div class="run-mode-history" id="runModeHistory"></div>
@@ -1863,6 +1910,44 @@
       <div class="notif-drawer-empty" id="notifEmpty">No notifications</div>
     </div>
 
+    <!-- Away Digest Modal -->
+    <div class="modal" id="awayDigestModal">
+      <div class="modal-backdrop" onclick="app.closeAwayDigest()"></div>
+      <div class="modal-content away-digest-modal">
+        <div class="modal-header">
+          <h3>Away Digest</h3>
+          <div class="modal-header-actions">
+            <button class="btn-toolbar btn-sm" onclick="app.loadAwayDigest()" title="Refresh away digest">&#x21BB; Refresh</button>
+            <button class="modal-close" onclick="app.closeAwayDigest()" aria-label="Close away digest">&times;</button>
+          </div>
+        </div>
+        <div class="modal-body">
+          <div class="away-digest-ranges" role="group" aria-label="Away digest range">
+            <button class="filter-btn active" data-away-range="since-last-visit" onclick="app.setAwayDigestRange('since-last-visit')">Since last visit</button>
+            <button class="filter-btn" data-away-range="1h" onclick="app.setAwayDigestRange('1h')">Last hour</button>
+            <button class="filter-btn" data-away-range="today" onclick="app.setAwayDigestRange('today')">Today</button>
+            <button class="filter-btn" data-away-range="24h" onclick="app.setAwayDigestRange('24h')">24h</button>
+            <button class="filter-btn" data-away-range="custom" onclick="app.setAwayDigestRange('custom')">Custom</button>
+          </div>
+          <div class="away-digest-custom-range" id="awayDigestCustomRange">
+            <label>
+              Since
+              <input type="datetime-local" id="awayDigestCustomSince">
+            </label>
+            <label>
+              Until
+              <input type="datetime-local" id="awayDigestCustomUntil">
+            </label>
+          </div>
+          <div class="away-digest-summary" id="awayDigestSummary"></div>
+          <div class="away-digest-freshness" id="awayDigestFreshness"></div>
+          <div class="away-digest-sections" id="awayDigestSections">
+            <p class="empty-message">Open the digest to load recent activity</p>
+          </div>
+        </div>
+      </div>
+    </div>
+
     <!-- Token Stats Modal -->
     <div class="modal" id="tokenStatsModal">
       <div class="modal-backdrop" onclick="app.closeTokenStats()"></div>

src/web/public/mobile.css

@@ -434,11 +434,14 @@ html.mobile-init .file-browser-panel {
     height: 12px;
   }
 
-  /* Hide header settings gear and lifecycle log on mobile - settings moved to toolbar.
+  /* Hide header settings gear, lifecycle log, and away digest on mobile - settings
+     moved to toolbar; away digest is a secondary informational control that doesn't
+     belong on the cramped phone header.
      (The attachments button is opt-in / default-hidden everywhere via its own
      --hidden marker, so it needs no mobile-specific rule here.) */
   .btn-icon-header.btn-settings,
-  .btn-icon-header.btn-lifecycle-log {
+  .btn-icon-header.btn-lifecycle-log,
+  .btn-icon-header.btn-away-digest {
     display: none !important;
   }
 
@@ -777,6 +780,20 @@ html.mobile-init .file-browser-panel {
     border-color: rgba(16, 185, 129, 0.5);
   }
 
+  /* Gemini mode colors on mobile */
+  .btn-toolbar.btn-run.mode-gemini,
+  .btn-toolbar.btn-run-gear.mode-gemini {
+    background: #10243f;
+    border-color: rgba(96, 165, 250, 0.3);
+    color: #dbeafe;
+  }
+
+  .btn-toolbar.btn-run.mode-gemini:active,
+  .btn-toolbar.btn-run-gear.mode-gemini:active {
+    background: #174ea6;
+    border-color: rgba(96, 165, 250, 0.5);
+  }
+
   /* Run mode dropdown menu — positioned above toolbar on mobile */
   .run-mode-menu {
     bottom: 100%;
@@ -1163,6 +1180,44 @@ html.mobile-init .file-browser-panel {
     -webkit-overflow-scrolling: touch;
   }
 
+  .away-digest-modal {
+    width: 100%;
+    max-width: 100%;
+    height: 100%;
+    max-height: 100%;
+  }
+
+  .away-digest-ranges {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 0.4rem;
+  }
+
+  .away-digest-ranges .filter-btn {
+    min-height: 38px;
+    padding: 0.4rem 0.5rem;
+  }
+
+  .away-digest-custom-range,
+  .away-digest-custom-range.active {
+    grid-template-columns: 1fr;
+  }
+
+  .away-digest-summary {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 0.5rem;
+  }
+
+  .away-digest-item {
+    grid-template-columns: 1fr;
+    gap: 0.5rem;
+  }
+
+  .away-digest-action {
+    width: 100%;
+    min-height: 38px;
+  }
+
   .modal-footer,
   .form-actions {
     padding: 0.75rem 1rem;

src/web/public/panels-ui.js

@@ -13,6 +13,15 @@
  * @loadorder 11 of 15 — loaded after settings-ui.js, before session-ui.js
  */
 
+const AWAY_DIGEST_LAST_VIEWED_KEY = 'codeman-away-digest-last-viewed';
+const AWAY_DIGEST_SECTIONS = [
+  ['needsAttention', 'Needs Attention'],
+  ['completed', 'Completed'],
+  ['stillRunning', 'Still Running'],
+  ['idle', 'Idle'],
+  ['informational', 'Informational'],
+];
+
 Object.assign(CodemanApp.prototype, {
   _addActivityEntry(agentId, entry, maxSize = 50) {
     const activity = this.subagentActivity.get(agentId) || [];
@@ -242,6 +251,271 @@ Object.assign(CodemanApp.prototype, {
   },
 
 
+  // ═══════════════════════════════════════════════════════════════
+  // Away Digest Modal
+  // ═══════════════════════════════════════════════════════════════
+
+  async openAwayDigest(range = 'since-last-visit') {
+    this.awayDigestRange = range;
+    this._awayDigestLoadedSuccessfully = false;
+    this._awayDigestSinceLastVisitGeneratedAt = undefined;
+    const modal = document.getElementById('awayDigestModal');
+    if (modal) modal.classList.add('active');
+    this.updateAwayDigestRangeControls();
+    await this.loadAwayDigest();
+  },
+
+  closeAwayDigest() {
+    const modal = document.getElementById('awayDigestModal');
+    const generatedAt = this._awayDigestSinceLastVisitGeneratedAt;
+    if (Number.isFinite(generatedAt)) {
+      try {
+        localStorage.setItem(AWAY_DIGEST_LAST_VIEWED_KEY, String(generatedAt));
+      } catch (err) {
+        console.warn('Failed to save away digest last-viewed marker:', err);
+      }
+    }
+    if (modal) modal.classList.remove('active');
+  },
+
+  setAwayDigestRange(range) {
+    this.awayDigestRange = range;
+    this._awayDigestLoadedSuccessfully = false;
+    this.updateAwayDigestRangeControls();
+    this.loadAwayDigest();
+  },
+
+  updateAwayDigestRangeControls() {
+    const range = this.awayDigestRange || 'since-last-visit';
+    document.querySelectorAll('[data-away-range]').forEach(btn => {
+      btn.classList.toggle('active', btn.dataset.awayRange === range);
+    });
+    const customRange = document.getElementById('awayDigestCustomRange');
+    if (customRange) customRange.classList.toggle('active', range === 'custom');
+    if (range === 'custom') this.ensureAwayDigestCustomDefaults();
+  },
+
+  ensureAwayDigestCustomDefaults() {
+    const sinceInput = document.getElementById('awayDigestCustomSince');
+    const untilInput = document.getElementById('awayDigestCustomUntil');
+    if (!sinceInput || !untilInput) return;
+
+    const now = new Date();
+    if (!untilInput.value) untilInput.value = this.formatAwayDigestDateTimeLocal(now);
+    if (!sinceInput.value) {
+      const since = new Date(now.getTime() - 60 * 60 * 1000);
+      sinceInput.value = this.formatAwayDigestDateTimeLocal(since);
+    }
+  },
+
+  formatAwayDigestDateTimeLocal(date) {
+    const pad = value => String(value).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
+  },
+
+  async loadAwayDigest() {
+    const summaryEl = document.getElementById('awayDigestSummary');
+    const freshnessEl = document.getElementById('awayDigestFreshness');
+    const sectionsEl = document.getElementById('awayDigestSections');
+    if (summaryEl) summaryEl.innerHTML = '<div class="away-digest-loading">Loading digest...</div>';
+    if (freshnessEl) freshnessEl.textContent = '';
+    if (sectionsEl) sectionsEl.innerHTML = '';
+
+    try {
+      const range = this.awayDigestRange || 'since-last-visit';
+      const params = new URLSearchParams({ range });
+
+      if (range === 'since-last-visit') {
+        const lastViewed = this.readAwayDigestLastViewed();
+        if (Number.isFinite(lastViewed)) params.set('lastViewed', String(lastViewed));
+      }
+
+      if (range === 'custom') {
+        this.ensureAwayDigestCustomDefaults();
+        const since = this.readAwayDigestDateTimeInput('awayDigestCustomSince');
+        const until = this.readAwayDigestDateTimeInput('awayDigestCustomUntil');
+        if (!Number.isFinite(since)) {
+          throw new Error('Choose a custom start time');
+        }
+        params.set('since', String(since));
+        if (Number.isFinite(until)) params.set('until', String(until));
+      }
+
+      const response = await fetch(`/api/away-digest?${params.toString()}`);
+      const data = await response.json();
+      if (!response.ok || !data.success) {
+        throw new Error(data.error || 'Failed to load away digest');
+      }
+
+      this._awayDigestLoadedSuccessfully = true;
+      this._awayDigestGeneratedAt = data.digest.generatedAt;
+      if (range === 'since-last-visit') {
+        this._awayDigestSinceLastVisitGeneratedAt = data.digest.generatedAt;
+      }
+      this.renderAwayDigest(data.digest);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to load away digest';
+      console.error('Failed to fetch away digest:', err);
+      if (summaryEl) summaryEl.innerHTML = '<div class="away-digest-load-error">Failed to load away digest</div>';
+      if (sectionsEl) {
+        sectionsEl.innerHTML = `<div class="empty-message">${escapeHtml(message)}</div>`;
+      }
+      this.showToast(message, 'error');
+    }
+  },
+
+  readAwayDigestLastViewed() {
+    try {
+      const value = localStorage.getItem(AWAY_DIGEST_LAST_VIEWED_KEY);
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : undefined;
+    } catch {
+      return undefined;
+    }
+  },
+
+  readAwayDigestDateTimeInput(id) {
+    const input = document.getElementById(id);
+    if (!input || !input.value) return undefined;
+    const parsed = Date.parse(input.value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  },
+
+  renderAwayDigest(digest) {
+    const summaryEl = document.getElementById('awayDigestSummary');
+    const freshnessEl = document.getElementById('awayDigestFreshness');
+    const sectionsEl = document.getElementById('awayDigestSections');
+    if (!summaryEl || !freshnessEl || !sectionsEl) return;
+
+    const inputTokens = digest.totals.inputTokens || 0;
+    const outputTokens = digest.totals.outputTokens || 0;
+    const estimatedCost = digest.totals.estimatedCost || 0;
+    summaryEl.innerHTML = `
+      <div class="away-digest-card">
+        <span class="away-digest-card-label">Needs Attention</span>
+        <span class="away-digest-card-value">${digest.totals.needsAttention}</span>
+      </div>
+      <div class="away-digest-card">
+        <span class="away-digest-card-label">Completed</span>
+        <span class="away-digest-card-value">${digest.totals.completed}</span>
+      </div>
+      <div class="away-digest-card">
+        <span class="away-digest-card-label">Active Sessions</span>
+        <span class="away-digest-card-value">${digest.totals.activeSessions}</span>
+      </div>
+      <div class="away-digest-card">
+        <span class="away-digest-card-label">Tokens</span>
+        <span class="away-digest-card-value">${this.formatTokens(inputTokens + outputTokens)}</span>
+        <span class="away-digest-card-cost">~$${estimatedCost.toFixed(2)}</span>
+      </div>
+    `;
+
+    const freshnessNotes = [];
+    if (digest.dataFreshness.runSummariesLiveOnly || digest.dataFreshness.subagentsLiveOnly) {
+      freshnessNotes.push('Run summaries and subagent completions use recent live state; lifecycle and token stats are persisted.');
+    }
+    if (digest.totals.tokenWindowPrecision === 'day') {
+      freshnessNotes.push('Token totals are aggregated at day precision.');
+    }
+    freshnessEl.textContent = freshnessNotes.join(' ');
+
+    sectionsEl.innerHTML = AWAY_DIGEST_SECTIONS
+      .map(([key, title]) => this.renderAwayDigestSection(title, digest.sections[key] || []))
+      .join('');
+    this.attachAwayDigestActions();
+  },
+
+  renderAwayDigestSection(title, items) {
+    const count = items.length;
+    const body = count
+      ? items.map(item => this.renderAwayDigestItem(item)).join('')
+      : '<div class="away-digest-empty">No items</div>';
+    return `
+      <section class="away-digest-section">
+        <div class="away-digest-section-title">
+          <h4>${escapeHtml(title)}</h4>
+          <span>${count}</span>
+        </div>
+        ${body}
+      </section>
+    `;
+  },
+
+  renderAwayDigestItem(item) {
+    const sourceLabel = this.formatAwayDigestSource(item.source);
+    const sessionLabel = item.sessionName || item.sessionId || '';
+    const detail = item.detail ? `<div class="away-digest-item-detail">${escapeHtml(item.detail)}</div>` : '';
+    const action = item.link ? `
+      <button class="away-digest-action"
+              data-away-link-type="${escapeHtml(item.link.type)}"
+              data-away-session-id="${escapeHtml(item.link.sessionId || '')}">
+        Open
+      </button>
+    ` : '';
+    return `
+      <article class="away-digest-item away-digest-${escapeHtml(item.severity)}">
+        <div class="away-digest-item-main">
+          <div class="away-digest-item-meta">
+            <span>${escapeHtml(this.formatAwayDigestTimestamp(item.timestamp))}</span>
+            <span>${escapeHtml(sourceLabel)}</span>
+            ${sessionLabel ? `<span>${escapeHtml(sessionLabel)}</span>` : ''}
+          </div>
+          <div class="away-digest-item-title">${escapeHtml(item.title)}</div>
+          ${detail}
+        </div>
+        ${action}
+      </article>
+    `;
+  },
+
+  attachAwayDigestActions() {
+    const sectionsEl = document.getElementById('awayDigestSections');
+    if (!sectionsEl) return;
+    sectionsEl.querySelectorAll('[data-away-link-type]').forEach(button => {
+      button.addEventListener('click', () => {
+        this.openAwayDigestItem(button.dataset.awayLinkType, button.dataset.awaySessionId || undefined);
+      });
+    });
+  },
+
+  async openAwayDigestItem(type, sessionId) {
+    if (type === 'session' && sessionId) {
+      await this.selectSession(sessionId);
+      this.closeAwayDigest();
+      return;
+    }
+    if (type === 'run_summary' && sessionId) {
+      await this.openRunSummary(sessionId);
+      this.closeAwayDigest();
+      return;
+    }
+    if (type === 'lifecycle') {
+      this.openLifecycleLog();
+      this.closeAwayDigest();
+    }
+  },
+
+  formatAwayDigestTimestamp(timestamp) {
+    if (!Number.isFinite(timestamp)) return '';
+    return new Date(timestamp).toLocaleString([], {
+      month: 'short',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: '2-digit',
+    });
+  },
+
+  formatAwayDigestSource(source) {
+    const labels = {
+      lifecycle: 'Lifecycle',
+      run_summary: 'Run Summary',
+      status: 'Status',
+      token_stats: 'Token Stats',
+      subagent: 'Subagent',
+    };
+    return labels[source] || source;
+  },
+
   // ═══════════════════════════════════════════════════════════════
   // Token Statistics Modal
   // ═══════════════════════════════════════════════════════════════

src/web/public/session-ui.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Quick start (case loading, session spawning for Claude/Shell/OpenCode),
+ * @fileoverview Quick start (case loading, session spawning for Claude/Shell/OpenCode/Codex/Gemini),
  * session options modal (per-session settings, color picker, rename),
  * session options tabs (Ralph config tab), case settings (CRUD, links),
  * create case modal, and mobile case picker.
@@ -151,7 +151,7 @@ Object.assign(CodemanApp.prototype, {
     return this.run();
   },
 
-  /** Run using the selected mode (Claude Code, OpenCode, or Codex) */
+  /** Run using the selected mode (Claude Code, OpenCode, Codex, or Gemini) */
   async run() {
     const mode = this._runMode || 'claude';
     if (mode === 'opencode') {
@@ -160,6 +160,9 @@ Object.assign(CodemanApp.prototype, {
     if (mode === 'codex') {
       return this.runCodex();
     }
+    if (mode === 'gemini') {
+      return this.runGemini();
+    }
     return this.runClaude();
   },
 
@@ -257,7 +260,7 @@ Object.assign(CodemanApp.prototype, {
       gearBtn.className = `btn-toolbar btn-run-gear mode-${mode}`;
     }
     if (label) {
-      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : 'Run';
+      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : mode === 'gemini' ? 'Run GM' : 'Run';
     }
   },
 
@@ -640,6 +643,47 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  async runGemini() {
+    const caseName = document.getElementById('quickStartCase').value || 'testcase';
+
+    this.terminal.clear();
+    this.terminal.writeln(`\x1b[1;32m Starting Gemini session in ${caseName}...\x1b[0m`);
+    this.terminal.writeln('');
+    this.terminal.focus();
+
+    try {
+      const statusRes = await fetch('/api/gemini/status');
+      const status = (await statusRes.json()).data;
+      if (!status.available) {
+        this.terminal.writeln('\x1b[1;31m Gemini CLI not found.\x1b[0m');
+        this.terminal.writeln('\x1b[90m Install with: npm install -g @google/gemini-cli\x1b[0m');
+        return;
+      }
+
+      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), this.loadAppSettingsFromStorage());
+      const res = await fetch('/api/quick-start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          caseName,
+          mode: 'gemini',
+          geminiConfig: { approvalMode: 'yolo' },
+          ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
+        })
+      });
+      const data = await res.json();
+      if (!data.success) throw new Error(data.error || 'Failed to start Gemini');
+
+      if (data.data.sessionId) {
+        await this.selectSession(data.data.sessionId);
+      }
+
+      this.terminal.focus();
+    } catch (err) {
+      this.terminal.writeln(`\x1b[1;31m Error: ${err.message}\x1b[0m`);
+    }
+  },
+
 
   // ═══════════════════════════════════════════════════════════════
   // Session Options Modal
@@ -651,8 +695,9 @@ Object.assign(CodemanApp.prototype, {
 
     this.editingSessionId = sessionId;
 
-    // Reset to an appropriate tab — Summary for OpenCode (Respawn/Ralph are Claude-only)
-    this.switchOptionsTab(session.mode === 'opencode' || session.mode === 'codex' ? 'summary' : 'respawn');
+    // Reset to an appropriate tab — Summary for external CLIs (Respawn/Ralph are Claude-only)
+    const isAltMode = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini';
+    this.switchOptionsTab(isAltMode ? 'summary' : 'respawn');
 
     // Update respawn status display and buttons
     const respawnStatus = document.getElementById('sessionRespawnStatus');
@@ -680,10 +725,10 @@ Object.assign(CodemanApp.prototype, {
       respawnSection.style.display = 'none';
     }
 
-    // Hide Claude-specific options for OpenCode sessions
-    const isOpenCode = session.mode === 'opencode' || session.mode === 'codex';
+    // Hide Claude-specific options for external CLI sessions
+    const isExternalCli = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini';
     const claudeOnlyEls = document.querySelectorAll('[data-claude-only]');
-    claudeOnlyEls.forEach(el => { el.style.display = isOpenCode ? 'none' : ''; });
+    claudeOnlyEls.forEach(el => { el.style.display = isExternalCli ? 'none' : ''; });
 
     // Reset duration presets to default (unlimited)
     this.selectDurationPreset('');
@@ -731,26 +776,28 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('respawnPresetSelect').value = '';
     document.getElementById('presetDescriptionHint').textContent = '';
 
-    // Hide Ralph/Todo tab and Respawn tab for opencode sessions (not supported)
+    // Hide Ralph/Todo tab and Respawn tab for external CLI sessions (not supported)
     const ralphTabBtn = document.querySelector('#sessionOptionsModal .modal-tab-btn[data-tab="ralph"]');
     const respawnTabBtn = document.querySelector('#sessionOptionsModal .modal-tab-btn[data-tab="respawn"]');
-    if (isOpenCode) {
+    if (isExternalCli) {
       if (ralphTabBtn) ralphTabBtn.style.display = 'none';
       if (respawnTabBtn) respawnTabBtn.style.display = 'none';
-      // Default to Context tab for opencode sessions since Respawn is hidden
+      // Default to Context tab for external CLI sessions since Respawn is hidden
       this.switchOptionsTab('context');
     } else {
       if (ralphTabBtn) ralphTabBtn.style.display = '';
       if (respawnTabBtn) respawnTabBtn.style.display = '';
     }
 
-    // Populate Ralph Wiggum form with current session values (skip for opencode)
-    if (!isOpenCode) {
+    // Populate Ralph Wiggum form with current session values (skip for external CLI sessions)
+    if (!isExternalCli) {
       const ralphState = this.ralphStates.get(sessionId);
       this.populateRalphForm({
         enabled: ralphState?.loop?.enabled ?? session.ralphLoop?.enabled ?? false,
         completionPhrase: ralphState?.loop?.completionPhrase || session.ralphLoop?.completionPhrase || '',
         maxIterations: ralphState?.loop?.maxIterations || session.ralphLoop?.maxIterations || 0,
+        maxTodos: ralphState?.loop?.maxTodos || session.ralphLoop?.maxTodos,
+        todoExpirationMinutes: ralphState?.loop?.todoExpirationMinutes || session.ralphLoop?.todoExpirationMinutes,
       });
     }
 
@@ -1579,6 +1626,7 @@ Object.defineProperty(CodemanApp.prototype, 'runMode', {
     return this._runMode || 'claude';
   },
   set(mode) {
-    this._runMode = mode === 'opencode' || mode === 'codex' || mode === 'claude' ? mode : 'claude';
+    this._runMode =
+      mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'claude' ? mode : 'claude';
   },
 });

src/web/public/styles.css

@@ -1178,6 +1178,11 @@ body.solo-mode .btn-lifecycle-log {
   color: #a855f7;
 }
 
+.session-tab .tab-mode.gemini {
+  background: rgba(138, 180, 248, 0.2);
+  color: #8ab4f8;
+}
+
 /* Timer Banner - Compact */
 .timer-banner {
   display: flex;
@@ -2362,6 +2367,21 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
   transform: translateY(-1px);
 }
 
+.welcome-btn-gemini {
+  background: linear-gradient(135deg, #10243f 0%, #174ea6 55%, #4f46e5 100%);
+  border-color: rgba(96, 165, 250, 0.4);
+  color: #dbeafe;
+  box-shadow: 0 2px 8px rgba(96, 165, 250, 0.16), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+
+.welcome-btn-gemini:hover {
+  background: linear-gradient(135deg, #17345f 0%, #2563eb 55%, #6366f1 100%);
+  box-shadow: 0 4px 20px rgba(96, 165, 250, 0.3), 0 0 40px rgba(99, 102, 241, 0.12), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+  border-color: rgba(147, 197, 253, 0.5);
+  color: #eff6ff;
+  transform: translateY(-1px);
+}
+
 .welcome-btn-tunnel {
   background: linear-gradient(135deg, #221538 0%, #3b1a7a 50%, #6d28d9 100%);
   border-color: rgba(124, 58, 237, 0.4);
@@ -2466,6 +2486,264 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
   max-width: 560px;
 }
 
+/* ── COD-9 cross-session search (folded into the welcome history panel) ── */
+.search-panel {
+  width: 100%;
+  margin-bottom: 0.9rem;
+  text-align: left;
+}
+
+.search-input-row {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.search-input {
+  flex: 1;
+  width: 100%;
+  box-sizing: border-box;
+  padding: 0.55rem 2rem 0.55rem 0.8rem;
+  font-size: 0.85rem;
+  color: var(--text);
+  background: rgba(255, 255, 255, 0.04);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 8px;
+  outline: none;
+  transition: border-color var(--transition-smooth), background var(--transition-smooth);
+}
+
+.search-input:focus {
+  border-color: rgba(59, 130, 246, 0.5);
+  background: rgba(255, 255, 255, 0.06);
+}
+
+.search-input::placeholder {
+  color: var(--text-dim);
+}
+
+.search-clear-btn {
+  position: absolute;
+  right: 0.4rem;
+  top: 50%;
+  transform: translateY(-50%);
+  appearance: none;
+  border: none;
+  background: transparent;
+  color: var(--text-dim);
+  font-size: 1.2rem;
+  line-height: 1;
+  padding: 0.1rem 0.35rem;
+  cursor: pointer;
+  border-radius: 6px;
+}
+
+.search-clear-btn:hover {
+  color: var(--text);
+  background: rgba(255, 255, 255, 0.08);
+}
+
+.search-filters {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin-top: 0.5rem;
+  align-items: center;
+}
+
+.search-filter-group {
+  display: flex;
+  gap: 0.3rem;
+  flex-wrap: wrap;
+}
+
+.search-filter-secondary {
+  margin-left: auto;
+}
+
+.search-filter-chip {
+  appearance: none;
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  background: rgba(255, 255, 255, 0.03);
+  color: var(--text-muted);
+  font-size: 0.68rem;
+  padding: 0.28rem 0.6rem;
+  border-radius: 999px;
+  cursor: pointer;
+  transition: all var(--transition-smooth);
+}
+
+.search-filter-chip:hover {
+  border-color: rgba(59, 130, 246, 0.3);
+  color: var(--text);
+}
+
+.search-filter-chip.active {
+  background: rgba(59, 130, 246, 0.18);
+  border-color: rgba(59, 130, 246, 0.5);
+  color: #cdddff;
+}
+
+.search-select {
+  appearance: none;
+  background: rgba(255, 255, 255, 0.03);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  color: var(--text-muted);
+  font-size: 0.68rem;
+  padding: 0.28rem 0.5rem;
+  border-radius: 6px;
+  cursor: pointer;
+  max-width: 9rem;
+}
+
+.search-select:focus {
+  outline: none;
+  border-color: rgba(59, 130, 246, 0.5);
+}
+
+.search-results {
+  display: flex;
+  flex-direction: column;
+  gap: 0.3rem;
+  margin-top: 0.7rem;
+  max-height: 320px;
+  overflow-y: auto;
+}
+
+.search-results[hidden] {
+  display: none;
+}
+
+.search-group-header {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  margin-top: 0.4rem;
+  padding: 0 0.2rem;
+}
+
+.search-group-header:first-child {
+  margin-top: 0;
+}
+
+.search-group-label {
+  font-size: 0.65rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-dim);
+  font-weight: 600;
+}
+
+.search-group-count {
+  font-size: 0.6rem;
+  color: var(--text-muted);
+  background: rgba(255, 255, 255, 0.06);
+  border-radius: 999px;
+  padding: 0.05rem 0.4rem;
+}
+
+.search-result-card {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  background: rgba(255, 255, 255, 0.03);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  border-radius: 8px;
+  padding: 0.5rem 0.7rem;
+  cursor: pointer;
+  transition: all var(--transition-smooth);
+}
+
+.search-result-card:hover,
+.search-result-card:focus-visible {
+  border-color: rgba(59, 130, 246, 0.35);
+  background: rgba(255, 255, 255, 0.06);
+  outline: none;
+}
+
+.search-result-top {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-width: 0;
+}
+
+.search-result-badge {
+  font-size: 0.58rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  padding: 0.1rem 0.4rem;
+  border-radius: 4px;
+  flex-shrink: 0;
+  font-weight: 600;
+}
+
+.search-badge-session {
+  background: rgba(59, 130, 246, 0.18);
+  color: #9dc0ff;
+}
+
+.search-badge-event {
+  background: rgba(168, 85, 247, 0.18);
+  color: #d4b3ff;
+}
+
+.search-badge-file {
+  background: rgba(34, 197, 94, 0.16);
+  color: #95e6b3;
+}
+
+.search-result-name {
+  flex: 1;
+  min-width: 0;
+  font-size: 0.74rem;
+  color: var(--text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.search-result-time {
+  font-size: 0.65rem;
+  color: var(--text-dim);
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+.search-result-snippet {
+  font-size: 0.7rem;
+  color: var(--text-muted);
+  line-height: 1.35;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  word-break: break-word;
+}
+
+.search-empty,
+.search-truncated {
+  font-size: 0.72rem;
+  color: var(--text-dim);
+  padding: 0.6rem 0.2rem;
+  text-align: left;
+}
+
+.search-truncated {
+  border-top: 1px dashed rgba(255, 255, 255, 0.08);
+  margin-top: 0.3rem;
+  color: var(--text-muted);
+}
+
+@media (max-width: 640px) {
+  .search-filter-secondary {
+    margin-left: 0;
+  }
+  .search-select {
+    max-width: 7rem;
+  }
+}
+
 .history-title {
   font-size: 0.85rem;
   color: var(--text-dim);
@@ -2910,6 +3188,22 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
   color: #e9d5ff;
 }
 
+/* Gemini mode colors */
+.btn-toolbar.btn-run.mode-gemini,
+.btn-toolbar.btn-run-gear.mode-gemini {
+  background: linear-gradient(135deg, #10243f 0%, #174ea6 55%, #4f46e5 100%);
+  border-color: rgba(96, 165, 250, 0.5);
+  color: #dbeafe;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+.btn-toolbar.btn-run.mode-gemini:hover,
+.btn-toolbar.btn-run-gear.mode-gemini:hover {
+  background: linear-gradient(135deg, #17345f 0%, #2563eb 55%, #6366f1 100%);
+  box-shadow: 0 0 12px rgba(96, 165, 250, 0.35), 0 2px 8px rgba(99, 102, 241, 0.2), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+  border-color: rgba(147, 197, 253, 0.6);
+  color: #eff6ff;
+}
+
 /* Dropdown menu */
 .run-mode-menu {
   display: none;
@@ -2963,6 +3257,7 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
 .run-mode-dot.claude { background: #3b82f6; }
 .run-mode-dot.opencode { background: #10b981; }
 .run-mode-dot.codex { background: #a855f7; }
+.run-mode-dot.gemini { background: #8ab4f8; }
 
 .run-mode-sep {
   height: 1px;
@@ -5108,6 +5403,238 @@ kbd {
   color: var(--text);
 }
 
+/* Away Digest Modal */
+.away-digest-modal {
+  max-width: 860px;
+  width: min(92vw, 860px);
+  max-height: 86vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.away-digest-modal .modal-body {
+  overflow-y: auto;
+  padding: 1rem;
+}
+
+.away-digest-ranges {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem;
+  margin-bottom: 0.75rem;
+}
+
+.away-digest-custom-range {
+  display: none;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0.75rem;
+  margin-bottom: 0.75rem;
+  padding: 0.75rem;
+  background: rgba(255, 255, 255, 0.03);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+}
+
+.away-digest-custom-range.active {
+  display: grid;
+}
+
+.away-digest-custom-range label {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+  color: var(--text-muted);
+  font-size: 0.7rem;
+  text-transform: uppercase;
+  letter-spacing: 0.4px;
+}
+
+.away-digest-custom-range input {
+  min-height: 34px;
+  padding: 0.35rem 0.5rem;
+  background: var(--bg-input);
+  border: 1px solid var(--border-light);
+  border-radius: 6px;
+  color: var(--text);
+}
+
+.away-digest-summary {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 0.75rem;
+  margin-bottom: 0.75rem;
+}
+
+.away-digest-card,
+.away-digest-loading,
+.away-digest-load-error {
+  min-height: 74px;
+  padding: 0.75rem;
+  background: rgba(255, 255, 255, 0.03);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+}
+
+.away-digest-loading,
+.away-digest-load-error {
+  grid-column: 1 / -1;
+  display: flex;
+  align-items: center;
+  color: var(--text-dim);
+  font-size: 0.8rem;
+}
+
+.away-digest-load-error {
+  color: var(--red);
+}
+
+.away-digest-card-label {
+  display: block;
+  margin-bottom: 0.25rem;
+  color: var(--text-muted);
+  font-size: 0.65rem;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.away-digest-card-value {
+  display: block;
+  color: var(--text);
+  font-family: 'SF Mono', Monaco, monospace;
+  font-size: 1.2rem;
+  font-weight: 600;
+}
+
+.away-digest-card-cost {
+  display: block;
+  margin-top: 0.15rem;
+  color: var(--accent-hover);
+  font-size: 0.7rem;
+}
+
+.away-digest-freshness {
+  min-height: 18px;
+  margin-bottom: 0.75rem;
+  color: var(--text-muted);
+  font-size: 0.72rem;
+  line-height: 1.4;
+}
+
+.away-digest-sections {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.away-digest-section {
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.away-digest-section-title {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.55rem 0.75rem;
+  background: rgba(255, 255, 255, 0.03);
+  border-bottom: 1px solid var(--border);
+}
+
+.away-digest-section-title h4 {
+  margin: 0;
+  color: var(--text-dim);
+  font-size: 0.72rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.away-digest-section-title span {
+  color: var(--text-muted);
+  font-family: 'SF Mono', Monaco, monospace;
+  font-size: 0.7rem;
+}
+
+.away-digest-item {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 0.75rem;
+  align-items: center;
+  padding: 0.75rem;
+  border-left: 3px solid var(--border-light);
+  border-bottom: 1px solid var(--border);
+}
+
+.away-digest-item:last-child {
+  border-bottom: none;
+}
+
+.away-digest-success {
+  border-left-color: var(--green);
+}
+
+.away-digest-warning {
+  border-left-color: var(--yellow);
+}
+
+.away-digest-error {
+  border-left-color: var(--red);
+}
+
+.away-digest-info {
+  border-left-color: var(--accent);
+}
+
+.away-digest-item-main {
+  min-width: 0;
+}
+
+.away-digest-item-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem 0.55rem;
+  margin-bottom: 0.3rem;
+  color: var(--text-muted);
+  font-size: 0.68rem;
+}
+
+.away-digest-item-title {
+  color: var(--text);
+  font-size: 0.85rem;
+  font-weight: 600;
+  line-height: 1.35;
+}
+
+.away-digest-item-detail {
+  margin-top: 0.25rem;
+  color: var(--text-dim);
+  font-size: 0.76rem;
+  line-height: 1.35;
+}
+
+.away-digest-action {
+  min-height: 32px;
+  padding: 0.35rem 0.7rem;
+  background: transparent;
+  border: 1px solid var(--border-light);
+  border-radius: 6px;
+  color: var(--accent-hover);
+  cursor: pointer;
+  font-size: 0.75rem;
+}
+
+.away-digest-action:hover {
+  background: rgba(59, 130, 246, 0.1);
+  border-color: rgba(96, 165, 250, 0.45);
+}
+
+.away-digest-empty {
+  padding: 0.75rem;
+  color: var(--text-muted);
+  font-size: 0.78rem;
+}
+
 /* Token Stats Modal */
 .token-stats-modal {
   max-width: 560px;

src/web/public/terminal-ui.js

@@ -983,6 +983,7 @@ Object.assign(CodemanApp.prototype, {
       overlay.classList.add('visible');
       this.loadTunnelStatus();
       this.loadHistorySessions();
+      this.initSearchPanel();
     }
     // Home screen has no input target — hide the CJK textarea (activeSessionId
     // is null by the time we get here). Guarded: defined on the app object.
@@ -2253,3 +2254,338 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 });
+
+// ═══════════════════════════════════════════════════════════════
+// COD-9 — Cross-session search (folded into the welcome history panel)
+// Consumes GET /api/search; renders grouped result cards with jump-to actions.
+// ═══════════════════════════════════════════════════════════════
+
+(function (global) {
+  const SEARCH_DEBOUNCE_MS = 250;
+  const SEARCH_LIMIT = 60;
+  const SOURCE_LABELS = { session: 'Sessions', event: 'Events', file: 'Files' };
+
+  /** Human-friendly relative-ish timestamp matching the history panel's style. */
+  function formatSearchTime(ts) {
+    if (!Number.isFinite(ts)) return '';
+    const d = new Date(ts);
+    return (
+      d.toLocaleDateString('en', { month: 'short', day: 'numeric' }) +
+      ' ' +
+      d.toLocaleTimeString('en', { hour: '2-digit', minute: '2-digit', hour12: false })
+    );
+  }
+
+  global.CodemanSearch = { SEARCH_DEBOUNCE_MS, SEARCH_LIMIT, SOURCE_LABELS, formatSearchTime };
+})(window);
+
+Object.assign(CodemanApp.prototype, {
+  /**
+   * Wire up the search box, filter chips, and selects inside the welcome
+   * history panel. Idempotent — safe to call every time the overlay opens.
+   */
+  initSearchPanel() {
+    const input = document.getElementById('searchInput');
+    if (!input || this._searchPanelWired) {
+      // Even when already wired, refresh the case dropdown (cases may have loaded since).
+      if (this._searchPanelWired) this._populateSearchCaseFilter();
+      return;
+    }
+    this._searchPanelWired = true;
+
+    // Active source-type filter set (mirrors the chip .active state → types= param).
+    this._searchTypes = new Set(['session', 'event', 'file']);
+    this._searchSecondary = { caseLabel: '', status: '', days: '' };
+    this._searchDebounceTimer = null;
+    this._searchSeq = 0;
+    this._searchLastData = null;
+
+    const clearBtn = document.getElementById('searchClearBtn');
+    const results = document.getElementById('searchResults');
+
+    input.addEventListener('input', () => {
+      if (clearBtn) clearBtn.hidden = input.value.length === 0;
+      this._scheduleSearch();
+    });
+    input.addEventListener('keydown', (ev) => {
+      if (ev.key === 'Escape' && input.value) {
+        ev.stopPropagation();
+        this._clearSearch();
+      }
+    });
+
+    if (clearBtn) {
+      clearBtn.addEventListener('click', () => this._clearSearch());
+    }
+
+    document.querySelectorAll('#searchFilters .search-filter-chip').forEach((chip) => {
+      chip.addEventListener('click', () => {
+        const t = chip.dataset.typeFilter;
+        // Keep at least one type selected.
+        if (this._searchTypes.has(t) && this._searchTypes.size === 1) return;
+        if (this._searchTypes.has(t)) {
+          this._searchTypes.delete(t);
+          chip.classList.remove('active');
+        } else {
+          this._searchTypes.add(t);
+          chip.classList.add('active');
+        }
+        this._runSearch();
+      });
+    });
+
+    const caseSel = document.getElementById('searchCaseFilter');
+    const statusSel = document.getElementById('searchStatusFilter');
+    const dateSel = document.getElementById('searchDateFilter');
+    if (caseSel) {
+      caseSel.addEventListener('change', () => {
+        this._searchSecondary.caseLabel = caseSel.value;
+        this._renderSearch(this._searchLastData);
+      });
+    }
+    if (statusSel) {
+      statusSel.addEventListener('change', () => {
+        this._searchSecondary.status = statusSel.value;
+        this._renderSearch(this._searchLastData);
+      });
+    }
+    if (dateSel) {
+      dateSel.addEventListener('change', () => {
+        this._searchSecondary.days = dateSel.value;
+        this._renderSearch(this._searchLastData);
+      });
+    }
+
+    this._populateSearchCaseFilter();
+    if (results) results.hidden = true;
+  },
+
+  /** Fill the case <select> from loaded cases (#caseName values). */
+  _populateSearchCaseFilter() {
+    const sel = document.getElementById('searchCaseFilter');
+    if (!sel) return;
+    const cases = Array.isArray(this.cases) ? this.cases : [];
+    const names = Array.from(new Set(cases.map((c) => c && c.name).filter(Boolean))).sort();
+    const current = sel.value;
+    // Rebuild options (keep the "All cases" placeholder).
+    sel.innerHTML = '';
+    const all = document.createElement('option');
+    all.value = '';
+    all.textContent = 'All cases';
+    sel.appendChild(all);
+    for (const name of names) {
+      const opt = document.createElement('option');
+      opt.value = name;
+      opt.textContent = '#' + name;
+      sel.appendChild(opt);
+    }
+    if (current && names.includes(current)) sel.value = current;
+  },
+
+  /** Debounced trigger from the input event. */
+  _scheduleSearch() {
+    clearTimeout(this._searchDebounceTimer);
+    this._searchDebounceTimer = setTimeout(() => this._runSearch(), window.CodemanSearch.SEARCH_DEBOUNCE_MS);
+  },
+
+  _clearSearch() {
+    const input = document.getElementById('searchInput');
+    const clearBtn = document.getElementById('searchClearBtn');
+    if (input) input.value = '';
+    if (clearBtn) clearBtn.hidden = true;
+    this._searchLastData = null;
+    this._renderSearch(null);
+  },
+
+  /** Execute the federated search request and render the result. */
+  async _runSearch() {
+    const input = document.getElementById('searchInput');
+    if (!input) return;
+    const q = input.value.trim();
+    if (q.length === 0) {
+      this._searchLastData = null;
+      this._renderSearch(null);
+      return;
+    }
+
+    const types = Array.from(this._searchTypes);
+    const params = new URLSearchParams();
+    params.set('q', q.slice(0, 200));
+    if (types.length > 0 && types.length < 3) params.set('types', types.join(','));
+    params.set('limit', String(window.CodemanSearch.SEARCH_LIMIT));
+
+    const seq = ++this._searchSeq;
+    const data = await this._apiJson('/api/search?' + params.toString());
+    // Drop stale responses (a newer query already fired).
+    if (seq !== this._searchSeq) return;
+
+    if (!data) {
+      // null = request error or 400 (bad input). Show an empty/error state.
+      this._searchLastData = { query: q, groups: [], totalResults: 0, truncated: false, _error: true };
+    } else {
+      this._searchLastData = data;
+    }
+    this._renderSearch(this._searchLastData);
+  },
+
+  /**
+   * Apply client-side secondary filters (case / status / date) to a group's
+   * results. Type filtering already happened server-side via types=.
+   */
+  _applySecondaryFilters(results) {
+    const { caseLabel, status, days } = this._searchSecondary;
+    let out = results;
+    if (caseLabel) {
+      const want = '#' + caseLabel;
+      out = out.filter((r) => (r.sessionName || '').includes(want) || r.sessionName === caseLabel);
+    }
+    if (status) {
+      const activeIds = new Set((this.sessionOrder || []).concat(Object.keys(this.sessions || {})));
+      out = out.filter((r) => {
+        const isActive = activeIds.has(r.sessionId);
+        return status === 'active' ? isActive : !isActive;
+      });
+    }
+    if (days) {
+      const cutoff = Date.now() - Number(days) * 24 * 60 * 60 * 1000;
+      out = out.filter((r) => Number.isFinite(r.timestamp) && r.timestamp >= cutoff);
+    }
+    return out;
+  },
+
+  /** Render the grouped result cards (or empty/loading states). */
+  _renderSearch(data) {
+    const results = document.getElementById('searchResults');
+    const historyTitle = document.getElementById('historyTitle');
+    const historyList = document.getElementById('historyList');
+    if (!results) return;
+
+    const searching = !!data;
+    // Hide the plain "Resume Conversation" history list while a search is active.
+    if (historyTitle) historyTitle.style.display = searching ? 'none' : '';
+    if (historyList) historyList.style.display = searching ? 'none' : '';
+
+    results.innerHTML = '';
+    if (!data) {
+      results.hidden = true;
+      return;
+    }
+    results.hidden = false;
+
+    if (data._error) {
+      const empty = document.createElement('div');
+      empty.className = 'search-empty';
+      empty.textContent = 'Search unavailable — check the query and try again.';
+      results.appendChild(empty);
+      return;
+    }
+
+    // Apply secondary (client-side) filters and recompute shown total.
+    const groups = (data.groups || [])
+      .map((g) => ({ type: g.type, results: this._applySecondaryFilters(g.results || []) }))
+      .filter((g) => g.results.length > 0);
+
+    const shownTotal = groups.reduce((n, g) => n + g.results.length, 0);
+
+    if (shownTotal === 0) {
+      const empty = document.createElement('div');
+      empty.className = 'search-empty';
+      empty.textContent = 'No results for "' + (data.query || '') + '"';
+      results.appendChild(empty);
+      return;
+    }
+
+    for (const group of groups) {
+      const header = document.createElement('div');
+      header.className = 'search-group-header';
+      const label = document.createElement('span');
+      label.className = 'search-group-label';
+      label.textContent = window.CodemanSearch.SOURCE_LABELS[group.type] || group.type;
+      const count = document.createElement('span');
+      count.className = 'search-group-count';
+      count.textContent = String(group.results.length);
+      header.append(label, count);
+      results.appendChild(header);
+
+      for (const r of group.results) {
+        results.appendChild(this._buildSearchResultCard(r));
+      }
+    }
+
+    if (data.truncated) {
+      const trunc = document.createElement('div');
+      trunc.className = 'search-truncated';
+      trunc.textContent = 'Showing the top matches — refine your search to narrow results.';
+      results.appendChild(trunc);
+    }
+  },
+
+  /** Build a single result card DOM node wired to its jump-to action. */
+  _buildSearchResultCard(r) {
+    const card = document.createElement('div');
+    card.className = 'search-result-card';
+    card.dataset.type = r.type;
+    card.tabIndex = 0;
+    card.setAttribute('role', 'button');
+
+    const topRow = document.createElement('div');
+    topRow.className = 'search-result-top';
+
+    const badge = document.createElement('span');
+    badge.className = 'search-result-badge search-badge-' + r.type;
+    badge.textContent = (window.CodemanSearch.SOURCE_LABELS[r.type] || r.type).replace(/s$/, '');
+
+    const name = document.createElement('span');
+    name.className = 'search-result-name';
+    name.textContent = r.sessionName || r.sessionId || '(session)';
+
+    const time = document.createElement('span');
+    time.className = 'search-result-time';
+    time.textContent = window.CodemanSearch.formatSearchTime(r.timestamp);
+
+    topRow.append(badge, name, time);
+
+    const snippet = document.createElement('div');
+    snippet.className = 'search-result-snippet';
+    snippet.textContent = r.snippet || '';
+
+    card.append(topRow, snippet);
+
+    const jump = () => this._jumpToSearchResult(r);
+    card.addEventListener('click', jump);
+    card.addEventListener('keydown', (ev) => {
+      if (ev.key === 'Enter' || ev.key === ' ') {
+        ev.preventDefault();
+        jump();
+      }
+    });
+
+    return card;
+  },
+
+  /**
+   * Navigate to a search result by jumpTo.kind, reusing the existing app methods:
+   *   session     → selectSession(sessionId)        (open/switch to the session)
+   *   run-summary → openRunSummary(sessionId)        (session options → summary tab)
+   *   file-preview→ openFilePreview(path, sessionId, attachmentId)
+   */
+  _jumpToSearchResult(r) {
+    const jt = r && r.jumpTo;
+    if (!jt) return;
+    // Leaving the welcome overlay so the target surface is visible.
+    if (typeof this.hideWelcome === 'function') this.hideWelcome();
+
+    try {
+      if (jt.kind === 'run-summary') {
+        this.openRunSummary(jt.sessionId);
+      } else if (jt.kind === 'file-preview') {
+        this.openFilePreview(jt.relativePath || '', jt.sessionId, jt.targetId || null);
+      } else {
+        // 'session' (default)
+        this.selectSession(jt.sessionId);
+      }
+    } catch (err) {
+      console.error('[search] jump failed', err);
+    }
+  },
+});

src/web/routes/index.ts

@@ -17,4 +17,5 @@ export { registerRalphRoutes } from './ralph-routes.js';
 export { registerPlanRoutes } from './plan-routes.js';
 export { registerOrchestratorRoutes } from './orchestrator-routes.js';
 export { registerClipboardRoutes } from './clipboard-routes.js';
+export { registerSearchRoutes } from './search-routes.js';
 export { registerWsRoutes } from './ws-routes.js';

src/web/routes/ralph-routes.ts

@@ -32,17 +32,16 @@ export function registerRalphRoutes(
   // Configure Ralph tracker for a session
   app.post('/api/sessions/:id/ralph-config', async (req) => {
     const { id } = req.params as { id: string };
-    const { enabled, completionPhrase, maxIterations, reset, disableAutoEnable } = parseBody(
-      RalphConfigSchema,
-      req.body,
-      'Invalid request body'
-    ) as {
-      enabled?: boolean;
-      completionPhrase?: string;
-      maxIterations?: number;
-      reset?: boolean | 'full';
-      disableAutoEnable?: boolean;
-    };
+    const { enabled, completionPhrase, maxIterations, maxTodos, todoExpirationMinutes, reset, disableAutoEnable } =
+      parseBody(RalphConfigSchema, req.body, 'Invalid request body') as {
+        enabled?: boolean;
+        completionPhrase?: string;
+        maxIterations?: number;
+        maxTodos?: number;
+        todoExpirationMinutes?: number;
+        reset?: boolean | 'full';
+        disableAutoEnable?: boolean;
+      };
     const session = findSessionOrFail(ctx, id);
 
     // Ralph tracker is not supported for external-CLI sessions (opencode/codex)
@@ -98,6 +97,14 @@ export function registerRalphRoutes(
       session.ralphTracker.setMaxIterations(maxIterations || null);
     }
 
+    if (maxTodos !== undefined) {
+      session.ralphTracker.setMaxTodos(maxTodos);
+    }
+
+    if (todoExpirationMinutes !== undefined) {
+      session.ralphTracker.setTodoExpirationMinutes(todoExpirationMinutes);
+    }
+
     // Persist and broadcast the update
     ctx.persistSessionState(session);
     ctx.broadcast(SseEvent.SessionRalphLoopUpdate, {

src/web/routes/search-routes.ts

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Cross-session federated search route (COD-9).
+ *
+ * Registers `GET /api/search?q=&types=&limit=` — a bounded, in-memory search
+ * across three v1 sources, returned in the standard ApiResponse envelope:
+ *   1. sessions/cases — name, working directory, session id
+ *   2. run-summary events — event title/details (from the live run-summary trackers)
+ *   3. file paths — per-session attachment history (workspace-relative paths only)
+ *
+ * This route is a THIN wrapper: it harvests the source arrays from the live
+ * server stores (held on the route context) in a bounded way, then delegates
+ * grouping/ranking/capping to the pure `searchSources()` core in
+ * `src/search-service.ts`. Terminal-buffer scanning and any persisted index are
+ * out of scope for v1.
+ *
+ * Safety: query input is Zod-validated (length-bounded `q`, allowlisted `types`,
+ * numeric `limit`); only workspace-relative file paths are ever exposed (the
+ * server-private `externalPath` on attachment history is never read here); and
+ * the pure core enforces a per-group and total result cap so a broad query
+ * cannot return an unbounded payload. No terminal output is read.
+ *
+ * Endpoints: GET /api/search
+ */
+
+import { FastifyInstance } from 'fastify';
+import { parseBody } from '../route-helpers.js';
+import { SearchQuerySchema } from '../schemas.js';
+import {
+  searchSources,
+  type SearchSources,
+  type SessionSearchInput,
+  type EventSearchInput,
+  type FileSearchInput,
+} from '../../search-service.js';
+import type { SearchSourceType } from '../../types/search.js';
+import type { SessionPort, InfraPort } from '../ports/index.js';
+
+/**
+ * Per-source harvest caps. These bound how much in-memory data we hand to the
+ * pure core BEFORE it applies its own result caps — they keep the harvest itself
+ * cheap on large deployments (e.g. 50 sessions × many events). They are
+ * deliberately well above the result caps so ranking still sees enough candidates.
+ */
+const MAX_EVENTS_PER_SESSION = 500;
+
+interface SessionLike {
+  id: string;
+  name: string;
+  workingDir: string;
+  lastActivityAt?: number;
+  createdAt?: number;
+  attachmentHistory?: Array<{
+    id: string;
+    fileName: string;
+    relativePath?: string;
+    timestamp?: number;
+    mtimeMs?: number;
+  }>;
+}
+
+/**
+ * Harvest the three source arrays from the live in-memory stores. Reads only
+ * bounded, already-loaded data — no disk I/O, no terminal buffers.
+ */
+function harvestSources(ctx: SessionPort & InfraPort): SearchSources {
+  const sessions: SessionSearchInput[] = [];
+  const events: EventSearchInput[] = [];
+  const files: FileSearchInput[] = [];
+
+  for (const raw of ctx.sessions.values()) {
+    const s = raw as unknown as SessionLike;
+    const sessionName = s.name ?? '';
+    const timestamp = s.lastActivityAt ?? s.createdAt ?? 0;
+
+    sessions.push({
+      sessionId: s.id,
+      sessionName,
+      workingDir: s.workingDir ?? '',
+      timestamp,
+    });
+
+    // Files: per-session attachment history. Only the workspace-relative path is
+    // surfaced; the server-private externalPath is intentionally never read.
+    const history = s.attachmentHistory ?? [];
+    for (const item of history) {
+      files.push({
+        sessionId: s.id,
+        sessionName,
+        fileName: item.fileName,
+        relativePath: item.relativePath,
+        timestamp: item.timestamp ?? item.mtimeMs ?? timestamp,
+        itemId: item.id,
+      });
+    }
+  }
+
+  // Events: from the live run-summary trackers, keyed by session id.
+  for (const [sessionId, tracker] of ctx.runSummaryTrackers) {
+    const session = ctx.sessions.get(sessionId) as unknown as SessionLike | undefined;
+    const sessionName = session?.name ?? '';
+    const summary = tracker.getSummary();
+    // Newest events are most relevant; cap the per-session harvest.
+    const evts = summary.events.slice(-MAX_EVENTS_PER_SESSION);
+    for (const e of evts) {
+      events.push({
+        sessionId,
+        sessionName,
+        eventId: e.id,
+        title: e.title,
+        details: e.details ?? '',
+        timestamp: e.timestamp,
+      });
+    }
+  }
+
+  return { sessions, events, files };
+}
+
+export function registerSearchRoutes(app: FastifyInstance, ctx: SessionPort & InfraPort): void {
+  app.get('/api/search', async (req) => {
+    // Zod-validate the query. parseBody throws a structured 400 on failure.
+    const { q, types, limit } = parseBody(SearchQuerySchema, req.query);
+
+    const allowed: Set<SearchSourceType> | null = types
+      ? new Set(
+          types
+            .split(',')
+            .map((t) => t.trim())
+            .filter(Boolean) as SearchSourceType[]
+        )
+      : null;
+
+    const sources = harvestSources(ctx);
+
+    // Apply the optional source-type filter before searching so excluded
+    // sources never contribute to (or consume budget in) the result set.
+    const filtered: SearchSources = {
+      sessions: !allowed || allowed.has('session') ? sources.sessions : [],
+      events: !allowed || allowed.has('event') ? sources.events : [],
+      files: !allowed || allowed.has('file') ? sources.files : [],
+    };
+
+    const result = searchSources(q, filtered);
+
+    // Optional caller-supplied total cap (always on top of the core's hard caps).
+    if (limit !== undefined && result.totalResults > limit) {
+      let remaining = limit;
+      const cappedGroups = [];
+      for (const group of result.groups) {
+        if (remaining <= 0) break;
+        const slice = group.results.slice(0, remaining);
+        remaining -= slice.length;
+        cappedGroups.push({ type: group.type, results: slice });
+      }
+      result.groups = cappedGroups;
+      result.totalResults = limit;
+      result.truncated = true;
+    }
+
+    return { success: true, data: result };
+  });
+}

src/web/routes/session-routes.ts

@@ -287,12 +287,14 @@ export function registerSessionRoutes(
     //
     // For keys the caller is actively setting, strip any stale disk entry a prior
     // Codeman version may have written. Scope limited to:
-    //   - Claude mode (OpenCode doesn't read .claude/settings.local.json)
+    //   - Claude mode (OpenCode/Codex/Gemini don't read .claude/settings.local.json)
     //   - workingDir inside CASES_DIR (Codeman's managed territory — we never mutate
     //     .claude/settings.local.json in arbitrary user repos that POST /api/sessions
     //     can target, because those may have hand-authored values).
     const canStripDisk =
       body.mode !== 'opencode' &&
+      body.mode !== 'codex' &&
+      body.mode !== 'gemini' &&
       body.envOverrides &&
       Object.keys(body.envOverrides).length > 0 &&
       workingDir.startsWith(CASES_DIR + '/');
@@ -349,6 +351,17 @@ export function registerSessionRoutes(
       }
     }
 
+    // Check Gemini availability if requested
+    if (body.mode === 'gemini') {
+      const { isGeminiAvailable } = await import('../../utils/gemini-cli-resolver.js');
+      if (!isGeminiAvailable()) {
+        return createErrorResponse(
+          ApiErrorCode.OPERATION_FAILED,
+          'Gemini CLI not found. Install with: npm install -g @google/gemini-cli'
+        );
+      }
+    }
+
     // Pre-validate resumeSessionId: check that the conversation file actually exists
     // in Claude's projects directory. If not, skip resume to avoid confusing
     // "No conversation found" errors from Claude CLI.
@@ -387,10 +400,13 @@ export function registerSessionRoutes(
         ? body.openCodeConfig?.model
         : mode === 'codex'
           ? body.codexConfig?.model
-          : mode !== 'shell'
-            ? modelConfig?.defaultModel || undefined
-            : undefined;
+          : mode === 'gemini'
+            ? body.geminiConfig?.model
+            : mode !== 'shell'
+              ? modelConfig?.defaultModel || undefined
+              : undefined;
     const claudeModeConfig = await ctx.getClaudeModeConfig();
+    const terminalHistoryConfig = await ctx.getTerminalHistoryConfig();
     const session = new Session({
       workingDir,
       mode,
@@ -403,9 +419,11 @@ export function registerSessionRoutes(
       allowedTools: claudeModeConfig.allowedTools,
       openCodeConfig: mode === 'opencode' ? body.openCodeConfig : undefined,
       codexConfig: mode === 'codex' ? body.codexConfig : undefined,
+      geminiConfig: mode === 'gemini' ? body.geminiConfig : undefined,
       resumeSessionId: validatedResumeId,
       envOverrides: body.envOverrides,
       effort: body.effort,
+      tmuxHistoryLimit: terminalHistoryConfig.tmuxHistoryLimit,
     });
 
     ctx.addSession(session);
@@ -601,9 +619,11 @@ export function registerSessionRoutes(
 
     try {
       // Auto-detect completion phrase from CLAUDE.md BEFORE starting (only if globally enabled and not explicitly disabled by user)
-      // Ralph tracker is not supported for opencode sessions
+      // Ralph tracker is not supported for opencode / codex / gemini sessions
       if (
         session.mode !== 'opencode' &&
+        session.mode !== 'codex' &&
+        session.mode !== 'gemini' &&
         ctx.store.getConfig().ralphEnabled &&
         !session.ralphTracker.autoEnableDisabled
       ) {
@@ -1235,6 +1255,7 @@ export function registerSessionRoutes(
       mode = 'claude',
       openCodeConfig,
       codexConfig,
+      geminiConfig,
       envOverrides,
       effort,
     } = parseBody(QuickStartSchema, req.body);
@@ -1261,6 +1282,17 @@ export function registerSessionRoutes(
       }
     }
 
+    // Check Gemini availability if requested
+    if (mode === 'gemini') {
+      const { isGeminiAvailable } = await import('../../utils/gemini-cli-resolver.js');
+      if (!isGeminiAvailable()) {
+        return createErrorResponse(
+          ApiErrorCode.OPERATION_FAILED,
+          'Gemini CLI not found. Install with: npm install -g @google/gemini-cli'
+        );
+      }
+    }
+
     // Resolve case path: check linked-cases registry first, then fall back to CASES_DIR.
     // This mirrors the behaviour of resolveCasePath() in case-routes so that linked
     // external project directories are honoured by quick-start just like regular case routes.
@@ -1289,8 +1321,8 @@ export function registerSessionRoutes(
         writeFileSync(join(casePath, 'CLAUDE.md'), claudeMd);
 
         // Write .claude/settings.local.json with hooks for desktop notifications
-        // (Claude-specific — OpenCode uses its own plugin system)
-        if (mode !== 'opencode') {
+        // (Claude-specific — OpenCode, Codex, and Gemini use their own systems)
+        if (mode !== 'opencode' && mode !== 'codex' && mode !== 'gemini') {
           await writeHooksConfig(casePath);
         }
 
@@ -1307,7 +1339,13 @@ export function registerSessionRoutes(
 
     // Strip stale disk entries for keys this request is actively setting (Claude only —
     // see POST /api/sessions for full rationale).
-    if (mode !== 'opencode' && envOverrides && Object.keys(envOverrides).length > 0) {
+    if (
+      mode !== 'opencode' &&
+      mode !== 'codex' &&
+      mode !== 'gemini' &&
+      envOverrides &&
+      Object.keys(envOverrides).length > 0
+    ) {
       await stripCaseEnvKeys(casePath, Object.keys(envOverrides));
     }
 
@@ -1320,10 +1358,13 @@ export function registerSessionRoutes(
         ? openCodeConfig?.model
         : mode === 'codex'
           ? codexConfig?.model
-          : mode !== 'shell'
-            ? qsModelConfig?.defaultModel || undefined
-            : undefined;
+          : mode === 'gemini'
+            ? geminiConfig?.model
+            : mode !== 'shell'
+              ? qsModelConfig?.defaultModel || undefined
+              : undefined;
     const qsClaudeModeConfig = await ctx.getClaudeModeConfig();
+    const qsTerminalHistoryConfig = await ctx.getTerminalHistoryConfig();
     const session = new Session({
       workingDir: casePath,
       mux: ctx.mux,
@@ -1335,8 +1376,10 @@ export function registerSessionRoutes(
       allowedTools: qsClaudeModeConfig.allowedTools,
       openCodeConfig: mode === 'opencode' ? openCodeConfig : undefined,
       codexConfig: mode === 'codex' ? codexConfig : undefined,
+      geminiConfig: mode === 'gemini' ? geminiConfig : undefined,
       envOverrides,
       effort,
+      tmuxHistoryLimit: qsTerminalHistoryConfig.tmuxHistoryLimit,
     });
 
     // Auto-detect completion phrase from CLAUDE.md BEFORE broadcasting
@@ -1373,7 +1416,7 @@ export function registerSessionRoutes(
         });
         ctx.broadcast(SseEvent.SessionInteractive, { id: session.id, mode: 'shell' });
       } else {
-        // Both 'claude' and 'opencode' modes use startInteractive()
+        // 'claude', 'opencode', 'codex', and 'gemini' modes use startInteractive()
         await session.startInteractive();
         getLifecycleLog().log({
           event: 'started',

src/web/routes/system-routes.ts

@@ -29,6 +29,12 @@ import { imageWatcher } from '../../image-watcher.js';
 import { workflowRunWatcher } from '../../workflow-run-watcher.js';
 import { applyStatusLineConfig } from '../../hooks-config.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
+import {
+  buildAwayDigest,
+  resolveAwayDigestRange,
+  type AwayDigestSession,
+  type AwayDigestSubagent,
+} from '../away-digest.js';
 import {
   findSessionOrFail,
   formatUptime,
@@ -43,6 +49,7 @@ import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort } from '..
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
 import { QR_AUTH_FAILURE_MAX } from '../../config/tunnel-config.js';
 import { AUTH_SESSION_TTL_MS } from '../../config/auth-config.js';
+import { resolveTerminalHistoryConfig } from '../../config/terminal-history.js';
 
 // Maximum screenshot upload size (10MB)
 const MAX_SCREENSHOT_SIZE = 10 * 1024 * 1024;
@@ -52,6 +59,12 @@ const SCREENSHOTS_DIR = dataPath('screenshots');
 /** Cached CPU count — doesn't change at runtime */
 const CPU_COUNT = cpus().length;
 
+function parseOptionalNumber(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === '') return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : Number.NaN;
+}
+
 /** Get system CPU and memory usage */
 function getSystemStats(): {
   cpu: number;
@@ -331,7 +344,7 @@ export function registerSystemRoutes(
   });
 
   // ═══════════════════════════════════════════════════════════════
-  // CLI Integrations (OpenCode)
+  // CLI Integrations (OpenCode, Codex, Gemini)
   // ═══════════════════════════════════════════════════════════════
 
   // ========== OpenCode ==========
@@ -352,6 +365,16 @@ export function registerSystemRoutes(
     };
   });
 
+  // ========== Gemini ==========
+
+  app.get('/api/gemini/status', async () => {
+    const { isGeminiAvailable, resolveGeminiDir } = await import('../../utils/gemini-cli-resolver.js');
+    return {
+      available: isGeminiAvailable(),
+      path: resolveGeminiDir(),
+    };
+  });
+
   // ═══════════════════════════════════════════════════════════════
   // State & Lifecycle (cleanup, lifecycle log, stats)
   // ═══════════════════════════════════════════════════════════════
@@ -415,6 +438,56 @@ export function registerSystemRoutes(
     };
   });
 
+  app.get('/api/away-digest', async (req, reply) => {
+    const query = req.query as {
+      range?: string;
+      since?: string;
+      until?: string;
+      lastViewed?: string;
+    };
+
+    let range;
+    try {
+      range = resolveAwayDigestRange({
+        range: query.range,
+        since: parseOptionalNumber(query.since),
+        until: parseOptionalNumber(query.until),
+        lastViewed: parseOptionalNumber(query.lastViewed),
+      });
+    } catch (err) {
+      reply.code(400);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err));
+    }
+
+    const lifecycleLog = getLifecycleLog();
+    const lifecycleEntries = await lifecycleLog.query({
+      since: range.since,
+      limit: 1000,
+    });
+
+    const sessions: AwayDigestSession[] = Array.from(ctx.sessions.values()).map((session) => ({
+      id: session.id,
+      name: session.name,
+      status: session.status,
+      inputTokens: session.inputTokens,
+      outputTokens: session.outputTokens,
+      totalCost: session.totalCost,
+    }));
+
+    const runSummaries = Array.from(ctx.runSummaryTrackers.values()).map((tracker) => tracker.getSummary());
+    const digest = buildAwayDigest({
+      range,
+      lifecycleEntries,
+      runSummaries,
+      sessions,
+      dailyTokenStats: ctx.store.getDailyStats(30),
+      subagents: subagentWatcher.getRecentSubagents(60) as AwayDigestSubagent[],
+      now: range.until,
+    });
+
+    return { success: true, digest };
+  });
+
   // ═══════════════════════════════════════════════════════════════
   // Configuration & Settings (config, settings, model config, CPU priority)
   // ═══════════════════════════════════════════════════════════════
@@ -552,6 +625,11 @@ export function registerSystemRoutes(
       const merged = { ...existing, ...settingsToStore };
       await fs.writeFile(SETTINGS_PATH, JSON.stringify(merged, null, 2));
 
+      // Apply a changed tmux history-limit to all live sessions immediately.
+      if (settings.tmuxHistoryLimit !== undefined) {
+        await ctx.mux.setHistoryLimit(resolveTerminalHistoryConfig(merged).tmuxHistoryLimit);
+      }
+
       // Handle subagent tracking toggle dynamically
       toggleService((settings.subagentTrackingEnabled as boolean) ?? true, subagentWatcher, 'Subagent watcher');
 

src/web/schemas.ts

@@ -9,6 +9,12 @@
 
 import { z } from 'zod';
 import { SAFE_PATH_PATTERN, isSafePushEndpoint } from '../utils/index.js';
+import {
+  MAX_TERMINAL_BUFFER_BYTES,
+  MAX_TERMINAL_SCROLLBACK_LINES,
+  MIN_TERMINAL_BUFFER_BYTES,
+  MIN_TERMINAL_SCROLLBACK_LINES,
+} from '../config/terminal-history.js';
 
 // ========== Path Validation ==========
 
@@ -46,7 +52,7 @@ const safePathSchema = z.string().max(1000).refine(isValidWorkingDir, {
 // ========== Env Var Allowlist ==========
 
 /** Allowlisted env var key prefixes */
-const ALLOWED_ENV_PREFIXES = ['CLAUDE_CODE_', 'OPENCODE_', 'CODEX_'];
+const ALLOWED_ENV_PREFIXES = ['CLAUDE_CODE_', 'OPENCODE_', 'CODEX_', 'GEMINI_', 'GOOGLE_'];
 
 /** Env var keys that are always blocked (security-sensitive) */
 const BLOCKED_ENV_KEYS = new Set([
@@ -76,7 +82,7 @@ const safeEnvOverridesSchema = z
     },
     {
       message:
-        'envOverrides contains blocked or disallowed env var keys. Only CLAUDE_CODE_*, OPENCODE_*, and CODEX_* keys are allowed.',
+        'envOverrides contains blocked or disallowed env var keys. Only CLAUDE_CODE_*, OPENCODE_*, CODEX_*, GEMINI_*, and GOOGLE_* keys are allowed.',
     }
   );
 
@@ -149,9 +155,26 @@ const CodexConfigSchema = z
   })
   .optional();
 
+/** Schema for Gemini CLI-specific configuration */
+const GeminiConfigSchema = z
+  .object({
+    model: z
+      .string()
+      .max(100)
+      .regex(/^[a-zA-Z0-9._\-/]+$/)
+      .optional(),
+    approvalMode: z.enum(['default', 'auto_edit', 'yolo', 'plan']).optional(),
+    resumeSession: z
+      .string()
+      .max(100)
+      .regex(/^[a-zA-Z0-9._-]+$/)
+      .optional(),
+  })
+  .optional();
+
 export const CreateSessionSchema = z.object({
   workingDir: safePathSchema.optional(),
-  mode: z.enum(['claude', 'shell', 'opencode', 'codex']).optional(),
+  mode: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini']).optional(),
   name: z.string().max(100).optional(),
   envOverrides: safeEnvOverridesSchema,
   /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
@@ -162,6 +185,7 @@ export const CreateSessionSchema = z.object({
   statusLineTelemetry: z.boolean().optional(),
   openCodeConfig: OpenCodeConfigSchema,
   codexConfig: CodexConfigSchema,
+  geminiConfig: GeminiConfigSchema,
   /** Resume a previous Claude conversation by its session ID (used for reboot recovery) */
   resumeSessionId: z
     .string()
@@ -258,9 +282,10 @@ export const QuickStartSchema = z.object({
     .string()
     .regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format. Use only letters, numbers, hyphens, underscores.')
     .optional(),
-  mode: z.enum(['claude', 'shell', 'opencode', 'codex']).optional(),
+  mode: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini']).optional(),
   openCodeConfig: OpenCodeConfigSchema,
   codexConfig: CodexConfigSchema,
+  geminiConfig: GeminiConfigSchema,
   envOverrides: safeEnvOverridesSchema,
   /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
   effort: effortLevelSchema,
@@ -393,6 +418,16 @@ export const SettingsUpdateSchema = z
     allowedTools: z.string().max(2000).optional(),
     // Codex CLI settings
     codexDangerouslyBypassApprovals: z.boolean().optional(),
+    // Terminal history and retention
+    terminalScrollbackLines: z
+      .number()
+      .int()
+      .min(MIN_TERMINAL_SCROLLBACK_LINES)
+      .max(MAX_TERMINAL_SCROLLBACK_LINES)
+      .optional(),
+    tmuxHistoryLimit: z.number().int().min(MIN_TERMINAL_SCROLLBACK_LINES).max(MAX_TERMINAL_SCROLLBACK_LINES).optional(),
+    terminalBufferMaxBytes: z.number().int().min(MIN_TERMINAL_BUFFER_BYTES).max(MAX_TERMINAL_BUFFER_BYTES).optional(),
+    terminalBufferTrimBytes: z.number().int().min(MIN_TERMINAL_BUFFER_BYTES).max(MAX_TERMINAL_BUFFER_BYTES).optional(),
     // CPU priority
     nice: z
       .object({
@@ -461,7 +496,20 @@ export const SettingsUpdateSchema = z
       .max(20)
       .optional(),
   })
-  .strict();
+  .strict()
+  .superRefine((settings, ctx) => {
+    if (
+      settings.terminalBufferMaxBytes !== undefined &&
+      settings.terminalBufferTrimBytes !== undefined &&
+      settings.terminalBufferTrimBytes > settings.terminalBufferMaxBytes
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['terminalBufferTrimBytes'],
+        message: 'terminalBufferTrimBytes must be less than or equal to terminalBufferMaxBytes',
+      });
+    }
+  });
 
 /**
  * Schema for POST /api/sessions/:id/input with length limit
@@ -497,6 +545,8 @@ export const RalphConfigSchema = z.object({
   enabled: z.boolean().optional(),
   completionPhrase: z.string().max(500).optional(),
   maxIterations: z.number().int().min(0).max(10000).optional(),
+  maxTodos: z.number().int().positive().max(10000).optional(),
+  todoExpirationMinutes: z.number().int().positive().max(525600).optional(),
   reset: z.union([z.boolean(), z.literal('full')]).optional(),
   disableAutoEnable: z.boolean().optional(),
 });
@@ -708,3 +758,35 @@ export const OrchestratorStartSchema = z.object({
 export const OrchestratorRejectSchema = z.object({
   feedback: z.string().min(1).max(10000),
 });
+
+// ========== Cross-Session Search (COD-9) ==========
+
+/** Valid federated source kinds for `GET /api/search?types=`. */
+export const SEARCH_SOURCE_TYPES = ['session', 'event', 'file'] as const;
+
+/**
+ * GET /api/search query validation.
+ *
+ * Query params arrive as strings: `q` is bounded (1..200 chars), `types` is an
+ * optional comma-separated allowlisted CSV, and `limit` is an optional coerced
+ * integer clamped to 1..60. Validation is the first line of defense — a missing
+ * or oversized `q`, an unknown type, or a non-numeric limit is rejected with 400.
+ */
+export const SearchQuerySchema = z.object({
+  q: z.string().trim().min(1, 'Query is required').max(200, 'Query too long (max 200 chars)'),
+  types: z
+    .string()
+    .max(100)
+    .optional()
+    .refine(
+      (v) =>
+        v === undefined ||
+        v
+          .split(',')
+          .map((t) => t.trim())
+          .filter(Boolean)
+          .every((t) => (SEARCH_SOURCE_TYPES as readonly string[]).includes(t)),
+      { message: 'Invalid types value' }
+    ),
+  limit: z.coerce.number().int().min(1).max(60).optional(),
+});

src/web/server.ts

@@ -129,6 +129,7 @@ import {
 import type { EventLoopMonitorHandle } from '../utils/index.js';
 import { MAX_CONCURRENT_SESSIONS, MAX_SSE_CLIENTS } from '../config/map-limits.js';
 import { MAX_PASTE_IMAGE_BYTES } from '../config/buffer-limits.js';
+import { resolveTerminalHistoryConfig } from '../config/terminal-history.js';
 import { SseEvent } from './sse-events.js';
 import { getLatestPlanUsage } from './plan-usage-latest.js';
 import type { ScheduledRun } from './ports/index.js';
@@ -150,6 +151,7 @@ import {
   registerRalphRoutes,
   registerPlanRoutes,
   registerClipboardRoutes,
+  registerSearchRoutes,
   registerOrchestratorRoutes,
   registerWsRoutes,
 } from './routes/index.js';
@@ -586,6 +588,7 @@ export class WebServer extends EventEmitter {
       getGlobalNiceConfig: this.getGlobalNiceConfig.bind(this),
       getModelConfig: this.getModelConfig.bind(this),
       getClaudeModeConfig: this.getClaudeModeConfig.bind(this),
+      getTerminalHistoryConfig: this.getTerminalHistoryConfig.bind(this),
       getDefaultClaudeMdPath: this.getDefaultClaudeMdPath.bind(this),
       getLightState: this.getLightState.bind(this),
       getLightSessionsState: this.getLightSessionsState.bind(this),
@@ -870,6 +873,7 @@ export class WebServer extends EventEmitter {
     registerRalphRoutes(this.app, ctx);
     registerPlanRoutes(this.app, ctx);
     registerClipboardRoutes(this.app, ctx);
+    registerSearchRoutes(this.app, ctx);
     registerOrchestratorRoutes(this.app, ctx);
     registerWsRoutes(this.app, ctx, () => this.getHostPolicy());
   }
@@ -1461,6 +1465,12 @@ export class WebServer extends EventEmitter {
     return {};
   }
 
+  // Resolve the bounds-clamped terminal-history config from settings.json.
+  private async getTerminalHistoryConfig() {
+    const settings = await this.readSettings();
+    return resolveTerminalHistoryConfig(settings);
+  }
+
   // Helper to get model configuration from settings
   private async getModelConfig(): Promise<{
     defaultModel?: string;
@@ -2124,6 +2134,9 @@ export class WebServer extends EventEmitter {
               muxSession: muxSession, // Pass the existing session so startInteractive() can attach to it
               claudeMode: recoveryClaudeMode.claudeMode,
               allowedTools: recoveryClaudeMode.allowedTools,
+              openCodeConfig: muxSession.mode === 'opencode' ? savedState?.openCodeConfig : undefined,
+              codexConfig: muxSession.mode === 'codex' ? savedState?.codexConfig : undefined,
+              geminiConfig: muxSession.mode === 'gemini' ? savedState?.geminiConfig : undefined,
               envOverrides: savedEnvOverrides,
               effort: savedState?.effort,
               attachmentHistory: savedAttachmentHistory,

test/away-digest-ui.test.ts

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const indexHtml = readFileSync(join(process.cwd(), 'src/web/public/index.html'), 'utf-8');
+const panelsJs = readFileSync(join(process.cwd(), 'src/web/public/panels-ui.js'), 'utf-8');
+const stylesCss = readFileSync(join(process.cwd(), 'src/web/public/styles.css'), 'utf-8');
+const mobileCss = readFileSync(join(process.cwd(), 'src/web/public/mobile.css'), 'utf-8');
+
+describe('away digest UI', () => {
+  it('exposes a header entry point and modal shell', () => {
+    expect(indexHtml).toContain('onclick="app.openAwayDigest()"');
+    expect(indexHtml).toContain('aria-label="Open away digest"');
+    expect(indexHtml).toContain('id="awayDigestModal"');
+    expect(indexHtml).toContain('id="awayDigestSummary"');
+    expect(indexHtml).toContain('id="awayDigestSections"');
+  });
+
+  it('offers supported range controls', () => {
+    expect(indexHtml).toContain('data-away-range="since-last-visit"');
+    expect(indexHtml).toContain('data-away-range="1h"');
+    expect(indexHtml).toContain('data-away-range="today"');
+    expect(indexHtml).toContain('data-away-range="24h"');
+    expect(indexHtml).toContain('id="awayDigestCustomSince"');
+    expect(indexHtml).toContain('id="awayDigestCustomUntil"');
+  });
+
+  it('fetches the aggregate endpoint and preserves since-last-visit until successful close', () => {
+    expect(panelsJs).toContain('/api/away-digest');
+    expect(panelsJs).toContain('codeman-away-digest-last-viewed');
+    expect(panelsJs).toContain('openAwayDigest');
+    expect(panelsJs).toContain('closeAwayDigest');
+  });
+
+  it('has desktop and mobile layout styles', () => {
+    expect(stylesCss).toContain('.away-digest-modal');
+    expect(stylesCss).toContain('.away-digest-summary');
+    expect(stylesCss).toContain('.away-digest-item');
+    expect(mobileCss).toContain('.away-digest-modal');
+    expect(mobileCss).toContain('.away-digest-ranges');
+  });
+});

test/away-digest.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import { buildAwayDigest, resolveAwayDigestRange } from '../src/web/away-digest.js';
+import type { LifecycleEntry, RunSummary } from '../src/types.js';
+
+const NOW = Date.UTC(2026, 5, 7, 12, 0, 0);
+const HOUR = 60 * 60 * 1000;
+
+function summary(sessionId: string, events: RunSummary['events']): RunSummary {
+  return {
+    sessionId,
+    sessionName: `${sessionId} name`,
+    startedAt: NOW - 4 * HOUR,
+    lastUpdatedAt: NOW - HOUR,
+    events,
+    stats: {
+      totalRespawnCycles: 0,
+      totalTokensUsed: 0,
+      peakTokens: 0,
+      totalTimeActiveMs: 0,
+      totalTimeIdleMs: 0,
+      errorCount: events.filter((event) => event.severity === 'error').length,
+      warningCount: events.filter((event) => event.severity === 'warning').length,
+      aiCheckCount: 0,
+      lastIdleAt: null,
+      lastWorkingAt: null,
+      stateTransitions: 0,
+    },
+  };
+}
+
+describe('away digest', () => {
+  it('resolves since-last-visit after the stored marker and defaults to 24h', () => {
+    expect(resolveAwayDigestRange({ range: 'since-last-visit', lastViewed: NOW - HOUR, now: NOW })).toMatchObject({
+      range: 'since-last-visit',
+      since: NOW - HOUR,
+      until: NOW,
+    });
+
+    expect(resolveAwayDigestRange({ range: 'since-last-visit', now: NOW })).toMatchObject({
+      since: NOW - 24 * HOUR,
+      until: NOW,
+    });
+  });
+
+  it('separates action-required, completed, live, idle, and informational items', () => {
+    const lifecycleEntries: LifecycleEntry[] = [
+      { ts: NOW - 10_000, event: 'exit', sessionId: 'failed', name: 'Failed Session', exitCode: 2 },
+      { ts: NOW - 9_000, event: 'exit', sessionId: 'clean', name: 'Clean Exit', exitCode: 0 },
+      { ts: NOW - 8_000, event: 'mux_died', sessionId: 'mux', name: 'Mux Session' },
+    ];
+
+    const digest = buildAwayDigest({
+      range: resolveAwayDigestRange({ range: '1h', now: NOW }),
+      lifecycleEntries,
+      runSummaries: [
+        summary('ralph', [
+          {
+            id: 'complete-1',
+            timestamp: NOW - 7_000,
+            type: 'ralph_completion',
+            severity: 'success',
+            title: 'Ralph completion detected',
+            details: 'Phrase: COMPLETE',
+          },
+        ]),
+        summary('error-session', [
+          {
+            id: 'error-1',
+            timestamp: NOW - 6_000,
+            type: 'error',
+            severity: 'error',
+            title: 'Session error',
+            details: 'Tool failed',
+          },
+        ]),
+      ],
+      sessions: [
+        { id: 'active', name: 'Active Session', status: 'working' },
+        { id: 'idle', name: 'Idle Session', status: 'idle' },
+      ],
+      dailyTokenStats: [
+        {
+          date: '2026-06-07',
+          inputTokens: 1_000,
+          outputTokens: 2_000,
+          estimatedCost: 0.18,
+          sessions: 2,
+        },
+      ],
+      subagents: [
+        {
+          id: 'agent-1',
+          sessionId: 'active',
+          description: 'Research complete',
+          status: 'completed',
+          lastUpdated: NOW - 5_000,
+        },
+      ],
+      now: NOW,
+    });
+
+    expect(digest.sections.needsAttention.map((item) => item.sessionId)).toEqual(['failed', 'mux', 'error-session']);
+    expect(digest.sections.completed.map((item) => item.sessionId)).toEqual(['ralph']);
+    expect(digest.sections.stillRunning.map((item) => item.sessionId)).toEqual(['active']);
+    expect(digest.sections.idle.map((item) => item.sessionId)).toEqual(['idle']);
+    expect(digest.sections.informational.map((item) => item.sessionId)).toContain('clean');
+    expect(digest.sections.informational.some((item) => item.source === 'subagent')).toBe(true);
+    expect(digest.totals).toMatchObject({
+      needsAttention: 3,
+      completed: 1,
+      activeSessions: 2,
+      inputTokens: 1_000,
+      outputTokens: 2_000,
+      estimatedCost: 0.18,
+      tokenWindowPrecision: 'day',
+    });
+    expect(digest.dataFreshness).toMatchObject({
+      lifecyclePersisted: true,
+      tokenStatsPersisted: true,
+      runSummariesLiveOnly: true,
+      subagentsLiveOnly: true,
+    });
+  });
+
+  it('excludes entries outside the selected range', () => {
+    const digest = buildAwayDigest({
+      range: resolveAwayDigestRange({ range: '1h', now: NOW }),
+      lifecycleEntries: [
+        { ts: NOW - 2 * HOUR, event: 'mux_died', sessionId: 'old' },
+        { ts: NOW - 1000, event: 'mux_died', sessionId: 'recent' },
+      ],
+      runSummaries: [],
+      sessions: [],
+      dailyTokenStats: [],
+      subagents: [],
+      now: NOW,
+    });
+
+    expect(digest.sections.needsAttention.map((item) => item.sessionId)).toEqual(['recent']);
+  });
+});

test/gemini-mode.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { CreateSessionSchema, QuickStartSchema } from '../src/web/schemas.js';
+
+describe('Gemini mode schemas', () => {
+  it('accepts Gemini session creation config', () => {
+    const parsed = CreateSessionSchema.parse({
+      workingDir: '/tmp',
+      mode: 'gemini',
+      geminiConfig: {
+        model: 'gemini-2.5-pro',
+        approvalMode: 'yolo',
+      },
+    });
+
+    expect(parsed.mode).toBe('gemini');
+    expect(parsed.geminiConfig).toEqual({
+      model: 'gemini-2.5-pro',
+      approvalMode: 'yolo',
+    });
+  });
+
+  it('accepts Gemini quick-start config', () => {
+    const parsed = QuickStartSchema.parse({
+      caseName: 'gemini-case',
+      mode: 'gemini',
+      geminiConfig: {
+        model: 'gemini-2.5-flash',
+        approvalMode: 'auto_edit',
+      },
+    });
+
+    expect(parsed.mode).toBe('gemini');
+    expect(parsed.geminiConfig?.model).toBe('gemini-2.5-flash');
+  });
+
+  it('rejects unsafe Gemini model strings', () => {
+    expect(() =>
+      CreateSessionSchema.parse({
+        workingDir: '/tmp',
+        mode: 'gemini',
+        geminiConfig: { model: 'gemini; rm -rf /' },
+      })
+    ).toThrow();
+  });
+});

test/mocks/mock-route-context.ts

@@ -9,6 +9,7 @@
  */
 import { vi } from 'vitest';
 import { MockSession, createMockSession } from './mock-session.js';
+import { resolveTerminalHistoryConfig } from '../../src/config/terminal-history.js';
 
 /**
  * Creates a mock context that satisfies all port interfaces.
@@ -76,6 +77,7 @@ export function createMockRouteContext(options?: { sessionId?: string }) {
     getGlobalNiceConfig: vi.fn(async () => undefined),
     getModelConfig: vi.fn(async () => null),
     getClaudeModeConfig: vi.fn(async () => ({})),
+    getTerminalHistoryConfig: vi.fn(async () => resolveTerminalHistoryConfig({})),
     getDefaultClaudeMdPath: vi.fn(async () => undefined),
     getLightState: vi.fn(() => ({ sessions: [], status: 'ok' })),
     getLightSessionsState: vi.fn(() => {
@@ -99,6 +101,7 @@ export function createMockRouteContext(options?: { sessionId?: string }) {
       getSession: vi.fn(() => null),
       clearRespawnConfig: vi.fn(),
       updateRespawnConfig: vi.fn(),
+      setHistoryLimit: vi.fn(async () => {}),
     },
     runSummaryTrackers: new Map(),
     activePlanOrchestrators: new Map(),

test/routes/ralph-routes.test.ts

@@ -21,6 +21,8 @@ function createMockRalphTracker() {
     disableAutoEnable: vi.fn(),
     startLoop: vi.fn(),
     setMaxIterations: vi.fn(),
+    setMaxTodos: vi.fn(),
+    setTodoExpirationMinutes: vi.fn(),
     resetCircuitBreaker: vi.fn(),
     generateFixPlanMarkdown: vi.fn(() => '# Fix Plan\n\n- [ ] Task 1\n'),
     importFixPlanMarkdown: vi.fn(() => 3),
@@ -158,6 +160,25 @@ describe('ralph-routes', () => {
       expect(tracker.setMaxIterations).toHaveBeenCalledWith(50);
     });
 
+    it('applies maxTodos and todoExpirationMinutes to the tracker (COD-52)', async () => {
+      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<
+        typeof createMockRalphTracker
+      >;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: `/api/sessions/${harness.ctx._sessionId}/ralph-config`,
+        payload: { maxTodos: 25, todoExpirationMinutes: 90 },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      // The ralph-config success path returns a bare {} envelope (matching its
+      // sibling config routes); an error would surface as { success: false }.
+      expect(body.success).not.toBe(false);
+      expect(tracker.setMaxTodos).toHaveBeenCalledWith(25);
+      expect(tracker.setTodoExpirationMinutes).toHaveBeenCalledWith(90);
+    });
+
     it('returns error for unknown session', async () => {
       const res = await harness.app.inject({
         method: 'POST',

test/routes/search-routes.test.ts

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview Tests for the cross-session search route (COD-9).
+ *
+ * Uses app.inject() — no real HTTP ports needed.
+ * Port: N/A (app.inject doesn't open ports)
+ *
+ * Covers query validation (400s), result shaping (grouped cards), caps,
+ * exact-before-recency ranking, and that at least two distinct sources
+ * (sessions + events) return results. Source data is injected via the mock
+ * route context (sessions map, runSummaryTrackers map, attachment history).
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import { registerSearchRoutes } from '../../src/web/routes/search-routes.js';
+import { installRouteErrorHandler } from '../../src/web/route-error-handler.js';
+import { createMockRouteContext } from '../mocks/index.js';
+import { RunSummaryTracker } from '../../src/run-summary.js';
+
+type Ctx = ReturnType<typeof createMockRouteContext>;
+
+async function harness(configure?: (ctx: Ctx) => void): Promise<{ app: FastifyInstance; ctx: Ctx }> {
+  const app = Fastify({ logger: false });
+  // Start from an empty session map so tests fully control the source data.
+  const ctx = createMockRouteContext();
+  ctx.sessions.clear();
+  ctx.runSummaryTrackers.clear();
+  configure?.(ctx);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  registerSearchRoutes(app, ctx as any);
+  installRouteErrorHandler(app);
+  await app.ready();
+  return { app, ctx };
+}
+
+/** Minimal session-like object compatible with the route's reads. */
+function fakeSession(opts: {
+  id: string;
+  name: string;
+  workingDir: string;
+  lastActivityAt?: number;
+  attachmentHistory?: unknown[];
+}) {
+  return {
+    id: opts.id,
+    name: opts.name,
+    workingDir: opts.workingDir,
+    lastActivityAt: opts.lastActivityAt ?? 0,
+    createdAt: 0,
+    attachmentHistory: opts.attachmentHistory ?? [],
+  };
+}
+
+describe('GET /api/search — validation', () => {
+  it('400 on missing q', async () => {
+    const { app } = await harness();
+    const res = await app.inject({ method: 'GET', url: '/api/search' });
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body).success).toBe(false);
+  });
+
+  it('400 on empty q', async () => {
+    const { app } = await harness();
+    const res = await app.inject({ method: 'GET', url: '/api/search?q=' });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('400 on oversized q (>200 chars)', async () => {
+    const { app } = await harness();
+    const q = 'x'.repeat(201);
+    const res = await app.inject({ method: 'GET', url: `/api/search?q=${q}` });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('400 on bad types value', async () => {
+    const { app } = await harness();
+    const res = await app.inject({ method: 'GET', url: '/api/search?q=foo&types=session,bogus' });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('400 on non-numeric limit', async () => {
+    const { app } = await harness();
+    const res = await app.inject({ method: 'GET', url: '/api/search?q=foo&limit=abc' });
+    expect(res.statusCode).toBe(400);
+  });
+});
+
+describe('GET /api/search — shaping & multi-source', () => {
+  beforeEach(() => {});
+
+  it('returns grouped results from sessions and events (two distinct sources)', async () => {
+    const { app } = await harness((ctx) => {
+      ctx.sessions.set(
+        's1',
+        fakeSession({ id: 's1', name: 'needle session', workingDir: '/home/u/proj', lastActivityAt: 100 }) as never
+      );
+      const tracker = new RunSummaryTracker('s2', 'Other session');
+      tracker.addEvent('warning', 'info', 'found a needle', 'in the logs');
+      ctx.runSummaryTrackers.set('s2', tracker);
+      ctx.sessions.set(
+        's2',
+        fakeSession({ id: 's2', name: 'Other session', workingDir: '/x', lastActivityAt: 50 }) as never
+      );
+    });
+    const res = await app.inject({ method: 'GET', url: '/api/search?q=needle' });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.success).toBe(true);
+    const types = body.data.groups.map((g: { type: string }) => g.type);
+    expect(types).toContain('session');
+    expect(types).toContain('event');
+    // Group order: sessions before events.
+    expect(types.indexOf('session')).toBeLessThan(types.indexOf('event'));
+    expect(body.data.totalResults).toBe(2);
+
+    const sessionResult = body.data.groups.find((g: { type: string }) => g.type === 'session').results[0];
+    expect(sessionResult.sessionId).toBe('s1');
+    expect(sessionResult.sessionName).toBe('needle session');
+    expect(typeof sessionResult.timestamp).toBe('number');
+    expect(typeof sessionResult.snippet).toBe('string');
+    expect(sessionResult.jumpTo).toEqual({ kind: 'session', sessionId: 's1' });
+  });
+
+  it('exposes file results via relativePath and never leaks an absolute path', async () => {
+    const { app } = await harness((ctx) => {
+      ctx.sessions.set(
+        's1',
+        fakeSession({
+          id: 's1',
+          name: 'Alpha',
+          workingDir: '/home/u/proj',
+          lastActivityAt: 1,
+          attachmentHistory: [
+            {
+              id: 'item-1',
+              sessionId: 's1',
+              fileName: 'needle.txt',
+              extension: 'txt',
+              attachmentType: 'text',
+              size: 10,
+              mtimeMs: 0,
+              timestamp: 5,
+              source: 'detected',
+              relativePath: 'docs/needle.txt',
+              externalPath: '/home/u/secret/needle.txt',
+            },
+          ],
+        }) as never
+      );
+    });
+    const res = await app.inject({ method: 'GET', url: '/api/search?q=needle' });
+    const body = JSON.parse(res.body);
+    const fileGroup = body.data.groups.find((g: { type: string }) => g.type === 'file');
+    expect(fileGroup).toBeTruthy();
+    expect(fileGroup.results[0].jumpTo.relativePath).toBe('docs/needle.txt');
+    // The server-private absolute/external path must never appear in the payload.
+    expect(res.body).not.toContain('/home/u/secret');
+  });
+
+  it('ranks exact session-name matches before more-recent partial matches', async () => {
+    const { app } = await harness((ctx) => {
+      ctx.sessions.set(
+        'exact-old',
+        fakeSession({ id: 'exact-old', name: 'needle', workingDir: '/x', lastActivityAt: 1 }) as never
+      );
+      ctx.sessions.set(
+        'partial-new',
+        fakeSession({ id: 'partial-new', name: 'needle-haystack', workingDir: '/x', lastActivityAt: 9999 }) as never
+      );
+    });
+    const res = await app.inject({ method: 'GET', url: '/api/search?q=needle' });
+    const body = JSON.parse(res.body);
+    const ids = body.data.groups[0].results.map((r: { sessionId: string }) => r.sessionId);
+    expect(ids).toEqual(['exact-old', 'partial-new']);
+  });
+});
+
+describe('GET /api/search — caps & filters', () => {
+  it('respects the limit query param as a total cap', async () => {
+    const { app } = await harness((ctx) => {
+      for (let i = 0; i < 20; i++) {
+        ctx.sessions.set(
+          `s${i}`,
+          fakeSession({ id: `s${i}`, name: `needle ${i}`, workingDir: '/x', lastActivityAt: i }) as never
+        );
+      }
+    });
+    const res = await app.inject({ method: 'GET', url: '/api/search?q=needle&limit=5' });
+    const body = JSON.parse(res.body);
+    expect(body.data.totalResults).toBe(5);
+    expect(body.data.truncated).toBe(true);
+  });
+
+  it('filters by types when provided', async () => {
+    const { app } = await harness((ctx) => {
+      ctx.sessions.set(
+        's1',
+        fakeSession({ id: 's1', name: 'needle session', workingDir: '/x', lastActivityAt: 1 }) as never
+      );
+      const tracker = new RunSummaryTracker('s1', 'needle session');
+      tracker.addEvent('warning', 'info', 'needle event', '');
+      ctx.runSummaryTrackers.set('s1', tracker);
+    });
+    const res = await app.inject({ method: 'GET', url: '/api/search?q=needle&types=event' });
+    const body = JSON.parse(res.body);
+    const types = body.data.groups.map((g: { type: string }) => g.type);
+    expect(types).toEqual(['event']);
+  });
+});

test/routes/system-routes.test.ts

@@ -76,11 +76,17 @@ vi.mock('../../src/utils/opencode-cli-resolver.js', () => ({
   resolveOpenCodeDir: vi.fn(() => null),
 }));
 
+vi.mock('../../src/utils/gemini-cli-resolver.js', () => ({
+  isGeminiAvailable: vi.fn(() => false),
+  resolveGeminiDir: vi.fn(() => null),
+}));
+
 import fs from 'node:fs/promises';
 import { existsSync, readdirSync } from 'node:fs';
 import { subagentWatcher } from '../../src/subagent-watcher.js';
 import { getLifecycleLog } from '../../src/session-lifecycle-log.js';
 import { isOpenCodeAvailable, resolveOpenCodeDir } from '../../src/utils/opencode-cli-resolver.js';
+import { isGeminiAvailable, resolveGeminiDir } from '../../src/utils/gemini-cli-resolver.js';
 
 const mockedReadFile = vi.mocked(fs.readFile);
 const mockedWriteFile = vi.mocked(fs.writeFile);
@@ -90,6 +96,8 @@ const mockedSubagentWatcher = vi.mocked(subagentWatcher);
 const mockedGetLifecycleLog = vi.mocked(getLifecycleLog);
 const mockedIsOpenCodeAvailable = vi.mocked(isOpenCodeAvailable);
 const mockedResolveOpenCodeDir = vi.mocked(resolveOpenCodeDir);
+const mockedIsGeminiAvailable = vi.mocked(isGeminiAvailable);
+const mockedResolveGeminiDir = vi.mocked(resolveGeminiDir);
 
 describe('system-routes', () => {
   let harness: RouteTestHarness;
@@ -117,6 +125,8 @@ describe('system-routes', () => {
     } as never);
     mockedIsOpenCodeAvailable.mockReturnValue(false);
     mockedResolveOpenCodeDir.mockReturnValue(null);
+    mockedIsGeminiAvailable.mockReturnValue(false);
+    mockedResolveGeminiDir.mockReturnValue(null);
   });
 
   afterEach(async () => {
@@ -194,6 +204,72 @@ describe('system-routes', () => {
     });
   });
 
+  // ========== GET /api/away-digest ==========
+
+  describe('GET /api/away-digest', () => {
+    it('returns a classified digest from lifecycle, active sessions, and token stats', async () => {
+      const lifecycleQuery = vi.fn(async () => [
+        {
+          ts: Date.now() - 1000,
+          event: 'exit',
+          sessionId: harness.ctx._sessionId,
+          name: 'Route Session',
+          exitCode: 7,
+        },
+      ]);
+      mockedGetLifecycleLog.mockReturnValue({
+        log: vi.fn(),
+        query: lifecycleQuery,
+      } as never);
+      harness.ctx._session.name = 'Route Session';
+      harness.ctx._session.status = 'working';
+      harness.ctx.store.getDailyStats.mockReturnValue([
+        {
+          date: new Date().toISOString().split('T')[0],
+          inputTokens: 100,
+          outputTokens: 200,
+          estimatedCost: 0.02,
+          sessions: 1,
+        },
+      ]);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/away-digest?range=1h' });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.digest.sections.needsAttention[0]).toMatchObject({
+        sessionId: harness.ctx._sessionId,
+        source: 'lifecycle',
+      });
+      expect(body.digest.sections.stillRunning[0]).toMatchObject({
+        sessionId: harness.ctx._sessionId,
+        source: 'status',
+      });
+      expect(body.digest.totals).toMatchObject({
+        activeSessions: 1,
+        needsAttention: 1,
+        inputTokens: 100,
+        outputTokens: 200,
+        tokenWindowPrecision: 'day',
+      });
+      expect(lifecycleQuery).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 1000,
+        })
+      );
+    });
+
+    it('rejects invalid ranges', async () => {
+      const res = await harness.app.inject({ method: 'GET', url: '/api/away-digest?range=forever' });
+
+      expect(res.statusCode).toBe(400);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+      expect(body.message ?? body.error).toMatch(/range/i);
+    });
+  });
+
   // ========== GET /api/debug/memory ==========
 
   describe('GET /api/debug/memory', () => {
@@ -699,6 +775,32 @@ describe('system-routes', () => {
     });
   });
 
+  // ========== GET /api/gemini/status ==========
+
+  describe('GET /api/gemini/status', () => {
+    it('returns unavailable when gemini is not installed', async () => {
+      mockedIsGeminiAvailable.mockReturnValue(false);
+      mockedResolveGeminiDir.mockReturnValue(null);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/gemini/status' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.available).toBe(false);
+      expect(body.path).toBeNull();
+    });
+
+    it('returns available with path when gemini is installed', async () => {
+      mockedIsGeminiAvailable.mockReturnValue(true);
+      mockedResolveGeminiDir.mockReturnValue('/usr/local/bin');
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/gemini/status' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.available).toBe(true);
+      expect(body.path).toBe('/usr/local/bin');
+    });
+  });
+
   // ========== GET /api/execution/model-config ==========
 
   describe('GET /api/execution/model-config', () => {

test/run-mode-ui.test.ts

@@ -61,6 +61,16 @@ describe('run mode UI', () => {
     expect(app.runMode).toBe('claude');
     expect(runBtnLabel.textContent).toBe('Run');
   });
+
+  it('accepts Gemini mode from server sync and updates the run button label', async () => {
+    const { app, storage, runBtnLabel } = loadRunModeHarness();
+
+    storage.set('codeman_runMode', 'claude');
+    await app.loadAppSettingsFromServer(Promise.resolve({ runMode: 'gemini' }));
+
+    expect(app.runMode).toBe('gemini');
+    expect(runBtnLabel.textContent).toBe('Run GM');
+  });
 });
 
 describe('Codex quick start settings', () => {
@@ -133,3 +143,56 @@ describe('Codex quick start settings', () => {
     expect(selected).toEqual(['sess-1']);
   });
 });
+
+describe('Gemini quick start', () => {
+  // Regression guard for the ApiResponse-envelope unwrap in runGemini(): the
+  // status check must read `.data.available` and the quick-start response must
+  // read `.data.sessionId`. Reading the raw shape (pre-fix) silently bails on
+  // the status check and never selects the new tab — exactly the two blockers
+  // caught in PR #134 review.
+  it('drives runGemini() through the {success,data} envelope and selects the new session', async () => {
+    const elements: Record<string, any> = {
+      quickStartCase: { value: 'gemini-case' },
+    };
+    const requests: Array<{ url: string; body?: any }> = [];
+    const CodemanApp = function CodemanApp(this: any) {};
+
+    const context = vm.createContext({
+      CodemanApp,
+      localStorage: { getItem: () => null, setItem: () => {} },
+      document: { getElementById: (id: string) => elements[id] ?? null },
+      // Mock responses use the real wire shape: the server.ts preSerialization
+      // hook wraps raw route payloads into the { success, data } envelope.
+      fetch: async (url: string, init?: { body?: string }) => {
+        requests.push({ url, body: init?.body ? JSON.parse(init.body) : undefined });
+        if (url === '/api/gemini/status') return { json: async () => ({ success: true, data: { available: true } }) };
+        if (url === '/api/quick-start')
+          return { json: async () => ({ success: true, data: { sessionId: 'sess-gm' } }) };
+        throw new Error(`unexpected fetch: ${url}`);
+      },
+      console,
+    });
+
+    const sessionUi = readFileSync(resolve(import.meta.dirname, '../src/web/public/session-ui.js'), 'utf8');
+    vm.runInContext(sessionUi, context, { filename: 'session-ui.js' });
+
+    const app = new (CodemanApp as any)();
+    app.terminal = { clear: () => {}, writeln: () => {}, focus: () => {} };
+    app.loadAppSettingsFromStorage = () => ({});
+    app.getCaseSettings = () => ({});
+    app.buildEnvOverrides = () => ({});
+    const selected: string[] = [];
+    app.selectSession = async (id: string) => {
+      selected.push(id);
+    };
+
+    await app.runGemini();
+
+    expect(requests.find((req) => req.url === '/api/quick-start')?.body).toMatchObject({
+      caseName: 'gemini-case',
+      mode: 'gemini',
+      geminiConfig: { approvalMode: 'yolo' },
+    });
+    expect(selected).toEqual(['sess-gm']);
+  });
+});

test/search-service.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Unit tests for the pure cross-session search core (COD-9).
+ *
+ * The core (`searchSources`) takes already-collected, in-memory source data
+ * plus a normalized query and returns grouped/ranked/capped results. No I/O,
+ * no live server — these tests exercise grouping order, exact-before-recency
+ * ranking, caps (total + per-group), snippet shaping, and path safety.
+ */
+import { describe, it, expect } from 'vitest';
+import { searchSources, SEARCH_TOTAL_CAP, SEARCH_PER_GROUP_CAP, type SearchSources } from '../src/search-service.js';
+
+function sources(overrides: Partial<SearchSources> = {}): SearchSources {
+  return {
+    sessions: [],
+    events: [],
+    files: [],
+    ...overrides,
+  };
+}
+
+describe('searchSources — grouping & order', () => {
+  it('orders groups sessions → events → files', () => {
+    const data = sources({
+      files: [
+        {
+          sessionId: 's1',
+          sessionName: 'Alpha',
+          fileName: 'query.txt',
+          relativePath: 'docs/query.txt',
+          timestamp: 100,
+          itemId: 'f1',
+        },
+      ],
+      events: [
+        { sessionId: 's1', sessionName: 'Alpha', eventId: 'e1', title: 'query started', details: '', timestamp: 100 },
+      ],
+      sessions: [{ sessionId: 's1', sessionName: 'query session', workingDir: '/home/u/proj', timestamp: 100 }],
+    });
+    const res = searchSources('query', data);
+    expect(res.groups.map((g) => g.type)).toEqual(['session', 'event', 'file']);
+  });
+
+  it('omits empty groups', () => {
+    const data = sources({
+      sessions: [{ sessionId: 's1', sessionName: 'query session', workingDir: '/home/u/proj', timestamp: 100 }],
+    });
+    const res = searchSources('query', data);
+    expect(res.groups.map((g) => g.type)).toEqual(['session']);
+  });
+});
+
+describe('searchSources — matching across distinct sources', () => {
+  it('returns results from at least two distinct sources', () => {
+    const data = sources({
+      sessions: [{ sessionId: 's1', sessionName: 'needle project', workingDir: '/home/u/proj', timestamp: 100 }],
+      events: [
+        { sessionId: 's2', sessionName: 'Other', eventId: 'e1', title: 'found a needle', details: '', timestamp: 100 },
+      ],
+    });
+    const res = searchSources('needle', data);
+    const types = res.groups.map((g) => g.type);
+    expect(types).toContain('session');
+    expect(types).toContain('event');
+    expect(res.totalResults).toBe(2);
+  });
+
+  it('matches session working directory', () => {
+    const data = sources({
+      sessions: [{ sessionId: 's1', sessionName: 'Unrelated', workingDir: '/home/u/needle-dir', timestamp: 100 }],
+    });
+    const res = searchSources('needle', data);
+    expect(res.totalResults).toBe(1);
+    expect(res.groups[0].results[0].sessionId).toBe('s1');
+  });
+
+  it('matches event details, not just title', () => {
+    const data = sources({
+      events: [
+        {
+          sessionId: 's1',
+          sessionName: 'A',
+          eventId: 'e1',
+          title: 'nothing here',
+          details: 'a needle in details',
+          timestamp: 100,
+        },
+      ],
+    });
+    const res = searchSources('needle', data);
+    expect(res.totalResults).toBe(1);
+  });
+
+  it('is case-insensitive', () => {
+    const data = sources({
+      sessions: [{ sessionId: 's1', sessionName: 'NEEDLE', workingDir: '/x', timestamp: 100 }],
+    });
+    expect(searchSources('needle', data).totalResults).toBe(1);
+  });
+});
+
+describe('searchSources — ranking (exact before recency)', () => {
+  it('places exact name matches before more-recent partial matches', () => {
+    const data = sources({
+      sessions: [
+        { sessionId: 'old-exact', sessionName: 'needle', workingDir: '/x', timestamp: 1 },
+        { sessionId: 'new-partial', sessionName: 'needle-haystack', workingDir: '/x', timestamp: 9999 },
+      ],
+    });
+    const res = searchSources('needle', data);
+    const ids = res.groups[0].results.map((r) => r.sessionId);
+    expect(ids).toEqual(['old-exact', 'new-partial']);
+    expect(res.groups[0].results[0].exactMatch).toBe(true);
+  });
+
+  it('within the same exactness tier, sorts newest first', () => {
+    const data = sources({
+      sessions: [
+        { sessionId: 'older', sessionName: 'needle-a', workingDir: '/x', timestamp: 10 },
+        { sessionId: 'newer', sessionName: 'needle-b', workingDir: '/x', timestamp: 20 },
+      ],
+    });
+    const res = searchSources('needle', data);
+    expect(res.groups[0].results.map((r) => r.sessionId)).toEqual(['newer', 'older']);
+  });
+});
+
+describe('searchSources — caps', () => {
+  it('enforces the per-group cap and flags truncated', () => {
+    const sessions = Array.from({ length: SEARCH_PER_GROUP_CAP + 5 }, (_, i) => ({
+      sessionId: `s${i}`,
+      sessionName: `needle ${i}`,
+      workingDir: '/x',
+      timestamp: i,
+    }));
+    const res = searchSources('needle', sources({ sessions }));
+    expect(res.groups[0].results.length).toBe(SEARCH_PER_GROUP_CAP);
+    expect(res.truncated).toBe(true);
+  });
+
+  it('enforces the total cap across groups', () => {
+    // Fill every group to its per-group cap; total must not exceed SEARCH_TOTAL_CAP.
+    const mk = <T>(n: number, f: (i: number) => T) => Array.from({ length: n }, (_, i) => f(i));
+    const data = sources({
+      sessions: mk(SEARCH_PER_GROUP_CAP, (i) => ({
+        sessionId: `s${i}`,
+        sessionName: `needle ${i}`,
+        workingDir: '/x',
+        timestamp: i,
+      })),
+      events: mk(SEARCH_PER_GROUP_CAP, (i) => ({
+        sessionId: `e${i}`,
+        sessionName: 'E',
+        eventId: `e${i}`,
+        title: `needle ${i}`,
+        details: '',
+        timestamp: i,
+      })),
+      files: mk(SEARCH_PER_GROUP_CAP, (i) => ({
+        sessionId: `f${i}`,
+        sessionName: 'F',
+        fileName: `needle${i}.txt`,
+        relativePath: `d/needle${i}.txt`,
+        timestamp: i,
+        itemId: `f${i}`,
+      })),
+    });
+    const res = searchSources('needle', data);
+    expect(res.totalResults).toBeLessThanOrEqual(SEARCH_TOTAL_CAP);
+  });
+});
+
+describe('searchSources — result card shape & path safety', () => {
+  it('shapes a file result with a relative-path jump target and no absolute leakage', () => {
+    const data = sources({
+      files: [
+        {
+          sessionId: 's1',
+          sessionName: 'Alpha',
+          fileName: 'needle.txt',
+          relativePath: 'docs/needle.txt',
+          timestamp: 123,
+          itemId: 'item-1',
+        },
+      ],
+    });
+    const r = searchSources('needle', data).groups[0].results[0];
+    expect(r.type).toBe('file');
+    expect(r.sessionId).toBe('s1');
+    expect(r.sessionName).toBe('Alpha');
+    expect(r.timestamp).toBe(123);
+    expect(r.jumpTo).toEqual({
+      kind: 'file-preview',
+      sessionId: 's1',
+      targetId: 'item-1',
+      relativePath: 'docs/needle.txt',
+    });
+    // No absolute path anywhere in the serialized result.
+    expect(JSON.stringify(r)).not.toContain('/home/');
+  });
+
+  it('drops files that only have a server-private absolute path (no relativePath)', () => {
+    const data = sources({
+      files: [
+        {
+          sessionId: 's1',
+          sessionName: 'Alpha',
+          fileName: 'needle.txt',
+          relativePath: undefined,
+          timestamp: 1,
+          itemId: 'i1',
+        },
+      ],
+    });
+    // fileName still matches, but there is no safe relativePath to expose → still
+    // returned, but jumpTo must not carry an absolute path.
+    const res = searchSources('needle', data);
+    if (res.totalResults > 0) {
+      expect(res.groups[0].results[0].jumpTo.relativePath).toBeUndefined();
+    }
+  });
+
+  it('truncates long snippets', () => {
+    const longDetail = 'needle ' + 'x'.repeat(500);
+    const data = sources({
+      events: [{ sessionId: 's1', sessionName: 'A', eventId: 'e1', title: 'evt', details: longDetail, timestamp: 1 }],
+    });
+    const r = searchSources('needle', data).groups[0].results[0];
+    expect(r.snippet.length).toBeLessThanOrEqual(200);
+  });
+
+  it('returns empty for a blank query', () => {
+    const data = sources({ sessions: [{ sessionId: 's1', sessionName: 'needle', workingDir: '/x', timestamp: 1 }] });
+    expect(searchSources('', data).totalResults).toBe(0);
+  });
+});

test/terminal-history-schema.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { SettingsUpdateSchema } from '../src/web/schemas.js';
+import {
+  MAX_TERMINAL_SCROLLBACK_LINES,
+  MIN_TERMINAL_SCROLLBACK_LINES,
+  MAX_TERMINAL_BUFFER_BYTES,
+  MIN_TERMINAL_BUFFER_BYTES,
+} from '../src/config/terminal-history.js';
+
+describe('SettingsUpdateSchema — terminal history keys', () => {
+  it('accepts valid in-range terminal-history settings', () => {
+    const res = SettingsUpdateSchema.safeParse({
+      terminalScrollbackLines: 100_000,
+      tmuxHistoryLimit: 100_000,
+      terminalBufferMaxBytes: 32 * 1024 * 1024,
+      terminalBufferTrimBytes: 24 * 1024 * 1024,
+    });
+    expect(res.success).toBe(true);
+  });
+
+  it('accepts a settings object that omits the terminal-history keys', () => {
+    const res = SettingsUpdateSchema.safeParse({ allowedTools: 'Bash' });
+    expect(res.success).toBe(true);
+  });
+
+  it('rejects scrollback below the minimum', () => {
+    const res = SettingsUpdateSchema.safeParse({ terminalScrollbackLines: MIN_TERMINAL_SCROLLBACK_LINES - 1 });
+    expect(res.success).toBe(false);
+  });
+
+  it('rejects scrollback above the maximum', () => {
+    const res = SettingsUpdateSchema.safeParse({ tmuxHistoryLimit: MAX_TERMINAL_SCROLLBACK_LINES + 1 });
+    expect(res.success).toBe(false);
+  });
+
+  it('rejects buffer bytes outside the byte bounds', () => {
+    expect(SettingsUpdateSchema.safeParse({ terminalBufferMaxBytes: MIN_TERMINAL_BUFFER_BYTES - 1 }).success).toBe(
+      false
+    );
+    expect(SettingsUpdateSchema.safeParse({ terminalBufferMaxBytes: MAX_TERMINAL_BUFFER_BYTES + 1 }).success).toBe(
+      false
+    );
+  });
+
+  it('rejects non-integer values', () => {
+    expect(SettingsUpdateSchema.safeParse({ terminalScrollbackLines: 12_345.5 }).success).toBe(false);
+  });
+
+  it('rejects trim > max via the cross-field superRefine', () => {
+    const res = SettingsUpdateSchema.safeParse({
+      terminalBufferMaxBytes: 4 * 1024 * 1024,
+      terminalBufferTrimBytes: 8 * 1024 * 1024,
+    });
+    expect(res.success).toBe(false);
+    if (!res.success) {
+      expect(res.error.issues.some((i) => i.path.includes('terminalBufferTrimBytes'))).toBe(true);
+    }
+  });
+
+  it('allows trim == max', () => {
+    const res = SettingsUpdateSchema.safeParse({
+      terminalBufferMaxBytes: 8 * 1024 * 1024,
+      terminalBufferTrimBytes: 8 * 1024 * 1024,
+    });
+    expect(res.success).toBe(true);
+  });
+});

test/terminal-history.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import {
+  resolveTerminalHistoryConfig,
+  DEFAULT_TERMINAL_SCROLLBACK_LINES,
+  DEFAULT_TMUX_HISTORY_LIMIT,
+  DEFAULT_TERMINAL_BUFFER_MAX_BYTES,
+  DEFAULT_TERMINAL_BUFFER_TRIM_BYTES,
+  MIN_TERMINAL_SCROLLBACK_LINES,
+  MAX_TERMINAL_SCROLLBACK_LINES,
+  MIN_TERMINAL_BUFFER_BYTES,
+  MAX_TERMINAL_BUFFER_BYTES,
+} from '../src/config/terminal-history.js';
+
+describe('resolveTerminalHistoryConfig', () => {
+  it('returns the documented defaults for empty settings', () => {
+    const cfg = resolveTerminalHistoryConfig({});
+    expect(cfg).toEqual({
+      terminalScrollbackLines: DEFAULT_TERMINAL_SCROLLBACK_LINES,
+      tmuxHistoryLimit: DEFAULT_TMUX_HISTORY_LIMIT,
+      terminalBufferMaxBytes: DEFAULT_TERMINAL_BUFFER_MAX_BYTES,
+      terminalBufferTrimBytes: DEFAULT_TERMINAL_BUFFER_TRIM_BYTES,
+    });
+  });
+
+  it('defaults match the prior hardcoded values (behavior-neutral)', () => {
+    expect(DEFAULT_TMUX_HISTORY_LIMIT).toBe(50_000);
+    expect(DEFAULT_TERMINAL_SCROLLBACK_LINES).toBe(50_000);
+    expect(DEFAULT_TERMINAL_BUFFER_MAX_BYTES).toBe(2 * 1024 * 1024);
+    expect(DEFAULT_TERMINAL_BUFFER_TRIM_BYTES).toBe(1.5 * 1024 * 1024);
+  });
+
+  it('passes valid in-range values through unchanged', () => {
+    const cfg = resolveTerminalHistoryConfig({
+      terminalScrollbackLines: 50_000,
+      tmuxHistoryLimit: 75_000,
+      terminalBufferMaxBytes: 16 * 1024 * 1024,
+      terminalBufferTrimBytes: 8 * 1024 * 1024,
+    });
+    expect(cfg).toEqual({
+      terminalScrollbackLines: 50_000,
+      tmuxHistoryLimit: 75_000,
+      terminalBufferMaxBytes: 16 * 1024 * 1024,
+      terminalBufferTrimBytes: 8 * 1024 * 1024,
+    });
+  });
+
+  it('clamps scrollback/history below MIN up to the floor', () => {
+    const cfg = resolveTerminalHistoryConfig({
+      terminalScrollbackLines: 1,
+      tmuxHistoryLimit: 0,
+    });
+    expect(cfg.terminalScrollbackLines).toBe(MIN_TERMINAL_SCROLLBACK_LINES);
+    expect(cfg.tmuxHistoryLimit).toBe(MIN_TERMINAL_SCROLLBACK_LINES);
+  });
+
+  it('clamps scrollback/history above MAX down to the ceiling', () => {
+    const cfg = resolveTerminalHistoryConfig({
+      terminalScrollbackLines: 999_999_999,
+      tmuxHistoryLimit: 999_999_999,
+    });
+    expect(cfg.terminalScrollbackLines).toBe(MAX_TERMINAL_SCROLLBACK_LINES);
+    expect(cfg.tmuxHistoryLimit).toBe(MAX_TERMINAL_SCROLLBACK_LINES);
+  });
+
+  it('clamps the buffer byte caps to their MIN/MAX bounds', () => {
+    const tooSmall = resolveTerminalHistoryConfig({ terminalBufferMaxBytes: 1 });
+    expect(tooSmall.terminalBufferMaxBytes).toBe(MIN_TERMINAL_BUFFER_BYTES);
+
+    const tooLarge = resolveTerminalHistoryConfig({ terminalBufferMaxBytes: 1024 * 1024 * 1024 });
+    expect(tooLarge.terminalBufferMaxBytes).toBe(MAX_TERMINAL_BUFFER_BYTES);
+  });
+
+  it('keeps trim <= max (trim is capped to the resolved max)', () => {
+    const cfg = resolveTerminalHistoryConfig({
+      terminalBufferMaxBytes: 4 * 1024 * 1024,
+      terminalBufferTrimBytes: 64 * 1024 * 1024,
+    });
+    expect(cfg.terminalBufferTrimBytes).toBeLessThanOrEqual(cfg.terminalBufferMaxBytes);
+    expect(cfg.terminalBufferTrimBytes).toBe(4 * 1024 * 1024);
+  });
+
+  it('caps the default trim to a lowered max', () => {
+    // Default trim (1.5MB) exceeds a 1MB max → trim must fall to the max.
+    const cfg = resolveTerminalHistoryConfig({ terminalBufferMaxBytes: 1 * 1024 * 1024 });
+    expect(cfg.terminalBufferTrimBytes).toBe(1 * 1024 * 1024);
+  });
+
+  it('truncates fractional inputs to integers', () => {
+    const cfg = resolveTerminalHistoryConfig({ terminalScrollbackLines: 12_345.9 });
+    expect(cfg.terminalScrollbackLines).toBe(12_345);
+  });
+
+  it('falls back to defaults for non-number / non-finite inputs', () => {
+    const cfg = resolveTerminalHistoryConfig({
+      terminalScrollbackLines: 'lots' as unknown as number,
+      tmuxHistoryLimit: NaN,
+      terminalBufferMaxBytes: null as unknown as number,
+      terminalBufferTrimBytes: Infinity,
+    });
+    expect(cfg.terminalScrollbackLines).toBe(DEFAULT_TERMINAL_SCROLLBACK_LINES);
+    expect(cfg.tmuxHistoryLimit).toBe(DEFAULT_TMUX_HISTORY_LIMIT);
+    expect(cfg.terminalBufferMaxBytes).toBe(DEFAULT_TERMINAL_BUFFER_MAX_BYTES);
+    // trim default is min(DEFAULT_TRIM, resolvedMax) — here resolvedMax is the default max.
+    expect(cfg.terminalBufferTrimBytes).toBe(DEFAULT_TERMINAL_BUFFER_TRIM_BYTES);
+  });
+
+  it('uses an empty object when called with no argument', () => {
+    expect(resolveTerminalHistoryConfig().tmuxHistoryLimit).toBe(DEFAULT_TMUX_HISTORY_LIMIT);
+  });
+});