@trac3er/oh-my-god 2.1.8 → 2.2.2

package/runtime/subagent_dispatcher.py

@@ -105,6 +105,35 @@ def resolve_execution_boundary(*, isolation: str = "worktree") -> dict[str, Any]
     }
 
 
+def resolve_isolation_contract(*, isolation: str) -> dict[str, Any]:
+    normalized = isolation.strip().lower() if isolation else "none"
+    if normalized == "worktree":
+        return {
+            "requested": "worktree",
+            "effective": "worktree",
+            "status": "supported",
+            "read_only": False,
+            "boundary": resolve_execution_boundary(isolation="worktree"),
+        }
+    if normalized == "container":
+        return {
+            "requested": "container",
+            "effective": "none",
+            "status": "deferred",
+            "reason": "container isolation is deferred/unsupported",
+            "read_only": True,
+            "boundary": resolve_execution_boundary(isolation="container"),
+        }
+    return {
+        "requested": "none",
+        "effective": "none",
+        "status": "read-only",
+        "reason": "none isolation permits read-only execution",
+        "read_only": True,
+        "boundary": resolve_execution_boundary(isolation="none"),
+    }
+
+
 def _job_path(job_id: str) -> str:
     """Return the file path for a specific job."""
     return os.path.join(_jobs_dir(), f"{job_id}.json")
@@ -146,6 +175,9 @@ def submit_job(
     agent_name: str,
     task_text: str,
     isolation: str = "none",
+    run_id: str | None = None,
+    evidence_hooks: list[str] | None = None,
+    attach_log: str | None = None,
 ) -> str:
     """Submit a subagent job for concurrent execution.
 
@@ -169,14 +201,19 @@ def submit_job(
 
         job_id = uuid.uuid4().hex[:8]
         now = datetime.now(timezone.utc).isoformat()
+        isolation_contract = resolve_isolation_contract(isolation=isolation)
         record: dict[str, Any] = {
             "job_id": job_id,
+            "run_id": run_id,
             "agent_name": agent_name,
             "task_text": task_text,
             "isolation": isolation,
+            "isolation_contract": isolation_contract,
             "status": "queued",
             "created_at": now,
             "artifacts": [],
+            "evidence_hooks": list(evidence_hooks or []),
+            "attach_log": attach_log,
             "error": None,
         }
         _jobs[job_id] = record
@@ -342,6 +379,23 @@ def _cleanup_worktree(worktree_dir: str) -> None:
         pass
 
 
+def _enforce_merge_writer_gate(run_id: str, record: dict[str, Any], project_dir: str) -> None:
+    try:
+        from runtime.merge_writer import get_merge_writer, MergeWriterAuthorizationError
+    except ImportError:
+        return
+    try:
+        get_merge_writer(project_dir).require_authorization(
+            run_id,
+            mutation_type="worker_dispatch",
+            isolation=str(record.get("isolation", "none")),
+        )
+    except MergeWriterAuthorizationError:
+        raise
+    except Exception:
+        pass
+
+
 def _run_job(job_id: str) -> None:
     """Execute a subagent job in the thread pool.
 
@@ -355,12 +409,25 @@ def _run_job(job_id: str) -> None:
             return
         record["status"] = "running"
         record["started_at"] = datetime.now(timezone.utc).isoformat()
+        record["worker_pid"] = os.getpid()
 
     _persist_job(job_id, record)
 
+    run_id = record.get("run_id") or job_id
+    try:
+        from runtime.worker_watchdog import get_worker_watchdog
+        get_worker_watchdog(_get_project_dir()).record_heartbeat(
+            run_id, worker_pid=os.getpid(),
+        )
+    except Exception:
+        pass
+
     worktree_dir: str | None = None
     project_dir = _get_project_dir()
     try:
+        if record.get("isolation") == "worktree":
+            _enforce_merge_writer_gate(run_id, record, project_dir)
+
         # Setup isolation if requested
         if record.get("isolation") == "worktree":
             worktree_dir = _setup_worktree(job_id)
@@ -385,11 +452,15 @@ def _run_job(job_id: str) -> None:
         evidence_payload = {
             "schema": "OmgSubagentEvidence",
             "job_id": job_id,
+            "run_id": record.get("run_id"),
             "agent_name": record["agent_name"],
             "task_text": record["task_text"],
             "worker": dispatch_result.get("worker", "unknown"),
             "exit_code": dispatch_result.get("exit_code", 0),
             "output": dispatch_result.get("output", ""),
+            "isolation_contract": record.get("isolation_contract", {}),
+            "evidence_hooks": list(record.get("evidence_hooks", [])),
+            "attach_log": record.get("attach_log"),
             "worktree": worktree_dir,
             "project_dir": active_project_dir,
         }
@@ -442,7 +513,10 @@ def get_job_status(job_id: str) -> dict[str, Any]:
 
 
 def cancel_job(job_id: str) -> bool:
-    """Cancel a queued or running job.
+    """Cancel a queued or running job, terminating the subprocess if running.
+
+    Performs real subprocess termination (SIGTERM then SIGKILL after timeout),
+    records terminal evidence, and cleans up stale worktrees.
 
     Args:
         job_id: Job identifier to cancel.
@@ -456,9 +530,49 @@ def cancel_job(job_id: str) -> bool:
             return False
         if record["status"] in ("completed", "failed", "cancelled"):
             return False
+        was_running = record["status"] == "running"
         record["status"] = "cancelled"
         record["completed_at"] = datetime.now(timezone.utc).isoformat()
 
+    run_id = record.get("run_id") or job_id
+    worker_pid = record.get("worker_pid")
+    worktree = record.get("worktree")
+
+    try:
+        from runtime.worker_watchdog import get_worker_watchdog
+        watchdog = get_worker_watchdog(_get_project_dir())
+
+        termination = None
+        if worker_pid is not None and was_running:
+            termination = watchdog.terminate_worker(run_id, worker_pid)
+
+        cleanup = None
+        if worktree:
+            cleanup = watchdog.cleanup_stale_worktree(run_id)
+
+        watchdog.emit_replay_evidence(
+            run_id,
+            f"cancel_job:{job_id}",
+            termination=termination,
+            cleanup=cleanup,
+        )
+
+        project_dir = _get_project_dir()
+        cancel_evidence: dict[str, Any] = {
+            "schema": "OmgSubagentCancelEvidence",
+            "job_id": job_id,
+            "run_id": run_id,
+            "agent_name": record.get("agent_name", ""),
+            "cancelled_at": record["completed_at"],
+            "was_running": was_running,
+            "worker_pid": worker_pid,
+            "termination": termination,
+            "cleanup": cleanup,
+        }
+        _write_job_evidence(job_id, cancel_evidence, project_dir=project_dir)
+    except Exception:
+        pass
+
     _persist_job(job_id, record)
     return True
 

package/runtime/team_router.py

@@ -14,6 +14,7 @@ import shutil
 import subprocess
 import threading
 import uuid
+from pathlib import Path
 from typing import Any
 from typing import cast
 
@@ -24,6 +25,11 @@ _OMG_ROOT = os.path.dirname(_ROUTER_DIR)
 _logger = logging.getLogger(__name__)
 _ROUTING_MODE_DEFAULT = "normal"
 _ROUTING_MODE_CLARIFICATION = "planning_read_only"
+_TEAM_STAGED_FLOW = ["team-plan", "team-exec", "team-verify", "team-fix"]
+_TEAM_COMMAND_ALIASES = {
+    "canonical": "/OMG:team",
+    "compatibility": ["/OMG:teams"],
+}
 
 # Import providers to trigger auto-registration in provider registry
 try:
@@ -36,7 +42,9 @@ except ImportError:
 from runtime.runtime_profile import resolve_parallel_workers
 from runtime.runtime_contracts import write_run_state
 from runtime.release_run_coordinator import resolve_current_run_id as resolve_coordinator_run_id
+from runtime.exec_kernel import get_exec_kernel
 from runtime.context_engine import ContextEngine
+from runtime.context_engine import _extract_clarification
 from runtime.context_engine import render_profile_digest_text
 from runtime.defense_state import DefenseState
 from runtime.equalizer import select_provider
@@ -82,18 +90,29 @@ def _check_tool_available(tool_name: str) -> bool:
     return False
 
 
-def _run_tool(cmd: list[str], *, timeout: int = 30) -> subprocess.CompletedProcess[str]:
+def _run_tool(
+    cmd: list[str],
+    *,
+    timeout: int = 30,
+    cwd: str | None = None,
+    env: dict[str, str] | None = None,
+) -> subprocess.CompletedProcess[str]:
     """Run an external tool with a mandatory timeout.
 
     Every subprocess call in the team router MUST go through this helper
     to guarantee the ``timeout`` parameter is always set.
     """
+    proc_env = os.environ.copy()
+    if env:
+        proc_env.update({key: str(value) for key, value in env.items()})
     return subprocess.run(
         cmd,
         capture_output=True,
         text=True,
         check=False,
         timeout=timeout,
+        cwd=cwd,
+        env=proc_env,
     )
 
 
@@ -255,26 +274,43 @@ def dispatch_team(req: TeamDispatchRequest) -> TeamDispatchResult:
             ]
         )
 
-    routing_mode = _ROUTING_MODE_DEFAULT
+    # --- Native question: block the turn when clarification is required ---
     if clarification_required:
-        routing_mode = _ROUTING_MODE_CLARIFICATION
-        findings.append("Clarification unresolved; downgrading to read-only planning mode")
-        actions = [
-            "Collect missing details using read/search/review tools only",
-            "Draft a concrete execution plan without mutation-capable steps",
-            "Return a single clarification request before any edits or writes",
-        ]
+        prompt = str(clarification_status.get("clarification_prompt", "")).strip()
+        if prompt:
+            findings.append(f"Clarification required: {prompt}")
+        else:
+            findings.append("Clarification required before dispatch")
+        return TeamDispatchResult(
+            status="clarification_required",
+            findings=findings,
+            actions=["Resolve the clarification question before dispatch"],
+            evidence={
+                "target": target,
+                "staged_flow": list(_TEAM_STAGED_FLOW),
+                "command_aliases": dict(_TEAM_COMMAND_ALIASES),
+                "clarification_status": clarification_status,
+                "routing_mode": _ROUTING_MODE_CLARIFICATION,
+                "generated_at": datetime.now(timezone.utc).isoformat(),
+            },
+        )
 
     evidence = {
         "target": target,
+        "staged_flow": list(_TEAM_STAGED_FLOW),
+        "command_aliases": dict(_TEAM_COMMAND_ALIASES),
         "equalizer": equalizer_decision,
         "generated_at": datetime.now(timezone.utc).isoformat(),
         "context_length": len(req.context or ""),
         "file_count": len(req.files or []),
-        "routing_mode": routing_mode,
+        "routing_mode": _ROUTING_MODE_DEFAULT,
         "clarification_status": clarification_status,
         "cli_health": cli_health,
         "live_connection": all(h.get("live_connection") for h in cli_health.values()) if cli_health else True,
+        "exec_kernel": {
+            "enabled": get_exec_kernel(_OMG_ROOT).enabled,
+            "run_id": resolve_coordinator_run_id(project_dir=_OMG_ROOT),
+        },
     }
 
     return TeamDispatchResult(status="ok", findings=findings, actions=actions, evidence=evidence)
@@ -411,6 +447,8 @@ def invoke_codex(prompt: str, project_dir: str, timeout: int = 120) -> dict[str,
         result = _run_tool(
             ["codex", "exec", "--json", prompt],
             timeout=timeout,
+            cwd=project_dir,
+            env={"CLAUDE_PROJECT_DIR": project_dir},
         )
         return {
             "model": "codex-cli",
@@ -448,9 +486,13 @@ def invoke_codex_tmux(prompt: str, project_dir: str, timeout: int = 120) -> dict
     session: str | None = None
     try:
         session_name = mgr.make_session_name("codex", unique_id=str(uuid.uuid4())[:8])
-        session = mgr.get_or_create_session(session_name)
+        session = mgr.get_or_create_session(session_name, cwd=project_dir)
         quoted_prompt = shlex.quote(prompt)
-        cmd = f"codex exec --json {quoted_prompt}; printf '\\n{_TMUX_EXIT_MARKER}:%s\\n' \"$?\""
+        cmd = (
+            f"env CLAUDE_PROJECT_DIR={shlex.quote(project_dir)} "
+            f"codex exec --json {quoted_prompt}; "
+            f"printf '\\n{_TMUX_EXIT_MARKER}:%s\\n' \"$?\""
+        )
         raw_output = mgr.send_command(session, cmd, timeout=timeout)
         output, exit_code = _parse_tmux_command_result(raw_output)
         return {"model": "codex-cli", "output": output, "exit_code": exit_code}
@@ -470,6 +512,8 @@ def invoke_gemini(prompt: str, project_dir: str, timeout: int = 120) -> dict[str
         result = _run_tool(
             ["gemini", "-p", prompt],
             timeout=timeout,
+            cwd=project_dir,
+            env={"CLAUDE_PROJECT_DIR": project_dir},
         )
         return {
             "model": "gemini-cli",
@@ -493,9 +537,13 @@ def invoke_gemini_tmux(prompt: str, project_dir: str, timeout: int = 120) -> dic
     session: str | None = None
     try:
         session_name = mgr.make_session_name("gemini", unique_id=str(uuid.uuid4())[:8])
-        session = mgr.get_or_create_session(session_name)
+        session = mgr.get_or_create_session(session_name, cwd=project_dir)
         quoted_prompt = shlex.quote(prompt)
-        cmd = f"gemini -p {quoted_prompt}; printf '\\n{_TMUX_EXIT_MARKER}:%s\\n' \"$?\""
+        cmd = (
+            f"env CLAUDE_PROJECT_DIR={shlex.quote(project_dir)} "
+            f"gemini -p {quoted_prompt}; "
+            f"printf '\\n{_TMUX_EXIT_MARKER}:%s\\n' \"$?\""
+        )
         raw_output = mgr.send_command(session, cmd, timeout=timeout)
         output, exit_code = _parse_tmux_command_result(raw_output)
         return {"model": "gemini-cli", "output": output, "exit_code": exit_code}
@@ -652,6 +700,27 @@ def execute_crazy_mode(
         context_parts.append(f"Focus files: {', '.join(files[:8])}")
     full_context = "\n\n".join(context_parts) if context_parts else ""
     
+    run_id = resolve_coordinator_run_id(project_dir=project_dir)
+    kernel = get_exec_kernel(project_dir)
+    if run_id:
+        kernel.register_run(run_id, source="team_router.execute_crazy_mode", reason="crazy_mode")
+    context_packet = _build_router_context_packet(
+        project_dir=project_dir,
+        run_id=run_id,
+        summary=full_context,
+        files=files,
+    )
+    clarification_status = _extract_clarification_status(context_packet)
+    if clarification_status.get("requires_clarification") is True:
+        return _build_clarification_blocked_result(
+            mode="crazy",
+            target_worker_count=5,
+            run_id=run_id,
+            clarification_status=clarification_status,
+            problem=problem,
+            project_dir=project_dir,
+        )
+
     worker_tasks = [
         {
             "agent_name": "architect-mode",
@@ -715,14 +784,6 @@ def execute_crazy_mode(
         + "\n\nProvide a unified action plan with dependency ordering."
     )
 
-    run_id = resolve_coordinator_run_id(project_dir=project_dir)
-    context_packet = _build_router_context_packet(
-        project_dir=project_dir,
-        run_id=run_id,
-        summary=full_context,
-        files=files,
-    )
-
     council_verdicts = run_critics(
         candidate={"output": synthesis_prompt},
         context_packet=context_packet,
@@ -740,6 +801,8 @@ def execute_crazy_mode(
 
     return {
         "status": "ok",
+        "stages": list(_TEAM_STAGED_FLOW),
+        "current_stage": "team-fix",
         "phases": [
             {"phase": 1, "agent": "claude-orchestrator", "status": "completed"},
             *[
@@ -767,6 +830,11 @@ def execute_crazy_mode(
             f"Council status: {council_status}",
         ],
         "council_verdicts": council_verdicts,
+        "exec_kernel": {
+            "enabled": kernel.enabled,
+            "run_id": run_id,
+            "attach_log": kernel.attach_log(run_id) if run_id else "",
+        },
     }
 
 
@@ -793,6 +861,27 @@ def execute_ccg_mode(
         context_parts.append(f"Focus files: {', '.join(files[:8])}")
     full_context = "\n\n".join(context_parts) if context_parts else ""
 
+    run_id = resolve_coordinator_run_id(project_dir=project_dir)
+    kernel = get_exec_kernel(project_dir)
+    if run_id:
+        kernel.register_run(run_id, source="team_router.execute_ccg_mode", reason="ccg_mode")
+    context_packet = _build_router_context_packet(
+        project_dir=project_dir,
+        run_id=run_id,
+        summary=full_context,
+        files=files,
+    )
+    clarification_status = _extract_clarification_status(context_packet)
+    if clarification_status.get("requires_clarification") is True:
+        return _build_clarification_blocked_result(
+            mode="ccg",
+            target_worker_count=2,
+            run_id=run_id,
+            clarification_status=clarification_status,
+            problem=problem,
+            project_dir=project_dir,
+        )
+
     worker_tasks = [
         {
             "agent_name": "backend-engineer",
@@ -829,14 +918,6 @@ def execute_ccg_mode(
         + "\n\nProvide a unified action plan merging backend and frontend perspectives."
     )
 
-    run_id = resolve_coordinator_run_id(project_dir=project_dir)
-    context_packet = _build_router_context_packet(
-        project_dir=project_dir,
-        run_id=run_id,
-        summary=full_context,
-        files=files,
-    )
-
     council_verdicts = run_critics(
         candidate={"output": synthesis_prompt},
         context_packet=context_packet,
@@ -854,6 +935,8 @@ def execute_ccg_mode(
 
     return {
         "status": "ok",
+        "stages": list(_TEAM_STAGED_FLOW),
+        "current_stage": "team-fix",
         "phases": [
             {"phase": 1, "agent": "claude-orchestrator", "status": "completed"},
             *[
@@ -881,6 +964,87 @@ def execute_ccg_mode(
             f"Council status: {council_status}",
         ],
         "council_verdicts": council_verdicts,
+        "exec_kernel": {
+            "enabled": kernel.enabled,
+            "run_id": run_id,
+            "attach_log": kernel.attach_log(run_id) if run_id else "",
+        },
+    }
+
+
+def _persist_question_state(
+    project_dir: str,
+    run_id: str,
+    question_text: str,
+    mode: str,
+    problem: str,
+) -> None:
+    """Write minimal question state to the run-state directory.
+
+    This is NOT a new schema — it is a flat file under .omg/state/ that
+    records which question is pending so the session can resume or reject.
+    """
+    state_dir = Path(project_dir) / ".omg" / "state" / "pending_question"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "question_pending": True,
+        "question_text": str(question_text).strip()[:500],
+        "mode": mode,
+        "problem": str(problem).strip()[:200],
+        "run_id": run_id,
+        "emitted_at": datetime.now(timezone.utc).isoformat(),
+    }
+    target = state_dir / f"{run_id}.json"
+    tmp = target.with_suffix(".tmp")
+    tmp.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    os.rename(tmp, target)
+
+
+def _build_clarification_blocked_result(
+    *,
+    mode: str,
+    target_worker_count: int,
+    run_id: str | None,
+    clarification_status: dict[str, Any],
+    problem: str,
+    project_dir: str = "",
+) -> dict[str, Any]:
+    """Build a blocked result when clarification is required.
+
+    The returned dict signals ``status='clarification_required'`` which
+    guarantees the turn ends — no worker dispatch or tool action follows.
+    Minimal question state is persisted via the run-state directory so the
+    session can resume or reject the question later.
+    """
+    prompt = str(clarification_status.get("clarification_prompt", "")).strip()
+    findings = [
+        f"Staged flow halted at team-plan for {mode} routing",
+        "Clarification unresolved before worker dispatch",
+    ]
+    if prompt:
+        findings.append(f"Clarification request: {prompt}")
+
+    # Persist minimal run-scoped question state for resume / reject
+    if run_id and project_dir:
+        _persist_question_state(project_dir, run_id, prompt, mode, problem)
+
+    return {
+        "status": "clarification_required",
+        "stages": list(_TEAM_STAGED_FLOW),
+        "current_stage": "team-plan",
+        "parallel_execution": False,
+        "sequential_execution": False,
+        "worker_count": 0,
+        "target_worker_count": target_worker_count,
+        "findings": findings,
+        "actions": [
+            "Clarify intent and acceptance criteria",
+            "Confirm required files and expected outcome",
+            "Re-run /OMG:team once clarification is resolved",
+        ],
+        "clarification_status": clarification_status,
+        "problem": problem,
+        "run_id": run_id,
     }
 
 
@@ -913,31 +1077,12 @@ def _build_router_context_packet(
 
 
 def _extract_clarification_status(context_packet: dict[str, Any] | None) -> dict[str, Any]:
-    if not isinstance(context_packet, dict):
-        return {
-            "requires_clarification": False,
-            "intent_class": "",
-            "clarification_prompt": "",
-            "confidence": 0.0,
-        }
-    status = context_packet.get("clarification_status")
-    if not isinstance(status, dict):
-        return {
-            "requires_clarification": False,
-            "intent_class": "",
-            "clarification_prompt": "",
-            "confidence": 0.0,
-        }
-    prompt = str(status.get("clarification_prompt", "")).strip().replace("\n", " ")
-    try:
-        confidence = float(status.get("confidence", 0.0))
-    except (TypeError, ValueError):
-        confidence = 0.0
+    status = _extract_clarification(context_packet)
     return {
         "requires_clarification": bool(status.get("requires_clarification") is True),
         "intent_class": str(status.get("intent_class", "")).strip(),
-        "clarification_prompt": prompt,
-        "confidence": round(max(0.0, min(1.0, confidence)), 2),
+        "clarification_prompt": str(status.get("clarification_prompt", "")).strip(),
+        "confidence": round(float(status.get("confidence", 0.0)), 2),
     }
 
 
@@ -1039,7 +1184,7 @@ def get_active_credential(provider: str, session_id: str | None = None) -> str |
 
     try:
         store = cred_mod.load_store(passphrase)
-    except (ValueError, OSError):
+    except (ValueError, OSError, RuntimeError):
         return None
 
     providers = store.get("providers", {})
@@ -1070,7 +1215,7 @@ def get_active_credential(provider: str, session_id: str | None = None) -> str |
     # Persist updated stats (best-effort)
     try:
         cred_mod.save_store(store, passphrase)
-    except (ValueError, OSError):
+    except (ValueError, OSError, RuntimeError):
         pass
 
     return keys[idx].get("key")
@@ -1099,7 +1244,7 @@ def on_rate_limit(provider: str, session_id: str | None = None) -> str | None:
 
     try:
         store = cred_mod.load_store(passphrase)
-    except (ValueError, OSError):
+    except (ValueError, OSError, RuntimeError):
         return None
 
     providers = store.get("providers", {})
@@ -1122,7 +1267,7 @@ def on_rate_limit(provider: str, session_id: str | None = None) -> str | None:
     # Persist (best-effort)
     try:
         cred_mod.save_store(store, passphrase)
-    except (ValueError, OSError):
+    except (ValueError, OSError, RuntimeError):
         pass
 
     return keys[new_idx].get("key")

package/runtime/test_intent_lock.py

@@ -142,6 +142,33 @@ def verify_lock(project_dir: str, run_id: str | None, lock_id: str | None = None
     }
 
 
+def verify_done_when(metadata: dict[str, Any] | None, run_id: str | None) -> dict[str, Any]:
+    metadata_obj = metadata if isinstance(metadata, dict) else {}
+    criteria = _extract_done_when_criteria(metadata_obj.get("done_when"))
+    if not criteria:
+        return {
+            "status": "missing_done_when",
+            "reason": "done_when_required",
+            "run_id": str(run_id or "").strip() or None,
+        }
+
+    done_when_run_id = _extract_done_when_run_id(metadata_obj.get("done_when"))
+    normalized_run_id = str(run_id or "").strip()
+    if done_when_run_id and normalized_run_id and done_when_run_id != normalized_run_id:
+        return {
+            "status": "done_when_contract_mismatch",
+            "reason": "done_when_run_id_mismatch",
+            "run_id": normalized_run_id,
+        }
+
+    return {
+        "status": "ok",
+        "reason": "done_when_present",
+        "run_id": normalized_run_id or done_when_run_id or None,
+        "done_when": criteria,
+    }
+
+
 def evaluate_test_delta(delta: dict[str, Any], project_dir: str | None = None) -> dict[str, Any]:
     override = delta.get("override")
     waiver_artifact = delta.get("waiver_artifact")
@@ -296,6 +323,30 @@ def _normalize_string_list(value: Any) -> list[str]:
     return [str(item).strip() for item in value if str(item).strip()]
 
 
+def _extract_done_when_criteria(value: Any) -> list[str]:
+    if isinstance(value, str):
+        token = value.strip()
+        return [token] if token else []
+    if isinstance(value, list):
+        return _normalize_string_list(value)
+    if isinstance(value, dict):
+        criteria = value.get("criteria")
+        if isinstance(criteria, str):
+            token = criteria.strip()
+            return [token] if token else []
+        if isinstance(criteria, list):
+            return _normalize_string_list(criteria)
+        summary = str(value.get("summary", "")).strip()
+        return [summary] if summary else []
+    return []
+
+
+def _extract_done_when_run_id(value: Any) -> str:
+    if isinstance(value, dict):
+        return str(value.get("run_id", "")).strip()
+    return ""
+
+
 def _selector_to_path(selector: str) -> str:
     return selector.split("::", 1)[0].strip()