fix(tui): stop early frames anchoring to the shell cursor

pi-tui paints on requestRender before ui.start(), so frames rendered during
construction and mounting were anchored at the shell cursor and the fixed
layout's scroll-to-home pushed the panel border into scrollback. Rendering is
now gated until the event loop starts, which runs before the main TUI mounts.

The gate writes a private pi-tui field, so a test asserts both the gate and
ui.start() clearing it — an upgrade that changes either fails there.

Author: elkaix

apps/pythinker-code/src/tui/pythinker-tui.ts

@@ -468,9 +468,14 @@ export class PythinkerTUI {
         return;
       }
 
-      const shouldReplayHistory = await this.initMainTui();
+      // Start the loop before mounting anything: pi-tui paints on invalidate
+      // even before ui.start(), so mounting first anchors early frames to the
+      // shell cursor and startEventLoop's scroll-to-home would push the live
+      // frame's top rows into scrollback for good. Same order as the
+      // migration branch above.
       this.startEventLoop();
       try {
+        const shouldReplayHistory = await this.initMainTui();
         this.startBackgroundFdAutocomplete();
         await this.finishStartup(shouldReplayHistory);
         this.startKeybindingsWatcher();
@@ -550,6 +555,14 @@ export class PythinkerTUI {
 
   private startEventLoop(): void {
     const start = (): void => {
+      // The fixed layout emits exactly `terminal.rows` lines per frame, and
+      // pi-tui's first render assumes a clean screen. Any shell output already
+      // on screen would scroll the frame's top rows (panel border included)
+      // out of view for good, so scroll the history up first and start at home.
+      if (this.state.layout === 'fixed') {
+        const rows = this.state.terminal.rows;
+        this.presentation.writeTerminalControl('\n'.repeat(Math.max(1, rows)) + '\u001B[H');
+      }
       this.presentation.start(() => {
         this.refreshFooter();
         this.state.ui.requestRender();

apps/pythinker-code/src/tui/tui-state.ts

@@ -71,6 +71,11 @@ export function createTUIState(options: PythinkerTUIOptions): TUIState {
 
   const terminal = new ProcessTerminal();
   const ui = new TUI(terminal);
+  // Gate rendering until the event loop starts: pi-tui paints on requestRender
+  // even before ui.start() (stopped defaults to false), so construction-time
+  // renders would anchor frames to the shell cursor. The field is private in
+  // pi-tui's types; ui.start() flips it back to false.
+  (ui as unknown as { stopped: boolean }).stopped = true;
 
   const transcriptContainer = new GutterContainer(CHROME_GUTTER, CHROME_GUTTER);
   const activityContainer = new GutterContainer(CHROME_GUTTER, CHROME_GUTTER);

apps/pythinker-code/test/tui/create-tui-state.test.ts

@@ -36,6 +36,27 @@ thinkingLevel: 'off',
 }
 
 describe('createTUIState', () => {
+  it('gates rendering until the event loop starts, and ui.start() re-opens it', () => {
+    // The gate writes pi-tui's PRIVATE `stopped` field, and `ui.start()` clearing
+    // it again is what lets the TUI ever paint. If an upgrade renames the field or
+    // stops resetting it, the app renders nothing — a silent, total failure. This
+    // asserts both halves so that upgrade fails here instead of in someone's terminal.
+    const state = createTUIState({
+      initialAppState: fakeInitialAppState(),
+      startup: { continueLast: false, yolo: false, auto: false, plan: false },
+      layout: 'fixed',
+    });
+    const ui = state.ui as unknown as { stopped: boolean; start: () => void };
+
+    expect(ui.stopped).toBe(true);
+
+    vi.spyOn(state.terminal, 'start').mockImplementation(() => {});
+    vi.spyOn(state.terminal, 'hideCursor').mockImplementation(() => {});
+    ui.start();
+
+    expect(ui.stopped).toBe(false);
+  });
+
   it('initializes all fields with sensible defaults', () => {
     const opts: PythinkerTUIOptions = {
       initialAppState: fakeInitialAppState(),