bug-fixing

# Bug-Fixing Workflow ## 0. Locate the bug Identify which surface fails: **managed session**, **waitForTextInSurface**, **replay**, **PTY buffer**, **diagnostics**, etc. ## 1. Choose test level - If the bug is **pure library logic** (replay, matching, messages), add or extend a **`tests/*.test.ts`** case that drives **`startManagedTtySession`**, **`waitForTextInSurface`**, or another appropriate **entry point**. - If the bug only shows up in a **downstream** project (e.g. Cypress task wiring), fix may belong in **this repo** (API/diagnostics) **and** the consumer; still add a **tty-assert** test if the contract is wrong here. ## 2. Write a failing test that reproduces the bug - **Minimum test** — one test (or the smallest addition) that covers the bug. - **Assert observable output** — assertion result, thrown message, diagnostic text — not private fields. - **Prefer expected-vs-actual** — `expect(actual).toEqual(expected)` or substring checks that show **what** broke. - **Guard against false positives** — the test must fail when the bug is present. - **Prefer updating over adding** — if an existing test should have caught this, strengthen that test. ## 3. Confirm the failure - **Run** `pnpm test` and verify the **new** behavior fails. - Confirm the failure is for the **right reason** (not missing `canvas`, wrong fixture path, etc.). - If the message is unclear, **improve the assertion** before fixing production code. ## 4. Fix the bug - Implement the **smallest** change that makes the test pass. - Remove debug-only code. ## 5. Confirm green - Run the **new** test and related tests in the same file / area. - Run **`pnpm lint`**. ## 6. Refactor - If tests overlap, simplify; keep one clear story per behavior.