plan: bind Escape to cancel in-progress turn when harness canvas is focused

[btipling]

Status: IMPLEMENTED
Source: #703
Type: Single issue — pure Zig (Wasm-only)

Summary

Bind Escape to bridge.queueCancelFromUi() in the harness event scan — the same cancel path as the ■ Stop icon. Today Stop is pointer-only; Escape does nothing to the in-flight round.

Where

One event-scan addition in ui.zig (the same for (0..es.len) loop at ~L617–664 that handles Ctrl+Enter and ↑/↓ history), plus a docs row.

Design

Condition	Behavior
Busy + Escape .down + queue_editing_index == null	bridge.queueCancelFromUi() + mark handled
Busy + Escape .down + queue-row editor open	skip — queue_band.handleEscape() already dismisses the editor (runs during queue_band.paint)
Idle + Escape	no-op — do not clear composer, do not leave the page
.repeat Escape events	skip — only the initial .down fires cancel (same as ■ single-fire)

Why this is safe

queueCancelFromUi() already has a no-op guard when lifecycle != .busy and !has_pending_submit (bridge.zig:288–289), so even a double-fire or a mis-placed Escape during idle is harmless. The queue-edit guard (queue_editing_index == null) matches the existing arrow-history guard at line 647 — the queue-row editor owns Esc.

Placement in the event scan

Insert the Escape handler after the Ctrl+Enter block (~L635) and before the arrow-history block (~L647). Escape has the highest priority after the send chord: if the operator presses Esc, don't also walk history or pass the key to textEntry.

Layers

Layer	Change
Harness (Wasm)	ui.zig +4–6 lines in event scan
Vercel backend	No change
DOM	No change

• No protocol bump — v9 cancel path reused as-is
• No bridge changes — queueCancelFromUi already exposed
• No TS changes → no vitest/typecheck/di-gate/build

Docs

• docs/harness-limits.md: Keyboard table → new row: **Escape** (harness focused, Busy) | Cancel the in-progress turn (same as ■ Stop). Idle: no-op. Queue-row editor: dismisses editor first (does not abort turn)

Ops & docs

• Cloud ops: N/A — no Production mutate
• Caps: No new caps, no existing cap changed
• Zig gates only: zig fmt, zig build harness -Doptimize=Debug, zig build test-rich-invariants, build-harness CI

Testing

Manual smoke plan:

1. Busy + Esc: Send prompt, press Esc while spinning → turn cancels (same as ■ Stop). Composer text preserved.
2. Idle + Esc: Press Esc with no turn running → nothing happens.
3. Queue edit + Esc: Edit a queued row, press Esc → editor closes (existing queue_band behavior). Press Esc again while still Busy → turn cancels.
4. DOM nav overlay + Esc: Open NavMenu → Esc closes menu (host DOM, not canvas).

No host-testable unit test — frame() requires a running bridge + lifecycle state.

Suggested next step

/plan-review → review, then /implement-plan to ship.

[btipling]

Plan review: #705 — HANDOFF-READY ✅

Issue: #705
Source: #703
Status: DRAFT → HANDOFF-READY (to be written to issue body)

Scores

Axis	Score	Notes
Correctness	5	Every claim verified against live main (4bc831b): event scan loop at L618-665, queueCancelFromUi guard at bridge.zig:288-289, handleEscape at queue_band.zig:293-308, queue_editing_index == null at L648, busy at L139, paint order (L584 before L618) correct
Performance	5	One extra ke.code == .escape check in the existing per-event loop; no alloc, no I/O, .repeat skipped early
Architectural soundness	5	Pure Wasm — ui.zig only; no protocol bump, no bridge changes, no TS changes
Testing	3	No host-testable path for ui.frame() (same class as every ui.zig change); manual smoke plan covers 4 scenarios adequately
Cloud ops	N/A	No Production mutate
Living docs	5	Single new row in keyboard table, format matches existing rows; ↑/↓ row already correct (pre-existing fix from PR #707)
Cap governance	5	No new caps, no existing caps changed

Baseline — all 6 claims grounded

#	Claim	Live code	Verdict
1	Event scan loop at ~L617-664	ui.zig:618-665 — exact match (off by 1 from plan, within tolerance)	✅
2	queueCancelFromUi no-op guard	bridge.zig:288-289 — if (lifecycle != .busy and !has_pending_submit) return;	✅
3	handleEscape in queue_band	queue_band.zig:293-308 — checks .escape + .down, marks handled, calls cancelEdit()	✅
4	queue_editing_index == null guard exists at L647	ui.zig:648 — if (state.queue_editing_index == null) on arrow block (off by 1, within tolerance)	✅
5	busy variable in scope	ui.zig:139 — var busy = life == .busy; — shared scope for entire frame()	✅
6	queue_band.paint runs before event scan	ui.zig:584 (paint) vs ui.zig:618 (event scan) — handleEscape fires first and marks handled → scan loop skips it	✅

Findings

#	Sev	Issue	Resolution
1	Minor (L8)	Line numbers drifted: plan says ~L617-664 and ~L647; live code is 618-665 and 648	Within tolerance (off by 1); no plan body change needed
2	Minor (L8)	Plan's doc-update section has a self-dialogue about ↑/↓ row that resolves itself — correctly notes plan #704 / PR #707 already fixed it	Implementer: only add the Escape row; ↑/↓ row is already correct

Design quality notes

The algorithm is well-scoped and safe. 4-6 lines in the existing event scan loop, reuses queueCancelFromUi as-is. The queue_editing_index == null guard is belt-and-suspenders — handleEscape() already marks events handled before the scan loop starts (L584 before L618), but the guard catches any future reordering.

Mark-handled policy: The plan text says "don't also walk history or pass the key to textEntry." The implementer should always mark Escape handled (e.handled = true) for all states (busy + idle), and only conditionally call queueCancelFromUi() when busy. This prevents an idle Escape from reaching the textEntry (where it could hypothetically trigger future dvui behavior). The bridge guard at L288-289 makes double-fire harmless regardless.

Ordering: Escape inserts between Ctrl+Enter (L635) and the arrow-history comment block (L637). This is correct — Escape should not steal Ctrl+Enter, and should prevent arrow walking on the same frame.

Residual risk

Near-zero. One extra key check in a loop that already runs 4+ checks per event. No alloc, no I/O, no protocol bump, no bridge changes. The only failure mode is a mis-ordered handler that steals Escape from queue_band, but handleEscape() runs first (during queue_band.paint at L584) and marks the event handled before the scan loop sees it.

Merge-gate residual risk

None. No TS changes → no vitest/typecheck/di-gate/build needed. Zig gates: zig fmt, zig build harness -Doptimize=Debug, zig build test-rich-invariants, build-harness CI.

---

Verdict: Ready for /implement-plan. The algorithm is simple, well-placed, and reuses existing infrastructure. No blockers.