DEV Community: Charlie Zhu

The Receiving Inspection Workshop: A Gate for AI-Written Code

Charlie Zhu — Fri, 16 Oct 2026 04:57:23 +0000

Three agent-written patches landed on a Friday afternoon. Two were nine-line diffs, one touched a helper nobody remembered owning, and all three were reviewed in the ten minutes between a standup and a release. On Monday the nightly seed job died, and nobody could say which candidate produced the line that killed it.

That team did not have a review problem. It had a receiving problem. A candidate sat in a pull request, looked plausible, and crossed into the trunk without anything recording what had actually been checked.

The last few weeks of DEV discussion keep circling a familiar split: model capability climbs, and the software wrapped around it stays about as fragile as the day it was written. That gap is not a model problem. It is a testing problem, and it is teachable in ninety minutes.

This workshop builds a receiving dock. Students leave with a gate that parses a candidate, runs it against a fixture, writes a verdict to a ledger, and refuses to be the last word on anything.

The invariant

The whole workshop hangs on one sentence, written by the students in the first ten minutes and never edited afterward: nothing reaches the trunk without a receipt.

A receipt is one JSON line. It names the task, the model that produced the candidate, the verdict, a machine-readable reason, and a timestamp. It is boring on purpose. When the nightly job breaks three days later, the receipt is what lets someone say this candidate passed a three-case fixture and nothing else, instead of reconstructing the week from chat scrollback.

The run sheet

Clock	Segment	Artifact at the end
00–10	The Monday failure story, told once	The written invariant
10–25	Fixture before gate	`tasks/03_slugify/test_solution.py`, three cases
25–45	Build the gate	`gate.py`, first `accept` receipt
45–60	Break it deliberately	Two quarantines, one false accept
60–75	Boundary sweep	A property test that catches the fake
75–90	Yield accounting and transport swap	`receipts.jsonl` and a yield number

Every segment ends with a file. If a segment runs long, the artifact gets cut down, never skipped, because a workshop that finishes with a feeling instead of a file teaches nothing rerunnable.

Fixture before gate

Students almost always want to write the gate first. That order produces a gate that grades whatever it happens to be shown, which is the exact failure mode of human review under deadline pressure.

The fixture comes first. A task is a directory with a prompt and a test file, and the candidate is expected to expose one function.

{
  "id": "03_slugify",
  "model": "fill-from-current-provider-docs",
  "prompt": "Write slugify(text: str) -> str"
}

# tasks/03_slugify/test_solution.py
from solution import slugify


def test_basic():
    assert slugify("Hello World") == "hello-world"


def test_collapses_runs():
    assert slugify("a   b---c") == "a-b-c"


def test_empty_stays_empty():
    assert slugify("") == ""

Three cases is the right number for the first pass. A fixture large enough to be impressive is a fixture nobody in the room can explain, and an unexplained fixture fails silently the day it is edited.

The gate

The gate is deliberately small: it parses, it runs, it records, it stops.

#!/usr/bin/env python3
"""gate.py - receiving inspection for model-written candidates."""
import ast, json, pathlib, subprocess, sys, time

ROOT = pathlib.Path(__file__).parent
MAX_BYTES = 8192


def parse_ok(path):
    try:
        ast.parse(path.read_text())
    except SyntaxError as exc:
        return False, f"syntax_error_line_{exc.lineno}"
    return True, "parsed"


def behavior(test_path, scratch):
    proc = subprocess.run(
        [sys.executable, "-m", "pytest", "-q", str(test_path)],
        cwd=scratch, capture_output=True, text=True, timeout=60,
    )
    lines = proc.stdout.strip().splitlines()
    return proc.returncode == 0, (lines[-1] if lines else "no_output")


def main(task_dir):
    task = json.loads(pathlib.Path(task_dir, "task.json").read_text())
    scratch = ROOT / "scratch" / task["id"]
    scratch.mkdir(parents=True, exist_ok=True)
    candidate = ROOT / "candidates" / f'{task["id"]}.py'
    verdict, reason = "quarantine", "no_candidate"

    if candidate.exists() and candidate.stat().st_size <= MAX_BYTES:
        ok, why = parse_ok(candidate)
        if ok:
            (scratch / "solution.py").write_text(candidate.read_text())
            (scratch / "test_solution.py").write_text(
                pathlib.Path(task_dir, "test_solution.py").read_text()
            )
            ok, why = behavior(scratch / "test_solution.py", scratch)
        verdict, reason = ("accept" if ok else "quarantine"), why
    elif candidate.exists():
        reason = f"oversize_{candidate.stat().st_size}b"

    receipt = {
        "task": task["id"],
        "model": task.get("model", "unspecified"),
        "verdict": verdict,
        "reason": reason,
        "ts": int(time.time()),
    }
    with open(ROOT / "receipts.jsonl", "a") as fh:
        fh.write(json.dumps(receipt) + "\n")
    print(json.dumps(receipt))


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

A candidate for the slug task, dropped at candidates/03_slugify.py, looks like this:

import re


def slugify(text):
    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")

$ pip install pytest
$ python gate.py tasks/03_slugify
{"task": "03_slugify", "model": "fill-from-current-provider-docs", "verdict": "accept", "reason": "3 passed", "ts": 1792000000}

If pytest reports an ImportError on solution, the instructor has hit the classic path problem; run the gate with PYTHONPATH=. set and the scratch directory as the working directory, and the failure disappears. That detour is worth five minutes, because everyone meets it eventually in their own repository.

Break it deliberately

This is the segment that changes how students think about green checks. The instructor supplies a candidate that hardcodes the fixture's answers:

def slugify(text):
    return {
        "Hello World": "hello-world",
        "a   b---c": "a-b-c",
        "": "",
    }.get(text, "")

The gate accepts it. Three tests, three passes, one receipt that says accept, and a function that will return an empty string for every input the product actually receives. The fixture graded the fixture.

The correction is a property check that ties output back to input instead of to remembered examples:

# tasks/03_slugify/test_boundary.py
import random, string
from solution import slugify


def test_alnum_digest_matches():
    rng = random.Random(7)
    for _ in range(200):
        raw = "".join(
            rng.choice(string.printable) for _ in range(rng.randint(1, 40))
        )
        digest = "".join(ch for ch in raw.lower() if ch.isalnum())
        assert slugify(raw).replace("-", "") == digest

The hardcoded candidate now fails within a handful of iterations, while the real implementation passes all two hundred. Students see the difference between evidence and a memory test, and they see it in code rather than in a slide.

Where the compute comes from

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

Two hundred generated candidates per cohort is small by industry standards and painful in a classroom, because it forces every student to hold a paid key before they have learned anything worth paying for. MonkeyCode, the project behind this article's operator, describes a free tier and a free server option; the operator currently reports the free allowance at ten million tokens. Those terms live on the project's own page and can change, so this workshop treats them as a starting point to check rather than constants to quote in a syllabus, and it asserts nothing about which models are included, how large the server is, or how long either offer lasts.

The harness itself assumes no vendor at all. The transport is one function, and the shape below is what students fill in from whatever endpoint they are actually using:

import json, os, urllib.request


def ask(prompt):
    request = urllib.request.Request(
        os.environ["BASE_URL"] + "/chat/completions",
        data=json.dumps({
            "model": os.environ["MODEL"],
            "messages": [{"role": "user", "content": prompt}],
        }).encode(),
        headers={
            "Authorization": f'Bearer {os.environ["API_KEY"]}',
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(request, timeout=120) as response:
        return json.load(response)["choices"][0]["message"]["content"]

The free server option earns its place in the boundary-sweep segment, where a loop of two hundred candidates would otherwise compete with whatever else is on the student's laptop. It is a convenience for the exercise, not a claim about production throughput.

Yield accounting

The last artifact is a number students compute themselves:

import collections, json

rows = [json.loads(line) for line in open("receipts.jsonl")]
counts = collections.Counter(row["verdict"] for row in rows)
total = sum(counts.values())
print(counts, "yield=", round(counts["accept"] / total, 3))

Yield is acceptance rate per task, and it belongs to the task, not to the model. A slug function with a clear contract collects accepts; a task whose prompt hides its error handling collects quarantines and tells the room nothing about model quality. That distinction is worth more than any leaderboard.

The verdict table

The gate produces four outcomes, and each maps to one action.

Verdict	Signal	Action
Accept	Parses, fixture green, sweep green	Merge with a link to the receipt
Repair	Parses, one named test fails with a local cause	One bounded revision, re-run the gate, two attempts maximum
Quarantine	Syntax error, oversize candidate, timeout, or missing file	Move the candidate to `quarantine/` and stop
Escalate	Sweep green but the diff touches files, network, or credentials	Human review of record, no exceptions

What this gate cannot see

The gate checks exactly what the fixture encodes and nothing more. A candidate that passes one afternoon is not guaranteed to pass tomorrow, because sampling variance means the same prompt can produce a different artifact; that is why the candidate bytes get stored next to the receipt and re-run on demand. The byte limit is arbitrary and exists to keep reviews short. The sixty-second timeout catches hangs, not deadlocks that resolve in ninety seconds. Concurrency, license headers, and secret handling are invisible to it.

Teams in regulated pipelines should not treat this gate as a control. It is a teaching device and a first filter, and a named human reviewer of record is still required wherever the rules say so. Teams with no fixture-writing habit should fix that habit before building the gate, or they will automate the grading of nothing.

A cohort that wants to see the sweep finish before deciding whether the gate belongs in its pipeline can start on the free tier and the free server option; the current terms page is the only place worth trusting for what is included today.

MonkeyCode provides free models that can run this workflow.

The Fare Gate Workshop: A Token Budget That Fails Loudly

Charlie Zhu — Thu, 15 Oct 2026 11:13:59 +0000

The Fare Gate Workshop: A Token Budget That Fails Loudly

The room goes quiet at the same moment every time. A scripted client loops through forty prompts, the provider stops answering somewhere around the thirty-first, and the traceback on the projector says nothing useful, because the real cause lives in an account nobody in the room can inspect. The failure is not a bug in the loop. It is a missing gate.

This workshop runs ninety minutes, uses one repository, and needs no paid key. Students write the component that refuses to spend before the refusal becomes real, and they leave with a ledger file they can hand to the next cohort. The framing comes from a complaint that keeps resurfacing in developer discussions: AI demos are easy to stage and hard to keep honest once quota and money enter the picture.

Think of a subway turnstile. Nobody expects the gate to explain the fare table to the crowd behind it. They expect it to close cleanly at the right moment and to leave a record of every entry. A token budget behaves the same way, and the record is the part students actually keep.

What the class builds

Three files, standard library only, no network required by default. ledger.py holds the spend record and the projection check. gate.py chooses a route and refuses when the projection crosses the budget. test_gate.py pins the behaviour so the exercises cannot be faked by accident. The ledger is append-only JSONL, which matters more than it sounds: a student who kills the process mid-batch and reruns the script should see the earlier spend still there.

# ledger.py — token ledger and preflight gate. Standard library only.
from __future__ import annotations
import json, pathlib, time

LEDGER_PATH = pathlib.Path("runs/ledger.jsonl")

def estimate_tokens(text: str) -> int:
    """Deliberately conservative: 4 chars per token, rounded up, +8 per message."""
    return max(1, -(-len(text) // 4)) + 8

class BudgetExceeded(RuntimeError):
    def __init__(self, spent: int, projected: int, budget: int):
        super().__init__(f"spent {spent} + projected {projected} > budget {budget}")
        self.spent, self.projected, self.budget = spent, projected, budget

class Ledger:
    def __init__(self, budget: int, path: pathlib.Path = LEDGER_PATH):
        self.budget, self.path = budget, path
        self.path.parent.mkdir(parents=True, exist_ok=True)

    def spent(self) -> int:
        if not self.path.exists():
            return 0
        rows = (json.loads(line) for line in self.path.read_text().splitlines() if line.strip())
        return sum(row["tokens"] for row in rows)

    def preflight(self, prompt: str, max_output: int) -> int:
        projected = estimate_tokens(prompt) + max_output
        if self.spent() + projected > self.budget:
            raise BudgetExceeded(self.spent(), projected, self.budget)
        return projected

    def record(self, route: str, tokens: int, note: str = "") -> None:
        row = {"ts": round(time.time(), 3), "route": route, "tokens": tokens, "note": note}
        with self.path.open("a") as fh:
            fh.write(json.dumps(row, sort_keys=True) + "\n")

    def report(self) -> str:
        spent = self.spent()
        pct = 100 * spent / self.budget if self.budget else 0.0
        return f"spent={spent} budget={self.budget} ({pct:.1f}%)"

The -(-len(text) // 4) trick is ceiling division, and the constant four is a guess that the calibration exercise later punishes. That is intentional. Students should feel the estimate drift before they trust it.

The gate, and the route table

Two routes exist: a local stub that never touches the network, and a hosted route that students wire to a real client themselves. The stub is what makes the class reproducible on a train with no signal, and it is also the honest default in argparse.

# gate.py — route selection; dry-run friendly by design.
import argparse
from ledger import Ledger, estimate_tokens, BudgetExceeded

def stub(prompt: str) -> tuple[str, int]:
    return f"[stub] {prompt[:40]}", estimate_tokens(prompt)

def hosted(prompt: str) -> tuple[str, int]:
    raise SystemExit(
        "Wire the provider client here. Read the key from the environment, "
        "never from source, and return (text, tokens_reported_by_provider)."
    )

ROUTES = {"stub": stub, "hosted": hosted}

def run(route: str, prompts: list[str], budget: int, max_output: int) -> int:
    led, refused = Ledger(budget=budget), 0
    for i, prompt in enumerate(prompts, 1):
        try:
            led.preflight(prompt, max_output)
        except BudgetExceeded as exc:
            print(f"{i:02d} refused: {exc}")
            refused += 1
            continue
        text, tokens = ROUTES[route](prompt)
        led.record(route, tokens, note=f"prompt={i}")
        print(f"{i:02d} {route} {tokens}t :: {text}")
    print(led.report(), f"refused={refused}")
    return refused

if __name__ == "__main__":
    ap = argparse.ArgumentParser()
    ap.add_argument("--route", choices=sorted(ROUTES), default="stub")
    ap.add_argument("--budget", type=int, default=600)
    ap.add_argument("--max-output", type=int, default=64)
    ap.add_argument("--prompts", type=int, default=40)
    args = ap.parse_args()
    batch = [f"Explain checkpointing, variation {i}." for i in range(1, args.prompts + 1)]
    run(args.route, batch, args.budget, args.max_output)

A class-sized demo looks like this, and the important line is the refusal, not the success.

python gate.py --route stub --budget 600 --max-output 64 --prompts 40
# 31 stub 15t :: [stub] Explain checkpointing, variation 31.
# 32 refused: spent 592 + projected 20 > budget 600
# spent=592 budget=600 (98.7%) refused=9

python -c "from ledger import Ledger; print(Ledger(600).report())"
# spent=592 budget=600 (98.7%)   <- survives a fresh process

The tests students must not skip

The two assertions below cover the only two failures that matter in production: the gate that never closes, and the ledger that forgets.

# test_gate.py — run with: pytest -q
import pytest
from ledger import Ledger, BudgetExceeded

def test_gate_refuses_when_projection_exceeds_budget(tmp_path):
    led = Ledger(budget=50, path=tmp_path / "l.jsonl")
    led.record("hosted", 40)
    with pytest.raises(BudgetExceeded):
        led.preflight("x" * 400, max_output=64)

def test_ledger_survives_process_restart(tmp_path):
    path = tmp_path / "l.jsonl"
    Ledger(budget=1000, path=path).record("stub", 12)
    assert Ledger(budget=1000, path=path).spent() == 12

The ninety minutes, block by block

The first ten minutes are the staged incident and nothing else; the class watches the loop die, then writes down three things the traceback failed to say. From ten to twenty-five, students copy ledger.py, run pytest -q, and watch both tests pass, which buys credibility for a file that looks trivial. The middle half hour is the gate itself: wire the refusal path, force BudgetExceeded on purpose with --budget 200, then open runs/ledger.jsonl and read the rows aloud. Students who finish early delete the ledger file and rerun, and the failure of that run is the lesson about persistence.

At the forty-five minute mark the class switches to the hosted route for roughly twelve minutes. The goal is not volume; it is the calibration step. Each student records estimate_tokens(prompt) + max_output before the call, compares it against the token count the provider reports, and writes the drift into a shared column on the board. Drift of twenty percent is common in a chatty batch, which is why the last fifteen minutes belong to the post-mortem: which of the three numbers would you trust in an alerting rule, and what would you set the budget to if the free allowance disappeared tomorrow. The final five minutes exist for one question only, and it is not about the code.

The hosted route and a free tier

Exercise four needs a real provider response, and not every student arrives with a key. For that block the workshop points the hosted route at MonkeyCode, whose free tier the operator describes as including ten million free tokens and a free server option; the ledger does not care who pays for the tokens, so the exercise survives either way. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Treat the free allowance as a teaching budget, not a production plan. Nothing here depends on specific model names, throughput, or hardware, because the class never needs them — the gate, the JSONL rows, and the drift column are provider-agnostic, and swapping the hosted client for a different vendor is a five-line change in gate.py. A reader who wants to run exercise four next week can claim the free tier and point the hosted route at it, then keep the ledger as the artifact.

Where this breaks, and who should skip it

The char-divided-by-four estimate is a heuristic, not a tokenizer. On code-heavy prompts it can be off by a wide margin, and the calibration block is the only honest defence against that. The gate is also per-process: two students running the same ledger file concurrently will interleave writes, and the file has no locking, so a team doing parallel batch work needs a real counter in a database instead. Refusals are coarse. The gate stops a whole prompt; it does not shrink the output budget or degrade gracefully to the stub, and adding that fallback is a legitimate second workshop.

Skip this entirely if the workload is interactive and single-shot, where a gate costs more attention than it saves. Skip it if quota exhaustion is already handled by platform-side limits you do not control. And skip it if the goal is throughput measurement, because a ledger records spend, not speed.

What remains after the room empties is a directory with one JSONL file in it, a few hundred lines of number, and a refusal message that reads like a sentence instead of a stack trace. That file is the part worth keeping. It is also the cheapest possible answer to the question every AI demo eventually raises, which is who is paying, and how much, and what happens when the answer runs out.

MonkeyCode provides free models that can run this workflow.

The Red Pencil Workshop

Charlie Zhu — Tue, 13 Oct 2026 00:18:32 +0000

The workshop opens on a staged failure, because a visible row count teaches faster than a definition. On the projector, a fake ledger shows three captures for one invoice after a short reply suggested a three-try loop around a gateway timeout. The teaching assistant does not start a lecture. She slides a red pencil across the bench and holds the next patch until the pencil mark and the test log agree.

That hour is the whole lesson. It is aimed at people who already write small Python services and who review a partner's patch before it lands. A fluent answer counts as a draft. A draft earns a mark only after a local test writes evidence a neighbor can rerun on a clean machine.

The pencil is not a stand-in for taste. It is a script exit line the pair reads aloud before anyone talks about merging. If the line and the test disagree, the paragraph loses.

The shop picture is a traveler card, not a courtroom. On a metal part, red pencil means a second person stood at the gauge and marked the card. The mark is worthless if the gauge never moved. Here the gauge is a unit test that counts capture attempts, and the mark is one stamped line.

Eighty minutes, one process

Eighty minutes is enough when the files already sit on the instructor machine. The first ten minutes replay the double charge, with the attempt list on screen, so the failure is a row count. The next fifteen minutes are local setup: a virtual environment, the modules below, and one command that prints three attempts for the bad policy.

The following twenty minutes are the first exercise. Pairs write a charge function that records an invoice key before the call and refuses a second call in the same process, even when the first call raised a timeout. They are not designing a payment network. They are stopping one process from repeating a side effect whose result is unknown.

Fifteen minutes go to the countercheck. A neighbor may paste a model reply into a text file, but only that neighbor runs the stamp, and the stamp does not read confidence. The last twenty minutes are a clean-directory rerun, including a cheat where someone types a passing line by hand. The neighbor deletes that file, runs the test, and makes the pencil follow the gauge.

Files the room can rerun

The modules are a lab design, written to be copied and executed. They are not a transcript of a timed class and they are not a measured production incident. ledger.py appends the attempt before it decides to time out. That order is the trap.

A retry loop can sound careful and still leave three rows, because the side effect happens before the exception. Students replace the loop with charge_once. The seen set lives only in memory, and that weakness is part of the lesson. A later week can put the same key in a journal file. This week stops at one process.

class Ledger:
    def __init__(self):
        self.attempts = []

    def capture(self, invoice_id, cents):
        self.attempts.append((invoice_id, cents))
        if str(invoice_id).endswith("-flaky"):
            raise TimeoutError("gateway timeout")
        return {"invoice_id": invoice_id, "cents": cents, "status": "captured"}


def charge_once(ledger, invoice_id, cents, seen):
    if invoice_id in seen:
        return {
            "invoice_id": invoice_id,
            "status": "already-attempted",
            "attempts": len(ledger.attempts),
        }
    seen.add(invoice_id)
    try:
        return ledger.capture(invoice_id, cents)
    except TimeoutError:
        return {
            "invoice_id": invoice_id,
            "status": "unknown-do-not-retry",
            "attempts": len(ledger.attempts),
        }


def charge_with_blind_retry(ledger, invoice_id, cents, _seen):
    last = None
    for _ in range(3):
        try:
            return ledger.capture(invoice_id, cents)
        except TimeoutError as exc:
            last = exc
    raise last

demo_blind.py is the opening scene reduced to a command. It does not pass or fail a suite. It prints the row count, and a correct copy prints blind attempts=3. If a pair hides the failure by catching the error inside capture, the count drops and the instructor puts the append back. The bad behavior has to stay visible, or the pencil has nothing to contradict.

from ledger import Ledger, charge_with_blind_retry

def main():
    ledger = Ledger()
    try:
        charge_with_blind_retry(ledger, "inv-9-flaky", 1250, set())
    except TimeoutError:
        pass
    print("blind attempts=%s" % len(ledger.attempts))

if __name__ == "__main__":
    main()

The gauge does not fail the suite in order to scold the specimen loop. It proves the once-only policy and writes one evidence line. The specimen stays in the other file so the demo command can still show three rows after the suite is green. A room that starts from a red bar learns to chase the first assertion. This room learns to produce a line a second script can read.

import unittest
from pathlib import Path
from ledger import Ledger, charge_once

EVIDENCE = Path("evidence.txt")

class RedPencilTest(unittest.TestCase):
    def test_timeout_does_not_authorize_a_second_capture(self):
        ledger = Ledger()
        seen = set()
        result = charge_once(ledger, "inv-9-flaky", 1250, seen)
        self.assertEqual(result["status"], "unknown-do-not-retry")
        self.assertEqual(ledger.attempts, [("inv-9-flaky", 1250)])
        self.assertEqual(result["attempts"], 1)
        EVIDENCE.write_text("PASS once-only attempts=1\n", encoding="utf-8")

    def test_same_key_is_not_sent_again(self):
        ledger = Ledger()
        seen = set()
        charge_once(ledger, "inv-9-flaky", 1250, seen)
        again = charge_once(ledger, "inv-9-flaky", 1250, seen)
        self.assertEqual(again["status"], "already-attempted")
        self.assertEqual(len(ledger.attempts), 1)

if __name__ == "__main__":
    unittest.main()

stamp.py lowercases the reply and rejects a few workshop phrases. The phrases are the ones a helpful draft tends to offer: always retry, safe to retry, ignore the test, trust this. The script then requires the evidence file to start with PASS and to contain attempts=1. A pair that wants the stamp rewrites the reply until it describes the once-only stop, then reruns the test so the evidence is fresh.

The script does not compare file clocks. The neighbor does. That human step is deliberate. The lab is a review habit, not a trust root, and a clock check would hide the social part of the pencil.

import sys
from pathlib import Path

BANNED = (
    "always retry",
    "safe to retry",
    "ignore the test",
    "trust this",
)

def stamp(reply_path, evidence_path):
    reply = Path(reply_path).read_text(encoding="utf-8").lower()
    evidence_file = Path(evidence_path)
    if evidence_file.exists():
        evidence = evidence_file.read_text(encoding="utf-8")
    else:
        evidence = ""
    for phrase in BANNED:
        if phrase in reply:
            return "REJECT: reply tells the class to retry or to skip tests"
    if not evidence.startswith("PASS"):
        return "REJECT: no local PASS evidence"
    if "attempts=1" not in evidence:
        return "REJECT: evidence does not record a single attempt"
    return "STAMP: red-pencil-ok"

if __name__ == "__main__":
    if len(sys.argv) != 3:
        print("usage: python stamp.py reply.txt evidence.txt")
        raise SystemExit(2)
    print(stamp(sys.argv[1], sys.argv[2]))

A clean pass uses ordinary commands. The lab assumes Python 3 with the standard library and nothing else. No third-party package is required, which keeps the first fifteen minutes from turning into an installer debate.

python -m venv .venv
source .venv/bin/activate
python demo_blind.py
python test_red_pencil.py
printf '%s\n' "charge_once records the key, then stops after a timeout" > reply.txt
python stamp.py reply.txt evidence.txt

The expected stamp line is STAMP: red-pencil-ok. The counterexample should run first. A reply that says it is safe to retry on timeout must print a REJECT line even when evidence.txt already contains PASS. Windows machines can activate with .venv\Scripts\activate and then use the same Python commands. The lesson does not depend on bash.

A draft is not a stamp

Only the second exercise needs a hosted model, and it still works without one. One student may paste the timeout text and ask for a patch. The partner saves that answer, unchanged, as reply.txt, and runs the stamp before anyone applies a diff. A local file that already contains the bad paragraph teaches the same refusal when the network is down. The model supplies drafts. The test supplies the stamp.

Free model access is a practical fit when a department will not issue paid keys for one afternoon, and a free server option is a practical fit when the instructor wants one shared copy of these files instead of a handful of zip attachments. MonkeyCode is one place those two options are offered for this kind of lab. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Neither option is required for the stamp to mean anything.

Terms should be read on the morning of the class, in the project documentation, because availability language moves. This article does not pin a token ceiling, a machine shape, a region, or an end date. A workshop sheet that freezes an unverified number becomes the outdated handout the next cohort has to unlearn.

The cheat stays on the clock because someone will find it. Hand-typing PASS into evidence.txt makes a careless reading look finished. The workshop names that move in the same tone as a skipped gauge. The neighbor deletes the file, runs the test module, and only then runs the stamp script.

If the script and the test disagree, the test wins. A screenshot of the stamp without that rerun is decoration. The pencil is there to slow the conversation, not to decorate the slide.

Who should leave this lab on the bench

This lab should not be pointed at a real charge path, a mail sender, or an inventory decrement. The in-memory set dies with the process, so two workers can still capture the same invoice. It should not be the only review on a pull request. It is a poor first week for students who have not met exceptions, because the timeout will hide the attempt list.

It is also the wrong artifact for anyone comparing model vendors. No latency, cost, quality, or uptime figure is collected. A team that needs those numbers should measure its own traffic against its own success criteria, rather than borrow a classroom stamp and treat it as a score.

A later hour can append the invoice key to a journal and refuse capture when the line already exists. That problem is closer to crash recovery than to reply hygiene, and it needs its own timer. This workshop ends when every pair can show three attempts, then one attempt, and can refuse a smooth paragraph that disagrees with the evidence file.

Instructors who want the fixture on a no-cost shared box can check the current free-server note in the MonkeyCode project before they book the date. If that note no longer matches the plan, the same files stay on the laptops and the stamp does not change.

The Spare Bench Workshop

Charlie Zhu — Sun, 11 Oct 2026 20:51:25 +0000

The workshop script opens on a familiar mess. Twelve laptops share one repository, and a patch drafted during the break already wears a confident commit message. The tests are green on the machine that asked for the draft. That green is a rumor until a clean checkout repeats it.

A spare bench is the room's answer to rumors. It is a second machine with a known tree, a fresh environment, a clock, and no leftover packages from last month's experiment. The bench can be a classmate's laptop. On days when a free server option is actually listed, the bench can be that server, and the brand still matters less than the rule: the machine that watched the draft does not get the final vote.

MonkeyCode shows up in this script only as a possible spare bench and a possible drafter. The operator describes it as an open-source coding assistant with free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Those two availability claims are classroom conveniences, not a capacity contract.

This write-up names no model, no token total, no hardware shape, and no rental duration, because those facts live on the current product page and they move. The morning of the session, the instructor opens that page. A missing option means the class switches the bench to any other clean machine. It does not mean the class skips the ledger.

The script is a proposal for an eighty-minute sitting, not a report of a timed cohort or a measured pass rate. Twenty minutes pin a fixture. Twenty-five minutes draft a candidate behind a fence. Twenty-five minutes rerun that candidate on the spare bench, and the last ten minutes write a refusal note when the ledger disagrees.

A short break sits between the draft and the rerun. Nobody gets to "fix" the bench by copying a virtual environment across the room. The hour is about a command another person can type, not about a laptop that remembers too much.

The fixture is dull on purpose. Dull code survives a clean machine, and a workshop that opens with a framework spends its hour on installation theater. Students create a tiny package that answers a warehouse question: how many boxes hold a given item count when every box has the same size. The contract is integer arithmetic. Floats are a trap the later exercise will spring.

# spare-bench/binpack/count.py
def boxes_needed(item_count, box_size):
    if box_size <= 0:
        raise ValueError("box_size must be positive")
    if item_count < 0:
        raise ValueError("item_count must be non-negative")
    return (item_count + box_size - 1) // box_size

An empty spare-bench/binpack/__init__.py keeps the import from depending on a path accident. The tests are frozen after the first successful run. Students may not edit them to make a candidate look clever.

# spare-bench/tests/test_count.py
import unittest
from binpack.count import boxes_needed

class CountTests(unittest.TestCase):
    def test_exact_fit(self):
        self.assertEqual(boxes_needed(8, 4), 2)

    def test_remainder(self):
        self.assertEqual(boxes_needed(9, 4), 3)

    def test_zero_items(self):
        self.assertEqual(boxes_needed(0, 4), 0)

    def test_bad_box(self):
        with self.assertRaises(ValueError):
            boxes_needed(3, 0)

if __name__ == "__main__":
    unittest.main()

The first block ends with two local runs, not one. The second run is there to prove the fixture itself is stable before anyone invites a model in. Commands below assume a POSIX shell. They are part of the exercise, and they are not presented as a benchmark.

mkdir -p spare-bench/binpack spare-bench/tests
python3 -m venv spare-bench/.venv
. spare-bench/.venv/bin/activate
cd spare-bench
PYTHONPATH=. python -m unittest discover -s tests -q
PYTHONPATH=. python -m unittest discover -s tests -q

Both runs should exit 0. A failure here is a path or packaging problem, and the class fixes that before any assistant is allowed to speak. Path confusion loves to dress up as a logic bug.

The second block permits a model. Free model access, including the option named above when the page still lists it, may draft boxes_needed. The prompt is fixed. Students paste the test file and ask for an implementation, then add one fence in the same breath: do not modify tests, do not add dependencies, do not rename the function, and do not include secrets. This fixture has none, and it should stay that way.

A fence is a constraint the ledger can see. A hunch is not. The worked candidate below is reconstructed for the exercise. It is not a transcript from a live model, and it should not be treated as a score against any product.

def boxes_needed(item_count, box_size):
    if box_size <= 0 or item_count < 0:
        raise ValueError("bad input")
    return round(item_count / box_size)

round(9 / 4) is round(2.25). Python's round uses banker's rounding, and that call returns 2. The fixture expects 3, because nine items need a third box. The combined ValueError also erases the two distinct messages in the reference, which will matter if a later test matches text.

The class does not need a leaderboard. A tidy function can be wrong in a way a glance rewards. Students save that candidate over count.py, leave the tests untouched, and run the suite on the laptop. A local failure is useful. A local pass is still not acceptance, because the laptop that requested the draft is a witness and the spare bench is the judge.

The third block copies the tree, not the virtual environment. If the free server option is listed that morning, students use it as the spare bench and install nothing beyond a current Python 3. If the option is absent, a second laptop with a new virtual environment plays the same role. The script the class keeps runs the suite, hashes combined output, and appends one JSON line. It does not retry. A hidden retry would launder the flake this hour is trying to see.

# smoke_ledger.py
import hashlib
import json
import os
import subprocess
import sys
import time
from pathlib import Path

def run_suite(cwd: Path) -> dict:
    start = time.perf_counter()
    proc = subprocess.run(
        [sys.executable, "-m", "unittest", "discover", "-s", "tests", "-q"],
        cwd=cwd,
        text=True,
        capture_output=True,
        env={**os.environ, "PYTHONPATH": str(cwd)},
    )
    blob = (proc.stdout + "\n" + proc.stderr).encode()
    return {
        "cmd": [sys.executable, "-m", "unittest", "discover", "-s", "tests", "-q"],
        "exit_code": proc.returncode,
        "seconds": round(time.perf_counter() - start, 3),
        "output_sha256": hashlib.sha256(blob).hexdigest(),
        "stdout_tail": proc.stdout[-400:],
        "stderr_tail": proc.stderr[-400:],
    }

def main() -> int:
    cwd = Path(sys.argv[1]).resolve()
    row = run_suite(cwd)
    with (cwd / "smoke-ledger.jsonl").open("a", encoding="utf-8") as handle:
        handle.write(json.dumps(row) + "\n")
    print(json.dumps(row, indent=2))
    return row["exit_code"]

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

The same invocation runs on every bench. Two lines are the comparison, not a dashboard.

python3 smoke_ledger.py spare-bench
python3 smoke_ledger.py spare-bench

Students then read the last pair without adopting a framework to test their runner. The helper is small enough to retype on the board.

import json
from pathlib import Path

def last_pair(path):
    rows = [json.loads(line) for line in Path(path).read_text().splitlines() if line]
    left, right = rows[-2], rows[-1]
    return {
        "exit_codes": (left["exit_code"], right["exit_code"]),
        "same_hash": left["output_sha256"] == right["output_sha256"],
        "seconds": (left["seconds"], right["seconds"]),
    }

Acceptance is narrow, and it is decided in prose so the rule cannot hide inside a config file. Both exit codes are 0, the hashes match, and the test file is byte-for-byte the file frozen in the first block. A matching hash with a failing exit code is a refusal. A passing exit code with a drifting hash is a note, not a celebration, because a timestamp or a reordered warning changes the digest even when the logic holds.

This fixture prints no logs, so the raw digest is enough. A later lab that adds logs should strip volatile lines before hashing, and should write that stripper down next to the fence. No hash from this article should be copied into a student's ledger. The script fills that field on their machine.

The reconstructed candidate fails the gate. test_remainder wants 3 and the function returns 2. The ledger's exit code is non-zero, and the stderr tail names the assertion. The repair is ceiling division, the same expression the reference used. After the repair, the student reruns the ledger on the spare bench and only then opens a pull request. The request links the ledger line. It does not link a screenshot of a chat.

The last ten minutes are a writing exercise with a mean streak. When the spare bench disagrees with the laptop, the student writes three sentences: what differed, which claim they withdraw, and which command a reviewer should rerun. They do not write that a model was wrong in general. They write that this candidate failed this fixture on this bench. The narrower sentence is the one a later class can trust.

A refusal note for the rounding candidate is short enough to read aloud. The first honest run failed test_remainder because round is not ceiling division. The withdrawn claim is that a readable implementation is a finished one. The rerun command is python3 smoke_ledger.py spare-bench from a clean tree, with the script setting PYTHONPATH.

This spare bench will not carry production work. It should not see secrets, customer records, or credentials. Free model access can change, throttle, or disappear between a Thursday plan and a Friday lab. A free server can be slow, asleep, or packaged differently from a student's laptop.

Nothing here measures that gap, and nothing here promises a quota. People who need a named model, a contractual uptime, a hardware shape, or graded deterministic generation should not use this setup as a system of record. They can still keep the ledger. The ledger does not care which assistant drafted the patch.

Courses that grade screenshots, prose style, or usage theater should skip the session. The artifact cannot see intent. It can see an exit code. Teams that want automatic merges should skip it too, until a human has accepted the refusal rule, because a green ledger on a toy fixture is not a release.

Integer box counts will not catch races, network calls, or migration hazards. The example is a scale model of a habit, and it should stay small enough to finish before the room gets restless. Windows students should translate the activation line rather than treat a missing source as a failed proof.

An instructor who wants this shape of bench can open the MonkeyCode project page, confirm that free model access and the free server option are still listed, read the license in the official repository, and only then point a class at it. If either option is gone, the eighty minutes still stand on a second laptop and the same script.

The Sample Coupon Workshop

Charlie Zhu — Sat, 10 Oct 2026 17:14:57 +0000

A maintainer on a small platform team opened the Monday board and found one red parser test sitting between a release note and a hallway argument. A colleague had already pasted the repository into a chat window. The reply came back long, calm, and wrong about a function renamed in March.

The build stayed red. The useful move was smaller than the argument. Cut a sample coupon from the same stock, mark it, and run one procedure the room can repeat before lunch.

In a metal shop, a coupon is not the bridge. It is a strip taken from the heat being used that day, etched with an identity, and put through a known load. A pass says something narrow: this piece, under this load, on this date, held. A fail says something narrow too.

The workshop treats a model note the same way. Students do not ask a model to bless a repository. They ask it to speak about one failing assert, then a local scorer decides whether the note even names the failure.

The session is ninety minutes, and the clock is part of the method. The first ten minutes stay with the Monday story and a hard constraint: no secret, no customer log, and no whole-tree paste. From minute ten to minute twenty-five the class cuts the coupon. One failing assert is enough, taken from a toy parser or from the fixture shipped with the notes.

The card is a small object with an id, the claim under test, the exact assert text, the tokens a note must name, and the moves a note must not recommend. From minute twenty-five to minute forty-five the class builds the scorer and runs two fixtures, one meant to pass and one meant to fail. From minute forty-five to minute sixty-five a note is produced, first from the checked-in fixture and only afterward, if the bench is actually up, from a live model. From minute sixty-five to minute eighty the room reads the score the way a shop traveler reads a stamp. The last ten minutes are reserved for what the coupon cannot certify, which is most of the repository.

The scorer is dull on purpose. Dull tools survive a classroom and a tired Tuesday. The script below is a worked example for Python 3.11 or newer, and it is meant to be rerun on a laptop with no network. It checks that a note mentions the error the coupon cares about, mentions the assert, mentions None, and does not wander into a rewrite the card forbade.

A hash and a timestamp turn the run into a record instead of a mood. The exit status lets a later exercise hang the same script on a tiny job without inventing a second rubric.

# coupon_check.py
# Worked example. Rerun locally before any network call.
import datetime
import hashlib
import json
import pathlib
import sys

COUPON = {
    "id": "coupon-parser-017",
    "claim": "empty input should raise ParseError, not return None",
    "failing_assert": "assert parse('') is not None",
    "must_name": ["parseerror", "assert"],
    "forbidden": ["rewrite the module", "change the public type"],
}

def score_note(note: str, coupon: dict) -> dict:
    text = " ".join(note.lower().split())
    names = {token: (token in text) for token in coupon["must_name"]}
    names["none"] = "none" in text
    wandered = [phrase for phrase in coupon["forbidden"] if phrase in text]
    passed = all(names.values()) and not wandered
    return {
        "coupon_id": coupon["id"],
        "passed": passed,
        "names": names,
        "wandered": wandered,
        "note_sha256": hashlib.sha256(note.encode("utf-8")).hexdigest(),
        "scored_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
    }

def explain(result: dict) -> str:
    if result["passed"]:
        return "stamp accepted: names present, fence held"
    parts = [f"missing {key}" for key, ok in result["names"].items() if not ok]
    if result["wandered"]:
        parts.append("left the card: " + ", ".join(result["wandered"]))
    return "; ".join(parts) if parts else "rejected"

def main() -> int:
    note_path = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else "note.txt")
    result = score_note(note_path.read_text(encoding="utf-8"), COUPON)
    result["summary"] = explain(result)
    print(json.dumps(result, ensure_ascii=True))
    return 0 if result["passed"] else 1

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

A fixture note is part of the artifact, not a consolation prize. A student who never reaches a model still finishes the hour. That split is the point of a coupon. The network is a second heat, not the stock.

python3 -m venv .venv
. .venv/bin/activate
printf '%s\n' "Empty input raises ParseError. The failing line is assert parse('') is not None. Keep the public type." > note.txt
python coupon_check.py note.txt
echo "pass fixture exit=$?"
printf '%s\n' "Rewrite the module and change the public type so the test goes green." > note-bad.txt
python coupon_check.py note-bad.txt
echo "fail fixture exit=$?"

The first command should exit 0 and set passed to true. The second should exit 1, set passed to false, and list the forbidden phrases under wandered. If either result flips, the class stops and reads the scorer before anyone mentions a model. A press that cannot reject a bad strip is not a press.

Live drafting sits behind that gate. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode enters as the bench for an optional second heat, not as the thing the coupon is trying to prove. Notes supplied for this workshop say the project offers free model access and a free server option.

Those sentences are availability claims. They are not a named model, not a token quota, not a hardware list, and not a promise that the window stays open next term. An older post that cites a grant size is the wrong instrument for this hour, because grants move and a copied number goes stale. The instructor opens the project documentation on the morning of class and writes the day's limits on the board in plain sentences.

If the board and the page disagree, the page wins. If the page is silent, the class stays on fixtures. No key belongs in the repository. A free server, when that option is actually open, can host the rerun script and the note log for the room. It is a shared bench, not a locker for production credentials, and not evidence that the parser is correct.

# live_note.py
# Unexecuted sketch. Wire it only after the class reads that day's docs.
def draft_note(prompt: str) -> str:
    raise NotImplementedError(
        "Connect free model access using the client documented on class day."
    )

The prompt such a sketch would send is the coupon card in a few lines, plus the assert, plus an instruction to refuse work outside the card. Students save the raw note and run the scorer on it. The model does not score itself. Generation can be cheap enough, on a free-access bench, to throw away. Judgment stays in a function the room can read, diff, and fail on purpose.

Reading the stamp fills the next stretch of the hour. A pass means the note named ParseError, named the assert, mentioned None, and stayed inside the fence. It does not mean the parser is fixed, and it does not mean the model understood the grammar. It means this note, hashed and timed, would not embarrass the card.

A fail is just as useful. Wandered phrases mean the note tried to leave the coupon and redesign the part. Missing names mean the note was fluent and empty. Either result is appended to a log the class can diff on Tuesday.

python coupon_check.py note.txt >> coupon-log.jsonl
python coupon_check.py note-bad.txt >> coupon-log.jsonl

Append-only is a teaching choice, not a storage fashion. Students who overwrite yesterday's stamp learn how to hide a miss. Keeping the miss beside the pass shows whether the procedure is stable or merely lucky. The lowercase fold inside the scorer deserves the same kind of attention.

ParseError and a lowercase spelling collapse to one token, which is friendly to tired typing, and also a hole. A note can say the word and still describe the wrong branch. Closing that hole is a follow-on exercise. Add a fixture that uses the right words in the wrong story, and make the scorer reject it. The press gets stricter only when a bad strip fails in public.

Limits belong on the same card as the claim. Free model access can be rate-limited, queued, region-gated, or closed without a classroom's permission. A free server can be full, slow, or simply not offered that week. The workshop is mis-built if those conditions cancel the hour, so the fixture path is the hour and the live path stays optional.

Keyword scoring can accept a clumsy note and reject a careful one that says empty-string exception instead of ParseError. That is a property of this press. The honest response is another fixture, not a speech about intelligence, and not a longer prompt full of pleading.

Some rooms should skip the live heat entirely. A course whose data rule forbids third-party prompts stays on fixtures. An air-gapped lab stays on fixtures. A team that needs a reviewed vendor, a retention schedule, or an uptime clause should not treat a free option as that contract.

Anyone about to paste a customer payload, an access token, or a production traceback into the prompt should leave the exercise. The coupon is a teaching strip. It is not a side door into someone else's system, and it is not a merge approval with extra steps.

The maintainer in the Monday story did not need a longer chat transcript. The useful object was a marked strip, a dull press, and a log that still made sense on Tuesday. Readers who want the optional heat can look up MonkeyCode's current free model access and free server option, write that day's limits on a card, and only then replace the fixture note. The scorer does not change when the heat changes.

The Dry-Run Card Workshop

Charlie Zhu — Fri, 09 Oct 2026 13:29:01 +0000

A borrowed classroom on a weeknight has a particular silence. Twelve chairs face a projector, the building Wi-Fi is already tired, and the only machine that can run the class exercise belongs to a free server option nobody on the teaching team administers. The model route is free as well, which is why it was chosen. The transcript that seemed to prove it worked came from a different prompt, on a different day, in a different account.

That transcript is not a fixture. A dry-run card is the scrap a shop clips to a job before the first cut, and it records whether a known prompt, a known expectation, and a known runner still agree. This workshop spends ninety minutes teaching that habit, with a Python probe pairs can rerun from an empty directory.

MonkeyCode enters the hour only as one live route an operator may already have, with free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The exercise stays useful if that name is removed. Any documented HTTP route, and any short-lived remote shell the instructor is allowed to touch, can fill the same two blanks.

A bench, not a promise

Free capacity resembles a loaner lathe. It lets a small group start without buying iron, and it can be claimed by someone else, slowed by a queue, or withdrawn when the offer changes. This draft names neither models nor token allowances, and it names neither hardware nor an end date. Those figures move, and no primary source for them was attached here, so the card treats them as observations students write in the morning rather than as facts copied from an older post.

A portfolio page thrown together in an afternoon can look finished while the runner underneath was never probed. The pressure to ship that kind of surface is easy to recognize. The remedy in this room is narrower than a debate about taste: a fit check small enough to finish before the building closes.

How the ninety minutes are cut

The first ten minutes are rules, spoken once and written on the board. Keys stay in the shell, never in the repository, and production hostnames stay out. Homework and customer text stay out of prompts. The only statuses the room will accept are offline_pass, live_pass, live_skip, and fail.

A skip is a result. It means the live bench was not configured, or the network refused the favor. A skip is not a pass wearing a softer word.

The following fifteen minutes build the card as data rather than as a slide. Each pair agrees on a task id, a prompt, a short expected substring, a timeout, and a field for the runner. The prompt in the worked example asks for the digits of a sum a human can check without a model. That modesty is intentional, because a workshop that opens with a framework migration will spend the hour debugging the exercise instead of the probe.

From minute 25 to minute 50, pairs type the probe and run the offline path. The script is a worked example for Python 3.11 with only the standard library. It was not executed against a live MonkeyCode deployment for this article, and the offline branch is the part students can rerun on a train. The live branch is opt-in, and a missing variable fails closed.

#!/usr/bin/env python3
"""Dry-run card probe. Offline fixture always runs. Live mode is opt-in.

Teaching example only. Not executed against a live vendor deployment
when these notes were written. The /probe path is a seam, not an API claim.
"""

from __future__ import annotations

import hashlib
import json
import os
import shlex
import subprocess
import sys
import urllib.error
import urllib.request
from datetime import datetime, timezone

CARD = {
    'task_id': 'sum-two-ints',
    'prompt': 'Reply with only the digits of 17+25.',
    'expect': '42',
    'timeout_s': 20,
}


def prompt_hash(text):
    return hashlib.sha256(text.encode('utf-8')).hexdigest()[:12]


def offline_model(prompt):
    if prompt == CARD['prompt']:
        return '42'
    return 'unsure'


def live_model(prompt):
    base = os.environ['MODEL_BASE_URL'].rstrip('/')
    token = os.environ['MODEL_API_TOKEN']
    body = json.dumps({'prompt': prompt, 'max_tokens': 16}).encode('utf-8')
    req = urllib.request.Request(
        base + '/probe',
        data=body,
        headers={
            'Authorization': 'Bearer ' + token,
            'Content-Type': 'application/json',
            'Accept': 'application/json',
        },
        method='POST',
    )
    with urllib.request.urlopen(req, timeout=CARD['timeout_s']) as resp:
        payload = json.loads(resp.read().decode('utf-8'))
    return str(payload.get('text', '')).strip()


def runner_check():
    raw = os.environ.get('RUNNER_CMD', '').strip()
    if not raw:
        return {'status': 'live_skip', 'detail': 'RUNNER_CMD unset'}
    argv = shlex.split(raw)
    try:
        done = subprocess.run(
            argv,
            check=False,
            capture_output=True,
            text=True,
            timeout=CARD['timeout_s'],
        )
    except (OSError, subprocess.TimeoutExpired) as exc:
        return {'status': 'fail', 'detail': type(exc).__name__}
    text = (done.stdout or '').strip()
    ok = done.returncode == 0 and CARD['expect'] in text
    return {
        'status': 'live_pass' if ok else 'fail',
        'exit_code': done.returncode,
        'detail': text[:80],
    }


def judge(text):
    return 'pass' if CARD['expect'] in text else 'fail'


def main():
    mode = os.environ.get('PROBE_MODE', 'offline')
    error = ''
    try:
        if mode == 'live':
            answer = live_model(CARD['prompt'])
            model_status = 'live_' + judge(answer)
            runner = runner_check()
        elif mode == 'offline':
            answer = offline_model(CARD['prompt'])
            model_status = 'offline_' + judge(answer)
            runner = {'status': 'live_skip', 'detail': 'offline mode'}
        else:
            answer = ''
            model_status = 'fail'
            error = 'bad_mode'
            runner = {'status': 'live_skip', 'detail': 'bad mode'}
    except (KeyError, urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
        answer = ''
        model_status = 'fail'
        error = type(exc).__name__
        runner = {'status': 'live_skip', 'detail': 'model probe failed closed'}

    card = {
        'task_id': CARD['task_id'],
        'prompt_hash': prompt_hash(CARD['prompt']),
        'mode': mode,
        'model_status': model_status,
        'answer_excerpt': answer[:40],
        'error': error,
        'runner': runner,
        'recorded_at': datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'),
    }
    json.dump(card, sys.stdout, indent=2)
    sys.stdout.write('\n')
    model_ok = model_status.endswith('pass')
    runner_ok = runner['status'] in ('live_pass', 'live_skip')
    return 0 if model_ok and runner_ok else 1


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

Students run the offline cut before they touch a network. A healthy card shows model_status of offline_pass and a runner status of live_skip. That second field stops a pair from claiming they tested a free server when they only tested a dictionary in a file.

python3 dry_run_card.py > offline-card.json
echo exit:$?
python3 -m json.tool offline-card.json > /dev/null

The live cut stays in the operator's own shell. The example host is intentionally invalid, and pairs substitute the base URL from documentation they opened that morning. If MonkeyCode is the route in use, that documentation is the source for the path, the auth header, and whether a free server is currently offered. The script's /probe path is a teaching seam, not a claim about a real API.

export PROBE_MODE=live
export MODEL_BASE_URL=https://example.invalid/v1
export MODEL_API_TOKEN=replace-me
export RUNNER_CMD='python3 -c print(17+25)'
python3 dry_run_card.py > live-card.json
echo exit:$?

During class, RUNNER_CMD may be that local Python process, so a pair without SSH can still finish. A real free server, when the morning's notes say one exists, should be an instructor-supplied wrapper such as a BatchMode SSH command written on the board from that day's access sheet. This article does not invent the host, the user, or the flags. A wrapper that echoes the token, or that sends student homework to the runner, fails the shop rules even if the sum comes back right.

From minute 50 to minute 70, pairs sabotage their own fixture. They change the expected substring, unset the token, and point RUNNER_CMD at a command that exits nonzero. The model field and the runner field are allowed to fail separately. A courteous sentence that happens to contain the digits does not mean the free server executed anything, and a server that prints those digits does not mean the model route is awake.

unset MODEL_API_TOKEN
PROBE_MODE=live python3 dry_run_card.py > failed-card.json
echo exit:$?

During that window the instructor walks the aisle with a paper copy of the card fields, not with a laptop full of answers. One pair will point the runner at a pipeline and discover that shlex refused the meaning they wanted from a pipe character. That refusal is the correct lesson. A free server is already a hallway the class does not own, and smuggling a shell pipeline into it on the same afternoon undoes the card.

Another pair will want to paste a class assignment into the prompt to make the demo feel real. The instructor sends them back to 17+25. Realism can wait until the gauge is boringly repeatable. A workshop that starts with an interesting bug usually ends with an interesting excuse.

The closing twenty minutes convert the card into a scheduling decision. Tomorrow's exercise may depend on the live route only when an offline pass is fresh and a live pass was recorded after the documentation check. A live skip means the assignment needs the offline fallback this workshop already is. A fail means the prompt shrinks, or the class edits by hand, because a borrowed bench can be busy.

Comparing two cards after a blip

A network blip around minute 60 is part of the lesson, not an interruption to apologize for. Pairs save the first offline card, run the live probe, and compare four fields only: mode, model status, runner status, and prompt hash. The hash is the mark that both cards describe the same prompt. A live card with a different hash is a different job, and it does not retire the offline result.

import json

def load(path):
    with open(path, encoding='utf-8') as handle:
        return json.load(handle)

def main():
    off = load('offline-card.json')
    live = load('live-card.json')
    same = off['prompt_hash'] == live['prompt_hash']
    print('same_prompt', same)
    print('offline', off['mode'], off['model_status'], off['runner']['status'])
    print('live', live['mode'], live['model_status'], live['runner']['status'])

if __name__ == '__main__':
    main()

python3 compare_cards.py

The comparison may be read even when the live process exited nonzero, which is why the room saved the JSON before trusting the exit code. That reading stays in the classroom. A gate in a shared pipeline should keep the nonzero exit, or a red probe will look green because someone added a shell bypass and forgot to take it out.

What the probe refuses to pretend

The substring check is a blunt gauge. It accepts the expected digits buried in a paragraph, and an exact-match variant will reject a trailing newline. Both are teaching choices, and neither certifies a patch, a migration, or a portfolio project. Pairs who want a harder second hour can require equality on a hash of the answer, then watch harmless formatting become a fail.

That frustration belongs in the workshop. It is cheaper there than in a gradebook. The runner hook splits a command the pair typed during class, and the instructor should say, while that command is still on the board, that the same pattern is a liability inside a service.

A card that executes text returned by a model is no longer a card. Adapting the request body to the documented call is part of the exercise. A mismatch should fail the card, because papering over it with a looser assertion teaches the wrong shop habit.

Who should leave this hour on the bench

An air-gapped course that must keep student source in the room should not aim prompts at a hosted model, free or otherwise. A team that needs a contract, a named region, or a budget it can forecast should rent or own the bench and write the allowance into a document it controls. Production deploys, credential handling, and any grade that cannot be repeated if the runner vanishes midweek sit outside this card. A community lab can live with a skip, and an on-call rotation cannot.

The operator describes the project as open source. The tree, when the class is actually using that route, is reading material and a place to file a mismatch. It is not a substitute for that morning's status page. Install steps belong to the tree's current instructions, and this article does not paraphrase them, because a paraphrased install is how a workshop inherits last month's flags.

Readers who already have a MonkeyCode account can aim the live probe at that route after they replace the teaching seam with the documented call. The offline fixture should stay in the repository either way. The next room can still finish the hour when the courtesy bench is closed.

The Checkpoint Workshop: Resumable Batch Runs in 90 Minutes

Charlie Zhu — Thu, 08 Oct 2026 09:25:29 +0000

It is 3 a.m. in the lab, and a batch of 412 prompt jobs dies at item 271. The terminal holds a partial traceback; the disk holds nothing. The next run starts at prompt one and pays for two hundred and seventy calls a second time. This workshop is built around that single failure and the smallest artifact that prevents it: an append-only ledger plus a key derived from the job itself.

The session runs ninety minutes. Students leave able to kill a process with kill -9 in the middle of a batch and then prove, with a script, that the resumed run produced neither a gap nor a duplicate.

What the lab assumes

Every student needs a machine with Python 3.9 or newer, two input files, and an HTTP JSON model endpoint configured through two environment variables. Nothing else is installed. No queue, no database, no orchestration layer, because the point of the exercise is that the durable part is a text file.

For the reference run the endpoint points at MonkeyCode. The project's operator describes it as providing free model access and a free server option, which matters here for a mundane reason: a ninety-minute lab where the long-running process has somewhere to live beats a lab where half the room is still provisioning. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Treat every number about that free tier as moveable. The operator states the free tier carries up to 10 million tokens, and that a free server option is available; quotas, model availability, and server terms change, so read the project's current documentation rather than a blog post from any month, including this one. The code below is a teaching artifact written for the lab. I have not benchmarked it, and the timings are teaching budgets rather than measured results.

The artifact: one line per finished job

The design is deliberately boring. Each completed job appends one JSON line to ledger.jsonl, flushed and fsynced before the runner moves on. The job's identity is a hash of its own payload, so the same job presented twice produces the same key. On restart the runner reads the ledger into a set and skips anything already in it.

jobs.jsonl looks like this:

{"id": "j-001", "prompt": "Summarise this changelog entry in one line: ..."}
{"id": "j-002", "prompt": "Rewrite this error message for a non-technical reader: ..."}

The runner is about forty lines. The request and response shapes depend on the endpoint, so students adapt call_model first and leave the ledger logic alone.

# runner.py -- teaching artifact, not production code
import hashlib, json, os, time, urllib.request
from pathlib import Path

LEDGER = Path("ledger.jsonl")
JOBS = Path("jobs.jsonl")
MODEL_URL = os.environ["MODEL_URL"]
API_KEY = os.environ.get("MODEL_KEY", "")


def key_of(job: dict) -> str:
    payload = json.dumps(job, sort_keys=True, separators=(",", ":"))
    return hashlib.sha256(payload.encode()).hexdigest()[:16]


def load_done() -> set:
    done = set()
    if not LEDGER.exists():
        return done
    for line in LEDGER.read_text(encoding="utf-8").splitlines():
        if not line.strip():
            continue
        try:
            record = json.loads(line)
        except json.JSONDecodeError:
            continue  # torn final write; let the job run again
        if record.get("status") == "ok":
            done.add(record["key"])
    return done


def append(record: dict) -> None:
    with LEDGER.open("a", encoding="utf-8") as fh:
        fh.write(json.dumps(record, sort_keys=True) + "\n")
        fh.flush()
        os.fsync(fh.fileno())


def call_model(prompt: str, timeout: int = 60) -> str:
    body = json.dumps({"prompt": prompt}).encode()
    req = urllib.request.Request(
        MODEL_URL,
        data=body,
        headers={"Content-Type": "application/json",
                 "Authorization": f"Bearer {API_KEY}"},
    )
    with urllib.request.urlopen(req, timeout=timeout) as resp:
        return json.loads(resp.read())["text"]


def run_one(job: dict) -> None:
    k = key_of(job)
    last_error = None
    for attempt in range(4):
        try:
            out = call_model(job["prompt"])
            append({"key": k, "job": job.get("id"), "status": "ok", "output": out})
            return
        except Exception as exc:  # noqa: BLE001 -- lab code on purpose
            last_error = exc
            time.sleep(2 ** attempt)
    append({"key": k, "job": job.get("id"),
            "status": "error", "error": str(last_error)})


def main() -> None:
    done = load_done()
    for line in JOBS.read_text(encoding="utf-8").splitlines():
        if not line.strip():
            continue
        job = json.loads(line)
        if key_of(job) in done:
            continue
        run_one(job)


if __name__ == "__main__":
    main()

Notice that load_done only counts records whose status is ok. Error records still land in the ledger for forensics, but they stay eligible for a later run. That single conditional is the difference between a retry policy and a silent data hole.

The ninety minutes

Minutes	Segment
0-10	The 3 a.m. crash: what a lost batch actually costs
10-25	Read the ledger format, run forty jobs end to end
25-45	Exercise 1: `kill -9` and resume
45-60	Exercise 2: the torn write
60-75	Exercise 3: two workers, one ledger
75-90	Debrief: what belongs in a record and what does not

Exercise 1: crash and resume

Students start the runner in the background, wait for a few seconds of work, and kill it hard.

python runner.py &
PID=$!
sleep 25
kill -9 $PID
wc -l ledger.jsonl    # some completed jobs, no summary
python runner.py      # resumes

The proof step is the part that matters. Counting lines is not evidence, because duplicates also add lines.

python - <<'PY'
import collections, json
keys = [json.loads(l)["key"] for l in open("ledger.jsonl") if l.strip()]
c = collections.Counter(keys)
print("lines", len(keys), "unique", len(c))
print("duplicates", [k for k, v in c.items() if v > 1])
PY

A clean run reports matching counts and an empty duplicate list. When a pair does appear, it is usually because the killed process had already sent the request and the restart sent it again before any ledger line existed; the fix is a claim file, which is Exercise 3.

Exercise 2: the torn write

kill -9 can land in the middle of fh.write, leaving a truncated last line. Students reproduce this deterministically without racing anything.

head -c -25 ledger.jsonl > ledger.tmp && mv ledger.tmp ledger.jsonl
python runner.py

The JSON parse fails on the final line, load_done skips it, and the corresponding job reruns. Nobody has to reason about it in the abstract; they watch the line count grow by one and the duplicate check stay clean. The lesson worth writing on the board: a reader that tolerates garbage is more valuable than a writer that promises never to produce it.

Exercise 3: two workers, one ledger

Two terminals, one ledger, no coordination.

python runner.py & python runner.py &
wait

Both processes read the same "done" set, both see the same missing key, and both call the model. The ledger now holds two records for one job. The repair is an exclusive claim created before the network call.

def claim(k: str) -> bool:
    os.makedirs("claims", exist_ok=True)
    try:
        fd = os.open(f"claims/{k}", os.O_CREAT | os.O_EXCL | os.O_WRONLY)
    except FileExistsError:
        return False
    os.close(fd)
    return True

Then have the class break it again by killing a worker between the claim and the ledger append. The claim file survives, the job never reruns, and the batch quietly loses a result. That trade-off is the real content of the exercise: exclusivity buys you no duplicates and costs you a stale-claim policy, usually a timestamp older than a few minutes that may be reclaimed.

When a ledger is not worth the trouble

Situation	Ledger?	Reason
Forty jobs, two seconds each	No	Rerunning the batch is cheaper than maintaining state
Four hundred jobs, a minute each	Yes	Losing halfway through costs hours
Side effects outside the ledger	Only with idempotent side effects	A key stops duplicate calls, not duplicate emails
Regulated or personal data	Not in plaintext	Hash the prompt for the key; store raw text only where policy allows
The only copy lives on a free host	Risky	Convenience is not durability

The last row deserves the most discussion. A free server option is a fine place to run a ninety-minute lab, and a poor place to keep the only record of a week-long run. Ledgers belong on storage you control, with the compute pointed at it.

Who should skip this

If the work is interactive, with a human reading each answer before the next call, the ledger costs more attention than it saves. If the pipeline writes to a customer system, hashing the input is not enough, because the side effect itself has to be idempotent. If the batch carries personal data, a plaintext JSONL file on a shared machine is a compliance problem, not an engineering one. And if the team has no place to keep the ledger, the honest answer is to fix that before writing the runner.

Early finishers should spend the remaining time attacking the artifact rather than admiring it: kill the process during fsync, put the ledger on a network path two machines share, and watch what the append does. Breaking the file teaches more than the happy path ever will.

The real output of the workshop is not runner.py. It is the habit of asking, before a long run starts, what the world looks like when it dies at item 271. Free model access and a free server option lower the cost of setting that lab up, so check the current limits before you schedule the session, and keep the fixture set small enough that a rerun is never a crisis.

The Tryout Plate Workshop

Charlie Zhu — Thu, 08 Oct 2026 06:51:33 +0000

At 9:10 the lab is already warm. A student has a green test line from an agent run and a finger resting on the merge control, the way a press operator rests a hand on the cycle button before the die has been proved. The instructor sets a scratched plate on the bench. Nothing that looks like production steel gets cut until that plate says the die is true.

This workshop runs ninety minutes. Every student leaves with a checker that reruns on a clean laptop, against a directory of ordinary files. The class does not grade the agent's prose. It grades whether a small change survived a fixed plate: allowed files only, tests actually executed, a stop reason written down, and no secret-shaped string in the diff.

Free model access makes the first attempt cheap. A cheap attempt is also how an unreviewed patch reaches a shared branch. The plate exists so the cheap attempt still has to pass a gauge.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is the open-source project this bench points at, because the operator states that free model access and a free server option are available. The handout does not bake in a token count, a model name, or a rental duration. Those figures move, and a number copied from an old post is how a lab lies to itself.

Ten minutes before the room starts, the instructor opens the current project documentation and writes the live limit on the whiteboard. If the page and a slide disagree, the page wins. Students who cannot see that page do not guess. They skip the hosted run and still complete the local plate.

The plate is a tiny fixture, not a tour of a framework. Students receive two files that already pass, plus one file the agent may touch. The task is dull on purpose. A function clamp_span should reject an inverted range and return the clipped length. A tryout plate that already contains a clever bug teaches the die, not the checker.

def clamp_span(start: int, end: int, limit: int) -> int:
    if limit < 0:
        raise ValueError("limit")
    if end < start:
        raise ValueError("span")
    return min(end, start + limit) - start

The matching test file is short enough to read standing up. Students run it before any agent is allowed near the tree.

import unittest
from clamp_span import clamp_span

class ClampTests(unittest.TestCase):
    def test_clips(self):
        self.assertEqual(clamp_span(0, 10, 4), 4)

    def test_inverted(self):
        with self.assertRaises(ValueError):
            clamp_span(5, 1, 4)

if __name__ == "__main__":
    unittest.main()

The agent may edit only clamp_span.py. Tests live in test_clamp.py and stay read-only for the run. That split is the scribed line on the plate. A change that wanders into the tests is a failed tryout, even when the new tests glow green.

Students do not need a local GPU, and they do not paste a paid key into a shared lab image. They send the same dull task through MonkeyCode's free model access. Pairs whose laptops cannot host the loop use the free server option and bring the transcript back as files. The checker never calls the product.

It reads what the run left behind. That seam is the whole method. When the hosted path is down, the plate still grades a local stub, and the lesson survives. A workshop that only works while a vendor dashboard is green is a demonstration, not a plate.

The worked example is one Python file, tryout_plate.py. It is a sample to copy and rerun, and it is unexecuted until a student runs it on their own machine. Nothing in it depends on a vendor SDK.

A run directory holds report.json and diff.patch. The report is what the student, or a thin adapter, writes after the agent stops. The checker exits 0 only when every gate holds.

#!/usr/bin/env python3
"""Tryout-plate checker. Sample only until a student runs it locally."""
import json, re, sys
from pathlib import Path

ALLOWED = {"clamp_span.py"}
SECRET = re.compile(r"(?i)(api[_-]?key|secret|password)\s*[:=]\s*\S+")
MAX_LINES = 80

def main(run_dir: str) -> int:
    root = Path(run_dir)
    report = json.loads((root / "report.json").read_text())
    patch = (root / "diff.patch").read_text()
    reasons = []
    if report.get("tests_exit") != 0:
        reasons.append("tests_failed")
    if report.get("tests_ran") is not True:
        reasons.append("tests_not_executed")
    if not report.get("stop_reason"):
        reasons.append("missing_stop_reason")
    extra = set(report.get("files_touched", [])) - ALLOWED
    if extra:
        reasons.append("off_plate:" + ",".join(sorted(extra)))
    if SECRET.search(patch):
        reasons.append("secret_shaped_text")
    changed = sum(
        1 for line in patch.splitlines()
        if line.startswith("+") or line.startswith("-")
    )
    if changed > MAX_LINES:
        reasons.append("diff_over_plate")
    verdict = "pass" if not reasons else "fail"
    print(json.dumps({
        "verdict": verdict,
        "reasons": reasons,
        "changed_lines": changed,
    }))
    return 0 if verdict == "pass" else 1

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

A passing report is short. The JSON below is a fixture, not a log captured from a live server. Students replace it with their own export before they trust the exit code.

{
  "tests_ran": true,
  "tests_exit": 0,
  "stop_reason": "tests_green_and_allowlist_held",
  "files_touched": ["clamp_span.py"]
}

The matching patch is also a fixture. It is small enough to read aloud. The change is plausible, which is exactly why the plate must not be asked to bless it alone.

--- a/clamp_span.py
+++ b/clamp_span.py
@@ -1,4 +1,4 @@
-    return min(end, start + limit) - start
+    return max(0, min(end, start + limit) - start)

The command line is the whole ceremony. Two copies, one process, one exit code.

mkdir -p run && cp report.json diff.patch run/
python3 tryout_plate.py run
echo "exit=$?"

A zero means the plate accepted this tryout. It does not mean the function is correct for every integer. It does not mean a reviewer can skip the diff.

The checker never executes the patch. Students still run the unit test themselves and write tests_exit from that process, not from the agent's claim. The second command is the gauge the first command only reads.

python3 -m unittest test_clamp.py
echo "tests_exit=$?"

An agent that announces success without a process exit code fails the plate on tests_not_executed. Speech is not a gauge. That single gate is the workshop's real lesson.

A false pass has a smell the room learns to name. The checker printed pass, unittest exited zero, and the diff still looks wrong because max(0, ...) changed a legal span that was already inside the limit. The plate did not lie. The fixture was too thin.

Students add one assertion, self.assertEqual(clamp_span(2, 5, 10), 3), rerun unittest, and only then copy the new exit code into report.json. The repair is a better plate, not a softer gate. A hosted model is not invited to edit the test in order to make the smell go away.

The ninety minutes move in five beats. The first ten belong to the scene: a green badge is not a merge, and the live documentation, not a blog number, sets the free-tier bound for the day. The next fifteen belong to the fixture.

Students run the unit test once, then confirm the checker fails closed when report.json is missing. Failure closed is the behavior they want before any model is involved. A missing file that exits zero would train the room to trust silence.

From minute twenty-five to minute fifty, each pair sends the fixed task through free model access. The prompt stays dull. Fix clamp_span so a negative span raises, keep the edit inside clamp_span.py, stop when unittest exits zero, and write the stop reason into report.json.

Pairs may not improve the prompt. A tryout that changes the ask is a different die. Pairs on small laptops use the free server option for that same prompt and download the transcript when the run stops.

The next twenty minutes are scoring. Each pair runs the checker, then breaks one gate on purpose: a second file in files_touched, a true tests_ran with no local unittest, or a patch that contains a made-up key. Three failures, three reasons, then one pass restored by reverting the break.

The last twenty minutes name what a hosted log can hide, and what this plate cannot see. A logic bug that still exits zero walks straight through. The plate catches process lies and boundary violations.

It does not catch wrong but plausible arithmetic. A human still reads the diff before anything leaves the lab branch. The free server made the attempt easy to repeat. It did not make the reading optional.

Two exercises are enough for a later rerun. Exercise A takes fifteen minutes. Delete stop_reason, confirm the verdict flips to fail, then restore the field.

Exercise B takes twenty minutes. Point the same checker at a second run directory from the free server, without editing the gates. If the export shape differs, students write a short adapter that emits report.json.

Adapters may change shape. Gates stay boring. A third, optional pass takes ten minutes the next morning: run the checker on an empty directory and confirm it raises rather than printing pass. Fail closed, even when the room is in a hurry.

This approach is a lab plate, not a release process. It should not be used on repositories that hold credentials, customer data, or unpublished vulnerability detail. A free server is still a remote machine, and this article does not claim a retention policy, an isolation guarantee, or a permanent quota. Read the current terms before any file leaves the laptop.

Teams that need a named model build, an attested log, or a fully offline room should not depend on a free hosted option for the run. They can still reuse the checker. Instructors who want a leaderboard will be disappointed.

The script records pass or fail for one fixture. It does not measure tokens, latency, or model rank, and those numbers are not invented here to fill a chart. A class that needs those measurements should design a separate bench, with clocks they control, after this plate is already boring.

The same plate refuses a certain optimism. Free model access removes the excuse that only one student could afford to try. It does not remove the need for a stop condition that a second process can see.

An earlier workshop on this account taught an agent loop how to stop. This one teaches the room to notice when the stop was only a sentence. The die is proved on the plate, or it is not proved.

Readers who want that split — a hosted attempt, a local grade — can check MonkeyCode's current free model access and free server option, copy the live limits onto a whiteboard, and rerun tryout_plate.py against a directory they produced themselves. The plate stays useful if another runner is swapped in. That is the property a toolroom actually keeps.

The Witness Mark Workshop

Charlie Zhu — Thu, 24 Sep 2026 19:31:12 +0000

A Friday handoff failed in a quiet way. The agent run had stopped, the ticket was still open, and the only note in the log was the word done. The next maintainer could not tell whether the job had finished, stalled on a constraint, or been cut short by a person. In a machine shop, a witness mark is the thin remaining line that shows where the cutter actually traveled, and a transcript without that line forces the next shift to guess.

This workshop spends 75 minutes on the habit. Six students share one fixture, a JSONL note, and a small Python checker. They do not tune a model, and they do not chase a score. They practice leaving a mark that a partner can rerun without a hallway conversation.

The lesson stays useful on a laptop with the standard library. A hosted bench is optional, and it is not the grader.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. The only product claims used here are operator-supplied: free model access, and a free server option, either of which can serve as that spare bench when a class wants a second place to draft a messy note. Quotas, model names, hardware, and duration are omitted because they were not verified for this draft.

The first ten minutes stay on paper. The instructor reads the night-shift note aloud and requires a card with five fields: intent, constraint, evidence, stop reason, and the exact command a stranger would type. Vague praise is rejected in the room before it can hide inside a file. Students hear the difference between a status word and a mark while the keyboard is still closed.

Minutes ten through thirty move to disk. Each student creates the bad twin, runs the checker, and writes the faults in ordinary words before editing anything. The repaired twin is the worked example, saved as a single JSONL line so a cold machine can rerun it.

mkdir -p samples
cat > samples/night_shift.jsonl << 'EOF'
{"intent":"close ticket 441","constraint":"stop on a repeated error","evidence":"looks fine","stop_reason":"done","rerun_command":"python3 witness_mark.py samples/night_shift.jsonl"}
EOF
cat > samples/repaired.jsonl << 'EOF'
{"intent":"close ticket 441 by confirming the retry budget","constraint":"stop if the same error id appears twice","evidence":"error_id=E17 count=2 at log line 88","stop_reason":"stopped after E17 repeated at line 88, before a third retry","rerun_command":"python3 witness_mark.py samples/repaired.jsonl"}
EOF
python3 witness_mark.py samples/night_shift.jsonl
python3 witness_mark.py samples/repaired.jsonl

A held file prints HOLD and leaves a non-zero exit. A cleared file prints CLEAR and then the line all marks clear. The contrast is the point of the half hour. One note can be replayed by a stranger, and the other only sounds finished.

The checker is a proposal for the room. It is not a production auditor, and it has not been scored against a live corpus. Failing output is a teaching signal, not a certificate. The fixture expects Python 3.9 or newer, because the annotations use built-in generic types.

#!/usr/bin/env python3
"""Proposal: classroom witness-mark checker. Not a production auditor."""

import json
import sys
from pathlib import Path

VAGUE = {"done", "ok", "fixed", "success", "completed", "finished", "lgtm"}
REQUIRED = ("intent", "constraint", "evidence", "stop_reason", "rerun_command")

def load_marks(path: Path) -> list[dict]:
    rows = []
    for lineno, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
        text = line.strip()
        if not text:
            continue
        try:
            row = json.loads(text)
        except json.JSONDecodeError as exc:
            raise SystemExit(f"{path}:{lineno}: invalid json: {exc}") from exc
        if not isinstance(row, dict):
            raise SystemExit(f"{path}:{lineno}: expected an object")
        row["_line"] = lineno
        rows.append(row)
    if not rows:
        raise SystemExit(f"{path}: no marks")
    return rows

def judge(row: dict) -> list[str]:
    faults = []
    for key in REQUIRED:
        value = row.get(key)
        if not isinstance(value, str) or not value.strip():
            faults.append(f"missing {key}")
    reason = str(row.get("stop_reason", "")).strip().lower().rstrip(".")
    if reason in VAGUE:
        faults.append("stop_reason is a slogan, not a mark")
    elif len(reason.split()) < 8:
        faults.append("stop_reason needs a verb, an object, and a boundary")
    evidence = str(row.get("evidence", ""))
    if evidence and not any(ch.isdigit() for ch in evidence):
        faults.append("evidence should name a line, id, or count")
    command = str(row.get("rerun_command", "")).strip()
    if command and not (
        command.startswith("python3 ")
        or command.startswith("pytest ")
        or command.startswith("./")
    ):
        faults.append("rerun_command must be a local python3, pytest, or ./ command")
    return faults

def main() -> None:
    if len(sys.argv) != 2:
        raise SystemExit("usage: python3 witness_mark.py <marks.jsonl>")
    path = Path(sys.argv[1])
    failed = 0
    for row in load_marks(path):
        faults = judge(row)
        label = f"{path}:{row['_line']}"
        if faults:
            failed += 1
            print(f"HOLD {label}")
            for fault in faults:
                print(f"  - {fault}")
        else:
            print(f"CLEAR {label}")
    if failed:
        raise SystemExit(f"{failed} mark(s) held")
    print("all marks clear")

if __name__ == "__main__":
    main()

A held note is not an insult. It means the next person would have to invent a story. The instructor walks the room once and refuses oral rescues, because a reason that cannot survive in the file cannot survive the shift change. Clever chat does not count as a witness mark, any more than a verbal claim counts on a bench where the layout line has been polished away.

The middle twenty minutes belong to the partner swap. Students exchange only the JSONL file, with no side thread and no shared screen. The partner reruns the command already written inside the note and decides whether the stop is understandable.

If the partner must ask what E17 means, the evidence field is still thin, even when the checker prints CLEAR. The script catches missing structure. It cannot catch a number that points at the wrong line. That gap is discussed on purpose, so nobody leaves believing a green line is the same thing as understanding.

The optional hosted pass takes the next ten minutes, and only if the spare bench is actually available. A student drafts one deliberately bad note there, copies it back, and runs the same local checker. The bench is not the grader. If access is missing, slow, or unfamiliar, the class skips the pass and stays with the two sample files.

The last fifteen minutes are the limitation review. The checker does not prove the agent was right. It only shows that the note has the fields a stranger needs in order to try the same command. Creative tasks and open-ended research will fight the required shape, and they should not be forced through it.

Teams that need a formal audit, a signed control, or a retention policy should not adopt this fixture as evidence. It stores whatever the student typed. Secrets, customer payloads, and private prompts do not belong in the JSONL, on a laptop or on a free server. A class without a human reviewer for this closing block will over-trust the word CLEAR.

The vague-word list needs the same honesty. The word done is banned because it hides the boundary, not because short writing is a moral failure. A precise five-word reason can be true and still fail the eight-word heuristic. Instructors should allow a paper override when the spoken review shows a real boundary that the script was too blunt to accept.

The heuristic is a teaching rail, not a law of clear writing. Empty notes were the problem in this room. Comments, as a habit, were not.

A solo developer who already writes replayable stop notes will learn little from the timing. A group that wants vendor benchmarks, model rankings, or a promised token budget will not find those measurements here, and should not invent them to fill the gap. The artifact is a note linter with a shop-floor rule: leave the line visible for the next person.

The closing move stays quiet. Each student keeps two files, the held note and the cleared note, beside the checker. Next week the same commands still run. That is the property the night shift needed.

Readers who want a spare bench for the optional pass can review MonkeyCode's current free model access and free server option, then confirm the live terms before a class depends on them.

The Routing Slip Workshop

Charlie Zhu — Wed, 23 Sep 2026 16:21:16 +0000

The night clerk at a rented machine shop kept a spike of yellow routing slips beside the crib window. Every bin that left the cage carried one. The mill stamped it. Inspection stamped it. Shipping would not tape a box that arrived with a blank trail. The paper was slower than a shout across the floor. It also survived the shout.

Tool-calling agents fail in that same hallway. A model emits a function name, a JSON body, and a calm pause. The runtime fires the HTTP request. Nothing records which station already ran, so the next turn asks again. The API is healthy. The slip is missing.

This lab period treats a tool call as a routing slip, not as a chatty side effect. Students leave with a validator they can rerun, a tiny parts-crib service, and a scripted agent that first violates the slip and then honors it. A live model is optional and comes last on purpose.

Shared history is the real teaching surface. Twenty laptops hitting localhost produce twenty private logs, and a private log cannot be put on a projector. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Instructors who want one crib URL for the whole room can run the service on MonkeyCode's free server option, and the optional live-calling close can use MonkeyCode's free model access. Those two availability claims are the only product facts used here. No model names, quotas, hardware, or runtimes are asserted.

The rest of the period is ordinary Python 3.11. Remove the product sentence and the slip still compiles.

The first twelve minutes are reading, not typing. Hand each student the same constraint: a parts crib that issues fasteners, and an agent that must not pull the same SKU twice in one job. The slip has four fields that actually bite. job_id ties the work. station names the current bench. seq is a monotonic integer. prev_hash is the SHA-256 of the previous slip body, or sixty-four zeros for the first stamp. Students who skip the reading write pretty JSON and still loop.

The next twenty-five minutes belong to the validator. The files below are the reference. Students type them, then break them on purpose. A slip with seq 3 that claims a prev_hash from seq 1 must fail. A second issue of SKU F-14 under the same job_id must fail. The instructor watches for people treating the hash as decoration. Decoration is how loops return.

Minutes thirty-eight to sixty-five are the crib service and the scripted agent. The agent is not a model. It is a Python loop with two canned plans, one sloppy and one stamped. That split is the pedagogy. If the first green test requires a hosted model, the room waits on network weather and nobody learns the contract.

The last fifteen minutes are optional live calling. Point a coding agent at the published schema and the crib URL. Do this only after the unit tests already fail and pass on cue. A model asked to invent the slip will invent a prettier slip. Prettier is not the lesson.

Save four files in one directory. No third-party packages. The lab uses the standard library so a borrowed classroom image is enough.

routing_slip.py is the paper. Canonical JSON is part of the contract, not a style choice, because extra whitespace would move every stamp.

from __future__ import annotations

import hashlib
import json
from dataclasses import dataclass
from typing import Any

ZERO = "0" * 64
ALLOWED_STATIONS = ("crib", "mill", "inspect", "ship")
ALLOWED_ACTIONS = ("issue", "stamp", "reject", "close")


def canonical(obj: Any) -> str:
    return json.dumps(obj, sort_keys=True, separators=(",", ":"))


def digest(obj: Any) -> str:
    return hashlib.sha256(canonical(obj).encode("utf-8")).hexdigest()


@dataclass(frozen=True)
class Slip:
    job_id: str
    station: str
    action: str
    seq: int
    sku: str
    qty: int
    prev_hash: str

    def body(self) -> dict[str, Any]:
        return {
            "job_id": self.job_id,
            "station": self.station,
            "action": self.action,
            "seq": self.seq,
            "sku": self.sku,
            "qty": self.qty,
            "prev_hash": self.prev_hash,
        }

    def stamp(self) -> str:
        return digest(self.body())


class SlipError(ValueError):
    pass


class Ledger:
    def __init__(self) -> None:
        self._slips: list[Slip] = []
        self._issued: dict[str, set[str]] = {}

    def accept(self, slip: Slip) -> str:
        if slip.station not in ALLOWED_STATIONS:
            raise SlipError(f"unknown station: {slip.station}")
        if slip.action not in ALLOWED_ACTIONS:
            raise SlipError(f"unknown action: {slip.action}")
        if slip.qty < 1 or slip.seq < 1:
            raise SlipError("qty and seq must be >= 1")

        if slip.seq == 1:
            if slip.prev_hash != ZERO:
                raise SlipError("first slip must chain from zero hash")
            if slip.station != "crib" or slip.action != "issue":
                raise SlipError("job must open at crib with issue")
        else:
            if not self._slips:
                raise SlipError("non-first slip with empty ledger")
            last = self._slips[-1]
            if slip.job_id != last.job_id:
                raise SlipError("job_id changed mid-route")
            if slip.seq != last.seq + 1:
                raise SlipError("seq is not monotonic")
            if slip.prev_hash != last.stamp():
                raise SlipError("prev_hash does not match last stamp")

        issued = self._issued.setdefault(slip.job_id, set())
        if slip.action == "issue" and slip.sku in issued:
            raise SlipError(f"sku already issued on this job: {slip.sku}")
        if slip.action == "issue":
            issued.add(slip.sku)

        self._slips.append(slip)
        return slip.stamp()

crib_server.py is the window. It keeps one ledger in memory and speaks a single POST route. Students should start it once and leave it running while the tests talk to it. Restarting it is a lesson of its own, because every stamp disappears.

from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import json
from urllib.parse import urlparse

from routing_slip import Ledger, Slip, SlipError

LEDGER = Ledger()


class CribHandler(BaseHTTPRequestHandler):
    def log_message(self, fmt: str, *args) -> None:
        # Keep the projector readable. Access noise hides SlipError text.
        return

    def _send(self, code: int, payload: dict) -> None:
        raw = json.dumps(payload).encode("utf-8")
        self.send_response(code)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(raw)))
        self.end_headers()
        self.wfile.write(raw)

    def do_POST(self) -> None:
        if urlparse(self.path).path != "/slip":
            self._send(404, {"ok": False, "error": "use POST /slip"})
            return
        length = int(self.headers.get("Content-Length", "0"))
        try:
            data = json.loads(self.rfile.read(length).decode("utf-8"))
            slip = Slip(
                job_id=str(data["job_id"]),
                station=str(data["station"]),
                action=str(data["action"]),
                seq=int(data["seq"]),
                sku=str(data["sku"]),
                qty=int(data["qty"]),
                prev_hash=str(data["prev_hash"]),
            )
            stamp = LEDGER.accept(slip)
        except (KeyError, TypeError, ValueError) as exc:
            self._send(400, {"ok": False, "error": str(exc)})
            return
        except SlipError as exc:
            self._send(409, {"ok": False, "error": str(exc)})
            return
        self._send(200, {"ok": True, "stamp": stamp})


if __name__ == "__main__":
    host, port = "127.0.0.1", 8765
    print(f"crib listening on http://{host}:{port}/slip")
    ThreadingHTTPServer((host, port), CribHandler).serve_forever()

agent_plans.py is the two-handed exercise. The sloppy plan looks helpful. It is not. The stamped plan is boring on purpose.

from __future__ import annotations

from routing_slip import ZERO, Slip

JOB = "job-4417"
SKU = "F-14"


def sloppy_plan() -> list[Slip]:
    first = Slip(JOB, "crib", "issue", 1, SKU, 8, ZERO)
    # Same SKU again, and the hash is theatre.
    second = Slip(JOB, "crib", "issue", 2, SKU, 8, ZERO)
    return [first, second]


def stamped_plan() -> list[Slip]:
    s1 = Slip(JOB, "crib", "issue", 1, SKU, 8, ZERO)
    s2 = Slip(JOB, "mill", "stamp", 2, SKU, 8, s1.stamp())
    s3 = Slip(JOB, "inspect", "stamp", 3, SKU, 8, s2.stamp())
    s4 = Slip(JOB, "ship", "close", 4, SKU, 8, s3.stamp())
    return [s1, s2, s3, s4]

test_routing_slip.py is the part that should survive after class. Run it with python -m unittest test_routing_slip.py -v. The double-issue test is the one to pin on the board.

import unittest

from agent_plans import sloppy_plan, stamped_plan
from routing_slip import Ledger, Slip, SlipError, ZERO


class RoutingSlipTests(unittest.TestCase):
    def test_stamped_plan_chains(self) -> None:
        ledger = Ledger()
        stamps = [ledger.accept(s) for s in stamped_plan()]
        self.assertEqual(len(stamps), 4)
        self.assertEqual(len(set(stamps)), 4)

    def test_double_issue(self) -> None:
        ledger = Ledger()
        first, second = sloppy_plan()
        ledger.accept(first)
        with self.assertRaises(SlipError):
            ledger.accept(second)

    def test_hash_mismatch(self) -> None:
        ledger = Ledger()
        first = Slip("job-9", "crib", "issue", 1, "A-1", 1, ZERO)
        ledger.accept(first)
        bad = Slip("job-9", "mill", "stamp", 2, "A-1", 1, ZERO)
        with self.assertRaises(SlipError):
            ledger.accept(bad)

    def test_stamps_are_stable(self) -> None:
        a = [s.stamp() for s in stamped_plan()]
        b = [s.stamp() for s in stamped_plan()]
        self.assertEqual(a, b)


if __name__ == "__main__":
    unittest.main()

Start the crib in one terminal with python crib_server.py. In another terminal a student can POST a slip with curl and watch 409 come back on the second issue. The status code is part of the teaching. Silent 200 responses are how duplicated fasteners leave the building.

python crib_server.py

curl -sS -X POST http://127.0.0.1:8765/slip \
  -H 'Content-Type: application/json' \
  -d '{"job_id":"job-4417","station":"crib","action":"issue","seq":1,"sku":"F-14","qty":8,"prev_hash":"0000000000000000000000000000000000000000000000000000000000000000"}'

The first plan issues F-14 twice and never stamps mill. The ledger throws SlipError, and that exception is the point. Students should read the error, not catch it into a retry that issues F-15. A retry that changes the SKU is how a shop loses inventory while the dashboard stays green.

The second plan opens at crib, chains the hash, stamps mill, stamps inspect, and closes at ship. The printed stamps should match across two reruns. If they drift, the canonical JSON helper was rewritten with extra whitespace. Hash drift is a contract bug, not a taste debate.

The block below is a proposed live prompt. It is unexecuted against any particular model, and it should stay unused until test_routing_slip.py is green on a cold run.

You may POST JSON slips to http://127.0.0.1:8765/slip.
You may not invent stations or skip inspect.
If the server returns 409, stop. Do not retry with a new SKU.
Job job-4417 needs SKU F-14 issued once, then mill, inspect, ship.
Chain prev_hash from the stamp in each 200 body.

The ledger lives in process memory. Restart the crib and the stamps vanish. That is acceptable for a lab and unacceptable for a warehouse. The hash is SHA-256 over canonical JSON, not a signature. Anyone who can POST can forge a slip. Do not put this on the public internet with real inventory, real tokens, or real customer identifiers.

The station list is a closed enum. Real shops add benches. Students who "fix" that by accepting any string will watch agents invent a station named retry and skip inspection. Closed enums feel rude in a demo. They are the mill stamp.

Teams that already gate tools through a typed MCP server or an API gateway with idempotency keys do not need a classroom ledger. They need to inspect the gateway they have. People hunting for a faster model should also stay out. Speed will not stamp a slip. Beginners who have not yet written a unit test will get more from a plain HTTP tutorial than from hash chaining.

Keep test_double_issue and test_hash_mismatch. Rename them if the shop metaphor fades. The names are less important than the refusal. An agent loop that cannot be refused is not a loop. It is a hose.

The yellow paper at the crib window was never about handwriting. It was about a second person being able to see the trail. The validator is that second person. Rerun it until the sloppy plan fails in one line and the stamped plan prints four hashes that do not move.

The Loaner Bench Workshop

Charlie Zhu — Tue, 22 Sep 2026 14:39:31 +0000

On a Tuesday evening a teaching assistant still has twenty USB sticks on the desk. Half the room can clone a repo. The other half cannot paste an API key into a homework file that will later be committed, screenshotted, and forgotten. The lab is supposed to teach how a coding assistant actually asks a program to do work. The bottleneck is not syntax. It is the missing bench.

A loaner bench is an old shop-floor idea. A machinist does not buy a surface plate for a two-hour class. The tool crib issues one, logs the serial, and wants it back with the workpiece and a note. The same pattern fits a ninety-minute session on tool calling. Students borrow a remote coding environment, run a tiny agent against a local function, and return a transcript that a script can grade. They do not take the bench home as a secret.

This outline is a teaching plan, not a field report from a particular campus. Instructors should treat the timings as a starting grid and the code as a rerunnable kernel. The scene above is a composite of a common lab failure, not a claim about one named classroom.

What the room is trying to prove

Industry conversation this week keeps circling agents that never leave the browser, models that emit tool calls, and the quieter worry that engineers stop reading what they ship. A class can use that noise without reenacting it. The learning goal is narrower. After ninety minutes a student can show that a model requested a named function, that the runtime executed only that function, and that a second pass with a wrong name was rejected.

MonkeyCode enters here as the loaner, not as the lesson. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The product's free model access and free server option are enough to give a room a shared bench when the school does not want twenty personal keys in a homework repo. The exercises below still run if that mention is stripped. The verifier is local Python. The remote side is only a place to draft and compare prompts.

The bench is optional on purpose. A student who already has another endpoint can point the same client at it. A student with no network can still run the grader against a recorded transcript. The class is about the call slip, not the brand of the crane.

Timing for a ninety-minute room

The first fifteen minutes are paper. Each pair writes two function names on a card: lookup_part and check_bin. They write one sentence each about arguments and one sentence about what the model is forbidden to invent. No laptops yet. The card is the contract. If the later transcript disagrees with the card, the card wins.

The next twenty-five minutes are the local runtime. Students paste the kernel below into a file named loaner_bench.py and run it once with a fixture transcript. The fixture is honest. It already contains a legal call and an illegal one. The point is to watch the gate close before anyone talks to a model.

Minutes forty through seventy are the live pass. Pairs send a short parts question through whatever draft environment the instructor issued. They paste the model's raw function-call text into the same script. They do not paste generated business logic into the inventory functions. If the model writes a new helper, that helper is treated as contamination and the run is marked dirty.

The last twenty minutes are the handback. Each pair submits three files: the card photo or text, loaner_bench.py, and transcript.json. The teaching assistant runs one command. Green means the legal call executed and the illegal call died. Red means the bench was used as a vending machine.

The kernel students can rerun

The inventory is deliberately boring. Boredom is the point. A SKU either exists or it does not. The model is not asked to design a warehouse.

# loaner_bench.py
# Teaching kernel. Label: runnable locally with Python 3.11+.
from __future__ import annotations

import json
import sys
from dataclasses import dataclass
from typing import Any, Callable

BIN_MAP = {
    "SKU-1044": {"bin": "A-12", "qty": 8},
    "SKU-2201": {"bin": "C-03", "qty": 0},
}

def lookup_part(sku: str) -> dict[str, Any]:
    row = BIN_MAP.get(sku)
    if row is None:
        return {"ok": False, "error": "unknown_sku"}
    return {"ok": True, "sku": sku, "qty": row["qty"]}

def check_bin(sku: str) -> dict[str, Any]:
    row = BIN_MAP.get(sku)
    if row is None:
        return {"ok": False, "error": "unknown_sku"}
    return {"ok": True, "sku": sku, "bin": row["bin"]}

TOOLS: dict[str, Callable[..., dict[str, Any]]] = {
    "lookup_part": lookup_part,
    "check_bin": check_bin,
}

@dataclass(frozen=True)
class CallSlip:
    name: str
    args: dict[str, Any]

def parse_slip(raw: str) -> CallSlip:
    payload = json.loads(raw)
    name = payload["name"]
    args = payload.get("args") or {}
    if not isinstance(name, str) or not isinstance(args, dict):
        raise ValueError("malformed_slip")
    return CallSlip(name=name, args=args)

def execute_slip(slip: CallSlip) -> dict[str, Any]:
    fn = TOOLS.get(slip.name)
    if fn is None:
        return {"ok": False, "error": "unknown_tool", "name": slip.name}
    try:
        return fn(**slip.args)
    except TypeError as exc:
        return {"ok": False, "error": "bad_args", "detail": str(exc)}

def grade(transcript_path: str) -> dict[str, Any]:
    data = json.loads(open(transcript_path, encoding="utf-8").read())
    results = [execute_slip(parse_slip(item["raw"])) for item in data["calls"]]
    legal = results[0]
    illegal = results[1]
    passed = legal.get("ok") is True and illegal.get("error") == "unknown_tool"
    return {"passed": passed, "results": results}

if __name__ == "__main__":
    path = sys.argv[1] if len(sys.argv) > 1 else "transcript.json"
    print(json.dumps(grade(path), indent=2))

A fixture sits beside it. The first slip is the one the card allowed. The second slip is a name the model likes to invent when nobody is watching.

{
  "calls": [
    {"raw": "{\"name\": \"lookup_part\", \"args\": {\"sku\": \"SKU-1044\"}}"},
    {"raw": "{\"name\": \"optimize_warehouse\", \"args\": {\"sku\": \"SKU-1044\"}}"}
  ]
}

Run it from a shell the same way a grader will.

python loaner_bench.py transcript.json

A passing room prints "passed": true. The legal lookup returns quantity eight. The invented optimizer dies with unknown_tool. Students who "fixed" the illegal call by adding a new function have failed the lab even if the JSON looks pretty. The crib does not grow new tools because a paragraph sounded confident.

Live pass without baking a vendor into the kernel

The kernel never imports a vendor SDK. That is intentional. During the live window, students may use MonkeyCode's free model access on the free server to draft a prompt such as: ask for SKU-1044 quantity, reply only with a JSON call slip for lookup_part or check_bin. They copy the model's text into a new transcript.json and rerun the grader.

If an instructor wants a client, keep it labeled as a sketch. Endpoints, model identifiers, and quotas change, and this article does not freeze them. A minimal shape looks like a POST of a prompt string and a paste of the text that came back. Anything more specific belongs in the day's lab sheet, not in a public kernel that students will copy for a year.

The interesting failure is consistent. Models that have been trained to be helpful will offer optimize_warehouse or a paragraph of advice. The crib does not take advice. It takes a slip. Watching a fluent paragraph fail the grader teaches more than a green smoke test. A second mutation is worth planting on the projector: change SKU-1044 to SKU-9999 and confirm the runtime does not invent a bin.

Students who finish early write a third slip by hand, check_bin for SKU-2201, and predict the quantity-zero row before they run it. The prediction is the point. The remote bench is only a way to produce text fast enough that the gate still has time to slam.

What the assistant should mark

The teaching assistant is not scoring prose. Three checks are enough. The card names match TOOLS. The first live call executed a function that already existed. The second call, or a planted mutation, still returns unknown_tool. A louder room can add a fourth check: SKU-9999 must not become a new inventory row because a model apologized and invented stock.

Pairs that cannot get a remote draft can still pass. They hand-write two slips, save them as JSON, and run the same command. The loaner bench is a convenience. It is not the credential. A transcript produced on a bus with no signal is as valid as one produced on a free server, provided the grader stays green.

Limits, and who should skip this lab

The kernel is not a production agent. It has no authentication, no retries, no streaming, and no audit trail beyond a JSON file. It will not measure latency. It will not prove that a free server will be there next term. Instructors who need a named model, a paper trail for procurement, or a data-processing agreement should not route classroom secrets through a shared loaner at all.

Do not put real customer SKUs, badges, or homework credentials into the prompt. The BIN_MAP is fiction. If a department cannot tolerate paste-into-a-cloud-box, run only the fixture path. Teams that already have a locked-down endpoint with an allow-list should keep using that endpoint. This lab is for the first time someone watches a model reach for a tool that does not exist. It is not a bake-off and it is not a performance study.

A class that wants a loaner bench rather than a stack of personal keys can run this once on MonkeyCode's free model access and free server option, then keep the grader after the accounts go quiet. The workpiece is the transcript. The bench goes back to the crib.

The Job Jacket Workshop

Charlie Zhu — Mon, 21 Sep 2026 12:52:37 +0000

A Thursday lab emptied faster than the logs. Laptops snapped shut while the projector still showed a green check copied from a chat transcript. The instructor asked for the command that produced it. Nobody could name one. The volunteer machine that had supposedly run the tests was already wiped for the next class.

Machine shops solved a similar vanishing act a century ago. A job jacket travels with the part. Prints, inspection notes, and the last measured size stay in the envelope even when the bench changes hands. The next shift does not have to trust a story about a clean run. The envelope either holds the numbers or the part does not move.

Agent-assisted homework fails the same way a part fails without a traveler. A model proposes a patch. Someone pastes it. A laptop somewhere maybe ran a test. The directory disappears. The grade rests on a screenshot of confidence. This workshop treats evidence as the workpiece. Students freeze a failing case, fill a tiny jacket file, and close the job only when a gate script can read both the failure and the repair.

The outline below is a proposed 75-minute lab. Instructors can rerun it as written on a single laptop. A shared machine is useful when the room cannot promise identical local setups, not because the jacket format needs a vendor.

Classroom operators sometimes need a loaner bench rather than a fleet of matching laptops. MonkeyCode's free model access and free server option can sit at the back of that room as Station B, where the gate script actually runs. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The files in this article do not depend on that product. Remove the vendor and the exercises still close.

Minute zero through ten is the scene, not a lecture. The instructor seeds a one-function repository with a quiet off-by-one and refuses chat screenshots as proof. Students may use an assistant to read the code. They may not close the job until the jacket names the command that failed, the command that passed, and the file that changed. The rest of the period is four stations on a clock, with a short buffer at the end for jackets that still refuse to close.

Station A occupies minutes ten through twenty-five. Each pair clones the seed and runs the test file before touching production code. The point is to capture a real failure, not to negotiate with a model about whether a failure exists. A jacket that starts with "tests were red in the chat" is rejected on sight. The seed looks like this.

# clip.py — seeded defect, do not "fix" until the jacket records a failing run

def clip_index(n: int, i: int) -> int:
    """Clamp i into [0, n-1] for n > 0.

    The seeded bug returns n when i == n, which is one past the last valid index.
    """
    if n <= 0:
        raise ValueError("n must be positive")
    if i < 0:
        return 0
    if i > n:  # seeded defect: should be i >= n
        return n - 1
    return i

# test_clip.py
import unittest
from clip import clip_index

class ClipIndexTests(unittest.TestCase):
    def test_zero(self):
        self.assertEqual(clip_index(5, 0), 0)

    def test_last_valid(self):
        self.assertEqual(clip_index(5, 4), 4)

    def test_equal_to_n(self):
        self.assertEqual(clip_index(5, 5), 4)

    def test_past_n(self):
        self.assertEqual(clip_index(5, 9), 4)

    def test_rejects_empty(self):
        with self.assertRaises(ValueError):
            clip_index(0, 0)

if __name__ == "__main__":
    unittest.main()

The first recorded command is ordinary. Students run it in the repo root and paste the tail of the output into the jacket, including the FAIL line. They do not summarize it. They do not translate it into optimism.

python -m unittest test_clip.py -v

Station B occupies minutes twenty-five through forty. Pairs write jacket.json before they edit clip.py. The jacket is deliberately boring. It is a traveler card, not a diary. Empty strings are allowed at this station only for pass_cmd and changed_file. Everything else must already be true.

{
  "job_id": "lab-clip-01",
  "operator": "pair-c",
  "seed_sha": "replace-with-git-rev-parse-HEAD",
  "fail_cmd": "python -m unittest test_clip.py -v",
  "fail_excerpt": "FAIL: test_equal_to_n",
  "pass_cmd": "",
  "pass_excerpt": "",
  "changed_file": "",
  "closed": false
}

git rev-parse HEAD

A jacket without a seed revision is a jacket for a rumor. Assistants are allowed to draft the JSON. They are not allowed to mark closed true. That bit belongs to the gate, which does not parse natural language and does not care how confident the model sounded.

Station C occupies minutes forty through sixty. This is the only station that may edit clip.py. The repair is a single comparison change, which is the pedagogical trap. Students who skip the jacket will finish in ninety seconds and have nothing to hand over. Students who keep the traveler will still finish quickly, but they will have a command log that another pair can rerun on a different machine. After the edit they run the same unittest module again and fill pass_cmd, pass_excerpt, and changed_file.

# clip.py — expected repair
def clip_index(n: int, i: int) -> int:
    if n <= 0:
        raise ValueError("n must be positive")
    if i < 0:
        return 0
    if i >= n:
        return n - 1
    return i

If the class is using a loaner bench, Station C runs there. The local laptop keeps the editor. The bench keeps the interpreter. That split is the whole point of a job jacket: the part can move, the envelope has to stay consistent. A pair that cannot reproduce the passing command on the bench has not closed the job, even if their chat window is full of green checkmarks.

Station D occupies minutes sixty through seventy-five. The gate script reads the jacket, refuses missing fields, and reruns fail_cmd against a copy of the seed only when instructors want a stricter lab. The default teaching version is milder. It checks that the jacket is complete, that closed is still false coming in, that the named file exists, and that pass_cmd exits zero now. Students invoke it once.

# close_job.py — proposed gate; run from the repo root
import json
import subprocess
import sys
from pathlib import Path

REQUIRED = (
    "job_id",
    "operator",
    "seed_sha",
    "fail_cmd",
    "fail_excerpt",
    "pass_cmd",
    "pass_excerpt",
    "changed_file",
)

def die(msg: str) -> None:
    sys.stderr.write(msg + "\n")
    sys.exit(1)

def main() -> None:
    jacket_path = Path("jacket.json")
    if not jacket_path.is_file():
        die("no jacket.json on the bench")

    jacket = json.loads(jacket_path.read_text(encoding="utf-8"))
    for key in REQUIRED:
        value = jacket.get(key, "")
        if not isinstance(value, str) or not value.strip():
            die(f"jacket field empty: {key}")

    if jacket.get("closed") is True:
        die("jacket already closed; reopen by setting closed to false")

    changed = Path(jacket["changed_file"])
    if not changed.is_file():
        die(f"changed_file missing: {changed}")

    excerpt = jacket["fail_excerpt"].strip()
    if "FAIL" not in excerpt and "Error" not in excerpt:
        die("fail_excerpt does not look like a failure")

    pass_cmd = jacket["pass_cmd"]
    completed = subprocess.run(pass_cmd, shell=True, check=False)
    if completed.returncode != 0:
        die("pass_cmd still failing; jacket stays open")

    jacket["closed"] = True
    jacket_path.write_text(json.dumps(jacket, indent=2) + "\n", encoding="utf-8")
    print("job closed:", jacket["job_id"])

if __name__ == "__main__":
    main()

python close_job.py
cat jacket.json

A closed jacket is the only artifact collected at the door. Chat logs are optional attachments. They are not the workpiece. Pairs who finish early swap jackets and try to reopen a neighbor's job by checking out the seed revision and running fail_cmd again. If the failure cannot be revived from the recorded command, the jacket was theater and the station is still open.

The method has limits that matter in a real room. The gate trusts pass_cmd as a shell string, so a student can point it at true or at a test file they gutted. Instructors who need a harder lab should pin the command to python -m unittest test_clip.py -v inside close_job.py and stop reading it from JSON. The seed shown here is a one-line defect. It teaches the traveler, not numerical methods, concurrency, or prompt injection. A jacket does not make a model honest. It only makes missing evidence obvious.

This lab is the wrong tool for take-home exams that must stay offline, for teams that already require reviewed CI on every branch, and for anyone hoping a free shared bench will replace code review. It is also the wrong tool if the instructor cannot see the gate output. A jacket closed on a private laptop and pasted into Slack is another screenshot. The envelope has to be on a bench the next pair can touch.

The repair itself is almost besides the point. What the period trains is a habit older than software: the part does not leave the shop because someone remembers it fitting. It leaves because the jacket still contains the measurement. Students who keep that envelope can change assistants, laptops, and even the loaner server. The job remains the same size.