DEV Community: Taylor Lin

Retry, Repair, or Replay: A Failure-Triage Tree for Agent Steps

Taylor Lin — Tue, 27 Oct 2026 13:06:12 +0000

Step 6 of a 9-step agent job times out. The run is holding a checkpoint, an open HTTP call that may or may not have landed, and a retry counter that nobody wired up. The next decision is the expensive one — and most codebases make it with a bare except: retry().

That default is wrong in two directions at once. It hammers dead endpoints, and it re-fires steps that already wrote something into the world.

This post is a glossary, a decision tree, and four worked leaves, plus a dependency-free classifier you can run in under a second. The scenario above is illustrative, not a customer story; the code is the artifact you can actually check.

Terms worth pinning down first

Failure class. Whether the fault is in the transport (timeout, 429, 5xx, connection reset) or in the task (wrong output, wrong field, wrong decision). These need different budgets, not the same for loop.

Side-effect boundary. The first line in a step after which the outside world has changed: a row written, an email sent, a payment authorized. Everything before it is safe to throw away.

Checkpoint. A stable identifier for the last known-good state, granular enough that replay resumes at a step rather than at the job.

Retry. Same input, same prompt, same parameters. Cheap to reason about, only valid before the side-effect boundary.

Repair. Changed input: a narrowed instruction, an added schema, one failing example. Expensive in tokens, appropriate when the output parses but is wrong.

Replay. Re-run from a checkpoint behind an idempotency key, so a duplicate request returns the original result instead of creating a second one.

Poison step. A step whose failure fingerprint is unchanged after the repair budget is spent. Retrying it is a way to convert a bug into an outage.

Reconciliation. The out-of-band read that proves what actually happened downstream. Triage decides what to try; reconciliation decides what is true.

The three branches

Every recovery decision in an agent step reduces to three questions, asked in this order.

Is the fingerprint stable and non-transient after repair? If yes, stop. This is a poison step and no branch below improves it.
Are there side effects? If yes, the only safe action is replay from a checkpoint with an idempotency key — or abort if no checkpoint exists.
Is the transport healthy? Transient and under budget means retry. Transient and over budget means abort: a dead endpoint is not a prompt problem. Non-transient means repair, once or twice, then abort.

Order matters more than the rules themselves. Side effects must be checked before the retry branch, and poison must be checked before replay, or you will replay a step whose model output was garbage in the first place.

Decision table

transient	side effects	checkpoint	repair attempts	action
yes	no	—	0	retry (budget open)
yes	yes	`ckpt-17`	0	replay behind idempotency key
yes	yes	none	0	abort, reconcile by hand
no	no	—	1	repair once, record prompt hash
no	no	—	2	abort, quarantine
no	yes	`ckpt-17`	2	abort — poison beats replay

The classifier, runnable

Save as triage.py. Standard library only, CPython 3.10+ for the union syntax.

#!/usr/bin/env python3
"""triage.py - pick a recovery action for a failed agent step."""
from __future__ import annotations

from dataclasses import dataclass
from enum import Enum


class Action(str, Enum):
    RETRY = "retry"
    REPAIR = "repair"
    REPLAY = "replay"
    ABORT = "abort"


RETRY_BUDGET = 3
REPAIR_BUDGET = 2


@dataclass(frozen=True)
class Failure:
    step: str
    transient: bool = False        # timeout, 429, 5xx, reset
    schema_ok: bool = True         # did output match the contract?
    side_effects: bool = False     # did this attempt already write outside?
    checkpoint: str | None = None  # last known-good state id
    attempts: int = 1
    repair_attempts: int = 0
    signature: str = ""            # normalized error fingerprint


def triage(f: Failure) -> tuple[Action, str]:
    if not f.transient and f.repair_attempts >= REPAIR_BUDGET:
        return Action.ABORT, "poison step: fingerprint survived the repair budget"
    if f.side_effects:
        if f.checkpoint:
            return Action.REPLAY, f"re-run from {f.checkpoint!r} behind an idempotency key"
        return Action.ABORT, "side effects with no checkpoint: reconcile by hand"
    if f.transient and f.attempts < RETRY_BUDGET:
        return Action.RETRY, "transport fault, retry budget open"
    if f.transient:
        return Action.ABORT, "transport budget spent; a prompt edit will not fix a dead endpoint"
    if f.repair_attempts < REPAIR_BUDGET:
        return Action.REPAIR, "transport fine, output wrong: narrow the instruction once"
    return Action.ABORT, "no leaf matched: escalate with the trace"


CASES = [
    ("transient read", Failure("fetch", transient=True, attempts=1), Action.RETRY),
    ("transport exhausted", Failure("fetch", transient=True, attempts=3), Action.ABORT),
    ("write with checkpoint",
     Failure("charge", transient=True, side_effects=True, checkpoint="ckpt-17"), Action.REPLAY),
    ("write without checkpoint", Failure("charge", side_effects=True), Action.ABORT),
    ("contract violation", Failure("extract", schema_ok=False), Action.REPAIR),
    ("repair exhausted", Failure("extract", schema_ok=False, repair_attempts=2), Action.ABORT),
    ("poison beats replay",
     Failure("charge", side_effects=True, checkpoint="ckpt-17", repair_attempts=2), Action.ABORT),
]


def main() -> int:
    failures = 0
    for name, failure, want in CASES:
        got, why = triage(failure)
        ok = got is want
        failures += 0 if ok else 1
        print(f"{'ok  ' if ok else 'FAIL'} {name:<24} -> {got.value:<6} {why}")
    return 1 if failures else 0


if __name__ == "__main__":
    raise SystemExit(main())

Run python3 triage.py. Expected output, with the last line being the one that catches the classic mistake — replaying a step whose model never produced valid output:

ok   transient read           -> retry  transport fault, retry budget open
ok   transport exhausted      -> abort  transport budget spent; a prompt edit will not fix a dead endpoint
ok   write with checkpoint    -> replay re-run from 'ckpt-17' behind an idempotency key
ok   write without checkpoint -> abort  side effects with no checkpoint: reconcile by hand
ok   contract violation       -> repair transport fine, output wrong: narrow the instruction once
ok   repair exhausted         -> abort  poison step: fingerprint survived the repair budget
ok   poison beats replay      -> abort  poison step: fingerprint survived the repair budget

If a line differs, the test fails and the tree disagrees with the table above. Fix the tree, not the table.

Four leaves, one worked example each

Leaf 1 — Retry

A geocoding lookup times out on attempt 1 of 3. transient=True, no side effects, no writes. Action: retry with backoff (200ms, 800ms, 3200ms), log the attempt counter, and let the budget run out. The thing you must not do: reuse this leaf for the enrichment step that posts a normalized address to an internal service. That step has a side-effect boundary.

Leaf 2 — Replay

The charge step times out after the provider accepted the request. Whether the charge landed is unknown, which is exactly the state replay exists for. You have ckpt-17, so you re-submit the same request with the same idempotency key and the provider returns the original response instead of a second charge.

class ReplayLedger:
    """Append-only claim file: first writer wins, replayers get False."""

    def __init__(self, path: str) -> None:
        self.path = path

    @staticmethod
    def key(job_id: str, step: str, checkpoint: str) -> str:
        return f"{job_id}:{step}:{checkpoint}"

    def claim(self, k: str) -> bool:
        with open(self.path, "a+", encoding="utf-8") as fh:
            fh.seek(0)
            if k in {line.strip() for line in fh if line.strip()}:
                return False
            fh.write(k + "\n")
            return True

The checkpoint is not optional here. With side_effects=True and checkpoint=None, the classifier aborts — deliberately, because the honest action is a human reading the provider's list endpoint, not a script guessing.

Leaf 3 — Repair

The extract step returns valid JSON that is missing due_date. The transport is fine; the contract is not. Repair means the input changes: append the required schema, add the one failing example, bump repair_attempts, and record a hash of the new prompt so the next failure is comparable to the last. Two repairs maximum. After that the fingerprint is stable and the leaf flips to abort.

Leaf 4 — Abort

The charge step returns 402 three times, transient=False, repair_attempts=2, and it has side effects. Every branch below the poison check would do something plausible and wrong. Action: quarantine the job, keep the trace, page a human, and run reconciliation against the provider before any resubmission. The cost of this leaf is one interrupted job. The cost of skipping it is a duplicate-charge incident.

Where free capacity actually lands in this tree

The repair leaf is the speculative one. Two repair attempts per failing step, across a nine-step job, means inference on inputs that mostly fail — and every repair changes the prompt, which makes the cost hard to amortize with caching.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

That is the honest place to try MonkeyCode's free model access: point only the repair branch at it, keep retry and replay on your existing infrastructure, and compare the abort rate after a week. The other fit is the replay ledger — a tiny append-only process that benefits from the free server option because it needs uptime, not compute. Free-tier quotas, model lists, and server terms change; read the project's current documentation rather than any number quoted in a blog post, including this one, and check the limits before you put a real queue behind it.

Limitations, and who should skip this

The ledger above is not concurrency-safe. Single writer only; multi-worker setups need a real store with an atomic conditional write.
Triage classifies failures, not outcomes. A step that returns HTTP 200 with semantically wrong data lands in repair, and only reconciliation catches it.
The tree assumes idempotent downstream operations or a written compensation action. If neither exists, replay is a duplicate generator and this whole approach is unsafe.
If your steps cannot checkpoint — long streaming writes, non-resumable file uploads — the side-effects branch collapses to abort and you gain little beyond a vocabulary.
Do not put financial, medical, or deletion paths behind an automated replay without a reconciliation step that a human reads.

Test plan before production

Run python3 triage.py and require exit code 0. All seven assertions are regression tests, especially the last one.
Add a fixture for every step in your job, recording real observed values for transient, schema_ok, side_effects, and checkpoint.
Point the job at a sandbox downstream that records every write. Inject a timeout after the write and confirm exactly one write appears after replay.
Force checkpoint=None on a side-effecting step and confirm the job aborts instead of retrying. This is the single most valuable test in the list.
Run 50 jobs with a 5% injected failure rate and compare duplicate-write count against your current except: retry() baseline. Zero is the target; anything else means the ledger is leaking.

Start with the selftest, not the architecture diagram. If the repair leaf turns out to be where your tokens go, running those speculative attempts on MonkeyCode's free model access for a week is a cheap way to get evidence before you change anything that is currently working.

Which Agent Step Deserves a Cache? A Glossary, a Decision Tree, and Four Worked Leaves

Taylor Lin — Mon, 26 Oct 2026 11:36:18 +0000

A nightly agent job runs 40 steps. Last sprint someone added a response cache to save calls on a free model endpoint. Tonight the summary cites a documentation paragraph that was deleted six hours ago, and nobody notices until a human reads the output.

Caching is the cheapest optimization in an agent pipeline and the easiest way to ship stale facts. The problem is not "should we cache" — it is which step deserves a cache, and with what invalidation contract. This post gives you a glossary, a four-question decision tree, and a worked example at each leaf, plus a replay test you can run before trusting any of it.

Glossary: seven terms worth agreeing on first

Step — one model call plus its deterministic wrapper (prompt assembly, parsing, validation). Caching decisions belong to the step, not the pipeline.
Cache key — the exact bytes that identify a reusable result. If the key omits an input, you get a silent wrong answer, not a miss.
Normalization — the rewrite applied to a prompt before hashing (whitespace collapse, Unicode NFKC, lowercasing). It raises hit rate and raises collision risk in the same move.
Staleness class — a label for how bad a stale answer is: cosmetic, misleading, or unsafe. Only cosmetic is a safe default for TTL caching.
TTL — the wall-clock bound on reuse. A TTL is a promise you make to readers about how old your facts can be.
Input digest — a hash of the files or records the step reads, not just the prompt text. Prompt-only keys miss content changes.
Hit budget — the fraction of steps you expect to serve from cache. Write it down; an unmeasured cache is a guess with extra failure modes.

The decision tree

Ask four questions per step, in order. Stop at the first leaf.

Q1. Does the step read external mutable state (live DB, clock, web, file tree)?
    yes -> Q2
    no  -> LEAF A (exact memo, no TTL)

Q2. Is a stale answer ever unsafe (side effects, money, access, published text)?
    yes -> LEAF C (no cache)
    no  -> Q3

Q3. Do prompts vary only by whitespace/casing/Unicode form across runs?
    yes -> LEAF D (normalized key + namespace)
    no  -> LEAF B (TTL cache, TTL from staleness class)

Four leaves. Each one below is a runnable decision, not a vibe.

Leaf A — exact memo, no TTL

Pure steps: schema validation of a tool call, prompt linting, deterministic reformatting, unit conversion. The output cannot change unless the input changes, so a TTL is pointless — the input digest is the invalidation.

from dataclasses import dataclass
from hashlib import sha256
import json

@dataclass(frozen=True)
class Step:
    name: str
    prompt: str
    input_digest: str          # hash of files/records the step reads
    reads_mutable_state: bool
    stale_is_unsafe: bool
    normalizable: bool = False

def cache_key(step: Step, model_tag: str) -> str:
    payload = {
        "model": model_tag,
        "prompt": step.prompt,
        "input": step.input_digest,
    }
    blob = json.dumps(payload, sort_keys=True).encode("utf-8")
    return sha256(blob).hexdigest()[:16]

Note model_tag is in the key. Swapping the model behind the same prompt must not reuse the old answer — that is the single most common cache bug in free-tier pipelines.

Leaf B — TTL cache, TTL set by staleness class

Steps that read mutable state but tolerate staleness: doc-snippet retrieval, changelog summaries, format detection. Here the cache lives for a bounded time and the bound is chosen from the staleness class, not from "how much money would we save".

This is where placement matters. A cache needs to survive between runs but not between deploys, and it needs to be reachable from wherever the step executes. Running the cache on the same box as the worker removes a network hop and one credential.

MonkeyCode offers free model access and a free server option (both operator-supplied availability claims — confirm current limits on the project page), which makes Leaf B practical for a hobby-scale job: model calls on the free endpoint, cache and state on the free server.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

import time

TTL_BY_CLASS = {"cosmetic": 6 * 3600, "misleading": 15 * 60}

def should_reuse(step: Step, cached_at: float, staleness_class: str) -> bool:
    ttl = TTL_BY_CLASS.get(staleness_class)
    if ttl is None:
        return False           # 'unsafe' has no TTL — see Leaf C
    return (time.time() - cached_at) < ttl

One rule: store the staleness class next to the value, not in your head. When the class changes after a code review, you want the old entries refused automatically.

Leaf C — no cache at all

Anything with a side effect or an accuracy obligation: sending mail, writing to a repo, granting access, producing the final user-facing answer. Recompute. If a free-tier call budget forces the issue, shrink the step instead of caching it — cache the retrieval that feeds the step, not the conclusion.

def admit(step: Step) -> str:
    if not step.reads_mutable_state:
        return "leaf_a_exact_memo"
    if step.stale_is_unsafe:
        return "leaf_c_no_cache"
    if step.normalizable:
        return "leaf_d_normalized"
    return "leaf_b_ttl"

That function is the whole artifact. Pipe every step definition through it in a test and assert the mapping matches your written design; the test is what stops someone from adding a cache to the final-answer step during a Friday refactor.

Leaf D — normalized key with a namespace

Prompts that differ only in whitespace or Unicode form deserve a normalized key — but the namespace must record the normalization version, or an edit to your normalizer silently reuses entries built under the old rules.

import re, unicodedata

def normalize(text: str, version: str = "v1") -> str:
    t = unicodedata.normalize("NFKC", text).strip().lower()
    t = re.sub(r"\s+", " ", t)
    return f"{version}:{t}"

Test the collision behavior explicitly:

assert normalize("Summarize  this.") == normalize("summarize this.\n")
assert normalize("a") != normalize("a", version="v2")

If the second assertion ever fails, every cached entry is now ambiguous across normalizer versions.

The replay test: three checks before you enable anything

Hit-rate check. Replay recorded step inputs with the cache on. Record actual hits; compare to the hit budget you wrote down. A hit rate far above budget usually means your key is missing an input.
Invalidation check. Mutate the source document that feeds one Leaf-B step. The next run must miss. If it hits, your TTL is carrying all the safety and your digest is decorative.
Kill-switch check. Flip an environment flag that disables the cache and confirm the pipeline still produces identical output. A cache you cannot turn off in one move is an outage waiting for a bad deploy.

Decision table

Step	Mutable state	Stale unsafe	Leaf	Invalidation
Tool-call schema validation	no	n/a	A	input digest
Doc snippet retrieval	yes	no	B	TTL + digest
Final user answer	yes	yes	C	none (recompute)
Intent classification	yes	no	D	TTL + norm version

Limitations and who should not use this

Latency-sensitive paths. If a step runs once per request and the cache lives on a separate free server, the round trip can cost more than the recompute. Co-locate or skip.
Steps with hidden inputs. If your prompt assembly pulls in conversation history or a user profile, the digest must include it. Steps you cannot fully describe should stay at Leaf C.
Workloads with no repetition. Low-overlap traffic produces misses plus a cache to maintain. Measure first; if your replay shows a single-digit hit rate, delete the layer.
Anything with a compliance clock. If readers are entitled to fresh data, a TTL cache is a policy change, not a performance tweak. Get it reviewed as one.

The cache is not the interesting part. The interesting part is the sentence you can write afterwards: this step may serve a result up to N minutes old, and here is the test that proves it. Steps that cannot survive that sentence belong at Leaf C.

If you want to try the shape — free model calls plus a free server to host the cache and the replay harness — MonkeyCode's project page is the place to check current terms, then run the three checks above against your own recorded steps before enabling anything in production.

Token Forensics for Agent Runs: Five Waste Signatures and the Order to Fix Them

Taylor Lin — Tue, 20 Oct 2026 09:44:06 +0000

A team I worked with had a nightly agent job that was supposed to run for six hours. By 11 a.m. its daily allowance was gone, and the run had produced two usable summaries out of nine.

Nobody could say which step ate the tokens. The router logs showed requests; they did not show cost. So the first instinct was to blame the model.

It was not the model. It was step 7 resending the same 4,000-token tool output on every attempt, after a validation failure that fired four times.

That is the whole problem in miniature: agent budgets rarely die from one big call. They die from structural waste that no request log records.

Below is the accounting I now run before changing anything — a small meter, five waste signatures, and the order in which to fix them.

1. Start with the report, not the router

Routing decisions are the wrong first lever. If 40% of your billed tokens are retries of a call that always fails, no amount of re-routing helps; you will just fail more cheaply.

Measure per step first. Then the routing question becomes answerable with numbers instead of vibes.

Glossary (six terms, used consistently below)

Term	Definition	Signal it produces
Billed tokens	Sum of prompt and completion tokens the provider counts for a run	Absolute cost
Static tokens	System prompt plus tool schemas, paid on every single call	`overhead_ratio`
Reused tokens	Context carried into a step unchanged from an earlier step	`redundancy_ratio`
Retry amplification	Share of billed tokens spent on attempts that ended in failure	`retry_amplification`
Prompt growth	How much the last successful prompt outgrew the first	`prompt_growth`
Leaf	The single branch the decision tree lands on, i.e. one prescribed first action	`leaf`

The sixth term matters most. A tree that returns three suggestions per run is a tree nobody follows.

2. The meter (stdlib only, ~60 lines)

You need three numbers per step that providers already return in usage, plus two annotations you add yourself: how many tokens are static, and how many are reused from an earlier step.

The annotations are manual or heuristic. That is a feature — it forces you to look at the prompt.

#!/usr/bin/env python3
"""meter.py - per-step token accounting for agent runs. Python 3.10+, stdlib only."""
from __future__ import annotations

import json
import sys
from dataclasses import dataclass


@dataclass
class Step:
    name: str
    prompt_tokens: int
    completion_tokens: int
    static_tokens: int = 0   # system prompt + tool schemas, paid per call
    reused_tokens: int = 0   # context carried over unchanged from an earlier step
    attempt: int = 1
    ok: bool = True


def load(path: str) -> list[Step]:
    with open(path, encoding="utf-8") as fh:
        return [Step(**row) for row in json.load(fh)]


def summarize(steps: list[Step]) -> dict:
    prompt = sum(s.prompt_tokens for s in steps)
    completion = sum(s.completion_tokens for s in steps)
    if not steps or prompt == 0:
        return {"steps": len(steps), "billed_tokens": prompt + completion}

    billed = prompt + completion
    wasted_retry = sum(
        s.prompt_tokens + s.completion_tokens for s in steps if not s.ok
    )
    ok_steps = [s for s in steps if s.ok]
    first = ok_steps[0].prompt_tokens if ok_steps else 0
    last = ok_steps[-1].prompt_tokens if ok_steps else 0

    return {
        "steps": len(steps),
        "billed_tokens": billed,
        "overhead_ratio": round(sum(s.static_tokens for s in steps) / prompt, 3),
        "retry_amplification": round(wasted_retry / billed, 3),
        "redundancy_ratio": round(sum(s.reused_tokens for s in steps) / prompt, 3),
        "prompt_growth": round((last - first) / first, 3) if first else 0.0,
    }


ACTIONS = {
    "B_retry": "install a stop rule before touching anything else",
    "A_overhead": "shrink the system prompt and tool schemas",
    "C_redundancy": "collapse steps or externalize state",
    "D_drift": "cap the transcript, move history to a scratch file",
    "F_leave_it": "budget is healthy; change nothing",
}


def classify(m: dict) -> str:
    if not m.get("billed_tokens"):
        return "F_leave_it"
    if m["retry_amplification"] > 0.25:
        return "B_retry"
    if m["overhead_ratio"] > 0.60:
        return "A_overhead"
    if m["redundancy_ratio"] > 0.40 and m["steps"] >= 8:
        return "C_redundancy"
    if m["prompt_growth"] > 0.30:
        return "D_drift"
    return "F_leave_it"


def main(argv: list[str]) -> int:
    if len(argv) != 2:
        print("usage: meter.py steps.json", file=sys.stderr)
        return 2
    report = summarize(load(argv[1]))
    leaf = classify(report)
    report["leaf"] = leaf
    report["first_action"] = ACTIONS[leaf]
    print(json.dumps(report, indent=2))
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv))

Input is a flat JSON array. Three rows are enough to show the shape:

[
  {"name": "plan",            "prompt_tokens": 3200, "completion_tokens": 410, "static_tokens": 2400, "reused_tokens": 0,    "attempt": 1, "ok": true},
  {"name": "fetch_schema",    "prompt_tokens": 5100, "completion_tokens": 120, "static_tokens": 2400, "reused_tokens": 2600, "attempt": 1, "ok": true},
  {"name": "validate_schema", "prompt_tokens": 5400, "completion_tokens": 90,  "static_tokens": 2400, "reused_tokens": 2600, "attempt": 3, "ok": false}
]

Run it:

python meter.py steps.json

Note: the script is dependency-free Python 3.10+. I have exercised it only against synthetic usage dicts, so treat its output as a structural description of your run, not as a benchmark of any model or provider.

3. The decision tree, in fix order

The branches are ordered by cost of ignorance, not by elegance. Retries are checked first because they are the cheapest thing to fix and the most expensive thing to leave alone.

retry_amplification > 0.25 → leaf B. A quarter of the budget is being spent on attempts that fail. Stop the run earlier.
overhead_ratio > 0.60 → leaf A. Most of each prompt is boilerplate you wrote once and now pay forever.
redundancy_ratio > 0.40 and at least 8 steps → leaf C. Long runs are resending the same material.
prompt_growth > 0.30 → leaf D. The transcript is growing faster than the work.
None of the above → leaf F. Do nothing. This leaf is real and should fire often.

The stop rule for leaf B

A ratio is a diagnosis; you need a hard stop in code.

DAILY_ALLOWANCE = 1_000_000          # your number, from your own account
MAX_WASTE_RATIO = 0.25
wasted = 0

for step in steps:
    result = run_step(step)
    if not result.ok:
        wasted += result.prompt_tokens + result.completion_tokens
    if wasted > DAILY_ALLOWANCE * MAX_WASTE_RATIO:
        raise SystemExit("stop: waste budget exhausted, fix the failing step first")

This turns an invisible leak into a visible crash. Crashes get fixed; leaks get re-billed.

4. Worked examples at each leaf

The numbers below are illustrative workloads, not measurements of any product.

Leaf B — retry amplification 0.41. Nine steps, 180k billed tokens, 74k of them on failed validation attempts. First action: make the validator return the exact field path, not "invalid input". Second: apply the stop rule above. Expected effect is bounded — you cap the loss, you do not recover the tokens.

Leaf A — overhead ratio 0.72. A 3,100-token system prompt plus four tool schemas against a 4,300-token average prompt. First action: move three rarely used tools behind a second call. If a schema is only needed after planning, it does not belong in the planner's prompt.

Leaf C — redundancy 0.55 with 12 steps. The same repository map is pasted into eight prompts. First action: externalize it to a file the agent reads by path, and pass a one-line index instead. Second: check whether steps 4 and 5 can merge — often they exist because of an earlier ordering constraint that no longer holds.

Leaf D — prompt growth 0.84. The first successful prompt was 2,900 tokens; the last was 5,300. First action: summarise every third turn into a scratch note and drop the raw turns. Second: measure again — if growth persists, the agent is accumulating state it never reads.

Leaf F — everything under threshold. The correct output of this workflow is often "no change". Record the report, set an alert on retry_amplification, and go do something else.

5. Where a free tier actually changes the math

One leaf benefits from cheap capacity, and it is not the one people expect.

Leaf C and leaf D often need a summariser: a step that compresses history before the expensive step reads it. That step is repetitive, low-stakes, and easy to validate — a good candidate for a free endpoint, because a bad summary fails loudly at the next step rather than silently.

That is where MonkeyCode fits in this workflow rather than in the headline. The project advertises free model access and a free server option, and an allowance of 10 million tokens at the time of writing — operator-stated figures that you should confirm against current terms before planning around them. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

I would not move the planning step there first. Move the step whose failure is easiest to detect, run the meter again, and compare billed_tokens before and after. If the number does not move, the free tier was a distraction, not an optimisation.

6. Limitations, and who should skip this

Usage accounting is not portable. Cached tokens, reasoning tokens, and tool-call tokens are reported differently across providers. Normalise or your ratios lie.
The annotations are manual. static_tokens and reused_tokens come from your reading of the prompt, not from the API.
It measures spend, not quality. A run can hit leaf F and still be useless. Pair this with a task-level success check.
Skip it if you already have tracing. If your stack records per-span token counts and you trust them, use those numbers and borrow only the fix order.
Skip it if latency dominates. On a latency-bound pipeline, shrinking prompts for token reasons can cost you more than it saves.

Closing

The order matters more than the thresholds. Retries, then boilerplate, then redundancy, then growth — and then, usually, nothing.

If you want to test this today, save one run's usage fields to JSON and run the meter against it. It is small enough to finish before lunch, and the leaf it returns is a better starting point than another router rewrite. If you decide the summariser step is worth moving, the project's free tier is a reasonable place to try it — with the meter still running.

Context Triage for Agent Prompts: Terms, Five Branches, and a Dependency-Free Budget Checker

Taylor Lin — Mon, 19 Oct 2026 08:26:24 +0000

Consider a support-triage agent that reads a ticket, pulls four tool results, and asks a model to classify and draft a reply. It works locally. Then someone adds a fifth tool, the history buffer grows by one turn, and every call starts failing on length before the model ever sees the question. This is a composite scenario, not a logged incident — but it is the most common shape of the failure.

The tempting fix is "switch to a bigger window." That is also the fix that keeps you on a treadmill, because the window you get from a free model endpoint is the one constraint you do not control. The fix that survives is triage: decide, before the call, which spans of your prompt are load-bearing and which are recoverable.

This post is that decision procedure. Terms first, then a five-branch tree with a worked example at each leaf, then the code I use to make the decision mechanical instead of vibes-based.

1. Glossary: the six terms that do the work

Span. One named, independently removable block of text in the prompt: the system instruction, the ticket body, each tool result, each prior turn. Triage is impossible if your prompt is one concatenated string; it is trivial if it is a list of spans.

Hard window. The context limit the endpoint enforces. If you exceed it, the request fails or gets silently cut. Treat it as unknown until you read the documentation — do not infer it from a successful call.

Soft budget. The number you actually target, deliberately below the hard window, leaving room for the model's output and for tokenizer drift between your counter and the provider's.

Eviction class. The label that decides whether a span may be dropped. Three classes are enough: pinned (the task is meaningless without it), reconstructible (can be replaced by a stub or summary), recoverable (can be re-fetched on demand if the model asks).

Truncation debt. The information you removed that the model will later need. It is not free. A prompt that fits by dropping a tool result often produces a confident, wrong answer twenty seconds later.

Leaf. A terminal branch of the decision tree: one specific trimming action, plus the check that tells you the trim was safe.

2. The tree: five branches, five leaves

Ask the branches in order. The first one that matches is your leaf; stop there.

Branch 1 — Does one pinned span already exceed the soft budget?

If a single pinned span is too large, no amount of dropping history will save you. Chunk it.

Leaf 1A — Chunk and label. Split the span into numbered chunks that each fit alone, process chunk 1 first, and carry forward only the extracted fields, not the raw text.

Worked example: a 900-line log file attached to a bug ticket. Chunk by time window, ask for {error_signature, first_occurrence, affected_endpoint} from each chunk, then classify on the merged fields. The merge output is a few hundred tokens; the log never needs to re-enter the window.

Branch 2 — Is the overflow from accumulated conversation turns?

Leaf 2A — Windowed eviction with a carry-forward summary. Keep the last n turns verbatim, replace everything older with one summary span marked reconstructible, and cap the summary at a fixed token count so it cannot itself become the problem.

Worked example: twelve turns of a refactoring session. Keep turns 9–12 verbatim; compress 1–8 into a bullet list of decisions ("chose strategy B; rejected caching layer; rename pending"). The decisions are what future turns reference. The transcript is not.

Branch 3 — Is the overflow from tool output?

This is the branch people skip, and it is usually the right one.

Leaf 3A — Lossy projection at the tool boundary. Do not store what the tool returned; store what the next step needs. A grep result becomes a list of {path, line, match}, not the file. A JSON API response becomes the two fields the prompt actually names.

Worked example: a dependency-audit tool returns 4 KB of advisory JSON; the agent only needs (package, severity, patched_version). Project to that triple at the tool boundary and the span drops by an order of magnitude — with no loss, because the model was never going to read the rest.

Branch 4 — Is the overflow from the instruction block itself?

Leaf 4A — Deduplicate and demote. Long system prompts accumulate contradictory restatements. Split the instruction span into numbered rules, drop exact duplicates, and demote examples into a separate reconstructible span that is only included when the task is in the "hard case" set.

Worked example: an instruction block with three separate paragraphs explaining output JSON format. Collapse to one rule plus one schema block. If the schema is large, keep the schema and move the worked examples out.

Branch 5 — Nothing trims enough without cutting pinned content.

Leaf 5A — Reduce the unit of work. Do not shrink the prompt further; shrink the job. One call per file instead of one call per repository. This is where triage becomes planning, and it is a legitimate outcome, not a failure.

Worked example: "review this PR" against a 40-file diff. Convert to per-file review calls plus one aggregator call that receives only the per-file verdicts.

3. Make it mechanical: a budget checker with no dependencies

The tree is only useful if a machine applies it. This checker takes spans, applies eviction classes, and returns what survived and what was removed. The token counter is pluggable — the default character heuristic is a stand-in so the example runs without a tokenizer.

from dataclasses import dataclass

@dataclass
class Span:
    name: str
    text: str
    evict: str   # "pinned" | "reconstructible" | "recoverable"
    priority: int  # lower number = dropped earlier

def char_counter(text: str) -> int:
    return max(1, len(text) // 4)

def triage(spans, soft_budget, counter=char_counter):
    total = sum(counter(s.text) for s in spans)
    if total <= soft_budget:
        return list(spans), [], total

    droppable = sorted(
        (s for s in spans if s.evict != "pinned"),
        key=lambda s: (s.priority, -counter(s.text)),
    )
    kept, dropped = list(spans), []
    for span in droppable:
        if total <= soft_budget:
            break
        kept.remove(span)
        dropped.append(span)
        total -= counter(span.text)
    return kept, dropped, total

def render(kept, dropped):
    lines = [s.text for s in kept]
    for s in dropped:
        lines.append(f"[{s.name} omitted: {s.evict}]")
    return "\n\n".join(lines)

Run it on a synthetic fixture — counts below are fixture output from char_counter, not provider tokenizer numbers and not a benchmark:

spans = [
    Span("instructions", "..." * 200, "pinned", 0),
    Span("ticket",       "..." * 300, "pinned", 0),
    Span("tool_audit",   "..." * 900, "recoverable", 1),
    Span("history_1_8",  "..." * 700, "reconstructible", 2),
    Span("schema",       "..." * 250, "pinned", 0),
]
kept, dropped, total = triage(spans, soft_budget=1200)
print(total, [s.name for s in dropped])

The point of the render stub line is honesty: the model is told a span exists and was omitted, so it can ask for it back instead of assuming the absence means "nothing there." Silent removal is where truncation debt gets expensive.

4. Which leaf for which symptom

Symptom you observe	First check	Leaf	Failure if you pick wrong
Failure on first call, short history	Size of each pinned span	1A	Chunking a prompt that was fine wastes calls
Degrades after turn ~10	Turn count vs. budget	2A	Summarizing too aggressively loses earlier decisions
Degrades after adding a tool	Tool output size	3A	Dropping the tool result makes the model guess
Works until you edit the system prompt	Rule duplication	4A	Demoting examples breaks edge-case accuracy
Every leaf still over budget	Task granularity	5A	More trimming yields a confident wrong answer

The table is the practical artifact. In practice, most teams are in branch 3 and believe they are in branch 2.

5. Limitations, and who should skip this

Counters disagree. Your character heuristic and the provider's tokenizer will drift. That is why the soft budget exists; set it with margin, not to the last token.
Summaries are lossy in ways tests miss. If your task depends on exact strings (IDs, hashes, error codes), chunk summarization is the wrong leaf — keep those spans pinned and reduce the job instead.
This is not a cost optimization. Triage reduces failures; it does not necessarily reduce call count. Branch 5 in particular increases it.
Skip this if your prompts fit comfortably with headroom, if you have a single fixed prompt with no history or tools, or if silent truncation by the endpoint is already documented and you accept it.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

6. Where the free surfaces fit

The workflow above was written around two surfaces: a free server running the agent runtime (where span assembly and the budget check happen) and free model access at the endpoint (where the window is enforced). Keeping the triage step on the server side means the model endpoint only ever sees a prompt that already fits — the failure moves from "request rejected" to "span listed as omitted," which is a much cheaper failure to debug.

Two cautions. Free availability is not the same as unlimited capacity: read the current documentation for quotas, window sizes, and server limits rather than assuming last month's numbers still hold, and back off immediately on a 429 instead of retrying around it. And measure your own prompts — the fixture above tells you nothing about your traffic.

If you want to try the leaves against a live endpoint, the budget checker is the only thing you need to bring; MonkeyCode's free model access and free server option are the two surfaces this was written around, and the tree works the same without them.

Admission Control Before Routing: A Free-Tier Quota Ledger for Agent Jobs

Taylor Lin — Sat, 17 Oct 2026 06:09:28 +0000

Picture a nightly batch: 400 classification calls, one free model endpoint, one free server, one cron entry. At 03:12 the run exits with code 0. The logs are green. The next morning half the labels are wrong, because the run quietly started receiving truncated or fallback responses once the quota window closed — and nothing in the pipeline noticed.

That scenario is constructed, but the arithmetic behind it is not. Almost every free-tier agent job I have seen has routing logic and no admission logic. It knows where to send work. It does not know whether it can afford to send work at all.

This article builds the missing layer: a local quota ledger plus a four-leaf decision tree that runs before any request leaves the machine. MonkeyCode's free model access and free server option are the deployment targets I use for the worked examples, because that is the combination most likely to hit this failure. Treat the availability claims as operator-supplied and re-read the project's current terms before you depend on them.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Terms first, tree second

Five terms carry the whole design. If you only take one, take replay cost.

Quota window — the period after which the provider's allowance resets, if it resets. You do not control it, so you must assume it can close mid-batch.
Unit cost — tokens charged per work item, input plus output, measured rather than guessed.
Replay cost — the extra units burned by retries and re-runs. A 15% retry rate is a 15% tax on your budget, and it is invisible if you only count successful calls.
Headroom — budget - spend, where spend includes failed and retried attempts, not just the ones that returned 200.
Admission — the decision to not start a job, or to start a smaller version of it, before the first request is issued.

Routing asks where. Admission asks whether, and how much. Skipping the second question is how you get exit code 0 with wrong output.

The ledger artifact

The script below is standard library only and deliberately boring. It appends one JSON line per attempt, so retries are billable by construction.

# ledger.py - Python 3.11+, stdlib only
import json, os
from dataclasses import dataclass, asdict

LEDGER = os.environ.get("LEDGER_PATH", "usage.jsonl")
BUDGET = int(os.environ.get("QUOTA_BUDGET", "200000"))
SAFETY = 0.80          # never plan past 80% of headroom
REPLAY = 0.15          # measured retry tax, replace with your own

@dataclass
class Entry:
    ts: float
    job_id: str
    tokens_in: int
    tokens_out: int
    status: str        # ok | retry | failed
    idem_key: str

def append(entry: Entry) -> None:
    with open(LEDGER, "a", encoding="utf-8") as f:
        f.write(json.dumps(asdict(entry)) + "\n")

def load() -> list[Entry]:
    if not os.path.exists(LEDGER):
        return []
    with open(LEDGER, encoding="utf-8") as f:
        return [Entry(**json.loads(line)) for line in f if line.strip()]

def spent() -> int:
    return sum(e.tokens_in + e.tokens_out for e in load())

def headroom() -> int:
    return BUDGET - spent()

def plan(items: int, per_item: int, deadline_bound: bool) -> tuple[str, dict]:
    unit = per_item * (1 + REPLAY)
    want = items * unit
    left = headroom()
    if want <= left * SAFETY:
        return "A", {"items_now": items, "items_later": 0}
    if want <= left:
        now = int(left * SAFETY // unit)
        return "B", {"items_now": now, "items_later": items - now}
    if not deadline_bound:
        per_window = int(BUDGET * SAFETY // unit)
        return "C", {"windows": -(-items // per_window), "per_window": per_window}
    now = int(left * SAFETY // unit)
    return "D", {"items_now": now, "items_rerouted": items - now}

Run it with an explicit budget for the window you are about to use:

QUOTA_BUDGET=200000 LEDGER_PATH=usage.jsonl python -c "import ledger; print(ledger.plan(130, 900, False))"

Two design choices matter more than the code. First, status is recorded but never filtered out of spent() — a failed attempt still consumed quota. Second, SAFETY is a hard multiplier, not advice: it forces a plan to survive a 20% estimation error without touching the last fifth of the allowance.

The tree, with four worked leaves

Hold the fixture constant: BUDGET = 200,000, already spent 60,000, so headroom = 140,000; SAFETY = 0.80 gives a planning ceiling of 112,000; REPLAY = 0.15. All four numbers below are hand arithmetic against that fixture, not provider measurements.

Leaf A — admit unchanged. 40 items at 900 units, want = 40 × 900 × 1.15 = 41,400, under the 112,000 ceiling. Run it, record it, move on. Leaf A is where you want 90% of your batches to land; if it is not, your per_item estimate is wrong.

Leaf B — admit a shrunken batch. 130 items at 900 units, want = 134,550. That exceeds the ceiling but fits inside 140,000, so the right move is partial admission: items_now = 112,000 // 1035 = 108, with 22 deferred. Validate chunk one's output before submitting chunk two. If chunk one's labels look wrong, you just saved 22 items of quota and a full-window outage.

Leaf C — defer to the next window. 300 items at 900 units, want = 310,500, no deadline. per_window = 160,000 // 1035 = 154, so the job needs two windows. Note that even a fresh window cannot absorb it in one pass — deferral without re-chunking just moves the failure.

Leaf D — reroute the overflow. Same 300 items, but deadline-bound. Take 108 locally and push the remaining 192 to the free server or a local model path. Leaf D is the only branch that depends on a property of your job rather than of your budget: it is valid only if every item carries an idempotency key and the reroute target produces comparable output. If either is false, fall back to C and negotiate the deadline.

Test the tree, not the model

The decision logic is deterministic, so it is cheap to pin down:

Boundary fixtures. Assert that want == 0.8 × headroom returns A and want == 0.8 × headroom + 1 returns B. Off-by-one at the ceiling is the most common regression.
Injected clock and path. Set LEDGER_PATH to a temp file per test; never read the developer's real ledger.
Conservation property. For every fixture, items_now + items_later (or items_rerouted) equals the input count. A leaf that loses work items is a bug, not an optimisation.
Retry accounting. Append a status="retry" entry and assert that spent() increases. If it does not, your replay tax is not being billed.
Window rollover. Move the ledger file aside, re-run, and confirm the plan returns to leaf A rather than remembering stale headroom.

Limitations, and who should skip this

The ledger counts what your process recorded. It cannot see another process using the same account, and without a file lock two concurrent writers will interleave lines. It also has no pricing knowledge: per_item and REPLAY are yours to measure, and they drift when prompt length or retry behaviour changes. Most importantly, admission control does not override a provider's own rate limiter; if the endpoint returns 429, stop the batch instead of retrying around the limit.

Skip all of this if you run one interactive session at a time, if your work items are genuinely non-repeatable and cannot be idempotent, or if you already have real billing dashboards with per-key spend. For a nightly batch on a free tier with a closing quota window, the ledger is roughly forty lines and it converts a silent failure into a printed plan.

If you want a place to try the tree end to end, MonkeyCode's free model access and free server option give you a realistic budget constraint to run these leaves against — check the current quota and server terms on the project page first, then let the ledger, not the cron entry, decide what runs tonight.

Split Placement: Deciding Which Agent Steps Run Locally, on a Free Server, or on a Free Model Endpoint

Taylor Lin — Fri, 16 Oct 2026 05:08:38 +0000

02:10, nineteen steps done, thirty-one to go

Picture a nightly triage job. It has sixty steps, it starts at 02:00, and at 02:10 it has finished nineteen of them. Step twenty needs to pull text out of a PDF, and the function that calls the model endpoint has just started returning 429 on every third request.

The job does not fail. It stalls, half-done, with no record of which leaf of the pipeline was running when the wall appeared. (The scenario is illustrative; the numbers describe the shape of the problem, not a benchmark I ran.)

Most writing about free AI tiers answers one question: which provider should the whole job use. That question is too coarse. Inside a single job, different steps belong in different places, and the placement decision is the one you can actually test.

Why placement is a separate question from tier choice

A job card is a promise about a workload. A placement decision is a predicate about one step: does it need a filesystem, does it touch regulated data, is it retry-safe, how tight is its deadline. Two steps in the same job can have identical inputs and still belong on opposite ends of your infrastructure.

Two themes keep showing up in current AI coverage: features moving into the client, and fatigue with generated output. Both push the same direction. Compute that can stay local should stay local, and anything that leaves the machine should leave under an explicit rule rather than a default.

The free tier used as the concrete case below is MonkeyCode's, which its operator describes as including free model access and a free server option.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

I have not independently verified the quota figure the operator quotes (described as 10M tokens) or the server specifications, so the harness below treats any quota as unknown and measures consumption instead of assuming headroom.

Glossary: ten terms this tree depends on

Placement leaf — the destination a step is assigned to. This article uses four: LOCAL, FREE_SERVER, FREE_MODEL, ESCALATE.

Data class — the egress sensitivity of a payload. I use three: PUBLIC, INTERNAL, REGULATED.

Deterministic step — a step whose output depends only on its input, so running it twice costs time and nothing else.

Retry-safe (idempotent) — a step that can be re-executed after a transport failure without duplicating a side effect.

p95_seconds — the measured 95th-percentile duration of a step on your hardware. Guessed values make the whole tree decorative.

Quota cliff — the moment a free allowance stops absorbing requests, after which every call is either throttled or billed.

Fallback ladder — the ordered list of endpoints a step may attempt before it escalates.

Outcome class — how a failed attempt should be interpreted: RETRYABLE, FATAL, or OK. Conflating the first two is the most common cause of hot retry loops.

Fixture hash — a short digest over the exact inputs a test used, recorded so a later run can prove it saw the same bytes.

Ledger row — one append-only record per attempt: step, endpoint, attempt index, outcome, elapsed seconds.

The tree: ordered predicates, first match wins

place(step)
|
+-- 1. data_class == REGULATED? -----------------> LEAF D: ESCALATE
+-- 2. deterministic AND p95 <= 2s AND no disk? --> LEAF A: LOCAL
+-- 3. needs_disk OR not text_only? --------------> LEAF B: FREE_SERVER
+-- 4. INTERNAL AND not retry_safe? --------------> LEAF D: ESCALATE
+-- 5. p95 > 0.5 * deadline? ---------------------> LEAF D: ESCALATE
+-- 6. otherwise (text, retry-safe) --------------> LEAF C: FREE_MODEL

The order is the contract, not a style choice. Move predicate 1 below predicate 6 and you have an egress incident with a passing test suite.

The four leaves, with a worked example each

Leaf A: `LOCAL`

Worked example: validate 12,000 issue bodies against a JSON Schema before anything else runs. The step is pure, takes under two seconds at p95, and never needs the network.

# placement.py - pure decision logic, no network, no API keys
from dataclasses import dataclass
from enum import Enum


class Leaf(str, Enum):
    LOCAL = "local"
    FREE_SERVER = "free_server"
    FREE_MODEL = "free_model"
    ESCALATE = "escalate"


class DataClass(str, Enum):
    PUBLIC = "public"        # safe to send to a third-party endpoint
    INTERNAL = "internal"    # company-internal, not customer data
    REGULATED = "regulated"  # PII, health, payment, or contract-bound


@dataclass(frozen=True)
class Step:
    name: str
    p95_seconds: float      # measured on your machine, not guessed
    deterministic: bool
    text_only: bool
    needs_disk: bool
    data_class: DataClass
    retry_safe: bool
    deadline_seconds: float | None = None


def place(step: Step) -> tuple[Leaf, str]:
    """Ordered predicates. First match wins, so order is the contract."""
    if step.data_class is DataClass.REGULATED:
        return Leaf.ESCALATE, "regulated payload: no third-party egress"

    if step.deterministic and not step.needs_disk and step.p95_seconds <= 2.0:
        return Leaf.LOCAL, "cheap pure function: egress would be waste"

    if step.needs_disk or not step.text_only:
        return Leaf.FREE_SERVER, "needs a filesystem or a non-text runtime"

    if step.data_class is DataClass.INTERNAL and not step.retry_safe:
        return Leaf.ESCALATE, "non-idempotent internal call on a shared endpoint"

    if step.deadline_seconds and step.p95_seconds > step.deadline_seconds * 0.5:
        return Leaf.ESCALATE, "free-tier latency variance can eat the deadline"

    return Leaf.FREE_MODEL, "stateless text transform, retry-safe"

Leaf B: `FREE_SERVER`

Worked example: extract text from 400 PDFs and keep an on-disk cache so a second run is nearly free. This step needs a filesystem and CPU time, not a model.

This is also the leaf where a free server option changes the cost shape. Compute-heavy, non-text steps have no reason to touch a model endpoint at all, and putting them there wastes the resource you are actually short on.

Leaf C: `FREE_MODEL`

Worked example: classify and summarize issue text, one call per item, no local state. Text in, text out, retry-safe, egress class PUBLIC.

Before this leaf is reachable you need a reason to believe the endpoint tolerates your request rate. That is what the ladder and the ledger below are for.

Leaf D: `ESCALATE`

Worked example: redact personal data before any summarization happens. The step is a queue write plus a human or in-boundary worker, never a third-party call.

Escalation is a leaf, not a failure. If your tree has no ESCALATE, it is not a decision tree; it is a preference list.

A reproducible harness in five steps

1. Pin the fixture hash. Record the exact bytes a run consumed, so a later result can be tied to a specific input set.

from hashlib import sha256

def fixture_hash(paths):
    h = sha256()
    for p in sorted(paths):
        h.update(p.encode())
        h.update(open(p, "rb").read())
    return h.hexdigest()[:12]

2. Pin the case table. Every leaf needs at least one case, including the ones you expect to be rare.

CASES = [
    (Step("parse_json", 0.3, True, True, False, DataClass.PUBLIC, True), Leaf.LOCAL),
    (Step("extract_pdf", 12.0, False, False, True, DataClass.INTERNAL, True), Leaf.FREE_SERVER),
    (Step("summarize_issue", 3.1, False, True, False, DataClass.PUBLIC, True), Leaf.FREE_MODEL),
    (Step("redact_pii", 4.0, False, True, False, DataClass.REGULATED, True), Leaf.ESCALATE),
]

3. Separate retryable from fatal. A 429 and a schema mismatch must not share a code path.

class Outcome(str, Enum):
    OK = "ok"
    RETRYABLE = "retryable"  # 429, 503, timeout
    FATAL = "fatal"          # 400, 401, schema mismatch


def run_ladder(step, endpoints, call, ledger):
    for attempt, endpoint in enumerate(endpoints, start=1):
        try:
            result = call(endpoint, step)
        except Retryable as exc:
            ledger(step.name, endpoint, attempt, Outcome.RETRYABLE, exc)
            continue
        except Fatal as exc:
            ledger(step.name, endpoint, attempt, Outcome.FATAL, exc)
            return Leaf.ESCALATE, exc
        ledger(step.name, endpoint, attempt, Outcome.OK, None)
        return endpoint, result
    return Leaf.ESCALATE, "ladder exhausted"

4. Prove the ladder with a stub, not with a live quota. A stub that fails on the first endpoint is deterministic, free, and runs in CI.

def test_ladder_falls_through():
    def call(endpoint, step):
        if endpoint == "model-a":
            raise Retryable("429")
        return "ok"

    endpoint, result = run_ladder(step, ["model-a", "free-server"], call, ledger=lambda *a: None)
    assert endpoint == "free-server"
    assert result == "ok"

5. Write a ledger row per attempt. Append-only JSONL is enough, and it is the only artifact that tells you where a quota went when it disappears.

import json, time

def ledger(step_name, endpoint, attempt, outcome, error, path="ledger.jsonl", t0=None):
    row = {
        "step": step_name,
        "endpoint": endpoint,
        "attempt": attempt,
        "outcome": outcome.value,
        "error": type(error).__name__ if error else None,
        "seconds": round(time.monotonic() - t0, 3) if t0 else None,
    }
    with open(path, "a") as fh:
        fh.write(json.dumps(row) + "\n")

Run the whole thing with pytest -q. If you want the leaf distribution for a real job, feed your step table through place() and count the leaves before you deploy anything.

Limitations and what I did not verify

Free tiers move. A tree that encodes this month's allowances will quietly lie next quarter, which is why the harness measures instead of assuming headroom. The p95_seconds values must come from your own runs; copy-pasting mine would produce confident nonsense.

The data-class verdicts are jurisdictional and contractual. REGULATED here means "handled under a reviewed boundary" and nothing more, so the compliance owner decides those rows, not the engineer writing the predicate.

The ladder costs latency. Each retryable failure adds a round trip, and any non-idempotent step placed on FREE_MODEL by mistake can duplicate a side effect instead of failing cleanly. Retry-safety is a property of your step, not of the endpoint.

The described MonkeyCode free tier and its reported quota are operator-supplied statements that I have not independently tested against live rate limits, model behavior, or uptime.

Who should not use this

Teams with hard contractual SLAs should not route deadline-critical steps through any free tier, whatever the tree says. Workloads dominated by large non-text payloads will spend more time uploading than computing and should keep those steps local or on a server you control. Anyone without an owner for the REGULATED branch should stop at the glossary and get one first.

If you have a nightly job with a mixed step table, run place() over it and post the leaf counts. The distribution usually says more about where your budget goes than the tree does, and it is a cheap thing to compare across two teams.

Routing Agent Jobs Across Free Tiers: A Glossary, a Decision Tree, and Four Worked Leaves

Taylor Lin — Thu, 15 Oct 2026 11:20:05 +0000

Two of this week's most-read posts on DEV were about AI fatigue and about tooling that lags behind model capability. Read together, they describe the same operational gap: models got cheaper and better, while the plumbing that decides where a job runs stayed informal, undocumented, and unreproducible.

The failure shape is familiar. A script that used to run on a laptop gets promoted to "the free tier" because the free tier is free. Nobody notices that the job is a webhook receiver — something has to connect to it. Nothing does. The retry loop runs for six hours, duplicate units pile up, and the only record of the routing decision is one sentence in a chat thread.

A week later, three questions have no answer: which lane did this job belong in, what evidence justified that lane, and what would move it out again.

So here is the artifact this post builds: a glossary, a decision tree with four leaves, a dependency-free router you can run (route_job.py), a test file that pins every branch, and a log query that turns routing records into a table you can argue with.

Glossary: the eight terms the tree depends on

Precision here saves arguments later. If two people mean different things by "free tier", the decision tree resolves nothing.

Job — one unit of work with a name, an input, an output, and an owner. Not a pipeline.
Lane — the placement class a job routes to. This post uses four: local_only, free_model, free_server, controlled.
Leaf — a terminal outcome of the tree, carrying one example, one expected routing record, and one exit condition.
Data class — what the input contains: public, internal, or sensitive. Assigned by the data owner, not by the engineer who is in a hurry.
Idempotent unit — work that replays from the start with no extra side effect. A duplicate is a wasted call, not a corrupted record.
Addressable — something must initiate a connection to the job: a webhook, a schedule, an SSH session. Addressability is a hosting requirement, not a model requirement.
Pinned model — a job whose output is reproducible only against a specific model revision. Reproducibility outranks cost.
Routing record — one JSON line written at dispatch time: job, lane, reason, data class, and the quota observed on that call.

The decision tree: five branches, in order

Branch order is the policy. Reorder it and you have a different system, so write the order down and test it.

Branch 1 — Can the answer be computed without a model? If yes, local_only.

Branch 2 — Is the input sensitive, or is there a contractual review? controlled. Boundaries beat convenience.

Branch 3 — Does the job need a pinned model? controlled. Free tiers move underneath you by design.

Branch 4 — Must something connect to the job, or does it run longer than a short request? free_server.

Branch 5 — Is a re-run cheap and safe? Not idempotent goes to controlled. Idempotent goes to free_model.

The two interesting leaves are free_model and free_server, because both assume you have a model endpoint and a host. Many free options exist for each; this post treats them as properties, not brands. MonkeyCode, for example, is an open-source project whose free model access and free server option map onto those two leaves.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Its current outreach states a free tier of 10,000,000 tokens plus a free server option. Treat both as configuration you read at run time, never as constants you hard-code: quotas and terms are set by the project and can change between the day you write the number down and the day you rely on it.

Four worked leaves

Leaf A — `local_only`

Example: a nightly disk-usage digest that reads /proc and prints a table. Why it stops here: the answer is computable without a model.

{"name":"disk-report","lane":"local_only","reason":"decidable without a model; keep it off the network"}

Exit condition: the day someone adds an LLM summarization step, this becomes two jobs. Keep the deterministic half exactly where it is.

Leaf B — `free_model`

Example: drafting a changelog entry from a public PR diff. Why it stops here: public input, single-shot, idempotent, no inbound connection.

{"name":"changelog-draft","lane":"free_model","reason":"disposable, non-sensitive, single-shot"}

Exit condition: the diff stops being public. Then Branch 2 fires and the job moves to controlled, no matter how cheap leaf B is.

Leaf C — `free_server`

Example: a watcher that receives a repo webhook, queues the event, and replies later. Why it stops here: it is addressable and long-running; the model call is incidental.

{"name":"repo-webhook","lane":"free_server","reason":"long-lived or addressable workload"}

Exit condition: if the watcher becomes part of an availability promise, a free server is the wrong instrument. Move it to infrastructure you own.

Leaf D — `controlled`

Example: redacting customer identifiers from support tickets before anything else touches them. Why it stops here: sensitive input plus contractual review.

{"name":"ticket-redaction","lane":"controlled","reason":"sensitive or contractual: do not route to a shared free tier"}

Exit condition: there is none that a cheaper endpoint can satisfy. This leaf exists to say no.

The artifact: a router you can run in one command

route_job.py has no dependencies and makes no network calls. It encodes the five branches as five early returns, in the order written above.

#!/usr/bin/env python3
"""route_job.py - classify an agent job into a placement lane. Python 3.9+, stdlib only."""
from __future__ import annotations
from dataclasses import dataclass, asdict
from enum import Enum
import json, sys


class Lane(str, Enum):
    LOCAL_ONLY = "local_only"
    FREE_MODEL = "free_model"
    FREE_SERVER = "free_server"
    CONTROLLED = "controlled"


class DataClass(str, Enum):
    PUBLIC = "public"
    INTERNAL = "internal"
    SENSITIVE = "sensitive"


@dataclass(frozen=True)
class JobSpec:
    name: str
    data_class: DataClass
    deterministic: bool
    idempotent: bool
    needs_inbound_endpoint: bool
    wall_clock_minutes: int
    requires_pinned_model: bool
    contractual_review: bool


def route(job: JobSpec):
    if job.deterministic:                                                  # Branch 1
        return Lane.LOCAL_ONLY, "decidable without a model; keep it off the network"
    if job.data_class is DataClass.SENSITIVE or job.contractual_review:    # Branch 2
        return Lane.CONTROLLED, "sensitive or contractual: do not route to a shared free tier"
    if job.requires_pinned_model:                                          # Branch 3
        return Lane.CONTROLLED, "pinned model required; free tiers move underneath you"
    if job.needs_inbound_endpoint or job.wall_clock_minutes > 15:           # Branch 4
        return Lane.FREE_SERVER, "long-lived or addressable workload"
    if not job.idempotent:                                                 # Branch 5
        return Lane.CONTROLLED, "non-idempotent: the cost of a duplicate is unbounded"
    return Lane.FREE_MODEL, "disposable, non-sensitive, single-shot"


def routing_record(job: JobSpec) -> dict:
    lane, reason = route(job)
    record = asdict(job)
    record["data_class"] = job.data_class.value
    record["lane"] = lane.value
    record["reason"] = reason
    return record


if __name__ == "__main__":
    with open(sys.argv[1], encoding="utf-8") as handle:
        jobs = [JobSpec(**{**raw, "data_class": DataClass(raw["data_class"])})
                for raw in json.load(handle)]
    for job in jobs:
        print(json.dumps(routing_record(job), sort_keys=True))

Steps to reproduce:

Save the file, and write a fixture jobs.json containing the four examples from the leaves above.
Run python route_job.py jobs.json | jq -c '{name, lane, reason}'.
Compare the four output lines against the expected records printed in each leaf. A mismatch is a branch-order disagreement, not a bug — decide which order you actually meant.

Expected output:

{"name":"disk-report","lane":"local_only","reason":"decidable without a model; keep it off the network"}
{"name":"changelog-draft","lane":"free_model","reason":"disposable, non-sensitive, single-shot"}
{"name":"repo-webhook","lane":"free_server","reason":"long-lived or addressable workload"}
{"name":"ticket-redaction","lane":"controlled","reason":"sensitive or contractual: do not route to a shared free tier"}

Pin every branch with a test, not a review

A decision tree that lives only in prose drifts. The file below pins the branch order. Run it with python test_route_job.py; the names also work under pytest.

# test_route_job.py
from route_job import JobSpec, DataClass, Lane, route

BASE = dict(deterministic=False, idempotent=True, needs_inbound_endpoint=False,
            wall_clock_minutes=3, requires_pinned_model=False, contractual_review=False)


def make(**overrides):
    return JobSpec(**{**BASE, **overrides})


def test_deterministic_never_leaves_the_machine():
    lane, _ = route(make(name="a", data_class=DataClass.PUBLIC, deterministic=True))
    assert lane is Lane.LOCAL_ONLY


def test_sensitive_beats_convenience():
    lane, reason = route(make(name="b", data_class=DataClass.SENSITIVE))
    assert lane is Lane.CONTROLLED and "sensitive" in reason


def test_pinned_model_beats_free_tier():
    lane, _ = route(make(name="c", data_class=DataClass.PUBLIC, requires_pinned_model=True))
    assert lane is Lane.CONTROLLED


def test_addressable_job_gets_a_server():
    lane, _ = route(make(name="d", data_class=DataClass.PUBLIC, needs_inbound_endpoint=True))
    assert lane is Lane.FREE_SERVER


def test_long_job_gets_a_server():
    lane, _ = route(make(name="e", data_class=DataClass.PUBLIC, wall_clock_minutes=45))
    assert lane is Lane.FREE_SERVER


def test_non_idempotent_never_lands_on_a_shared_model():
    lane, _ = route(make(name="f", data_class=DataClass.PUBLIC, idempotent=False))
    assert lane is Lane.CONTROLLED


def test_disposable_public_single_shot():
    lane, _ = route(make(name="g", data_class=DataClass.PUBLIC))
    assert lane is Lane.FREE_MODEL


if __name__ == "__main__":
    for name, fn in sorted(globals().items()):
        if name.startswith("test_") and callable(fn):
            fn()
            print("ok", name)

Two properties matter more than coverage. First, the assertions use is, so renaming a lane fails loudly instead of quietly changing meaning. Second, the precedence tests — test_sensitive_beats_convenience and test_pinned_model_beats_free_tier — fail the moment somebody reorders the branches. That is the point.

Turn routing records into a table you can argue with

Write one routing record per dispatch and append them to a JSONL file. Then:

jq -r '[.lane, .name] | @tsv' routing.jsonl | sort | uniq -c | sort -rn

Keep the counts next to a small ledger. Fill the cells from your own logs; do not paste numbers you have not observed.

Column	Why it is there
`job`	joins the routing record to the unit of work
`lane`	makes drift visible when a job silently changes placement
`reason`	the branch that fired — the only field that survives a rewrite
`retries`	idempotency failures show up here first
`quota_observed`	what the endpoint actually reported, not what the docs said
`review_flag`	who has to look before this job moves again

Limitations, and who should not use this

The tree is a policy encoding, not evidence about any provider. It has not been validated against your workload, and both thresholds — wall_clock_minutes > 15 and the public/internal split — are placeholders to replace with numbers from your own logs.

Do not adopt this approach if:

The workload is regulated, or the data class cannot be assigned by a named owner.
You need a contractual availability or residency guarantee. A free tier is not that, whatever today's terms say.
Your jobs need pinned model revisions. Branch 3 will keep sending them elsewhere, correctly.
You cannot write one routing record per dispatch. Without the ledger, the tree is just an opinion.

Also note that a free server is a placement, not an SLA. If the watcher in Leaf C sits on the critical path of a customer promise, label a free host as a prototype and plan the move before the promise is made.

What to do next

Before you move any job to a cheaper lane, run the fixture, pin the branches with the tests, and record the lane you chose. Then revisit the ledger monthly. The interesting column is not retries; it is reason, because that is where a changed assumption becomes visible — and a changed assumption is the only thing that should move a job between leaves.

If you want somewhere to run the free_model and free_server leaves while you build the ledger, MonkeyCode is an open-source project with free model access and a free server option. Start with the repository, run the fixture above against four of your own jobs, and compare your lanes to the expected records before you move anything real.

Evidence Grades for Agent Claims: Terms, Branches, and Six Leaves

Taylor Lin — Tue, 13 Oct 2026 00:52:11 +0000

A composite night review, not a logged incident from this account, starts with a ticket already marked ready to close. Three agent notes sit on it. One says the suite passed. One blames a flake on the runner. One calls a dependency bump safe. The sentences are complete. No exit code, command, or job id is attached.

That gap is the failure this tree is built to catch. Fluent claims close work that never produced an artifact. A reviewer who rereads the prose is still guessing. A grade is a smaller, checkable decision.

What the gate is allowed to decide

The procedure answers one question. May this claim mutate ticket state, or may it only remain a comment?

It does not rank models, estimate cost, or certify a suite. The checker later in this article is an unexecuted proposal. Nothing here is a measured production result, and no latency or accuracy figure is implied.

Glossary

Stable words matter. A loose "pass" in chat becomes a closed ticket when terms drift.

Claim. A statement an agent wants applied to a job. "Tests passed", "the flake is environmental", and "the bump is safe" are claims. Tone is not part of the definition.

Evidence packet. A host-side record with a job id, the command that ran, an exit code, and a bounded log excerpt. A paragraph of prose is not a packet, even if it sounds specific.

Grade. One of Missing, Asserted, Derived, or Observed. The grade describes the packet. It does not describe how confident the model sounded.

Leaf. A terminal branch with one allowed action. Leaves do not negotiate, and urgency in the ticket title is not a fifth grade.

Mutation. A write that changes status, merge state, or assignees. Posting a comment is not a mutation in this tree.

Host. The place that stores the packet and runs the grader. A model response is not a host, and a chat scroll is not storage.

Model call. An optional labeling step over a packet the host already has. A model call may restate a grade. It may not create missing fields.

Redaction. Removal of secrets, tokens, and customer rows before any packet leaves the host. Redaction is a precondition, not a leaf.

MonkeyCode enters only after those terms are fixed. The operator describes it as an open-source project with free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Those two availability claims are operator-supplied for this draft. This article does not name models, quotas, hardware, retention, or a time window. Confirm the current project terms before you treat either option as durable. A number read on an older page is not evidence you can plan a job around.

Free model access fits one step: suggesting a grade label for a redacted packet. The free server option fits one other step: running the same grader off a laptop, if you accept that server as a host. Neither step may promote a Missing packet to Observed.

Numbered walk

Store the claim and look for a packet on the host. If the packet is absent, assign Missing and stop. Do not call a model to invent an exit code.
Compare job ids. A packet from job A cannot support a claim about job B. A mismatch stays Missing for this claim, even if the log text looks related.
Classify the source. Exit code plus command plus log excerpt is Observed. A summary that points at a log you did not keep is Derived. A bare sentence is Asserted.
Read the requested action. Comment is not a mutation. Closing, merging, and reassigning are mutations.
Land on one leaf. Write the grade beside the claim. Apply that leaf's action and nothing stronger.

Branches

Grade	Action asked	Leaf	Allowed result
Missing, or job id mismatch	any	L0	Reject. No model call.
Asserted	comment	L1	Comment only, tagged ungraded.
Asserted	mutation	L2	Reject the mutation.
Derived	any	L3	Hold for a human with the raw artifact.
Observed, ids match	comment	L4	Comment allowed, grade recorded.
Observed, ids match	mutation	L5	No auto-close. Host re-check, then human accept.

Six leaves, four grades. L1 and L2 split Asserted by action. L4 and L5 split Observed the same way. The grade never rises because the request is urgent, cheap, or already written in confident prose.

L0, missing packet

Claim: "tests passed", job id job-18, action close. Packet: none.

The branch ends at Missing. The ticket stays open. A free model must not be asked what the exit code would have been. Guessed digits are still a missing packet.

A second case lands here too. The host has a packet, but its job_id is job-17. Related logs are not interchangeable. Treat the mismatch as Missing for job-18.

L1, asserted comment

Claim text: "Looks green from here." Fields present: job id only. Action: comment.

Grade is Asserted. The leaf allows a comment that says the note is ungraded. It does not allow a bot to move the column. The comment should quote the missing fields, not smooth them over.

L2, asserted mutation

Same Asserted claim, action close. The leaf rejects. A deadline in the title does not create a command, an exit code, or a log excerpt.

If a reviewer still wants the column to move, that is a new human action with its own reason. It is not a successful grade of the agent claim.

L3, derived summary

Packet: {"job_id": "job-18", "summary": "model says the log showed exit 0"}. The raw log was never stored. Action: close.

Grade is Derived. Hold the ticket. A human needs the artifact, not a second paraphrase. Copying the summary to a free server does not make it Observed. Another model restating "exit 0" is still Derived.

L4, observed comment

Packet includes job_id job-18, command python -m unittest tests.test_gate, exit_code 0, and a 20-line excerpt. Action: comment.

Grade is Observed. The comment may quote the exit code and the command. That is the full permission of this leaf. It is not a silent close, and it is not a claim that the suite covered every risk in the diff.

L5, observed mutation

Same Observed packet. Action: close. The leaf refuses automatic close. The host runs the recorded command again, or a human accepts the stored packet explicitly. A model may explain the excerpt. It may not be the acceptor.

Non-zero exits stay on this side of the tree if the fields are complete. They are Observed evidence of failure. They are not a prompt to shop for a kinder summary.

Proposal code

The module below is an unexecuted proposal. It encodes the leaves. It does not call a network, and it does not depend on a vendor SDK.

from enum import Enum

class Grade(Enum):
    MISSING = "missing"
    ASSERTED = "asserted"
    DERIVED = "derived"
    OBSERVED = "observed"

def grade_packet(packet, claim_job_id):
    if not packet or packet.get("job_id") != claim_job_id:
        return Grade.MISSING
    has_exit = "exit_code" in packet
    has_log = bool(packet.get("log_excerpt"))
    has_cmd = bool(packet.get("command"))
    if has_exit and has_log and has_cmd:
        return Grade.OBSERVED
    if packet.get("summary") and not (has_exit and has_log and has_cmd):
        return Grade.DERIVED
    return Grade.ASSERTED

def leaf_action(grade, action):
    if grade is Grade.MISSING:
        return "L0", "reject"
    if grade is Grade.ASSERTED and action == "comment":
        return "L1", "comment_ungraded"
    if grade is Grade.ASSERTED:
        return "L2", "reject_mutation"
    if grade is Grade.DERIVED:
        return "L3", "hold"
    if action == "comment":
        return "L4", "comment_observed"
    return "L5", "human_accept_after_host_recheck"

Expected mappings for a local check, also unexecuted in this draft:

Packet sketch	Action	Expected
`None`	close	L0, reject
`{"job_id":"job-18"}`	comment	L1, comment_ungraded
`{"job_id":"job-18"}`	close	L2, reject_mutation
`{"job_id":"job-17","command":"pytest","exit_code":0,"log_excerpt":"ok"}`	close	L0, reject
`{"job_id":"job-18","summary":"exit 0"}`	close	L3, hold
full observed fields for `job-18`	comment	L4, comment_observed
full observed fields for `job-18`	close	L5, human_accept_after_host_recheck

A host can build a packet without a model. This shell sketch is an example workflow, not a timed run. The command is fixed on purpose. Do not interpolate untrusted text into a shell.

job_id="job-18"
python -m unittest tests.test_gate > "/tmp/${job_id}.log" 2>&1
code=$?
python - "$job_id" "$code" "/tmp/${job_id}.log" <<'PY'
import json, sys
job_id, code, path = sys.argv[1], int(sys.argv[2]), sys.argv[3]
excerpt = open(path, encoding="utf-8", errors="replace").read()[-2000:]
print(json.dumps({
    "job_id": job_id,
    "command": "python -m unittest tests.test_gate",
    "exit_code": code,
    "log_excerpt": excerpt,
}))
PY

The excerpt bound is intentional. Unbounded logs and secrets do not belong in the packet. They also do not belong on a server you do not administer.

Where an optional model step sits

After the host has a grade, a model may restate it for a human comment. That helps when the reviewer wants a short note. It does not help when the grade is Missing or Derived and someone hopes wording will upgrade the leaf.

If you use free model access, send the redacted packet and the leaf table. Require the reply to echo the leaf id from leaf_action. If the reply names a stronger action than the function returned, keep the function's result. The function is the gate. The model is a narrator.

If you use the free server option, copy the grader and the redacted packet only. Do not copy environment files, credentials, or customer fixtures. Price does not describe access control. Until you have read the current retention notes, assume the packet could persist, and treat the server as a shared host.

Limitations

Four grades hide partial truth. An Observed packet can still record the wrong command. Job id match does not prove the suite covered the change. A human accept at L5 can be rubber-stamped, which turns the leaf into theater.

The tree ignores retry policy on purpose. A non-zero code is still Observed. Whether to rerun belongs in a separate rule set. Mixing those rules here would let a flake story erase an exit code.

Bounded excerpts drop context. A 2,000-character tail can miss the real failure higher in the log. Raise the bound only after you have a redaction pass, not before.

No accuracy, latency, or token figures are reported. If a page quotes a quota, verify it on the day you rely on it. This draft will not freeze a number that was not supplied as a durable term.

Who should skip it

Skip this gate if you need a formal attestation for an auditor. The tree is an engineering control, not a certification, and it keeps no tamper-evident history by itself.

Skip it if logs exist only inside a chat scroll. Build a host packet first, or accept that every claim stays Missing. A free run does not retroactively create the artifact.

Skip it if the team will override L5 whenever a run feels cheap. A gate that loses to convenience does not grade evidence. It decorates the close button.

If a sandbox for redacted packets is the missing piece, the operator points at MonkeyCode's free model access and free server option. Read the current terms, keep the leaf function authoritative, and leave secrets off that server until retention is clear to you.

Classify the Egress Leaf Before a Free Server Accepts the Card

Taylor Lin — Sun, 11 Oct 2026 21:21:20 +0000

Consider this run as a worked scene, not as a reported incident. A nightly eval card finishes on a laptop. The fixture hash matches the value recorded at build time. The writable surface is a temp directory the job created and then removed.

The next morning the same card is aimed at a free model server so the laptop can sleep. The score shifts. The diff does not.

No model note explains the move, because the model was not the object that changed. The host changed. The card never named an egress class, so the shift has no leaf to attach to.

This note is a glossary plus a decision tree for that gap. It does not rank models. It does not choose a retry. It answers one question: may this card be accepted by a host that did not build it?

Where this check sits

Place the tree before two later checks. One branches on failure class. The other pins a fixture hash before a score is allowed to leave the machine. Those checks assume the host is already legitimate.

This check decides whether a host change is even a legal move for the card. It is not a backend catalog. It does not compare providers, context windows, or prices.

MonkeyCode is the named host option in the worked leaves below. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Two availability claims are treated as operator-supplied, and only those two: free model access, and a free server option.

This draft states no model names, no numeric quota, no hardware, no duration, and no permanence. A token count is left out on purpose. It was not verified against a primary source dated 2026-10-12, and a stale allowance is an input this tree is built to reject.

If the live page does not offer either option on the day you run, the host pin is local or empty. The tree still applies. Empty fails the pin check. Local survives only when the other fields allow it.

Glossary

Fill these fields before you walk the branches. A missing field is not a default. It is a stop.

Card. The work unit. It carries a fixture id, a fixture hash, an egress class, a residue list, a host pin, a replay window, and the name of the writable surface. A prompt file by itself is not a card.
Egress class. One of machine-local, redacted-metadata, or public-fixture. You set it before the call. The server does not infer it.
Residue. The list of byte classes that would remain in a remote log, cache, or prompt store after the response returns. An empty list is a recorded claim, not a proof that the remote side forgot the call.
Host pin. The expected host identity, written before the call. local is valid. A blank string is not a pin.
Replay window. The interval during which the same fixture hash must reproduce the same score on the pinned host. The tree does not time the window. It requires the card to name one.
Leaf. The terminal result. The only legal values are hold, split, and release.

Fill the card in order

Do this before any network call. The order is the control. A later step must not rewrite an earlier one to force a friendlier leaf.

Hash the fixture bytes on the machine that owns them. Record the algorithm name beside the digest.
List residue. If you cannot name every byte class that would leave, stop and set the class to machine-local.
Write the host pin as local until a live page gives you a host string you are willing to copy.
Name the replay window in the same units your eval job already uses. Do not shorten the window to squeeze a card into release.
Name the writable surface. If the surface is unset, treat the card as incomplete and hold it, even though the sample function below does not read that field yet.

The hash command is a proposal. It was not run for this draft. Point it at a fixture you already trust, not at a ticket export.

python3 -c 'import hashlib, pathlib, sys; p = pathlib.Path(sys.argv[1]); print("sha256:" + hashlib.sha256(p.read_bytes()).hexdigest())' fixture.txt

The branches

Walk in order. The first matching step wins. Do not skip a step because a free server is idle, or because yesterday's page showed an allowance.

If egress_class is machine-local, the leaf is hold.
If residue is non-empty, the leaf is hold.
If host_pin, fixture_hash, or replay_window is blank, the leaf is hold.
If egress_class is redacted-metadata, the leaf is split.
If egress_class is public-fixture and steps 1-3 did not fire, the leaf is release.
Any other value, including a typo, is hold. Unknown is not a soft yes.

Egress class	Residue	Pins present	Leaf
machine-local	empty or not	any	hold
public-fixture	non-empty	yes	hold
any	any	no	hold
redacted-metadata	empty	yes	split
public-fixture	empty	yes	release

Leaf one: hold

Card H is a support transcript. The fixture id is ticket-1842. A template left the egress class as public-fixture. The residue list contains customer_email and session_cookie.

Step 2 matches. The leaf is hold. The free server does not get a vote, because price does not edit residue.

The next edit is the template default, not a search for a larger allowance. Keep the body on the machine that already holds the hash. If a later failure-class branch needs a label, compute that label locally and do not attach the transcript.

Leaf two: split

Card S is a public function docstring plus a local note naming the team that owns the fixture. The egress class is redacted-metadata. Residue is empty. The host pin is local-builder. The fixture hash and the replay window are both set.

Steps 1-3 do not match. Step 4 matches. The leaf is split.

The payload that may move is small and fixed: fixture id, hash, egress class, and a failure-class label already computed on the builder. The docstring body, the ownership note, and the writable-surface path stay.

A free model server is eligible only for that metadata-sized call, and only after you replace the placeholder pin with a host string copied that day. The score allowed to leave the machine remains the local score. The remote response does not replace it.

If the client sends the whole card unless you pass an allowlist, do not use that client for a split leaf. The leaf would describe a call you did not make.

Leaf three: release

Card R is a synthetic docstring checked into the repo. It was generated from a fixed seed. It has no personal names and no machine paths.

The egress class is public-fixture. Residue is empty. The host pin is the placeholder free-server until a live page names a real host. The fixture hash is present. The replay window is 24h.

Steps 1-4 do not match. Step 5 matches. The leaf is release.

Release means eligible. It does not mean the server is reachable, inexpensive, or unchanged since last week. Copy the host string published on the run date into host_pin. If that page publishes no host string, clear the pin. The next walk hits step 3 and holds the card.

That fallback is the reason to write the pin before the call, not after a surprising score.

Classifier

This module is a proposal. It was not executed while drafting. It implements the six steps and rejects unknown classes.

from dataclasses import dataclass

@dataclass(frozen=True)
class Card:
    fixture_id: str
    egress_class: str
    residue: tuple
    host_pin: str
    fixture_hash: str
    replay_window: str

def classify(card: Card) -> str:
    if card.egress_class == "machine-local":
        return "hold"
    if card.residue:
        return "hold"
    if not (card.host_pin and card.fixture_hash and card.replay_window):
        return "hold"
    if card.egress_class == "redacted-metadata":
        return "split"
    if card.egress_class == "public-fixture":
        return "release"
    return "hold"

Pair it with an oracle. The expected strings are the specification. If a run disagrees, change the function or change the glossary. Do not edit the printout to match a wish.

from egress_leaf import Card, classify

CASES = [
    (Card("ticket-1842", "public-fixture", ("customer_email",), "local", "sha256:abc", "24h"), "hold"),
    (Card("doc-17", "redacted-metadata", (), "local-builder", "sha256:def", "24h"), "split"),
    (Card("seed-04", "public-fixture", (), "free-server", "sha256:9f2c", "24h"), "release"),
    (Card("seed-04", "public-fixture", (), "", "sha256:9f2c", "24h"), "hold"),
    (Card("seed-04", "public-fixtre", (), "free-server", "sha256:9f2c", "24h"), "hold"),
]

def main() -> None:
    failed = 0
    for card, expected in CASES:
        got = classify(card)
        if got != expected:
            failed += 1
            print(f"FAIL {card.fixture_id}: got {got}, expected {expected}")
        else:
            print(f"OK {card.fixture_id}: {got}")
    raise SystemExit(failed)

if __name__ == "__main__":
    main()

Save the first file as egress_leaf.py and the second as check_egress_leaves.py. Then run the oracle.

python3 check_egress_leaves.py

You should see five OK lines and exit code 0. The fifth case is a misspelled class, and the legal result is hold. A non-zero exit means the tree and the oracle diverged.

Limits

The tree does not estimate cost, latency, or quality. It will release a public fixture onto a weak host and hold a sensitive card back from a strong one. That bias is intentional.

A release leaf with a placeholder pin is only safe until the first real call. Replace the placeholder or clear it. Free model access and a free server option are ways to fill host_pin. They are not reasons to skip residue, and they are not a retention policy or a region list.

If your program needs those facts, read them from a current primary page and record the date beside the pin. This article cannot supply them. The sample classifier also ignores the writable-surface name. That is a gap. Until you add the field, keep the manual step and treat an unnamed surface as hold.

Who should skip it

Skip the tree for customer content, credentials, session material, or any card whose residue you cannot list. Skip it when policy requires a signed data-processing agreement before an off-machine call. There is no field for that signature, so the honest leaf is hold.

Skip it as a capacity plan. An option that is free on the day you read the page is not a forecast for next week. Keep any existing route-by-data-class check and any failure-class branch. This tree does not retire them. It only refuses a card that has not earned an egress leaf.

When a card does reach split or release, open the current MonkeyCode project page, copy the host string it publishes, and only then set host_pin. If the page and this draft disagree, the page wins.

Branch on Failure Class Before the Host or the Model Moves

Taylor Lin — Sat, 10 Oct 2026 17:45:41 +0000

A scheduler prints step 4 failed at 02:14. The wrapper does what a tired script usually does: it resubmits the same prompt. The first host is busy, so the job lands somewhere else. A helper also swaps the model route, because a free endpoint answered first.

The new diff is green. The allowlist was not read again. Nothing in the log says whether the failure was a timeout, a schema miss, or a tool call outside the named surface.

That sequence is not a retry. It is three decisions collapsed into one button. This walkthrough splits them into a glossary, an ordered tree, and a function you can run on local rows.

The scenario is a composite, used to show the branches. It is not a report from a named fleet, and it carries no measured failure rate.

Terms the tree will accept

Use the same words on the job card, the log line, and the review note. If a field is missing, the tree has no input, and the only legal output is stop.

Step binding. The host id, the model route id, and the input snapshot id for one attempt. Change any field and you have a new binding, not a second try of the old one.

Input snapshot. A content id for the prompt, the tool schema, and the fixture ids the step may read. How you compute that id is out of scope here. The tree only needs equality: same snapshot, or not.

Failure class. A closed label for why the attempt missed its contract. unknown is allowed. It is also a stop, not a prompt to let another model invent the label.

Same-binding retry. Same host, same route, same snapshot. Only the attempt counter moves.

Compute move. The host changes. The route and the snapshot stay. Use it for reachability, not for a better answer.

Route narrowing. The route changes to a smaller, tools-off, read-only call. The reply is stored as a sketch. Accepting that sketch is a later job, not this leaf.

Halt. No socket is opened. A person reads the attempt record before any new binding exists.

Attempt record. One row: failure_class, attempt, writes, tools_enabled, snapshot_same. The function below reads only those fields.

Checks, in order

First match wins. Do not also move the host because a later leaf looks cheaper.

If failure_class is empty or unknown, return halt. A missing label is not repaired by another call.
If failure_class is scope_creep, return halt. A write or tool call outside the allowlist is not a transport fault. A new host would copy it.
If writes or tools_enabled is true, and the class is contract_miss or score_wobble, return halt. A writing step that failed its schema does not become safe on a narrower route.
If the class is transport, attempt is 1, and the snapshot matches, return same-binding retry. One quiet resubmit. Not a loop.
If the class is transport, attempt is greater than 1, and the snapshot matches, return compute move. Keep the model route string byte-for-byte.
If the class is contract_miss, writes is false, and tools are off, return route narrowing. Ask for one labeled field. Do not turn tools back on so the model can look around.
Every other row returns halt. That includes score_wobble on a read-only step. Two scores are a record. They are not a cue to sample until one looks clean.

One worked row per leaf

The rows are illustrations. They are not excerpts from a production log.

Halt, unknown class. {failure_class: "unknown", attempt: 1, writes: false, tools_enabled: false, snapshot_same: true}. Open the raw stderr and assign a class by a fixed rule. Do not spend a free call to justify the next free call.

Halt, scope creep. {failure_class: "scope_creep", attempt: 1, writes: true, tools_enabled: true, snapshot_same: true}. Freeze the card. The next machine must not receive this prompt until the allowlist and the diff have been read. A spare server is still a server.

Halt, writing contract miss. {failure_class: "contract_miss", attempt: 1, writes: true, tools_enabled: false, snapshot_same: true}. Keep the bad output beside the schema error. A second sample can parse and still name the wrong path.

Same-binding retry. {failure_class: "transport", attempt: 1, writes: false, tools_enabled: false, snapshot_same: true}. Resubmit once. Same host id, same route id. If the counter would become 3, this leaf no longer applies.

Compute move. {failure_class: "transport", attempt: 2, writes: false, tools_enabled: true, snapshot_same: true}. Select a host that can read the same snapshot and the same route. Tools stay as they were. You moved compute. You did not relax policy.

Route narrowing. {failure_class: "contract_miss", attempt: 1, writes: false, tools_enabled: false, snapshot_same: true}. Send a shorter prompt that requests a single field, with tools disabled. Store the reply as a sketch. Promotion stays a separate card.

Halt, score wobble. {failure_class: "score_wobble", attempt: 2, writes: false, tools_enabled: false, snapshot_same: true}. Keep both numbers. Do not average them. Do not call again to break the tie.

A snapshot mismatch on a transport failure also halts. If the bytes changed, you are not retrying. You are running a different step.

failure_class	attempt	writes	tools	snapshot_same	leaf
unknown	1	false	false	true	halt
scope_creep	1	true	true	true	halt
contract_miss	1	true	false	true	halt
transport	1	false	false	true	same_binding_retry
transport	2	false	true	true	compute_move
contract_miss	1	false	false	true	route_narrowing
score_wobble	2	false	false	true	halt
transport	2	false	false	false	halt

Run the leaves locally

This function is a proposal. It does not open a network connection. It does not know which vendor string you will later attach to a leaf. Run it before you trust the table above; the assertions are the table, encoded.

from dataclasses import dataclass

@dataclass(frozen=True)
class Attempt:
    failure_class: str
    attempt: int
    writes: bool
    tools_enabled: bool
    snapshot_same: bool

def decide(row: Attempt) -> str:
    if row.failure_class in {"", "unknown"}:
        return "halt"
    if row.failure_class == "scope_creep":
        return "halt"
    if (row.writes or row.tools_enabled) and row.failure_class in {
        "contract_miss",
        "score_wobble",
    }:
        return "halt"
    if (
        row.failure_class == "transport"
        and row.attempt == 1
        and row.snapshot_same
    ):
        return "same_binding_retry"
    if (
        row.failure_class == "transport"
        and row.attempt > 1
        and row.snapshot_same
    ):
        return "compute_move"
    if (
        row.failure_class == "contract_miss"
        and not row.writes
        and not row.tools_enabled
    ):
        return "route_narrowing"
    return "halt"

def test_leaves() -> None:
    assert decide(Attempt("unknown", 1, False, False, True)) == "halt"
    assert decide(Attempt("scope_creep", 1, True, True, True)) == "halt"
    assert decide(Attempt("contract_miss", 1, True, False, True)) == "halt"
    assert decide(Attempt("transport", 1, False, False, True)) == "same_binding_retry"
    assert decide(Attempt("transport", 2, False, True, True)) == "compute_move"
    assert decide(Attempt("contract_miss", 1, False, False, True)) == "route_narrowing"
    assert decide(Attempt("score_wobble", 2, False, False, True)) == "halt"
    assert decide(Attempt("transport", 2, False, False, False)) == "halt"

Save it as retry_tree.py. Then:

python -m py_compile retry_tree.py
python -c "import retry_tree; retry_tree.test_leaves(); print('leaves_ok')"

py_compile only checks syntax. The second command runs the eight assertions. If one fails, the table and the function have drifted. Edit the table before you edit the function. Do not delete a leaf to make the command quiet.

Two leaves can name a vendor option

The other leaves stay vendor-free. Compute move may set the new host id to a free server when the operator has confirmed that option. The model route does not change. Route narrowing may set the route to free model access when that option is confirmed, and only for a read-only call with tools off.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is relevant only on those two leaves, and only if the current offer matches what the operator confirmed. This article does not state model names, token quotas, hardware, regions, or duration. Those facts go stale quickly, and a hard-coded quota in a job card is worse than a missing host id. Read the operator's current docs, then write the host id and the route id into config. If either option is absent, point compute move at any approved spare host and point route narrowing at any approved smaller route. The tree still holds.

Limits of the function

decide does not parse stderr. Something else must set failure_class before this runs. Prefer a deterministic map: timeout with an empty body is transport; a schema error is contract_miss; an allowlist miss is scope_creep; a changed score on an unchanged snapshot is score_wobble. If that map is itself a model call, its mistakes become silent halts or silent moves.

The same-binding leaf allows one extra attempt. A disk that fails twice is a ticket, not a third call. Raise the cap only with a written reason in the attempt record, not with a while loop in the worker.

Compute move assumes the new host can address the same snapshot. A snapshot that lives only on the first machine makes the leaf invalid. Return halt until the snapshot is published to a path both hosts can read.

Route narrowing refuses tools and writes. A task that cannot be asked as a single labeled field does not get that leaf. It gets halt. Shrinking the prompt until it fits is a review decision, not a retry-worker decision.

Who should not use this

Skip the tree if attempt records do not already store a write bit and a tool bit. Guessing those flags inside the retry script rebuilds the one-button wrapper this walkthrough is trying to retire.

Skip it for interactive chat. There is no step boundary, no allowlist, and no snapshot id. The leaves assume a job card.

Skip compute move when policy forbids a data set on a shared or free host. The function cannot see that policy unless you encode the denial as halt before decide runs. Do not add a silent exception for a single job.

Skip it if you need a quality comparison between models. Nothing here measures accuracy, latency, or cost. A green leaves_ok line means the branches match the table. It does not mean a route is good.

Put the halt in front of the socket

Store the eight rows as fixtures, and call decide before the worker opens a connection. On compute_move or route_narrowing, copy the host or the route from operator-confirmed config, and write the new binding beside the old one. On halt, the next artifact is a review note. Another call is the failure mode, not the fix.

Pin the Fixture Hash Before an Agent Score Leaves the Machine

Taylor Lin — Fri, 09 Oct 2026 14:06:19 +0000

Thursday's pagination card looked done. The agent summary said the tests passed, and the diff touched only list_users.py plus one fixture. Monday's clean worktree failed the same card. The prompt was identical; the sample payload was not.

That gap is what this workflow classifies. A free model call cannot repair a fixture that was never pinned. A free server cannot make two runs comparable when they saw different files.

The walkthrough is a constructed example, not a measured incident. No pass rates are claimed. Use the branch logic locally before any hosted seat is involved.

Glossary

Use these terms as written on the task card. If a field cannot be filled, the tree treats it as missing, and missing is a result rather than a prompt to guess.

Task card. One agent job with a goal, inputs, and the files it may read. A chat transcript is not a task card.

Fixture bundle. Pinned inputs plus the oracle that judges the result. A folder of whatever happened to be in the repo this morning is not a bundle.

Oracle kind. How correctness is judged. This workflow allows pytest, schema, or human. An empty value means there is no oracle.

Mutation scope. What the run may change. Allowed values are read_only, workspace, network, and secrets.

Writable root. The single directory a workspace run may write. If it is unset, the write surface is unnamed.

Leak flag. True when the bundle holds credentials, customer rows, or anything you would not paste into a shared runner.

Stale window. Hours after which a fixture hash is no longer accepted for scoring. You pick the number for your suite. This text does not set a vendor default.

Runner seat. Where the model call and the tool host execute. Store an operator-filled label. Do not infer the seat from a price tier.

Score receipt. A small JSON record of leaf, hash, oracle kind, mutation scope, and runner seat. A model summary is not a receipt.

The four-leaf decision tree

Evaluate the checks in order. Stop at the first match. Later checks do not rescue an earlier failure.

If oracle_kind is missing, or leak_flag is true, the leaf is refuse.
Else if scope is network or secrets, or scope is workspace without a writable root, the leaf is quarantine.
Else if fixture_sha256 is missing, or age_hours exceeds stale_after_hours, the leaf is refresh.
Else the leaf is score.

Order	Condition	Leaf	Next action
1	No oracle, or leak flag set	refuse	Do not call a model
2	Network, secrets, or unnamed writes	quarantine	Do not upload the bundle
3	Missing hash, or past the stale window	refresh	Rebuild locally; do not score
4	Pinned, fresh, and bounded	score	Bind a runner seat, then run

A free seat does not reorder the table. It is only a candidate after row 4.

Numbered workflow

Write the task card in one file. Name the oracle kind before you open a model session.
Hash the fixture bundle on your machine. Store the digest beside the card, not inside the prompt.
Set mutation scope. If scope is workspace, set exactly one writable root. Reject a card that says "edit the repo" and names no path.
Run the classifier. Branch on the leaf. Do not override refuse or quarantine because a hosted seat is idle.
On score only, bind a runner seat. Keep that model call off any host that can read production credentials.
Write the score receipt in the same commit as the hash. If the seat label is unknown, leave it blank. Do not invent one.

Artifact: classify_fixture.py

Save the following as classify_fixture.py. It is proposal code: run it yourself. It does not contact a network API, and the asserts only lock the branch order.

"""Classify an agent fixture before any runner seat is bound."""

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum
import hashlib
import json
from pathlib import Path


class Leaf(str, Enum):
    REFUSE = "refuse"
    QUARANTINE = "quarantine"
    REFRESH = "refresh"
    SCORE = "score"


@dataclass(frozen=True)
class FixtureCard:
    oracle_kind: str | None
    mutation_scope: str
    writable_root: str | None
    fixture_sha256: str | None
    age_hours: float
    stale_after_hours: float
    leak_flag: bool


def classify(card: FixtureCard) -> Leaf:
    if not card.oracle_kind or card.leak_flag:
        return Leaf.REFUSE
    unsafe_scope = card.mutation_scope in {"network", "secrets"}
    unnamed_write = card.mutation_scope == "workspace" and not card.writable_root
    if unsafe_scope or unnamed_write:
        return Leaf.QUARANTINE
    if not card.fixture_sha256 or card.age_hours > card.stale_after_hours:
        return Leaf.REFRESH
    return Leaf.SCORE


def bundle_sha256(paths: list[Path]) -> str:
    digest = hashlib.sha256()
    for path in sorted(paths, key=lambda item: item.as_posix()):
        digest.update(path.as_posix().encode())
        digest.update(b"\0")
        digest.update(path.read_bytes())
        digest.update(b"\0")
    return digest.hexdigest()


def receipt(card: FixtureCard, seat: str | None) -> dict:
    leaf = classify(card)
    return {
        "leaf": leaf.value,
        "oracle_kind": card.oracle_kind,
        "mutation_scope": card.mutation_scope,
        "fixture_sha256": card.fixture_sha256,
        "runner_seat": seat if leaf is Leaf.SCORE else None,
    }


if __name__ == "__main__":
    refuse = FixtureCard(None, "read_only", None, "abc", 1, 24, False)
    leak = FixtureCard("pytest", "read_only", None, "abc", 1, 24, True)
    quarantine = FixtureCard("pytest", "secrets", None, "abc", 1, 24, False)
    unnamed = FixtureCard("pytest", "workspace", None, "abc", 1, 24, False)
    refresh = FixtureCard(
        "pytest", "workspace", "/tmp/eval/pagination", None, 3, 24, False
    )
    stale = FixtureCard("pytest", "read_only", None, "abc", 48, 24, False)
    score = FixtureCard(
        "pytest", "workspace", "/tmp/eval/pagination", "abc", 3, 24, False
    )
    assert classify(refuse) is Leaf.REFUSE
    assert classify(leak) is Leaf.REFUSE
    assert classify(quarantine) is Leaf.QUARANTINE
    assert classify(unnamed) is Leaf.QUARANTINE
    assert classify(refresh) is Leaf.REFRESH
    assert classify(stale) is Leaf.REFRESH
    assert classify(score) is Leaf.SCORE
    print(json.dumps(receipt(score, seat=None), indent=2))

Run the classifier, then pin a real bundle with files you already have:

python3 classify_fixture.py
find fixtures/pagination -type f -print0 | sort -z | xargs -0 shasum -a 256

The first command should print a score receipt with runner_seat set to null. The second prints digests you computed. Paste a digest into the card. Do not ask a model to invent it.

python3 - <<'PY'
import hashlib
import pathlib
path = pathlib.Path("fixtures/pagination/sample.json")
print(hashlib.sha256(path.read_bytes()).hexdigest())
PY

Local test plan

Case	Distinct input	Expected leaf
empty oracle	`oracle_kind` is null	refuse
leak flag	oracle set, `leak_flag` true	refuse
secrets scope	`mutation_scope` is `secrets`	quarantine
unnamed write	`workspace` and root null	quarantine
missing hash	hash null, age inside window	refresh
stale hash	hash set, age 48, window 24	refresh
ready card	pinned, fresh, workspace root set	score

All seven asserts in __main__ must pass before you bind a seat. If you reorder the leaves, change the asserts in the same edit. A green model demo does not replace that check.

Worked leaf: refuse

Card text: "make the users page feel faster." Oracle kind is empty. Leak flag is false. Scope is read_only. A hash may even be present. It does not matter.

The classifier returns refuse. Stop. There is no judgment to record, so a model paragraph would only look like a score. Write the receipt and close the card until an oracle exists.

{"leaf":"refuse","oracle_kind":null,"mutation_scope":"read_only","fixture_sha256":null,"runner_seat":null}

A schema check on page size is enough to leave this leaf later. A summary that says the page looks faster is not an oracle kind.

Worked leaf: quarantine

Card text: "hit staging and confirm pagination." Oracle kind is pytest. Scope is secrets because .env holds a staging token. You might have left leak_flag false. Scope alone is enough to stop.

The leaf is quarantine. Do not upload the bundle to a shared server, free or otherwise. Do not paste the token into a prompt to save a step. Delete the secret and reclassify, or run tools only on a machine you already control, outside this tree.

Quarantine is a block, not a softer score. Idle capacity does not reclassify it.

Worked leaf: refresh

Card: pagination regression. Oracle kind is pytest. Scope is workspace. Writable root is /tmp/eval/pagination. The sample file is 90 hours old. The stale window on the card is 24. The hash field is empty.

The leaf is refresh. Rebuild the expected body from the spec you checked in, then hash the bundle. Do not record a model score against the old file. Two greens on different payloads are not a comparison.

After the digest is stored and age is reset by that rebuild, run classify again. Only a new score result continues. Keep the refresh receipt so the gap stays visible.

{"leaf":"refresh","oracle_kind":"pytest","mutation_scope":"workspace","fixture_sha256":null,"runner_seat":null}

Worked leaf: score

Same pagination card, now pinned. Oracle kind is pytest. Scope is workspace. Writable root is set. Hash is present. Age is 3 hours. Stale window is 24. Leak flag is false.

The leaf is score. Bind a runner seat in the receipt before the call. Keep the model call off any host that can read production credentials.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. One seat you may fill, if it matches your constraints, is MonkeyCode's free model access on its free server option. This article does not name models, token quotas, hardware, or how long that option remains available. Check the current product terms before you depend on them.

{
  "leaf": "score",
  "oracle_kind": "pytest",
  "mutation_scope": "workspace",
  "fixture_sha256": "<digest you computed>",
  "runner_seat": "operator-filled-label"
}

If the seat label is still unknown, leave it null and do not start the run. A missing seat is an incomplete receipt. It is not a default to whichever seat happens to be free.

How to read a failed receipt

A failed receipt is still a result. Store it next to the card so the next run does not start from chat memory.

If leaf is refuse, the missing piece is the oracle or a raised leak flag. Fix the card. Do not tune the prompt to talk past the gap.

If leaf is quarantine, the bundle is not eligible for a shared seat. Removing a secret is a fixture edit. That edit needs a new hash and a new classification. Do not reuse the old digest.

If leaf is refresh, the score field stays empty. A model may be used only after the hash exists. Calling it during refresh mixes a draft file into the baseline.

If leaf is score and runner_seat is null, the run has not started. Fill the seat from documentation you checked the same day. A seat name copied from an old post is not evidence.

What this does not prove

A score leaf means the fixture is comparable enough to run. It does not mean the patch is correct, secure, or cheaper than a local model. The asserts only prove branch order in this script.

Free model access and a free server option are availability claims supplied for this draft. They are not a benchmark, a capacity promise, or a reason to skip refuse and quarantine. If the vendor page disagrees with this text, trust the vendor page.

Hashes catch file drift. They do not catch a wrong spec. If the pinned oracle expects the bug, every model can pass by preserving it. Review the oracle before you treat the receipt as a quality signal.

Who should skip this workflow

Skip it for regulated data, production secrets, or unbounded network writes. Quarantine is the ceiling of this tree, not a hosting guide for those cards.

Skip it if you need an uptime commitment. Nothing here selects a free seat for reliability, latency, or retention.

Skip it if people will edit refuse results into score to keep a demo moving. The receipt is useless once leaves are rewritten after the fact.

For a card that already classifies as score, bind the seat from the MonkeyCode documentation you checked today, and keep that receipt beside the diff. If those docs and this tree disagree, follow the docs and leave the seat blank until the card still lands on score.

Route Agent Job Cards by Data Class, Not by Token Balance

Taylor Lin — Thu, 08 Oct 2026 09:45:41 +0000

Consider a library maintainer with a red CI job and a thirty-minute window before a demo. A teammate pasted a .env file, a customer export, and the failing workflow into a remote agent session and asked for a deploy fix.

The diff came back tidy. The session log still held the export two hours later. The patch was not the failure. The unnamed venue was the failure: nobody had decided which bytes could leave the laptop, or which side effects a free remote runner was allowed to attempt.

This draft is a routing procedure for that decision. It classifies a job card into a venue, then names the evidence that venue can honestly produce. It does not score models, and it does not report a benchmark.

Time-sensitive product claims are limited to an operator briefing dated 2026-10-08. Figures that were not in that briefing are omitted rather than estimated.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode enters only after the route is chosen. The briefing describes it as an open-source project with free model access, a stated free allowance of 10 million tokens, and a free server option. Those are availability claims, not a hardware spec, a latency number, a named model list, or a promise that the allowance will exist next month. Recheck the project docs on the day you run. Remove every product mention and the router still applies to any remote runner with the same constraints.

Glossary

Seven terms keep the later tree small. Each one is an input or an output of the router, not a slogan.

Job card. A record with a goal, a data class, a side-effect class, and the exact files the agent may read. No card, no run.
Data class. One of synthetic, public_repo, internal_code, or restricted. Restricted covers secrets, credentials, customer records, and anything policy forbids leaving the machine.
Side-effect class. One of none, local_write, sandbox_write, or external_effect. External effect means push, deploy, email, ticket mutation, or a production API call.
Venue. Where the prompt may be seen and where writes may happen: local_static, free_remote_sketch, remote_text_local_rerun, or owned_sandbox. A fifth result, refuse, means the card is incomplete.
Allowance. A consumable quota for model calls. The 2026-10-08 briefing states a free allowance of 10 million tokens. It does not state a reset period, a per-model split, or a concurrency cap, so this draft does not invent them.
Evidence packet. Job card, venue JSON, command log, diff, and test output from a machine you control. A remote string that says done is not a packet.
Prompt residue. Any secret, customer row, or unreleased path left in a remote session. Residue fails the route even when the diff is correct.

Decision table

Read the table before the narrative tree. The first matching row wins.

Data class	Side effect	Owned sandbox	Venue	Remote may see files	Remote may act
restricted, or a sensitive filename	any	any	local_static	no	no
synthetic	none or local_write	not required	free_remote_sketch	yes, listed files only	no
public_repo or internal_code	not external_effect	not required	remote_text_local_rerun	yes, listed files only	no
any non-restricted	external_effect	yes	owned_sandbox	no	no
anything else	external_effect	no	refuse	no	no

Public contribution sprints make the third row common. The repo is already public. The temptation is to let the runner push the branch. The table still says no.

Internal code is not a free pass into that third row. Use it only when your own rules already allow that source to leave the machine. If they do not, mark the card restricted and the same files fall to row one.

The tree, as numbered steps

If data class is restricted, or the file list contains env files, key files, or customer exports, stop. Venue is local_static.
Else if data class is synthetic and the side effect is none or local_write inside a fixture directory, venue is free_remote_sketch.
Else if data class is public_repo or internal_code, and the side effect is not external_effect, venue is remote_text_local_rerun.
Else if an external effect is required and the card names a sandbox your team administers, venue is owned_sandbox.
Else refuse the job. A missing sandbox plus an external effect is not fixed by a longer prompt.

Token balance is not a step. A large remaining allowance does not promote a card into a looser row.

Leaf 1, local static

Card: goal is to explain a login failure. Data class is restricted. Files are .env and customers.csv.

The router returns local_static. Those files do not go to a remote session, free or otherwise. You inventory the tree, scan for known secret shapes, and rewrite the question against a synthetic fixture you are willing to send later.

# Proposed commands. Not executed for this draft.
git status --short
rg -n --hidden -g '!.git' 'AKIA|BEGIN .*PRIVATE KEY|password\s*=' .
python3 venue_route.py --card cards/login_debug.json --assert-venue local_static

Worked packet: route JSON with venue local_static, the scan match count from your machine, and a statement that remote calls were zero. If the scan matches, the original card stays closed until the fixture exists. That is the whole leaf. There is no second step that tries the free server with the real export.

A renamed key file can miss the filename denylist. Treat the scan as part of this leaf, not as an optional extra. The denylist in the sample code is a backstop for obvious names only.

Leaf 2, free remote sketch

Card: goal is to parse fixtures/events.json. Data class is synthetic. Side effect is local_write. Files are limited to the fixture, src/parse_events.py, and tests/test_parse_events.py.

The router returns free_remote_sketch. This is the leaf where free model access and the free server option are in scope. Send the listed files only. Record reported token use if the product surfaces it. Do not fill in a remainder; the briefing did not define how usage is counted.

After the sketch returns, acceptance happens on your machine.

# Proposed. Your machine, not the remote runner.
git apply --check sketch.diff
pytest tests/test_parse_events.py -q
python3 venue_route.py --card cards/parser.json --assert-venue free_remote_sketch

Worked packet shape, with blanks you fill from your own run:

venue=free_remote_sketch
remote_calls=1
local_pytest_exit=
files_changed=
push_attempted=no

A blank local_pytest_exit means the leaf is unfinished. The allowance, stated as 10 million tokens in the briefing, is spent on this kind of fixture. It is not a reason to widen the file list.

Leaf 3, remote text and local rerun

Card: goal is to fix an off-by-one in a public sample's pagination helper. Data class is public_repo. Side effect is local_write. No deploy and no push.

The router returns remote_text_local_rerun. The free server may read the public files and return a diff. It may not push, open a pull request, or call a package registry. A contribution sprint does not move that boundary. The branch move stays on a machine that holds your credentials.

python3 venue_route.py --card cards/pagination.json --assert-venue remote_text_local_rerun
git apply --check pagination.diff
pytest tests/test_pagination.py -q
git diff --stat

Store a form, not a fabricated measurement:

venue=remote_text_local_rerun
remote_calls=1
local_pytest_exit=
files_changed=
push_attempted=no

If the only copy of the test log lives on the free server, you do not have this leaf. You have a transcript. Copy the diff back, rerun, and keep the exit code next to the card.

Leaf 4, owned sandbox

Card: goal is to apply a migration to staging. Data class is internal_code. Side effect is external_effect. The card names a sandbox host the team administers.

The router returns owned_sandbox. A free server is the wrong place to hold a migration credential, even when the token allowance would cover the prompt. Do not attach that runner. If you want a SQL draft, produce it on a machine that already has a schema fixture and does not need the DSN in the prompt. A person runs the SQL on the sandbox, with a transaction opened first and a rollback written down before execution.

python3 venue_route.py --card cards/migration.json --assert-venue owned_sandbox
# Human step on the sandbox you control. Not a free-server step.
psql "$STAGING_DSN" -v ON_ERROR_STOP=1 -c 'BEGIN;' -f migration.sql

Worked packet: route JSON, SQL diff, sandbox host name, and the transaction outcome from that host. A remote transcript is not required. If one exists and it contains the DSN, the route failed. The useful next step is rotation, not a cleaner prompt.

Refuse, the guardrail

Card: goal is to deploy a preview. Side effect is external_effect. owned_sandbox is false.

The router returns refuse. There is no extra venue called try-it-and-watch. Close the card, or name a sandbox you administer. Then the job can re-enter at leaf 4.

Router code

The classifier below is proposal code for this workflow. It was not executed against a live account for this draft. It performs no network call. It only reads a local JSON card.

#!/usr/bin/env python3
"""Classify a job card into a venue. Proposal: no model call."""
import argparse
import json
import sys

RESTRICTED_NAMES = {".env", ".env.local", "id_rsa", "customers.csv", "secrets.json"}

def route(card: dict) -> dict:
    files = set(card.get("files") or [])
    data = card.get("data_class")
    effect = card.get("side_effect")
    reasons = []
    if data == "restricted" or files & RESTRICTED_NAMES:
        reasons.append("restricted payload or sensitive filename")
        venue = "local_static"
    elif data == "synthetic" and effect in {"none", "local_write"}:
        reasons.append("synthetic fixture, no external effect")
        venue = "free_remote_sketch"
    elif data in {"public_repo", "internal_code"} and effect != "external_effect":
        reasons.append("text may leave; effects stay local")
        venue = "remote_text_local_rerun"
    elif effect == "external_effect" and card.get("owned_sandbox"):
        reasons.append("effect required; sandbox is team-owned")
        venue = "owned_sandbox"
    else:
        reasons.append("no safe leaf")
        venue = "refuse"
    return {
        "venue": venue,
        "reasons": reasons,
        "remote_may_see_files": venue in {
            "free_remote_sketch",
            "remote_text_local_rerun",
        },
        "remote_may_effect": False,
    }

def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--card", required=True)
    parser.add_argument("--assert-venue")
    args = parser.parse_args()
    with open(args.card, encoding="utf-8") as handle:
        decision = route(json.load(handle))
    json.dump(decision, sys.stdout, indent=2)
    sys.stdout.write("\n")
    if args.assert_venue and decision["venue"] != args.assert_venue:
        return 2
    return 0 if decision["venue"] != "refuse" else 3

if __name__ == "__main__":
    raise SystemExit(main())

Leaf-2 card:

{
  "goal": "parse fixtures/events.json",
  "data_class": "synthetic",
  "side_effect": "local_write",
  "files": ["fixtures/events.json", "src/parse_events.py"],
  "owned_sandbox": false
}

Proposed checks, not run for this draft:

# tests/test_venue_route.py
from venue_route import route

def test_four_leaves_and_refuse():
    assert route({"data_class": "restricted", "side_effect": "none", "files": []})["venue"] == "local_static"
    assert route({"data_class": "synthetic", "side_effect": "local_write", "files": ["fixtures/events.json"]})["venue"] == "free_remote_sketch"
    assert route({"data_class": "public_repo", "side_effect": "local_write", "files": ["src/page.py"]})["venue"] == "remote_text_local_rerun"
    assert route({"data_class": "internal_code", "side_effect": "external_effect", "files": ["migration.sql"], "owned_sandbox": True})["venue"] == "owned_sandbox"
    assert route({"data_class": "public_repo", "side_effect": "external_effect", "owned_sandbox": False, "files": []})["venue"] == "refuse"

def test_filename_backstop():
    card = {"data_class": "synthetic", "side_effect": "none", "files": [".env"]}
    assert route(card)["venue"] == "local_static"
    assert route(card)["remote_may_effect"] is False

python3 venue_route.py --card cards/parser.json --assert-venue free_remote_sketch
python3 venue_route.py --card cards/login_debug.json --assert-venue local_static
python3 venue_route.py --card cards/pagination.json --assert-venue remote_text_local_rerun
python3 venue_route.py --card cards/migration.json --assert-venue owned_sandbox
python3 venue_route.py --card cards/deploy_preview.json --assert-venue refuse

Exit code 3 on the last command is success for the guardrail. Exit code 2 means the card and the expected venue disagree. That is a bug in the card or in route, not a reason to override the tree by hand.

Runbook

Write the job card before opening any session. Data class, side-effect class, file list, and sandbox flag are required fields.
Run the router. Store the JSON in the evidence packet beside the card.
On local_static or refuse, stop. Build a synthetic fixture or name a sandbox. Do not negotiate the leaf inside the prompt.
On free_remote_sketch or remote_text_local_rerun, attach only listed files. Free model access and the free server option are sufficient for the sketch, inside the stated token allowance. Do not grant push credentials to that runner.
Apply with git apply --check, then rerun the narrow test on a machine you control. Store the exit code.
On owned_sandbox, a person performs the effect inside that sandbox. The free server never receives the credential. Record the sandbox outcome, not the chat summary.

Limits of the method

The router does not measure patch quality. It does not compare products. It does not claim the 10 million token figure is permanent, per-organization, or tied to a named model. The briefing stated the allowance and stopped there.

It also does not claim the free server meets a specific isolation standard. If policy requires a residency region, a retention window, or a subprocessor list, those facts have to come from current project documentation, not from this article.

The filename denylist is short on purpose. Extend it from your own secret inventory, then keep that list in the repo that runs the router. A green local test still says nothing about files the remote runner saw outside the card. If you cannot reconstruct the file list from the session, discard the sketch and start from a new card.

Who should skip it

Skip the remote leaves when a contract forbids source leaving a named network boundary. Skip them when the only failing test needs production rows to reproduce. Skip the tree entirely if you wanted a model leaderboard. It will not produce one.

Teams that already block outbound copy of secrets can still adopt the card. The review gate then receives a venue field and a local exit code, which is a smaller artifact than a full transcript.

If you already have a synthetic leaf-2 card, the free model access and free server option from the 2026-10-08 briefing are enough to draft the first patch, after you recheck the current allowance and server terms. Keep the evidence packet on your machine either way.

DEV Community: Taylor Lin

Retry, Repair, or Replay: A Failure-Triage Tree for Agent Steps

Terms worth pinning down first

The three branches

Decision table

The classifier, runnable

Four leaves, one worked example each

Leaf 1 — Retry

Leaf 2 — Replay

Leaf 3 — Repair

Leaf 4 — Abort

Where free capacity actually lands in this tree

Limitations, and who should skip this

Test plan before production

Which Agent Step Deserves a Cache? A Glossary, a Decision Tree, and Four Worked Leaves

Glossary: seven terms worth agreeing on first

The decision tree

Leaf A — exact memo, no TTL

Leaf B — TTL cache, TTL set by staleness class

Leaf C — no cache at all

Leaf D — normalized key with a namespace

The replay test: three checks before you enable anything

Decision table

Limitations and who should not use this

Token Forensics for Agent Runs: Five Waste Signatures and the Order to Fix Them

1. Start with the report, not the router

Glossary (six terms, used consistently below)

2. The meter (stdlib only, ~60 lines)

3. The decision tree, in fix order

The stop rule for leaf B

4. Worked examples at each leaf

5. Where a free tier actually changes the math

6. Limitations, and who should skip this

Closing

Context Triage for Agent Prompts: Terms, Five Branches, and a Dependency-Free Budget Checker

1. Glossary: the six terms that do the work

2. The tree: five branches, five leaves

Branch 1 — Does one pinned span already exceed the soft budget?

Branch 2 — Is the overflow from accumulated conversation turns?

Branch 3 — Is the overflow from tool output?

Branch 4 — Is the overflow from the instruction block itself?

Branch 5 — Nothing trims enough without cutting pinned content.

3. Make it mechanical: a budget checker with no dependencies

4. Which leaf for which symptom

5. Limitations, and who should skip this

6. Where the free surfaces fit

Admission Control Before Routing: A Free-Tier Quota Ledger for Agent Jobs

Terms first, tree second

The ledger artifact

The tree, with four worked leaves

Test the tree, not the model

Limitations, and who should skip this

Split Placement: Deciding Which Agent Steps Run Locally, on a Free Server, or on a Free Model Endpoint

02:10, nineteen steps done, thirty-one to go

Why placement is a separate question from tier choice

Glossary: ten terms this tree depends on

The tree: ordered predicates, first match wins

The four leaves, with a worked example each

Leaf A: LOCAL

Leaf B: FREE_SERVER

Leaf C: FREE_MODEL

Leaf D: ESCALATE

A reproducible harness in five steps

Limitations and what I did not verify

Who should not use this

Routing Agent Jobs Across Free Tiers: A Glossary, a Decision Tree, and Four Worked Leaves

Glossary: the eight terms the tree depends on

The decision tree: five branches, in order

Four worked leaves

Leaf A — local_only

Leaf B — free_model

Leaf C — free_server

Leaf D — controlled

The artifact: a router you can run in one command

Pin every branch with a test, not a review

Turn routing records into a table you can argue with

Limitations, and who should not use this

What to do next

Evidence Grades for Agent Claims: Terms, Branches, and Six Leaves

What the gate is allowed to decide

Leaf A: `LOCAL`

Leaf B: `FREE_SERVER`

Leaf C: `FREE_MODEL`

Leaf D: `ESCALATE`

Leaf A — `local_only`

Leaf B — `free_model`

Leaf C — `free_server`

Leaf D — `controlled`