Phase 2.6.F — full-screen TUI renderer (Home + chat): alt-screen, scroll/auto-follow, flicker-free swaps, mouse-wheel, a11y

[cemililik]

What this is

Phase 2.6.F — the full-screen TUI foundation (ADR-0068). A bare relavium on a TTY (and relavium chat) now opens a full-screen alternate-screen renderer with an in-app scrolling viewport, replacing the inline <Static> output that clipped long responses. The inline renderer is retained, byte-identical, as the opt-out + the screen-reader / machine path.

Built on the ink-7 substrate + the hand-rolled viewport from earlier 2.6.F steps; this PR carries Step 4b-2 → Step 5b, each landed under a strict per-step discipline: implement → Opus adversarial review (3 finders + independent skeptic verification) → fold verified findings → Sonnet review → fold → next step. Every fix was empirically break-verified (break production, confirm the pinning test fails, revert).

The renderer, end to end

• Viewport + scroll / auto-follow (4b-2): PgUp/PgDn page, Ctrl+Home/Ctrl+End jump to top/tail; an upward scroll pauses tail-follow, reaching the bottom (or Ctrl+End) resumes it. Grapheme-aware displayWidth (Intl.Segmenter) so the 1-DisplayLine==1-row invariant holds under emoji/CJK. The scroll geometry is read live at the keypress so a mid-stream burst can't yank a paused reader to the tail.
• caps-lift (4b-3): a per-entry WeakMap wrap cache keyed on the immutable transcript entry — an append is O(history) lookups + ONE segmentation, and it never thrashes.
• Inter-session flicker fix (4b-3): ink 7 tied the DECSET-1049 enter/exit to per-session mount/unmount, so a /clear or /models re-drive flickered primary→alt→primary. Verified against ink 7.1.0's compiled build that full-screen rendering is decoupled from the alternateScreen option, then hoisted the alt-buffer toggle above the per-session loop (withHoistedAltScreen): enter once, exit once, no flicker. Terminal restore is guaranteed on every exit path (finally + process.on('exit') + SIGTERM/SIGHUP/SIGQUIT), all idempotent.
• Default flip (4b-3): DEFAULT_ALT_SCREEN → true. --no-alt-screen / [preferences].alt_screen = false opt out; --json / CI / non-TTY stay inline + byte-identical.
• Mouse-wheel scroll (5b): SGR mouse reporting drives the same scroll actions (default-on in full-screen; native selection needs Shift/Option — documented).
• Accessibility (5a): a dedicated accessibility.md — the alt screen is screen-reader-hostile; the inline renderer is the documented escape hatch.

Review outcomes (both rounds, folded)

• Opus caught a real flip regression: the /clear/reseat rebuild-failure hint (with the resumable chat-resume <id>) was written into the alt buffer and discarded → user dropped to a bare shell with no error. Fixed (lifted past the alt-exit). Also: the >8192-line LRU thrash (→ per-entry cache), SIGQUIT stranding, and interactive-test terminal pollution.
• Sonnet caught a self-inflicted test blind spot (the hoist-wiring altActive derivation had no coverage) and the mid-session notice class (budget-cap warning / MCP-skipped diagnostic lost in the alt buffer) — both fixed.

How to verify

pnpm turbo run lint typecheck test + pnpm turbo run build are green (1761 CLI tests). The signal / terminal-lifecycle paths that can't be unit-tested need a real-TTY manual pass (see the checklist below).

Manual real-TTY checklist

• bare relavium opens full-screen; scroll (PgUp/PgDn/Ctrl+Home/End) + mouse-wheel work; typing at the prompt is unaffected
• /clear and /models do not flicker the terminal
• --no-alt-screen (and [preferences].alt_screen = false) fall back to the inline renderer cleanly
• double Ctrl-C and kill -TERM <pid> restore the terminal (primary buffer, cursor, mouse selection) — not stranded in alt
• relavium chat --json / a piped run is byte-identical to before (no escape bytes)

Not in this PR (Step 5 remainder — done fresh)

• /scrollback + /edit copy-and-search hatches (ink suspendTerminal; findings recorded)
• the branded Home banner
• Step 5's own review rounds

Refs: ADR-0068 (+ ADR-0067 floor, ADR-0057/0059/0062 surfaces)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added full-screen alternate-screen transcript mode with bounded viewport, tail-follow scrolling, PgUp/PgDn + Ctrl+Home/End controls, and resize re-clamping.
  • Added ink-native bracketed paste handling with CRLF/CR normalization and stricter paste eligibility; supports inline opt-out via --no-alt-screen and [preferences].alt_screen=false.
• Bug Fixes
  • Improved alternate-screen lifecycle safety across exit, signals, and errors (idempotent enter/restore; final output on the primary buffer only).
  • Routed budget warnings and MCP “skipped lines” into in-app transcript notices.
• Documentation
  • Updated accessibility, chat/home references, and config/CLI option docs for render-mode and paste behavior.
• Chores / Tests
  • Raised supported Node minimums, added a CI Node 22 floor-check job, and expanded Vitest discovery to *.test.tsx.

[sourcery-ai]

Sorry @cemililik, your pull request is larger than the review limit of 150000 diff characters

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 940f744d-260b-44cf-9fe9-93ca77006779

📥 Commits

Reviewing files that changed from the base of the PR and between 7d4899f and 4c01aef.

📒 Files selected for processing (6)

• apps/cli/src/commands/chat.ts
• apps/cli/src/render/tui/chat-app.test.tsx
• apps/cli/src/render/tui/harness-util.ts
• apps/cli/src/render/tui/home-app.test.tsx
• docs/reference/cli/accessibility.md
• docs/reference/contracts/config-spec.md

✅ Files skipped from review due to trivial changes (2)

• docs/reference/cli/accessibility.md
• docs/reference/contracts/config-spec.md

🚧 Files skipped from review as they are similar to previous changes (3)

• apps/cli/src/render/tui/chat-app.test.tsx
• apps/cli/src/render/tui/home-app.test.tsx
• apps/cli/src/commands/chat.ts

---

📝 Walkthrough

Walkthrough

This PR raises the Node.js floor to >=22 across runtime, CI, and docs, and adds an ink 7 alternate-screen renderer for chat and Home. It also threads render-mode selection, scroll/view handling, native paste, and alt-screen lifecycle control through the CLI.

Changes

Node 22 supported floor

Layer / File(s)	Summary
Runtime floor updates package.json, apps/cli/package.json, .nvmrc, .npmrc, apps/cli/README.md, apps/cli/tsup.config.ts, pnpm-workspace.yaml, packages/mcp/src/sdk-websocket.ts, packages/shared/src/config.ts, packages/shared/src/config.test.ts	Sets Node and type/package floors to >=22, updates the build target, and aligns runtime comments and config schema docs.
CI and documentation rollout .github/workflows/ci.yml, docs/decisions/*, docs/tech-stack.md, docs/reference/desktop/database-schema.md, docs/roadmap/*, docs/reference/cli/*, docs/standards/testing.md	Updates CI gates, ADRs, roadmap notes, and CLI docs to record the floor change and the related runtime/support wording.

Ink 7 full-screen renderer

Layer / File(s)	Summary
Render mode and alt-screen primitives apps/cli/src/config/resolve.ts, apps/cli/src/process/options.ts, apps/cli/src/program.ts, apps/cli/src/render/alt-screen.ts, apps/cli/src/render/render-mode.ts, apps/cli/src/render/tui/scroll.ts, apps/cli/src/render/tui/viewport.ts, apps/cli/src/render/tui/transcript-viewport.tsx, related tests	Adds the alt-screen preference, --no-alt-screen, render-mode precedence, controller, scrolling model, wrapping/measurement helpers, and transcript viewport.
Chat renderer viewport and lifecycle apps/cli/src/render/tui/chat-ink.tsx, apps/cli/src/render/tui/chat-app.test.tsx, apps/cli/src/render/tui/chat-ink.test.ts, apps/cli/src/render/tui/chat-input.ts, apps/cli/src/render/tui/chat-input.test.ts, apps/cli/src/render/tui/chat-projection.ts, apps/cli/src/render/tui/chat-projection.test.ts	Wires the chat renderer to the new viewport, scroll, paste, transcript wrapping, and exit-finalization flow.
Chat command hoist and notices apps/cli/src/commands/chat.ts, apps/cli/src/commands/chat-alt-hoist.test.ts, apps/cli/src/commands/chat.test.ts, apps/cli/src/engine/mcp-servers.ts, apps/cli/src/engine/mcp-servers.test.ts	Adds the hoisted alt-screen wrapper, lifecycle hooks, rebuild forwarding, and notice routing for budget/MCP diagnostics.
Home renderer alt-screen and paste wiring apps/cli/src/home/drive-home.tsx, apps/cli/src/render/tui/home-app.tsx, apps/cli/src/render/tui/home-controller.ts, apps/cli/src/render/tui/home-controller.test.ts, apps/cli/src/render/tui/home-input.ts, apps/cli/src/render/tui/home-input.test.ts, apps/cli/src/render/tui/home-app.test.tsx	Adds Home render-mode resolution, alt-screen scroll/view wiring, and native handlePaste behavior.
Harness and build config for ink 7 apps/cli/src/render/tui/harness-util.ts, apps/cli/src/render/tui/harness-smoke.test.tsx, vitest.config.ts, pnpm-workspace.yaml, apps/cli/package.json, docs/standards/testing.md	Adds ink-testing-library support, .test.tsx collection, and shared TUI harness utilities.
ADR-0068 and CLI docs docs/decisions/0068*, docs/decisions/0047*, docs/reference/cli/*, docs/reference/contracts/config-spec.md, docs/roadmap/deferred-tasks.md	Documents the ink 7 renderer decision and updates CLI-facing docs for alt-screen, paste, and accessibility behavior.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

• HodeTech/Relavium#54: Introduced the core relavium chat REPL implementation that this PR extends with hoisted alt-screen behavior and summary handling.
• HodeTech/Relavium#55: Shares the same chat driver and session-finalization code paths that this PR extends for alt-screen loop control.
• HodeTech/Relavium#61: Related to the Home paste path that this PR rewires from marker-based handling to native handlePaste.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.58% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: a full-screen TUI renderer for Home and chat with alt-screen, scrolling, mouse support, and accessibility work.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch development

---

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request raises the Node.js supported floor to >=22 and upgrades ink to version 7 to implement a full-screen alternate-screen renderer for the Home and chat REPL. Key additions include a scrollable transcript viewport with keyboard and mouse-wheel navigation, native bracketed paste handling, and a new component test suite using ink-testing-library. The review feedback is highly constructive and should be addressed: first, refactor the module-global liveSessionNotice in chat.ts to a session-local reference to prevent potential race conditions and test interference; second, optimize TranscriptViewport by adding a dependency array to useEffect to avoid performance overhead from calling measureElement on every render; and finally, update the outdated comments in config.ts and documentation in config-spec.md that still list scroll-back and mouse-wheel scroll as pending features.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The module-global variable liveSessionNotice introduces shared state across the module. While a single REPL runs at a time in production, this can cause race conditions, cross-talk, or test interference if multiple sessions or tests run concurrently in the same process. To make the session lifecycle fully re-entrant and robust, consider threading a session-local reference (e.g., a mutable ref object { current?: (text: string) => void }) through ChatReplDeps and FreshChatWiringDeps instead of relying on a module-level global variable.

[gemini-code-assist]

Calling measureElement on every single render (due to the lack of a dependency array in useEffect) can cause performance bottlenecks and layout thrashing, especially during fast token streaming where the component re-renders frequently. To optimize this, consider passing the terminal dimensions (cols and rows) as props to TranscriptViewport and adding a dependency array to useEffect (e.g., [props.lines.length, props.cols, props.rows, height, props.onMeasure]). This ensures layout measurement only runs when the terminal size or the transcript line count actually changes, significantly reducing CPU overhead during active streaming.

[gemini-code-assist]

The comment here states that scroll-back (PgUp/PgDn, Step 4b-2) is still pending. However, scroll-back has been fully implemented and tested in this PR. Please update the comment to reflect that scroll-back is now supported, leaving only the copy-and-search hatches as pending.

[gemini-code-assist]

The documentation states that mouse-wheel scroll is still pending. However, mouse-wheel scroll has been fully implemented and tested in this PR. Please update the documentation to remove 'mouse-wheel' from the pending list.

[coderabbitai]

Actionable comments posted: 6

🧹 Nitpick comments (11)

docs/roadmap/phases/phase-2.6-conversational-authoring.md (1)

782-789: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Contradictory "non-configurable" vs. "configurable ceiling" wording.

Line 787 introduces guardrails as "engine-enforced and non-configurable where noted," then in the same breath describes the concurrency ceiling as "a configurable ceiling (default 5)." As written, it's ambiguous whether the concurrency ceiling is meant to be a hard constant (like the depth-3 limit) or a tunable setting — this will matter once the 2.6.N ADR is drafted from this spec.

✏️ Suggested clarification

-    **Hard limits are engine-enforced
-    and non-configurable where noted:** maximum nesting depth **3** (parent → child → grandchild; a
-    grandchild cannot spawn further); maximum concurrent children per turn bounded at a configurable ceiling
-    (default **5**). Hard-coding these bounds lets downstream UX (error messages, history tree views, cost
+    **Hard limits are engine-enforced and non-configurable:** maximum nesting depth **3** (parent →
+    child → grandchild; a grandchild cannot spawn further). Maximum concurrent children per turn is
+    bounded at a **configurable** ceiling (default **5**). Hard-coding the depth bound (and defaulting
+    the concurrency bound) lets downstream UX (error messages, history tree views, cost
     indentation) design against fixed limits from day one.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/roadmap/phases/phase-2.6-conversational-authoring.md` around lines 782 -
789, Clarify the guardrail wording in the 2.6. O permissions section so it is
not contradictory. Update the paragraph around the hard limits statement to
distinguish the fixed nesting depth enforced by the engine from the
concurrent-children ceiling, and make it explicit whether the ceiling is
configurable or non-configurable. Keep the language consistent in the
surrounding `Permission model + hard guardrails` description so readers can tell
which limits are hard-coded versus tunable.

packages/shared/src/config.ts (1)

144-151: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Stale schema comment — out of sync with the shipped feature.

This inline comment describes the "⚠ PREVIEW at Step 4b-1" state, claiming scroll-back and the default are still pending: "⚠ PREVIEW at Step 4b-1: true renders the transcript through a tail-following, resize-tracked VIEWPORT, but scroll-back (PgUp/PgDn, Step 4b-2) + the [/v copy-and-search hatches (Step 5) are still pending, so history that scrolls off the top is not yet reachable — fully usable once scroll lands." It also says the phase default is "opt-in until the viewport lands."

But docs/reference/contracts/config-spec.md (same PR) says the default flipped to alt-ON and scroll-back already shipped: "Since Step 4b-3 the DEFAULT is ON — a TTY opens full-screen — so this key is the durable OPT-OUT... The transcript renders through a resize-tracked VIEWPORT with SCROLL-BACK + auto-follow — PgUp/PgDn page, Ctrl+Home/Ctrl+End jump to top/tail... Still pending (Step 5): the [-dump / v-open-in-$EDITOR copy-and-search hatches + mouse-wheel." The PR stack also lists mouse-wheel scrolling as delivered in a later step. This schema doc-comment should be updated to match the current (post Step 4b-3 / Step 10) state so engineers reading the schema aren't misled about pending work and the default direction.

📝 Suggested comment update

-        // Full-screen alt-screen renderer opt-in/out (2.6.F, ADR-0068 §e) — `false` (or the `--no-alt-screen` flag)
-        // keeps the byte-identical INLINE renderer (native scrollback + the emulator's own a11y), the screen-reader
-        // fallback. The `--no-alt-screen` flag overrides this key; a non-TTY / machine (`--json`/CI) path ignores
-        // both and always renders inline. Absent ⇒ the phase default (opt-in until the viewport lands — ADR-0068 §b).
-        // ⚠ PREVIEW at Step 4b-1: `true` renders the transcript through a tail-following, resize-tracked VIEWPORT,
-        // but scroll-back (PgUp/PgDn, Step 4b-2) + the `[`/`v` copy-and-search hatches (Step 5) are still pending, so
-        // history that scrolls off the top is not yet reachable — fully usable once scroll lands.
+        // Full-screen alt-screen renderer opt-in/out (2.6.F, ADR-0068 §e) — `false` (or the `--no-alt-screen` flag)
+        // keeps the byte-identical INLINE renderer (native scrollback + the emulator's own a11y), the screen-reader
+        // fallback. The `--no-alt-screen` flag overrides this key; a non-TTY / machine (`--json`/CI) path ignores
+        // both and always renders inline. Absent ⇒ the phase default (alt-ON since Step 4b-3 — ADR-0068 §b). The
+        // viewport supports scroll-back (PgUp/PgDn, Ctrl+Home/Ctrl+End) and mouse-wheel; the `[`/`v`
+        // copy-and-search hatches (Step 5) are still pending. See config-spec.md for the full description.
         alt_screen: z.boolean().optional(),

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/shared/src/config.ts` around lines 144 - 151, Update the inline
schema comment for alt_screen in config.ts so it matches the shipped behavior
described by the current config spec. Replace the stale “preview / opt-in /
scroll-back pending” wording with the current state: default ON for
TTY/full-screen, this key acting as the durable opt-out, and
scroll-back/auto-follow already available. Keep the comment aligned with the
alt_screen z.boolean().optional() setting and remove references to Step
4b-1/4b-2 that are no longer accurate.

apps/cli/src/render/alt-screen.test.ts (1)

74-78: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Prefer toHaveLength for the length assertion.

Line 77 compares out.length via toEqual; toHaveLength gives clearer failure output.

♻️ Suggested tweak

-    const afterRestore = out.length;
-    c.clearBetween(); // after restore → no-op (buffer is gone)
-    expect(out.length).toBe(afterRestore);
+    const afterRestore = out.length;
+    c.clearBetween(); // after restore → no-op (buffer is gone)
+    expect(out).toHaveLength(afterRestore);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/render/alt-screen.test.ts` around lines 74 - 78, The length
assertion in the alt-screen test should use `toHaveLength` instead of comparing
`out.length` directly. Update the expectation in `alt-screen.test.ts` around the
`c.clearBetween()` no-op check so it asserts on `out` with `toHaveLength`,
keeping the existing `afterRestore` value and the `c.restore` / `c.clearBetween`
flow unchanged.

Source: Linters/SAST tools

apps/cli/src/render/tui/scroll.test.ts (1)

118-122: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

as never cast bypasses the "no unsafe as" rule.

{ upArrow: true } as never forces an object with an unrelated property through scrollMotionForKey. Since ScrollKey's fields are all optional, the same "not a scroll key" case can be tested without a cast (e.g. { ctrl: false } or simply relying on the existing {} case above at line 119).

As per coding guidelines, "All source must be TypeScript, in strict mode: no any, no unsafe as, and prefer type guards."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/render/tui/scroll.test.ts` around lines 118 - 122, Remove the
unsafe `as never` cast in the `scrollMotionForKey` test and keep the
non-scroll-key coverage using a valid `ScrollKey`-shaped object or the existing
empty-object case. Update the `returns undefined for a non-scroll key` test in
`scroll.test.ts` so it exercises the same fallback path without forcing an
unrelated property through type checking, preserving the intent of
`scrollMotionForKey` while complying with the no-unsafe-`as` rule.

Source: Coding guidelines

apps/cli/src/render/tui/transcript-viewport.tsx (1)

85-93: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Array index as React key (Sonar hint) — low risk here, optional to change.

visible.map((line, index) => ...) keys on index; since <Text> is a stateless leaf fully determined by its props each render, this is unlikely to cause visible bugs, but a key derived from content/offset would be more defensive if the list ever gains reordering/animation.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/render/tui/transcript-viewport.tsx` around lines 85 - 93, The
`visible.map((line, index) => ...)` in `TranscriptViewport` uses the array index
as the React key; switch to a stable key derived from the line’s identity (for
example, its text plus any available offset or sequence field) so `<Text>`
instances remain correctly keyed even if the list order changes. Update the key
in the `visible` render loop without changing the displayed output or
`styleProps` behavior.

Source: Linters/SAST tools

apps/cli/src/render/tui/chat-projection.ts (2)

265-311: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Overview doc block documents wrapTranscript but sits above the private wrapEntry.

The lines 265-277 JSDoc describes flattening the whole transcript into DisplayLines (the public contract), but it's attached to the private per-entry helper wrapEntry rather than the exported wrapTranscript (line 312), which has no doc comment of its own. Consider moving the transcript-level description to sit above wrapTranscript and keeping only the per-entry doc above wrapEntry.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/render/tui/chat-projection.ts` around lines 265 - 311, Move the
transcript-level JSDoc that describes flattening the full transcript into
width-wrapped DisplayLines so it sits above wrapTranscript instead of wrapEntry,
since that comment documents the public contract of the exported function. Keep
wrapEntry with only a short per-entry doc that explains its one-entry wrapping
behavior, and make sure the symbols wrapTranscript and wrapEntry are clearly
matched to their own docs.

---

318-320: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Prefer optional chaining, per static analysis.

♻️ Proposed simplification

-    const cached = entryWrapCache.get(entry);
-    let lines: readonly DisplayLine[];
-    if (cached !== undefined && cached.cols === cols) {
+    const cached = entryWrapCache.get(entry);
+    let lines: readonly DisplayLine[];
+    if (cached?.cols === cols) {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/render/tui/chat-projection.ts` around lines 318 - 320, The cache
lookup in chat projection uses an explicit undefined check before reading cols;
simplify this by using optional chaining in the cached entry handling within the
chat-projection logic. Update the condition around entryWrapCache.get and the
cached.cols comparison so it safely reads cols only when a cached value exists,
keeping the behavior unchanged while matching the static analysis suggestion.

Source: Linters/SAST tools

apps/cli/src/render/tui/chat-input.test.ts (1)

547-565: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Derive gates from the flags object instead of hardcoding the key list.

The exhaustive gate-coverage test is only as good as the manually maintained gates array. If a new field is added to PasteEditableFlags without also adding it here, the "drops the paste on any single busy/overlay gate" guarantee silently loses coverage for that field — on a fail-closed, approval-gating predicate where that matters.

♻️ Proposed fix to keep the gate list in sync automatically

-    const gates: (keyof PasteEditableFlags)[] = [
-      'running',
-      'shellBusy',
-      'submitBusy',
-      'paletteOpen',
-      'searchOpen',
-      'mentionOpen',
-      'modelPickerOpen',
-      'effortPickerOpen',
-      'reasonCaptureOpen',
-      'approvalPending',
-    ];
+    const gates = Object.keys(ALL_CLEAR) as (keyof PasteEditableFlags)[];

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/render/tui/chat-input.test.ts` around lines 547 - 565, The
exhaustive gate test in chat-input.test.ts is manually maintaining the list used
by pasteIsEditable, so new PasteEditableFlags fields can slip through unnoticed.
Update the test to derive the gate keys from the flags object/ALL_CLEAR shape
instead of hardcoding them, while still iterating through each gate and
asserting a single enabled flag makes pasteIsEditable return false.

apps/cli/src/commands/chat.ts (1)

405-414: 🩺 Stability & Availability | 🔵 Trivial | ⚖️ Poor tradeoff

Module-level liveSessionNotice singleton — verify the "one session per process" invariant always holds.

This file-private pointer is documented as safe because "a REPL runs exactly ONE session at a time per process." That's true for the current single chatCommand/chatResumeCommand invocation model, but it's a global mutable coupling point — any future concurrent use (e.g. a test harness running two chatCommand() calls via Promise.all, or a future embedding scenario) would cross-wire budget/MCP-skipped notices between unrelated sessions. Worth a short comment reiterating the invariant is load-bearing, or threading the sink through ChatReplDeps/ReplWiring instead of module state.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/commands/chat.ts` around lines 405 - 414, The module-level
liveSessionNotice singleton relies on a strict “one session per process”
invariant, so make that assumption explicit and load-bearing in the surrounding
chat flow. Update the chatCommand/chatResumeCommand and driveOneSession wiring
to either clearly document and guard the single-session guarantee, or better,
pass the notice sink through ChatReplDeps/ReplWiring instead of keeping it as
module state so concurrent invocations cannot cross-wire notices between
sessions.

apps/cli/src/home/drive-home.tsx (1)

472-480: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Minor duplication: terminal-restore sequence repeated in onSignal and finally.

writeControl(DISABLE_BRACKETED_PASTE); writeControl(DISABLE_MOUSE); (plus the enclosing try/catch) is now written out twice. Extracting a small restoreTerminalControls() closure would remove the duplication without changing behavior.

♻️ Optional dedup

+    const restoreTerminal = (): void => {
+      instance?.unmount();
+      writeControl(DISABLE_BRACKETED_PASTE);
+      writeControl(DISABLE_MOUSE);
+    };
     try {
-        instance?.unmount(); // restore the terminal from raw mode BEFORE anything else
-        writeControl(DISABLE_BRACKETED_PASTE);
-        writeControl(DISABLE_MOUSE); // restore native mouse text-selection (no-op if never enabled)
+        restoreTerminal();
      } catch {

Also applies to: 554-566

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/home/drive-home.tsx` around lines 472 - 480, The terminal
restore logic is duplicated in both the signal handler and the cleanup path, so
extract the repeated best-effort sequence into a small restoreTerminalControls
helper/closure near onSignal and finally. Move the instance?.unmount() and the
DISABLE_BRACKETED_PASTE/DISABLE_MOUSE writeControl calls, along with the
existing try/catch, into that helper and invoke it from both places to keep
behavior identical while removing duplication.

docs/reference/cli/chat-session.md (1)

25-26: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Sentence fragment: "Still pending (Step 5): the [/v copy-and-search hatches — see …" is missing a verb/subject-predicate structure.

Minor grammar nit flagged by static analysis; a quick rewrite reads more cleanly.

✏️ Suggested rewrite

-Still pending (Step 5): the **`[`/`v`** copy-and-search hatches — see [config-spec.md](../contracts/config-spec.md)'s `alt_screen` caveat.
+The **`[`/`v`** copy-and-search hatches are still pending (Step 5) — see [config-spec.md](../contracts/config-spec.md)'s `alt_screen` caveat.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/reference/cli/chat-session.md` around lines 25 - 26, The sentence in the
CLI chat-session docs is a fragment and needs a complete subject-verb structure.
Rewrite the “Still pending (Step 5)” line in the relevant documentation text so
it reads as a full sentence while preserving the meaning about the `[`/`v`
copy-and-search hatches and the `alt_screen` caveat, and keep the surrounding
references to ADR-0068 and config-spec.md intact.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/cli/README.md`:
- Around line 22-23: The CLI README support note is overstating the LTS status
by listing 24 and 26 as LTS lines; update the wording in the Node.js requirement
blurb to keep the support story accurate. Rephrase the sentence around the Node
support claim so it only says Node.js ≥ 22, or at most 22/24, and avoid
describing 26 as LTS while leaving the rest of the install/runtime text
unchanged.

In `@apps/cli/src/commands/chat.ts`:
- Around line 405-426: The budget warning routing in
emitLiveNotice/livingSessionNotice is being installed for plain and JSON
sessions too, but those drivers do not render store.notice, so the warning never
reaches stderr. Update the wiring around driveOneSession so liveSessionNotice =
(text) => store.notice(text) is only used for the ink/alt-screen path, and make
drivePlain and driveJson keep using io.writeErr for mid-session notices; use the
existing emitLiveNotice, liveSessionNotice, and budgetWarningText symbols to
keep the fix localized.

In `@apps/cli/src/render/tui/home-app.tsx`:
- Around line 197-233: Mouse reports are only being parsed inside the altChat
path, so SGR mouse input can still fall through to controller.handleKey in other
Home states. Update the useInput handler in home-app.tsx to detect and consume
parseMouseScroll(input) whenever alternateScreen is enabled, regardless of
state.mode or noOverlay, and keep only the scroll application logic behind the
existing altChat check so raw mouse bytes never reach the prompt/palette/reason
capture handlers.

In `@apps/cli/src/render/tui/home-controller.ts`:
- Around line 1473-1482: `handlePaste` mutates the input buffer through
`insertAtCursor` but never clears history navigation, unlike other real edits
such as `append`, `backspace`, `newline`, `kill`, `mention-restore`, and
`search-accept`. Update `handlePaste` in `home-controller` to reset the history
nav state with `resetHistoryNav(history)` when a paste is accepted, alongside
the existing `doctorRunId`/`set` update, so a paste behaves like any other
buffer-changing edit and does not leave stale Up/Down recall state behind.

In `@docs/decisions/0051-cli-distribution-thin-bundle-private-engine.md`:
- Around line 5-11: The amendment note in this ADR is inconsistent with the
later mechanics section, so update the document in both places together. In the
ADR body around the bundle build and runtime floor references, align the
published `engines.node` and `tsup` target statements with the amended Node 22
floor so there is no remaining `node20` / `>=20.12.0` wording; keep the same
bundle-boundary decision while replacing the outdated floor-specific values.

In `@docs/decisions/0067-node-supported-floor-22-reaffirm-better-sqlite3.md`:
- Around line 56-60: The wording in the decision note overstates Node 26 as an
LTS line; update the `better-sqlite3 under >=22` section to refer only to Node
22/24 as supported LTS lines, or change the phrasing to “supported lines” if you
want to keep Node 26 included. Make the same terminology fix in the related
`85-87` passage so the `supported LTS lines` wording is consistent throughout
the document.

---

Nitpick comments:
In `@apps/cli/src/commands/chat.ts`:
- Around line 405-414: The module-level liveSessionNotice singleton relies on a
strict “one session per process” invariant, so make that assumption explicit and
load-bearing in the surrounding chat flow. Update the
chatCommand/chatResumeCommand and driveOneSession wiring to either clearly
document and guard the single-session guarantee, or better, pass the notice sink
through ChatReplDeps/ReplWiring instead of keeping it as module state so
concurrent invocations cannot cross-wire notices between sessions.

In `@apps/cli/src/home/drive-home.tsx`:
- Around line 472-480: The terminal restore logic is duplicated in both the
signal handler and the cleanup path, so extract the repeated best-effort
sequence into a small restoreTerminalControls helper/closure near onSignal and
finally. Move the instance?.unmount() and the
DISABLE_BRACKETED_PASTE/DISABLE_MOUSE writeControl calls, along with the
existing try/catch, into that helper and invoke it from both places to keep
behavior identical while removing duplication.

In `@apps/cli/src/render/alt-screen.test.ts`:
- Around line 74-78: The length assertion in the alt-screen test should use
`toHaveLength` instead of comparing `out.length` directly. Update the
expectation in `alt-screen.test.ts` around the `c.clearBetween()` no-op check so
it asserts on `out` with `toHaveLength`, keeping the existing `afterRestore`
value and the `c.restore` / `c.clearBetween` flow unchanged.

In `@apps/cli/src/render/tui/chat-input.test.ts`:
- Around line 547-565: The exhaustive gate test in chat-input.test.ts is
manually maintaining the list used by pasteIsEditable, so new PasteEditableFlags
fields can slip through unnoticed. Update the test to derive the gate keys from
the flags object/ALL_CLEAR shape instead of hardcoding them, while still
iterating through each gate and asserting a single enabled flag makes
pasteIsEditable return false.

In `@apps/cli/src/render/tui/chat-projection.ts`:
- Around line 265-311: Move the transcript-level JSDoc that describes flattening
the full transcript into width-wrapped DisplayLines so it sits above
wrapTranscript instead of wrapEntry, since that comment documents the public
contract of the exported function. Keep wrapEntry with only a short per-entry
doc that explains its one-entry wrapping behavior, and make sure the symbols
wrapTranscript and wrapEntry are clearly matched to their own docs.
- Around line 318-320: The cache lookup in chat projection uses an explicit
undefined check before reading cols; simplify this by using optional chaining in
the cached entry handling within the chat-projection logic. Update the condition
around entryWrapCache.get and the cached.cols comparison so it safely reads cols
only when a cached value exists, keeping the behavior unchanged while matching
the static analysis suggestion.

In `@apps/cli/src/render/tui/scroll.test.ts`:
- Around line 118-122: Remove the unsafe `as never` cast in the
`scrollMotionForKey` test and keep the non-scroll-key coverage using a valid
`ScrollKey`-shaped object or the existing empty-object case. Update the `returns
undefined for a non-scroll key` test in `scroll.test.ts` so it exercises the
same fallback path without forcing an unrelated property through type checking,
preserving the intent of `scrollMotionForKey` while complying with the
no-unsafe-`as` rule.

In `@apps/cli/src/render/tui/transcript-viewport.tsx`:
- Around line 85-93: The `visible.map((line, index) => ...)` in
`TranscriptViewport` uses the array index as the React key; switch to a stable
key derived from the line’s identity (for example, its text plus any available
offset or sequence field) so `<Text>` instances remain correctly keyed even if
the list order changes. Update the key in the `visible` render loop without
changing the displayed output or `styleProps` behavior.

In `@docs/reference/cli/chat-session.md`:
- Around line 25-26: The sentence in the CLI chat-session docs is a fragment and
needs a complete subject-verb structure. Rewrite the “Still pending (Step 5)”
line in the relevant documentation text so it reads as a full sentence while
preserving the meaning about the `[`/`v` copy-and-search hatches and the
`alt_screen` caveat, and keep the surrounding references to ADR-0068 and
config-spec.md intact.

In `@docs/roadmap/phases/phase-2.6-conversational-authoring.md`:
- Around line 782-789: Clarify the guardrail wording in the 2.6. O permissions
section so it is not contradictory. Update the paragraph around the hard limits
statement to distinguish the fixed nesting depth enforced by the engine from the
concurrent-children ceiling, and make it explicit whether the ceiling is
configurable or non-configurable. Keep the language consistent in the
surrounding `Permission model + hard guardrails` description so readers can tell
which limits are hard-coded versus tunable.

In `@packages/shared/src/config.ts`:
- Around line 144-151: Update the inline schema comment for alt_screen in
config.ts so it matches the shipped behavior described by the current config
spec. Replace the stale “preview / opt-in / scroll-back pending” wording with
the current state: default ON for TTY/full-screen, this key acting as the
durable opt-out, and scroll-back/auto-follow already available. Keep the comment
aligned with the alt_screen z.boolean().optional() setting and remove references
to Step 4b-1/4b-2 that are no longer accurate.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7cff1acf-c368-418f-8832-6fe449b38537

📥 Commits

Reviewing files that changed from the base of the PR and between 88f8fff and 721e4b5.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (65)

• .github/workflows/ci.yml
• .npmrc
• .nvmrc
• apps/cli/README.md
• apps/cli/package.json
• apps/cli/src/commands/chat-alt-hoist.test.ts
• apps/cli/src/commands/chat.test.ts
• apps/cli/src/commands/chat.ts
• apps/cli/src/config/resolve.ts
• apps/cli/src/engine/mcp-servers.test.ts
• apps/cli/src/engine/mcp-servers.ts
• apps/cli/src/engine/media-wiring.test.ts
• apps/cli/src/home/drive-home.test.ts
• apps/cli/src/home/drive-home.tsx
• apps/cli/src/process/options.test.ts
• apps/cli/src/process/options.ts
• apps/cli/src/program.ts
• apps/cli/src/render/alt-screen.test.ts
• apps/cli/src/render/alt-screen.ts
• apps/cli/src/render/render-mode.test.ts
• apps/cli/src/render/render-mode.ts
• apps/cli/src/render/tui/chat-app.test.tsx
• apps/cli/src/render/tui/chat-ink.test.ts
• apps/cli/src/render/tui/chat-ink.tsx
• apps/cli/src/render/tui/chat-input.test.ts
• apps/cli/src/render/tui/chat-input.ts
• apps/cli/src/render/tui/chat-projection.test.ts
• apps/cli/src/render/tui/chat-projection.ts
• apps/cli/src/render/tui/harness-smoke.test.tsx
• apps/cli/src/render/tui/harness-util.ts
• apps/cli/src/render/tui/home-app.test.tsx
• apps/cli/src/render/tui/home-app.tsx
• apps/cli/src/render/tui/home-controller.test.ts
• apps/cli/src/render/tui/home-controller.ts
• apps/cli/src/render/tui/home-input.test.ts
• apps/cli/src/render/tui/home-input.ts
• apps/cli/src/render/tui/scroll.test.ts
• apps/cli/src/render/tui/scroll.ts
• apps/cli/src/render/tui/transcript-viewport.tsx
• apps/cli/src/render/tui/viewport.test.ts
• apps/cli/src/render/tui/viewport.ts
• apps/cli/tsup.config.ts
• docs/decisions/0021-node-sqlite-driver-better-sqlite3.md
• docs/decisions/0047-cli-framework-commander-ink-clack.md
• docs/decisions/0051-cli-distribution-thin-bundle-private-engine.md
• docs/decisions/0067-node-supported-floor-22-reaffirm-better-sqlite3.md
• docs/decisions/0068-full-screen-tui-renderer-ink7-harness.md
• docs/decisions/README.md
• docs/reference/cli/accessibility.md
• docs/reference/cli/chat-session.md
• docs/reference/cli/commands.md
• docs/reference/cli/home.md
• docs/reference/contracts/config-spec.md
• docs/reference/desktop/database-schema.md
• docs/roadmap/deferred-tasks.md
• docs/roadmap/phases/node-runtime-upgrade.md
• docs/roadmap/phases/phase-2.6-conversational-authoring.md
• docs/standards/testing.md
• docs/tech-stack.md
• package.json
• packages/mcp/src/sdk-websocket.ts
• packages/shared/src/config.test.ts
• packages/shared/src/config.ts
• pnpm-workspace.yaml
• vitest.config.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/decisions/0067-node-supported-floor-22-reaffirm-better-sqlite3.md`:
- Around line 81-107: The amendment updates the CI floor leg to Node 22.13.0,
but the Consequences section still says Node 22.0.0, so the ADR is now
inconsistent. Update the stale Consequences bullet to match the revised CI floor
in the decision note, and if you prefer to keep the original text there, add a
brief amendment pointer that explicitly calls out the Consequences section using
its existing wording around the dedicated CI floor leg and published minimum.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e41c5d17-9d4a-46d1-815a-87d5daf81ca4

📥 Commits

Reviewing files that changed from the base of the PR and between bdbe426 and 2d6c0c2.

📒 Files selected for processing (6)

• .github/workflows/ci.yml
• apps/cli/README.md
• apps/cli/package.json
• docs/decisions/0067-node-supported-floor-22-reaffirm-better-sqlite3.md
• docs/tech-stack.md
• package.json

🚧 Files skipped from review as they are similar to previous changes (4)

• package.json
• apps/cli/package.json
• apps/cli/README.md
• docs/tech-stack.md

[cemililik]

@coderabbitai review all

[coderabbitai]

@cemililik, sure — I'll do a full review of all the changes in this PR.

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

apps/cli/src/commands/chat-alt-hoist.test.ts (2)

657-657: 🎯 Functional Correctness | 🔴 Critical | ⚡ Quick win

Remove the duplicate openSessionStore properties.

Each affected object literal defines openSessionStore twice. TypeScript reports duplicate object properties, so these tests will not compile until one copy is removed from each object.

Also applies to: 674-674, 688-688, 719-719

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/commands/chat-alt-hoist.test.ts` at line 657, The affected test
object literals in chat-alt-hoist.test.ts define openSessionStore twice, which
causes TypeScript duplicate-property errors. Update each impacted object literal
referenced in the test cases by removing the redundant openSessionStore entry so
only one property remains, and keep the change localized to the relevant test
setup objects.

Source: Linters/SAST tools

---

477-477: 🎯 Functional Correctness | 🔴 Critical | ⚡ Quick win

Remove the duplicate BudgetWarn declarations.

The same type alias is emitted four times in the same scope, which causes a duplicate-identifier TypeScript error. Keep a single declaration.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/commands/chat-alt-hoist.test.ts` at line 477, The generated test
scope contains duplicate BudgetWarn type alias declarations, which triggers a
TypeScript duplicate-identifier error. In chat-alt-hoist.test.ts, locate the
repeated BudgetWarn declarations in the same scope and keep only one shared type
alias, then update any nearby references to use that single definition.

🧹 Nitpick comments (2)

docs/reference/contracts/config-spec.md (1)

71-72: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Trim the restated renderer mechanics; link instead.

The alt_screen key description is appropriately detailed for the setting itself (default, precedence, opt-out), but the second sentence re-describes the full viewport/scroll/mouse-wheel renderer mechanics and pending follow-ups — content that already has (or should have) a canonical home in ADR-0068 / accessibility.md. Restating it here risks drift if the renderer behavior changes but only one copy is updated.

✏️ Suggested trim

-                                   # The transcript renders through a resize-tracked VIEWPORT with SCROLL-BACK + auto-follow — PgUp/PgDn page, Ctrl+Home/Ctrl+End jump to top/tail, an upward scroll pauses the tail-follow and reaching the bottom resumes it (the scroll keymap yields to any keyboard-owning overlay); a `/clear` or `/models` swap no longer flickers the terminal (the alt buffer is held across sessions). Mouse-wheel scrolling works too. Still pending (Step 5): the `[`-dump / `v`-open-in-$EDITOR copy-and-search hatches. Set `false` (or `--no-alt-screen`) for the inline renderer — the screen-reader-friendly path.
+                                   # See ADR-0068 and ../cli/accessibility.md for the full-screen renderer's viewport/scroll/mouse-wheel behavior and its inline-fallback rationale. Set `false` (or `--no-alt-screen`) for the inline renderer — the screen-reader-friendly path.

As per coding guidelines, "Specs live in [docs/reference/]; link, don't restate. One canonical home per artifact."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/reference/contracts/config-spec.md` around lines 71 - 72, Trim the
redundant renderer-mechanics prose in the `alt_screen` entry so this spec only
describes the setting’s behavior, default, and precedence. In the
`config-spec.md` section for `alt_screen`, remove the re-stated
viewport/scroll/mouse-wheel/session-flicker details and pending Step 5 notes,
and replace them with a brief pointer to the canonical ADR-0068/accessibility
documentation.

Source: Coding guidelines

apps/cli/src/render/tui/chat-app.test.tsx (1)

232-234: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the repeated settle helper into harness-util.js.

The same 3-line settle closure (loop 4×flush()) is redefined identically in six separate test cases. Since flush/waitFor/bracketed already live in harness-util.js, hoisting a shared settleFrames() there would remove the duplication as this suite keeps growing.

♻️ Proposed refactor

// harness-util.ts
+export async function settleFrames(times = 4): Promise<void> {
+  for (let i = 0; i < times; i += 1) await flush();
+}

// chat-app.test.tsx (each occurrence)
-    const settle = async (): Promise<void> => {
-      for (let i = 0; i < 4; i += 1) await flush();
-    };
+    const settle = settleFrames;

Also applies to: 271-273, 297-299, 334-336, 362-364, 389-391, 416-418

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/render/tui/chat-app.test.tsx` around lines 232 - 234, The
repeated settle helper in chat-app.test.tsx is duplicated across multiple test
cases, so hoist this 4x flush loop into harness-util.js as a shared
settleFrames() utility alongside flush/waitFor/bracketed, then update each test
to use the shared helper instead of redefining the same closure.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/cli/src/commands/chat.test.ts`:
- Line 657: The object literals in chat.test.ts define openSessionStore more
than once, causing a duplicate-property TypeScript error. In each affected test
case, update the mocked client/fixture object so it keeps only one
openSessionStore definition and remove the redundant duplicate, using the
surrounding test setup and the openSessionStore stub as the place to fix it.

In `@apps/cli/src/commands/chat.ts`:
- Around line 1570-1579: The `buildInteractiveShellRunner` wrapper is leaking an
`any` from `built.session.runUserCommand`, causing strict-TS lint failures. Fix
the source type on the session path by ensuring `BuiltChatSession.session` and
`AgentSession.runUserCommand` are explicitly typed with `UserCommandOutcome`/the
expected command signature, and import any missing type definitions so the call
in `buildInteractiveShellRunner` resolves without unsafe member access or
return. Do not silence it with `any` or casts; make the underlying
`session`/`runUserCommand` types precise.

---

Outside diff comments:
In `@apps/cli/src/commands/chat-alt-hoist.test.ts`:
- Line 657: The affected test object literals in chat-alt-hoist.test.ts define
openSessionStore twice, which causes TypeScript duplicate-property errors.
Update each impacted object literal referenced in the test cases by removing the
redundant openSessionStore entry so only one property remains, and keep the
change localized to the relevant test setup objects.
- Line 477: The generated test scope contains duplicate BudgetWarn type alias
declarations, which triggers a TypeScript duplicate-identifier error. In
chat-alt-hoist.test.ts, locate the repeated BudgetWarn declarations in the same
scope and keep only one shared type alias, then update any nearby references to
use that single definition.

---

Nitpick comments:
In `@apps/cli/src/render/tui/chat-app.test.tsx`:
- Around line 232-234: The repeated settle helper in chat-app.test.tsx is
duplicated across multiple test cases, so hoist this 4x flush loop into
harness-util.js as a shared settleFrames() utility alongside
flush/waitFor/bracketed, then update each test to use the shared helper instead
of redefining the same closure.

In `@docs/reference/contracts/config-spec.md`:
- Around line 71-72: Trim the redundant renderer-mechanics prose in the
`alt_screen` entry so this spec only describes the setting’s behavior, default,
and precedence. In the `config-spec.md` section for `alt_screen`, remove the
re-stated viewport/scroll/mouse-wheel/session-flicker details and pending Step 5
notes, and replace them with a brief pointer to the canonical
ADR-0068/accessibility documentation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0ab045d0-3e48-436b-81fa-58734c61b843

📥 Commits

Reviewing files that changed from the base of the PR and between 88f8fff and 7d4899f.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (65)

• .github/workflows/ci.yml
• .npmrc
• .nvmrc
• apps/cli/README.md
• apps/cli/package.json
• apps/cli/src/commands/chat-alt-hoist.test.ts
• apps/cli/src/commands/chat.test.ts
• apps/cli/src/commands/chat.ts
• apps/cli/src/config/resolve.ts
• apps/cli/src/engine/mcp-servers.test.ts
• apps/cli/src/engine/mcp-servers.ts
• apps/cli/src/engine/media-wiring.test.ts
• apps/cli/src/home/drive-home.test.ts
• apps/cli/src/home/drive-home.tsx
• apps/cli/src/process/options.test.ts
• apps/cli/src/process/options.ts
• apps/cli/src/program.ts
• apps/cli/src/render/alt-screen.test.ts
• apps/cli/src/render/alt-screen.ts
• apps/cli/src/render/render-mode.test.ts
• apps/cli/src/render/render-mode.ts
• apps/cli/src/render/tui/chat-app.test.tsx
• apps/cli/src/render/tui/chat-ink.test.ts
• apps/cli/src/render/tui/chat-ink.tsx
• apps/cli/src/render/tui/chat-input.test.ts
• apps/cli/src/render/tui/chat-input.ts
• apps/cli/src/render/tui/chat-projection.test.ts
• apps/cli/src/render/tui/chat-projection.ts
• apps/cli/src/render/tui/harness-smoke.test.tsx
• apps/cli/src/render/tui/harness-util.ts
• apps/cli/src/render/tui/home-app.test.tsx
• apps/cli/src/render/tui/home-app.tsx
• apps/cli/src/render/tui/home-controller.test.ts
• apps/cli/src/render/tui/home-controller.ts
• apps/cli/src/render/tui/home-input.test.ts
• apps/cli/src/render/tui/home-input.ts
• apps/cli/src/render/tui/scroll.test.ts
• apps/cli/src/render/tui/scroll.ts
• apps/cli/src/render/tui/transcript-viewport.tsx
• apps/cli/src/render/tui/viewport.test.ts
• apps/cli/src/render/tui/viewport.ts
• apps/cli/tsup.config.ts
• docs/decisions/0021-node-sqlite-driver-better-sqlite3.md
• docs/decisions/0047-cli-framework-commander-ink-clack.md
• docs/decisions/0051-cli-distribution-thin-bundle-private-engine.md
• docs/decisions/0067-node-supported-floor-22-reaffirm-better-sqlite3.md
• docs/decisions/0068-full-screen-tui-renderer-ink7-harness.md
• docs/decisions/README.md
• docs/reference/cli/accessibility.md
• docs/reference/cli/chat-session.md
• docs/reference/cli/commands.md
• docs/reference/cli/home.md
• docs/reference/contracts/config-spec.md
• docs/reference/desktop/database-schema.md
• docs/roadmap/deferred-tasks.md
• docs/roadmap/phases/node-runtime-upgrade.md
• docs/roadmap/phases/phase-2.6-conversational-authoring.md
• docs/standards/testing.md
• docs/tech-stack.md
• package.json
• packages/mcp/src/sdk-websocket.ts
• packages/shared/src/config.test.ts
• packages/shared/src/config.ts
• pnpm-workspace.yaml
• vitest.config.ts

[coderabbitai]

🎯 Functional Correctness | 🔴 Critical | ⚡ Quick win

Remove the duplicate openSessionStore properties.

These object literals contain the same property twice, which produces a TypeScript duplicate-property error. Retain only one definition in each scenario.

Also applies to: 674-674, 688-688, 719-719

🧰 Tools

🪛 ESLint

[error] 657-657: Unsafe assignment of an error typed value.

(@typescript-eslint/no-unsafe-assignment)

---

[error] 657-657: Unsafe assignment of an error typed value.

(@typescript-eslint/no-unsafe-assignment)

---

[error] 657-657: Unsafe member access .db on a type that cannot be resolved.

(@typescript-eslint/no-unsafe-member-access)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/commands/chat.test.ts` at line 657, The object literals in
chat.test.ts define openSessionStore more than once, causing a
duplicate-property TypeScript error. In each affected test case, update the
mocked client/fixture object so it keeps only one openSessionStore definition
and remove the redundant duplicate, using the surrounding test setup and the
openSessionStore stub as the place to fix it.

Source: Linters/SAST tools

[coderabbitai]

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Unsafe any flagged on built.session.runUserCommand — strict-TS violation.

ESLint reports no-unsafe-return/no-unsafe-call/no-unsafe-member-access on this exact line, meaning built.session.runUserCommand is resolving to any even though the enclosing function declares a typed return signature. This is new code in this PR, so it's a regression against strict typing, and would fail a lint-gated CI (at odds with this PR's "green lint" claim).

As per coding guidelines, "TypeScript-first, strict. No any, no unsafe as." Please run the verification below to locate why session/runUserCommand's type isn't resolving cleanly (likely a broken/implicit-any type on AgentSession.runUserCommand or on BuiltChatSession.session), then add an explicit type/import fix rather than letting the any leak through.

#!/bin/bash
set -euo pipefail
rg -n 'runUserCommand' packages/core/src/engine/agent-session.ts -A 6 -B 6
rg -n 'interface BuiltChatSession' apps/cli/src/chat/session-host.ts -A 20
rg -n "session:\s*" apps/cli/src/chat/session-host.ts -A 3 -B 3

🧰 Tools

🪛 ESLint

[error] 1577-1577: Unsafe return of a value of type error.

(@typescript-eslint/no-unsafe-return)

---

[error] 1577-1577: Unsafe call of a type that could not be resolved.

(@typescript-eslint/no-unsafe-call)

---

[error] 1577-1577: Unsafe member access .runUserCommand on a type that cannot be resolved.

(@typescript-eslint/no-unsafe-member-access)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/cli/src/commands/chat.ts` around lines 1570 - 1579, The
`buildInteractiveShellRunner` wrapper is leaking an `any` from
`built.session.runUserCommand`, causing strict-TS lint failures. Fix the source
type on the session path by ensuring `BuiltChatSession.session` and
`AgentSession.runUserCommand` are explicitly typed with `UserCommandOutcome`/the
expected command signature, and import any missing type definitions so the call
in `buildInteractiveShellRunner` resolves without unsafe member access or
return. Do not silence it with `any` or casts; make the underlying
`session`/`runUserCommand` types precise.

Sources: Coding guidelines, Linters/SAST tools

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.1% Duplication on New Code

See analysis details on SonarQube Cloud