feat(cli): cli changes to align with rollups-node [upcoming changes]

[brunomenezes]

Summary

Aligns the CLI with rollups-node v2.0.0-alpha.13 (released 2026-10-02), which makes a guest exception or machine halt a terminal state: the node permanently stops processing inputs for that application, across restarts, while L1 indexing stays active — so cartesi send keeps succeeding and inputs pile up unprocessed.

cartesi run never re-read application status after deploying, so this was completely silent. That is the main thing fixed here.

Also folds in #520 (close it when this merges) and fixes four bugs found while verifying against the released node.

What changes

Terminal application states

• ApplicationStatus widened from 4 to the node's 9 states, adding GUEST_EXCEPTION, MACHINE_HALTED, MCYCLE_OVERFLOW, UNEXPECTED_YIELD and INVALID_OUTPUTS_ROOT, with the node's reason diagnostic now parsed — plus the first unit tests for exec/rollups.ts.
• cartesi run polls application status and warns the moment it leaves OK, reporting reason. cartesi status colours terminal states and prints the reason under the table.

Startup and health

• The wait for healthy services is bounded. The backoff had no maxTimeout, so a service that never started held the command for up to 19 hours. An exited container now fails fast instead of consuming the budget.

Node signer configuration

• alpha.13's standalone node always starts its PRT service, and with claim submission enabled by default that service needs its own signer — for which PRT has no default mnemonic, so the node refuses to start. The devnet mnemonic is now passed as CARTESI_PRT_AUTH_MNEMONIC unconditionally, not only under --prt.
• Both auth families are host-overridable and symmetric at six variables each (CARTESI_AUTH_* and CARTESI_PRT_AUTH_*). Adding CARTESI_AUTH_KIND matters: without it only plain-mnemonic signing was reachable for the Claimer, since the node picks its signing path from that kind alone.
• CARTESI_PRT_AUTH_AWS_KMS_KEY_ID is not in the list. alpha.13 moved KMS region, endpoint and credentials to AWS SDK variables, which are not CARTESI_-prefixed and so can never reach the node through this mechanism — the key id alone signs nothing.

Bugs found while verifying

• getMachineHash() passed no image, so it always read snapshots with the default SDK (emulator 0.20) and returned undefined for any app pinning a different sdk. cartesi hash reported "snapshot not found" and cartesi run skipped deploy() with no error.
• --claim-staging-period was dropped when deploying with --prt. It is a persistent flag on the node's whole deploy command, so a value passed alongside --prt was silently discarded.
• Contract codegen call sites from #520: renamed portal deposit functions, getInputBox removed in favour of probing version, and the new 6-argument calculateDaveAppAddress. cartesi deposit and fork validation were broken against contracts 3.0.0-alpha.10.
• CI installed Foundry v1.4.3 for a dependency apps/cli no longer has.

Verification

Against the released node, with the SDK image built from this branch:

CARTESI_TEST_SDK=cartesi/sdk:devel CARTESI_TEST_RUNTIME_VERSION=devel bun test apps/cli/

184 pass / 1 skip / 0 fail across 15 files. The skip is pre-existing (docker.test.ts sqfs drive). tsc reports no errors under src/; the 11 remaining are pre-existing in tests/unit/compose/builder.test.ts.

End to end on a local devnet: cartesi build → cartesi run → application OK → cartesi address-book printing all 17 contracts, every address holding code. With CARTESI_AUTH_KIND=private_key the node reports the Claimer signing from the given key while PRT stays on its own account, confirming the override reaches the node and the two signers differ as alpha.13 requires. Also verified on a Base Sepolia fork.

⚠️ Must land first

1. #497 Version Packages (alpha) — publishes cartesi/sdk:0.12.0-alpha.42. DEFAULT_SDK_VERSION is still 0.12.0-alpha.41, whose rollups-runtime is node alpha.12, so until that image ships everything above is inert at default settings. Nothing breaks if this merges first (alpha.12 ignores the unknown CARTESI_PRT_AUTH_* variables and accepts the same deploy flags), but the alignment does not take effect. When it ships, bump DEFAULT_SDK_VERSION in apps/cli/src/config.ts.
2. Drop the first commit — chore: temporary ci wiring for the pr-built sdk images is CI scaffolding pinned to pr-${{ github.event.number }}. It must not merge:
   It exists because the suite's default SDK image is older than the node this code targets, and it becomes unnecessary with step 1.

Notes for reviewers

• Closed #520 — its 8 commits are replayed here unchanged.
• The first CI run may go red: cli.yaml races sdk.yaml for ghcr.io/cartesi/sdk:pr-529. Re-run once the SDK build finishes.

[changeset-bot]

🦋 Changeset detected

Latest commit: b805479

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cartesi/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​cartesi/​wagmi-plugin@​1.0.0-alpha.7
	modern-tar@​0.7.7

View full report

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🟢	Lines	94.72% (🎯 0%)	10962 / 11573
🔵	Statements	94.72%	10962 / 11573
🔵	Functions	81.07%	167 / 206
🔵	Branches	0%	0 / 0

📁 File Coverage (20 files)

File	Lines	Statements	Functions	Branches	Uncovered Lines
apps/cli/src/base.ts	🔴 35.93%	🔴 35.93%	🟡 60%	🔴 0%	49, 70-71, 79-83, 88, 110-1...
apps/cli/src/builder/directory.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/docker.ts	🟢 86.72%	🟢 86.72%	🟡 66.67%	🔴 0%	75-77, 79, 109-111, 169-178
apps/cli/src/builder/empty.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/none.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/tar.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/compose/anvil.ts	🟡 79.25%	🟡 79.25%	🟢 100%	🔴 0%	19-29
apps/cli/src/compose/builder.ts	🟢 99.79%	🟢 99.79%	🟢 100%	🔴 0%	228
apps/cli/src/compose/bundler.ts	🔴 4.82%	🔴 4.82%	🔴 0%	🔴 0%	8-40, 44-75, 79-92
apps/cli/src/compose/common.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/compose/database.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/compose/explorer.ts	🔴 6.67%	🔴 6.67%	🔴 0%	🔴 0%	10-38, 43-55, 59-72
apps/cli/src/compose/node.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/compose/passkey.ts	🔴 8.33%	🔴 8.33%	🔴 0%	🔴 0%	9-18, 23-42, 46-59
apps/cli/src/compose/paymaster.ts	🔴 7.69%	🔴 7.69%	🔴 0%	🔴 0%	8-21, 25-44, 48-61
apps/cli/src/compose/proxy.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/config.ts	🟢 94.32%	🟢 94.32%	🟢 95.24%	🔴 0%	75-76, 251, 260, 269, 363, ...
apps/cli/src/contracts.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
...rc/errors/ForkChainValidationError.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
...c/errors/UnsupportedForkChainError.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-

[tuler]

I don't know if I like the state polling by cartesi run. I'm not convinced it's necessary.

[brunomenezes]

I don't know if I like the state polling by cartesi run. I'm not convinced it's necessary.

Iteration. If is not good we drop in the coming versions.