<!-- 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 with terminal-observable behavior** — CLIs, REPLs, shells, and full-screen TUIs that you can drive by spawning them attached to a PTY. Do **NOT** call `tdt_*` tools for changes that produce no terminal-observable behavior.

**How to tell whether the change has terminal-observable behavior:**
- A CLI entrypoint (`bin/` script, `package.json` `"bin"` field, a `main()` that parses argv, a `cobra`/`commander`/`click`/`clap` command tree)
- A REPL / interactive prompt the user types into
- A full-screen TUI (`blessed`, `ink`, `ratatui`, `bubbletea`, `ncurses`, …)
- A script / build target / shell command whose stdout, stderr, or exit code changed

If the change is a web-only UI with no command-line or terminal surface — that's the **browser cycle**, not this one. Do NOT call any `tdt_*` tools.

**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 attempt to spawn a PTY. Stop and tell the user clearly: this change has no terminal-observable behavior; ask them to run `ironbee terminal disable` to unblock the gate.

## Terminal flow

The terminal cycle drives CLIs / REPLs / TUIs by spawning them attached to a PTY (like tmux). Pick the evidence path that fits the changed code area:

1. **Pick an evidence path** per changed code area:
   - **Run-evidence path** (one-shot command confirms the change works):
     - Run the affected command end-to-end: `mcp__terminal-devtools__tdt_pty_run` — it spawns the command attached to a PTY, runs it to completion, and returns the FULL output plus the exit code in one call. Best for non-interactive CLIs, build targets, scripts, and test runs.
     - Confirm the returned output shows the expected result AND the exit code matches expectation (`0` for success; the expected non-zero code when failure is the change under test).
   - **Interactive-evidence path** (driving a live session confirms an interactive change):
     - Spawn the program attached to a PTY: `mcp__terminal-devtools__tdt_pty_start` — returns a `paneId` you reference for the rest of the flow. Best for REPLs, shells, and full-screen TUIs.
     - Drive input to exercise the changed code: `mcp__terminal-devtools__tdt_interaction_send-keys` (tmux key syntax — `Enter`, `C-c`, `Up`, `Tab`, …) for control keys / navigation, `mcp__terminal-devtools__tdt_interaction_send-text` for literal text.
     - **Synchronize before reading** — block until the expected output appears with `mcp__terminal-devtools__tdt_sync_wait-for` (prefer this over fixed delays).
     - Capture the output: `mcp__terminal-devtools__tdt_content_capture` — use `mode: stream` for line-oriented programs (REPLs, shells; supports an incremental `since` cursor so you read only new lines), and `mode: screen` for full-screen TUIs (snapshots the rendered screen).
     - Confirm the capture shows the expected result for the change.
     - Stop the pane when done: `mcp__terminal-devtools__tdt_pty_stop`.
     - **Auxiliary (NOT evidence — synchronization / housekeeping only):** `mcp__terminal-devtools__tdt_sync_wait-for-idle` (block until output settles), `mcp__terminal-devtools__tdt_content_get-cursor` (read the stream cursor position), `mcp__terminal-devtools__tdt_pty_resize` (resize the PTY), `mcp__terminal-devtools__tdt_pty_signal` (send a signal), `mcp__terminal-devtools__tdt_pty_list` (list active panes). None of these count toward the gate — they help you drive the session, they don't inspect the change.

**Batch (speed):** on the run-evidence path, a single `mcp__terminal-devtools__tdt_pty_run` already does the whole thing (spawn + run + capture + exit code), so there's nothing to batch. On the interactive-evidence path, `tdt_pty_start` runs standalone first (prerequisite); then batch a coherent sequence of `tdt_interaction_send-*` + `tdt_sync_wait-for` + `tdt_content_capture` into one `mcp__terminal-devtools__tdt_execute` — the capture reads the state after the batched input, so to assert an intermediate state add a `tdt_sync_wait-for` + capture at that point too.

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

```json
{
  "session_id": "<sid>",
  "status": "pass",
  "checks": ["`mycli build` exits 0 and prints the new summary line", "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 affected command was run via `tdt_pty_run` AND its output AND exit code confirm the change behaved correctly.
- **Interactive-evidence**: a pane was spawned (`tdt_pty_start`) AND input was driven (`tdt_interaction_send-keys` / `tdt_interaction_send-text`) AND output was captured (`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.