DEV Community: Casey Li

Workloads a Free Token Tier Should Never See

Casey Li — Tue, 27 Oct 2026 13:31:10 +0000

Most workloads should never touch a free token tier. The useful engineering work is deciding that before the first request, not during the postmortem. A free tier behaves like a borrowed laptop: fine for a sketch, wrong for payroll.

What follows is a disqualification checklist rather than an onboarding guide. It takes the free capacity as real and asks a narrower question — which jobs are refused no matter how attractive the zero on the invoice looks.

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

The operator advertises 10 million free tokens and a free server option for the project. Both numbers belong on the project's own pages, and both should be re-read on the day you wire anything in. The gate below does not depend on those numbers, which is the point: policy first, capacity second.

Six disqualifiers, no exceptions

The first is a data boundary. If the payload contains personal data, health data, credentials, customer content, or source you would not paste into a public gist, the free path is closed. Not because the vendor is untrustworthy, but because you cannot audit the path, and unauditable paths do not get to hold regulated data.

The second is privilege. Any workload that deletes, deploys, migrates, signs, or moves money is out. A free endpoint is a shared convenience; privilege grants are a different class of object and should never be reachable from it.

The third is latency in the interactive path. If a human is waiting and your budget is a couple of seconds, a shared free path cannot be inside that budget by construction, because you control neither queue depth nor neighbours. Batch it, or pay for the guarantee.

The fourth is durability. Free servers are for compute, not custody. State that must survive a restart belongs in a database you operate, and the free instance should be able to vanish at any moment without a support ticket.

The fifth is evidence. If an auditor, a customer, or a court may ask which model produced this output, the answer has to be a pinned artifact you own. You cannot pin what you do not control.

The sixth is blast radius. When a failure pages an on-call engineer or surfaces directly to a customer, the failure needs a party contractually on the hook. Free tiers are not on the hook, and pretending otherwise converts a subsidy into an outage.

The gate as code

A checklist that lives in a wiki rots. The one below lives in CI and takes a JSON descriptor per workload. It has no dependencies beyond the standard library.

#!/usr/bin/env python3
"""free_tier_gate.py - refuse a free token tier before it carries work.

Usage:
    python3 free_tier_gate.py workload.json
    python3 free_tier_gate.py *.json
Exit codes: 0 = all allowed, 1 = at least one denied, 2 = bad input.
"""
from __future__ import annotations

import json
import sys
from pathlib import Path

SENSITIVE = {"pii", "phi", "secrets", "customer_content", "internal_source"}
PRIVILEGED = {"deploy", "delete", "payment", "grant", "migrate", "sign"}
LATENCY_FLOOR_MS = 2000


def r_data(w):
    bad = sorted(set(w.get("data_classes", [])) & SENSITIVE)
    return f"data classes cross a boundary you cannot audit: {bad}" if bad else None


def r_privilege(w):
    bad = sorted(set(w.get("actions", [])) & PRIVILEGED)
    return f"privileged actions on a subsidised path: {bad}" if bad else None


def r_latency(w):
    budget = w.get("latency_budget_ms", 10**9)
    if w.get("user_facing") and budget < LATENCY_FLOOR_MS:
        return f"user-facing call with a {budget} ms budget cannot sit on a shared path"
    return None


def r_durability(w):
    if w.get("stateful") or w.get("needs_durable_disk"):
        return "workload expects state to outlive the instance"
    return None


def r_evidence(w):
    if w.get("requires_pinned_artifact"):
        return "workload needs a pinned model or image the free tier does not promise"
    return None


def r_blast(w):
    if w.get("on_failure") in {"page_oncall", "customer_visible_error"}:
        return f"failure mode is {w['on_failure']}, which a free tier cannot underwrite"
    return None


RULES = [r_data, r_privilege, r_latency, r_durability, r_evidence, r_blast]


def evaluate(w):
    reasons = [r for rule in RULES if (r := rule(w))]
    return ("DENY" if reasons else "ALLOW"), reasons


def main(argv):
    if not argv:
        print(__doc__, file=sys.stderr)
        return 2
    code = 0
    for name in argv:
        try:
            w = json.loads(Path(name).read_text())
        except (OSError, json.JSONDecodeError) as exc:
            print(f"{name}: unreadable descriptor ({exc})", file=sys.stderr)
            code = max(code, 2)
            continue
        verdict, reasons = evaluate(w)
        print(f"{w.get('name', name)}: {verdict}")
        for reason in reasons:
            print(f"  - {reason}")
        if verdict == "DENY":
            code = max(code, 1)
    return code


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

A descriptor is deliberately boring, and the boring ones are the survivors.

{
  "name": "nightly-changelog-summary",
  "data_classes": ["public_docs"],
  "actions": ["read"],
  "user_facing": false,
  "stateful": false,
  "requires_pinned_artifact": false,
  "on_failure": "retry_next_night"
}

Running the gate over a mixed directory produces the kind of output a reviewer can act on without a meeting.

$ python3 free_tier_gate.py *.json
nightly-changelog-summary: ALLOW
invoice-extraction: DENY
  - data classes cross a boundary you cannot audit: ['customer_content', 'pii']
  - failure mode is customer_visible_error, which a free tier cannot underwrite

Two tests keep the rules honest, because a gate nobody tests slowly drifts toward ALLOW.

import unittest
from free_tier_gate import evaluate


class GateTest(unittest.TestCase):
    def test_refuses_privileged_action(self):
        verdict, reasons = evaluate({"actions": ["delete"], "on_failure": "retry"})
        self.assertEqual(verdict, "DENY")
        self.assertTrue(any("privileged" in r for r in reasons))

    def test_allows_offline_batch(self):
        verdict, reasons = evaluate({"data_classes": ["public_docs"], "on_failure": "retry"})
        self.assertEqual((verdict, reasons), ("ALLOW", []))

What survives the gate

Plenty survives, and it is the unglamorous half of the work. Summarising public documentation, drafting commit messages, classifying already-published text, generating throwaway scaffolding for a spike, and labelling a synthetic fixture set all pass every rule above. The free server is a reasonable home for ephemeral previews, demo endpoints fed by fake data, and CI jobs that can be recreated from a lockfile.

The shared property is that a sudden disappearance costs an afternoon, not a customer. That is the only durability guarantee a free tier can offer, and it is enough for this class of work.

Exit criteria you can automate

Refusal is a decision made once. Exit is a decision made continuously. A small probe that demotes the free path without a deploy is worth more than a paragraph in a runbook.

#!/usr/bin/env bash
# exit_probe.sh - remove the free path from rotation without a deploy.
set -euo pipefail
FLAG="${FLAG:-/var/run/free_tier_disabled}"
URL="${URL:?set URL to the health endpoint}"
deadline=$(( $(date +%s) + 3600 ))

while [ "$(date +%s)" -lt "$deadline" ]; do
  read -r http secs <<<"$(curl -s -o /dev/null -w '%{http_code} %{time_total}' --max-time 5 "$URL" || echo '000 5.0')"
  if [ "$http" != "200" ] || awk -v s="$secs" 'BEGIN{exit !(s > 3.0)}'; then
    date -u +%FT%TZ > "$FLAG"
    echo "free tier demoted at $(cat "$FLAG")"
    exit 1
  fi
  sleep 60
done

Any scheduler can run it. The flag file is the contract: readers check it before every call, and no one has to trust memory at 3 a.m.

Who should skip this entirely

Teams handling regulated data should not start here. Neither should products whose core promise is latency, teams that need a named party to answer a support ticket, or anyone who cannot rotate the credential the free path uses. A team without centralised logging has one more reason to wait, because an unauditable path plus unreadable logs is indistinguishable from no testing at all.

The approach also has limits worth stating plainly. The gate encodes policy, not security; it will not stop a determined engineer from calling the endpoint by hand. Token allowances and server terms change, and an approval issued in October is not an approval in January. Re-run the descriptors whenever the terms are re-read.

If a descriptor returns ALLOW, running that batch against MonkeyCode's free tier is a sensible first stop, and the checklist is what keeps it cheap rather than expensive later.

MonkeyCode provides free models that can run this workflow.

The Free Endpoint Does Not Belong on the Interactive Path

Casey Li — Mon, 26 Oct 2026 12:05:42 +0000

Free capacity rarely fails by returning errors. It fails as a queue, and the queue surfaces as latency on a request a user is already waiting for. That asymmetry is the whole argument: MonkeyCode's free model access and free server option fit background lanes and batch jobs, and they fit badly behind a spinner in a product surface.

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

The offering is described by the operator as free model access with a 10 million token allowance, plus a free server option. Nothing below assumes a model name, a concurrency limit, hardware, or how long the offer lasts. Those are exactly the unknowns the harness is built to measure rather than guess.

Errors are the wrong signal

A saturated free endpoint still answers 200. It answers slowly. Your dashboard shows a clean error rate while your users watch a cursor blink, and the first thing that breaks is not the model call but the request timeout wrapped around it.

Then the retries arrive. An SDK retries twice, your service retries once, and a single slow call becomes four queued calls competing for the same capacity. Latency is self-inflicted from that point on, and the error rate you were watching finally moves — after the damage.

Interactive paths punish this behaviour twice. The user pays the latency directly, and the retry storm you generate lands on shared free capacity that other lanes also depend on. Background work absorbs the same queue as throughput; a person cannot.

Measure the thing that actually degrades

First-byte latency, not success rate, is the number that decides path placement. The harness below is deliberately endpoint-agnostic: it takes a full URL and an exact request body from the environment, so it measures whatever you actually intend to ship instead of an invented API shape. It is an unexecuted reference implementation — run it against your own endpoint before trusting any number in it.

# probe_free_endpoint.py -- endpoint-agnostic latency ledger
import json, os, time, urllib.request

URL = os.environ["PROBE_URL"]          # full URL, supplied by you
TOKEN = os.environ["PROBE_TOKEN"]
PAYLOAD = json.load(open(os.environ["PROBE_BODY"]))
LEDGER = os.environ.get("PROBE_LEDGER", "ledger.jsonl")
N = int(os.environ.get("PROBE_N", "20"))
TIMEOUT = float(os.environ.get("PROBE_TIMEOUT", "60"))

def one(i):
    req = urllib.request.Request(
        URL, data=json.dumps(PAYLOAD).encode(), method="POST",
        headers={"Content-Type": "application/json",
                 "Authorization": f"Bearer {TOKEN}"},
    )
    t0 = time.monotonic()
    first, nbytes = None, 0
    try:
        with urllib.request.urlopen(req, timeout=TIMEOUT) as r:
            status = r.status
            while True:
                chunk = r.read(1024)
                if not chunk:
                    break
                if first is None:
                    first = time.monotonic() - t0
                nbytes += len(chunk)
    except Exception as e:
        return {"i": i, "ok": False, "err": type(e).__name__,
                "total_s": round(time.monotonic() - t0, 3)}
    return {"i": i, "ok": True, "status": status, "bytes": nbytes,
            "first_byte_s": round(first, 3) if first else None,
            "total_s": round(time.monotonic() - t0, 3)}

def pct(xs, p):
    xs = sorted(x for x in xs if x is not None)
    if not xs:
        return None
    k = max(0, min(len(xs) - 1, round((p / 100) * (len(xs) - 1))))
    return xs[k]

if __name__ == "__main__":
    rows = [one(i) for i in range(N)]
    with open(LEDGER, "a") as f:
        for r in rows:
            f.write(json.dumps(r) + "\n")
    ok = [r for r in rows if r["ok"]]
    print(json.dumps({
        "n": N,
        "ok_rate": round(len(ok) / N, 3),
        "p50_first_byte_s": pct([r.get("first_byte_s") for r in ok], 50),
        "p95_first_byte_s": pct([r.get("first_byte_s") for r in ok], 95),
        "p95_total_s": pct([r.get("total_s") for r in ok], 95),
    }, indent=2))

Run it the way you would run a smoke test, not a benchmark:

PROBE_URL="$FREE_URL" PROBE_TOKEN="$FREE_TOKEN" \
PROBE_BODY=./request.json PROBE_N=30 \
python probe_free_endpoint.py

Append-only JSONL is the point. A single run tells you almost nothing; thirty runs across a morning tell you whether the p95 moves when the rest of the world wakes up. The ledger is what makes the admission decision auditable six weeks later, when nobody remembers why the lane was split.

Admit only with headroom

A free lane should clear the path's latency objective with margin to spare, because you cannot buy your way out of a queue mid-incident. The rule below encodes that asymmetry: first byte must land inside half the budget, and total time inside eighty percent, before the lane is allowed anywhere near a user.

# admission.py -- unexecuted; bounds come from your own SLO, not from this article
def admits(stats, slo_first_byte, slo_total, min_ok_rate=0.99):
    if stats["ok_rate"] < min_ok_rate:
        return False, "ok_rate below floor"
    if (stats["p95_first_byte_s"] or 9e9) > 0.50 * slo_first_byte:
        return False, "first byte has no headroom"
    if (stats["p95_total_s"] or 9e9) > 0.80 * slo_total:
        return False, "total has no headroom"
    return True, "admitted with margin"

A lane that passes this rule is a candidate for interactive use. A lane that fails it is not slow, it is misrouted. Those are different bugs and they get different fixes.

Lane placement, decided once

Lane	Human waiting	Free capacity fits	Required fallback
Autocomplete, chat reply	Yes	Only with measured headroom	Paid or local endpoint
PR review comments	No, minutes	Yes	Requeue, then drop
Nightly summarisation	No, hours	Yes	Next window
Anything holding a lock	Depends	No	Unbounded path only
Write path with side effects	Yes	No	Idempotent local path

The fourth row is the trap. Free capacity inside a critical section holds a lock for a duration nobody controls, and every waiter inherits the queue.

Red flags, as prose

Five signals should stop a design review cold. The first is a spinner: if a person is watching the call resolve, free capacity needs measured headroom, not optimism. The second is a retry policy written before the endpoint was measured, because two layers of retries against a queue multiply rather than divide. The third is state: if the free server also holds a queue, a cron table, or a lock that the request path depends on, the model's latency and the scheduler's latency become one number you cannot separate. The fourth is privilege: a free endpoint should never be the thing that approves, merges, deletes, or pays. The fifth is opacity: if you cannot reproduce the same request body from a fixture file, you are not measuring the thing you ship.

Better alternatives exist for each red flag

For the spinner, move the call off the request path and stream a cached answer while the slow lane works. For the retry storm, cap attempts at one per layer and let the caller decide. For shared state, keep the free server stateless — every artefact reconstructed from your own durable store. For privilege, put a human or a deterministic rule at the boundary and let the model draft only. For opacity, the probe harness above is the fix, and it is cheaper than the incident review it prevents.

Exit criteria, written before adoption

Exit when the probe's p95 first-byte latency exceeds half the path's budget in three consecutive measurement windows. Exit when the fallback rate crosses the headroom you measured, because at that moment the free lane is no longer an optimisation but a dependency. Exit, most of all, when a single engineer would need to be paged to keep the lane alive — that is the definition of the free tier becoming load-bearing, and it is a staffing decision disguised as an infrastructure one. Record the exit date and the number that triggered it in the same ledger file.

Limitations, and who should skip this

The harness measures one client from one location. It says nothing about behaviour under your real concurrency, nothing about correctness of responses, and nothing about data handling, which is a review you must do separately before sending anything sensitive to any third-party endpoint. Latency measured at 09:00 may not describe 21:00.

Teams with a hard real-time contract, teams handling regulated data without a completed review, and teams whose on-call rotation cannot absorb a new dependency should not adopt a free lane at all. Neither should anyone who needs a duration guarantee; the operator describes free access and a free server, not a service level, and this article deliberately asserts no numbers beyond the stated allowance.

Start by measuring. Point the probe at the free model access endpoint and, separately, at whatever the free server option actually serves, then let the ledger rather than the announcement decide which lane each one earns.

Before a Free Coding Agent Sees Your Repo: A Preflight Gate

Casey Li — Tue, 20 Oct 2026 10:10:31 +0000

Most arguments about free coding agents are arguments about capability. The question that actually decides outcomes is routing: which work should never reach a free model tier at all. Teams that answer this once stop re-litigating it every sprint. Teams that answer it per task end up with a review queue nobody trusts.

What follows is a field guide to the negative case, encoded as a gate. It reads the repository, not the task description, because people describe their intentions optimistically and directories do not. The gate returns an exit code, and the exit code decides the route.

The repository is evidence; the prompt is a claim

A prompt saying "small refactor, no sensitive data" is an assertion. git ls-files is a fact. The asymmetry matters, because a mis-scoped task sent to a paid model costs money, while the same task sent to a free tier can cost a credential, a customer record, or a compliance finding. Price is the wrong axis for the decision.

AI fatigue, when it is not simply model fatigue, is often routing fatigue: the recurring cost of deciding, badly, where each piece of work belongs. A gate turns that recurring decision into a file that can be reviewed once, versioned, and argued with deliberately instead of repeatedly.

The script below is a template, not a shipped tool. It has not been run against an unknown repository, and every check in it is meant to be adapted before anyone trusts it.

#!/usr/bin/env bash
# gate.sh — may work on this repo be routed to a free model tier?
# Exit 0 = free tier acceptable; 10 = free tier with restrictions; 20 = do not route.
set -u

repo="${1:-.}"
reasons=()
code=0

block() { reasons+=("BLOCK  $1"); code=20; }
limit() { [ "$code" -lt 20 ] && code=10; reasons+=("LIMIT  $1"); return 0; }

# 1. Tracked credential-shaped files are a stop, never a warning.
if git -C "$repo" ls-files | grep -Eq '(^|/)(\.env($|\.)|id_rsa|id_ed25519|[^/]*\.(pem|p12|pfx))$'; then
  block "tracked credential-shaped files"
fi

# 2. Secret-shaped literals in tracked source.
if git -C "$repo" grep -InE '(sk-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]{30,}|AKIA[0-9A-Z]{16})' >/dev/null 2>&1; then
  block "secret-shaped literal in tracked source"
fi

# 3. Uncommitted work means the tree is not the artifact under review.
if [ -n "$(git -C "$repo" status --porcelain)" ]; then
  limit "dirty worktree; commit or stash before the run"
fi

# 4. Data classification is explicit, because defaults are always optimistic.
if [ -f "$repo/DATA_CLASSIFICATION" ]; then
  class="$(head -n1 "$repo/DATA_CLASSIFICATION" | tr -d '[:space:]')"
  case "$class" in
    public|internal) : ;;
    *) block "data classification '${class}' requires a private route" ;;
  esac
else
  limit "no DATA_CLASSIFICATION file; scope to internal-only work"
fi

# 5. Production wiring in the same tree narrows what a task may touch.
if git -C "$repo" grep -IlE '\b(prod|production)\b' >/dev/null 2>&1; then
  limit "production references present; scope the task to a subdirectory"
fi

printf 'gate=%s\n' "$code"
if [ "${#reasons[@]}" -eq 0 ]; then printf 'no findings\n'; else printf '%s\n' "${reasons[@]}"; fi
exit "$code"

Reading the result is the method. Exit 0 means the tree is clean, classified, and free of secret shapes, so the free tier becomes the default route rather than an exception. Exit 10 means the work is admissible but must be scoped to a subdirectory with a written reason. Exit 20 means the repository has a problem that no model choice can fix.

Exit	Signal	Route
0	Clean, classified, no secret shapes	Free tier is the default
10	Admissible but scoped	Free tier on a subdirectory, with a receipt
20	Evidence of exposure	Local or private route; repair the repo first

The 10 branch is where discipline leaks. A limit that is never recorded becomes a block that is never enforced, and a block that is never enforced becomes an incident that is explained away. Recording the decision is cheap compared with reconstructing it after the fact.

# Append one line per run so the route decision survives the sprint.
receipt() {
  printf '%s gate=%s head=%s dirty=%s\n' \
    "$(date -u +%FT%TZ)" "$1" \
    "$(git rev-parse --short HEAD 2>/dev/null || echo no-git)" \
    "$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')" \
    >> .free-tier-runs.log
}

./gate.sh . ; receipt $?

The free server is a staging decision

A free server option changes where the work runs, not what the work is allowed to touch. The exit conditions are therefore about state and reachability, not about performance. If a job needs inbound connections into a private network, a long-lived secret, persistent disk the team later grows attached to, or an audit trail someone will eventually request, the free server is the wrong host and no amount of convenience changes that.

Ephemeral is fine. Stateless is fine. A build that can be recreated from a commit hash in one command is fine. Anything whose loss would require a meeting is not.

This is precisely the shape MonkeyCode presents: free model access plus a free server option, which is why a gate is the first thing to write and the last thing to remove. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The allowance itself is operator-supplied and changes over time; confirm the current token figure and any server limits on the project's own documentation before planning capacity around them, because a number quoted in a blog post is not a contract.

When to leave

Three signals say the free route has stopped paying for itself. The gate blocks more work than it passes, which means the repository is the problem and the tier is a distraction. Reconstructing why a free run failed takes longer than writing the patch would have taken. Or the review queue grows monotonically for a week while nobody can say which runs were free and which were not.

Each of those is an exit criterion, and each is observable without a benchmark. None of them require comparing model quality, which is the comparison that consumes the most argument and settles the least.

Who should not adopt this

Teams without version-control discipline should skip the gate entirely; on an untracked repository it inspects nothing and returns confidence it has not earned. Regulated workloads where any third-party route is disallowed do not need a script, only a policy. Solo prototypes where nothing is at risk will find the gate pure overhead, and that is a legitimate answer. The last group is anyone who cannot state the data classification of the repository in front of them, which is a block rather than a task.

A gate is not a security review. It catches the boring failures, the ones that recur, and it does so in under a second on most trees. The interesting failures still need a person.

If gate.sh exits 0 on a repository, that is the moment the free tier at MonkeyCode is worth an actual run rather than another opinion piece.

A Refusal Contract for Free Coding Agents

Casey Li — Mon, 19 Oct 2026 08:52:34 +0000

A free coding agent fails in a predictable direction: it says yes. Ask for a one-line fix and the patch also renames a directory. Ask for a test and the diff arrives with a modified lockfile and a new CI workflow attached. The damage is rarely bad syntax. It is correct code in a place nobody approved.

Prompts do not fix this. "Be conservative" is advice, and advice loses to a strong prior. What holds is a contract the agent cannot satisfy by talking: a diff that either passes a rule set or never reaches review. The useful question is not which model wrote the patch, but what the patch is allowed to touch once it exists.

This is a field guide to that boundary, including the cases where the whole arrangement should be abandoned.

Put the refusal outside the model

The instinct is to filter output. A sturdier boundary is the artifact — the pull request diff, checked by a script with no opinion about prose. The script is boring, testable, and identical whether a free model, a paid model, or a tired human produced the change.

Three files carry the contract. tools/policy.yaml states the allowed blast radius. tools/gate.py reads a diff and returns one of three verdicts. The gate's JSON output becomes the receipt attached to the pull request, so the next reader sees why something stopped instead of guessing.

# tools/policy.yaml
allow_paths:
  - src/
  - tests/
deny_paths:
  - tools/          # the gate must not rewrite its own rules
  - infra/
  - .github/
  - '*.lock'
max_files_changed: 5
max_lines_changed: 200

The deny entry for tools/ is not decoration. If the policy file is editable by the same process it constrains, every other rule is advisory. That single line is the difference between a contract and a suggestion.

The gate

Roughly sixty lines, standard library plus PyYAML. It reads the diff against a base ref rather than trusting the agent's own summary of what it did. The code below is illustrative — written for this article and not executed against a real repository — so treat the thresholds as a starting point, not a calibrated policy.

#!/usr/bin/env python3
"""tools/gate.py - a refusal gate for agent-produced diffs."""
import json, os, subprocess, sys
from fnmatch import fnmatch
import yaml

def git(*args):
    return subprocess.run(['git', *args], capture_output=True, text=True, check=True).stdout

def diff_stats(base):
    files, added, removed = [], 0, 0
    for line in git('diff', '--numstat', base + '...').splitlines():
        a, d, name = line.split('\t')
        files.append(name)
        added += int(a) if a.isdigit() else 0
        removed += int(d) if d.isdigit() else 0
    return {'files': files, 'added': added, 'removed': removed}

def hit(name, patterns):
    for pat in patterns:
        if fnmatch(name, pat) or fnmatch(os.path.basename(name), pat):
            return pat
    return None

def verdict(stats, policy):
    reasons = []
    for name in stats['files']:
        if hit(name, policy['deny_paths']):
            reasons.append('denied_path:' + name)
    outside = [n for n in stats['files'] if not hit(n, policy['allow_paths'])]
    if outside:
        reasons.append('outside_allowlist:' + ','.join(outside))
    if len(stats['files']) > policy['max_files_changed']:
        reasons.append('file_budget:' + str(len(stats['files'])))
    churn = stats['added'] + stats['removed']
    if churn > policy['max_lines_changed']:
        reasons.append('churn_budget:' + str(churn))
    if not reasons:
        decision = 'allow'
    elif any(r.startswith('denied_path') for r in reasons):
        decision = 'refuse'
    else:
        decision = 'review'
    return dict(decision=decision, reasons=reasons, **stats)

if __name__ == '__main__':
    base = sys.argv[1] if len(sys.argv) > 1 else 'origin/main'
    with open('tools/policy.yaml', encoding='utf-8') as fh:
        policy = yaml.safe_load(fh)
    result = verdict(diff_stats(base), policy)
    print(json.dumps(result, indent=2))
    sys.exit({'allow': 0, 'review': 1, 'refuse': 2}[result['decision']])

Exit codes matter more than the JSON body. CI branches on the number without parsing anything.

set +e
python3 tools/gate.py origin/main > receipt.json
status=$?
case $status in
  0) echo 'allow: normal review path' ;;
  1) gh pr edit "$PR" --add-label needs-human ;;
  2) gh pr close "$PR" --comment 'Refused by policy. See receipt.json.' ;;
esac

The middle verdict does the most work. Most agent patches are not hostile; they are over-broad. review hands a human the cheap decision — this touched three extra files, was that intended? — without pretending the diff is dangerous. A gate that only knows allow and block becomes a nuisance within a week and gets disabled.

Shapes worth denying on sight

Lockfiles and generated code are the clearest case for refusal over review. The diff is unreadable, regeneration is the correct fix, and review time spent on it is time not spent on the actual change. Deny the path and let the lockfile update happen deliberately.

Directory moves and import rewrites deserve the same treatment. They are mechanically easy for a model and expensive for a reviewer, because a single missed reference surfaces later as a runtime error in an unrelated test. If a task needs a rename, it needs a task of its own.

Anything adjacent to secrets belongs behind a hard deny: environment files, deploy keys, credential fixtures, and the deployment directory that reads them. A model does not need to exfiltrate anything to cause harm here; pasting a realistic-looking key into a test fixture is enough to trip scanners for a month.

Finally, long-lived processes and CI configuration. An agent that starts a watcher, a dev server, or a background job leaves state behind that nobody accounts for. And a patch that edits the workflow which runs the gate has effectively voted on its own rules.

Where a free model and a free server fit

The drafting step is the part that benefits from cheap inference: generate a candidate patch, run it through the gate, discard most of it. The free model access in MonkeyCode is a reasonable place to do that drafting, and the free server option is a reasonable place to run the gate, because both jobs are short-lived and neither needs standing database credentials. The agent finishes, the gate renders a verdict, the process exits. Nothing holds a lease on your infrastructure.

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

The free allowance and the free server are operator-supplied claims, currently described as a ten-million-token allowance with a hosted option. Verify the current terms yourself before sizing work around them; a number you have not re-read this month is a number you should not plan capacity on. The same caution applies to the project being open source — read the code that would run in your pipeline, not the landing page.

A test you can rerun

Five fixture tasks are enough to learn whether the gate helps or merely annoys. Seed a repository with one task that genuinely belongs inside the allowlist, two that need a single extra file, one that must touch a lockfile, and one that only makes sense as a CI edit. Label the expected verdict for each in a plain TSV.

pass=0; total=0
while IFS=$'\t' read -r task expected; do
  total=$((total+1))
  ./run_agent.sh "fixtures/tasks/$task" > "out/$task.diff"
  git apply --index "out/$task.diff"
  got=$(python3 tools/gate.py origin/main | jq -r .decision)
  git reset --hard -q origin/main
  [ "$got" = "$expected" ] && pass=$((pass+1))
done < fixtures/labels.tsv
echo "$pass/$total"

run_agent.sh is your harness around whatever model you are evaluating; swap it and the scoring loop stays. Three numbers fall out of a single run: agreement with your labels, the false-refusal rate on tasks that were fine, and the churn per accepted patch. The last one trends upward quietly, and it is the earliest sign that the allowlist is too loose.

Exit criteria

Three signals say the arrangement has stopped paying for itself. If more than one accepted patch in five needs a follow-up human fix in the same file within a week, the gate is letting through work it should have reviewed — tighten the budget before tightening the prompt. If review verdicts outnumber allow verdicts for two consecutive weeks, the tasks being routed here are the wrong shape, and no amount of model quality fixes routing. If time-to-first-edit on the free path exceeds what a developer would spend writing the patch by hand, the free path is a hobby.

Retire it deliberately rather than by attrition. Move the repeated task shapes to a paid or primary path, narrow the free path to drafting inside a small allowlist, and keep the gate either way — the gate is useful with any model behind it.

Who should not use this

Teams without CI on the agent's output should not start here; a gate that nobody runs is a document. Repositories dominated by generated code will fight the churn budget on every patch, and the honest answer is path-level exclusion, not a cleverer threshold. Work that requires a long-lived process, a persistent session, or access to production credentials should stay on infrastructure you own end to end. And any workflow with an audit requirement that forbids third-party services in the review path is simply out of scope, regardless of how cheap the drafting gets.

If you adopt one idea from this, make it the deny rule protecting the policy file itself. Every other line in the contract assumes the rules are out of reach.

Exit Criteria for a Free Model Tier

Casey Li — Sun, 18 Oct 2026 07:29:37 +0000

A free model tier is a lease with an unpublished end date. Signing it is not the mistake. Learning the terms during a production incident is.

The useful artifact before adoption is not a benchmark. It is an exit ticket: a short, executable set of conditions that says this tier has stopped fitting my workload, written while things still look fine, with the numbers filled in by the tier itself. Everything below is that artifact — the harness, the decision table, and the red flags that justify skipping the experiment entirely.

Averages hide the actual failure mode

Free endpoints rarely degrade along a smooth curve. They fail by category: the response envelope changes, output stops conforming to your schema, server errors replace client errors, a quota wall appears without a reset header, a long input comes back truncated.

None of that surfaces in a p50 latency chart. That is why the usual "is it fast enough" review reads green right up to the day it isn't. Probe categories instead. Every one of them is observable from outside with a plain HTTP client and no vendor SDK.

The harness

The script below uses only the standard library, because the moment a probe needs a vendor SDK it also needs a maintenance budget and a version pin. It assumes an OpenAI-compatible POST /chat/completions; confirm the path, auth header, and payload against your provider's documentation before trusting a single number it prints. Treat it as a template rather than a validated tool.

# probe.py - stdlib only. Run it from the host you plan to call the model from.
import json, os, time, urllib.error, urllib.request
from datetime import datetime, timezone

BASE  = os.environ["FREE_TIER_BASE_URL"].rstrip("/")
KEY   = os.environ["FREE_TIER_API_KEY"]
MODEL = os.environ["FREE_TIER_MODEL"]

CASES = [
    {"id": "json-shape", "kind": "json", "keys": ["ok", "n"],
     "prompt": 'Reply with JSON only: {"ok": true, "n": 7}'},
    {"id": "long-input", "kind": "text", "min_len": 1200,
     "prompt": "Repeat the word 'token' 400 times, comma separated."},
    {"id": "empty-input", "kind": "any",
     "prompt": "Summarise this text: ''"},
]

def call(prompt, timeout=60):
    body = json.dumps({"model": MODEL,
                       "messages": [{"role": "user", "content": prompt}]}).encode()
    req = urllib.request.Request(
        f"{BASE}/chat/completions", data=body, method="POST",
        headers={"Content-Type": "application/json",
                 "Authorization": f"Bearer {KEY}"})
    t0 = time.monotonic()
    try:
        with urllib.request.urlopen(req, timeout=timeout) as r:
            return {"status": r.status,
                    "body": r.read().decode("utf-8", "replace"),
                    "ms": int((time.monotonic() - t0) * 1000), "err": None,
                    "rl": {k.lower(): v for k, v in r.headers.items()
                           if k.lower().startswith("x-ratelimit")}}
    except urllib.error.HTTPError as e:
        return {"status": e.code,
                "body": e.read().decode("utf-8", "replace"),
                "ms": int((time.monotonic() - t0) * 1000),
                "err": f"http_{e.code}", "rl": {}}
    except Exception as e:                      # timeouts, DNS, TLS
        return {"status": None, "body": str(e),
                "ms": int((time.monotonic() - t0) * 1000),
                "err": type(e).__name__, "rl": {}}

def score(case, resp):
    if resp["err"]:
        return {"id": case["id"], "conform": 0, "reason": resp["err"]}
    try:
        text = json.loads(resp["body"])["choices"][0]["message"]["content"]
    except Exception:
        return {"id": case["id"], "conform": 0, "reason": "envelope_mismatch"}
    if case["kind"] == "json":
        try:
            ok = all(k in json.loads(text) for k in case["keys"])
        except Exception:
            ok = False
        return {"id": case["id"], "conform": int(ok),
                "reason": None if ok else "bad_json"}
    if case["kind"] == "text":
        ok = len(text) >= case["min_len"]
        return {"id": case["id"], "conform": int(ok),
                "reason": None if ok else "truncated_or_short"}
    return {"id": case["id"], "conform": 1, "reason": None}

for _ in range(5):                              # five passes, worst case counts
    run = {"ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
           "model": MODEL, "rows": []}
    for case in CASES:
        resp = call(case["prompt"])
        run["rows"].append({**score(case, resp), "status": resp["status"],
                            "ms": resp["ms"], "rl": resp["rl"]})
    with open("probe.jsonl", "a") as f:
        f.write(json.dumps(run) + "\n")
    print(run["rows"])

Five passes per case, append-only JSONL, one row per case per pass. The value is not the absolute conformance score; it is the diff between this run and the run after the next upstream change, which nobody will announce. Header capture matters more than latency here — an x-ratelimit-remaining that moves is a budget you can plan against, and its absence is itself a finding.

Turning rows into a verdict

The second file is where the exit ticket actually lives. The thresholds are policy you choose, not measurements anyone published; pick numbers that match your own tolerance and write them down where a reviewer can argue with them.

# verdict.py - reads probe.jsonl, exits 0 (keep), 1 (warn), 2 (exit)
import json, sys

STAY, LEAVE = 0.95, 0.80          # policy, not measured fact

runs = [json.loads(l) for l in open("probe.jsonl")]
if len(runs) < 2:
    sys.exit(0)

cur, prev = runs[-1], runs[-2]
conf  = lambda r: sum(x["conform"] for x in r["rows"]) / len(r["rows"])
fivex = lambda r: sum(1 for x in r["rows"] if (x["status"] or 0) >= 500)

print(f"conform cur={conf(cur):.2f} prev={conf(prev):.2f} 5xx={fivex(cur)}")
if conf(cur) < LEAVE or fivex(cur) >= 2:
    sys.exit(2)
if conf(cur) < STAY and conf(prev) < STAY:
    sys.exit(1)
sys.exit(0)

Exit code 2 is the ticket firing, not a suggestion. Wire it to whatever your team actually watches, otherwise the script becomes a file nobody reads and the whole exercise collapses into documentation theatre.

The decision table

Signal	Keep	Open the exit ticket	First move
Output shape across repeated identical prompts	one stable envelope	two shapes in five prompts	pin parsing to a schema, log failures
Error class mix over 100 calls	4xx only when your request is wrong	any 5xx cluster, or a 429 with no reset header	record retry budget, cap it in code
Fixture conformance between adjacent runs	flat	drop larger than your team's tolerance	snapshot last-good responses before retrying
Time to a first useful token	inside your UX budget	outside it three runs in a row	move the call off the request path
Cost of one extra retry	rounding error	free tier plus your retries outweighs a paid call	stop retrying, price the paid path

The last row is the one teams skip. Retries are free only if someone else pays for them; when the free tier is slow, your own compute absorbs the difference, and that is a real invoice even when the model line item reads zero.

Where MonkeyCode fits, and where it does not

MonkeyCode participates in this loop in two deliberately unexciting places. It advertises free model access and a free server option, and it is described as an open-source project; a free allowance on the order of ten million tokens has been mentioned in outreach material. That combination makes it a reasonable subject for the probe and a reasonable host for running the probe, since the measurement host stops being a budget line of its own. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Verify the allowance and the server terms against the project's own pages before planning any capacity around them. Quotas move, free endpoints get re-rated, and a number quoted in a post is not a number you can page someone about. The honest use of a free tier is as a candidate under measurement, not as a line item you have already spent.

Red flags that end the experiment early

A credential on the free host that can spend money elsewhere is the first one. If a deploy key on a free box can push to main or mint a paid API key, the saved cost is an illusion and the blast radius has quietly grown; rotate the key or move the host.

Second, the free endpoint must never be the only implementation of an interface in your codebase. One adapter module, one function, one configuration seam — if swapping the backend touches more than a single file, the tier owns you and the exit ticket cannot fire on schedule.

Third, scheduled work with no owner. A cron job on a host nobody is on call for will fail silently for a week and then fail loudly on the day it matters. Fourth, data you cannot re-derive: fixtures, prompt logs, and eval rows should be reproducible from the repository, not resident on the free disk.

Who should not use this approach

Teams with retention or residency obligations that a free host cannot contractually meet should not start. Neither should anyone whose product promises a pinned model version, a hard p95, or deterministic output, because free tiers re-rate and re-route without notice to you. And a team with nobody to own the probe should skip straight to a paid tier; an unowned exit ticket decays into folklore within a quarter.

An exit ticket is cheap to write and embarrassing to write late. Keep the JSONL, run the harness for a week, and the decision stops being a debate about vibes — the rows make the argument for you, and they travel with you to whatever tier comes next.

The Stop List for Free Inference and Free Hosts

Casey Li — Sat, 17 Oct 2026 06:30:15 +0000

Most teams can name the day they adopted a free inference endpoint or a free server. Almost none can name the sentence that would make them leave it. That unwritten sentence is the actual risk, and it has nothing to do with price.

A stop list fixes this. It is a short document, dated, that pairs each free dependency with an observable signal and a pre-agreed action. Written before adoption, it turns a diffuse unease into a decision any on-call engineer can execute at 3 a.m. without a committee.

The artifacts below are three small ones: a capability ledger you can lint, a detach drill that proves your job survives losing the endpoint, and an exit-criteria table. MonkeyCode appears once, exactly where it is useful — as a disposable target for the drill. Its free model access and free server option are described only as the project states them. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Why benchmarks answer the wrong question

A benchmark tells you how good a tier is while it works. Your incident review will never be about that. It will be about what the code did in the ninety seconds after the endpoint stopped answering, and whether that behavior was designed or accidental.

Dependency shape matters more than quality. A summarizer that posts into a review queue and can be re-run by hand is shallow. A nightly job that mutates a durable table and has no second writer is deep, and depth is what makes removal expensive. Deep dependencies are not automatically wrong; they are wrong when nobody wrote down the cost of cutting them.

The useful classification is therefore about blast radius, not model quality. That is what the ledger encodes.

Artifact 1: a capability ledger you can lint

One JSON file per job, checked in next to the code. It records what the job actually asks of the endpoint, in vocabulary a reviewer can argue about.

{
  "job": "nightly-summarizer",
  "endpoint": "free-inference",
  "capabilities": ["mutates_durable_state"],
  "hard_latency_ms": null,
  "fallback": "enqueue to primary model",
  "owner": "platform"
}

The lint is deliberately blunt. Five capability flags are treated as red lines, because each one converts a vendor-side change into an incident you cannot cancel.

# stoplist.py - unexecuted template; wire into CI as a pre-merge check.
import json
import sys

RED_LINES = {
    "mutates_durable_state": "a free tier must never be the only writer",
    "grants_authority": "issued credentials outlive the endpoint",
    "carries_identity": "session trust cannot depend on a vendor's uptime",
    "bills_money": "spend needs a ceiling you control, not one they set",
    "hard_latency_ms": "no service level means no latency floor",
}


def audit(ledger: dict) -> list[tuple[str, str]]:
    hits = [(c, RED_LINES[c]) for c in ledger.get("capabilities", []) if c in RED_LINES]
    if ledger.get("hard_latency_ms") is not None and not ledger.get("fallback"):
        hits.append(("hard_latency_ms", RED_LINES["hard_latency_ms"]))
    return hits


ledger = json.loads(open(sys.argv[1]).read())
hits = audit(ledger)
for cap, why in hits:
    print(f"RED LINE  {ledger['job']}: {cap} -> {why}")
sys.exit(1 if hits else 0)

Running it against the sample above exits 1 with one line naming the durable write. The team then either adds a second writer or marks the job as an accepted, owned exception. Both outcomes are fine. Silence is the only failure mode the lint exists to prevent.

Artifact 2: the detach drill

Exit criteria are worthless if nobody can measure the exit. The drill runs one command twice: once normally, once with every provider base URL pointed at a port that refuses connections. Nothing else changes. The job's behavior in the second run is your true portability story.

#!/usr/bin/env python3
# detach_drill.py - unexecuted template. Usage:
#   python detach_drill.py ./data/jobs.db python -m app.worker --once
import hashlib
import os
import subprocess
import sys
import time

DETACHED = {
    "OPENAI_BASE_URL": "http://127.0.0.1:9/v1",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:9/v1",
}  # port 9 refuses immediately; no server is started on purpose


def digest(path: str) -> str:
    h = hashlib.sha256()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(65536), b""):
            h.update(chunk)
    return h.hexdigest()[:12]


def run(cmd: list[str], extra_env: dict, timeout: int = 180) -> dict:
    env = {**os.environ, **extra_env}
    t0 = time.monotonic()
    proc = subprocess.run(cmd, env=env, capture_output=True, text=True, timeout=timeout)
    stderr_tail = proc.stderr.strip().splitlines() or [""]
    return {
        "exit": proc.returncode,
        "secs": round(time.monotonic() - t0, 1),
        "tail": stderr_tail[-1][:160],
    }


def drill(cmd: list[str], state_file: str) -> bool:
    before = digest(state_file)
    wired = run(cmd, {})
    detached = run(cmd, DETACHED)
    after = digest(state_file)

    checks = {
        "wired_succeeds": wired["exit"] == 0,
        "detached_fails_loud": detached["exit"] != 0,
        "detached_fails_fast": detached["secs"] < 15,
        "state_untouched": before == after,
    }
    for name, ok in checks.items():
        print(f"{'PASS' if ok else 'FAIL'}  {name}")
    print(f"  wired    exit={wired['exit']} {wired['secs']}s {wired['tail']}")
    print(f"  detached exit={detached['exit']} {detached['secs']}s {detached['tail']}")
    return all(checks.values())


if __name__ == "__main__":
    sys.exit(0 if drill(sys.argv[2:], sys.argv[1]) else 1)

Four checks, each with a reason. detached_fails_loud catches the quietly-degrading job that swallows the error and writes perfect-looking zeros. detached_fails_fast catches the retry stack whose default backoff turns a refused connection into a six-minute hang; fifteen seconds is a starting threshold, tune it to your job's own budget. state_untouched catches partial writes, which are the only failure here that a rerun cannot repair.

Run the drill on a schedule, not once. A dependency that fails cleanly in October can fail messily in December after someone adds a single try/except.

Artifact 3: exit criteria with thresholds

A criterion without a number is a feeling. Each row below names something you can observe in logs or a dashboard, a threshold committed to in advance, and the action that follows automatically.

Observable signal	Committed threshold	Action when crossed
Free path p95 vs paid path p95	Free path above 2x for 3 consecutive days	Route the job to the paid path
Detach drill result	Two consecutive failures	Remove the free endpoint from that job
Pages attributable to the endpoint	More than one per month	Move to a paid or self-hosted deployment
Vendor-stated allowance remaining	Consumed before day 20 of the month	Add budgeting in code, not throttling in comments
Fallback path usage	Zero invocations for 90 days	The fallback is untested; drill it or delete it

The last row is the one teams skip. An untested fallback is a comment.

Where a free endpoint legitimately belongs

MonkeyCode is an open-source project offering free model access and a free server option; the operator states a free allowance on the order of ten million tokens, which should be read as a vendor-stated figure and verified on the project's own pages rather than treated as measured capacity. The honest use in this article is narrow and real: the drill needs a target you are willing to break.

Pointing detach_drill.py at a free endpoint costs nothing and teaches you the shape of your own code. The same free server option is a reasonable place to host the throwaway harness, the ledger lint, and a staging copy of the job under test — work whose worst outcome is a wasted afternoon.

That is also the boundary. Regulated data, identity issuance, anything that writes a system of record, and any latency promise you have put in a contract all sit outside it. Those need a paid tier with terms, or your own hardware, and the stop list should say so in the first paragraph rather than the last.

Limitations of this approach

The drill measures your code's shape, not the endpoint's reliability. It will not warn you that a free allowance is being reduced, and it cannot distinguish a graceful refusal from a graceful refusal that happens to return the wrong answer — for that you need assertion-level tests on output content, which is a different artifact.

All three snippets above are unexecuted templates. Port numbers, timeouts, file paths, and environment variable names must be adapted to your stack before anyone trusts a pass.

Finally, a stop list ages. Put a review date on the file, and treat a stale ledger as a red line of its own, because the risk being managed is not the free tier — it is the assumption that nothing about it will change.

Before the Free Tier Becomes Load-Bearing

Casey Li — Fri, 16 Oct 2026 05:33:09 +0000

Before the Free Tier Becomes Load-Bearing

Free model endpoints and free servers are the cheapest way to learn whether an idea deserves to exist. They are also the easiest place to build a dependency nobody agreed to maintain. Picking a free tier takes an afternoon; writing the exit criteria while it still feels like a gift takes discipline.

A workload fits free capacity only when three questions come back boring. Is the call reversible? Does anyone downstream have a deadline on the result? Would a silent failure look like a wrong answer, or merely a slow one? Two uncomfortable answers are enough to move the workload off the free tier, regardless of how pleasant last Tuesday's latency looked.

MonkeyCode is an open-source project that offers free model access and a free server option; the operator of this account states a free allowance of ten million tokens alongside that server. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Free offerings move, so read the current terms on the project's own pages and treat everything below as method rather than as a price list.

The news cycle keeps arguing about what models can do. The quieter question, where the request actually lands and who answers it at 03:00, decides whether a bad afternoon becomes an outage with your name attached.

Score the workload, not the endpoint

Write the workload down as three facts before you touch a base URL. Does it mutate something a human will later trust? Does another system wait on it synchronously? Can you regenerate the output from inputs you still hold? An internal note summariser answers no, no, yes, and that is a green light. A payment decision, an access grant, or a lease renewal answers yes, yes, no, and free capacity does not change the answer.

The same test applies to the free server. It is a room you rent, not a filing cabinet. Scratch environments, preview deploys, and throwaway reproductions belong there; anything you would have to restore belongs somewhere with a restore story you have already rehearsed.

A triage script you can run in five minutes

The script below probes an OpenAI-compatible chat endpoint, reports a median and a worst case, and prints a verdict. It uses only the standard library, so it runs from a laptop, a CI job, or a container without a dependency install.

#!/usr/bin/env python3
"""Triage a free model endpoint. Stdlib only."""

import json
import os
import statistics
import time
import urllib.error
import urllib.request

BASE = os.environ['FREE_BASE_URL'].rstrip('/')
KEY = os.environ['FREE_API_KEY']
MODEL = os.environ['FREE_MODEL']
N = int(os.environ.get('PROBES', '20'))
WORST_BUDGET_MS = float(os.environ.get('P99_BUDGET_MS', '4000'))
ERROR_BUDGET = float(os.environ.get('ERROR_BUDGET', '0.02'))


def one_probe(timeout=30.0):
    payload = json.dumps({
        'model': MODEL,
        'messages': [{'role': 'user', 'content': 'reply with the single word ok'}],
        'max_tokens': 4,
    }).encode()
    request = urllib.request.Request(
        f'{BASE}/chat/completions',
        data=payload,
        headers={'Content-Type': 'application/json',
                 'Authorization': f'Bearer {KEY}'},
    )
    started = time.perf_counter()
    try:
        with urllib.request.urlopen(request, timeout=timeout) as response:
            response.read()
        return (time.perf_counter() - started) * 1000, None
    except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError) as exc:
        elapsed = (time.perf_counter() - started) * 1000
        return elapsed, f'{type(exc).__name__}:{getattr(exc, "code", "?")}'


def main():
    ok_ms, failures = [], []
    for attempt in range(1, N + 1):
        elapsed, error = one_probe()
        if error:
            failures.append(error)
            print(f'probe {attempt:02d} {elapsed:8.1f} ms  FAIL {error}')
        else:
            ok_ms.append(elapsed)
            print(f'probe {attempt:02d} {elapsed:8.1f} ms  ok')

    error_rate = len(failures) / N
    median_ms = statistics.median(ok_ms) if ok_ms else float('nan')
    worst_ms = max(ok_ms) if ok_ms else float('nan')
    print(f'\nok={len(ok_ms)}/{N} error_rate={error_rate:.1%} '
          f'median={median_ms:.0f}ms worst={worst_ms:.0f}ms')

    if error_rate > ERROR_BUDGET * 3 or worst_ms > WORST_BUDGET_MS * 3:
        print('RED    remove it from the request path')
    elif error_rate > ERROR_BUDGET or worst_ms > WORST_BUDGET_MS:
        print('AMBER  keep it behind a queue with a fallback')
    else:
        print('GREEN  exploratory and batched work only')


if __name__ == '__main__':
    main()

Run it from two places. One vantage point measures the path between your desk and the service more than it measures the service itself. A CI runner and a laptop on a different network give you two independent observations; if they disagree by an order of magnitude, you have learned something about routing before you learned anything about capacity.

export FREE_BASE_URL='https://your-endpoint/v1'
export FREE_API_KEY='...'
export FREE_MODEL='...'          # a model the free catalogue exposes today
export P99_BUDGET_MS=4000
export ERROR_BUDGET=0.02
python3 free_tier_triage.py

Reading the numbers honestly

Twenty probes cannot prove anything about a weekday peak, and the script does not pretend otherwise. It reports a median and a worst case on purpose: a median hides the tail, and an average hides both. A median of 700 ms with a worst case of 22 seconds describes an endpoint that is fine until it is not, which is precisely the shape of dependency that hurts.

Treat the output as a triage label, not a certificate.

Signal	Example threshold	Verdict	Action
Error rate across two runs	above 2%	amber	queue it, add a fallback
Worst case above budget	above 4 s	amber	hard timeout plus a deadline
Worst case above 3x budget	any run	red	take it out of the request path
Any irreversible write	always	red	keep it on the primary path
Data with retention or residency obligations	always	red	do not send it

The table matters less than the fact that you filled it in before the first production request. Numbers agreed in advance end arguments; numbers invented after an incident only start them.

Five red flags worth writing down

Irreversible writes are the first. If the free call is the only thing that can commit a decision, its availability becomes your correctness, and no amount of retry logic repairs that.

An externally promised deadline is the second. Once you publish a latency target to a customer or another team, free capacity is disqualified by commitment rather than by benchmark, and that is a governance decision, not a technical one.

Regulated, personal, or client-owned data is the third. Free capacity is not the place for it, even for a demo that "nobody will see," because demo data has a habit of becoming seed data.

A single measurement vantage is the fourth. One laptop, one network, one conclusion; the second vantage point is what turns an anecdote into evidence.

No named owner for the exit is the fifth, and it is the one that keeps free tiers alive long past their usefulness. If nobody owns the switch, the default is to stay.

When something else is the better answer

For anything user-visible with a deadline, a paid or self-hosted endpoint on your own request path is the honest choice, and a queue with bounded concurrency in front of the free tier is the compromise when cost dominates. For classification, extraction, and summarisation where a deterministic fallback exists, a rules engine or a cache first, then the model, will usually beat a model-first design on both cost and predictability. For regulated workloads, the free server is still useful as a place to reproduce a bug against synthetic data, and that is the whole of its role.

None of this argues against free capacity. It argues for keeping it where failure is cheap: experiments, batch jobs that can be re-run, drafts a human will read anyway, and the scratch environment where you test the migration you will eventually perform.

Exit criteria, agreed before the first request

Write four triggers and one rehearsal. The triggers are numeric, not emotional: error rate above budget on two consecutive probe runs, any externally promised latency target, any regulated data entering the pipeline, or a second team starting to depend on the path. The rehearsal is a shadow run: send the same frozen sample through the replacement endpoint for a day, compare outputs, and only then flip the switch, which should be one environment variable and one deploy.

Add a review date, because free tiers are not stable facts. A path that was fine in October can be the wrong shape by January, and the calendar is a cheaper reminder than an incident.

Who should not do this

Skip the free tier entirely if you handle data you cannot legally send to a third party, if your product promises sub-second interaction, if you need tenant isolation you can point at in an audit, or if you need a contract with a name on it. Skip it too if you have no way to measure: an unmeasured free dependency is not a strategy, it is a coin flip with extra steps.

If you want a free endpoint to run the rubric against, MonkeyCode's open-source project is the one this account works with, and the probe script is a better first step than an architecture diagram.

A Free Reviewer Should Comment, Never Block

Casey Li — Thu, 15 Oct 2026 11:34:09 +0000

A Free Reviewer Should Comment, Never Block

The free tier is the right home for a model that only ever produces comments. The moment a required check, a protected-branch rule, or a paging alert depends on it, a paid responsibility has been moved onto capacity that nobody promised to keep running. That failure mode is not a slow review. It is a merge queue with no owner.

That is the argument. The rest of this piece is the field guide for staying on the correct side of it.

What the free tier is, and what that implies

MonkeyCode is described by its maintainers as an open-source project offering free model access and a free server option; the same material advertises a free allowance on the order of ten million tokens. Those are operator-supplied availability claims rather than measured results, and the part of any free tier most likely to move is the quota itself. Check the project's own documentation before sizing a pipeline against a number.

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

None of that makes free access a poor choice. It makes it a specific one: inexpensive, genuinely useful, and outside your control. Workloads should be sorted along that single axis before anything else is decided. A process that posts a review comment fits the free tier well. A process that decides whether a merge is allowed does not, because the second one is a gate, and gates are contracts. Contracts need a party that answers when they break.

The split that keeps this honest

The workflow that survives contact with a free tier has two jobs, not one. The advisory job may fail at any time and nobody notices. The gate job is deterministic, boring, and owned by you. They share a repository and nothing else.

The reviewer below reads a diff on stdin, prints comments, and returns zero no matter what happens. That final return is the design, not laziness: an advisory reviewer that can fail a build is a gate wearing the wrong name.

# advisory_review.py - illustrative, not executed for this article.
import json, os, sys, urllib.request

BASE = os.environ['FREE_BASE_URL']   # confirm the current endpoint from the project docs
KEY  = os.environ['FREE_API_KEY']
MAX_DIFF_BYTES = 60_000              # a partial review beats a dead job

def ask(diff):
    payload = {
        'messages': [
            {'role': 'system', 'content':
             'Review the diff. Return one JSON object per line: '
             '{"path": str, "note": str}. No summary, no praise.'},
            {'role': 'user', 'content': diff},
        ],
        'max_tokens': 700,
        'temperature': 0,
    }
    req = urllib.request.Request(
        BASE + '/chat/completions',
        data=json.dumps(payload).encode(),
        headers={'Authorization': 'Bearer ' + KEY,
                 'Content-Type': 'application/json'},
    )
    with urllib.request.urlopen(req, timeout=45) as resp:
        return json.load(resp)['choices'][0]['message']['content'].splitlines()

def main():
    diff = sys.stdin.read()
    if len(diff) > MAX_DIFF_BYTES:
        print('::notice::diff truncated at %d bytes; review is partial'
              % MAX_DIFF_BYTES)
        diff = diff[:MAX_DIFF_BYTES]
    try:
        for line in ask(diff):
            print('::warning::' + line)
    except Exception as exc:
        # The entire point: unavailability is a non-event.
        print('::notice::advisory reviewer unavailable (%s); gate unaffected' % exc)
    return 0

if __name__ == '__main__':
    sys.exit(main())

Two details carry most of the value. The 60 KB truncation is stated out loud, because a silent truncation teaches reviewers to distrust comments they cannot verify. The broad exception handler does not swallow a bug; it converts an outage into a log line, which is the correct weight for a comment.

The workflow then keeps the two concerns physically separate:

# .github/workflows/review.yml - illustrative.
name: review
on: pull_request

jobs:
  advisory:
    runs-on: ubuntu-latest
    continue-on-error: true        # belt
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - env:
          FREE_BASE_URL: ${{ secrets.FREE_BASE_URL }}
          FREE_API_KEY: ${{ secrets.FREE_API_KEY }}
        run: git diff origin/${{ github.base_ref }}...HEAD | python3 advisory_review.py

  gate:
    runs-on: ubuntu-latest         # no shared steps, no shared secrets
    steps:
      - uses: actions/checkout@v4
      - run: make lint test

The gate job never imports the reviewer, never reads its secrets, and never waits on it. That independence is the artifact worth copying. Everything else here is a variation on a single HTTP call.

One weekly measurement keeps the arrangement from drifting:

#!/usr/bin/env bash
# reviewer_drift.sh - illustrative. Summarises the last 100 advisory runs.
set -euo pipefail
runs=$(gh run list --workflow review.yml --limit 100 --json conclusion)
total=$(jq 'length' <<<"$runs")
failed=$(jq '[.[] | select(.conclusion != "success")] | length' <<<"$runs")
awk -v t="$total" -v f="$failed" 'BEGIN {
  printf "advisory runs: %d\nunavailable:   %d\nrate:          %.1f%%\n", t, f, (t ? 100*f/t : 0)
}'
# Policy, not product: above roughly 5% the reviewer becomes an outage you
# keep explaining. Above roughly 20% nobody reads the comments any more, and
# the free tier has stopped working for you while remaining free.

Where the line actually sits

The distinction is not open source against paid. It is whether a failure costs a re-read or a release.

Workload	Free tier	Why
Advisory comment on a side-project PR	Yes	A missed comment costs a re-read.
Inline autocomplete for one developer	Usually	Slow output annoys rather than blocks.
Drafting a changelog line from a merged diff	Yes, human-signed	A person still owns the wording and the publish.
Required status check on a protected branch	No	The free tier now holds the merge bit.
Deciding whether to replay a webhook or page a human	No	Failures arrive as missing work, not as errors.
Inputs already governed by a third-party processing rule	Decide first	The free path is the one people take by accident.

Where the free tier is wrong, three alternatives are usually better: a deterministic linter, a paid endpoint with a written response time, or a human checklist that takes ten minutes. Each of them can fail loudly, which is more than can be said for a comment bot that quietly stopped posting.

The last two rows of the table are where quiet incidents live. A reviewer that never runs looks like a quiet week. A webhook that never replays looks like a customer who stopped ordering.

Red flags worth acting on immediately

Four signals, in the order they usually appear.

The reviewer starts showing up in an incident channel. Once a comment bot has uptime expectations, it is infrastructure, and free capacity is not offered with uptime expectations attached.

A fallback branch approves when the model is unavailable. Failing open on a gate converts every provider hiccup into an unreviewed merge. Failing closed is defensible; failing open with a green check is not.

Prompts begin to contain production rows, customer identifiers, or a full private export, because the free path was the shortest one. That decision belongs to whoever owns data policy, and it is usually made by accident on a Friday afternoon.

Nobody can reconstruct last Tuesday's reviews from logs. If the advisory job's inputs and outputs are not retained, the pipeline has no history, and no one can say whether the reviewer ever helped.

Exit criteria

Three checkable rules, written so a person can act on them without a meeting.

Promotion requires evidence. After thirty days, count how many advisory comments changed a line of code and how many distinct people acted on them. Meaningful conversion by more than one person justifies dedicated, contracted capacity. It does not justify promoting free capacity into a required check.

Failure rate has a ceiling. Cross five percent unavailability in a week and the reviewer is either noise to accept or a dependency to move. Above twenty percent the comments have stopped being read; keep the job for the archive and stop pretending it informs anything.

Scope has a boundary. The moment the reviewer needs a credential broader than read access to the repository it reviews, the free tier is the wrong host and the design is wrong regardless of host.

Limitations and who should skip this

This approach assumes a repository where a merge can be paused safely. Teams under an audit obligation that requires a named approver per change need a record of who approved what, and an advisory bot produces no such record. Regulated environments should settle the data-processing question before any diff leaves the network. Groups that need a contractual response time cannot get one from a free tier, and should not paper over that by wiring it into a gate.

The approach is also weak on large diffs. Truncation keeps the job alive and makes the review partial by construction, so a monorepo with thousand-line pull requests will see shallow comments. That is an acceptable trade for a comment and an unacceptable one for a gate.

If any of the red flags above look familiar, the free tier is still a reasonable place to measure them for a month before buying anything. Bring it in as a commenter, read the output for thirty days, and let the numbers decide whether it has earned a promotion.

Leave the Receipt on the Primary

Casey Li — Tue, 13 Oct 2026 02:35:47 +0000

A free server can rehearse a handler. It cannot be the book that proves the handler already ran. That split is the whole field guide. Model quality can rise, drafts can get cleaner, and the receipt row still belongs on a store the team controls.

The failure looks small until money, mail, or a webhook fires twice. A process on a scratch host writes done into a local file, the host is reclaimed, and the next boot treats the work as new. The side effect was real. The memory of it was not.

A rehearsal stage can host the scene. It is a poor box office. This note is about outbound effects, not about a consumer offset. The offset problem is a reader advancing a cursor too early. The receipt problem is a sender forgetting that the outside world was already called.

What the scratch path is for

Free model access is useful for drafting the handler, the failure notes, and the tests. A free server is useful for running that draft against fixtures the operator can throw away. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Those two options are availability claims supplied for this draft, not a quota, a hardware bill, or a promise that the path stays up.

No model name, token ceiling, or retention window is asserted here. None of those figures was verified against a primary source for this piece. A cleaner completion does not move the system of record. Software still has to remember what it already did after the process is gone.

The draft is a proposal. It is not an executed production trace. Treat generated code the way a team treats a patch from a new teammate: read it, run it where loss is cheap, and refuse to let it appoint itself as the ledger.

The invariant

Commit the receipt on the primary before the side effect, or do not perform the side effect. The primary is the database, queue, or object store the team already trusts for orders and audits. The scratch host may cache a copy for the length of a test. It may not be the only copy.

A receipt is a small row: an idempotency key, a status, a payload hash, and a timestamp the primary assigns. If the row is already done, the handler returns the stored result and does not call the downstream again. If the scratch disk disagrees with the primary, the primary wins.

That rule closes a class of double-send bugs that no smoother draft will fix by wording alone. Think of the free host as a practice room with a piano that can be rolled away overnight. The set list can be rehearsed there. The ticket stub that says a customer already paid has to live in the office safe.

A reproducible check

The following Python is an illustrative harness, not a benchmark and not a claim about any vendor runtime. It uses the standard library only so a reader can run it on a laptop. SQLite stands in for a primary the team owns. It is not a suggestion to keep the real ledger on the scratch host.

This harness is a proposal for a local check. It was not run against a vendor host while this note was written. The point is placement, not speed.

#!/usr/bin/env python3
"""Illustrative receipt placement. Not a production client."""

import hashlib
import json
import sqlite3
import tempfile
from pathlib import Path

def receipt_key(action: str, payload: dict) -> str:
    body = json.dumps(payload, sort_keys=True, separators=(",", ":"))
    return hashlib.sha256(f"{action}\n{body}".encode()).hexdigest()

def open_primary(path: Path) -> sqlite3.Connection:
    conn = sqlite3.connect(path)
    conn.execute("PRAGMA journal_mode=WAL")
    conn.execute(
        """
        CREATE TABLE IF NOT EXISTS receipts (
            key TEXT PRIMARY KEY,
            status TEXT NOT NULL,
            result TEXT
        )
        """
    )
    conn.commit()
    return conn

def claim(conn: sqlite3.Connection, key: str) -> str:
    cur = conn.execute(
        "INSERT INTO receipts(key, status, result) VALUES (?, 'claimed', NULL) "
        "ON CONFLICT(key) DO NOTHING",
        (key,),
    )
    conn.commit()
    if cur.rowcount == 1:
        return "owned"
    row = conn.execute(
        "SELECT status FROM receipts WHERE key = ?", (key,)
    ).fetchone()
    return row[0] if row else "missing"

def finish(conn: sqlite3.Connection, key: str, result: str) -> None:
    conn.execute(
        "UPDATE receipts SET status = 'done', result = ? WHERE key = ?",
        (result, key),
    )
    conn.commit()

def perform_once(conn: sqlite3.Connection, action: str, payload: dict, effect) -> str:
    key = receipt_key(action, payload)
    state = claim(conn, key)
    if state == "done":
        row = conn.execute(
            "SELECT result FROM receipts WHERE key = ?", (key,)
        ).fetchone()
        return row[0]
    if state != "owned":
        raise RuntimeError(f"refusing side effect; receipt state={state}")
    result = effect(payload)
    finish(conn, key, result)
    return result

def demo() -> None:
    calls = {"n": 0}

    def send_mail(payload: dict) -> str:
        calls["n"] += 1
        return f"sent:{payload['to']}"

    with tempfile.TemporaryDirectory() as tmp:
        primary = open_primary(Path(tmp) / "primary.db")
        payload = {"to": "ops@example.test", "body": "cutover check"}
        first = perform_once(primary, "mail", payload, send_mail)
        second = perform_once(primary, "mail", payload, send_mail)
        assert first == second == "sent:ops@example.test"
        assert calls["n"] == 1
        print("primary_receipt_ok", calls["n"])

if __name__ == "__main__":
    demo()

Save it as receipt_placement.py and run it where a lost temp directory is acceptable.

python3 receipt_placement.py

The expected line is primary_receipt_ok 1. A second call in the same process must not increment the effect. That is only the happy path. A leftover claimed row must refuse the send, which is what state != "owned" is for. A sweeper, not another prompt, decides whether that stuck claim is safe to finish or must be compensated.

Debugging a double send

When a drill sends twice, ignore the model's explanation and follow the disk. Print the receipt key, then query the primary, not the scratch log. If the primary has no row, the handler performed an effect without a claim.

If the primary has claimed and never done, the crash sat in the gap, and a sweeper owes a decision. If the primary has done and the effect still ran, the handler ignored its own row. Those three shapes have different fixes. Retrying the prompt is not one of them.

A placement probe makes the scratch host fail on purpose. Copy the fixture primary to a path the team keeps, delete the temporary directory that stood in for the free server, and open only the copied primary. Call the same payload again with a counter that starts at zero in the new process. The counter must stay at zero, and the stored result must come back.

# Fixture paths only. Do not point this at a production file.
cp /tmp/drill/primary.db "$HOME/receipt-fixtures/primary.db"
rm -rf /tmp/drill
sqlite3 "$HOME/receipt-fixtures/primary.db" \
  "SELECT status, result FROM receipts LIMIT 5;"

If the only passing run is the one where scratch and primary share a fate, the test is grading the wrong disk. The command is a shape for the check, not a production runbook.

Red flags

The scratch host is holding the only receipt when a restart would resend. That is the first flag. The second is a generated handler that writes status to /tmp, or to an in-memory map, and then calls a real provider. The third is a review comment that calls the free server durable enough for now. Durability is a property of the store and the backup story, not a mood.

A fourth flag shows up in the prompt, not the disk. If the model is asked to decide whether a charge, a delete, or a customer email already happened, authority has moved into a draft. The model can propose the branch. The primary row decides the branch. A fluent account of a missing receipt is not a receipt.

Clock skew on a free server is another quiet flag. If expiry math lives only on that host's clock, a stepped clock can reopen a closed key. Store the deadline in the primary, and compare against a time the primary records. The scratch host may display the value. It should not invent it.

Better alternatives

Keep the receipt table, or an equivalent unique constraint, on the same primary that owns the business row. Use the free server as a client of that primary during a drill, with a test schema and fake downstreams. If the primary cannot be reached from the drill, stop the side effect. A skipped send is cheaper than a second send the ledger cannot remember.

When the team has no primary yet, the alternative is not to crown the free server. Stand up a store with backups and a named owner first, even if that store is a single small database on hardware the team administers. Free model access can still draft the migration and the handler. The draft waits until the store exists.

For pure read-only exploration, skip the receipt path entirely. Fixtures, recorded responses, and a local stub are enough. The moment the code can reach a real mailbox, payment API, or webhook target, the receipt rule turns on. A free server remains a fair place to run the stub. It is a bad place to be the only memory of a live call.

Exit criteria

Leave the free server as the status holder when any of these become true. The handler can cause a customer-visible side effect. The receipt must survive a host rebuild. More than one worker can claim the same key. An auditor asks where the proof lives, or a deploy pipeline would promote the scratch disk into the only copy of status.

Exit does not mean abandon the drafting loop. It means the loop's output is a patch against the primary schema, reviewed like any other patch. The free path keeps generating candidates. The primary keeps the bit that says the work finished.

A practical cut line sits in operations, not in taste. If losing the scratch host tonight would cause a resend, a double refund, or a gap in the audit trail, the receipt is already late. Move it before the next real call. Confidence in a draft is not a reason to stay.

Who should not use this split

Teams that need the free host to be their only database should not follow this guide as a workaround. They need a real store, not a clever prompt. Workloads that cannot tolerate a claim row stuck in claimed after a crash need a sweeper and a compensation path this sketch does not provide.

The harness also ignores authentication, encryption, and multi-region clocks. Copying it into a payment service as-is would be a mistake. Anyone who needs a published quota, a named model, or a retention guarantee should stop at the operator's current docs rather than infer them from a field note.

This article does not measure latency, does not rank providers, and does not say the free options are permanent. Readers who want a rehearsal bench can try the free model access and the free server for drafts and fixtures, and leave the receipt book on the primary.

Closing the ledger

The useful habit is boring, which is why it survives a trend cycle. Draft on the cheap path. Prove the effect once. Store the proof where a vanished scratch disk cannot erase it.

Better completions will keep arriving. The row that says the mail already went out should not have to arrive with them.

Keep Lease Renewal Off the Free Host

Casey Li — Sun, 11 Oct 2026 22:08:04 +0000

A free model may explain a stuck lock. A free server may store the redacted trace. Neither may mint a fencing token, extend a lease, or declare that a worker still owns the resource. Renewal is a clock decision, and the clock has to share a crash domain with the writer.

Double writes rarely look dramatic in the log. Two workers each received a late yes, each appended a batch, and each recorded success. The free host sounded sure. The scratch server was already up for a demo, so the renewal helper landed there by habit. Habit is not a fence.

A delayed answer from a host the worker does not control is just another packet. Packets do not own rows. Stronger language models do not change that fact. A clearer sentence about a lost lease is still a lost lease.

This field guide draws the boundary in the other direction. The process that can crash with the worker keeps the token, the expiry, and the admit bit. A remote assistant sees a redacted snapshot only after that bit is settled. Operators who want a scratch reader for those snapshots can use MonkeyCode's free model access and free server option for narration, not for the lease table. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Those two availability claims are operator-supplied. This article does not state model names, token quotas, hardware sizes, durations, or permanence, because those details were not verified from a primary source for this draft.

A lease is timed permission, not a paragraph about permission. The owner records a resource key, a monotonic fencing token, and an expiry measured on a clock it trusts. A contender may request renewal. Admission happens only when the token matches and that same clock still shows time left, or when a deliberate handoff has already stored a successor token.

A free host that can be reset, shared, or slowed by someone else's experiment cannot make that call. If the worker must ask it whether a write is still legal, the design has already fail-opened. The coat-check stub is the right picture. A careful description of the coat helps the person searching the rack, and it still does not authorize a new stub.

Narration and issuance are different jobs. Only narration may sit on a convenience host. Several smells show that issuance has already drifted, and each one is worth catching in review before the next incident writes it into the postmortem.

A renewal that succeeds only after an HTTP round trip to an unadministered host is the first smell. Timeouts become a policy argument. Teams under a deadline treat timeout as still-owner, because the other reading stops the job. That generous reading is how two writers enter the same shard.

A second smell sits in the prompt. The current fencing token appears in a tool schema, and the model is asked to return whether renewal should proceed. The token has left the building. Free-tier logs and scratch disks now hold a capability, and obedience to the reply completes the delegation even when the prompt said advice only.

A third smell is operational rather than syntactic. The free server became the lease table because the demo container was already running. Scratch hosts get wiped. Shared capacity gets reused by the next exercise. A lock table that can disappear between acquire and renew is a whiteboard with a timer painted on it.

The fourth smell is the absence of a local deny. When the advisor is down and the worker writes anyway, the advisor was the lock, and the default was fail-open. Fail-open can caption a graph. It cannot own a partition.

The split worth keeping is small enough to test on a laptop. The worker admits or refuses renewal locally. A side task exports a snapshot that says whether a token exists and how many milliseconds remain. That snapshot may travel. The integer token may not.

The following module is an unexecuted reference implementation. It is not a benchmark, and it is not a claim about any hosted product. The source label is a teaching guard, not authentication.

#!/usr/bin/env python3
"""Local lease gate. Unexecuted reference; not a measured lock service."""

from __future__ import annotations

import time
from dataclasses import dataclass


class LeaseError(Exception):
    pass


@dataclass
class Lease:
    resource: str
    token: int
    expires_at: float


class LocalLeaseOwner:
    def __init__(self, now=time.monotonic):
        self._now = now
        self._leases: dict[str, Lease] = {}
        self._next = 1

    def acquire(self, resource: str, ttl_s: float) -> Lease:
        if ttl_s <= 0:
            raise LeaseError("ttl must be positive")
        now = self._now()
        current = self._leases.get(resource)
        if current and current.expires_at > now:
            raise LeaseError("resource still leased")
        lease = Lease(resource, self._next, now + ttl_s)
        self._next += 1
        self._leases[resource] = lease
        return lease

    def renew(self, resource: str, token: int, ttl_s: float, source: str) -> Lease:
        if source != "local-worker":
            raise LeaseError("refuse renewal from %s" % source)
        if ttl_s <= 0:
            raise LeaseError("ttl must be positive")
        now = self._now()
        current = self._leases.get(resource)
        lost = (
            current is None
            or current.token != token
            or current.expires_at <= now
        )
        if lost:
            raise LeaseError("lost lease; do not write")
        renewed = Lease(resource, token, now + ttl_s)
        self._leases[resource] = renewed
        return renewed

    def redact_for_narration(self, resource: str) -> dict:
        current = self._leases.get(resource)
        if current is None:
            return {
                "resource": resource,
                "state": "absent",
                "token_present": False,
            }
        remaining = current.expires_at - self._now()
        state = "held" if remaining > 0 else "expired"
        return {
            "resource": resource,
            "state": state,
            "remaining_ms": max(0, int(remaining * 1000)),
            "token_present": True,
        }


def _demo() -> None:
    clock = {"t": 0.0}
    owner = LocalLeaseOwner(now=lambda: clock["t"])
    lease = owner.acquire("invoice-batch-7", 5.0)
    owner.renew("invoice-batch-7", lease.token, 5.0, "local-worker")
    try:
        owner.renew("invoice-batch-7", lease.token, 5.0, "free-host")
    except LeaseError as exc:
        assert "refuse renewal" in str(exc)
    else:
        raise SystemExit("remote renewal must fail")
    trace = owner.redact_for_narration("invoice-batch-7")
    assert trace["token_present"] is True
    assert "token" not in trace
    print("local renewal admitted; remote renewal refused; trace redacted")


if __name__ == "__main__":
    _demo()

A local check is enough to pin the boundary. It does not prove cluster safety. It proves the reference refuses the wrong source and withholds the capability from the narration payload.

python3 lease_gate.py

An expiry check belongs beside that smoke test. Advance a fake clock past the deadline and require the local source to fail closed too. A gate that only distrusts remote names, while renewing stale local tokens, is half a fence.

python3 - << 'PY'
import lease_gate as gate
clock = {"t": 0.0}
owner = gate.LocalLeaseOwner(now=lambda: clock["t"])
lease = owner.acquire("shard-a", 1.0)
clock["t"] = 1.1
try:
    owner.renew("shard-a", lease.token, 1.0, "local-worker")
except gate.LeaseError as exc:
    print("expired renew denied:", exc)
else:
    raise SystemExit("expired lease must not renew")
PY

Reviewers can also search the worker tree for renewal calls that do not stay on the local owner. A hit is a defect, not a feature flag. An attacker-controlled label is not a trust boundary. The real boundary is a missing network method.

grep -n "renew(" worker.py | grep -v "local_owner.renew"
grep -R "fencing_token" logs/ && echo "token leaked into logs"

Better homes exist for a real lock, and they are dull on purpose. A primary database row updated with compare-and-swap on the resource and the token keeps the fence next to the data. A consensus service the team already runs is appropriate when more than one machine must agree. A partitioned queue that never assigns the same key to two workers removes the shared lease entirely.

Each of those options fails in its own way. None of them fails because a demo server was recycled. The compare-and-swap itself can be stated as a single guarded update, with the clock read on the primary rather than supplied by a narrator.

UPDATE leases
SET expires_at = now() + interval '5 seconds'
WHERE resource = $1
  AND token = $2
  AND expires_at > now();

Zero rows means the worker has lost the lease and must not write. The statement does not consult a model. It does not consult a scratch server. If now() on the primary and the worker clock disagree beyond the safety margin, the team fixes the clocks. It does not average them inside a prompt.

Explanation still has a place. This is where a free model earns its keep without touching the bit. Feed it the redacted snapshot. Ask for a timeline of acquire, last local renew, and expiry, written as sentences a new on-call can read. Ask which log line contradicts the worker's belief that it still holds the shard, then stop.

A sentence that recommends a write is a comment in a ticket, not an input to the gate. Paste the snapshot. Do not paste the token in order to make the prose richer. Richer prose is not worth a leaked capability.

A free server can hold that snapshot overnight: a file, a notebook, a static note for the reader. It should not hold the token table, the worker clock, or a cron that calls renew. Scratch space is for artifacts a human can delete without paging the data owner. Lease state is not one of those artifacts.

The operational picture is easy to say and easy to violate. The worker acquires and renews against the local owner or the primary store. Every renewal is a compare-and-swap. A side process exports the redacted snapshot on a timer.

If the side process dies, renewals continue. If the free host dies, renewals continue. If the primary store dies, writers stop. That last clause is the availability trade. Moving it into a helpful model call does not delete it.

Leave the free path, and do not return, when any one of these is true. The write is externally visible, such as a payment capture, a customer message, a DNS change, or a migration commit. The cost of a double write exceeds the cost of a delayed job. Two workers can hold the same key during a rolling deploy.

Nobody can name the clock that decides expiry. The reset, sleep, or reuse policy of the free server is unknown. One hit is enough to keep renewal local. Several hits mean the design was never a prototype. It was an unowned lock with a notebook attached.

Exit is finished only when three quiet checks pass, outside an incident. A remote source cannot renew, and deleting the guard fails the smoke test in the refusing direction. Application logs or a packet capture show no fencing token traveling toward the free host. Killing the free server does not change renew latency, because that server was never on the renew path.

Until those three are true, the narration hook is a second lock with a polite voice. Do not declare the integration done because the demo transcript read well.

Some teams should not use this split at all. Multi-region mutual exclusion needs a protocol that already defines partitions, fencing, and membership. The sample above is one process and one dict. It will not survive a second machine, and dressing the dict up with a remote narrator does not add a region.

People measuring model accuracy should not cite the script as a score. It never calls a model. Operators who want a model to run the cluster should not begin with lease renewal. Begin with read-only comments on redacted logs, and leave write tools unplugged.

Teams that cannot rotate the token store should not export traces, redacted or otherwise, until that store is local and boring. Free model access is the wrong tool when the prompt is only useful if it contains secrets, customer payloads, or the token itself. The fix is to delete fields until the prompt is harmless, not to hunt a larger window.

A free server is the wrong disk when the data must survive a reset, meet a retention rule, or stay inside a network boundary the free option does not claim. An unknown boundary is a reason to stay home. Unknown quotas are the same kind of reason. A draft that cannot cite a current primary source for a numeric limit should not invent one in order to sound specific.

This guide does not score MonkeyCode uptime, answer quality, or numeric limits. It does not claim the sample ran in CI. It does not improve on published lease algorithms. It only refuses to relocate their admit bit.

Laptop suspend can still jump a clock, and a production owner has to define that case before trusting a five-second TTL. Remote lock managers are legitimate when they are operated as lock managers. They are not legitimate just because a free host was idle on a Thursday.

Park redacted traces with a free reader if that helps the on-call. Keep the token on the clock that already owns the write.

When the Scratch Host Must Not Hold the Oracle

Casey Li — Sat, 10 Oct 2026 18:50:23 +0000

A free model pass is a draft signal, not a release gate. The golden fixture, its content hash, and the bit that says a change may ship stay on infrastructure the team already owns and can replay without a vendor round trip. A hosted assistant can suggest a patch, and a spare host can run a throwaway smoke. Neither is the system of record for whether the suite passed.

The blur starts when the assistant feels faster than review. A flaky assertion fails, the model rewrites the expected file so the assertion goes quiet, and a scratch host prints a green line that someone pastes into the release note. The lab notebook left the building, and the wax seal left with it. Regression evidence only holds when the same bytes can be hashed tomorrow on a machine the team administers.

That property belongs to storage and process, not to how confident the draft sounded. A helpful explanation of a stack trace does not become an oracle because it arrived quickly. The oracle is the frozen expected bytes plus a scorer the team can run offline. Speed of the sketch is a separate concern, and mixing the two is how a green log replaces a test.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. Free model access is a reasonable place to ask for a patch sketch or a failure explanation. A free server option is a reasonable place to boot a process the team can afford to throw away if the run fails. Those roles stop at the draft, and they do not extend to custody of fixtures, to the scorer, or to the pass bit other jobs trust.

Red flags, not outages

Red flags show up as ownership slips rather than as dramatic outages. A fixture appears in the assistant transcript and never lands in the repository as a reviewed diff, or the only copy of expected output sits on a host the team does not administer. The pass bit is a sentence the model wrote about its own patch, or a log line from a runner that prints green without recomputing hashes. Release timing starts to depend on whether that path answers during the window the team actually has.

Any one of those slips is enough to pull the gate back. Together they mean the suite is no longer a test, and a rumor with a timestamp will not survive the next incident review. The fix is not a stricter prompt and not a longer system message. Careful wording does not restore a file that was never committed, and it does not turn an unadministered disk into a system of record.

Three homes for the pass bit are easy to confuse because all three can print the word passed. The model transcript is cheap to read and useless as authority, since a later reader cannot replay the bytes that were judged. Disk on a free server is a fair place for a crash dump and a bad place for the only oracle, because retention and rebuild of that disk sit outside the release job. The primary runner that already produces release artifacts is slower to sketch on, and it is the only home that can refuse a drifted fixture without asking a draft for permission.

The anti-pattern is letting the transcript or the free host write a file the primary is expected to trust. Later jobs then stop opening fixtures and start reading a boolean. Booleans travel well, and they hide which tree was scored, which is why the owned pass has to carry the hash rather than a color.

A seal the draft cannot refresh

A better arrangement is dull on purpose. Fixtures live in the repo beside the code that consumes them, and a local command hashes those files before any assistant proposes an edit. The hash ignores mtime, file owner, and directory walk order, so two checkouts of the same bytes agree. The assistant may propose a source change or a fixture change, but the proposal is a diff, not a commit, and it has no path that updates the seal.

A free server may run the candidate in a scratch directory whose outputs are labeled untrusted. The owned runner checks the hash, runs the scorer the team already maintains, and is the only writer of the pass file. If the free path is down, releases slow by the time a human needs to sketch a patch. They do not stop because the oracle went missing, which is the failure this split is built to prevent.

The Python below is a proposal, not a captured run. It has not been executed against a live free server, and it states no model name, quota, or timing result. It refuses an untrusted smoke result as authority, and it stops if the fixture tree drifts after the seal. NUL separators keep a filename from colliding with contents, and sorting makes the digest independent of filesystem order.

#!/usr/bin/env python3
"""Proposal: seal fixtures locally, then reject an untrusted pass bit.

Not executed against a live free server. Point ROOT at a temp checkout.
primary-score.json must be written by the owned runner after its own suite.
A file that merely claims runner=primary-runner is not identity proof.
"""
from __future__ import annotations

import hashlib
import json
import sys
from pathlib import Path

ROOT = Path("fixtures")
SEAL = Path("fixtures.seal.json")
UNTRUSTED = Path("smoke-result.json")
PRIMARY_SCORE = Path("primary-score.json")
OWNED_PASS = Path("owned-pass.json")
OWNER = "primary-runner"

def read_json(path: Path) -> dict:
    try:
        data = json.loads(path.read_text())
    except json.JSONDecodeError as exc:
        raise SystemExit(f"bad json in {path}: {exc}") from exc
    if not isinstance(data, dict):
        raise SystemExit(f"expected object in {path}")
    return data

def tree_hash(root: Path) -> str:
    digest = hashlib.sha256()
    if not root.is_dir():
        raise SystemExit(f"missing fixture dir: {root}")
    files = sorted(p for p in root.rglob("*") if p.is_file())
    if not files:
        raise SystemExit("empty fixture dir; refuse to seal a vacuum")
    for path in files:
        rel = path.relative_to(root).as_posix()
        digest.update(rel.encode())
        digest.update(b"\0")
        digest.update(path.read_bytes())
        digest.update(b"\0")
    return digest.hexdigest()

def seal() -> None:
    payload = {"algo": "sha256", "fixture_hash": tree_hash(ROOT), "owner": OWNER}
    SEAL.write_text(json.dumps(payload, indent=2) + "\n")
    print(f"sealed {payload['fixture_hash']}")

def gate() -> None:
    if not SEAL.is_file():
        raise SystemExit("no seal; refuse to score")
    sealed = read_json(SEAL)
    current = tree_hash(ROOT)
    if current != sealed.get("fixture_hash"):
        raise SystemExit("fixture drift after seal; draft cannot refresh the oracle")
    if sealed.get("owner") != OWNER:
        raise SystemExit("seal owner is not the primary runner")
    if UNTRUSTED.is_file():
        smoke = read_json(UNTRUSTED)
        if smoke.get("runner") != OWNER:
            print("ignored untrusted smoke; it cannot set the pass bit")
    if not PRIMARY_SCORE.is_file():
        raise SystemExit("primary has not scored; refuse to promote a draft")
    score = read_json(PRIMARY_SCORE)
    if score.get("runner") != OWNER or score.get("passed") is not True:
        raise SystemExit("primary score missing or failed")
    if score.get("fixture_hash") != current:
        raise SystemExit("primary score hashed a different tree")
    OWNED_PASS.write_text(json.dumps({
        "passed": True,
        "runner": OWNER,
        "fixture_hash": current,
    }, indent=2) + "\n")
    print("owned pass written")

if __name__ == "__main__":
    cmd = sys.argv[1] if len(sys.argv) > 1 else "gate"
    {"seal": seal, "gate": gate}[cmd]()

A scratch directory makes the boundary visible before anyone wires a host. The first gate is supposed to fail closed, and the gate after the fixture edit is supposed to fail closed as well. Those failures are the control, not bugs in the demo.

mkdir -p fixtures
printf 'expected: 2\n' > fixtures/add.out
python3 seal_fixtures.py seal
printf '%s\n' '{"passed":true,"runner":"free-smoke"}' > smoke-result.json
python3 seal_fixtures.py gate || echo "blocked_without_primary_score=$?"
python3 - <<'PY'
import json
from pathlib import Path
seal = json.loads(Path("fixtures.seal.json").read_text())
Path("primary-score.json").write_text(json.dumps({
    "passed": True,
    "runner": "primary-runner",
    "fixture_hash": seal["fixture_hash"],
}) + "\n")
PY
python3 seal_fixtures.py gate
printf 'expected: 3\n' > fixtures/add.out
python3 seal_fixtures.py gate || echo "blocked_after_drift=$?"

The transcript below is illustrative. It is not a log captured from a run, and the hex digest will differ if the fixture bytes differ.

sealed <sha256 of fixtures/>
ignored untrusted smoke; it cannot set the pass bit
primary has not scored; refuse to promote a draft
blocked_without_primary_score=1
ignored untrusted smoke; it cannot set the pass bit
owned pass written
fixture drift after seal; draft cannot refresh the oracle
blocked_after_drift=1

Read the owned pass after the successful gate and the free-smoke identity is absent. The file names the primary runner and repeats the sealed hash, which is the only identity later jobs should accept. Drift the oracle the way an eager rewrite would, and the next gate stops before it can refresh the seal. A human commits the fixture change, a reviewer reads the diff, and only then does someone run seal again on the primary.

The primary-score.json written in that demo is a stand-in so the gate can be exercised. A real job replaces that file with the output of the suite the team already trusts, and the stand-in must never be copied into CI. The free server JSON can sit in the build log as a hint about what broke. Nothing in gate ORs that passed field into the result, and the omission is deliberate, because a hint that can flip a boolean will be used as a boolean the first time the primary is slow.

The scratch host receives a copy of the candidate, not a write credential for the seal, the primary score, or the owned pass. If those paths are mounted into the free server, the split is theater. A forged primary-score.json with the right runner name is just another untrusted green line. The gate cannot detect a lie about identity that the filesystem itself allowed.

Wire the same rule into the job that already publishes artifacts. The shell is illustrative, not a workflow from a specific vendor, and it assumes the proposal lives at seal_fixtures.py beside a real primary score.

set -euo pipefail
test -f fixtures.seal.json
test -f primary-score.json
python3 seal_fixtures.py gate
python3 - <<'PY'
import json
from pathlib import Path
seal = json.loads(Path("fixtures.seal.json").read_text())
owned = json.loads(Path("owned-pass.json").read_text())
assert owned["runner"] == "primary-runner"
assert owned["passed"] is True
assert owned["fixture_hash"] == seal["fixture_hash"]
print(owned["fixture_hash"])
PY

If gate exits non-zero, the job stops. There is no fallback that asks a free model whether the red result was probably fine, because that fallback is the original bug in a softer voice. A sketch can still happen earlier, on a branch, where a wrong suggestion costs a review comment instead of a shipped oracle.

When to walk away

Exit is a set of conditions, not a mood. Take the free path out of the gate when a fixture hash changes without a human commit, when the smoke host holds the only expected output, or when two runs of the same candidate disagree and nobody can name the bytes that were scored. Also take it out when the release window is shorter than the worst stall the team has actually observed on that path. An unmeasured hope is not an SLO, and this note does not invent one.

The same exit applies when the suite touches secrets, live payments, production rows, or prompts that still contain customer text. Those bytes should not move to a host the team does not administer in exchange for a faster comment. The alternative is the owned runner alone, with the assistant kept as an editor. That editor never sees the pass bit and never receives a credential that can rewrite the seal.

This approach is a poor fit for several teams, and a halfway adoption is worse than a skip. A group with no primary runner should not rename a free server into one, because the missing piece is custody rather than a hostname. A group whose fixtures hold customer data, tokens, or unredacted prompts should not upload that tree for a faster sketch. A group that cannot tolerate a manual patch when the free path stalls should keep the assistant off the release path.

This article does not state a quota, a hardware shape, a duration, or a promise that a free option remains. Those details change, and a post is the wrong place to freeze them. Hash equality does not prove domain correctness either. It only proves the oracle did not move under the draft, so the real scorer still belongs on the primary, in the language CI already runs, with failures a human can open.

Used inside those limits, MonkeyCode's free model access is the sketch step: a candidate diff, read by a person, and dropped on a branch the primary will score. The free server option is the scratch smoke, a place to run the candidate where a crash does not delete the seal. For a team that already owns CI, the next step is small. Point the sketch at that free model access, keep the seal file on the primary, and treat every other green line as unread until the owned gate reprints it.

Commit the Offset Before the Draft

Casey Li — Fri, 09 Oct 2026 15:10:23 +0000

A consumer watermark is a durability fact, not a suggestion. Free model access can draft fixtures and review notes. It must not choose, delay, or advance an offset commit. The process that read the record is the only one allowed to stamp progress.

Picture a warehouse ledger and the rubber stamp beside it. A clerk may pencil a note about a strange crate, and that note can even be useful at the next shift change. The stamp that marks the crate as received stays with the person who counted the crate. Helpful prose does not move inventory.

An offset is that stamp. Once it moves forward, the log treats earlier records as done, and a later restart will not hand them back. Duplicates are often recoverable through an idempotent handler. Silent skips are not, because nothing in the next poll announces the hole.

The commit therefore stays on the client even when a team wants a second opinion on the policy. A remote draft can be slow, empty, or confidently wrong. Waiting on that draft before committing leaves a window where a rebalance retires the assignment epoch the code still believes it holds. Applying a suggested higher offset deletes the gap between the true mark and the fiction from the retry set.

Some teams still want a scratch environment for sample batches and for a written critique of the commit policy. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option, and either can hold that scratch work: fixture files, a policy diff, a review comment. Neither option is a commit log, a consumer group, or a fence.

This article does not name models, token quotas, hardware, duration, or permanence. Those details were not verified for this draft, and inventing them would turn a boundary guide into an advertisement with fake specifications. A design that needs those numbers before the consumer can move is already outside the approach described here.

A notebook that shows a draft matching a fixture set is encouraging, and it is still only a comment on examples. That result can justify keeping an offline review step on a scratch workspace. It cannot justify moving the stamp, any more than a passing lint run justifies skipping the commit protocol.

Red flags show up as ordinary code, not as a dramatic outage banner. The first is a parser. Production code that reads a model string and casts the last token to an integer has already handed the watermark away, regardless of how careful the prompt sounded.

Shared membership is the next flag. A free server process that joins the same consumer group, or a scratch disk treated as the source of truth for the committed offset, has promoted an optional seat into a replica.

The third flag is narrower than a general debate about retries. A failed commit call whose backoff is chosen by prompting, instead of by the client library inside the process that holds the assignment, has moved a protocol decision off the client. The fourth flag is a test that treats a model score as proof the offset is safe. A score is not a fence epoch.

Better alternatives are dull, which is the point. Keep a checkpoint next to the consumer, and bind every commit to the epoch issued when the assignment was granted. Advance the mark only after the handler returns success and the epoch still matches. Generate fixtures as plain files, review them as data, and merge policy changes through the same path as any other patch.

The broker client, or a local file that stands in for it during tests, performs the commit. A free server seat, when one already exists, is a reasonable scratch workspace for the fixture directory so it does not clutter a laptop. It is a poor place to park a group coordinator, a member id, or the watermark itself.

The modules below are a proposal. They were not executed while this article was written. An operator should run the commands before treating the pattern as local evidence, and should keep the files out of any process that talks to a real broker until that run is green.

# checkpoint_gate.py — proposal, unexecuted in this draft
from __future__ import annotations

import json
from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True)
class Assignment:
    group: str
    partition: int
    epoch: int


class Checkpoint:
    def __init__(self, path: Path) -> None:
        self.path = path

    def load(self) -> dict:
        if not self.path.exists():
            return {"epoch": None, "offset": -1}
        return json.loads(self.path.read_text(encoding="utf-8"))

    def commit(self, assignment: Assignment, offset: int) -> None:
        current = self.load()
        stored = current["epoch"]
        if stored not in (None, assignment.epoch):
            raise RuntimeError(
                f"fence mismatch: stored={stored} offered={assignment.epoch}"
            )
        if offset < current["offset"]:
            raise RuntimeError("refusing to move the watermark backward")
        payload = {
            "epoch": assignment.epoch,
            "offset": offset,
            "group": assignment.group,
            "partition": assignment.partition,
        }
        tmp = self.path.with_suffix(".tmp")
        tmp.write_text(json.dumps(payload), encoding="utf-8")
        tmp.replace(self.path)


def apply_advisory(advisory: dict, assignment: Assignment, store: Checkpoint) -> None:
    """Review comments never move the watermark, even if they name an offset."""
    del advisory, assignment, store

The anti-pattern is short enough to keep beside the gate as a warning. It is not a function the consumer loop should import, even behind a feature flag.

# do_not_ship.py — illustrated failure, not an API
def commit_from_model_text(text: str, consumer, partition: int) -> None:
    offset = int(text.strip().split()[-1])
    consumer.commit({partition: offset})

That function fails in three independent ways. It trusts prose, it carries no epoch, and it can skip every record the model did not mention. Deleting it is the fix. Wrapping the same parse in a helper with a nicer name is not a fix.

A pair of tests locks the boundary. The advisory names a much higher offset, and the stored mark must stay put. A stale epoch must be rejected even when the offered offset looks like the next honest step.

# test_checkpoint_gate.py — proposal, unexecuted in this draft
from pathlib import Path

from checkpoint_gate import Assignment, Checkpoint, apply_advisory


def test_advisory_cannot_advance(tmp_path: Path) -> None:
    store = Checkpoint(tmp_path / "wm.json")
    live = Assignment("invoices", 3, epoch=7)
    store.commit(live, 10)
    apply_advisory(
        {"suggested_offset": 99, "note": "draft from a free model"},
        live,
        store,
    )
    loaded = store.load()
    assert loaded["offset"] == 10
    assert loaded["epoch"] == 7


def test_stale_epoch_is_refused(tmp_path: Path) -> None:
    store = Checkpoint(tmp_path / "wm.json")
    store.commit(Assignment("invoices", 3, epoch=7), 10)
    try:
        store.commit(Assignment("invoices", 3, epoch=6), 11)
    except RuntimeError as exc:
        assert "fence mismatch" in str(exc)
    else:
        raise AssertionError("stale epoch was allowed to commit")

Fixture generation stays boring on purpose. It writes JSON and returns. It does not open a socket, and it does not import the checkpoint type. If that script grows a commit call, review stops before any discussion of prompt quality.

# write_fixtures.py — proposal, unexecuted in this draft
import json
from pathlib import Path


def write_fixtures(out: Path, count: int = 24) -> None:
    out.mkdir(parents=True, exist_ok=True)
    rows = [
        {"id": i, "amount_cents": 100 + i, "kind": "invoice.posted"}
        for i in range(count)
    ]
    target = out / "batch.json"
    target.write_text(json.dumps(rows, indent=2) + "\n", encoding="utf-8")


if __name__ == "__main__":
    write_fixtures(Path("scratch/batch"))

The local check is a short command sequence from a clean virtual environment. The fragment assumes a POSIX shell, and a Windows host needs the equivalent activation step before the same pytest invocation. No credential is required, because the gate has no vendor client and the fixture writer has no network call.

python -m venv .venv
. .venv/bin/activate
python -m pip install pytest
python -m pytest test_checkpoint_gate.py -q
python write_fixtures.py
python -c "import pathlib; text = pathlib.Path('checkpoint_gate.py').read_text(); assert 'socket' not in text and 'commit_from_model_text' not in text"

The last command is a crude tripwire. It will not catch a dynamic import hidden inside a constructed string, so a human still reads the diff. Its job is to fail fast when a network call or the anti-pattern name is pasted into the file that is supposed to be a stamp.

The table is a field guide, not a scorecard. The commit column never says to ask a model. The exit column is the point at which this whole split should be abandoned rather than patched with a cleverer prompt.

Situation	Where progress is stamped	What a free draft may do	Exit if this appears
Handler succeeded and the epoch matches	Client checkpoint or broker commit	Comment on policy text, offline	Draft text is parsed into an offset
Epoch changed after a rebalance	Nobody, until the new owner commits	Nothing on the hot path	Scratch host still stores the old member id
Fixture batch for review	Nowhere	Write JSON in a scratch workspace	Fixture script imports the consumer
Commit call failed	Client-library backoff in the assigned process	An incident note after the fact	A prompt is asked whether to retry the commit
A quota or uptime figure is required to proceed	Not this design	Not a substitute for that figure	The consumer blocks on the free option

Exit criteria are operational. Drop model involvement on this path when any one of them is true.

The consumer cannot make progress unless the free option is reachable. An auditor requires every commit input to be replayed without a third party.

Someone wants to hide a draft hop inside the handler because the latency budget looks tight on a diagram. A reviewer cannot explain the fence without opening a prompt. The scratch workspace starts holding group membership, offsets, or credentials.

The replacement in each of those cases is the same shape. Use a broker-native commit, keep a tested local fence in the assigned process, and limit model output to documents that never ship. Removing the model from the path entirely is a valid outcome of the field guide, not a failure of it.

Several teams should not adopt the split at all. A pipeline whose only runtime is a free server seat should not pretend that seat is a consumer group. Payment, clinical, and legal logs, where a skipped offset is an integrity incident, should not collect policy advice on the same path that stamps progress. Operators who need a published quota, a named model, or an uptime commitment before accepting a dependency will not find those facts in this article, and should not infer them.

Anyone who would auto-apply a generated patch onto Checkpoint.commit is already past the first red flag. The useful response is to stop the merge, not to add a second model that checks the first.

Limitations sit next to the proposal so they are harder to skip. The samples remain unexecuted until the commands above are run on a machine the operator controls. They imitate the shape of an offset commit. They are not a Kafka client, and they do not speak a broker protocol.

Filesystem replace is not a replicated log. A crash between the temp write and the replace can leave a stray file, which a real commit protocol handles with more care than this stand-in. The gate does not encrypt the checkpoint, authenticate the caller, or address poison records, idempotent handlers, or dead-letter routing.

Those neighboring problems stay neighboring on purpose. Moving any of them onto free inference is a different design, and this article does not bless that move. No latency, cost, or accuracy figure here should be quoted elsewhere, because none was measured.

The habit that survives contact with a rebalance is small. Stamp progress in the process that holds the assignment. Let a draft comment from outside the fence. When the draft and the stamp trade places, put the watermark back on the client and leave it there.