fix(verify-pypi): gh_watch multi-run and monitoring track plans 121-126

docs/plans/2026-05-24-020-verify-pypi-regression-post-268-plan.md

@@ -40,8 +40,8 @@ Plan 019 landed via PR #268 but remained `in_progress` without post-merge verifi
 | Stale branch cleanup | `fix/pypi-verify-regression-concurrency` deleted (merged #275, stray docs) | ✅ plan 026 |
 | Local CLI PyPI parity (plan 042) | holopatcher/kotormcp install from PyPI; kotordiff not on PyPI; `--help` rc=1 (workflow continue-on-error) | ✅ pass (parity with CI skip semantics; py3.14 local) |
 | Local PyPI parity (plan 041) | ephemeral venv `pip install pykotor[all]` + workflow import scripts | ✅ pass (Linux/py3; CI matrix still queued) |
-| Verify PyPI CI (post-#277) | https://github.com/OpenKotOR/PyKotor/actions/runs/26372746392 |  ✅ success — **Check trigger** on `8916e2f`|
-| Forward Commits (post-#306) | https://github.com/OpenKotOR/PyKotor/actions/runs/26547345351 |  ⏳ pending — merge on `44ccf2a`|
+| Verify PyPI CI (post-#277) | https://github.com/OpenKotOR/PyKotor/actions/runs/26549547772 |  ✅ success — **Check trigger** on `ca61ce8`|
+| Forward Commits (post-#306) | https://github.com/OpenKotOR/PyKotor/actions/runs/26549293445 |  ❌ failure — merge on `ca61ce8`|
 | Local FC dry-run (plan 051) | cherry-pick `49da28057`→bleeding-edge + workflow restore | ✅ pass (`d8dc53968`; docs conflict auto-resolved) |
 | Solution doc (plan 050) | `docs/solutions/testing/verify-pypi-regression-closeout.md` | ✅ prefer/defer/avoid + local command |
 | Local verify script (plan 048) | `python3 .github/scripts/local_verify_pypi_slice.py` | ✅ pass (replaces manual plan 047 slice) |
@@ -62,9 +62,9 @@ Plan 019 landed via PR #268 but remained `in_progress` without post-merge verifi
 
 **Track status (plan 051):** **Monitoring-only.** Code and local parity complete (#268–#306, plans 019–066). Await CI green on [26372746392](https://github.com/OpenKotOR/PyKotor/actions/runs/26372746392) and FC [26365648344](https://github.com/OpenKotOR/PyKotor/actions/runs/26365648344); no further workflow changes unless CI reports new failures.
 
-**Last CI check (plan 114):** 2026-05-27 — verify [26372746392](https://github.com/OpenKotOR/PyKotor/actions/runs/26372746392) success on `8916e2f`; FC [26547345351](https://github.com/OpenKotOR/PyKotor/actions/runs/26547345351) pending on `44ccf2a`.
+**Last CI check (plan 214):** 2026-05-29 — verify [26549547772](https://github.com/OpenKotOR/PyKotor/actions/runs/26549547772) success on `ca61ce8`; FC [26549293445](https://github.com/OpenKotOR/PyKotor/actions/runs/26549293445) failure on `ca61ce8`.
 
-**Plans:** 019–114 document the closeout track; authoritative learning in `docs/solutions/testing/verify-pypi-regression-closeout.md`.
+**Plans:** 019–214 document the closeout track; authoritative learning in `docs/solutions/testing/verify-pypi-regression-closeout.md`.
 
 ---
 

docs/plans/2026-05-24-115-investigate-drift-active-wait-plan.md

@@ -0,0 +1,37 @@
+---
+title: "fix: investigate ci drift briefing wait on active runs"
+type: fix
+status: active
+date: 2026-05-28
+origin: docs/solutions/testing/verify-pypi-regression-closeout.md
+---
+
+# fix: Investigate CI Drift Active-Run Wait (plan 115)
+
+## Summary
+
+When `proceed_reason` is `investigate_ci_drift` but FC/verify runs are still active, agents should wait before `--lfg-refresh --dry-run`. Enrich drift briefing with structured fields and route to `--lfg-preflight-watch`.
+
+---
+
+## Problem Frame
+
+Live: FC run IDs churn while queued; drift briefing only has text notes and suggests refresh dry-run prematurely.
+
+---
+
+## Requirements
+
+- R1. `_build_ci_drift_detail` exposes doc vs live drift fields and `wait_recommended`.
+- R2. `_build_drift_refresh_commands` lists refresh/closeout/preflight-watch commands.
+- R3. `investigate_ci_drift` briefing includes `drift`, `refresh_commands`, active run refs, `monitor_commands` when waiting.
+- R4. `_build_proceed_hint` prefers `--lfg-preflight-watch` when drift + active runs.
+- R5. stderr `wait=true` and drift field hints; tests; `PLAN_TRACK_CAP` `115`; docs.
+
+---
+
+## Test scenarios
+
+- T1. Drift + FC queued → `wait_recommended` true, command includes preflight-watch.
+- T2. Drift + both terminal → `refresh_commands.closeout` present.
+- T3. stderr includes `wait=true` when active.

docs/plans/2026-05-24-116-defer-preflight-watch-command-plan.md

@@ -0,0 +1,36 @@
+---
+title: "fix: defer fc-active command routes to preflight-watch"
+type: fix
+status: active
+date: 2026-05-28
+origin: docs/solutions/testing/verify-pypi-regression-closeout.md
+---
+
+# fix: Defer Preflight-Watch Command (plan 116)
+
+## Summary
+
+When deferred on active FC (`fc_active_pending`), `monitor_commands` includes `preflight_watch` but `command`/`proceed_hint` still suggest manual `--lfg-preflight` retry. Route primary command to **`--lfg-preflight-watch`**.
+
+---
+
+## Problem Frame
+
+Live: `fc_active_pending`; agents get watch_fc_run but command says re-run preflight manually.
+
+---
+
+## Requirements
+
+- R1. `_defer_preflight_watch_recommended` true for fc/verify active defer reasons.
+- R2. `_build_proceed_hint` uses `--lfg-preflight-watch` for those defers.
+- R3. Defer briefing sets `watch_recommended` and `command` to preflight-watch.
+- R4. Defer stderr includes `watch_recommended=true`; tests; `PLAN_TRACK_CAP` `116`; docs.
+
+---
+
+## Test scenarios
+
+- T1. fc_active_pending proceed_hint → preflight-watch.
+- T2. Defer briefing command matches preflight_watch monitor command.
+- T3. stderr includes watch_recommended=true.

docs/plans/2026-05-24-117-defer-sha-gap-detail-plan.md

@@ -0,0 +1,36 @@
+---
+title: "fix: defer briefing sha gap detail and preflight retry"
+type: fix
+status: active
+date: 2026-05-28
+origin: docs/solutions/testing/verify-pypi-regression-closeout.md
+---
+
+# fix: Defer SHA Gap Detail (plan 117)
+
+## Summary
+
+Defer `monitor_commands.preflight_retry` incorrectly copies the watch `command`. Fix to always single-shot preflight. Add structured **`sha_gap`** on defer when FC SHA lags master.
+
+---
+
+## Problem Frame
+
+Live: `fc_active_pending`; `preflight_retry` duplicates preflight-watch; agents lack structured SHA fields beyond text notes.
+
+---
+
+## Requirements
+
+- R1. `_build_defer_monitor_commands` always sets `preflight_retry` to `--lfg-preflight --json`.
+- R2. `_build_defer_sha_gap_detail` exposes fc_head, master_sha, queued_hours.
+- R3. Defer briefing attaches `sha_gap` when FC stale gap pending.
+- R4. Defer stderr includes `sha_gap=` short form; tests; `PLAN_TRACK_CAP` `117`; docs.
+
+---
+
+## Test scenarios
+
+- T1. Watch defer → preflight_retry is single-shot, command is watch.
+- T2. fc_active_pending briefing includes sha_gap with head SHAs.
+- T3. stderr includes sha_gap= prefix.

docs/plans/2026-05-24-118-lfg-gate-watch-plan.md

@@ -0,0 +1,37 @@
+---
+title: "feat: lfg gate-watch and defer post-terminal commands"
+type: feat
+status: active
+date: 2026-05-28
+origin: docs/solutions/testing/verify-pypi-regression-closeout.md
+---
+
+# feat: LFG Gate-Watch + Post-Terminal Commands (plan 118)
+
+## Summary
+
+Agents repeatedly run `--lfg-gate` (exit 2) while FC is queued. Add **`--lfg-gate-watch`** (gate + preflight-watch) and defer **`post_terminal_commands`** for after FC completes.
+
+---
+
+## Problem Frame
+
+Live: `fc_active_pending` with watch_recommended; gate exits 2 without polling; no structured next steps after FC terminal.
+
+---
+
+## Requirements
+
+- R1. `--lfg-gate-watch` enables `--lfg-gate --lfg-preflight-watch`.
+- R2. `_build_defer_post_terminal_commands` with preflight/prefetch-gate hints.
+- R3. Defer briefing attaches `post_terminal_commands`; monitor_commands includes `gate_watch`.
+- R4. `preflight_watch_summary.next_hint` from proceed_hint after watch.
+- R5. `lfg_mode` `gate_watch`; tests; `PLAN_TRACK_CAP` `118`; docs.
+
+---
+
+## Test scenarios
+
+- T1. `--lfg-gate-watch` sets gate + preflight-watch flags.
+- T2. Defer briefing includes post_terminal_commands.prefetch_gate when fc_sha_stale.
+- T3. Watch summary includes next_hint when defer clears.

docs/plans/2026-05-24-119-defer-gate-watch-primary-plan.md

@@ -0,0 +1,36 @@
+---
+title: "fix: defer and drift wait prefer gate-watch command"
+type: fix
+status: active
+date: 2026-05-28
+origin: docs/solutions/testing/verify-pypi-regression-closeout.md
+---
+
+# fix: Prefer Gate-Watch as Primary Wait Command (plan 119)
+
+## Summary
+
+Defer and drift-wait briefings still primary-route to `--lfg-preflight-watch`. Prefer **`--lfg-gate-watch`** so agents poll once and get strict gate exit semantics.
+
+---
+
+## Problem Frame
+
+Live: `fc_active_pending`; `gate_watch` exists in monitor_commands but `command`/`proceed_hint` use preflight-watch.
+
+---
+
+## Requirements
+
+- R1. Defer `command` and `_build_proceed_hint` use `gate_watch` when watch recommended.
+- R2. Drift wait uses `refresh_commands.gate_watch` as primary command.
+- R3. Preflight watch poll stderr includes `sha_gap=` when present.
+- R4. Tests; `PLAN_TRACK_CAP` `119`; closeout + plan 020 docs.
+
+---
+
+## Test scenarios
+
+- T1. fc_active_pending defer → command is gate-watch.
+- T2. investigate_ci_drift + active FC → command is gate-watch.
+- T3. Watch poll line includes sha_gap when checkpoint stale.

docs/plans/2026-05-24-120-fc-active-queue-backlog-plan.md

@@ -0,0 +1,36 @@
+---
+title: "fix: fc-active defer queue backlog context"
+type: fix
+status: active
+date: 2026-05-28
+origin: docs/solutions/testing/verify-pypi-regression-closeout.md
+---
+
+# fix: FC-Active Defer Queue Backlog (plan 120)
+
+## Summary
+
+`fc_active_pending` defer returns before `queue_backlog_note` is set. Surface queue backlog on that path and attach **`queue_context`** + **`primary_action`** to defer briefing.
+
+---
+
+## Problem Frame
+
+Live: FC queued 0.2h (not severe yet); fc_active_pending path skips backlog note logic used by other defer branches.
+
+---
+
+## Requirements
+
+- R1. fc_active_pending checkpoint sets `queue_backlog_note` when FC queued ≥ 4h.
+- R2. `_build_defer_queue_context` exposes backlog flags and max queued hours.
+- R3. Defer briefing includes `queue_context`, `primary_action: gate_watch`, and queue note in notes.
+- R4. stderr `queue_backlog=true` when severe; tests; `PLAN_TRACK_CAP` `120`; docs.
+
+---
+
+## Test scenarios
+
+- T1. FC active stale gap + queued 4.5h → checkpoint has queue_backlog_note.
+- T2. Defer briefing queue_context.queue_backlog true when severe.
+- T3. stderr includes queue_backlog=true.

docs/plans/2026-05-24-121-gate-watch-poll-labels-plan.md

@@ -0,0 +1,54 @@
+---
+title: "fix: gate-watch poll labels and defer queued stderr"
+type: fix
+status: active
+date: 2026-05-28
+origin: docs/solutions/testing/verify-pypi-regression-closeout.md
+---
+
+# fix: Gate-Watch Poll Labels and Defer Queued Stderr (plan 121)
+
+## Summary
+
+When agents run **`--lfg-gate-watch`**, poll stderr still says "preflight watch". Add mode-aware watch labels, surface **`max_queued_hours`** on defer briefing stderr, and include **`next_hint`** in watch summary lines.
+
+---
+
+## Problem Frame
+
+Live defer: FC queued ~0.3h on `573c9d4` vs master `8916e2f`; primary wait is **`--lfg-gate-watch`**. Poll lines and summary stderr use preflight naming, and defer briefing stderr omits queued hours unless backlog is severe (≥4h).
+
+---
+
+## Requirements
+
+- R1. `_format_preflight_watch_poll_line` accepts a watch label; gate mode prints `LFG gate watch poll`.
+- R2. `_watch_lfg_preflight_defer` accepts `watch_label`; summary/next stderr use gate vs preflight naming.
+- R3. `_emit_lfg_agent_briefing_stderr` adds `queued=0.3h` from `queue_context.max_queued_hours` on defer.
+- R4. `_format_preflight_watch_summary_line` appends truncated `next_hint` when present.
+- R5. Tests; `PLAN_TRACK_CAP` `121`; closeout doc bullet for plan 121.
+
+---
+
+## Scope Boundaries
+
+- No change to exit codes, defer logic, or FC terminal classification.
+- No browser/UI work.
+
+---
+
+## Implementation Units
+
+- U1. **Watch label plumbing** — `watch_label` param on poll formatter and watch loop; main passes `gate` when `lfg_gate_watch`.
+- U2. **Defer stderr queued hours** — emit `queued=X.Xh` from queue_context when defer action.
+- U3. **Watch summary next_hint** — summary line suffix; gate vs preflight summary stderr prefix.
+- U4. **Tests and docs** — unit tests; bump `PLAN_TRACK_CAP`; closeout Prefer bullet.
+
+---
+
+## Test scenarios
+
+- T1. Poll line with `watch_label="gate"` contains `gate watch poll`.
+- T2. Defer stderr with `queue_context.max_queued_hours=0.33` contains `queued=0.3h`.
+- T3. Summary formatter with `next_hint` includes truncated hint in line.
+- T4. Plan patch test expects `019–121`.

docs/plans/2026-05-24-122-defer-expected-after-terminal-plan.md

@@ -0,0 +1,45 @@
+---
+title: "fix: defer expected-after-terminal and queue warn"
+type: fix
+status: active
+date: 2026-05-28
+origin: docs/solutions/testing/verify-pypi-regression-closeout.md
+---
+
+# fix: Defer Expected-After-Terminal and Queue Warn (plan 122)
+
+## Summary
+
+During **`fc_active_pending`** defer, agents need explicit post-FC guidance and early queue warnings before the 4h severe threshold. Add **`expected_after_terminal`** to defer briefing, **`queue_backlog_warning`** at ≥2h queued, and defer-reason transition in watch summary stderr.
+
+---
+
+## Problem Frame
+
+Live: FC queued 0.5h on stale SHA; agents must gate-watch then run prefetch+gate after terminal. Briefing has **`post_terminal_commands`** but no single primary **`expected_after_terminal`** field. Queue severity only surfaces at 4h.
+
+---
+
+## Requirements
+
+- R1. Defer briefing includes **`expected_after_terminal`** `{action, command}` preferring `prefetch_gate` → `gate` → `preflight`.
+- R2. **`queue_context.queue_backlog_warning`** when `max_queued_hours` ≥ 2 and < 4.
+- R3. Defer stderr **`queue_warn=true`** when warning active.
+- R4. Watch summary line includes **`reason=start->end`** when defer reasons differ across watch.
+- R5. Tests; `PLAN_TRACK_CAP` `122`; closeout doc bullet.
+
+---
+
+## Scope Boundaries
+
+- No change to defer exit codes or FC classification logic.
+- No doc auto-apply while deferred.
+
+---
+
+## Test scenarios
+
+- T1. Defer briefing with `prefetch_gate` post_terminal → `expected_after_terminal.action=prefetch_gate`.
+- T2. queue_context warning at 2.5h queued, not severe.
+- T3. stderr includes `queue_warn=true` and `expected_after=prefetch_gate`.
+- T4. Summary line with differing start/end defer reasons includes `reason=`.

docs/plans/2026-05-24-123-drift-expected-after-terminal-plan.md

@@ -0,0 +1,32 @@
+---
+title: "fix: drift expected-after-terminal and primary action"
+type: fix
+status: active
+date: 2026-05-28
+origin: docs/solutions/testing/verify-pypi-regression-closeout.md
+---
+
+# fix: Drift Expected-After-Terminal and Primary Action (plan 123)
+
+## Summary
+
+Live gate reports **`investigate_ci_drift`** with active FC/verify runs. Parity with defer briefing: add **`expected_after_terminal`**, **`primary_action: gate_watch`**, and **`queue_context`** on drift-wait paths; surface on stderr.
+
+---
+
+## Requirements
+
+- R1. `_build_drift_expected_after(refresh_commands)` prefers closeout → refresh_dry_run → gate → preflight.
+- R2. Drift briefing with `wait_recommended` sets `primary_action: gate_watch`, `expected_after_terminal`, and `queue_context`.
+- R3. Drift briefing without wait sets `expected_after_terminal` to closeout when available.
+- R4. Stderr for `investigate_ci_drift` includes `primary_action`, `expected_after`, and `queued=` when queue_context present.
+- R5. Fix `expected_after` variable shadowing `action` in stderr emitter; tests; `PLAN_TRACK_CAP` 123; docs.
+
+---
+
+## Test scenarios
+
+- T1. Active FC drift → `wait_recommended`, `primary_action=gate_watch`, `expected_after.action=refresh_dry_run`.
+- T2. Terminal drift → `expected_after.action=closeout`.
+- T3. stderr drift includes `expected_after=refresh_dry_run` and `primary_action=gate_watch`.
+- T4. Plan patch expects `019–123`.