loop-engineer 0.10.0__tar.gz → 0.11.0__tar.gz

{loop_engineer-0.10.0 → loop_engineer-0.11.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "loop-engineer",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Design, launch, verify, repair, and improve agent loops. A Claude-Code-native architect+operator for long-running, verifiable, self-improving agentic-coding systems.",
   "author": {
     "name": "Sollan Systems",

loop_engineer-0.11.0/.github/workflows/ci.yml

@@ -0,0 +1,243 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  gates:
+    name: gates (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install gate dependencies
+        run: python -m pip install --upgrade pip pyyaml pytest jsonschema hypothesis
+
+      - name: Frontmatter gate
+        run: python -B scripts/validate_frontmatter.py
+
+      - name: Structural self-eval gate
+        run: python -B scripts/self_eval.py
+
+      - name: Test suite
+        run: python -B -m pytest -q -p no:cacheprovider scripts
+
+      - name: Compile portable core
+        run: python -B -m py_compile loop/*.py scripts/*.py
+
+      - name: Manifests and schemas are valid JSON
+        run: |
+          python -B -c "import json, glob; \
+          files = ['.claude-plugin/plugin.json', '.claude-plugin/marketplace.json'] \
+          + glob.glob('schemas/*.json') + glob.glob('evals/**/*.json', recursive=True); \
+          [json.load(open(f)) for f in files]; \
+          print(f'valid JSON: {len(files)} files')"
+
+      - name: Quickstart smoke test
+        run: |
+          python -B -m loop doctor --mode release examples/coverage-repair
+          python -B -m loop inspect examples/coverage-repair
+
+      - name: Plan lint smoke test
+        run: |
+          python -B -m loop plan-lint --mode release examples/plans/coverage-repair.plan.json
+          if python -B -m loop plan-lint --mode release examples/plans/invalid/cyclic-dependency.plan.json; then
+            echo "::error::cyclic-dependency.plan.json unexpectedly passed plan-lint"
+            exit 1
+          fi
+          if python -B -m loop plan-lint --mode release examples/plans/invalid/missing-goal.plan.json; then
+            echo "::error::missing-goal.plan.json unexpectedly passed plan-lint"
+            exit 1
+          fi
+
+  recipe-langgraph:
+    name: recipe (langgraph)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Install recipe dependencies
+        run: python -m pip install --upgrade pip pyyaml pytest jsonschema langgraph
+      - name: LangGraph recipe end-to-end
+        run: python -B -m pytest -q -p no:cacheprovider scripts/test_langgraph_recipe.py scripts/test_langgraph_recipe_st3.py
+
+  recipe-temporal:
+    name: recipe (temporal)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Install recipe dependencies
+        run: python -m pip install --upgrade pip pyyaml pytest jsonschema temporalio
+      - name: Temporal recipe end-to-end
+        # start_local() downloads the Temporal dev-server binary (~20MB) to
+        # $TMPDIR/temporal-sdk-python-<version> — ephemeral and quick, so (like
+        # recipe-langgraph) this job carries no cache step.
+        run: python -B -m pytest -q -p no:cacheprovider scripts/test_temporal_recipe.py
+
+  anchor-live:
+    name: chain anchor (live end-to-end)
+    runs-on: ubuntu-latest
+    # action-dogfood gates a store-free example, so the anchor surface — the
+    # --expect-chain-head gate and the action's chain-head output — has no live
+    # cover there. This job seeds a chained store and pins both verdicts.
+    env:
+      WRONG_HEAD: "0000000000000000000000000000000000000000000000000000000000000000"
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install probe dependencies
+        # jsonschema so the probe's own doctor gate is as strict as the action's.
+        run: python -m pip install --upgrade pip pyyaml jsonschema
+
+      - name: Seed a chained workspace
+        id: seed
+        run: |
+          workspace="${RUNNER_TEMP}/anchor-ws"
+          head="$(python -B scripts/ci_anchor_probe.py "$workspace")"
+          echo "head=$head" >> "$GITHUB_OUTPUT"
+          echo "workspace=$workspace" >> "$GITHUB_OUTPUT"
+
+      - name: doctor accepts the seeded anchor
+        env:
+          ANCHOR_WS: ${{ steps.seed.outputs.workspace }}
+          ANCHOR_HEAD: ${{ steps.seed.outputs.head }}
+        run: python -B -m loop doctor --expect-chain-head "$ANCHOR_HEAD" "$ANCHOR_WS"
+
+      - name: doctor rejects a wrong anchor
+        env:
+          ANCHOR_WS: ${{ steps.seed.outputs.workspace }}
+        run: |
+          # Inverted so an unexpected PASS fails the job. 1 is doctor's
+          # report-not-ok code; 2 means the flag itself was refused, which would
+          # prove nothing about the anchor comparison — so pin 1 exactly.
+          set +e
+          out="$(python -B -m loop doctor --expect-chain-head "$WRONG_HEAD" "$ANCHOR_WS" 2>&1)"
+          status=$?
+          set -e
+          if [ "$status" -ne 1 ]; then
+            echo "::error::doctor exited $status on a wrong anchor; expected 1"
+            echo "$out"
+            exit 1
+          fi
+          case "$out" in
+            *chain_anchor_mismatch*) ;;
+            *) echo "::error::doctor did not report chain_anchor_mismatch"; echo "$out"; exit 1 ;;
+          esac
+
+      - name: Action gate with the seeded anchor
+        id: gate
+        uses: ./
+        with:
+          path: ${{ steps.seed.outputs.workspace }}
+          expect-chain-head: ${{ steps.seed.outputs.head }}
+          # 0 keeps inspect warn-only: the scaffold's advisory score must never
+          # be able to flake the anchor verdict this job exists to pin.
+          fail-under-score: "0"
+
+      - name: Action emitted the seeded head
+        env:
+          GATE_HEAD: ${{ steps.gate.outputs.chain-head }}
+          SEED_HEAD: ${{ steps.seed.outputs.head }}
+        run: |
+          if [ "$GATE_HEAD" != "$SEED_HEAD" ]; then
+            echo "::error::action chain-head output '$GATE_HEAD' != seeded head '$SEED_HEAD'"
+            exit 1
+          fi
+
+      - name: Action gate with a wrong anchor
+        id: gate-mismatch
+        continue-on-error: true
+        uses: ./
+        with:
+          path: ${{ steps.seed.outputs.workspace }}
+          expect-chain-head: ${{ env.WRONG_HEAD }}
+          fail-under-score: "0"
+
+      - name: Wrong anchor failed the gate and still recorded the head
+        env:
+          GATE_OUTCOME: ${{ steps.gate-mismatch.outcome }}
+          GATE_HEAD: ${{ steps.gate-mismatch.outputs.chain-head }}
+          SEED_HEAD: ${{ steps.seed.outputs.head }}
+        run: |
+          if [ "$GATE_OUTCOME" != "failure" ]; then
+            echo "::error::a wrong anchor did not fail the action (outcome: $GATE_OUTCOME)"
+            exit 1
+          fi
+          if [ "$GATE_HEAD" != "$SEED_HEAD" ]; then
+            echo "::error::the always-run anchor step recorded '$GATE_HEAD', not the observed head"
+            exit 1
+          fi
+  recipe-openhands:
+    name: recipe (openhands)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          # openhands-sdk requires >=3.12; the certifier itself is stdlib-only, so
+          # its behavioural e2e already runs on the whole gates matrix.
+          python-version: "3.12"
+      - name: Install recipe dependencies
+        run: python -m pip install --upgrade pip pyyaml pytest jsonschema openhands-sdk==1.37.1 openhands-tools==1.37.1
+      - name: OpenHands schema-drift alarm
+        run: python -B -m pytest -q -p no:cacheprovider scripts/test_openhands_sdk_drift.py scripts/test_openhands_recipe.py
+
+  action-dogfood:
+    name: action (dogfood on flagship example)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # The repo root's live .loop/ is gitignored, so it does not exist in a fresh
+      # CI checkout — the tracked flagship example is the contract the action gates
+      # (doctor-clean, inspect 90/strong in the action's dependency-free install).
+      - uses: ./
+        with:
+          path: "examples/coverage-repair"
+          fail-under-score: "90"
+
+      - name: pre-commit consumer fixture
+        # bare `python` is on PATH here because the preceding `uses: ./` composite step ran setup-python
+        # (persisted via GITHUB_PATH) — keep the action step before this one.
+        run: |
+          python -m pip install --quiet pre-commit pytest pyyaml
+          python -B -m pytest -q -p no:cacheprovider scripts/test_precommit_hook.py
+
+  recipe-ruflo:
+    name: recipe (ruflo)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install recipe dependencies
+        # No npm, no Node, no credentials: ruflo has no Python package, and a live
+        # swarm needs the `claude` binary plus model spend. The example replays the
+        # committed examples/ruflo-gate/fixture/ recording instead — the gate,
+        # projection, emit, doctor and metrics path all still execute for real.
+        # The opt-in live schema-drift alarm (LOOP_RUFLO_LIVE=1) stays skipped here.
+        run: python -m pip install --upgrade pip pyyaml pytest jsonschema
+      - name: ruflo recipe end-to-end
+        run: python -B -m pytest -q -p no:cacheprovider scripts/test_ruflo_recipe.py

{loop_engineer-0.10.0 → loop_engineer-0.11.0}/.github/workflows/publish.yml

@@ -13,7 +13,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 

{loop_engineer-0.10.0 → loop_engineer-0.11.0}/CHANGELOG.md

@@ -14,6 +14,53 @@ All notable changes to `loop-engineer` are documented here.
   `WORKFLOW.md` and `README.md` are reworded to describe the mechanism; the 0.3.4
   history is left intact.
 
+## 0.11.0 — 2026-07-26
+
+**Verifier identity, and evidence that is load-bearing.** Two slices of the
+tamper-evident-provenance program ship together, because neither was cut on its own.
+
+*Verifier identity and independence (PR #94).* evidence@1 records now carry
+`verified_by.code_digest` and `verified_by.policy_digest` — the runner hashes the
+verifier it actually executed and the goalpost it was held to. `loop doctor`
+reports `self_verified_evidence` when a record declares that its producer also
+verified it, making the independence rule of `reference/safety-and-approvals.md` §5
+a machine check rather than prose. Verify bundles record the visible/held-out
+criterion partition.
+
+*Evidence wiring (PR #102).* A verified dispatch binds its evidence digests into
+the hash chain at append time, using the existing `artifact_hashes` envelope field
+— no new event type and still one append per dispatch. The bundle is also written
+to a content-addressed object store whose location is derived from the digest, so
+a third-party reader finds the original bytes from `record["sha256"]` alone and a
+swapped bundle no longer destroys the evidence. `loop doctor` hash-verifies every
+discovered record, re-hashes what the chain bound, and compares a record's
+`policy_digest` against the live `TASKS.json` goalpost. Five new issue codes:
+`evidence_chain_mismatch`, `missing_bound_evidence`, `policy_digest_mismatch`,
+`unverified_evidence_terminal`, `bound_evidence_escape`.
+
+**Behavioural flag — `Succeeded` can now mean more.** The opt-in
+`completion_policy.mode: all_required_verified_evidence` requires every cited
+evidence entry to be a workspace-relative record that hash-verifies, **attests a
+pass**, is chain-bound wherever a store exists, and agrees with the live goalpost.
+The default `all_required` is unchanged and every record written before this
+release still validates. The canonical green-marker rule now lives in
+`loop.evidence.verify_bundle_is_green` and is shared object-for-object with
+`scripts/metrics.py`, so a bundle cannot read RED to the FCR gate and GREEN to the
+completion gate.
+
+**Known limitations, stated rather than discovered.** Binding makes tampering
+detectable against an anchor, not impossible: without `--expect-chain-head` a
+worker who can rewrite `.loop/` can rewrite the chain too, and a contract with no
+event store cannot chain-bind at all. Deleting `.loop/events.db` after a run leaves
+plain `loop doctor` quiet — the `missing_event_store` tripwire only fires on
+leftover `-wal`/`-shm` residue — so the external anchor is the control that holds.
+Four upgrade notes in `reference/repo-os-contract.md` §17 name the behaviour that
+can turn a previously-clean contract red: `policy_digest_mismatch` is not opt-in
+and has no first-class re-baseline affordance; the `completion_policy` enum
+widening is forward-incompatible as a hard error against an older kernel; `os.link`
+now runs once per dispatch; and a bound artifact above the 64 MiB read cap fails
+doctor with no configuration knob.
+
 ## 0.10.0 — 2026-07-25
 
 **The hash-linked event chain.** Every `loop-engineer/event@1` row now carries

{loop_engineer-0.10.0 → loop_engineer-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-engineer
-Version: 0.10.0
+Version: 0.11.0
 Summary: Portable Loop Contract Core: validate and inspect repo-native operating contracts for agent loops.
 Project-URL: Homepage, https://github.com/SollanSystems/loop-engineer
 Project-URL: Repository, https://github.com/SollanSystems/loop-engineer
@@ -44,7 +44,7 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml)
 [![Python 3.10–3.12](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Release](https://img.shields.io/badge/release-0.10.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
+[![Release](https://img.shields.io/badge/release-0.11.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
 
 Long-running agents commit **false completion**. After context compaction they
 forget what "done" meant, optimize to the visible test, patch in circles, and
@@ -67,7 +67,15 @@ ships, on disk and runnable today:
   hash-chained; `loop doctor --expect-chain-head` verifies the log against an
   externally anchored head. The chain is tamper-evident **relative to an
   anchor** — an adversary with workspace write access can rewrite an unanchored
-  log.
+  log. Verify runs record which verifier actually ran — command, code digest
+  (recorded only when the verifier is a workspace file, an honest null with a
+  named reason otherwise — e.g. `python3 -m pytest`), policy digest — and
+  `loop doctor` fails when a record declares that its own
+  producer verified it; identity is recorded, not proven: a worker can write a
+  false verifier name. A verified dispatch **binds its evidence digests into the
+  hash chain**, and `loop doctor` re-hashes them — binding makes tampering
+  detectable against an anchor, not impossible: without `--expect-chain-head` a
+  worker who can rewrite `.loop/` can rewrite the chain too.
 
 ![The inspector scores a self-asserted DIY loop 0/weak, then the gate-backed example 90/strong — both runs live](docs/demo.gif)
 
@@ -371,7 +379,7 @@ present. Recipe:
 **CI** — one workflow step validates the contract and publishes a scorecard:
 
 ```yaml
-- uses: SollanSystems/loop-engineer@v0.10.0
+- uses: SollanSystems/loop-engineer@v0.11.0
   with:
     path: "."
 ```
@@ -464,8 +472,8 @@ doctor` and the contract's own `verify-*` scripts).
 
 ## Status
 
-- Version: `0.10.0`
-- Release tag: `v0.10.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
+- Version: `0.11.0`
+- Release tag: `v0.11.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
 - License: MIT
 - Primary interface: Claude Code plugin
 - Portable core: Python CLI + JSON schemas

{loop_engineer-0.10.0 → loop_engineer-0.11.0}/README.md

@@ -5,7 +5,7 @@
 [![CI](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml)
 [![Python 3.10–3.12](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Release](https://img.shields.io/badge/release-0.10.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
+[![Release](https://img.shields.io/badge/release-0.11.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
 
 Long-running agents commit **false completion**. After context compaction they
 forget what "done" meant, optimize to the visible test, patch in circles, and
@@ -28,7 +28,15 @@ ships, on disk and runnable today:
   hash-chained; `loop doctor --expect-chain-head` verifies the log against an
   externally anchored head. The chain is tamper-evident **relative to an
   anchor** — an adversary with workspace write access can rewrite an unanchored
-  log.
+  log. Verify runs record which verifier actually ran — command, code digest
+  (recorded only when the verifier is a workspace file, an honest null with a
+  named reason otherwise — e.g. `python3 -m pytest`), policy digest — and
+  `loop doctor` fails when a record declares that its own
+  producer verified it; identity is recorded, not proven: a worker can write a
+  false verifier name. A verified dispatch **binds its evidence digests into the
+  hash chain**, and `loop doctor` re-hashes them — binding makes tampering
+  detectable against an anchor, not impossible: without `--expect-chain-head` a
+  worker who can rewrite `.loop/` can rewrite the chain too.
 
 ![The inspector scores a self-asserted DIY loop 0/weak, then the gate-backed example 90/strong — both runs live](docs/demo.gif)
 
@@ -332,7 +340,7 @@ present. Recipe:
 **CI** — one workflow step validates the contract and publishes a scorecard:
 
 ```yaml
-- uses: SollanSystems/loop-engineer@v0.10.0
+- uses: SollanSystems/loop-engineer@v0.11.0
   with:
     path: "."
 ```
@@ -425,8 +433,8 @@ doctor` and the contract's own `verify-*` scripts).
 
 ## Status
 
-- Version: `0.10.0`
-- Release tag: `v0.10.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
+- Version: `0.11.0`
+- Release tag: `v0.11.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
 - License: MIT
 - Primary interface: Claude Code plugin
 - Portable core: Python CLI + JSON schemas

{loop_engineer-0.10.0 → loop_engineer-0.11.0}/action.yml

@@ -41,7 +41,7 @@ outputs:
 runs:
   using: "composite"
   steps:
-    - uses: actions/setup-python@v6
+    - uses: actions/setup-python@v7
       with:
         python-version: ${{ inputs.python-version }}
 

{loop_engineer-0.10.0 → loop_engineer-0.11.0}/docs/gap-reports/scoreboard.md

@@ -57,7 +57,16 @@ for exactly the machinery our signals miss.
 Harnesses whose run state lives fundamentally off-repo (OpenHands and
 SWE-agent trajectories, platform-hosted runs) are out of scope: there is no
 on-disk run record for a repo-native inspector to read — which is its own
-answer to the question this scoreboard asks.
+answer to the question this scoreboard asks.†
+
+> † **Correction (2026-07-25).** For OpenHands this is now only half true. The
+> V1 SDK (`openhands-sdk` 1.37.1) persists `base_state.json` + an `events/`
+> trajectory whenever `persistence_dir=` is set — enough for an external
+> certifier to read a run's terminal signal, its iteration cap, and its full
+> event log. It is still not a *repo-native* contract (the record lives outside
+> the repo by default and carries no spec, plan, or ledger), so the row stays
+> out of the scoreboard; but the gap is addressable from outside, which is what
+> [`examples/openhands-certify/`](../../examples/openhands-certify/) does.
 
 ## The scoreboard
 
@@ -283,8 +292,10 @@ FCR/RP — is a missing **layer**, one every harness on this board could emit
 at its finish line. The port is small: four `loop.emit` calls
 (`open_contract`, `append_iteration`, `append_receipt`, `terminate`), worked
 end-to-end for a real engine in
-[`docs/integrations/langgraph.md`](../integrations/langgraph.md) and
-[`docs/integrations/temporal.md`](../integrations/temporal.md).
+[`docs/integrations/langgraph.md`](../integrations/langgraph.md),
+[`docs/integrations/temporal.md`](../integrations/temporal.md), and — for a
+harness with no seam to hook at all —
+[`docs/integrations/openhands.md`](../integrations/openhands.md).
 
 ## Contribute a row
 

loop_engineer-0.11.0/docs/integrations/openhands.md

@@ -0,0 +1,118 @@
+# OpenHands — certify the run after it ends
+
+OpenHands owns the EXECUTE tier: the autonomous coding runtime that plans, edits,
+runs commands, and decides for itself when it is done. What it cannot do is
+independently check *its own* completion claim — the agent both does the work and
+declares `FINISHED`. Loop Engineer adds the tier *above* it: a contract-and-proof
+layer that turns "the conversation finished" into evidence-backed proof-of-done.
+It never replaces OpenHands; it certifies what OpenHands ran.
+
+## The pattern
+
+Unlike LangGraph (`END` edge) or Temporal (certify activity), OpenHands has **no
+seam to insert a certify node into** — the run ends when the agent sets its own
+execution status. So the recipe is a **post-run certifier** over the record the SDK
+already persisted:
+
+```
+<persistence_dir>/<conversation-id-hex>/base_state.json     # execution_status, max_iterations, stats
+<persistence_dir>/<conversation-id-hex>/events/event-00000-<uuid>.json   ← the trajectory
+                                        events/event-00001-<uuid>.json
+```
+
+The conversation id segment is the UUID **hex** (32 chars, no hyphens); a
+conversation only persists when you pass `persistence_dir=`. The certifier takes a
+conversation dir directly, so that composition rule is documentation, not code.
+
+```python
+from loop import emit
+from loop.integrations import EngineOutcome, to_terminal_state
+
+state = json.loads((conv_dir / "base_state.json").read_text(encoding="utf-8"))
+events = sorted((conv_dir / "events").glob("event-*.json"), key=event_index)
+
+gate = holdout_gate.decide(visible, withheld)          # visible green + withheld green?
+ac = anticheat_scan.scan(diff_text=git_diff, trajectory=[str(p) for p in events])
+terminal = to_terminal_state(
+    outcome=to_engine_outcome(state, events, artifacts=[...]),
+    gate_verdict=gate, anticheat=ac,
+    criteria_met={"1": gate["verdict"] == "Succeeded"},
+)
+emit.terminate(ws, state=terminal["state"], criteria_met=terminal["criteria_met"],
+               evidence=terminal["evidence"], false_completion=terminal["false_completion"],
+               reason=terminal["reason"], iteration_id=1)
+```
+
+The certifier **imports no `openhands` package** — the record is plain JSON, so it
+runs on Python 3.10 even though the SDK requires 3.12, and the gate needs no LLM
+key. The event log doubles as the trajectory fed to `anticheat_scan.scan`: the
+"the runtime ran the tests but the agent read the answer key" case OpenHands
+cannot catch about itself, because the answer key is not part of its contract.
+
+## OpenHands signal → typed terminal state
+
+| `base_state.json` signal | `EngineOutcome` field | Typed terminal state |
+|---|---|---|
+| `execution_status: "finished"`, gate green + anticheat clean | `reached_end=True` | `Succeeded` |
+| `execution_status: "finished"`, visible green / withheld red | `reached_end=True` | `FailedUnverifiable` (`false_completion: true`) |
+| `execution_status: "stuck"` (stuck detector) | `budget_exhausted=True` | `FailedBudget` |
+| `execution_status: "error"` + `ConversationErrorEvent.code == "MaxIterationsReached"` | `budget_exhausted=True` | `FailedBudget` |
+| `execution_status: "error"`, any other code | `external_error="<code>: <detail>"` | `FailedBlocked` |
+| `execution_status: "paused"` (`conversation.pause()`) | `human_abort=True` | `AbortedByHuman` |
+| `idle` / `running` / `waiting_for_confirmation` (read mid-flight or abandoned) | `reached_end=False` | `FailedUnverifiable` |
+| trajectory touched an answer-key path (anticheat HIGH) | — | `FailedUnverifiable` |
+| the diff edits a gate script (anticheat CRITICAL) | — | `FailedSafety` |
+
+**The precedence trap.** A max-iteration stop arrives *as*
+`execution_status == "error"` with a `ConversationErrorEvent` whose `code` is
+`MaxIterationsReached`. Since `to_terminal_state` ranks blocked above budget,
+setting **both** `external_error` and `budget_exhausted` reports `FailedBlocked`
+and silently loses the budget signal. Inspect the error code first and set
+**exactly one**. `code` is a free-form `str`, so anything unrecognized falls
+through to `FailedBlocked` — which fails safe: an unclassified error can never
+become `Succeeded`.
+
+## Zero-install mode
+
+The `loop.integrations` module is convenience, not a requirement — the whole
+projection is the SAME ~15 lines the LangGraph and Temporal recipes paste
+(the adapter is engine-neutral):
+
+```python
+def to_terminal(gate, anticheat, criteria_met, evidence,
+                *, human_abort=False, blocked=None, over_budget=False):
+    fc = gate.get("false_completion") is True
+    if anticheat.get("downgrade_to") == "FailedSafety": state = "FailedSafety"
+    elif human_abort: state = "AbortedByHuman"
+    elif blocked: state = "FailedBlocked"
+    elif over_budget: state = "FailedBudget"
+    elif any(v is None for v in criteria_met.values()): state = "FailedSpecGap"
+    elif (not gate or not anticheat or anticheat.get("downgrade_to")
+          or gate.get("verdict") != "Succeeded" or fc
+          or not any(criteria_met.values()) or not evidence): state = "FailedUnverifiable"
+    else: state = "Succeeded"
+    return {"schema": "loop-engineer/terminal@1", "state": state,
+            "criteria_met": {k: v is True for k, v in criteria_met.items()},
+            "evidence": list(evidence), "false_completion": fc}
+```
+
+## Gate it in CI
+
+```yaml
+- run: pip install loop-engineer
+- run: python certify_run.py run/ --conversation "$CONV_DIR" --agent-workspace "$WS"
+- run: loop doctor run/          # -> {"ok": true}: the contract is structurally honest
+- run: loop metrics run/         # -> false_completion_rate + evidence-backed scorecard
+```
+
+`loop metrics` scores the run from its on-disk evidence — not the agent's narration.
+
+Verified against `openhands-sdk` 1.37.1 (2026-07-25), MIT
+([`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk),
+"Copyright (c) 2026 OpenHands contributors" — PyPI carries no license metadata).
+The persistence layout, the `ConversationExecutionStatus` members, and the
+`MaxIterationsReached` literal are pinned live by
+[`scripts/test_openhands_sdk_drift.py`](../../scripts/test_openhands_sdk_drift.py).
+
+Full runnable example (six committed fixture conversations + the false-completion
+demo): [`examples/openhands-certify/`](../../examples/openhands-certify/).