Agent-Legible Environments
What a cheap model needed to operate a stateful program it could not see inside
Table of Contents
1. Overview
This is a research project on debugging, context surfaces and LLMs: what an LLM agent needs in order to operate and debug a stateful program it can't see inside. The target is ordinary application debugging (a Rails request that 500s, a Django migration that half-applied, a Clojure system map with one component in the wrong state). The testbed is Umoria 5.7.15, a 1987 dungeon crawler: a stateful C program with source, a deterministic RNG, a curses UI that hides most of its state, and failures that are cheap to reproduce.
A cheap model (Claude Haiku) operated the program through a single shell tool. A second, stronger model acted as operator: it read process memory with lldb, changed the agent's prompt and environment between runs, and sent advice through a declared side channel during runs. Each change was registered as an experiment with a refutation condition before it ran.
The working claim:
A cheap agent operating a stateful program does best when the environment is made legible, not when the agent is made strong.
Five properties carried most of the effect:
- State the agent can read without guessing: emitted versus elicited versus declared (screen scraping, debugger reads, a schema'd event channel).
- Exact replay: a save tree that turns any logged state into a branch point.
- A coach channel with declared trust: advice the agent treats as advice, not as suspicious tool output.
- Navigation over capability: raising the agent's in-game power didn't move it past the stair-finding bottleneck; relocation and detection did.
- Failure labels and doctrine as data: every rule tied to the incident that bought it, in a shape a learner can consume.
None of the five is new on its own. The note sets each against the research that already owns it, then maps the set back onto application debugging. The evidence is one operator, one evening and small samples.
2. The testbed
Umoria runs natively in an 80x24 tmux pane under a debug build. The player is
a Haiku process whose only tool is bin/mctl, in a neutral directory, with its
prompt as the whole system prompt. mctl sends keys, returns the screen (or a
compact view about 65% smaller), and on request attaches lldb, reads the
player and dungeon structs, and detaches. A save, plus a seed, plus the key
log, replays exactly. A read-only tmux window ("moria-tv") lets a human watch.
An operator session (Claude Code) reads transcripts, writes memory between
runs through lldb, and queues one-shot notes for the player's next call.
The vocabulary is from Context Surfaces: a surface is emitted (it tells you) or elicited (you ask it). A shell is a hand: it reaches surfaces and is not one.
| party | sees | acts through |
|---|---|---|
| player (Haiku) | the screen each call; mctl state on request |
keys, via bin/mctl only |
| operator session | transcripts, intents, lldb reads, the source | whispers; lldb writes between runs |
| human watcher | moria-tv, read-only | chat to the operator |
| coach (Opus, after the run) | the transcript; in one arm, the source | a strategy brief for the next run |
Every experiment was registered in a CONJECTURE.md with its refutation
condition before the first key was sent. Most runs were 300 player calls with
a $1.50–$2 cap.
3. Five properties of a legible environment
3.1. Emitted, elicited, declared
The agent had three ways to know the game's state, and they fail differently.
The screen is emitted: it arrives with every keystroke. It is also a rendered subset of the state, chosen for a human. The clearest failure: Saint Thud, the synthetic warrior, fought about 430 calls with a Shovel in hand and his Holy Avenger in the pack. Nothing on the compact screen shows the wielded item. The operator found it by noticing STR read 18/83 instead of 18/100. The rule "wield the sword after digging" was in his prompt the whole time. The finding, as logged: the agent does not track state it cannot see, even with the rule in its prompt.
Debugger reads are elicited. mctl state returns HP, depth, gold, food and
flags as JSON from the process's own structs. They are exact, and they only
answer the question asked. The operator used lldb to settle what the screen
could not (what is wielded, real STR, carried weight); the player rarely
asked.
A declared event channel is the third option and the one the harness is
building next. Umoria's -more- prompt discards every key except Space, Esc
and Enter, so chained keys vanish and whatever follows the first Space runs as
commands. Monster sightings flush typed-ahead input. Item letters shift after
every drop. The agent sends keys into a UI whose blocking states it cannot
see. Experiment 025 patches the game to write one JSON line per blocking state
and per turn to fd 3, under a versioned observation schema. The NetHack
Learning Environment (Küttler et al. 2020) took the same step: its misc
observation is three booleans that declare the game's blocking states. On
NetHack, a harness-side --More-- guard already took swallowed-key complaints
from 4–5 per run to 0.
Forty years of game bots split on this same question. Rog-O-Matic
(Mauldin et al. 1983) scraped the terminal through a pseudo-terminal it
designed to be easy to tokenise, and synchronised on the cursor sitting on the
@. The Angband Borg (Angband developers, n.d.) moved inside the binary, read the
terminal buffer directly, and, per a comment in its source (borg-think.c),
used "cheat" reads of game structs for inventory because parsing those screens
caused "an insane amount of screen flashing". This harness sits in the odd middle: Rog-O-Matic's screen plus the
Borg's struct reads, from outside the process.
Software-engineering agents rediscovered the point as interface design.
SWE-agent (Yang et al. 2024) showed that the agent-computer interface
(a windowed file viewer, a linter-guarded edit command, concise feedback)
changes resolution rates with the model held fixed. Removing the linter guard on edits took its SWE-bench Lite score from 18.0%
to 15.0%; a 100-line file window beat both a 30-line window and the whole
file. debug-gym (Yuan et al. 2025) hands agents pdb as a tool, and
the result bears directly on a cheap player: on SWE-bench Lite, pdb raised
Claude 3.7 Sonnet from 37.2% to 48.4% (52.1% when unlocked after five
rewrites), while for GPT-4o-mini and GPT-4o pdb-from-the-start was slightly
worse than no debugger. The authors note it "could to some extent harm" weaker
models. A debugger is an elicited surface, and asking it good questions is a
skill the cheap model lacks. LDB
(Zhong, Wang, and Shang 2024) segments a program into basic blocks and shows the model
intermediate variable values at each, which is a debugger read packaged as
emitted context. ChatDBG (Levin et al. 2025) gives the model the
debugger's controls and lets it drive; on Python programs one query produced an
actionable fix 67% of the time, 85% with one follow-up. LLDB itself has shipped
a Model Context Protocol server since LLVM 21 (LLVM Project 2025), exposing
sessions and a single blocking command tool: the raw mctl state path, made
standard. Humans have the same preference the cheap model showed: in a study
of 458 developers' IDE sessions, Beller et al. (Beller et al. 2018)
found debuggers used less than expected and "printf debugging" still the
common choice. A print statement is an emitted surface the developer built on
purpose.
The app analogue is direct. Scraping a rendered HTML error page is the
screen. Attaching ruby/debug (ruby/debug contributors 2026), pdb (Python Software Foundation 2026),
or an nREPL (nREPL contributors 2026) session is the debugger read. Structured logs
(OpenTelemetry Authors 2026a), an OpenAPI description (Miller et al. 2021), and
traces under the OpenTelemetry GenAI conventions (OpenTelemetry Authors 2026b)
are the declared channel. The game says: build the declared channel first,
because the agent will not ask the debugger the question it does not know it
has.
3.2. Exact replay turns state into branch points
Experiment 013 established that the same save, seed and keys give the same future, and a different seed fans out. That made every save a node in a tree. Runs became bursts that end in a save; deaths are pruned; the tree is walked the way the dungeon is. It also made death cheap. Thunk's registered death policy was "retry from the node with the next seed", and the second attempt reused everything the first one learned.
Two lines of prior work own this idea. Go-Explore (Ecoffet et al. 2021)
archives states, returns to one exactly, then explores; exact return is what
prevents its named failure, derailment. Jericho
(Hausknecht et al. 2020) uses get_state / set_state as an oracle:
try candidate actions from a saved state and group them by the world diff they
cause, which yields the valid actions. That is restore used for knowledge, not
for checkpointing.
Debuggers own the other half. rr (O’Callahan et al. 2017) records a Linux
process once and replays it deterministically under gdb, forwards and
backwards; it runs one thread at a time to avoid nondeterministic races, and
the paper reports recording slowdown under a factor of two outside make.
Pernosco (Pernosco 2026) precomputes every program state in an rr recording
so that moving in time is instantaneous and a value can be traced back to its
source. gdb's own process record (Free Software Foundation 2026) and Undo's UDB
(Undo Ltd 2026) provide reverse execution; Replay.io (Replay.io 2026) records
browser sessions. The agent hook is already arriving: Undo ships undo mcp,
which lets an agent drive its engine over a recording; Replay.io documents an
MCP server for "agentic time travel debugging"; a community rr-mcp
(jnjaeschke 2026) wraps rr. All of them give an agent the property that mattered
most here: a state you can return to and ask a second question of.
For apps, the save tree is a recorded failing request. The agent's best move
on a flaky Django test is not a tenth speculative print; it is a recording
it can rewind to the line where the bad value first appeared, and a second
seed it can fan out from.
3.3. A coach channel with declared trust
The operator could queue a note with mctl whisper; it printed once on the
player's next call. By the end of the day 76 whispers had been sent. The
first 44 were measured: all delivered, median 1 s from queue to delivery.
Latency was never the problem. Five things were:
- Trust must be declared. A whisper sent to a run whose prompt did not name the channel was treated as suspicious tool output. Once the prompt declared a coach channel, notes were followed. This is prompt-injection hygiene seen from the friendly side: an agent that obeys any text in a tool result is the vulnerability, so the trusted path has to be named in advance.
- Notes about habits work; notes about a live fight arrive stale. "Finish the Lich" landed after Thunk had teleported away from a second lich; he started re-detecting it. Two such cases were logged.
- The coach can be wrong. One whisper got Word of Recall backwards and sent the warrior home with no way back.
- The coach can break the harness. A whisper appended to
mctl stateoutput made the runner's final-state JSON invalid; the save step was skipped and a level-11 character was lost. Notes now go to stderr. - Reviewers inherit the player's beliefs unless they get the oracle. A coach reading only the transcript repeated the player's claim that a rogue steals gold. Given read access to the source, the same coach did not, and every citation it made checked out.
The app analogue: a human or senior agent advising a cheap one needs a declared channel, notes that name the note they replace, and the same read access to ground truth the junior had. A post-incident reviewer with only the agent's transcript inherits the agent's errors.
3.5. Failure labels and doctrine as data
The player's prompt is doctrine: operator rules, each earned by a logged incident. The runbook's lessons log is in the operator's framing, "encountered a problem → died (or nearly) → made a note". The augmentation ledger is the same shape for outside help. These are human-labelled failures, which is the expensive part of most learning setups.
The spell-usage table from the Thunk runs shows why the labels have to be checked against behaviour. Parsed from seven runs' transcripts (attempts, so failures count):
| casts | spell | role |
|---|---|---|
| 100 | Detect Monsters | habit: every arrival, teleport, room |
| 39 | Identify | identify phase; many retries (~84% failure at clvl 12) |
| 37 | Magic Missile | first-cast experience, then cheap kills |
| 34 | Light Area | dark rooms |
| 31 | Teleport Self | escape; teleport-and-detect cycle |
| 19 | Frost Bolt | main attack after "spend mana, keep charges" |
| 16 | Find Hidden Traps/Doors | underused against the every-room rule |
| 14 | Fire Bolt | from clvl 15 |
| 10 | Stone to Mud | dead ends; a self-discovered firing slit |
| 9 | Create Food | from clvl 9 |
| 8 | Frost Ball | from clvl 19 |
| 3 | Phase Door | early only |
Eleven spells account for about 95% of casts. "Find traps in every room" was a rule given and mostly not followed (16 casts against Detect Monsters' 100). Detect-after-teleport was a habit formed with little prompting. Using Stone to Mud to cut a firing slit through a wall was in no rule at all. The habits are what to keep; the unfollowed rules are noise to drop before they become constraints for a learner.
That is the hand-over to reinforcement learning. Reflexion (Shinn et al. 2023) feeds verbal self-reflection into the next trial; the lessons log is that, except a lesson here can be tested by replaying from the pre-death node. NetHack is Hard to Hack (Piterbarg, Pinto, and Fergus 2023) instrumented AutoAscend to log which strategy it chose at each step and trained on those hierarchical labels; the player's one-line intent before each call is the narrated version. Options (Sutton, Precup, and Singh 1999) give the formal frame for the macro actions (fight, flee, detect, rest, dig, recall) the raw keys need relabelling into.
4. Comparison
All 42 cited works checked against primary sources (arXiv, proceedings, Crossref, official docs). Corrected from the draft: Hambro's gap is "nearly threefold" vs a hybrid neural winner; Undo and Replay.io now ship MCP servers; OTel GenAI conventions moved to the semantic-conventions-genai repo; Claude Plays Pokemon harness reduced to what anthropic.com states; BALROG 1.5% figure dropped as unchecked.
How each approach lets the agent see state, whether it can return to a state, how outside advice reaches it, and what evidence exists.
| approach | how the agent sees state | replay? | coaching / trust | evidence |
|---|---|---|---|---|
| Rog-O-Matic (1981–86) (Mauldin et al. 1983) | screen scrape via a custom pty; sync on cursor at @ |
no; a level-indexed game log | none; fixed expert priorities | best median score vs 15 CMU experts (1983) |
| Angband Borg (c. 1997) (Angband developers, n.d.) | in-process: terminal buffer plus struct "cheat" reads | no | none; halts on the bell with a key history | "won the game several times" (borg.txt, source tree) |
| NLE / MiniHack (Küttler et al. 2020; Samvelyan et al. 2021) | in-process arrays; misc declares blocking states |
via the game's own save; seeds | n/a (RL environment) | NetHack Challenge: best symbolic median nearly 3x the neural winner's (Hambro et al. 2022) |
| NetPlay (Jeurissen et al. 2024) | LLM text built from NLE; skills interrupted by events | no | none | best with detailed context; struggles with ambiguous tasks and menus |
| BALROG (Paglieri et al. 2025) | text and/or images | no | none | several models worse with images than with text |
| Jericho (Hausknecht et al. 2020) | text API, world-state hash | get_state / set_state, used as an oracle |
n/a | valid actions found by restore-and-diff |
| Go-Explore (Ecoffet et al. 2021) | emulator frames, downscaled cells | exact restore is the method | n/a | solved "all previously unsolved Atari games" |
| Voyager (Wang et al. 2024) | Mineflayer API, text | no; skill library of executable code persists | self-verification | 3.3x more unique items, milestones up to 15.3x faster (arXiv version) |
| Claude Plays Pokémon (Anthropic 2025) | "screen pixel input" plus function calls to press buttons and navigate | no | "basic memory" | 3.7 Sonnet beat three Gym Leaders; harness details beyond that are press-only |
| SWE-agent (Yang et al. 2024) | designed ACI: windowed viewer, linter-guarded edits | no | none | ablation: linter guard removed 18.0 → 15.0% on SWE-bench Lite |
| debug-gym (Yuan et al. 2025) | pdb as a tool, plus file view and rewrite |
no | none | pdb helps strong models (Sonnet 3.7: 37.2 → 48.4% SWE-bench Lite), not weak ones |
| LDB (Zhong, Wang, and Shang 2024) | intermediate values per basic block (emitted from a trace) | re-runs the tests | none | up to +9.8% on HumanEval, MBPP, TransCoder |
| ChatDBG (Levin et al. 2025) | LLM drives lldb/gdb/pdb on a live process | no | the user's question | 67% actionable fixes in one query on Python, 85% with one follow-up |
| Agentless (Xia et al. 2025) | fixed localize/repair/validate pipeline, no agent loop | no | none | 32.67% SWE-bench Lite at $0.68 per issue (FSE version) |
| rr / Pernosco (O’Callahan et al. 2017; Pernosco 2026) | full debugger on a recording | deterministic record/replay, reverse execution | n/a; Undo and Replay.io now ship MCP servers | rr: recording slowdown under 2x outside make |
| OTel GenAI tracing (OpenTelemetry Authors 2026b) | spans and attributes per model and tool call | no; post-hoc | n/a | a convention, status Development; execute_tool spans per tool call |
| this harness | screen (emitted), lldb JSON (elicited), fd-3 events (planned, declared) | save + seed + keys = same future | declared whisper channel; source-reading coach | 151 runs, 14,704 steps; see next section |
5. What was measured
Numbers copied from the operator's private harness records (approach summary, experiment write-ups, run diaries, spell-usage tally, whisper log). Not recomputed from raw runs. Token counts summed from per-call usage records.
All figures are from the harness's own records for 2026-10-16.
| measure | value |
|---|---|
| player runs | 151 |
| recorded key steps (screen after each) | 14,704 |
| coach whispers | 76 (first 44: all delivered, median 1 s) |
| save nodes | 55 |
| tokens | ≈ 1.66 billion, almost all cache reads: Haiku players ≈ 1.02 B (output 2.5 M), operator session ≈ 0.59 B (output 1.0 M), subagents ≈ 0.05 B |
| numbered experiments, each registered before running | 26 (001–026) |
Results by line:
| line | character | best result | how |
|---|---|---|---|
| honest (018) | Half-Troll Warrior | clvl 6, 458 gold, 150 ft | doctrine + burst tree; stairs were the wall |
| synthetic (020) | Saint Thud: Half-Troll, Holy Avenger, speed −3 | clvl 19, 1,850 ft | 12 augmentations, incl. a move to dungeon level 35 |
| synthetic mage (026) | Thunk: Halfling Mage, speed −3, three wands | clvl 23, 1,900 ft; killed a Mature Red Dragon | dropped at dungeon level 35 at clvl 1 |
| NetHack (022/024) | synthetic Valkyrie | Dlvl 13 alive / 12 dead; with a dive brake, 8 and 8 alive | own runner, --More-- guard |
Three numbers carry the argument.
Thunk reached clvl 11 from clvl 1 twice: 190 calls and $0.16 on the first attempt, 256 calls and $0.45 on the second. The registered hypothesis (026a) was supported in 2 of 2 attempts. One or two wand kills at depth did most of the levelling, because kill experience divides by character level; first-cast experience for each new spell did the rest.
Navigation, not power, moved the warrior. Holy Avenger plus speed: refuted at 200 ft. Add a teleport curse: 350 ft in the next 300 calls (n = 1 each).
The player is the cheap part. The Haiku players read about a billion tokens, nearly all of it cached screens and prompts, and wrote 2.5 million. The operator session, which watched, read lldb and whispered, read 0.59 billion on a far more expensive model. A legible environment is how that ratio comes down: every whisper that worked became a prompt line, and the planned harness work aims to turn the rest into code.
6. Back to Rails, Django and Clojure
| game | application |
|---|---|
| the curses screen | a rendered HTML page, a stack trace in a browser |
mctl state via lldb |
ruby/debug, binding.irb, pdb, an nREPL eval of the system map |
| fd-3 JSON events (025c) | structured logs, OpenTelemetry spans, an OpenAPI-described admin endpoint |
-more- swallowing keys |
an interactive prompt (a migration's y/n, a REPL's pending read) the agent cannot see |
| item letters shifting | positional references (row 3 of the table) instead of ids |
| save + seed + keys | rr / Replay.io recordings; a captured failing request plus fixture seed |
| the burst tree | bisecting from a known-good recording, not re-running from scratch |
| coach whispers | a reviewer's note on a declared channel, not text in a tool result |
| Door/Stair Location | a route table, call graph or code-graph index handed over first |
| the lessons log | a runbook where each rule names the incident that bought it |
Two cautions carry over intact. First, the debugger is elicited: the agent gets exactly the answer to the question it asked, and the Shovel episode shows it will not ask about state it cannot see. Pair every debugger tool with an emitted channel. Second, the screen is also the user's view. Do not remove it; an agent that only sees structured events will miss what a user sees.
Django Debug Toolbar (Django Debug Toolbar contributors 2026) is a small existence proof that apps already emit this kind of panel for humans. LangSmith, Langfuse and Arize Phoenix (LangChain 2026; Langfuse 2026; Arize AI 2026) trace the agent; the gap is the same trace for the program under test.
7. Limitations
- One operator, one day. Every whisper and augmentation came from the same person in the same session. The coach effect is not separable from that person.
- Small n. Most comparisons are one run per arm, on different seeds. 020d's curse result is a lead; the harness's own notebook calls it that. Thunk's 2 of 2 is two attempts.
- Synthetic characters. Saint Thud and Thunk carry forged items and were moved deep through lldb. Their results measure the prompt and the environment. Honest play is a separate line. The honest line topped out at 150 ft.
- A cheap model. Haiku throughout. A stronger player may need less legibility; the cost ratio suggests that is the expensive way to buy it.
- Confounds acknowledged in the records. 020d also tidied the pack and changed a whisper. A cost drop from $1.35 to $0.38 between runs 21 and 22 is unexplained (cache-read tokens fell from 29.4M to 17.9M) and is not attributed to the curse.
- Harness defects were part of the data. One run "died" because
bin/playwas edited while it ran; one level-11 character was lost to a whisper in the runner's JSON. Both are fixed. Neither is a property of the agent. - No application pilot yet. The mapping to Rails, Django and Clojure is argued here and untested.
- The harness and transcripts are not published. Readers can't audit them; treat the numbers as one operator's field notes.
8. Next steps
025: make the game automation-friendly. Four gated phases, each registered with a refutation condition:
| phase | change | gate |
|---|---|---|
| 025a | key guard: stop before any key that would land in a blocking prompt; screen-settled sync, not sleeps | a scripted probe set with no LLM; refuted if any key passes a block |
| 025b | named-item commands (mctl do wield Shovel) using the game's own "Try <item>?" confirmation |
drop five items by name after shuffling; refuted if a wrong item moves |
| 025c | game patch: one JSON line per blocking state and per turn on fd 3 | RNG-neutral: replay three recorded runs with and without it, compare the seed after every key |
| 025d | observation.v1 / action.v1 JSON Schemas; the player prompt generated from the action schema |
every observation in a 150-turn run validates |
RL hand-over. Materialise one row per step across all runs (observation, action, next observation, reward fields, run id, prompt version, whisper in effect). Relabel raw keys into about ten macro actions. Baselines: filtered behaviour cloning on the best trajectories (Pomerleau 1988; Ross, Gordon, and Bagnell 2011), then offline RL with IQL or CQL (Kostrikov, Nair, and Levine 2022; Kumar et al. 2020) on the macro actions (Levine et al. 2020). Use the save tree for counterfactual roll-outs from logged states, which pure offline RL cannot do.
Thunk2. A fresh clvl-1 drop with Thunk's own self-written doctrine and a stripped prompt, against the rule-heavy record. Each rule the stripped run rediscovers unprompted is a candidate feature; each it does not need is noise.
An application pilot. The same five properties on a small Rails or Clojure service with a seeded bug: the rendered page, a debugger or nREPL tool, a structured event channel, an rr or request-replay recording, and a declared reviewer channel, one added per arm.