Adversarial review flagged: removing the opt-in label transitions a
live workflow to ABANDONED — but ABANDONED is TERMINAL with only
``operator_unstick`` re-entry → DISCOVERED, losing all prior
controller_events continuity. Operators removing the label to "pause"
a long-running PR will be surprised it restarted from scratch.
Fix: introduce a non-terminal ``PAUSED`` state.
State machine changes (``tools/controller/state_machine.py``):
- ``PAUSED`` added to KNOWN_STATES (non-terminal — has exits via
``opt_in_label_restored`` and ``operator_unstick``).
- ``opt_in_label_removed`` / ``opt_in_label_restored`` events
documented in EVENTS but NOT listed per-state in TRANSITIONS —
they're out-of-band master-driven events written directly by
reconciliation. Listing them per-state breaks the
per-state-event-set invariants (ESCALATING / CONFLICT_RESOLVING).
- ``(PAUSED, operator_unstick) → DISCOVERED`` for the escape hatch.
Schema change (``tools/controller/db/models.py``):
- ``workflows.pre_pause_state: Mapped[str | None]`` column captures
the resume target. Master writes it on pause; clears it on resume.
Reconciliation logic (``tools/controller/master/reconciliation.py``):
- New ``_apply_transition_with_pre_pause`` helper writes both
``current_state`` and ``pre_pause_state`` atomically + emits the
``reconciliation`` event row.
- On label removal (current != PAUSED): captures pre_pause_state,
transitions to PAUSED.
- On label restoration (current == PAUSED): reads pre_pause_state
(fallback DISCOVERED for legacy NULL data), transitions back,
clears pre_pause_state.
- PAUSED workflows are now SCANNED by reconciliation (not just
non-terminals) so we can detect label-restored.
Behaviour matrix:
| current | label | result |
|---------|----------|------------------------------------------|
| any != | absent | → PAUSED, pre_pause_state = current |
| PAUSED | present | → pre_pause_state (or DISCOVERED) |
| PAUSED | absent | stays PAUSED (no transition) |
| any != | present | regular state checks (no-op for label) |
Tests (test_label_gate.py refactor + 3 new tests):
- test_label_removed_pauses_workflow (was: abandons)
- test_label_restored_resumes_from_pre_pause_state (new)
- test_paused_workflow_without_label_stays_paused (new)
- test_resume_fallback_when_pre_pause_state_missing (new — legacy
data without the new column)
- Existing event-reason test still passes (reason string unchanged).
Total: 590 controller tests pass, 0 regressions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
drew
feeec3e9c7