fix(deploy): terminal-window-aware guard so done tasks hold Done in Plane (ORCH-094)

A DB stage=done task with 0 active jobs flapped in Plane between `Awaiting
Deploy` and `Monitoring after Deploy` instead of holding `Done` (verified live
on ORCH-061, task 47): the three deploy-phase setters were terminal-blind, so
any stale/duplicate/unknown caller under the bot token re-stamped an
intermediate status over the terminal Done, forever.

- New leaf src/deploy_status_guard.py (pure, never-raise, config-gated): decide()
  -> ALLOW | CONVERGE_DONE | SUPPRESS on the entry of set_issue_awaiting_deploy /
  set_issue_deploying / set_issue_monitoring. A deploy-phase status is legitimate
  iff the task is non-terminal OR (done AND post-deploy window active); otherwise
  done converges to Done idempotently, cancelled is suppressed (FR-2, D1/D2).
- D3: move post_deploy.arm_monitor ABOVE the terminal-sync block in advance_stage
  so window_active is True when the legitimate first Monitoring is set (the task
  is already DB-done by then); a re-drive after the window closes converges to Done.
- D4: run_post_deploy_monitor no-ops without a status PATCH / re-queue when the
  task became cancelled mid-window (zombie-tick guard, FR-3).
- D5: additive `reason` kwarg on the three setters + one structured log line per
  verdict (work_item/caller/target/db_stage/window_active/verdict); new read-only
  db.get_task_by_work_item_id; post_deploy.window_active helper.
- Flags deploy_status_guard_enabled (kill-switch -> 1:1) / deploy_status_guard_repos
  (CSV; empty = self-hosting only). STAGE_TRANSITIONS / QG_CHECKS / check_* /
  machine-verdict keys / DB schema untouched (reads existing tasks.stage).

Tests: TC-01..TC-12 across 5 new test modules + config flags; updated the
reason-kwarg assertions in test_deploy_terminal_sync / test_deploy_approve.
Full regress green (1413). Docs: CHANGELOG, CLAUDE.md, docs/architecture/README.md
(status -> реализовано), .env.example.

Refs: ORCH-094

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/test_self_deploy_cycle_regression.py

@@ -0,0 +1,128 @@
+"""ORCH-094 — the real deploy cycle is NOT suppressed by the guard (TC-11 / AC-4).
+
+A genuinely-deploying (non-terminal) self-hosting task must still walk
+`Awaiting Deploy -> Deploying -> Monitoring after Deploy -> Done` exactly as before
+ORCH-094. The critical regression case is the LEGITIMATE first `Monitoring`: by the
+time the terminal-sync runs the task is ALREADY DB-`done` (update_task_stage ran
+above), so the guard would wrongly converge it to Done UNLESS the arm-block moved
+ABOVE the terminal-sync (ADR-001 D3) marks the post-deploy window active first.
+This test exercises that ordering end-to-end via run_deploy_finalizer with the REAL
+guard + REAL arm_monitor wired in (only the network PATCH primitive is mocked).
+"""
+import os
+import tempfile
+
+import pytest
+
+_test_db = os.path.join(tempfile.gettempdir(), "test_self_deploy_cycle_regression.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+os.environ["ORCH_REPOS_DIR"] = tempfile.gettempdir()
+os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
+os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
+
+from unittest.mock import MagicMock  # noqa: E402
+
+import src.db as _db  # noqa: E402
+from src.db import init_db, get_db  # noqa: E402
+from src import stage_engine  # noqa: E402
+from src import plane_sync  # noqa: E402
+from src import post_deploy  # noqa: E402
+from src import self_deploy  # noqa: E402
+from src import config as cfg  # noqa: E402
+
+
+@pytest.fixture(autouse=True)
+def fresh_db(monkeypatch, tmp_path):
+    monkeypatch.setattr(_db.settings, "db_path", _test_db)
+    if os.path.exists(_test_db):
+        os.unlink(_test_db)
+    init_db()
+    monkeypatch.setattr(self_deploy.settings, "repos_dir", str(tmp_path))
+    monkeypatch.setattr(self_deploy.settings, "host_repos_dir", str(tmp_path))
+    monkeypatch.setattr(post_deploy.settings, "repos_dir", str(tmp_path))
+    monkeypatch.setattr(post_deploy.settings, "host_repos_dir", str(tmp_path))
+    # Guard ON, self-hosting only.
+    monkeypatch.setattr(cfg.settings, "deploy_status_guard_enabled", True, raising=False)
+    monkeypatch.setattr(cfg.settings, "deploy_status_guard_repos", "", raising=False)
+    # Post-deploy monitor applies for self repo (arm fires on deploy->done).
+    monkeypatch.setattr(post_deploy.settings, "post_deploy_monitor_enabled", True)
+    monkeypatch.setattr(post_deploy.settings, "post_deploy_repos", "")
+    monkeypatch.setattr(stage_engine.post_deploy.settings, "post_deploy_monitor_enabled", True)
+    monkeypatch.setattr(stage_engine.post_deploy.settings, "post_deploy_repos", "")
+    # Stub the worktree/git artefact writers.
+    monkeypatch.setattr(stage_engine.self_deploy, "write_deploy_log", MagicMock(return_value=True))
+    monkeypatch.setattr(stage_engine.merge_gate, "release_merge_lease", MagicMock())
+    yield
+
+
+@pytest.fixture
+def spy_plane(monkeypatch):
+    """Spy plane_sync's low-level PATCH + Done convergence (the REAL guard runs)."""
+    direct = MagicMock()
+    done = MagicMock()
+    monkeypatch.setattr(plane_sync, "_set_issue_state_direct", direct)
+    monkeypatch.setattr(plane_sync, "set_issue_done", done)
+    monkeypatch.setattr(plane_sync, "_resolve_project_id", lambda w=None, p=None: "proj-1")
+    monkeypatch.setattr(
+        plane_sync, "get_project_states",
+        lambda pid: {"awaiting_deploy": "S-aw", "deploying": "S-dep", "monitoring": "S-mon",
+                     "done": "S-done"},
+    )
+    # stage_engine.set_issue_done is a module-level binding -> patch it too so a
+    # non-self / fallback Done path is observable; here we expect Monitoring though.
+    monkeypatch.setattr(stage_engine, "set_issue_done", done)
+    return direct, done
+
+
+def _make_task(stage, repo="orchestrator", wi="ORCH-063", branch="feature/ORCH-063-x"):
+    conn = get_db()
+    cur = conn.execute(
+        "INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage) "
+        "VALUES (?, ?, ?, ?, ?)",
+        (f"plane-{wi}", wi, repo, branch, stage),
+    )
+    tid = cur.lastrowid
+    conn.commit()
+    conn.close()
+    return tid
+
+
+def _pass(*a, **k):
+    return (True, "ok")
+
+
+def test_tc11_non_terminal_awaiting_deploying_pass(spy_plane):
+    direct, done = spy_plane
+    _make_task("deploy")
+    # Phase A / Phase B statuses on a NON-terminal task proceed (no convergence).
+    plane_sync.set_issue_awaiting_deploy("ORCH-063", reason="phase_a")
+    plane_sync.set_issue_deploying("ORCH-063", reason="phase_b")
+    assert direct.call_count == 2
+    done.assert_not_called()
+
+
+def test_tc11_legit_monitoring_preserved_on_deploy_done(spy_plane, monkeypatch):
+    direct, done = spy_plane
+    # Hook reported exit 0.
+    self_deploy.write_marker("orchestrator", "ORCH-063", self_deploy.RESULT, "0")
+    monkeypatch.setattr(
+        stage_engine, "QG_CHECKS",
+        {**stage_engine.QG_CHECKS, "check_deploy_status": _pass},
+    )
+
+    tid = _make_task("deploy")
+    stage_engine.run_deploy_finalizer(
+        {"task_id": tid, "repo": "orchestrator", "id": 1, "agent": "deploy-finalizer"}
+    )
+
+    # Stage advanced to done.
+    conn = get_db()
+    stage = conn.execute("SELECT stage FROM tasks WHERE id=?", (tid,)).fetchone()[0]
+    conn.close()
+    assert stage == "done"
+    # The arm-block ran BEFORE terminal-sync -> the window is active -> the guard
+    # ALLOWS the legitimate Monitoring PATCH (S-mon), it is NOT converged to Done.
+    assert post_deploy.has_marker("orchestrator", "ORCH-063", post_deploy.ARMED)
+    mon_calls = [c for c in direct.call_args_list if c.args[1] == "S-mon"]
+    assert len(mon_calls) == 1, f"expected one Monitoring PATCH, got {direct.call_args_list}"
+    done.assert_not_called()