android-midscene-automation 0.2.3 → 1.1.0

package/artemis-main/artemis/graph/checkpoints.py

@@ -0,0 +1,1243 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Plan-driven checkpoint scheduling, the append-only verdict ledger, and exit
+settlement bookkeeping.
+
+Checkpoint processing preserves three invariants:
+
+1. **Append-only history**: the Operator's context is never rolled back or
+   switched; verdicts influence the future (status flips forward, findings
+   injected) but never rewrite the past.
+2. **Release / verdict / wrap-up separation**: fail-open only affects the
+   release decision — the verdict value itself (``inconclusive``) is always
+   recorded verbatim; assert failures are never repaired but always produce a
+   machine-readable test result.
+3. **Zero side effects inside check tasks**: state mutation happens only at
+   harvest points (``execution_check_node``) and at exit settlement.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from artemis.utils.notes import append_note_content, get_note_file_path
+from artemis.utils.plan_grammar import (
+    CHECKBOX_LINE_RE,
+    STATUS_ACTIVE,
+    STATUS_DONE,
+    CheckItem,
+    PlanSnapshot,
+    apply_finding_lines,
+    parse_plan,
+    subgoal_hash,
+)
+from third_party.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+LEDGER_FILENAME = "check_ledger.jsonl"
+RUN_OUTCOME_FILENAME = "run_outcome.json"
+#: Per-attempt transcript of the Checker's own streamed reasoning (one record
+#: per attempt, appended by the Checker when its run ends). Companion of the
+#: ledger for UI replay: the ledger books verdicts, this file keeps what the
+#: Checker said while reaching them.
+STREAMS_FILENAME = "check_streams.jsonl"
+#: Upper bound on the persisted text of one attempt (all segments together);
+#: the middle is cut out with a marker so both the opening and the conclusion
+#: survive.
+STREAM_TEXT_LIMIT = 20_000
+
+#: Event type published on the DataEngine bus (and forwarded over IPC/SSE to the
+#: admin console) for every visible step of the Checker's process.
+CHECKER_EVENT = "checker_event"
+FINAL_CHECKPOINT_ID = "final"
+FINAL_SUBGOAL_TEXT = "Final review against the user's original goal"
+
+# --- Config accessors (all fail-safe against a missing execution_setup) --------------
+
+
+def _setup(ctx) -> Any:
+    return getattr(ctx, "execution_setup", None)
+
+
+def midway_checks_enabled(ctx) -> bool:
+    setup = _setup(ctx)
+    return bool(setup) and bool(getattr(setup, "midway_checks_enabled", False))
+
+
+def final_check_enabled(ctx) -> bool:
+    setup = _setup(ctx)
+    return bool(setup) and bool(getattr(setup, "final_check_enabled", False))
+
+
+def _setting(ctx, name: str, default):
+    setup = _setup(ctx)
+    value = getattr(setup, name, None) if setup else None
+    return default if value is None else value
+
+
+# --- Data contracts ------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class EvidenceAnchor:
+    """Anchors a checkpoint to the evidence available at completion time."""
+
+    anchor_step_id: str | None
+    trigger_ts: float
+    plan_text: str
+
+
+@dataclass(frozen=True)
+class PendingCheckpoint:
+    """A queued checkpoint: enqueue happens at plan-write time, spawn happens in
+    ``execution_check_node`` after the turn's step is recorded."""
+
+    checkpoint_id: str
+    subgoal_text: str
+    check_items: tuple[CheckItem, ...]
+    plan_text: str
+    trigger_ts: float
+
+
+@dataclass(frozen=True)
+class CheckpointRun:
+    """One in-flight (or finished) check attempt held in ``ctx.checkpoint_tasks``."""
+
+    attempt_id: str
+    task: asyncio.Task
+    checkpoint: PendingCheckpoint
+
+
+class TestSummary(BaseModel):
+    passed: int = 0
+    failed: int = 0
+    inconclusive: int = 0
+    unchecked: int = 0
+    failed_items: list[dict] = Field(default_factory=list)
+    #: Check lines the user retired mid-run (dropped from the plan under user
+    #: guidance): their earlier verdicts are reported here, never as failures.
+    retired: int = 0
+    retired_items: list[dict] = Field(default_factory=list)
+
+    @property
+    def total(self) -> int:
+        return self.passed + self.failed + self.inconclusive + self.unchecked
+
+
+class RunOutcome(BaseModel):
+    """Machine-readable run outcome: goal-achievement axis x test-result axis."""
+
+    task_status: Literal["completed", "partial", "blocked"]
+    tests: TestSummary
+
+
+# --- Live process events --------------------------------------------------------------
+
+
+def publish_checker_event(ctx, payload: dict) -> None:
+    """Publishes one ``checker_event`` on the DataEngine bus.
+
+    The event is a *projection* for observers (admin console / SSE): the
+    append-only ledger stays the single source of truth, and publishing never
+    influences booking or release. Best-effort: a missing engine or a failing
+    subscriber is logged and ignored.
+    """
+    engine = getattr(ctx, "data_engine", None)
+    publish = getattr(engine, "_publish", None)
+    if not callable(publish):
+        return
+    now = time.time()
+    try:
+        # ``timestamp`` mirrors the other bus events so the UI orders checker
+        # blocks on the same timeline as steps and traces.
+        publish(CHECKER_EVENT, {"ts": now, "timestamp": now, **payload})
+    except Exception as e:
+        logger.debug(f"Failed to publish checker event: {e}")
+
+
+def announce_checker_attempt(
+    ctx,
+    *,
+    attempt_id: str | None,
+    phase: str,
+    checkpoint_id: str,
+    subgoal_text: str,
+    anchor_step_id: str | None,
+    check_items,
+) -> None:
+    """Publishes ``attempt_started`` from inside the Checker's traced scope.
+
+    Called at the entry of the checker functions so the event can carry the
+    Checker's own ``trace_id``: the UI uses it to route the Checker's streamed
+    reasoning (``llm_stream``) and tool traces into the attempt's timeline
+    block instead of the Operator step that happens to be current.
+    """
+    if not attempt_id:
+        return
+    try:
+        from artemis.data_engine.context_vars import CURRENT_TRACE_ID
+
+        trace_id = CURRENT_TRACE_ID.get()
+    except (ImportError, LookupError):
+        trace_id = None
+    if trace_id:
+        _attempt_traces(ctx)[attempt_id] = str(trace_id)
+    publish_checker_event(
+        ctx,
+        {
+            "event": "attempt_started",
+            "phase": phase,
+            "attempt_id": attempt_id,
+            "checkpoint_id": checkpoint_id,
+            "subgoal_text": subgoal_text,
+            "anchor_step_id": anchor_step_id,
+            "trace_id": str(trace_id) if trace_id else None,
+            "items": check_item_payloads(check_items),
+        },
+    )
+
+
+def _attempt_traces(ctx) -> dict:
+    """attempt_id -> the Checker's trace id for that attempt (set at announce
+    time). Persisted on ledger records so the UI backfill can re-attach the
+    attempt's tool traces (which carry that trace as parent) to its block."""
+    traces = getattr(ctx, "checker_attempt_traces", None)
+    if not isinstance(traces, dict):
+        traces = {}
+        try:
+            ctx.checker_attempt_traces = traces
+        except (AttributeError, TypeError, ValueError):
+            pass
+    return traces
+
+
+def attempt_trace_id(ctx, attempt_id: str | None) -> str | None:
+    if not attempt_id:
+        return None
+    value = _attempt_traces(ctx).get(attempt_id)
+    return str(value) if value else None
+
+
+def verdict_payloads(verdicts) -> list[dict]:
+    """Plain-dict projection of verdict objects (pydantic or attribute bags)."""
+    out: list[dict] = []
+    for v in verdicts or []:
+        out.append(
+            {
+                "item_text": str(getattr(v, "item_text", "") or ""),
+                "kind": str(getattr(v, "kind", "") or ""),
+                "status": str(getattr(v, "status", "") or ""),
+                "evidence": str(getattr(v, "evidence", "") or ""),
+                "suggestion": str(getattr(v, "suggestion", "") or ""),
+            }
+        )
+    return out
+
+
+def check_item_payloads(check_items) -> list[dict]:
+    return [
+        {"kind": ci.kind, "text": ci.text, "when": getattr(ci, "when", "on_complete")}
+        for ci in (check_items or [])
+    ]
+
+
+# --- Ledger (append-only) ------------------------------------------------------------
+
+
+def ledger_path(base_dir: str | Path) -> Path:
+    return Path(base_dir) / LEDGER_FILENAME
+
+
+def append_ledger_record(base_dir: str | Path, record: dict) -> None:
+    """Appends one verdict record. Records are immutable once written; any later
+    result for the same item can only be appended as a new record."""
+    record = dict(record)
+    record.setdefault("ts", time.time())
+    path = ledger_path(base_dir)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except Exception as e:
+        logger.error(f"Failed to append check ledger record: {e}")
+
+
+def read_ledger(base_dir: str | Path) -> list[dict]:
+    path = ledger_path(base_dir)
+    if not path.exists():
+        return []
+    records: list[dict] = []
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                records.append(json.loads(line))
+            except Exception:
+                logger.warning(f"Skipping malformed ledger line: {line[:120]}")
+    except Exception as e:
+        logger.error(f"Failed to read check ledger: {e}")
+    return records
+
+
+def has_ledger_records(base_dir: str | Path) -> bool:
+    path = ledger_path(base_dir)
+    try:
+        return path.exists() and path.stat().st_size > 0
+    except Exception:
+        return False
+
+
+# --- Attempt stream transcripts (append-only, one record per attempt) ----------------
+
+
+def streams_path(base_dir: str | Path) -> Path:
+    return Path(base_dir) / STREAMS_FILENAME
+
+
+def clamp_stream_segments(
+    segments: list[dict], limit: int = STREAM_TEXT_LIMIT
+) -> tuple[list[dict], int]:
+    """Bounds the total text of an attempt's stream segments to ``limit`` chars.
+
+    The head and the tail of the attempt (in stream order) are kept and the
+    middle is replaced by one ``…[N chars truncated]…`` marker, attached to the
+    segment where the cut happens. Returns ``(segments, dropped_chars)``;
+    segments left with no text are removed.
+    """
+    texts = [str(s.get("text") or "") for s in segments]
+    total = sum(len(t) for t in texts)
+    if total <= limit:
+        return [dict(s) for s in segments], 0
+
+    head_end = limit // 2
+    tail_start = total - (limit - head_end)
+    dropped = tail_start - head_end
+    marker = f"\n…[{dropped} chars truncated]…\n"
+    out: list[dict] = []
+    pos = 0
+    marker_done = False
+    for seg, text in zip(segments, texts):
+        start, end = pos, pos + len(text)
+        pos = end
+        piece = ""
+        if start < head_end:
+            piece += text[: max(0, min(len(text), head_end - start))]
+        if end > tail_start:
+            if not marker_done:
+                piece += marker
+                marker_done = True
+            piece += text[max(0, tail_start - start) :]
+        elif start < head_end < end and not marker_done:
+            piece += marker
+            marker_done = True
+        if not piece:
+            continue
+        out.append({**seg, "text": piece})
+    return out, dropped
+
+
+def append_attempt_stream_record(
+    base_dir: str | Path, record: dict, limit: int = STREAM_TEXT_LIMIT
+) -> None:
+    """Appends one attempt's streamed-reasoning transcript.
+
+    ``record["segments"]`` is a list of ``{execution_id, role, when, text}``
+    dicts (``role`` is ``thought`` for the model's reasoning stream and
+    ``answer`` for its visible text) in the order the turns started. The text
+    is clamped to ``limit`` chars before writing; the record then carries
+    ``truncated`` / ``dropped_chars``.
+    """
+    record = dict(record)
+    record.setdefault("ts", time.time())
+    segments, dropped = clamp_stream_segments(list(record.get("segments") or []), limit)
+    record["segments"] = segments
+    record["truncated"] = dropped > 0
+    record["dropped_chars"] = dropped
+    path = streams_path(base_dir)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except Exception as e:
+        logger.error(f"Failed to append check stream record: {e}")
+
+
+def read_attempt_streams(base_dir: str | Path) -> list[dict]:
+    path = streams_path(base_dir)
+    if not path.exists():
+        return []
+    records: list[dict] = []
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                loaded = json.loads(line)
+            except Exception:
+                logger.warning(f"Skipping malformed check stream line: {line[:120]}")
+                continue
+            if isinstance(loaded, dict):
+                records.append(loaded)
+    except Exception as e:
+        logger.error(f"Failed to read check streams: {e}")
+    return records
+
+
+# --- Plan helpers --------------------------------------------------------------------
+
+
+def _read_plan_text(ctx) -> str:
+    if not getattr(ctx, "data_engine", None):
+        return ""
+    path = get_note_file_path(ctx.data_engine.base_dir, "task_plan")
+    if not path.exists():
+        return ""
+    try:
+        return path.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.error(f"Failed to read task plan: {e}")
+        return ""
+
+
+def _subgoal_still_current(ctx, checkpoint_id: str) -> bool:
+    """The anchored subgoal's text is unchanged iff an item with the same
+    content hash still exists in the current plan."""
+    snapshot = parse_plan(_read_plan_text(ctx))
+    return any(i.is_top_level and i.key == checkpoint_id for i in snapshot.items)
+
+
+def revert_subgoal_status(ctx, subgoal_key: str) -> bool:
+    """Flips the matching top-level subgoal from ``[x]`` back to ``[/]``.
+
+    This is a forward-looking state change (never a rollback of history) and is
+    written directly to the file, bypassing the wrapped note tools.
+    """
+    if not getattr(ctx, "data_engine", None):
+        return False
+    path = get_note_file_path(ctx.data_engine.base_dir, "task_plan")
+    if not path.exists():
+        return False
+    try:
+        lines = path.read_text(encoding="utf-8").split("\n")
+        changed = False
+        for idx, line in enumerate(lines):
+            match = CHECKBOX_LINE_RE.match(line)
+            if not match or match.group("indent"):
+                continue
+            if subgoal_hash(match.group("text").strip()) == subgoal_key:
+                if match.group("status") == STATUS_DONE:
+                    lines[idx] = re.sub(
+                        r"^(\s*-\s*\[)" + re.escape(STATUS_DONE) + r"(\])",
+                        lambda m: m.group(1) + STATUS_ACTIVE + m.group(2),
+                        line,
+                    )
+                    changed = True
+                break
+        if changed:
+            path.write_text("\n".join(lines), encoding="utf-8")
+        return changed
+    except Exception as e:
+        logger.error(f"Failed to revert subgoal status: {e}")
+        return False
+
+
+# --- Verify-finding persistence (four layers) -------------
+#
+# Layer 1: the append-only ledger above (single source of truth — unchanged).
+# Layer 2: `- finding:` plan lines — a single-direction projection rendered by
+#          :func:`sync_finding_lines`; harness code never reads them back.
+# Layer 3: the system-authored `checker-<checkpoint_id>` note — full details on
+#          first failure, then one appended section per attempt verdict.
+# Layer 4: single-turn ``operator_feedback`` findings (unchanged).
+
+#: Reserved note-key prefixes for system-authored checker repair logs. The
+#: model-side note tool wrappers reject writes to these keys. ``checker-`` is
+#: the prefix actually used for storage (a colon is not a legal filename
+#: character on Windows/NTFS); ``checker:`` is reserved alongside it so the
+#: conceptual spelling can never be squatted either.
+CHECKER_NOTE_PREFIXES = ("checker-", "checker:")
+
+_FINDING_HEADLINE_EVIDENCE_LIMIT = 160
+
+
+def checker_note_key(checkpoint_id: str) -> str:
+    """Note key of the system-authored detail/repair log for one checkpoint."""
+    return f"checker-{checkpoint_id}"
+
+
+def is_checker_note_key(key: str) -> bool:
+    """True when a note key is reserved for system-authored checker logs."""
+    return str(key or "").strip().lower().startswith(CHECKER_NOTE_PREFIXES)
+
+
+def _finding_registry(ctx) -> dict:
+    """checkpoint_id -> rendered headline of the unresolved verify finding.
+
+    Kept as a dynamic context attribute (``ArtemisContext`` allows extras) so
+    the registry lives exactly as long as the run.
+    """
+    registry = getattr(ctx, "checker_findings", None)
+    if not isinstance(registry, dict):
+        registry = {}
+        try:
+            ctx.checker_findings = registry
+        except (AttributeError, TypeError, ValueError):
+            pass
+    return registry
+
+
+def _finding_items(ctx) -> dict:
+    """checkpoint_id -> ``{(kind, item_text), ...}`` of the failed verify items
+    that produced the headline currently held in :func:`_finding_registry`.
+
+    Sibling map of the registry (same lifetime, same keys) so a headline can
+    be retired when user guidance withdraws every item behind it.
+    """
+    items = getattr(ctx, "checker_finding_items", None)
+    if not isinstance(items, dict):
+        items = {}
+        try:
+            ctx.checker_finding_items = items
+        except (AttributeError, TypeError, ValueError):
+            pass
+    return items
+
+
+def _register_finding(ctx, checkpoint_id: str, verify_failures: list) -> None:
+    _finding_registry(ctx)[checkpoint_id] = _render_finding_headline(checkpoint_id, verify_failures)
+    _finding_items(ctx)[checkpoint_id] = {
+        (str(getattr(v, "kind", "") or ""), str(getattr(v, "item_text", "") or ""))
+        for v in verify_failures
+    }
+
+
+def _clear_finding(ctx, checkpoint_id: str) -> bool:
+    """Drops a checkpoint's standing headline; True when one was registered."""
+    _finding_items(ctx).pop(checkpoint_id, None)
+    return _finding_registry(ctx).pop(checkpoint_id, None) is not None
+
+
+def _retired_checks(ctx) -> set[tuple[str, str]]:
+    retired = getattr(ctx, "guidance_retired_checks", None)
+    return retired if isinstance(retired, set) else set()
+
+
+def retire_check_items(ctx, items) -> None:
+    """Records ``(kind, text)`` check items the Operator dropped under user
+    guidance and withdraws their already-materialized findings.
+
+    Recording feeds the harvest gate (:func:`_active_verdicts`) and the run
+    outcome. Cleanup: every standing headline produced *only* by now-retired
+    items is popped and the plan's finding lines are re-projected; a headline
+    that still names a live item stays untouched.
+    """
+    incoming = {(str(kind), str(text)) for kind, text in items}
+    if not incoming:
+        return
+    retired = _retired_checks(ctx) | incoming
+    ctx.guidance_retired_checks = retired
+    registry = _finding_registry(ctx)
+    produced_by = _finding_items(ctx)
+    stale = [cid for cid in list(registry) if produced_by.get(cid) and produced_by[cid] <= retired]
+    for cid in stale:
+        _clear_finding(ctx, cid)
+        logger.info(
+            f"Checkpoint {cid}: standing finding headline withdrawn — every item"
+            " behind it was retired by user guidance."
+        )
+    if stale:
+        sync_finding_lines(ctx)
+
+
+def reinstate_check_items(ctx, items) -> None:
+    """Removes ``(kind, text)`` items from the retired set: the Operator has
+    declared them in the plan again, so their verdicts drive side effects
+    once more and the run outcome counts them normally. A no-op when none of
+    the given items is retired."""
+    retired = _retired_checks(ctx)
+    if not retired:
+        return
+    back = {(str(kind), str(text)) for kind, text in items} & retired
+    if not back:
+        return
+    ctx.guidance_retired_checks = retired - back
+    logger.info(
+        "Check line(s) retired under user guidance are declared again and"
+        f" reinstated: {sorted(back)}"
+    )
+
+
+def _active_verdicts(ctx, checkpoint, verdicts: list) -> list:
+    """The verdicts still allowed to drive side effects: those whose
+    ``(kind, item_text)`` was not retired by user guidance. Ledger recording is
+    never filtered — this gate only protects execution state."""
+    retired = _retired_checks(ctx)
+    if not retired:
+        return list(verdicts)
+    active: list = []
+    dropped: list = []
+    for v in verdicts:
+        key = (str(getattr(v, "kind", "") or ""), str(getattr(v, "item_text", "") or ""))
+        (dropped if key in retired else active).append(v)
+    if dropped:
+        logger.info(
+            f"Checkpoint {checkpoint.checkpoint_id}: {len(dropped)} verdict(s)"
+            " recorded but dropped from side effects — their check items were"
+            " retired by user guidance: "
+            + ", ".join(
+                f"[{k}] '{t}'"
+                for k, t in ((getattr(v, "kind", ""), getattr(v, "item_text", "")) for v in dropped)
+            )
+        )
+    return active
+
+
+def _render_finding_headline(checkpoint_id: str, verify_failures: list) -> str:
+    first = verify_failures[0]
+    evidence = str(getattr(first, "evidence", "") or "").strip()
+    if len(evidence) > _FINDING_HEADLINE_EVIDENCE_LIMIT:
+        evidence = evidence[: _FINDING_HEADLINE_EVIDENCE_LIMIT - 1] + "…"
+    detail = f": {evidence}" if evidence else ""
+    return (
+        f"verify failed — '{first.item_text}'{detail}"
+        f" (details & repair log: note '{checker_note_key(checkpoint_id)}')"
+    )
+
+
+def sync_finding_lines(ctx) -> None:
+    """Re-projects the unresolved verify findings into ``task_plan.md``.
+
+    Deterministic merge-back protection for the ``- finding:`` channel: every
+    call strips all finding lines and re-renders one per unresolved checkpoint
+    under its subgoal, so a model deletion grows back and a resolved finding
+    disappears. Pure projection — nothing is ever parsed back out of the plan.
+    """
+    if not getattr(ctx, "data_engine", None):
+        return
+    path = get_note_file_path(ctx.data_engine.base_dir, "task_plan")
+    if not path.exists():
+        return
+    try:
+        content = path.read_text(encoding="utf-8")
+        registry = getattr(ctx, "checker_findings", None)
+        findings = dict(registry) if isinstance(registry, dict) else {}
+        projected = apply_finding_lines(content, findings)
+        if projected != content:
+            path.write_text(projected, encoding="utf-8")
+    except Exception as e:
+        logger.error(f"Failed to project finding lines into task plan: {e}")
+
+
+def _log_checker_note(ctx, run: CheckpointRun, verdicts: list) -> None:
+    """Appends this attempt's verdicts to the checkpoint's system note.
+
+    The note starts at the FIRST failed verify (full criterion/evidence/
+    suggestion detail) and afterwards accumulates one section per attempt —
+    including the eventually passing one — as a persistent repair log. It is
+    written through the notes storage API directly (never the model tool
+    path), stays on disk after resolution, and is discoverable via read_note /
+    search_history under the key returned by :func:`checker_note_key`.
+    """
+    try:
+        base_dir = ctx.data_engine.base_dir
+        cid = run.checkpoint.checkpoint_id
+        key = checker_note_key(cid)
+        note_path = get_note_file_path(base_dir, key)
+        verify_failures = [v for v in verdicts if v.kind == "verify" and v.status == "failed"]
+        if not note_path.exists() and not verify_failures:
+            return  # the log only starts once a verify criterion has failed
+
+        blocks: list[str] = []
+        if not note_path.exists():
+            blocks.append(
+                f"# Checker findings — subgoal: {run.checkpoint.subgoal_text}\n"
+                "System-authored verification log (append-only). Each section"
+                " records one checkpoint attempt's verdicts."
+            )
+        outcome = "failed" if verify_failures else "passed"
+        lines = [f"## attempt {run.attempt_id} — verify {outcome}"]
+        for v in verdicts:
+            line = f"- [{v.kind}] '{v.item_text}': {v.status} — {v.evidence}"
+            suggestion = str(getattr(v, "suggestion", "") or "")
+            if suggestion:
+                line += f"\n  suggestion: {suggestion}"
+            lines.append(line)
+        blocks.append("\n".join(lines))
+        append_note_content(base_dir, key, "\n\n".join(blocks))
+    except Exception as e:
+        logger.error(f"Failed to append checker note for {run.attempt_id}: {e}")
+
+
+# --- Queueing (called from _process_plan_write; never spawns) ------------------------
+
+
+def queue_checkpoints(
+    ctx,
+    state,
+    after: PlanSnapshot,
+    new_completions: list[str],
+    plan_text: str,
+) -> None:
+    """Enqueues a pending checkpoint for every newly completed top-level subgoal
+    that carries ``on_complete`` check items.
+
+    Spawning is deliberately deferred to ``execution_check_node``: at this
+    moment the turn's step is not yet recorded, so an anchor taken here would
+    point at the previous turn.
+    """
+    if not midway_checks_enabled(ctx):
+        return
+    if state is not None and getattr(state, "user_stop_requested", False):
+        return
+    items_by_key = {i.key: i for i in after.top_level}
+    for text in new_completions:
+        key = subgoal_hash(text)
+        item = items_by_key.get(key)
+        if item is None:
+            continue
+        check_items = tuple(ci for ci in after.check_items_of(item) if ci.when == "on_complete")
+        if not check_items:
+            continue
+        ctx.pending_checkpoints.append(
+            PendingCheckpoint(
+                checkpoint_id=key,
+                subgoal_text=text,
+                check_items=check_items,
+                plan_text=plan_text,
+                trigger_ts=time.time(),
+            )
+        )
+        logger.info(f"Queued checkpoint for completed subgoal: {text}")
+
+
+# --- Harvest ------------------------------------------------------------------
+
+
+def _record_verdicts(
+    ctx,
+    run: CheckpointRun,
+    verdicts: list,
+    anchor_step_id: str | None,
+) -> None:
+    base_dir = ctx.data_engine.base_dir
+    when_by_text = {(ci.kind, ci.text): ci.when for ci in run.checkpoint.check_items}
+    for v in verdicts:
+        append_ledger_record(
+            base_dir,
+            {
+                "attempt_id": run.attempt_id,
+                "checkpoint_id": run.checkpoint.checkpoint_id,
+                "subgoal_text": run.checkpoint.subgoal_text,
+                "trace_id": attempt_trace_id(ctx, run.attempt_id),
+                "item_text": v.item_text,
+                "kind": v.kind,
+                "when": when_by_text.get((v.kind, v.item_text), "on_complete"),
+                "status": v.status,
+                "evidence": v.evidence,
+                "suggestion": getattr(v, "suggestion", ""),
+                "anchor_step_id": anchor_step_id,
+            },
+        )
+
+
+def _annotate_history_chunks(ctx, run: CheckpointRun, verdicts) -> None:
+    """Annotate an existing history chunk: a verdict harvested after its subgoal's
+    segment was chunk-compressed is appended to that chunk and bumps its
+    version. Best-effort — history annotation never gates checkpoint booking."""
+    try:
+        chunker = getattr(getattr(ctx, "transcript_ledger", None), "chunker", None)
+        if chunker is None:
+            return
+        payload = [
+            {
+                "kind": getattr(v, "kind", "check"),
+                "item_text": getattr(v, "item_text", ""),
+                "status": getattr(v, "status", ""),
+                "evidence": getattr(v, "evidence", ""),
+            }
+            for v in verdicts
+        ]
+        chunker.annotate_from_checkpoint(run.checkpoint.checkpoint_id, payload)
+    except Exception as e:
+        logger.debug(f"History chunk annotation skipped: {e}")
+
+
+def _record_attempt_failure(ctx, run: CheckpointRun, status: str, evidence: str) -> None:
+    base_dir = ctx.data_engine.base_dir
+    for ci in run.checkpoint.check_items:
+        append_ledger_record(
+            base_dir,
+            {
+                "attempt_id": run.attempt_id,
+                "checkpoint_id": run.checkpoint.checkpoint_id,
+                "subgoal_text": run.checkpoint.subgoal_text,
+                "trace_id": attempt_trace_id(ctx, run.attempt_id),
+                "item_text": ci.text,
+                "kind": ci.kind,
+                "when": ci.when,
+                "status": status,
+                "evidence": evidence,
+                "anchor_step_id": None,
+            },
+        )
+
+
+def harvest_run(
+    ctx,
+    state,
+    run: CheckpointRun,
+    *,
+    allow_side_effects: bool,
+    cancelled_status: str = "superseded",
+    anchor_step_id: str | None = None,
+) -> list[str]:
+    """Books a finished (done/cancelled) attempt into the ledger and, when the
+    verdict is still applicable, applies its execution-state side effects.
+
+    Returns Operator-facing findings (injected as ``operator_feedback``). The
+    verdict values themselves are never altered by the release decision:
+    an errored verify is *released* (fail-open) but *recorded* inconclusive.
+    """
+    task = run.task
+    findings: list[str] = []
+    checkpoint = run.checkpoint
+
+    def _event(status: str, verdicts_payload: list[dict], **extra) -> None:
+        publish_checker_event(
+            ctx,
+            {
+                "event": "attempt_finished",
+                "phase": "checkpoint",
+                "attempt_id": run.attempt_id,
+                "checkpoint_id": checkpoint.checkpoint_id,
+                "subgoal_text": checkpoint.subgoal_text,
+                "trace_id": attempt_trace_id(ctx, run.attempt_id),
+                "status": status,
+                "verdicts": verdicts_payload,
+                "findings": list(findings),
+                **extra,
+            },
+        )
+
+    def _failure_verdicts(status: str, evidence: str) -> list[dict]:
+        return [
+            {
+                "item_text": ci.text,
+                "kind": ci.kind,
+                "status": status,
+                "evidence": evidence,
+                "suggestion": "",
+            }
+            for ci in checkpoint.check_items
+        ]
+
+    if task.cancelled():
+        evidence = (
+            "attempt superseded by a newer completion of the same subgoal"
+            if cancelled_status == "superseded"
+            else "cancelled at exit settlement (settlement timeout)"
+        )
+        _record_attempt_failure(ctx, run, cancelled_status, evidence)
+        _event(cancelled_status, _failure_verdicts(cancelled_status, evidence))
+        return findings
+
+    exc = task.exception()
+    if exc is not None:
+        status = "inconclusive"
+        reason = (
+            f"check timed out after {_setting(ctx, 'checkpoint_timeout', 180.0)}s"
+            if isinstance(exc, (asyncio.TimeoutError, TimeoutError))
+            else f"check raised an exception: {exc}"
+        )
+        logger.warning(
+            f"Checkpoint attempt {run.attempt_id} did not produce a verdict"
+            f" ({reason}); releasing (fail-open) but recording inconclusive."
+        )
+        _record_attempt_failure(ctx, run, status, reason)
+        _event("error", _failure_verdicts(status, reason), error=reason)
+        return findings
+
+    report = task.result()
+    verdicts = list(getattr(report, "verdicts", []) or [])
+    _record_verdicts(ctx, run, verdicts, anchor_step_id)
+    _annotate_history_chunks(ctx, run, verdicts)
+    # Layer 3: the per-checkpoint repair log accumulates every booked attempt.
+    _log_checker_note(ctx, run, verdicts)
+
+    # Guidance gate: a verdict for a check item the user retired mid-run (the
+    # Operator dropped its line under a guidance waiver) is a result for a
+    # withdrawn requirement — booked above, never a repair/halt trigger.
+    active = _active_verdicts(ctx, checkpoint, verdicts)
+    all_retired = bool(verdicts) and not active
+
+    # Applicability gate for side effects: the verdict must belong to the
+    # current attempt of its checkpoint AND the anchored subgoal's text must be
+    # unchanged in the current plan AND at least one verdict must still be
+    # live. Stale/mismatched/fully retired verdicts are ledger-only.
+    applicable = (
+        allow_side_effects
+        and not all_retired
+        and _subgoal_still_current(ctx, checkpoint.checkpoint_id)
+    )
+    user_stopped = bool(state is not None and getattr(state, "user_stop_requested", False))
+
+    verify_failures = [v for v in active if v.kind == "verify" and v.status == "failed"]
+    assert_failures = [v for v in active if v.kind == "assert" and v.status == "failed"]
+
+    registry_changed = False
+    reverted = False
+
+    if verify_failures and applicable and not user_stopped:
+        max_repairs = int(_setting(ctx, "checkpoint_max_repairs", 2))
+        repairs = ctx.checkpoint_repairs.get(checkpoint.checkpoint_id, 0)
+        if repairs < max_repairs:
+            ctx.checkpoint_repairs[checkpoint.checkpoint_id] = repairs + 1
+            reverted = revert_subgoal_status(ctx, checkpoint.checkpoint_id)
+            # Layer 2: register the standing plan headline for this unresolved
+            # finding; the projection below renders it under the subgoal.
+            _register_finding(ctx, checkpoint.checkpoint_id, verify_failures)
+            registry_changed = True
+            for v in verify_failures:
+                suggestion = getattr(v, "suggestion", "") or ""
+                findings.append(
+                    f"[verify failed] Subgoal '{checkpoint.subgoal_text}' —"
+                    f" criterion '{v.item_text}': {v.evidence}"
+                    + (f" Suggestion: {suggestion}" if suggestion else "")
+                )
+            if reverted:
+                findings.append(
+                    f"The subgoal '{checkpoint.subgoal_text}' has been set back to"
+                    " in-progress ([/]). Address the findings above, then complete"
+                    " it again."
+                )
+        else:
+            # Quota exhausted: the run is settled for this checkpoint — the
+            # standing headline is retired (the ledger and the checker note
+            # keep the full record).
+            registry_changed = _clear_finding(ctx, checkpoint.checkpoint_id)
+            logger.warning(
+                f"Checkpoint {checkpoint.checkpoint_id} exhausted its repair"
+                f" quota ({max_repairs}); verdict stays failed, no further"
+                " repair loop."
+            )
+    elif not verify_failures and not all_retired:
+        # A booked attempt without failed verify criteria resolves (or
+        # releases) the checkpoint: its standing headline is retired. (A fully
+        # retired report says nothing about the checkpoint — its headline, if
+        # any, was already handled by ``retire_check_items``.)
+        registry_changed = _clear_finding(ctx, checkpoint.checkpoint_id)
+
+    if registry_changed:
+        sync_finding_lines(ctx)
+
+    if assert_failures:
+        policy = str(_setting(ctx, "assert_failure_policy", "continue"))
+        if policy == "halt":
+            ctx.assert_halt = True
+            logger.warning(
+                "Assert failure under 'halt' policy: latching halt flag for exit settlement."
+            )
+
+    # Event payload: ``verdicts`` carries every booked verdict (ledger view);
+    # ``applicable`` is False when nothing could take effect — including a
+    # report whose check items were all retired by user guidance; ``retired``
+    # lists the ``(kind, item_text)`` pairs of the verdicts dropped by that
+    # guidance gate (empty when none were).
+    _event(
+        "done",
+        verdict_payloads(verdicts),
+        applicable=bool(applicable),
+        reverted=bool(reverted),
+        retired=[
+            {"kind": p["kind"], "item_text": p["item_text"]}
+            for p in verdict_payloads(verdicts)
+            if (p["kind"], p["item_text"]) in _retired_checks(ctx)
+        ],
+        repairs_used=int(ctx.checkpoint_repairs.get(checkpoint.checkpoint_id, 0)),
+    )
+    return findings
+
+
+def harvest_finished_checkpoints(ctx, state) -> list[str]:
+    """Non-blocking harvest: books every ``done()`` attempt, never awaits a
+    running one. Returns Operator-facing findings."""
+    if not getattr(ctx, "data_engine", None):
+        return []
+    findings: list[str] = []
+    for cid, run in list(ctx.checkpoint_tasks.items()):
+        if not run.task.done():
+            continue
+        del ctx.checkpoint_tasks[cid]
+        findings.extend(harvest_run(ctx, state, run, allow_side_effects=True))
+    return findings
+
+
+# --- Spawn after record_step -------------------------------------------------
+
+
+async def spawn_pending_checkpoints(ctx, state, anchor_step_id: str | None) -> list[str]:
+    """Spawns queued checkpoints against the just-recorded step, honoring the
+    concurrency cap and superseding stale attempts without losing verdicts.
+
+    Returns findings harvested from superseded-but-finished attempts.
+    """
+    findings: list[str] = []
+    if not getattr(ctx, "data_engine", None):
+        return findings
+    if not midway_checks_enabled(ctx):
+        return findings
+    if state is not None and getattr(state, "user_stop_requested", False):
+        return findings
+
+    from artemis.agents.checker.checker import run_checkpoint_check
+
+    max_concurrent = int(_setting(ctx, "max_concurrent_checkpoints", 3))
+    timeout = float(_setting(ctx, "checkpoint_timeout", 180.0))
+    goal = getattr(state, "initial_goal", "") if state is not None else ""
+
+    while ctx.pending_checkpoints and len(ctx.checkpoint_tasks) < max_concurrent:
+        pending: PendingCheckpoint = ctx.pending_checkpoints.pop(0)
+        cid = pending.checkpoint_id
+
+        old_run: CheckpointRun | None = ctx.checkpoint_tasks.pop(cid, None)
+        if old_run is not None:
+            if old_run.task.done():
+                # A finished-but-unharvested attempt: book it first (verdicts,
+                # including failures, are never dropped), ledger-only.
+                findings.extend(harvest_run(ctx, state, old_run, allow_side_effects=False))
+            else:
+                old_run.task.cancel()
+                try:
+                    await old_run.task
+                except (asyncio.CancelledError, Exception) as exc:
+                    logger.debug(
+                        f"Superseded checkpoint attempt {old_run.attempt_id} ended with "
+                        f"{exc!r}; harvesting anyway",
+                        exc_info=True,
+                    )
+                harvest_run(ctx, state, old_run, allow_side_effects=False)
+
+        seq = ctx.checkpoint_attempt_seq.get(cid, 0) + 1
+        ctx.checkpoint_attempt_seq[cid] = seq
+        attempt_id = f"{cid}#{seq}"
+        anchor = EvidenceAnchor(
+            anchor_step_id=anchor_step_id,
+            trigger_ts=pending.trigger_ts,
+            plan_text=pending.plan_text,
+        )
+        task = asyncio.create_task(
+            asyncio.wait_for(
+                run_checkpoint_check(
+                    ctx,
+                    check_items=pending.check_items,
+                    anchor=anchor,
+                    goal=goal,
+                    subgoal_text=pending.subgoal_text,
+                    attempt_id=attempt_id,
+                ),
+                timeout=timeout,
+            )
+        )
+        ctx.checkpoint_tasks[cid] = CheckpointRun(
+            attempt_id=attempt_id, task=task, checkpoint=pending
+        )
+        logger.info(f"Spawned checkpoint attempt {attempt_id} anchored at step {anchor_step_id}")
+
+    return findings
+
+
+# --- Exit settlement barrier ------------------------------------------
+
+
+async def settle_all_checkpoints(ctx, state) -> None:
+    """The one intentional blocking wait of the whole flow: collects every
+    outstanding checkpoint before exit, bounded by ``settlement_timeout``.
+    Attempts still running at the deadline are cancelled and recorded
+    ``unchecked`` (settlement timeout). Runs unconditionally — a started check
+    must be booked before exit regardless of the final-check switch."""
+    if not getattr(ctx, "data_engine", None):
+        return
+    runs = list(ctx.checkpoint_tasks.values())
+    ctx.checkpoint_tasks.clear()
+    if not runs:
+        return
+
+    timeout = float(_setting(ctx, "settlement_timeout", 120.0))
+    tasks = [r.task for r in runs]
+    try:
+        _done, pending = await asyncio.wait(tasks, timeout=timeout)
+    except Exception as e:
+        logger.error(f"Settlement wait failed: {e}")
+        pending = {t for t in tasks if not t.done()}
+
+    for t in pending:
+        t.cancel()
+    for t in pending:
+        try:
+            await t
+        except (asyncio.CancelledError, Exception) as exc:
+            logger.debug(
+                f"Cancelled checkpoint attempt ended with {exc!r} at settlement; harvesting anyway",
+                exc_info=True,
+            )
+
+    for run in runs:
+        # Settlement is bookkeeping, not a repair point: side effects off.
+        harvest_run(
+            ctx,
+            state,
+            run,
+            allow_side_effects=False,
+            cancelled_status="unchecked",
+        )
+
+
+# --- Run outcome ---------------------------------------------------------------------
+
+_RESOLVABLE = ("passed", "failed", "inconclusive")
+
+
+def resolve_item_status(kind: str, records: list[dict]) -> str:
+    """Resolves one check item's final status from its ledger records.
+
+    Assert: the first failure is permanent — any failed record makes the item
+    failed. Verify: the latest substantive verdict wins (a repaired-then-passed
+    verify is passed). No substantive record at all -> unchecked.
+    """
+    substantive = [r for r in records if r.get("status") in _RESOLVABLE]
+    if kind == "assert" and any(r.get("status") == "failed" for r in substantive):
+        return "failed"
+    if substantive:
+        return substantive[-1]["status"]
+    return "unchecked"
+
+
+def compute_test_summary(
+    check_items: list[CheckItem],
+    records: list[dict],
+    retired: set[tuple[str, str]] | None = None,
+) -> TestSummary:
+    """Folds the verdict ledger into pass/fail counts over the declared items.
+
+    ``retired`` names check lines the Operator dropped under user guidance; a
+    line that is retired and no longer declared in the plan is reported under
+    ``retired`` with its last recorded verdict, not as a pass or a failure —
+    the user withdrew that requirement.
+    """
+    summary = TestSummary()
+    retired = retired or set()
+    by_item: dict[tuple[str, str], list[dict]] = {}
+    for r in records:
+        by_item.setdefault((str(r.get("kind")), str(r.get("item_text"))), []).append(r)
+
+    seen: set[tuple[str, str]] = set()
+    all_items: list[tuple[str, str]] = []
+    for ci in check_items:
+        sig = (ci.kind, ci.text)
+        if sig not in seen:
+            seen.add(sig)
+            all_items.append(sig)
+    # Items that only ever existed in the ledger (e.g. their plan lines were
+    # legitimately revised by the Planner) still count.
+    for sig in by_item:
+        if sig not in seen:
+            seen.add(sig)
+            all_items.append(sig)
+
+    declared = {(ci.kind, ci.text) for ci in check_items}
+    for kind, text in all_items:
+        status = resolve_item_status(kind, by_item.get((kind, text), []))
+        if (kind, text) in retired and (kind, text) not in declared:
+            summary.retired += 1
+            summary.retired_items.append({"item_text": text, "kind": kind, "last_status": status})
+            continue
+        if status == "passed":
+            summary.passed += 1
+        elif status == "failed":
+            summary.failed += 1
+            failing = [r for r in by_item.get((kind, text), []) if r.get("status") == "failed"]
+            summary.failed_items.append(
+                {
+                    "item_text": text,
+                    "kind": kind,
+                    "evidence": failing[-1].get("evidence", "") if failing else "",
+                }
+            )
+        elif status == "inconclusive":
+            summary.inconclusive += 1
+        else:
+            summary.unchecked += 1
+    return summary
+
+
+def compute_run_outcome(
+    snapshot: PlanSnapshot,
+    records: list[dict],
+    *,
+    verify_blocked: bool,
+    retired: set[tuple[str, str]] | None = None,
+) -> RunOutcome:
+    """Assembles the machine-readable run outcome.
+
+    ``verify_blocked`` marks the "verify unmet and budget exhausted" exit —
+    the goal-achievement axis then reads blocked even though the plan claims
+    completion. Assert failures never change ``task_status``: a finished task
+    with failed assertions is ``completed`` with ``tests.failed > 0``.
+    """
+    tests = compute_test_summary(list(snapshot.all_check_items), records, retired=retired)
+    if verify_blocked:
+        task_status: Literal["completed", "partial", "blocked"] = "blocked"
+    elif snapshot.all_top_level_done:
+        task_status = "completed"
+    else:
+        task_status = "partial"
+    return RunOutcome(task_status=task_status, tests=tests)
+
+
+def write_run_outcome(base_dir: str | Path, outcome: RunOutcome, extra: dict | None = None) -> None:
+    try:
+        payload = outcome.model_dump()
+        if extra:
+            payload.update(extra)
+        path = Path(base_dir) / RUN_OUTCOME_FILENAME
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+    except Exception as e:
+        logger.error(f"Failed to write run outcome: {e}")
+
+
+def read_run_outcome(base_dir: str | Path) -> dict | None:
+    path = Path(base_dir) / RUN_OUTCOME_FILENAME
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None