@agentikos/omega-os 0.1.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/plan.py

@@ -0,0 +1,846 @@
+"""Plan v7 — FSM-enforced sequential plan executor.
+
+What pre-v0.19 got wrong
+------------------------
+
+The legacy ``/planner`` skill stored everything in a flat ``tracker.json``
+that the agent read end-to-end at every turn. Three failure modes:
+
+  1. **Visibility leak.** With 1500 tasks visible, an agent picks by bias
+     (short, easy, exciting) and skips ahead — "I'll do T-090 first,
+     it's the fun one". The user observed it jumping from T-050 to T-090
+     without finishing T-051..T-089.
+  2. **Soft constraint.** The order was a PROMPT instruction
+     ("NEVER skip a step"). No runtime checks. The agent could violate
+     and nothing rejected the violation.
+  3. **No explicit DAG.** Dependencies were implicit in numbering. Even
+     an honest agent couldn't tell that T-007 depended on T-005.
+
+What this module does instead
+-----------------------------
+
+  * **Persistent store.** Every task is a row in SQLite (per-project DB).
+    The agent sees one task at a time via ``next_eligible``, never the
+    whole list.
+  * **Explicit ``depends_on``.** Every task carries its predecessors as
+    a list of task ids. The plan refuses to advance a task whose deps
+    aren't all VERIFIED.
+  * **FSM enforced at engine level.** Transitions are validated by the
+    reducer. An attempt to mark T-090 DONE while T-089 is still PENDING
+    raises ``IllegalTransition`` — the agent CANNOT bypass it.
+  * **Verified completion.** Each task has a ``verify_cmd``. ``mark_done``
+    runs it inside the project root and refuses to flip to VERIFIED if
+    the command fails.
+
+Public API (consumed by ``omega plan`` CLI)
+-------------------------------------------
+
+  build_plan(slug)         — read plan/DAG.json + Genesis features → load store
+  next_eligible(slug)      — return the next PENDING task with all deps VERIFIED
+  mark_in_progress(slug, task_id)
+  mark_done(slug, task_id, *, verify=True) — runs verify_cmd, refuses if FAIL
+  mark_failed(slug, task_id, reason)
+  status(slug)             — counts per state + active task
+  list_tasks(slug, *, state=None)
+  replan(slug)             — reload DAG.json (idempotent)
+
+The store
+---------
+
+One SQLite DB per project at::
+
+  $OMEGA_HOME/Agentik_Coding/projects/<slug>/plan/plan.db
+
+Schema::
+
+  CREATE TABLE tasks (
+    id            TEXT PRIMARY KEY,        -- F-001, F-002, ...
+    slug          TEXT NOT NULL,
+    title         TEXT NOT NULL,
+    depends_on    TEXT NOT NULL,           -- JSON array of task ids
+    wave          INTEGER NOT NULL,
+    estimated_minutes INTEGER NOT NULL,
+    files_owned   TEXT NOT NULL,           -- JSON array
+    verify_cmd    TEXT NOT NULL,
+    skill         TEXT NOT NULL,
+    state         TEXT NOT NULL,           -- pending | in_progress | claimed_done | verified | failed
+    started_at    REAL,
+    finished_at   REAL,
+    last_attempt_at REAL,
+    attempts      INTEGER NOT NULL DEFAULT 0,
+    last_error    TEXT
+  );
+  CREATE INDEX idx_state ON tasks(state);
+  CREATE INDEX idx_wave  ON tasks(wave);
+
+The FSM
+-------
+
+  pending → in_progress      (next_eligible picked it)
+  in_progress → claimed_done (worker wrote .done.json; not yet trusted)
+  claimed_done → verified    (verify_cmd exited 0 — TERMINAL ok)
+  in_progress → failed       (worker exhausted retries — TERMINAL bad)
+  claimed_done → failed      (verify_cmd exited != 0 → also TERMINAL bad)
+
+The reducer (below) is the ONLY place that touches the ``state`` column.
+Every transition validates the predecessors are all VERIFIED. There is
+no other code path that can change task state.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import subprocess
+import threading
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# Valid states + transitions
+PENDING = "pending"
+IN_PROGRESS = "in_progress"
+CLAIMED_DONE = "claimed_done"
+VERIFIED = "verified"
+FAILED = "failed"
+
+_TERMINAL = (VERIFIED, FAILED)
+
+# Allowed (current, next) transitions. Anything outside this set raises.
+_ALLOWED: set[tuple[str, str]] = {
+    (PENDING, IN_PROGRESS),
+    (IN_PROGRESS, CLAIMED_DONE),
+    (CLAIMED_DONE, VERIFIED),
+    (CLAIMED_DONE, FAILED),
+    (IN_PROGRESS, FAILED),
+    # retry: a FAILED task can be reset to PENDING (operator explicit)
+    (FAILED, PENDING),
+}
+
+
+class PlanError(RuntimeError):
+    """Raised when an operation violates the plan FSM contract."""
+
+
+# ---------------------------------------------------------------------------
+# Dataclass mirror of the row
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PlanTask:
+    id: str
+    slug: str
+    title: str
+    depends_on: list[str]
+    wave: int
+    estimated_minutes: int
+    files_owned: list[str]
+    verify_cmd: str
+    skill: str
+    state: str = PENDING
+    started_at: float | None = None
+    finished_at: float | None = None
+    last_attempt_at: float | None = None
+    attempts: int = 0
+    last_error: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @staticmethod
+    def from_row(row: sqlite3.Row) -> "PlanTask":
+        return PlanTask(
+            id=row["id"], slug=row["slug"], title=row["title"],
+            depends_on=json.loads(row["depends_on"]),
+            wave=row["wave"], estimated_minutes=row["estimated_minutes"],
+            files_owned=json.loads(row["files_owned"]),
+            verify_cmd=row["verify_cmd"], skill=row["skill"],
+            state=row["state"],
+            started_at=row["started_at"], finished_at=row["finished_at"],
+            last_attempt_at=row["last_attempt_at"],
+            attempts=row["attempts"], last_error=row["last_error"] or "",
+        )
+
+
+# ---------------------------------------------------------------------------
+# Path resolver — strict per-project isolation
+# ---------------------------------------------------------------------------
+
+
+def _omega_home(explicit: str | Path | None = None) -> Path:
+    if explicit is not None:
+        return Path(explicit)
+    return Path(os.environ.get("OMEGA_HOME", str(Path.home() / "Omega")))
+
+
+def project_root(slug: str, omega_home: str | Path | None = None) -> Path:
+    return _omega_home(omega_home) / "Agentik_Coding" / "projects" / slug
+
+
+def db_path(slug: str, omega_home: str | Path | None = None) -> Path:
+    return project_root(slug, omega_home) / "plan" / "plan.db"
+
+
+def dag_path(slug: str, omega_home: str | Path | None = None) -> Path:
+    return project_root(slug, omega_home) / "plan" / "DAG.json"
+
+
+# ---------------------------------------------------------------------------
+# DB bootstrap
+# ---------------------------------------------------------------------------
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS tasks (
+  id                TEXT PRIMARY KEY,
+  slug              TEXT NOT NULL,
+  title             TEXT NOT NULL,
+  depends_on        TEXT NOT NULL,
+  wave              INTEGER NOT NULL,
+  estimated_minutes INTEGER NOT NULL,
+  files_owned       TEXT NOT NULL,
+  verify_cmd        TEXT NOT NULL,
+  skill             TEXT NOT NULL,
+  state             TEXT NOT NULL,
+  started_at        REAL,
+  finished_at       REAL,
+  last_attempt_at   REAL,
+  attempts          INTEGER NOT NULL DEFAULT 0,
+  last_error        TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_state ON tasks(state);
+CREATE INDEX IF NOT EXISTS idx_wave  ON tasks(wave);
+"""
+
+
+def _connect(slug: str, omega_home: str | Path | None = None) -> sqlite3.Connection:
+    p = db_path(slug, omega_home)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(p), isolation_level=None, check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL;")
+    conn.execute("PRAGMA synchronous=NORMAL;")
+    conn.executescript(_SCHEMA)
+    return conn
+
+
+# Per-connection lock to serialise writes across threads.
+_locks: dict[str, threading.Lock] = {}
+_locks_lock = threading.Lock()
+
+
+def _lock_for(slug: str) -> threading.Lock:
+    with _locks_lock:
+        if slug not in _locks:
+            _locks[slug] = threading.Lock()
+        return _locks[slug]
+
+
+# ---------------------------------------------------------------------------
+# build_plan — load DAG.json into the store
+# ---------------------------------------------------------------------------
+
+
+def _validate_dag(features: list[dict[str, Any]]) -> None:
+    """Topological soundness + uniqueness check."""
+    ids = [f["id"] for f in features]
+    if len(ids) != len(set(ids)):
+        dupes = [x for x in ids if ids.count(x) > 1]
+        raise PlanError(f"duplicate feature ids in DAG: {sorted(set(dupes))}")
+    id_set = set(ids)
+    for f in features:
+        for dep in f.get("depends_on", []):
+            if dep not in id_set:
+                raise PlanError(
+                    f"feature {f['id']} depends on unknown {dep!r}"
+                )
+    # Cycle detection via Kahn's algorithm
+    indeg = {fid: 0 for fid in ids}
+    for f in features:
+        for dep in f.get("depends_on", []):
+            indeg[f["id"]] += 1
+    queue = [fid for fid, d in indeg.items() if d == 0]
+    seen = 0
+    edges = {f["id"]: list(f.get("depends_on", [])) for f in features}
+    rev = {fid: [] for fid in ids}
+    for fid, deps in edges.items():
+        for d in deps:
+            rev[d].append(fid)
+    while queue:
+        cur = queue.pop()
+        seen += 1
+        for nxt in rev[cur]:
+            indeg[nxt] -= 1
+            if indeg[nxt] == 0:
+                queue.append(nxt)
+    if seen != len(ids):
+        raise PlanError("DAG has a cycle — features must be acyclic")
+
+
+def build_plan(
+    slug: str,
+    *,
+    omega_home: str | Path | None = None,
+    reset_failed: bool = False,
+) -> dict[str, Any]:
+    """Read ``plan/DAG.json``, validate the DAG, upsert every task.
+
+    Idempotent: re-running picks up new features and updates titles +
+    depends_on for known ones. State is PRESERVED (a task already
+    VERIFIED stays VERIFIED). If ``reset_failed=True``, every FAILED task
+    is re-set to PENDING.
+    """
+    dp = dag_path(slug, omega_home)
+    if not dp.exists():
+        raise PlanError(
+            f"no DAG at {dp} — run `omega genesis run {slug}` to produce it"
+        )
+    data = json.loads(dp.read_text())
+    features = data.get("features") or []
+    _validate_dag(features)
+
+    inserted = 0
+    updated = 0
+    with _lock_for(slug):
+        conn = _connect(slug, omega_home)
+        try:
+            existing = {
+                r["id"]: r for r in conn.execute(
+                    "SELECT * FROM tasks WHERE slug = ?", (slug,)
+                ).fetchall()
+            }
+            for f in features:
+                fid = f["id"]
+                if fid in existing:
+                    # Update mutable metadata only; preserve state +
+                    # timing fields.
+                    conn.execute(
+                        "UPDATE tasks SET title=?, depends_on=?, wave=?, "
+                        "estimated_minutes=?, files_owned=?, verify_cmd=?, "
+                        "skill=? WHERE id=?",
+                        (
+                            f["title"], json.dumps(f.get("depends_on", [])),
+                            int(f.get("wave", 1)),
+                            int(f.get("estimated_minutes", 30)),
+                            json.dumps(f.get("files_owned", [])),
+                            f.get("verify_cmd", "true"),
+                            f.get("skill", ""),
+                            fid,
+                        ),
+                    )
+                    updated += 1
+                else:
+                    conn.execute(
+                        "INSERT INTO tasks(id, slug, title, depends_on, wave, "
+                        "estimated_minutes, files_owned, verify_cmd, skill, "
+                        "state, attempts) VALUES (?,?,?,?,?,?,?,?,?,?,0)",
+                        (
+                            fid, slug, f["title"],
+                            json.dumps(f.get("depends_on", [])),
+                            int(f.get("wave", 1)),
+                            int(f.get("estimated_minutes", 30)),
+                            json.dumps(f.get("files_owned", [])),
+                            f.get("verify_cmd", "true"),
+                            f.get("skill", ""),
+                            PENDING,
+                        ),
+                    )
+                    inserted += 1
+            if reset_failed:
+                conn.execute(
+                    "UPDATE tasks SET state=?, last_error='' "
+                    "WHERE slug=? AND state=?",
+                    (PENDING, slug, FAILED),
+                )
+        finally:
+            conn.close()
+
+    return {"slug": slug, "inserted": inserted, "updated": updated,
+            "total": len(features)}
+
+
+# ---------------------------------------------------------------------------
+# State helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_task(
+    slug: str, task_id: str, *, omega_home: str | Path | None = None,
+) -> PlanTask | None:
+    conn = _connect(slug, omega_home)
+    try:
+        row = conn.execute(
+            "SELECT * FROM tasks WHERE id = ? AND slug = ?", (task_id, slug),
+        ).fetchone()
+    finally:
+        conn.close()
+    if not row:
+        return None
+    return PlanTask.from_row(row)
+
+
+def list_tasks(
+    slug: str,
+    *,
+    state: str | None = None,
+    omega_home: str | Path | None = None,
+) -> list[PlanTask]:
+    """List every task for a project. Filter by state when provided."""
+    conn = _connect(slug, omega_home)
+    try:
+        if state is None:
+            rows = conn.execute(
+                "SELECT * FROM tasks WHERE slug = ? "
+                "ORDER BY wave, id", (slug,),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT * FROM tasks WHERE slug = ? AND state = ? "
+                "ORDER BY wave, id", (slug, state),
+            ).fetchall()
+    finally:
+        conn.close()
+    return [PlanTask.from_row(r) for r in rows]
+
+
+def status(slug: str, *, omega_home: str | Path | None = None) -> dict[str, Any]:
+    """Per-state counts + the currently-active task (if any) + completion %."""
+    conn = _connect(slug, omega_home)
+    try:
+        counts = {
+            r["state"]: r["c"] for r in conn.execute(
+                "SELECT state, COUNT(*) AS c FROM tasks WHERE slug = ? "
+                "GROUP BY state", (slug,),
+            ).fetchall()
+        }
+        active = conn.execute(
+            "SELECT id, title FROM tasks WHERE slug = ? AND state = ? "
+            "LIMIT 1", (slug, IN_PROGRESS),
+        ).fetchone()
+        total = conn.execute(
+            "SELECT COUNT(*) AS c FROM tasks WHERE slug = ?", (slug,),
+        ).fetchone()["c"]
+    finally:
+        conn.close()
+    verified = counts.get(VERIFIED, 0)
+    pct = round(100.0 * verified / total, 1) if total else 0.0
+    return {
+        "slug": slug,
+        "total": total,
+        "counts": {
+            "pending":      counts.get(PENDING, 0),
+            "in_progress":  counts.get(IN_PROGRESS, 0),
+            "claimed_done": counts.get(CLAIMED_DONE, 0),
+            "verified":     counts.get(VERIFIED, 0),
+            "failed":       counts.get(FAILED, 0),
+        },
+        "active": dict(active) if active else None,
+        "completion_pct": pct,
+    }
+
+
+# ---------------------------------------------------------------------------
+# The reducer — the ONLY place state transitions happen
+# ---------------------------------------------------------------------------
+
+
+def _are_deps_verified(
+    conn: sqlite3.Connection, slug: str, deps: list[str],
+) -> tuple[bool, list[str]]:
+    """Return (ok, missing). ``missing`` is the list of deps that aren't
+    VERIFIED yet — used to compose a clear error message."""
+    if not deps:
+        return True, []
+    placeholders = ",".join("?" * len(deps))
+    rows = conn.execute(
+        f"SELECT id, state FROM tasks WHERE slug=? AND id IN ({placeholders})",
+        (slug, *deps),
+    ).fetchall()
+    have = {r["id"]: r["state"] for r in rows}
+    missing = [d for d in deps if have.get(d) != VERIFIED]
+    return (len(missing) == 0), missing
+
+
+def _transition(
+    slug: str, task_id: str, new_state: str,
+    *,
+    omega_home: str | Path | None = None,
+    skip_dep_check: bool = False,
+    error: str = "",
+    attempts_delta: int = 0,
+) -> PlanTask:
+    """Atomically transition one task. The single funnel for every state change.
+
+    Validates:
+      1. Task exists.
+      2. (current → new) is in the ALLOWED set.
+      3. When new == IN_PROGRESS, every dependency must be VERIFIED.
+      4. When new == VERIFIED, the previous state must be CLAIMED_DONE
+         AND every dependency must be VERIFIED (defence in depth).
+
+    Raises :class:`PlanError` on any violation.
+    """
+    with _lock_for(slug):
+        conn = _connect(slug, omega_home)
+        try:
+            row = conn.execute(
+                "SELECT * FROM tasks WHERE slug=? AND id=?",
+                (slug, task_id),
+            ).fetchone()
+            if not row:
+                raise PlanError(f"unknown task {task_id!r} for slug {slug!r}")
+            cur_state = row["state"]
+            if (cur_state, new_state) not in _ALLOWED:
+                raise PlanError(
+                    f"illegal transition {task_id}: "
+                    f"{cur_state} → {new_state}"
+                )
+            # Dep enforcement
+            deps = json.loads(row["depends_on"])
+            if new_state in (IN_PROGRESS, VERIFIED) and not skip_dep_check:
+                ok, missing = _are_deps_verified(conn, slug, deps)
+                if not ok:
+                    raise PlanError(
+                        f"{task_id} cannot move to {new_state} — "
+                        f"unverified deps: {missing}"
+                    )
+            now = time.time()
+            updates: dict[str, Any] = {"state": new_state}
+            if new_state == IN_PROGRESS:
+                updates["started_at"] = now
+                updates["last_attempt_at"] = now
+            elif new_state == VERIFIED:
+                updates["finished_at"] = now
+            elif new_state == FAILED:
+                updates["finished_at"] = now
+                if error:
+                    updates["last_error"] = error
+            elif new_state == PENDING:
+                # operator-issued retry — clear timing
+                updates["started_at"] = None
+                updates["finished_at"] = None
+                updates["last_error"] = ""
+            sets = ", ".join(f"{k}=?" for k in updates.keys())
+            args = list(updates.values())
+            if attempts_delta:
+                sets += ", attempts = attempts + ?"
+                args.append(attempts_delta)
+            args.append(slug)
+            args.append(task_id)
+            conn.execute(
+                f"UPDATE tasks SET {sets} WHERE slug=? AND id=?",
+                args,
+            )
+            # Re-read the row.
+            row = conn.execute(
+                "SELECT * FROM tasks WHERE slug=? AND id=?",
+                (slug, task_id),
+            ).fetchone()
+        finally:
+            conn.close()
+    return PlanTask.from_row(row)
+
+
+# ---------------------------------------------------------------------------
+# Public state-change API
+# ---------------------------------------------------------------------------
+
+
+def mark_in_progress(
+    slug: str, task_id: str, *,
+    omega_home: str | Path | None = None,
+) -> PlanTask:
+    """Move PENDING → IN_PROGRESS. Refuses if any dep isn't VERIFIED."""
+    return _transition(
+        slug, task_id, IN_PROGRESS, omega_home=omega_home,
+        attempts_delta=1,
+    )
+
+
+def mark_claimed_done(
+    slug: str, task_id: str, *,
+    omega_home: str | Path | None = None,
+) -> PlanTask:
+    """Worker wrote .done.json → IN_PROGRESS → CLAIMED_DONE.
+
+    Not verified yet — the next call (``mark_done`` with verify) decides.
+    """
+    return _transition(
+        slug, task_id, CLAIMED_DONE, omega_home=omega_home,
+        skip_dep_check=True,   # deps were already checked at IN_PROGRESS
+    )
+
+
+def mark_done(
+    slug: str, task_id: str, *,
+    omega_home: str | Path | None = None,
+    verify: bool = True,
+    verify_cwd: str | Path | None = None,
+    verify_timeout_s: int = 600,
+) -> PlanTask:
+    """Run the verify_cmd; CLAIMED_DONE → VERIFIED on exit 0,
+    CLAIMED_DONE → FAILED otherwise.
+
+    If ``verify=False``, the verification step is skipped (operator
+    override — useful when the verify_cmd doesn't yet exist).
+    """
+    task = _get_task(slug, task_id, omega_home=omega_home)
+    if task is None:
+        raise PlanError(f"unknown task {task_id!r}")
+    if task.state != CLAIMED_DONE:
+        # Allow IN_PROGRESS → VERIFIED only when we explicitly skip verify
+        # (the operator knows what they're doing); otherwise demand the
+        # claimed_done pit-stop.
+        if task.state == IN_PROGRESS and not verify:
+            _transition(slug, task_id, CLAIMED_DONE,
+                        omega_home=omega_home, skip_dep_check=True)
+        else:
+            raise PlanError(
+                f"{task_id} is in state {task.state}; "
+                f"expected {CLAIMED_DONE} before mark_done"
+            )
+
+    if verify:
+        cwd = Path(verify_cwd) if verify_cwd else project_root(slug, omega_home)
+        try:
+            proc = subprocess.run(
+                ["bash", "-c", task.verify_cmd],
+                check=False, capture_output=True, text=True,
+                timeout=verify_timeout_s, cwd=str(cwd),
+            )
+            rc = proc.returncode
+            tail = (proc.stdout + "\n" + proc.stderr).strip()[-400:]
+        except subprocess.TimeoutExpired:
+            rc = 124
+            tail = f"verify_cmd timed out after {verify_timeout_s}s"
+        except OSError as exc:
+            rc = 127
+            tail = f"verify_cmd exec error: {exc}"
+        if rc != 0:
+            return _transition(
+                slug, task_id, FAILED, omega_home=omega_home,
+                error=f"verify_cmd rc={rc}: {tail}",
+                skip_dep_check=True,
+            )
+
+    return _transition(
+        slug, task_id, VERIFIED, omega_home=omega_home,
+    )
+
+
+def mark_failed(
+    slug: str, task_id: str, reason: str = "",
+    *,
+    omega_home: str | Path | None = None,
+) -> PlanTask:
+    """Force-fail a task (operator action — e.g. mission abort)."""
+    return _transition(
+        slug, task_id, FAILED, omega_home=omega_home,
+        error=reason, skip_dep_check=True,
+    )
+
+
+def retry(
+    slug: str, task_id: str, *,
+    omega_home: str | Path | None = None,
+) -> PlanTask:
+    """Reset a FAILED task to PENDING (operator decided to retry)."""
+    return _transition(
+        slug, task_id, PENDING, omega_home=omega_home,
+        skip_dep_check=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# next_eligible — the function workers call to know what to do next
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RunResult:
+    """Result of an autonomous ``run`` loop iteration set."""
+
+    slug: str
+    iterations: int = 0
+    verified: list[str] = field(default_factory=list)
+    failed: list[str] = field(default_factory=list)
+    skipped_no_eligible: bool = False
+    elapsed_s: float = 0.0
+    final_status: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def run(
+    slug: str,
+    *,
+    omega_home: str | Path | None = None,
+    worker_role: str = "worker_ui",
+    max_iterations: int | None = None,
+    dispatch: Any | None = None,
+    spawn_cmd: list[str] | None = None,
+    on_iteration: Any | None = None,
+    sleep_between_s: float = 0.0,
+) -> RunResult:
+    """Autonomous multi-day plan loop with FSM enforcement.
+
+    Walks ``pending → in_progress → claimed_done → verified`` for every
+    eligible task in turn, using ``next_eligible`` to pick the single
+    next task. Built so it can run UNATTENDED for hours / days inside a
+    detached tmux session.
+
+    Dispatch path
+    -------------
+
+    For each task:
+
+      1. ``mark_in_progress`` (FAILS via reducer if any dep isn't VERIFIED —
+         that's the cardinal invariant that fixes the v6 skip bug).
+      2. Call the ``dispatch`` callable (or run ``spawn_cmd`` via subprocess
+         if no callable was passed) with the task object. The callable
+         is responsible for invoking the worker (omega worker spawn / a
+         Hermes call / a /team mission / whatever) AND waiting for the
+         worker's ``.done.json``.
+      3. ``mark_claimed_done`` once the worker reported done.
+      4. ``mark_done`` which runs ``verify_cmd`` inside the project root.
+         If verify_cmd exits 0 → VERIFIED. Otherwise → FAILED.
+
+    The loop continues until ``next_eligible`` returns None OR
+    ``max_iterations`` is hit. Failed tasks do NOT unlock their
+    dependants (correct behaviour — the loop falls naturally to
+    no-eligible after one failure cascade).
+
+    Parameters
+    ----------
+    dispatch : callable(task: PlanTask) -> None
+        How to spawn the worker. None ⇒ use ``spawn_cmd``. If both are
+        None, the loop ONLY runs the engine's verify_cmd (useful for
+        dry-running a plan whose tasks are already implemented).
+    spawn_cmd : list[str]
+        Shell tokens to run for each task. ``{task_id}``, ``{slug}``,
+        ``{title}``, ``{verify}``, ``{files}``, ``{skill}`` are substituted.
+    on_iteration : callable(task: PlanTask, result: str) -> None
+        Optional hook for telemetry / Telegram updates after each task.
+    """
+    import time as _t
+    started = _t.time()
+    out = RunResult(slug=slug)
+    iters = 0
+    while True:
+        if max_iterations is not None and iters >= max_iterations:
+            break
+        task = next_eligible(slug, omega_home=omega_home)
+        if task is None:
+            out.skipped_no_eligible = True
+            break
+        iters += 1
+        # Step 1: PENDING → IN_PROGRESS (reducer-enforced dep check)
+        try:
+            mark_in_progress(slug, task.id, omega_home=omega_home)
+        except PlanError as exc:
+            # next_eligible promised this would work; if it didn't, the
+            # store is in a bad state. Skip + record + continue.
+            out.failed.append(task.id)
+            if on_iteration:
+                on_iteration(task, f"in_progress failed: {exc}")
+            continue
+
+        # Step 2: dispatch the worker
+        dispatch_err: str | None = None
+        try:
+            if dispatch is not None:
+                dispatch(task)
+            elif spawn_cmd:
+                substituted = [
+                    seg.format(
+                        task_id=task.id, slug=task.slug, title=task.title,
+                        verify=task.verify_cmd, skill=task.skill,
+                        files=",".join(task.files_owned),
+                    ) for seg in spawn_cmd
+                ]
+                subprocess.run(substituted, check=False, timeout=3600)
+            # No dispatch + no spawn_cmd = test/dry mode → straight to claimed.
+        except Exception as exc:  # noqa: BLE001
+            dispatch_err = f"dispatch raised: {exc!r}"
+
+        # Step 3: mark_claimed_done (engine-side bookkeeping)
+        try:
+            mark_claimed_done(slug, task.id, omega_home=omega_home)
+        except PlanError as exc:
+            mark_failed(slug, task.id,
+                        reason=f"could not move to claimed_done: {exc}",
+                        omega_home=omega_home)
+            out.failed.append(task.id)
+            if on_iteration:
+                on_iteration(task, f"claimed failed: {exc}")
+            continue
+
+        # Step 4: verify_cmd runs (engine, not worker) → VERIFIED or FAILED
+        try:
+            t = mark_done(slug, task.id, omega_home=omega_home, verify=True)
+            if t.state == VERIFIED:
+                out.verified.append(task.id)
+                if on_iteration:
+                    on_iteration(task, "verified")
+            else:
+                out.failed.append(task.id)
+                if on_iteration:
+                    on_iteration(task, f"failed: {t.last_error}")
+        except PlanError as exc:
+            mark_failed(slug, task.id, reason=str(exc),
+                        omega_home=omega_home)
+            out.failed.append(task.id)
+            if on_iteration:
+                on_iteration(task, f"verify raised: {exc}")
+
+        if dispatch_err and task.id not in out.failed:
+            # Worker side blew up after engine already verified — record
+            # the warning in last_error but don't override state.
+            out.failed.append(task.id)
+
+        if sleep_between_s > 0:
+            _t.sleep(sleep_between_s)
+
+    out.iterations = iters
+    out.elapsed_s = round(_t.time() - started, 2)
+    out.final_status = status(slug, omega_home=omega_home)
+    return out
+
+
+def next_eligible(
+    slug: str,
+    *,
+    omega_home: str | Path | None = None,
+) -> PlanTask | None:
+    """Return the single next task the agent should work on.
+
+    Eligibility rule: state=PENDING AND every dep is VERIFIED.
+    Ordering: lowest wave first, then lowest id (lexicographic).
+
+    The worker MUST be handed ONLY this object — never the full task
+    list. That's how we close the visibility leak from the v6 planner.
+    """
+    with _lock_for(slug):
+        conn = _connect(slug, omega_home)
+        try:
+            rows = conn.execute(
+                "SELECT * FROM tasks WHERE slug = ? AND state = ? "
+                "ORDER BY wave, id", (slug, PENDING),
+            ).fetchall()
+        finally:
+            conn.close()
+    for row in rows:
+        task = PlanTask.from_row(row)
+        with _lock_for(slug):
+            conn = _connect(slug, omega_home)
+            try:
+                ok, _ = _are_deps_verified(conn, slug, task.depends_on)
+            finally:
+                conn.close()
+        if ok:
+            return task
+    return None