DEV Community: Taylor Wang

The Bug That Only Existed on My Laptop: Why I Keep a Boring Baseline Server Now

Taylor Wang — Thu, 13 Aug 2026 02:34:20 +0000

The most expensive bug I chased this year took three evenings, and the fix was deleting nothing and changing nothing. The code was correct. My laptop was lying.

The symptom: a small data-export script that produced a subtly wrong CSV — a handful of rows out of order, only on Fridays, only in the evening. The script hadn't changed in months. The tests passed. The logic was obviously right when I read it. I added logging, then more logging, then started doubting the timezone handling, the database driver, and eventually myself.

The actual cause was embarrassingly dull. The script read a directory of daily export files and sorted them by name. My laptop's locale had been switched during a language experiment weeks earlier, and string collation changed just enough that two filename prefixes ordered differently after 6 PM, when a second daily file appeared and the sort actually mattered. Fridays were when I ran the export late. Three variables I never thought to check — locale, timing, file count — combined into a heisenbug that could not exist on any other machine I had access to.

This post is the postmortem I wish someone had handed me: how environment drift creates bugs that are invisible to code review, the fingerprint script I now run to detect it, and why I keep one deliberately boring server around as a baseline.

Localhost is a snowflake and nobody documents it

We talk a lot about dev/prod parity, but most solo devs have a quieter problem: laptop/laptop parity over time. Your machine today is not your machine from three months ago. OS updates change default tools. You install a database for one project and it grabs a port another project expects. You tweak an environment variable in a shell session, forget it, and it's gone after reboot — taking some behavior with it.

Code review can't catch any of this, because the code isn't wrong. Version control can't catch it, because nothing was committed. The drift lives in the gap between what your repository says and what your machine actually is.

My rule now: anything that runs unattended or produces output I rely on gets a fingerprint recorded alongside the output, so when something looks wrong I can diff the environments before I diff the code.

The fingerprint script

This is the actual artifact. It's a small shell script that snapshots everything that has ever caused me a drift bug, and writes it next to whatever the job produces:

#!/usr/bin/env bash
# env_fingerprint.sh — snapshot the environment alongside a job's output.
# Usage: ./env_fingerprint.sh > output/fingerprint_$(date +%F).txt

{
  echo "=== date ===";            date -u; date
  echo "=== locale ===";          locale
  echo "=== timezone ===";        cat /etc/timezone 2>/dev/null || true
  echo "=== shell ===";           echo "$SHELL  $BASH_VERSION"
  echo "=== os ===";              uname -a
  echo "=== key tool versions ==="
  for t in python3 node psql sqlite3 git; do
    command -v "$t" >/dev/null && { printf "%s: " "$t"; "$t" --version 2>&1 | head -1; }
  done
  echo "=== relevant env vars ==="
  env | grep -Ei '^(LC_|LANG|TZ|PATH|.*_HOME)' | sort
  echo "=== disk / memory ===";   df -h . | tail -1; free -h 2>/dev/null | head -2
} 2>&1

The workflow around it matters more than the script:

Every scheduled job writes a fingerprint into its output folder before running.
When output looks wrong, my first move is diff between the fingerprint of a good run and the bad run — not the source code.
Only if the fingerprints are identical do I start reading code.

This reordered my debugging. Environment diff first, code diff second. In the Friday-CSV case, step 2 would have surfaced LC_COLLATE changing between runs in about ninety seconds, instead of three evenings.

Why the baseline is a server, not a second laptop

Fingerprints tell you that something drifted, but they're even more useful when you have one machine that deliberately doesn't drift. I keep a single low-spec server whose entire personality is boredom: default locale, UTC, minimal packages, nothing installed unless a job needs it. Every job that matters runs there on a schedule. My laptop is where I experiment; the server is where truth lives.

For this I used the free server option from MonkeyCode, which also includes free model access. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The model access has been incidentally useful for one specific step in this workflow: pasting a pair of before/after fingerprints and asking for a hypothesis about which diff lines could plausibly affect a given symptom. It's a decent triage accelerator for exactly this kind of "twelve lines changed, which two matter?" problem. Two honest caveats: I can't speak to quotas, hardware specs, or how long the free options remain available — verify current terms before depending on them — and any baseline machine works for the core idea, including a $5 VPS, a Raspberry Pi, or an old laptop in a closet. The value is in the discipline, not the vendor.

When the baseline catches things — and when it can't

The laptop/server split pays off most in a specific band of situations:

Symptom pattern	Baseline helps?	Why
Works interactively, breaks on schedule	Yes	Scheduling strips your interactive env (PATH, SSH agent, locale)
Output differs between runs, same code	Yes	Fingerprint diff isolates the drift variable
Bug reproduces everywhere consistently	No	That's a code bug; go read the code
Concurrency / load-dependent failure	Rarely	A quiet single-tenant baseline won't reproduce it
"Works on my machine" in a team	Partially	You need shared infra, not a personal baseline

Limitations worth stating plainly. A baseline server doesn't help with anything that only manifests under real traffic or real data volume. It adds one more machine to patch and secure — an unmaintained baseline is worse than none, because it gives false confidence. And if your actual production environment is a container fleet, a single plain VM is a weak stand-in; your baseline should mirror production's shape, which for some teams means a staging namespace instead.

If you're a solo dev whose "production" is a handful of scripts and cron jobs, though, you're probably in the sweet spot.

The takeaway I'd tattoo on my terminal

When a bug makes no sense, stop asking "what's wrong with this code?" and ask "what's different about where it ran?" Record a fingerprint, keep one machine boring on purpose, and diff environments before you diff logic.

If you've got your own laptop-only bug story — the kind that dissolved the moment you looked at the environment instead of the code — I'd love to read it in the comments. Those stories are how the rest of us calibrate what to fingerprint next.

I Moved My Discord Bot Off a Paid LLM API. Five Things Broke.

Taylor Wang — Wed, 12 Aug 2026 23:16:05 +0000

My Discord bot has one job: when someone pastes a stack trace into our server's #help channel, it rewrites the trace into a plain-English explanation plus a likely fix. It ran for months on a paid LLM API at a few dollars a month — small money, but the kind that nags you when the workload is trivially bursty: silent for days, then thirty requests in an evening when a game update breaks everyone's mods.

So I pointed it at a free endpoint instead. The migration took an afternoon. The consequences of the migration took two weeks to fully shake out, because nothing failed loudly. Everything failed slightly. This is a log of the five things that broke, what each one taught me about provider portability, and the wrapper code that now sits between my bot and any LLM endpoint so I never have to debug these twice.

The endpoint I moved to is MonkeyCode, which offers free model access and a free server option — the right price shape for a hobby bot with spiky traffic. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Every failure below, though, is generic to switching OpenAI-compatible providers. I verified that by deliberately reproducing two of them against a second endpoint. Treat this as a portability field report, not a product review.

Break 1: The model name was a lie I told myself

My config had the model name hardcoded in three places: the request builder, the logging line, and a cost-estimation function that divided tokens by a per-model price. When I swapped providers, I updated one of the three. The bot ran fine — and my logs confidently recorded the old model name for a week, which made every later debugging session confusing because I was reading telemetry for a model I wasn't using.

Fix: model identity is configuration, not code, and it flows from exactly one source.

# llm_config.py — single source of truth
from dataclasses import dataclass
import os

@dataclass(frozen=True)
class LLMConfig:
    base_url: str
    api_key: str
    model: str          # whatever the CURRENT provider's catalog calls it
    max_output_tokens: int
    timeout_s: float

def load_config() -> LLMConfig:
    return LLMConfig(
        base_url=os.environ["LLM_BASE_URL"],
        api_key=os.environ["LLM_API_KEY"],
        model=os.environ["LLM_MODEL"],
        max_output_tokens=int(os.environ.get("LLM_MAX_OUTPUT", "600")),
        timeout_s=float(os.environ.get("LLM_TIMEOUT_S", "20")),
    )

Boring, obvious, and the root cause of the messiest week. A related trap: never assume a model name means the same thing across providers, or even across months on the same provider. Catalogs change. Check what your endpoint actually serves before writing it into an environment variable, and expect to change it again.

Break 2: Rate limits arrived as success-shaped failures

On the paid API, I had never once seen a 429. On a free tier, the evening burst pattern hit the limit within the first weekend. The truly bad part: my error handler treated non-200 responses as "log and move on," so during peak hours the bot silently ignored half the stack traces posted. Users thought it was ignoring them specifically and reposted, which made the burst worse. A rate limit had become a feedback loop.

Fix: bounded retries with jittered backoff, and — critically — a visible degraded state.

# llm_call.py — retry wrapper with honest degradation
import asyncio
import random
import openai

MAX_ATTEMPTS = 4

async def call_with_backoff(client, cfg, messages) -> str | None:
    for attempt in range(MAX_ATTEMPTS):
        try:
            resp = await asyncio.to_thread(
                client.chat.completions.create,
                model=cfg.model,
                messages=messages,
                temperature=0.2,
                max_tokens=cfg.max_output_tokens,
                timeout=cfg.timeout_s,
            )
            return resp.choices[0].message.content
        except openai.RateLimitError:
            if attempt == MAX_ATTEMPTS - 1:
                return None  # caller must say so out loud
            base = min(2 ** attempt, 8)
            await asyncio.sleep(base + random.uniform(0, base))
        except openai.APITimeoutError:
            return None  # a slow answer in a chat channel is a wrong answer
    return None

async def explain_trace(client, cfg, trace: str) -> str:
    result = await call_with_backoff(client, cfg, [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": trace},
    ])
    if result is None:
        return ("⚠️ I'm rate-limited right now. Try again in a minute, "
                "or trim the trace to the first error line — shorter "
                "messages are more likely to get through.")
    return result

The degraded message does two jobs: it resets user expectations, and it gives them an actionable workaround (shorter input). Silence is the worst possible response to a rate limit in an interactive product.

Break 3: Context length differences truncated my prompts mid-word

The old setup had headroom I never measured, so my prompt builder happily concatenated the system prompt, the full stack trace, and the last five channel messages for context. On the new model, long traces started returning explanations of the wrong error — because the actual exception line, at the end of the paste, had been truncated away by the context window.

No exception was raised. The model just answered a different question than the user asked. This is the nastiest class of provider-migration bug: output stays plausible while becoming wrong.

Fix: budget tokens explicitly and truncate deliberately, keeping the semantically important part. For stack traces, the important part is the last exception block, not the first frames:

def trim_trace(trace: str, char_budget: int) -> str:
    """Keep the tail of the trace: the exception line matters most."""
    if len(trace) <= char_budget:
        return trace
    head_room = char_budget // 4
    tail = trace[-(char_budget - head_room):]
    # don't cut mid-line; align to a newline
    nl = tail.find("\n")
    if 0 < nl < 200:
        tail = tail[nl + 1:]
    return trace[:head_room] + "\n[...middle frames omitted...]\n" + tail

Character budgets are a crude proxy for tokens, but a 4:1 char-to-token estimate with a safety margin beats not thinking about it at all. The general principle: after any provider switch, find your longest realistic input and verify end-to-end what the model actually receives.

Break 4: Streaming behaved differently, so I stopped streaming

The bot edits its own Discord message progressively as tokens arrive — a nice touch that made it feel fast. The new endpoint delivered chunks on a different cadence: larger, less frequent batches. The visual result was a message that sat empty for seconds, then jumped. Worse, my progressive-edit logic issued a Discord API edit per chunk, and the chunkier cadence interacted badly with Discord's own rate limits on message edits.

Fix: I removed streaming for this use case. Deliberate regression, correct call. For a chat bot whose answers are a few hundred tokens, perceived speed comes more from a fast first reaction than from progressive rendering. The bot now posts "🔎 reading the trace…" immediately (a fast, guaranteed reaction), then replaces it with the full answer in one edit. Users rated it as feeling faster than the stuttering stream. The lesson generalizes: provider features that seem free — streaming, JSON modes, tool calling — are exactly where behavioral differences hide, because they're the least standardized parts of an API that is otherwise deliberately compatible.

Break 5: My health check checked the wrong thing

I had an uptime monitor hitting the endpoint's root URL. It stayed green through every incident above, because the server was always up; it was the model path that rate-limited, truncated, or lagged. A TCP-level health check for an LLM-backed feature is close to useless.

Fix: a synthetic probe that exercises the real path, run on a schedule, alerting on latency and content sanity:

async def synthetic_probe(client, cfg) -> dict:
    start = asyncio.get_event_loop().time()
    result = await call_with_backoff(client, cfg, [
        {"role": "user", "content":
         "Reply with exactly: PROBE_OK"},
    ])
    elapsed = asyncio.get_event_loop().time() - start
    return {
        "ok": result is not None and "PROBE_OK" in result,
        "latency_s": round(elapsed, 2),
    }

Two weeks of probe data also gave me something I never had on the paid API: an honest picture of the free tier's behavior under my real traffic pattern — when bursts collide with limits, what p50 latency actually feels like. If you run one thing from this article, run the probe. It converts "the free tier seems flaky" into data you can act on.

What I'd tell anyone doing the same migration

The switch was worth it: the bot's operating cost for this workload went to zero, and every failure above was a latent bug in my code that the paid tier's headroom had been papering over. Free capacity is unforgiving in a useful way.

But be honest about the fit:

Good candidates: bursty hobby tools, bots, personal automations, internal utilities — workloads where a retry and a polite degraded message are acceptable, and where request volume would otherwise generate a real bill.
Bad candidates: anything with a latency SLA, user-facing flows where a failed call breaks a purchase or signup, and workloads with steady high volume that will live permanently against rate limits. If your traffic graph is a flat line, a free tier is not your production plan; it's your development environment.
Either way: build the portability wrapper first — single-source config, backoff with visible degradation, deliberate truncation, a synthetic probe — and the choice of provider becomes a config change you can revisit quarterly instead of a commitment.

If you want a concrete place to try this, MonkeyCode's free model access and free server option are what this bot currently runs on; the wrapper above means it could run somewhere else tomorrow, which is precisely the property worth engineering for. The migration took an afternoon. The engineering to make the next migration boring took two weeks — and it's the part that was actually worth doing.

Reserve the Expensive Model for Thinking: A Free-Tier Pipeline for Git Chores

Taylor Wang — Wed, 12 Aug 2026 16:40:44 +0000

There's a strange pattern in how most of us use AI coding tools. We'll happily burn premium-model tokens writing a commit message — a task whose failure mode is "slightly awkward wording" — and then cheap out on the one prompt where a mistake costs us a production incident.

I did the opposite experiment for a month: I routed every low-stakes, high-frequency writing chore in my git workflow to free-tier models, and saved the expensive calls exclusively for work where being wrong actually hurts. The surprise wasn't that it saved money. It was that the chores got better, because I stopped doing them by hand at 6pm when my patience was gone.

This article is the setup: which chores qualify, the scripts, and the routing rule that keeps it honest.

The qualification test: reversible, verifiable, boring

Not everything belongs on the free tier. A chore qualifies only if it passes all three checks:

Check	Question	Example pass	Example fail
Reversible	Can I undo a bad output in seconds?	Commit message draft	Migration script
Verifiable	Can I glance at it and know if it's wrong?	PR description summary	Regex for log parsing edge cases
Boring	Do I currently do it badly because it's tedious?	Changelog entries	Architecture decisions

Three chores passed cleanly for me: commit message drafts, PR description scaffolding, and first-pass log triage. Notice what they share — a human reviews every one before it matters. The model isn't making decisions; it's removing the blank page.

Chore 1: Commit messages as a prepare-commit-msg hook

The prepare-commit-msg hook fires before your editor opens and pre-fills the message. Instead of a blank buffer, you get a draft you edit or delete:

#!/bin/sh
# .git/hooks/prepare-commit-msg
COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2

# Skip merges, squashes, and commits that already have a message
[ -n "$COMMIT_SOURCE" ] && exit 0

DIFF=$(git diff --cached --stat && git diff --cached | head -c 6000)
[ -z "$DIFF" ] && exit 0

DRAFT=$(mc-query "Write a conventional-commit style message for this diff.
Subject line under 72 chars, imperative mood, then a blank line and
a 2-3 sentence body explaining WHY, not what. Output only the message.

$DIFF")

if [ -n "$DRAFT" ]; then
  echo "$DRAFT" > "$COMMIT_MSG_FILE"
fi

Here mc-query is a thin wrapper around whatever model endpoint you're using. Disclosure: This article was prepared as part of MonkeyCode's product outreach. In my case that wrapper points at MonkeyCode, whose free model access is what makes a hook like this psychologically sustainable — a commit hook fires on every commit, and I'd disable it within a week if each one had a meter attached. I run the wrapper against their free server option so the hook also works from a scratch VM or a CI runner without me copying credentials around.

The key design choice: the hook writes a draft into your editor, never a final message. You still read it. Most days I change two words; some days I delete it and write my own. Both outcomes are fine — the cost of a wrong draft is one keystroke.

Chore 2: PR descriptions from the branch, not from memory

The commit hook handles single commits; PRs need the whole branch. This script diffs against the base branch and produces a skeleton with the sections my team actually uses:

#!/usr/bin/env bash
# pr-draft.sh — run from your feature branch
BASE=${1:-main}

CONTEXT=$(git log --oneline $BASE..HEAD; echo '---'; git diff $BASE...HEAD | head -c 8000)

mc-query "Draft a PR description with exactly these sections:
## What changes (bullet list, one line each)
## Why (2-3 sentences)
## How to verify (numbered steps a reviewer can run)
## Risks (be specific; write 'none identified' only if true)
Base it only on the commits and diff below. Do not invent ticket numbers.

$CONTEXT" > pr-draft.md

The "How to verify" section is where this earns its keep. I used to write "tested locally" and move on. Now the draft forces concrete steps, and even when the model's steps are slightly off, correcting them takes thirty seconds and the reviewer gets something runnable.

One guardrail baked into the prompt: "Do not invent ticket numbers." Free models will cheerfully fabricate a plausible-looking PROJ-1234. Any placeholder in your team's conventions deserves the same explicit prohibition.

Chore 3: Log triage as a filter, not a verdict

When a deploy misbehaves, the first hour is usually scrolling. This one-liner classifies log lines into buckets so you scroll less:

journalctl -u myapp --since "1 hour ago" \
  | grep -iE 'error|warn|exception' \
  | head -200 \
  | mc-query "Group these log lines by probable root cause.
For each group: a one-line hypothesis, a count, and the first timestamp.
Mark anything you are unsure about with [?]. Do not suggest fixes yet."

Two deliberate constraints here. First, head -200: this is a triage filter, and if 200 lines don't reveal the shape of the problem, the answer is in metrics or traces anyway, not more log. Second, "Do not suggest fixes yet" — unconstrained, the model jumps to confident remediation advice, and triage is exactly the moment you're most suggestible. Get the grouping first; decide the fix yourself.

The routing rule that keeps it honest

After a month, my split looks like this:

Free tier: commit drafts, PR skeletons, log grouping, renaming things, writing throwaway scripts, "what does this error mean" lookups.
Paid calls only: changes that touch money, data, or auth; anything I can't fully review in under five minutes; anything where a wrong answer is worse than no answer.

The rule isn't "free for small tasks" — it's "free for tasks where review is cheap and reversal is cheaper." A ten-line change to a billing calculation is small but stays on the paid tier. A 200-line PR description is large but stays free, because I'll read every word before it ships.

Where this breaks down

Be honest about the limits before copying this setup:

Review discipline is load-bearing. The moment you start accepting commit drafts without reading them, the chore automation becomes a slow leak of nonsense into your history. If your team has a rubber-stamp culture, fix that first.
Diffs leave your machine. The hook sends staged diffs to an external endpoint. If your code can't leave your perimeter, this whole article is moot — use a local model or nothing.
Free tiers are not an SLA. Free model access and free servers can be rate-limited, deprioritized, or discontinued. Every script above fails silently to manual behavior (exit 0, empty draft) precisely so a bad day on the free tier means a blank commit editor, not a blocked workflow. Build that escape hatch into whatever you write.
This is not for low-commit-frequency work. If you commit twice a week, the hook saves you nothing and adds a dependency. The payoff scales with chore frequency.

What I actually learned

The interesting result wasn't cost. It was consistency: my commit history got noticeably more uniform, PR descriptions stopped being afterthoughts, and the 6pm version of me no longer writes "fix stuff" as a message. Cheap models on boring tasks beat good intentions, because they show up every time.

If you want to try the routing split without a billing dashboard watching every experiment, MonkeyCode's free models and free server are a low-commitment place to point the mc-query wrapper — the scripts above don't care what's behind it, so swap the backend whenever your needs outgrow the free tier.

Make AI Patches Prove Themselves Before They Touch Main

Taylor Wang — Wed, 12 Aug 2026 13:24:36 +0000

A lot of teams have quietly moved from “Can AI write code?” to a more uncomfortable question: “What do we do with the code it writes?” The risky part is not that a model sometimes produces a bad diff. The risky part is that a fluent diff can look reviewable before it has earned trust. It names plausible functions, imitates local style, and may even include comments that sound like intent. If your process treats that as a pull request, you have outsourced the easiest step and kept the hardest one.

This article lays out a patch gate you can run before an AI-assisted change is allowed to become a real branch. It is written for a small team, a solo maintainer, or anyone who wants a faster loop without pretending that generated code is automatically correct. I am not assuming a specific stack. The example below is Python-shaped because it is readable, but the same gate works for Node, Go, Rust, or infrastructure config if you swap the check commands.

The core idea: separate generation from admission. Generation can happen anywhere. Admission should be boring, deterministic, and hard to talk your way through.

The failure mode to design around

The common failure is not “AI writes syntax errors.” Modern assistants usually clear that bar. The more expensive failures are semantic drift, hidden environment assumptions, and confident edits outside the requested blast radius.

Semantic drift means the code still runs but solves a nearby problem. A caching helper caches errors forever. A retry wrapper retries non-idempotent POSTs. A migration adds the column but loses the backfill path. Hidden environment assumptions are worse in generated code because models love convenience: localhost URLs, a file path that exists on the prompt author’s machine, a package version from memory, a shell tool that is present in a demo image but not production. Blast-radius creep is the quietest: you asked for a validator tweak and received a “cleanup” touching logging, dependency pins, and two tests.

A good gate does not ask, “Does this look smart?” It asks, “What did the diff change, what did it refuse to change, what breaks first, and can a stranger rerun the evidence?”

A three-lane admission gate

Use three lanes. Keep them small enough that people actually run them.

Lane 1: mechanical truth. Formatting, type checks, unit tests, dependency audit, secret scan, license headers if you have them. No model judgment is allowed here. If pytest, ruff, mypy, npm test, or go test fails, the patch is not “almost ready.” It is rejected until the generator or a human fixes it.

Lane 2: contract review. The patch must include a short contract note written by the human requester, not the model: intended behavior, explicit non-goals, files allowed to change, commands used to verify, and rollback expectation. This prevents the assistant from defining the task after seeing its own output.

Lane 3: adversarial sandbox. Run the patch in a disposable environment with seed data, then ask a separate review prompt to attack it: find misuse cases, boundary inputs, concurrency hazards, unsafe defaults, and missing telemetry. Treat the reviewer output as leads, not verdicts. Any claimed bug must be reproducible by a command or test before it blocks merge; otherwise it goes into a follow-up note.

This is where free model access can be useful without becoming a load-bearing dependency. A team can reserve paid or private capacity for production-sensitive work while using a no-cost sandbox lane for throwaway review passes on non-secret code. Disclosure: This article was prepared as part of MonkeyCode's product outreach. In this workflow, MonkeyCode is relevant only if your operator confirms that its free model access and free server option fit your compliance needs; treat both as availability claims to verify in current account settings, not as quotas, permanence, hardware guarantees, or benchmark results.

The important rule: free capacity is for trials and criticism, not for secrets, customer data, or unreleased security mitigations.

Artifact: a patch-gate scaffold

The following is a scaffold, not a benchmark and not a claim that I ran it against your repository. It assumes a Git checkout, a patch file, and a safe temporary worktree. Replace the bracketed commands with your own.

#!/usr/bin/env python3
# ai_patch_gate.py - scaffold; adapt commands before trusting it.
import os, re, shlex, subprocess, sys, tempfile
from pathlib import Path

REPO = Path(os.environ.get("REPO", ".")).resolve()
PATCH = Path(os.environ["PATCH_FILE"]).resolve()
CONTRACT = Path(os.environ["CONTRACT_FILE"]).resolve()

SECRET_RE = re.compile(r"(?i)(api[_-]?key|secret|token|password)\s*[:=]\s*['\"][^'\"]{8,}")
ALLOWED = set()

def run(cmd, cwd=REPO, timeout=300):
    p = subprocess.run(shlex.split(cmd), cwd=cwd, text=True,
                       stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=timeout)
    return p.returncode, p.stdout

def fail(stage, out):
    print(f"\n[GATE FAIL] {stage}\n{out[-4000:]}")
    sys.exit(1)

def parse_contract():
    text = CONTRACT.read_text(encoding="utf-8")
    for line in text.splitlines():
        if line.startswith("allowed-path:"):
            ALLOWED.add(line.split(":", 1)[1].strip())
    required = ["intent:", "non-goals:", "verify:", "rollback:"]
    missing = [k for k in required if k not in text]
    if missing:
        fail("contract", f"missing keys: {missing}")
    if not ALLOWED:
        fail("contract", "no allowed-path entries")

def apply_in_worktree():
    tmp = Path(tempfile.mkdtemp(prefix="patch-gate-"))
    code, out = run(f"git worktree add {shlex.quote(str(tmp))} HEAD")
    if code: fail("worktree", out)
    code, out = run(f"git apply --check {shlex.quote(str(PATCH))}", cwd=tmp)
    if code: fail("patch-check", out)
    code, out = run(f"git apply {shlex.quote(str(PATCH))}", cwd=tmp)
    if code: fail("patch-apply", out)
    return tmp

def check_blast_radius(wt):
    code, out = run("git diff --name-only HEAD", cwd=wt)
    if code: fail("diff", out)
    changed = [x for x in out.splitlines() if x.strip()]
    bad = [p for p in changed if not any(p.startswith(a) for a in ALLOWED)]
    if bad:
        fail("blast-radius", "changed outside allowed paths:\n" + "\n".join(bad))
    joined = "\n".join((wt / p).read_text(encoding="utf-8", errors="ignore")
                       for p in changed if (wt / p).is_file())
    if SECRET_RE.search(joined):
        fail("secret-scan", "possible hardcoded credential in changed files")
    return changed

def mechanical(wt):
    for cmd in [
        os.environ.get("FMT_CMD", "true"),
        os.environ.get("LINT_CMD", "true"),
        os.environ.get("TEST_CMD", "pytest -q"),
    ]:
        if cmd == "true":
            continue
        code, out = run(cmd, cwd=wt, timeout=int(os.environ.get("CMD_TIMEOUT", "900")))
        if code: fail(cmd, out)

def review_packet(wt, changed):
    diff = subprocess.run(["git", "diff", "HEAD"], cwd=wt, text=True,
                          stdout=subprocess.PIPE).stdout
    prompt = f"""You are a hostile reviewer. Do not rewrite the patch.
List only concrete defects with reproduction ideas. If none, say NONE.
Context contract:\n{CONTRACT.read_text(encoding='utf-8')}
Changed files: {changed}\nDiff:\n{diff[:24000]}
"""
    out = Path("review-prompt.txt")
    out.write_text(prompt, encoding="utf-8")
    print(f"[GATE INFO] wrote {out}; send only non-secret code to your reviewer endpoint.")
    print("[GATE INFO] set REVIEW_ENDPOINT if you wire this to a free sandbox server.")

if __name__ == "__main__":
    parse_contract()
    wt = apply_in_worktree()
    changed = check_blast_radius(wt)
    mechanical(wt)
    review_packet(wt, changed)
    print("[GATE PASS] mechanical lanes passed; human still owns merge.")

Example contract file:

intent: reject empty coupon codes before checkout totals are computed
non-goals: no pricing redesign, no logging changes, no dependency updates
allowed-path: app/checkout/
allowed-path: tests/checkout/
verify: pytest -q tests/checkout; ruff check app/checkout
rollback: revert single commit; no database migration

Run shape:

PATCH_FILE=coupon.diff CONTRACT_FILE=coupon.contract \
LINT_CMD="ruff check app/checkout" TEST_CMD="pytest -q tests/checkout" \
python3 ai_patch_gate.py

If you connect the review packet to a hosted assistant, make the endpoint an environment variable and keep the packet redacted. A free server can be a reasonable place for disposable review of public or synthetic code when your operator has confirmed that use is permitted; it is not automatically a place for proprietary diffs. Do not infer retention, isolation, region, rate limits, or model identity from the word “free.” Put those in your team’s threat model and verify them before use.

Decision table: where free capacity helps and where it does not

Situation	Use a free sandbox lane?	Why
Synthetic bug reproduction with fake data	Yes, if terms allow	Low sensitivity, high iteration value
Public OSS patch before maintainers review	Often yes	Diff is already public; checks still local
Private repo with customer identifiers	No	Redaction is fragile; one paste can leak
Security fix under embargo	No	Disclosure risk outweighs convenience
Regulated data or signed DPA required	Only after legal approval	“Free” is not a compliance boundary
Final release gate	No	Admission should depend on reproducible checks, not a service you cannot audit

The prompt contract matters more than the model

Most teams spend energy choosing a model and almost none constraining the task. A tiny contract prevents a large class of arguments. Require three things before generation: the exact acceptance test, the forbidden files, and the evidence format. After generation, require the model to output a diff plus a self-critique, then discard the self-critique unless it names a reproducible command.

A useful review prompt is not “Is this good?” It is: “Given this contract and diff, list only ways to make the stated acceptance test pass while violating a non-goal. Rank by production impact. Do not suggest style changes.” That prompt produces fewer essays and more actionable attacks. It also gives junior reviewers a way to challenge generated code without needing to out-argue a confident paragraph.

Limitations and who should skip this

This gate adds latency. If your change is a typo in internal docs, the full ceremony is waste. It also cannot prove absence of bugs; it can only make some classes of bugs more expensive to sneak through. Flaky tests will become more visible, which is good, but teams sometimes respond by deleting the alarm instead of fixing the fire drill. Resist that.

Do not use an external free lane for incident response involving live credentials, for code governed by export controls, for medical/financial decision logic without domain review, or when your organization cannot answer basic questions about data retention. Do not let a reviewer model mark its own homework: the same prompt that generated the patch should not be the only authority approving it. Keep humans on merge rights, keep rollback cheap, and keep generated changes smaller than your ability to explain them during an outage.

The habit worth stealing is the split between creativity and custody. Let assistants draft, brainstorm, and attack. Let deterministic checks, explicit contracts, and accountable people decide what enters main. If you adapt the scaffold, start with one repository and one contract key, then post the weirdest failure your gate caught so others can add it to their checklist.