Loading article…

Loading 4weird…

DocsHeal loops

Docs · desktop · opencode

Heal until clean, or until budget.

Heal loops bugtest → fix → re-test until the suite is clean or a budget trips — iteration count, token cap, or spend cap, whichever hits first. Coin quotes follow the house rule (100 coins = $1, 75/25 split); MCP-mediated payment is a queued future where only stubs exist today.

loop: test → fix → re-test
100 🪙: = $1.00 always
75 / 25: provider / platform
MCP pay: queued future

The loop

Bugtest → fix → retest

Export writes the BUGFIX-<game>-<stamp>.md/json report; Fix hands it to OpenCode so it edits code itself and shows the diff; Heal repeats test → fix → re-test until clean or the iteration budget is spent. Swarm agents reach the same loop via the opencode.export / opencode.heal tools.

Bugtest
Run the game tools / test suite and collect failures into a BUGFIX report. A stubbed run that fails twice then passes must heal and stop.
Fix
Hand the report to OpenCode (opencode run -f file, the desktop Fix button, or the opencode.heal tool) so it edits code and shows the git diff.
Retest
Re-run the same suite. Clean → done with a verdict. Still failing → next round, until the loop terminates on clean, on max rounds, or on budget.
Always-fail stops on budget
A stubbed always-fail run must stop on the token/spend budget with a verdict — never spin forever. The loop always terminates.

Budgets

Token budgets beat iteration counts

Iteration caps alone cannot price a loop — one round can burn far more tokens than the next. The heal budget tracks input/output tokens, prices them, and stops on max tokens or max spend (USD), with per-iteration ledger lines. Integer-token accounting, fail-open clamps, never exceeds budget.

maxTokens

Hard cap on input + output tokens across all rounds. Trips before max iterations in a heavy run.

maxSpendUSD

Hard cap on priced spend. A run with maxSpendUSD set tiny stops on spend, not on round count.

Per-iteration ledger

Every round logs its token usage so the stop reason is auditable after the verdict.

Coin quotes

Every quote splits 75/25

Heal-loop cost estimates are read-only quotes in integer coins: 100 coins = $1.00, provider keeps 75% as on-site credits, platform keeps 25% for infrastructure. Quotes never write to any ledger — settlement stays a later lane.

75% provider credits

25% platform

Example: a 400-coin ($4.00) job → 300 coins provider credits, 100 coins platform. You only ever see the gross 400. All credits are on-site only (cloud compute, game credits, other on-site services); never cash-out, never withdrawable.

MCP pay

MCP-mediated payment is queued-future

Driving bugtest + fix remotely (terminal exec, heal start/status, opencode fix tools over MCP) and paying for it in coins is the queued future: where only stubs exist today, this page describes intent, not a live payment path. Nothing here debits a wallet.

Remote tools first
Terminal exec (allow-listed, token-authed), heal start/status, and opencode fix arrive as MCP tools before any money moves.
Quotes before charges
Every paid action gets a read-only coin quote first — same 100 = $1, same 75/25 split, same zero-write rule.
Settlement last, guarded
Actual ledger movement needs its own guarded lane (auth, rate limits, audit log). Until that ships, MCP pay stays described, not billed.

Worked example

A three round heal with real numbers

Follow one stubbed suite through the loop: it fails twice on the same assertion, then passes. Every round logs tokens so the stop reason is auditable.

Round 1: bugtest fails, fix lands
The suite reports 2 failures in 40 tests. OpenCode edits the collision handler and the ledger logs 18,400 input tokens plus 3,100 output tokens for the round.
Round 2: retest fails, fix narrows
One failure remains. The second fix touches a single branch and logs 12,050 input tokens plus 1,800 output tokens. Running total: about 35,350 tokens.
Round 3: retest clean, verdict done
All 40 tests pass. The loop stops on clean with a verdict summarizing rounds, totals, and the diff. No budget tripped, so nothing was cut short.
Contrast: always-fail stops on budget
Swap in a suite that can never pass and set maxSpendUSD tiny. The loop now stops on spend after a few rounds with a budget verdict, never spinning forever.

Stop reasons

Every loop ends one of four ways

The verdict names exactly one stop reason. Learn the four so a Heal result never surprises you.

Stop reason	What it means	What to do next
Clean	Suite passed fully on a retest round.	Review the diff, keep the fix, ship the game.
Max rounds	Iteration cap hit while failures remain.	Shrink the repro, raise the cap deliberately, re-heal.
Max tokens	Cumulative input plus output tokens hit maxTokens.	Trim context in the report or raise maxTokens, then resume.
Max spend	Priced spend hit maxSpendUSD first.	Check the per-iteration ledger, price the next attempt with a coin quote, re-run funded.

FAQ

Heal loop questions, answered

Pricing, quoting, and payment futures in one place. Start on the setup page if the binary itself is missing.

How do I price a loop before starting it?

Take the last similar verdict, sum its ledger tokens, price them at your provider rate, then convert dollars to coins at 100 to 1. That quote is read-only: it predicts, it never debits.

Why did my loop stop on round 2 with failures left?

A token or spend budget tripped before the round cap. Open the verdict ledger: the stop reason names the exact cap and the round totals that crossed it.

Can Heal pay the provider in coins today?

No. MCP-mediated coin payment is queued future with stubs only. Quotes today are estimates; any future settlement needs its own guarded lane with auth and audit.

Where does Export fit in?

Export writes the BUGFIX report that round 1 consumes. Revisit Desktop OpenCode setup for the report format and the cli versus server choice.

← Terminal

Web /terminal vs the desktop panel.

← Setup

CLI requirements and run vs serve modes.

Loading article…

DocsHeal loops

Docs · desktop · opencode

Heal until clean, or until budget.

loop: test → fix → re-test
100 🪙: = $1.00 always
75 / 25: provider / platform
MCP pay: queued future

The loop

Bugtest → fix → retest

Bugtest
Run the game tools / test suite and collect failures into a BUGFIX report. A stubbed run that fails twice then passes must heal and stop.
Fix
Hand the report to OpenCode (opencode run -f file, the desktop Fix button, or the opencode.heal tool) so it edits code and shows the git diff.
Retest
Re-run the same suite. Clean → done with a verdict. Still failing → next round, until the loop terminates on clean, on max rounds, or on budget.
Always-fail stops on budget
A stubbed always-fail run must stop on the token/spend budget with a verdict — never spin forever. The loop always terminates.

Budgets

Token budgets beat iteration counts

maxTokens

Hard cap on input + output tokens across all rounds. Trips before max iterations in a heavy run.

maxSpendUSD

Hard cap on priced spend. A run with maxSpendUSD set tiny stops on spend, not on round count.

Per-iteration ledger

Every round logs its token usage so the stop reason is auditable after the verdict.

Coin quotes

Every quote splits 75/25

75% provider credits

25% platform

MCP pay

MCP-mediated payment is queued-future

Remote tools first
Terminal exec (allow-listed, token-authed), heal start/status, and opencode fix arrive as MCP tools before any money moves.
Quotes before charges
Every paid action gets a read-only coin quote first — same 100 = $1, same 75/25 split, same zero-write rule.
Settlement last, guarded
Actual ledger movement needs its own guarded lane (auth, rate limits, audit log). Until that ships, MCP pay stays described, not billed.

Worked example

A three round heal with real numbers

Follow one stubbed suite through the loop: it fails twice on the same assertion, then passes. Every round logs tokens so the stop reason is auditable.

Round 1: bugtest fails, fix lands
The suite reports 2 failures in 40 tests. OpenCode edits the collision handler and the ledger logs 18,400 input tokens plus 3,100 output tokens for the round.
Round 2: retest fails, fix narrows
One failure remains. The second fix touches a single branch and logs 12,050 input tokens plus 1,800 output tokens. Running total: about 35,350 tokens.
Round 3: retest clean, verdict done
All 40 tests pass. The loop stops on clean with a verdict summarizing rounds, totals, and the diff. No budget tripped, so nothing was cut short.
Contrast: always-fail stops on budget
Swap in a suite that can never pass and set maxSpendUSD tiny. The loop now stops on spend after a few rounds with a budget verdict, never spinning forever.

Stop reasons

Every loop ends one of four ways

The verdict names exactly one stop reason. Learn the four so a Heal result never surprises you.

Stop reason	What it means	What to do next
Clean	Suite passed fully on a retest round.	Review the diff, keep the fix, ship the game.
Max rounds	Iteration cap hit while failures remain.	Shrink the repro, raise the cap deliberately, re-heal.
Max tokens	Cumulative input plus output tokens hit maxTokens.	Trim context in the report or raise maxTokens, then resume.
Max spend	Priced spend hit maxSpendUSD first.	Check the per-iteration ledger, price the next attempt with a coin quote, re-run funded.

FAQ

Heal loop questions, answered

Pricing, quoting, and payment futures in one place. Start on the setup page if the binary itself is missing.

How do I price a loop before starting it?

Take the last similar verdict, sum its ledger tokens, price them at your provider rate, then convert dollars to coins at 100 to 1. That quote is read-only: it predicts, it never debits.

Why did my loop stop on round 2 with failures left?

A token or spend budget tripped before the round cap. Open the verdict ledger: the stop reason names the exact cap and the round totals that crossed it.

Can Heal pay the provider in coins today?

No. MCP-mediated coin payment is queued future with stubs only. Quotes today are estimates; any future settlement needs its own guarded lane with auth and audit.

Where does Export fit in?

Export writes the BUGFIX report that round 1 consumes. Revisit Desktop OpenCode setup for the report format and the cli versus server choice.

← Terminal

Web /terminal vs the desktop panel.

← Setup

CLI requirements and run vs serve modes.

Heal until clean, or until budget.

Bugtest → fix → retest

Bugtest

Fix

Retest

Always-fail stops on budget

Token budgets beat iteration counts

Every quote splits 75/25

MCP-mediated payment is queued-future

Remote tools first

Quotes before charges

Settlement last, guarded

A three round heal with real numbers

Round 1: bugtest fails, fix lands

Round 2: retest fails, fix narrows

Round 3: retest clean, verdict done

Contrast: always-fail stops on budget

Every loop ends one of four ways

Heal loop questions, answered

Heal until clean, or until budget.

Bugtest → fix → retest

Bugtest

Fix

Retest

Always-fail stops on budget

Token budgets beat iteration counts

Every quote splits 75/25

MCP-mediated payment is queued-future

Remote tools first

Quotes before charges

Settlement last, guarded

A three round heal with real numbers

Round 1: bugtest fails, fix lands

Round 2: retest fails, fix narrows

Round 3: retest clean, verdict done

Contrast: always-fail stops on budget

Every loop ends one of four ways

Heal loop questions, answered