Watchdog state inspect

.github/actions/install-cartesi-machine/action.yml

@@ -0,0 +1,51 @@
+name: "Install cartesi-machine"
+description: "Install the pinned machine-emulator .deb and export LIBCARTESI_PATH / INCLUDECARTESI_PATH for the Rust bindings."
+
+inputs:
+  version:
+    description: "cartesi-machine release tag"
+    required: true
+  sha256-amd64:
+    description: "SHA-256 for the amd64 .deb"
+    required: true
+  sha256-arm64:
+    description: "SHA-256 for the arm64 .deb"
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Install cartesi-machine
+      shell: bash
+      run: |
+        set -euo pipefail
+        ARCH="$(dpkg --print-architecture)"
+        VERSION="${{ inputs.version }}"
+
+        case "${ARCH}" in
+          amd64)
+            DEB_SHA256="${{ inputs.sha256-amd64 }}"
+            ;;
+          arm64)
+            DEB_SHA256="${{ inputs.sha256-arm64 }}"
+            ;;
+          *)
+            echo "unsupported arch for machine-emulator: ${ARCH}" >&2
+            exit 1
+            ;;
+        esac
+
+        wget -O /tmp/machine-emulator.deb "https://github.com/cartesi/machine-emulator/releases/download/${VERSION}/machine-emulator_${ARCH}.deb"
+        echo "${DEB_SHA256}  /tmp/machine-emulator.deb" | sha256sum --check
+        sudo apt-get install -y /tmp/machine-emulator.deb
+        rm -f /tmp/machine-emulator.deb
+        cartesi-machine --version
+
+        # testsi's cartesi-machine bindings (cartesi/dave) link this prebuilt
+        # emulator; they build only with LIBCARTESI_PATH set (external_cartesi).
+        # The static archive references libslirp, so callers must also install
+        # libslirp-dev.
+        test -f /usr/lib/libcartesi.a
+        test -f /usr/include/cartesi-machine/cm.h
+        echo "LIBCARTESI_PATH=/usr/lib" >> "${GITHUB_ENV}"
+        echo "INCLUDECARTESI_PATH=/usr/include/cartesi-machine" >> "${GITHUB_ENV}"

.github/actions/setup-guest-toolchain/action.yml

@@ -80,29 +80,11 @@ runs:
         sudo apt-get install -y /tmp/xgenext2fs.deb
 
     - name: Install cartesi-machine
-      shell: bash
-      run: |
-        set -euo pipefail
-        ARCH="$(dpkg --print-architecture)"
-        VERSION="${{ inputs.cartesi-machine-version }}"
-
-        case "${ARCH}" in
-          amd64)
-            DEB_SHA256="${{ inputs.cartesi-machine-sha256-amd64 }}"
-            ;;
-          arm64)
-            DEB_SHA256="${{ inputs.cartesi-machine-sha256-arm64 }}"
-            ;;
-          *)
-            echo "unsupported arch for machine-emulator: ${ARCH}" >&2
-            exit 1
-            ;;
-        esac
-
-        wget -O /tmp/machine-emulator.deb "https://github.com/cartesi/machine-emulator/releases/download/${VERSION}/machine-emulator_${ARCH}.deb"
-        echo "${DEB_SHA256}  /tmp/machine-emulator.deb" | sha256sum --check
-        sudo apt-get install -y /tmp/machine-emulator.deb
-        cartesi-machine --version
+      uses: ./.github/actions/install-cartesi-machine
+      with:
+        version: ${{ inputs.cartesi-machine-version }}
+        sha256-amd64: ${{ inputs.cartesi-machine-sha256-amd64 }}
+        sha256-arm64: ${{ inputs.cartesi-machine-sha256-arm64 }}
 
     - name: Set up QEMU
       uses: docker/setup-qemu-action@v4

.github/workflows/ci.yml

@@ -28,8 +28,20 @@ jobs:
             libfaketime \
             lua5.4 \
             liblua5.4-dev \
+            lua-check \
+            libcurl4-openssl-dev \
             libslirp-dev
 
+      # canonical-test links the emulator through testsi's cartesi-machine
+      # bindings, so the workspace build needs the pinned CM .deb and the
+      # LIBCARTESI_PATH / INCLUDECARTESI_PATH this action exports.
+      - name: Install cartesi-machine
+        uses: ./.github/actions/install-cartesi-machine
+        with:
+          version: ${{ env.CARTESI_MACHINE_VERSION }}
+          sha256-amd64: ${{ env.CARTESI_MACHINE_SHA256_AMD64 }}
+          sha256-arm64: ${{ env.CARTESI_MACHINE_SHA256_ARM64 }}
+
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -53,11 +65,13 @@ jobs:
       - name: Clippy
         run: cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
 
-      - name: Watchdog Lua tests
-        run: lua5.4 watchdog/tests/run.lua
+      - name: Watchdog Lua lint
+        run: cd watchdog && luacheck --no-color *.lua tests/*.lua
 
-      - name: Watchdog divergence drill
-        run: bash scripts/test-watchdog-divergence-drill.sh
+      - name: Watchdog Lua unit tests
+        run: |
+          bash scripts/watchdog-lua-deps.sh
+          lua5.4 watchdog/tests/run.lua
 
       - name: Test
         timeout-minutes: 15
@@ -132,9 +146,8 @@ jobs:
       - name: Run rollups E2E tests (Rust and C hosts)
         run: just test-rollups-e2e
 
-      # Runs after the e2e step so the canonical machine image is already built;
-      # exercises the in-process machine_cartesi binding incl. store -> reload -> advance,
-      # which the Rust harness never loads (its compare passes only load the genesis image).
+      # Runs after the e2e step so the canonical images already exist. Builds the
+      # watchdog test guest and checks the executor against the reference CLI.
       - name: Watchdog Lua CM e2e
         run: just test-watchdog-e2e
 

AGENTS.md

@@ -162,6 +162,7 @@ signing, and SSZ batch encoding.
 - `examples/canonical-app/` — on-chain scheduler reference implementation.
 - `examples/canonical-test/` — e2e test harness for the canonical app.
 - `sdk/rust-client/` — Rust client library for the sequencer API.
+- `sdk/guest/` — canonical-guest SDK: `trolley` (guest rollup API over `libcmt-sys`), `rollups-types` (rollups ABI encodings), and `testsi` (host-side guest image tests); provenance in its README.
 - `tests/{benchmarks,e2e,harness}/` — test infrastructure.
 
 ### Sequencer module layout
@@ -370,7 +371,9 @@ Prefer black-box tests around `POST /tx` and commit outcomes for integration.
 
 Some `sequencer` tests use Anvil (Foundry). They run by default and fail with a
 clear message if `anvil` is not on PATH. Use the configured Nix/direnv environment
-or install Foundry. `canonical-test` additionally needs libslirp.
+or install Foundry. `canonical-test` additionally needs the Cartesi Machine
+library named by `LIBCARTESI_PATH`/`INCLUDECARTESI_PATH` (the devshell exports
+both) and libslirp.
 
 ## Shell and Commands
 
@@ -453,5 +456,6 @@ work reaches another boundary.
 | Trust boundaries, provider behavior, or hostile L1 input | [Threat model](docs/threat-model/README.md) — actor assumptions, supported failures, and residual risks. |
 | Submission fees or oracle pricing | [L1 fee policy](docs/l1-fee-policy.md) — estimation and replacement limits; [threat-model actor table](docs/threat-model/README.md#actors-and-trust) — oracle source and outage assumptions. |
 | Command setup or deployment configuration | [Running](README.md#running) and [config.rs](sequencer/src/commands/config.rs) — invocation, identity pinning, defaults, and validation. |
-| Watchdog development or operation | [Architecture](docs/watchdog/README.md); [local dev](docs/watchdog/getting-started.md) for Anvil; [operator deployment](docs/watchdog/operator-deployment.md) for Sepolia/mainnet. |
+| Watchdog development or operation | [Watchdog README](docs/watchdog/README.md) — contract, state sources, commands, and state; [incident runbook](docs/watchdog/incident-runbook.md) — what a latched divergence requires; [local dev](docs/watchdog/getting-started.md) for Anvil; [operator deployment](docs/watchdog/operator-deployment.md) for Sepolia/mainnet. |
+| Canonical guest, machine images, or a Cartesi Machine bump | [Cartesi Machine facts](docs/cartesi-machine.md) — version pinning, host semantics, storage, memory ranges, and the guest side. |
 | A new mechanism, simplification, or work spanning an active track | Owning design and [invariants](docs/invariants.md) — reasons and assumptions; [review register](docs/review/register.md) — unresolved work; [coordination tracks](docs/plans/2026-07-coordination-tracks.md) — priorities and dependencies. Follow the [review lifecycle](docs/review/README.md) when recording conclusions. |