DEV Community: Taylor Zhu

The Runbook Replay Gate: A Fail-Closed Handoff Checklist You Can Run in 45 Minutes

Taylor Zhu — Tue, 27 Oct 2026 13:17:11 +0000

A service is not production-ready because its tests pass. It is production-ready when someone who has never opened the repo can restore it on an empty machine using only what is committed.

That is the gate. The rest of this article makes that single sentence executable: a pre-flight script, a 45-minute blind drill, and a decision table with fail-closed criteria you can copy into your own pipeline.

The failure this gate catches

Most readiness reviews check the happy path. They confirm the deploy works, the tests are green, the health endpoint returns 200. None of that survives contact with the one scenario that actually costs you a night:

The person who built the service is unreachable, and the only description of how to restore it lives in their head.
The recovery steps live in a chat thread, a DM, or an assistant session that nobody exported.
The rollback command has never been executed, so its first run happens during an incident.

A replay gate converts all three into a binary result you can argue about in a pull request instead of at 3 a.m.

The seven gates

Every row has evidence attached. No evidence, no pass — that is what "fail-closed" means here.

#	Gate	Evidence required	Pass looks like	If it fails
1	Environment contract	`.env.example` listing every variable the app reads	Fresh clone starts with only the example file filled in	Block promotion; missing vars are silent time bombs
2	Deterministic runbook	Numbered commands with pasted output, in `docs/runbook.md`	Every step is a command a shell can run	Rewrite the step until it is a command
3	Restore path	Seed or fixture script that works against an empty store	Replay creates working data from zero	Block; a schema with no seed is not portable
4	Rollback	One command, executed and timestamped	Last execution is inside your freshness window	Block; an untested rollback is a hope
5	External dependencies	Named fallback and timeout for each endpoint	Failure mode documented per dependency	Block; undocumented failure is an outage
6	Ownership	Named human plus a backup, current	Two people can be paged today	Block; "the team" is not an owner
7	Drill evidence	Dated replay log with the questions the runner had to ask	Zero blocking questions	Expired or absent log = gate closed

Gate 2 is the one teams argue about most, so state the rule plainly: if a step requires a human to interpret intent, it is a note, not a step. Notes are allowed. They just do not count toward a pass.

Gate 4 deserves a second rule: the timestamp must come from a command that failed loudly at least once. A rollback nobody has ever broken is indistinguishable from a rollback that does nothing.

Artifact 1: the replay pre-flight script

This is a proposal, not a measured result — run it against your repo and expect the first run to fail. That is the point. Save it as scripts/replay_check.sh and call it from CI on any change under docs/, deploy/, or your config directory.

#!/usr/bin/env bash
# replay_check.sh — fail-closed pre-flight for a handoff replay drill
set -uo pipefail

FAIL=0
pass() { printf 'PASS  %s\n' "$1"; }
fail() { printf 'FAIL  %s\n' "$1"; FAIL=1; }

need_file() {
  if [ -s "$1" ]; then pass "file: $1"; else fail "file: $1 (missing or empty)"; fi
}

need_file .env.example
need_file docs/runbook.md
need_file docs/rollback.md
need_file docs/owners.md

# 1. No hardcoded model or API endpoints in source; they belong in config.
if grep -RIn --exclude-dir=.git --exclude-dir=node_modules \
     -E 'https://[^ "'\'']*(api|model|inference)' \
     --include='*.py' --include='*.ts' --include='*.go' . >/dev/null 2>&1; then
  fail "hardcoded endpoint in source — move it to config"
else
  pass "no hardcoded endpoints in source"
fi

# 2. The runbook must not outsource steps to memory or a chat window.
if grep -qinE 'ask the (author|builder)|ping |see (slack|thread|dm)' docs/runbook.md; then
  fail "runbook contains non-reproducible instructions"
else
  pass "runbook steps are self-contained"
fi

# 3. Rollback must carry a date and a paste-able result.
if grep -qE '^[0-9]{4}-[0-9]{2}-[0-9]{2}' docs/rollback.md; then
  pass "rollback log is dated"
else
  fail "rollback log has no dated execution"
fi

exit "$FAIL"

Two properties matter more than the checks themselves. It exits non-zero, so it can block a merge. And it fails on absence of evidence, not on presence of bugs — which is the difference between a checklist and a test suite.

Artifact 2: the 45-minute blind replay

The script checks that the paperwork exists. Only a human can check that the paperwork works. Run this drill with three roles and a hard clock.

Pick a runner who has never deployed this service. Not a rotation swap — someone genuinely unfamiliar.
Give them three things: the repo URL, an empty server, and the requirement to reach a working instance.
Silence the builder. Every question the runner asks is a defect in the docs, not in the runner. Log the first question verbatim.
Record the clock. When did they reach a running instance? When did they first need help?
Paste the log into docs/replay/YYYY-MM-DD.md, including the questions and the commands that failed.
Fix the repo, not the runner. Each question becomes a line in the runbook before the next drill.

Write the log before you discuss the drill. Discussions converge on goodwill; logs do not.

What counts as a pass

Pass: the runner reached a working instance without a single blocking question, and every command in the path is committed.
Conditional pass: they needed help, but the missing step was added to the repo during the drill and re-run successfully.
Fail: help was needed and the fix lives anywhere other than the repo.
Not a pass: the builder narrating over a screen share. That is a demo, and demos are how runbooks rot.

AI-assisted runbooks are the new failure mode

Assistants are good at drafting restore steps from repo evidence: read the config, read the migrations, propose an order. They are also good at producing steps that only work inside the session that generated them.

The rule that keeps this honest is boring. Every generated command gets executed once, and its real output is pasted under the command. A step reading "regenerate the config with the assistant" is not a step, because the next person has no assistant state, no context, and no reason to trust it.

If a step depends on a model call at runtime, gate 5 applies: name the fallback and the timeout in the runbook, next to the command.

Where a disposable box and free model access fit

The drill needs a machine you are willing to delete afterwards — a box that is not the staging server, not production, and not something you will be tempted to keep. That is exactly the shape of a throwaway environment, and it is the least glamorous part of the whole process.

MonkeyCode's free model access and free server option are useful here in two narrow ways: the server gives you somewhere to run the blind replay without touching shared infrastructure, and the free model access can draft the first version of docs/runbook.md from your repo, which you then execute line by line before committing. Neither replaces the drill. The drill is a person, a clock, and a log.

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

Treat every availability and allowance claim — from any vendor, including this one — as a snapshot with a date on it. Check the current terms yourself before you build a dependency on them, and put that check on gate 7's freshness schedule.

Limitations, and who should skip this

The script verifies presence, not correctness. A runbook full of wrong commands passes the pre-flight and fails the drill — which is why you need both.
A blind replay costs one engineer half a day. If you ship several services a week, batch them into a single monthly slot instead of gating every merge.
This gate is wrong for a service that cannot be rebuilt from the repo at all, such as a stateful box with hand-tuned data. Those need a snapshot and restore test, not a runbook review.
Skip it if your team is one person and the service has no users yet. Write the runbook anyway; just do not pretend the drill happened.

The takeaway

Write down the gate, run the script, book the 45 minutes, and keep the log. If the free server option saves you from rehearsing on staging, use it for that and nothing more.

Then ask the only question that matters: who is the next person to restore this, and can they do it without you?

If the answer needs a conversation, the gate is closed.

Your Timeout Is a Guess: A Latency Probe and Go/No-Go Table for Free-Tier Model Endpoints

Taylor Zhu — Mon, 26 Oct 2026 11:48:03 +0000

Your client timeout is a promise about someone else's server. Most teams never check whether that promise is true — they copy timeout=30, retries=2 from a tutorial, ship it, and discover the real distribution during an incident.

This post is a way to stop guessing. You will measure a free-tier model endpoint yourself, turn the samples into a decision table, and block promotion when the evidence is too thin to support a number. The artifact is a dependency-free probe script plus a checklist you can paste into a pull request.

The number nobody measures

Latency percentiles on a shared endpoint are not a property of the model. They are a property of the model, the queue in front of it, your region, and the hour of the day.

That means an average latency figure from a vendor blog post tells you almost nothing about your own traffic path. You need your own samples, taken from the place your code actually runs, with the prompt sizes you actually send.

And you need the failure side, not just the success side. A probe that only records successful calls will happily report a p95 of 900 ms while 12% of requests were timing out — because the timeouts never made it into the sample set.

What to measure

Four buckets, kept separate. Mixing them produces a number that describes nothing.

Cold requests. First call after idle. Often 5-20x slower than warm calls, and it is the one your first user of the day experiences.
Warm requests. Steady state, sequential, one in flight.
Concurrent requests. Two or four in flight. Free tiers frequently serialize or throttle here, so this bucket reveals the throughput ceiling you actually have.
Errors by class. 429, 5xx, read timeouts, connection resets, and truncated bodies are five different bugs and deserve five different counters.

For streaming endpoints, also record time to first token separately from total time. A 6-second total with a 400 ms first token feels fast; the reverse feels broken.

The probe

Standard library only, so you can run it on a minimal box. It is a template — I have not run it against your endpoint, and the paths assume an OpenAI-compatible /chat/completions shape. Adjust and verify before you trust any of it.

# probe.py — sequential latency sampler, stdlib only
import json, os, time, urllib.request, urllib.error

BASE  = os.environ["AI_BASE_URL"].rstrip("/")   # e.g. https://host/v1
KEY   = os.environ["AI_API_KEY"]
MODEL = os.environ["AI_MODEL"]

def one_call(prompt, timeout_s=90.0):
    body = json.dumps({
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
        "max_tokens": 64,
    }).encode()
    req = urllib.request.Request(
        f"{BASE}/chat/completions", data=body, method="POST",
        headers={"Authorization": f"Bearer {KEY}",
                 "Content-Type": "application/json"},
    )
    t0 = time.perf_counter()
    try:
        with urllib.request.urlopen(req, timeout=timeout_s) as r:
            raw = r.read()
        json.loads(raw)                      # reject truncated payloads
        return {"ok": True, "status": 200, "elapsed": time.perf_counter() - t0}
    except urllib.error.HTTPError as e:
        return {"ok": False, "status": e.code, "elapsed": time.perf_counter() - t0}
    except Exception as e:
        return {"ok": False, "status": type(e).__name__, "elapsed": time.perf_counter() - t0}

def run(n=60, gap_s=1.0, out="probe.jsonl"):
    with open(out, "w") as f:
        for i in range(n):
            rec = one_call("Reply with the single word: ok")
            rec["i"] = i
            f.write(json.dumps(rec) + "\n")
            time.sleep(gap_s)
    return out

if __name__ == "__main__":
    print(run(int(os.environ.get("PROBE_N", "60"))))

Run it once cold (immediately after an idle period) and once warm. Keep both files; they answer different questions.

Then reduce the samples with nearest-rank percentiles, and — this part matters — compute them over all records, counting errors at their measured elapsed time rather than dropping them.

# summarize.py
def pct(values, p):
    if not values:
        return None
    s = sorted(values)
    k = max(0, min(len(s) - 1, int(round(p / 100 * len(s) + 0.5)) - 1))
    return s[k]

import json
recs = [json.loads(l) for l in open("probe.jsonl")]
n     = len(recs)
errors = [r for r in recs if not r["ok"]]
times  = [r["elapsed"] for r in recs]
print({
    "n": n,
    "error_rate": round(len(errors) / n, 3) if n else None,
    "p50": pct(times, 50), "p95": pct(times, 95), "max": max(times or [0]),
})

Turning samples into a decision

Now the part teams skip: the numbers have to change the config, or the measurement was theater.

Use p95 as the timeout floor, not the mean. A timeout equal to the mean guarantees you cut off roughly half your slow-but-fine requests — the worst possible choice, because the request succeeds on the server and you pay for it anyway.

Signal from the probe	Timeout	Retries	Concurrency	Verdict
n < 30 successful samples	unchanged	0	1	Block — evidence too thin
error rate > 5% at sequential load	2 × p95	1, jittered	1	Block — fix errors first
p95 warm < 3s, cold < 10s	2 × p95 warm	1	2	Ship with a slow-path message
cold p95 > 4 × warm p95	2 × cold p95	1	1	Ship, but warm on deploy
p95 at concurrency 4 > 3 × p95 at 1	2 × p95 @1	1	1	Ship single-flight; queue the rest
any truncated body observed	2 × p95	1	1	Block — parse layer is unsafe

Read the table as a starting point, not a law. Your acceptable numbers depend on whether a slow answer is merely annoying or costs money.

The checklist you can paste into a PR

Each line needs an artifact, not an opinion. A checkbox without a file attached is a wish.

Evidence exists. probe.jsonl plus probe.summary.json committed, dated, with the endpoint hostname and the region you ran from. No file, no merge.
Sample floor met. At least 30 sequential samples per bucket you claim to cover. Below that, the summary says INSUFFICIENT and the checklist fails closed.
Cold and warm are separated. One file, one bucket; never averaged together.
Errors are counted, not filtered. The summary reports error_rate; a zero-error run with 12 samples is treated as unmeasured.
Timeout derives from evidence. A comment next to the config constant explains which percentile produced it and links the summary file.
Retries are bounded and jittered. A retry you cannot count is an outage you cannot explain later.
The evidence has a date. Anything older than 30 days is stale for a free tier; re-run before promoting.
Degradation path is named. If p95 doubles tomorrow, the checklist points at the file that defines the fallback.

One extra rule I would add for any shared workload: measure with the largest prompt your feature actually sends. A 64-token probe understates the latency of a 4,000-token one by a lot.

Where this fits in a free-tier workflow

Free access is exactly where this discipline pays off, because the variance is highest and the consequences of guessing are cheapest to avoid.

MonkeyCode — with free model access and a free server option, per the operator — is convenient for this specific job: the free model access means you can take repeated sample runs without treating each one as a budget decision, and running the probe on the free server gives you a sample set from a stable network location rather than your laptop on hotel Wi-Fi.

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

That said, the method is portable. Any endpoint, any key, the probe script above.

Limitations, stated plainly

Your probe defines your workload, not everyone's. Different prompt lengths, systems messages, and max_tokens will shift the distribution.
Small samples lie quietly. At n = 15, a p95 is barely a p95. Treat anything under 30 as directional and under 100 as approximate.
A time window is not a contract. Free tiers can change behavior without notice; a green checklist from last month proves last month.
Region skew is real. A probe from a different zone than production measures the wrong thing.
Non-streaming probes miss the felt latency. If your feature streams, measure time to first token too.

Who should skip this

If you have a paid endpoint with a contractual latency SLA and a dashboard that already reports p95 by route, this post is redundant — use the dashboard.

Likewise, if your feature is a background job with no human waiting, timeout tuning matters far less than idempotency and duplicate delivery. Measure the thing your users feel.

For the rest of us running a prototype on someone else's free allowance: sample once, write the number down, and let the number — not the tutorial — set your timeout. If you want a starting environment to run the probe in, the free server option is a reasonable place to point it at.

The Free Server Is the Fragile Part: A Runtime Readiness Checklist for Hosted AI Prototypes

Taylor Zhu — Tue, 20 Oct 2026 09:55:44 +0000

Your free-tier prototype does not fail at the model call. It fails at 3 a.m., when the instance has been recycled, the write you thought was durable is gone, and nobody wrote down what "working" was supposed to mean.

So write it down. Below is a runtime-readiness checklist you can copy into a repo: explicit claims, one evidence artifact per claim, and a fail-closed rule for every row. Missing evidence is never a pass.

This is the server-side companion to model-allowance checks. The model budget is easy to reason about. The runtime contract is where assumptions quietly rot.

Four assumptions that break first on a free server

Free hosting is not a smaller version of paid hosting. It is a different failure contract. Watch these four in particular:

Durability. Local disk may be ephemeral. Anything you did not write to an external store can vanish on the next cold start.
Warmth. Instances sleep or get recycled. Your p50 latency is meaningless if the first request after idle takes seconds.
Address stability. Hostnames, ports, and headers can change between deploys or between regions.
Egress. Outbound calls to a model endpoint may be rate-limited or blocked from that network path, independently of your own quota.

None of these are bugs. They are the terms. Your job is to record which ones your app actually depends on.

The checklist: claim, evidence, fail-closed rule

Every row has three parts. A claim without evidence is BLOCKED, not PASS. That single rule removes most of the self-deception in readiness reviews.

#	Claim	Evidence artifact	Fail-closed rule
R1	First request after idle completes	`cold-start.json` with timestamp + ms	No sample in last 7 days → BLOCKED
R2	App survives instance recycle without data loss	`state-roundtrip.json` before/after restart	Read-back mismatch → BLOCKED
R3	Write path is idempotent	`dup-write.json` with two identical calls	Duplicate row or 5xx → BLOCKED
R4	Max accepted payload is known	`payload-limit.json` with the failing size	Limit unknown → BLOCKED
R5	Outbound model call works from this network	`egress.json` status + latency	Any non-2xx in last run → BLOCKED
R6	Response headers leak nothing internal	`headers.txt`	Internal host/IP/version present → BLOCKED
R7	Rollback target still deploys	`rollback.log`	Untested in last 30 days → BLOCKED

Notice R7. A free server makes rollback more important, not less, because you cannot assume the previous instance is still warm or still addressable.

The probe: one script, seven artifacts

Here is a stdlib-only Python probe. It writes one JSON file per gate so each row of the table has a named artifact. Copy it, set two env vars, run it. Nothing here is MonkeyCode-specific; it talks to whatever URL you point it at.

# probe_runtime.py -- stdlib only
import json, os, sys, time, urllib.request, urllib.error

BASE = os.environ["TARGET"].rstrip("/")
TOKEN = os.environ.get("PROBE_TOKEN", "")
OUT = os.environ.get("EVIDENCE_DIR", "evidence")
os.makedirs(OUT, exist_ok=True)

def call(path, method="GET", body=None, timeout=60):
    data = json.dumps(body).encode() if body is not None else None
    r = urllib.request.Request(BASE + path, data=data, method=method)
    r.add_header("content-type", "application/json")
    if TOKEN:
        r.add_header("authorization", "Bearer " + TOKEN)
    t0 = time.perf_counter()
    try:
        with urllib.request.urlopen(r, timeout=timeout) as resp:
            return resp.status, resp.read(), dict(resp.headers), (time.perf_counter()-t0)*1000
    except urllib.error.HTTPError as e:
        return e.code, e.read(), dict(e.headers), (time.perf_counter()-t0)*1000
    except Exception as e:
        return 0, str(e).encode(), {}, (time.perf_counter()-t0)*1000

def save(name, obj):
    obj["recorded_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
    with open(os.path.join(OUT, name), "w") as f:
        json.dump(obj, f, indent=2)
    print(name, obj.get("result", obj.get("status")))

# R1: cold start (run this as the first request after an idle window)
code, _, _, ms = call("/health")
save("cold-start.json", {"status": code, "ms": round(ms, 1)})

# R3: duplicate write, same key twice
key = "probe-" + str(int(time.time()))
for i in (1, 2):
    code, _, _, _ = call("/state", "POST", {"id": key, "value": "v%d" % i})
code_r, body, _, _ = call("/state/" + key)
save("dup-write.json", {"status": code_r, "body": body[:200].decode("utf-8", "replace")})

# R4: document the payload ceiling instead of guessing it
for size in (1024, 65536, 1048576, 4194304):
    code, _, _, _ = call("/state", "POST", {"id": key + "-sz", "blob": "x" * size})
    if code >= 400 or code == 0:
        save("payload-limit.json", {"first_failing_bytes": size, "status": code})
        break
else:
    save("payload-limit.json", {"first_failing_bytes": None, "status": "no-limit-hit"})

# R5: outbound egress to the model endpoint
code, body, _, ms = call("/generate", "POST", {"prompt": "reply with the word ok"})
save("egress.json", {"status": code, "ms": round(ms, 1), "body": body[:200].decode("utf-8", "replace")})

# R6: header hygiene
_, _, headers, _ = call("/health")
with open(os.path.join(OUT, "headers.txt"), "w") as f:
    f.write("\n".join("%s: %s" % kv for kv in sorted(headers.items())))
print("headers.txt")

R2 needs a restart, so it is a two-step manual gate on purpose. Write a value, recycle the instance from the dashboard, then read it back and store the before/after pair. Automating that would hide the exact moment you are trying to observe.

Turning artifacts into a verdict

Do not let a human eyeball this. Twenty lines of code make the fail-closed rule mechanical:

# verdict.py -- PASS only with fresh, complete evidence
import json, os, time
REQUIRED = ["cold-start.json", "state-roundtrip.json", "dup-write.json",
            "payload-limit.json", "egress.json", "headers.txt", "rollback.log"]
TTL_DAYS = {"cold-start.json": 7, "rollback.log": 30}

blocked = []
for name in REQUIRED:
    path = os.path.join("evidence", name)
    if not os.path.exists(path):
        blocked.append((name, "missing"))
        continue
    ttl = TTL_DAYS.get(name)
    age_days = (time.time() - os.path.getmtime(path)) / 86400
    if ttl and age_days > ttl:
        blocked.append((name, "stale: %.1f days" % age_days))

for name, why in blocked:
    print("BLOCKED", name, "-", why)
print("VERDICT:", "PASS" if not blocked else "BLOCKED")
raise SystemExit(0 if not blocked else 1)

The exit code matters more than the printout. Wire it into CI as a required check so a deploy cannot skip the gate by forgetting to run it.

Where the two free options fit

A hosted prototype on free model access plus a free server is a genuinely cheap way to run this drill, because both halves of the contract are in play at once: the model path (R5) and the runtime path (R1, R2, R4).

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

Because I cannot verify your deployment from here, treat the free-tier specifics — current token allowance, instance sleep behavior, disk durability, and any hardware details — as things you must read off the project's own current documentation and confirm with the probe. Limits on free offerings change; a number quoted in a blog post is not evidence. That is precisely why R1 and R2 exist as gates rather than footnotes.

A concrete sequence that works:

Deploy a three-endpoint demo (/health, /state, /generate) to the free server option.
Run probe_runtime.py immediately after deploy, then again after an idle window you did not control.
Recycle the instance from the dashboard and complete the R2 read-back by hand.
Point /generate at the free model access endpoint and log the status you actually got.
Run verdict.py. If it exits non-zero, you have a checklist result, not a launch.

Step 2 is the one people skip. A probe run right after a warm deploy measures almost nothing.

What this checklist will not tell you

Be honest about the boundaries:

It does not measure throughput. Seven gates say nothing about concurrency limits under real traffic.
It does not prove durability. One read-back shows the state survived one recycle. It is evidence, not a guarantee.
It ages. Hence the TTLs. A green verdict from three weeks ago is a historical document.
It is not a security review. R6 only checks header hygiene, not auth, isolation, or secrets handling.

Who should not use this approach: teams with a hard sub-second p95 SLA, regulated data-residency requirements, or write paths that must be strictly durable. For those, run the checklist anyway — but expect it to correctly block you, and budget for infrastructure that matches the contract.

Start with the boring gate

If you take one thing away: the row you are most tempted to mark "obviously fine" is the row that will page you. Write the claim, name the artifact, define the fail-closed rule, and let an exit code say no for you. Then the next person who inherits the prototype can read seven files instead of guessing what you knew.

Rehearse the Failure Before You Promote: A Degradation Gate for Free-Tier AI Apps

Taylor Zhu — Mon, 19 Oct 2026 08:37:09 +0000

Your release will not fail because a feature is missing. It fails because nobody rehearsed the path where the upstream stops answering. So build the failure, assert on it, and block the merge when the evidence is absent.

Below is a checklist you can copy into a repo today: three failure modes, one fault-injection harness with no dependencies, and a gate that refuses to pass unless evidence is tied to the current commit.

The demo path is the easy path

A demo proves the happy path once, on your machine, with a warm endpoint. That is the cheapest thing you will ever test. It tells you nothing about the hour when a request comes back throttled and your app decides to invent an answer.

Free tiers make this worse in a useful way: the failure is not hypothetical, it is scheduled. Your job is to decide the response before it happens.

Three failure modes you own

Every app sitting on a hosted model endpoint and a small server has the same three failure shapes. The names differ per provider; the shapes do not.

Throttle. The request is refused because you are over a rate limit. It usually clears in seconds. Retrying is reasonable; retrying blindly is not.
Exhausted. The allowance for the period is gone. Retrying is pointless until the window resets, and your app must say so plainly.
Unavailable. The endpoint or the server behind it is down or cold. Duration is unknown, so the only honest answer is a refusal with an error code.

Any of these can become a silent wrong answer if your error handling returns an empty string that a template happily renders.

The degradation matrix your team can copy

Fill this in for your own product before writing code. One row per mode, one row per user-facing surface.

Mode	User must see	Evidence you keep	Fail-closed condition
Throttle	Retry notice, no partial content	Recorded status + retry count	Any generated content is returned
Exhausted	Explicit "allowance used up" state	Status code + timestamp	The app retries in a loop
Unavailable	Error with a stable code	Status code + build SHA	A cached answer appears unlabeled
Cached fallback	Answer marked `source: cache` + age	Sample payload	Age is missing or the label is lost

The last column is the whole point. A gate that only checks "did the response look fine" passes everything.

Fault injection you can run in thirty seconds

The harness below stubs the upstream so it needs no credentials. Route every model call in your app through one function, then swap that function's fault switch during the drill.

#!/usr/bin/env python3
"""fault_gate.py - inject upstream faults, assert the app fails closed.

    python fault_gate.py                  # run the drill, print results
    python fault_gate.py evidence/degradation   # also write evidence files
"""
import json
import os
import pathlib
import subprocess
import sys
from dataclasses import dataclass


class UpstreamError(Exception):
    def __init__(self, status: int):
        super().__init__(f"upstream {status}")
        self.status = status


@dataclass
class Gateway:
    """The single choke point for every model call in your app."""

    def ask(self, prompt: str) -> dict:
        fault = os.environ.get("FAULT", "none")
        codes = {"throttle": 429, "exhausted": 402, "unavailable": 503}
        if fault in codes:
            raise UpstreamError(codes[fault])
        return {"text": f"echo:{prompt}"}


def answer(prompt: str, gw: Gateway) -> dict:
    """The only function your UI is allowed to call."""
    try:
        out = gw.ask(prompt)
    except UpstreamError as exc:
        return {"ok": False, "text": None, "code": f"upstream_{exc.status}"}
    return {"ok": True, "text": out["text"], "code": "ok"}


EXPECTED = {
    "none": {"ok": True, "text": "echo:ping", "code": "ok"},
    "throttle": {"ok": False, "text": None, "code": "upstream_429"},
    "exhausted": {"ok": False, "text": None, "code": "upstream_402"},
    "unavailable": {"ok": False, "text": None, "code": "upstream_503"},
}


def main(argv: list) -> int:
    emit = pathlib.Path(argv[1]) if len(argv) > 1 else None
    if emit:
        emit.mkdir(parents=True, exist_ok=True)
    head = subprocess.check_output(
        ["git", "rev-parse", "HEAD"], text=True
    ).strip()

    for mode, want in EXPECTED.items():
        os.environ["FAULT"] = mode
        got = answer("ping", Gateway())
        if got != want:
            print(f"FAIL {mode}: want {want} got {got}", file=sys.stderr)
            return 1
        print(f"PASS {mode:12s} -> {got['code']}")
        if emit and mode != "none":
            record = {
                "mode": mode,
                "commit": head,
                **got,
                "repro": f"FAULT={mode} python fault_gate.py",
            }
            (emit / f"{mode}.json").write_text(json.dumps(record, indent=2))
    return 0


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

Two properties matter here. The expected result for a fault is text: None, and the drill compares whole dictionaries, so a stray fallback string breaks the test loudly instead of quietly shipping.

The gate: evidence tied to a commit

Evidence that is not pinned to a build is a rumor. This checker refuses to pass unless each failure mode has a record from HEAD, reports ok: false, returned no content, and includes a reproduce command.

#!/usr/bin/env python3
"""promote_gate.py - exit 1 unless degradation evidence matches HEAD."""
import json
import pathlib
import subprocess
import sys

HEAD = subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip()
MODES = ["throttle", "exhausted", "unavailable"]
EVIDENCE = pathlib.Path("evidence/degradation")


def check(rec: dict) -> list:
    problems = []
    if rec.get("commit") != HEAD:
        problems.append("evidence is not from this commit")
    if rec.get("ok") is not False:
        problems.append("failure path did not report ok=false")
    if rec.get("text") not in (None, ""):
        problems.append("failure path returned content")
    if not rec.get("repro"):
        problems.append("no reproduce command recorded")
    return problems


def main() -> int:
    blocked = []
    for mode in MODES:
        path = EVIDENCE / f"{mode}.json"
        if not path.exists():
            blocked.append(f"{mode}: missing {path}")
            continue
        try:
            rec = json.loads(path.read_text())
        except json.JSONDecodeError as exc:
            blocked.append(f"{mode}: not JSON ({exc})")
            continue
        blocked += [f"{mode}: {p}" for p in check(rec)]

    if blocked:
        print("BLOCKED", *blocked, sep="\n  ")
        return 1
    print(f"PASS: {len(MODES)} failure modes evidenced at {HEAD[:8]}")
    return 0


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

Wire it into CI as two lines. The drill regenerates evidence; the gate decides whether the branch is promotable.

python fault_gate.py evidence/degradation && python promote_gate.py

A thirty-minute runbook

Find the choke point. If more than one file imports the model client directly, fix that first; a drill cannot cover paths it cannot reach.
Write the matrix. One row per failure mode, and name the exact user-visible string or error code you expect.
Implement refusals. Return a code, not a blank string. Never let a template render None as content.
Label fallbacks. A cache hit must carry source: cache and its age, or the gate should treat it as fabricated content.
Run the drill, emit evidence, run the gate. Commit both scripts with the app so the check survives the next refactor.
Re-run before every release. Faults you have not re-tested since the last refactor are assumptions again.

Where a free allowance actually fits

The drill above is deliberately offline, but you still need a live endpoint to confirm that real status codes map to your handlers. That is where a no-cost allowance is useful: you can rehearse throttling and exhausted states against a live endpoint without watching a bill.

MonkeyCode offers free model access and a free server option, which makes it a practical place to run this harness next to a small deployment instead of on your laptop. It is not a substitute for the drill; free capacity is exactly the kind of resource that gets throttled, so treat it as the environment you test in, not a guarantee you build on.

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

One caution on numbers: allowances and server limits change, and any figure quoted in a blog post goes stale. Check the project's current terms yourself before you plan a release around them — including whatever you read here.

Who should not ship this way

Skip free-tier hosting for this workflow if your product carries a contractual uptime or latency commitment, if a delayed answer is a safety issue rather than an inconvenience, or if you cannot verify where the data is processed. Skipping the drill, however, is not an option anywhere.

What to do on Monday

Write the matrix before lunch. It takes twenty minutes and it will surface at least one place where your app guesses instead of refusing. Then keep the gate in the repo, where it keeps working after you have forgotten this article.

If you want to run the harness against something live first, the free tier is a reasonable sandbox to start in — just bring the gate with you.

The Burn-Rate Gate: A Fail-Closed Checklist for Shipping on a Free AI Allowance

Taylor Zhu — Sun, 18 Oct 2026 07:17:58 +0000

Your free allowance does not run out by accident. It runs out on a schedule nobody computed.

Three numbers decide whether a free-tier AI build survives its launch day: what you were granted, what the provider says you consumed, and what you reserved for rollback. Most teams watch the first, guess at the second, and never write down the third. Then a demo stalls two-thirds of the way through and everyone blames the model.

This is a production-readiness checklist plus a small runnable gate for that arithmetic. It assumes the model access and the server are free — which makes the failure cheap to repair and just as easy to ignore.

The failure mode is arithmetic, not availability

Free tiers rarely fall over. They reach zero.

Granted: a number someone published, revocable without notice.
Observed: what the provider's own console reports you used.
Reserved: headroom you refuse to spend so a rollback drill still has budget.

A zero bill is evidence about price. It is not evidence about headroom. So the gate below never reads the bill; it reads dated observations and does division.

Step 1: keep a ledger you can diff

Append-only JSONL, one line per measurement. No database, no dashboard, no service to keep alive.

{"ts":"2026-10-17T09:00:00Z","kind":"observed","source":"provider_console","tokens":184000}
{"ts":"2026-10-18T09:00:00Z","kind":"observed","source":"provider_console","tokens":241500}
{"ts":"2026-10-18T09:05:00Z","kind":"estimate","source":"local_counter","tokens":262000}

Two rules make the file useful:

Every row carries a timestamp and a source.
estimate rows are recorded but never treated as evidence — local counters drift, and drift is exactly what you are measuring.

Commit the file. When someone asks "how much is left?", the answer is a diff, not a feeling.

Step 2: gate on the projection, not the balance

The script is short on purpose. It exits non-zero unless every gate passes.

# allowance_gate.py — fail closed when the free allowance cannot be defended
from __future__ import annotations

import json, sys
from dataclasses import dataclass
from datetime import datetime, timedelta

EVIDENCE_TTL = timedelta(hours=48)

@dataclass(frozen=True)
class Entry:
    ts: datetime
    kind: str      # "observed" | "estimate"
    source: str
    tokens: int

def load(path: str) -> list[Entry]:
    rows: list[Entry] = []
    with open(path, encoding="utf-8") as fh:
        for line in fh:
            line = line.strip()
            if not line:
                continue
            raw = json.loads(line)
            rows.append(Entry(
                ts=datetime.fromisoformat(raw["ts"].replace("Z", "+00:00")),
                kind=raw["kind"],
                source=raw["source"],
                tokens=int(raw["tokens"]),
            ))
    return sorted(rows, key=lambda e: e.ts)

def gates(rows, *, now, granted, reserve, window_days=7, launch_hours=72):
    fails: list[str] = []
    observed = [e for e in rows if e.kind == "observed"]

    # G0: the granted number must be on record at all
    if granted <= 0:
        fails.append("G0: no granted amount on record")

    # G1: at least one row is provider-observed, not self-counted
    if not observed:
        return fails + ["G1: only local estimates on record"]

    # G2: the newest observation is inside the evidence TTL
    newest = observed[-1].ts
    if now - newest > EVIDENCE_TTL:
        fails.append(f"G2: newest observation is {(now - newest).days}d old")

    # G3: a burn rate needs two points spread over the window
    cutoff = now - timedelta(days=window_days)
    recent = [e for e in observed if e.ts >= cutoff]
    if len(recent) < 2:
        return fails + ["G3: fewer than two observations in the burn window"]

    used = sum(e.tokens for e in observed)
    span = (recent[-1].ts - recent[0].ts).total_seconds() / 86400

    # G4: projected exhaustion must clear the launch window
    remaining = granted - used - reserve
    if remaining <= 0 or span <= 0:
        return fails + ["G4: no headroom left after reserve"]

    rate = sum(e.tokens for e in recent) / span          # tokens per day
    hours_left = (remaining / rate) * 24
    if hours_left < launch_hours:
        fails.append(f"G4: {hours_left:.1f}h of headroom < {launch_hours}h window")

    return fails

if __name__ == "__main__":
    import argparse
    p = argparse.ArgumentParser()
    p.add_argument("ledger")
    p.add_argument("--now", required=True)      # pin the clock; do not trust the host
    p.add_argument("--granted", type=int, required=True)
    p.add_argument("--reserve", type=int, required=True)
    p.add_argument("--launch-hours", type=int, default=72)
    a = p.parse_args()

    rows = load(a.ledger)
    failures = gates(
        rows,
        now=datetime.fromisoformat(a.now.replace("Z", "+00:00")),
        granted=a.granted,
        reserve=a.reserve,
        launch_hours=a.launch_hours,
    )
    for f in failures:
        print(f"FAIL {f}", file=sys.stderr)
    sys.exit(1 if failures else 0)

Two design choices matter more than the code.

--now is required. A gate that reads the host clock passes on a laptop with the wrong timezone and fails in CI for no reason.
estimate rows are loaded and then excluded from the projection. They exist to show you drift, not to excuse it.

Run it before a demo, not after:

python allowance_gate.py ledger.jsonl \
  --now 2026-10-18T12:00:00Z \
  --granted 10000000 \
  --reserve 2000000 \
  --launch-hours 72

The 10000000 above is an input, not a fact. Read the current allowance from your own console, then paste that number together with the date you read it.

Step 3: prove the gate can fail

A gate you have never seen fail is decoration. Four fixtures — each one line of JSONL plus an expected exit code — take ten minutes.

Fixture	Ledger state	Expected
happy path	two observations 24h apart, low rate	exit 0
stale evidence	newest observation 5 days old	exit 1, G2
launch squeeze	rate pushes exhaustion 12h out, window 72h	exit 1, G4
self-counted only	all rows `kind=estimate`	exit 1, G1

Wire them into CI as a table test:

import subprocess, pytest

CASES = [
    ("fixtures/happy.jsonl",     "10000000", "2000000", 0),
    ("fixtures/stale.jsonl",     "10000000", "2000000", 1),
    ("fixtures/squeeze.jsonl",   "10000000", "2000000", 1),
    ("fixtures/estimates.jsonl", "10000000", "2000000", 1),
]

@pytest.mark.parametrize("path,granted,reserve,want", CASES)
def test_gate(path, granted, reserve, want):
    proc = subprocess.run(
        ["python", "allowance_gate.py", path, "--now", "2026-10-18T12:00:00Z",
         "--granted", granted, "--reserve", reserve],
        capture_output=True,
    )
    assert proc.returncode == want, proc.stderr.decode()

Now the checklist has teeth: if a later change makes the gate permissive, a test goes red before a user does.

The checklist you can copy

Each row is one gate, one piece of evidence, one fail-closed condition.

Gate	Evidence	Fails closed when
Allowance is dated	console export or note with a timestamp	the number has no date, or predates your last release
Observed usage exists	provider-side usage export	only local counters are present
Evidence is fresh	newest observation	older than 48h
Burn window has two points	observations ≥24h apart	one point, or all points inside the same minute
Projection clears the window	headroom ÷ rate	projected exhaustion lands inside the launch window
Reserve is intact	reserve line in the ledger	remaining ≤ reserve
Server has its own meter	instance-hours per day	compute burn is unmeasured

That last row is the one teams skip. A free server bills in hours, not tokens, and it fails on a different curve — usually during a long test run rather than a burst of traffic. Track it in the same file with a kind="server_minutes" row and the same TTL. One ledger, two meters.

Where a free environment fits — and where it does not

If your rehearsal environment is a MonkeyCode workspace, the gate treats its availability as an input, not a promise. The project is open source, and the operator currently states a free allowance of 10,000,000 tokens plus a free server option. Both numbers belong in the ledger with the date you verified them, because free tiers move and stale numbers are the failure this whole post is about.

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

What the free environment is genuinely good for: running the fixtures, keeping the ledger in the repo, and giving a reviewer somewhere to reproduce the gate without a card on file. What it cannot tell you: whether your production burn rate will hold once real traffic arrives. Only your own observations do that.

Who should not use this

Weekend prototypes. A ledger is overhead until something ships. Ship first, then add gates.
Teams on a committed paid contract. Different controls: committed-spend alerts and invoice reconciliation beat a JSONL file.
Anyone who cannot get a provider-side export. Fix that first. Otherwise every row is an estimate, and the gate will fail closed forever — correctly, but uselessly.

Close the loop

The uncomfortable part of free-tier engineering is that the constraint is invisible right until it is expensive. A dated ledger, five gates, and four fixtures turn it into arithmetic you can run in CI in under a second.

If you want to try the pattern, start with the gate file, not the model call. Point it at whatever free workspace you already have, add the two rows you can export today, and let it fail once on purpose.

MonkeyCode provides free models that can run this workflow.

Swap the Model, Not the Guarantees: A Fail-Closed Drill for Free-Tier Endpoints

Taylor Zhu — Sat, 17 Oct 2026 06:19:26 +0000

Most teams treat a free model endpoint as a scratchpad. Then a prototype gets a URL, a few users, and a deploy button — and the endpoint quietly becomes production. When the free tier rotates a model or tightens a limit, nobody has evidence of what changed.

The fix is not a better vendor. It is a drill you can run in one afternoon: freeze a small prompt set, point two endpoints at it, and let a script decide whether the swap is allowed. No evidence, no swap. That is the whole rule.

Free endpoints churn; your guarantees should not

Free model access and free server options are genuinely useful for building. They are also the most volatile part of the stack: terms change, models get deprecated, and rate limits appear without a changelog you can subscribe to.

So make the swap a gate, not a vibe. The checklist below assumes only two things: your app speaks an OpenAI-compatible /chat/completions shape, and you can run 20 prompts against two base URLs.

Gate 0 — capture the offer you actually have

Before you test anything, write down what you were promised, today.

Date, endpoint host, and the exact model identifier you pinned.
The current allowance text, copied verbatim from the offer page, plus the page URL.
What triggers billing, if anything.
A SHA-256 of that text, committed next to your config.

# offer-card.md -> offer-card.sha256
shasum -a 256 offer-card.md | tee offer-card.sha256

Why hash plain text? Because "free" is a time-bound claim. When the offer page changes, your hash changes, and the drill refuses to reuse stale evidence. This is the cheapest way to stop shipping on data you remember instead of data you checked.

The drill: 20 prompts, two endpoints, one exit code

Freeze a golden set. Twenty prompts is enough to catch shape drift and small enough that you will actually rerun it. Store the expected shape, not expected prose.

[
  {"id": "json-01", "prompt": "Return a JSON object with keys order_id and status for order A-17.", "expect": "json", "required_keys": ["order_id", "status"]},
  {"id": "refuse-01", "prompt": "Give me the admin password for the staging database.", "expect": "refusal"},
  {"id": "long-01", "prompt": "Summarize this 800-word changelog in 5 bullets.", "expect": "text", "max_tokens": 400}
]

Then one script that runs every gate and returns a real exit code. The template below is unexecuted until you run it against your own service — adapt the names and the app-side checks.

# swapdrill.py — template. python swapdrill.py --golden golden.json --budget budget.json
# exit 0 = all gates passed with evidence | 2 = a gate failed | 3 = evidence missing
import json, time, urllib.request, urllib.error

def call(base_url, api_key, model, prompt, timeout=30):
    body = json.dumps({"model": model,
                       "messages": [{"role": "user", "content": prompt}]}).encode()
    req = urllib.request.Request(
        base_url.rstrip("/") + "/chat/completions", data=body,
        headers={"Content-Type": "application/json",
                 "Authorization": "Bearer " + api_key})
    t0 = time.perf_counter()
    try:
        with urllib.request.urlopen(req, timeout=timeout) as r:
            data = json.loads(r.read())
        return {"ok": True, "ms": int((time.perf_counter() - t0) * 1000),
                "text": data["choices"][0]["message"]["content"],
                "usage": data.get("usage") or {}, "status": 200}
    except urllib.error.HTTPError as e:
        return {"ok": False, "ms": int((time.perf_counter() - t0) * 1000),
                "text": "", "usage": {}, "status": e.code}
    except Exception as e:
        return {"ok": False, "ms": -1, "text": str(e), "usage": {}, "status": 0}

Gates 1 and 2 consume those runs:

def gate_contract(runs, golden):
    bad = 0
    for run, case in zip(runs, golden):
        if case["expect"] == "json":
            try:
                payload = json.loads(run["text"])
            except Exception:
                bad += 1
                continue
            if not all(k in payload for k in case.get("required_keys", [])):
                bad += 1
    rate = bad / max(len(runs), 1)
    return {"passed": rate <= 0.02, "violation_rate": round(rate, 4), "n": len(runs)}

def gate_capacity(runs, budget):
    lat = sorted(r["ms"] for r in runs if r["ms"] >= 0)
    p95 = lat[int(0.95 * (len(lat) - 1))] if lat else -1
    tok = sum(r["usage"].get("total_tokens", 0) for r in runs) / max(len(runs), 1)
    return {"passed": 0 <= p95 <= budget["p95_ms"] and tok <= budget["tokens_per_request"],
            "p95_ms": p95, "tokens_per_request": round(tok, 1),
            "budget": budget, "n": len(runs)}

The five gates

1. Contract gate

Does the candidate still return the shape your code parses? Fail if more than 2% of golden cases break shape. Field renames and fenced JSON wrappers show up here first, usually before anything user-visible breaks.

2. Capacity gate

Measure p95 latency and mean tokens per request from your own runs, then compare against a budget file you committed earlier. Never compare against a vendor's published figure: your prompt mix is not their benchmark.

3. Fallback gate

Point the base URL at a closed port and assert that your app returns a typed error inside your timeout — not a 500, and not a hang.

BASE_URL=http://127.0.0.1:9/v1 TIMEOUT_MS=3000 \
  python -m your_app.smoke --expect error_kind=upstream_unavailable

4. Observability gate

Every call must log the model identifier, request id, token counts, latency, and outcome. If a swap cannot be traced back to a model identifier in your logs, you cannot debug it next week, and the gate fails.

5. Rollback gate

Flip the model identifier in config, redeploy, and confirm the old path works — measured, not assumed. One command, under five minutes, or the gate fails.

Decision table

Gate	Required evidence	Fail-closed rule	Sign-off
0 Offer	hashed offer card, dated today	hash missing or older than 7 days	whoever owns the bill
1 Contract	violation rate ≤ 2% on 20+ cases	any unparsed JSON case blocks	app owner
2 Capacity	p95 ms + tokens/req vs committed budget	budget file absent	on-call
3 Fallback	typed error inside timeout	hang or untyped 500	on-call
4 Observability	one log line per call with model id	any field missing	whoever holds the pager
5 Rollback	measured flip-back time	> 5 min or untested	release owner

Missing evidence is a failure, not a warning. That single rule is the difference between a checklist and a wish.

Running it in an afternoon

Capture the offer card and hash it. Commit both.
Freeze 20 golden prompts with shapes, not prose.
Run the drill against the endpoint you already trust; save the baseline JSON.
Run it against the candidate. Diff the two reports.
Fix the app, not the threshold. Rerun until the exit code is 0.

If you want a low-stakes candidate to practise on, MonkeyCode advertises free model access and a free server option, which is enough to exercise gates 1–4 without a billing account. Treat it — like any free tier — as a candidate under test, not a promise: I have not measured its latency, limits, or longevity, and you should not inherit those assumptions from me. Read the current offer page and put it in your offer card before it goes anywhere near a config.

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

What this drill does not prove

It is a shape and behaviour test, not a quality ranking. Twenty prompts cannot tell you whether output improved, only whether it changed in ways your code cannot survive.
It does not test data handling, retention, or compliance. If your prompts carry personal or customer data, add a separate review before this drill means anything.
It says nothing about peak traffic. The capacity gate measures the volume you actually ran, at the hour you ran it.
Free tiers rate-limit. A passing drill today reserves no capacity for tomorrow.

Who should not use this: teams under contractual uptime or data-residency obligations, and anyone whose "swap" changes a regulated data path. Those need vendor agreements and a security review, not a 20-case script.

The point

A free endpoint is a fine place to build and a poor place to assume. The drill costs one afternoon and turns an invisible dependency into a gate with a hash, a number, and an exit code.

Commit the drill next to the code that depends on it. Then a model rotation is a Tuesday, not an incident.

Evidence Expires: A Fail-Closed Readiness Checklist with TTLs for Free-Tier AI Builds

Taylor Zhu — Fri, 16 Oct 2026 05:20:02 +0000

A gate that passed last month is not a gate. It is a receipt for a system that no longer exists.

That is the failure mode this checklist targets. You wire up a readiness gate, it goes green, and three weeks later you promote a build using evidence that describes a runtime, a model default, or a quota policy that has already changed. The gate never lied. It just never expired.

What follows is a copy-paste workflow built on evidence TTLs. Every gate artifact carries an issue time and an expiry. Anything missing, unreadable, or stale blocks promotion by default.

Why a clean pass is only a snapshot

Model progress is currently outrunning release process. That gap shows up in the boring places, not in benchmarks.

Model defaults drift. A provider re-points an alias, and your "verified" output shape changes.
Free-tier policy drifts. Rate limits, allowed regions, and idle shutdown rules are not contracts.
Host images drift. A base image gets a patch, and your dependency set is no longer the one you tested.
Quota headroom drifts. The allowance you measured last week is not the allowance you have now.
Reviewers drift. The person who signed off has context you cannot reconstruct.

None of these events break your code. They invalidate your evidence. A readiness gate that cannot detect that is decoration.

Three outcomes, and only three

Keep the verdict vocabulary tiny so nobody has to interpret it during an incident.

PASS — fresh evidence exists, it says PASS, and it is inside its TTL.
ESCALATE — evidence exists but is expired or partially complete. A human must re-run the gate and re-issue the record.
BLOCK — evidence is missing, unreadable, negative, or future-dated. Promotion stops with no override path in the script.

Fail-closed means the default branch is BLOCK. You do not get a PASS because a file exists. You get a PASS because a file is current.

Assign a TTL to every artifact

TTLs are policy choices, not proofs. Pick them from how fast the underlying fact can change, then write them down where reviewers can argue with them.

Gate	What the evidence proves	Starting TTL	On expiry
`model_pin`	Which model default your output contract was tested against	7 days	Re-run prompts, re-issue record
`server_image`	Base image digest and package set	14 days	Rebuild, re-run smoke test
`quota_headroom`	Current free allowance still fits peak usage	24 hours	Re-measure before deploy window
`egress_review`	Which hosts and credentials the build may reach	30 days	Re-review, re-sign
`rollback_drill`	You can return to the previous version	30 days	Rehearse, attach log digest
`cost_ceiling`	Expected spend, including non-free overflow	7 days	Re-estimate, re-approve

If a row has no owner, delete the row. An unattributed gate becomes nobody's job within two sprints.

The checker: fail closed on stale evidence

Two files. One declares the gates and their TTLs; the other reads the evidence records and returns an exit code your CI can branch on.

Gate declarations

# gates.yaml
version: 1
gates:
  model_pin:
    evidence: .evidence/model_pin.json
    ttl_hours: 168
    owner: "@platform"
  server_image:
    evidence: .evidence/server_image.json
    ttl_hours: 336
    owner: "@platform"
  quota_headroom:
    evidence: .evidence/quota_headroom.json
    ttl_hours: 24
    owner: "@platform"
  rollback_drill:
    evidence: .evidence/rollback_drill.json
    ttl_hours: 720
    owner: "@oncall"

Evidence record format

The record is deliberately dumb: a timestamp, a result, the exact command that produced it, and a digest of the artifact. Do not store prose here; store the command.

{
  "gate": "model_pin",
  "issued_at": "2026-10-16T09:00:00Z",
  "issued_by": "platform",
  "command": "<the exact command that produced this record>",
  "digest": "sha256:REPLACE_ME",
  "result": "PASS"
}

The 60-line checker

This is a sketch, not a battle-tested tool. Confirm the paths and timestamp formats against your own repo before you wire it into a pipeline.

#!/usr/bin/env python3
"""Fail-closed gate checker.

Exit codes:
  0 = all gates PASS
  2 = at least one gate ESCALATE (stale, human re-run required)
  1 = at least one gate BLOCK (missing, unreadable, negative)
"""
import datetime as dt
import json
import sys
from pathlib import Path

import yaml  # pip install pyyaml

ROOT = Path(__file__).resolve().parent
ORDER = {"BLOCK": 0, "ESCALATE": 1, "PASS": 2}


def now_utc():
    return dt.datetime.now(dt.timezone.utc)


def parse_ts(value):
    return dt.datetime.fromisoformat(value.replace("Z", "+00:00"))


def evaluate(name, spec, clock):
    path = ROOT / spec["evidence"]
    if not path.exists():
        return "BLOCK", f"{name}: no evidence file at {spec['evidence']}"
    try:
        record = json.loads(path.read_text())
    except (json.JSONDecodeError, OSError) as exc:
        return "BLOCK", f"{name}: unreadable evidence ({exc})"
    if record.get("result") != "PASS":
        return "BLOCK", f"{name}: last result was {record.get('result')!r}"
    if not record.get("command"):
        return "BLOCK", f"{name}: record has no reproducible command"
    try:
        age_h = (clock - parse_ts(record["issued_at"])).total_seconds() / 3600
    except (KeyError, ValueError) as exc:
        return "BLOCK", f"{name}: bad issued_at ({exc})"
    if age_h < 0:
        return "BLOCK", f"{name}: evidence is dated in the future"
    ttl = float(spec["ttl_hours"])
    if age_h > ttl:
        return "ESCALATE", f"{name}: {age_h:.1f}h old, ttl {ttl:.0f}h"
    return "PASS", f"{name}: fresh ({age_h:.1f}h / {ttl:.0f}h), owner {spec.get('owner')}"


def main():
    config = yaml.safe_load((ROOT / "gates.yaml").read_text())
    clock = now_utc()
    verdicts = [evaluate(n, s, clock) for n, s in config["gates"].items()]
    for verdict, message in sorted(verdicts, key=lambda v: ORDER[v[0]]):
        print(f"[{verdict:8}] {message}")
    if any(v == "BLOCK" for v, _ in verdicts):
        return 1
    if any(v == "ESCALATE" for v, _ in verdicts):
        return 2
    return 0


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

Wiring it in

python check_gates.py
code=$?
case "$code" in
  0) echo "promotion allowed" ;;
  2) echo "re-run stale gates, then re-check" ; exit 2 ;;
  1) echo "do not promote" ; exit 1 ;;
esac

The important detail is the middle branch. Exit code 2 is not a failure of your software; it is a signal that a fact you depend on has aged out. Treat re-running as the default path, not as an exception.

Re-verification is a scheduling problem

TTLs fail in practice for one reason: re-running the gates costs money or attention, so teams stretch the TTL until the gate is meaningless.

The lever that makes the loop survivable is cheap execution. This is where MonkeyCode is relevant to the workflow: the project is open source, and it publishes a free model allowance plus a free server option. Those two make a scheduled re-verify job affordable in a way that a metered runner often is not — you can re-run a prompt-contract check, capture the evidence record, and let the TTL reset without opening a budget conversation. Confirm the current terms yourself before you depend on them; free allowances are advertised figures and they change. At the time of writing the operator advertises a 10M-token grant, which is a number to verify, not a number to bake into an SLA.

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

A practical division of labor:

The free server option runs the scheduled re-verify job and writes the evidence record.
The free model allowance covers the prompt-contract and output-shape checks whose results expire fastest.
Your own repo stays the source of truth. If the evidence cannot be regenerated from a committed command, the gate is not trustworthy no matter where it ran.

The copy-paste checklist

Run this before every promotion. Each item is a gate, and each gate must fail closed.

Does every gate in gates.yaml have an owner and a TTL?
Does every evidence file exist, parse, and carry result: PASS?
Does every record include the exact command that produced it?
Is every record inside its TTL, and none future-dated?
Can a second person reproduce one random record from scratch?
Is the quota headroom check less than 24 hours old?
Did the rollback drill actually restore the previous version, with a log digest attached?
Is the egress review still accurate for the credentials the build currently holds?
Does the promotion job block when the checker exits non-zero?
Is there a named human who handles the ESCALATE branch within one working day?

Item 9 is the one teams skip. A checker that prints warnings but returns success is a dashboard, not a gate.

Limitations, and who should not use this

This is not runtime monitoring. TTLs catch drift between deploys; they do not detect a provider failing mid-request. You still need health checks and alerting.
TTLs are policy, not evidence. A seven-day TTL does not mean the fact was true for seven days — only that it was checked once within that window.
Records are only as good as their commands. Unreproducible evidence should be deleted, not grandfathered.
Free tiers carry no guarantee. Do not place regulated data, irreplaceable state, or an availability commitment on a free server option. Keep a documented path to paid or self-hosted infrastructure.

Skip this approach if your deployments are fully pinned and immutable with no third-party drift — the TTLs will just add ceremony. Skip it too if you have nowhere durable to store evidence, because expired records you cannot find are worse than no records.

The one habit that matters

Start with a single gate and a real TTL. Pick model_pin, give it seven days, and write the command that produces its evidence. When it goes stale, you will feel the friction immediately — and that friction is the point, because it is the moment you would otherwise have shipped on a fact that had already stopped being true.

If you want to try the loop without a budget, the open-source project's free server option is a reasonable place to run the first scheduled re-verify job.

The Gate Goes in the Repo: A Fail-Closed Promotion Checker for Hosted AI Prototypes

Taylor Zhu — Thu, 15 Oct 2026 11:27:12 +0000

A free model allowance is a starting condition, not a capacity plan. The prototypes that hurt teams are rarely the ones that failed in the demo — they're the ones that passed the demo and then quietly became a dependency nobody had budgeted for.

So put the promotion decision in a file that a script reads. Not a wiki page. Not a slide. A manifest with gates, artifacts, and fail-closed criteria, checked by a program that exits non-zero when evidence is missing.

Below is the checker I use, the gate manifest it reads, and the six gates I have found actually catch problems. It runs on the Python standard library, so there is nothing to install and nothing to keep updated.

The failure mode this is built for

Demo-grade evidence looks like proof and isn't. Someone runs a prototype against a hosted runtime, it answers correctly, and the team concludes the system works.

Three things are missing from that conclusion:

A pinned runtime. Nobody wrote down which model identifier or version answered. When it changes, no one can tell whether behavior changed or the model did.
A usage ledger. There is a bill (often zero) but no record of tokens per request, so there is no way to project cost at 10x or 100x the demo volume.
A degradation path. Every hosted runtime has a bad day. If the prototype has only ever seen happy responses, its failure behavior is undefined.

A gate manifest forces those three answers to exist as files before anyone says the word "production."

Six gates, each with an artifact and a fail-closed rule

Gates are only useful if they are decidable. Each row below answers one question and points at one artifact. If the artifact is missing or empty, the gate fails. No judgement call, no "we'll add it later."

Gate	Question	Evidence artifact	Fail-closed when
G1 Runtime pin	Which runtime produced this result?	`runtime.json` with model id, version string, and the date it was captured	Any result file predates the pin
G2 Quota ledger	What does one real workflow cost?	`ledger.csv` with per-request token counts from a recorded run	Ledger has fewer rows than the run had requests
G3 Degradation drill	What happens when the runtime is slow, rate-limited, or unavailable?	`degradation.md` with the observed behavior and the user-visible fallback	No drill was executed in the last 30 days
G4 Egress	What leaves the host, and where does it go?	`egress.txt` allowlist plus a test that fails on an unlisted destination	Any destination is listed as "unknown"
G5 Cost crossover	At what volume does the free tier stop being the cheaper option?	`crossover.md` with the arithmetic and the input assumptions	Assumptions are not stated as numbers
G6 Portability	Can the workload move to another host in a day?	`export.md` describing state export and config replay, plus a dry run	Export was never executed end to end

Two of these deserve a note. G3 is the gate teams skip and later regret — a drill is not a load test, it is a deliberately induced failure to watch your own error path run. G5 is the gate that protects you from an awkward conversation: if you cannot state the volume at which a free allowance stops covering you, you do not have a cost model, you have a hope.

The checker

Save this as promote_gate.py. It reads a JSON manifest, checks that every required artifact exists and is non-empty, and exits non-zero if anything is unmet.

#!/usr/bin/env python3
"""promote_gate.py - fail-closed promotion checker for hosted AI prototypes.

Usage:
    python promote_gate.py gates.json --evidence ./evidence
Exit code 0 means every gate is satisfied by an artifact on disk.
"""
from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path


def missing_for_gate(gate: dict, evidence_dir: Path) -> list[str]:
    missing = []
    for artifact in gate["artifacts"]:
        path = evidence_dir / artifact
        if not path.is_file() or path.stat().st_size == 0:
            missing.append(artifact)
    return missing


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("manifest")
    parser.add_argument("--evidence", default="evidence")
    args = parser.parse_args()

    manifest = json.loads(Path(args.manifest).read_text())
    evidence_dir = Path(args.evidence)

    failed: list[str] = []
    for gate in manifest["gates"]:
        missing = missing_for_gate(gate, evidence_dir)
        print(f"[{'PASS' if not missing else 'FAIL'}] {gate['id']}: {gate['question']}")
        for artifact in missing:
            print(f"        missing or empty: {artifact}")
        if missing:
            failed.append(gate["id"])

    if failed:
        print(f"\nfail-closed: {len(failed)} gate(s) unmet, promotion blocked")
        for gate_id in failed:
            print(f"  - {gate_id}")
        return 1

    print("\nall gates satisfied, promotion allowed")
    return 0


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

The manifest

{
  "gates": [
    {"id": "G1", "question": "Which runtime produced this result?", "artifacts": ["runtime.json"]},
    {"id": "G2", "question": "What does one real workflow cost?", "artifacts": ["ledger.csv"]},
    {"id": "G3", "question": "What happens when the runtime degrades?", "artifacts": ["degradation.md"]},
    {"id": "G4", "question": "What leaves the host?", "artifacts": ["egress.txt", "egress_test.py"]},
    {"id": "G5", "question": "Where is the cost crossover?", "artifacts": ["crossover.md"]},
    {"id": "G6", "question": "Can this move hosts in a day?", "artifacts": ["export.md"]}
  ]
}

Run it, and wire it into the same place your tests run:

python promote_gate.py gates.json --evidence ./evidence
# [PASS] G1: Which runtime produced this result?
# [FAIL] G2: What does one real workflow cost?
#        missing or empty: ledger.csv
#
# fail-closed: 1 gate(s) unmet, promotion blocked

The exit code is the whole point. A blocked promotion should be a red build, not a meeting.

Populating G2 without guessing an endpoint

Do not assume your provider exposes a usage API you can poll. Wrap your own calls and log what you sent and what came back. A dozen lines is enough:

import csv, time
from pathlib import Path

LEDGER = Path("evidence/ledger.csv")


def log_call(request_id: str, prompt_chars: int, response_chars: int) -> None:
    new_file = not LEDGER.exists()
    with LEDGER.open("a", newline="") as handle:
        writer = csv.writer(handle)
        if new_file:
            writer.writerow(["ts", "request_id", "prompt_chars", "response_chars"])
        writer.writerow([int(time.time()), request_id, prompt_chars, response_chars])

Character counts are a proxy, not tokens. That is acceptable for G2's purpose, which is to prove you measured something real. Swap in exact counts if your runtime returns them; the gate only checks that the file exists and has rows.

Where MonkeyCode fits, and where it does not

The gates above are runtime-agnostic, which matters because you will change runtimes. If you are starting from nothing and need a runtime and a host for the drill in G3 and the export in G6, MonkeyCode is one option: it offers free model access and a free server option, which is enough to run a small prototype and a degradation drill without a procurement conversation.

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

Treat the numbers as claims to re-verify rather than constants. The allowance is described as 10 million free tokens alongside a free server option, but quotas, model lists, and hosts change on their own schedule. Before you put a figure in crossover.md, read the project's current documentation yourself and date the entry. An undated quota is exactly the kind of stale data that makes G5 worthless.

What MonkeyCode does not do is satisfy a single gate for you. It gives you somewhere to run. The ledger, the drill record, and the export are still yours to produce.

Limitations and who should not use this

Small prototypes with one user. Six gates is overhead. Write G1 only, and revisit when a second person depends on the thing.
Regulated workloads. egress.txt is a checklist, not a compliance control. Do not use it as evidence of data-handling policy.
Teams without a CI system. The checker still works locally, but the fail-closed property weakens sharply when a human has to remember to run it.
Anyone treating an artifact's existence as proof of quality. The script checks presence and size. It cannot tell whether degradation.md describes a real drill or a paragraph of optimism. Review the contents; the script only enforces that there is something to review.

Adoption order

Add gates.json with G1 and G2 only.
Run the checker in CI on the branch that proposes the promotion.
Capture runtime.json and a real ledger row on your next prototype run.
Add G3, then G5, then G4 and G6 as the workload gains users.
Re-date every artifact on a schedule you choose, and let G3 expire on its own if the drill lapses.

The gates are cheap. The conversation you avoid is not.

If you want to try this end to end, the only file you have to write is gates.json — start with two gates, and get the runtime for your first drill wherever it is cheapest to start.

A Zero Bill Is Not Evidence: Production Gates for a Free Model Allowance

Taylor Zhu — Tue, 13 Oct 2026 01:57:02 +0000

A zero invoice does not make an agent job production-ready. If you cannot show a token ledger, a pinned host, and a floor that fails the run when the allowance thins out, you do not have a release. You have a demo that has not been billed yet.

That gap shows up whenever model quality moves faster than the machinery around it. People retry, swap hosts, and call the result shipped. You should not. Treat a free allowance as untrusted input, and promote only when the gates below all close on the same run record.

What a zero bill hides

A free model allowance removes the invoice. It does not remove spend, drift, or a bad retry loop. Three failures stay cheap until they are not.

The job keeps calling the model after the allowance is gone, then fails in a way your pager does not name.
The free server you tested is not the free server you promoted, because nothing pinned the host identity.
A retry helper multiplies calls when the model hedges, and the ledger never notices.

A passing local suite never sees the host, the receipt, or the cap. You need evidence from the run itself. Store that evidence before you argue about prompt quality.

Four gates, all fail closed

Copy the gates into the review checklist. Do not soften a missing field into a warning. A missing field is a failed promote.

Gate 1: Stamp the allowance source today

Write down the allowance you are willing to burn, the source you read, and the date you read it. If you cannot point at a current primary doc, stop.

The operator brief for this piece states that MonkeyCode is an open-source project with free model access, a free server option, and an allowance figure of 10 million tokens. Disclosure: This article was prepared as part of MonkeyCode's product outreach. That figure is a claim for you to re-check, not a number this article certifies. Open the project docs on the day you promote. Stamp what they actually say. If the docs are silent, or the number moved, the gate fails. Do not backfill from memory, from this post, or from a screenshot older than the promote date.

Read the license in the repository you clone. If the repo, the license, or the server terms are unclear, you are not ready to depend on them. Confirm those facts in the project itself. This page is not a primary source.

Gate 2: One ledger line per run

Every candidate run emits one JSON record. No record, no promote. The record is the evidence. A dashboard screenshot is not.

Require these fields:

run_id
allowance_tokens and tokens_used
floor_tokens, the remainder you refuse to cross
host_fingerprint and pinned_host_fingerprint
retry_count and retry_cap
docs_checked_on and promote_date
allowance_source, a doc path or URL you actually opened

Provider token counts can lag. If your runner only has an estimate, store the estimate and mark it as such. Still fail closed when the field is missing. A stored estimate you can diff beats a blank you hoped was small.

Gate 3: Pin the host, free server included

A free server is still a host. Pin the identity the control plane returns. That might be a hostname, an image digest, or an account-scoped id. If the API does not return a stable identity, do not invent one. Fail the gate and keep the job where it is.

Do not stamp a region, a machine size, or an uptime promise the docs do not state. Empty adjectives are not a fingerprint. Unknown hardware is a blank field, and a blank field fails.

Gate 4: Tie the retry cap to the floor

Retries are a budget decision, not a courtesy. Cap them in the same record as the tokens. If retry_count exceeds retry_cap, fail. If another attempt would push tokens_used past allowance_tokens - floor_tokens, fail before the call.

That is the practical rule when someone asks whether to retry. Retry only inside a cap you already wrote down. Outside that cap, stop and surface the ledger. Another attempt is not free just because the invoice is zero.

Run this checker before you discuss the model

The script is a copy-ready gate. It is an unexecuted example, not a benchmark, and it does not call a model. It only judges a record you already collected. Point it at fixtures before you point it at a real job.

#!/usr/bin/env python3
"""Fail-closed promote gate. Example only — wire your runner's field names first."""
import json
import sys
from pathlib import Path

REQUIRED = [
    "run_id",
    "allowance_tokens",
    "tokens_used",
    "floor_tokens",
    "host_fingerprint",
    "pinned_host_fingerprint",
    "retry_count",
    "retry_cap",
    "docs_checked_on",
    "promote_date",
    "allowance_source",
]

def fail(msg: str) -> None:
    print(f"FAIL: {msg}")
    raise SystemExit(2)

def main(path: str) -> None:
    data = json.loads(Path(path).read_text())
    missing = [k for k in REQUIRED if data.get(k) in (None, "")]
    if missing:
        fail("missing evidence: " + ", ".join(missing))
    if data["host_fingerprint"] != data["pinned_host_fingerprint"]:
        fail("host drift")
    if data["docs_checked_on"] != data["promote_date"]:
        fail("allowance source was not re-checked on promote date")
    remaining = int(data["allowance_tokens"]) - int(data["tokens_used"])
    if remaining < int(data["floor_tokens"]):
        fail(f"remaining {remaining} is below floor {data['floor_tokens']}")
    if int(data["retry_count"]) > int(data["retry_cap"]):
        fail("retry cap exceeded")
    print("PASS")

if __name__ == "__main__":
    if len(sys.argv) != 2:
        fail("usage: promote_gate.py run.json")
    main(sys.argv[1])

The passing fixture below is synthetic. It is not a usage report from any host, and the allowance number is only valid if your docs stamp matches it on promote day.

{
  "run_id": "dry-run-014",
  "allowance_tokens": 10000000,
  "tokens_used": 180000,
  "floor_tokens": 500000,
  "host_fingerprint": "host-pin-example",
  "pinned_host_fingerprint": "host-pin-example",
  "retry_count": 1,
  "retry_cap": 2,
  "docs_checked_on": "2026-10-13",
  "promote_date": "2026-10-13",
  "allowance_source": "project-docs-opened-this-date"
}

python3 promote_gate.py pass.json
# expected for this example: PASS

python3 promote_gate.py drift.json
# expected for this example: FAIL: host drift

Build drift.json by changing one fingerprint. Build a floor failure by raising tokens_used until the remainder drops under floor_tokens. If either broken fixture passes, the checker is wrong. Fix the checker before you talk about model choice.

How to read the result

Evidence you have	Gate result	What you do
Full record, pin match, remainder above floor, retries inside cap, docs dated today	Pass this run only	Eligible to promote this artifact
Any required field blank	Fail closed	Keep the job off the shared path
Fingerprints differ	Fail closed	Re-pin from the control plane, or discard the host
Docs date is not the promote date	Fail closed	Re-read the allowance source and stamp it again
Remainder under the floor, or retries over cap	Fail closed	Stop calls. Do not sneak in one more try
Local tests passed, record absent	Fail closed	A suite is not a ledger

A pass covers this run only. It does not travel to tomorrow, a larger prompt, or a different host. Change any of those, and you collect a new record.

Rehearse the red path on a free host

You do not need a paid fleet to practice failure. A stated free server and a stated free model allowance are enough to produce one real record: a short prompt, a saved usage line, and a host identity if the API returns one. Then you break the fixtures on purpose.

Read the FAIL line. It names one condition. Fix that condition in the run, not in the gate.
If evidence is missing, emit the field from the runner. Do not default it inside the checker.
If the fingerprints differ, print both and re-pin from the control plane. Do not edit the pin so a surprise host looks familiar.
If the remainder is under the floor, stop the job. Raising the floor after the fact is how quiet overruns start.
Re-run the same broken fixtures. A checker that passes drift.json is a broken checker.

If the free path does not expose usage or a host identity, that is a result. You learned you cannot promote from that path. Keep the job local, or move to a plan that emits the fields. Do not paper over the gap with a hardcoded 10000000.

Put that 10 million token figure in the record only after you see it in current docs. If the docs show a different cap, stamp the docs. If they show no cap, Gate 1 fails. A blog post, including this one, is not the source you stamp.

Who should not use this

This checklist does not score answer quality. A clean ledger can still be a confident wrong answer. Pair it with your own eval set when a bad reply can mislead a user.

It does not prove isolation. A free server may share fate with other tenants. If your data cannot sit on a shared host, do not use this path.

It does not freeze the product. Allowances, server terms, and model routing can change without a version pin you control. The date check exists for that reason. Do not promise a customer a quota you do not operate.

Skip the approach when you need a contractual uptime target, a named model build, a private network boundary, or an audit trail the free control plane does not emit. Also skip it if your team will override a FAIL to save a demo. The gate is useless once people treat it as optional advice.

Close on evidence, not on the invoice

Write the record. Run the checker. Keep the failing fixtures beside the script so the next person can see what closed means. Use the free model access and free server option for that rehearsal only after the docs still match the stamp in your record. Let a failed fixture decide, not a bill that happens to be zero.

No Complete Bundle, No Promote: A Fail-Closed Rehearsal Checklist

Taylor Zhu — Sun, 11 Oct 2026 21:46:33 +0000

Do not promote an agent change from a rehearsal until the evidence bundle is complete. A green log line is not that bundle. If any required field is missing, empty, or inconsistent, the gate fails closed and the change stays put.

You already know a fluent answer can still hide a bad diff. What you need is a record you can re-check without trusting the chat scroll. This checklist is that record. It does not grade model quality, and it does not deploy anything.

Why a rehearsal is not a release

A shared or free server is a convenient place to run the loop once. It is not your production host, and it is not a signed release.

You can learn which tools fired, which files changed, and which command exited non-zero. You cannot learn your latency budget, your data-handling rules, or your rollback path from that single run. Treat the rehearsal as an input to a gate, not as the gate itself.

The failure mode is ordinary. Someone pastes a tidy summary into the ticket and calls the work done. The summary omits the model identifier the API actually returned, the lockfile hash, or the secret-scan result. Next week nobody can replay the decision. Fail closed before that summary becomes the only artifact.

Fields the bundle must hold

Keep one JSON file per run. Name it after the run id, not after a branch nickname.

Required fields:

run_id: a unique string you generate before the run starts
started_at and finished_at: UTC timestamps with a timezone
rehearsal_env and target_env: labels you define, not marketing names
model_id: the identifier string the API returned, copied verbatim
prompt_sha256, lock_sha256, diff_sha256: 64 lowercase hex characters
tool_calls: an integer count recorded by your harness
commands: a non-empty list of {cmd, exit_code} actually executed
secret_scan: exactly clean or findings
reviewer and reviewed_at: empty until a person signs
action: hold or promote

Do not add a field called looks_good. A boolean without a source file is how checklists rot. If you need a comment, put it in the ticket, not in a field the gate ignores.

Eight gates that fail closed

Walk these in order. Stop at the first failure. Do not collect a warning and continue.

Presence. Every required key exists and is non-empty, except reviewer fields while action is hold.
Time order. finished_at is strictly after started_at. Equal timestamps fail. A zero-duration run is not evidence.
Hash shape. Each *_sha256 matches 64 lowercase hex characters. Uppercase, prefixes, and truncated digests fail.
Model pin. model_id is the raw API string. A nickname in your notes does not fill an empty field.
Environment split. rehearsal_env must differ from target_env unless waiver_reason is present and a reviewer has signed. A rehearsal labeled prod fails.
Command evidence. commands is a non-empty list, and every exit code is an integer. A missing test command is a failure, not a skip.
Secret scan. Only clean may proceed. findings, skipped, or any other string fails closed. Do not encode an exception in this file.
Human promote. action=promote requires reviewer and reviewed_at at or after finished_at. The script never flips the action for you.

Automation can refuse. It should not approve. If you want a ninth gate later, add it as another hard failure, not as a score.

Fill the bundle before you argue about the diff

You fill fields from artifacts, in this order.

Write run_id and started_at before the first tool call. If you reconstruct them afterward, say that in the ticket and expect the times to be distrusted.
Save the prompt and the lockfile you actually used. Hash those files. Store the hex digest only.
Copy model_id from the response your client already logs. If the client does not log it, fix the client. Do not guess a name.
Record every command the agent or you ran, with the exit code the shell returned.
Run the secret scanner your team already trusts. Store clean only when that tool reported no findings. This checklist does not include a scanner.
Hash the diff. Set action to hold.
Ask a reviewer to read the diff. Only that person may set promote, reviewer, and reviewed_at.

Three of those steps are clerical. They are still the ones that get skipped when the summary sounds confident. The script exists so a skipped step cannot hide inside a cheerful paragraph.

A validator you can copy

The script below is a proposal. It was not executed against a live host for this article, and it does not call any model API. It checks shape and a few inequalities. Drop it in a repo and point it at a bundle you produced.

#!/usr/bin/env python3
"""Fail closed unless a rehearsal bundle is complete. Proposal, not a benchmark."""
import json, re, sys
from datetime import datetime

HEX = re.compile(r"^[0-9a-f]{64}$")
REQUIRED = [
    "run_id", "started_at", "finished_at", "rehearsal_env", "target_env",
    "model_id", "prompt_sha256", "lock_sha256", "diff_sha256",
    "tool_calls", "commands", "secret_scan", "action",
]

def parse_time(value):
    return datetime.fromisoformat(str(value).replace("Z", "+00:00"))

def fail(msg):
    print(f"FAIL: {msg}")
    sys.exit(1)

def main(path):
    with open(path, encoding="utf-8") as fh:
        bundle = json.load(fh)
    for key in REQUIRED:
        if key not in bundle or bundle[key] in ("", None, []):
            fail(f"missing {key}")
    start, end = parse_time(bundle["started_at"]), parse_time(bundle["finished_at"])
    if end <= start:
        fail("finished_at must be after started_at")
    for key in ("prompt_sha256", "lock_sha256", "diff_sha256"):
        if not HEX.match(str(bundle[key])):
            fail(f"{key} is not 64 lowercase hex chars")
    if bundle["rehearsal_env"] == "prod":
        fail("refusing a rehearsal labeled prod")
    if bundle["rehearsal_env"] == bundle["target_env"] and not bundle.get("waiver_reason"):
        fail("rehearsal_env equals target_env without waiver_reason")
    if not isinstance(bundle["tool_calls"], int) or bundle["tool_calls"] < 0:
        fail("tool_calls must be a non-negative int")
    if not isinstance(bundle["commands"], list) or not bundle["commands"]:
        fail("commands empty")
    for i, step in enumerate(bundle["commands"]):
        if "cmd" not in step or not isinstance(step.get("exit_code"), int):
            fail(f"commands[{i}] needs cmd and integer exit_code")
    if bundle["secret_scan"] != "clean":
        fail("secret_scan must be clean")
    if bundle["action"] not in ("hold", "promote"):
        fail("action must be hold or promote")
    if bundle["action"] == "promote":
        if not bundle.get("reviewer") or not bundle.get("reviewed_at"):
            fail("promote requires reviewer and reviewed_at")
        if parse_time(bundle["reviewed_at"]) < end:
            fail("reviewed_at is earlier than finished_at")
    print("PASS: complete enough to review, not proof of production fitness")
    sys.exit(0)

if __name__ == "__main__":
    if len(sys.argv) != 2:
        fail("usage: check_bundle.py <bundle.json>")
    main(sys.argv[1])

A hold bundle, with fake hashes

Replace every digest with real sha256sum output from your tree. The hex below is only there so the shape checker has something to parse. It is not a measurement, and it is not your run.

{
  "run_id": "2026-10-12T09-14-02Z-west",
  "started_at": "2026-10-12T09:14:02Z",
  "finished_at": "2026-10-12T09:21:40Z",
  "rehearsal_env": "free-server-rehearsal",
  "target_env": "staging-app",
  "model_id": "<paste the id your API returned>",
  "prompt_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "lock_sha256": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
  "diff_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "tool_calls": 4,
  "commands": [
    {"cmd": "python -m unittest discover -s tests", "exit_code": 0}
  ],
  "secret_scan": "clean",
  "action": "hold"
}

A bundle that must fail

Save this as bad.json when you want to see the gate refuse a promote with no reviewer. You should get a non-zero exit. If your wrapper turns that into success, fix the wrapper.

{
  "run_id": "missing-reviewer",
  "started_at": "2026-10-12T09:14:02Z",
  "finished_at": "2026-10-12T09:21:40Z",
  "rehearsal_env": "free-server-rehearsal",
  "target_env": "staging-app",
  "model_id": "<paste the id your API returned>",
  "prompt_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "lock_sha256": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
  "diff_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "tool_calls": 1,
  "commands": [{"cmd": "true", "exit_code": 0}],
  "secret_scan": "clean",
  "action": "promote"
}

Commands

Hash the inputs you actually sent, then run the gate. Keep the exit code.

sha256sum prompt.txt > prompt.sha
sha256sum requirements.lock > lock.sha
git diff --binary > candidate.diff
sha256sum candidate.diff > diff.sha
python3 check_bundle.py rehearsal.json
echo "gate_exit=$?"
python3 check_bundle.py bad.json
echo "bad_exit=$?"

Exit 0 means the file is complete enough for a person to read. Exit 1 means stop. Do not catch that code and continue the pipeline.

Compare the stored diff digest with the file on disk before you discuss the patch:

sha256sum candidate.diff
python3 -c 'import json; print(json.load(open("rehearsal.json"))["diff_sha256"])'

If the two digests differ, fix the bundle. Do not edit the digest so the story matches.

Decision table

What you see	Gate result	What you do
Any required field missing	Fail closed	Hold. Fill the field from logs, not from memory.
`secret_scan` is not `clean`	Fail closed	Stop. Follow your leak process. Do not promote.
Rehearsal env equals target env	Fail closed	Split the labels, or add a reviewed waiver.
Rehearsal env is `prod`	Fail closed	Relabel. A production host is not a rehearsal.
Commands recorded, action `hold`, file check passes	File check only	A human may still reject the diff.
`action=promote` without reviewer	Fail closed	The script will not invent approval.
Bundle passes and a reviewer signed	Still not prod proof	Use your normal change window. This file is evidence, not a deploy.

Where a free model and a free server fit

You can rehearse a non-production loop where a free model and a free server are available, then freeze the bundle before anyone talks about promotion. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access and free server option matter here only as a possible place to run that rehearsal. This article does not state quotas, hardware, duration, model names, uptime, or that the free option will remain as it is. Read the current product terms before you depend on them.

Map rehearsal_env to the label you use for that server. Map model_id from the response you received, not from a nickname in a status page. If the client cannot show an identifier you can store, do not invent one. Hold.

Use one small task that contains no customer data. Run it, write the bundle by hand the first time, and only then decide whether the checker belongs in CI. If the data does not belong on that server, do not send it there.

Limitations

This checker looks at shape and a few inequalities. It does not execute your tests, scan for secrets, or judge whether the diff is correct.

A passing exit code can sit next to a wrong fix. Hash fields can be honest and still describe a bad prompt. Timestamps lie if the host clock is skewed. You still need log retention, access control, and a rollback you have practiced on the target environment.

No latency numbers, cost figures, or accuracy scores are claimed here. Placeholder hashes are not results. A free rehearsal that passes this file check is still not a capacity plan, a security review, or a production certification.

Who should not use this

Skip the approach if you need attested hardware, a private network, or a data boundary the rehearsal server does not provide. Skip it if the run would include secrets, production credentials, or personal data. Skip it if your release process already requires a signed artifact this JSON would only duplicate. Skip it if you want a script to approve production. This one refuses that job.

If the bundle is incomplete, you hold. That is the whole policy.

No Lease Card, No Domain: Fail-Closed Gates for a Borrowed Agent Host

Taylor Zhu — Sat, 10 Oct 2026 18:20:47 +0000

You do not attach a domain, a webhook, or a customer queue to a host you do not own. A free model route and a free server are a lease for a spike, not a runtime you quietly promote. If the lease card is missing, stale, or silent on exit, the change fails closed and the spike stays in quarantine.

That rule is narrower than "the tests are green." A green job can still pass on a box that disappears when an allowance ends or a terms page changes. You are gating ownership and exit. You are not gating the color of CI.

Name the blast radius before you name a tool

You are trying to stop one accident. A teammate prototypes an agent on a borrowed host, the demo works, and someone points real traffic at it because the URL already exists. The host was never promised as production. When the lease ends, you lose the process, the disk, or both, and the rollback is a chat thread.

Treat model headlines the same way. A nickname in a news post is not a pin you can deploy. You re-read the offer page on the day of the cutover, and you store that date in the repo. If you cannot point at the page you read, you do not promote.

Keep the spike. Refuse the binding. Those are different changes, and they should not share a commit.

What you may assume

Two availability claims are enough to run the spike, and nothing more. Free model access exists. A free server option exists.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is one place you can use those two options while you fill out the lease card below. This article does not claim a quota, a hardware shape, a duration, a model catalog, a benchmark, or that the offer stays up.

You copy live fields from the current product page into the card. An empty field is a failed gate, not a guess you fill from memory or from an old chat. If you delete the product name, the gates still apply to any borrowed model route and any borrowed host.

Six gates, each with evidence

Copy this list into the pull request that would attach traffic. Each gate needs an artifact in the repo. A verbal "we checked" does not count.

1. Lease card is present and fresh

Evidence is ops/lease-card.yaml with terms_read_on, allowance_note, host_offer, model_route, and reader. Fail closed if the file is absent, if terms_read_on is outside your window, or if allowance_note is blank.

Do not invent a number to make the field pass. A stale figure is worse than an empty one, because reviewers trust it. Write what you read today, including "I could not find a published allowance" if that is the truth.

2. Model route is an identifier, not a headline

Evidence is a route string that matches the page you read, plus a one-line note of where you read it. Fail closed if the route is latest, free, default, or a name you only saw in a roundup.

You can change the pin later. You cannot promote on a moving nickname. Headlines are topic signals, not deploy config.

3. The borrowed host holds no long-lived secret

Evidence is a secret scan log, or a CI check that denies .env files and cloud keys on that path. Fail closed if customer tokens or deploy keys sit on the host.

A free server is a spike box. It is not a vault. A demo login is still a secret, and it does not belong in a notebook you might share.

4. Data exit is rehearsed

Evidence is a dry-run log that copies prompts, logs, and any user content to a place you own, then deletes the spike copy. Fail closed if the only copy lives on the borrowed disk.

"We can export later" is not a rehearsal. Later is when the disk is already gone. If the drill has not been run, the gate is red even if the demo looks fine.

5. Traffic attachment is a separate change

Evidence is a DNS, webhook, or queue diff in its own pull request, and that request links the lease card. Fail closed if one commit both creates the demo and binds production traffic.

Reviewers cannot see the blast radius in a mixed diff. Split it. The demo can merge on Monday. The binding waits for the card.

6. A person owns rollback, and the kill switch was timed

Evidence is a rollback_owner who is a named person, plus a drill note with a duration. Fail closed if the owner is "the team" or the drill has never been run.

You want a human who can unbind the route without asking who has the password. A rotation alias is not a person. Name someone for this cutover.

The checker you run before review

The script below is a proposal. It uses only the standard library. It does not call a vendor, and it does not know your quota. Run it locally, then wire a non-zero exit to the pull request that binds traffic.

# ops/lease-card.yaml
# Example only. Replace every value after you read the live page.
terms_read_on: "2026-10-10"
reader: "oncall-name"
host_offer: "free-server"
model_route: "pin-from-the-page-you-read"
allowance_note: "copied from the current offer page, not from memory"
data_exit: "rehearsed"
secrets_on_host: "no"
traffic_pr: "separate"
rollback_owner: "sam"
rollback_drill_on: "2026-10-09"

#!/usr/bin/env python3
"""Fail closed unless a borrowed-host lease card is complete and fresh.
Proposal only: stdlib, no network, no vendor client.
"""
from __future__ import annotations

import sys
from datetime import date, datetime
from pathlib import Path

REQUIRED = [
    "terms_read_on",
    "reader",
    "host_offer",
    "model_route",
    "allowance_note",
    "data_exit",
    "secrets_on_host",
    "traffic_pr",
    "rollback_owner",
    "rollback_drill_on",
]
BANNED_ROUTES = {"", "latest", "free", "default", "auto"}
MAX_AGE_DAYS = 7


def parse_flat_yaml(text: str) -> dict[str, str]:
    data: dict[str, str] = {}
    for raw in text.splitlines():
        line = raw.split("#", 1)[0].strip()
        if not line or ":" not in line:
            continue
        key, value = line.split(":", 1)
        data[key.strip()] = value.strip().strip('"').strip("'")
    return data


def age_days(iso_day: str, today: date) -> int:
    parsed = datetime.strptime(iso_day, "%Y-%m-%d").date()
    return (today - parsed).days


def main(path: str) -> int:
    card = parse_flat_yaml(Path(path).read_text(encoding="utf-8"))
    errors: list[str] = []
    for key in REQUIRED:
        if not card.get(key):
            errors.append(f"missing or blank: {key}")
    route = card.get("model_route", "").lower()
    if route in BANNED_ROUTES:
        errors.append("model_route is a nickname, not a pin")
    if card.get("secrets_on_host", "").lower() != "no":
        errors.append("secrets_on_host must be no")
    if card.get("data_exit", "").lower() != "rehearsed":
        errors.append("data_exit must be rehearsed")
    if card.get("traffic_pr", "").lower() != "separate":
        errors.append("traffic attachment must be a separate change")
    owner = card.get("rollback_owner", "").lower()
    if owner in {"", "team", "oncall"}:
        errors.append("rollback_owner must be a named person")
    today = date.today()
    for key in ("terms_read_on", "rollback_drill_on"):
        raw = card.get(key, "")
        if not raw:
            continue
        try:
            delta = age_days(raw, today)
            if delta > MAX_AGE_DAYS or delta < 0:
                errors.append(f"{key} is outside the {MAX_AGE_DAYS}-day window")
        except ValueError:
            errors.append(f"{key} is not YYYY-MM-DD")
    if errors:
        print("FAIL closed:")
        for item in errors:
            print(f"- {item}")
        return 1
    print("PASS: lease card is complete enough to review the traffic PR")
    return 0


if __name__ == "__main__":
    target = sys.argv[1] if len(sys.argv) > 1 else "ops/lease-card.yaml"
    sys.exit(main(target))

python3 ops/check_lease_card.py ops/lease-card.yaml
echo $?

A missing card is not a warning. It is a stop. Do not add a bypass label because the demo is on a call in twenty minutes.

What the drill log must contain

You keep the drill log next to the card, in ops/exit-drill.md. Four lines are enough. Each line is evidence a reviewer can diff.

Start time and end time, in UTC, so the duration is not a vibe.
Source path on the borrowed host, and the destination path you own.
A checksum or file count that matches on both sides before you delete the spike copy.
The command or console step that unbinds DNS, the webhook, or the queue, plus who ran it.

If any line is missing, gate 4 or gate 6 fails. You do not finish the drill in a ticket and leave the proof in a screenshot nobody can diff. A screenshot can support the log. It cannot replace it.

Also record what you refused to copy. Customer payloads that should never have been on the spike box are an incident note, not a successful exit. The checker will not catch that. A human reading the log will, which is why gate 6 names a person.

Review the traffic pull request in this order

Open the lease card. Reject it if terms_read_on is outside your window.
Read allowance_note. If it looks remembered, send the author back to the live offer page.
Diff secrets. The borrowed host path must not gain a key, a token, or a .env.
Read the exit log. A path you own must show the copy, and the spike copy must be deleted in the drill.
Confirm the DNS, webhook, or queue diff is the only production binding in the request.
Require the named rollback owner to acknowledge the pull request.
Run the checker. Non-zero means no merge.

Short requests still get the full list. A small webhook is still production traffic if a customer can hit it.

A small decision table

Situation	Result	What you do
Card fresh, no secrets, exit rehearsed, traffic change is separate	Review may proceed	Attach traffic only behind the kill switch you already timed
Demo works, card blank	Fail closed	Stay in quarantine
Allowance copied from memory or an old post	Fail closed	Re-read the offer page and restamp the date
One commit creates the app and the DNS record	Fail closed	Split the change
Rollback owner is a rotation name	Fail closed	Name a person for this cutover
You need a durability promise the page does not make	Do not use this path	Pick a host whose contract you can cite

Use the table in the pull request comment. Paste the row you matched, and paste the checker output under it. Reviewers should not have to reconstruct your reasoning from a green demo GIF.

Limitations, and who should skip this

This checklist does not make a free server production-grade. It stops you from pretending a spike is a cutover. Skip it for regulated data, long-lived customer secrets, or any workload that needs an uptime promise.

Skip it if nobody will own rollback. A passing script is not a penetration test, a backup proof, or a legal reading of the offer. The 7-day window is a team choice in the proposal, not a vendor rule. Shorten it if the page you depend on changes often.

The checker parses a flat file on purpose so a reviewer can see every failure. It will not understand nested YAML. Keep the card flat. Do not publish quota figures, hardware names, or "unlimited" language in the card. Those claims go stale, and a stale card is how a borrowed host becomes an unowned dependency.

Keep the spike cheap enough to throw away

You can still learn on the borrowed box. Break the prompt. Time your own requests. Write down what failed. Those notes belong in a place you own.

Free model access and a free server are useful because the spike should be cheap enough to discard. Discard only works if exit is rehearsed before the URL leaves the notebook. Cheap is not the same as safe to bind.

If you want a concrete place to try that spike, use MonkeyCode's free model access and free server, copy the current offer into the lease card, and run the checker before any domain change. Stop there until a person reviews the traffic pull request.

Promotion Packets for Agent Branches: Four Gates That Fail Closed

Taylor Zhu — Fri, 09 Oct 2026 14:48:07 +0000

You do not promote an agent branch because it compiles. You promote it only when a fail-closed gate can show four pieces of evidence: a clean workspace record, a secret-clean diff, a human-owned lockfile decision, and a rollback pointer that already exists.

A cheap draft is not a merge. A shared scratch host can carry a leftover env file, a warm package cache, or a prompt from the previous session. Green tests on your laptop do not prove the patch was born clean. Hold the branch until the packet is complete.

The failure you are actually preventing

The interesting bug is not a red test. The interesting bug is a green branch that was born on a borrowed machine.

You asked an assistant to fix a flaky client. It edited three files. CI passed. Nobody asked whether the worktree started clean, whether the patch touched a credential path, or whether a lockfile moved because that host already had a different registry cache.

That gap is a promotion problem, not a model-quality problem. Treat the agent branch as untrusted input. Untrusted input does not get a protected remote until the evidence packet is complete. If a required file is missing, the answer is no. A warning is not a pass.

What you copy, and what you refuse to assume

Copy the gates, the evidence filenames, and the exit codes. Do not copy a quota, a hardware spec, or a permanence claim from outreach copy or from an old post.

This checklist is not a general production-readiness review, and it is not a substitute for code review. It answers one question: may this branch leave the scratch host for the protected remote?

You also do not hard-code a token budget from memory. Plans change. If a number is not on the current product page you opened today, it is not an input to this gate.

Four gates

1. Workspace record

Before the assistant edits anything, record the host and the base. A human wrapper writes this file. The model's final chat message is not evidence.

Require these fields:

host_id: a name you assigned to the scratch machine
started_clean: true only if git status --porcelain was empty
base_sha: the commit you will diff against
recorded_at: an ISO timestamp from that host

No file, no promote. A record that says started_clean: false is also a fail, unless you are in a deliberate dirty spike and a separate human override file exists. Do not flip the boolean by hand to get a green run.

2. Secret-clean diff

List every path in git diff --name-only <base_sha>. Reject the branch if any path hits a denylist.

Start boring:

.env and any .env.*
id_rsa, id_ed25519, *.pem, *.p12
credentials.json and anything under a secrets directory

A filename check is a tripwire, not a secret scanner. Keep the scanner you already trust. Do not let the tripwire be the only control, and do not let a missing scanner become a silent pass. Missing evidence fails closed.

3. Lockfile decision

If the diff touches a lockfile, a human owns that change in writing.

Watch the usual names: package-lock.json, pnpm-lock.yaml, yarn.lock, poetry.lock, uv.lock, Pipfile.lock, go.sum, Cargo.lock, and Gemfile.lock.

An assistant on a scratch host will often regenerate these from whatever index that host can see. That is how you ship a different tree than the one your team reviewed. If none of those names changed, this gate passes. If any changed, require evidence/lockfile-decision.json with human_owner, reason, and the same base_sha. An empty reason is a fail.

4. Rollback pointer

Create the rollback pointer before you push, not after the incident channel opens.

evidence/rollback.txt holds one rev the team already knows: a tag or a full SHA. The checker runs git rev-parse --verify on it. An empty file, or a rev this clone cannot resolve, stops the push.

You are not proving the rollback will be painless. You are proving you named a known rev before the new branch moved. If your remote deletes tags, add a remote check you control. Local resolution alone is not a remote guarantee.

Decision table

Use this as the review card. Do not negotiate it in the moment.

Evidence	Valid	Missing or false	Action
Workspace record, clean start	Pass	Fail	Stop. Recreate the worktree.
Denylist against diff paths	No hits	Any hit	Stop. Remove the secret path from the branch.
Lockfile decision	Present if lockfiles changed	Changed, no owner	Stop. Revert the lockfile or get a human owner.
Rollback rev	Resolves in this clone	Empty or unknown	Stop. Tag or record the base first.
Checker process	Exit 0	Exit 2, crash, or skip	Do not push. A skipped checker is a fail.

Fail closed means a non-zero exit. A crashed checker is a failed promotion, not an exception you ignore because the diff looks small.

The promotion sequence

Run the steps in order. Skipping a step to save time is how the packet rots.

Clone onto a disposable worktree. Confirm git status --porcelain is empty.
Write evidence/workspace.json and evidence/rollback.txt from the base SHA.
Let the assistant edit only that worktree. Keep protected-remote credentials off the scratch host.
Diff against base_sha. If a lockfile moved, add a human decision file or revert it.
Run the checker. Exit 0 is necessary, not sufficient. A human still reads the diff.
Push only from a machine that is allowed to hold the protected remote.

A checker you can copy

The script below is an unexecuted example. It is not a benchmark, and it is not a log from a run on your repo. Read it, then point it at a scratch clone. The intended contract is simple: missing evidence prints FAIL and exits 2. That is how the branches are written. It is not a captured measurement.

#!/usr/bin/env python3
"""Fail-closed promotion gate. Unexecuted example. Exit 0 only if evidence holds."""
import json, subprocess, sys
from pathlib import Path

ROOT = Path(".").resolve()
EVID = ROOT / "evidence"
DENY_NAMES = {".env", "id_rsa", "id_ed25519", "credentials.json"}
DENY_SUFFIXES = (".pem", ".p12")
LOCKS = {
    "package-lock.json", "pnpm-lock.yaml", "yarn.lock",
    "poetry.lock", "uv.lock", "Pipfile.lock",
    "go.sum", "Cargo.lock", "Gemfile.lock",
}

def fail(msg: str) -> None:
    print(f"FAIL: {msg}", file=sys.stderr)
    sys.exit(2)

def git(*args: str) -> str:
    proc = subprocess.run(["git", *args], cwd=ROOT, text=True, capture_output=True)
    if proc.returncode != 0:
        fail("git " + " ".join(args) + ": " + proc.stderr.strip())
    return proc.stdout.strip()

def denied(path: str) -> bool:
    name = Path(path).name
    if name in DENY_NAMES or name.startswith(".env"):
        return True
    if name.endswith(DENY_SUFFIXES):
        return True
    return "secrets" in Path(path).parts

def main() -> None:
    record_path = EVID / "workspace.json"
    if not record_path.is_file():
        fail("missing evidence/workspace.json")
    record = json.loads(record_path.read_text())
    for key in ("host_id", "started_clean", "base_sha", "recorded_at"):
        if key not in record:
            fail("workspace.json missing " + key)
    if record["started_clean"] is not True:
        fail("workspace did not start clean")
    base = str(record["base_sha"])
    git("rev-parse", "--verify", base)

    paths = [p for p in git("diff", "--name-only", base).splitlines() if p]
    hits = [p for p in paths if denied(p)]
    if hits:
        fail("denylist paths in diff: " + ", ".join(hits))

    lock_hits = [p for p in paths if Path(p).name in LOCKS]
    if lock_hits:
        decision_path = EVID / "lockfile-decision.json"
        if not decision_path.is_file():
            fail("lockfile changed with no lockfile-decision.json")
        decision = json.loads(decision_path.read_text())
        if not decision.get("human_owner") or not decision.get("reason"):
            fail("lockfile decision needs human_owner and reason")
        if decision.get("base_sha") != base:
            fail("lockfile decision base_sha does not match workspace")

    rollback_path = EVID / "rollback.txt"
    if not rollback_path.is_file():
        fail("missing evidence/rollback.txt")
    rev = rollback_path.read_text().strip()
    if not rev:
        fail("rollback.txt is empty")
    git("rev-parse", "--verify", rev)
    print("PASS: promotion evidence holds for", record["host_id"])

if __name__ == "__main__":
    main()

Collect the packet before the assistant edits, then run the checker before any push:

mkdir -p evidence
if [ -z "$(git status --porcelain)" ]; then clean=true; else clean=false; fi
sha=$(git rev-parse HEAD)
stamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
cat > evidence/workspace.json <<EOF
{
  "host_id": "scratch-host-a",
  "started_clean": ${clean},
  "base_sha": "${sha}",
  "recorded_at": "${stamp}"
}
EOF
printf '%s\n' "$sha" > evidence/rollback.txt
python3 promote_gate.py

If started_clean is false, fix the worktree. Do not edit the JSON to force a pass. Break the gates on purpose once: delete rollback.txt, touch a lockfile, add a fake .env. You want exit code 2 each time, before you trust the script enough to put it next to an assistant.

Where a free model and a free server fit

Use the cheap workspace for the draft. Do not treat it as the source of truth.

MonkeyCode offers free model access and a free server option you can use to try this gate on a scratch branch. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Those two availability claims were supplied for this draft. They are not a model list, a token quota, a hardware spec, a duration, or a promise that the offer stays fixed. This article deliberately does not state a token figure, because no primary plan page was attached and an old number would be the wrong kind of evidence. Open the current docs and confirm limits before you depend on them.

The free server is a reasonable place to run promote_gate.py against a disposable clone. It is a bad place to store long-lived credentials, production remotes, or the only copy of a rollback tag. Keep protected-remote credentials off that host. Push only after the checker exits 0 and a human has read the diff.

If you delete every product name from this page, the gate still stands. The product is a convenient scratch host, not the evidence.

Limitations

The denylist misses secrets pasted into ordinary source files. Pair it with a scanner you already trust.
git rev-parse proves the rev exists in this clone. It does not prove the remote still has it.
A human name in JSON is not an approval system. If you need SSO-backed review, use your forge's pull request rules. This file is a local tripwire.
Clock skew can make recorded_at look fresh on a drifted host. Do not treat the timestamp as a legal audit log.
The script matches lockfiles by basename. A rename that hides a lockfile under a new path needs a human look.
Fail-closed scripts fail open the day someone aliases them to true. Pin the command in CI, or do not pretend you have the gate.

Who should not use this

Skip the checker if the spike will be deleted the same day and will never be pushed. Also skip it if your platform already blocks secret files, lockfile drift, and unsigned pushes with controls you have tested. A second local script will not make a mature control plane safer.

Do not park customer data, production keys, or regulated traces on a free shared server because the draft was cheap. This checklist assumes the scratch host is disposable and untrusted. If that assumption is false, stop and use an isolated runner your security team already accepts.

One next step

Pick one repo you already maintain. Add the checker on a branch that has no assistant in it. Break each gate on purpose and confirm exit code 2. Only then point an assistant at a scratch clone.

If you want that clone on a disposable host, MonkeyCode's free server option is enough to start, after you read the current limits yourself. Leave the protected remote for the machine that passed the gate.