Skip to content

Ensemble v5.7 verification — persistent modes, native key ownership, carets, statusline, and wizard memory flow ​

Spec: #90. Tickets #91–#95 were integrated on integration/ensemble-v5.7; #95 is the docs and full-verification pass.

Environment: Node v26.12.1, OpenCode v2.2.5 (pinned plugin types 2.2.1), Linux/tmux, 160×80 fake TUI and 120×40 real TUI. The fake provider used its default 60 ms chunk delay for the deterministic queue/live probes. The real scenario used the host model catalog and exercised the full wizard, group chat, completions, and native session path rather than skipping.

v5.7 behavior delivered ​

  • Persistent mode. Normal, Insert, Visual, and Command are global interaction states. Focus moves, overlay opens/closes, wizard-step changes, and surface changes never assign a mode. Only explicit mode keys change it; Enter opens/focuses a target but never enters Insert. Command records its return mode, Visual stays self-contained, and leaving Ensemble resets Normal.
  • Esc ladder and Ctrl+G. Insert/Visual/Command → Normal. From Normal, Esc clears search/filter, leaves the composer, backs out of a field, overlay, or dialog, or is a no-op. A wizard text field's first Esc goes to field Normal; the second cancels, with a dirty-draft confirm. Ctrl+G leaves the focused editor and sets Normal.
  • One caret model. Composer, settings fields, wizard/prompt fields, and the command/search input all map to a non-blinking block caret in Normal and a non-blinking line caret in Insert, Visual, and Command. An unfocused editor paints none. Insert → Normal keeps the editor focused; only leaving the editor or its context blurs it.
  • Native key ownership. Raw keys require both the newest page mount and the Ensemble route. Leaving blurs every editor, clears command/leader/overlay/ pending state, sets Normal, and keeps the page mounted for F2. A hidden Ensemble page never consumes native keys, so letters and / work in the native prompt immediately after :q or Space q.
  • Typed statusline. Row one is built from typed segments: filled mode chip, context, selection, git, position, pending chord, and catalog hints. Hint keys and git/position use accent, descriptions are muted, and feedback is colored. Row two carries :// or the latest message. The mode chip and command input are never truncated; hints drop first on narrow bars.
  • Chrome separators. Non-content chrome joins with a faint │ and one space, with ASCII | as the fallback. This covers the statusline, hints, footers, rail metadata, work rows, and activity lines. Chat content is not rewritten.
  • Leader label. The rail stays transparent. LEADER is inline text after a faint │ separator on the agent's name row, colored with the leader accent and bold. There is no badge box, padding row, or opaque cutout. The title branch follows on the next row.
  • Wizard navigation and memories. n next, N previous, Enter next/confirm, and Esc cancel. Text steps open in the arrival mode; there is no auto-Insert. The memories step is an ordered list with a add, e edit, x delete, and j/k selection. Enter saves one memory, clears an add field while keeping it focused, and keeps an edit's text. Settings memory add/edit uses the same persistent-field flow.

Root causes and fixes ​

  1. Native key trap after leaving Ensemble (#91). The host keeps the Ensemble page mounted when it navigates to the native session. The raw renderer listener checked only isActive(token), so the hidden page still consumed keys; : opened Command mode in the hidden page and called stopPropagation, while / was swallowed the same way (Esc first did not reliably unlock typing). page-activation.ts now exposes ownsRawKeys(token, routeActive) and the app requires the visible Ensemble route in addition to the newest mount. clearInteractionForLeave() blurs the composer and every overlay editor, clears command/leader/completion/picker/ confirm/result/approval state, resets Normal, and keeps the page mounted for F2. The fake and real live checks type immediately after quitting and prove / reaches the native prompt.
  2. Mode coupled to focus and context (#92). The reducer assigned normal in focus.set, overlay.set, field close, wizard transitions, and parts of the Esc ladder, and Enter forced Insert. Those assignments were removed. Focus/overlay/step changes now only move focus (and blur/focus the relevant editor); mode changes are explicit events. Wizard step arrival focuses a text field without entering Insert, and an Insert list step is visibly inert (no text target) while structural keys still act.
  3. No caret in Normal (#92). Insert → Normal returned a blur-editor intent, so the textarea lost focus and OpenTUI painted no cursor. The reducer now keeps the editor focused on Insert → Normal and the adapter sets cursorStyle from a pure mode mapping: non-blinking block in Normal, non-blinking line in Insert/Visual/Command. Blur happens only when leaving the editor or context. The same mapping is applied to composer, settings, wizard/prompt, and command/search editors.
  4. Flat, dot-separated statusline (#93). The bar was one string with one color and · hints. statusline.ts now builds typed segments/parts with tones and a mode-chip role; components.tsx renders chip backgrounds with contrast text and faint separators. Fitting keeps the mode chip and drops hints from the right before core segments. separators.ts owns the shared │/ASCII | grammar and a legacy-dot splitter for migration; statusline, footers, rail metadata, work rows, and activity lines use it.
  5. Invisible leader badge (#93). The badge used fg={colors.bg} as a cutout; on transparent themes that was transparent and the text vanished. theme.ts uses the detected terminal background for the cutout, and falls back to automatic black/white contrast from the accent when no surface is guaranteed. The extra connector stem was removed and one blank row added under the leader row.
  6. Wizard memory blob and implicit navigation (#94). WizardDraft.memories became string[], and pure addWizardMemory/updateWizardMemory/ deleteWizardMemory/clampWizardMemoryCursor/wizardMemorySaveList helpers drive a one-by-one list. The step uses a/e/x, j/k, n/N, Enter, and Esc; the add/edit field is Insert and persistent. Creation saves each list entry as its own memory and skips an empty list. Settings memory add/edit shares the same persistent-field behavior, including after an edit.

Key regression coverage ​

RegressionUnit seamLive evidenceResult
Quit → native typing → /page-activation.test.ts route gate; interaction route.leave cleanupfake: :q, immediate letters, native slash menu, F2; real: Space q, immediate letters, native slash menupass
Mode persistence across wizard stepsinteraction.test.ts, wizard.test.ts step arrivalfake: roster/chat Enter keeps Normal; wizard text/list steps keep arrival mode; empty live N/npass
Block/line caret across every editorcaretStyleForMode/caretForEditor; focus-intent test for composer, settings, prompt, wizardtext capture cannot observe caret shape; live mode labels/hints confirm the transitionsmapper pass; rendered shape manual
Statusline segments and │ separatorsstatusline.test.ts, separators.test.ts, chrome.test.ts, workrows.test.tsfake help/search/settings/work rows read │; statusline hints and rows assertedpass
Badge cutout/contrasttheme.test.ts opaque-surface, cutout, light/dark fallbackfake confirms LEADER and one blank row before the title branch; text capture cannot see colorhelper pass; color manual
Wizard n/N/Esckeymap.test.ts, wizard.test.ts, interaction cancel intentsfake n/N step round trip and dirty cancel; empty live N/n and discard confirmpass
One-by-one memorieswizard.test.ts add/edit/delete/clamp/savefake add, edit, delete, exact snapshot order ["Likes deterministic fixtures v2","Uses pnpm"]; empty list writes zero memoriespass
Settings memory paritysettings/keymap catalog testsfake add field stays in Insert and clears; edit stays focused; exact snapshot update, provenance, no duplicate rowspass

Verification commands ​

Pre-merge (branch feat/v57-95) ​

CommandResult
git diff --checkexit 0, no whitespace errors
npm run checkexit 0
npm test559 passed, 0 failed, 0 skipped
npm run test:live:fake4 passes total; one intermediate failure investigated and fixed (below); final two consecutive passes
npm run test:live:fake:emptypass
npm run test:livepass after two live-script expectation fixes (below)

Repeat live runs ​

  • Fake live pass 1: before the documentation/help edit.
  • Fake live failure: timed out after 10s waiting for filtered help counts both quit rows. The new help policy row made the quit fuzzy filter return four matches instead of two (the new native-quit row, plus an incidental fuzzy match in the badge prose). The probe's exact count was coupled to help prose, not to behavior. It now filters Space q, which deterministically selects the three quit-path rows (Esc never leaves, :q / Space q, leader Space q), and asserts match 1/3 → match 2/3. No sleep was added.
  • Fake live passes 2 and 3: after the probe fix; both passed end to end.
  • Fake live pass 4: final repeat on the same tree; passed.
  • Empty live: passed, including the one-by-one empty list, n/N, explained empty model catalog, dirty-cancel confirm, and zero-write assertion.
  • Real live failure 1: leaving the wizard leaves Normal behind. The real script still assumed a wizard text step opens in Insert. v5.7 keeps the arrival mode, so the script now presses i explicitly; it also uses Ctrl+G rather than Esc while the onboarding run is streaming, because the host can swallow Esc in that window.
  • Real live failure 2: move-home prompt dismissed. The confirm was opened while the wizard still carried Insert. The first Esc correctly changed Insert → Normal rather than closing the dialog. The script now normalizes with Ctrl+G and rejects the confirm with its own n key.
  • Real live pass 3: passed the whole scenario, including the new immediate native typing and / probe.

Documentation changes ​

  • README.md: persistent mode/caret/Ctrl+G rules, native hand-back and F2, typed statusline and │ separators, wizard n/N/Esc and one-by-one memories, settings memory parity, v5.7 verification link, and explicit macOS/Herdr unverified wording.
  • docs/implementation.md: corrected the stale wizard description (no more “Esc goes back a step/auto-Insert”), added the v5.7 mode, caret, native key ownership, statusline, separator, badge, and memory sections, and expanded known limitations.
  • GLOSSARY.md: defines Mode as the persistent global state and notes that quitting hands the keyboard to the native prompt with F2 returning.
  • src/v2/tui/help.ts + help.test.ts: fixed the wizard Esc wording (Esc cancels; n/N navigate), and documented persistent mode, the block/line caret contract, native key hand-back (including /), │/ASCII separators, LEADER cutout/contrast, and wizard/settings memory persistence. The new test fails before the entries exist and covers each contract.
  • scripts/README.md: describes the v5.7 fake/empty coverage and the native quit// probe.
  • scripts/live-check.sh: explicit Insert entry and mode-persistence checks in both real wizards, mode reset after wizard completion, and the immediate native typing// check after Space q.
  • scripts/lib/live-harness.sh: deterministic help filter probe changed from the prose-coupled quit count to Space q.

Static stale-reference check ​

sh
grep -rnE '(go back one step|previous step|forces? insert|auto-?insert|implicit|Enter (forces|enters) Insert)' \
  README.md GLOSSARY.md docs/implementation.md src/v2/tui/help.ts scripts/README.md

The only remaining match is the workspace leader step preselecting a member chosen in the previous step; it describes navigation between wizard configurations, not mode. The v5.7 change is described explicitly as “Enter no longer forces Insert”, “never auto-Insert”, and “N previous”.

sh
grep -rn ' · ' README.md GLOSSARY.md docs/implementation.md scripts/README.md src/v2/tui/help.ts

Remaining dots are architecture-diagram node lists, help section titles (Composer · Insert), and prose. No documentation claims that statusline or chrome separators use ·; the statusline, hints, footers, rail metadata, work rows, and activity lines use │.

Remaining limits ​

  • macOS/Herdr was not verified. This environment is Linux/tmux. The collision-free shortcut intent, the badge cutout on that host, and Esc/Ctrl+G behavior under a live native run remain a manual check.
  • Actual caret shape and badge color are not observable in tmux text capture. The pure mode-to-caret and cutout/contrast helpers are unit-tested; no headless renderer pixel probe was performed. A desktop-terminal check of the block/line cursor and the light/dark badge remains a manual step.
  • Real mouse drag remains manual. tmux does not reliably inject drag gestures; pane-bounded normalization/copy is unit-covered.
  • The host still owns disposal of old plugin pages. The route gate prevents stale key ownership but cannot force disposal.
  • The large TUI component was not split. app.tsx remains a follow-up.
  • The statusline help probe still depends on generated help prose for its exact match 1/3 count. The query was chosen to be semantically stable; future help entries that match Space q must update this probe deliberately.

Post-merge verification ​

git merge integration/ensemble-v5.7 reported Already up to date at integration tip 485bdc4 (no conflicts, no source changes). The full matrix was rerun on the merged tree:

CommandResult
git diff --checkexit 0
npm run checkexit 0
npm test559 passed, 0 failed, 0 skipped
npm run test:live:fakepass twice (post-merge runs 1 and 2)
npm run test:live:fake:emptypass
npm run test:livepass with the real host catalog

The post-merge reruns used the same deterministic fake/empty harnesses and the same real-provider scenario as the pre-merge runs. No new flakes appeared.

2026-11-05 v5.7 code-review fix pass ​

Branch fix/v57-review, based on integration/ensemble-v5.7 at 95d94d4. This pass is scoped to the review findings; it adds no product features and does not modify or close the issues.

Findings and fixes ​

  1. Command/search caret and editing. CommandInput now carries a cursor, and line-editor.ts is a pure insertion/backspace/delete/motion core. Row two draws a visible line caret for ://, and the app handles Left/Right, Home/End, Backspace, Delete, and insertion at the cursor. History recall and Tab completion still work; both put the cursor at the end of the recalled/completed text. Tests: line-editor.test.ts, statusline.test.ts caret-layout cases, interaction.test.ts command cursor cases, and a live edit probe in scripts/live-check-fake.sh.
  2. Command input truncation. Row two renders the prompt cell separately from the scrolling input. commandCaretLayout drops leading text until the caret fits and accounts for double-width cells; the input never relies on terminal truncation, and the prompt is fixed. fitStatuslineSegments now returns only the mandatory mode chip for zero or negative widths instead of leaking every segment into a truncating renderer. Tests: statusline.test.ts zero/negative-width and caret-layout cases.
  3. Separator coverage. The work-row footer now joins through chromeJoin; surfaceTitle, settings header/tab/section/provenance/model labels, picker/help/composer footer lines, wizard title/filter/memory lines, and the activity overflow use the shared │ grammar. ChromeText paints the separators faint and keeps message content untouched. Tests: separators.test.ts helper and static app-source checks, settings.test.ts, skills.test.ts, and memories.test.ts.
  4. GLOSSARY. The Mode and Leader key entries are concise domain definitions. Behavior rules remain in README, docs/implementation.md, and the generated help catalog.
  5. Wizard memory leaks. isWizardMemoryStep is the pure gate. The app guards field opening, add/edit/delete, submit, close, the runDialogAction memory cases, and the dialogDescriptor memory-editor branch. On a non-memory step, a/e/x are inert and Enter reaches the step action instead of a stale field. Tests: wizard.test.ts gate and static app checks.
  6. Overlay close focus. The interaction state remembers the editor that owned the caret when an overlay opened. Closing a picker, prompt, confirm, or result in Insert restores that editor; Normal close keeps its existing focus. The app's overlay effect now dispatches the reducer event and applies its focus intent instead of keeping only the state. Tests: interaction.test.ts picker/prompt/confirm close and Normal-close cases; app-wiring.test.ts pins the adapter dispatch.
  7. Insert-without-target status. The statusline no longer suppresses git, position, selection size, or the pending chord. Insert without a target adds a muted no text target notice and replaces the typing hints with Esc normal. Tests: statusline.test.ts segment order, app-wiring.test.ts static check, and updated fake/empty/real live assertions.
  8. Render evidence. A headless OpenTUI probe (createTestRenderer) mounted real TextareaRenderable and badge cells:
    • Normal caret: visible=true, style=block, blinking=false.
    • Insert caret: visible=true, style=line, blinking=false.
    • Blurred editor: visible=false.
    • Badge cutout (accelerator #55aaff, opaque surface #222222): glyph foreground [34,34,34,255], background [85,170,255,255]; both match the expected surface/accent colors.
    • Automatic fallback (white accent, no opaque surface): glyph foreground [0,0,0,255], background [255,255,255,255].
    • Light cutout (#0055aa on #f5f5f5): glyph foreground [245,245,245,255], background [0,85,170,255]. The probe script was temporary and is not committed; its output is recorded here as the render check that text capture cannot provide.
  9. Review scope kept with rationale. Settings memory add still clears the filter and selects the newly created memory by id once the snapshot arrives. This is required for deterministic cursor placement after an add; a position-based guess is racy across the event refresh and the explicit mutation refresh. The leader chip keeps its own theme role and recolor as part of the colored statusline, not as an unrelated theme change.

Low-risk cleanups ​

  • Removed unused STATUSLINE_SEPARATOR.
  • Replaced the fake CommandInput used for help filtering with StatuslineRow2Input.
  • Extracted the repeated Insert-without-target suppression into one notice path.
  • Kept statuslineRow1; tests and the segment formatter still share it.
  • Did not unify the wizard/settings memory field helpers: they own different renderable refs, signals, and async save paths, so a shared helper would add indirection without removing behavior.
  • Deliberately out of scope: the large app.tsx split and the nested insert.enter switch rewrite remain follow-ups.

Verification commands and results ​

Pre-merge on fix/v57-review:

CommandResult
git diff --checkexit 0
npm run checkexit 0
npm test577 passed, 0 failed, 0 skipped
npm run test:live:fakepass twice consecutively (review runs 1 and 2)
npm run test:live:fake:emptypass
npm run test:livepass with the real host catalog

Remaining limits ​

  • macOS/Herdr remains unverified; this environment is Linux/tmux.
  • Real mouse-drag automation remains manual.
  • The headless probe verifies cursor state and badge cell colors, not every terminal's font rendering of the caret glyph.
  • app.tsx remains a single large component; this pass intentionally did not split it.
  • The command-line live edit probe waits for Normal after cancel before reopening :; without that wait the host key queue can deliver : before the Escape transition lands.

Post-merge rerun ​

git merge integration/ensemble-v5.7 --no-edit reported Already up to date at 95d94d4; the integration tip had not moved since the branch base. The full matrix was rerun on the committed review-fix tree:

CommandResult
git diff --checkexit 0
npm run checkexit 0
npm test577 passed, 0 failed, 0 skipped
npm run test:live:fakepass (post-merge run 1)
npm run test:live:fakepass (post-merge run 2)
npm run test:live:fake:emptypass
npm run test:livepass with the real host catalog

Review fix commit: db7b893 (fix(v57-review): address code-review findings).

Post-verification visual fixes (#96) ​

Two live visual regressions were found after v5.7:

  • The rail painted the opaque cutout surface behind the entire pane, so it was black instead of transparent. The rail now stays transparent; only the LEADER glyphs use the detected terminal default background (or automatic contrast when detection fails).
  • The statusline/chrome used nested <span> children whose fg/bg were lost on this OpenTUI build; passing StyledText through the JSX content prop rendered [object Object]. Both now set native StyledText chunks through the text renderable's content property after mount, preserving mode-chip backgrounds, key colors, muted descriptions, and faint separators.

Verified after the fix: npm run check 0; npm test 579/579; fake live, empty live, and real live passed. Regression guards pin the StyledText ref path and the transparent rail.

Post-verification statusline refinements (#97) ​

  • Mode chip gained one cell of inner padding on each side; Normal uses black text on the muted grey chip. Other modes keep automatic contrast.
  • The leader badge no longer reserves a blank row; terminal cells cannot render a half-row gap, so the title branch starts immediately below.
  • Git metadata is split into semantic tones: muted git label, faint punctuation, info/blue branch, warn dirty mark, good ahead, bad behind. Palette gained an info role for the branch color.

Post-verification inline leader and fast navigation (#98) ​

  • The leader badge box is gone. LEADER now renders inline on the agent name row, after the shared faint │ separator, in the leader accent color. The async terminal-background detection and leaderBadge contrast machinery were removed with the box.
  • j/k latency root cause. The rail row computed const selected = props.cursor === index() once inside the <For> item callback. The cursor read was not reactive, so the highlight only moved when the 250 ms snapshot poll rebuilt the item array. The row now reads props.cursor through a thunk inside the rendered expression; a tmux probe dropped move latency from a 0–250 ms spread (mean ~130 ms) to one frame (~9–30 ms). A control run that kept host keymap dispatch but added the reactive read measured the same one-frame latency, so the poll was the cause, not key routing.

Verified after the fix: npm run check 0; unit tests pass; fake live, empty live, and real live pass. Static guards pin the reactive cursor thunk and the inline leader separator/color.

Released under the MIT License.