feat(ultracode): in-page agent transcript windows + minimize-to-tab (1.1.14)

Clicking an agent card opens its live transcript as an in-page connected
floating window instead of a detached browser popup. The "−" button on both
run and agent windows now minimizes into the originating session tab as a
restorable ULTRA badge (🧬 runs, 📄 transcripts). Removes the old
collapse-to-header behavior.

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

CHANGELOG.md

@@ -1,5 +1,148 @@
 # aicodeman
 
+## 1.1.14
+
+### Patch Changes
+
+- Ultracode (Workflow-tool) floating windows — agent transcripts in-page, and minimize-to-tab.
+  - **Agent transcripts open in-page, connected, instead of a detached browser popup.** Clicking an agent card (in a run window or the dock panel) now opens the agent's live transcript as its own draggable floating window, tied by a connector line to its parent run window (falling back to the run's session tab if that window has since closed) — the same line idiom the run windows use. Re-clicking a card focuses the existing window; closing it removes the window and its line. (Previously this spawned a separate `window.open` browser popup.)
+  - **The window "−" button now minimizes into the originating session tab**, mirroring the subagent-window idiom. The window genie-animates into its tab and is tracked there; the tab shows an `ULTRA` badge whose hover/click dropdown lists each minimized item (🧬 run windows, 📄 agent transcripts). Click an item to restore its floating window, or dismiss it with ×. A run minimized while still active keeps tracking in the background and its badge auto-clears shortly after the run finishes. Both run windows and agent-transcript windows minimize into the same merged badge.
+  - Removed the old collapse-to-header behavior that the "−" button previously triggered (now superseded by minimize-to-tab).
+
+## 1.1.13
+
+### Patch Changes
+
+- Keep the `/compact` button in the extended (full) mobile keyboard accessory bar; only the simple bar drops it. (1.1.12 had removed it from both.)
+
+## 1.1.12
+
+### Patch Changes
+
+- Remove the `/compact` button from the mobile keyboard accessory bar. It had been reintroduced in 1.1.10; this removes the button from both the simple and full accessory-bar layouts (the underlying command handler is left in place as inert plumbing).
+
+## 1.1.11
+
+### Patch Changes
+
+- Ultracode (Workflow-tool) run visualization — much better live tracking.
+
+  While a run is in flight, the watcher previously showed empty agent slots ("agent N", 0 tokens, raw `wf_…` id as the title) because the detailed completion JSON only lands when the run finishes. The live path now enriches in-flight runs directly from the on-disk transcript tree:
+  - **Real per-agent stats mid-run** — tokens and tool-call counts are parsed from each `agent-<id>.jsonl` transcript (tool counts match the final accounting exactly; token totals land within ~1% of the completion value), with model and a prompt preview. All mtime-cached (transcripts, journal, and script meta) so idle polls do no extra reads.
+  - **Readable window/run title** — workflow name, summary, and phases are derived from the persisted `workflows/scripts/<name>-<runId>.js` instead of showing the raw run id.
+  - **Agent status colors** — done agents show green, working agents show yellow (this also fixes the run/agent status badges, which referenced undefined `--success`/`--warning` CSS variables and were rendering with no color).
+  - **Connector line** — the floating-window → session-tab line now uses the session-tab accent blue (was purple).
+  - **Click a run to open its floating window** — clicking a workflow in the dock panel opens (or focuses) its floating window with the connector line, in addition to the auto-popped windows.
+  - Agents are ordered by journal launch order; concurrent run-detail fetches are de-duplicated.
+
+## 1.1.10
+
+### Patch Changes
+
+- Mobile CJK input, iPad keyboard accessory bar, and terminal touch interaction fixes (PRs #130, #131).
+
+  Mobile / CJK (#130):
+  - Restore reliable real-time CJK (e.g. Pinyin) composition in the always-visible textarea, and refocus input when the terminal is tapped.
+  - Stop clearing the textarea during `compositionstart` — some IMEs include existing text in the composition region, and clearing it mid-composition corrupted input.
+  - iPad-specific fixes: `#cjkInput` positioning, paste-dialog placement, and duplicated voice-dictation output.
+  - Split CJK keyboard positioning by device size (phones vs iPad use different keyboard offsets).
+  - iPad accessory-bar styling/positioning: moved the accessory-bar and paste-overlay base styles out of the `max-width:1023px`-gated mobile stylesheet so iPad landscape (≥1024px) renders them correctly.
+  - Raise the toolbar stacking context while the case-settings popover is open so the popover is no longer hidden behind the toolbar.
+  - Restore the `/compact` button to the keyboard accessory bar (with double-tap confirmation, like `/clear`); the paste dialog now submits pasted text on "Send".
+
+  Terminal touch + forced redraw (#131):
+  - Enable terminal touch interaction on all touch devices and show the stop button on touch devices.
+  - Add an 8px tap threshold so micro-drift is treated as a tap, not a scroll, fixing cases where a tap failed to register.
+  - Tap-to-position the cursor via a synthesized mouse report, gated on the live mouse-tracking mode so it never triggers local text selection when tracking is off; let SGR mouse reports through to the PTY even while the CJK input field owns focus.
+  - Suppress the cursor/momentum side effects of a sub-threshold tap so a jittery tap no longer both positions the cursor and starts a momentum fling.
+  - New opt-in, per-device "Redraw Terminal" header button (`showRedrawButton`, default off) that forces an xterm redraw via a resize jitter to clear occasional rendering glitches; the resize path now accepts a `force` flag (threaded through the session, HTTP, and WebSocket resize routes) that guarantees a SIGWINCH/redraw at the current device's size without bypassing multi-client resize arbitration.
+
+## 1.1.9
+
+### Patch Changes
+
+- Two welcome-screen tunnel changes:
+  - **UI (Daylight Blue skin):** the **Cloudflare Tunnel** button is now purple (was orange/yellow), keeping the three welcome buttons visually distinct — Claude blue, Tunnel purple, OpenCode green.
+  - **Enable a tunnel without `CODEMAN_PASSWORD`, with a warning.** Previously enabling the Cloudflare tunnel with no password set was hard-refused unless you set `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1`. Now you can opt in straight from the browser: clicking the tunnel toggle without a password pops a **security confirm dialog** ("publishes this machine to a public URL with no login — effectively remote code execution; set CODEMAN_PASSWORD instead"), and only on confirm does it enable, sending an explicit per-request `acknowledgeUnauthTunnel:true`. The server logs a loud warning whenever a passwordless public tunnel starts. curl/API/CLI callers are unchanged — still refused unless they set a password, set the env var, or pass `acknowledgeUnauthTunnel:true` — so nothing gets exposed accidentally. The acknowledgment is an action field and is never persisted to settings.json.
+
+## 1.1.8
+
+### Patch Changes
+
+- UI (Daylight Blue skin): give the welcome-screen action buttons distinct colors instead of all reading blue. **Run Claude Code** keeps the blue accent, **Cloudflare Tunnel** now uses Cloudflare's brand orange, and **Run OpenCode** uses an emerald green — so the three are visually distinguishable at a glance. Scoped to the default `daylight-blue` skin only (daylight-green and OG are unchanged), with matching hover/active states and dark ink for contrast. Verified in a real browser: the three buttons compute to blue / orange / green gradients on the welcome overlay.
+
+## 1.1.7
+
+### Patch Changes
+
+- Fix: terminal scroll-up (scrollback) intermittently breaking for **Claude** sessions — most visible on iPhone, where you suddenly "can't scroll up the Claude console."
+
+  Root cause: Claude Code periodically emits alternate-screen switches (`\x1b[?1049h`/`\x1b[?47h`/`\x1b[?1047h`), scrollback-erase (`\x1b[3J`), and mouse-tracking enables — typically when it draws a full-screen UI (pickers/dialogs, the boot welcome). xterm.js obeys these by moving to the scrollback-less alternate buffer (or wiping saved lines / hijacking the wheel), so the conversation history becomes unreachable until Claude returns to its normal view. Codeman already stripped these sequences so history stays scrollable, but the strip was gated to **Codex mode only** — Claude (and the equivalent buffer-replay path) let them through.
+
+  The strip is now shared via a single `isAltScreenStripMode(mode)` predicate (`codex || claude`) applied at BOTH sites that were Codex-only: the live PTY stream (`Session._handleTerminalOutput`, including the split-across-chunks carry reassembly) and the `/terminal` buffer replay used on tab-switch/reconnect. `shell` is deliberately excluded so full-screen TUIs run from a shell (vim/less/htop) keep their alternate screen; `opencode` is also unchanged.
+
+  Verified end-to-end on an isolated instance against a real Claude session: the replayed buffer and live stream now carry zero alt-screen/scrollback-erase/mouse sequences, the terminal stays in the normal buffer with scrollback intact, and touch swipe-up scrolls correctly. Covered by new unit tests (`test/claude-scrollback-strip.test.ts`); the existing Codex strip tests are unchanged.
+
+## 1.1.6
+
+### Patch Changes
+
+- Fix: ultracode floating run windows now pop on a fresh device/browser that loads while a run is already active.
+
+  `ultracodeFloatingWindows` syncs from the server (it's a non-display setting), but on a first-time device the SSE `getLightState` run snapshot can seed the run list BEFORE the async settings load resolves — so the floating-window gate read `false` at that instant and skipped any already-active run, leaving the window un-popped until the next ~10s watcher tick. The app now re-runs `syncAllUltracodeFloatingWindows()` once server settings finish loading (in the `loadAppSettingsFromServer().then()` callback), so an in-flight run pops its window immediately. Idempotent: open windows are left as-is, and if the setting is off any premature windows are torn down. Verified end-to-end against a real in-flight run on an isolated instance — a pristine browser (empty localStorage) seeds the setting from the server and pops the active run's window ~0.4s after first paint.
+
+  Also corrected a stale `@fileoverview` comment in `ultracode-windows.js` that claimed the floating windows are gated on `showUltracodeAgents`; they are gated on the dedicated `ultracodeFloatingWindows` toggle (only the docked "Ultracode Agents" panel uses `showUltracodeAgents`).
+
+## 1.1.5
+
+### Patch Changes
+
+- Fix: the Ultracode Agents panel's (×) Close button now fully hides the panel.
+
+  `closeUltracodeAgentsPanel()` only removed the `open` class, which drops the bottom-docked drawer to its collapsed _peek_ state (the 36px header strip stays visible) rather than closing it — so clicking (×) looked like it did nothing. It now also adds the `hidden` class (`display:none`), mirroring `closeSubagentsPanel()`. It deliberately does NOT flip the `showUltracodeAgents` setting (that also gates the run watcher and floating windows); the header launcher button reopens the panel. Verified in a real browser: after (×) the panel computes `display:none`.
+
+## 1.1.4
+
+### Patch Changes
+
+- Fix: ultracode floating run windows (and the live dock panel) now appear DURING an in-flight Workflow/ultracode run, not only after it finishes.
+
+  The Workflow runtime writes the run-state file `…/workflows/wf_<id>.json` only at completion (always a terminal status); while a run is live, its only on-disk state is the sibling `…/subagents/workflows/wf_<id>/` transcript tree. `workflow-run-watcher` previously scanned only the completion file, so it never observed a run until it was already terminal — and the floating-window auto-pop is gated on an ACTIVE run, so it never fired for a live run (the feature was effectively dead for in-flight runs).
+
+  The watcher now ALSO scans the `subagents/workflows/wf_<id>/` transcript tree and synthesizes a minimal ACTIVE run (status `running`, agent slots keyed by their `agentId` so the agent-card → live-transcript click still works, `lastActivityAt` from the newest agent/journal mtime, per-agent done/running derived from the run journal's `result` events) when no completion file exists yet. When the run finishes, the real `wf_<id>.json` supersedes the synthesized record (same runId), restoring full phase/token detail and the normal finish → 8s-grace auto-close flow. The watcher stays standalone (it never imports subagent-watcher). Verified end-to-end against a real in-flight run; adds unit coverage for live synthesis, agentId preservation, journal-derived state, empty-dir skipping, and completion-file precedence.
+
+## 1.1.3
+
+### Patch Changes
+
+- Ultracode floating run windows + a dedicated toggle to control them.
+  - **New: floating ultracode run windows.** When enabled, each active ultracode / Workflow run pops a small draggable window (like the file browser) connected by a glowing line to its originating session tab — the same connector-line idiom as subagent windows. The tab is resolved by matching the run's `sessionUuid` to a session's `claudeSessionId`. The window mirrors the live agent grid (phases, per-agent model / tokens burned / tool calls / state), auto-closes a few seconds after its run finishes, and remembers windows you explicitly dismiss so they don't re-pop. These windows are **additional to** the existing docked "Ultracode Agents" master-detail panel, which is unchanged.
+  - **New setting "Ultracode Floating Windows"** (App Settings → Display), **default OFF**, independent of the "Ultracode Agents" panel toggle. Either toggle now starts the server-side workflow-run watcher (at boot and on live settings change), so the floating windows work even with the docked panel off.
+  - Internals: new frontend module `ultracode-windows.js` (load order 15.5); ultracode connector lines are appended into the shared `#connectionLines` SVG within the existing batched read/write reflow pass in `subagent-windows.js`; new `ultracodeFloatingWindows` app-settings key in `schemas.ts`; watcher gating in `server.ts` + `system-routes.ts` now ORs both ultracode toggles.
+  - Docs: `CLAUDE.md` brought up to date for the 1.1.2 ultracode/workflow-run subsystem (Agents / Frontend / Types / Config inventories, JS load order, a Key Patterns entry) and the new floating-windows feature.
+
+## 1.1.2
+
+### Patch Changes
+
+- Ultracode/Workflow run visualization + subagent discovery fixes.
+  - **Ultracode / Workflow run visualization** (new, opt-in): App Settings → Display → "Ultracode Agents" (`showUltracodeAgents`, default OFF) adds a master-detail tab that shows ultracode / Workflow-tool runs like Claude Code's "working agents" view — the LEFT pane lists runs and their phases (selectable tasks), the RIGHT pane shows each run's agents with model, live state, tokens burned, and tool calls. Clicking an agent opens its live transcript. Backed by a new standalone workflow-run watcher that reads the per-run state JSON (stripping the heavy embedded script/result/logs so payloads stay small), exposes `GET /api/workflows` and `GET /api/workflows/:runId`, and broadcasts `workflow:run_discovered/updated/removed` SSE events. The header launcher and panel stay hidden until the setting is enabled (the setting is synced across devices, not per-device).
+  - **Subagent tracking discovery fix**: restored subagent tracking after Claude Code changed the on-disk format from `agent-*.jsonl` to `agent-*.meta.json` (background agents were showing 0). Also discovers workflow-nested subagents under `subagents/workflows/<wf>/` and hardens the meta→transcript upgrade path so an agent re-points to its `.jsonl` transcript once it appears.
+  - **File viewer**: opens audio, SVG, and other binary files the same way the attachments viewer does.
+  - **Tooling**: hardened the real-overview screenshot capture script and documented the `deviceScaleFactor` / static-cache gotchas.
+
+## 1.1.1
+
+### Patch Changes
+
+- Six reviewed contributor PRs (all adversarially reviewed and fixed before merge):
+  - **Markdown sanitizer hardened against mutation-XSS (#126).** The denylist `_sanitizeHtml` is replaced with vendored DOMPurify 3.4.8 (authentic, byte-matched to the official dist) wired via a new `sanitize-html.js` allowlist, with a fail-closed escape fallback. The curated allowlist is genuinely enforced (no `USE_PROFILES` override) so non-markdown tags and svg/math/style/script/event-handler/`javascript:` vectors are stripped while legitimate markdown survives.
+  - **Hook-event secret now required unconditionally (#127).** The `/api/hook-event` + `/api/status-telemetry` localhost bypass requires the per-instance hook secret whether or not a managed tunnel is running, closing the own-loopback-reverse-proxy gap. A self-heal refreshes pre-secret hook configs in existing cases on spawn so password-protected installs don't silently 401 their hooks. No-password loopback installs are unaffected.
+  - **`codeman doctor` dependency checker (#125).** New `doctor`/`check-deps` command probes Node, the agent CLIs, tmux, and document converters per environment (linux/darwin/win32/wsl), with grouped or `--json` output and a non-zero exit when a required tool is missing. Requires Node 22+, reports `pdftoppm` (used for PDF/Office thumbnails), and validates `--category`.
+  - **macOS Option / physical-key session shortcuts (#129).** Tab switching matches physical key codes (`e.code`) so Option+1–9 works on macOS layouts that remap Option, plus Option/Alt+`[`/`]` for previous/next session — without leaking escape sequences into the focused terminal.
+  - **Desktop session tabs auto-wrap to a second row on overflow (#128)** instead of horizontal scrolling (off when the manual two-row layout is pinned; mobile/tablet unchanged), re-evaluated on window resize.
+  - **CJK input textarea hidden on the welcome screen (#123)** so it no longer floats over the welcome overlay, and re-shown on session entry; vertical centering fixed.
+
 ## 1.1.0
 
 ### Minor Changes

CLAUDE.md

@@ -56,7 +56,7 @@ 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.0 (must match `package.json`)
+**Version**: 1.1.14 (must match `package.json`)
 
 ## Project Overview
 
@@ -108,6 +108,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **`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`.
 - **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).
 
 **Import conventions**: Utils from `./utils`, types from `./types` (barrel), config from specific `./config/*` files.
 
@@ -123,7 +124,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **Respawn** | `src/respawn-controller.ts` ★ + 4 helpers (`-adaptive-timing`, `-health`, `-metrics`, `-patterns`) | Read `docs/respawn-state-machine.md` first |
 | **Ralph** | `src/ralph-tracker.ts` ★, `src/ralph-loop.ts` + 5 helpers (`-config`, `-fix-plan-watcher`, `-plan-tracker`, `-stall-detector`, `-status-parser`) | Read `docs/ralph-wiggum-guide.md` first |
 | **Orchestrator** | `src/orchestrator-loop.ts`, `src/orchestrator-planner.ts`, `src/orchestrator-verifier.ts` | Read `docs/orchestrator-loop-architecture.md` first |
-| **Agents** | `src/subagent-watcher.ts` ★, `src/team-watcher.ts`, `src/bash-tool-parser.ts`, `src/transcript-watcher.ts` | |
+| **Agents** | `src/subagent-watcher.ts` ★, `src/team-watcher.ts`, `src/bash-tool-parser.ts`, `src/transcript-watcher.ts`, `src/workflow-run-watcher.ts` | `workflow-run-watcher` is STANDALONE (never touches `subagent-watcher`) — see Key Patterns |
 | **AI** | `src/ai-checker-base.ts`, `src/ai-idle-checker.ts`, `src/ai-plan-checker.ts` | |
 | **Tasks** | `src/task.ts`, `src/task-queue.ts`, `src/task-tracker.ts` | |
 | **State** | `src/state-store.ts`, `src/run-summary.ts`, `src/session-lifecycle-log.ts` | |
@@ -131,14 +132,14 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **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` | |
-| **Frontend** | `src/web/public/app.js` (~3.9K lines, core) + 5 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`) + 7 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 5 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `input-cjk.js`, `image-input.js`) + `sw.js` | |
-| **Types** | `src/types/index.ts` (barrel) → 15 domain files; also `src/types.ts` root re-export | See `@fileoverview` in index.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 |
 
 ★ = 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`.
 
 **Local packages**: `packages/xterm-zerolag-input/` — local echo overlay for xterm.js; single-source, bundled to the gitignored `vendor/xterm-zerolag-input.js` and consumed by `app.js` (see Gotchas). `packages/gesture-control/` (`codeman-gesture-control`) — hand-tracking overlay source; built to `src/web/public/gesture/gesture-codeman.js` via `npm run build:gesture` (see Frontend → Gesture control).
 
-**Config**: `src/config/` — 12 files, no barrel (`index.ts`) exists; import from the specific file.
+**Config**: `src/config/` — 14 files, no barrel (`index.ts`) exists; import from the specific file.
 
 **Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap`, `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority).
 
@@ -173,11 +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`.
+
 **Port interfaces**: Routes declare dependencies via port interfaces (`src/web/ports/`). Routes use intersection types (e.g., `SessionPort & EventPort`).
 
 ### Frontend
 
-Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `app.js`(6) → `terminal-ui.js`(7) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `orchestrator-panel.js`(9.5) → `settings-ui.js`(10) → `panels-ui.js`(11) → `session-ui.js`(12) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15) → `image-input.js`(16). `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData).
+Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `sanitize-html.js`(5.6) → `app.js`(6) → `terminal-ui.js`(7) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `orchestrator-panel.js`(9.5) → `settings-ui.js`(10) → `panels-ui.js`(11) → `ultracode-panel.js`(11.5) → `session-ui.js`(12) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15) → `ultracode-windows.js`(15.5) → `image-input.js`(16). `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData).
 
 **Z-index layers**: subagent windows (1000), plan agents (1100), mobile/tablet fixed header (1200, `mobile.css`), modals on ≤768px (1300 — must beat the fixed header or the modal close button is buried; bug fixed in `b8cb467`), log viewers (2000), image popups (3000), local echo overlay (7).
 
@@ -208,7 +211,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 | **QR Auth** | Single-use 6-char tokens (60s TTL) for tunnel login. See `docs/qr-auth-plan.md` |
 | **Sessions** | 24h cookie (`codeman_session`), auto-extend, device context audit |
 | **Rate limit** | 10 failed auth/IP → 429 (15min decay). QR has separate limiter |
-| **Hook bypass** | `/api/hook-event` (and `/api/status-telemetry`, the statusLine exporter) exempt from auth (localhost-only, schema-validated). While the **managed tunnel** runs, the bypass additionally requires the per-instance `X-Codeman-Hook-Secret` header (COD-54, `config/hook-secret.ts`): hook curls cat the secret file at exec time via `$CODEMAN_HOOK_SECRET_FILE` (session env), failures rate-limit in a dedicated bucket (never lock out login). External loopback proxies (own cloudflared/`tailscale serve`) aren't detected — plain bypass still applies there. Tunnel enable also **refuses** without `CODEMAN_PASSWORD` unless `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` (COD-55) |
+| **Hook bypass** | `/api/hook-event` (and `/api/status-telemetry`, the statusLine exporter) exempt from auth (localhost-only, schema-validated). While the **managed tunnel** runs, the bypass additionally requires the per-instance `X-Codeman-Hook-Secret` header (COD-54, `config/hook-secret.ts`): hook curls cat the secret file at exec time via `$CODEMAN_HOOK_SECRET_FILE` (session env), failures rate-limit in a dedicated bucket (never lock out login). External loopback proxies (own cloudflared/`tailscale serve`) aren't detected — plain bypass still applies there. Tunnel enable **refuses** without `CODEMAN_PASSWORD` unless exposure is acknowledged — via `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` (env, COD-55) **or** the per-request `acknowledgeUnauthTunnel:true` action field (1.1.9): the welcome/settings tunnel toggle pops a security confirm dialog and, on confirm, resends with that flag (server logs a loud warning on every passwordless tunnel start; curl/API stay refused without password/env/flag). The flag is an action field, never persisted |
 | **Env vars** | `CODEMAN_MUX` (managed session), `CODEMAN_API_URL` (auto-set for hooks), `CODEMAN_ALLOWED_HOSTS` (extra Host/Origin allowlist entries for reverse proxies, comma-separated; bare `.suffix` matches subdomains) |
 | **Validation** | Zod schemas, path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`) |
 | **Headers** | CORS localhost-only, CSP, X-Frame-Options, HSTS if HTTPS |

README.md

@@ -483,7 +483,8 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
 |----------|--------|
 | `Ctrl/Cmd+W` | Kill active session |
 | `Ctrl/Cmd+Tab` | Next session |
-| `Alt+1`–`Alt+9` | Switch to tab N |
+| `Alt/Option+[` / `Alt/Option+]` | Previous / next session |
+| `Alt/Option+1`-`Alt/Option+9` | Switch to tab N (physical keys, so macOS Option layouts work) |
 | `Ctrl+Shift+{` / `Ctrl+Shift+}` | Move active tab left / right |
 | `Ctrl/Cmd+L` | Clear terminal |
 | `Ctrl+Shift+R` | Restore terminal size |

docs/ultracode-agent-viz-plan.md

@@ -0,0 +1,271 @@
+# Ultracode / Workflow Agent Visualization — Design & Implementation Plan
+
+> **Status: IMPLEMENTED (2026-06-15, rev. 3) — Phases 1–3 shipped & verified; Phase 4 (live-transcript link) deferred.** A dedicated, opt-in **master-detail tab** (`showUltracodeAgents`, default OFF) shows ultracode/Workflow runs as Claude Code's "working agents" TUI: LEFT = runs + phases (selectable tasks), RIGHT = each run's agents with model, live state, **tokens burned**, and **tool calls**.
+>
+> ### What rev. 3 changed vs. rev. 2 (decided during implementation against on-disk truth)
+> 1. **UI is a master-detail TAB, not grouped floating subagent windows.** The user asked for the CC "working agents" view (left task picker, right agent stats). Built as a new docked panel `#ultracodeAgentsPanel` (clones `.subagents-panel` master-detail CSS) + `src/web/public/ultracode-panel.js` — NOT via `openSubagentWindow`/grouped windows.
+> 2. **STANDALONE — zero edits to `subagent-watcher.ts`.** w16-claudeman's commit `f6a30d7` already discovers the per-agent workflow *transcripts* (`watchWorkflowDirs`). The data the view needs (run/phase/per-agent tokens+toolCalls) lives in the *run-state* JSON, read by a brand-new `src/workflow-run-watcher.ts` (globs the disjoint `…/workflows/wf_*.json` tree). No shared files with w16.
+> 3. **No per-agent transcript streaming needed for v1.** The run-state JSON already carries `tokens`/`toolCalls`/`state`/`label`/`phase` per agent, so the whole view reads from `wf_<runId>.json` alone. (Phase 4 will optionally link a card to its already-tracked transcript via `agentId` — no watcher edits.)
+> 4. **Agent states are `start | progress | done`** (verified on disk) — NOT running/queued. `start`=queued (no agentId/tokens/toolCalls yet), `done` has `durationMs`/`resultPreview`.
+> 5. **The run JSON's `script` (15–660KB embedded JS), `scriptPath`, `result`, `logs` are STRIPPED in the watcher** before caching/broadcast (a 28-agent run drops 174KB → ~25KB; `promptPreview`/`resultPreview` truncated).
+> 6. **SSE/snapshot ship lightweight run SUMMARIES (no `agents[]`); the RIGHT pane fetches the full run** via `GET /api/workflows/:runId` on selection. (A 25-run snapshot is ~20KB vs ~900KB if it carried every agent.) The LEFT list shows ALL cached runs (LRU-bounded), not a recency window — a run browser must show past runs.
+>
+> _Original rev. 2 proposal (grouped floating windows, extending subagent-watcher) preserved below for context; superseded by the above._
+
+### What changed in rev. 2 (vs. the first draft)
+
+1. **No backend cross-watcher coupling.** The per-agent label/phase/agentType/state **join moves to the frontend at render time** — the run object already carries every agent's entry keyed by `agentId`. This deletes `subagent-watcher`'s backward dependency on `workflow-run-watcher` (`getAgentLabel()` + its TTL cache), removes the registration-vs-run-state **race** (labels always track the latest `workflow:run_updated`), and drops the per-agent `meta.json` read from the hot path.
+2. **`SubagentInfo` grows by 2 fields, not 4** (`isWorkflowAgent`, `workflowRunId`) — both derivable from the file path alone at registration, zero extra I/O. `agentType`/`label`/`phase`/`state` come from the run object on the frontend.
+3. **The `isInternalAgent` bypass covers BOTH drop sites** — `registerAgentFile` *and* the late re-resolution in `processEntry`. The first draft named only one.
+4. **De-duplicated.** Each trap (`journal.jsonl`, the `projects/*/*/workflows` depth, the gate-mismatch lesson, reuse-not-rebuild) is stated once in its owning section.
+
+### Code-reuse verified against the tree (2026-06-14)
+
+Confirmed present and shaped as assumed: `subagent-watcher.ts` — `watchSubagentDir`/`registerAgentFile`/`tailFile`/`processEntry`, `getRecentSubagents`, `isInternalAgent` (drops on `MIN_DESCRIPTION_LENGTH=5`), `STARTUP_MAX_FILE_AGE_MS=4h`, `MAX_TRACKED_AGENTS`, `knownSubagentDirs`/`dirWatchers`. `team-watcher.ts` — `configMtimes` mtime-skip + chokidar + `setInterval` poll. `server.ts` — `setupSubagentWatcherListeners`, `getLightState()` (`subagents: getRecentSubagents(15)`, `LIGHT_STATE_CACHE_TTL_MS=1000`), `isSubagentTrackingEnabled()` (`settings.subagentTrackingEnabled ?? true`). Frontend — `_SSE_HANDLER_MAP`, `this.subagents` Map, `handleInit`/`cleanupAllFloatingWindows`, `renderSubagentPanel`/`_renderSubagentPanelImmediate`, `getTeammateBadgeHtml`, `openSubagentWindow` + `.subagent-window-parent` sub-header.
+
+## 1. The enabling fact: on-disk artifacts
+
+The Workflow tool (what `ultracode` drives) persists each workflow agent as a transcript under the **same `subagents/` directory Codeman already watches**, one level deeper. Empirically verified against a real run (`wf_a8e09f2c-550`); **re-confirm the shape against a fresh run at implementation time** (§8 mandates a live e2e pass anyway):
+
+```
+~/.claude/projects/<projHash>/<sessionUuid>/
+  ├─ subagents/
+  │    ├─ agent-XX.jsonl                    ← regular Task subagent (tracked today)
+  │    └─ workflows/wf_<runId>/
+  │         ├─ agent-YY.jsonl               ← WORKFLOW agent — IDENTICAL line format
+  │         ├─ agent-YY.meta.json           ← {"agentType":"workflow-subagent"} (optional enrichment)
+  │         └─ journal.jsonl                ← run journal {type:"started",...} — MUST be skipped
+  └─ workflows/wf_<runId>.json              ← run state: runId, workflowName, summary, status,
+                                               phases[], workflowProgress[], totals (DIFFERENT tree)
+```
+
+The per-agent `.jsonl` line shape is identical to a regular subagent transcript:
+
+```jsonc
+{ "parentUuid": null, "isSidechain": true, "agentId": "ac6a1d27012a64e38",
+  "type": "user" | "assistant", "message": { "role": "...", "content": "..." }, ... }
+```
+
+Because the line shape is identical, the entire existing parse→event→render pipeline works unchanged once discovery reaches those files. The only new data is the **run-level metadata** in `workflows/wf_<runId>.json` (name, summary, phases, and `workflowProgress[]` — the per-agent labels/state/tools), which supplies the group header and per-agent labels.
+
+**Can show:** per-agent live transcript (tool calls, messages, results); per-agent status (active/idle/completed via the existing mtime/PID/pgrep liveness); per-agent model + running token totals (from each agent's JSONL `message.usage`, exactly as today); the run's `workflowName`/`summary`/`phases[]`; per-agent `label`/`phaseTitle`/`state`/`lastToolName` (from `workflowProgress[]`); grouping under `wf_<runId>`.
+
+**Cannot show:** anything absent from the artifacts — a live phase cursor beyond `workflowProgress[].state`; an authoritative **budget/cost ceiling** (only consumed totals exist — `usage` + run-state `totalTokens`, no remaining-budget field); runs older than `STARTUP_MAX_FILE_AGE_MS` (4h) after a server restart (live monitoring only).
+
+## 2. Architecture
+
+**Decision: EXTEND `subagent-watcher.ts` for per-agent discovery/streaming; ADD a thin `workflow-run-watcher.ts` (modeled on `team-watcher.ts`) for the group-header metadata ONLY. The agent→run-metadata join happens on the FRONTEND, so the two watchers stay decoupled.**
+
+- The per-agent JSONL is identical in shape, so re-running it through `registerAgentFile()` → `tailFile()` → `processEntry()` and the existing `subagent:*` events is free and reconnect-safe (those agents land in `agentInfo`, replayed by `getRecentSubagents(15)`). A parallel per-agent watcher would duplicate the liveness/token/tool-call/SSE machinery for zero benefit.
+- Run metadata lives in a *different* file under a *different* tree (`workflows/wf_<runId>.json`, sibling to `subagents/`). A small `WorkflowRunWatcher` watching `projects/*/*/workflows/wf_*.json` (mtime-skip, like `team-watcher`'s `configMtimes`) is the clean home; folding it into `subagent-watcher` would entangle two unrelated watch roots and put a JSON re-read in the hot per-line path.
+- **The two watchers never call each other.** The frontend receives both streams and joins agent→label by `agentId` at render time (the run object carries every agent's entry). This removes the timing coupling entirely.
+
+```
+~/.claude/projects/<projHash>/<sessionUuid>/
+  ├─ subagents/
+  │    ├─ agent-XX.jsonl ──────────────► SubagentWatcher (EXTENDED: also descends
+  │    └─ workflows/wf_<runId>/                workflows/wf_<runId>/, tags isWorkflowAgent+runId)
+  │         ├─ agent-YY.jsonl ─┐           reuse registerAgentFile/tailFile/processEntry
+  │         └─ journal.jsonl (SKIP)        emits subagent:* (now w/ 2 workflow fields)
+  └─ workflows/wf_<runId>.json ──────► WorkflowRunWatcher (NEW, team-watcher-shaped)
+       {workflowName,phases,workflowProgress[]}   emits workflow:run_discovered|updated|removed
+
+                         server.ts
+   setupSubagentWatcherListeners()    ──► broadcast(subagent:*)     ─┐
+   setupWorkflowRunWatcherListeners() ──► broadcast(workflow:run_*)  │ SSE
+   getLightState(): subagents + workflowRuns ───────────────────────┘
+                              │
+                              ▼  app.js dispatch table
+   panels-ui: partition this.subagents by workflowRunId; header + per-agent
+   labels JOINED from this.workflowRuns.get(runId).agents (by agentId)
+```
+
+## 3. Backend changes (ordered, file-by-file)
+
+### 3a. `src/subagent-watcher.ts` — nested discovery + 2 tag fields
+
+**(1) Extend `SubagentInfo` with exactly two optional fields** (optional → regular subagents and the wire shape are unaffected):
+
+```ts
+isWorkflowAgent?: boolean;   // true when discovered under subagents/workflows/<wf_runId>/
+workflowRunId?: string;      // e.g. "wf_23dbeab2-152" (parent dir name)
+```
+
+Both are derived from the **file path alone** at registration — no extra reads. They ride existing `subagent:discovered|updated|completed` payloads (no new per-agent event). Do **not** add `agentType`/`label`/`phase`/`workflowName` here — those come from the run object on the frontend (§4c).
+
+**(2) Constant.** `const WORKFLOWS_SUBDIR = 'workflows';` near the existing dir constants.
+
+**(3) `watchSubagentDir()` — descend into `workflows/<wf_runId>/`.** After the existing direct-child registration loop:
+
+```ts
+// Workflow agents live one level deeper: subagents/workflows/<wf_runId>/agent-*.jsonl
+const wfRoot = join(dir, WORKFLOWS_SUBDIR);
+try {
+  for (const runId of await readdir(wfRoot)) {
+    if (!runId.startsWith('wf_')) continue;
+    await this.watchWorkflowRunDir(join(wfRoot, runId), projectHash, sessionId, runId);
+  }
+} catch { /* no workflows subdir — normal for most sessions */ }
+```
+
+The existing `fs.watch(dir, …)` on `subagents/` is **non-recursive on Linux** and won't fire for writes inside `workflows/<runId>/`, so each run dir needs its own watcher.
+
+**(4) New private `watchWorkflowRunDir(runDir, projectHash, sessionId, runId)`** — clone `watchSubagentDir`'s structure, but:
+- Register only files matching `^agent-.*\.jsonl$`, **explicitly skipping `journal.jsonl`** (it ends in `.jsonl` but is `{type:'started',…}`, not a transcript — registering it would create a phantom agent).
+- Call `registerAgentFile(filePath, projectHash, sessionId, isInitialScan, runId)` so the agent is tagged.
+- Install one `watch(runDir, …)` per run dir; on `error` and `stop()`, reuse the existing teardown (close + delete from `dirWatchers`/`knownSubagentDirs`/`dirWatcherErrorHandlers`).
+- Guard re-registration **per run dir** in `knownSubagentDirs`, **not** `wfRoot` — the 5s full scan must still re-`readdir(wfRoot)` to pick up *new* `wf_<runId>` dirs created mid-session.
+
+**(5) `registerAgentFile()` — accept + apply `runId`.** Add a trailing optional `runId?: string`. When set, the whole change is:
+
+```ts
+if (runId) { info.isWorkflowAgent = true; info.workflowRunId = runId; }
+```
+
+No `meta.json` read, no run-state lookup, no description override. `agentId`s are globally unique `a<16hex>` (verified: 0 collisions across a 370-agent corpus), so keep the flat `agentInfo` map keyed by `agentId` — do **not** switch to a composite key. Add a one-line dev-assert log if `agentInfo.has(agentId)` with a *different* `workflowRunId`, so a future collision is observable.
+
+**(6) `isInternalAgent` bypass — BOTH drop sites.** Workflow agents have no Task-tool spawn record, so `_resolveDescription` yields only the first-user-message fallback (often a long phase prompt) or empty → `isInternalAgent` (`length < MIN_DESCRIPTION_LENGTH`) would wrongly drop them. They are real by construction (the `subagents/workflows/wf_*/` path is the discriminator). Gate the drop on `!info.isWorkflowAgent` at **both** places:
+- `registerAgentFile` initial check (`isInternalAgent(description)`),
+- `processEntry`'s late re-resolution (the second `isInternalAgent` call).
+
+**(7) `stop()` teardown.** Per-run watchers live in `dirWatchers`, so the existing close-all loop covers them — verify no separate map was introduced (24h runs spawn many `wf_<runId>` dirs → FSWatcher leak risk).
+
+### 3b. NEW `src/workflow-run-watcher.ts` (singleton, EventEmitter — model on `team-watcher.ts`)
+
+- **Watch root:** `~/.claude/projects/<projHash>/<sessionUuid>/workflows/wf_*.json` — **two** levels under `projects` (verified: `projects/*/workflows` is empty; must be `projects/*/*/workflows/`). chokidar `depth:3` + a poll fallback, mirroring `team-watcher`'s dual discovery + interval.
+- **mtime-skip:** `runMtimes: Map<absPath, number>` (mirror `team-watcher.configMtimes`).
+- **Parse:** read `wf_<runId>.json`, take the **top-level structured keys** (`runId`, `workflowName`, `summary`, `status`, `phases:[{title,detail}]`, `agentCount`, `defaultModel`, `durationMs`, `totalTokens`, `totalToolCalls`, `workflowProgress[]`). **Do NOT parse the embedded `script` string** — name/phases/summary are already top-level; the script's `export const meta` is redundant and costly. Derive `sessionUuid` from the dir name, `projectHash` from the dir above; expose `getProjectHash(workingDir)` for Codeman-session correlation.
+- **`workflowProgress[] → agents[]`:** filter `type === 'workflow_agent'`, map each to a `WorkflowAgentEntry` (§3c) keyed by `agentId`. **This array is the join source the frontend uses** — no backend `getAgentLabel()` API, no TTL cache, no import from `subagent-watcher`.
+- **Emit** `workflow:run_discovered|updated|removed` carrying `WorkflowRunInfo`; removal by set-diff (mirror `team-watcher`).
+- **Lifecycle:** `start()`/`stop()` with `CleanupManager` teardown of chokidar + interval + caches; `LRUMap`-bounded run cache (24h memory rule).
+
+### 3c. `src/types/` — workflow run types
+
+```ts
+export interface WorkflowAgentEntry {   // one workflowProgress[type==='workflow_agent']
+  agentId: string; label: string; phaseIndex?: number; phaseTitle?: string;
+  agentType?: string; model?: string; state?: string;       // 'done'|'running'|'queued'|...
+  lastToolName?: string; lastToolSummary?: string; tokens?: number; toolCalls?: number;
+}
+export interface WorkflowRunInfo {
+  runId: string; sessionUuid: string; projectHash: string;
+  workflowName?: string; summary?: string; status?: string;  // 'running'|'completed'|...
+  phases: Array<{ title: string; detail?: string }>;
+  agentCount?: number; defaultModel?: string;
+  agents: WorkflowAgentEntry[];          // workflowProgress filtered to workflow_agent, keyed by agentId
+  startedAt?: number; durationMs?: number; totalTokens?: number; totalToolCalls?: number;
+}
+```
+
+The two `SubagentInfo` workflow fields stay inline in `subagent-watcher.ts` (matching the existing convention).
+
+### 3d. `src/web/sse-events.ts` — register run events
+
+Add `workflow:run_discovered`, `workflow:run_updated`, `workflow:run_removed` after the `subagent:*` block and to the `SseEvent` union. **No new per-agent event** — workflow agents reuse `subagent:*`.
+
+### 3e. `src/web/server.ts` — bridge, snapshot, gating
+
+- **`setupWorkflowRunWatcherListeners()`** (beside `setupSubagentWatcherListeners`): map the three run events → `this.broadcast(...)`. Add `cleanupWorkflowRunWatcherListeners()` (store handler refs).
+- **Start/stop:** call `workflowRunWatcher.start()`/`.stop()` beside `subagentWatcher`, **gated on the same enable condition** (§3f).
+- **`getLightState()`:** add `workflowRuns: workflowRunWatcher.getRecentRuns(15)` beside `subagents: subagentWatcher.getRecentSubagents(15)` so headers replay on reconnect (agents already replay via `subagents`). Keep the `LIGHT_STATE_CACHE_TTL_MS` memoization.
+- **Gating read:** add `isWorkflowAgentTrackingEnabled()` mirroring `isSubagentTrackingEnabled()` (boot-time `dataPath('settings.json')` read). Gate `workflowRunWatcher.start()` **and** the subagent-watcher `workflows/` descent (§3a-3) on `showUltracodeAgents` so non-opted-in users never register historical workflow agents.
+
+### 3f. `src/web/schemas.ts` — settings key
+
+Add `showUltracodeAgents: z.boolean().optional()` to the `.strict()` settings update schema near `showPlanUsageLimits` (required — `.strict()` 400s the whole PUT on an unknown key).
+
+### 3g. `src/web/routes/system-routes.ts` — poll API
+
+- `GET /api/subagents` and `GET /api/sessions/:id/subagents` include workflow agents once registered — **no change** (they carry `isWorkflowAgent`/`workflowRunId`; a consumer joins to `/api/workflows/:runId` for labels).
+- Add `GET /api/workflows` → `workflowRunWatcher.getRecentRuns()` and `GET /api/workflows/:runId` (uniform `ApiResponse` contract; headers are also in `getLightState`).
+- `GET /api/subagents/:agentId/transcript` works for workflow agents (they're in `agentInfo`) — no new route.
+
+## 4. Frontend changes (file-by-file)
+
+### 4a. `src/web/public/constants.js`
+- Add the three SSE strings to `SSE_EVENTS`, matching §3d exactly (`WORKFLOW_RUN_DISCOVERED: 'workflow:run_discovered'`, etc.).
+- Reuse `ZINDEX_SUBAGENT_BASE=1000` for the agent windows (they ARE subagent windows). The group **header/cluster** is in-flow panel DOM, not a floating window — no new z-index (1100 is plan-subagent).
+
+### 4b. `src/web/public/app.js`
+- Constructor: `this.workflowRuns = new Map();  // runId -> WorkflowRunInfo` beside `this.subagents`.
+- `_SSE_HANDLER_MAP`: add three rows → `_onWorkflowRunDiscovered/Updated/Removed` (must exist before `connectSSE` builds the wrappers).
+- `handleInit`: after seeding `data.subagents`, seed `this.workflowRuns` from `data.workflowRuns` (clear-then-set). **Clear `this.workflowRuns` everywhere the subagent Maps are cleared** (incl. `cleanupAllFloatingWindows`) — 24h leak guard.
+
+### 4c. `src/web/public/panels-ui.js` — the join lives here
+- `_onWorkflowRunDiscovered/Updated(data)` → `this.workflowRuns.set(data.runId, data)` + debounced re-render; `_onWorkflowRunRemoved` → delete + re-render.
+- **No change to `_onSubagentDiscovered/Updated`** — they already store the whole payload, so the 2 new fields ride along.
+- `renderSubagentPanel`/`_renderSubagentPanelImmediate`: when `showUltracodeAgents` is on, **partition `this.subagents` into flat (no `workflowRunId`) vs grouped-by-`workflowRunId`**. Flat agents render exactly as today. For each group: build the header from `this.workflowRuns.get(runId)` (`workflowName` + phase/status chip from `phases[]`), then render that run's agents reusing the existing per-agent row markup. **Per-agent label/phase/agentType come from the JOIN** — build `Map(agentId → entry)` from `this.workflowRuns.get(runId).agents` and look each agent up by `agent.agentId`; render the small chip via the `getTeammateBadgeHtml` pattern. (If the run object hasn't arrived yet, fall back to the agent's own `description` — the run `:updated` event will fill it in on the next render.)
+- `findParentSessionForSubagent` is unchanged — workflow agent `sessionId === session.claudeSessionId`. **Do not conflate `workflowRunId` with `sessionId`.**
+
+### 4d. `src/web/public/subagent-windows.js`
+**Decision: REUSE `.subagent-window` per agent + a group sub-header — do NOT build a cluster class.** A cluster path duplicates Map/z-index/drag/cleanup/persistence for no functional gain; reuse keeps connection lines, minimize-to-tab, and `localStorage` persistence. In `openSubagentWindow`, where the optional `.subagent-window-parent` sub-header is built: when `agent.workflowRunId` is set, inject a `.subagent-workflow-header` showing `this.workflowRuns.get(runId)?.workflowName` + the joined agent's `label`/phase (look up by `agentId`), mirroring the `from <session>` sub-header. Respect the existing skip guards (teammate-terminal windows, minimized/`_lazyTerminal`).
+
+**Do NOT auto-open windows** for workflow agents — a multi-phase run can spawn many, against the 50-window/60fps budget + `MAX_TRACKED_AGENTS=500`. They render collapsed in the grouped panel; the user expands via the existing panel buttons.
+
+### 4e. `src/web/public/settings-ui.js` + `index.html`
+- `index.html` Panels block: add a `settings-item` checkbox `id="appSettingsShowUltracodeAgents"` ("Show ULTRACODE / Workflow Agents").
+- `openAppSettings`: load `settings.showUltracodeAgents` with `false` fallback (mirror `showPlanUsageLimits`).
+- `saveAppSettings`: collect `showUltracodeAgents` into the fresh settings literal (uncollected keys reset to default every save).
+- Live-apply on toggle: re-run `renderSubagentPanel()` (show/hide group sections) — a panel re-render, not a CSS-class strip.
+- **SYNCED, not per-device:** do NOT add `showUltracodeAgents` to `displayKeys` and do NOT strip it in the per-device block. A synced value gives the server-side gate (`isWorkflowAgentTrackingEnabled`, §3e) one canonical truth to decide whether to run the watcher; a per-device value can't gate a process-wide watcher. (Contrast `showResponseViewer`, pure client display.)
+- `styles.css` + `mobile.css`: add `.subagent-workflow-header` and `.subagent-group-badge` next to `.subagent-window-parent`; mirror device overrides in `mobile.css`.
+
+## 5. Settings / opt-in wiring
+
+- **Key:** `showUltracodeAgents` (boolean, **default OFF**). Fallback `false` in `openAppSettings`; "absent ⇒ off" in `isWorkflowAgentTrackingEnabled()`. Schema `z.boolean().optional()` in the `.strict()` update schema, kept OUT of `displayKeys` (synced).
+- **Runtime gating:** `workflowRunWatcher.start()` and the subagent-watcher `workflows/` descent run only when the boot-time `settings.json` read reports `showUltracodeAgents === true` (mirroring `isSubagentTrackingEnabled`). The frontend additionally gates display. Toggling at runtime gates **display** immediately (panel re-render); the **watcher branch** picks up on next boot — matches existing `subagentTrackingEnabled` semantics. (Optional polish: restart just the workflow watcher on toggle for instant on/off.)
+
+## 6. SSE events
+
+**Reused (no change):** `subagent:discovered|updated|tool_call|tool_result|progress|message|completed`. Workflow agents flow through these; payloads now carry the optional `isWorkflowAgent`/`workflowRunId` fields on `SubagentInfo`. SSE payloads aren't schema-gated (typed only at `broadcast()` call sites), so the new fields propagate with zero friction.
+
+**New (3 events, run-level metadata):**
+
+| Event (backend const / frontend key) | Payload |
+|---|---|
+| `workflow:run_discovered` / `WORKFLOW_RUN_DISCOVERED` | `WorkflowRunInfo` |
+| `workflow:run_updated` / `WORKFLOW_RUN_UPDATED` | `WorkflowRunInfo` |
+| `workflow:run_removed` / `WORKFLOW_RUN_REMOVED` | `{ runId: string }` |
+
+Sync requirement (CLAUDE.md): each must appear in **both** `sse-events.ts` (§3d) and `constants.js` `SSE_EVENTS` (§4a), be emitted via `broadcast()` in `setupWorkflowRunWatcherListeners()` (§3e), and have a dispatch-table row + `_on*` handler (§4b/§4c).
+
+## 7. Edge cases & cleanup
+
+- **`journal.jsonl` phantom-agent trap** — owned by §3a-4: run-dir registration requires the `agent-` prefix and excludes `journal.jsonl`.
+- **`isInternalAgent` over-filtering** — owned by §3a-6: bypass at BOTH drop sites; titled from the frontend join (or the description fallback).
+- **No workflow agents in the flat list** — `renderSubagentPanel` partitions on `agent.workflowRunId` (§4c). When the toggle is OFF, the descent never ran, so they aren't in `this.subagents` at all.
+- **Completion/idle** — keep the existing per-agent mtime/PID/pgrep liveness as the per-card source of truth. Optionally render a group-level "workflow done" badge from run-state `status==='completed'`.
+- **Limits** — `MAX_TRACKED_AGENTS=500` LRU-evicts workflow agents in the same flat map; no auto-open (50-window budget); the 4h `STARTUP_MAX_FILE_AGE_MS` skip means a run completed >4h ago won't reload after restart (acceptable — live monitoring).
+- **Reconnect/replay** — agents via `getRecentSubagents(15)`; headers via `workflowRuns: getRecentRuns(15)` in `getLightState`. `handleInit` clears `this.workflowRuns` alongside the subagent Maps.
+- **Watcher teardown** — every per-run `fs.watch` and the chokidar watcher closes in `stop()` and on `error`; `CleanupManager` for the new watcher (24h runs create many run dirs).
+- **CLAUDE.md discipline** — read-only `~/.claude/...` artifacts; no new `~/.codeman/...` paths, no env-var prefixes touched. Claude-mode-only by nature (external CLIs don't write workflow transcripts).
+
+## 8. Testing & verification
+
+- **Unit (pure):**
+  - `test/workflow-run-watcher.test.ts`: feed a scrubbed fixture `wf_<runId>.json` → assert `WorkflowRunInfo` extraction (name/summary/phases, `workflowProgress`→`agents[]` keyed by `agentId`), mtime-skip, removal-by-set-diff.
+  - Extend `subagent-watcher` coverage: temp `subagents/workflows/wf_X/agent-Y.jsonl` + a stray `journal.jsonl` → assert `agent-Y` registered with `isWorkflowAgent`/`workflowRunId` and `journal.jsonl` NOT registered; assert a short-description workflow agent is NOT dropped at **either** `isInternalAgent` site.
+- **Route/inject (`app.inject`):** `GET /api/workflows` + `:runId` return the `ApiResponse` envelope; `GET /api/subagents` includes a tagged agent.
+- **Frontend (vm-sandbox, like `test/run-mode-ui.test.ts`):** dispatch `subagent:discovered` with `workflowRunId` + `workflow:run_discovered` → assert `renderSubagentPanel` produces a group section under the workflow name with the agent inside it (label sourced from the **join**, not flat); assert order-independence (agent before run, and run before agent both resolve); assert OFF hides the section.
+- **REQUIRED real end-to-end** (the always-end-to-end-test rule — the plan-usage chip shipped *dead* from a gate mismatch): on dev/beta with `showUltracodeAgents` ON, **drive a real ultracode/workflow run**, then (1) `curl …/api/workflows | jq` shows the live run with `agents[]`; (2) `curl …/api/subagents | jq '.data[]|select(.isWorkflowAgent)'` shows tagged agents; (3) watch `/api/events` for `workflow:run_discovered` + `subagent:discovered` with the workflow fields; (4) Playwright (`waitUntil:'domcontentloaded'`, wait 3–4s) asserts the grouped DOM cluster renders with the workflow-name header and live status. Verify path gates against `GET /api/sessions` `workingDir`. **Test against a LIVE run** — all at-rest runs are `completed`/`done`; `running`/`queued` states only exist mid-run.
+
+## 9. Phased rollout
+
+| Phase | Scope | Done-check | Size |
+|---|---|---|---|
+| **P1 — Backend discovery + tagging (gated, no UI)** | §3a (nested descent, `journal.jsonl` skip, 2 `SubagentInfo` fields, `isInternalAgent` bypass ×2) + §3f schema key + §3e gate read. No run watcher yet. | With `showUltracodeAgents` forced on, `curl /api/subagents \| jq '.data[]\|select(.isWorkflowAgent)'` lists real workflow agents during a live run; flat subagents unchanged; `tsc --noEmit` + targeted watcher test green. | S–M |
+| **P2 — Run-state metadata + SSE** | §3b (`workflow-run-watcher.ts`) + §3c types + §3d/§3e (SSE, bridge, `getLightState` replay) + §3g routes. | `curl /api/workflows \| jq` returns runs with `agents[]`/`phases`; SSE emits `workflow:run_discovered`; reconnect snapshot carries `workflowRuns`. | M |
+| **P3 — Frontend grouped UI** | §4a–§4d (constants, app.js state/dispatch/init, panels-ui grouped render + **agent→label join**, subagent-windows group sub-header). Reuse `.subagent-window`; no auto-open. | Playwright: live run renders a group section under the workflow name with per-agent rows + live status + joined labels; flat subagents stay flat; expand opens a window with the workflow sub-header. | M |
+| **P4 — Settings toggle + polish + docs** | §4e (checkbox, settings-ui load/save/live-apply, SYNCED), styles/mobile, phase chips, CLAUDE.md "Key Patterns" entry + this doc's status → SHIPPED. | Toggling the checkbox shows/hides the cluster live (no reload for display); OFF by default on a fresh install; CI green. | S |
+
+Each phase is independently shippable: P1 is invisible (gated, no UI), P2 adds an API with no UI dependency, P3 lights up the UI for flag-enablers, P4 exposes the toggle and finalizes defaults/docs.
+
+## 10. Effort & risk
+
+**Size:** P1 = S–M, P2 = M, P3 = M, P4 = S. Total ≈ **M** (one focused engineer, ~2–4 days incl. the real end-to-end run — down from the first draft's M-L now that the backend join/coupling is gone).
+
+**Top 3 risks:**
+
+1. **Non-recursive watch on Linux misses live writes.** `fs.watch` is non-recursive and `{recursive:true}` is unreliable on Linux → per-`wf_<runId>` watchers (§3a-4) are correct, but the 5s full scan must re-`readdir(wfRoot)` to catch *new* run dirs mid-session, and each watcher must be torn down to avoid FSWatcher leaks in 24h runs. Mitigation: explicit per-run-dir registration + verified `dirWatchers` teardown; chokidar (with `CleanupManager`) only in the new run watcher, where `team-watcher` already proves the pattern.
+2. **Discovery cost / over-registration.** A user with hundreds of historical workflow agents could flood `agentInfo` on boot. Mitigation: the 4h `STARTUP_MAX_FILE_AGE_MS` skip drops old files on the initial scan, the descent only runs when the toggle is on, and `MAX_TRACKED_AGENTS=500` LRU-evicts. Verify boot scan time doesn't regress with the corpus present.
+3. **Shipping-dead-on-a-gate** (the repo's recurring failure mode — the plan-usage chip shipped dead because injection was gated on `CASES_DIR` while real sessions ran elsewhere). Same trap here if the path/mode gate is wrong (e.g. `projects/*/workflows` instead of `projects/*/*/workflows`, or correlation via the wrong session key). Mitigation: the **mandatory live ultracode end-to-end run** in §8 against a real session's `workingDir`, observing the real SSE event + real DOM cluster — not the at-rest corpus, not unit tests alone.

package-lock.json

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

package.json

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

scripts/build.mjs

@@ -67,6 +67,7 @@ appendFileSync(
 
 // 4. Minify frontend assets
 run('minify input-cjk.js', 'npx esbuild dist/web/public/input-cjk.js --minify --outfile=dist/web/public/input-cjk.js --allow-overwrite');
+run('minify sanitize-html.js', 'npx esbuild dist/web/public/sanitize-html.js --minify --outfile=dist/web/public/sanitize-html.js --allow-overwrite');
 run('minify app.js', 'npx esbuild dist/web/public/app.js --minify --outfile=dist/web/public/app.js --allow-overwrite');
 run('minify terminal-ui.js', 'npx esbuild dist/web/public/terminal-ui.js --minify --outfile=dist/web/public/terminal-ui.js --allow-overwrite');
 run('minify respawn-ui.js', 'npx esbuild dist/web/public/respawn-ui.js --minify --outfile=dist/web/public/respawn-ui.js --allow-overwrite');
@@ -90,6 +91,7 @@ console.log('\n[build] content-hash cache busting');
     'notification-manager.js',
     'keyboard-accessory.js',
     'input-cjk.js',
+    'sanitize-html.js',
     'app.js',
     'terminal-ui.js',
     'respawn-ui.js',

scripts/capture-readme-real.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * capture-readme-real.mjs
+ *
+ * Captures README desktop scenes (multi-session dashboard, monitor, subagent
+ * windows) from a REAL Codeman instance — intended to run against an ISOLATED
+ * dev/beta instance (CODEMAN_INSTANCE=beta on :5000) seeded from prod's settings,
+ * NOT prod itself (never touch prod's live sessions).
+ *
+ * Reuses the high-quality capture recipe proven in capture-real-overview.mjs:
+ *   - DSF=2 + ?nowebgl  → crisp retina at the TRUE font size (WebGL doubles
+ *     glyphs under DSF=2; the DOM renderer respects devicePixelRatio).
+ *   - per-device localStorage seeding so the capture matches a real device.
+ *
+ *   SCENE=dashboard|monitor|subagent|all  BASE=http://localhost:5000 \
+ *     OUT=screenshots-readme-real/desktop  node scripts/capture-readme-real.mjs
+ */
+import { chromium } from 'playwright';
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+
+const BASE = process.env.BASE || 'http://localhost:5000';
+const OUT = process.env.OUT || 'screenshots-readme-real/desktop';
+const SKIN = process.env.SKIN || 'daylight-blue';
+const SCENE = process.env.SCENE || 'all';
+const FONT = Math.max(10, Math.min(24, Number(process.env.FONT || 13)));
+const VIEWPORT = { width: Number(process.env.VW || 1280), height: Number(process.env.VH || 720) };
+const DSF = Number(process.env.DSF || 2);
+const PLAN_USAGE = process.env.PLAN_USAGE !== '0';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const url = (extra = '') => {
+  const sep = BASE.includes('?') ? '&' : '?';
+  const params = [];
+  if (DSF > 1) params.push('nowebgl'); // DOM renderer → correct font size at DSF>1
+  if (extra) params.push(extra);
+  return params.length ? `${BASE}${sep}${params.join('&')}` : BASE;
+};
+
+async function newCtx(browser) {
+  const context = await browser.newContext({
+    viewport: VIEWPORT,
+    deviceScaleFactor: DSF,
+    ignoreHTTPSErrors: BASE.startsWith('https'),
+  });
+  const page = await context.newPage();
+  page.setDefaultTimeout(30000);
+  await page.addInitScript(
+    ([skin, planUsage, font]) => {
+      try {
+        localStorage.setItem('codeman:skin', skin);
+        localStorage.setItem('codeman-font-size', String(font));
+        const blob = { skin, showFileBrowser: false, showProjectInsights: false };
+        if (planUsage) blob.showPlanUsageLimits = true;
+        localStorage.setItem('codeman-app-settings', JSON.stringify(blob));
+      } catch {
+        /* ignore */
+      }
+    },
+    [SKIN, PLAN_USAGE, FONT]
+  );
+  return { context, page };
+}
+
+async function bootstrap(page) {
+  await page.waitForFunction(() => window.app && window.app.terminal, { timeout: 20000 });
+  await sleep(1200);
+}
+
+async function listSessions(page) {
+  return page.evaluate(() =>
+    Array.from(window.app.sessions.values()).map((s) => ({ id: s.id, name: s.name, mode: s.mode }))
+  );
+}
+
+async function shoot(page, name) {
+  const out = join(OUT, name);
+  await page.evaluate((f) => {
+    try {
+      if (window.app.setFontSize) window.app.setFontSize(f);
+    } catch {}
+    try {
+      window.app.fitAddon && window.app.fitAddon.fit();
+    } catch {}
+    try {
+      window.app.applyHeaderVisibilitySettings && window.app.applyHeaderVisibilitySettings();
+    } catch {}
+  }, FONT);
+  await sleep(1500);
+  await page.screenshot({ path: out, fullPage: false });
+  console.log('  Saved: ' + out);
+}
+
+async function sceneDashboard(browser) {
+  console.log('Scene: dashboard');
+  const { context, page } = await newCtx(browser);
+  await page.goto(url(), { waitUntil: 'domcontentloaded' });
+  await bootstrap(page);
+  const sessions = await listSessions(page);
+  // Select a claude session so the active terminal shows rich content; all tabs render.
+  const target = sessions.find((s) => s.mode === 'claude') || sessions[0];
+  if (target) await page.evaluate((id) => window.app.selectSession(id), target.id);
+  await sleep(4000);
+  await shoot(page, 'multi-session-dashboard.png');
+  await context.close();
+}
+
+async function sceneMonitor(browser) {
+  console.log('Scene: monitor');
+  const { context, page } = await newCtx(browser);
+  await page.goto(url(), { waitUntil: 'domcontentloaded' });
+  await bootstrap(page);
+  const sessions = await listSessions(page);
+  const target = sessions.find((s) => s.mode === 'claude') || sessions[0];
+  if (target) await page.evaluate((id) => window.app.selectSession(id), target.id);
+  await sleep(2500);
+  // toggleMonitorPanel() opens the panel, clears the hidden state, loads REAL
+  // mux sessions (/api/mux), starts stats, and renders the task panel.
+  await page.evaluate(async () => {
+    try {
+      await window.app.toggleMonitorPanel();
+    } catch {}
+  });
+  await sleep(3000);
+  await shoot(page, 'multi-session-monitor.png');
+  await context.close();
+}
+
+async function sceneSubagent(browser) {
+  console.log('Scene: subagent');
+  const { context, page } = await newCtx(browser);
+  await page.goto(url(), { waitUntil: 'domcontentloaded' });
+  await bootstrap(page);
+  // Select the session whose subagents we want (subagentActiveTabOnly means
+  // app.subagents only fills for the active tab). Prefer SUBAGENT_SID env.
+  const sessions = await listSessions(page);
+  const targetId = process.env.SUBAGENT_SID || (sessions.find((s) => s.mode === 'claude') || sessions[0])?.id;
+  if (targetId) await page.evaluate((id) => window.app.selectSession(id), targetId);
+  // Wait (up to ~25s) for live subagents to arrive via SSE into app.subagents.
+  let agents = [];
+  for (let i = 0; i < 25; i++) {
+    agents = await page.evaluate(() =>
+      Array.from(window.app.subagents?.entries?.() || []).map(([id, a]) => ({ id, name: a.name ?? a.agentType ?? '' }))
+    );
+    if (agents.length >= 1) break;
+    await sleep(1000);
+  }
+  console.log('  live in-browser subagents:', JSON.stringify(agents));
+  if (agents.length === 0) {
+    console.log('  NO live subagents — skipping (stage a longer subagent task and run this while it runs).');
+    await context.close();
+    return;
+  }
+  await page.evaluate(
+    (ids) => {
+      ids.slice(0, 2).forEach((id) => {
+        try {
+          window.app.openSubagentWindow(id);
+        } catch {}
+      });
+    },
+    agents.map((a) => a.id)
+  );
+  await sleep(2000);
+  await page.evaluate(() => {
+    const wins = Array.from(window.app.subagentWindows.values());
+    const place = [
+      { left: 360, top: 60, w: 430, h: 330 },
+      { left: 810, top: 60, w: 430, h: 330 },
+    ];
+    wins.slice(0, 2).forEach((win, i) => {
+      const el = win.element;
+      const p = place[i];
+      el.style.left = p.left + 'px';
+      el.style.top = p.top + 'px';
+      el.style.width = p.w + 'px';
+      el.style.height = p.h + 'px';
+    });
+  });
+  await sleep(1500);
+  await shoot(page, 'subagent-spawn.png');
+  await context.close();
+}
+
+async function main() {
+  mkdirSync(OUT, { recursive: true });
+  const browser = await chromium.launch({
+    headless: true,
+    args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage', '--disable-gpu'],
+  });
+  console.log(`BASE=${BASE} SKIN=${SKIN} DSF=${DSF} VIEWPORT=${VIEWPORT.width}x${VIEWPORT.height} SCENE=${SCENE}`);
+  if (SCENE === 'dashboard' || SCENE === 'all') await sceneDashboard(browser);
+  if (SCENE === 'monitor' || SCENE === 'all') await sceneMonitor(browser);
+  if (SCENE === 'subagent' || SCENE === 'all') await sceneSubagent(browser);
+  await browser.close();
+}
+
+main().catch((e) => {
+  console.error('FATAL', e.message);
+  process.exit(1);
+});

scripts/capture-real-overview.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * capture-real-overview.mjs
+ *
+ * Captures a REAL claude-overview screenshot from a LIVE Codeman server
+ * (no mock injection). Drive a real session to do real work, then run:
+ *
+ *   SID=<sessionId> BASE=http://localhost:5000 OUT=screenshots-real \
+ *     node scripts/capture-real-overview.mjs
+ *
+ * Skin defaults to daylight-blue (prod default) via the localStorage pre-paint
+ * contract in index.html. Output: <OUT>/claude-overview.png at 1280x720 (DSF 2).
+ */
+import { chromium } from 'playwright';
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+
+const SID = process.env.SID;
+const BASE = process.env.BASE || 'http://localhost:5000';
+const OUT = process.env.OUT || 'screenshots-real';
+const SKIN = process.env.SKIN || 'daylight-blue';
+// Unique filename per run (timestamped) so a viewer holding an old render of a
+// fixed path can never shadow a fresh capture. Override with NAME=… if needed.
+const STAMP = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+const NAME = process.env.NAME || `claude-overview-${STAMP}.png`;
+const VIEWPORT = { width: Number(process.env.VW || 1512), height: Number(process.env.VH || 812) };
+// IMPORTANT: default deviceScaleFactor is 1, NOT 2. xterm's WebGL renderer in
+// headless Chromium draws terminal glyphs at ~2× their nominal size when DSF=2
+// (while still reporting nominal 8px cell dims internally, so it can't be caught
+// by measuring terminal.cols/cell — only the pixels reveal it). The HTML chrome
+// is unaffected, so DSF=2 makes ONLY the console font look comically large. DSF=1
+// renders the console at its true size, matching a real (non-headless) browser.
+const DSF = Number(process.env.DSF || 1);
+
+if (!SID) {
+  console.error('SID env var required (the live session id to screenshot)');
+  process.exit(1);
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const main = async () => {
+  mkdirSync(OUT, { recursive: true });
+  const browser = await chromium.launch({
+    headless: true,
+    args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage', '--disable-gpu'],
+  });
+  const context = await browser.newContext({
+    viewport: VIEWPORT,
+    deviceScaleFactor: DSF,
+    ignoreHTTPSErrors: BASE.startsWith('https'),
+  });
+  const page = await context.newPage();
+  page.setDefaultTimeout(30000);
+
+  // Force the skin before any page script runs (pre-paint <head> contract), and
+  // seed the PER-DEVICE display blob so the capture reflects what prod actually
+  // shows on the user's real device — notably the plan-usage chip, which is a
+  // per-device setting (default OFF) deleted from the server payload, so a fresh
+  // browser would otherwise hide it. PLAN_USAGE=0 disables.
+  const PLAN_USAGE = process.env.PLAN_USAGE !== '0';
+  // Terminal console font size. App default is 14px; a fresh headless browser has
+  // no saved codeman-font-size, so it renders at 14 — much larger than a real
+  // device where the console has been zoomed down. Seed a smaller value (clamped
+  // to the app's [10,24] range) so the console font looks normal in the capture.
+  const FONT = Math.max(10, Math.min(24, Number(process.env.FONT || 14)));
+  await page.addInitScript(
+    ([skin, planUsage, font]) => {
+      try {
+        localStorage.setItem('codeman:skin', skin);
+        localStorage.setItem('codeman-font-size', String(font));
+        // Desktop app-settings blob (settings-ui.js getSettingsStorageKey()).
+        // Present these display keys explicitly so the server merge won't seed
+        // side panels open (display keys only seed from server when absent from
+        // localStorage). Matches the clean full-width-terminal reference look.
+        const blob = {
+          skin,
+          showFileBrowser: false,
+          showMonitor: false,
+          showSubagents: false,
+          showProjectInsights: false,
+        };
+        if (planUsage) blob.showPlanUsageLimits = true;
+        localStorage.setItem('codeman-app-settings', JSON.stringify(blob));
+      } catch {
+        /* ignore */
+      }
+    },
+    [SKIN, PLAN_USAGE, FONT]
+  );
+
+  // At DSF>1, xterm's WebGL renderer draws glyphs at ~2x (see DSF comment above).
+  // The app honors a `?nowebgl` URL param that switches to xterm's DOM renderer,
+  // which respects devicePixelRatio correctly — so DSF=2 + nowebgl yields a crisp
+  // 2x (retina) capture at the TRUE font size. Auto-enable it whenever DSF>1.
+  const url = DSF > 1 ? `${BASE}${BASE.includes('?') ? '&' : '?'}nowebgl` : BASE;
+  console.log(`Loading ${url} (DSF=${DSF}) ...`);
+  await page.goto(url, { waitUntil: 'domcontentloaded' });
+  await page.waitForFunction(() => window.app && window.app.terminal, { timeout: 20000 });
+  await sleep(1500);
+
+  console.log(`Selecting session ${SID} ...`);
+  await page.evaluate((sid) => window.app.selectSession(sid), SID);
+
+  // Let the terminal buffer stream in + xterm render + any Ink redraw settle.
+  await sleep(2000);
+
+  // Force a clean fit (avoids capturing a transient pre-fit frame where the
+  // terminal renders at the wrong column count) and re-apply per-device header
+  // visibility so the seeded plan-usage chip is shown.
+  await page.evaluate((font) => {
+    // Force the console font explicitly (setFontSize also re-fits) in case
+    // loadFontSize didn't pick up the seeded value before the session rendered.
+    try {
+      if (window.app.setFontSize) window.app.setFontSize(font);
+      else window.app.terminal.options.fontSize = font;
+    } catch {}
+    try {
+      window.app.fitAddon && window.app.fitAddon.fit();
+    } catch {}
+    try {
+      window.dispatchEvent(new Event('resize'));
+    } catch {}
+    try {
+      window.app.applyHeaderVisibilitySettings && window.app.applyHeaderVisibilitySettings();
+    } catch {}
+  }, FONT);
+  await sleep(3000);
+
+  // Optionally scroll the terminal up to frame the rich tool-call region
+  // (Read/Write/Bash + green test results) instead of the trailing summary.
+  const SCROLL = Number(process.env.SCROLL || 0);
+  if (SCROLL) {
+    await page.evaluate((n) => {
+      const t = window.app && window.app.terminal;
+      if (t && t.scrollLines) t.scrollLines(-n);
+    }, SCROLL);
+    await sleep(800);
+  }
+
+  const outPath = join(OUT, NAME);
+  await page.screenshot({ path: outPath, fullPage: false });
+  console.log(`Saved: ${outPath}`);
+
+  await context.close();
+  await browser.close();
+};
+
+main().catch((e) => {
+  console.error('FATAL', e.message);
+  process.exit(1);
+});

src/cli.ts

@@ -626,4 +626,34 @@ program
     }
   });
 
+program
+  .command('doctor')
+  .alias('check-deps')
+  .description('Check Codeman tool dependencies (Node, Claude CLI, tmux, LibreOffice, MS Office)')
+  .option('--json', 'Output structured JSON instead of a table')
+  .option('--category <name>', 'Only check one category (core|office|other)')
+  .action(async (options) => {
+    const { createRealHost, checkAll } = await import('./utils/dependency-checker.js');
+    const { renderTable, renderJson, computeExitCode } = await import('./utils/dependency-report.js');
+    const { DEPENDENCY_REGISTRY, TOOL_CATEGORIES } = await import('./config/dependency-registry.js');
+
+    if (options.category && !(TOOL_CATEGORIES as readonly string[]).includes(options.category)) {
+      console.error(`Unknown category "${options.category}". Valid categories: ${TOOL_CATEGORIES.join(', ')}`);
+      process.exit(2);
+    }
+
+    const host = createRealHost();
+    const registry = options.category
+      ? DEPENDENCY_REGISTRY.filter((t) => t.category === options.category)
+      : DEPENDENCY_REGISTRY;
+    const results = checkAll(registry, host);
+
+    if (options.json) {
+      console.log(JSON.stringify(renderJson(results, host.environment), null, 2));
+    } else {
+      console.log(renderTable(results, host.environment));
+    }
+    process.exit(computeExitCode(results));
+  });
+
 export { program };

src/config/dependency-registry.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Static registry of downstream tool dependencies probed by
+ * `codeman doctor`. Each entry declares per-environment resolvers and the
+ * skills that use it. EXTENSION POINT: skill-manifest-driven discovery
+ * (COD follow-up) will merge dynamically-found entries into this list.
+ *
+ * @module config/dependency-registry
+ */
+
+export type ProbeEnvironment = 'linux' | 'darwin' | 'win32' | 'wsl';
+
+/** The valid `--category` filter values; single source of truth for the type, the CLI
+ *  help text, and CLI input validation. */
+export const TOOL_CATEGORIES = ['core', 'office', 'other'] as const;
+export type ToolCategory = (typeof TOOL_CATEGORIES)[number];
+
+/** Resolve a binary on the PATH and read its version. */
+export interface PathResolver {
+  kind: 'path';
+  bins: string[];
+  versionArg?: string; // default '--version'
+  versionRegex?: RegExp; // default matches first \d+.\d+(.\d+)?
+}
+
+/** Resolve a Windows-installed app reachable from win32 or WSL. */
+export interface WindowsSideResolver {
+  kind: 'windows-side';
+  appDirs: string[]; // relative to a Program Files root
+  exes: string[]; // candidate executables; first found wins
+}
+
+export interface ResolverSpec {
+  match: ProbeEnvironment[];
+  resolver: PathResolver | WindowsSideResolver;
+}
+
+export interface ToolDependency {
+  id: string;
+  label: string;
+  category: ToolCategory;
+  required: boolean;
+  usedBy?: string[];
+  minVersion?: string;
+  resolvers: ResolverSpec[];
+  installHint?: Partial<Record<ProbeEnvironment, string>>;
+}
+
+const ALL: ProbeEnvironment[] = ['linux', 'darwin', 'wsl', 'win32'];
+
+export const DEPENDENCY_REGISTRY: ToolDependency[] = [
+  {
+    id: 'node',
+    label: 'Node.js',
+    category: 'core',
+    required: true,
+    minVersion: '22.0.0',
+    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['node'], versionArg: '--version' } }],
+    installHint: { linux: 'https://nodejs.org', darwin: 'brew install node', wsl: 'https://nodejs.org' },
+  },
+  {
+    id: 'claude',
+    label: 'Claude CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['Claude Code sessions (default backend)'],
+    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['claude'], versionArg: '--version' } }],
+    installHint: { linux: 'https://docs.claude.com/claude-code', darwin: 'https://docs.claude.com/claude-code' },
+  },
+  {
+    id: 'tmux',
+    label: 'tmux',
+    category: 'core',
+    required: true,
+    resolvers: [{ match: ['linux', 'darwin', 'wsl'], resolver: { kind: 'path', bins: ['tmux'], versionArg: '-V' } }],
+    installHint: { linux: 'sudo apt install tmux', darwin: 'brew install tmux', wsl: 'sudo apt install tmux' },
+  },
+  {
+    id: 'opencode',
+    label: 'OpenCode CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['OpenCode sessions'],
+    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['opencode'], versionArg: '--version' } }],
+  },
+  {
+    id: 'codex',
+    label: 'Codex CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['Codex sessions'],
+    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['codex'], versionArg: '--version' } }],
+  },
+  {
+    id: 'libreoffice',
+    label: 'LibreOffice',
+    category: 'office',
+    required: false,
+    usedBy: ['document preview', 'thumbnails'],
+    resolvers: [
+      {
+        match: ['linux', 'darwin', 'wsl'],
+        resolver: { kind: 'path', bins: ['libreoffice', 'soffice'], versionArg: '--version' },
+      },
+    ],
+    installHint: { linux: 'sudo apt install libreoffice', darwin: 'brew install --cask libreoffice' },
+  },
+  {
+    id: 'pdftoppm',
+    label: 'pdftoppm',
+    category: 'office',
+    required: false,
+    usedBy: ['document preview', 'PDF/Office first-page thumbnails'],
+    // poppler's pdftoppm prints its version to stderr; presence is what matters here.
+    resolvers: [
+      { match: ['linux', 'darwin', 'wsl'], resolver: { kind: 'path', bins: ['pdftoppm'], versionArg: '-v' } },
+    ],
+    installHint: {
+      linux: 'sudo apt install poppler-utils',
+      darwin: 'brew install poppler',
+      wsl: 'sudo apt install poppler-utils',
+    },
+  },
+  {
+    id: 'msoffice',
+    label: 'MS Office',
+    category: 'office',
+    required: false,
+    usedBy: ['document preview', 'thumbnails'],
+    resolvers: [
+      {
+        match: ['wsl', 'win32'],
+        resolver: {
+          kind: 'windows-side',
+          appDirs: ['Microsoft Office/root/Office16'],
+          exes: ['WINWORD.EXE', 'POWERPNT.EXE', 'EXCEL.EXE'],
+        },
+      },
+    ],
+  },
+];

src/config/workflow-config.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Workflow (ultracode) run-watcher polling and cache configuration.
+ *
+ * Controls how frequently WorkflowRunWatcher polls
+ * ~/.claude/projects/<projHash>/<sessionUuid>/workflows/wf_*.json
+ * and how many runs are cached in memory.
+ *
+ * Distinct from the Agent-Teams config (team-config.ts). The run-state JSON is
+ * rewritten on every agent tick across a whole run (28+ agents), so the watcher
+ * relies on a per-file mtime skip; the poll itself is just N stat() calls.
+ *
+ * @module config/workflow-config
+ */
+
+/** Workflow run-state poll interval (ms). Short because a poll is just N mtime stats. */
+export const WORKFLOW_RUN_POLL_INTERVAL_MS = 10_000;
+
+/** Max cached workflow runs (LRU eviction). */
+export const MAX_CACHED_WORKFLOW_RUNS = 100;
+
+/**
+ * Default recency window (minutes) for getRecentRuns(). Generous enough that a
+ * recently-finished long run still appears in the LEFT-pane list — filtered on
+ * last-activity, not start time, so multi-hour runs don't vanish.
+ */
+export const WORKFLOW_RUN_RECENT_WINDOW_MIN = 240;

src/hooks-config.ts

@@ -243,6 +243,43 @@ export async function writeHooksConfig(casePath: string): Promise<void> {
   });
 }
 
+/**
+ * Self-heal a case's hooks block so the COD-91 unconditional hook-secret gate keeps
+ * accepting its hook events.
+ *
+ * `writeHooksConfig` only runs when a case is first CREATED. Cases created before the
+ * X-Codeman-Hook-Secret header was added (COD-54, 2026-06-10) keep hook curls in their
+ * settings.local.json that POST to /api/hook-event WITHOUT the secret — which, once the
+ * gate requires it unconditionally (COD-91), silently 401 on a password-protected
+ * install. This refreshes the hooks block so those stale curls regain the header.
+ *
+ * Deliberately surgical: regenerates ONLY when settings.local.json already contains
+ * Codeman's own hook curls (they target `/api/hook-event`) that lack the secret header.
+ * No-op when the file/hooks are absent (we never impose hooks on a user who removed
+ * them), when the hooks aren't ours, or when the secret is already present — so it never
+ * clobbers a user's customizations and is cheap enough to call on every Claude spawn.
+ */
+export async function refreshStaleHookSecret(casePath: string): Promise<void> {
+  const settingsPath = join(casePath, '.claude', 'settings.local.json');
+  if (!existsSync(settingsPath)) return;
+  await withSettingsLock(settingsPath, async () => {
+    let existing: Record<string, unknown>;
+    try {
+      existing = JSON.parse(await readFile(settingsPath, 'utf-8'));
+    } catch {
+      return; // malformed — leave it untouched (case-create owns the happy path)
+    }
+    const hooksJson = JSON.stringify(existing.hooks ?? null);
+    const isOurs = hooksJson.includes('/api/hook-event');
+    // The generated curl carries this header literal (see generateHooksConfig); its
+    // absence on our own hooks means they predate COD-54 and need regenerating.
+    const hasSecret = hooksJson.includes('X-Codeman-Hook-Secret');
+    if (!isOurs || hasSecret) return;
+    const merged = { ...existing, ...generateHooksConfig() };
+    await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
+  });
+}
+
 /** Unique marker identifying Codeman's own statusLine command (vs a user's). */
 const STATUSLINE_MARKER = '/api/status-telemetry';
 

src/session.ts

@@ -136,6 +136,21 @@ export function isExternalCliMode(mode: SessionMode): boolean {
   return mode === 'opencode' || mode === 'codex';
 }
 
+/**
+ * Modes whose TUI emits alt-screen / scrollback-erase / mouse-tracking sequences
+ * 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.
+ */
+export function isAltScreenStripMode(mode: SessionMode): boolean {
+  return mode === 'codex' || mode === 'claude';
+}
+
 // Note: Claude CLI PATH resolution moved to session-cli-builder.ts (buildClaudeEnv)
 
 /** PTY fallback geometry when tmux can't be queried (matches pre-#80 hardcoded values). */
@@ -265,9 +280,10 @@ export class Session extends EventEmitter {
   private _messages: ClaudeMessage[] = [];
   private _lineBuffer: string = '';
   private _lineBufferFlushTimer: NodeJS.Timeout | null = null;
-  // Codex only: trailing partial CSI held back so sequences split across PTY
-  // chunks can't slip past the alt-screen/scrollback strip (see _handleTerminalOutput)
-  private _codexSeqCarry: string = '';
+  // Alt-screen-strip modes (Codex/Claude): trailing partial CSI held back so
+  // sequences split across PTY chunks can't slip past the alt-screen/scrollback
+  // strip (see _handleTerminalOutput / isAltScreenStripMode)
+  private _altScreenSeqCarry: string = '';
   private resolvePromise: ((value: { result: string; cost: number }) => void) | null = null;
   private rejectPromise: ((reason: Error) => void) | null = null;
   private _promptResolved: boolean = false; // Guard against race conditions in runPrompt
@@ -1134,35 +1150,40 @@ export class Session extends EventEmitter {
   }
 
   private _handleTerminalOutput(data: string): void {
-    // Codex emits sequences that wipe xterm.js scrollback, plus mouse-tracking
-    // enables that hijack the scroll wheel so the user can't reach scrollback:
+    // Codex AND Claude Code emit sequences that wipe xterm.js scrollback, plus
+    // mouse-tracking enables that hijack the scroll wheel so the user can't reach
+    // scrollback. Claude Code does this intermittently (e.g. full-screen pickers /
+    // dialogs), which is why terminal scroll-up "randomly" breaks for Claude
+    // sessions on mobile and desktop until the dialog closes:
     //   - \x1b[?1049h / \x1b[?47h / \x1b[?1047h: switch to the alt buffer (no
     //     scrollback) — \x1b[?...l switches back.
     //   - \x1b[3J: erase saved lines (scrollback). (\x1b[2J / \x1b[J — erase
     //     the visible viewport — are left intact; the TUI repaints those rows.)
     //   - \x1b[?1000h / 1002h / 1003h / 1005h / 1006h / 1007h: mouse-tracking
     //     modes (X10, button-event, any-event, UTF-8, SGR, alt-scroll). Once on,
-    //     xterm.js forwards wheel events to codex instead of scrolling the
+    //     xterm.js forwards wheel events to the CLI instead of scrolling the
     //     viewport, so the conversation is in scrollback but unreachable.
     //     (Focus events at ?1004 are left alone — codeman uses them for
     //     active-tab detection.)
     // Strip them at the source so neither the persisted buffer nor the live
     // SSE/WS stream carries them, keeping everything in the main buffer with
-    // scrollback intact. Codex's cursor-positioned redraws overwrite only the
-    // cells they actually target, so the non-erased rows keep their content.
-    if (this.mode === 'codex') {
+    // scrollback intact. These are controlled TUIs whose cursor-positioned
+    // redraws overwrite only the cells they target, so non-erased rows keep
+    // their content. Gated to Codex/Claude (isAltScreenStripMode) — shell must
+    // keep the alt screen for vim/less/htop.
+    if (isAltScreenStripMode(this.mode)) {
       // Reassemble sequences split across PTY chunk boundaries first: a chunk
       // ending mid-sequence ('\x1b[?104' now, '9h' next) would slip past the
       // strip below and leave xterm stuck in the scrollback-less alt buffer
       // until the next buffer replay. Hold back an incomplete digit-only CSI
       // tail (≤7 chars — the longest strippable intro is '\x1b[?1049') and
       // prepend it to the next chunk; complete sequences are never held.
-      data = this._codexSeqCarry + data;
-      this._codexSeqCarry = '';
+      data = this._altScreenSeqCarry + data;
+      this._altScreenSeqCarry = '';
       // eslint-disable-next-line no-control-regex
       const splitTail = data.match(/\x1b(?:\[\??[0-9]{0,4})?$/);
       if (splitTail) {
-        this._codexSeqCarry = splitTail[0];
+        this._altScreenSeqCarry = splitTail[0];
         data = data.slice(0, -splitTail[0].length);
         if (!data) return;
       }
@@ -1809,7 +1830,7 @@ export class Session extends EventEmitter {
     this._errorBuffer = '';
     this._messages = [];
     this._lineBuffer = '';
-    this._codexSeqCarry = '';
+    this._altScreenSeqCarry = '';
     this._lastActivityAt = Date.now();
   }
 
@@ -2300,7 +2321,7 @@ export class Session extends EventEmitter {
    * @param cols - Number of columns (width in characters)
    * @param rows - Number of rows (height in lines)
    */
-  resize(cols: number, rows: number, options: { viewportType?: ResizeViewportType } = {}): void {
+  resize(cols: number, rows: number, options: { viewportType?: ResizeViewportType; force?: boolean } = {}): void {
     const isSmallViewport = options.viewportType === 'mobile' || options.viewportType === 'tablet';
     if (options.viewportType === 'desktop') {
       this._lastDesktopDims = { cols, rows };
@@ -2313,7 +2334,8 @@ export class Session extends EventEmitter {
       }
       this._mobileSizeOverride = true;
     }
-    if (this.ptyProcess && (cols !== this._ptyCols || rows !== this._ptyRows)) {
+    const dimsChanged = cols !== this._ptyCols || rows !== this._ptyRows;
+    if (this.ptyProcess && (dimsChanged || options.force)) {
       this._ptyCols = cols;
       this._ptyRows = rows;
       if (this._mux && this._muxSession) {

src/subagent-watcher.ts

@@ -13,6 +13,8 @@
  * - `SubagentEvents` — typed event map
  *
  * Watched patterns: `~/.claude/projects/{project}/{session}/subagents/agent-{id}.jsonl`
+ *   plus the `agent-{id}.meta.json` discovery sidecar (2026-06 format) and nested
+ *   workflow agents under `subagents/workflows/{workflowId}/agent-{id}.jsonl`.
  * Parses JSONL entries: user/assistant messages, tool_use/tool_result blocks, progress events.
  * Tracks per-agent: status, token counts, model, description, tool call count, liveness (PID).
  *
@@ -30,7 +32,7 @@ import { watch, existsSync, FSWatcher } from 'node:fs';
 import { createReadStream } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { homedir } from 'node:os';
-import { join, basename } from 'node:path';
+import { join, basename, dirname } from 'node:path';
 import { execFile } from 'node:child_process';
 import { readFile, readdir, stat as statAsync } from 'node:fs/promises';
 import { PENDING_TOOL_CALL_TTL_MS, MAX_PENDING_TOOL_CALLS, MAX_TRACKED_AGENTS } from './config/map-limits.js';
@@ -1150,6 +1152,10 @@ export class SubagentWatcher extends EventEmitter {
               try {
                 await statAsync(subagentDir);
                 await this.watchSubagentDir(subagentDir, project, session);
+                // Workflow agents nest one level deeper under subagents/workflows/{wf}/
+                // (each holds its own agent-{id}.jsonl/.meta.json) — the flat watcher
+                // above never sees them, so discover and watch each workflow dir too.
+                await this.watchWorkflowDirs(subagentDir, project, session);
               } catch {
                 // subagent dir doesn't exist - skip
               }
@@ -1179,8 +1185,12 @@ export class SubagentWatcher extends EventEmitter {
     try {
       const files = await readdir(dir);
       for (const file of files) {
-        if (file.endsWith('.jsonl')) {
+        if (file.startsWith('agent-') && file.endsWith('.jsonl')) {
           await this.registerAgentFile(join(dir, file), projectHash, sessionId, true);
+        } else if (file.startsWith('agent-') && file.endsWith('.meta.json')) {
+          // Claude Code (2026-06) writes a `agent-{id}.meta.json` sidecar for TUI
+          // Task subagents and no longer always writes a per-agent `.jsonl` here.
+          await this.registerAgentMeta(join(dir, file), projectHash, sessionId, true);
         }
       }
     } catch {
@@ -1190,13 +1200,26 @@ export class SubagentWatcher extends EventEmitter {
     // Single directory watcher handles both new files and file content changes
     try {
       const watcher = watch(dir, (_eventType, filename) => {
-        if (!filename?.endsWith('.jsonl')) return;
-        const filePath = join(dir, filename);
+        // Only agent-{id}.jsonl / agent-{id}.meta.json — ignore siblings like a
+        // workflow dir's journal.jsonl (would otherwise register a bogus "journal" agent).
+        const isAgent = !!filename && filename.startsWith('agent-');
+        const isJsonl = isAgent && filename.endsWith('.jsonl');
+        const isMeta = isAgent && filename.endsWith('.meta.json');
+        if (!isJsonl && !isMeta) return;
+        const filePath = join(dir, filename as string);
 
         // Debounce 100ms to batch rapid writes
         this.fileDeb.schedule(filePath, () => {
           if (!existsSync(filePath)) return;
 
+          if (isMeta) {
+            // Meta sidecar — discovery only (not a transcript; never tail it).
+            if (!this.fileAgentContext.has(filePath)) {
+              this.registerAgentMeta(filePath, projectHash, sessionId).catch(() => {});
+            }
+            return;
+          }
+
           if (this.fileAgentContext.has(filePath)) {
             // Known file — handle content change
             this.handleFileChange(filePath).catch(() => {}); // Ignore - errors logged internally, don't crash watcher callback
@@ -1225,6 +1248,40 @@ export class SubagentWatcher extends EventEmitter {
     }
   }
 
+  /**
+   * Discover and watch nested workflow agent directories.
+   *
+   * The Workflow tool runs its subagents under
+   * `subagents/workflows/{workflowId}/agent-{id}.jsonl` (+ `.meta.json`, alongside
+   * a `journal.jsonl` of orchestration events). The flat `subagents/` watcher does
+   * not recurse, and Node's `fs.watch({ recursive: true })` is unsupported on Linux,
+   * so each workflow dir gets its own watcher here. Idempotent via `knownSubagentDirs`
+   * and re-driven by the periodic scan, so newly created workflows are picked up
+   * within one scan cycle (~5s) — the same latency as a new session's `subagents/`.
+   */
+  private async watchWorkflowDirs(subagentDir: string, projectHash: string, sessionId: string): Promise<void> {
+    const workflowsRoot = join(subagentDir, 'workflows');
+    let names: string[];
+    try {
+      names = await readdir(workflowsRoot);
+    } catch {
+      return; // no workflows for this session
+    }
+    for (const name of names) {
+      // Workflow ids are directories (e.g. `wf_<id>`); skip any stray files that
+      // share the root (a workflow id never carries a file extension).
+      if (name.endsWith('.jsonl') || name.endsWith('.json')) continue;
+      const wfDir = join(workflowsRoot, name);
+      try {
+        const st = await statAsync(wfDir);
+        if (!st.isDirectory()) continue;
+        await this.watchSubagentDir(wfDir, projectHash, sessionId);
+      } catch {
+        // workflow dir vanished mid-scan — skip
+      }
+    }
+  }
+
   /**
    * Handle a file content change for an already-registered agent file.
    * Tails from last known position, updates info, retries description if missing.
@@ -1291,6 +1348,16 @@ export class SubagentWatcher extends EventEmitter {
 
     const agentId = basename(filePath).replace('agent-', '').replace('.jsonl', '');
 
+    // Meta→transcript upgrade: the agent may already be registered from its
+    // `.meta.json` sidecar (discovery-only — nothing to tail). Now that the real
+    // `.jsonl` transcript has appeared, re-point to it and drop the stale sidecar
+    // context, emitting `updated` below rather than a duplicate `discovered`.
+    const priorEntry = this.agentInfo.get(agentId);
+    const isMetaUpgrade = !!priorEntry && priorEntry.filePath.endsWith('.meta.json');
+    if (isMetaUpgrade && priorEntry) {
+      this.fileAgentContext.delete(priorEntry.filePath);
+    }
+
     // Initial info - handle race condition where file may be deleted between discovery and stat
     let fileStat;
     try {
@@ -1341,7 +1408,7 @@ export class SubagentWatcher extends EventEmitter {
     // Track file context for directory watcher change handling
     this.fileAgentContext.set(filePath, { projectHash, sessionId });
     this.agentInfo.set(agentId, info);
-    this.emit('subagent:discovered', info);
+    this.emit(isMetaUpgrade ? 'subagent:updated' : 'subagent:discovered', info);
 
     // Read existing content
     this.tailFile(filePath, agentId, sessionId, 0)
@@ -1356,6 +1423,86 @@ export class SubagentWatcher extends EventEmitter {
     this.resetIdleTimer(agentId);
   }
 
+  /**
+   * Register a subagent discovered via its `agent-{id}.meta.json` sidecar.
+   *
+   * As of the 2026-06 Claude Code format change, TUI Task subagents write the
+   * `agent-{id}.meta.json` sidecar (`{ agentType, description, toolUseId }`) at
+   * spawn, a beat *before* the `agent-{id}.jsonl` transcript appears in the same
+   * dir. The legacy `.jsonl`-only discovery saw nothing in that window ("0
+   * tracked"); this surfaces the agent from the sidecar immediately. The
+   * transcript then lands within ~1s at the standard path and grows incrementally
+   * (empirically verified — it is fully tailable, NOT a dead end), so:
+   *   - if the `.jsonl` already exists, defer to registerAgentFile (richer); else
+   *   - register meta-only now, and when the sibling `.jsonl` arrives the dir
+   *     watcher routes it to registerAgentFile, which detects the prior meta-only
+   *     entry and *upgrades* it in place (re-points filePath, starts tailing).
+   *
+   * Edge case: if the transcript never materializes (e.g. an agent that dies
+   * before writing one), the agent stays meta-only — no live feed, status ages
+   * out via the idle timer / stale cleanup.
+   */
+  private async registerAgentMeta(
+    metaPath: string,
+    projectHash: string,
+    sessionId: string,
+    isInitialScan: boolean = false
+  ): Promise<void> {
+    if (this.fileAgentContext.has(metaPath)) return;
+    const agentId = basename(metaPath).replace('agent-', '').replace('.meta.json', '');
+    if (this.agentInfo.has(agentId)) return;
+
+    // Prefer a real transcript if one was written alongside the sidecar.
+    const jsonlPath = join(dirname(metaPath), `agent-${agentId}.jsonl`);
+    if (existsSync(jsonlPath)) {
+      await this.registerAgentFile(jsonlPath, projectHash, sessionId, isInitialScan);
+      return;
+    }
+
+    let fileStat;
+    try {
+      fileStat = await statAsync(metaPath);
+    } catch {
+      return; // deleted between discovery and stat
+    }
+    if (isInitialScan && Date.now() - fileStat.mtime.getTime() > STARTUP_MAX_FILE_AGE_MS) {
+      return; // skip stale historical agents on startup
+    }
+
+    let description: string | undefined;
+    try {
+      const meta = JSON.parse(await readFile(metaPath, 'utf8')) as { agentType?: string; description?: string };
+      description = meta.description || meta.agentType;
+    } catch {
+      return; // unreadable / not yet fully written — a later watch event retries
+    }
+    if (this.isInternalAgent(description)) return;
+
+    const info: SubagentInfo = {
+      agentId,
+      sessionId,
+      projectHash,
+      filePath: metaPath,
+      startedAt: fileStat.birthtime.toISOString(),
+      lastActivityAt: fileStat.mtime.getTime(),
+      status: 'active',
+      toolCallCount: 0,
+      entryCount: 0,
+      fileSize: fileStat.size,
+      description,
+    };
+
+    if (this.agentInfo.size >= MAX_TRACKED_AGENTS) {
+      const oldestId = this.findOldestInactiveAgent();
+      if (oldestId) this.removeAgent(oldestId);
+    }
+
+    this.fileAgentContext.set(metaPath, { projectHash, sessionId });
+    this.agentInfo.set(agentId, info);
+    this.emit('subagent:discovered', info);
+    this.resetIdleTimer(agentId);
+  }
+
   /**
    * Tail a file from a specific position
    */

src/types/index.ts

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

src/types/workflow-run.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview Types for ultracode / Workflow-tool run visualization.
+ *
+ * A Workflow run persists its state to
+ * `~/.claude/projects/<projHash>/<sessionUuid>/workflows/wf_<runId>.json`
+ * (a sibling of the deeper `subagents/workflows/wf_<runId>/agent-*.jsonl`
+ * transcript tree that subagent-watcher tracks). This file is the single source
+ * for the master-detail "working agents" view: a run's tasks/phases on the LEFT
+ * and per-agent stats (tokens burned, tool calls) on the RIGHT.
+ *
+ * Field presence is STATE-DRIVEN and verified against real runs on disk:
+ *   - state 'start'    (queued): no agentId/tokens/toolCalls/startedAt/durationMs/...
+ *   - state 'progress' (running): has agentId/tokens/toolCalls, no durationMs/resultPreview
+ *   - state 'done'     (finished): all fields, incl. durationMs/resultPreview
+ * Absent fields are genuinely ABSENT (never explicit null) — use `?:`, not null.
+ *
+ * @module types/workflow-run
+ */
+
+/** One declared phase of a run (from the run JSON's top-level `phases[]`, 0-indexed). */
+export interface WorkflowRunPhase {
+  /** Phase title; equals each member agent's `phaseTitle`. Always present. */
+  title: string;
+  /** Human description of the phase. Always present in `phases[]`. */
+  detail: string;
+}
+
+/**
+ * One agent slot in a run, derived from `workflowProgress[]` entries where
+ * `type === 'workflow_agent'`. Optional fields are absent until the agent
+ * reaches the relevant lifecycle state (see module doc).
+ */
+export interface WorkflowAgentInfo {
+  /** 1-based stable slot index, unique within the run. Always present. */
+  index: number;
+  /** Agent label, e.g. "probe:dompurify-config". Always present. */
+  label: string;
+  /** 1-based phase number; join via `run.phases[phaseIndex - 1]`. Always present. */
+  phaseIndex: number;
+  /** Phase title (=== run.phases[phaseIndex-1].title). Always present. */
+  phaseTitle: string;
+  /** Model id, e.g. "claude-opus-4-8[1m]". Always present. */
+  model: string;
+  /** Lifecycle state. Real on-disk values: 'start' | 'progress' | 'done'. Open union. */
+  state: 'start' | 'progress' | 'done' | (string & {});
+  /** Epoch ms the slot was queued. Always present. */
+  queuedAt?: number;
+  /** Epoch ms of the last progress tick. Always present once any progress occurs. */
+  lastProgressAt?: number;
+  /** Truncated prompt the agent was given. Always present. */
+  promptPreview?: string;
+  /**
+   * Globally-unique agent id; equals the `agent-<agentId>.jsonl` transcript stem
+   * (the Phase-4 correlation key). ABSENT while state === 'start'.
+   */
+  agentId?: string;
+  /** Epoch ms the agent began. Absent while 'start'. */
+  startedAt?: number;
+  /** Attempt counter. Absent while 'start'. */
+  attempt?: number;
+  /** Tokens burned so far (RIGHT pane). Absent while 'start'. */
+  tokens?: number;
+  /** Tool calls made so far (RIGHT pane). Absent while 'start'. */
+  toolCalls?: number;
+  /** Name of the most recent tool. Present for progress/done (occasionally absent). */
+  lastToolName?: string;
+  /** Short summary of the most recent tool call. May be absent even when 'done'. */
+  lastToolSummary?: string;
+  /** Total run time (ms). Present ONLY when 'done' — the live-vs-finished discriminator. */
+  durationMs?: number;
+  /** Truncated final result. Present ONLY when 'done'. */
+  resultPreview?: string;
+}
+
+/**
+ * Run-level info shipped to the browser.
+ *
+ * IMPORTANT: the on-disk JSON also carries `script` (15–660KB of embedded JS),
+ * `scriptPath`, `result`, and `logs`. The watcher STRIPS all four before the
+ * object is ever cached/broadcast — never let them reach SSE/getLightState/route.
+ */
+export interface WorkflowRunInfo {
+  /** Run id (=== the wf_<runId>.json filename stem). Always present. */
+  runId: string;
+  /** Workflow name from `meta.name`. Always present. */
+  workflowName?: string;
+  /**
+   * Run status. Real on-disk values seen: 'completed' | 'killed'.
+   * 'running' | 'failed' are inferred (parse defensively; keep open union).
+   */
+  status?: 'completed' | 'killed' | 'running' | 'failed' | (string & {});
+  /** Concise human description (best LEFT-pane label). Always present. */
+  summary?: string;
+  /** Total agent slots, INCLUDING not-yet-started 'start' agents. */
+  agentCount?: number;
+  /** Total tokens across the run (partial mid-run). */
+  totalTokens?: number;
+  /** Total tool calls across the run (partial mid-run). */
+  totalToolCalls?: number;
+  /** Total run duration (ms). */
+  durationMs?: number;
+  /** Run start time (epoch MILLIS). */
+  startTime?: number;
+  /** ISO end/write timestamp. */
+  timestamp?: string;
+  /** Default model for the run. */
+  defaultModel?: string;
+  /** Background-task id that owns the run. */
+  taskId?: string;
+  /** Declared phases (0-indexed). */
+  phases: WorkflowRunPhase[];
+  /** Agents, derived from `workflowProgress` filtered to `type === 'workflow_agent'`. */
+  agents: WorkflowAgentInfo[];
+  /** Error message, present when status is 'killed'/'failed'. */
+  error?: string;
+
+  // ----- Watcher-derived (NOT in the JSON body — captured from the file path) -----
+  /** `<sessionUuid>` path segment (for per-session scoping). */
+  sessionUuid: string;
+  /** `<projHash>` path segment. */
+  projectHash: string;
+  /**
+   * Most recent activity (epoch ms): max agent `lastProgressAt`, else `startTime`.
+   * Drives recency filtering/sorting so finished long runs still surface.
+   */
+  lastActivityAt: number;
+}
+
+/**
+ * Lightweight run projection (no `agents[]`) for the LEFT-pane list and the
+ * getLightState reconnect snapshot. A full run with 28 agents serializes to
+ * ~36KB; the snapshot ships dozens of runs, so it carries summaries only and the
+ * RIGHT pane fetches the full run (`GET /api/workflows/:runId`) on selection.
+ */
+export type WorkflowRunSummary = Omit<WorkflowRunInfo, 'agents'>;

src/utils/dependency-checker.ts

@@ -0,0 +1,211 @@
+/**
+ * @fileoverview Probe engine for `codeman doctor`. Resolves each registry tool
+ * against an injectable ProbeHost (real impl uses child_process/fs; tests inject
+ * fakes) and returns structured results. Pure given the host — no global I/O.
+ *
+ * @module utils/dependency-checker
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import type { ProbeEnvironment, ToolCategory, ToolDependency } from '../config/dependency-registry.js';
+
+export interface EnvDetectionInputs {
+  platform: NodeJS.Platform;
+  procVersion: string;
+  hasWindowsInterop: boolean;
+}
+
+export function detectEnvironment(inputs: EnvDetectionInputs): ProbeEnvironment {
+  if (inputs.platform === 'win32') return 'win32';
+  if (inputs.platform === 'darwin') return 'darwin';
+  const isWsl = /microsoft|wsl/i.test(inputs.procVersion) && inputs.hasWindowsInterop;
+  return isWsl ? 'wsl' : 'linux';
+}
+
+const DEFAULT_VERSION_RE = /(\d+\.\d+(?:\.\d+)?)/;
+
+export function extractVersion(text: string, re?: RegExp): string | undefined {
+  const m = (re ?? DEFAULT_VERSION_RE).exec(text);
+  return m ? m[1] : undefined;
+}
+
+/** Returns -1 if a < b, 0 if equal, 1 if a > b (numeric, component-wise). */
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = b.split('.').map((n) => parseInt(n, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+export type ToolStatus = 'ok' | 'missing' | 'outdated' | 'skipped' | 'error';
+
+export interface ToolResult {
+  id: string;
+  label: string;
+  category: ToolCategory;
+  required: boolean;
+  usedBy: string[];
+  status: ToolStatus;
+  version?: string;
+  path?: string;
+  installHint?: string;
+  reason?: string;
+}
+
+export interface ProbeHost {
+  environment: ProbeEnvironment;
+  which(bin: string): string | null;
+  fileExists(path: string): boolean;
+  runVersion(bin: string, args: string[]): string | null;
+  windowsProgramRoots(): string[];
+  windowsFileVersion(winPath: string): string | null;
+}
+
+function finalize(
+  base: Pick<ToolResult, 'id' | 'label' | 'category' | 'required' | 'usedBy'>,
+  tool: ToolDependency,
+  path: string,
+  version: string | undefined
+): ToolResult {
+  if (tool.minVersion) {
+    if (!version) return { ...base, status: 'error', path, reason: 'version required but could not be parsed' };
+    if (compareVersions(version, tool.minVersion) < 0) return { ...base, status: 'outdated', path, version };
+  }
+  return { ...base, status: 'ok', path, version };
+}
+
+export function checkTool(tool: ToolDependency, host: ProbeHost): ToolResult {
+  const base = {
+    id: tool.id,
+    label: tool.label,
+    category: tool.category,
+    required: tool.required,
+    usedBy: tool.usedBy ?? [],
+  };
+  const installHint = tool.installHint?.[host.environment];
+
+  const spec = tool.resolvers.find((r) => r.match.includes(host.environment));
+  if (!spec) return { ...base, status: 'skipped', reason: `not applicable on ${host.environment}` };
+
+  if (spec.resolver.kind === 'path') {
+    const { bins, versionArg, versionRegex } = spec.resolver;
+    for (const bin of bins) {
+      const resolved = host.which(bin);
+      if (resolved) {
+        const out = host.runVersion(bin, [versionArg ?? '--version']);
+        const version = out ? extractVersion(out, versionRegex) : undefined;
+        return finalize(base, tool, resolved, version);
+      }
+    }
+    return { ...base, status: 'missing', installHint };
+  }
+
+  // windows-side
+  const { appDirs, exes } = spec.resolver;
+  for (const root of host.windowsProgramRoots()) {
+    for (const dir of appDirs) {
+      for (const exe of exes) {
+        const winPath = `${root}/${dir}/${exe}`;
+        if (host.fileExists(winPath)) {
+          const raw = host.windowsFileVersion(winPath);
+          const version = raw ? extractVersion(raw) : undefined;
+          return finalize(base, tool, winPath, version);
+        }
+      }
+    }
+  }
+  return { ...base, status: 'missing', installHint };
+}
+
+export function checkAll(registry: ToolDependency[], host: ProbeHost): ToolResult[] {
+  return registry.map((tool) => checkTool(tool, host));
+}
+
+function safeWhich(bin: string): string | null {
+  try {
+    const out = execFileSync(process.platform === 'win32' ? 'where' : 'which', [bin], {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT_MS,
+    }).trim();
+    const first = out.split(/\r?\n/)[0]?.trim();
+    return first && existsSync(first) ? first : null;
+  } catch {
+    return null;
+  }
+}
+
+function safeRunVersion(bin: string, args: string[]): string | null {
+  try {
+    return execFileSync(bin, args, {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (err: unknown) {
+    // Some tools (e.g. ffmpeg) exit non-zero on -version but still print to stdout
+    const stdout = (err as { stdout?: Buffer | string })?.stdout;
+    return stdout ? stdout.toString() : null;
+  }
+}
+
+function readProcVersion(): string {
+  try {
+    return readFileSync('/proc/version', 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function listWindowsProgramRoots(): string[] {
+  const roots: string[] = [];
+  try {
+    for (const entry of readdirSync('/mnt')) {
+      for (const pf of ['Program Files', 'Program Files (x86)']) {
+        const root = `/mnt/${entry}/${pf}`;
+        if (existsSync(root)) roots.push(root);
+      }
+    }
+  } catch {
+    // /mnt absent (not WSL) -> no roots
+  }
+  return roots;
+}
+
+function readWindowsFileVersion(winPath: string): string | null {
+  try {
+    const windowsPath = execFileSync('wslpath', ['-w', winPath], {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT_MS,
+    }).trim();
+    const out = execFileSync(
+      'powershell.exe',
+      ['-NoProfile', '-Command', `(Get-Item '${windowsPath.replace(/'/g, "''")}').VersionInfo.ProductVersion`],
+      { encoding: 'utf-8', timeout: EXEC_TIMEOUT_MS }
+    ).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+export function createRealHost(): ProbeHost {
+  const environment = detectEnvironment({
+    platform: process.platform,
+    procVersion: readProcVersion(),
+    hasWindowsInterop: safeWhich('cmd.exe') !== null || safeWhich('powershell.exe') !== null,
+  });
+  return {
+    environment,
+    which: safeWhich,
+    fileExists: existsSync,
+    runVersion: safeRunVersion,
+    windowsProgramRoots: listWindowsProgramRoots,
+    windowsFileVersion: readWindowsFileVersion,
+  };
+}

src/utils/dependency-report.ts

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Renders ToolResult[] from the dependency checker into a
+ * human-readable grouped table or JSON, and computes the process exit code.
+ * Plain text only (no color) so output is stable and snapshot-friendly; the
+ * CLI layer may colorize.
+ *
+ * @module utils/dependency-report
+ */
+
+import type { ProbeEnvironment, ToolCategory } from '../config/dependency-registry.js';
+import type { ToolResult, ToolStatus } from './dependency-checker.js';
+
+const CATEGORY_ORDER: ToolCategory[] = ['core', 'office', 'other'];
+
+function glyph(r: ToolResult): string {
+  if (r.status === 'ok') return '✓';
+  if (r.status === 'skipped') return '○';
+  return r.required ? '✗' : '○';
+}
+
+function statusText(r: ToolResult): string {
+  if (r.status === 'ok') return r.version ?? 'installed';
+  if (r.status === 'outdated') return `${r.version ?? '?'} (below minimum)`;
+  if (r.status === 'skipped') return 'n/a';
+  if (r.status === 'error') return 'version error';
+  return 'not found';
+}
+
+export function computeExitCode(results: ToolResult[]): number {
+  const failed = results.some(
+    (r) => r.required && (r.status === 'missing' || r.status === 'outdated' || r.status === 'error')
+  );
+  return failed ? 1 : 0;
+}
+
+export function renderTable(results: ToolResult[], environment: ProbeEnvironment): string {
+  const lines: string[] = [`Codeman dependency check — ${environment}`, ''];
+  for (const category of CATEGORY_ORDER) {
+    const rows = results.filter((r) => r.category === category);
+    if (rows.length === 0) continue;
+    lines.push(category.toUpperCase());
+    for (const r of rows) {
+      const detail = r.path ? `  ${r.path}` : '';
+      lines.push(`  ${glyph(r)} ${r.label.padEnd(14)} ${statusText(r).padEnd(22)}${detail}`);
+      if (r.usedBy.length) lines.push(`        used by: ${r.usedBy.join(', ')}`);
+      if (r.installHint) lines.push(`        install: ${r.installHint}`);
+    }
+    lines.push('');
+  }
+  const ok = results.filter((r) => r.status === 'ok').length;
+  const requiredMissing = results.filter((r) => r.required && r.status !== 'ok' && r.status !== 'skipped').length;
+  const optionalMissing = results.filter((r) => !r.required && r.status === 'missing').length;
+  lines.push(`Summary: ${ok} ok · ${requiredMissing} required missing · ${optionalMissing} optional missing`);
+  return lines.join('\n');
+}
+
+export interface DependencyReportJson {
+  platform: { environment: ProbeEnvironment };
+  summary: { ok: number; requiredMissing: number; optionalMissing: number; exitCode: number };
+  tools: ToolResult[];
+}
+
+export function renderJson(results: ToolResult[], environment: ProbeEnvironment): DependencyReportJson {
+  const byStatus = (s: ToolStatus) => results.filter((r) => r.status === s).length;
+  return {
+    platform: { environment },
+    summary: {
+      ok: byStatus('ok'),
+      requiredMissing: results.filter((r) => r.required && r.status !== 'ok' && r.status !== 'skipped').length,
+      optionalMissing: results.filter((r) => !r.required && r.status === 'missing').length,
+      exitCode: computeExitCode(results),
+    },
+    tools: results,
+  };
+}

src/web/middleware/auth.ts

@@ -36,20 +36,12 @@ interface AuthState {
  * Register HTTP Basic Auth middleware with session cookies and rate limiting.
  * Only active when CODEMAN_PASSWORD is set.
  *
- * @param getTunnelRunning - returns true while a managed tunnel is active. Used
- *   to gate the `/api/hook-event` localhost bypass: when a tunnel is up, tunneled
- *   internet traffic reaches the loopback origin with `req.ip === 127.0.0.1`, so
- *   the bypass additionally requires the shared hook secret (COD-54). When no
- *   tunnel is running (loopback-only, the normal case) the plain localhost bypass
- *   is kept so already-deployed (pre-secret) hooks + the loop channel keep working.
- *   Optional; defaults to "no tunnel" (unchanged behavior) when omitted.
+ * The `/api/hook-event` + `/api/status-telemetry` localhost bypass requires the
+ * shared hook secret unconditionally (COD-91) — see the onRequest hook below.
+ *
  * @returns AuthState for lifecycle management (dispose on server stop)
  */
-export function registerAuthMiddleware(
-  app: FastifyInstance,
-  https: boolean,
-  getTunnelRunning: () => boolean = () => false
-): AuthState {
+export function registerAuthMiddleware(app: FastifyInstance, https: boolean): AuthState {
   const state: AuthState = {
     authSessions: null,
     authFailures: null,
@@ -114,30 +106,26 @@ export function registerAuthMiddleware(
     // COD-54: the bare localhost bypass is unsafe while a tunnel is running, because
     // `cloudflared --url http://127.0.0.1:port` proxies internet traffic INTO the
     // loopback origin, so a tunneled request arrives with req.ip === 127.0.0.1 and
-    // would pass. So:
-    //   - tunnel running → bypass requires the shared hook secret (local hooks present
-    //     it via the X-Codeman-Hook-Secret header; internet traffic can't know it),
-    //   - tunnel not running (loopback-only, the normal case) → keep the plain
-    //     localhost bypass so already-deployed (pre-secret) hooks + the loop's own
-    //     credential-less hook channel keep working.
+    // would pass. COD-91: require the shared hook secret on the loopback bypass
+    // UNCONDITIONALLY (not just while the managed tunnel is up). Codeman can't detect
+    // a user's own loopback reverse proxy (their own `cloudflared --url`, `tailscale
+    // serve`, nginx → 127.0.0.1), so tunnel-gating left that path with the unsafe plain
+    // bypass. Managed-session hooks always present the secret (X-Codeman-Hook-Secret,
+    // from $CODEMAN_HOOK_SECRET_FILE — generated for every instance), so requiring it
+    // always closes the gap without breaking the legitimate hook channel.
     if ((req.url === '/api/hook-event' || req.url === '/api/status-telemetry') && req.method === 'POST') {
       const ip = req.ip;
       const isLoopback = ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
       if (isLoopback) {
-        if (!getTunnelRunning()) {
-          // Loopback-only: unchanged behavior.
-          done();
-          return;
-        }
-        // Tunnel up: require the shared secret (constant-time compare).
+        // Always require the shared secret (constant-time compare).
         const presented = Buffer.from(req.headers[HOOK_SECRET_HEADER.toLowerCase()]?.toString() ?? '');
         const expected = Buffer.from(getHookSecret());
         if (presented.length === expected.length && timingSafeEqual(presented, expected)) {
           done();
           return;
         }
-        // Wrong/absent secret while tunneled — rate-limit per IP in the DEDICATED
-        // hook bucket (never authFailures, which would lock out the login path).
+        // Wrong/absent secret — rate-limit per IP in the DEDICATED hook bucket
+        // (never authFailures, which would lock out the login path).
         const hookIp = req.ip;
         const hookFailures = hookSecretFailures.get(hookIp) ?? 0;
         if (hookFailures >= AUTH_FAILURE_MAX) {

src/web/public/app.js

@@ -221,6 +221,11 @@ const _SSE_HANDLER_MAP = [
   [SSE_EVENTS.SUBAGENT_TOOL_RESULT, '_onSubagentToolResult'],
   [SSE_EVENTS.SUBAGENT_COMPLETED, '_onSubagentCompleted'],
 
+  // Workflow runs (ultracode)
+  [SSE_EVENTS.WORKFLOW_RUN_DISCOVERED, '_onWorkflowRunDiscovered'],
+  [SSE_EVENTS.WORKFLOW_RUN_UPDATED, '_onWorkflowRunUpdated'],
+  [SSE_EVENTS.WORKFLOW_RUN_REMOVED, '_onWorkflowRunRemoved'],
+
   // Images
   [SSE_EVENTS.IMAGE_DETECTED, '_onImageDetected'],
   [SSE_EVENTS.ATTACHMENT_DETECTED, '_onAttachmentDetected'],
@@ -339,6 +344,17 @@ class CodemanApp {
     this.subagentToolResults = new Map(); // Map<agentId, Map<toolUseId, result>> - tool results by toolUseId
     this.activeSubagentId = null; // Currently selected subagent for detail view
     this.subagentPanelVisible = false;
+
+    // Ultracode / Workflow run visualization (master-detail tab)
+    this.workflowRuns = new Map(); // runId -> run summary (LEFT list)
+    this.workflowRunDetails = new Map(); // runId -> full run with agents[] (RIGHT pane)
+    this.activeWorkflowRunId = null;
+    this.activeWorkflowPhaseIndex = null;
+    // Ultracode floating run windows (additional to the dock panel — ultracode-windows.js)
+    this.ultracodeWindows = new Map(); // runId -> { element, parentSessionId, dragListeners, collapsed }
+    this.ultracodeWindowsClosed = new Set(); // runIds the user explicitly dismissed (don't re-pop)
+    this.ultracodeWindowCloseTimers = new Map(); // runId -> auto-close timeout
+    this.ultracodeWindowZIndex = 1000;
     this.subagentWindows = new Map(); // Map<agentId, { element, position }>
     this.subagentWindowZIndex = ZINDEX_SUBAGENT_BASE;
     this.minimizedSubagents = new Map(); // Map<sessionId, Set<agentId>> - minimized to tab
@@ -649,6 +665,16 @@ class CodemanApp {
       this.applySkin();
       this.applyTabWrapSettings();
       this.applyMonitorVisibility();
+      // ultracodeFloatingWindows syncs from the server (non-display key), but on a
+      // FRESH device the getLightState run snapshot can seed workflowRuns BEFORE this
+      // async settings load resolves — so the floating-window gate read false then and
+      // skipped any already-active run. Re-sync now that the real setting is loaded so
+      // an in-flight run pops its window immediately instead of waiting for the next
+      // ~10s SSE tick. Idempotent: open windows are left as-is; if the setting is off
+      // it tears any premature windows down.
+      if (typeof this.syncAllUltracodeFloatingWindows === 'function') {
+        this.syncAllUltracodeFloatingWindows();
+      }
     });
     // Hide loading skeleton now that the app shell is ready
     document.body.classList.add('app-loaded');
@@ -770,14 +796,31 @@ class CodemanApp {
         if (this.attachmentHistoryDrawerOpen) this.closeAttachmentHistory();
       }
 
-      // Alt+1-9: switch to Codeman session by index
-      if (e.altKey && !e.ctrlKey && !e.shiftKey && e.key >= '1' && e.key <= '9') {
-        const idx = parseInt(e.key) - 1;
-        if (idx < this.sessionOrder.length) {
+      // Option/Alt session navigation uses physical key CODES, not e.key, so macOS
+      // keyboard layouts that emit special characters under Option (Option+1 -> ¡,
+      // Option+[ -> "“") still switch sessions. e.code is the physical key regardless
+      // of layout. Option+1-9 = switch by index; Option+[ / Option+] = prev / next.
+      if (e.altKey && !e.ctrlKey && !e.shiftKey) {
+        const code = e.code || '';
+        const digitMatch = code.match(/^Digit([1-9])$/);
+        if (digitMatch) {
+          const idx = parseInt(digitMatch[1], 10) - 1;
+          if (idx < this.sessionOrder.length) {
+            e.preventDefault();
+            this.selectSession(this.sessionOrder[idx]);
+          }
+          return;
+        }
+        if (e.code === 'BracketLeft') {
           e.preventDefault();
-          this.selectSession(this.sessionOrder[idx]);
+          this.prevSession();
+          return;
+        }
+        if (e.code === 'BracketRight') {
+          e.preventDefault();
+          this.nextSession();
+          return;
         }
-        return;
       }
 
       // Match against shortcut table
@@ -1302,28 +1345,14 @@ class CodemanApp {
 
   /** Strip dangerous elements and attributes from HTML (XSS prevention) */
   _sanitizeHtml(html) {
-    const tpl = document.createElement('template');
-    tpl.innerHTML = html;
-    const frag = tpl.content;
-    for (const el of frag.querySelectorAll('script, iframe, object, embed, form, base, meta, link, style')) {
-      el.remove();
+    if (typeof window !== 'undefined' && typeof window.sanitizeMarkdownHtml === 'function') {
+      return window.sanitizeMarkdownHtml(html);
     }
-    for (const el of frag.querySelectorAll('*')) {
-      for (const attr of [...el.attributes]) {
-        const name = attr.name.toLowerCase();
-        if (name.startsWith('on')) {
-          el.removeAttribute(attr.name);
-        } else if (['href', 'src', 'action', 'xlink:href', 'formaction'].includes(name)) {
-          const val = attr.value.replace(/\s/g, '').toLowerCase();
-          if (val.startsWith('javascript:') || val.startsWith('vbscript:') || val.startsWith('data:text/html')) {
-            el.removeAttribute(attr.name);
-          }
-        }
-      }
-    }
-    const div = document.createElement('div');
-    div.appendChild(frag);
-    return div.innerHTML;
+    // Fail closed: DOMPurify unavailable — never return un-sanitized HTML.
+    return String(html == null ? '' : html)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
   }
 
   /**
@@ -2166,12 +2195,17 @@ class CodemanApp {
     // Mobile defaults ship cjkInputEnabled: false (native terminal input by
     // default on touch), but an explicit user enable is honored everywhere —
     // the App Settings toggle must not be a silent no-op on phones.
-    const showCjk = this._serverCjkOverride || (settings.cjkInputEnabled ?? defaults.cjkInputEnabled ?? false);
+    // The welcome/home screen (no active session) has nothing to type into.
+    // Force-hide the CJK textarea there — otherwise the `position: fixed`
+    // `.cjk-input-visible` rule floats it over the welcome overlay and blocks
+    // content. Re-synced on session enter/leave via hideWelcome()/showWelcome().
+    const cjkUserEnabled =
+      this._serverCjkOverride || (settings.cjkInputEnabled ?? defaults.cjkInputEnabled ?? false);
+    const showCjk = cjkUserEnabled && !!this.activeSessionId;
     cjkEl.classList.toggle('cjk-input-visible', !!showCjk);
     document.body.classList.toggle('cjk-input-visible', !!showCjk);
     cjkEl.style.display = showCjk ? 'block' : 'none';
     cjkEl.setAttribute('aria-hidden', showCjk ? 'false' : 'true');
-    if (showCjk && cjkEl.value === '\u200B') cjkEl.value = '';
     if (!showCjk) window.cjkActive = false;
     if (typeof KeyboardHandler !== 'undefined') KeyboardHandler.updateLayoutForKeyboard();
   }
@@ -2219,6 +2253,11 @@ class CodemanApp {
     // Clear subagent activity/results maps (prevents leaks if data.subagents is missing)
     this.subagentActivity.clear();
     this.subagentToolResults.clear();
+    // Clear ultracode workflow run state (re-seeded from data.workflowRuns below)
+    if (this.workflowRuns) this.workflowRuns.clear();
+    if (this.workflowRunDetails) this.workflowRunDetails.clear();
+    this.activeWorkflowRunId = null;
+    this.activeWorkflowPhaseIndex = null;
     // Clean up mobile/keyboard handlers and re-init (prevents listener accumulation on reconnect)
     MobileDetection.cleanup();
     KeyboardHandler.cleanup();
@@ -2393,6 +2432,11 @@ class CodemanApp {
       });
     }
 
+    // Seed ultracode workflow runs (LEFT-pane summaries) from the snapshot
+    if (data.workflowRuns) {
+      this.seedWorkflowRuns(data.workflowRuns);
+    }
+
     // Restore previously active session (survives page reload + SSE reconnect)
     // Must always re-select because handleInit clears terminal state above.
     // Reset activeSessionId so selectSession doesn't early-return.
@@ -2656,6 +2700,39 @@ class CodemanApp {
       this._fullRenderSessionTabs();
     }
 
+    this.updateTabOverflowMode();
+  }
+
+  // Auto-wrap desktop session tabs to a second row when they overflow one row,
+  // unless the user has pinned the manual two-row layout (tabTwoRows). Mobile/
+  // tablet keep horizontal scroll. Policy lives in constants.js for unit testing.
+  updateTabOverflowMode() {
+    const container = this.$('sessionTabs');
+    if (!container) return;
+
+    const deviceType = MobileDetection.getDeviceType();
+    const settings = this.loadAppSettingsFromStorage();
+    const defaults = this.getDefaultSettings();
+    const manualTwoRows = deviceType === 'desktop' ? (settings.tabTwoRows ?? defaults.tabTwoRows ?? false) : false;
+
+    if (manualTwoRows || deviceType !== 'desktop') {
+      container.classList.remove('tabs-auto-wrap');
+      return;
+    }
+
+    // Measure the natural one-row overflow, then enable wrapping only if needed.
+    container.classList.remove('tabs-auto-wrap');
+    const shouldWrap = window.CodemanTabOverflow?.shouldAutoWrapTabs
+      ? window.CodemanTabOverflow.shouldAutoWrapTabs({
+          deviceType,
+          manualTwoRows,
+          tabCount: this.sessions.size,
+          scrollWidth: container.scrollWidth,
+          clientWidth: container.clientWidth,
+        })
+      : container.scrollWidth > container.clientWidth + 1;
+
+    container.classList.toggle('tabs-auto-wrap', shouldWrap);
   }
 
   _fullRenderSessionTabs() {
@@ -2696,6 +2773,10 @@ class CodemanApp {
       const minimizedCount = minimizedAgents?.size || 0;
       const subagentBadge = minimizedCount > 0 ? this.renderSubagentTabBadge(id, minimizedAgents) : '';
 
+      // Ultracode runs + agent transcripts minimized to this tab (ultracode-windows.js
+      // renders one merged ULTRA badge; returns '' when nothing is minimized).
+      const ultracodeBadge = this.renderUltracodeTabBadge ? this.renderUltracodeTabBadge(id) : '';
+
       // Show folder name if session has a custom name AND tall tabs setting is enabled
       const folderName = session.workingDir ? session.workingDir.split('/').pop() || '' : '';
       const tallTabsEnabled = this._tallTabsEnabled ?? false;
@@ -2715,6 +2796,7 @@ class CodemanApp {
           </span>
           ${hasRunningTasks ? `<span class="tab-badge" onclick="event.stopPropagation(); app.toggleTaskPanel()" aria-label="${taskStats.running} running tasks">${taskStats.running}</span>` : ''}
           ${subagentBadge}
+          ${ultracodeBadge}
           <span class="tab-gear" onclick="event.stopPropagation(); app.openSessionOptions('${escapeHtml(id)}')" title="Session options" aria-label="Session options" tabindex="0">&#x2699;</span>
           <span class="tab-detach" onclick="event.stopPropagation(); app.detachSession('${escapeHtml(id)}')" title="Open in a new window" aria-label="Open session in a new window" tabindex="0">&#x29C9;</span>
           <span class="tab-close" onclick="event.stopPropagation(); app.requestCloseSession('${escapeHtml(id)}')" title="Close session" aria-label="Close session" tabindex="0">&times;</span>
@@ -2732,6 +2814,12 @@ class CodemanApp {
 
     // Update connection lines after tabs change (positions may have shifted)
     this.updateConnectionLines();
+
+    // Re-evaluate desktop auto-wrap for every full rebuild, including the incremental
+    // branch's early `_fullRenderSessionTabs(); return;` paths and the manual two-rows
+    // toggle (applyTabWrapSettings calls this) which would otherwise leave a stale
+    // tabs-auto-wrap class until the next content render.
+    this.updateTabOverflowMode();
   }
 
   // Set up arrow key navigation for session tabs (accessibility)

src/web/public/constants.js

@@ -114,9 +114,24 @@ function evaluateWebGLLongTaskTrip(recent, entries, now, config = WEBGL_FALLBACK
 // Expose for tests. `const` declarations at the top of a non-module script
 // are global lexical bindings but not `window` properties, so explicit
 // assignment is the test-visible API surface.
+// Desktop tab-overflow policy: auto-wrap the session tabs to a second row when
+// they overflow one row (and the user hasn't pinned the manual two-row layout).
+function shouldAutoWrapTabs(input) {
+  if (!input || input.deviceType !== 'desktop') return false;
+  if (input.manualTwoRows) return false;
+  if ((input.tabCount || 0) < 2) return false;
+
+  const scrollWidth = Number(input.scrollWidth) || 0;
+  const clientWidth = Number(input.clientWidth) || 0;
+  return scrollWidth > clientWidth + 1;
+}
+
 if (typeof window !== 'undefined') {
   window.WEBGL_FALLBACK = WEBGL_FALLBACK;
   window.evaluateWebGLLongTaskTrip = evaluateWebGLLongTaskTrip;
+  window.CodemanTabOverflow = {
+    shouldAutoWrapTabs,
+  };
 }
 
 // Scheduler API — prioritize terminal writes over background UI updates.
@@ -335,6 +350,11 @@ const SSE_EVENTS = {
   SUBAGENT_TOOL_RESULT: 'subagent:tool_result',
   SUBAGENT_COMPLETED: 'subagent:completed',
 
+  // Workflow runs (ultracode / Workflow tool)
+  WORKFLOW_RUN_DISCOVERED: 'workflow:run_discovered',
+  WORKFLOW_RUN_UPDATED: 'workflow:run_updated',
+  WORKFLOW_RUN_REMOVED: 'workflow:run_removed',
+
   // Images
   IMAGE_DETECTED: 'image:detected',
   ATTACHMENT_DETECTED: 'attachment:detected',

src/web/public/index.html

@@ -39,6 +39,9 @@
   <script defer src="vendor/xterm-addon-unicode11.min.js"></script>
   <script defer src="vendor/xterm-zerolag-input.js"></script>
   <script defer src="vendor/marked.min.js"></script>
+  <!-- DOMPurify (allowlist HTML sanitizer for rendered markdown).
+       Must load before sanitize-html.js (which wires it) and app.js (which calls it). -->
+  <script defer src="vendor/dompurify.min.js"></script>
   <!-- Synchronous mobile detection — runs before first paint to prevent panel flash -->
   <script>if(window.innerWidth<768||(('ontouchstart' in window||navigator.maxTouchPoints>0)&&window.innerWidth<1024))document.documentElement.classList.add('mobile-init');</script>
   <!-- Synchronous skin selection — runs before first paint to prevent theme flash -->
@@ -113,12 +116,14 @@
             <span class="stat-value" id="statMem">--</span>
           </div>
         </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-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>
         </button>
         <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><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"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
+        <button class="btn-icon-header btn-ultracode-agents btn-ultracode-agents--hidden" onclick="app.toggleUltracodeAgentsPanel()" title="Ultracode / Workflow agents" aria-label="Open ultracode workflow agents"><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"><circle cx="6" cy="6" r="2.5"/><circle cx="6" cy="18" r="2.5"/><circle cx="18" cy="12" r="2.5"/><path d="M8.2 7.2 15.6 11M8.2 16.8 15.6 13"/></svg></button>
         <div class="header-plan-usage header-plan-usage--hidden" id="planUsageChip" title="Claude plan usage limits">—</div>
         <button class="btn-icon-header btn-notifications" onclick="app.toggleNotifications()" title="Notifications" aria-label="Toggle notifications" style="display:none;">
           <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="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
@@ -505,7 +510,8 @@
           <div class="shortcuts-grid">
             <div><kbd>Ctrl</kbd>+<kbd>W</kbd></div><div>Close Session</div>
             <div><kbd>Ctrl</kbd>+<kbd>Tab</kbd></div><div>Next Session</div>
-            <div><kbd>Alt</kbd>+<kbd>1-9</kbd></div><div>Switch to Tab N</div>
+            <div><kbd>Alt/Option</kbd>+<kbd>[</kbd> / <kbd>Alt/Option</kbd>+<kbd>]</kbd></div><div>Previous / Next Session</div>
+            <div><kbd>Alt/Option</kbd>+<kbd>1-9</kbd></div><div>Switch to Tab N</div>
             <div><kbd>Ctrl</kbd>+<kbd>L</kbd></div><div>Clear Terminal</div>
             <div><kbd>Ctrl</kbd>+<kbd>+</kbd></div><div>Increase Font</div>
             <div><kbd>Ctrl</kbd>+<kbd>-</kbd></div><div>Decrease Font</div>
@@ -596,6 +602,29 @@
       </div>
     </div>
 
+    <!-- Ultracode / Workflow agents master-detail panel (opt-in via showUltracodeAgents) -->
+    <div class="subagents-panel ultracode-agents-panel hidden" id="ultracodeAgentsPanel">
+      <div class="subagents-panel-header">
+        <div class="subagents-panel-title">
+          Ultracode Agents <span id="ultracodeCountBadge" class="subagent-badge"></span>
+        </div>
+        <div class="subagents-panel-actions">
+          <button class="btn-icon-sm" onclick="app.toggleUltracodeAgentsPanel()" title="Toggle panel">&#x25B2;</button>
+          <button class="btn-icon-sm" onclick="app.closeUltracodeAgentsPanel()" title="Close">&times;</button>
+        </div>
+      </div>
+      <div class="subagents-panel-body">
+        <div class="subagent-container">
+          <div class="subagent-list ultracode-run-list" id="ultracodeRunList">
+            <div class="subagent-empty">No ultracode runs detected</div>
+          </div>
+          <div class="subagent-detail ultracode-agent-grid" id="ultracodeAgentGrid">
+            <div class="subagent-empty">Select a run to view its agents</div>
+          </div>
+        </div>
+      </div>
+    </div>
+
     <!-- Session Options Modal (includes Respawn Settings) -->
     <div class="modal" id="sessionOptionsModal">
       <div class="modal-backdrop" onclick="app.closeSessionOptions()"></div>
@@ -1030,6 +1059,13 @@
                   <span class="slider"></span>
                 </label>
               </div>
+              <div class="settings-item" title="Show a terminal redraw button in the header — refit the terminal to the current screen size (useful when switching between devices)">
+                <span class="settings-item-label">Redraw Terminal Button</span>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsShowRedrawButton">
+                  <span class="slider"></span>
+                </label>
+              </div>
 
               <!-- Tab Bar Section -->
               <div class="settings-section-header">Tab Bar</div>
@@ -1071,6 +1107,20 @@
                   <span class="slider"></span>
                 </label>
               </div>
+              <div class="settings-item" title="Show ultracode / Workflow runs as a master-detail tab (tasks on the left, agents with tokens + tool calls on the right)">
+                <span class="settings-item-label">Ultracode Agents</span>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsShowUltracodeAgents">
+                  <span class="slider"></span>
+                </label>
+              </div>
+              <div class="settings-item" title="Pop a floating window for each active ultracode / Workflow run, connected by a line to its session tab (additional to the Ultracode Agents panel)">
+                <span class="settings-item-label">Ultracode Floating Windows</span>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsUltracodeFloatingWindows">
+                  <span class="slider"></span>
+                </label>
+              </div>
 
               <!-- Subagent Options Section -->
               <div class="settings-section-header">Subagent Options</div>
@@ -1914,6 +1964,8 @@
   <script defer src="notification-manager.js"></script>
   <script defer src="keyboard-accessory.js"></script>
   <script defer src="input-cjk.js"></script>
+  <!-- Hardened markdown HTML sanitizer (wires DOMPurify). Must precede app.js. -->
+  <script defer src="sanitize-html.js"></script>
   <script defer src="app.js"></script>
   <script defer src="terminal-ui.js"></script>
   <script defer src="respawn-ui.js"></script>
@@ -1921,10 +1973,12 @@
   <script defer src="orchestrator-panel.js"></script>
   <script defer src="settings-ui.js"></script>
   <script defer src="panels-ui.js"></script>
+  <script defer src="ultracode-panel.js"></script>
   <script defer src="session-ui.js"></script>
   <script defer src="ralph-wizard.js"></script>
   <script defer src="api-client.js"></script>
   <script defer src="subagent-windows.js"></script>
+  <script defer src="ultracode-windows.js"></script>
   <script defer src="image-input.js"></script>
 </body>
 </html>

src/web/public/input-cjk.js

@@ -14,13 +14,21 @@
  * This means compositionstart fires even for English text, and compositionend
  * may not fire until the user explicitly confirms (space, candidate tap).
  *
- * We use InputEvent.inputType to distinguish:
- * - `insertCompositionText`: tentative text, may change (CJK candidates, pinyin)
- * - `insertText`: final committed text (confirmed word, punctuation, space)
+ * During composition, all input events are ignored — only compositionend
+ * triggers a flush (CJK candidate selection).
  *
- * During composition, `insertText` events are flushed immediately (punctuation,
- * English words confirmed by IME). `insertCompositionText` waits for
- * compositionend (CJK candidate selection).
+ * ## iOS dictation challenge (WebKit Bug 261764)
+ *
+ * iOS/iPadOS voice dictation does NOT fire composition events. Text arrives
+ * as bare input events with isComposing === false. Dictation refinement is
+ * a delete→reinsert cycle (deleteContentBackward + insertReplacementText),
+ * all within a few ms. Flushing on every input event would send irrevocable
+ * provisional text to the PTY, causing duplication when the IME replaces it.
+ *
+ * Solution: outside composition, flush is DEBOUNCED (200ms). The entire
+ * delete→reinsert cycle collapses into one flush of the final textarea value.
+ * Keyboard typing of single printable characters still goes through the
+ * keydown handler (immediate, no debounce).
  *
  * ## Phantom character for Android backspace
  *
@@ -41,16 +49,30 @@
 // eslint-disable-next-line no-unused-vars
 const CjkInput = (() => {
   let _textarea = null;
-  let _terminalContainer = null;
-  let _xtermTextarea = null;
   let _send = null;
   let _initialized = false;
   let _composing = false;
+  let _flushTimer = null;
+  let _dictationActive = false;
+  let _dictationDecayTimer = null;
+  let _keydownSentAt = 0;
   const _listeners = {};
 
-  // Zero-width space: always present in textarea so Android backspace has
-  // something to delete, triggering the `input` event we need to detect it.
-  const PHANTOM = '\u200B';
+  const PHANTOM = '​';
+
+  // Two-tier debounce for non-composition input:
+  // - KEYBOARD: short debounce (third-party IMEs like Doubao may not fire
+  //   composition events even for keyboard CJK typing)
+  // - DICTATION: long debounce (iOS voice dictation sends delete→reinsert
+  //   refinement cycles without composition events — WebKit Bug 261764)
+  //
+  // Dictation is detected by deleteContentBackward on non-empty text or
+  // insertReplacementText — signals that the IME is rewriting provisional
+  // text. Once detected, dictation mode persists for 3s (covers multi-word
+  // dictation with natural pauses between words).
+  const DEBOUNCE_KEYBOARD_MS = 150;
+  const DEBOUNCE_DICTATION_MS = 1500;
+  const DICTATION_DECAY_MS = 3000;
 
   const PASSTHROUGH_KEYS = {
     ArrowUp:    '\x1b[A',
@@ -66,35 +88,15 @@ const CjkInput = (() => {
     c: '\x03', d: '\x04', l: '\x0c', z: '\x1a', a: '\x01', e: '\x05',
   };
 
-  /** Strip phantom characters from a string */
   function _strip(str) {
-    return str.replace(/\u200B/g, '');
+    return str.replace(/​/g, '');
   }
 
-  /** Reset textarea to phantom-only state with cursor at end */
   function _resetToPhantom() {
     _textarea.value = PHANTOM;
     _textarea.setSelectionRange(1, 1);
   }
 
-  function _isMobileComposer() {
-    return !!(
-      _textarea &&
-      typeof MobileDetection !== 'undefined' &&
-      MobileDetection.isTouchDevice() &&
-      _textarea.classList.contains('cjk-input-visible')
-    );
-  }
-
-  function _resetInput() {
-    if (_isMobileComposer()) {
-      _textarea.value = '';
-    } else {
-      _resetToPhantom();
-    }
-  }
-
-  /** Check if textarea contains only phantom(s) or is empty — no real user text */
   function _isEffectivelyEmpty() {
     return !_strip(_textarea.value);
   }
@@ -108,61 +110,77 @@ const CjkInput = (() => {
     _resetToPhantom();
   }
 
+  /** Cancel any pending debounced flush */
+  function _cancelDebouncedFlush() {
+    if (_flushTimer) {
+      clearTimeout(_flushTimer);
+      _flushTimer = null;
+    }
+  }
+
+  /** Mark that dictation rewriting is in progress */
+  function _enterDictationMode() {
+    _dictationActive = true;
+    clearTimeout(_dictationDecayTimer);
+    _dictationDecayTimer = setTimeout(() => {
+      _dictationActive = false;
+      _dictationDecayTimer = null;
+    }, DICTATION_DECAY_MS);
+  }
+
+  /** Schedule a flush after input settles */
+  function _debouncedFlush() {
+    _cancelDebouncedFlush();
+    const delay = _dictationActive ? DEBOUNCE_DICTATION_MS : DEBOUNCE_KEYBOARD_MS;
+    _flushTimer = setTimeout(() => {
+      _flushTimer = null;
+      _flush();
+    }, delay);
+  }
+
   return {
     init({ send }) {
       if (_initialized) this.destroy();
 
       _send = send;
       _composing = false;
+      _flushTimer = null;
       _textarea = document.getElementById('cjkInput');
       if (!_textarea) return this;
-      _terminalContainer = document.getElementById('terminalContainer');
 
-      // Seed the phantom character for the hidden/immediate CJK path.
-      _resetInput();
+      _resetToPhantom();
 
       _listeners.mousedown = (e) => { e.stopPropagation(); };
       _listeners.focus = () => {
         window.cjkActive = true;
-        if (_isMobileComposer() && _textarea.value === PHANTOM) {
-          _textarea.value = '';
-          return;
+        if (!_textarea.value) _resetToPhantom();
+      };
+      _listeners.blur = () => {
+        // Keep cjkActive while CJK input is visible — iOS dictation and system
+        // UI may steal focus temporarily, and clearing the flag during that
+        // window lets xterm's onData process duplicated input.
+        if (!_textarea.classList.contains('cjk-input-visible')) {
+          window.cjkActive = false;
         }
-        // Restore phantom if textarea was emptied while blurred
-        if (!_textarea.value && !_isMobileComposer()) _resetToPhantom();
+        // Reset composing state — some IMEs fire compositionstart without a
+        // matching compositionend, leaving _composing stuck true and blocking
+        // all subsequent input events.
+        _composing = false;
       };
-      _listeners.blur = () => { window.cjkActive = false; };
       _textarea.addEventListener('mousedown', _listeners.mousedown);
       _textarea.addEventListener('focus', _listeners.focus);
       _textarea.addEventListener('blur', _listeners.blur);
 
-      _listeners.xtermFocusRedirect = () => {
-        if (!_isMobileComposer()) return;
-        _textarea.focus();
-      };
-      if (_terminalContainer) {
-        _xtermTextarea = _terminalContainer.querySelector('.xterm-helper-textarea');
-        if (_xtermTextarea) {
-          _xtermTextarea.addEventListener('focus', _listeners.xtermFocusRedirect, { capture: true });
-        }
-      }
-
-      // ── Composition tracking ──
+      // ── Composition tracking (keyboard IME — works for CJK typing) ──
       _listeners.compositionstart = () => {
         _composing = true;
-        if (_isMobileComposer()) {
-          if (_textarea.value === PHANTOM) _textarea.value = '';
-          return;
-        }
-        // Clear phantom so IME sees a clean textarea — some IMEs include
-        // existing text in the composition region which would corrupt input.
-        if (_textarea.value === PHANTOM) {
-          _textarea.value = '';
-        }
+        _cancelDebouncedFlush();
+        // Leave textarea.value untouched — programmatic changes during
+        // compositionstart cancel the IME composition on iOS Safari.
       };
       _listeners.compositionend = () => {
         _composing = false;
-        if (_isMobileComposer()) return;
+        _cancelDebouncedFlush();
         // Defer flush: some Android IMEs haven't committed text to textarea
         // when compositionend fires. setTimeout(0) ensures we read the final value.
         setTimeout(_flush, 0);
@@ -172,56 +190,40 @@ const CjkInput = (() => {
 
       // ── Keydown: special keys work REGARDLESS of composition state ──
       _listeners.keydown = (e) => {
-        // Enter: flush accumulated text (or bare Enter if empty).
-        // No isComposing guard — Android IMEs set isComposing=true for English
-        // prediction, but Enter should ALWAYS send. We preventDefault to stop
-        // the IME from also handling Enter (which could double-send or do nothing).
         if (e.key === 'Enter') {
           e.preventDefault();
           _composing = false;
+          _cancelDebouncedFlush();
           const val = _strip(_textarea.value);
           if (val) {
             _send(val + '\r');
           } else {
             _send('\r');
           }
-          _resetInput();
+          _resetToPhantom();
           return;
         }
 
-        // Escape: clear textarea (always works)
         if (e.key === 'Escape') {
           e.preventDefault();
           _composing = false;
-          _resetInput();
+          _cancelDebouncedFlush();
+          _resetToPhantom();
           return;
         }
 
-        // Ctrl combos: forward to PTY (always works)
         if (e.ctrlKey && CTRL_KEYS[e.key]) {
           e.preventDefault();
           _send(CTRL_KEYS[e.key]);
           return;
         }
 
-        // Below: only when NOT composing (composing keystrokes belong to IME)
-        if (_composing) return;
-
-        if (_isMobileComposer()) {
-          if (e.key === 'Backspace' && _isEffectivelyEmpty()) {
-            e.preventDefault();
-            _send('\x7f');
-            return;
-          }
-          if (PASSTHROUGH_KEYS[e.key] && _isEffectivelyEmpty()) {
-            e.preventDefault();
-            _send(PASSTHROUGH_KEYS[e.key]);
-          }
-          return;
-        }
+        // Below: only when NOT composing (composing keystrokes belong to IME).
+        // Also check isComposing/keyCode 229 — the first keydown of a CJK
+        // sequence arrives BEFORE compositionstart, so _composing is still false.
+        if (_composing || e.isComposing || e.keyCode === 229) return;
 
         // Backspace: forward to PTY when no real text in textarea
-        // (Desktop path — Android uses the input event + phantom approach)
         if (e.key === 'Backspace' && _isEffectivelyEmpty()) {
           e.preventDefault();
           _send('\x7f');
@@ -236,62 +238,62 @@ const CjkInput = (() => {
           return;
         }
 
-        // Single printable character: send immediately to PTY
-        // (Desktop keyboards with physical keys — Android sends 'Unidentified')
+        // Single printable character: send immediately to PTY.
+        // Third-party IMEs on iOS may ignore preventDefault, so the char
+        // still enters the textarea and fires an input event — _keydownSentAt
+        // tells the input handler to skip that echo.
         if (e.key.length === 1 && !e.ctrlKey && !e.altKey && !e.metaKey && _isEffectivelyEmpty()) {
           e.preventDefault();
           _send(e.key);
+          _keydownSentAt = performance.now();
+          _resetToPhantom();
           return;
         }
       };
       _textarea.addEventListener('keydown', _listeners.keydown);
 
-      // ── Input event: the primary path for Android virtual keyboards ──
-      // Android sends keyCode 229 + key "Unidentified" for virtual key presses,
-      // making keydown unreliable. input fires AFTER character insertion and
-      // carries inputType which tells us whether the text is final or tentative.
+      // ── Input event: primary path for virtual keyboards + dictation ──
       _listeners.input = (e) => {
-        if (_isMobileComposer()) {
-          if (_textarea.value.includes(PHANTOM)) {
-            _textarea.value = _strip(_textarea.value);
-          }
-          return;
-        }
-
         // ── Backspace / delete detection ──
-        // Android long-press backspace generates rapid deleteContentBackward events.
-        // The phantom character ensures the textarea is never truly empty, so each
-        // press/repeat fires an input event that we can catch here.
         if (e.inputType === 'deleteContentBackward' || e.inputType === 'deleteWordBackward') {
+          if (_composing) return;
           if (_isEffectivelyEmpty()) {
-            // No real text left — forward backspace to PTY
+            _cancelDebouncedFlush();
             _send('\x7f');
             _resetToPhantom();
             return;
           }
-          // User is editing their own text in the textarea — let it be.
-          // Ensure phantom is still present for the NEXT backspace.
+          // Delete on non-empty text outside composition = dictation rewrite.
+          // The IME is revising provisional text — switch to long debounce.
+          _enterDictationMode();
           if (!_textarea.value.startsWith(PHANTOM)) {
             _textarea.value = PHANTOM + _textarea.value;
             _textarea.setSelectionRange(1, 1);
           }
+          _debouncedFlush();
           return;
         }
 
-        if (_composing) {
-          // insertText during composition = IME committed final text
-          // (e.g., punctuation key inserts 。directly, or IME confirms a word).
-          // Flush immediately — this text won't change.
-          if (e.inputType === 'insertText') {
-            _flush();
-            return;
-          }
-          // insertCompositionText = IME is still working (pinyin, candidates,
-          // English prediction). Wait for compositionend to flush.
+        // insertReplacementText = dictation/autocorrect refinement
+        if (e.inputType === 'insertReplacementText') {
+          _enterDictationMode();
+          _debouncedFlush();
           return;
         }
-        // Outside composition: send immediately
-        _flush();
+
+        if (_composing) return;
+
+        // Keydown handler already sent this character — just clear the
+        // textarea echo that the IME inserted despite preventDefault.
+        if (performance.now() - _keydownSentAt < 100) {
+          _resetToPhantom();
+          return;
+        }
+
+        // Outside composition: keyboard typing or voice dictation.
+        // If dictation mode was detected (delete/replacement events seen
+        // recently), use long debounce. Otherwise short debounce for keyboard.
+        _debouncedFlush();
       };
       _textarea.addEventListener('input', _listeners.input);
 
@@ -300,18 +302,16 @@ const CjkInput = (() => {
     },
 
     destroy() {
+      _cancelDebouncedFlush();
+      clearTimeout(_dictationDecayTimer);
+      _dictationActive = false;
       if (_textarea) {
         for (const [event, handler] of Object.entries(_listeners)) {
           if (handler) _textarea.removeEventListener(event, handler);
         }
       }
-      if (_xtermTextarea && _listeners.xtermFocusRedirect) {
-        _xtermTextarea.removeEventListener('focus', _listeners.xtermFocusRedirect, { capture: true });
-      }
       window.cjkActive = false;
       _composing = false;
-      _terminalContainer = null;
-      _xtermTextarea = null;
       for (const key of Object.keys(_listeners)) delete _listeners[key];
       _initialized = false;
     },

src/web/public/keyboard-accessory.js

@@ -4,10 +4,10 @@
  * Defines two exports:
  *
  * - KeyboardAccessoryBar (singleton object) — Quick action buttons shown above the virtual
- *   keyboard on mobile: arrow up/down, /init, /clear, paste, Esc, and dismiss.
+ *   keyboard on mobile: arrow up/down, /init, /clear, /compact, paste, Esc, and dismiss.
  *   The paste button opens a dialog that handles both text paste and image attach
  *   (native picker + best-effort image paste, routed through app._uploadAndInsertImages).
- *   Destructive actions (/clear) require double-tap confirmation (2s amber state).
+ *   Destructive actions (/clear, /compact) require double-tap confirmation (2s amber state).
  *   Commands are sent as text + Enter separately for Ink compatibility.
  *   Only initializes on touch devices (MobileDetection.isTouchDevice guard).
  *
@@ -100,6 +100,7 @@ const KeyboardAccessoryBar = {
       <button class="accessory-btn" data-action="esc" title="Escape">Esc</button>
       <button class="accessory-btn" data-action="init" title="/init">/init</button>
       <button class="accessory-btn" data-action="clear" title="/clear">/clear</button>
+      <button class="accessory-btn" data-action="compact" title="/compact">/compact</button>
       <button class="accessory-btn accessory-btn-dismiss" data-action="dismiss" title="Dismiss keyboard">
         <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
           <path d="M19 9l-7 7-7-7"/>
@@ -129,7 +130,7 @@ const KeyboardAccessoryBar = {
       // Refocus terminal so keyboard stays open (tap blurs terminal → keyboard dismisses → toolbar shifts)
       const refocusActions = new Set(['scroll-up', 'scroll-down', 'arrow-left', 'arrow-right', 'tab', 'shift-tab', 'ctrl-o', 'opt-enter', 'esc', 'effort-max']);
       if (refocusActions.has(action) ||
-          (action === 'clear' && this._confirmAction)) {
+          ((action === 'clear' || action === 'compact') && this._confirmAction)) {
         if (typeof app !== 'undefined' && app.terminal) {
           app.terminal.focus();
         }
@@ -192,11 +193,12 @@ const KeyboardAccessoryBar = {
       case 'init':
         this.sendCommand('/init');
         break;
-      case 'clear': {
-        // Require double-tap: first tap turns amber, second tap within 2s sends
+      case 'clear':
+      case 'compact': {
+        const cmd = action === 'clear' ? '/clear' : '/compact';
         if (this._confirmAction === action && this._confirmTimer) {
           this.clearConfirm();
-          this.sendCommand('/clear');
+          this.sendCommand(cmd);
         } else {
           this.setConfirm(action, btn);
         }
@@ -300,7 +302,10 @@ const KeyboardAccessoryBar = {
     const sendText = () => {
       const text = textarea.value;
       close();
-      if (text) app.sendInput(text);
+      if (text) {
+        app.sendInput(text);
+        setTimeout(() => app.sendInput('\r'), 80);
+      }
     };
 
     // Filter to images, close the dialog, and hand off to the shared

src/web/public/mobile-handlers.js

@@ -139,6 +139,9 @@ const MobileDetection = {
       resizeTimeout = setTimeout(() => {
         this.updateBodyClass();
         this.updateAppHeight();
+        // Tab auto-wrap is width-driven, so it must re-evaluate on resize — the only
+        // other trigger is a tab content render. No-op on mobile/tablet (method bails).
+        if (typeof app !== 'undefined') app.updateTabOverflowMode?.();
       }, 100);
     };
     window.addEventListener('resize', this._resizeHandler);
@@ -288,57 +291,60 @@ const KeyboardHandler = {
   updateLayoutForKeyboard() {
     if (!window.visualViewport) return;
 
-    // Only adjust on mobile
-    if (!MobileDetection.isSmallScreen() && !MobileDetection.isMediumScreen()) {
+    if (!MobileDetection.isTouchDevice()) {
       this.resetLayout();
       return;
     }
 
-    const toolbar = document.querySelector('.toolbar');
-    const accessoryBar = document.querySelector('.keyboard-accessory-bar');
     const cjkInput = document.getElementById('cjkInput');
-    const main = document.querySelector('.main');
+    const isSmallMedium = MobileDetection.isSmallScreen() || MobileDetection.isMediumScreen();
 
     if (this.keyboardVisible) {
-      // Calculate how far the toolbar (position:fixed, bottom:0) needs to
-      // translate up so it sits at the bottom of the visual viewport.
-      // This formula accounts for iOS scrolling the visual viewport (offsetTop)
-      // when the user types in xterm's hidden textarea.
-      //
-      // MUST measure against the LAYOUT viewport (window.innerHeight): the
-      // bars are position:fixed, which anchors to the layout viewport — on
-      // iOS that keeps its full height while the keyboard is open. Measuring
-      // the shrunken .app instead (its height tracks --app-height = visual
-      // viewport) made the offset compute to 0 on iOS, leaving the toolbar
-      // and accessory bar behind the OS keyboard (0.9.8 regression). On
-      // Android the layout viewport itself shrinks with the keyboard, so
-      // innerHeight === visualBottom and the offset is naturally 0 there.
-      const layoutHeight = window.innerHeight;
-      const visualBottom = window.visualViewport.offsetTop + window.visualViewport.height;
-      const keyboardOffset = Math.max(0, layoutHeight - visualBottom);
-
-      // Move toolbar and accessory bar above keyboard.
-      // When keyboardOffset is 0 (viewport scrolled to layout bottom),
-      // the bars are naturally positioned via their CSS bottom values —
-      // just clear the transforms.  Never dismiss keyboard state here;
-      // that's handleViewportResize's job.
-      if (toolbar) {
-        toolbar.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
-      }
-      if (accessoryBar) {
-        accessoryBar.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
-      }
-      if (cjkInput?.classList.contains('cjk-input-visible')) {
-        cjkInput.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
-      }
-
-      // Reserve only Codeman's visible controls. The OS keyboard is outside
-      // the visual viewport; adding its height here creates a large blank area
-      // above the mobile toolbar on iPhone.
       const keyboardHeight = this.initialViewportHeight - (window.visualViewport.height || window.innerHeight);
-      if (main && keyboardHeight > 0) {
-        const cjkInputHeight = cjkInput?.classList.contains('cjk-input-visible') ? 44 : 0;
-        main.style.paddingBottom = `${84 + cjkInputHeight}px`;
+      const accessoryBar = document.querySelector('.keyboard-accessory-bar');
+
+      if (isSmallMedium) {
+        // Phones/small tablets: toolbar and accessory bar are position:fixed
+        // via CSS. Use translateY to lift them above the keyboard.
+        const toolbar = document.querySelector('.toolbar');
+        const main = document.querySelector('.main');
+
+        const layoutHeight = window.innerHeight;
+        const visualBottom = window.visualViewport.offsetTop + window.visualViewport.height;
+        const keyboardOffset = Math.max(0, layoutHeight - visualBottom);
+
+        if (toolbar) {
+          toolbar.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
+        }
+        if (accessoryBar) {
+          accessoryBar.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
+        }
+        if (main && keyboardHeight > 0) {
+          const cjkInputHeight = cjkInput?.classList.contains('cjk-input-visible') ? 44 : 0;
+          main.style.paddingBottom = `${84 + cjkInputHeight}px`;
+        }
+      } else if (keyboardHeight > 0) {
+        // iPad: use direct bottom positioning (translateY unreliable —
+        // iOS auto-scrolls the visual viewport, making keyboardOffset ≈ 0).
+        if (accessoryBar) {
+          accessoryBar.style.bottom = `${keyboardHeight}px`;
+        }
+      }
+
+      // CJK textarea positioning (always position:fixed on touch devices).
+      if (cjkInput?.classList.contains('cjk-input-visible') && keyboardHeight > 0) {
+        if (isSmallMedium) {
+          // Phones: use translateY like toolbar/accessory bar.
+          const layoutHeight = window.innerHeight;
+          const visualBottom = window.visualViewport.offsetTop + window.visualViewport.height;
+          const keyboardOffset = Math.max(0, layoutHeight - visualBottom);
+          cjkInput.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
+          cjkInput.style.bottom = '';
+        } else {
+          // iPad: direct bottom = keyboard + accessory bar height.
+          cjkInput.style.bottom = `${keyboardHeight + 44}px`;
+          cjkInput.style.transform = '';
+        }
       }
     } else {
       this.resetLayout();
@@ -357,9 +363,11 @@ const KeyboardHandler = {
     }
     if (accessoryBar) {
       accessoryBar.style.transform = '';
+      accessoryBar.style.bottom = '';
     }
     if (cjkInput) {
       cjkInput.style.transform = '';
+      cjkInput.style.bottom = '';
     }
     if (main) {
       main.style.paddingBottom = '';

src/web/public/mobile.css

@@ -1065,85 +1065,7 @@ html.mobile-init .file-browser-panel {
   }
 
   /* Paste overlay for iOS clipboard access */
-  .paste-overlay {
-    position: fixed;
-    inset: 0;
-    background: rgba(0, 0, 0, 0.6);
-    z-index: 10000;
-    display: flex;
-    align-items: flex-start;
-    justify-content: center;
-    padding-top: 15vh;
-  }
-
-  .paste-dialog {
-    background: var(--bg-secondary, #1e1e2e);
-    border: 1px solid var(--border-color, #444);
-    border-radius: 12px;
-    padding: 12px;
-    width: calc(100% - 24px);
-    max-width: 400px;
-  }
-
-  .paste-textarea {
-    width: 100%;
-    min-height: 80px;
-    max-height: 200px;
-    background: var(--bg-primary, #0d0d14);
-    color: var(--text-primary, #e0e0e0);
-    border: 1px solid var(--border-color, #444);
-    border-radius: 8px;
-    padding: 8px;
-    font-family: inherit;
-    font-size: 16px;
-    resize: none;
-    box-sizing: border-box;
-  }
-
-  .paste-textarea:focus {
-    outline: none;
-    border-color: var(--accent-color, #7aa2f7);
-  }
-
-  .paste-actions {
-    display: flex;
-    justify-content: flex-end;
-    gap: 8px;
-    margin-top: 10px;
-  }
-
-  .paste-cancel, .paste-new, .paste-send, .paste-image {
-    padding: 8px 18px;
-    border: none;
-    border-radius: 8px;
-    font-size: 14px;
-    cursor: pointer;
-  }
-
-  /* Image attach button — left-aligned, accent outline */
-  .paste-image {
-    margin-right: auto;
-    background: var(--bg-tertiary, #333);
-    color: var(--accent-color, #7aa2f7);
-    border: 1px solid var(--accent-color, #7aa2f7);
-  }
-
-  .paste-cancel {
-    background: var(--bg-tertiary, #333);
-    color: var(--text-secondary, #aaa);
-  }
-
-  .paste-new {
-    background: var(--bg-tertiary, #333);
-    color: var(--accent-color, #7aa2f7);
-    border: 1px solid var(--accent-color, #7aa2f7);
-  }
-
-  .paste-send {
-    background: var(--accent-color, #7aa2f7);
-    color: #fff;
-    font-weight: 600;
-  }
+  /* Paste overlay styles extracted to universal section below (line ~2293+) */
 
   /* LEGACY: Hide old toolbar select (no longer used on mobile) */
   .toolbar-select {
@@ -2177,95 +2099,9 @@ html.mobile-init .file-browser-panel {
 }
 
 
-/* ============================================================================
-   Keyboard Accessory Bar — all mobile/tablet sizes
-   Visual styles extracted from phone breakpoint so they apply on iPad too.
-   Phone-specific positioning (position: fixed) remains in @media (max-width: 430px).
-   ============================================================================ */
-.keyboard-accessory-bar {
-  display: none;
-  height: 44px;
-  background: #1a1a1a;
-  border-top: 1px solid rgba(255, 255, 255, 0.1);
-  padding: 6px 8px;
-  gap: 8px;
-  align-items: center;
-  overflow-x: auto;
-  overflow-y: hidden;
-  -webkit-overflow-scrolling: touch;
-  z-index: 51;
-}
-
-.keyboard-accessory-bar.visible {
-  display: flex;
-}
-
-.keyboard-accessory-bar::-webkit-scrollbar {
-  display: none;
-}
-
-.accessory-btn {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  flex-shrink: 0;
-  gap: 4px;
-  padding: 6px 12px;
-  background: #2a2a2a;
-  border: 1px solid rgba(255, 255, 255, 0.15);
-  border-radius: 6px;
-  color: #e5e5e5;
-  font-size: 0.65rem;
-  font-weight: 500;
-  cursor: pointer;
-  transition: background 0.15s, border-color 0.15s;
-}
-
-.accessory-btn.confirming {
-  background: #6b4f00;
-  border-color: #b8860b;
-  color: #ffd54f;
-}
-
-.accessory-btn:active {
-  background: #3a3a3a;
-}
-
-.accessory-btn svg {
-  width: 14px;
-  height: 14px;
-}
-
-.accessory-btn-arrow {
-  padding: 6px 10px;
-  background: #2563eb;
-  border-color: rgba(59, 130, 246, 0.5);
-  color: #fff;
-}
-
-.accessory-btn-arrow:active {
-  background: #1d4ed8;
-}
-
-.accessory-btn-dismiss {
-  margin-left: auto;
-  flex: 1 1 0;
-  max-width: 80px;
-  padding: 10px 8px;
-  background: #334d6e;
-  border-color: rgba(100, 150, 200, 0.4);
-  color: #c0d4e8;
-  font-weight: 600;
-}
-
-.accessory-btn-dismiss svg {
-  width: 20px;
-  height: 20px;
-}
-
-.accessory-btn-dismiss:active {
-  background: #3d5f85;
-}
+/* Keyboard accessory bar + paste overlay base styles moved to styles.css
+   (always loaded — covers iPad landscape where mobile.css doesn't load).
+   Phone-specific overrides remain in @media (max-width: 430px) above. */
 
 /* ============================================================================
    iOS Safari Specific Fixes

src/web/public/panels-ui.js

@@ -2503,6 +2503,25 @@ Object.assign(CodemanApp.prototype, {
       bodyEl.innerHTML = `<iframe src="${escapeHtml(rawSrc)}" title="${escapeHtml(filePath)}"></iframe>`;
       return;
     }
+    // SVG renders as an image, but file-raw deliberately serves SVG as an
+    // untrusted octet-stream attachment (XSS hardening), so a direct
+    // <img src=file-raw> would break. Fetch the bytes and render via a
+    // same-origin blob typed image/svg+xml — <img> never executes scripts in
+    // the referenced SVG, so this is safe while still rendering the graphic.
+    if (ext === 'svg') {
+      footerEl.textContent = 'SVG';
+      try {
+        const res = await fetch(`/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}`);
+        if (!res.ok) throw new Error('Failed to load image');
+        const blobUrl = URL.createObjectURL(new Blob([await res.text()], { type: 'image/svg+xml' }));
+        bodyEl.innerHTML = `<img src="${blobUrl}" alt="${escapeHtml(filePath)}">`;
+        const img = bodyEl.querySelector('img');
+        if (img) img.onload = () => URL.revokeObjectURL(blobUrl);
+      } catch (err) {
+        bodyEl.innerHTML = `<div class="binary-message">Error: ${escapeHtml(err.message)}</div>`;
+      }
+      return;
+    }
 
     try {
       const res = await fetch(`/api/sessions/${sessionId}/file-content?path=${encodeURIComponent(filePath)}&lines=500`);
@@ -2519,8 +2538,12 @@ Object.assign(CodemanApp.prototype, {
       } else if (data.type === 'video') {
         bodyEl.innerHTML = `<video src="${data.url}" controls autoplay></video>`;
         footerEl.textContent = `${this.formatFileSize(data.size)} \u2022 ${data.extension}`;
+      } else if (data.type === 'audio') {
+        bodyEl.innerHTML = `<audio src="${data.url}" controls autoplay></audio>`;
+        footerEl.textContent = `${this.formatFileSize(data.size)} \u2022 ${data.extension}`;
       } else if (data.type === 'binary') {
-        bodyEl.innerHTML = `<div class="binary-message">Binary file (${this.formatFileSize(data.size)})<br>Cannot preview</div>`;
+        const downloadHref = `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}&download=true`;
+        bodyEl.innerHTML = `<div class="binary-message">Binary file (${this.formatFileSize(data.size)})<br>Cannot preview<br><a href="${escapeHtml(downloadHref)}" download>Download</a></div>`;
         footerEl.textContent = data.extension || 'binary';
       } else {
         // Text content

src/web/public/sanitize-html.js

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Allowlist-based HTML sanitizer for markdown-rendered, agent/transcript-derived
+ * content that is subsequently assigned via innerHTML (response viewer, attachment markdown
+ * preview, message bodies).
+ *
+ * Security (COD-56): the previous sanitizer was a hand-rolled DENYLIST — it removed a fixed
+ * set of tags (script/iframe/object/embed/form/base/meta/link/style), stripped on* attrs and a
+ * few dangerous URL schemes, then re-serialized. Denylists are mXSS-prone: they did not strip
+ * `svg`/`math` (which carry their own foreign-namespace parsing rules and can smuggle script via
+ * namespace confusion), did not strip `style` attributes (CSS `expression()`/`url(javascript:)`
+ * on legacy engines), and had no positive allowlist, so any tag/attribute not explicitly named
+ * survived. `marked` runs with raw-HTML passthrough, so crafted HTML echoed by an agent flows
+ * straight into this function.
+ *
+ * This module replaces that with DOMPurify (Cure53), an allowlist sanitizer that is the
+ * industry standard for mXSS defense. It is configured to allow exactly the tag/attribute set
+ * that markdown rendering legitimately produces (headings, lists, code, blockquotes, links,
+ * tables, images with safe src) and to FORBID `style`/`svg`/`math` plus all event handlers and
+ * dangerous URL schemes.
+ *
+ * Cross-environment: in the browser this file runs as a classic <script> after
+ * vendor/dompurify.min.js and wires `window.sanitizeMarkdownHtml`. The factory is also exported
+ * (window/globalThis + CommonJS) so a jsdom unit test can build a sanitizer bound to a
+ * jsdom-window DOMPurify instance and exercise the exact same config.
+ *
+ * @globals {function} sanitizeMarkdownHtml - (html:string) => string, sanitized HTML
+ * @globals {function} createMarkdownSanitizer - (DOMPurify) => sanitizeMarkdownHtml (for tests)
+ * @dependency vendor/dompurify.min.js (provides the global DOMPurify)
+ * @loadorder 5.6 of 15 — after input-cjk.js(5.5), before app.js(6) (app.js calls it)
+ */
+
+(function (root) {
+  'use strict';
+
+  /**
+   * Tags markdown rendering (marked, gfm) legitimately emits. Anything outside this set is
+   * dropped by DOMPurify. Deliberately excludes svg/math (mXSS foreign-namespace vectors) and
+   * form/embed/object/iframe/script/style (no place in rendered markdown).
+   */
+  var ALLOWED_TAGS = [
+    'a',
+    'b',
+    'blockquote',
+    'br',
+    'caption',
+    'code',
+    'del',
+    'div',
+    'em',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'hr',
+    'i',
+    'img',
+    'ins',
+    'kbd',
+    'li',
+    'mark',
+    'ol',
+    'p',
+    'pre',
+    'q',
+    's',
+    'samp',
+    'span',
+    'strong',
+    'sub',
+    'sup',
+    'table',
+    'tbody',
+    'td',
+    'tfoot',
+    'th',
+    'thead',
+    'tr',
+    'ul',
+    'var',
+  ];
+
+  /**
+   * Attributes allowed on the tags above. `style` is intentionally absent (CSS-based vectors).
+   * `class`/`id` survive because the response viewer adds wrapper classes downstream and code
+   * blocks may carry `language-*` classes from marked.
+   */
+  var ALLOWED_ATTR = [
+    'href',
+    'src',
+    'alt',
+    'title',
+    'class',
+    'id',
+    'name',
+    'colspan',
+    'rowspan',
+    'align',
+    'width',
+    'height',
+    'lang',
+    'dir',
+    'start',
+    'reversed',
+    'type',
+  ];
+
+  /**
+   * Build a sanitizer bound to a specific DOMPurify instance. The browser passes the global
+   * DOMPurify; tests pass a jsdom-window-bound instance so the same config is exercised under
+   * vitest without a real browser.
+   */
+  function createMarkdownSanitizer(DOMPurify) {
+    if (!DOMPurify || typeof DOMPurify.sanitize !== 'function') {
+      throw new Error('createMarkdownSanitizer: a DOMPurify instance is required');
+    }
+
+    var CONFIG = {
+      ALLOWED_TAGS: ALLOWED_TAGS,
+      ALLOWED_ATTR: ALLOWED_ATTR,
+      // Defense in depth even though style/svg/math are not in ALLOWED_TAGS: also forbid the
+      // foreign-namespace roots and style so config drift can't silently re-admit them.
+      FORBID_TAGS: ['style', 'svg', 'math', 'script', 'iframe', 'object', 'embed', 'form'],
+      FORBID_ATTR: ['style'],
+      // NOTE: do NOT set USE_PROFILES here. DOMPurify treats USE_PROFILES and
+      // ALLOWED_TAGS/ALLOWED_ATTR as mutually exclusive — when a profile is set it
+      // RESETS the allow-lists to the full profile and silently ignores the curated
+      // lists above, widening the tag set far beyond what markdown emits. Relying on
+      // the explicit ALLOWED_TAGS/ALLOWED_ATTR keeps the tight allowlist in force;
+      // FORBID_TAGS/FORBID_ATTR remain as defense-in-depth. DOMPurify still applies
+      // its default safe-URI handling (blocks javascript:/vbscript:, allows
+      // http/https/mailto/tel + data: only on image tags).
+      ALLOW_DATA_ATTR: false,
+      ADD_ATTR: [],
+      RETURN_DOM: false,
+      RETURN_DOM_FRAGMENT: false,
+      // Keep text content of any removed element (so stripping a stray tag doesn't eat prose),
+      // matching the previous serializer's behavior of dropping the element but not its text.
+      KEEP_CONTENT: true,
+    };
+
+    return function sanitizeMarkdownHtml(html) {
+      return DOMPurify.sanitize(html == null ? '' : String(html), CONFIG);
+    };
+  }
+
+  // Expose the factory for tests (and any non-browser consumer).
+  if (root) {
+    root.createMarkdownSanitizer = createMarkdownSanitizer;
+    // In the browser, vendor/dompurify.min.js has already defined the global DOMPurify.
+    if (root.DOMPurify && typeof root.DOMPurify.sanitize === 'function') {
+      root.sanitizeMarkdownHtml = createMarkdownSanitizer(root.DOMPurify);
+    }
+  }
+
+  // CommonJS export for the vitest/jsdom unit test.
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = {
+      createMarkdownSanitizer: createMarkdownSanitizer,
+      ALLOWED_TAGS: ALLOWED_TAGS,
+      ALLOWED_ATTR: ALLOWED_ATTR,
+    };
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : this);

src/web/public/settings-ui.js

@@ -313,8 +313,12 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('appSettingsShowProjectInsights').checked = settings.showProjectInsights ?? defaults.showProjectInsights ?? false;
     document.getElementById('appSettingsShowFileBrowser').checked = settings.showFileBrowser ?? defaults.showFileBrowser ?? false;
     document.getElementById('appSettingsShowSubagents').checked = settings.showSubagents ?? defaults.showSubagents ?? false;
+    document.getElementById('appSettingsShowUltracodeAgents').checked = settings.showUltracodeAgents ?? defaults.showUltracodeAgents ?? false;
+    document.getElementById('appSettingsUltracodeFloatingWindows').checked =
+      settings.ultracodeFloatingWindows ?? defaults.ultracodeFloatingWindows ?? false;
     document.getElementById('appSettingsShowMultiMonitorButton').checked = settings.showMultiMonitorButton ?? defaults.showMultiMonitorButton ?? false;
     document.getElementById('appSettingsShowPlanUsageLimits').checked = settings.showPlanUsageLimits ?? defaults.showPlanUsageLimits ?? false;
+    document.getElementById('appSettingsShowRedrawButton').checked = settings.showRedrawButton ?? defaults.showRedrawButton ?? false;
     // Gesture control lives in the Input section (alongside Local Echo / CJK Input)
     // but is only available when the instance runs with CODEMAN_GESTURE=1 (server sets
     // window.__codemanGestureAvailable). Hide just this item otherwise so the toggle
@@ -1173,6 +1177,48 @@ Object.assign(CodemanApp.prototype, {
     } catch {
       /* non-JSON body — use the default message */
     }
+    // 403 = the no-password safety refusal (COD-55). Warn loudly and let the
+    // operator acknowledge the risk; on confirm, retry with explicit acknowledgment.
+    if (res.status === 403) {
+      const confirmed = confirm(
+        '⚠️ SECURITY WARNING — no password set\n\n' +
+          'Enabling the Cloudflare tunnel will publish THIS machine to a public URL with ' +
+          'NO login. Anyone who gets the URL has full terminal control — effectively remote ' +
+          'code execution on your computer.\n\n' +
+          'Strongly recommended: set CODEMAN_PASSWORD instead.\n\n' +
+          'Enable the unauthenticated public tunnel anyway?'
+      );
+      if (!confirmed) {
+        this._dismissTunnelConnecting?.();
+        this.showToast('Tunnel not enabled', 'info');
+        return true;
+      }
+      try {
+        const retry = await fetch('/api/settings', {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ tunnelEnabled: true, acknowledgeUnauthTunnel: true }),
+        });
+        if (retry.ok) {
+          this.showToast('Public tunnel enabling — no password set ⚠️', 'warning');
+          return false; // proceed with the caller's success/connecting path
+        }
+        let m = 'Failed to enable tunnel.';
+        try {
+          const b = await retry.json();
+          if (b && b.error) m = b.error;
+        } catch {
+          /* non-JSON */
+        }
+        this._dismissTunnelConnecting?.();
+        this.showToast(m, 'error');
+        return true;
+      } catch {
+        this._dismissTunnelConnecting?.();
+        this.showToast('Failed to enable tunnel', 'error');
+        return true;
+      }
+    }
     this._dismissTunnelConnecting?.();
     this.showToast(message, 'error');
     return true;
@@ -1368,8 +1414,11 @@ Object.assign(CodemanApp.prototype, {
       showProjectInsights: document.getElementById('appSettingsShowProjectInsights').checked,
       showFileBrowser: document.getElementById('appSettingsShowFileBrowser').checked,
       showSubagents: document.getElementById('appSettingsShowSubagents').checked,
+      showUltracodeAgents: document.getElementById('appSettingsShowUltracodeAgents').checked,
+      ultracodeFloatingWindows: document.getElementById('appSettingsUltracodeFloatingWindows').checked,
       showMultiMonitorButton: document.getElementById('appSettingsShowMultiMonitorButton').checked,
       showPlanUsageLimits: document.getElementById('appSettingsShowPlanUsageLimits').checked,
+      showRedrawButton: document.getElementById('appSettingsShowRedrawButton').checked,
       gestureControlEnabled: document.getElementById('appSettingsGestureControl').checked,
       subagentTrackingEnabled: document.getElementById('appSettingsSubagentTracking').checked,
       subagentActiveTabOnly: document.getElementById('appSettingsSubagentActiveTabOnly').checked,
@@ -1682,9 +1731,12 @@ Object.assign(CodemanApp.prototype, {
         showProjectInsights: false,
         showFileBrowser: false,
         showSubagents: false,
+        showUltracodeAgents: false,
+        ultracodeFloatingWindows: false,
         showMultiMonitorButton: false,
         showPlanUsageLimits: false,
         showAttachmentsButton: false,
+        showRedrawButton: false,
         // Input
         gestureControlEnabled: false,
         // Feature toggles - keep tracking on even on mobile
@@ -1805,6 +1857,15 @@ Object.assign(CodemanApp.prototype, {
       multiMonitorBtn.classList.toggle('btn-multimonitor--hidden', !showMultiMonitorButton);
     }
 
+    // Ultracode/Workflow agents launcher — hidden by default; reveal when enabled.
+    // Marker class only (base is display:inline-flex !important) so it's auto-excluded
+    // from the mobile-header-buttons-policy guard.
+    const showUltracodeAgents = settings.showUltracodeAgents ?? defaults.showUltracodeAgents ?? false;
+    const ultracodeBtn = document.querySelector('.btn-ultracode-agents');
+    if (ultracodeBtn) {
+      ultracodeBtn.classList.toggle('btn-ultracode-agents--hidden', !showUltracodeAgents);
+    }
+
     // Plan-usage chip — hidden by default (App Settings → Display → "Plan Usage
     // Limits"). Server renders the initial state on reload; this handles a live
     // toggle from a settings save. Marker class (base is display:inline-flex
@@ -1815,6 +1876,12 @@ Object.assign(CodemanApp.prototype, {
       planUsageChip.classList.toggle('header-plan-usage--hidden', !showPlanUsageLimits);
     }
 
+    const showRedrawButton = settings.showRedrawButton ?? defaults.showRedrawButton ?? false;
+    const redrawBtn = document.querySelector('.btn-redraw-terminal');
+    if (redrawBtn) {
+      redrawBtn.classList.toggle('btn-redraw-terminal--hidden', !showRedrawButton);
+    }
+
     // Notification bell is retired (notifications live in Settings → Notifications
     // + the drawer); keep it hidden regardless of the notification-enabled state.
     const notifBtn = document.querySelector('.btn-notifications');
@@ -1876,6 +1943,27 @@ Object.assign(CodemanApp.prototype, {
       }
     }
 
+    // Ultracode agents panel visibility (SYNCED setting — not in displayKeys)
+    const showUltracodeAgents = settings.showUltracodeAgents ?? defaults.showUltracodeAgents ?? false;
+    const ultracodePanel = document.getElementById('ultracodeAgentsPanel');
+    if (ultracodePanel) {
+      if (showUltracodeAgents) {
+        ultracodePanel.classList.remove('hidden');
+      } else {
+        ultracodePanel.classList.remove('open');
+        ultracodePanel.classList.add('hidden');
+      }
+    }
+    // Floating ultracode run windows have their OWN opt-in (default OFF), independent of the
+    // docked panel above: pop active runs when enabled, tear them all down when disabled
+    // (additional layer — ultracode-windows.js).
+    const ultracodeFloatingWindows = settings.ultracodeFloatingWindows ?? defaults.ultracodeFloatingWindows ?? false;
+    if (ultracodeFloatingWindows) {
+      if (typeof this.syncAllUltracodeFloatingWindows === 'function') this.syncAllUltracodeFloatingWindows();
+    } else if (typeof this.removeAllUltracodeWindows === 'function') {
+      this.removeAllUltracodeWindows();
+    }
+
     // File browser panel visibility
     const fileBrowserPanel = document.getElementById('fileBrowserPanel');
     if (fileBrowserPanel) {
@@ -2027,7 +2115,7 @@ Object.assign(CodemanApp.prototype, {
         // are NOT display keys — they control server-side behavior and must sync from server.
         const displayKeys = new Set([
           'showFontControls', 'showSystemStats', 'showTokenCount', 'showCost',
-          'showLifecycleLog', 'showResponseViewer',
+          'showLifecycleLog', 'showResponseViewer', 'showRedrawButton',
           'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
           'subagentActiveTabOnly', 'tabTwoRows', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
           'skin', 'showPlanUsageLimits', 'showAttachmentsButton',

src/web/public/styles.css

@@ -312,6 +312,13 @@ body {
   max-height: 120px;
 }
 
+.session-tabs.tabs-auto-wrap {
+  flex-wrap: wrap;
+  overflow-x: hidden;
+  overflow-y: auto;
+  max-height: 96px;
+}
+
 .session-tabs::-webkit-scrollbar {
   width: 4px;
   height: 0;
@@ -989,6 +996,12 @@ body {
   display: none !important;
 }
 
+/* Redraw terminal header button: hidden by default (opt-in via App Settings →
+   Display → "Header Displays"). Pure client-side toggle. */
+.btn-redraw-terminal--hidden {
+  display: none !important;
+}
+
 .btn-icon-header.btn-settings {
   width: 30px;
   height: 30px;
@@ -2222,6 +2235,34 @@ body.solo-mode .btn-lifecycle-log {
   background: transparent !important;
 }
 
+/* Touch devices: prevent browser from claiming the touch gesture before
+   our JS touchmove handler fires. Without this, the browser starts native
+   scrolling during the first few px of finger travel and ignores our
+   subsequent preventDefault() — breaking custom terminal scroll. */
+.touch-device .terminal-container,
+.touch-device .terminal-container .xterm,
+.touch-device .terminal-container .xterm-viewport,
+.touch-device .terminal-container .xterm-screen {
+  touch-action: none;
+}
+
+/* Mobile terminal taps are cursor-positioning gestures, not text-selection gestures.
+   xterm re-enables selectable DOM text in its accessibility tree, so force the
+   whole terminal subtree back to non-selectable on touch devices. Synthetic mouse
+   events for tap-to-position still dispatch normally through JavaScript. */
+body.touch-device .terminal-container .xterm,
+body.touch-device .terminal-container .xterm .xterm-viewport,
+body.touch-device .terminal-container .xterm .xterm-screen,
+body.touch-device .terminal-container .xterm .xterm-rows,
+body.touch-device .terminal-container .xterm .xterm-accessibility-tree,
+body.touch-device .terminal-container .xterm .xterm-accessibility-tree *,
+body.touch-device .terminal-container .xterm .xterm-selection,
+body.touch-device .terminal-container .xterm .xterm-helper-textarea {
+  user-select: none !important;
+  -webkit-user-select: none !important;
+  -webkit-touch-callout: none !important;
+}
+
 /* Welcome Overlay */
 .welcome-overlay {
   position: absolute;
@@ -2712,6 +2753,13 @@ body.solo-mode .btn-lifecycle-log {
   contain: style;
 }
 
+/* backdrop-filter creates a stacking context, trapping the popover's
+   z-index inside the toolbar. When the popover is open, raise the toolbar
+   above the CJK input (z-index 52) so the popover is interactable. */
+.toolbar:has(.case-settings-popover:not(.hidden)) {
+  z-index: 100;
+}
+
 .toolbar-left,
 .toolbar-right {
   display: flex;
@@ -3000,6 +3048,11 @@ body.solo-mode .btn-lifecycle-log {
   white-space: nowrap;
 }
 
+/* Touch devices (iPad, tablets): show stop button — no physical Ctrl+C */
+.touch-device .btn-toolbar.btn-stop {
+  display: flex;
+}
+
 /* Mobile app settings gear - hidden on desktop, shown on mobile */
 .btn-settings-mobile {
   display: none;
@@ -5520,6 +5573,45 @@ kbd {
   letter-spacing: 0.03em;
 }
 
+/* Ultracode run minimized-to-tab badge — same chip shape as the subagent badge but a
+   distinct purple (matches the ultracode window accent), and a SEPARATE class so the
+   incremental tab-update path (which keys on .tab-subagent-badge) never touches it.
+   Reuses the shared .subagent-dropdown for its restore/dismiss list. */
+.session-tab .tab-ultracode-badge {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 2px;
+  height: 16px;
+  padding: 0 5px;
+  border-radius: 8px;
+  font-size: 0.6rem;
+  cursor: pointer;
+  background: #a855f7;
+  color: white;
+  margin-left: 4px;
+  transition: transform 0.1s, background 0.15s;
+}
+@media (hover: hover) {
+  .session-tab .tab-ultracode-badge:hover {
+    background: #9333ea;
+    transform: scale(1.05);
+  }
+}
+.session-tab .tab-ultracode-badge .subagent-label {
+  font-size: 0.55rem;
+  font-weight: 600;
+  letter-spacing: 0.03em;
+}
+/* Per-item type glyph in the ULTRA dropdown (🧬 run vs 📄 transcript). */
+.subagent-dropdown-item .ultracode-dd-icon {
+  font-size: 0.7rem;
+  line-height: 1;
+  flex-shrink: 0;
+  margin-right: 1px;
+}
+
 /* Subagent Dropdown - compact, hover-triggered */
 .subagent-dropdown {
   display: none;
@@ -7232,12 +7324,22 @@ kbd {
   max-height: 100%;
 }
 
+.file-preview-body audio {
+  display: block;
+  width: 90%;
+  margin: 2rem auto;
+}
+
 .file-preview-body .binary-message {
   padding: 2rem;
   text-align: center;
   color: var(--text-muted);
 }
 
+.file-preview-body .binary-message a {
+  color: var(--accent, #4ea1ff);
+}
+
 .file-preview-footer {
   padding: 0.35rem 0.75rem;
   font-size: 0.7rem;
@@ -8338,6 +8440,368 @@ kbd {
   display: none !important;
 }
 
+/* "Ultracode Agents" header launcher — opt-in (App Settings → Display), hidden by
+   default everywhere (so the mobile-header-buttons-policy guard auto-excludes it).
+   Base inline-flex !important + a more-specific marker rule to hide. */
+.btn-ultracode-agents {
+  display: inline-flex !important;
+}
+.btn-ultracode-agents.btn-ultracode-agents--hidden {
+  display: none !important;
+}
+
+/* ===== Ultracode / Workflow agents master-detail panel ===== */
+/* Reuses .subagents-panel dock behavior but anchors LEFT so it never overlaps the
+   bottom-right subagents panel when both are open. */
+.ultracode-agents-panel {
+  right: auto;
+  left: 0.5rem;
+  width: 640px;
+}
+@media (max-width: 700px) {
+  .ultracode-agents-panel {
+    left: 0;
+    right: 0;
+    width: 100%;
+    max-width: 100%;
+  }
+}
+
+/* LEFT pane: run rows */
+.ultracode-run-item {
+  padding: 0.45rem 0.5rem;
+  border-radius: 6px;
+  background: var(--bg-input);
+  margin-bottom: 0.4rem;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+.ultracode-run-item:hover {
+  background: var(--bg-card);
+}
+.ultracode-run-item.selected {
+  background: var(--bg-card);
+  border: 1px solid var(--accent);
+}
+.ultracode-run-head {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  margin-bottom: 0.2rem;
+}
+.ultracode-run-name {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.ultracode-run-stats {
+  font-size: 0.65rem;
+  color: var(--text-dim);
+}
+.ultracode-status {
+  font-size: 0.58rem;
+  padding: 0.05rem 0.3rem;
+  border-radius: 4px;
+  margin-left: auto;
+  text-transform: lowercase;
+  background: var(--text-muted);
+  color: white;
+  flex-shrink: 0;
+}
+.ultracode-status.completed {
+  background: var(--green);
+}
+.ultracode-status.active {
+  background: var(--yellow);
+  color: black;
+}
+.ultracode-status.failed {
+  background: var(--red, #b3261e);
+  color: white;
+}
+
+/* LEFT pane: phase chips for the selected run */
+.ultracode-phase-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+  margin-top: 0.4rem;
+}
+.ultracode-phase-chip {
+  font-size: 0.62rem;
+  padding: 0.1rem 0.4rem;
+  border-radius: 10px;
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  color: var(--text-muted);
+  cursor: pointer;
+}
+.ultracode-phase-chip:hover {
+  color: var(--text);
+}
+.ultracode-phase-chip.selected {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: white;
+}
+
+/* RIGHT pane: per-phase header + agent cards */
+.ultracode-phase-header {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  font-size: 0.7rem;
+  font-weight: 600;
+  color: var(--text);
+  margin: 0.5rem 0 0.3rem;
+  padding-bottom: 0.2rem;
+  border-bottom: 1px solid var(--border);
+}
+.ultracode-phase-sub {
+  font-size: 0.62rem;
+  font-weight: 400;
+  color: var(--text-dim);
+}
+.ultracode-agent-card {
+  background: var(--bg-input);
+  border-radius: 6px;
+  padding: 0.4rem 0.5rem;
+  margin-bottom: 0.35rem;
+  border-left: 3px solid transparent;
+}
+/* At-a-glance agent state: yellow while working, green when done. */
+.ultracode-agent-card.uw-state-working {
+  border-left-color: var(--yellow);
+  background: color-mix(in srgb, var(--yellow) 9%, var(--bg-input));
+}
+.ultracode-agent-card.uw-state-done {
+  border-left-color: var(--green);
+  background: color-mix(in srgb, var(--green) 9%, var(--bg-input));
+}
+.ultracode-agent-card--clickable {
+  cursor: pointer;
+  transition: background 0.15s;
+}
+.ultracode-agent-card--clickable:hover {
+  background: var(--bg-card);
+}
+/* Keep the state tint on hover (equal specificity to the hover rule, so it must
+   come after it) — a tad stronger so the hover still reads as interactive. */
+.ultracode-agent-card--clickable.uw-state-working:hover {
+  background: color-mix(in srgb, var(--yellow) 16%, var(--bg-card));
+}
+.ultracode-agent-card--clickable.uw-state-done:hover {
+  background: color-mix(in srgb, var(--green) 16%, var(--bg-card));
+}
+.ultracode-agent-top {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  margin-bottom: 0.25rem;
+}
+.ultracode-agent-label {
+  font-size: 0.72rem;
+  font-weight: 600;
+  color: var(--text);
+  font-family: var(--font-mono);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.ultracode-agent-state {
+  font-size: 0.56rem;
+  padding: 0.05rem 0.3rem;
+  border-radius: 4px;
+  margin-left: auto;
+  flex-shrink: 0;
+  background: var(--text-muted);
+  color: white;
+}
+.ultracode-agent-state.completed {
+  background: var(--green);
+}
+.ultracode-agent-state.active {
+  background: var(--yellow);
+  color: black;
+}
+.ultracode-agent-state.idle {
+  background: var(--bg-card);
+  color: var(--text-muted);
+}
+.ultracode-agent-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.3rem;
+}
+.ultracode-chip {
+  font-size: 0.62rem;
+  padding: 0.05rem 0.35rem;
+  border-radius: 4px;
+  background: var(--bg-card);
+  color: var(--text-muted);
+  font-family: var(--font-mono);
+}
+.ultracode-chip-tok {
+  color: var(--accent);
+}
+.ultracode-chip-tool {
+  color: var(--text);
+}
+.ultracode-agent-sub {
+  font-size: 0.62rem;
+  color: var(--text-dim);
+  margin-top: 0.25rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* ========== Ultracode floating run windows (additional to the dock panel) ========== */
+/* A draggable window that auto-pops while a Workflow/ultracode run is active and is
+   tied by a glowing connector line to the originating session tab (ultracode-windows.js). */
+.ultracode-window {
+  position: fixed;
+  width: 380px;
+  height: 320px;
+  min-width: 260px;
+  min-height: 140px;
+  max-width: 92vw;
+  max-height: 80vh;
+  background: var(--bg-card);
+  border: 1px solid #a855f7;
+  border-radius: 8px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.45), 0 0 0 1px rgba(168, 85, 247, 0.15);
+  z-index: 1000;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  resize: both;
+  contain: layout paint;
+  transition: transform 0.18s ease, opacity 0.18s ease;
+}
+.ultracode-window.spawning {
+  transform: scale(0.92);
+  opacity: 0;
+}
+.ultracode-window-header {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.45rem 0.6rem;
+  background: var(--bg-input);
+  border-bottom: 1px solid var(--border);
+  cursor: move;
+}
+.ultracode-window-title {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  flex: 1;
+  min-width: 0;
+}
+.ultracode-window-title .icon {
+  font-size: 0.95rem;
+  flex-shrink: 0;
+}
+.ultracode-window-title .uw-name {
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.ultracode-window-title .uw-status {
+  flex-shrink: 0;
+  margin-left: 0;
+}
+.ultracode-window-actions {
+  display: flex;
+  gap: 0.25rem;
+  flex-shrink: 0;
+}
+.ultracode-window-actions button {
+  background: transparent;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  padding: 0.15rem 0.4rem;
+  font-size: 0.9rem;
+  line-height: 1;
+}
+.ultracode-window-actions button:hover {
+  color: var(--text);
+}
+.ultracode-window-body {
+  flex: 1;
+  overflow-y: auto;
+  overflow-x: hidden;
+  padding: 0.5rem;
+  background: var(--bg);
+  min-height: 0;
+}
+.ultracode-window-body::-webkit-scrollbar {
+  width: 6px;
+}
+.ultracode-window-body::-webkit-scrollbar-thumb {
+  background: var(--border);
+  border-radius: 3px;
+}
+.ultracode-window-body .uw-summary {
+  font-size: 0.65rem;
+  color: var(--text-dim);
+  font-family: var(--font-mono);
+  margin-bottom: 0.4rem;
+}
+
+/* Ultracode connector line — the session-tab accent blue (dashed to stay distinct
+   from the solid subagent lines, per the same-blue-as-the-tab request). */
+.connection-line.ultracode-connection {
+  stroke: var(--accent);
+  stroke-width: 3;
+  stroke-dasharray: 6 3;
+  filter: drop-shadow(0 0 2px rgba(0, 0, 0, 0.8))
+          drop-shadow(0 0 5px rgba(var(--accent-rgb), 0.85))
+          drop-shadow(0 0 10px rgba(var(--accent-rgb), 0.5));
+  animation: ultracode-conn-pulse 1.4s ease-in-out infinite;
+}
+.connection-line.ultracode-connection:hover {
+  stroke-width: 3.5;
+}
+@keyframes ultracode-conn-pulse {
+  0%, 100% { opacity: 0.8; }
+  50% { opacity: 1; }
+}
+
+/* Agent-transcript window: spawned from an agent card (in a run window or the dock
+   panel), tied to its parent run window by its own connector line. Reuses the
+   .ultracode-window chrome; wider with a monospace transcript body. */
+.ultracode-agent-window {
+  width: 470px;
+  height: 420px;
+  border-color: #38bdf8;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.45), 0 0 0 1px rgba(56, 189, 248, 0.18);
+}
+.ultracode-agent-window .ultracode-window-body .uw-transcript {
+  margin: 0;
+  white-space: pre-wrap;
+  word-break: break-word;
+  font-family: var(--font-mono);
+  font-size: 0.68rem;
+  line-height: 1.45;
+  color: var(--text);
+}
+/* Distinguish the parent→agent line from the tab→run line: solid cyan, no dashes.
+   Must follow .ultracode-connection (equal specificity → source order wins). */
+.connection-line.ultracode-agent-connection {
+  stroke: #38bdf8;
+  stroke-dasharray: none;
+  filter: drop-shadow(0 0 2px rgba(0, 0, 0, 0.8)) drop-shadow(0 0 5px rgba(56, 189, 248, 0.85));
+}
+
 /* Plan-usage chip (App Settings → Display → "Plan Usage Limits"). Shows the
    live 5-hour + weekly plan limits parsed from the Claude statusline. Hidden by
    default via the marker class below; the server strips it at render when the
@@ -8966,8 +9430,9 @@ kbd {
   bottom: calc(var(--safe-area-bottom) + 40px);
   z-index: 52;
   display: block;
-  min-height: 44px;
-  max-height: 96px;
+  min-height: 34px;
+  max-height: 68px;
+  padding: 6px 10px;
   border: 1px solid rgba(80, 120, 190, 0.55);
   border-left: none;
   border-right: none;
@@ -8986,6 +9451,193 @@ body.touch-device.cjk-input-visible .main {
   padding-bottom: calc(84px + var(--safe-area-bottom));
 }
 
+/* ═══════════════════════════════════════════════════════════════
+   Keyboard Accessory Bar
+   Base styles in styles.css (always loaded) so iPad landscape (≥1024px,
+   where mobile.css doesn't load) still gets dark styling. Phone overrides
+   remain in mobile.css @media (max-width: 430px).
+   ═══════════════════════════════════════════════════════════════ */
+
+.keyboard-accessory-bar {
+  display: none;
+  height: 44px;
+  background: #1a1a1a;
+  border-top: 1px solid rgba(255, 255, 255, 0.1);
+  padding: 6px 8px;
+  gap: 8px;
+  align-items: center;
+  overflow-x: auto;
+  overflow-y: hidden;
+  -webkit-overflow-scrolling: touch;
+  z-index: 51;
+}
+
+.keyboard-accessory-bar.visible {
+  display: flex;
+}
+
+.keyboard-accessory-bar::-webkit-scrollbar {
+  display: none;
+}
+
+/* Touch devices: fixed positioning to float above keyboard.
+   Phone CSS (mobile.css) adds bottom + safe-area padding;
+   iPad JS sets bottom dynamically via updateLayoutForKeyboard(). */
+.touch-device .keyboard-accessory-bar {
+  position: fixed;
+  left: 0;
+  right: 0;
+  transition: transform 0.15s ease-out;
+  will-change: transform;
+}
+
+.accessory-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  gap: 4px;
+  padding: 6px 12px;
+  background: #2a2a2a;
+  border: 1px solid rgba(255, 255, 255, 0.15);
+  border-radius: 6px;
+  color: #e5e5e5;
+  font-size: 0.65rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 0.15s, border-color 0.15s;
+}
+
+.accessory-btn.confirming {
+  background: #6b4f00;
+  border-color: #b8860b;
+  color: #ffd54f;
+}
+
+.accessory-btn:active {
+  background: #3a3a3a;
+}
+
+.accessory-btn svg {
+  width: 14px;
+  height: 14px;
+}
+
+.accessory-btn-arrow {
+  padding: 6px 10px;
+  background: #2563eb;
+  border-color: rgba(59, 130, 246, 0.5);
+  color: #fff;
+}
+
+.accessory-btn-arrow:active {
+  background: #1d4ed8;
+}
+
+.accessory-btn-dismiss {
+  margin-left: auto;
+  flex: 1 1 0;
+  max-width: 100px;
+  padding: 10px 8px;
+  background: #2563eb;
+  border-color: rgba(59, 130, 246, 0.5);
+  color: #fff;
+  font-weight: 600;
+}
+
+.accessory-btn-dismiss svg {
+  width: 22px;
+  height: 22px;
+}
+
+.accessory-btn-dismiss:active {
+  background: #1d4ed8;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Paste Overlay
+   Base styles in styles.css so iPad landscape works.
+   ═══════════════════════════════════════════════════════════════ */
+
+.paste-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.6);
+  z-index: 10000;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding-top: 15vh;
+}
+
+.paste-dialog {
+  background: var(--bg-secondary, #1e1e2e);
+  border: 1px solid var(--border-color, #444);
+  border-radius: 12px;
+  padding: 12px;
+  width: calc(100% - 24px);
+  max-width: 400px;
+}
+
+.paste-textarea {
+  width: 100%;
+  min-height: 80px;
+  max-height: 200px;
+  background: var(--bg-primary, #0d0d14);
+  color: var(--text-primary, #e0e0e0);
+  border: 1px solid var(--border-color, #444);
+  border-radius: 8px;
+  padding: 8px;
+  font-family: inherit;
+  font-size: 16px;
+  resize: none;
+  box-sizing: border-box;
+}
+
+.paste-textarea:focus {
+  outline: none;
+  border-color: var(--accent-color, #7aa2f7);
+}
+
+.paste-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 10px;
+}
+
+.paste-cancel, .paste-new, .paste-send, .paste-image {
+  padding: 8px 18px;
+  border: none;
+  border-radius: 8px;
+  font-size: 14px;
+  cursor: pointer;
+}
+
+.paste-image {
+  margin-right: auto;
+  background: var(--bg-tertiary, #333);
+  color: var(--accent-color, #7aa2f7);
+  border: 1px solid var(--accent-color, #7aa2f7);
+}
+
+.paste-cancel {
+  background: var(--bg-tertiary, #333);
+  color: var(--text-secondary, #aaa);
+}
+
+.paste-new {
+  background: var(--bg-tertiary, #333);
+  color: var(--accent-color, #7aa2f7);
+  border: 1px solid var(--accent-color, #7aa2f7);
+}
+
+.paste-send {
+  background: var(--accent-color, #7aa2f7);
+  color: #fff;
+  font-weight: 600;
+}
+
 /* ═══════════════════════════════════════════════════════════════
    Orchestrator Panel
    ═══════════════════════════════════════════════════════════════ */
@@ -9857,3 +10509,38 @@ html:not([data-skin="og"]) {
 /* ---- Focus rings (driven by --accent, now emerald) stay accessible ---- */
 :focus-visible { outline-color: var(--accent); }
 }
+
+/* ---- Daylight Blue: distinct identity per welcome action button ----
+   Run Claude Code keeps the blue accent; Cloudflare Tunnel is purple; Run
+   OpenCode is emerald green — so the three are clearly different colors instead
+   of all reading blue. Scoped to daylight-blue only; placed after the shared
+   daylight block to win on equal specificity. ---- */
+html[data-skin="daylight-blue"] .welcome-btn-opencode {
+  background: linear-gradient(135deg, #0d9f6e, #2fbf85);
+  border-color: rgba(16, 185, 129, 0.5);
+  color: #04291b;
+}
+html[data-skin="daylight-blue"] .welcome-btn-opencode:hover {
+  background: linear-gradient(135deg, #10b981, #34d399);
+  border-color: rgba(52, 211, 153, 0.6);
+  box-shadow: 0 0 28px -4px rgba(16, 185, 129, 0.4);
+}
+html[data-skin="daylight-blue"] .welcome-btn-tunnel {
+  background: linear-gradient(135deg, #7c3aed, #a855f7);
+  border-color: rgba(168, 85, 247, 0.5);
+  color: #f5f3ff;
+}
+html[data-skin="daylight-blue"] .welcome-btn-tunnel:hover {
+  background: linear-gradient(135deg, #8b5cf6, #c084fc);
+  border-color: rgba(192, 132, 252, 0.6);
+  box-shadow: 0 0 28px -4px rgba(124, 58, 237, 0.45);
+}
+html[data-skin="daylight-blue"] .welcome-btn-tunnel.active {
+  background: linear-gradient(135deg, #6d28d9, #7c3aed);
+  border-color: rgba(124, 58, 237, 0.6);
+  color: #f5f3ff;
+}
+html[data-skin="daylight-blue"] .welcome-btn-tunnel.active:hover {
+  background: linear-gradient(135deg, #7c3aed, #8b5cf6);
+  box-shadow: 0 0 28px -4px rgba(124, 58, 237, 0.5);
+}

src/web/public/subagent-windows.js

@@ -455,6 +455,16 @@ Object.assign(CodemanApp.prototype, {
         svg.appendChild(line);
       }
     }
+
+    // Ultracode floating run windows → parent tab (additional layer, ultracode-windows.js).
+    // Drawn into the same SVG and same batched read/write pass; the tab-rect cache is shared.
+    if (typeof this._appendUltracodeConnectionLines === 'function') {
+      this._appendUltracodeConnectionLines(svg, rects);
+    }
+    // Agent-transcript windows → their run window / tab (ultracode-windows.js).
+    if (typeof this._appendUltracodeAgentConnectionLines === 'function') {
+      this._appendUltracodeAgentConnectionLines(svg, rects);
+    }
   },
 
   // ═══════════════════════════════════════════════════════════════
@@ -975,6 +985,9 @@ Object.assign(CodemanApp.prototype, {
     }
     this.imagePopups.clear();
 
+    // Clean up ultracode floating run windows (re-seeded from data.workflowRuns on reconnect)
+    if (typeof this.removeAllUltracodeWindows === 'function') this.removeAllUltracodeWindows();
+
     // Clear orphaned plan generation state
     this.activePlanOrchestratorId = null;
     this._planProgressHandler = null;

src/web/public/terminal-ui.js

@@ -19,6 +19,10 @@
   // suppressed, so high-frequency Codex status redraws don't snap the viewport
   // back to the bottom while the user is inspecting earlier output.
   const USER_SCROLL_STICKY_SUPPRESS_MS = 1500;
+  // Mobile browsers synthesize trusted mouse events after touchend. During this
+  // short window, only the app's synthetic tap-to-position mouse event should
+  // reach xterm.
+  const TOUCH_COMPAT_MOUSE_SUPPRESS_MS = 450;
 
   function isTerminalQueryResponse(data) {
     return TERMINAL_QUERY_RESPONSE_PATTERN.test(data) || TERMINAL_OSC_RESPONSE_PATTERN.test(data);
@@ -46,6 +50,7 @@
     isTerminalQueryResponse,
     shouldSuppressTerminalQueryResponse,
     USER_SCROLL_STICKY_SUPPRESS_MS,
+    TOUCH_COMPAT_MOUSE_SUPPRESS_MS,
   };
   global.CODEMAN_XTERM_THEMES = CODEMAN_XTERM_THEMES;
   global.codemanCurrentXtermTheme = currentXtermTheme;
@@ -107,6 +112,7 @@ Object.assign(CodemanApp.prototype, {
 
     const container = document.getElementById('terminalContainer');
     this.terminal.open(container);
+    this._installMobileTapMouseGuard();
 
     // Suppress xterm key handling during CJK IME composition.
     // Without this, xterm processes raw keyDown events (e.g., "Process" key)
@@ -114,8 +120,14 @@ Object.assign(CodemanApp.prototype, {
     this.terminal.attachCustomKeyEventHandler((ev) => {
       if (ev.isComposing || ev.keyCode === 229) return false;
 
-      // Let Alt+digit pass through to browser (tab switching)
-      if (ev.altKey && ev.key >= '0' && ev.key <= '9') return false;
+      // Let the app's Alt/Option session-nav shortcuts reach the document keydown handler
+      // (app.js switches tabs by PHYSICAL e.code) instead of xterm injecting ESC<char> into
+      // the PTY. Mirror app.js's gate exactly — same physical codes + modifier guard — so
+      // macOS Option layouts (Option+1 -> "¡", Option+[ -> "“") are suppressed here too and
+      // don't leak an escape sequence into the focused terminal on every tab switch.
+      if (ev.altKey && !ev.ctrlKey && !ev.shiftKey && /^(Digit[1-9]|BracketLeft|BracketRight)$/.test(ev.code || '')) {
+        return false;
+      }
 
       // Ctrl+V / Cmd+V: intercept before xterm sends ^V to PTY.
       // Route through our paste trap which handles both images and text.
@@ -359,11 +371,14 @@ Object.assign(CodemanApp.prototype, {
       let pixelAccum = 0;
 
       let didScroll = false; // track whether touchmove fired (tap vs scroll)
+      let touchStartY = 0;
+      const TAP_THRESHOLD = 8; // px — ignore micro-drift to distinguish tap from scroll
       container.addEventListener(
         'touchstart',
         (ev) => {
           if (ev.touches.length === 1) {
             touchLastY = ev.touches[0].clientY;
+            touchStartY = touchLastY;
             velocity = 0;
             pixelAccum = 0;
             isTouching = true;
@@ -382,9 +397,18 @@ Object.assign(CodemanApp.prototype, {
         'touchmove',
         (ev) => {
           if (ev.touches.length === 1 && isTouching) {
-            ev.preventDefault();
-            didScroll = true;
             const touchY = ev.touches[0].clientY;
+            if (!didScroll && Math.abs(touchY - touchStartY) >= TAP_THRESHOLD) {
+              didScroll = true;
+            }
+            // Below the tap threshold, treat the gesture as a potential tap:
+            // don't preventDefault (iOS needs click synthesis to show the
+            // keyboard) and don't accumulate scroll distance or velocity. Without
+            // this guard, sub-threshold micro-drift still scrolls a line and
+            // leaves a non-zero velocity that touchend turns into a momentum
+            // fling, so a jittery tap would both position the cursor AND scroll.
+            if (!didScroll) return;
+            ev.preventDefault();
             const delta = touchLastY - touchY; // positive = scroll down
             pixelAccum += delta;
             velocity = delta * 1.2;
@@ -404,20 +428,38 @@ Object.assign(CodemanApp.prototype, {
 
       container.addEventListener(
         'touchend',
-        () => {
+        (ev) => {
           isTouching = false;
           if (!scrollFrame && Math.abs(velocity) > 0.3) {
             scrollFrame = requestAnimationFrame(scrollLoop);
           }
-          // Tap (no scroll): refocus xterm's hidden textarea so keyboard input
-          // routes back to the terminal. Without this, a tap on the terminal area
-          // consumes the touch event but xterm's textarea never regains focus.
           if (!didScroll && this.terminal) {
+            // ── Tap-to-position cursor ──────────────────────────────────
+            // Synthesize a click from the real touch point so the foreground app
+            // moves its cursor to the tapped cell (iOS doesn't reliably do this
+            // itself under touch-action:none). CRITICAL: only when mouse tracking
+            // is ON. xterm disables its local SelectionService while mouse events
+            // are active, so the synthetic click is forwarded to the PTY as an SGR
+            // report (cursor moves). But when tracking is OFF, that same click
+            // drives xterm's LOCAL selection (detail 1/2/3 → char/word/line) — a
+            // tap on CJK text would select & copy it instead of positioning. So
+            // gate strictly on the live mouse-tracking mode.
+            const touch = ev.changedTouches && ev.changedTouches[0];
+            const mouseMode = this.terminal.modes?.mouseTrackingMode;
+            const mouseTrackingOn = !!mouseMode && mouseMode !== 'none';
+            if (touch) {
+              this._suppressTrustedTapMouseEvents();
+            }
+            if (touch && mouseTrackingOn) {
+              this._dispatchSyntheticTerminalClick(touch.clientX, touch.clientY);
+            }
+            this._syncMobileHelperTextareaToCursor();
+            // Route subsequent typing to the right place: keep the CJK input
+            // field focused when Chinese input is on, otherwise the terminal.
             const cjkInput = document.getElementById('cjkInput');
             if (cjkInput?.classList.contains('cjk-input-visible')) {
               cjkInput.focus();
             } else {
-              this._syncMobileHelperTextareaToCursor();
               this.terminal.focus();
             }
           }
@@ -579,8 +621,13 @@ Object.assign(CodemanApp.prototype, {
     // survives tab switches and reconnects.
 
     this.terminal.onData((data) => {
-      // CJK input has focus — block xterm from sending to PTY
-      if (window.cjkActive || document.activeElement?.id === 'cjkInput') return;
+      // Mouse SGR reports (tap-to-position) are NOT IME input — they must reach
+      // the PTY even while the CJK input field owns focus. Without this exception
+      // tapping to move the cursor silently does nothing whenever Chinese input
+      // is on, because cjkActive stays true the whole time the field is visible.
+      const isMouseReport = /^\x1b\[<\d+;\d+;\d+[Mm]$/.test(data);
+      // CJK input has focus — block xterm from sending keystrokes to PTY
+      if (!isMouseReport && (window.cjkActive || document.activeElement?.id === 'cjkInput')) return;
       if (this.activeSessionId) {
         // Filter terminal query replies generated by xterm.js itself.
         // Forwarding them through the WebSocket injects DA/DSR/CPR replies
@@ -937,6 +984,9 @@ Object.assign(CodemanApp.prototype, {
       this.loadTunnelStatus();
       this.loadHistorySessions();
     }
+    // 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.
+    this._updateCjkInputState?.();
   },
 
   hideWelcome() {
@@ -950,6 +1000,9 @@ Object.assign(CodemanApp.prototype, {
       clearTimeout(this._welcomeQrShrinkTimer);
       qrWrap.classList.remove('expanded');
     }
+    // Entering a session — restore CJK textarea if the user has it enabled
+    // (activeSessionId is already set by selectSession before this call).
+    this._updateCjkInputState?.();
   },
 
   /**
@@ -1565,71 +1618,11 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  // CJK textarea already provides visual feedback — bypass local echo
+  // buffering so each composed word reaches the PTY immediately.
   _handleCjkInput(text) {
     if (!this.activeSessionId) return;
-    const sessionId = this.activeSessionId;
-    const session = this.sessions.get(sessionId);
-    const useLocalEcho = !!(this._localEchoEnabled && this._localEchoOverlay && session?.mode !== 'shell');
-    if (!useLocalEcho) {
-      this._sendInputAsync(sessionId, text);
-      return;
-    }
-
-    if (text === '\x7f') {
-      const source = this._localEchoOverlay.removeChar();
-      if (source === 'flushed') {
-        // Sync app-level flushed Maps (per-session state for tab switching),
-        // mirroring the onData backspace path — otherwise switching tabs away
-        // and back restores a stale, too-long flushed overlay.
-        const { count, text: flushedText } = this._localEchoOverlay.getFlushed();
-        if (this._flushedOffsets?.has(sessionId)) {
-          if (count === 0) {
-            this._flushedOffsets.delete(sessionId);
-            this._flushedTexts?.delete(sessionId);
-          } else {
-            this._flushedOffsets.set(sessionId, count);
-            this._flushedTexts?.set(sessionId, flushedText);
-          }
-        }
-        this._sendInputAsync(sessionId, text);
-      }
-      return;
-    }
-
-    if (/[\r\n]+$/.test(text)) {
-      const committed = text.replace(/[\r\n]+$/g, '');
-      if (committed) this._localEchoOverlay.appendText(committed);
-      const pending = this._localEchoOverlay.pendingText || '';
-      this._localEchoOverlay.clear();
-      this._localEchoOverlay.suppressBufferDetection();
-      this._flushedOffsets?.delete(sessionId);
-      this._flushedTexts?.delete(sessionId);
-      if (pending) this._sendInputAsync(sessionId, pending);
-      setTimeout(() => this._sendInputAsync(sessionId, '\r'), pending ? 80 : 0);
-      return;
-    }
-
-    // Multi-byte escape sequence (arrow/Home/End from a hardware keyboard on
-    // the composer) — forward to the PTY without touching overlay state,
-    // mirroring the onData path. Appending it to pending text would type raw
-    // ESC bytes into the prompt on the next Enter.
-    if (text.length > 1 && text.charCodeAt(0) === 27) {
-      this._sendInputAsync(sessionId, text);
-      return;
-    }
-
-    if (text.length === 1 && text.charCodeAt(0) < 32) {
-      const pending = this._localEchoOverlay.pendingText || '';
-      this._localEchoOverlay.clear();
-      this._localEchoOverlay.suppressBufferDetection();
-      this._flushedOffsets?.delete(sessionId);
-      this._flushedTexts?.delete(sessionId);
-      if (pending) this._sendInputAsync(sessionId, pending);
-      this._sendInputAsync(sessionId, text);
-      return;
-    }
-
-    this._localEchoOverlay.appendText(text);
+    this._sendInputAsync(this.activeSessionId, text);
   },
 
   /**
@@ -1983,9 +1976,10 @@ Object.assign(CodemanApp.prototype, {
     }
 
     try {
-      // Send resize to restore proper dimensions (with minimum enforcement).
-      // The PTY's SIGWINCH on real dim change is enough for Ink to redraw.
-      await this.sendResize(this.activeSessionId);
+      // Force resize even when dimensions match the server's last known state —
+      // another device may have changed the PTY size since this client last sent,
+      // and force guarantees a SIGWINCH → Ink redraw at the current device's size.
+      await this.sendResize(this.activeSessionId, { force: true });
 
       this.showToast(`Terminal restored to ${dims.cols}x${dims.rows}`, 'success');
     } catch (err) {
@@ -2042,6 +2036,62 @@ Object.assign(CodemanApp.prototype, {
     } catch {}
   },
 
+  // ═══════════════════════════════════════════════════════════════
+  // Synthetic tap → mouse report
+  // ═══════════════════════════════════════════════════════════════
+  // Dispatch a mousedown+mouseup pair at viewport coords (clientX/clientY) to
+  // xterm's root element. xterm's mouse-reporting handler reads the event's
+  // client coords, maps them to a terminal cell relative to .xterm-screen, and
+  // — when the foreground app has mouse tracking active (DECSET 1000/1002/1006,
+  // which Claude's input enables) — encodes an SGR mouse report to the PTY.
+  // That is the same path a real desktop click takes; on touch devices the
+  // browser's own compatibility-event synthesis is unreliable (and suppressed
+  // by touch-action:none), so we drive it explicitly. With mouse tracking off
+  // it degrades to a harmless zero-length click (no drag → no text selection).
+  _dispatchSyntheticTerminalClick(clientX, clientY) {
+    const el = this.terminal?.element;
+    if (!el || !Number.isFinite(clientX) || !Number.isFinite(clientY)) return;
+    // xterm registers its mouseup listener on document during mousedown, so a
+    // bubbling mouseup reaches it; dispatch both to the root element in order.
+    const base = {
+      bubbles: true,
+      cancelable: true,
+      view: window,
+      clientX,
+      clientY,
+      screenX: clientX,
+      screenY: clientY,
+      button: 0,
+      detail: 1,
+    };
+    try {
+      el.dispatchEvent(new MouseEvent('mousedown', { ...base, buttons: 1 }));
+      el.dispatchEvent(new MouseEvent('mouseup', { ...base, buttons: 0 }));
+    } catch {
+      /* MouseEvent constructor unavailable — tap-to-position simply no-ops */
+    }
+  },
+
+  _installMobileTapMouseGuard() {
+    const el = this.terminal?.element;
+    if (!el || el._codemanTapMouseGuardInstalled) return;
+    if (typeof MobileDetection !== 'undefined' && MobileDetection.isTouchDevice && !MobileDetection.isTouchDevice()) return;
+    el._codemanTapMouseGuardInstalled = true;
+    const suppressTrustedCompatMouse = (ev) => {
+      const suppressUntil = this._trustedTapMouseSuppressUntil || 0;
+      if (!ev.isTrusted || performance.now() > suppressUntil) return;
+      ev.preventDefault();
+      ev.stopImmediatePropagation();
+    };
+    el.addEventListener('mousedown', suppressTrustedCompatMouse, true);
+    el.addEventListener('mouseup', suppressTrustedCompatMouse, true);
+  },
+
+  _suppressTrustedTapMouseEvents() {
+    const ms = window.CodemanTerminalInput?.TOUCH_COMPAT_MOUSE_SUPPRESS_MS || 450;
+    this._trustedTapMouseSuppressUntil = performance.now() + ms;
+  },
+
   increaseFontSize() {
     const current = this.terminal.options.fontSize || 14;
     this.setFontSize(Math.min(current + 2, 24));
@@ -2091,8 +2141,8 @@ Object.assign(CodemanApp.prototype, {
   /**
    * Send resize to a session with minimum dimension enforcement.
    * @param {string} sessionId
-   * @param {{ forceHttp?: boolean }} [options]
-   * @returns {Promise<void>}
+   * @param {{ forceHttp?: boolean, force?: boolean }} [options]
+   * @returns {Promise<boolean>} Whether dimensions changed from the last send
    */
   async sendResize(sessionId, options = {}) {
     // Fit terminal to container before reading dimensions — ensures local
@@ -2121,16 +2171,20 @@ Object.assign(CodemanApp.prototype, {
     // Fast path: WebSocket resize
     if (!options.forceHttp && this._wsReady && this._wsSessionId === sessionId) {
       try {
-        this._ws.send(JSON.stringify({ t: 'z', c: dims.cols, r: dims.rows, v: viewportType }));
+        const msg = { t: 'z', c: dims.cols, r: dims.rows, v: viewportType };
+        if (options.force) msg.f = true;
+        this._ws.send(JSON.stringify(msg));
         return changed;
       } catch {
         // Fall through to HTTP POST
       }
     }
+    const body = { ...dims, viewportType };
+    if (options.force) body.force = true;
     await fetch(`/api/sessions/${sessionId}/resize`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ ...dims, viewportType }),
+      body: JSON.stringify(body),
     });
     return changed;
   },

src/web/public/ultracode-panel.js

@@ -0,0 +1,324 @@
+/**
+ * @fileoverview Ultracode / Workflow run visualization — master-detail dock panel.
+ *
+ * Mirrors Claude Code's "working agents" TUI: LEFT pane = runs and their phases
+ * (selectable "tasks"), RIGHT pane = the selected run's agents with model, live
+ * state, TOKENS burned, and TOOL CALLS. Opt-in via the `showUltracodeAgents`
+ * setting; the launcher button + panel are hidden until enabled.
+ *
+ * Data: run SUMMARIES arrive via getLightState (`data.workflowRuns`) and the
+ * `workflow:run_*` SSE events (LEFT list). The full run (with agents[]) is fetched
+ * per-run from GET /api/workflows/:runId when a run is selected (RIGHT pane).
+ *
+ * Standalone: reads only the workflow-run endpoints; never touches subagent state.
+ *
+ * @mixin Extends CodemanApp.prototype via Object.assign
+ * @loadorder 11.5 (after panels-ui.js, before session-ui.js)
+ */
+/* global CodemanApp, SSE_EVENTS, escapeHtml */
+
+Object.assign(CodemanApp.prototype, {
+  /** Ensure workflow state maps exist (lazy — constructor also seeds them). */
+  _ensureWorkflowState() {
+    if (!this.workflowRuns) this.workflowRuns = new Map(); // runId -> summary
+    if (!this.workflowRunDetails) this.workflowRunDetails = new Map(); // runId -> full run (with agents)
+    if (this.activeWorkflowRunId === undefined) this.activeWorkflowRunId = null;
+    if (this.activeWorkflowPhaseIndex === undefined) this.activeWorkflowPhaseIndex = null;
+  },
+
+  /** Seed the LEFT list from a getLightState snapshot (array of run summaries). */
+  seedWorkflowRuns(summaries) {
+    this._ensureWorkflowState();
+    this.workflowRuns.clear();
+    (summaries || []).forEach((s) => this.workflowRuns.set(s.runId, s));
+    // Restore floating windows for runs that are still active & recent (additional layer).
+    if (typeof this._syncUltracodeFloatingWindow === 'function') {
+      (summaries || []).forEach((s) => this._syncUltracodeFloatingWindow(s, { fromSeed: true }));
+    }
+    this.renderUltracodeAgentsPanel();
+  },
+
+  // ----- SSE handlers (wired in app.js _SSE_HANDLER_MAP) -----
+  _onWorkflowRunDiscovered(data) {
+    this._upsertWorkflowRun(data);
+  },
+  _onWorkflowRunUpdated(data) {
+    this._upsertWorkflowRun(data);
+  },
+  _onWorkflowRunRemoved(data) {
+    this._ensureWorkflowState();
+    if (!data || !data.runId) return;
+    this.workflowRuns.delete(data.runId);
+    this.workflowRunDetails.delete(data.runId);
+    if (this.activeWorkflowRunId === data.runId) this.activeWorkflowRunId = null;
+    // Retire the floating run window too (additional layer — ultracode-windows.js).
+    if (typeof this.closeUltracodeWindow === 'function') this.closeUltracodeWindow(data.runId, false);
+    this.renderUltracodeAgentsPanel();
+  },
+
+  _upsertWorkflowRun(summary) {
+    this._ensureWorkflowState();
+    if (!summary || !summary.runId) return;
+    this.workflowRuns.set(summary.runId, summary);
+    // If the live-updating run is the one open in the detail pane, refresh its agents.
+    if (this.activeWorkflowRunId === summary.runId) {
+      this._fetchWorkflowRunDetail(summary.runId);
+    }
+    // Auto-pop / refresh the floating run window for active runs (additional layer).
+    if (typeof this._syncUltracodeFloatingWindow === 'function') this._syncUltracodeFloatingWindow(summary);
+    this.renderUltracodeAgentsPanel();
+  },
+
+  // ----- Panel open/close -----
+  toggleUltracodeAgentsPanel() {
+    const panel = document.getElementById('ultracodeAgentsPanel');
+    if (!panel) return;
+    panel.classList.remove('hidden');
+    panel.classList.toggle('open');
+    if (panel.classList.contains('open')) this.renderUltracodeAgentsPanel();
+  },
+  closeUltracodeAgentsPanel() {
+    // The X must FULLY hide the panel. Removing only `open` drops it to the
+    // collapsed peek state (header strip still visible), so add `hidden`
+    // (display:none) too — mirrors closeSubagentsPanel. Not the showUltracodeAgents
+    // setting: that also gates the watcher + floating windows; the launcher reopens.
+    const panel = document.getElementById('ultracodeAgentsPanel');
+    if (panel) {
+      panel.classList.remove('open');
+      panel.classList.add('hidden');
+    }
+  },
+
+  // ----- Selection -----
+  selectWorkflowRun(runId) {
+    this._ensureWorkflowState();
+    this.activeWorkflowRunId = runId;
+    this.activeWorkflowPhaseIndex = null; // reset phase filter on run change
+    this._fetchWorkflowRunDetail(runId);
+    this.renderUltracodeAgentsPanel();
+    // Clicking a run also pops its floating window (with connector line to the
+    // session tab), like the auto-popped one — an explicit open, so it ignores the
+    // floating-windows auto-pop toggle (ultracode-windows.js).
+    if (typeof this.openUltracodeWindowForRun === 'function') this.openUltracodeWindowForRun(runId);
+  },
+  selectWorkflowPhase(phaseIndex) {
+    this._ensureWorkflowState();
+    // phaseIndex null => show all phases
+    this.activeWorkflowPhaseIndex = phaseIndex === null || phaseIndex === undefined ? null : Number(phaseIndex);
+    this._renderUltracodeDetail();
+  },
+
+  async _fetchWorkflowRunDetail(runId) {
+    // De-dupe concurrent fetches for the same run — selecting a run can trigger both
+    // a panel refresh and a floating-window open, which would otherwise double-fetch.
+    if (!this._wfDetailInFlight) this._wfDetailInFlight = new Set();
+    if (this._wfDetailInFlight.has(runId)) return;
+    this._wfDetailInFlight.add(runId);
+    try {
+      const res = await fetch(`/api/workflows/${encodeURIComponent(runId)}`);
+      const env = await res.json();
+      const run = env && env.success ? env.data : null;
+      if (run) {
+        this.workflowRunDetails.set(runId, run);
+        if (this.activeWorkflowRunId === runId) this._renderUltracodeDetail();
+        // Refresh the floating window (if one is open for this run) with the fetched agents[].
+        if (this.ultracodeWindows && this.ultracodeWindows.has(runId)) this.renderUltracodeWindowContent(runId);
+      }
+    } catch {
+      /* transient — next update retries */
+    } finally {
+      this._wfDetailInFlight.delete(runId);
+    }
+  },
+
+  // Phase 4: fetch an agent's live transcript by agentId. The workflow agent's
+  // agentId is byte-identical to the agent-<id>.jsonl stem already tracked by
+  // subagent-watcher, so we reuse the existing transcript route — no watcher edits.
+  // Returns { formatted: string[], entryCount } or null when nothing is available
+  // (queued / aged out of tracking / tracking disabled). Rendering into a connected
+  // in-page floating window lives in ultracode-windows.js (openUltracodeAgentWindow) —
+  // we no longer spawn a detached browser popup.
+  async _fetchWorkflowAgentTranscript(agentId) {
+    if (!agentId) return null;
+    let data = null;
+    try {
+      const res = await fetch(`/api/subagents/${encodeURIComponent(agentId)}/transcript?format=formatted`);
+      data = await res.json();
+    } catch {
+      data = null;
+    }
+    const ok = data && data.success && data.data;
+    const formatted = ok ? data.data.formatted : null;
+    const entryCount = ok ? data.data.entryCount || 0 : 0;
+    if (!formatted || !entryCount) return null;
+    return { formatted, entryCount };
+  },
+
+  // ----- Render (debounced) -----
+  renderUltracodeAgentsPanel() {
+    clearTimeout(this._ultracodeRenderTimer);
+    this._ultracodeRenderTimer = setTimeout(() => this._renderUltracodeAgentsPanelImmediate(), 150);
+  },
+
+  _renderUltracodeAgentsPanelImmediate() {
+    this._ensureWorkflowState();
+    const panel = document.getElementById('ultracodeAgentsPanel');
+    if (!panel) return;
+    const badge = document.getElementById('ultracodeCountBadge');
+    if (badge) badge.textContent = this.workflowRuns.size ? String(this.workflowRuns.size) : '';
+    this._renderUltracodeRunList();
+    this._renderUltracodeDetail();
+  },
+
+  _renderUltracodeRunList() {
+    const list = document.getElementById('ultracodeRunList');
+    if (!list) return;
+    const runs = Array.from(this.workflowRuns.values()).sort(
+      (a, b) => (b.lastActivityAt || 0) - (a.lastActivityAt || 0)
+    );
+    if (!runs.length) {
+      list.innerHTML = '<div class="subagent-empty">No ultracode runs detected</div>';
+      return;
+    }
+    list.innerHTML = runs.map((r) => this._workflowRunRowHtml(r)).join('');
+  },
+
+  _workflowRunRowHtml(r) {
+    const active = r.runId === this.activeWorkflowRunId;
+    const name = escapeHtml(r.workflowName || r.summary || r.runId);
+    const status = String(r.status || '');
+    const statusCls = this._workflowStatusClass(status);
+    const stats = `${r.agentCount ?? 0} agents · ${this._fmtNum(r.totalTokens)} tok · ${r.totalToolCalls ?? 0} tools`;
+    let phasesHtml = '';
+    if (active && Array.isArray(r.phases) && r.phases.length) {
+      const allActive = this.activeWorkflowPhaseIndex === null ? ' selected' : '';
+      const chips = [
+        `<div class="ultracode-phase-chip${allActive}" onclick="event.stopPropagation();app.selectWorkflowPhase(null)">All</div>`,
+      ];
+      r.phases.forEach((p, i) => {
+        const sel = this.activeWorkflowPhaseIndex === i + 1 ? ' selected' : '';
+        chips.push(
+          `<div class="ultracode-phase-chip${sel}" title="${escapeHtml(p.detail || '')}" onclick="event.stopPropagation();app.selectWorkflowPhase(${i + 1})">${escapeHtml(p.title || 'Phase ' + (i + 1))}</div>`
+        );
+      });
+      phasesHtml = `<div class="ultracode-phase-list">${chips.join('')}</div>`;
+    }
+    return (
+      `<div class="ultracode-run-item${active ? ' selected' : ''}" onclick="app.selectWorkflowRun('${escapeHtml(r.runId)}')">` +
+      `<div class="ultracode-run-head"><span class="ultracode-run-name">${name}</span>` +
+      `<span class="ultracode-status ${statusCls}">${escapeHtml(status || '—')}</span></div>` +
+      `<div class="ultracode-run-stats">${escapeHtml(stats)}</div>` +
+      phasesHtml +
+      `</div>`
+    );
+  },
+
+  _renderUltracodeDetail() {
+    const detail = document.getElementById('ultracodeAgentGrid');
+    if (!detail) return;
+    const runId = this.activeWorkflowRunId;
+    if (!runId) {
+      detail.innerHTML = '<div class="subagent-empty">Select a run to view its agents</div>';
+      return;
+    }
+    const run = this.workflowRunDetails.get(runId);
+    if (!run) {
+      detail.innerHTML = '<div class="subagent-empty">Loading agents…</div>';
+      return;
+    }
+    const phases = Array.isArray(run.phases) ? run.phases : [];
+    let agents = Array.isArray(run.agents) ? run.agents : [];
+    if (this.activeWorkflowPhaseIndex !== null) {
+      agents = agents.filter((a) => a.phaseIndex === this.activeWorkflowPhaseIndex);
+    }
+    if (!agents.length) {
+      detail.innerHTML = '<div class="subagent-empty">No agents in this view</div>';
+      return;
+    }
+    // Group agents by phaseIndex, in phase order.
+    const groups = new Map();
+    agents.forEach((a) => {
+      const key = a.phaseIndex || 0;
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push(a);
+    });
+    const orderedKeys = Array.from(groups.keys()).sort((a, b) => a - b);
+    const html = orderedKeys
+      .map((key) => {
+        const group = groups.get(key);
+        const title = (phases[key - 1] && phases[key - 1].title) || `Phase ${key}`;
+        const tok = group.reduce((s, a) => s + (a.tokens || 0), 0);
+        const tools = group.reduce((s, a) => s + (a.toolCalls || 0), 0);
+        const header =
+          `<div class="ultracode-phase-header"><span>${escapeHtml(title)}</span>` +
+          `<span class="ultracode-phase-sub">${this._fmtNum(tok)} tok · ${tools} tools</span></div>`;
+        return header + group.map((a) => this._workflowAgentCardHtml(a, runId)).join('');
+      })
+      .join('');
+    detail.innerHTML = html;
+  },
+
+  _workflowAgentCardHtml(a, runId) {
+    const state = String(a.state || 'start');
+    const stateCls = this._workflowAgentStateClass(state);
+    const stateLabel = state === 'start' ? 'queued' : state === 'progress' ? 'running' : state;
+    const model = this._modelShort(a.model);
+    const tokens = a.tokens === undefined ? '—' : this._fmtNum(a.tokens);
+    const tools = a.toolCalls === undefined ? '—' : String(a.toolCalls);
+    let secondary = '';
+    if (state === 'done' && a.resultPreview) {
+      secondary = escapeHtml(a.resultPreview);
+    } else if (a.lastToolName) {
+      secondary = escapeHtml(a.lastToolName + (a.lastToolSummary ? ' · ' + a.lastToolSummary : ''));
+    }
+    // Phase 4: cards with an agentId open the live transcript (the agentId is byte-identical
+    // to the agent-<id>.jsonl stem already tracked by subagent-watcher). 'start' agents have
+    // no agentId yet, so they stay non-clickable.
+    const clickable = !!a.agentId;
+    // At-a-glance state tint on the whole card: green when done, yellow while working.
+    const cardStateCls = state === 'done' ? ' uw-state-done' : state === 'progress' ? ' uw-state-working' : '';
+    const cardAttrs = clickable
+      ? ` class="ultracode-agent-card ultracode-agent-card--clickable${cardStateCls}" role="button" tabindex="0"` +
+        ` title="View transcript" onclick="app.openUltracodeAgentWindow('${escapeHtml(a.agentId)}','${escapeHtml(runId || '')}')"`
+      : ` class="ultracode-agent-card${cardStateCls}"`;
+    return (
+      `<div${cardAttrs}>` +
+      `<div class="ultracode-agent-top">` +
+      `<span class="ultracode-agent-label">${escapeHtml(a.label || 'agent')}</span>` +
+      `<span class="ultracode-agent-state ${stateCls}">${escapeHtml(stateLabel)}</span>` +
+      `</div>` +
+      `<div class="ultracode-agent-meta">` +
+      `<span class="ultracode-chip" title="model">${escapeHtml(model)}</span>` +
+      `<span class="ultracode-chip ultracode-chip-tok" title="tokens burned">${tokens} tok</span>` +
+      `<span class="ultracode-chip ultracode-chip-tool" title="tool calls">${tools} tools</span>` +
+      `</div>` +
+      (secondary ? `<div class="ultracode-agent-sub">${secondary}</div>` : '') +
+      `</div>`
+    );
+  },
+
+  // ----- helpers -----
+  _workflowStatusClass(status) {
+    if (status === 'completed') return 'completed';
+    if (status === 'running') return 'active';
+    if (status === 'killed' || status === 'failed') return 'failed';
+    return '';
+  },
+  _workflowAgentStateClass(state) {
+    if (state === 'done') return 'completed';
+    if (state === 'progress') return 'active';
+    return 'idle'; // start / queued
+  },
+  _modelShort(model) {
+    if (!model) return '';
+    return String(model)
+      .replace(/^claude-/, '')
+      .replace(/-\d{8}$/, '');
+  },
+  _fmtNum(n) {
+    if (n === undefined || n === null) return '0';
+    if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + 'M';
+    if (n >= 1000) return (n / 1000).toFixed(1) + 'k';
+    return String(n);
+  },
+});

src/web/public/ultracode-windows.js

@@ -0,0 +1,848 @@
+/**
+ * @fileoverview Ultracode floating run windows — auto-popping draggable windows
+ * with a connector line to the originating session tab.
+ *
+ * This is the "floating thing" companion to the docked master-detail panel in
+ * `ultracode-panel.js` (the dock panel stays — these windows are ADDITIONAL).
+ * When the `ultracodeFloatingWindows` setting is on (a DEDICATED toggle, separate
+ * from the dock panel's `showUltracodeAgents` — see `_ultracodeFloatingEnabled`),
+ * a small floating window pops up
+ * for each ACTIVE ultracode/Workflow run (status not completed/killed/failed),
+ * mirroring the live agent grid, and is connected by a glowing line to the
+ * Codeman tab whose `claudeSessionId` matches the run's `sessionUuid` — the same
+ * line idiom subagent windows use. The window auto-closes a few seconds after
+ * its run finishes; an explicitly-closed run is remembered and never re-pops.
+ *
+ * Reuses, rather than duplicates:
+ *  - `makeWindowDraggable` + the shared `#connectionLines` SVG (subagent-windows.js)
+ *  - `_workflowAgentCardHtml`, `_fmtNum`, `_workflowStatusClass`, `_fetchWorkflowRunDetail`,
+ *    and the `workflowRuns` / `workflowRunDetails` maps (ultracode-panel.js)
+ *
+ * The connector-line draw is appended to the shared SVG from inside
+ * `_updateConnectionLinesImmediate` (subagent-windows.js calls
+ * `_appendUltracodeConnectionLines` at the end of its render pass), so both the
+ * subagent and ultracode lines live in one batched read→write reflow pass.
+ *
+ * @mixin Extends CodemanApp.prototype via Object.assign
+ * @dependency subagent-windows.js (makeWindowDraggable, updateConnectionLines, #connectionLines)
+ * @dependency ultracode-panel.js (workflowRuns/workflowRunDetails, _workflowAgentCardHtml, _fmtNum)
+ * @loadorder 15.5 (after subagent-windows.js — needs makeWindowDraggable at runtime)
+ */
+/* global CodemanApp, escapeHtml */
+
+Object.assign(CodemanApp.prototype, {
+  /** Lazily seed the floating-window state maps (constructor also seeds them). */
+  _ensureUltracodeWindowState() {
+    if (!this.ultracodeWindows) this.ultracodeWindows = new Map(); // runId -> { element, parentSessionId, dragListeners }
+    if (!this.ultracodeWindowsClosed) this.ultracodeWindowsClosed = new Set(); // runIds the user dismissed
+    if (!this.ultracodeWindowCloseTimers) this.ultracodeWindowCloseTimers = new Map(); // runId -> setTimeout id
+    if (!this.ultracodeAgentWindows) this.ultracodeAgentWindows = new Map(); // agentId -> { element, runId, dragListeners }
+    if (!this.minimizedUltracodeRuns) this.minimizedUltracodeRuns = new Map(); // sessionId -> Set<runId> minimized to a tab
+    if (!this.minimizedUltracodeAgents) this.minimizedUltracodeAgents = new Map(); // sessionId -> Map<agentId,{runId,label}>
+    if (this.ultracodeWindowZIndex === undefined) this.ultracodeWindowZIndex = 1000;
+  },
+
+  /** Floating windows have their own opt-in (default OFF), independent of the dock panel. */
+  _ultracodeFloatingEnabled() {
+    const settings = this.loadAppSettingsFromStorage ? this.loadAppSettingsFromStorage() : {};
+    return !!(settings && settings.ultracodeFloatingWindows);
+  },
+
+  /** A run is "working" until it reaches a terminal status. Mid-run status is absent. */
+  _isWorkflowRunActive(run) {
+    const s = String((run && run.status) || '');
+    return !(s === 'completed' || s === 'killed' || s === 'failed');
+  },
+
+  /**
+   * Resolve which Codeman tab a run belongs to: the session whose
+   * `claudeSessionId` equals the run's `sessionUuid` (the path segment the watcher
+   * captured). Falls back to the active session so the line still lands somewhere.
+   */
+  _resolveUltracodeParentSession(run) {
+    const uuid = run && run.sessionUuid;
+    if (uuid && this.sessions) {
+      for (const [sessionId, session] of this.sessions) {
+        if (session && session.claudeSessionId === uuid) return sessionId;
+      }
+    }
+    if (this.activeSessionId && this.sessions && this.sessions.has(this.activeSessionId)) {
+      return this.activeSessionId;
+    }
+    return null;
+  },
+
+  /**
+   * Auto-pop driver — called for every run discovered/updated and on reconnect seed.
+   * Creates a floating window for active runs, refreshes existing ones, and schedules
+   * an auto-close once a run finishes.
+   */
+  _syncUltracodeFloatingWindow(run, opts) {
+    this._ensureUltracodeWindowState();
+    if (!run || !run.runId) return;
+    const runId = run.runId;
+    const existing = this.ultracodeWindows.get(runId);
+    // Auto-pop is gated on the floating-windows toggle, but an ALREADY-open window
+    // (e.g. one opened by clicking the run in the dock) keeps refreshing regardless.
+    if (!existing && !this._ultracodeFloatingEnabled()) return;
+    if (this.ultracodeWindowsClosed.has(runId)) return; // respect explicit dismissal
+
+    const active = this._isWorkflowRunActive(run);
+
+    // Minimized to a tab — keep it there (don't re-pop a window). Clear the tab badge a
+    // short while after the run finishes, mirroring the floating window's finish grace.
+    if (this._isUltracodeRunMinimized(runId)) {
+      if (!active && !this.ultracodeWindowCloseTimers.has(runId)) {
+        const timer = setTimeout(() => {
+          this.ultracodeWindowCloseTimers.delete(runId);
+          this._removeMinimizedUltracodeRun(runId);
+          this.renderSessionTabs();
+          this.updateConnectionLines();
+        }, 8000);
+        this.ultracodeWindowCloseTimers.set(runId, timer);
+      }
+      return;
+    }
+
+    if (active) {
+      // Run is alive — cancel any pending auto-close.
+      const pending = this.ultracodeWindowCloseTimers.get(runId);
+      if (pending) {
+        clearTimeout(pending);
+        this.ultracodeWindowCloseTimers.delete(runId);
+      }
+      if (existing) {
+        this.renderUltracodeWindowContent(runId);
+        this._fetchWorkflowRunDetail(runId); // refresh agents[]; re-renders window on land
+      } else {
+        // On a reconnect snapshot, only restore windows for genuinely recent runs so
+        // a backlog of stale undefined-status runs doesn't carpet the screen.
+        if (opts && opts.fromSeed) {
+          const FLOAT_SEED_MAX_AGE_MS = 5 * 60 * 1000;
+          const age = Date.now() - (run.lastActivityAt || 0);
+          if (!(run.lastActivityAt && age < FLOAT_SEED_MAX_AGE_MS)) return;
+        }
+        this.createUltracodeWindow(run);
+      }
+    } else if (existing) {
+      // Finished — refresh to the final state (status + final agent states), show it
+      // briefly, then retire the floating window.
+      this._fetchWorkflowRunDetail(runId);
+      this.renderUltracodeWindowContent(runId);
+      if (!this.ultracodeWindowCloseTimers.has(runId)) {
+        const FLOAT_FINISH_GRACE_MS = 8000;
+        const timer = setTimeout(() => {
+          this.ultracodeWindowCloseTimers.delete(runId);
+          this.closeUltracodeWindow(runId, false);
+        }, FLOAT_FINISH_GRACE_MS);
+        this.ultracodeWindowCloseTimers.set(runId, timer);
+      }
+    }
+  },
+
+  /**
+   * Explicitly open (or focus) the floating window for a run — the click-through
+   * from the dock panel's run list. Unlike auto-pop this ignores the floating-windows
+   * toggle and clears any prior dismissal (it's a direct user action), then draws the
+   * connector line from the run's session tab.
+   */
+  openUltracodeWindowForRun(runId) {
+    this._ensureUltracodeWindowState();
+    if (!runId) return;
+    const run = this.workflowRuns && this.workflowRuns.get(runId);
+    if (!run) return;
+    this.ultracodeWindowsClosed.delete(runId); // an explicit open overrides a past dismissal
+    this._removeMinimizedUltracodeRun(runId); // …and a past minimize-to-tab
+    const existing = this.ultracodeWindows.get(runId);
+    if (existing) {
+      // Already open — bring to front and refresh.
+      existing.element.style.zIndex = ++this.ultracodeWindowZIndex;
+      this.renderUltracodeWindowContent(runId);
+      this._fetchWorkflowRunDetail(runId);
+      this.updateConnectionLines();
+    } else {
+      this.createUltracodeWindow(run);
+    }
+  },
+
+  /** Build and mount a floating window for a run, positioned near its parent tab. */
+  createUltracodeWindow(run) {
+    this._ensureUltracodeWindowState();
+    const runId = run.runId;
+    if (this.ultracodeWindows.has(runId)) return;
+    const parentSessionId = this._resolveUltracodeParentSession(run);
+    const titleText = run.workflowName || run.summary || runId;
+
+    const win = document.createElement('div');
+    win.className = 'ultracode-window spawning';
+    win.id = `ultracode-window-${runId}`;
+    win.style.zIndex = ++this.ultracodeWindowZIndex;
+    win.innerHTML = `
+      <div class="ultracode-window-header">
+        <div class="ultracode-window-title" title="${escapeHtml(titleText)}">
+          <span class="icon">🧬</span>
+          <span class="uw-name">${escapeHtml(titleText)}</span>
+          <span class="uw-status"></span>
+        </div>
+        <div class="ultracode-window-actions">
+          <button class="uw-min" type="button" title="Minimize to tab">─</button>
+          <button class="uw-close" type="button" title="Close">&times;</button>
+        </div>
+      </div>
+      <div class="ultracode-window-body" id="ultracode-window-body-${runId}">
+        <div class="subagent-empty">Loading agents…</div>
+      </div>
+    `;
+
+    // Position: spawn from the parent tab if we can find it, else cascade.
+    const parentTab = parentSessionId ? document.querySelector(`.session-tab[data-id="${parentSessionId}"]`) : null;
+    if (parentTab) {
+      const r = parentTab.getBoundingClientRect();
+      const left = Math.max(8, Math.min(r.left, window.innerWidth - 392));
+      win.style.left = `${left}px`;
+      win.style.top = `${r.bottom + 14}px`;
+    } else {
+      const n = this.ultracodeWindows.size;
+      win.style.left = `${24 + n * 26}px`;
+      win.style.top = `${96 + n * 26}px`;
+    }
+
+    document.body.appendChild(win);
+    // Drop the spawn class on the next frame so the transition runs.
+    requestAnimationFrame(() => win.classList.remove('spawning'));
+
+    const header = win.querySelector('.ultracode-window-header');
+    const dragListeners = this.makeWindowDraggable(win, header);
+
+    win.querySelector('.uw-min').addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.minimizeUltracodeWindowToTab(runId);
+    });
+    win.querySelector('.uw-close').addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.closeUltracodeWindow(runId, true);
+    });
+    const nameEl = win.querySelector('.uw-name');
+    if (parentSessionId) {
+      nameEl.style.cursor = 'pointer';
+      nameEl.title = 'Go to session';
+      nameEl.addEventListener('click', () => this.selectSession(parentSessionId));
+    }
+
+    this.ultracodeWindows.set(runId, { element: win, parentSessionId, dragListeners });
+
+    this.renderUltracodeWindowContent(runId);
+    this._fetchWorkflowRunDetail(runId); // pull agents[] for the body
+    this.updateConnectionLines();
+  },
+
+  // ── Minimize a run window into its originating tab (same idiom as subagent windows) ──
+
+  /** Is this run currently minimized to a tab (so auto-pop should leave it alone)? */
+  _isUltracodeRunMinimized(runId) {
+    if (!this.minimizedUltracodeRuns) return false;
+    for (const set of this.minimizedUltracodeRuns.values()) {
+      if (set.has(runId)) return true;
+    }
+    return false;
+  },
+
+  /** Drop a run from the minimized-to-tab tracking (all sessions, or a specific one). */
+  _removeMinimizedUltracodeRun(runId, sessionId) {
+    if (!this.minimizedUltracodeRuns) return;
+    if (sessionId) {
+      const set = this.minimizedUltracodeRuns.get(sessionId);
+      if (set) {
+        set.delete(runId);
+        if (!set.size) this.minimizedUltracodeRuns.delete(sessionId);
+      }
+      return;
+    }
+    for (const [sid, set] of this.minimizedUltracodeRuns) {
+      if (set.delete(runId) && !set.size) this.minimizedUltracodeRuns.delete(sid);
+    }
+  },
+
+  /**
+   * Minimize the floating run window into its originating session tab: record it as
+   * minimized (so a badge renders on the tab), genie-animate the window toward that
+   * tab, then remove the floating element. Restorable from the tab badge dropdown.
+   */
+  minimizeUltracodeWindowToTab(runId) {
+    this._ensureUltracodeWindowState();
+    const data = this.ultracodeWindows.get(runId);
+    if (!data) return;
+
+    let parentSessionId = data.parentSessionId;
+    if (!parentSessionId) {
+      const summary = this.workflowRuns && this.workflowRuns.get(runId);
+      parentSessionId = summary ? this._resolveUltracodeParentSession(summary) : null;
+    }
+    // No tab to fly into → fall back to a plain close so the window isn't orphaned.
+    if (!parentSessionId) {
+      this.closeUltracodeWindow(runId, true);
+      return;
+    }
+
+    // Cancel any pending finish auto-close — the badge owns the run's lifecycle now.
+    const pending = this.ultracodeWindowCloseTimers.get(runId);
+    if (pending) {
+      clearTimeout(pending);
+      this.ultracodeWindowCloseTimers.delete(runId);
+    }
+
+    if (!this.minimizedUltracodeRuns.has(parentSessionId)) this.minimizedUltracodeRuns.set(parentSessionId, new Set());
+    this.minimizedUltracodeRuns.get(parentSessionId).add(runId);
+
+    const element = data.element;
+    const dragListeners = data.dragListeners;
+    this._animateUltracodeWindowToTab(element, parentSessionId, () => {
+      this._teardownUltracodeDrag(dragListeners);
+      if (element) element.remove();
+      this.ultracodeWindows.delete(runId);
+      // Full rebuild so the tab badge renders (the incremental path only knows subagent badges).
+      this._fullRenderSessionTabs();
+      this.updateConnectionLines();
+    });
+  },
+
+  /** Genie the window toward the center of its tab, then invoke `done` to tear it down. */
+  _animateUltracodeWindowToTab(element, sessionId, done) {
+    const tab = sessionId ? document.querySelector(`.session-tab[data-id="${sessionId}"]`) : null;
+    if (!tab || !element) {
+      done();
+      return;
+    }
+    const w = element.getBoundingClientRect();
+    const t = tab.getBoundingClientRect();
+    const dx = t.left + t.width / 2 - (w.left + w.width / 2);
+    const dy = t.top + t.height / 2 - (w.top + w.height / 2);
+    element.style.transformOrigin = 'center center';
+    element.style.transition = 'transform 0.26s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.26s ease';
+    element.style.pointerEvents = 'none';
+    requestAnimationFrame(() => {
+      element.style.transform = `translate(${dx}px, ${dy}px) scale(0.06)`;
+      element.style.opacity = '0';
+    });
+    let finished = false;
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      done();
+    };
+    element.addEventListener('transitionend', finish, { once: true });
+    setTimeout(finish, 320); // fallback in case transitionend doesn't fire
+  },
+
+  /** Tab badge (with restore/dismiss dropdown) for runs minimized to this session's tab. */
+  renderUltracodeTabBadge(sessionId) {
+    this._ensureUltracodeWindowState();
+    const runSet = this.minimizedUltracodeRuns.get(sessionId);
+    const agentMap = this.minimizedUltracodeAgents.get(sessionId);
+    const total = (runSet ? runSet.size : 0) + (agentMap ? agentMap.size : 0);
+    if (total === 0) return '';
+
+    const trunc = (s) => (s.length > 25 ? s.slice(0, 25) + '…' : s);
+    const items = [];
+    // Minimized run windows (🧬) first…
+    if (runSet) {
+      for (const runId of runSet) {
+        const run = this.workflowRuns && this.workflowRuns.get(runId);
+        const name = run ? run.workflowName || run.summary || runId : runId;
+        const statusCls = this._workflowStatusClass(run ? String(run.status || '') : '');
+        items.push(
+          `<div class="subagent-dropdown-item" onclick="event.stopPropagation(); app.restoreUltracodeRunFromTab('${escapeHtml(runId)}','${escapeHtml(sessionId)}')" title="Click to restore run">` +
+            `<span class="subagent-dropdown-status ${statusCls}"></span>` +
+            `<span class="ultracode-dd-icon">🧬</span>` +
+            `<span class="subagent-dropdown-name">${escapeHtml(trunc(name))}</span>` +
+            `<span class="subagent-dropdown-close" onclick="event.stopPropagation(); app.dismissMinimizedUltracodeRun('${escapeHtml(runId)}','${escapeHtml(sessionId)}')" title="Dismiss">&times;</span>` +
+            `</div>`
+        );
+      }
+    }
+    // …then minimized agent transcripts (📄).
+    if (agentMap) {
+      for (const [agentId, entry] of agentMap) {
+        const name = (entry && entry.label) || agentId;
+        items.push(
+          `<div class="subagent-dropdown-item" onclick="event.stopPropagation(); app.restoreUltracodeAgentFromTab('${escapeHtml(agentId)}','${escapeHtml(sessionId)}')" title="Click to restore transcript">` +
+            `<span class="subagent-dropdown-status"></span>` +
+            `<span class="ultracode-dd-icon">📄</span>` +
+            `<span class="subagent-dropdown-name">${escapeHtml(trunc(name))}</span>` +
+            `<span class="subagent-dropdown-close" onclick="event.stopPropagation(); app.dismissMinimizedUltracodeAgent('${escapeHtml(agentId)}','${escapeHtml(sessionId)}')" title="Dismiss">&times;</span>` +
+            `</div>`
+        );
+      }
+    }
+    const label = total === 1 ? 'ULTRA' : `ULTRA (${total})`;
+    return (
+      `<span class="tab-ultracode-badge" onmouseenter="app.showSubagentDropdown(this)" onmouseleave="app.scheduleHideSubagentDropdown(this)" onclick="event.stopPropagation(); app.pinSubagentDropdown(this);">` +
+      `<span class="subagent-label">${label}</span>` +
+      `<div class="subagent-dropdown" onmouseenter="app.cancelHideSubagentDropdown()" onmouseleave="app.scheduleHideSubagentDropdown(this.parentElement)">${items.join('')}</div>` +
+      `</span>`
+    );
+  },
+
+  /** Restore a minimized run from its tab badge: re-open the floating window. */
+  restoreUltracodeRunFromTab(runId, sessionId) {
+    this._ensureUltracodeWindowState();
+    this._removeMinimizedUltracodeRun(runId, sessionId);
+    this._fullRenderSessionTabs();
+    this.openUltracodeWindowForRun(runId);
+  },
+
+  /** Dismiss a minimized run from its tab badge (don't re-pop it). */
+  dismissMinimizedUltracodeRun(runId, sessionId) {
+    this._ensureUltracodeWindowState();
+    this._removeMinimizedUltracodeRun(runId, sessionId);
+    this.ultracodeWindowsClosed.add(runId);
+    this._fullRenderSessionTabs();
+    this.updateConnectionLines();
+  },
+
+  // ── Minimize an agent transcript window into its tab (same idiom as run windows) ──
+
+  /** Is this agent transcript currently minimized to a tab? */
+  _isUltracodeAgentMinimized(agentId) {
+    if (!this.minimizedUltracodeAgents) return false;
+    for (const map of this.minimizedUltracodeAgents.values()) {
+      if (map.has(agentId)) return true;
+    }
+    return false;
+  },
+
+  /** Look up a minimized agent's {runId,label} entry (across sessions). */
+  _getMinimizedUltracodeAgent(agentId) {
+    if (!this.minimizedUltracodeAgents) return null;
+    for (const map of this.minimizedUltracodeAgents.values()) {
+      if (map.has(agentId)) return map.get(agentId);
+    }
+    return null;
+  },
+
+  /** Drop an agent from minimized tracking (all sessions, or a specific one). */
+  _removeMinimizedUltracodeAgent(agentId, sessionId) {
+    if (!this.minimizedUltracodeAgents) return;
+    if (sessionId) {
+      const map = this.minimizedUltracodeAgents.get(sessionId);
+      if (map) {
+        map.delete(agentId);
+        if (!map.size) this.minimizedUltracodeAgents.delete(sessionId);
+      }
+      return;
+    }
+    for (const [sid, map] of this.minimizedUltracodeAgents) {
+      if (map.delete(agentId) && !map.size) this.minimizedUltracodeAgents.delete(sid);
+    }
+  },
+
+  /** Minimize an agent transcript window into the run's originating session tab. */
+  minimizeUltracodeAgentWindowToTab(agentId) {
+    this._ensureUltracodeWindowState();
+    const info = this.ultracodeAgentWindows.get(agentId);
+    if (!info) return;
+    const runId = info.runId;
+    const summary = runId && this.workflowRuns ? this.workflowRuns.get(runId) : null;
+    let parentSessionId = summary ? this._resolveUltracodeParentSession(summary) : null;
+    if (!parentSessionId && this.activeSessionId && this.sessions && this.sessions.has(this.activeSessionId)) {
+      parentSessionId = this.activeSessionId;
+    }
+    // No tab to fly into → plain close rather than orphan it.
+    if (!parentSessionId) {
+      this.closeUltracodeAgentWindow(agentId);
+      return;
+    }
+    const labelEl = info.element.querySelector('.uw-name');
+    const label = labelEl ? labelEl.textContent : agentId;
+    if (!this.minimizedUltracodeAgents.has(parentSessionId))
+      this.minimizedUltracodeAgents.set(parentSessionId, new Map());
+    this.minimizedUltracodeAgents.get(parentSessionId).set(agentId, { runId, label });
+
+    const element = info.element;
+    const dragListeners = info.dragListeners;
+    this._animateUltracodeWindowToTab(element, parentSessionId, () => {
+      this._teardownUltracodeDrag(dragListeners);
+      if (element) element.remove();
+      this.ultracodeAgentWindows.delete(agentId);
+      this._fullRenderSessionTabs();
+      this.updateConnectionLines();
+    });
+  },
+
+  /** Restore a minimized agent transcript from its tab badge: re-open its window. */
+  restoreUltracodeAgentFromTab(agentId, sessionId) {
+    this._ensureUltracodeWindowState();
+    const entry = this._getMinimizedUltracodeAgent(agentId);
+    const runId = entry ? entry.runId : null;
+    this._removeMinimizedUltracodeAgent(agentId, sessionId);
+    this._fullRenderSessionTabs();
+    this.openUltracodeAgentWindow(agentId, runId);
+  },
+
+  /** Dismiss a minimized agent transcript from its tab badge. */
+  dismissMinimizedUltracodeAgent(agentId, sessionId) {
+    this._ensureUltracodeWindowState();
+    this._removeMinimizedUltracodeAgent(agentId, sessionId);
+    this._fullRenderSessionTabs();
+    this.updateConnectionLines();
+  },
+
+  /** Remove a floating window. `userInitiated` records a dismissal so it won't re-pop. */
+  closeUltracodeWindow(runId, userInitiated) {
+    this._ensureUltracodeWindowState();
+    const pending = this.ultracodeWindowCloseTimers.get(runId);
+    if (pending) {
+      clearTimeout(pending);
+      this.ultracodeWindowCloseTimers.delete(runId);
+    }
+    const data = this.ultracodeWindows.get(runId);
+    if (userInitiated) this.ultracodeWindowsClosed.add(runId);
+    if (!data) return;
+    this._teardownUltracodeDrag(data.dragListeners);
+    data.element.remove();
+    this.ultracodeWindows.delete(runId);
+    this.updateConnectionLines();
+  },
+
+  /** Detach the document-level drag listeners returned by makeWindowDraggable. */
+  _teardownUltracodeDrag(dl) {
+    if (!dl) return;
+    document.removeEventListener('mousemove', dl.move);
+    document.removeEventListener('mouseup', dl.up);
+    if (dl.touchMove) {
+      document.removeEventListener('touchmove', dl.touchMove);
+      document.removeEventListener('touchend', dl.up);
+      document.removeEventListener('touchcancel', dl.up);
+    }
+    if (dl.handle) {
+      dl.handle.removeEventListener('mousedown', dl.handleMouseDown);
+      dl.handle.removeEventListener('touchstart', dl.handleTouchStart);
+    }
+  },
+
+  // ── Agent-transcript windows ────────────────────────────────────────────────
+  // Clicking an agent card (in a run window OR the dock panel) opens the agent's
+  // live transcript as its OWN in-page floating window, line-tied to its parent run
+  // window (or the run's session tab when that window is closed). Replaces the old
+  // detached `window.open` browser popup so the transcript stays inside the same
+  // draggable, connector-line floating-window system as the run windows.
+
+  /** Open (or focus) the floating transcript window for a workflow agent. */
+  async openUltracodeAgentWindow(agentId, runId) {
+    this._ensureUltracodeWindowState();
+    if (!agentId) return;
+    this._removeMinimizedUltracodeAgent(agentId); // an explicit open overrides a past minimize
+    const existing = this.ultracodeAgentWindows.get(agentId);
+    if (existing && existing.element) {
+      // Already open — bring to front and refresh transcript.
+      existing.element.style.zIndex = ++this.ultracodeWindowZIndex;
+      this.updateConnectionLines();
+    } else if (!this.createUltracodeAgentWindow(agentId, runId)) {
+      return;
+    }
+    // Body shows a loading state until the fetch lands (re-fetch on focus too, so a
+    // still-running agent's transcript grows as you re-click).
+    const data = this._fetchWorkflowAgentTranscript ? await this._fetchWorkflowAgentTranscript(agentId) : null;
+    this.renderUltracodeAgentWindowContent(agentId, data);
+  },
+
+  /** Build and mount the floating agent-transcript window shell near its parent. */
+  createUltracodeAgentWindow(agentId, runId) {
+    this._ensureUltracodeWindowState();
+    if (this.ultracodeAgentWindows.has(agentId)) return this.ultracodeAgentWindows.get(agentId).element;
+
+    const label = this._ultracodeAgentLabel(agentId, runId) || agentId;
+    const win = document.createElement('div');
+    win.className = 'ultracode-window ultracode-agent-window spawning';
+    win.id = `ultracode-agent-window-${agentId}`;
+    win.style.zIndex = ++this.ultracodeWindowZIndex;
+    win.innerHTML = `
+      <div class="ultracode-window-header">
+        <div class="ultracode-window-title" title="${escapeHtml(label)} — transcript">
+          <span class="icon">📄</span>
+          <span class="uw-name">${escapeHtml(label)}</span>
+        </div>
+        <div class="ultracode-window-actions">
+          <button class="uw-min" type="button" title="Minimize to tab">─</button>
+          <button class="uw-close" type="button" title="Close">&times;</button>
+        </div>
+      </div>
+      <div class="ultracode-window-body">
+        <div class="subagent-empty">Loading transcript…</div>
+      </div>
+    `;
+
+    // Position: offset from the parent run window if it's open, else cascade.
+    const parentWin = runId ? this.ultracodeWindows.get(runId) : null;
+    if (parentWin && parentWin.element) {
+      const r = parentWin.element.getBoundingClientRect();
+      win.style.left = `${Math.max(8, Math.min(r.left + 40, window.innerWidth - 472))}px`;
+      win.style.top = `${Math.max(8, Math.min(r.top + 40, window.innerHeight - 160))}px`;
+    } else {
+      const n = this.ultracodeAgentWindows.size;
+      win.style.left = `${Math.min(140 + n * 28, Math.max(8, window.innerWidth - 472))}px`;
+      win.style.top = `${110 + n * 28}px`;
+    }
+
+    document.body.appendChild(win);
+    requestAnimationFrame(() => win.classList.remove('spawning'));
+
+    const header = win.querySelector('.ultracode-window-header');
+    const dragListeners = this.makeWindowDraggable(win, header);
+    win.querySelector('.uw-min').addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.minimizeUltracodeAgentWindowToTab(agentId);
+    });
+    win.querySelector('.uw-close').addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.closeUltracodeAgentWindow(agentId);
+    });
+
+    this.ultracodeAgentWindows.set(agentId, { element: win, runId, dragListeners });
+    this.updateConnectionLines();
+    return win;
+  },
+
+  /** Resolve a human label for an agent from the run's fetched detail.agents[]. */
+  _ultracodeAgentLabel(agentId, runId) {
+    const detail = this.workflowRunDetails && runId ? this.workflowRunDetails.get(runId) : null;
+    const agents = detail && Array.isArray(detail.agents) ? detail.agents : null;
+    if (agents) {
+      const found = agents.find((a) => a.agentId === agentId);
+      if (found && found.label) return found.label;
+    }
+    return null;
+  },
+
+  /** Fill an agent window's body with the fetched transcript (or a friendly empty state). */
+  renderUltracodeAgentWindowContent(agentId, data) {
+    const info = this.ultracodeAgentWindows.get(agentId);
+    if (!info || !info.element) return;
+    const body = info.element.querySelector('.ultracode-window-body');
+    if (!body) return;
+    if (!data || !data.formatted || !data.entryCount) {
+      body.innerHTML =
+        '<div class="subagent-empty">No transcript available yet — the agent may be queued, aged out of tracking, or subagent tracking is disabled.</div>';
+      return;
+    }
+    const text = escapeHtml(data.formatted.join('\n'));
+    body.innerHTML = `<div class="uw-summary">${data.entryCount} entries</div><pre class="uw-transcript">${text}</pre>`;
+  },
+
+  /** Close one floating agent-transcript window. */
+  closeUltracodeAgentWindow(agentId) {
+    this._ensureUltracodeWindowState();
+    const info = this.ultracodeAgentWindows.get(agentId);
+    if (!info) return;
+    this._teardownUltracodeDrag(info.dragListeners);
+    if (info.element) info.element.remove();
+    this.ultracodeAgentWindows.delete(agentId);
+    this.updateConnectionLines();
+  },
+
+  /** Tear down every floating window (called on SSE reconnect; keeps user dismissals). */
+  removeAllUltracodeWindows() {
+    this._ensureUltracodeWindowState();
+    const hadMinimized = this.minimizedUltracodeRuns.size > 0 || this.minimizedUltracodeAgents.size > 0;
+    const had = this.ultracodeWindows.size > 0 || this.ultracodeAgentWindows.size > 0;
+    for (const [, data] of this.ultracodeWindows) {
+      this._teardownUltracodeDrag(data.dragListeners);
+      if (data.element) data.element.remove();
+    }
+    this.ultracodeWindows.clear();
+    for (const [, info] of this.ultracodeAgentWindows) {
+      this._teardownUltracodeDrag(info.dragListeners);
+      if (info.element) info.element.remove();
+    }
+    this.ultracodeAgentWindows.clear();
+    for (const t of this.ultracodeWindowCloseTimers.values()) clearTimeout(t);
+    this.ultracodeWindowCloseTimers.clear();
+    this.minimizedUltracodeRuns.clear();
+    this.minimizedUltracodeAgents.clear();
+    // Redraw so the now-orphaned connector lines are cleared from the shared SVG.
+    if (had) this.updateConnectionLines();
+    // Drop any now-stale tab badges.
+    if (hadMinimized) this.renderSessionTabs();
+  },
+
+  /** When the feature is toggled on, pop windows for any currently-active runs. */
+  syncAllUltracodeFloatingWindows() {
+    this._ensureUltracodeWindowState();
+    if (!this._ultracodeFloatingEnabled()) {
+      this.removeAllUltracodeWindows();
+      return;
+    }
+    if (!this.workflowRuns) return;
+    for (const run of this.workflowRuns.values()) {
+      this._syncUltracodeFloatingWindow(run, { fromSeed: true });
+    }
+  },
+
+  /** Refresh a floating window's header + body from the latest summary/detail. */
+  renderUltracodeWindowContent(runId) {
+    const data = this.ultracodeWindows.get(runId);
+    if (!data) return;
+    const summary = this.workflowRuns && this.workflowRuns.get(runId);
+    const detail = this.workflowRunDetails && this.workflowRunDetails.get(runId);
+    // Summary is the freshest run-level info (every SSE tick); detail supplies agents[]
+    // but is fetched less often. Merge so a completed summary isn't masked by stale detail.
+    const run = summary && detail ? { ...detail, ...summary, agents: detail.agents } : detail || summary;
+    if (!run) return;
+
+    const nameEl = data.element.querySelector('.uw-name');
+    if (nameEl) nameEl.textContent = run.workflowName || run.summary || runId;
+
+    const statusEl = data.element.querySelector('.uw-status');
+    if (statusEl) {
+      const finished = !this._isWorkflowRunActive(run);
+      const label = run.status ? String(run.status) : finished ? '—' : 'running';
+      const clsKey = run.status ? run.status : finished ? '' : 'running';
+      statusEl.textContent = label;
+      statusEl.className = 'uw-status ultracode-status ' + this._workflowStatusClass(clsKey);
+    }
+
+    const body = data.element.querySelector('.ultracode-window-body');
+    if (body) body.innerHTML = this._ultracodeWindowBodyHtml(run);
+  },
+
+  /** Compact body: a stats line + agent cards grouped by phase (reuses panel helpers). */
+  _ultracodeWindowBodyHtml(run) {
+    const phases = Array.isArray(run.phases) ? run.phases : [];
+    const agents = Array.isArray(run.agents) ? run.agents : null;
+    const agentCount = run.agentCount ?? (agents ? agents.length : 0);
+    const head = `<div class="uw-summary">${this._fmtNum(run.totalTokens)} tok · ${run.totalToolCalls ?? 0} tools · ${agentCount} agents</div>`;
+
+    if (!agents) {
+      // Summary-only (detail not fetched yet): show phase chips as a teaser.
+      if (phases.length) {
+        const chips = phases
+          .map(
+            (p) =>
+              `<span class="ultracode-phase-chip" title="${escapeHtml(p.detail || '')}">${escapeHtml(p.title || '')}</span>`
+          )
+          .join('');
+        return (
+          head + `<div class="ultracode-phase-list">${chips}</div><div class="subagent-empty">Loading agents…</div>`
+        );
+      }
+      return head + '<div class="subagent-empty">Loading agents…</div>';
+    }
+    if (!agents.length) return head + '<div class="subagent-empty">No agents yet</div>';
+
+    const groups = new Map();
+    agents.forEach((a) => {
+      const key = a.phaseIndex || 0;
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push(a);
+    });
+    const orderedKeys = Array.from(groups.keys()).sort((a, b) => a - b);
+    const grid = orderedKeys
+      .map((key) => {
+        const group = groups.get(key);
+        const title = (phases[key - 1] && phases[key - 1].title) || `Phase ${key}`;
+        const tok = group.reduce((s, a) => s + (a.tokens || 0), 0);
+        const tools = group.reduce((s, a) => s + (a.toolCalls || 0), 0);
+        const header =
+          `<div class="ultracode-phase-header"><span>${escapeHtml(title)}</span>` +
+          `<span class="ultracode-phase-sub">${this._fmtNum(tok)} tok · ${tools} tools</span></div>`;
+        return header + group.map((a) => this._workflowAgentCardHtml(a, run.runId)).join('');
+      })
+      .join('');
+    return head + grid;
+  },
+
+  /**
+   * Append ultracode-window → parent-tab connector lines into the shared SVG.
+   * Invoked at the tail of `_updateConnectionLinesImmediate` (subagent-windows.js),
+   * so it shares that pass's batched read/write discipline. `rects` is the tab-rect
+   * cache already populated for subagent lines — reuse it, fill any gaps.
+   */
+  _appendUltracodeConnectionLines(svg, rects) {
+    this._ensureUltracodeWindowState();
+    if (!svg || !this.ultracodeWindows.size) return;
+    if (!rects) rects = new Map();
+
+    // PHASE 1: layout reads (resolve parents, batch getBoundingClientRect).
+    const winList = [];
+    for (const [runId, data] of this.ultracodeWindows) {
+      if (!data.element) continue;
+      if (!data.parentSessionId) {
+        const summary = this.workflowRuns && this.workflowRuns.get(runId);
+        if (summary) data.parentSessionId = this._resolveUltracodeParentSession(summary);
+      }
+      const parentSessionId = data.parentSessionId;
+      if (!parentSessionId) continue;
+      const tabKey = 'tab:' + parentSessionId;
+      if (!rects.has(tabKey)) {
+        const tab = document.querySelector(`.session-tab[data-id="${parentSessionId}"]`);
+        if (tab) rects.set(tabKey, tab.getBoundingClientRect());
+      }
+      winList.push({ runId, parentSessionId, winRect: data.element.getBoundingClientRect() });
+    }
+
+    // PHASE 2: writes (curve from tab bottom-center to window top-center).
+    for (const { runId, parentSessionId, winRect } of winList) {
+      const tabRect = rects.get('tab:' + parentSessionId);
+      if (!tabRect) continue;
+      const x1 = tabRect.left + tabRect.width / 2;
+      const y1 = tabRect.bottom;
+      const x2 = winRect.left + winRect.width / 2;
+      const y2 = winRect.top;
+      const midY = (y1 + y2) / 2;
+      const path = `M ${x1} ${y1} C ${x1} ${midY}, ${x2} ${midY}, ${x2} ${y2}`;
+      const line = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+      line.setAttribute('d', path);
+      line.setAttribute('class', 'connection-line ultracode-connection');
+      line.setAttribute('data-run-id', runId);
+      line.setAttribute('data-parent-tab', parentSessionId);
+      svg.appendChild(line);
+    }
+  },
+
+  /**
+   * Append agent-window → parent connector lines into the shared SVG. Parent is the
+   * agent's run floating window when open, else the run's session tab. Called right
+   * after `_appendUltracodeConnectionLines` so it shares the same batched pass + the
+   * tab-rect cache.
+   */
+  _appendUltracodeAgentConnectionLines(svg, rects) {
+    this._ensureUltracodeWindowState();
+    if (!svg || !this.ultracodeAgentWindows.size) return;
+    if (!rects) rects = new Map();
+
+    for (const [agentId, info] of this.ultracodeAgentWindows) {
+      if (!info.element) continue;
+      const winRect = info.element.getBoundingClientRect();
+      // Anchor: parent run window bottom-center if open, else the run's tab.
+      let px, py;
+      const runWin = info.runId ? this.ultracodeWindows.get(info.runId) : null;
+      if (runWin && runWin.element) {
+        const pr = runWin.element.getBoundingClientRect();
+        px = pr.left + pr.width / 2;
+        py = pr.bottom;
+      } else {
+        const summary = info.runId && this.workflowRuns ? this.workflowRuns.get(info.runId) : null;
+        const parentSessionId = summary ? this._resolveUltracodeParentSession(summary) : null;
+        if (!parentSessionId) continue;
+        const tabKey = 'tab:' + parentSessionId;
+        if (!rects.has(tabKey)) {
+          const tab = document.querySelector(`.session-tab[data-id="${parentSessionId}"]`);
+          if (tab) rects.set(tabKey, tab.getBoundingClientRect());
+        }
+        const tabRect = rects.get(tabKey);
+        if (!tabRect) continue;
+        px = tabRect.left + tabRect.width / 2;
+        py = tabRect.bottom;
+      }
+      const x2 = winRect.left + winRect.width / 2;
+      const y2 = winRect.top;
+      const midY = (py + y2) / 2;
+      const path = `M ${px} ${py} C ${px} ${midY}, ${x2} ${midY}, ${x2} ${y2}`;
+      const line = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+      line.setAttribute('d', path);
+      line.setAttribute('class', 'connection-line ultracode-connection ultracode-agent-connection');
+      line.setAttribute('data-agent-id', agentId);
+      svg.appendChild(line);
+    }
+  },
+});

src/web/routes/file-routes.ts

@@ -511,49 +511,73 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & Even
     try {
       const stat = await fs.stat(resolvedPath);
 
-      // Check if it's a binary/media file
+      // Classify by extension. Known media types render with a dedicated player;
+      // other known-binary types are flagged so the client offers a download
+      // affordance instead of trying to decode the bytes as text. Matches the
+      // breadth of formats the attachments viewer renders (image/audio/video/pdf)
+      // so the file viewer can open the same files.
       const ext = filePath.split('.').pop()?.toLowerCase() || '';
-      const binaryExts = new Set([
-        'png',
-        'jpg',
-        'jpeg',
-        'gif',
-        'webp',
-        'ico',
-        'svg',
-        'bmp',
-        'mp4',
-        'webm',
-        'mov',
-        'avi',
-        'mp3',
-        'wav',
-        'ogg',
+      const imageExts = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp', 'ico']);
+      const videoExts = new Set(['mp4', 'webm', 'mov', 'm4v', 'ogv']);
+      const audioExts = new Set(['mp3', 'wav', 'ogg', 'oga', 'm4a', 'aac', 'flac', 'opus']);
+      const otherBinaryExts = new Set([
         'pdf',
         'zip',
         'tar',
         'gz',
+        'bz2',
+        'xz',
+        '7z',
+        'rar',
         'exe',
         'dll',
         'so',
+        'dylib',
+        'bin',
+        'wasm',
+        'class',
+        'o',
+        'a',
         'woff',
         'woff2',
         'ttf',
         'eot',
+        'otf',
+        'xlsx',
+        'xls',
+        'doc',
+        'docx',
+        'ppt',
+        'pptx',
+        'odt',
+        'ods',
+        'odp',
+        'avi',
+        'mkv',
+        'wmv',
+        'flv',
       ]);
-      const imageExts = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp', 'ico']);
-      const videoExts = new Set(['mp4', 'webm', 'mov', 'avi']);
 
-      if (raw === 'true' || binaryExts.has(ext)) {
-        // Return metadata for binary files
+      const mediaType = imageExts.has(ext)
+        ? 'image'
+        : videoExts.has(ext)
+          ? 'video'
+          : audioExts.has(ext)
+            ? 'audio'
+            : null;
+
+      const fileRawUrl = `/api/sessions/${id}/file-raw?path=${encodeURIComponent(filePath)}`;
+
+      if (raw === 'true' || mediaType || otherBinaryExts.has(ext)) {
+        // Return metadata for media/binary files (no text body)
         return {
           success: true,
           data: {
             path: filePath,
             size: stat.size,
-            type: imageExts.has(ext) ? 'image' : videoExts.has(ext) ? 'video' : 'binary',
+            type: mediaType ?? 'binary',
             extension: ext,
-            url: `/api/sessions/${id}/file-raw?path=${encodeURIComponent(filePath)}`,
+            url: fileRawUrl,
           },
         };
       }
@@ -567,10 +591,39 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & Even
         );
       }
 
+      // Read as raw bytes so we can sniff for binary content before decoding. An
+      // unrecognized extension (none at all, or a format not listed above) that
+      // is actually binary would otherwise be dumped to the viewer as UTF-8
+      // mojibake; a NUL byte in the first 8KB is a reliable binary signal that
+      // (unlike a static extension list) catches arbitrary binary formats.
+      const fileBuffer = await fs.readFile(resolvedPath);
+      const buf = Buffer.isBuffer(fileBuffer) ? fileBuffer : Buffer.from(String(fileBuffer));
+      const sniffLength = Math.min(buf.length, 8192);
+      let looksBinary = false;
+      for (let i = 0; i < sniffLength; i++) {
+        if (buf[i] === 0) {
+          looksBinary = true;
+          break;
+        }
+      }
+
+      if (looksBinary) {
+        return {
+          success: true,
+          data: {
+            path: filePath,
+            size: stat.size,
+            type: 'binary',
+            extension: ext,
+            url: fileRawUrl,
+          },
+        };
+      }
+
       // Read text file with line limit (bounded to prevent DoS)
       const MAX_LINES_LIMIT = 10000;
       const maxLines = Math.min(parseInt(lines || '500', 10) || 500, MAX_LINES_LIMIT);
-      const content = await fs.readFile(resolvedPath, 'utf-8');
+      const content = buf.toString('utf-8');
       const allLines = content.split('\n');
       const truncatedContent = allLines.length > maxLines;
       const displayContent = truncatedContent ? allLines.slice(0, maxLines).join('\n') : content;
@@ -638,9 +691,16 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & Even
         mp4: 'video/mp4',
         webm: 'video/webm',
         mov: 'video/quicktime',
+        m4v: 'video/mp4',
+        ogv: 'video/ogg',
         mp3: 'audio/mpeg',
         wav: 'audio/wav',
         ogg: 'audio/ogg',
+        oga: 'audio/ogg',
+        opus: 'audio/ogg',
+        m4a: 'audio/mp4',
+        aac: 'audio/aac',
+        flac: 'audio/flac',
         pdf: 'application/pdf',
         json: 'application/json',
       };

src/web/routes/session-routes.ts

@@ -18,7 +18,7 @@ import {
   type ApiResponse,
   type SessionColor,
 } from '../../types.js';
-import { Session } from '../../session.js';
+import { Session, isAltScreenStripMode } from '../../session.js';
 import { SseEvent } from '../sse-events.js';
 import {
   CreateSessionSchema,
@@ -45,7 +45,13 @@ import {
   validatePathWithinBase,
 } from '../route-helpers.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
-import { writeHooksConfig, updateCaseModel, stripCaseEnvKeys, applyStatusLineConfig } from '../../hooks-config.js';
+import {
+  writeHooksConfig,
+  updateCaseModel,
+  stripCaseEnvKeys,
+  applyStatusLineConfig,
+  refreshStaleHookSecret,
+} from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
 import { imageWatcher } from '../../image-watcher.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
@@ -73,12 +79,13 @@ const LEADING_WHITESPACE_PATTERN = /^[\s\r\n]+/;
  *   (1049 also saves cursor and clears the alt buffer).
  * - CSI 3 J = erase saved lines (scrollback).
  *
- * Codex emits `\x1b[?1049h` and clear-scrollback sequences during startup and
- * on repaint. xterm.js obeys them by switching to the alt buffer (no native
- * scrollback) and wiping saved lines, so the user's conversation history
- * disappears on every tab switch / pane refresh. Stripping these from the
- * replayed byte stream keeps everything in the main buffer with scrollback
- * intact. Mirrors the live-stream strip in Session._handleTerminalOutput.
+ * Codex AND Claude Code emit `\x1b[?1049h` and clear-scrollback sequences (the
+ * latter intermittently, e.g. full-screen pickers/dialogs). xterm.js obeys them
+ * by switching to the alt buffer (no native scrollback) and wiping saved lines,
+ * so the user's conversation history disappears on every tab switch / pane
+ * refresh (and scroll-up breaks live). Stripping these from the replayed byte
+ * stream keeps everything in the main buffer with scrollback intact. Mirrors the
+ * live-stream strip in Session._handleTerminalOutput (isAltScreenStripMode).
  */
 // eslint-disable-next-line no-control-regex
 const ALT_SCREEN_TOGGLE_PATTERN = /\x1b\[\?(?:47|1047|1049)[hl]/g;
@@ -312,6 +319,13 @@ export function registerSessionRoutes(
       await applyStatusLineConfig(workingDir, true);
     }
 
+    // COD-91 self-heal: refresh a pre-secret hooks block in an existing case so the now
+    // unconditional hook-secret gate keeps accepting its hook events. No-op for fresh
+    // cases (writeHooksConfig already wrote the secret) and for non-Codeman/absent hooks.
+    if ((body.mode ?? 'claude') === 'claude') {
+      await refreshStaleHookSecret(workingDir).catch(() => {});
+    }
+
     // Check OpenCode availability if requested
     if (body.mode === 'opencode') {
       const { isOpenCodeAvailable } = await import('../../utils/opencode-cli-resolver.js');
@@ -732,14 +746,10 @@ export function registerSessionRoutes(
 
   app.post('/api/sessions/:id/resize', async (req) => {
     const { id } = req.params as { id: string };
-    const { cols, rows, viewportType } = parseBody(ResizeSchema, req.body);
+    const { cols, rows, viewportType, force } = parseBody(ResizeSchema, req.body);
     const session = findSessionOrFail(ctx, id);
 
-    if (viewportType) {
-      session.resize(cols, rows, { viewportType });
-    } else {
-      session.resize(cols, rows);
-    }
+    session.resize(cols, rows, { viewportType, force });
     return {};
   });
 
@@ -976,10 +986,11 @@ export function registerSessionRoutes(
     // the terminal appears empty when switching tabs.
     let strippedBuffer = stripInkRedrawBloat(rawBuffer);
 
-    // Strip alt-screen toggles and scrollback-erase from codex byte streams.
-    // xterm.js obeys them by switching to its scrollback-less alt buffer and
-    // wiping saved lines, so conversation history disappears on tab switch.
-    if (session.mode === 'codex') {
+    // Strip alt-screen toggles and scrollback-erase from Codex/Claude byte
+    // streams. xterm.js obeys them by switching to its scrollback-less alt
+    // buffer and wiping saved lines, so conversation history disappears on tab
+    // switch. Same gate as the live-stream strip in session.ts.
+    if (isAltScreenStripMode(session.mode)) {
       strippedBuffer = strippedBuffer
         .replace(ALT_SCREEN_TOGGLE_PATTERN, '')
         .replace(ERASE_SCROLLBACK_PATTERN, '')
@@ -1279,6 +1290,11 @@ export function registerSessionRoutes(
       } catch (err) {
         return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to create case: ${getErrorMessage(err)}`);
       }
+    } else if (mode !== 'opencode') {
+      // COD-91 self-heal for an EXISTING case: refresh a pre-secret hooks block so the
+      // now-unconditional hook-secret gate keeps accepting its hook events. No-op when
+      // the hooks aren't ours or already carry the secret.
+      await refreshStaleHookSecret(casePath).catch(() => {});
     }
 
     // Strip stale disk entries for keys this request is actively setting (Claude only —

src/web/routes/system-routes.ts

@@ -26,6 +26,7 @@ import {
 } from '../schemas.js';
 import { subagentWatcher } from '../../subagent-watcher.js';
 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 {
@@ -504,20 +505,34 @@ export function registerSystemRoutes(
     // control = effectively RCE) to a public *.trycloudflare.com URL. Because the
     // tunnel binds to loopback, server.ts's non-loopback bind guard never trips, and
     // with no CODEMAN_PASSWORD the auth middleware is inactive — so the tunnel URL is
-    // unauthenticated. Refuse to start a tunnel unless auth is configured OR the
-    // operator has acknowledged unauthenticated-network exposure. A public tunnel is
-    // higher-stakes than a LAN bind, so this is REFUSE (vs the bind guard's warn).
+    // unauthenticated. Refuse to start a tunnel unless auth is configured OR exposure
+    // is acknowledged: either the CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK env var, or an
+    // explicit per-request `acknowledgeUnauthTunnel:true` (the UI sends this after a
+    // confirm dialog). This keeps curl/API/CLI callers protected by default while
+    // letting an operator opt in from the browser without setting the env var.
     // Guard runs BEFORE persisting so a refused tunnelEnabled:true is not saved.
-    if (settings.tunnelEnabled === true && !ctx.tunnelManager.isRunning() && !isUnauthenticatedNetworkAcknowledged()) {
-      const msg =
-        'Refusing to start the Cloudflare tunnel without authentication: it would publish ' +
-        'full terminal control to a public URL with no password. Set CODEMAN_PASSWORD to ' +
-        'require login, or set CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1 to acknowledge an ' +
-        'unauthenticated public tunnel.';
-      throw Object.assign(new Error(msg), {
-        statusCode: 403,
-        body: createErrorResponse(ApiErrorCode.OPERATION_FAILED, msg),
-      });
+    if (settings.tunnelEnabled === true && !ctx.tunnelManager.isRunning()) {
+      const acknowledged = isUnauthenticatedNetworkAcknowledged() || settings.acknowledgeUnauthTunnel === true;
+      if (!acknowledged) {
+        const msg =
+          'Refusing to start the Cloudflare tunnel without authentication: it would publish ' +
+          'full terminal control to a public URL with no password. Set CODEMAN_PASSWORD to ' +
+          'require login, set CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1, or resend with ' +
+          'acknowledgeUnauthTunnel:true to acknowledge an unauthenticated public tunnel.';
+        throw Object.assign(new Error(msg), {
+          statusCode: 403,
+          body: createErrorResponse(ApiErrorCode.OPERATION_FAILED, msg),
+        });
+      }
+      // Loud warning whenever a public tunnel is started with no password — whether
+      // acknowledged via env var or the per-request UI confirmation.
+      if (!process.env.CODEMAN_PASSWORD) {
+        console.warn(
+          '⚠️  [tunnel] Starting an UNAUTHENTICATED public Cloudflare tunnel — no CODEMAN_PASSWORD set. ' +
+            'Anyone with the tunnel URL gets full terminal control (effectively RCE). ' +
+            'Set CODEMAN_PASSWORD to require login.'
+        );
+      }
     }
 
     try {
@@ -531,15 +546,24 @@ export function registerSystemRoutes(
       } catch {
         /* ignore */
       }
-      // statusLineTelemetry is an ACTION field (reconcile the plan-usage exporter),
-      // not a stored setting — strip it before persisting so settings.json stays clean.
-      const { statusLineTelemetry, ...settingsToStore } = settings;
+      // statusLineTelemetry and acknowledgeUnauthTunnel are ACTION fields (not stored
+      // settings) — strip them before persisting so settings.json stays clean.
+      const { statusLineTelemetry, acknowledgeUnauthTunnel, ...settingsToStore } = settings;
       const merged = { ...existing, ...settingsToStore };
       await fs.writeFile(SETTINGS_PATH, JSON.stringify(merged, null, 2));
 
       // Handle subagent tracking toggle dynamically
       toggleService((settings.subagentTrackingEnabled as boolean) ?? true, subagentWatcher, 'Subagent watcher');
 
+      // Handle ultracode/workflow run watcher toggle dynamically (default OFF).
+      // Either the docked panel OR the floating windows keep the watcher running.
+      toggleService(
+        ((settings.showUltracodeAgents as boolean) ?? false) ||
+          ((settings.ultracodeFloatingWindows as boolean) ?? false),
+        workflowRunWatcher,
+        'Workflow run watcher'
+      );
+
       // Handle image watcher toggle dynamically
       toggleService((settings.imageWatcherEnabled as boolean) ?? false, imageWatcher, 'Image watcher', () => {
         // Re-watch all active sessions that have image watcher enabled
@@ -691,6 +715,27 @@ export function registerSystemRoutes(
     }
   });
 
+  // ========== Workflow Run Monitoring (ultracode) ==========
+
+  // LEFT-pane list: lightweight run summaries (no agents[]).
+  app.get('/api/workflows', async (req) => {
+    const { minutes } = req.query as { minutes?: string };
+    const runs = minutes
+      ? workflowRunWatcher.getRecentRunSummaries(parseInt(minutes, 10))
+      : workflowRunWatcher.getAllRunSummaries();
+    return { success: true, data: runs };
+  });
+
+  // RIGHT-pane detail: full run incl. agents[] (tokens/toolCalls/state per agent).
+  app.get('/api/workflows/:runId', async (req) => {
+    const { runId } = req.params as { runId: string };
+    const run = workflowRunWatcher.getRun(runId);
+    if (!run) {
+      return createErrorResponse(ApiErrorCode.NOT_FOUND, `Workflow run ${runId} not found`);
+    }
+    return { success: true, data: run };
+  });
+
   // ========== Subagent Monitoring ==========
 
   app.get('/api/subagents', async (req) => {

src/web/routes/ws-routes.ts

@@ -23,7 +23,7 @@
  *     {"t":"r"}           — needs refresh (reload buffer)
  *   Client -> Server:
  *     {"t":"i","d":"..."} — input (keystroke or paste)
- *     {"t":"z","c":N,"r":N} — resize terminal
+ *     {"t":"z","c":N,"r":N,"f":bool} — resize terminal (f=true forces SIGWINCH even if dims unchanged)
  */
 
 import { FastifyInstance } from 'fastify';
@@ -146,11 +146,8 @@ export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort, getHost
             session.releaseDesktopSizing(sizingToken);
             holdsDesktopClaim = false;
           }
-          if (viewportType) {
-            session.resize(msg.c, msg.r, { viewportType });
-          } else {
-            session.resize(msg.c, msg.r);
-          }
+          const force = msg.f === true;
+          session.resize(msg.c, msg.r, { viewportType, force });
         }
       } catch {
         // Ignore malformed messages

src/web/schemas.ts

@@ -186,6 +186,7 @@ export const ResizeSchema = z.object({
   cols: z.number().int().min(1).max(500),
   rows: z.number().int().min(1).max(200),
   viewportType: z.enum(['mobile', 'tablet', 'desktop']).optional(),
+  force: z.boolean().optional(),
 });
 
 /**
@@ -348,8 +349,17 @@ export const SettingsUpdateSchema = z
     ralphTrackerEnabled: z.boolean().optional(),
     subagentTrackingEnabled: z.boolean().optional(),
     subagentActiveTabOnly: z.boolean().optional(),
+    /** Ultracode/Workflow run visualization (default OFF). Gates workflowRunWatcher + the master-detail tab. SYNCED. */
+    showUltracodeAgents: z.boolean().optional(),
+    /** Floating ultracode run windows w/ tab connector lines (default OFF). Also starts workflowRunWatcher. SYNCED. */
+    ultracodeFloatingWindows: z.boolean().optional(),
     imageWatcherEnabled: z.boolean().optional(),
     tunnelEnabled: z.boolean().optional(),
+    // Action field (NOT persisted): explicit per-request acknowledgment that the
+    // operator accepts exposing an UNAUTHENTICATED public tunnel (no CODEMAN_PASSWORD).
+    // Lets the UI enable a tunnel after a confirm dialog without the
+    // CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK env var. Stripped before persisting.
+    acknowledgeUnauthTunnel: z.boolean().optional(),
     tabTwoRows: z.boolean().optional(),
     agentTeamsEnabled: z.boolean().optional(),
     /** Model for new Claude sessions (e.g. "claude-fable-5[1m]", "opus[1m]"); takes precedence over opusContext1mEnabled */
@@ -375,6 +385,7 @@ export const SettingsUpdateSchema = z
     // (client-side), but telemetry COLLECTION is server-side, so the per-device
     // toggle signals it out-of-band here rather than via showPlanUsageLimits.
     statusLineTelemetry: z.boolean().optional(),
+    showRedrawButton: z.boolean().optional(),
     // Input
     gestureControlEnabled: z.boolean().optional(),
     // Claude CLI settings

src/web/server.ts

@@ -44,7 +44,7 @@ import { dataPath } from '../config/instance.js';
 import { getHookSecret } from '../config/hook-secret.js';
 import { EventEmitter } from 'node:events';
 import { Session, isExternalCliMode, type BackgroundTask } from '../session.js';
-import type { ClaudeMode, SessionAttachmentHistoryItem, SessionState } from '../types.js';
+import type { ClaudeMode, SessionAttachmentHistoryItem, SessionState, WorkflowRunInfo } from '../types.js';
 import { RespawnController, RespawnConfig } from '../respawn-controller.js';
 import type { TerminalMultiplexer } from '../mux-interface.js';
 import { createMultiplexer } from '../mux-factory.js';
@@ -60,6 +60,7 @@ import {
   type SubagentToolResult,
 } from '../subagent-watcher.js';
 import { imageWatcher } from '../image-watcher.js';
+import { workflowRunWatcher, summarizeRun } from '../workflow-run-watcher.js';
 import { attachmentRegistry, buildFileThumbnailRoute, registerExternalAttachment } from '../attachment-registry.js';
 import {
   buildDetectedAttachmentHistoryItem,
@@ -259,6 +260,11 @@ export class WebServer extends EventEmitter {
     attachmentDetected: (event: AttachmentDetectedEvent) => void;
     error: (error: Error, sessionId?: string) => void;
   } | null = null;
+  private workflowRunWatcherHandlers: {
+    discovered: (info: WorkflowRunInfo) => void;
+    updated: (info: WorkflowRunInfo) => void;
+    removed: (data: { runId: string }) => void;
+  } | null = null;
   private tunnelManager: TunnelManager = new TunnelManager();
   private authSessions: StaleExpirationMap<string, import('./ports/auth-port.js').AuthSessionRecord> | null = null;
   private authFailures: StaleExpirationMap<string, number> | null = null;
@@ -338,6 +344,7 @@ export class WebServer extends EventEmitter {
 
     // Set up subagent watcher listeners
     this.setupSubagentWatcherListeners();
+    this.setupWorkflowRunWatcherListeners();
 
     // Set up image watcher listeners
     this.setupImageWatcherListeners();
@@ -437,6 +444,31 @@ export class WebServer extends EventEmitter {
     }
   }
 
+  /**
+   * Bridge WorkflowRunWatcher events → SSE. Broadcasts run SUMMARIES (no agents[])
+   * to keep payloads small; the full agents[] is fetched per-run via
+   * GET /api/workflows/:runId when the user selects a run.
+   */
+  private setupWorkflowRunWatcherListeners(): void {
+    this.workflowRunWatcherHandlers = {
+      discovered: (info: WorkflowRunInfo) => this.broadcast(SseEvent.WorkflowRunDiscovered, summarizeRun(info)),
+      updated: (info: WorkflowRunInfo) => this.broadcast(SseEvent.WorkflowRunUpdated, summarizeRun(info)),
+      removed: (data: { runId: string }) => this.broadcast(SseEvent.WorkflowRunRemoved, data),
+    };
+    workflowRunWatcher.on('run_discovered', this.workflowRunWatcherHandlers.discovered);
+    workflowRunWatcher.on('run_updated', this.workflowRunWatcherHandlers.updated);
+    workflowRunWatcher.on('run_removed', this.workflowRunWatcherHandlers.removed);
+  }
+
+  private cleanupWorkflowRunWatcherListeners(): void {
+    if (this.workflowRunWatcherHandlers) {
+      workflowRunWatcher.off('run_discovered', this.workflowRunWatcherHandlers.discovered);
+      workflowRunWatcher.off('run_updated', this.workflowRunWatcherHandlers.updated);
+      workflowRunWatcher.off('run_removed', this.workflowRunWatcherHandlers.removed);
+      this.workflowRunWatcherHandlers = null;
+    }
+  }
+
   /**
    * Set up event listeners for image watcher.
    * Broadcasts image detection events to SSE clients for auto-popup.
@@ -630,7 +662,7 @@ export class WebServer extends EventEmitter {
     registerHostGuard(this.app, () => this.getHostPolicy());
 
     // Auth middleware (Basic Auth + session cookies + rate limiting)
-    const authState = registerAuthMiddleware(this.app, this.https, () => this.tunnelManager.isRunning());
+    const authState = registerAuthMiddleware(this.app, this.https);
     if (authState) {
       this.authSessions = authState.authSessions;
       this.authFailures = authState.authFailures;
@@ -1669,6 +1701,7 @@ export class WebServer extends EventEmitter {
       respawnStatus,
       globalStats: this.store.getAggregateStats(activeSessionTokens),
       subagents: subagentWatcher.getRecentSubagents(15), // 15 min to avoid stale agents
+      workflowRuns: workflowRunWatcher.getAllRunSummaries(), // ultracode run summaries (no agents[]) for the LEFT list
       timestamp: now,
       inputCjkForm: process.env.INPUT_CJK_FORM?.toUpperCase() === 'ON',
       planUsage: getLatestPlanUsage(), // last-known plan-usage telemetry, for the header chip on fresh load
@@ -1937,6 +1970,14 @@ export class WebServer extends EventEmitter {
       console.log('Subagent watcher disabled by user settings');
     }
 
+    // Start workflow run watcher for ultracode / Workflow run visualization (if enabled)
+    if (await this.isWorkflowAgentTrackingEnabled()) {
+      workflowRunWatcher.start();
+      console.log('Workflow run watcher started - monitoring ~/.claude/projects for ultracode run activity');
+    } else {
+      console.log('Workflow run watcher disabled by user settings (showUltracodeAgents off)');
+    }
+
     // Start image watcher for auto-popup of screenshots (if enabled)
     if (await this.isImageWatcherEnabled()) {
       imageWatcher.start();
@@ -1983,6 +2024,25 @@ export class WebServer extends EventEmitter {
     return true; // Default enabled
   }
 
+  /**
+   * Check if ultracode/workflow run tracking is enabled in settings (default: FALSE — opt-in).
+   * The watcher feeds BOTH the docked Ultracode Agents panel (`showUltracodeAgents`) and the
+   * floating run windows (`ultracodeFloatingWindows`), so either toggle starts it.
+   */
+  private async isWorkflowAgentTrackingEnabled(): Promise<boolean> {
+    const settingsPath = dataPath('settings.json');
+    try {
+      const content = await fs.readFile(settingsPath, 'utf-8');
+      const settings = JSON.parse(content);
+      return (settings.showUltracodeAgents ?? false) || (settings.ultracodeFloatingWindows ?? false);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+        console.error('Failed to read showUltracodeAgents setting:', err);
+      }
+    }
+    return false; // Default disabled (opt-in)
+  }
+
   /**
    * Check if image watcher is enabled in settings (default: false)
    */
@@ -2337,12 +2397,16 @@ export class WebServer extends EventEmitter {
 
     // Clean up watcher listeners to prevent memory leaks
     this.cleanupSubagentWatcherListeners();
+    this.cleanupWorkflowRunWatcherListeners();
     this.cleanupImageWatcherListeners();
     this.cleanupTeamWatcherListeners();
 
     // Stop subagent watcher
     subagentWatcher.stop();
 
+    // Stop workflow run watcher
+    workflowRunWatcher.stop();
+
     // Stop image watcher
     imageWatcher.stop();
 

src/web/sse-events.ts

@@ -15,6 +15,7 @@
  * - **Mux** (4): created, killed, died, statsUpdated
  * - **Respawn** (24): stateChanged, cycleStarted/Completed, step*, aiCheck*, planCheck*, timer*, log, ...
  * - **Subagents** (7): discovered, updated, tool_call, tool_result, progress, message, completed
+ * - **Workflow runs** (3): run_discovered, run_updated, run_removed (ultracode / Workflow tool)
  * - **Scheduled** (6): created, updated, completed, stopped, log, deleted
  * - **Teams** (4): created, updated, removed, taskUpdated
  * - **Transcript** (4): complete, plan_mode, tool_start, tool_end
@@ -215,6 +216,15 @@ export const SubagentMessage = 'subagent:message' as const;
 /** Subagent finished. */
 export const SubagentCompleted = 'subagent:completed' as const;
 
+// ─── Workflow Runs (ultracode / Workflow tool) ───────────────────────────────
+
+/** A workflow run was discovered (first time seen). Payload: WorkflowRunInfo. */
+export const WorkflowRunDiscovered = 'workflow:run_discovered' as const;
+/** A workflow run changed (agent state/token tick). Payload: WorkflowRunInfo. */
+export const WorkflowRunUpdated = 'workflow:run_updated' as const;
+/** A workflow run's file disappeared. Payload: { runId: string }. */
+export const WorkflowRunRemoved = 'workflow:run_removed' as const;
+
 // ─── Scheduled Runs ──────────────────────────────────────────────────────────
 
 /** Scheduled run created. */
@@ -446,6 +456,11 @@ export const SseEvent = {
   SubagentMessage,
   SubagentCompleted,
 
+  // Workflow runs (ultracode)
+  WorkflowRunDiscovered,
+  WorkflowRunUpdated,
+  WorkflowRunRemoved,
+
   // Scheduled runs
   ScheduledCreated,
   ScheduledUpdated,

src/workflow-run-watcher.ts

@@ -0,0 +1,888 @@
+/**
+ * @fileoverview Workflow (ultracode) Run Watcher
+ *
+ * Emits events powering the master-detail "working agents" view (tasks/phases on
+ * the LEFT, per-agent tokens/tool-calls on the RIGHT) AND the floating run
+ * windows, from TWO disk sources per run:
+ *
+ *   1. COMPLETION artifact — `…/workflows/wf_<id>.json`. The Workflow runtime
+ *      writes this with the FULL run state (phases, per-agent tokens/tool-calls,
+ *      result), but — as of the mid-2026 runtime — only when the run FINISHES
+ *      (always a terminal status). It is the authoritative, detailed record.
+ *   2. LIVE transcript dir — `…/subagents/workflows/wf_<id>/` (agent-*.jsonl +
+ *      journal.jsonl). This appears WHILE a run is in flight, before any
+ *      `wf_<id>.json` exists. From it we synthesize a minimal ACTIVE run
+ *      (status 'running', agent slots keyed by agentId, lastActivityAt from file
+ *      mtimes) so the floating window pops DURING the run instead of only after.
+ *
+ * Precedence: when a completion `wf_<id>.json` exists it ALWAYS supersedes the
+ * synthesized live record (same runId), so a finished run shows full detail and
+ * the normal finish→auto-close flow runs. Without source 2 the floating-window
+ * feature is dead for live runs (the completion file only lands at the end, so
+ * the watcher would never see a run while it is active).
+ *
+ * Still STANDALONE: it never imports from or touches subagent-watcher.ts. It
+ * independently reads the same `subagents/workflows/` tree subagent-watcher uses,
+ * but as a separate singleton with no shared mutable state.
+ *
+ * Discovery is dual: a periodic poll (catches new run dirs + removals) plus a
+ * per-dir chokidar watcher (live updates). A per-source mtime skip keeps the hot
+ * path cheap — the completion JSON / live dir is re-read only when its mtime moves.
+ *
+ * @module workflow-run-watcher
+ */
+
+import { EventEmitter } from 'node:events';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { watch as chokidarWatch, type FSWatcher as ChokidarWatcher } from 'chokidar';
+
+import type { WorkflowRunInfo, WorkflowRunSummary, WorkflowAgentInfo, WorkflowRunPhase } from './types/workflow-run.js';
+import { LRUMap } from './utils/lru-map.js';
+import {
+  WORKFLOW_RUN_POLL_INTERVAL_MS,
+  MAX_CACHED_WORKFLOW_RUNS,
+  WORKFLOW_RUN_RECENT_WINDOW_MIN,
+} from './config/workflow-config.js';
+
+const WORKFLOWS_SUBDIR = 'workflows';
+const SUBAGENTS_SUBDIR = 'subagents';
+const RUN_FILE_PREFIX = 'wf_';
+const RUN_FILE_SUFFIX = '.json';
+const LIVE_JOURNAL_FILE = 'journal.jsonl';
+const LIVE_AGENT_PREFIX = 'agent-';
+const LIVE_TRANSCRIPT_SUFFIX = '.jsonl';
+const SCRIPTS_SUBDIR = 'scripts';
+
+/** Hard caps on the largest per-agent strings so a 28-agent run stays compact. */
+const PROMPT_PREVIEW_MAX = 200;
+const RESULT_PREVIEW_MAX = 240;
+/** Cap a live script read so a runaway/huge embedded script can't blow memory. */
+const SCRIPT_READ_MAX_BYTES = 512 * 1024;
+/** LRU cap on cached per-agent transcript stats across all live runs. */
+const MAX_CACHED_AGENT_STATS = 2000;
+
+function truncate(value: string | undefined, max: number): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+
+/** First text from a transcript message's `content` (string or content-block array). */
+function extractMessageText(content: unknown): string | undefined {
+  if (typeof content === 'string') return content.trim() || undefined;
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block && typeof block === 'object' && (block as { type?: string }).type === 'text') {
+        const t = (block as { text?: string }).text;
+        if (typeof t === 'string' && t.trim()) return t.trim();
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Isolate the `meta = { … }` object literal from a workflow script so that later
+ * declarations (e.g. JSON-Schema objects with their own `description:`/`title:`
+ * fields, or prose containing `phases: [`) can't be mistaken for meta. Brace-matches
+ * naively — a `{`/`}` inside a string value can still confuse it, in which case we
+ * return undefined and the caller falls back to scanning the whole body. Best-effort.
+ */
+function extractMetaBlock(body: string): string | undefined {
+  const m = /(?:^|[^A-Za-z0-9_])(?:export\s+const|const|let|var)\s+meta\s*=\s*\{/.exec(body);
+  if (!m) return undefined;
+  const open = body.indexOf('{', m.index);
+  if (open < 0) return undefined;
+  let depth = 0;
+  for (let i = open; i < body.length; i++) {
+    if (body[i] === '{') depth++;
+    else if (body[i] === '}' && --depth === 0) return body.slice(open, i + 1);
+  }
+  return undefined; // unterminated (truncated script) — caller falls back to whole body
+}
+
+/**
+ * Best-effort extraction of a single/double-quoted `key: '...'` value from a workflow
+ * `meta` literal (the script is JS we must not eval). The key is anchored to a key
+ * position (`{`/`,`/whitespace before it) so e.g. `description` can't match the tail
+ * of `..._description`; pass the scoped meta block so later same-named schema fields
+ * can't win. Returns undefined on no match.
+ */
+function extractMetaString(body: string, key: string): string | undefined {
+  const re = new RegExp(`(?:^|[{,\\s])${key}\\s*:\\s*(['"])((?:\\\\.|(?!\\1).)*)\\1`);
+  const m = re.exec(body);
+  return m ? m[2].replace(/\\(['"\\`])/g, '$1') : undefined;
+}
+
+/** Best-effort `meta.phases: [{title, detail}, …]` extraction (pass the scoped meta block). */
+function extractMetaPhases(body: string): WorkflowRunPhase[] {
+  const keyMatch = /(?:^|[^A-Za-z0-9_])phases\s*:\s*\[/.exec(body);
+  if (!keyMatch) return [];
+  const open = body.indexOf('[', keyMatch.index);
+  if (open < 0) return [];
+  // Brace-match to the array's closing ] so nested arrays don't end it early.
+  let depth = 0;
+  let end = -1;
+  for (let i = open; i < body.length; i++) {
+    if (body[i] === '[') depth++;
+    else if (body[i] === ']' && --depth === 0) {
+      end = i;
+      break;
+    }
+  }
+  if (end < 0) return [];
+  const block = body.slice(open, end + 1);
+  const phases: WorkflowRunPhase[] = [];
+  const re = /title\s*:\s*(['"])((?:\\.|(?!\1).)*)\1(?:\s*,\s*detail\s*:\s*(['"])((?:\\.|(?!\3).)*)\3)?/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(block)) !== null && phases.length < 20) {
+    phases.push({
+      title: m[2].replace(/\\(['"\\`])/g, '$1'),
+      detail: (m[4] || '').replace(/\\(['"\\`])/g, '$1'),
+    });
+  }
+  return phases;
+}
+
+/** Drop the heavy `agents[]` for list/snapshot use. */
+export function summarizeRun(info: WorkflowRunInfo): WorkflowRunSummary {
+  const { agents: _agents, ...summary } = info;
+  void _agents;
+  return summary;
+}
+
+interface DiscoveredRun {
+  filePath: string;
+  projectHash: string;
+  sessionUuid: string;
+  runId: string;
+}
+
+/** An in-flight run discovered from its `subagents/workflows/wf_<id>/` transcript dir. */
+interface DiscoveredLiveRun {
+  dirPath: string;
+  projectHash: string;
+  sessionUuid: string;
+  runId: string;
+}
+
+/** Per-agent stats parsed from one `agent-<id>.jsonl` transcript (mtime-cached). */
+interface AgentTranscriptStats {
+  /** Tokens for the agent's LAST usage-bearing message (in+out+cache) ≈ the completion-JSON `tokens`. */
+  tokens: number;
+  /** Count of `tool_use` blocks across the transcript (matches the completion-JSON `toolCalls`). */
+  toolCalls: number;
+  /** Most-recent model id seen. */
+  model: string;
+  /** Name of the most-recent `tool_use` block. */
+  lastToolName?: string;
+  /** First user-message text, truncated — a hint of what the agent was asked. */
+  promptPreview?: string;
+}
+
+/** Workflow meta derived live from `workflows/scripts/<name>-<runId>.js`. */
+interface LiveWorkflowMeta {
+  workflowName?: string;
+  summary?: string;
+  phases: WorkflowRunPhase[];
+}
+
+/** A live agent file on disk (transcript and/or meta), keyed by its `<id>` stem. */
+interface LiveAgentFile {
+  agentId: string;
+  transcriptPath?: string;
+  transcriptMtime?: number;
+}
+
+/** A `workflowProgress[]` entry as it appears on disk (loosely typed for defensive parsing). */
+interface RawProgressEntry {
+  type?: string;
+  index?: number;
+  label?: string;
+  phaseIndex?: number;
+  phaseTitle?: string;
+  model?: string;
+  state?: string;
+  queuedAt?: number;
+  lastProgressAt?: number;
+  promptPreview?: string;
+  agentId?: string;
+  startedAt?: number;
+  attempt?: number;
+  tokens?: number;
+  toolCalls?: number;
+  lastToolName?: string;
+  lastToolSummary?: string;
+  durationMs?: number;
+  resultPreview?: string;
+}
+
+export class WorkflowRunWatcher extends EventEmitter {
+  private projectsDir: string;
+  private pollTimer: NodeJS.Timeout | null = null;
+  private _isRunning = false;
+
+  /** runId -> latest parsed run info (LRU-bounded). */
+  private runs = new LRUMap<string, WorkflowRunInfo>({ maxSize: MAX_CACHED_WORKFLOW_RUNS });
+  /** absolute run-file path -> last seen mtimeMs (skip unchanged files). */
+  private fileMtimes = new Map<string, number>();
+  /** runId -> absolute run-file path (for mtime cleanup on removal). */
+  private runIdToPath = new Map<string, string>();
+  /** absolute live transcript-dir path -> newest member mtimeMs (skip unchanged live runs). */
+  private liveDirMtimes = new Map<string, number>();
+  /** runId -> absolute live transcript-dir path (for mtime cleanup on removal). */
+  private runIdToLiveDir = new Map<string, string>();
+  /** transcript abs path -> { mtimeMs, stats }; re-parse a transcript only when its mtime moves. */
+  private agentStatCache = new LRUMap<string, { mtimeMs: number; stats: AgentTranscriptStats }>({
+    maxSize: MAX_CACHED_AGENT_STATS,
+  });
+  /** runId -> derived script meta (immutable per run; re-derived only until a name is found). */
+  private liveMetaCache = new Map<string, LiveWorkflowMeta>();
+  /** journal abs path -> { mtimeMs, parsed }; re-parse the journal only when it grows. */
+  private journalCache = new Map<
+    string,
+    { mtimeMs: number; parsed: { startedOrder: string[]; doneIds: Set<string> } }
+  >();
+  /** watched-dir absolute path -> chokidar watcher (workflows/ + subagents/workflows/). */
+  private dirWatchers = new Map<string, ChokidarWatcher>();
+
+  constructor(projectsDir?: string) {
+    super();
+    this.projectsDir = projectsDir || join(homedir(), '.claude', 'projects');
+    this.setMaxListeners(50);
+  }
+
+  // ========== Public API ==========
+
+  isRunning(): boolean {
+    return this._isRunning;
+  }
+
+  start(): void {
+    if (this._isRunning) return;
+    this._isRunning = true;
+    this.poll();
+    this.pollTimer = setInterval(() => this.poll(), WORKFLOW_RUN_POLL_INTERVAL_MS);
+  }
+
+  stop(): void {
+    this._isRunning = false;
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+    for (const watcher of this.dirWatchers.values()) {
+      watcher.close().catch(() => {}); // best-effort teardown
+    }
+    this.dirWatchers.clear();
+    this.runs.clear();
+    this.fileMtimes.clear();
+    this.runIdToPath.clear();
+    this.liveDirMtimes.clear();
+    this.runIdToLiveDir.clear();
+    this.agentStatCache.clear();
+    this.liveMetaCache.clear();
+    this.journalCache.clear();
+  }
+
+  /** All cached runs (no recency filter), most-recently-active first. */
+  getAllRuns(): WorkflowRunInfo[] {
+    return Array.from(this.runs.values()).sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+  }
+
+  /** Runs active within the last `minutes`, most-recently-active first. */
+  getRecentRuns(minutes: number = WORKFLOW_RUN_RECENT_WINDOW_MIN): WorkflowRunInfo[] {
+    const cutoff = Date.now() - minutes * 60_000;
+    return this.getAllRuns().filter((r) => r.lastActivityAt >= cutoff);
+  }
+
+  /**
+   * Lightweight summaries (no agents[]) of ALL cached runs, most-recently-active
+   * first. This is the LEFT-pane list + getLightState snapshot source: the cache
+   * is LRU-bounded (MAX_CACHED_WORKFLOW_RUNS), so it's already size-capped, and a
+   * run-browser should show past runs — NOT hide everything older than a window.
+   */
+  getAllRunSummaries(): WorkflowRunSummary[] {
+    return this.getAllRuns().map(summarizeRun);
+  }
+
+  /** Summaries filtered to the last `minutes` of activity (opt-in via ?minutes). */
+  getRecentRunSummaries(minutes: number = WORKFLOW_RUN_RECENT_WINDOW_MIN): WorkflowRunSummary[] {
+    return this.getRecentRuns(minutes).map(summarizeRun);
+  }
+
+  getRun(runId: string): WorkflowRunInfo | undefined {
+    return this.runs.get(runId);
+  }
+
+  getStats(): { runCount: number; running: number; agentCount: number } {
+    let running = 0;
+    let agentCount = 0;
+    for (const run of this.runs.values()) {
+      if (run.status === 'running') running++;
+      agentCount += run.agents.length;
+    }
+    return { runCount: this.runs.size, running, agentCount };
+  }
+
+  // ========== Private ==========
+
+  private poll(): void {
+    this.pollAsync().catch(() => {
+      // Filesystem may be transiently unavailable; the next poll retries.
+    });
+  }
+
+  private async pollAsync(): Promise<void> {
+    const { files, liveDirs, watchDirs } = await this.discover();
+
+    // Install a live watcher for each watched dir; tear down watchers for dirs that vanished.
+    for (const dir of watchDirs) this.ensureDirWatcher(dir);
+    for (const dir of Array.from(this.dirWatchers.keys())) {
+      if (!watchDirs.has(dir)) this.removeDirWatcher(dir);
+    }
+
+    const seenRunIds = new Set<string>();
+    const realRunIds = new Set<string>();
+    for (const file of files) {
+      seenRunIds.add(file.runId);
+      realRunIds.add(file.runId);
+      await this.maybeParse(file);
+    }
+
+    // In-flight runs: synthesize from the transcript tree ONLY while no completion
+    // wf_*.json exists yet — the real file (full detail + terminal status) supersedes.
+    for (const live of liveDirs) {
+      if (realRunIds.has(live.runId)) continue;
+      seenRunIds.add(live.runId);
+      await this.maybeParseLive(live);
+    }
+
+    // Removal by set-diff: a cached run discoverable from neither source.
+    for (const runId of Array.from(this.runs.keys())) {
+      if (!seenRunIds.has(runId)) {
+        this.runs.delete(runId);
+        const path = this.runIdToPath.get(runId);
+        if (path) this.fileMtimes.delete(path);
+        this.runIdToPath.delete(runId);
+        const liveDir = this.runIdToLiveDir.get(runId);
+        if (liveDir) {
+          this.liveDirMtimes.delete(liveDir);
+          // Drop cached transcript stats + journal parse under this run's live dir.
+          const prefix = liveDir.endsWith('/') ? liveDir : liveDir + '/';
+          for (const key of Array.from(this.agentStatCache.keys())) {
+            if (key.startsWith(prefix)) this.agentStatCache.delete(key);
+          }
+          for (const key of Array.from(this.journalCache.keys())) {
+            if (key.startsWith(prefix)) this.journalCache.delete(key);
+          }
+        }
+        this.liveMetaCache.delete(runId);
+        this.runIdToLiveDir.delete(runId);
+        this.emit('run_removed', { runId });
+      }
+    }
+  }
+
+  /**
+   * Walk projects/<projHash>/<sessionUuid>/ for both run sources:
+   *   - completion files: `workflows/wf_*.json`
+   *   - in-flight runs:   `subagents/workflows/wf_<id>/` (transcript dirs)
+   * Returns the dirs to chokidar-watch (so a new run/file is caught sub-poll).
+   */
+  private async discover(): Promise<{
+    files: DiscoveredRun[];
+    liveDirs: DiscoveredLiveRun[];
+    watchDirs: Set<string>;
+  }> {
+    const files: DiscoveredRun[] = [];
+    const liveDirs: DiscoveredLiveRun[] = [];
+    const watchDirs = new Set<string>();
+
+    let projectHashes: string[];
+    try {
+      projectHashes = await readdir(this.projectsDir);
+    } catch {
+      return { files, liveDirs, watchDirs };
+    }
+
+    for (const projectHash of projectHashes) {
+      let sessions: string[];
+      try {
+        sessions = await readdir(join(this.projectsDir, projectHash));
+      } catch {
+        continue;
+      }
+      for (const sessionUuid of sessions) {
+        const sessionDir = join(this.projectsDir, projectHash, sessionUuid);
+
+        // (1) Completion artifacts: workflows/wf_*.json
+        const workflowsDir = join(sessionDir, WORKFLOWS_SUBDIR);
+        try {
+          const names = await readdir(workflowsDir);
+          let hasRun = false;
+          for (const name of names) {
+            if (!name.startsWith(RUN_FILE_PREFIX) || !name.endsWith(RUN_FILE_SUFFIX)) continue;
+            hasRun = true;
+            files.push({
+              filePath: join(workflowsDir, name),
+              projectHash,
+              sessionUuid,
+              runId: name.slice(0, -RUN_FILE_SUFFIX.length),
+            });
+          }
+          if (hasRun) watchDirs.add(workflowsDir);
+        } catch {
+          // no workflows dir for this session — normal
+        }
+
+        // (2) In-flight runs: subagents/workflows/wf_*/
+        const liveParent = join(sessionDir, SUBAGENTS_SUBDIR, WORKFLOWS_SUBDIR);
+        try {
+          const names = await readdir(liveParent);
+          let hasLive = false;
+          for (const name of names) {
+            if (!name.startsWith(RUN_FILE_PREFIX) || name.endsWith(RUN_FILE_SUFFIX)) continue; // wf_<id> dir, not a file
+            hasLive = true;
+            liveDirs.push({
+              dirPath: join(liveParent, name),
+              projectHash,
+              sessionUuid,
+              runId: name,
+            });
+          }
+          if (hasLive) watchDirs.add(liveParent);
+        } catch {
+          // no subagents/workflows dir for this session — normal
+        }
+      }
+    }
+    return { files, liveDirs, watchDirs };
+  }
+
+  private async maybeParse(file: DiscoveredRun): Promise<void> {
+    let mtime: number;
+    try {
+      mtime = (await stat(file.filePath)).mtimeMs;
+    } catch {
+      return; // vanished between discover and stat
+    }
+    if (this.fileMtimes.get(file.filePath) === mtime) return;
+    this.fileMtimes.set(file.filePath, mtime);
+
+    const info = await this.parseFile(file);
+    if (!info) return;
+
+    const existed = this.runs.has(info.runId);
+    this.runs.set(info.runId, info);
+    this.runIdToPath.set(info.runId, file.filePath);
+    this.emit(existed ? 'run_updated' : 'run_discovered', info);
+  }
+
+  /**
+   * Re-synthesize an in-flight run from its transcript dir. Cheap pass first: stat
+   * the dir members and skip entirely when the newest mtime is unchanged, so an idle
+   * poll never reads a single (large) transcript. Only on a real change do we parse —
+   * and even then per-transcript stats come from an mtime-keyed cache, so only the
+   * transcripts that actually grew are re-read.
+   */
+  private async maybeParseLive(live: DiscoveredLiveRun): Promise<void> {
+    let entries: string[];
+    try {
+      entries = await readdir(live.dirPath);
+    } catch {
+      return; // vanished between discover and read
+    }
+
+    // Cheap pass: newest member mtime + the agent-file set (no transcript reads yet).
+    let newestMtime = 0;
+    let journalPath: string | null = null;
+    let journalMtime = 0;
+    const agentFiles = new Map<string, LiveAgentFile>();
+    for (const name of entries) {
+      if (name !== LIVE_JOURNAL_FILE && !name.startsWith(LIVE_AGENT_PREFIX)) continue;
+      const full = join(live.dirPath, name);
+      let m = 0;
+      try {
+        m = (await stat(full)).mtimeMs;
+      } catch {
+        continue; // entry vanished — ignore
+      }
+      if (m > newestMtime) newestMtime = m;
+      if (name === LIVE_JOURNAL_FILE) {
+        journalPath = full;
+        journalMtime = m;
+        continue;
+      }
+      // agent-<stem>.jsonl (transcript) or agent-<stem>.meta.json (queued-slot marker)
+      const stem = name.slice(LIVE_AGENT_PREFIX.length).replace(/\.(meta\.json|jsonl)$/, '');
+      if (!stem) continue;
+      const slot = agentFiles.get(stem) || { agentId: stem };
+      if (name.endsWith(LIVE_TRANSCRIPT_SUFFIX)) {
+        slot.transcriptPath = full;
+        slot.transcriptMtime = m;
+      }
+      agentFiles.set(stem, slot);
+    }
+    if (agentFiles.size === 0) return; // nothing to show yet
+
+    // Skip the expensive parse when nothing changed since the last synthesis.
+    if (this.liveDirMtimes.get(live.dirPath) === newestMtime) return;
+    this.liveDirMtimes.set(live.dirPath, newestMtime);
+
+    const info = await this.parseLiveDir(live, agentFiles, journalPath, journalMtime, newestMtime);
+    if (!info) return;
+
+    const existed = this.runs.has(info.runId);
+    this.runs.set(info.runId, info);
+    this.runIdToLiveDir.set(info.runId, live.dirPath);
+    this.emit(existed ? 'run_updated' : 'run_discovered', info);
+  }
+
+  /**
+   * Build an ACTIVE WorkflowRunInfo from a live transcript dir, ENRICHED so the
+   * floating window / panel show real data mid-run rather than empty slots:
+   *   - per-agent tokens + tool-calls + model + last tool, parsed from each
+   *     `agent-<id>.jsonl` (mtime-cached — only changed transcripts are re-read);
+   *   - per-agent state: 'done' once the journal logs a `result` (→ green badge),
+   *     'progress' once it logs `started` or a transcript exists (→ yellow), else 'start';
+   *   - run name/summary/phases from the live `workflows/scripts/<name>-<runId>.js`
+   *     (the completion wf_<id>.json, which carries these, only lands at the end);
+   *   - run totals = sums of the per-agent stats.
+   */
+  private async parseLiveDir(
+    live: DiscoveredLiveRun,
+    agentFiles: Map<string, LiveAgentFile>,
+    journalPath: string | null,
+    journalMtime: number,
+    newestMtime: number
+  ): Promise<WorkflowRunInfo | null> {
+    const { startedOrder, doneIds } = journalPath
+      ? await this.readJournal(journalPath, journalMtime)
+      : { startedOrder: [] as string[], doneIds: new Set<string>() };
+    const startIndex = new Map<string, number>();
+    startedOrder.forEach((id, i) => startIndex.set(id, i));
+
+    // Order agents by journal launch order; not-yet-started ones trail (sorted by id).
+    const ids = Array.from(agentFiles.keys()).sort((a, b) => {
+      const ia = startIndex.has(a) ? (startIndex.get(a) as number) : Number.MAX_SAFE_INTEGER;
+      const ib = startIndex.has(b) ? (startIndex.get(b) as number) : Number.MAX_SAFE_INTEGER;
+      if (ia !== ib) return ia - ib;
+      return a < b ? -1 : a > b ? 1 : 0;
+    });
+
+    let totalTokens = 0;
+    let totalToolCalls = 0;
+    let defaultModel = '';
+    const agents: WorkflowAgentInfo[] = [];
+    for (let i = 0; i < ids.length; i++) {
+      const id = ids[i];
+      const file = agentFiles.get(id) as LiveAgentFile;
+      const stats = file.transcriptPath
+        ? await this.agentTranscriptStats(file.transcriptPath, file.transcriptMtime || 0)
+        : null;
+      const state = doneIds.has(id) ? 'done' : startIndex.has(id) || file.transcriptPath ? 'progress' : 'start';
+      if (stats) {
+        totalTokens += stats.tokens;
+        totalToolCalls += stats.toolCalls;
+        if (stats.model && !defaultModel) defaultModel = stats.model;
+      }
+      agents.push({
+        index: i + 1,
+        label: `agent ${i + 1}`,
+        phaseIndex: 1,
+        phaseTitle: '',
+        model: stats?.model || '',
+        state,
+        agentId: id,
+        tokens: stats ? stats.tokens : undefined,
+        toolCalls: stats ? stats.toolCalls : undefined,
+        lastToolName: stats?.lastToolName,
+        promptPreview: stats?.promptPreview,
+      });
+    }
+
+    // Script meta is immutable for the life of a run, so derive it at most once.
+    // Re-derive only while we still lack a name (the script can land a poll or two
+    // after the first transcripts, which seed the run before the script exists).
+    let meta = this.liveMetaCache.get(live.runId);
+    if (!meta || !meta.workflowName) {
+      meta = await this.deriveLiveWorkflowMeta(live);
+      this.liveMetaCache.set(live.runId, meta);
+    }
+
+    return {
+      runId: live.runId,
+      workflowName: meta.workflowName,
+      summary: meta.summary,
+      status: 'running',
+      agentCount: agents.length,
+      totalTokens,
+      totalToolCalls,
+      defaultModel: defaultModel || undefined,
+      phases: meta.phases,
+      agents,
+      sessionUuid: live.sessionUuid,
+      projectHash: live.projectHash,
+      lastActivityAt: newestMtime || 0,
+    };
+  }
+
+  /** Parse one agent transcript for token/tool stats; cached on the file's mtime. */
+  private async agentTranscriptStats(path: string, mtimeMs: number): Promise<AgentTranscriptStats | null> {
+    // peek (not get) on the hit-check so a cache HIT doesn't churn the LRU — every
+    // active agent is looked up each poll, and get() would delete+reinsert each time.
+    const cached = this.agentStatCache.peek(path);
+    if (cached && cached.mtimeMs === mtimeMs) return cached.stats;
+    let text: string;
+    try {
+      text = await readFile(path, 'utf-8');
+    } catch {
+      return null; // vanished mid-poll
+    }
+    let tokens = 0;
+    let toolCalls = 0;
+    let model = '';
+    let lastToolName: string | undefined;
+    let promptPreview: string | undefined;
+    for (const line of text.split('\n')) {
+      if (!line) continue;
+      let entry: { type?: string; message?: unknown };
+      try {
+        entry = JSON.parse(line) as { type?: string; message?: unknown };
+      } catch {
+        continue; // tolerate a partially-written trailing line
+      }
+      const msg = entry.message as
+        | {
+            model?: string;
+            usage?: {
+              input_tokens?: number;
+              output_tokens?: number;
+              cache_read_input_tokens?: number;
+              cache_creation_input_tokens?: number;
+            };
+            content?: Array<{ type?: string; name?: string; text?: string }> | string;
+          }
+        | undefined;
+      if (!promptPreview && entry.type === 'user' && msg) {
+        promptPreview = truncate(extractMessageText(msg.content), PROMPT_PREVIEW_MAX);
+      }
+      if (!msg || typeof msg !== 'object') continue;
+      if (typeof msg.model === 'string' && msg.model) model = msg.model;
+      const u = msg.usage;
+      if (u) {
+        const total =
+          (u.input_tokens || 0) +
+          (u.output_tokens || 0) +
+          (u.cache_read_input_tokens || 0) +
+          (u.cache_creation_input_tokens || 0);
+        // Anthropic usage already reflects cumulative context, so the agent's running
+        // token total ≈ its LATEST usage-bearing message — last non-zero wins.
+        if (total > 0) tokens = total;
+      }
+      if (Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+          if (block && block.type === 'tool_use' && typeof block.name === 'string') {
+            toolCalls++;
+            lastToolName = block.name;
+          }
+        }
+      }
+    }
+    const stats: AgentTranscriptStats = { tokens, toolCalls, model, lastToolName, promptPreview };
+    this.agentStatCache.set(path, { mtimeMs, stats });
+    return stats;
+  }
+
+  /**
+   * Read the run journal: agent ids in `started` order plus the set that already
+   * logged a terminal `result`. (`started` lines appear in launch order.)
+   */
+  private async readJournal(
+    journalPath: string,
+    mtimeMs: number
+  ): Promise<{ startedOrder: string[]; doneIds: Set<string> }> {
+    const cached = this.journalCache.get(journalPath);
+    if (cached && cached.mtimeMs === mtimeMs) return cached.parsed;
+    const startedOrder: string[] = [];
+    const seenStarted = new Set<string>();
+    const doneIds = new Set<string>();
+    let text: string;
+    try {
+      text = await readFile(journalPath, 'utf-8');
+    } catch {
+      return { startedOrder, doneIds }; // journal not written yet
+    }
+    for (const line of text.split('\n')) {
+      if (!line) continue;
+      try {
+        const ev = JSON.parse(line) as { type?: string; agentId?: string };
+        if (!ev || typeof ev.agentId !== 'string') continue;
+        if (ev.type === 'started' && !seenStarted.has(ev.agentId)) {
+          seenStarted.add(ev.agentId);
+          startedOrder.push(ev.agentId);
+        } else if (ev.type === 'result') {
+          doneIds.add(ev.agentId);
+        }
+      } catch {
+        // tolerate a partially-written trailing line
+      }
+    }
+    const parsed = { startedOrder, doneIds };
+    this.journalCache.set(journalPath, { mtimeMs, parsed });
+    return parsed;
+  }
+
+  /**
+   * Derive name/summary/phases for a live run from its persisted script file
+   * `…/workflows/scripts/<name>-<runId>.js`. The filename yields a reliable name;
+   * `meta.description`/`meta.phases` are best-effort regex extractions (the script is
+   * JS we must not eval), so any parse miss simply leaves those optional fields absent.
+   */
+  private async deriveLiveWorkflowMeta(live: DiscoveredLiveRun): Promise<LiveWorkflowMeta> {
+    const empty: LiveWorkflowMeta = { phases: [] };
+    const scriptsDir = join(this.projectsDir, live.projectHash, live.sessionUuid, WORKFLOWS_SUBDIR, SCRIPTS_SUBDIR);
+    let names: string[];
+    try {
+      names = await readdir(scriptsDir);
+    } catch {
+      return empty;
+    }
+    const suffix = `-${live.runId}.js`;
+    const fileName = names.find((n) => n.endsWith(suffix)) || names.find((n) => n.includes(live.runId));
+    if (!fileName) return empty;
+    const nameFromFile = fileName.endsWith(suffix) ? fileName.slice(0, -suffix.length) : fileName.replace(/\.js$/, '');
+    let body = '';
+    try {
+      body = (await readFile(join(scriptsDir, fileName), 'utf-8')).slice(0, SCRIPT_READ_MAX_BYTES);
+    } catch {
+      return { workflowName: nameFromFile || undefined, phases: [] };
+    }
+    // Scope name/summary/phases parsing to the `meta` literal so later script
+    // declarations (schemas, prose) can't be mistaken for it.
+    const metaBlock = extractMetaBlock(body) || body;
+    return {
+      workflowName: nameFromFile || extractMetaString(metaBlock, 'name') || undefined,
+      summary: extractMetaString(metaBlock, 'description') || undefined,
+      phases: extractMetaPhases(metaBlock),
+    };
+  }
+
+  /**
+   * Parse a wf_<runId>.json into WorkflowRunInfo, STRIPPING the heavyweight
+   * `script`/`scriptPath`/`result`/`logs` fields (the embedded script alone is
+   * 15–660KB) so they never reach the cache, SSE, or routes.
+   */
+  private async parseFile(file: DiscoveredRun): Promise<WorkflowRunInfo | null> {
+    let raw: Record<string, unknown>;
+    try {
+      raw = JSON.parse(await readFile(file.filePath, 'utf-8')) as Record<string, unknown>;
+    } catch {
+      return null; // mid-write or malformed — next mtime change re-parses
+    }
+    if (!raw || typeof raw !== 'object') return null;
+
+    const progress = Array.isArray(raw.workflowProgress) ? (raw.workflowProgress as RawProgressEntry[]) : [];
+    const agents: WorkflowAgentInfo[] = progress
+      .filter((e) => e && e.type === 'workflow_agent')
+      .map((e) => this.toAgent(e));
+
+    const phases: WorkflowRunPhase[] = Array.isArray(raw.phases)
+      ? (raw.phases as Array<Record<string, unknown>>).map((p) => ({
+          title: typeof p.title === 'string' ? p.title : '',
+          detail: typeof p.detail === 'string' ? p.detail : '',
+        }))
+      : [];
+
+    let lastProgress = 0;
+    for (const a of agents) {
+      if (typeof a.lastProgressAt === 'number' && a.lastProgressAt > lastProgress) lastProgress = a.lastProgressAt;
+    }
+    const startTime = typeof raw.startTime === 'number' ? raw.startTime : undefined;
+    const lastActivityAt = lastProgress || startTime || 0;
+
+    return {
+      runId: typeof raw.runId === 'string' ? raw.runId : file.runId,
+      workflowName: typeof raw.workflowName === 'string' ? raw.workflowName : undefined,
+      status: typeof raw.status === 'string' ? raw.status : undefined,
+      summary: typeof raw.summary === 'string' ? raw.summary : undefined,
+      agentCount: typeof raw.agentCount === 'number' ? raw.agentCount : undefined,
+      totalTokens: typeof raw.totalTokens === 'number' ? raw.totalTokens : undefined,
+      totalToolCalls: typeof raw.totalToolCalls === 'number' ? raw.totalToolCalls : undefined,
+      durationMs: typeof raw.durationMs === 'number' ? raw.durationMs : undefined,
+      startTime,
+      timestamp: typeof raw.timestamp === 'string' ? raw.timestamp : undefined,
+      defaultModel: typeof raw.defaultModel === 'string' ? raw.defaultModel : undefined,
+      taskId: typeof raw.taskId === 'string' ? raw.taskId : undefined,
+      error: typeof raw.error === 'string' ? raw.error : undefined,
+      phases,
+      agents,
+      sessionUuid: file.sessionUuid,
+      projectHash: file.projectHash,
+      lastActivityAt,
+    };
+  }
+
+  private toAgent(e: RawProgressEntry): WorkflowAgentInfo {
+    return {
+      index: typeof e.index === 'number' ? e.index : 0,
+      label: typeof e.label === 'string' ? e.label : '',
+      phaseIndex: typeof e.phaseIndex === 'number' ? e.phaseIndex : 0,
+      phaseTitle: typeof e.phaseTitle === 'string' ? e.phaseTitle : '',
+      model: typeof e.model === 'string' ? e.model : '',
+      state: typeof e.state === 'string' ? e.state : 'start',
+      queuedAt: e.queuedAt,
+      lastProgressAt: e.lastProgressAt,
+      promptPreview: truncate(e.promptPreview, PROMPT_PREVIEW_MAX),
+      agentId: e.agentId,
+      startedAt: e.startedAt,
+      attempt: e.attempt,
+      tokens: e.tokens,
+      toolCalls: e.toolCalls,
+      lastToolName: e.lastToolName,
+      lastToolSummary: truncate(e.lastToolSummary, RESULT_PREVIEW_MAX),
+      durationMs: e.durationMs,
+      resultPreview: truncate(e.resultPreview, RESULT_PREVIEW_MAX),
+    };
+  }
+
+  private ensureDirWatcher(workflowsDir: string): void {
+    if (this.dirWatchers.has(workflowsDir)) return;
+    try {
+      const watcher = chokidarWatch(workflowsDir, {
+        depth: 0,
+        awaitWriteFinish: { stabilityThreshold: 200 },
+        ignoreInitial: true,
+        persistent: false,
+      });
+      const handler = () => this.poll();
+      watcher.on('add', handler);
+      watcher.on('change', handler);
+      watcher.on('unlink', handler);
+      // subagents/workflows/ children are wf_<id>/ DIRS — catch their add/remove too.
+      watcher.on('addDir', handler);
+      watcher.on('unlinkDir', handler);
+      watcher.on('error', () => {
+        // chokidar surfaced an error for this dir — drop the watcher; poll still covers it.
+        this.removeDirWatcher(workflowsDir);
+      });
+      this.dirWatchers.set(workflowsDir, watcher);
+    } catch {
+      // Watch setup failed — periodic poll still discovers changes.
+    }
+  }
+
+  private removeDirWatcher(workflowsDir: string): void {
+    const watcher = this.dirWatchers.get(workflowsDir);
+    if (watcher) {
+      watcher.close().catch(() => {});
+      this.dirWatchers.delete(workflowsDir);
+    }
+  }
+}
+
+/** Process-wide singleton (mirrors subagentWatcher / imageWatcher). */
+export const workflowRunWatcher = new WorkflowRunWatcher();

test/auth-security.test.ts

@@ -14,6 +14,7 @@ import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach, vi }
 import { WebServer } from '../src/web/server.js';
 import { TmuxManager } from '../src/tmux-manager.js';
 import { SettingsUpdateSchema } from '../src/web/schemas.js';
+import { getHookSecret, HOOK_SECRET_HEADER } from '../src/config/hook-secret.js';
 
 const AUTH_PORT = 3160;
 const NOAUTH_PORT = 3161;
@@ -250,28 +251,28 @@ describe('Auth Security', () => {
   });
 
   describe('Hook Event Endpoint', () => {
-    it('should allow hook events from localhost without auth', async () => {
+    it('should allow hook events from localhost with the hook secret (no Basic auth)', async () => {
       const res = await fetch(`${baseUrl}/api/hook-event`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', [HOOK_SECRET_HEADER]: getHookSecret() },
         body: JSON.stringify({
           event: 'stop',
           sessionId: 'nonexistent-session',
           data: {},
         }),
       });
-      // Should pass auth (localhost bypass) but may 404 on session — that's fine
-      // The key assertion is it does NOT return 401
+      // Should pass auth (localhost bypass + hook secret) but may 404 on session — that's fine.
+      // The key assertion is it does NOT return 401 (COD-91: secret required even with no tunnel).
       expect(res.status).not.toBe(401);
     });
 
     it('should reject hook events with invalid schema', async () => {
       const res = await fetch(`${baseUrl}/api/hook-event`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', [HOOK_SECRET_HEADER]: getHookSecret() },
         body: JSON.stringify({ invalid: 'data' }),
       });
-      // Schema validation should catch this
+      // Past the auth gate (valid secret) → schema validation should catch this (not a 401).
       expect(res.status).not.toBe(401); // Not an auth error
     });
   });

test/claude-scrollback-strip.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import { Session, isAltScreenStripMode } from '../src/session.js';
+
+type SessionInternals = {
+  _handleTerminalOutput(data: string): void;
+};
+
+function handleOutput(session: Session, data: string): void {
+  (session as unknown as SessionInternals)._handleTerminalOutput(data);
+}
+
+describe('isAltScreenStripMode', () => {
+  it('strips for the controlled TUIs (codex + claude), not shell/opencode', () => {
+    expect(isAltScreenStripMode('codex')).toBe(true);
+    expect(isAltScreenStripMode('claude')).toBe(true);
+    expect(isAltScreenStripMode('shell')).toBe(false);
+    expect(isAltScreenStripMode('opencode')).toBe(false);
+  });
+});
+
+describe('Claude terminal scrollback strip', () => {
+  it('strips alt-screen toggles, scrollback-erase, and mouse-tracking', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    handleOutput(session, '\x1b[?1049h\x1b[55;1Hdialog\x1b[3J\x1b[?1006h\x1b[?1049l');
+
+    expect(emitted[0]).toBe('\x1b[55;1Hdialog');
+    expect(session.terminalBuffer).toBe('\x1b[55;1Hdialog');
+  });
+
+  it('keeps the visible-screen erase (2J / [J) — only scrollback-erase (3J) is dropped', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+
+    handleOutput(session, '\x1b[?1049h\x1b[2Jvisible\x1b[3Jscrollback\x1b[?1049l');
+
+    expect(session.terminalBuffer).toBe('\x1b[2Jvisiblescrollback');
+  });
+
+  it('preserves an ordinary erase-display redraw (no scrollback sequences)', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+
+    handleOutput(session, '\x1b[H\x1b[Jclaude redraw');
+
+    expect(session.terminalBuffer).toBe('\x1b[H\x1b[Jclaude redraw');
+  });
+
+  it('strips sequences split across PTY chunk boundaries (carry reassembly)', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    handleOutput(session, 'before\x1b[?104');
+    handleOutput(session, '9h\x1b[2Jafter\x1b[3');
+    handleOutput(session, 'Jtail');
+
+    expect(session.terminalBuffer).toBe('before\x1b[2Jaftertail');
+    expect(emitted).toEqual(['before', '\x1b[2Jafter', 'tail']);
+  });
+
+  it('emits nothing for a chunk that is only a partial CSI, then completes it', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    handleOutput(session, '\x1b[?100'); // pure partial — held, nothing emitted
+    handleOutput(session, '6h done'); // completes ?1006h (stripped); rest passes
+
+    expect(emitted).toEqual([' done']);
+    expect(session.terminalBuffer).toBe(' done');
+  });
+
+  it('does not touch ordinary Claude conversation output', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+
+    const text = 'Here is line one\r\nHere is line two\r\n\x1b[2mdim status\x1b[0m';
+    handleOutput(session, text);
+
+    expect(session.terminalBuffer).toBe(text);
+  });
+});
+
+describe('Shell terminal output is NOT stripped (vim/less/htop need the alt screen)', () => {
+  it('leaves alt-screen toggles, scrollback-erase, and mouse-tracking intact for shell', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'shell' });
+
+    const vimLike = '\x1b[?1049h\x1b[?1002h\x1b[2J~ editing\x1b[3J\x1b[?1002l\x1b[?1049l';
+    handleOutput(session, vimLike);
+
+    expect(session.terminalBuffer).toBe(vimLike);
+  });
+});

test/cod54-hook-event-auth.test.ts

@@ -4,15 +4,19 @@
  * The `/api/hook-event` localhost bypass let tunnel traffic (cloudflared
  * --url http://127.0.0.1:port) reach the loopback origin with req.ip ===
  * 127.0.0.1 and drive respawn/Ralph signals unauthenticated. The fix gates
- * the bypass behind a shared hook secret WHEN A TUNNEL IS RUNNING, while
- * keeping the plain localhost bypass for the normal loopback-only case so
- * already-deployed (pre-secret) hooks and the loop's own channel keep working.
+ * the bypass behind a shared hook secret. COD-91 makes that requirement
+ * UNCONDITIONAL — the loopback bypass requires the secret whether or not a
+ * managed tunnel is running, because Codeman can't detect a user's own loopback
+ * reverse proxy (own cloudflared / `tailscale serve` / nginx → 127.0.0.1).
+ * Managed-session hooks always present the secret, so the legitimate channel
+ * keeps working.
  *
  * Tests:
  *  - tunnel running + no secret  → 401 (closes the hole)
  *  - tunnel running + bad secret → 401
  *  - tunnel running + good secret → not 401 (allowed)
- *  - tunnel NOT running + no secret → not 401 (back-compat regression guard)
+ *  - tunnel NOT running + no secret → 401 (COD-91: secret required unconditionally)
+ *  - tunnel NOT running + good secret → not 401 (allowed)
  *  - rate limiting: rapid unauthorized hook POSTs eventually 429
  *
  * Port: 3230 (tunnel-running), 3231 (tunnel-down), 3232 (rate-limit)
@@ -83,7 +87,7 @@ describe('COD-54 hook-event auth — tunnel running requires secret', () => {
   });
 });
 
-describe('COD-54 hook-event auth — tunnel down keeps localhost bypass (back-compat)', () => {
+describe('COD-91 hook-event auth — tunnel down ALSO requires the secret', () => {
   let server: WebServer;
   let baseUrl: string;
   let isRunningSpy: ReturnType<typeof vi.spyOn>;
@@ -105,8 +109,13 @@ describe('COD-54 hook-event auth — tunnel down keeps localhost bypass (back-co
     delete process.env.CODEMAN_USERNAME;
   });
 
-  it('still allows a localhost hook POST WITHOUT a secret (existing hooks + loop channel keep working)', async () => {
+  it('rejects a localhost hook POST WITHOUT a secret even with no tunnel (COD-91)', async () => {
     const res = await postHook(baseUrl);
+    expect(res.status).toBe(401);
+  });
+
+  it('allows a localhost hook POST WITH the correct secret when no tunnel is running', async () => {
+    const res = await postHook(baseUrl, { [HOOK_SECRET_HEADER]: getHookSecret() });
     expect(res.status).not.toBe(401);
   });
 });

test/dependency-checker.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect } from 'vitest';
+import { DEPENDENCY_REGISTRY } from '../src/config/dependency-registry.js';
+import {
+  detectEnvironment,
+  extractVersion,
+  compareVersions,
+  checkTool,
+  checkAll,
+  createRealHost,
+} from '../src/utils/dependency-checker.js';
+import type { ProbeHost } from '../src/utils/dependency-checker.js';
+import type { ProbeEnvironment, ToolDependency } from '../src/config/dependency-registry.js';
+
+describe('DEPENDENCY_REGISTRY', () => {
+  it('has unique ids', () => {
+    const ids = DEPENDENCY_REGISTRY.map((t) => t.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('hard-requires only node and tmux; agent CLIs and office are optional', () => {
+    const required = DEPENDENCY_REGISTRY.filter((t) => t.required)
+      .map((t) => t.id)
+      .sort();
+    expect(required).toEqual(['node', 'tmux']);
+    // all agent CLIs are optional (Codeman runs any of them)
+    const agentClis = ['claude', 'opencode', 'codex'];
+    expect(DEPENDENCY_REGISTRY.filter((t) => agentClis.includes(t.id)).every((t) => t.required === false)).toBe(true);
+    const office = DEPENDENCY_REGISTRY.filter((t) => t.category === 'office');
+    expect(office.every((t) => t.required === false)).toBe(true);
+  });
+
+  it('gives msoffice a windows-side resolver scoped to wsl + win32 only', () => {
+    const ms = DEPENDENCY_REGISTRY.find((t) => t.id === 'msoffice');
+    expect(ms).toBeDefined();
+    const spec = ms!.resolvers.find((r) => r.resolver.kind === 'windows-side');
+    expect(spec).toBeDefined();
+    expect([...spec!.match].sort()).toEqual(['win32', 'wsl']);
+    expect(ms!.resolvers.some((r) => r.match.includes('linux'))).toBe(false);
+  });
+});
+
+describe('detectEnvironment', () => {
+  it('returns win32/darwin straight from platform', () => {
+    expect(detectEnvironment({ platform: 'win32', procVersion: '', hasWindowsInterop: false })).toBe('win32');
+    expect(detectEnvironment({ platform: 'darwin', procVersion: '', hasWindowsInterop: false })).toBe('darwin');
+  });
+
+  it('detects wsl from /proc/version + interop, else linux', () => {
+    const wsl = detectEnvironment({
+      platform: 'linux',
+      procVersion: 'Linux version 6.6 (Microsoft@WSL2)',
+      hasWindowsInterop: true,
+    });
+    expect(wsl).toBe('wsl');
+    expect(detectEnvironment({ platform: 'linux', procVersion: 'Microsoft', hasWindowsInterop: false })).toBe('linux');
+    expect(detectEnvironment({ platform: 'linux', procVersion: 'generic', hasWindowsInterop: true })).toBe('linux');
+  });
+});
+
+describe('extractVersion', () => {
+  it('pulls a dotted version from typical --version output', () => {
+    expect(extractVersion('v22.22.1')).toBe('22.22.1');
+    expect(extractVersion('tmux 3.4')).toBe('3.4');
+    expect(extractVersion('no digits here')).toBeUndefined();
+  });
+  it('honors a custom regex', () => {
+    expect(extractVersion('ProductVersion 16.0.19929.20172', /(\d+\.\d+\.\d+)/)).toBe('16.0.19929');
+  });
+});
+
+describe('compareVersions', () => {
+  it('orders by numeric components', () => {
+    expect(compareVersions('18.0.0', '18.0.0')).toBe(0);
+    expect(compareVersions('16.5.0', '18.0.0')).toBe(-1);
+    expect(compareVersions('22.22.1', '18.0.0')).toBe(1);
+    expect(compareVersions('3.4', '3.4.0')).toBe(0);
+  });
+});
+
+function fakeHost(env: ProbeEnvironment, over: Partial<ProbeHost> = {}): ProbeHost {
+  return {
+    environment: env,
+    which: () => null,
+    fileExists: () => false,
+    runVersion: () => null,
+    windowsProgramRoots: () => [],
+    windowsFileVersion: () => null,
+    ...over,
+  };
+}
+
+const tmuxTool: ToolDependency = {
+  id: 'tmux',
+  label: 'tmux',
+  category: 'core',
+  required: true,
+  resolvers: [{ match: ['linux', 'wsl'], resolver: { kind: 'path', bins: ['tmux'], versionArg: '-V' } }],
+};
+const nodeTool: ToolDependency = {
+  id: 'node',
+  label: 'Node.js',
+  category: 'core',
+  required: true,
+  minVersion: '18.0.0',
+  resolvers: [{ match: ['linux'], resolver: { kind: 'path', bins: ['node'] } }],
+};
+const msTool: ToolDependency = {
+  id: 'msoffice',
+  label: 'MS Office',
+  category: 'office',
+  required: false,
+  resolvers: [
+    {
+      match: ['wsl', 'win32'],
+      resolver: { kind: 'windows-side', appDirs: ['Microsoft Office/root/Office16'], exes: ['WINWORD.EXE'] },
+    },
+  ],
+};
+
+describe('checkTool', () => {
+  it('reports ok with path + version when found on PATH', () => {
+    const host = fakeHost('linux', {
+      which: (b) => (b === 'tmux' ? '/usr/bin/tmux' : null),
+      runVersion: () => 'tmux 3.4',
+    });
+    expect(checkTool(tmuxTool, host)).toMatchObject({
+      id: 'tmux',
+      status: 'ok',
+      version: '3.4',
+      path: '/usr/bin/tmux',
+    });
+  });
+
+  it('reports missing when no bin resolves', () => {
+    expect(checkTool(tmuxTool, fakeHost('linux'))).toMatchObject({ id: 'tmux', status: 'missing' });
+  });
+
+  it('reports outdated when below minVersion', () => {
+    const host = fakeHost('linux', { which: () => '/n', runVersion: () => 'v16.5.0' });
+    expect(checkTool(nodeTool, host)).toMatchObject({ id: 'node', status: 'outdated', version: '16.5.0' });
+  });
+
+  it('reports error when minVersion set but version unparseable', () => {
+    const host = fakeHost('linux', { which: () => '/n', runVersion: () => 'unknown' });
+    expect(checkTool(nodeTool, host)).toMatchObject({ id: 'node', status: 'error' });
+  });
+
+  it('reports skipped when no resolver matches the environment', () => {
+    expect(checkTool(msTool, fakeHost('linux'))).toMatchObject({ id: 'msoffice', status: 'skipped' });
+  });
+
+  it('finds windows-side apps under WSL', () => {
+    const host = fakeHost('wsl', {
+      windowsProgramRoots: () => ['/mnt/c/Program Files'],
+      fileExists: (p) => p === '/mnt/c/Program Files/Microsoft Office/root/Office16/WINWORD.EXE',
+      windowsFileVersion: () => '16.0.19929.20172',
+    });
+    expect(checkTool(msTool, host)).toMatchObject({
+      id: 'msoffice',
+      status: 'ok',
+      version: '16.0.19929',
+      path: '/mnt/c/Program Files/Microsoft Office/root/Office16/WINWORD.EXE',
+    });
+  });
+});
+
+describe('checkAll', () => {
+  it('maps every tool to a result', () => {
+    const results = checkAll([tmuxTool, msTool], fakeHost('linux'));
+    expect(results.map((r) => r.id)).toEqual(['tmux', 'msoffice']);
+  });
+});
+
+describe('createRealHost', () => {
+  it('returns a host with a valid detected environment and callable methods', () => {
+    const host = createRealHost();
+    expect(['linux', 'darwin', 'win32', 'wsl']).toContain(host.environment);
+    expect(typeof host.which).toBe('function');
+    expect(Array.isArray(host.windowsProgramRoots())).toBe(true);
+  });
+});

test/dependency-report.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { renderTable, renderJson, computeExitCode } from '../src/utils/dependency-report.js';
+import type { ToolResult } from '../src/utils/dependency-checker.js';
+
+const results: ToolResult[] = [
+  {
+    id: 'node',
+    label: 'Node.js',
+    category: 'core',
+    required: true,
+    usedBy: [],
+    status: 'ok',
+    version: '22.22.1',
+    path: '/n',
+  },
+  {
+    id: 'tmux',
+    label: 'tmux',
+    category: 'core',
+    required: true,
+    usedBy: [],
+    status: 'missing',
+    installHint: 'sudo apt install tmux',
+  },
+  {
+    id: 'libreoffice',
+    label: 'LibreOffice',
+    category: 'office',
+    required: false,
+    usedBy: ['document preview', 'thumbnails'],
+    status: 'missing',
+  },
+  {
+    id: 'msoffice',
+    label: 'MS Office',
+    category: 'office',
+    required: false,
+    usedBy: ['document preview', 'thumbnails'],
+    status: 'skipped',
+    reason: 'not applicable on linux',
+  },
+];
+
+describe('computeExitCode', () => {
+  it('non-zero when a required tool is missing/outdated/error', () => {
+    expect(computeExitCode(results)).toBe(1);
+  });
+  it('zero when only optional tools are missing', () => {
+    const ok = results.filter((r) => r.id !== 'tmux');
+    expect(computeExitCode(ok)).toBe(0);
+  });
+});
+
+describe('renderTable', () => {
+  it('groups by category and shows status, version, and install hints', () => {
+    const out = renderTable(results, 'linux');
+    expect(out).toContain('CORE');
+    expect(out).toContain('Node.js');
+    expect(out).toContain('22.22.1');
+    expect(out).toContain('OFFICE');
+    expect(out).toContain('document preview');
+    expect(out).toContain('sudo apt install tmux');
+  });
+});
+
+describe('renderJson', () => {
+  it('includes environment, summary, and per-tool data', () => {
+    const json = renderJson(results, 'linux');
+    expect(json.platform.environment).toBe('linux');
+    expect(json.summary.exitCode).toBe(1);
+    expect(json.summary.ok).toBe(1);
+    expect(json.tools).toHaveLength(4);
+  });
+});

test/hook-secret-selfheal.test.ts

@@ -0,0 +1,106 @@
+/**
+ * COD-91 — `refreshStaleHookSecret` self-heal.
+ *
+ * Making the hook-event secret unconditionally required (PR #127) would silently 401 the
+ * hook curls baked into cases created before the secret header existed (COD-54). Those
+ * curls live in `.claude/settings.local.json` and `writeHooksConfig` only runs at case
+ * CREATION, so existing cases never refresh. `refreshStaleHookSecret` regenerates the
+ * hooks block on session spawn — but ONLY when the case already holds Codeman's own
+ * pre-secret hook curls, never clobbering a user's customizations.
+ *
+ * Pure filesystem logic against a temp dir — no port / server / tmux.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { refreshStaleHookSecret } from '../src/hooks-config.js';
+
+const SECRET_HEADER = 'X-Codeman-Hook-Secret';
+
+// A faithful pre-secret Codeman hook curl (what cases created before COD-54 contain):
+// targets /api/hook-event, but with NO X-Codeman-Hook-Secret header.
+function staleCodemanHooks() {
+  return {
+    Stop: [
+      {
+        matcher: '',
+        hooks: [
+          {
+            type: 'command',
+            command:
+              "HOOK_DATA=$(cat 2>/dev/null || echo '{}'); " +
+              'printf \'{"event":"stop","sessionId":"%s","data":%s}\' "$CODEMAN_SESSION_ID" "$HOOK_DATA" | ' +
+              'curl -s -X POST "$CODEMAN_API_URL/api/hook-event" -H \'Content-Type: application/json\' --data @- 2>/dev/null || true',
+            timeout: 5,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+describe('refreshStaleHookSecret', () => {
+  let dir: string;
+  let settingsPath: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'codeman-selfheal-'));
+    mkdirSync(join(dir, '.claude'), { recursive: true });
+    settingsPath = join(dir, '.claude', 'settings.local.json');
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('adds the secret header to a stale Codeman hooks block and preserves other keys', async () => {
+    writeFileSync(
+      settingsPath,
+      JSON.stringify({ env: { CLAUDE_CODE_FOO: '1' }, model: 'opus', hooks: staleCodemanHooks() }, null, 2)
+    );
+    await refreshStaleHookSecret(dir);
+
+    const after = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    expect(JSON.stringify(after.hooks)).toContain(SECRET_HEADER);
+    expect(JSON.stringify(after.hooks)).toContain('CODEMAN_HOOK_SECRET_FILE');
+    // sibling keys untouched
+    expect(after.env).toEqual({ CLAUDE_CODE_FOO: '1' });
+    expect(after.model).toBe('opus');
+  });
+
+  it('leaves a hooks block that already carries the secret unchanged', async () => {
+    // Seed with a current block by healing a stale one first, then re-heal: second pass must no-op.
+    writeFileSync(settingsPath, JSON.stringify({ hooks: staleCodemanHooks() }, null, 2));
+    await refreshStaleHookSecret(dir);
+    const healed = readFileSync(settingsPath, 'utf-8');
+    expect(healed).toContain(SECRET_HEADER);
+
+    await refreshStaleHookSecret(dir);
+    expect(readFileSync(settingsPath, 'utf-8')).toBe(healed); // byte-identical: no rewrite
+  });
+
+  it('does not touch hooks that are not Codeman’s (no /api/hook-event)', async () => {
+    const foreign = JSON.stringify(
+      { hooks: { Stop: [{ matcher: '', hooks: [{ type: 'command', command: 'echo hi', timeout: 5 }] }] } },
+      null,
+      2
+    );
+    writeFileSync(settingsPath, foreign);
+    await refreshStaleHookSecret(dir);
+    expect(readFileSync(settingsPath, 'utf-8')).toBe(foreign);
+  });
+
+  it('is a no-op when settings.local.json is absent (does not create one)', async () => {
+    await refreshStaleHookSecret(dir);
+    expect(existsSync(settingsPath)).toBe(false);
+  });
+
+  it('leaves a malformed settings file untouched', async () => {
+    const garbage = '{ not valid json';
+    writeFileSync(settingsPath, garbage);
+    await refreshStaleHookSecret(dir);
+    expect(readFileSync(settingsPath, 'utf-8')).toBe(garbage);
+  });
+});

test/keyboard-shortcuts.test.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const appSource = readFileSync('src/web/public/app.js', 'utf8');
+const terminalUiSource = readFileSync('src/web/public/terminal-ui.js', 'utf8');
+const helpHtml = readFileSync('src/web/public/index.html', 'utf8');
+const readme = readFileSync('README.md', 'utf8');
+
+describe('keyboard shortcuts', () => {
+  it('uses physical Option+number keys so macOS special characters do not break tab switching', () => {
+    expect(appSource).toContain('e.code ||');
+    expect(appSource).toContain('Digit([1-9])');
+    expect(appSource).toContain('parseInt(digitMatch[1], 10) - 1');
+  });
+
+  it('provides Option+bracket shortcuts for previous and next session', () => {
+    expect(appSource).toContain("e.code === 'BracketLeft'");
+    expect(appSource).toContain("e.code === 'BracketRight'");
+    expect(appSource).toContain('this.prevSession()');
+    expect(appSource).toContain('this.nextSession()');
+  });
+
+  it('suppresses xterm PTY injection for the same physical Alt nav codes (no ESC leak)', () => {
+    // terminal-ui.js must gate its xterm pass-through on the SAME physical e.code set the
+    // app.js handler consumes; otherwise Alt+[ / Alt+] (and Option+digit on remapped macOS
+    // layouts) switch tabs AND inject ESC<char> into the focused terminal. Keep in sync.
+    expect(terminalUiSource).toContain('/^(Digit[1-9]|BracketLeft|BracketRight)$/.test(ev.code');
+  });
+
+  it('documents the Alt/Option shortcuts in help and README', () => {
+    expect(helpHtml).toContain('<kbd>Alt/Option</kbd>+<kbd>[</kbd>');
+    expect(helpHtml).toContain('<kbd>Alt/Option</kbd>+<kbd>]</kbd>');
+    expect(helpHtml).toContain('<kbd>Alt/Option</kbd>+<kbd>1-9</kbd>');
+    expect(readme).toContain('`Alt/Option+[` / `Alt/Option+]`');
+    expect(readme).toContain('`Alt/Option+1`-`Alt/Option+9`');
+  });
+});

test/markdown-sanitizer.test.ts

@@ -0,0 +1,226 @@
+/**
+ * COD-56 — markdown HTML sanitizer (mXSS hardening).
+ *
+ * The response viewer / attachment preview render agent- and transcript-derived markdown to
+ * HTML via `marked` (raw-HTML passthrough) and assign the result with innerHTML. The HTML must
+ * be sanitized first. The original sanitizer (`_sanitizeHtml` in app.js) was a hand-rolled
+ * DENYLIST and is mXSS-prone — it never stripped `svg`/`math`/`style`, so foreign-namespace and
+ * CSS vectors survived.
+ *
+ * This suite drives the EXACT shipping artifacts:
+ *   - src/web/public/vendor/dompurify.min.js   (the vendored sanitizer)
+ *   - src/web/public/sanitize-html.js          (our allowlist config wired to DOMPurify)
+ *
+ * It runs in the DEFAULT node environment (it deliberately does NOT declare a per-file jsdom
+ * environment) and constructs a jsdom window here, then binds the vendored DOMPurify to it. A
+ * per-file jsdom environment externalizes node:fs/node:path under vite, which made this suite fail
+ * to load when
+ * run in isolation (it only survived the full CI run because an earlier node-env test happened to
+ * pre-cache node:fs). Building the window in-test keeps fs/path native and the suite order-robust.
+ *
+ * It feeds a corpus of mXSS payloads (svg/math/style/namespace-confusion/event-handler) and
+ * asserts the output carries NO script-executing constructs, that the curated allowlist is
+ * actually enforced (non-markdown tags dropped), and that legitimate markdown-rendered HTML
+ * survives unchanged. A faithful re-implementation of the OLD denylist is included and asserted to
+ * LET payloads through — the gap this fix closes.
+ *
+ * No port / server needed.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { JSDOM } from 'jsdom';
+
+const publicDir = join(process.cwd(), 'src/web/public');
+
+// One jsdom window shared by the shipping sanitizer (bound to its DOMPurify) and the old-denylist
+// reference impl (which needs a DOM `document`).
+const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
+const jsdomWindow = dom.window as unknown as Window & typeof globalThis;
+const jsdomDocument = jsdomWindow.document;
+
+/** Build the SHIPPING sanitizer the way the browser does: vendored DOMPurify (bound to our jsdom
+ *  window) + the EXACT CONFIG from sanitize-html.js — so the same allow/forbid lists are exercised
+ *  under vitest without a real browser. */
+function loadShippingSanitizer(): (html: string) => string {
+  const dompurifySrc = readFileSync(join(publicDir, 'vendor/dompurify.min.js'), 'utf8');
+  const sanitizeSrc = readFileSync(join(publicDir, 'sanitize-html.js'), 'utf8');
+
+  // dompurify.min.js is a UMD — evaluate it as CommonJS to obtain the factory (createDOMPurify),
+  // then bind it to our jsdom window so DOMPurify sanitizes against a real DOM.
+  const dpModule: { exports: unknown } = { exports: {} };
+  // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+  new Function('module', 'exports', dompurifySrc)(dpModule, dpModule.exports);
+  const factory = dpModule.exports as (win: unknown) => { sanitize: (h: string, c?: unknown) => string };
+  const DOMPurify = factory(jsdomWindow);
+
+  // sanitize-html.js exposes createMarkdownSanitizer via its CommonJS export.
+  const sanModule: { exports: { createMarkdownSanitizer?: (dp: unknown) => (html: string) => string } } = {
+    exports: {},
+  };
+  // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+  new Function('module', 'exports', sanitizeSrc)(sanModule, sanModule.exports);
+  const create = sanModule.exports.createMarkdownSanitizer;
+  if (typeof create !== 'function') throw new Error('createMarkdownSanitizer not exported');
+  const fn = create(DOMPurify);
+  if (typeof fn !== 'function') throw new Error('sanitizeMarkdownHtml not wired');
+  return fn;
+}
+
+/** Faithful copy of the OLD denylist _sanitizeHtml (app.js pre-COD-56) — used only to prove RED. */
+function oldDenylistSanitize(html: string): string {
+  const tpl = jsdomDocument.createElement('template');
+  tpl.innerHTML = html;
+  const frag = tpl.content;
+  for (const el of frag.querySelectorAll('script, iframe, object, embed, form, base, meta, link, style')) {
+    el.remove();
+  }
+  for (const el of frag.querySelectorAll('*')) {
+    for (const attr of [...el.attributes]) {
+      const name = attr.name.toLowerCase();
+      if (name.startsWith('on')) {
+        el.removeAttribute(attr.name);
+      } else if (['href', 'src', 'action', 'xlink:href', 'formaction'].includes(name)) {
+        const val = attr.value.replace(/\s/g, '').toLowerCase();
+        if (val.startsWith('javascript:') || val.startsWith('vbscript:') || val.startsWith('data:text/html')) {
+          el.removeAttribute(attr.name);
+        }
+      }
+    }
+  }
+  const div = jsdomDocument.createElement('div');
+  div.appendChild(frag);
+  return div.innerHTML;
+}
+
+// mXSS / XSS payloads. Each must be neutralized by the shipping sanitizer.
+const PAYLOADS: { name: string; html: string }[] = [
+  { name: 'img onerror', html: '<img src=x onerror=alert(1)>' },
+  { name: 'svg onload', html: '<svg onload=alert(1)></svg>' },
+  { name: 'svg/script', html: '<svg><script>alert(1)</script></svg>' },
+  { name: 'svg/style mXSS', html: '<svg><style><img src=x onerror=alert(1)></style></svg>' },
+  {
+    name: 'math/mtext/table namespace confusion',
+    html: '<math><mtext><table><mglyph><style><img src=x onerror=alert(1)></style></table></mtext></math>',
+  },
+  { name: 'style attr expression', html: '<div style="width:expression(alert(1))">x</div>' },
+  { name: 'style attr url(javascript:)', html: '<div style="background:url(javascript:alert(1))">x</div>' },
+  { name: 'style element', html: '<style>body{background:url("javascript:alert(1)")}</style>' },
+  { name: 'noscript wrap', html: '<noscript><p title="</noscript><img src=x onerror=alert(1)>">' },
+  { name: 'a javascript: href', html: '<a href="javascript:alert(1)">x</a>' },
+  { name: 'iframe srcdoc', html: '<iframe srcdoc="<img src=x onerror=alert(1)>"></iframe>' },
+  {
+    name: 'foreignObject mXSS',
+    html: '<svg><foreignObject><iframe src="javascript:alert(1)"></iframe></foreignObject></svg>',
+  },
+  { name: 'details ontoggle', html: '<details open ontoggle=alert(1)>x</details>' },
+  { name: 'object data', html: '<object data="javascript:alert(1)"></object>' },
+];
+
+function assertNeutralized(out: string, label: string) {
+  const lower = out.toLowerCase();
+  expect(lower, `${label}: no <script>`).not.toContain('<script');
+  expect(lower, `${label}: no <svg>`).not.toContain('<svg');
+  expect(lower, `${label}: no <math>`).not.toContain('<math');
+  expect(lower, `${label}: no <iframe>`).not.toContain('<iframe');
+  expect(lower, `${label}: no <object>`).not.toContain('<object');
+  expect(lower, `${label}: no <style>`).not.toContain('<style');
+  expect(lower, `${label}: no onerror`).not.toContain('onerror');
+  expect(lower, `${label}: no onload`).not.toContain('onload');
+  expect(lower, `${label}: no ontoggle`).not.toContain('ontoggle');
+  expect(lower, `${label}: no style= attr`).not.toMatch(/\sstyle\s*=/);
+  expect(lower, `${label}: no javascript: scheme`).not.toContain('javascript:');
+  expect(lower, `${label}: no expression(`).not.toContain('expression(');
+}
+
+describe('COD-56 markdown sanitizer (DOMPurify allowlist)', () => {
+  let sanitize: (html: string) => string;
+
+  beforeAll(() => {
+    sanitize = loadShippingSanitizer();
+  });
+
+  describe('mXSS / XSS payloads are neutralized', () => {
+    for (const { name, html } of PAYLOADS) {
+      it(`blocks: ${name}`, () => {
+        assertNeutralized(sanitize(html), name);
+      });
+    }
+  });
+
+  describe('curated allowlist is actually enforced (USE_PROFILES must not override it)', () => {
+    // These tags are in DOMPurify's default html profile but NOT in the curated ALLOWED_TAGS.
+    // If USE_PROFILES were set, the profile would override the allowlist and these would survive.
+    const NON_MARKDOWN_TAGS: { name: string; html: string; tag: string }[] = [
+      { name: 'button', html: '<button>click</button>', tag: '<button' },
+      { name: 'input', html: '<input value="x">', tag: '<input' },
+      { name: 'details', html: '<details open>d</details>', tag: '<details' },
+      { name: 'audio', html: '<audio controls></audio>', tag: '<audio' },
+      { name: 'select/option', html: '<select><option>o</option></select>', tag: '<select' },
+      { name: 'label', html: '<label>l</label>', tag: '<label' },
+    ];
+    for (const { name, html, tag } of NON_MARKDOWN_TAGS) {
+      it(`drops non-markdown tag: ${name}`, () => {
+        expect(sanitize(html).toLowerCase()).not.toContain(tag);
+      });
+    }
+  });
+
+  describe('legitimate markdown-rendered HTML survives', () => {
+    it('keeps bold, links, lists, code, headings, tables, safe images', () => {
+      const md =
+        '<h2>Title</h2>' +
+        '<p><strong>bold</strong> and <em>em</em> and <a href="https://example.com">link</a></p>' +
+        '<ul><li>one</li><li>two</li></ul>' +
+        '<pre><code class="language-js">const x = 1;</code></pre>' +
+        '<blockquote><p>quote</p></blockquote>' +
+        '<table><thead><tr><th>h</th></tr></thead><tbody><tr><td>c</td></tr></tbody></table>' +
+        '<img src="https://example.com/a.png" alt="pic">';
+      const out = sanitize(md);
+      expect(out).toContain('<strong>bold</strong>');
+      expect(out).toContain('<em>em</em>');
+      expect(out).toContain('href="https://example.com"');
+      expect(out).toContain('<li>one</li>');
+      expect(out).toContain('<code class="language-js">const x = 1;</code>');
+      expect(out).toContain('<blockquote>');
+      expect(out).toContain('<th>h</th>');
+      expect(out).toContain('<td>c</td>');
+      expect(out).toContain('src="https://example.com/a.png"');
+      expect(out).toContain('alt="pic"');
+    });
+
+    it('preserves a relative/inline image src and code fences', () => {
+      const out = sanitize('<p>see <code>code</code></p><img src="/local/path.png" alt="x">');
+      expect(out).toContain('<code>code</code>');
+      expect(out).toContain('src="/local/path.png"');
+    });
+  });
+
+  // RED EVIDENCE: the OLD denylist let mXSS through. This documents the gap the fix closes;
+  // it asserts the OLD logic FAILS to neutralize at least the svg/math/style vectors.
+  describe('RED: the old denylist sanitizer was bypassable', () => {
+    it('old code leaves <svg> / <math> roots in the output', () => {
+      // svg/math were never in the denylist tag set -> they survive (mXSS foreign namespace).
+      const svgOut = oldDenylistSanitize('<svg><circle></circle></svg>').toLowerCase();
+      const mathOut = oldDenylistSanitize('<math><mtext>x</mtext></math>').toLowerCase();
+      expect(svgOut).toContain('<svg');
+      expect(mathOut).toContain('<math');
+    });
+
+    it('old code leaves a CSS-vector style attribute in the output', () => {
+      const out = oldDenylistSanitize('<div style="background:url(javascript:alert(1))">x</div>').toLowerCase();
+      // style attributes were never stripped by the denylist.
+      expect(out).toMatch(/\sstyle\s*=/);
+      expect(out).toContain('javascript:');
+    });
+
+    it('NEW code closes those same gaps', () => {
+      expect(sanitize('<svg><circle></circle></svg>').toLowerCase()).not.toContain('<svg');
+      expect(sanitize('<math><mtext>x</mtext></math>').toLowerCase()).not.toContain('<math');
+      const out = sanitize('<div style="background:url(javascript:alert(1))">x</div>').toLowerCase();
+      expect(out).not.toMatch(/\sstyle\s*=/);
+      expect(out).not.toContain('javascript:');
+    });
+  });
+});

test/mobile/keyboard.test.ts

@@ -528,15 +528,24 @@ describe('Virtual Keyboard', () => {
       expect(afterEnter.sentInputs).toEqual(['hello', '\r']);
     });
 
-    it('shows the CJK textarea on mobile only for server override', async () => {
+    it('shows the CJK textarea on mobile for server override only inside an active session', async () => {
       const state = await page.evaluate(() => {
-        app._serverCjkOverride = true;
-        app._updateCjkInputState();
-
         const input = document.getElementById('cjkInput');
         if (!(input instanceof HTMLElement)) return null;
+
+        // Welcome screen (no active session): even with the server override on, the
+        // fixed-position textarea must stay hidden so it doesn't float over the overlay.
+        app.activeSessionId = null;
+        app._serverCjkOverride = true;
+        app._updateCjkInputState();
+        const onWelcomeDisplay = getComputedStyle(input).display;
+
+        // Entering a session reveals it.
+        app.activeSessionId = 'cjk-server-override-test';
+        app._updateCjkInputState();
         const cs = getComputedStyle(input);
         return {
+          onWelcomeDisplay,
           display: cs.display,
           position: cs.position,
           bottom: cs.bottom,
@@ -546,6 +555,7 @@ describe('Virtual Keyboard', () => {
       });
 
       expect(state).not.toBeNull();
+      expect(state?.onWelcomeDisplay).toBe('none');
       expect(state?.display).not.toBe('none');
       expect(state?.position).toBe('fixed');
       expect(Number(state?.zIndex)).toBeGreaterThan(50);

test/routes/file-routes.test.ts

@@ -215,6 +215,50 @@ describe('file-routes', () => {
       expect(body.data.url).toContain('file-raw');
     });
 
+    it('returns audio metadata for audio files', async () => {
+      mockedStat.mockResolvedValue({ size: 2048 } as never);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/sessions/${harness.ctx._sessionId}/file-content?path=clip.mp3`,
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data.type).toBe('audio');
+      expect(body.data.url).toContain('file-raw');
+    });
+
+    it('flags known-binary extensions (e.g. xlsx) instead of dumping mojibake', async () => {
+      mockedStat.mockResolvedValue({ size: 4096 } as never);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/sessions/${harness.ctx._sessionId}/file-content?path=sheet.xlsx`,
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data.type).toBe('binary');
+      expect(body.data.content).toBeUndefined();
+    });
+
+    it('sniffs NUL bytes and flags binary content for unknown extensions', async () => {
+      const binary = Buffer.from([0x50, 0x4b, 0x03, 0x04, 0x00, 0x01, 0x02]);
+      mockedReadFile.mockResolvedValue(binary as never);
+      mockedStat.mockResolvedValue({ size: binary.length } as never);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/sessions/${harness.ctx._sessionId}/file-content?path=mystery.dat`,
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data.type).toBe('binary');
+      expect(body.data.content).toBeUndefined();
+    });
+
     it('rejects path traversal attempts', async () => {
       // realpathSync resolves the symlink to a path outside workingDir
       mockedRealpathSync.mockReturnValue('/etc/passwd' as never);

test/routes/session-routes.test.ts

@@ -369,7 +369,7 @@ describe('session-routes', () => {
       expect(res.statusCode).toBe(200);
       const body = JSON.parse(res.body);
       expect(body.success).toBe(true);
-      expect(harness.ctx._session.resize).toHaveBeenCalledWith(120, 40);
+      expect(harness.ctx._session.resize).toHaveBeenCalledWith(120, 40, { viewportType: undefined, force: undefined });
     });
 
     it('passes viewport type through for resize arbitration', async () => {
@@ -381,7 +381,19 @@ describe('session-routes', () => {
       expect(res.statusCode).toBe(200);
       const body = JSON.parse(res.body);
       expect(body.success).toBe(true);
-      expect(harness.ctx._session.resize).toHaveBeenCalledWith(48, 28, { viewportType: 'mobile' });
+      expect(harness.ctx._session.resize).toHaveBeenCalledWith(48, 28, { viewportType: 'mobile', force: undefined });
+    });
+
+    it('passes force resize through for redraw requests', async () => {
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: `/api/sessions/${harness.ctx._sessionId}/resize`,
+        payload: { cols: 120, rows: 40, force: true },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(harness.ctx._session.resize).toHaveBeenCalledWith(120, 40, { viewportType: undefined, force: true });
     });
 
     it('rejects cols exceeding max (500)', async () => {

test/routes/system-routes-tunnel-guard.test.ts

@@ -117,6 +117,35 @@ describe('COD-55 tunnel password guard (PUT /api/settings tunnelEnabled)', () =>
     expect(tunnel.start).toHaveBeenCalledTimes(1);
   });
 
+  it('ALLOWS tunnel-enable with per-request acknowledgeUnauthTunnel:true (start called, 200, flag not persisted)', async () => {
+    const res = await harness.app.inject({
+      method: 'PUT',
+      url: '/api/settings',
+      payload: { tunnelEnabled: true, acknowledgeUnauthTunnel: true },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(tunnel.start).toHaveBeenCalledTimes(1);
+    // The action flag must NOT be persisted to settings.json.
+    expect(mockedWriteFile).toHaveBeenCalled();
+    const persisted = JSON.parse(mockedWriteFile.mock.calls[0][1] as string);
+    expect(persisted.acknowledgeUnauthTunnel).toBeUndefined();
+    expect(persisted.tunnelEnabled).toBe(true);
+  });
+
+  it('still REFUSES when acknowledgeUnauthTunnel is false (4xx, start not called)', async () => {
+    const res = await harness.app.inject({
+      method: 'PUT',
+      url: '/api/settings',
+      payload: { tunnelEnabled: true, acknowledgeUnauthTunnel: false },
+    });
+
+    expect(res.statusCode).toBeGreaterThanOrEqual(400);
+    expect(res.statusCode).toBeLessThan(500);
+    expect(tunnel.start).not.toHaveBeenCalled();
+    expect(mockedWriteFile).not.toHaveBeenCalled();
+  });
+
   it('does not guard tunnel-disable (tunnelEnabled:false always allowed)', async () => {
     tunnel = makeTunnelManager(true);
     (harness.ctx as unknown as { tunnelManager: unknown }).tunnelManager = tunnel;

test/routes/workflow-routes.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Route tests for the ultracode workflow endpoints:
+ *   GET /api/workflows            → run summaries (no agents[])
+ *   GET /api/workflows/:runId     → full run (with agents[]) or 404
+ *
+ * Uses app.inject() — no real ports. The workflow-run-watcher singleton is mocked
+ * so we control the returned data (positive + not-found) without touching ~/.claude.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
+import { registerSystemRoutes } from '../../src/web/routes/system-routes.js';
+import { vi } from 'vitest';
+
+// ── Mocks required by registerSystemRoutes ──────────────────────────
+vi.mock('node:fs/promises', () => ({
+  default: { readFile: vi.fn(async () => '{}'), writeFile: vi.fn(async () => undefined) },
+}));
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>();
+  return { ...actual, existsSync: vi.fn(() => true), mkdirSync: vi.fn(), readdirSync: vi.fn(() => []) };
+});
+vi.mock('../../src/subagent-watcher.js', () => ({
+  subagentWatcher: {
+    getSubagents: vi.fn(() => []),
+    getRecentSubagents: vi.fn(() => []),
+    isRunning: vi.fn(() => true),
+    start: vi.fn(),
+    stop: vi.fn(),
+  },
+}));
+vi.mock('../../src/image-watcher.js', () => ({
+  imageWatcher: { isRunning: vi.fn(() => false), start: vi.fn(), stop: vi.fn(), watchSession: vi.fn() },
+}));
+vi.mock('../../src/session-lifecycle-log.js', () => ({
+  getLifecycleLog: vi.fn(() => ({ log: vi.fn(), query: vi.fn(async () => []) })),
+}));
+vi.mock('../../src/utils/opencode-cli-resolver.js', () => ({
+  isOpenCodeAvailable: vi.fn(() => false),
+  resolveOpenCodeDir: vi.fn(() => null),
+}));
+
+const SUMMARY = {
+  runId: 'wf_abc123',
+  workflowName: 'review-open-prs',
+  status: 'completed',
+  summary: 'Deep review',
+  agentCount: 2,
+  totalTokens: 1000,
+  totalToolCalls: 10,
+  phases: [{ title: 'Review', detail: 'one per PR' }],
+  sessionUuid: 'sess-1',
+  projectHash: 'proj-1',
+  lastActivityAt: 123,
+};
+const FULL_RUN = {
+  ...SUMMARY,
+  agents: [
+    {
+      index: 1,
+      label: 'review:pr-1',
+      phaseIndex: 1,
+      phaseTitle: 'Review',
+      model: 'opus',
+      state: 'done',
+      tokens: 500,
+      toolCalls: 5,
+    },
+    {
+      index: 2,
+      label: 'review:pr-2',
+      phaseIndex: 1,
+      phaseTitle: 'Review',
+      model: 'opus',
+      state: 'done',
+      tokens: 500,
+      toolCalls: 5,
+    },
+  ],
+};
+
+vi.mock('../../src/workflow-run-watcher.js', () => ({
+  workflowRunWatcher: {
+    getAllRunSummaries: vi.fn(() => [SUMMARY]),
+    getRecentRunSummaries: vi.fn(() => [SUMMARY]),
+    getRun: vi.fn((runId: string) => (runId === 'wf_abc123' ? FULL_RUN : undefined)),
+    isRunning: vi.fn(() => false),
+    start: vi.fn(),
+    stop: vi.fn(),
+  },
+}));
+
+describe('workflow routes', () => {
+  let harness: RouteTestHarness;
+
+  beforeEach(async () => {
+    harness = await createRouteTestHarness(registerSystemRoutes);
+  });
+  afterEach(async () => {
+    await harness.app.close();
+  });
+
+  it('GET /api/workflows returns the envelope with summaries (no agents[])', async () => {
+    const res = await harness.app.inject({ method: 'GET', url: '/api/workflows' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.success).toBe(true);
+    expect(Array.isArray(body.data)).toBe(true);
+    expect(body.data).toHaveLength(1);
+    expect(body.data[0].runId).toBe('wf_abc123');
+    expect('agents' in body.data[0]).toBe(false);
+  });
+
+  it('GET /api/workflows/:runId returns the full run with agents[]', async () => {
+    const res = await harness.app.inject({ method: 'GET', url: '/api/workflows/wf_abc123' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.success).toBe(true);
+    expect(body.data.agents).toHaveLength(2);
+    expect(body.data.agents[0].tokens).toBe(500);
+  });
+
+  it('GET /api/workflows/:runId 404s for an unknown run', async () => {
+    const res = await harness.app.inject({ method: 'GET', url: '/api/workflows/wf_nope' });
+    const body = res.json();
+    expect(body.success).toBe(false);
+    expect(body.errorCode).toBe('NOT_FOUND');
+  });
+});

test/routes/ws-routes.test.ts

@@ -285,7 +285,7 @@ describe('ws-routes', () => {
         ws.send(JSON.stringify({ t: 'z', c: 120, r: 40 }));
 
         await vi.waitFor(() => {
-          expect(session.resize).toHaveBeenCalledWith(120, 40);
+          expect(session.resize).toHaveBeenCalledWith(120, 40, { viewportType: undefined, force: false });
         });
       } finally {
         ws.close();
@@ -300,7 +300,22 @@ describe('ws-routes', () => {
         ws.send(JSON.stringify({ t: 'z', c: 48, r: 28, v: 'mobile' }));
 
         await vi.waitFor(() => {
-          expect(session.resize).toHaveBeenCalledWith(48, 28, { viewportType: 'mobile' });
+          expect(session.resize).toHaveBeenCalledWith(48, 28, { viewportType: 'mobile', force: false });
+        });
+      } finally {
+        ws.close();
+      }
+    });
+
+    it('passes force resize through for redraw requests', async () => {
+      const ws = await connectWs('/ws/sessions/ws-test-session/terminal');
+      try {
+        const session = ctx._session;
+
+        ws.send(JSON.stringify({ t: 'z', c: 120, r: 40, f: true }));
+
+        await vi.waitFor(() => {
+          expect(session.resize).toHaveBeenCalledWith(120, 40, { viewportType: undefined, force: true });
         });
       } finally {
         ws.close();
@@ -342,7 +357,7 @@ describe('ws-routes', () => {
         ws.send(JSON.stringify({ t: 'z', c: 1, r: 1 }));
 
         await vi.waitFor(() => {
-          expect(session.resize).toHaveBeenCalledWith(1, 1);
+          expect(session.resize).toHaveBeenCalledWith(1, 1, { viewportType: undefined, force: false });
         });
       } finally {
         ws.close();
@@ -357,7 +372,7 @@ describe('ws-routes', () => {
         ws.send(JSON.stringify({ t: 'z', c: 500, r: 200 }));
 
         await vi.waitFor(() => {
-          expect(session.resize).toHaveBeenCalledWith(500, 200);
+          expect(session.resize).toHaveBeenCalledWith(500, 200, { viewportType: undefined, force: false });
         });
       } finally {
         ws.close();

test/session-resize-arbitration.test.ts

@@ -113,6 +113,15 @@ describe('Session resize arbitration', () => {
     expect(resize).toHaveBeenCalledWith(100, 30);
   });
 
+  it('applies forced resizes even when the dimensions did not change', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'shell' });
+    const resize = attachFakePty(session, 120, 40);
+
+    session.resize(120, 40, { force: true });
+
+    expect(resize).toHaveBeenCalledWith(120, 40);
+  });
+
   describe('idle-desktop override (whoever is active wins)', () => {
     afterEach(() => {
       vi.useRealTimers();

test/subagent-watcher.test.ts

@@ -404,6 +404,136 @@ describe('SubagentWatcher', () => {
     });
   });
 
+  describe('Meta-sidecar discovery (2026-06 Claude Code format)', () => {
+    it('should discover a subagent from agent-{id}.meta.json when no .jsonl exists', async () => {
+      // New format: TUI Task subagents write only a meta sidecar (no per-agent .jsonl).
+      mockExistsSync.mockImplementation((p: string) => !String(p).endsWith('.jsonl'));
+      mockReaddirSync.mockImplementation((path: string) => {
+        if (path.includes('subagents')) return ['agent-meta1.meta.json'];
+        if (path.includes('session1')) return ['subagents'];
+        if (path.includes('project1')) return ['session1'];
+        return ['project1'];
+      });
+      mockStatSync.mockReturnValue({
+        isDirectory: () => true,
+        birthtime: new Date(),
+        mtime: new Date(),
+        size: 120,
+      });
+      mockReadFileSync.mockReturnValue(
+        JSON.stringify({ agentType: 'general-purpose', description: 'Audit server.js', toolUseId: 'toolu_x' })
+      );
+
+      const discoveredHandler = vi.fn();
+      watcher.on('subagent:discovered', discoveredHandler);
+
+      watcher.start();
+      await flushAsyncScan();
+
+      expect(discoveredHandler).toHaveBeenCalled();
+      const info = discoveredHandler.mock.calls[0][0] as SubagentInfo;
+      expect(info.agentId).toBe('meta1');
+      expect(info.description).toBe('Audit server.js');
+      expect(info.status).toBe('active');
+      expect(watcher.getSubagents()).toHaveLength(1);
+    });
+
+    it('should prefer the real .jsonl transcript when one exists alongside the meta', async () => {
+      // Both sidecar and transcript present → defer to the richer .jsonl path.
+      mockExistsSync.mockReturnValue(true); // sibling agent-both.jsonl exists
+      mockReaddirSync.mockImplementation((path: string) => {
+        if (path.includes('subagents')) return ['agent-both.meta.json'];
+        if (path.includes('session1')) return ['subagents'];
+        if (path.includes('project1')) return ['session1'];
+        return ['project1'];
+      });
+      mockStatSync.mockReturnValue({
+        isDirectory: () => true,
+        birthtime: new Date(),
+        mtime: new Date(),
+        size: 100,
+      });
+      // Mirror the passing discovery tests: leave createReadStream unmocked so
+      // _resolveDescription fails gracefully (undefined) and discovery still fires.
+      mockReadFileSync.mockReturnValue('');
+      const mockRl = createMockRl();
+      mockCreateInterface.mockReturnValue(mockRl);
+
+      const discoveredHandler = vi.fn();
+      watcher.on('subagent:discovered', discoveredHandler);
+
+      watcher.start();
+      await flushAsyncScan();
+      mockRl.emit('close');
+      await vi.advanceTimersByTimeAsync(100);
+
+      expect(discoveredHandler).toHaveBeenCalled();
+      const info = discoveredHandler.mock.calls[0][0] as SubagentInfo;
+      expect(info.agentId).toBe('both');
+      // filePath points at the transcript, not the sidecar.
+      expect(info.filePath.endsWith('.jsonl')).toBe(true);
+    });
+  });
+
+  describe('Workflow-nested subagents (subagents/workflows/{wf}/)', () => {
+    // The Workflow tool nests its agents one level deeper than TUI Task subagents:
+    // subagents/workflows/{workflowId}/agent-{id}.jsonl — plus a sibling journal.jsonl.
+    // The flat subagents/ scan misses them; watchWorkflowDirs() descends one level.
+    function mockWorkflowLayout(wfFiles: string[]) {
+      mockReaddirSync.mockImplementation((path: string) => {
+        const p = String(path);
+        if (p.endsWith('wf_test')) return wfFiles;
+        if (p.endsWith('workflows')) return ['wf_test'];
+        if (p.endsWith('subagents')) return ['workflows']; // no flat agents, just the workflows dir
+        if (p.includes('session1')) return ['subagents'];
+        if (p.includes('project1')) return ['session1'];
+        return ['project1'];
+      });
+      mockStatSync.mockReturnValue({
+        isDirectory: () => true,
+        birthtime: new Date(),
+        mtime: new Date(),
+        size: 100,
+      });
+      const mockRl = createMockRl();
+      mockCreateInterface.mockReturnValue(mockRl);
+      return mockRl;
+    }
+
+    it('should discover an agent nested under subagents/workflows/{wf}/', async () => {
+      mockExistsSync.mockReturnValue(true); // sibling .jsonl exists for the meta
+      const mockRl = mockWorkflowLayout(['agent-wf1.jsonl', 'agent-wf1.meta.json', 'journal.jsonl']);
+
+      const discoveredHandler = vi.fn();
+      watcher.on('subagent:discovered', discoveredHandler);
+
+      watcher.start();
+      await flushAsyncScan();
+      mockRl.emit('close');
+      await vi.advanceTimersByTimeAsync(100);
+
+      expect(discoveredHandler).toHaveBeenCalled();
+      const info = discoveredHandler.mock.calls[0][0] as SubagentInfo;
+      expect(info.agentId).toBe('wf1');
+      expect(info.filePath.endsWith('.jsonl')).toBe(true);
+      expect(info.filePath).toContain('workflows');
+    });
+
+    it('should NOT register a workflow dir journal.jsonl as a bogus agent', async () => {
+      mockExistsSync.mockReturnValue(true);
+      const mockRl = mockWorkflowLayout(['agent-wf1.jsonl', 'journal.jsonl']);
+
+      watcher.start();
+      await flushAsyncScan();
+      mockRl.emit('close');
+      await vi.advanceTimersByTimeAsync(100);
+
+      const agents = watcher.getSubagents();
+      expect(agents).toHaveLength(1); // only agent-wf1, never "journal"
+      expect(agents.every((a) => a.agentId !== 'journal')).toBe(true);
+    });
+  });
+
   describe('Status Lifecycle', () => {
     it('should start agents as active', async () => {
       const mockRl = createMockRl();

test/tab-overflow.test.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { describe, expect, it } from 'vitest';
+
+function loadTabOverflowHelper() {
+  const context = vm.createContext({ window: {}, globalThis: {} });
+  const source = readFileSync(resolve(import.meta.dirname, '../src/web/public/constants.js'), 'utf8');
+  vm.runInContext(source, context, { filename: 'constants.js' });
+  return (context.window as { CodemanTabOverflow: { shouldAutoWrapTabs: (input: unknown) => boolean } })
+    .CodemanTabOverflow;
+}
+
+describe('tab overflow layout policy', () => {
+  it('auto-wraps desktop tabs when their rendered width exceeds available tab space', () => {
+    const helper = loadTabOverflowHelper();
+
+    expect(
+      helper.shouldAutoWrapTabs({
+        deviceType: 'desktop',
+        manualTwoRows: false,
+        tabCount: 18,
+        scrollWidth: 1400,
+        clientWidth: 760,
+      })
+    ).toBe(true);
+  });
+
+  it('does not auto-wrap when manual tall tabs are enabled or on mobile/tablet', () => {
+    const helper = loadTabOverflowHelper();
+
+    expect(
+      helper.shouldAutoWrapTabs({
+        deviceType: 'desktop',
+        manualTwoRows: true,
+        tabCount: 18,
+        scrollWidth: 1400,
+        clientWidth: 760,
+      })
+    ).toBe(false);
+    expect(
+      helper.shouldAutoWrapTabs({
+        deviceType: 'mobile',
+        manualTwoRows: false,
+        tabCount: 18,
+        scrollWidth: 1400,
+        clientWidth: 320,
+      })
+    ).toBe(false);
+  });
+
+  it('respects the boundary conditions (exact fit, +1 tolerance, and tabCount < 2)', () => {
+    const helper = loadTabOverflowHelper();
+    const base = { deviceType: 'desktop' as const, manualTwoRows: false, tabCount: 6 };
+
+    // Exact fit: no overflow, no wrap.
+    expect(helper.shouldAutoWrapTabs({ ...base, scrollWidth: 800, clientWidth: 800 })).toBe(false);
+    // Within the +1 sub-pixel tolerance: still no wrap.
+    expect(helper.shouldAutoWrapTabs({ ...base, scrollWidth: 801, clientWidth: 800 })).toBe(false);
+    // 2px over: wrap.
+    expect(helper.shouldAutoWrapTabs({ ...base, scrollWidth: 802, clientWidth: 800 })).toBe(true);
+    // A single overflowing tab must not wrap (need at least 2 to form a second row).
+    expect(helper.shouldAutoWrapTabs({ ...base, tabCount: 1, scrollWidth: 1400, clientWidth: 760 })).toBe(false);
+  });
+});

test/terminal-touch-tap.test.ts

@@ -0,0 +1,116 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { describe, expect, it, vi } from 'vitest';
+
+function loadTerminalUiHarness() {
+  const CodemanApp = function CodemanApp(this: any) {};
+  let now = 1_000;
+  const context = vm.createContext({
+    window: {},
+    CodemanApp,
+    console: { warn: vi.fn(), log: vi.fn() },
+    _crashDiag: { log: vi.fn() },
+    performance: { now: () => now },
+    requestAnimationFrame: (_fn: () => void) => 1,
+    setTimeout: (_fn: () => void) => 1,
+    Blob: function Blob() {},
+    URL: {
+      createObjectURL: () => 'blob:yield',
+      revokeObjectURL: () => {},
+    },
+    Worker: function Worker(this: any) {
+      this.postMessage = () => {};
+    },
+    MobileDetection: {
+      isTouchDevice: () => true,
+    },
+    DEC_SYNC_STRIP_RE: /\x1b\[\?2026[hl]/g,
+    TERMINAL_CHUNK_SIZE: 32 * 1024,
+  });
+
+  const code = readFileSync(resolve(import.meta.dirname, '../src/web/public/terminal-ui.js'), 'utf8');
+  vm.runInContext(code, context, { filename: 'terminal-ui.js' });
+
+  const app = new (CodemanApp as any)();
+  return {
+    app,
+    setNow: (value: number) => {
+      now = value;
+    },
+  };
+}
+
+function createElementHarness() {
+  const listeners = new Map<string, (ev: any) => void>();
+  return {
+    element: {
+      addEventListener: vi.fn((type: string, listener: (ev: any) => void) => {
+        listeners.set(type, listener);
+      }),
+    },
+    dispatch(type: string, event: any) {
+      listeners.get(type)?.(event);
+    },
+  };
+}
+
+describe('terminal touch tap mouse guard', () => {
+  it('suppresses browser trusted compatibility mouse events during the tap window', () => {
+    const { app } = loadTerminalUiHarness();
+    const { element, dispatch } = createElementHarness();
+    app.terminal = { element };
+
+    app._installMobileTapMouseGuard();
+    app._suppressTrustedTapMouseEvents();
+
+    const event = {
+      isTrusted: true,
+      preventDefault: vi.fn(),
+      stopImmediatePropagation: vi.fn(),
+    };
+    dispatch('mousedown', event);
+
+    expect(event.preventDefault).toHaveBeenCalledOnce();
+    expect(event.stopImmediatePropagation).toHaveBeenCalledOnce();
+  });
+
+  it('allows the app synthetic mouse event through the tap window', () => {
+    const { app } = loadTerminalUiHarness();
+    const { element, dispatch } = createElementHarness();
+    app.terminal = { element };
+
+    app._installMobileTapMouseGuard();
+    app._suppressTrustedTapMouseEvents();
+
+    const event = {
+      isTrusted: false,
+      preventDefault: vi.fn(),
+      stopImmediatePropagation: vi.fn(),
+    };
+    dispatch('mousedown', event);
+
+    expect(event.preventDefault).not.toHaveBeenCalled();
+    expect(event.stopImmediatePropagation).not.toHaveBeenCalled();
+  });
+
+  it('allows trusted mouse events after the tap window expires', () => {
+    const { app, setNow } = loadTerminalUiHarness();
+    const { element, dispatch } = createElementHarness();
+    app.terminal = { element };
+
+    app._installMobileTapMouseGuard();
+    app._suppressTrustedTapMouseEvents();
+    setNow(2_000);
+
+    const event = {
+      isTrusted: true,
+      preventDefault: vi.fn(),
+      stopImmediatePropagation: vi.fn(),
+    };
+    dispatch('mousedown', event);
+
+    expect(event.preventDefault).not.toHaveBeenCalled();
+    expect(event.stopImmediatePropagation).not.toHaveBeenCalled();
+  });
+});

test/workflow-run-watcher.test.ts

@@ -0,0 +1,415 @@
+/**
+ * Tests for WorkflowRunWatcher — parses wf_<runId>.json run-state into
+ * WorkflowRunInfo for the ultracode master-detail view.
+ *
+ * Drives the real discover→parse path against a synthetic on-disk fixture in a
+ * temp projects dir (never the shared singleton, never ~/.claude).
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { WorkflowRunWatcher } from '../src/workflow-run-watcher.js';
+import type { WorkflowRunInfo } from '../src/types/workflow-run.js';
+
+const PROJECT_HASH = '-home-arkon-default-claudeman';
+const SESSION_UUID = '388113c8-cd01-4e80-93a8-3be66ab1519b';
+const RUN_ID = 'wf_test1234-abc';
+
+/** A run JSON shaped like a real (killed) run: all three agent states + the bloat fields. */
+function sampleRunJson() {
+  return {
+    runId: RUN_ID,
+    timestamp: '2026-06-15T00:00:00.000Z',
+    taskId: 'task_abc',
+    // --- bloat fields that MUST be stripped ---
+    script: 'export const meta = {};\n'.repeat(5000), // ~110KB
+    scriptPath: '/tmp/whatever.js',
+    result: { plan: { huge: 'object' } },
+    logs: ['line1', 'line2'],
+    // --- real fields ---
+    agentCount: 3,
+    durationMs: 795173,
+    summary: 'Deep adversarial review of open PRs',
+    workflowName: 'review-open-prs',
+    status: 'killed',
+    error: 'user stopped the task',
+    startTime: 1781466999000,
+    defaultModel: 'claude-opus-4-8[1m]',
+    totalTokens: 109703,
+    totalToolCalls: 44,
+    phases: [
+      { title: 'Review', detail: 'one deep reviewer per PR' },
+      { title: 'Probe', detail: 'targeted security/correctness probes' },
+      { title: 'Verify', detail: 'adversarially verify each finding' },
+    ],
+    workflowProgress: [
+      { type: 'workflow_phase', index: 0, phaseIndex: 1, phaseTitle: 'Review' },
+      {
+        type: 'workflow_agent',
+        index: 1,
+        label: 'probe:dompurify-config',
+        phaseIndex: 2,
+        phaseTitle: 'Probe',
+        agentId: 'a6c0e282c3f5ac0bf',
+        model: 'claude-opus-4-8[1m]',
+        state: 'done',
+        startedAt: 1781467000002,
+        queuedAt: 1781466999962,
+        attempt: 1,
+        lastToolName: 'StructuredOutput',
+        lastToolSummary: 'Does the profile setting make the allowlist dead config',
+        promptPreview: 'You are reviewing a pull request...',
+        lastProgressAt: 1781467524143,
+        tokens: 104703,
+        toolCalls: 41,
+        durationMs: 524140,
+        resultPreview: '{"verdict":"concern"}',
+      },
+      {
+        type: 'workflow_agent',
+        index: 2,
+        label: 'review:pr-127',
+        phaseIndex: 1,
+        phaseTitle: 'Review',
+        agentId: 'a1234567890abcdef',
+        model: 'claude-opus-4-8[1m]',
+        state: 'progress',
+        startedAt: 1781467010000,
+        queuedAt: 1781466999970,
+        attempt: 1,
+        lastToolName: 'Read',
+        promptPreview: 'Review PR 127...',
+        lastProgressAt: 1781467600000,
+        tokens: 5000,
+        toolCalls: 3,
+      },
+      {
+        type: 'workflow_agent',
+        index: 3,
+        label: 'verify:finding-x',
+        phaseIndex: 3,
+        phaseTitle: 'Verify',
+        model: 'claude-opus-4-8[1m]',
+        state: 'start',
+        queuedAt: 1781466999980,
+        promptPreview: 'Verify finding x...',
+        lastProgressAt: 1781466999980,
+      },
+    ],
+  };
+}
+
+describe('WorkflowRunWatcher', () => {
+  let projectsDir: string;
+  let watcher: WorkflowRunWatcher;
+
+  beforeEach(async () => {
+    projectsDir = await mkdtemp(join(tmpdir(), 'wfw-test-'));
+    const workflowsDir = join(projectsDir, PROJECT_HASH, SESSION_UUID, 'workflows');
+    await mkdir(workflowsDir, { recursive: true });
+    await writeFile(join(workflowsDir, `${RUN_ID}.json`), JSON.stringify(sampleRunJson()), 'utf-8');
+    watcher = new WorkflowRunWatcher(projectsDir);
+  });
+
+  afterEach(async () => {
+    watcher.stop();
+    await rm(projectsDir, { recursive: true, force: true });
+  });
+
+  /** Start the watcher and resolve with the first discovered run. */
+  function firstRun(): Promise<WorkflowRunInfo> {
+    return new Promise<WorkflowRunInfo>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('timed out waiting for run_discovered')), 5000);
+      watcher.once('run_discovered', (info: WorkflowRunInfo) => {
+        clearTimeout(timer);
+        resolve(info);
+      });
+      watcher.start();
+    });
+  }
+
+  it('discovers and parses a run, deriving session/project from the path', async () => {
+    const info = await firstRun();
+    expect(info.runId).toBe(RUN_ID);
+    expect(info.workflowName).toBe('review-open-prs');
+    expect(info.status).toBe('killed');
+    expect(info.error).toBe('user stopped the task');
+    expect(info.sessionUuid).toBe(SESSION_UUID);
+    expect(info.projectHash).toBe(PROJECT_HASH);
+    expect(info.totalTokens).toBe(109703);
+    expect(info.totalToolCalls).toBe(44);
+  });
+
+  it('keeps only workflow_agent entries (drops workflow_phase markers)', async () => {
+    const info = await firstRun();
+    expect(info.agents).toHaveLength(3);
+    expect(info.phases).toHaveLength(3);
+  });
+
+  it('STRIPS the heavyweight script/scriptPath/result/logs fields', async () => {
+    const info = await firstRun();
+    const asAny = info as unknown as Record<string, unknown>;
+    expect('script' in asAny).toBe(false);
+    expect('scriptPath' in asAny).toBe(false);
+    expect('result' in asAny).toBe(false);
+    expect('logs' in asAny).toBe(false);
+    // The serialized run that reaches a client must be small.
+    expect(JSON.stringify(info).length).toBeLessThan(5000);
+  });
+
+  it('carries tokens/toolCalls/durationMs on a done agent', async () => {
+    const info = await firstRun();
+    const done = info.agents.find((a) => a.state === 'done')!;
+    expect(done.agentId).toBe('a6c0e282c3f5ac0bf');
+    expect(done.tokens).toBe(104703);
+    expect(done.toolCalls).toBe(41);
+    expect(done.durationMs).toBe(524140);
+    expect(done.resultPreview).toBeDefined();
+  });
+
+  it('omits agentId/tokens/toolCalls/durationMs on a start (queued) agent', async () => {
+    const info = await firstRun();
+    const queued = info.agents.find((a) => a.state === 'start')!;
+    expect(queued.agentId).toBeUndefined();
+    expect(queued.tokens).toBeUndefined();
+    expect(queued.toolCalls).toBeUndefined();
+    expect(queued.durationMs).toBeUndefined();
+    expect(queued.label).toBe('verify:finding-x');
+  });
+
+  it('a progress agent has tokens but no durationMs (live discriminator)', async () => {
+    const info = await firstRun();
+    const running = info.agents.find((a) => a.state === 'progress')!;
+    expect(running.tokens).toBe(5000);
+    expect(running.toolCalls).toBe(3);
+    expect(running.durationMs).toBeUndefined();
+  });
+
+  it('phase join: agent.phaseIndex-1 indexes run.phases', async () => {
+    const info = await firstRun();
+    for (const agent of info.agents) {
+      expect(info.phases[agent.phaseIndex - 1].title).toBe(agent.phaseTitle);
+    }
+  });
+
+  it('exposes the run via getAllRuns/getRun after discovery', async () => {
+    await firstRun();
+    expect(watcher.getAllRuns()).toHaveLength(1);
+    expect(watcher.getRun(RUN_ID)?.runId).toBe(RUN_ID);
+    expect(watcher.getStats().agentCount).toBe(3);
+  });
+
+  it('getRecentRunSummaries omits agents[] (lightweight snapshot)', async () => {
+    await firstRun();
+    const summaries = watcher.getRecentRunSummaries(100000);
+    expect(summaries).toHaveLength(1);
+    expect('agents' in summaries[0]).toBe(false);
+    expect(summaries[0].runId).toBe(RUN_ID);
+    expect(summaries[0].agentCount).toBe(3);
+  });
+});
+
+/**
+ * In-flight runs: the Workflow runtime writes the completion wf_<id>.json only when
+ * a run FINISHES, so while it is live the only on-disk state is its
+ * subagents/workflows/wf_<id>/ transcript dir. The watcher synthesizes a minimal
+ * ACTIVE run from that dir so the floating window pops DURING the run.
+ */
+describe('WorkflowRunWatcher — in-flight (live) runs', () => {
+  const LIVE_RUN_ID = 'wf_live5678-xyz';
+  let projectsDir: string;
+  let liveDir: string;
+  let watcher: WorkflowRunWatcher;
+
+  beforeEach(async () => {
+    projectsDir = await mkdtemp(join(tmpdir(), 'wfw-live-'));
+    liveDir = join(projectsDir, PROJECT_HASH, SESSION_UUID, 'subagents', 'workflows', LIVE_RUN_ID);
+    await mkdir(liveDir, { recursive: true });
+    // Two agents started; one already produced a result (journal `result` line).
+    await writeFile(
+      join(liveDir, 'agent-aaa111.meta.json'),
+      JSON.stringify({ agentType: 'workflow-subagent' }),
+      'utf-8'
+    );
+    await writeFile(join(liveDir, 'agent-aaa111.jsonl'), '{"type":"assistant"}\n', 'utf-8');
+    await writeFile(
+      join(liveDir, 'agent-bbb222.meta.json'),
+      JSON.stringify({ agentType: 'workflow-subagent' }),
+      'utf-8'
+    );
+    await writeFile(join(liveDir, 'agent-bbb222.jsonl'), '{"type":"assistant"}\n', 'utf-8');
+    await writeFile(
+      join(liveDir, 'journal.jsonl'),
+      '{"type":"started","agentId":"aaa111"}\n{"type":"started","agentId":"bbb222"}\n{"type":"result","agentId":"aaa111","result":{}}\n',
+      'utf-8'
+    );
+    watcher = new WorkflowRunWatcher(projectsDir);
+  });
+
+  afterEach(async () => {
+    watcher.stop();
+    await rm(projectsDir, { recursive: true, force: true });
+  });
+
+  function firstRun(): Promise<WorkflowRunInfo> {
+    return new Promise<WorkflowRunInfo>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('timed out waiting for run_discovered')), 5000);
+      watcher.once('run_discovered', (info: WorkflowRunInfo) => {
+        clearTimeout(timer);
+        resolve(info);
+      });
+      watcher.start();
+    });
+  }
+
+  it('synthesizes an ACTIVE run from the transcript dir when no completion file exists', async () => {
+    const info = await firstRun();
+    expect(info.runId).toBe(LIVE_RUN_ID);
+    expect(info.status).toBe('running'); // active → frontend pops a floating window
+    expect(info.sessionUuid).toBe(SESSION_UUID);
+    expect(info.projectHash).toBe(PROJECT_HASH);
+    expect(info.agents).toHaveLength(2);
+    expect(info.agentCount).toBe(2);
+    expect(info.lastActivityAt).toBeGreaterThan(0);
+  });
+
+  it('preserves agentId per slot (so the card→transcript click join still works)', async () => {
+    const info = await firstRun();
+    const ids = info.agents.map((a) => a.agentId).sort();
+    expect(ids).toEqual(['aaa111', 'bbb222']);
+  });
+
+  it('marks an agent done/progress from journal result lines', async () => {
+    const info = await firstRun();
+    expect(info.agents.find((a) => a.agentId === 'aaa111')!.state).toBe('done'); // has a result line
+    expect(info.agents.find((a) => a.agentId === 'bbb222')!.state).toBe('progress'); // started, no result yet
+  });
+
+  it('counts the live run as running in getStats', async () => {
+    await firstRun();
+    expect(watcher.getStats().running).toBe(1);
+  });
+
+  it('does NOT surface a live dir that has no agent files yet', async () => {
+    const empty = join(projectsDir, PROJECT_HASH, SESSION_UUID, 'subagents', 'workflows', 'wf_empty0000-noo');
+    await mkdir(empty, { recursive: true });
+    await firstRun(); // resolves on the real (populated) live run
+    // The empty run id must never enter the cache.
+    expect(watcher.getRun('wf_empty0000-noo')).toBeUndefined();
+    expect(watcher.getAllRuns().map((r) => r.runId)).toEqual([LIVE_RUN_ID]);
+  });
+
+  it('a completion wf_*.json supersedes the live dir for the same runId (real status wins)', async () => {
+    const workflowsDir = join(projectsDir, PROJECT_HASH, SESSION_UUID, 'workflows');
+    await mkdir(workflowsDir, { recursive: true });
+    await writeFile(
+      join(workflowsDir, `${LIVE_RUN_ID}.json`),
+      JSON.stringify({ runId: LIVE_RUN_ID, status: 'completed', durationMs: 1234, phases: [], workflowProgress: [] }),
+      'utf-8'
+    );
+    const info = await firstRun();
+    expect(info.runId).toBe(LIVE_RUN_ID);
+    expect(info.status).toBe('completed'); // real completion file wins, not synthesized 'running'
+    expect(info.durationMs).toBe(1234);
+    // Only one cached entry for the runId — no live/real duplication.
+    expect(watcher.getAllRuns()).toHaveLength(1);
+  });
+});
+
+/**
+ * Live ENRICHMENT: while a run is in-flight the watcher now parses each agent
+ * transcript for real tokens/tool-calls/model, maps state→colour from the journal,
+ * and derives the run name/summary/phases from the persisted script — so the
+ * floating window/panel show real data mid-run instead of "0 tok / agent N".
+ */
+describe('WorkflowRunWatcher — live enrichment (tokens/state/name)', () => {
+  const RUN = 'wf_enrich01-abc';
+  let projectsDir: string;
+  let watcher: WorkflowRunWatcher;
+
+  beforeEach(async () => {
+    projectsDir = await mkdtemp(join(tmpdir(), 'wfw-enrich-'));
+    const sessionDir = join(projectsDir, PROJECT_HASH, SESSION_UUID);
+    const liveDir = join(sessionDir, 'subagents', 'workflows', RUN);
+    await mkdir(liveDir, { recursive: true });
+    const scriptsDir = join(sessionDir, 'workflows', 'scripts');
+    await mkdir(scriptsDir, { recursive: true });
+
+    // Agent aaa: a user prompt + two assistant turns with usage + two tool_use blocks.
+    await writeFile(
+      join(liveDir, 'agent-aaa.jsonl'),
+      [
+        '{"type":"user","message":{"role":"user","content":"Audit the docs"}}',
+        '{"type":"assistant","message":{"model":"claude-opus-4-8","usage":{"input_tokens":1000,"output_tokens":40},"content":[{"type":"tool_use","name":"Bash"}]}}',
+        '{"type":"assistant","message":{"model":"claude-opus-4-8","usage":{"input_tokens":2000,"cache_read_input_tokens":500,"output_tokens":80},"content":[{"type":"tool_use","name":"Edit"},{"type":"text","text":"done"}]}}',
+      ].join('\n') + '\n',
+      'utf-8'
+    );
+    await writeFile(join(liveDir, 'agent-aaa.meta.json'), JSON.stringify({ agentType: 'workflow-subagent' }), 'utf-8');
+    // Agent bbb: started, no result yet, minimal transcript (no usage).
+    await writeFile(join(liveDir, 'agent-bbb.jsonl'), '{"type":"assistant","message":{"content":[]}}\n', 'utf-8');
+    // bbb starts BEFORE aaa, so journal launch order ['bbb','aaa'] differs from the
+    // old alphabetical sort ['aaa','bbb'] — the ordering assertion below is adversarial.
+    await writeFile(
+      join(liveDir, 'journal.jsonl'),
+      '{"type":"started","agentId":"bbb"}\n{"type":"started","agentId":"aaa"}\n{"type":"result","agentId":"aaa","result":{}}\n',
+      'utf-8'
+    );
+    // Persisted script — name from filename, summary/phases from the meta literal.
+    await writeFile(
+      join(scriptsDir, `my-cool-workflow-${RUN}.js`),
+      "export const meta = {\n  name: 'my-cool-workflow',\n  description: 'Audit and update the docs',\n  phases: [ { title: 'Plan', detail: 'plan it' }, { title: 'Do', detail: 'do it' } ],\n}\n",
+      'utf-8'
+    );
+    watcher = new WorkflowRunWatcher(projectsDir);
+  });
+
+  afterEach(async () => {
+    watcher.stop();
+    await rm(projectsDir, { recursive: true, force: true });
+  });
+
+  function firstRun(): Promise<WorkflowRunInfo> {
+    return new Promise<WorkflowRunInfo>((resolve, reject) => {
+      const t = setTimeout(() => reject(new Error('timed out')), 5000);
+      watcher.once('run_discovered', (info: WorkflowRunInfo) => {
+        clearTimeout(t);
+        resolve(info);
+      });
+      watcher.start();
+    });
+  }
+
+  it('derives workflowName/summary/phases from the live script file', async () => {
+    const info = await firstRun();
+    expect(info.workflowName).toBe('my-cool-workflow');
+    expect(info.summary).toBe('Audit and update the docs');
+    expect(info.phases.map((p) => p.title)).toEqual(['Plan', 'Do']);
+  });
+
+  it('parses per-agent tokens (last usage-bearing message) + tool-call counts from the transcript', async () => {
+    const info = await firstRun();
+    const aaa = info.agents.find((a) => a.agentId === 'aaa')!;
+    expect(aaa.tokens).toBe(2580); // last turn: 2000 in + 500 cache + 80 out
+    expect(aaa.toolCalls).toBe(2); // Bash + Edit
+    expect(aaa.model).toBe('claude-opus-4-8');
+    expect(aaa.promptPreview).toBe('Audit the docs');
+  });
+
+  it('maps state to done (→green) / progress (→yellow) from the journal', async () => {
+    const info = await firstRun();
+    expect(info.agents.find((a) => a.agentId === 'aaa')!.state).toBe('done');
+    expect(info.agents.find((a) => a.agentId === 'bbb')!.state).toBe('progress');
+  });
+
+  it('orders agents by journal launch order (NOT alphabetical) and sums run-level totals', async () => {
+    const info = await firstRun();
+    // bbb started first in the journal though it sorts after aaa — launch order wins.
+    expect(info.agents.map((a) => a.agentId)).toEqual(['bbb', 'aaa']);
+    expect(info.agents[0].label).toBe('agent 1'); // = bbb, the first-launched
+    expect(info.totalToolCalls).toBe(2);
+    expect(info.totalTokens).toBe(2580);
+  });
+});