---
phase: 01-safety-foundation
plan: 02
subsystem: terminal
tags: [rust, ratatui, crossterm, signal-hook, atomic-bool, panic-hook, raw-mode]

# Dependency graph
requires: []
provides:
  - "src/terminal.rs: init_terminal(), restore_terminal(), install_panic_hook(), Term type alias"
  - "src/signals.rs: SignalFlags, register_signals(), init_logging() stub"
affects:
  - 01-03
  - all future phases (terminal safety envelope)

# Tech tracking
tech-stack:
  added:
    - "ratatui::crossterm (via re-export — crossterm is a transitive dependency)"
    - "signal-hook 0.4.3 (direct dependency, already in Cargo.toml)"
  patterns:
    - "main screen buffer with Viewport::Fullscreen instead of alternate screen"
    - "let _ = for all cleanup operations in restore and panic hook"
    - "AtomicBool polling for signal handling without async runtime"
    - "take_hook + set_hook for panic hook chaining"

key-files:
  created:
    - src/terminal.rs
    - src/signals.rs
  modified:
    - src/main.rs

key-decisions:
  - "Use ratatui::crossterm re-export instead of direct crossterm dependency (avoids version conflicts)"
  - "SIGINT not registered via signal-hook — handled via crossterm key events for double-press Ctrl+C (Plan 03)"
  - "restore_terminal() never calls ratatui::restore() — that would call LeaveAlternateScreen which was never entered"

patterns-established:
  - "Cleanup-safe pattern: every operation in restore_terminal() and panic hook uses let _ ="
  - "No unwrap() or ? in panic hook — double-panic prevention"
  - "Viewport::Fullscreen for main screen BBS immersive mode"

requirements-completed: [LIFE-01, LIFE-02, LIFE-03, LIFE-04]

# Metrics
duration: 3min
completed: 2026-02-28
---

# Phase 1 Plan 02: Terminal Safety Primitives Summary

**Main-screen BBS terminal with panic recovery hook, SIGHUP/SIGTERM AtomicBool flag registration, and broken-pipe-safe cleanup using ratatui::crossterm re-export**

## Performance

- **Duration:** ~3 min
- **Started:** 2026-02-28T20:10:36Z
- **Completed:** 2026-02-28T20:12:58Z
- **Tasks:** 2
- **Files modified:** 3

## Accomplishments

- Terminal initializes on the main screen buffer (not alternate screen) with raw mode — immersive BBS feel where TUI output persists in scroll history after exit
- Panic hook restores terminal state before printing a BBS-themed user message, then delegates to original hook for sysop details (journald/SSH log)
- SIGHUP and SIGTERM register a shared AtomicBool flag for event loop polling; SIGINT deliberately excluded to enable double-press Ctrl+C via crossterm key events in Plan 03
- All cleanup paths (restore_terminal, panic hook) use `let _ =` on every operation — no double-panic risk

## Task Commits

Each task was committed atomically:

1. **Task 1: Terminal init/restore and panic hook** - `b258b6d` (feat)
2. **Task 2: Signal handling and logging stub** - `966b47e` (feat)

## Files Created/Modified

- `src/terminal.rs` - init_terminal() (main screen, raw mode, Viewport::Fullscreen), restore_terminal() (let _ = pattern), install_panic_hook() (BBS message + original hook delegation), Term type alias
- `src/signals.rs` - SignalFlags struct, register_signals() (SIGHUP + SIGTERM only), should_terminate() poll method, init_logging() Phase 1 stub
- `src/main.rs` - Added `mod signals;` and `mod terminal;` declarations

## Decisions Made

- Used `ratatui::crossterm` re-export path instead of adding crossterm as a direct dependency. Crossterm is a transitive dependency only; using the re-export avoids version conflicts and keeps Cargo.toml minimal.
- SIGINT is NOT registered via signal-hook. The double-press Ctrl+C state machine (SHEL-01) will use crossterm key events (`KeyCode::Char('c') + KeyModifiers::CONTROL`) in the event loop — registering SIGINT twice causes double-handling.
- `restore_terminal()` never calls `ratatui::restore()`. That function calls `LeaveAlternateScreen` unconditionally, which corrupts the terminal since we never entered the alternate screen.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] Used ratatui::crossterm re-export instead of bare crossterm import**
- **Found during:** Task 1 (terminal.rs build verification)
- **Issue:** `use crossterm::...` failed to compile — crossterm is a transitive dependency not listed in Cargo.toml directly. Compiler error: "use of unresolved module or unlinked crate `crossterm`" with hint pointing to `ratatui::crossterm`
- **Fix:** Changed all `crossterm::` imports to `ratatui::crossterm::` re-export path. Also updated the inlined `execute!` calls inside the panic hook closure to use the fully-qualified `ratatui::crossterm::` path.
- **Files modified:** src/terminal.rs
- **Verification:** `cargo build` succeeds
- **Committed in:** b258b6d (Task 1 commit)

---

**Total deviations:** 1 auto-fixed (1 blocking import error)
**Impact on plan:** Necessary fix — imports must resolve for compilation. Using re-export path is semantically identical and more robust against version mismatches.

## Issues Encountered

None beyond the crossterm import deviation documented above.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- Terminal safety envelope is complete: all exit paths (panic, signal, normal quit) restore the terminal correctly
- `install_panic_hook()` should be called first in main() before any terminal init
- `register_signals()` returns a `SignalFlags` whose `should_terminate()` method the Plan 03 event loop will poll at the top of each iteration
- `init_terminal()` and `restore_terminal()` are ready for Plan 03 integration into the application entry point

## Self-Check: PASSED

- src/terminal.rs: FOUND
- src/signals.rs: FOUND
- 01-02-SUMMARY.md: FOUND
- Commit b258b6d (Task 1): FOUND
- Commit 966b47e (Task 2): FOUND

---
*Phase: 01-safety-foundation*
*Completed: 2026-02-28*