<!-- Terminal verification is ENABLED for this project. The stop hook
     enforces a terminal cycle whenever an edited file matches
     `terminal.verifyPatterns`. -->

## ⚠️ CRITICAL: when NOT to use terminal-devtools

**`terminal-devtools` is ONLY for programs you run in a terminal** — CLIs, REPLs, shells, and full-screen TUIs. It spawns the program attached to a PTY (like tmux) so you can drive it and observe its output. Do **NOT** call `MCP:tdt_*` tools for changes with no terminal-observable behavior.

**How to tell whether the change is terminal-observable:**
- A CLI / command entrypoint (`bin/`, a `main()` that parses argv, a `package.json` `bin` field, a Cobra / Click / argparse / Commander command)
- A REPL or interactive shell the change affects
- A full-screen TUI (curses / blessed / ink / bubbletea / ratatui)

If the change is web-only UI with no terminal surface, that belongs to the **browser cycle** — do NOT call any `MCP:tdt_*` tools for it.

**Misconfiguration recovery.** If this cycle activated but the change has no terminal-observable behavior, the operator enabled the terminal cycle by mistake. The stop hook will keep blocking with `incomplete_tools` until `maxRetries` is exhausted. Don't fabricate a PTY session. Stop and tell the user clearly: the change has no terminal surface; ask them to run `ironbee terminal disable` to unblock the gate.

## Terminal flow

1. **Pick an evidence path** per changed code area:
   - **Run-evidence path** (a one-shot command confirms the change works):
     - Run the command in a PTY: `MCP:tdt_pty_run` with the command line — it returns the full output AND the exit code in one call.
     - Confirm the output is what the change should produce AND the exit code is expected (`0` for success, or the specific non-zero code a flag/error path should return). The exit code is as important as the text — a command that prints the right thing but exits non-zero is a fail.
   - **Interactive-evidence path** (driving a REPL / shell / full-screen TUI confirms the change is live):
     - Spawn the program attached to a PTY: `MCP:tdt_pty_start` — it returns a `paneId` you use for the rest of the flow.
     - Drive it with input: `MCP:tdt_interaction_send-keys` (tmux key syntax — `Enter`, `C-c`, `Up`, `Tab`, …) for control keys / navigation, or `MCP:tdt_interaction_send-text` to type a literal string.
     - **Synchronize before reading** — call `MCP:tdt_sync_wait-for` to block until the expected output appears, rather than guessing a delay.
     - Capture the output: `MCP:tdt_content_capture` — use `mode: stream` for line-oriented programs (REPLs, shells; pass an incremental `since` cursor to read only new lines) and `mode: screen` for full-screen TUIs (the rendered screen buffer).
     - Confirm the captured output shows the expected result.
     - Stop the pane when done: `MCP:tdt_pty_stop`.
     - **Auxiliary (NOT evidence — sync/setup/correlation only):** `MCP:tdt_sync_wait-for-idle` (wait until output stops changing), `MCP:tdt_content_get-cursor` (current cursor position), `MCP:tdt_pty_resize` / `MCP:tdt_pty_signal` / `MCP:tdt_pty_list` (manage panes). None of these count toward the gate — they help you drive the test, they don't inspect it.

**Batch (speed):** on the run-evidence path each `MCP:tdt_pty_run` is one round-trip already. On the interactive path, prefer `MCP:tdt_sync_wait-for` over fixed delays so you read exactly when the output is ready; capture incrementally with `mode: stream` + a `since` cursor instead of re-reading the whole buffer.

### Verdict fields
The verdict is platform-agnostic — submit only semantic judgment:

```json
{
  "session_id": "<sid>",
  "status": "pass",
  "checks": ["`mycli --json` emits valid JSON and exits 0", "REPL `:help` lists the new command"]
}
```

On fail, include `issues`. On pass after a previous fail, include `fixes`.

Terminal-cycle pass criteria:
- **Run-evidence**: the command was run via `MCP:tdt_pty_run` AND its output and exit code confirm the change behaved correctly.
- **Interactive-evidence**: a pane was spawned (`MCP:tdt_pty_start`) AND input was driven (`MCP:tdt_interaction_send-keys` / `MCP:tdt_interaction_send-text`) AND output was captured (`MCP:tdt_content_capture`) AND it shows the expected result.

## Multi-cycle (browser + terminal simultaneously)

Both cycles can be active simultaneously. One `verification-start` covers all active cycles; one platform-agnostic verdict covers them all; one retry counter applies globally.