feat: alt screen でスクロールバックを無効化し上へのスクロールをロック (#5)

## 概要


全画面レイアウト（#3）でも端末を**上へスクロールできてしまう**問題を修正する。原因は通常スクリーンバッファのまま描画しており、シェルの過去出力などのスクロールバックが残っていたこと。

起動時に **alt screen（代替スクリーンバッファ, `\x1b[?1049h`）** へ入るようにした。alt screen
にはスクロールバックが存在しないため、vim / htop と同様にスクロールがロックされる。終了時は `\x1b[?1049l` で
leave し、元のシェル画面を復元する。

## 変更点

- **`src/utils/alt-screen.ts`（新規）**: enter/leave の薄い I/O ラッパ。`leave`
は冪等。クラッシュ時に端末を alt screen に取り残さないよう `process.on('exit')` に保険登録し、明示 leave
で解除する。
- **`src/utils/alt-screen.spec.ts`（新規）**: enter/leave シーケンス・冪等性・exit
フックの登録/解除・exit イベント経由の復元をカバー。
- **`src/index.tsx`**: 合成ルートで配線。`process.stdout.isTTY` かつ起動時 `rows >=
MIN_FULLSCREEN_ROWS` のときだけ
enter（インライン描画フォールバック時は端末スクロールに頼るため通常バッファのまま）。判定は起動時の一度きり（途中リサイズでバッファを切り替えると画面が壊れるため追従しない）。終了時の残存
worktree 案内は **leave 後**に書き、シェル履歴へ残す。
- **docs / rules**: `TECH_NOTES.md` / `ARCHITECTURE.md` / `TASKS.md` /
`.claude/rules/ink-components.md` を実装に合わせて更新。

## 設計判断

- alt screen の enter/leave は純粋ロジックではなく端末への I/O なので `utils/`
に配置（アーキテクチャ規約: 純粋ロジックと I/O の分離）。
- フォールバック時（非 TTY / 低い端末）は enter しない — インライン描画は端末スクロールに依存するため。

## テスト計画

- [x] `npm test` — 147件 全緑（coverage 閾値クリア）
- [x] `npm run lint` / `npm run typecheck` / `npm run build` — 緑
- [ ] 手動: 使い捨てリポジトリで `npm run dev` 起動 → マウスホイールで上へスクロールできないこと
- [ ] 手動: 終了後にシェル画面が復元され、残存 worktree 案内が履歴に残ること
- [ ] 手動: 低い端末（< 16 行）でインライン描画へフォールバックし、通常どおりスクロールできること

Author: takecchi

.claude/rules/ink-components.md

@@ -23,6 +23,10 @@
   やめてインライン描画へフォールバックする（クリップで入力欄・フッタが消えるのを防ぐ）。
   判定は `isFullscreenViewport(rows)`。
 - 各 view は `flexGrow={1}` の縦 flex にし、入力欄+フッタは flexGrow スペーサで最下部に固定する。
+- 全画面で描くときは起動時に **alt screen**（`\x1b[?1049h`、`utils/alt-screen.ts`）へ入る。
+  通常バッファのままだとスクロールバックが残り上へスクロールできてしまうため。
+  インライン描画フォールバック時（TTY でない / 起動時 rows が閾値未満）は enter しない。
+  配線は `src/index.tsx`（合成ルート）で行い、終了メッセージは leave 後に書く。
 - **`<Static>` は使わない**。Static はスクロールバック側に書き出すため、全画面レイアウトでは
   ビューポート外に消えて見えなくなる。追記ログは「末尾ビューポート」
   （`flexGrow={1}` + `overflowY="hidden"` + `justifyContent="flex-end"`）で最新行を下端に表示し、

docs/ARCHITECTURE.md

@@ -151,7 +151,7 @@ interface SessionState {
 
 ### UI (ui/)
 
-Claude Code の実画面に寄せる: 画面は**端末の縦幅いっぱい**（web の 100dvh 相当。`App` が root Box に `useWindowSize()` の rows を指定。極端に低い端末では `isFullscreenViewport` が false になりインライン描画へフォールバック）に描画し、下部に**上下の全幅横罫線だけ**の入力欄（`PromptInput`、角丸枠ではない）、その下にモード行（`StatusFooter` = `⏵⏵ auto mode on (shift+tab to cycle)` + 文脈ヒント）を flexGrow スペーサで**最下部に固定**。ヘッダは枠なしのワードマーク。色とグリフは `theme.ts` に集約。
+Claude Code の実画面に寄せる: 画面は**端末の縦幅いっぱい**（web の 100dvh 相当。`App` が root Box に `useWindowSize()` の rows を指定。極端に低い端末では `isFullscreenViewport` が false になりインライン描画へフォールバック）に描画し、全画面時は起動時に **alt screen**（`utils/alt-screen.ts`）へ入ってスクロールバックを無効化（上へのスクロールをロック）し、下部に**上下の全幅横罫線だけ**の入力欄（`PromptInput`、角丸枠ではない）、その下にモード行（`StatusFooter` = `⏵⏵ auto mode on (shift+tab to cycle)` + 文脈ヒント）を flexGrow スペーサで**最下部に固定**。ヘッダは枠なしのワードマーク。色とグリフは `theme.ts` に集約。
 
 - `App`: ビュー状態（`list` | `detail:<id>`）と全体キーバインドを管理。`cwd` を受け取りバナーへ渡す。
 - `Banner`: 起動時ヘッダ（`✻ codiva` + サブタイトル + cwd）。枠なし3行、一覧上部に表示。

docs/TASKS.md

@@ -116,6 +116,7 @@ UI なし。すべてユニットテストで駆動する。
 ## Phase 6: Backlog（MVP後、着手前にユーザーと相談）
 
 - [x] 全画面（100dvh 相当）レイアウト: root に端末 rows を指定、入力欄+フッタを下部固定、詳細ログは `<Static>` から末尾ビューポートへ置換
+- [x] alt screen（`\x1b[?1049h`/`\x1b[?1049l`）でスクロールバックを無効化し、上へのスクロールをロック（`utils/alt-screen.ts`）
 - [ ] 詳細ビューのログスクロール（末尾ビューポートは最新行のみ表示。過去ログを遡る手段が未実装）
 - [ ] 入力欄の複数行化（Shift+Enter 改行、行数に応じて上に伸び、上限超過で内部スクロール — Claude Code 同等）
 - [x] アプリ再起動後のセッション復元（`.codiva/state.json` + SDK `resume`）

docs/TECH_NOTES.md

@@ -174,7 +174,7 @@ function toUserMessage(text: string): SDKUserMessage {
 - **`useInput`**: グローバルキーハンドラ。フォーカス管理は `useFocus` もあるが、MVP はビュー単位の単純な状態分岐で足りる。
 - **`useApp().exit()`**: 終了。終了前に SessionManager.dispose()（全 abort）を呼ぶ。
 - 再描画スロットリング: コアからの onChange を UI 側で ~100ms デバウンス。`useSyncExternalStore` の getSnapshot が返す参照が変わらなければ再描画されない点を利用する。
-- alt-screen（全画面）にしたい場合は起動時に `\x1b[?1049h`、終了時に `\x1b[?1049l` を書く。MVP では必須ではない。
+- **alt screen（代替スクリーンバッファ）**: 全画面レイアウトでも通常バッファのままだとシェルの過去出力がスクロールバックに残り、上へスクロールできてしまう。起動時に `\x1b[?1049h` で alt screen に入り、終了時に `\x1b[?1049l` で抜ける（`utils/alt-screen.ts`）。alt screen にはスクロールバックが存在しないため vim / htop と同様にスクロールがロックされ、終了すると元の画面が復元される。enter するのは「TTY かつ起動時の rows が `MIN_FULLSCREEN_ROWS` 以上」のときだけ（インライン描画フォールバック時はスクロールバックに頼るため通常バッファのまま）。終了時の残存 worktree 案内は leave 後に書き、通常バッファに残す。クラッシュ時の取り残し防止に `process.on('exit')` で leave を保険登録する。
 
 ## git worktree の実装メモ
 

src/index.tsx

@@ -1,6 +1,7 @@
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { render } from 'ink';
 import {
+  isFullscreenViewport,
   messages,
   notificationFor,
   resolveLang,
@@ -10,6 +11,7 @@ import {
 } from '@/core';
 import {
   defaultStatePath,
+  enterAltScreen,
   loadConfig,
   loadState,
   notify,
@@ -93,6 +95,13 @@ async function main(): Promise<void> {
   process.once('SIGTERM', flushSyncAndExit(143));
   process.once('SIGHUP', flushSyncAndExit(129));
 
+  // 全画面レイアウトで描くときは alt screen に入り、スクロールバックを無効化する
+  // （上へのスクロールをロック）。低すぎる端末はインライン描画へフォールバックし
+  // 端末スクロールに頼るため、通常バッファのまま。判定は起動時の一度きり
+  // （途中のリサイズでバッファを切り替えると画面が壊れるため追従しない）。
+  const useAltScreen = process.stdout.isTTY && isFullscreenViewport(process.stdout.rows ?? 0);
+  const leaveAltScreen = useAltScreen ? enterAltScreen(process.stdout) : undefined;
+
   const { waitUntilExit } = render(<App manager={manager} cwd={repoRoot} messages={t} />, {
     exitOnCtrlC: false,
   });
@@ -105,6 +114,9 @@ async function main(): Promise<void> {
   }
   await saveState(manager.persistableState(), statePath).catch(() => undefined);
 
+  // 終了メッセージは alt screen を抜けてから書き、通常バッファ（シェルの履歴）に残す。
+  leaveAltScreen?.();
+
   // Sessions are aborted on quit but their worktrees are intentionally kept so
   // no work is lost. Tell the user where they are.
   const remaining = manager.activeWorktreePaths();

src/utils/alt-screen.spec.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { enterAltScreen } from './alt-screen';
+
+const ENTER = '\x1b[?1049h';
+const LEAVE = '\x1b[?1049l';
+
+function fakeStream(): { writes: string[]; stream: { write(text: string): void } } {
+  const writes: string[] = [];
+  return { writes, stream: { write: (text: string) => writes.push(text) } };
+}
+
+describe('enterAltScreen', () => {
+  it('enter で ?1049h を書き、leave で ?1049l を書く', () => {
+    const { writes, stream } = fakeStream();
+    const leave = enterAltScreen(stream);
+    expect(writes).toEqual([ENTER]);
+    leave();
+    expect(writes).toEqual([ENTER, LEAVE]);
+  });
+
+  it('leave は冪等（2回呼んでも ?1049l は1回だけ）', () => {
+    const { writes, stream } = fakeStream();
+    const leave = enterAltScreen(stream);
+    leave();
+    leave();
+    expect(writes).toEqual([ENTER, LEAVE]);
+  });
+
+  it('クラッシュ保険の exit フックを登録し、leave で解除する', () => {
+    const before = process.listenerCount('exit');
+    const { stream } = fakeStream();
+    const leave = enterAltScreen(stream);
+    expect(process.listenerCount('exit')).toBe(before + 1);
+    leave();
+    expect(process.listenerCount('exit')).toBe(before);
+  });
+
+  it('process の exit イベントで leave される（明示 leave を忘れても復元）', () => {
+    const { writes, stream } = fakeStream();
+    enterAltScreen(stream);
+    process.emit('exit', 0);
+    expect(writes).toEqual([ENTER, LEAVE]);
+    // exit フック経由でも解除・冪等化されている
+    process.emit('exit', 0);
+    expect(writes).toEqual([ENTER, LEAVE]);
+  });
+});

src/utils/alt-screen.ts

@@ -0,0 +1,33 @@
+/**
+ * 代替スクリーンバッファ（alternate screen buffer）の enter/leave。
+ * 通常バッファのまま全画面描画するとシェルの過去出力がスクロールバックに残り
+ * 上へスクロールできてしまう。alt screen にはスクロールバックが存在しないため、
+ * vim / htop と同様にスクロールがロックされ、leave すると元の画面が復元される。
+ */
+const ENTER_ALT_SCREEN = '\x1b[?1049h';
+const LEAVE_ALT_SCREEN = '\x1b[?1049l';
+
+/** テストでフェイクを注入できるよう、必要な write だけに絞ったストリーム型。 */
+export interface AltScreenStream {
+  write(text: string): unknown;
+}
+
+/**
+ * alt screen に入り、抜けるための関数を返す。leave は冪等。
+ * クラッシュ（uncaughtException 等）で明示 leave を通らなくても端末を
+ * alt screen に取り残さないよう、process の exit イベントにも保険で登録する。
+ */
+export function enterAltScreen(stream: AltScreenStream = process.stdout): () => void {
+  stream.write(ENTER_ALT_SCREEN);
+  let left = false;
+  const leave = (): void => {
+    if (left) {
+      return;
+    }
+    left = true;
+    process.removeListener('exit', leave);
+    stream.write(LEAVE_ALT_SCREEN);
+  };
+  process.on('exit', leave);
+  return leave;
+}

src/utils/index.ts

@@ -1,3 +1,4 @@
+export * from './alt-screen';
 export * from './config';
 export * from './git';
 export * from './notify';