@trac3er/oh-my-god 2.1.8 → 2.2.2

package/build/lib/hooks/pre-compact.py

@@ -32,6 +32,12 @@ except ImportError:
     except Exception:
         collect_protected_context = None
 
+try:
+    from runtime.context_limits import get_model_limits, compaction_trigger
+except Exception:
+    get_model_limits = None
+    compaction_trigger = None
+
 
 MAX_SNAPSHOT_BYTES = int(os.environ.get("OMG_PRECOMPACT_MAX_SNAPSHOT_BYTES", "262144"))
 GIT_DIFF_TIMEOUT_SEC = int(os.environ.get("OMG_PRECOMPACT_GIT_DIFF_TIMEOUT_SEC", "1"))
@@ -225,6 +231,51 @@ def _load_context_budget_config(project_dir):
     return defaults
 
 
+def _detect_model_id(data):
+    for key in ("CLAUDE_MODEL", "OMG_MODEL_ID", "OPENAI_MODEL"):
+        value = os.environ.get(key, "").strip()
+        if value:
+            return value
+
+    if not isinstance(data, dict):
+        return ""
+
+    model = data.get("model")
+    if isinstance(model, dict):
+        for key in ("id", "display_name", "name"):
+            value = str(model.get(key, "") or "").strip()
+            if value:
+                return value
+    elif isinstance(model, str) and model.strip():
+        return model.strip()
+
+    context = data.get("context")
+    if isinstance(context, dict):
+        nested_model = context.get("model")
+        if isinstance(nested_model, dict):
+            for key in ("id", "display_name", "name"):
+                value = str(nested_model.get(key, "") or "").strip()
+                if value:
+                    return value
+
+    return ""
+
+
+def _host_aware_compaction_threshold(data):
+    model_id = _detect_model_id(data)
+    if get_model_limits is not None and compaction_trigger is not None:
+        limits = get_model_limits(model_id)
+        trigger = int(compaction_trigger(model_id))
+    else:
+        limits = {"class_label": "128k-class"}
+        trigger = 80_000
+    return {
+        "model_id": model_id,
+        "class_label": str(limits.get("class_label", "128k-class")),
+        "trigger_tokens": trigger,
+    }
+
+
 # ---------------------------------------------------------------------------
 # Main hook execution (side-effects — only runs when invoked as script)
 # ---------------------------------------------------------------------------
@@ -236,6 +287,7 @@ def main():
         sys.exit(0)
 
     project_dir = _resolve_project_dir()
+    compaction_limits = _host_aware_compaction_threshold(data)
     ts = datetime.now().strftime("%Y%m%d_%H%M%S")
     state_dir = resolve_state_dir(project_dir, "state", "")
     snapshot_dir = os.path.join(state_dir, "snapshots", ts)
@@ -250,25 +302,40 @@ def main():
         resolve_state_file(project_dir, "state/ledger/failure-tracker.json", "ledger/failure-tracker.json"),
         resolve_state_file(project_dir, "state/ralph-loop.json", "ralph-loop.json"),
     ]
-    cached = read_cache(snapshot_files)
     saved = []
     for src in snapshot_files:
-        if cached.get(src) is not None:
+        if os.path.exists(src):
             dst = os.path.join(snapshot_dir, os.path.basename(src))
             if snapshot_file(src, dst, MAX_SNAPSHOT_BYTES):
                 saved.append(os.path.basename(src))
 
-    profile = first_lines(cached.get(resolve_state_file(project_dir, "state/profile.yaml", "profile.yaml")), 20)
-    wm = first_lines(cached.get(resolve_state_file(project_dir, "state/working-memory.md", "working-memory.md")), 15)
-    plan = first_lines(cached.get(resolve_state_file(project_dir, "state/_plan.md", "_plan.md")), 10)
-    checklist = first_lines(cached.get(resolve_state_file(project_dir, "state/_checklist.md", "_checklist.md")), 50)
-    tracker = cached.get(resolve_state_file(project_dir, "state/ledger/failure-tracker.json", "ledger/failure-tracker.json"))
-    ralph_loop = cached.get(resolve_state_file(project_dir, "state/ralph-loop.json", "ralph-loop.json"))
+    summary_files = {
+        "profile": resolve_state_file(project_dir, "state/profile.yaml", "profile.yaml"),
+        "working_memory": resolve_state_file(project_dir, "state/working-memory.md", "working-memory.md"),
+        "plan": resolve_state_file(project_dir, "state/_plan.md", "_plan.md"),
+        "checklist": resolve_state_file(project_dir, "state/_checklist.md", "_checklist.md"),
+        "tracker": resolve_state_file(project_dir, "state/ledger/failure-tracker.json", "ledger/failure-tracker.json"),
+        "ralph_loop": resolve_state_file(project_dir, "state/ralph-loop.json", "ralph-loop.json"),
+    }
+    cached = read_cache(list(summary_files.values()))
+
+    profile = first_lines(cached.get(summary_files["profile"]), 20)
+    wm = first_lines(cached.get(summary_files["working_memory"]), 15)
+    plan = first_lines(cached.get(summary_files["plan"]), 10)
+    checklist = first_lines(cached.get(summary_files["checklist"]), 50)
+    tracker = cached.get(summary_files["tracker"])
+    ralph_loop = cached.get(summary_files["ralph_loop"])
 
     parts = [
         f"# Handoff -- {datetime.now().strftime('%Y-%m-%d %H:%M')}",
         "Auto-generated before context compaction.",
     ]
+    model_label = compaction_limits["model_id"] or "unknown"
+    parts.append(
+        "## Compaction Budget\n"
+        f"Model: {model_label} ({compaction_limits['class_label']})\n"
+        f"Trigger: {compaction_limits['trigger_tokens']} tokens"
+    )
     if profile:
         parts.append("<!-- section: working-state -->")
         parts.append("## Project\n" + profile)
@@ -369,23 +436,28 @@ def main():
             if turns:
                 config = _load_context_budget_config(project_dir)
                 result = _apply_hybrid_summarization(turns, config)
+                summaries = result.get("summaries", [])
+                discarded_raw = result.get("discarded_count", 0)
+                discarded_count = discarded_raw if isinstance(discarded_raw, int) else 0
+                full_turns = result.get("full_turns", [])
                 # Format as additionalContext supplement
                 summary_parts = []
-                if result["summaries"]:
+                if isinstance(summaries, list) and summaries:
                     summary_parts.append("## Conversation Context (Hybrid Summary)")
-                    for s in result["summaries"]:
-                        summary_parts.append(s)
-                    if result["discarded_count"] > 0:
+                    for s in summaries:
+                        if isinstance(s, str):
+                            summary_parts.append(s)
+                    if discarded_count > 0:
                         summary_parts.append(
-                            f"({result['discarded_count']} oldest turns discarded — see memory/handoff)"
+                            f"({discarded_count} oldest turns discarded — see memory/handoff)"
                         )
-                    summary_text = "\n".join(summary_parts)
+                    _summary_text = "\n".join(summary_parts)
                     # Output as JSON if no protected context was already output
                     print(
                         f"[OMG pre-compact] Hybrid summarization: "
-                        f"{len(result['full_turns'])} full, "
-                        f"{len(result['summaries'])} batches, "
-                        f"{result['discarded_count']} discarded",
+                        f"{len(full_turns) if isinstance(full_turns, list) else 0} full, "
+                        f"{len(summaries)} batches, "
+                        f"{discarded_count} discarded",
                         file=sys.stderr,
                     )
     except Exception:

package/build/lib/hooks/prompt-enhancer.py

@@ -18,10 +18,19 @@ import hashlib
 import json, sys, os, re, time
 from datetime import datetime, timezone
 import importlib
+from pathlib import Path
 
-HOOKS_DIR = os.path.dirname(__file__)
-if HOOKS_DIR not in sys.path:
-    sys.path.insert(0, HOOKS_DIR)
+HOOKS_DIR = str(Path(__file__).resolve().parent)
+_PROJECT_ROOT = str(Path(HOOKS_DIR).parent)
+_PORTABLE_RUNTIME_ROOT = str(Path(_PROJECT_ROOT) / "omg-runtime")
+for path in (HOOKS_DIR, _PROJECT_ROOT, _PORTABLE_RUNTIME_ROOT):
+    if path not in sys.path:
+        sys.path.insert(0, path)
+
+try:
+    from runtime.complexity_scorer import score_complexity
+except ImportError:
+    score_complexity = None
 
 try:
     from hooks._common import setup_crash_handler, json_input, atomic_json_write, get_feature_flag, _resolve_project_dir
@@ -249,6 +258,14 @@ def _build_intent_gate_state(prompt_text, payload):
     run_id = _resolve_run_id(payload, source_prompt_hash)
     signal_hits = _count_signals(INTENT_MAP[intent_class]["signals"], prompt_text)
     confidence = min(0.99, 0.76 + (signal_hits * 0.07) + (0.06 if intent_class == "ambiguous_config" else 0.0))
+    governance_payload = {}
+    if score_complexity is not None:
+        try:
+            governance_raw = score_complexity(prompt_text).get("governance")
+            if isinstance(governance_raw, dict):
+                governance_payload = governance_raw
+        except Exception:
+            governance_payload = {}
 
     return {
         "schema": "IntentGateClarificationState",
@@ -260,6 +277,7 @@ def _build_intent_gate_state(prompt_text, payload):
         "missing_slots": missing_slots,
         "clarification_prompt": clarification_prompt,
         "source_prompt_hash": source_prompt_hash,
+        "governance": governance_payload,
         "updated_at": datetime.now(timezone.utc).isoformat(),
     }
 
@@ -300,6 +318,30 @@ if detected_intent in ("fix", "implement", "refactor"):
     parts.append(
         "@verify: After EVERY change run build/lint/test. Show exit code."
     )
+    methodology_run_id = _resolve_run_id(data, _hash_prompt(prompt))
+    parts.append(
+        "@methodology: "
+        f"run_id={methodology_run_id} require plan+lock+done_when before mutation; "
+        "verify done_when after run."
+    )
+
+_gov_payload: dict[str, object] | None = None
+if score_complexity is not None and detected_intent in (
+    "fix", "implement", "refactor", "plan", "review",
+):
+    try:
+        _gov_raw = score_complexity(prompt).get("governance")
+        if isinstance(_gov_raw, dict):
+            _gov_payload = _gov_raw
+    except Exception:
+        pass
+if _gov_payload and budget_ok():
+    parts.append(
+        f"@governance: read_first={_gov_payload.get('read_first', False)} "
+        f"simplify_only={_gov_payload.get('simplify_only', False)} "
+        f"optimize_only={_gov_payload.get('optimize_only', False)} "
+        f"complexity={_gov_payload.get('complexity', 'low')}"
+    )
 
 if parts and budget_ok():
     add("\n".join(parts))
@@ -403,10 +445,21 @@ if not is_crazy and not is_ulw and budget_ok():
     elif word_count > 40:
         complexity_score += 1
 
+    complexity_category = "low"
+    if score_complexity is not None:
+        try:
+            scored = score_complexity(prompt)
+            scored_category = str(scored.get("category", "low")).strip().lower()
+            if scored_category in {"trivial", "low", "medium", "high"}:
+                complexity_category = scored_category
+        except Exception:
+            pass
+
     # HIGH complexity (≥4): auto-trigger CRAZY
     if complexity_score >= 4:
         add(
             "@mode:CRAZY(auto) — Complex task detected (multi-step/multi-component). "
+            f"Complexity label={complexity_category}. "
             "All agents active: Claude=orchestrator, Codex=deep-code, Gemini=UI/UX. "
             "Work through all items systematically. Verify each step."
         )
@@ -414,6 +467,7 @@ if not is_crazy and not is_ulw and budget_ok():
     elif complexity_score >= 2:
         add(
             "@mode:PERSISTENT(auto) — Multi-step task detected. "
+            f"Complexity label={complexity_category}. "
             "Work through ALL items. Skip if blocked, continue others. "
             "Don't stop until checklist complete."
         )

package/build/lib/hooks/secret-guard.py

@@ -6,14 +6,18 @@ Delegates file policy decisions to policy_engine.py.
 import json
 import os
 import sys
+from pathlib import Path
 
-HOOKS_DIR = os.path.dirname(__file__)
-PROJECT_ROOT = os.path.dirname(HOOKS_DIR)
-for path in (HOOKS_DIR, PROJECT_ROOT):
+HOOKS_DIR = str(Path(__file__).resolve().parent)
+PROJECT_ROOT = str(Path(HOOKS_DIR).parent)
+PORTABLE_RUNTIME_ROOT = str(Path(PROJECT_ROOT) / "omg-runtime")
+for path in (HOOKS_DIR, PROJECT_ROOT, PORTABLE_RUNTIME_ROOT):
     if path not in sys.path:
         sys.path.insert(0, path)
 
-from _common import setup_crash_handler, json_input, deny_decision, is_bypass_mode, get_project_dir
+from _common import bootstrap_runtime_paths, setup_crash_handler, json_input, deny_decision, is_bypass_mode, get_project_dir
+
+bootstrap_runtime_paths(__file__)
 
 # Fail-closed: deny on crash (security hook)
 setup_crash_handler("secret-guard", fail_closed=True)

package/build/lib/hooks/session-start.py

@@ -9,17 +9,21 @@ import os
 import sys
 import time as _time
 import re as _re
+from pathlib import Path
 
-HOOKS_DIR = os.path.dirname(__file__)
-PROJECT_ROOT = os.path.dirname(HOOKS_DIR)
-if PROJECT_ROOT not in sys.path:
-    sys.path.insert(0, PROJECT_ROOT)
-if HOOKS_DIR not in sys.path:
-    sys.path.insert(0, HOOKS_DIR)
+HOOKS_DIR = str(Path(__file__).resolve().parent)
+PROJECT_ROOT = str(Path(HOOKS_DIR).parent)
+PORTABLE_RUNTIME_ROOT = str(Path(PROJECT_ROOT) / "omg-runtime")
+for path in (HOOKS_DIR, PROJECT_ROOT, PORTABLE_RUNTIME_ROOT):
+    if path not in sys.path:
+        sys.path.insert(0, path)
 
-from hooks._common import setup_crash_handler, json_input, get_feature_flag, _resolve_project_dir
+from hooks._common import bootstrap_runtime_paths, setup_crash_handler, json_input, get_feature_flag, _resolve_project_dir
 from hooks.state_migration import resolve_state_file, resolve_state_dir
 from hooks._budget import BUDGET_SESSION_TOTAL, BUDGET_SESSION_IDLE
+
+bootstrap_runtime_paths(__file__)
+
 from runtime.context_engine import render_profile_digest_text
 
 setup_crash_handler("session-start", fail_closed=False)

package/build/lib/hooks/setup_wizard.py

@@ -14,12 +14,17 @@ from typing import Any, cast
 
 import yaml
 
-from hooks._common import get_feature_flag
+_HOOKS_DIR = Path(__file__).resolve().parent
+_PROJECT_ROOT = _HOOKS_DIR.parent
+_PORTABLE_RUNTIME_ROOT = _PROJECT_ROOT / "omg-runtime"
+for path in (_HOOKS_DIR, _PROJECT_ROOT, _PORTABLE_RUNTIME_ROOT):
+    path_str = str(path)
+    if path_str not in sys.path:
+        sys.path.insert(0, path_str)
 
-# Ensure project root is on sys.path for runtime imports
-_PROJECT_ROOT = os.path.normpath(os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
-if _PROJECT_ROOT not in sys.path:
-    sys.path.insert(0, _PROJECT_ROOT)
+from hooks._common import bootstrap_runtime_paths, get_feature_flag
+
+bootstrap_runtime_paths(__file__)
 
 from runtime.cli_provider import get_provider, list_available_providers  # noqa: E402
 from runtime.mcp_config_writers import (  # noqa: E402
@@ -47,6 +52,7 @@ from runtime.adoption import (  # noqa: E402
     build_adoption_report,
     get_mode_profile,
     get_preset_features,
+    detect_ecosystems,
     resolve_preset,
     write_adoption_report,
 )
@@ -249,12 +255,15 @@ def get_default_mcps_for_preset(preset: str) -> list[str]:
         the requested *preset* level.
     """
     level = _PRESET_LEVEL.get(preset, 0)
-    return [
+    default_ids = [
         m["id"]
         for m in MCP_CATALOG
         if _PRESET_LEVEL.get(m.get("min_preset", ""), -1) <= level
         and m.get("min_preset") is not None
     ]
+    if preset == "buffet" and os.environ.get("OMG_SETUP_ENABLED", "0").strip() != "1":
+        default_ids.append("notebooklm")
+    return default_ids
 
 
 def _normalize_mcp_ids(selected_ids: list[str]) -> list[str]:
@@ -1028,9 +1037,15 @@ def run_setup_wizard(
 
     selected_preset = resolve_preset(preset or ("balanced" if non_interactive else "safe"))
     selected_setup_mode = select_setup_mode(setup_mode)
+    requested_mode = mode
+    if requested_mode is None and non_interactive:
+        detected = detect_ecosystems(project_dir)
+        if not detected:
+            requested_mode = "omg-only"
+
     adoption = build_adoption_report(
         project_dir,
-        requested_mode=mode,
+        requested_mode=requested_mode,
         preset=selected_preset,
         adopt=adopt,
     )
@@ -1110,7 +1125,8 @@ def run_setup_wizard(
         "blockers": [{"name": c["name"], "message": c["message"]} for c in blockers],
     }
 
-    if blockers:
+    has_detected_cli = any(bool(v.get("detected", False)) for v in clis.values() if isinstance(v, dict))
+    if blockers and not non_interactive and not has_detected_cli:
         result["status"] = "validation_failed"
 
     return result

package/build/lib/hooks/stop_dispatcher.py

@@ -9,14 +9,20 @@ import subprocess
 import sys
 import time
 from datetime import datetime, timedelta, timezone
+from pathlib import Path
 import warnings
 
-sys.path.insert(0, os.path.dirname(__file__))
-sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+HOOKS_DIR = str(Path(__file__).resolve().parent)
+PROJECT_ROOT = str(Path(HOOKS_DIR).parent)
+PORTABLE_RUNTIME_ROOT = str(Path(PROJECT_ROOT) / "omg-runtime")
+for path in (HOOKS_DIR, PROJECT_ROOT, PORTABLE_RUNTIME_ROOT):
+    if path not in sys.path:
+        sys.path.insert(0, path)
 
 from hooks._common import (  # noqa: E402
     atomic_json_write,
     block_decision,
+    bootstrap_runtime_paths,
     check_performance_budget,
     get_feature_flag,
     get_project_dir,
@@ -28,9 +34,12 @@ from hooks._common import (  # noqa: E402
     setup_crash_handler,
     should_skip_stop_hooks,
     STOP_CHECK_MAX_MS,
+    STOP_DISPATCHER_TOTAL_MAX_MS,
 )
 from hooks.state_migration import resolve_state_file  # noqa: E402
 
+bootstrap_runtime_paths(__file__)
+
 from runtime.release_run_coordinator import resolve_current_run_id  # noqa: E402
 from runtime import test_intent_lock  # noqa: E402
 
@@ -136,6 +145,14 @@ def _is_internal_control_path(file_path: str) -> bool:
     return any(p.lower() in fl for p in INTERNAL_CONTROL_PATH_PATTERNS)
 
 
+_RALPH_DEFAULT_TIMEOUT_MINUTES = 10
+
+
+def _watchdog_check(start_time):
+    """Return True if the dispatcher has exceeded its wall-clock budget."""
+    return (time.time() - start_time) >= (STOP_DISPATCHER_TOTAL_MAX_MS / 1000)
+
+
 try:
     from hooks.shadow_manager import has_recent_evidence  # type: ignore
 except Exception:  # intentional: optional feature — shadow_manager may not exist
@@ -628,7 +645,7 @@ def check_bare_done(data, project_dir):
 
 
 def _proof_chain_strict_enabled() -> bool:
-    return os.environ.get("OMG_PROOF_CHAIN_STRICT", "0").strip() == "1"
+    return os.environ.get("OMG_PROOF_CHAIN_STRICT", "1").strip() != "0"
 
 
 def _load_test_delta_from_evidence(project_dir: str, run_id: str | None) -> dict[str, object]:
@@ -720,7 +737,7 @@ def check_tdd_proof_chain(data, project_dir):
     advisories = data.setdefault("_stop_advisories", [])
     advisories.append(
         "[OMG advisory] tdd proof chain incomplete: active lock evidence or waiver artifact is missing. "
-        "Set OMG_PROOF_CHAIN_STRICT=1 to hard-block completion."
+        "Production default is fail-closed; OMG_PROOF_CHAIN_STRICT=0 downgrades to advisory."
     )
     return []
 
@@ -828,24 +845,63 @@ def format_ralph_block_reason(state, project_dir):
         f"If truly done, run: /OMG:ralph-stop"
     )
 
+def persist_ralph_question(project_dir, question_text):
+    """Persist a pending clarification question in the Ralph loop state.
+
+    Called when any hook or the context engine detects ambiguity during a
+    Ralph iteration.  The next stop-hook check will emit the question via
+    block_decision and end the turn — no tool action may proceed.
+    """
+    ralph_path = os.path.join(project_dir, ".omg", "state", "ralph-loop.json")
+    if not os.path.exists(ralph_path):
+        return
+    try:
+        with open(ralph_path, "r", encoding="utf-8") as f:
+            state = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return
+    state["question_pending"] = True
+    state["question_text"] = str(question_text).strip()[:500]
+    state["question_emitted_at"] = datetime.now(timezone.utc).isoformat()
+    atomic_json_write(ralph_path, state)
+
+
 def check_ralph_loop(project_dir, data):
+    """Check Ralph loop state and return (block_reasons, advisories, is_question).
+
+    When *is_question* is True the block is a clarification question and the
+    caller MUST use block_reason="clarification_required" so that the turn
+    ends without any further tool action.
+    """
     del data
 
     if not get_feature_flag("ralph_loop"):
-        return [], []
+        return [], [], False
     ralph_path = os.path.join(project_dir, ".omg", "state", "ralph-loop.json")
     if not os.path.exists(ralph_path):
-        return [], []
+        return [], [], False
     try:
         with open(ralph_path, "r", encoding="utf-8") as f:
             state = json.load(f)
     except (json.JSONDecodeError, OSError):
-        return [], []
+        return [], [], False
     if not state.get("active"):
-        return [], []
-    
+        return [], [], False
+
+    # --- Pending clarification question: block and end turn immediately ---
+    if state.get("question_pending"):
+        question_text = str(state.get("question_text", "")).strip()
+        if not question_text:
+            question_text = "Clarification required before continuing Ralph loop"
+        # Do NOT increment iteration — the loop is paused on the question
+        return [question_text], [], True
+
     # Check if Ralph loop has expired
-    timeout_minutes = int(os.environ.get("OMG_RALPH_TIMEOUT_MINUTES", "30"))
+    _raw_timeout = os.environ.get("OMG_RALPH_TIMEOUT_MINUTES", "")
+    try:
+        timeout_minutes = int(_raw_timeout) if _raw_timeout.strip() else _RALPH_DEFAULT_TIMEOUT_MINUTES
+    except (ValueError, TypeError):
+        timeout_minutes = _RALPH_DEFAULT_TIMEOUT_MINUTES
     started_at_str = state.get("started_at")
     if started_at_str:
         try:
@@ -855,7 +911,7 @@ def check_ralph_loop(project_dir, data):
             if elapsed.total_seconds() > timeout_minutes * 60:
                 state["active"] = False
                 atomic_json_write(ralph_path, state)
-                return [], [f"Ralph loop expired after {timeout_minutes} minutes. Stopping."]
+                return [], [f"Ralph loop expired after {timeout_minutes} minutes. Stopping."], False
         except (ValueError, TypeError):
             pass
     
@@ -864,11 +920,11 @@ def check_ralph_loop(project_dir, data):
     if iteration >= max_iter:
         state["active"] = False
         atomic_json_write(ralph_path, state)
-        return [], ["Ralph loop reached max iterations. Stopping."]
+        return [], ["Ralph loop reached max iterations. Stopping."], False
     state["iteration"] = iteration + 1
     atomic_json_write(ralph_path, state)
     reason = format_ralph_block_reason(state, project_dir)
-    return [reason], []
+    return [reason], [], False
 
 
 def check_planning_gate(project_dir):
@@ -972,41 +1028,63 @@ def check_todo_continuation(data: dict[str, object]) -> dict[str, str] | None:
 
 
 def main():
+    _watchdog_start = time.time()
+
     data = json_input()
 
     # Unified guard: stop-hook loop, context-limit, and re-entry detection
     if should_skip_stop_hooks(data):
         sys.exit(0)
 
+    # Watchdog: bail out if we already burned too much wall-clock time
+    if _watchdog_check(_watchdog_start):
+        print("[OMG] stop_dispatcher: wall-clock watchdog expired", file=sys.stderr)
+        sys.exit(0)
+
     project_dir = _resolve_project_dir()
     data["_stop_ctx"] = _build_context(project_dir)
     data["_stop_advisories"] = []
 
     # P1: Ralph loop check (implemented in Task 18)
-    block_reasons, advisories = check_ralph_loop(project_dir, data)
+    block_reasons, advisories, is_question = check_ralph_loop(project_dir, data)
     if advisories:
         data["_stop_advisories"].extend(advisories)
     if block_reasons:
-        record_stop_block(project_dir, reason="ralph_loop")
-        block_decision(block_reasons[0])
+        # Clarification questions use a distinct block_reason so the turn
+        # ends cleanly — no tool action may follow a question emission.
+        br = "clarification_required" if is_question else "ralph_loop"
+        block_decision(block_reasons[0], block_reason=br, project_dir=project_dir)
+        return
+
+    if _watchdog_check(_watchdog_start):
+        print("[OMG] stop_dispatcher: wall-clock watchdog expired", file=sys.stderr)
+        sys.exit(0)
 
     # P2: Planning enforcement (implemented in Task 22)
     block_reasons, advisories = check_planning_gate(project_dir)
     if block_reasons:
-        record_stop_block(project_dir, reason="planning_gate")
-        block_decision(block_reasons[0])
+        block_decision(block_reasons[0], block_reason="planning_gate", project_dir=project_dir)
+        return
     advisories.extend(check_scope_drift(project_dir))
     if advisories:
         data["_stop_advisories"].extend(advisories)
 
+    if _watchdog_check(_watchdog_start):
+        print("[OMG] stop_dispatcher: wall-clock watchdog expired", file=sys.stderr)
+        sys.exit(0)
+
     # P3: Todo continuation enforcement (Task 1.6)
     _p3_start = time.monotonic()
     todo_result = check_todo_continuation(data)
     _p3_elapsed = (time.monotonic() - _p3_start) * 1000
     check_performance_budget("check_todo_continuation", _p3_elapsed, STOP_CHECK_MAX_MS)
     if todo_result and todo_result.get("decision") == "block":
-        record_stop_block(project_dir, reason="todo_continuation")
-        block_decision(todo_result["reason"])
+        block_decision(todo_result["reason"], block_reason="todo_continuation", project_dir=project_dir)
+        return
+
+    if _watchdog_check(_watchdog_start):
+        print("[OMG] stop_dispatcher: wall-clock watchdog expired", file=sys.stderr)
+        sys.exit(0)
 
     blocks = []
     for check_fn in [
@@ -1022,6 +1100,9 @@ def main():
         _test_validator_check,
         _quality_runner_check,
     ]:
+        if _watchdog_check(_watchdog_start):
+            print("[OMG] stop_dispatcher: wall-clock watchdog expired during quality checks", file=sys.stderr)
+            sys.exit(0)
         if check_fn is None:
             continue
         try:
@@ -1037,8 +1118,8 @@ def main():
         print("\n".join(advisories), file=sys.stderr)
 
     if blocks:
-        record_stop_block(project_dir, reason="quality_check")
-        block_decision("\n\n---\n\n".join(blocks))
+        block_decision("\n\n---\n\n".join(blocks), block_reason="quality_check", project_dir=project_dir)
+        return
 
     check_simplifier(data, project_dir)
     reset_stop_block_tracker(project_dir)