DEV Community: Charlie Hu

Weekend Build Log: A Cold-Start Test for Free-Tier Demo Hosts

Charlie Hu — Fri, 16 Oct 2026 05:28:54 +0000

A weekend demo ships in one of two states: it works on the author's laptop, or it works from a cold start on the host where reviewers will open it. The gap between those two states is almost never the application code. It is three host properties that most build logs never measure.

Core conclusion: before a side project is called "done", measure cold-start time, disk durability, and idle/restart behavior on the actual host. Treat everything else — UI polish, extra endpoints, model choice — as optional.

The scope cut: three tiers, one weekend

The build log below is written so it can be replayed on any free-tier host. No product benchmark numbers appear in it, because free-tier behavior differs by region and changes without notice. The scripts are the artifact; the numbers are yours to fill in.

Tier assignment used for the build:

Tier 1 — must ship. One /healthz endpoint, one read-only route, the cold-start probe, the durability probe, and a README with copy-pasteable commands.
Tier 2 — ship only if Friday's measurements allow. Seed fixtures, one write path behind an environment flag, a short demo script.
Tier 3 — explicitly never this weekend. Auth, multi-tenant data, background workers, dashboards, and any migration of real data.

One rule keeps the tiers honest: adding a Tier 2 item requires removing a Tier 1 item or shortening the demo script by the same amount of time. Otherwise the tier list becomes a wish list with deadlines attached.

Why free hosts break demos in three specific ways

Cold start after idle. A host that sleeps the process turns a 200 ms request into a multi-second one. The first reviewer to open the link pays that cost.
Ephemeral disk. Files written at runtime disappear on restart. SQLite in a container without a mounted volume is the classic case.
Unknown restart policy. Whether the supervisor restarts a crashed process, and how quickly, is usually undocumented on free tiers.

None of these are reasons to avoid a free host. They are reasons to measure before the demo depends on them.

Artifact 1: the cold-start probe

The probe clones the repository into a temporary directory, installs it, boots it, and polls until the health endpoint answers.

#!/usr/bin/env bash
# cold-start.sh  <git-url>
# Measures: clean checkout -> first successful /healthz response.
set -euo pipefail

REPO="${1:?usage: cold-start.sh <git-url>}"
PORT="${PORT:-8080}"
BUDGET_MS="${BUDGET_MS:-0}"   # 0 = measure only, no assertion
WORK="$(mktemp -d)"

git clone --depth 1 "$REPO" "$WORK/app" >/dev/null
cd "$WORK/app"

START=$(date +%s%3N)
if [ -f package.json ]; then
  npm ci --silent
  (PORT="$PORT" npm start >"$WORK/boot.log" 2>&1 &)
elif [ -f requirements.txt ]; then
  python -m venv .venv
  ./.venv/bin/pip install -q -r requirements.txt
  (PORT="$PORT" ./.venv/bin/python -m app >"$WORK/boot.log" 2>&1 &)
else
  echo "no known manifest; add a branch for your stack"
  exit 2
fi

until curl -sf "http://127.0.0.1:$PORT/healthz" >/dev/null 2>&1; do
  sleep 0.2
done
END=$(date +%s%3N)

ELAPSED=$(( END - START ))
echo "cold_start_ms=$ELAPSED budget_ms=$BUDGET_MS"

if [ "$BUDGET_MS" -gt 0 ] && [ "$ELAPSED" -gt "$BUDGET_MS" ]; then
  echo "FAIL: cold start over budget"
  exit 1
fi
echo "PASS"

Run it three times locally and three times on the host, then set BUDGET_MS to roughly twice the slowest observed value. The assertion exists to catch regressions between Friday and Sunday, not to publish a speed claim.

Artifact 2: the durability probe

Durability is a yes/no question and takes about two minutes to answer. Gate the debug route behind an environment variable, and delete it after the measurement.

# Before a restart
curl -s -X POST "$BASE/debug/token" -d "value=$(date +%s)" -o before.txt
# Restart the service using the host's own control panel or CLI
curl -s "$BASE/debug/token" -o after.txt

if diff -q before.txt after.txt >/dev/null; then
  echo "durable: state survived restart"
else
  echo "ephemeral: treat the disk as scratch space"
fi

An ephemeral result does not kill the demo. It changes the design: the read path is served from a fixture baked into the image, and any runtime writes are declared in the README as lost-on-restart.

Artifact 3: the triage table

Property	How to measure	If it fails	Ship the demo anyway?
Cold start	`cold-start.sh` against the host	Show a static warming-up page and ping before review	Yes, with a warm-up step in the runbook
Disk durability	Token probe across a restart	Serve fixtures from the image; no runtime writes	Yes, if the demo is read-only
Restart on crash	Kill the process via the host CLI	Add a manual restart step to the runbook	Yes, for a short review window
Outbound network	One `curl` to a known endpoint from the app	Precompute anything fetched at runtime	Only if the demo has no live-data need

The rule applied to the table: a failed property becomes a documented demo step, never an unstated assumption.

Where free model access fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option; both are operator-supplied availability claims here, and model names, quotas, regions, and terms can change, so verify current details on the project's own pages before planning around them. No quota figures, hardware specs, or benchmark results are stated in this article, because none were measured for it.

Free model access covers exactly three of the weekend's chores:

Generating fixture variations from a small hand-written example.
Drafting the README from the final diff, which a human then corrects.
Triaging boot logs into cause and noise after a failed deploy.

It does not belong on the request path of a live demo. A demo that calls out to a model on every page load adds a network dependency to the one thing the reviewer will click. Keep the call count explicit instead:

MAX_MODEL_CALLS = 3  # chores only: fixtures, README draft, log triage
calls = 0

def ask(prompt: str) -> str:
    global calls
    if calls >= MAX_MODEL_CALLS:
        raise RuntimeError('weekend model budget exhausted; do it by hand')
    calls += 1
    return client.complete(prompt)   # placeholder: wire to any provider

The free server option is the natural host for a demo of this size, with one caveat: the probes above decide whether it can hold the demo, not a product page. Measure on the free tier first, then decide what the README promises.

What got skipped, on purpose

Authentication. The demo has no users, so it has no user model.
Persistence for writes. The read path carries the demo; writes stay in memory.
CI beyond the two probes. The probes are the only tests that protect the review experience.
A custom domain. A default hostname is one fewer thing to break on Sunday night.

Every item on that list belongs in the README under known gaps. A reviewer who finds an unlisted gap assumes the rest is guesswork too.

Limitations and who should not use this

Demos that hold real user data need durability guarantees a free tier may not offer.
Anything with an uptime or latency commitment to a customer needs a paid host with a stated SLA.
Teams already running infrastructure should reuse it; adding a second platform for one weekend costs more than it saves.
The durability probe writes and reads a debug route. Remove that route after measuring, and confirm the host's terms allow the traffic the probe generates.

Sunday-night runbook

Run cold-start.sh against the deployed URL and record the number.
Restart the service, open the demo link, and confirm the first request path works cold.
Walk the demo script out loud, once, end to end.
Confirm every skipped item is listed in the README.
Freeze the branch. No commits after step 5.

A weekend side project is not judged by how much it contains. It is judged by whether a stranger can open it on Monday and see the one thing it does. If that trade-off fits your next weekend, the free server option is a reasonable place to start — run the cold-start probe before writing the README, and let the measurement set the scope.

A Machine-Checked Scope Budget for One-Weekend AI Demos

Charlie Hu — Thu, 15 Oct 2026 11:32:48 +0000

A Machine-Checked Scope Budget for One-Weekend AI Demos

The demo ships or it does not. What decides which is a file, not an intention.

Weekend AI side projects usually fail at the same place: the plan grows faster than the clock. A single-path demo needs a much smaller surface than most people budget for, and that surface has to be enforced by something other than willpower at 11 p.m. on Sunday.

The pattern below uses three artifacts: a golden-path smoke test, a scope budget that a script is allowed to veto, and a cut table that decides in advance what gets deleted rather than deferred. The running example is a small "summarize one file into a changelog stub" service with exactly one model call in the path.

MonkeyCode's free model access and free server option are relevant here for one narrow reason: they remove two classic weekend sinks, key provisioning and deploy plumbing. The pattern itself is independent of any provider. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Rule one: the golden path is a command, not a paragraph

Write the demo as one shell command that either exits 0 or exits non-zero. If the golden path cannot be expressed as a command, the scope is not yet small enough to start.

#!/usr/bin/env bash
# smoke.sh - the golden path end to end, no mocks, no manual steps
set -euo pipefail

BASE_URL="${BASE_URL:-http://localhost:8080}"
FIXTURE="${FIXTURE:-fixtures/tiny_repo.txt}"
OUT="$(mktemp)"

# 1. the service is up and self-reports
curl -fsS --max-time 5 "$BASE_URL/health" | grep -q '"status":"ok"'

# 2. one real request against a frozen fixture
curl -fsS --max-time 45 -X POST "$BASE_URL/summarize" \
  -H 'content-type: text/plain' \
  --data-binary "@$FIXTURE" \
  -o "$OUT"

# 3. the response is markdown with a heading, not an error page
grep -q '^## ' "$OUT" || { echo "FAIL: no markdown heading"; exit 1; }
grep -qi 'summary' "$OUT" || { echo "FAIL: no summary section"; exit 1; }

echo "GOLDEN PATH OK ($(wc -c <"$OUT") bytes)"

The important property is that step 2 crosses a real network boundary. A smoke test that stubs the model call proves nothing about the demo, because the model call is the part most likely to break during a live walkthrough.

Rule two: the plan is a file a script can reject

Scope creep is easier to catch as a validation error than as a feeling. Put the whole weekend in weekend.yml, then let a small checker refuse plans that cannot fit.

# weekend.yml - the plan the checker is allowed to veto
budget_hours: 12
golden_path:
  name: "summarize one file into a changelog stub"
  must_pass_by: "sunday 20:00"
items:
  - id: read-fixture
    hours: 1
    tier: must
  - id: model-call
    hours: 2
    tier: must
  - id: render-markdown
    hours: 2
    tier: must
  - id: deploy-hosted
    hours: 1
    tier: must
  - id: auth
    hours: 4
    tier: later
    tripwire: "only if the demo needs more than one user"
  - id: history-db
    hours: 6
    tier: later
    tripwire: "only if a reviewer asks for past runs"
  - id: settings-ui
    hours: 5
    tier: later
    tripwire: "only if a config value must be edited by a non-developer"

#!/usr/bin/env python3
"""scope-check.py - reject the plan before the weekend rejects it."""
import sys
import yaml  # pip install pyyaml

MAX_MUST_ITEMS = 4
MAX_MUST_HOURS_PER_ITEM = 3


def load(path):
    with open(path, encoding="utf-8") as fh:
        return yaml.safe_load(fh)


def check(plan):
    problems = []
    budget = plan["budget_hours"]
    musts = [i for i in plan["items"] if i["tier"] == "must"]
    must_hours = sum(i["hours"] for i in musts)

    if must_hours > budget:
        problems.append(f"must items need {must_hours}h, budget is {budget}h")
    if len(musts) > MAX_MUST_ITEMS:
        problems.append(f"{len(musts)} must items; the ceiling is {MAX_MUST_ITEMS}")
    for item in musts:
        if item["hours"] > MAX_MUST_HOURS_PER_ITEM:
            problems.append(
                f"must item '{item['id']}' is {item['hours']}h; split or demote it"
            )
    for item in plan["items"]:
        if item["tier"] != "must" and not item.get("tripwire"):
            problems.append(f"deferred item '{item['id']}' has no tripwire")
    return problems


def main():
    path = sys.argv[1] if len(sys.argv) > 1 else "weekend.yml"
    problems = check(load(path))
    if problems:
        print("SCOPE CHECK FAILED")
        for problem in problems:
            print(f"  - {problem}")
        return 1
    print("SCOPE CHECK PASSED")
    return 0


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

Example transcript for the plan above:

$ python3 scope-check.py weekend.yml
SCOPE CHECK PASSED

$ python3 scope-check.py weekend.yml   # after adding a 4h 'oauth' must-item
SCOPE CHECK FAILED
  - must items need 13h, budget is 12h
  - must item 'oauth' is 4h; split or demote it

The tripwire requirement matters more than the hour math. A deferred item with a written tripwire has a condition for returning; a deferred item without one is just a wish that will resurface mid-demo.

Rule three: keep one network dependency in the path

Each additional service in the golden path multiplies the number of things that can be down at demo time. In this build, the path has exactly two: the app host and the model endpoint.

The request shape below is a sketch, not a verified contract. Endpoint paths and model identifiers change between releases, so read the project's current documentation instead of copying a blog snippet, including this one.

# shape sketch: confirm base URL and model id against current docs
export MC_BASE="${MC_BASE:?set from docs}"
export MC_MODEL="${MC_MODEL:?set from docs}"

curl -fsS --max-time 45 "$MC_BASE/chat/completions" \
  -H "authorization: bearer $MC_TOKEN" \
  -H 'content-type: application/json' \
  -d "$(jq -n --arg m "$MC_MODEL" --rawfile f fixtures/tiny_repo.txt \
        '{model:$m,messages:[{role:"user",content:("Summarize as markdown:\n" + $f)}]}')"

Two properties are worth copying regardless of provider. First, the model identifier lives in an environment variable, so switching providers is a config change rather than a code change. Second, every model call has a wall-clock timeout shorter than the smoke test's patience, so a hung request fails loudly instead of stalling a walkthrough.

Gate the whole thing behind one command and run it before every rehearsal:

check:
    python3 scope-check.py weekend.yml
    ./smoke.sh

The cut table

Decisions get easier when the response to a scope item is chosen by rule instead of by mood.

Signal	Action	Reason
Item is not on the golden path	Delete it	Deferral keeps the cost in the plan
Must-item exceeds 3 hours	Split or demote	Long must-items are where weekends die
Requires a second stateful service	Stub it with a file or constant	A database is a second failure domain
Requires a secret that is not on hand	Replace with a public fixture	Provisioning is not demo work
Only improves visual polish	Skip, and log it	Polish is the first thing viewers forgive
Triggered by a real reviewer question	Re-promote to must	Evidence beats aesthetics

What this weekend skipped, on purpose

Authentication. The demo runs as a single anonymous user. Multi-user auth was deferred with a concrete tripwire rather than half-built.
Persistence. Results are not stored. A file-backed stub would have added a migration story and a second failure mode.
A settings interface. Configuration stays in environment variables, which is honest about who the demo is for.
Model comparison. One model, one prompt, one output shape. Comparing providers is a separate project with its own budget.
Streaming output. The response arrives whole. Streaming is a latency feature, and the demo has no latency claim to defend.
Test coverage beyond the golden path. Unit tests exist where they were cheap; the smoke test is the gate.

Recent community discussion has been heavy on AI fatigue, and this cut list is the practical response to it. A smaller AI surface is easier to defend to a reader, a reviewer, or a future maintainer.

Limits, and who should not copy this

The scope checker validates a plan, not a product. It cannot tell whether the golden path is worth building.
A 12-hour budget suits a single developer with a known stack. Teams coordinate more than they code, so the numbers do not transfer.
Anything with real users, credentials, or regulated data should not run on a demo-grade setup with no auth and no persistence.
Free-tier availability, allowances, and server specifications are set by the provider and change over time. Verify current terms on the project's own pages before planning around them, and do not treat a free tier as a production SLA.
If verification is impossible for a given claim, remove the claim instead of softening it. The scripts above are the only parts that need to be true for the pattern to work.

Closing

A weekend side project succeeds when the golden path runs, the plan is small enough to enforce, and the skipped list is written down. The checker and the smoke test take under an hour to write and they pay for themselves the first time a demo survives a rehearsal it should have failed.

If the free model access or the free server option is what decides whether the weekend happens at all, read the project's current terms first, then start from the smoke test rather than from the feature list. The repository is open source, so the fastest way to verify any capability claim is the source itself.

A Source-Locked Claim Gate for a One-Path Weekend Demo

Charlie Hu — Tue, 13 Oct 2026 02:31:34 +0000

A weekend side project should refuse to print a number it cannot point at. That is the conclusion, and the rest of this log is the cut that makes the conclusion enforceable. A longer prompt does not hold the line. A local allowlist does.

The working demo is deliberately small. It reads one markdown note, checks every detected number and link against a hand-edited allowlist, and writes a JSON receipt. If the receipt is not clean, the note does not ship. Optional static hosting comes after that check, not before it.

Why this cut, this weekend

Agent demos fail in a specific way. The prose sounds finished, then a quota, a latency figure, or a documentation link appears that nobody opened. The failure is not mystical. It is an untracked claim.

Public developer discussion has spent energy on retries, agreeable models, and the gap between model progress and ordinary software discipline. Those threads are context, not a source of figures for this log. No statistic from a third-party post is repeated here. The engineering move is local: treat unsourced numbers as build errors.

This account's recent notes already covered attempt caps, fixture locks, read-only routes, and status cards. The missing piece is the claim itself. A frozen fixture can still contain a made-up capacity line. The gate below targets that line, and nothing wider.

Scope that fits in a weekend

Four artifacts and one command define the path. The checker does not import an SDK. The hot path does not open a socket.

Files that stay

notes/demo.md holds the only prose the demo is allowed to show.
claims/allowlist.toml holds the only numbers, phrases, and URLs the prose may repeat.
gate_claims.py is a local checker with a boring exit code.
receipts/latest.json is the pass or fail record a reviewer can diff.

Work that does not get built

The skip list is part of the design, not a backlog apology.

No automatic retry after a red receipt.
No write tool pointed at the repository.
No multi-model comparison and no named-model bake-off.
No token meter and no cost chart.
No account system on the optional host.
No live search inside the demo process.

A side project that implements that list stops being a weekend demo. The cut keeps the path teachable, and it keeps a bad figure from hiding inside extra machinery.

Hand-write the allowlist first

Suggestions can arrive later. Authority starts in a file a human can read without a model session. The shape below is a proposal, not a verified product sheet.

# claims/allowlist.toml
# Unexecuted proposal. Rows show file shape, not measured product facts.

[[claim]]
kind = "phrase"
text = "free model access"
source = "operator-supplied availability note, re-check before publish"

[[claim]]
kind = "phrase"
text = "free server option"
source = "operator-supplied availability note, re-check before publish"

[[claim]]
kind = "url"
text = "https://dev.to/devlab_1905"
source = "this account home, open once on publish day"

A token allotment does not belong in the example. Neither does a server size, a region, or a promise that an offer lasts. If a primary page is checked on demo day and a human adds a sourced row, the gate can allow that exact text. Until then, the prose must not invent it.

Proposed checker

The program below is a proposal. It is labeled unexecuted. It is not a benchmark, and it is not a claim that this account ran it on 2026-10-13.

#!/usr/bin/env python3
"""Fail markdown that prints numbers or links missing from an allowlist.

Proposal only. Not a recorded test run.
"""

from __future__ import annotations

import json
import re
import sys
from pathlib import Path

NUM = re.compile(r"\b\d[\d,]*(?:\.\d+)?%?\b")
URL = re.compile(r"https?://[^\s)]+")
BANNED = ("forever", "unlimited", "fastest", "guaranteed")


def load_allowlist(path: Path) -> set[str]:
    allowed: set[str] = set()
    for raw in path.read_text(encoding="utf-8").splitlines():
        line = raw.strip()
        if line.startswith("text = "):
            value = line.split("=", 1)[1].strip().strip('"')
            allowed.add(value)
    return allowed


def gate(markdown: str, allowed: set[str]) -> dict:
    failures = []
    lowered_allowed = {item.lower() for item in allowed}
    for word in BANNED:
        if word in markdown.lower() and word not in lowered_allowed:
            failures.append({"kind": "wording", "text": word})
    for match in NUM.findall(markdown):
        if match not in allowed:
            failures.append({"kind": "number", "text": match})
    for match in URL.findall(markdown):
        if match not in allowed:
            failures.append({"kind": "url", "text": match})
    return {
        "ok": not failures,
        "failure_count": len(failures),
        "failures": failures,
    }


def main() -> int:
    if len(sys.argv) != 3:
        print("usage: gate_claims.py NOTE.md ALLOWLIST.toml", file=sys.stderr)
        return 2
    note = Path(sys.argv[1]).read_text(encoding="utf-8")
    allowed = load_allowlist(Path(sys.argv[2]))
    receipt = gate(note, allowed)
    out = Path("receipts")
    out.mkdir(exist_ok=True)
    (out / "latest.json").write_text(
        json.dumps(receipt, indent=2) + "\n",
        encoding="utf-8",
    )
    print(json.dumps(receipt, indent=2))
    return 0 if receipt["ok"] else 1


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

Run it from the demo root after the two input files exist.

mkdir -p receipts notes claims
python3 gate_claims.py notes/demo.md claims/allowlist.toml
echo "exit=$?"

Exit code 0 means the detected claims were already allowlisted. Exit code 1 means the note stays unpublished. Exit code 2 means the command was called wrong. The receipt file is the review object. A model transcript is not.

Two notes, two expected receipts

These fixtures are specifications for a later run. They are not recorded outputs.

Passing note

This demo reads one local note and writes a receipt.
It may mention free model access only as an operator-supplied option.

That note has no bare number and no URL. The checker should return ok: true when the phrase row exists and the banned-word list stays quiet. The sample script does not yet prove that an allowlisted phrase occurs in the note. That gap is intentional. A weekend can ship the failure mode first, then add a presence check only if a real run shows a need.

Failing note

The free tier includes 8192 tokens and stays unlimited.
Docs live at https://example.com/pricing.

Expected failures include the number 8192, the word unlimited, and the unlisted URL. The demo stops. Nobody repairs it by asking for another draft. The human deletes the sentences, or replaces them with sourced rows after opening a primary page on the same day.

Decision table

Signal in the note	Result	Next edit
Number absent from `text` rows	Fail	Remove it, or add a row whose source was opened that day
URL absent from `text` rows	Fail	Drop the link
Banned wording such as unlimited	Fail	Use a dated check instead of a permanence claim
Allowlisted operator phrase, no new number	Pass	Keep a single plain mention
Step index such as a digit in a list	Often fail	Spell the step, or allowlist the digit as a structural index
Image-only claim	Not detected	Do not use images for figures in this demo

The last two rows are why the gate is a lock for a side project, not a general truth machine. Lists that need digits should be rewritten, or the digits should be added as explicit rows with source structural index, not a product fact.

One model pass, after the file exists

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

MonkeyCode is relevant only after claims/allowlist.toml exists. The operator describes it as an open-source project and states that free model access and a free server option are available. This log does not add model names, quotas, hardware, regions, or a duration. Those details were not verified against a primary source for 2026-10-13, and an unverified figure would fail the gate this article is arguing for.

Use free model access for one classification pass on the note. Ask for labels only: plain, numeric, or needs-source. Paste the labels beside the note in a scratch file. Merge nothing automatically. If the labels are wrong, shrink the note. A second call is a skip, not a remedy.

Use the free server option, if it is still offered when the receipt is green, as a static file host for receipts/latest.json and a single HTML page. The page may print ok and failure_count. It gets no form, no upload, and no proxy to a model endpoint. If that option is down, or the terms differ from what was assumed, skip hosting. The local command remains the demo either way.

Readers comparing this cut with their own side project can confirm the repository license and the current free-access terms, then run the checker against one note they already trust. A local red receipt is a better introduction than a hosted tour.

Static page, still optional

A few lines of HTML are enough for a reviewer who wants the receipt visible. They load JSON only when both files sit on the same origin. This snippet is also a proposal, not a deployed site.

<pre id="out">receipt not loaded</pre>
<script>
fetch("./latest.json")
  .then((res) => res.json())
  .then((data) => {
    document.getElementById("out").textContent = JSON.stringify(data, null, 2);
  })
  .catch(() => {
    document.getElementById("out").textContent = "local receipt missing";
  });
</script>

That page teaches the receipt shape. It does not teach product capacity. Leaving it offline is a valid weekend outcome, and it should be the default if the host terms were not re-read that day.

Test plan before anyone treats the script as done

No run is claimed here. A reviewer would still want a fixed sequence before trusting the exit code.

Sequence

Empty-claim note. Expect ok: true and failure_count: 0.
Note containing 8192. Expect a number failure and exit 1.
Note containing an unlisted URL. Expect a URL failure.
Note containing guaranteed. Expect a wording failure.
Note whose only URL is copied exactly from an allowlist row. Expect that URL not to fail.
Run the same command with the network interface disabled. Expect an identical receipt, because the checker should not dial out.
Point the command at a missing file. Expect a traceback or a usage error, then decide whether a cleaner message is worth a later weekend. It is not required for this cut.

Record the seven results in the receipt directory only after a real run. Until then, the plan and the script stay labeled as proposals. A green reading invented in the write-up would be the same class of defect the gate exists to catch.

Who should walk away

The regex misses spelled-out numbers and claims split across markup. A determined draft can smuggle a figure in an image or in HTML entities. The sample loader is a line scan, not a TOML parser, so a wrapped string can fool it. Those are reasons to keep the input small, not reasons to trust the script on a large corpus.

Do not use this path for pricing pages, incident reports, security advisories, medical text, or legal text. Do not use it as evidence in a launch review. Do not point a write-capable agent at the allowlist and call the result independent.

People who need signed provenance, citation graphs, or policy approval need a different system. People who want a model to retry until the exit code turns green are outside the cut. The red receipt is the feature that retry loop would automate away.

What shipped, on paper

The weekend artifact is a scope decision plus a proposed command. One note in. One allowlist. One receipt out. Hosting is a trailing option tied to a free server offer that must be re-read before use. Free model access, if still available, may label sentences once. It does not get to mint numbers.

That is a build log, not a product announcement. The demo is finished when an unsourced figure cannot pass, even if the optional page never goes up.

Stop After One Call: A Weekend Export Tour With a Hard Attempt Cap

Charlie Hu — Sun, 11 Oct 2026 22:01:36 +0000

A weekend agent demo is done when one lane returns one valid payload. Another call is a different project. This proposed build log keeps an export tour inside that limit: one canned file list, a local stub, an optional hosted run, and a hard cap of one attempt per lane.

The tour names exports from a folder list. It does not edit files, open a pull request, or rank assistants. The stub lane is the demo. The hosted lane is a switch that stays off until a URL has been checked the same day.

What the cut protects

Recent public discussion has treated model quality as the main variable and ordinary software work as an afterthought. That framing is a poor fit for a side project. The failure mode on a weekend is smaller and duller: an unset variable, a second call that quietly changes the result, or a paragraph that sounds finished while the JSON is wrong.

Path that stayed

The surviving path has four parts.

samples/exports.json stores the canned file list and sets allow_writes to false.
lane_runner.py runs a deterministic stub with no network.
--lane both may perform one hosted call when HOSTED_BASE_URL is present.
lane-report.json records the payload, the attempt count, and any skip reason.

Path that left

Work that did not survive the cut:

backoff, jitter, and a backup model
install, format, or commit steps
a vendor scoreboard
signup automation
any numeric claim about token grants, machine size, or how long a free tier lasts

The cut is the artifact. A longer prompt would only lengthen the skip list.

Working stub

The script in the next section is a proposal. It has not been executed for this article. No latency number is claimed, because none was measured.

Expected stub behavior is narrow. Given src/app.py, src/__init__.py, and README.md, the export list contains app and nothing else. attempts equals 1 and writes is empty. A visitor can inspect that result with the network disconnected.

A non-zero exit means the shape check failed. The demo is not mostly working in that case. The stub gets fixed, then the same command runs again. That later local run is a human edit cycle, not a model retry.

Commands for the local lane

mkdir -p samples
printf '%s\n' '{"allow_writes":false,"files":["src/app.py","src/__init__.py","README.md"]}' > samples/exports.json
python lane_runner.py --lane stub
python -m json.tool lane-report.json

Runner, one attempt per lane

#!/usr/bin/env python3
"""Proposal only. Not executed for this article. One attempt per lane."""

import argparse
import json
import os
import sys
import urllib.error
import urllib.request
from pathlib import Path

ROOT = Path(__file__).resolve().parent
SAMPLE = ROOT / "samples" / "exports.json"
REPORT = ROOT / "lane-report.json"
MAX_ATTEMPTS = 1


def load_sample() -> dict:
    data = json.loads(SAMPLE.read_text(encoding="utf-8"))
    if data.get("allow_writes") is not False:
        raise SystemExit("sample must set allow_writes to false")
    files = data.get("files")
    if not isinstance(files, list) or not files:
        raise SystemExit("sample needs a non-empty files list")
    return data


def stub_lane(sample: dict) -> dict:
    exports = []
    for name in sample["files"]:
        if name.endswith(".py") and not name.endswith("__init__.py"):
            exports.append(Path(name).stem)
    return {
        "exports": exports,
        "attempts": 1,
        "writes": [],
        "source": "stub",
    }


def hosted_lane(sample: dict) -> dict:
    base = os.environ.get("HOSTED_BASE_URL", "").rstrip("/")
    if not base:
        return {
            "skipped": True,
            "reason": "HOSTED_BASE_URL unset",
            "attempts": 0,
        }
    payload = json.dumps(
        {
            "files": sample["files"],
            "allow_writes": False,
            "attempts_allowed": MAX_ATTEMPTS,
        }
    ).encode("utf-8")
    req = urllib.request.Request(
        base + "/export-tour",
        data=payload,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=8) as resp:
            body = json.loads(resp.read().decode("utf-8"))
    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
        # One failure ends the lane. There is no retry branch.
        return {"skipped": True, "reason": type(exc).__name__, "attempts": 1}
    body["attempts"] = 1
    body["skipped"] = False
    body["source"] = "hosted"
    return body


def problems(result: dict) -> list[str]:
    if result.get("skipped"):
        return []
    found = []
    if result.get("attempts") != 1:
        found.append("attempts must equal 1")
    if result.get("writes"):
        found.append("writes must stay empty")
    if not isinstance(result.get("exports"), list):
        found.append("exports must be a list")
    return found


def main() -> int:
    parser = argparse.ArgumentParser(description="Run one attempt per lane")
    parser.add_argument("--lane", choices=("stub", "both"), default="stub")
    args = parser.parse_args()
    sample = load_sample()
    report = {"demo": "export-tour", "max_attempts": MAX_ATTEMPTS, "lanes": {}}
    stub = stub_lane(sample)
    report["lanes"]["stub"] = {"result": stub, "problems": problems(stub)}
    if args.lane == "both":
        hosted = hosted_lane(sample)
        report["lanes"]["hosted"] = {
            "result": hosted,
            "problems": problems(hosted),
        }
    REPORT.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
    bad = [name for name, lane in report["lanes"].items() if lane["problems"]]
    if bad:
        print("failed lanes: " + ",".join(bad), file=sys.stderr)
        return 1
    print("wrote", REPORT)
    return 0


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

Report the runner should write

A passing stub report looks like the sample below. The values come from the canned file list, not from a live service.

{
  "demo": "export-tour",
  "max_attempts": 1,
  "lanes": {
    "stub": {
      "result": {
        "exports": ["app"],
        "attempts": 1,
        "writes": [],
        "source": "stub"
      },
      "problems": []
    }
  }
}

problems must be empty. A witty summary field is ignored on purpose, because the tour did not ask for one. Extra prose is how a weekend demo starts pretending to be finished.

Hosted lane, without invented limits

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

The operator brief for this draft describes MonkeyCode as an open-source project and supplies two availability claims: free model access, and a free server option. Both belong only to the hosted lane. They are not benchmark results.

This article names no model, states no token grant, describes no hardware, and does not say how long either option remains in place. No primary quota or pricing page was attached for a check on 2026-10-12. Stale numbers would be worse than silence, so the numbers stay out.

A free server, when the project still offers one, is a convenient place to boot this same runner. It does not raise MAX_ATTEMPTS. A failed free call is still one attempt. The skip reason goes in the report, and the process stops.

export HOSTED_BASE_URL="https://example.invalid"
python lane_runner.py --lane both
unset HOSTED_BASE_URL

example.invalid is a placeholder, not a service. It should be replaced only after the current project documentation has been read. Running the hosted lane before the stub is green reverses the weekend: the interesting failure moves onto a network, and the local bug stays hidden.

Situation	Lane to trust	What the report should show
No account, laptop only	stub	one stub result, hosted key absent
Host URL checked that day	both	hosted shape matches, or one recorded skip
URL missing or docs stale	stub	hosted skipped, attempts 0
Timeout or bad JSON	stub	hosted skipped, attempts 1, no second call
Demo needs writes or an SLA	neither	stop; this runner does not cover that

Free model access changes the location of the single call. It does not change the pass rule. Shape still beats fluency.

Order of work

The weekend order is fixed so the hosted option cannot sneak in early.

Write the canned file list and refuse writes in that file.
Run the stub lane until problems is empty.
Read the current host documentation. Stop if the free server option is unclear or gone.
Run --lane both once. Record a skip if the call fails.
Leave retries unimplemented.

A demo that starts at step 4 has no baseline. The stub result is the baseline. Hosted output is interesting only when it matches that shape or admits a skip.

This order also keeps a free model call from becoming the first test. The first test should pass on a laptop with the cable unplugged. That constraint is ordinary engineering, not a comment on any vendor.

What this weekend skips

The skip list is part of the log, not a second tool.

Retry helpers of every kind. One miss ends the lane.
Shell side effects, patches, and commits. The tour describes exports.
Multi-account orchestration and any script that signs a person up.
A comparison post against other assistants. One folder list cannot carry that weight.
Persistence past a single JSON report. There is no database in this demo.
Portfolio layout, launch copy, and a public uptime claim.

Those items can return on a later weekend. They are not required to show the export tour.

Checks before the demo is called done

The checks below describe control flow. They are not measured timings, and they were not executed for this article.

env -u HOSTED_BASE_URL python lane_runner.py --lane stub
env -u HOSTED_BASE_URL python lane_runner.py --lane both
python - <<'PY'
import json
report = json.load(open("lane-report.json"))
hosted = report["lanes"]["hosted"]["result"]
assert report["max_attempts"] == 1
assert hosted["attempts"] == 0
assert hosted["skipped"] is True
print("hosted lane skipped without a second call")
PY

One more check belongs on a scratch branch. Change stub_lane so attempts is 2, run the stub lane, and expect exit code 1. Revert the edit after the failure appears. That failure is the point of the cap.

A green process that called a host twice would be the bug the cap is meant to catch. The report is the place that bug should show up, as a non-zero exit rather than a second request.

Who should leave this approach alone

The cap is a scope lock for a side project. It is a bad default in other settings.

An on-call debug of idempotent reads, where a documented retry policy may be appropriate.
A procurement note that needs a contractual quota, a named model, or a hardware spec.
A security review. An empty writes list in a stub does not prove a real tool cannot touch disk.
A leaderboard, a hackathon ranking, or any claim that one canned file measures assistant quality.
A production agent with customer data. lane-report.json is not an audit log.

A free host makes the extra attempt feel cheap. Cheap is not the same as finished. Extra calls also risk rate limits that this draft refuses to guess.

The runner stays useful if every product name is removed. Keep the canned file list, the single attempt, and the report. A reader who still wants the hosted lane can read the project's current notes on free model access and the free server option, then decide whether that second command belongs in the same weekend.

One Status Card and a Three-Column Cut Log for a Weekend Agent Demo

Charlie Hu — Sat, 10 Oct 2026 18:40:57 +0000

A weekend agent demo fails when a second screen appears. One read-only status card, fed by one bounded fetch, is enough to show the path. Everything else belongs in a cut log, not in the repository opened on Saturday morning.

This build log keeps that cut explicit. It records what stays in the demo, what is deferred, and what is refused. It does not claim a production agent, a measured latency, or a hosting plan that will still be free next week.

The constraint that actually holds

Side-project agents expand by tool count. A status lookup becomes a ticket writer, then an email draft, then a schema change added for the demo. The room sees motion. The operator cannot point to the single call that was allowed to leave the machine.

Visibility is the constraint that survives the weekend. A stranger should be able to name the input, the output, and the stop condition from one card. When that explanation needs another panel, the scope has already slipped.

Public conversation this week has circled generated portfolios and the cost of trusting generated code. Those posts are topic signals, not sources for this log. The transferable lesson is narrower: a small artifact with a written cut list is easier to defend than a wide demo.

What the build keeps

The kept path is a read-only status card. The input is a local JSON fixture. The transform is a pure admission function. The output is a headline, a detail line, and the remaining call budget.

service is a short public name, such as billing-read.
state is one of up, degraded, or down.
checked_at is an ISO-8601 timestamp supplied by the fixture, never invented by a model.
budget_left is a local counter. It is not a provider invoice and not a token meter.

The card may describe a service state. It may not change that state. Network side effects and multi-step planning stay outside the Saturday repository.

A second service is not a small addition. It doubles the fixture rules, the failure copy, and the chance that a prompt picks up a field nobody reviewed. The build therefore stops at one name.

Where a hosted option is allowed to enter

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

Two availability claims are treated as operator-supplied for this draft: free model access, and a free server option. This log does not name models, invent a token quota, or treat hardware, duration, or pricing as stable. Those details change. The current project page is the source of truth before anyone moves a demo off localhost.

MonkeyCode participates only as an optional host for the one card. The admission logic is ordinary Python and does not require a hosted runtime. A hosted model is worth a look only when the weekend needs a short plain-language headline and the laptop will not stay open. A free server option is worth a look only after the operator confirms, the same day, that the option still exists and that the fixture contains no secrets.

Decision table

Situation	Decision	Reason
Fixture holds only public status fields	Local run is enough	No need to spend a hosted call
Headline must be one plain sentence	Hosted model is optional	Prompt stays limited to fixture fields
Free-server terms are unverified today	Stay on localhost	An availability claim is not a capacity plan
Prompt would include keys, customer text, or private logs	Refuse	Free access does not relax data rules
Demo needs a write, a payment, or an email send	Refuse this weekend	Out of scope, hosted or local
Quota, model name, or uptime is unknown	Do not print a number	Unverified figures go stale quickly

The table is a gate, not a ranking. It does not claim that one host is faster, cheaper, or more accurate than another. It states when a hosted option may enter the log at all.

The artifact

The module below is a proposed, unexecuted example. It has not been benchmarked, and it does not open a socket. It is the contract the demo should enforce before any hosted request is considered.

Secret rejection happens before the budget increments. A poisoned fixture should not burn the only Saturday admission. Incomplete fixtures are deferred for the same reason: a missing timestamp is a data bug, not a model task.

from dataclasses import dataclass, field

ALLOWED_STATES = {'up', 'degraded', 'down'}
REFUSED_KEYS = {'api_key', 'token', 'password', 'email', 'customer_id'}

@dataclass
class CutLog:
    kept: list[str] = field(default_factory=list)
    deferred: list[str] = field(default_factory=list)
    refused: list[str] = field(default_factory=list)

@dataclass
class Budget:
    limit: int = 3
    spent: int = 0

    def admit(self) -> bool:
        if self.spent >= self.limit:
            return False
        self.spent += 1
        return True

def reject_secrets(payload: dict) -> str | None:
    found = REFUSED_KEYS.intersection(payload)
    if found:
        return 'refused:' + ','.join(sorted(found))
    return None

def build_card(payload: dict, budget: Budget, log: CutLog) -> dict:
    secret = reject_secrets(payload)
    if secret:
        log.refused.append(secret)
        return {'ok': False, 'reason': secret}
    state = payload.get('state')
    service = payload.get('service')
    checked = payload.get('checked_at')
    if state not in ALLOWED_STATES or not service or not checked:
        log.deferred.append('incomplete-fixture')
        return {'ok': False, 'reason': 'incomplete-fixture'}
    if not budget.admit():
        log.deferred.append('budget-empty')
        return {'ok': False, 'reason': 'budget-empty'}
    log.kept.append('status-card')
    return {
        'ok': True,
        'headline': f'{service} is {state}',
        'detail': f'checked_at={checked}',
        'budget_left': budget.limit - budget.spent,
    }

A manual driver can sit in the same file. It is still a proposal, not a recorded test from this drafting session.

def _demo():
    log = CutLog()
    budget = Budget(limit=1)
    good = {
        'service': 'billing-read',
        'state': 'degraded',
        'checked_at': '2026-10-10T09:00:00Z',
    }
    bad = {
        'service': 'billing-read',
        'state': 'up',
        'checked_at': '2026-10-10T09:00:00Z',
        'api_key': 'do-not-send',
    }
    first = build_card(good, budget, log)
    second = build_card(good, budget, log)
    third = build_card(bad, Budget(), log)
    assert first['ok'] and first['budget_left'] == 0
    assert second['reason'] == 'budget-empty'
    assert third['reason'].startswith('refused:')
    assert 'status-card' in log.kept
    assert 'budget-empty' in log.deferred

Intended local check, after the file is saved as weekend_card.py:

python -m py_compile weekend_card.py
python -c 'import weekend_card; weekend_card._demo()'

If those asserts hold, the shape is one kept card, one deferred budget miss, and one refused secret. No latency number belongs next to that shape. A green local run also does not prove that a hosted rewrite will preserve the fixture.

Failure messages the card should show

A demo that only shows the happy path hides the gate. The card view should have three visible outcomes, each mapped from the function result.

Kept. Headline is the service name plus the state. Detail repeats checked_at exactly. Budget drops by one.
Deferred. Reason is incomplete-fixture or budget-empty. The view shows the reason and does not call a model to fill the gap.
Refused. Reason starts with refused:. The forbidden field value is not copied into the headline, the log, or a prompt.

That third outcome matters more than the headline. A weekend audience can forgive a dull sentence. It should not be shown a demo that forwards an api_key because the field happened to sit beside a status.

Render the reason in the same panel as the headline. A separate debug console will be ignored once the room is watching the card. If the reason cannot fit on the card, the scope is again too wide.

What this weekend skips

The cut log is part of the demo, not a footnote after the applause.

No write path. The card cannot open a ticket, restart a service, or edit a file outside the fixture.
No second tool. Search, shell, and mail stay deferred even if a hosted server would make them easy to attach.
No model-name theater. String formatting already produces a true headline from the fixture. A hosted model may rephrase that headline later, and only after the gate passes.
No quota on the slide. If a free allotment exists, its size is whatever the project page says on demo day, not a number frozen into this article.
No multi-service map. One service name is the whole stage. A second service is a second weekend.

Deferred work can return later. Refused work should not return under a renamed prompt. Renaming api_key to notes is a bypass, not a scope change, and the weekend rule is to stop rather than teach the filter a new synonym list.

Manual test plan

Run this plan before anyone else sees the card.

Load a fixture with only service, state, and checked_at. Confirm ok is true and budget_left drops by one.
Repeat the same fixture until the budget returns budget-empty. Confirm no extra headline is produced.
Add api_key to a copy of the fixture. Confirm the reason starts with refused: and the value never appears in headline.
Remove checked_at. Confirm the result is incomplete-fixture, not a guessed timestamp.
Pass an unknown state such as maybe. Confirm it is deferred, not coerced to up.
If a hosted call is still desired, send only the three allowed fields. Compare the returned sentence with the local headline. Keep the local headline if the hosted one adds a claim that was not in the fixture.
Re-read the project page the same day for free model access and the free server option. If either claim is gone or newly qualified, leave the demo on localhost.

Step 6 is the only point where a hosted model should see data. If that comparison is skipped, the demo has not tested the host. It has only tested the laptop.

Limitations, and who should walk away

This approach is a weekend gate. It is not an evaluation harness, a security review, or a capacity plan.

The budget counts local admissions, not provider tokens. A real hosted call can consume more than one unit even when this script records one.
Free access can be rate-limited, region-limited, or withdrawn. A demo script must not promise that a server will still be free on Monday.
The secret check is a key-name filter. It misses secrets stored under unusual names, inside nested text, or in a fixture comment. Treat it as a tripwire, not a scanner.
String formatting can still embarrass the operator if service contains markup. Escape the value before any HTML render.
No accuracy benchmark is claimed. Do not cite this log as evidence that a hosted model is correct.
The example timestamp is fixture data. It is not a record of a live incident.

Walk away when the audience needs write access, when the fixture holds private data, when compliance requires a named retention period, or when the demo cannot proceed without a guaranteed quota. Those projects need a reviewed environment and a written contract. A Saturday card will not supply either.

Teams that already have a staging gate, a secret scanner, and an on-call path also do not need this log. The module would duplicate lighter checks they already run, without adding the audit trail those systems keep.

How to file the log

Keep three short lines in the repository README, next to the module. Update them when the scope changes. Do not let the README drift ahead of the code.

Kept: read-only status card from three fixture fields, local budget of one to three admissions.
Deferred: hosted headline rewrite, second service, any tool beyond the pure function.
Refused: secrets in the prompt, write actions, printed quotas that were not checked the same day.

If a hosted pass is used, add one more line: the date the project page was read, and whether free model access and the free server option were still stated. Omit the line rather than guess. A missing line is easier to explain than a stale number.

Closing the log

The working demo is the card plus the cut log. The skipped work is the result that matters: a second screen, a write tool, and an unverified number never earned a place in the build. Operators who still want a hosted pass can set MonkeyCode's current free-model and free-server terms beside the decision table, and stop when the page and the table disagree.

Leave the Write Path at Home: One Read, a Route Contract, and a Skip Ledger

Charlie Hu — Fri, 09 Oct 2026 15:03:27 +0000

A weekend agent demo stays showable when the public slice does one read, rejects every write, and fails closed if that contract drifts. A larger prompt does not create that boundary. A route contract, a skip ledger, and a checker that runs before any process listens do. This build log treats that cut as the whole product for the weekend. Hosting and a model call stay optional, and every skipped write is named before the demo starts.

The failure mode is familiar. A second tool appears, a scratch file changes, and the walkthrough cannot be repeated from a clean directory. Moving that surface onto a free server does not repair it. The host only makes the unfinished path easier for someone else to open.

The cut this log actually ships

The working slice is small on purpose.

One user-facing path looks up a note by id.
One optional model call summarizes that same note.
Mutating tools stay at zero.
A skip ledger records what was not built, and why.

That list is the product. A portfolio page, a multi-step agent, or a write-back bot is a different weekend. Those ideas can wait in the ledger without being smuggled into the handler "just for the demo."

What "done" means before noon

Done is a local GET that returns one note, a POST that returns 405, a contract file that names both results, and a checker that exits zero. A free server is not part of done. It is a later choice, used only if the local contract still holds.

The samples below are a proposal for that cut. They are not a recorded run from this account, and the note text is illustrative.

The working read path

The process binds to localhost first. Nothing in the handler creates, updates, or deletes a note. Unknown ids return 404. Unknown paths return 404. Writes return 405 even if a client guesses a route that might exist next weekend.

# demo_app.py — proposal, not a recorded service
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import json

NOTES = {
    "n1": "One read. No writes. Every skip is written down.",
}

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path.startswith("/notes/"):
            note_id = self.path.rsplit("/", 1)[-1]
            text = NOTES.get(note_id)
            body = {"id": note_id, "text": text}
            status = 200 if text else 404
        else:
            body, status = {"error": "only /notes/{id}"}, 404
        raw = json.dumps(body).encode()
        self.send_response(status)
        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):
        self.send_error(405, "writes are out of this weekend's cut")

    def do_PUT(self):
        self.send_error(405, "writes are out of this weekend's cut")

    def do_DELETE(self):
        self.send_error(405, "writes are out of this weekend's cut")

if __name__ == "__main__":
    ThreadingHTTPServer(("127.0.0.1", 8765), Handler).serve_forever()

The local check is a plan, not a published timing result.

python3 demo_app.py
curl -sS http://127.0.0.1:8765/notes/n1
curl -sS -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:8765/notes/n1
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8765/notes/missing

The expected shape is simple. The first request returns the note. The second returns 405. The third returns 404. If any of those differ, the weekend stops. No extra route is added to make the demo feel larger.

A route contract the checker can fail

A contract file sits beside the app. It is the source the checker trusts, not the README. If the file and the handler disagree, the file wins and the process does not get a public bind.

# demo_contract.yaml — illustrative flat file
listen: 127.0.0.1
port: 8765
allowed_methods: ["GET"]
allowed_paths: ["/notes/{id}"]
model_calls_max: 1
tools_effect: read
skip_ledger: skips.md

# check_contract.py — proposal, flat keys only
import sys
from pathlib import Path

REQUIRED = ("allowed_methods", "allowed_paths", "tools_effect", "skip_ledger", "listen")
WRITE_MARKERS = ("POST", "PUT", "PATCH", "DELETE")

def load_flat(path: Path) -> dict:
    data = {}
    for line in path.read_text().splitlines():
        if not line or line.startswith("#") or line.startswith(" "):
            continue
        if ":" not in line:
            continue
        key, value = line.split(":", 1)
        data[key.strip()] = value.strip()
    return data

def main(path: str) -> int:
    contract_path = Path(path)
    data = load_flat(contract_path)
    missing = [key for key in REQUIRED if key not in data]
    if missing:
        print("missing:", ", ".join(missing))
        return 1
    methods = data["allowed_methods"].upper()
    if any(marker in methods for marker in WRITE_MARKERS):
        print("write method is outside the weekend cut")
        return 1
    if data["tools_effect"] != "read":
        print("tool effect must stay read")
        return 1
    if data["listen"] != "127.0.0.1":
        print("listen must stay on localhost until the local check passes")
        return 1
    ledger = contract_path.parent / data["skip_ledger"]
    if not ledger.is_file() or not ledger.read_text().strip():
        print("skip ledger missing or empty")
        return 1
    print("contract ok")
    return 0

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

printf "- No note creation: a write needs validation and undo.\n" > skips.md
python3 check_contract.py demo_contract.yaml

Why the parser stays tiny

The loader ignores indented lines and does not understand nested YAML. That is a limitation, not a hidden feature. If the contract grows nested keys, this checker will pass a file it did not actually read. The next change, if one is earned, is a real parser plus a fixture file. Until then the contract stays flat, and the limitation stays in the build log.

Decision table for the weekend

Choice	This weekend	Left out	Reason
GET `/notes/{id}`	Keep		The walkthrough has a start and an end
One summary of that note	Optional		Shows model access without a tool loop
Create or edit notes		Skip	A write needs validation, storage, and undo
Accounts on a public host		Skip	A free server demo is not an identity system
Live secrets in the tree		Skip	The demo must run without production credentials
Latency table		Skip	This proposal has no measured timings

The table is the review surface. A teammate can reject a row without reading the handler. If a row cannot name a reason, it does not belong in the cut.

Where free model access and a free server fit

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

MonkeyCode enters this method in one place. A side project can use its free model access and its free server option after the localhost contract already passes. Those two availability claims are the only product facts this log uses. Model names, token quotas, hardware size, and how long a free option lasts are not assumed here. They change, and a weekend plan that hard-codes them will go stale before the demo is shown.

The sequence stays ordered.

check_contract.py exits zero on a clean tree.
The GET and the rejected POST both match the expected status codes on 127.0.0.1.
Only then is a free server considered.
The same contract travels with the process. Spare capacity is not a reason to add a write route.
The single model call uses whatever free model access the current docs list. If that list is empty, the note lookup still ships.

The lookup is the demo. The summary is color. A missing model must not expand the tool list, and a free host must not become the place where an untested write is tried "because the machine is already up."

Before any bind past localhost, the operator reads the current project documentation and stops if the documented limits do not cover a one-call read. No quota figure in a chat thread replaces that check.

What the skip ledger holds

The ledger is a file in the tree, not a memory of what felt hard on Saturday.

Note creation stays out, because a write path needs validation and a rollback story.
A tool loop stays out, because a second call hides cost and makes the walkthrough non-deterministic.
Login stays out, because accounts on a public free server are a different product.
A benchmark table stays out, because this proposal was not timed.
Any claim that a free option is permanent stays out, because permanence was not verified.

Skipped work is still work. Naming it keeps the next weekend from pretending the cut was an accident.

# skips.md
- No create/update/delete: needs storage and undo.
- No second model call: one summary is the ceiling.
- No accounts: public hosting is not an identity system.
- No quota or hardware claims: confirm current docs instead.

Who should not use this cut

This approach is a bad fit when the side project is the write. A form that must save data, a bot that must open a pull request, or a demo whose point is multi-step tool use will be distorted by a read-only contract. Forcing those projects through this checker produces a demo that cannot show the actual behavior.

Teams that need audited production controls should not treat the script as a security review. It does not parse full YAML, does not scan dependencies, and does not prove that a model will refuse a harmful request. It only checks a flat contract and an empty-or-missing ledger.

Anyone pasting live credentials into the demo to see whether a free server responds is outside the method. The read path is designed to run without production tokens. A secret that appears in the tree has already failed the weekend, even if the HTTP status codes look right.

Close the weekend on the contract

The weekend ends when one GET works, one write is rejected, the skip ledger is non-empty, and the checker exits zero. Hosting and model access remain optional layers on top of that result. Readers who want to try the same cut can review MonkeyCode's current free model access and free server option, then confirm the docs before binding anything past localhost.

Pin the Fixture Before a Weekend Agent Demo Leaves Localhost

Charlie Hu — Thu, 08 Oct 2026 10:37:25 +0000

A weekend agent demo survives Monday only when three files travel with the code: a frozen task fixture, an endpoint pin, and a local usage ceiling. Free model access can execute that fixture. It should not decide what the demo is.

This log is a scope cut for one side project. It is not a product review, and it is not a benchmark. The scripts are proposed examples. They were not run against a live quota, and they report no latency, accuracy, or cost.

Cut the demo to one label

The finished path does one thing. It reads a synthetic support note and writes one label: billing, access, or other. There is no second task hiding in the same function.

That limit is what makes the weekend reviewable. A demo that also opens tickets, browses a docs site, and drafts a reply cannot be hashed as a single input. When the label flips on Monday, the author will not know which extra behavior moved.

The note is invented. Names, invoices, and symptoms in the fixture are placeholders. A copied inbox, a production log, or a real company identifier does not enter this directory. Public write-ups about models noticing a live target are a reason to stay on fake text. They are not a procedure to repeat, and this log does not describe one.

Files that define done

Four paths are the whole project. Anything beyond them is a different weekend.

fixtures/note.txt is the only model input.
pins/demo_pin.json stores the fixture hash, base URL, model id, character ceiling, and a network flag.
scripts/pin_check.py exits non-zero when those fields disagree with disk.
scripts/run_demo.py prints a label from a local stub, or from the pinned endpoint if the flag allows it.

Skipped on purpose: a web UI, streaming output, automatic retries, extra tools, and any store of past runs. Those pieces answer different questions. This cut asks whether the same note still maps to a label after the endpoint changes.

Freeze the note

The fixture stays short so a human can read it during review. The refund wording is there so the stub has an obvious branch. No card number, no email address, and no account id appear.

Customer asked for a refund on invoice 1842 after a duplicate charge.
No payment instrument is included in this synthetic note.

A longer note is a different task. If the file grows past the pin's character ceiling, the checker fails closed. Growing the fixture and raising the ceiling in the same commit is a scope change, and it should look like one in review.

Pin data, not a slogan

The pin is configuration. The model id is whatever string the operator copies from current documentation on the day of the run. This log does not nominate a model, a hardware shape, a duration, or a token grant.

{
  "fixture": "fixtures/note.txt",
  "fixture_sha256": "REPLACE_AFTER_HASH",
  "base_url": "http://127.0.0.1:8787",
  "model_id": "REPLACE_FROM_CURRENT_DOCS",
  "max_chars": 1200,
  "allow_network": false
}

allow_network begins false. The first passing run never leaves the machine. Switching the base URL to a hosted server is a deliberate edit, reviewed like any other config change.

Refuse the run when the pin drifts

The checker below is unexecuted example code. Run it locally, and keep the exit codes only after they match the operator's tree.

import hashlib
import json
import pathlib
import sys

ROOT = pathlib.Path(__file__).resolve().parents[1]

def file_sha256(path: pathlib.Path) -> str:
    return hashlib.sha256(path.read_bytes()).hexdigest()

def main() -> int:
    pin = json.loads((ROOT / "pins/demo_pin.json").read_text())
    fixture = ROOT / pin["fixture"]
    text = fixture.read_text(encoding="utf-8")
    if file_sha256(fixture) != pin["fixture_sha256"]:
        print("fixture hash drift", file=sys.stderr)
        return 2
    if len(text) > int(pin["max_chars"]):
        print("fixture exceeds local ceiling", file=sys.stderr)
        return 3
    local = pin["base_url"].startswith("http://127.0.0.1")
    if not pin["allow_network"] and not local:
        print("network disabled; pin is not local", file=sys.stderr)
        return 4
    print("pin ok")
    return 0

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

max_chars is not a billing tokenizer. It cannot prove what a vendor will meter. It only stops a swollen file from masquerading as the weekend task. Real usage, if the vendor shows it, is read from that vendor's own page on the day of the call.

Exit codes stay boring on purpose. 2 means the note changed. 3 means the local ceiling was crossed. 4 means the pin points off-box while network is still forbidden. A later script can map those codes to a message, but the weekend version should fail in a way a human can see in the terminal.

Prove the layout before any network call

Hash the fixture, write the digest into the pin, then check. The stub comes last among the local steps, and it still does not open a socket.

python -c "import hashlib,pathlib; p=pathlib.Path('fixtures/note.txt'); print(hashlib.sha256(p.read_bytes()).hexdigest())"
python scripts/pin_check.py
python scripts/run_demo.py --mode stub

The stub is intentionally crude. It exists so out/last_label.txt has a writer before a hosted model is introduced.

def stub_label(text: str) -> str:
    lowered = text.lower()
    if "invoice" in lowered or "refund" in lowered:
        return "billing"
    if "password" in lowered or "login" in lowered:
        return "access"
    return "other"

A keyword map will mis-label paraphrases. That failure is acceptable here. The log does not claim the stub, or any later model, is accurate. Accuracy would need a labeled set and a scored run, and neither is part of this cut.

The runner should pass --mode stub straight to that function and write the returned word. A hosted mode, if added later, should send the fixture bytes and store the label the same way. Two writers for one output file will make Monday's diff lie about which path produced it.

Where hosted free access fits

Once the stub writes a label from the hashed note, the same bytes can be posted to a hosted endpoint. MonkeyCode is the hosted option this log considers. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The operator supplied two availability claims and no further product sheet: free model access, and a free server option. The project was also described as open source. This draft does not verify a license, a repository statistic, a model list, or a numeric quota. It does not state that either free option is permanent, faster, or sufficient for a given hardware need.

A remembered token quota does not belong in the pin or in the article. Quotas change, and a number carried from an older page is how weekend write-ups go stale. Copy the model id from the current docs into an uncommitted pin. Leave the committed pin on localhost with allow_network set to false.

Choose the runner from the constraint

Constraint	Runner	Why
Layout or hash still failing	Local stub	A remote call will not fix a bad fixture
Need the label on a second machine without a private GPU	Hosted free server, if today's terms allow	The fixture stays the same; only the base URL changes
Note contains secrets or personal data	Stop	Hosted access does not make that upload acceptable
Need an SLA, a private network, or a frozen model build	Stop	A weekend pin is not a production control
Hoping for a speed or quality ranking	Stop	This log did not measure either

Remove the product name and the label task still stands. That is the test for whether the mention is doing work. Here it only names one place a free hosted process might execute the already-pinned fixture.

What the weekend refuses to add

The skip list is part of the result, not a backlog disguised as depth.

No tool registry, loop cap, or turn budget. Those controls solve other failures and are not restated as if they were new.
No retry loop. A refused or timed-out call stops, so a free pool is not burned by an unattended script this log does not implement.
No scoreboard. One synthetic note cannot support a quality claim.
No sign-up flow, no shared server, and no background worker.
No comparison that calls one host faster, cheaper, or stronger. That run was not performed.

If a later weekend adds retries, it needs its own ceiling and its own log. Bolting them onto this pin would hide the drift check.

Limits, and who should not use the pin

The checker trusts a file the operator can edit. It is a drift tripwire, not an authorization boundary. Flipping allow_network to true is a one-line change. Review that line the same way a dependency bump is reviewed.

A matching hash does not make a fixture safe. It only shows the fixture is the same file that was reviewed. Confidential text remains confidential after hashing. A local character ceiling is also not a cost cap, because the vendor may tokenize differently, add system text, or meter a failed request.

Walk away from this approach when any of the following is true.

The input is production data, a credential, or customer text.
The team needs retention controls, a private network path, or a contractual uptime target.
The reader came for benchmark numbers. None are available from this draft.
The pin is expected to stop a determined caller. It will not.

Free model access and a free server can also throttle, expire, or change models without this repository noticing. A demo that works only while a grant remains has an external dependency. Stub mode is the path that does not depend on that grant.

Before the demo is shown to anyone

Run the checker on a clean tree. Confirm the committed pin still points at 127.0.0.1 and still disables network. If a hosted trial is useful, keep that URL in an uncommitted pin and read the vendor page the same day for model ids and server terms.

For that trial, the current MonkeyCode docs are the place to confirm free model access and the free server option, then paste only those live values into the uncommitted pin. Do not promote a remembered quota into the article, the README, or the fixture.

Monday's reader should be able to hash the note, run the stub, and see the same label path without creating an account. That is the bar this cut was built to clear.

Freeze the Fixture: A Weekend Demo Lock for Agent Side Projects

Charlie Hu — Thu, 08 Oct 2026 08:17:51 +0000

A weekend agent demo stays reviewable when the sample input, the allowed write, and the stop check are frozen before any model call. A larger prompt does not hold that line. This build log cuts the work to one fixture, one patch tray, and one local command, then records what was left out.

The demo turns three markdown notes into one summary file. An agent may propose a unified diff. It may not edit the fixture, read secrets, or open a pull request. The demo is done when a checker applies that diff to a temporary copy and a tiny script exits zero.

The cut

Side-project scope dies in the second feature. The list below is the whole product for the weekend, not a preface to a platform.

Keep one fixture directory with three notes.
Allow one write path, fixtures/notes/out/summary.md.
Accept a unified diff only from inbox/proposal.diff.
Apply that diff on a copy, never on the working tree.
Stop after one check script. No retry loop and no second tool.

A chat pane, a web search step, and an auto-merge button are skips. They do not become Sunday work.

Freeze inputs before the model

Live model output drifts between Saturday and the next show-and-tell. A demo that cannot be replayed against the same notes cannot be compared, reviewed, or trusted twice. The lock file stores hashes of the input notes and the only path a patch may create. The model is invited after that file exists, not before.

Hashing is a local step. It does not need an account, a server, or a network call.

python3 scripts/demo_lock.py hash --lock demo.lock.json
python3 scripts/demo_lock.py check --lock demo.lock.json --patch inbox/proposal.diff

The first command rewrites the inputs map. The second command is the demo. A non-zero exit leaves the inbox file in place and the fixture inputs unchanged.

The lock file

The lock is JSON checked into the repo. It names the fixture, the allowed write, a byte cap, forbidden prefixes, and the check command. The hashes below are placeholders for the shape of the file. They are not measured outputs from a run.

{
  "name": "weekend-notes-demo",
  "fixture_dir": "fixtures/notes",
  "allowed_writes": ["fixtures/notes/out/summary.md"],
  "forbidden_prefixes": [".git/", ".env", "secrets/"],
  "max_patch_bytes": 8192,
  "checks": ["python3 scripts/check_summary.py"],
  "inputs": {
    "fixtures/notes/in/01-standup.md": "<sha256>",
    "fixtures/notes/in/02-bug.md": "<sha256>",
    "fixtures/notes/in/03-ship.md": "<sha256>"
  }
}

A lock without hashes is a wish list. Fill the hashes, commit the lock, and only then ask for a diff.

What stays, what goes

The cut is easier to keep when it is a table instead of a mood.

Signal during the weekend	Decision
Diff touches only `summary.md`	Keep. Run the checker.
Diff adds a dependency or a second file	Skip. Do not widen the lock.
Check fails on the first patch	Stop. Read the diff. No automatic retry.
A second fixture would make a nicer demo	Skip. One fixture is the demo.
The summary sounds fluent but misses the bug	Fail the check, or accept that prose quality is out of scope.
Someone asks for a hosted chat	Skip. The interface is an exit code.

The checker

The script below is a proposal. It was not executed against a live model for this draft. It refuses an oversized patch, refuses paths outside the single allowed write, verifies input hashes, copies the tree, runs git apply --check, applies the diff on that copy, then runs the check command with the working directory pinned to the copy.

Path rules

Only +++ and --- lines are inspected, which is enough to reject a casual extra file and not enough to understand every diff feature. A hit on a forbidden prefix, or any path outside allowed_writes, stops the run before Git is invoked. /dev/null is ignored so a new-file diff can still name the one allowed summary path.

Apply on a copy

git apply --check is the real apply gate. The proposal script never points that command at the working tree. The copy drops .git and inbox so a dirty inbox cannot leak into the stage. The check command is read from the lock, split with shlex, and run without a shell, so a patch cannot rewrite the command that judges it. Keep the lock file out of allowed_writes.

#!/usr/bin/env python3
"""Proposal: freeze a weekend demo fixture before any model call."""

import argparse
import hashlib
import json
import shlex
import shutil
import subprocess
import sys
import tempfile
from pathlib import Path

def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    digest.update(path.read_bytes())
    return digest.hexdigest()

def load_lock(path: Path) -> dict:
    data = json.loads(path.read_text(encoding="utf-8"))
    required = (
        "fixture_dir",
        "allowed_writes",
        "forbidden_prefixes",
        "max_patch_bytes",
        "checks",
    )
    missing = [key for key in required if key not in data]
    if missing:
        raise SystemExit("lock missing keys: " + ", ".join(missing))
    return data

def verify_inputs(lock: dict, root: Path) -> None:
    inputs = lock.get("inputs") or {}
    if not inputs:
        raise SystemExit("lock has no input hashes; run hash first")
    for rel, expected in inputs.items():
        path = root / rel
        if not path.is_file():
            raise SystemExit("missing input: " + rel)
        if sha256_file(path) != expected:
            raise SystemExit("fixture drift: " + rel)

def reject_patch(lock: dict, patch_text: str) -> None:
    if len(patch_text.encode("utf-8")) > int(lock["max_patch_bytes"]):
        raise SystemExit("patch exceeds max_patch_bytes")
    for line in patch_text.splitlines():
        if not (line.startswith("+++ ") or line.startswith("--- ")):
            continue
        raw = line[4:].strip()
        if raw == "/dev/null":
            continue
        rel = raw[2:] if raw.startswith(("a/", "b/")) else raw
        blocked = any(rel.startswith(prefix) for prefix in lock["forbidden_prefixes"])
        if blocked or rel not in lock["allowed_writes"]:
            raise SystemExit("path rejected: " + rel)

def apply_on_copy(lock: dict, root: Path, patch_path: Path) -> int:
    fixture = root / lock["fixture_dir"]
    if not fixture.is_dir():
        raise SystemExit("missing fixture: " + str(fixture))
    with tempfile.TemporaryDirectory(prefix="demo-lock-") as tmp:
        stage = Path(tmp) / "stage"
        shutil.copytree(root, stage, ignore=shutil.ignore_patterns(".git", "inbox"))
        probe = subprocess.run(
            ["git", "apply", "--check", str(patch_path)],
            cwd=stage,
            capture_output=True,
            text=True,
        )
        if probe.returncode != 0:
            sys.stderr.write(probe.stderr)
            return probe.returncode
        applied = subprocess.run(
            ["git", "apply", str(patch_path)],
            cwd=stage,
            capture_output=True,
            text=True,
        )
        if applied.returncode != 0:
            sys.stderr.write(applied.stderr)
            return applied.returncode
        for command in lock["checks"]:
            result = subprocess.run(shlex.split(command), cwd=stage)
            if result.returncode != 0:
                return result.returncode
    return 0

def hash_inputs(lock_path: Path) -> None:
    lock = load_lock(lock_path)
    root = lock_path.parent
    folder = root / lock["fixture_dir"] / "in"
    inputs = {}
    for path in sorted(folder.glob("*.md")):
        rel = path.relative_to(root).as_posix()
        inputs[rel] = sha256_file(path)
    lock["inputs"] = inputs
    lock_path.write_text(json.dumps(lock, indent=2) + "\n", encoding="utf-8")

def main() -> int:
    parser = argparse.ArgumentParser(description="Check a weekend demo lock")
    parser.add_argument("action", choices=("hash", "check"))
    parser.add_argument("--lock", required=True)
    parser.add_argument("--patch")
    args = parser.parse_args()
    lock_path = Path(args.lock)
    if args.action == "hash":
        hash_inputs(lock_path)
        return 0
    if not args.patch:
        raise SystemExit("check requires --patch")
    lock = load_lock(lock_path)
    verify_inputs(lock, lock_path.parent)
    patch_path = Path(args.patch)
    reject_patch(lock, patch_path.read_text(encoding="utf-8"))
    return apply_on_copy(lock, lock_path.parent, patch_path)

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

The companion check fails closed. A missing file, an empty file, a file past the character cap, or a leftover placeholder is a failed demo. Fluent wording is not a pass.

#!/usr/bin/env python3
"""Proposal: stop check for the notes demo. Not executed in this draft."""

from pathlib import Path
import sys

SUMMARY = Path("fixtures/notes/out/summary.md")
MAX_CHARS = 1200

def main() -> int:
    if not SUMMARY.is_file():
        print("missing summary", file=sys.stderr)
        return 1
    text = SUMMARY.read_text(encoding="utf-8").strip()
    if not text:
        print("empty summary", file=sys.stderr)
        return 1
    if len(text) > MAX_CHARS:
        print("summary too long", file=sys.stderr)
        return 1
    if "TODO" in text or "FIXME" in text:
        print("placeholder left in summary", file=sys.stderr)
        return 1
    return 0

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

Sample notes, not a fake project

The fixture is three short files under fixtures/notes/in/. One file is a standup. One file is a bug note. One file is a ship note. Each file should stay under a few hundred words so the summary cap means something. The summary should mention the bug and the ship decision, and it should not invent a customer, a metric, or a version that the notes do not contain.

This draft does not pretend those notes already exist in a running repo. Write them on Saturday morning, hash them, and stop editing them. A fixture that changes after the model call is not a fixture.

A stronger check can require two literals copied from the notes, such as a bug id and a ship date. That test stays local. It does not ask another model to grade the prose, and it avoids treating a confident paragraph as evidence.

Where a free model and a free server fit

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

The lock, the fixture, and the checker stay on the laptop. Free model access is relevant only as a way to draft inbox/proposal.diff for this one summary path. A free server option is relevant only as a place to run that generate step, not as a home for the fixture or for secrets. This draft does not name a model, a token quota, a machine size, or an end date. Those details were not verified here, and they go stale. Read the current product page before treating either option as a weekend plan. Repository layout, license, and release status are omitted for the same reason.

Use a short generate brief, not a growing prompt. Hand over the three input filenames, the single allowed write path, and the byte cap. Ask for a unified diff and nothing else. If the reply is not a diff, discard it. Do not paste the checker source into the brief. The checker is the judge, not part of the suggestion.

Split the work so a product mention cannot swallow the demo:

Local, required: hash the inputs, store the lock, apply the patch, run the check.
Remote, optional: request one unified diff that touches only the summary path.
Never remote: the lock file, the check script, or any secret.

If the remote step is down, write the diff by hand. The same checker still runs. Removing every product mention leaves a usable workflow.

What the working demo includes

A passing demo is a handful of files and one command, not a hosted app.

demo.lock.json with hashes produced by demo_lock.py hash
Three notes under fixtures/notes/in/
scripts/demo_lock.py and scripts/check_summary.py
One inbox/proposal.diff, from a person or from one model call
A check command that exits 0

python3 scripts/demo_lock.py hash --lock demo.lock.json
python3 scripts/demo_lock.py check --lock demo.lock.json --patch inbox/proposal.diff
echo $?

Exit codes

Zero means the copy applied and the summary check passed. Any other code means the patch stays in the inbox. There is no silent rewrite of the working tree. Run the check twice. The second run should behave the same, because the apply happens in a temp directory that is deleted on the way out.

What was skipped

Skipping is part of the log.

No multi-file refactor. The allowed write list is one path.
No streaming chat, and no second turn when the check fails.
No browser, no package install, and no network call inside the checker.
No automatic commit, push, or pull request.
No benchmark of model quality. A pass means the fixture contract held, not that the prose is good.
No claim about uptime, later pricing, or which model id answered.
No portfolio site, profile renderer, or visual theme. The demo is a command.

Failures to force before Sunday

Treat this list as a test plan. These are not recorded results from a run.

A patch larger than 8192 bytes should exit before git apply.
A diff that edits .env or secrets/notes.md should exit on the path rule.
A diff that creates fixtures/notes/out/extra.md should exit because that path is not allowed.
A summary that contains TODO should fail check_summary.py.
A missing fixtures/notes directory should exit before any apply.
A changed input note should exit with fixture drift before any apply.
A clean diff that writes a short summary without placeholders should be the only green path.
Running the green path twice should not change files under fixtures/notes/in/.

Review the patch with git apply --check on a throwaway clone if the proposal script is still unreviewed. The script is a sketch of the gate, not a substitute for reading the diff.

Limitations

The path parser is naive. Unified diffs can carry renames, quoted paths, and binary sections that this sketch does not fully classify. git apply --check is the real apply gate, and it requires Git on the machine. Patches with CRLF endings and Windows path separators are untested here. Copying the whole tree into a temp directory is fine for a tiny side project and wrong for a monorepo.

The checker does not understand intent. It will accept a fluent summary that still misstates the bug unless the check script encodes a literal from the notes. Hash equality proves the inputs did not change. It does not prove the summary is true.

Do not use this approach for a hosted agent, a multi-tool workflow, or a quality score on prose. Do not use it when the weekend goal is a portfolio site, a game, or a profile page. Those need a different cut. A team that already has a review bot should not replace that bot with this file.

Before calling the weekend done

Confirm the lock hashes match the three notes on disk.
Confirm the inbox holds one diff, not a chain of retries.
Confirm the apply step used a temp copy and left the fixture inputs unchanged.
Confirm the skipped list is still skipped.
Confirm any product sentence in the README matches current docs, not this draft.

If a free server is already available, point only the generate step at it and leave the lock in the repo. If it is not, write the diff by hand and keep the same check. Call the demo done when that command exits 0 on a clean copy, and leave the skip list in the README so the next session does not quietly grow the scope.

A Scope Card Beats a Bigger Prompt: Cutting a Weekend Agent Demo to One Path

Charlie Hu — Thu, 24 Sep 2026 21:34:20 +0000

A weekend agent demo is finished when one named path returns a checked result. A larger prompt does not finish it. Free model access and a free server option lower the cost of a trial, and they leave the failure mode unchanged: the side project dies in unfinished scope.

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. Model names, token quotas, hardware, duration, and permanence are omitted because they were not verified for this draft. Current docs should be checked before either option is treated as a fixed budget.

The public posts on this account already cover small controls around agent side projects: merge gates, tool allowlists, call envelopes, circuit breakers, dry-run staging, and worker heartbeats. This note does not rebuild those controls. It covers the cut that has to happen before any of them earn a place in a two-day repo. The audience is a developer shipping a narrow demo, not a team designing a platform.

Cut first, then host

The working demo is a local command. It reads a scope card, accepts one intent, and prints a fixture result plus an explicit skip ledger. A live call stays behind a flag that defaults to off.

A free server can host that same process later. It is not required to prove the slice. Saturday defines the card. Sunday runs the fixture path and writes down what was refused.

Anything that needs a model token is a follow-up slice, and only if the fixture cannot show the response shape honestly. That order is the method. Hosting is a later convenience, not the proof.

Scope card

The card is JSON so the draft runner has no parser dependency. Field names stay blunt on purpose. A reader should see the cut without a diagram.

{
  "slice_id": "invoice-status-v0",
  "allowed_intents": ["lookup_invoice_status"],
  "fixture": {
    "tool": "billing.lookup",
    "input": {"invoice_id": "INV-1042"},
    "output": {"status": "open", "currency": "USD", "amount_cents": 4200}
  },
  "skipped": [
    "multi-invoice search",
    "refunds and other writes",
    "a browser UI",
    "retries, workers, and cron",
    "a second model call to explain the status"
  ],
  "live": {
    "enabled_by_default": false,
    "env_base_url": "AGENT_SLICE_BASE_URL",
    "path": "/v0/slice",
    "timeout_seconds": 10
  }
}

slice_id names the demo. allowed_intents is a closed set. fixture is the result a reviewer can rerun without an account. skipped is the scope cut, stored as data so it shows up in the command output.

live records how a later call would be addressed. The path /v0/slice is a local contract for this side project. It is not a documented vendor endpoint, and it should not be copied into a client as if it were one.

Runner

The module below is a proposal. It has not been timed, load-tested, or pointed at a hosted offer. It refuses unknown intents before any network call. It replays the fixture unless --live is set. It prints the skip list on every exit path so a green demo cannot hide the cut.

#!/usr/bin/env python3
"""Unexecuted proposal: one-intent scope runner for a weekend demo."""

from __future__ import annotations

import argparse
import json
import os
import sys
import urllib.error
import urllib.request
from pathlib import Path


def load_card(path: Path) -> dict:
    try:
        card = json.loads(path.read_text(encoding="utf-8"))
    except json.JSONDecodeError as exc:
        raise SystemExit(f"card_not_json: {exc}") from exc
    for key in ("slice_id", "allowed_intents", "fixture", "skipped", "live"):
        if key not in card:
            raise SystemExit(f"card_missing_field: {key}")
    if not isinstance(card["allowed_intents"], list) or not card["allowed_intents"]:
        raise SystemExit("card_needs_one_intent")
    return card


def decide(card: dict, intent: str, live: bool) -> dict:
    skipped = list(card.get("skipped") or [])
    allowed = set(card["allowed_intents"])
    if intent not in allowed:
        return {
            "ok": False,
            "slice_id": card["slice_id"],
            "reason": "intent_outside_slice",
            "skipped": skipped,
        }
    if not live:
        return {
            "ok": True,
            "slice_id": card["slice_id"],
            "mode": "fixture",
            "result": card["fixture"]["output"],
            "skipped": skipped,
        }
    env_name = card["live"]["env_base_url"]
    base = os.environ.get(env_name, "").rstrip("/")
    if not base:
        return {
            "ok": False,
            "slice_id": card["slice_id"],
            "reason": "live_requested_but_base_url_missing",
            "skipped": skipped,
        }
    payload = json.dumps(
        {
            "slice_id": card["slice_id"],
            "intent": intent,
            "input": card["fixture"]["input"],
        }
    ).encode("utf-8")
    timeout = int(card["live"].get("timeout_seconds", 10))
    req = urllib.request.Request(
        base + card["live"]["path"],
        data=payload,
        headers={"content-type": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            body = json.loads(resp.read().decode("utf-8"))
    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
        return {
            "ok": False,
            "slice_id": card["slice_id"],
            "reason": "live_call_failed",
            "detail": type(exc).__name__,
            "skipped": skipped,
        }
    return {
        "ok": True,
        "slice_id": card["slice_id"],
        "mode": "live",
        "result": body,
        "skipped": skipped,
    }


def main() -> int:
    parser = argparse.ArgumentParser(description="Run one scoped demo path")
    parser.add_argument("--card", required=True)
    parser.add_argument("--intent", required=True)
    parser.add_argument("--live", action="store_true")
    args = parser.parse_args()
    report = decide(load_card(Path(args.card)), args.intent, args.live)
    json.dump(report, sys.stdout, indent=2)
    sys.stdout.write("\n")
    return 0 if report.get("ok") else 2


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

Two behaviors are deliberate. The live failure returns an error type, not the exception text, so a URL or upstream body is less likely to land in a pasted demo log. The fixture path never reads AGENT_SLICE_BASE_URL.

A configured host cannot change the default demo. That split is what makes the weekend rerunnable after a laptop reboot, with or without a network.

Commands and expected reports

Save the card as scope.invoice.json and the module as slice_runner.py. Then run the dry path:

python3 slice_runner.py \
  --card scope.invoice.json \
  --intent lookup_invoice_status

The expected report shape is:

{
  "ok": true,
  "slice_id": "invoice-status-v0",
  "mode": "fixture",
  "result": {"status": "open", "currency": "USD", "amount_cents": 4200},
  "skipped": ["multi-invoice search", "refunds and other writes"]
}

An intent outside the card must fail closed, with no socket:

python3 slice_runner.py \
  --card scope.invoice.json \
  --intent refund_invoice
echo "exit=$?"

reason should be intent_outside_slice, and the exit code should be 2. The skip list should still print. A reviewer who asks for refunds gets a recorded refusal, not a silent success.

Requesting a live call without the env var is the third check:

python3 slice_runner.py \
  --card scope.invoice.json \
  --intent lookup_invoice_status \
  --live

Expected reason: live_requested_but_base_url_missing. The runner must not guess a host, and it must not fall back to the fixture while claiming a live result. Those are different failures. Mixing them makes the demo look healthier than the setup is.

Decision table

Weekend pressure	Keep in v0	Replace with the fixture	Write into `skipped`
Add one more intent	Only if the sentence still names one path	—	The extra intent
Show a model answer	Only for a field the fixture cannot shape	Status, amount, currency	Explanations and chat
Put it on a server	One process, one route, after the local command works	A checked-in JSON file	Queues and background jobs
Make it look finished	The skip list in the output	—	A UI that hides skips
Handle failure	Non-zero exit and a reason code	—	Retries and backoff trees

Use the table as a review checklist, not as a slogan. If a row cannot be filled without inventing a metric, the row stays blank and the work stays skipped.

Where a free route actually helps

Free model access is relevant on the step a fixture would fake. In this invoice slice, that step does not exist yet. Status, currency, and amount are canned. A later card might allow one intent, classify_invoice_note, whose input is a short ambiguous string and whose output is a label plus a reason code.

That is the first honest use of a model. It is still one request, still checked against allowed_intents, and still off unless --live is passed. A free server option is relevant after that local command is boring.

Copy the same three files to the host, set the base URL only for the live flag, and keep the fixture command as the regression check. Region, size, and how long the offer lasts are not known here. If the host is unavailable on demo day, the fixture path still runs on a laptop. That fallback is the reason the card exists.

Do not treat either option as a capacity plan. This draft measured nothing: no latency, no token count, no concurrency. A number copied from an older post would be worse than a blank. Confirm the current terms in the product docs before spending a weekend on a live flag.

What the weekend skips

The skip list is the build log. It is not a backlog disguised as humility.

No planner loop. One intent in, one result out. Turn caps belong to a different note.
No tool bus. The fixture names one tool string. It does not route, stage, or allowlist a catalog.
No receipt book and no heartbeat. Those mechanisms answer other questions. Pulling them in would erase the cut.
No write path. Refunds stay skipped because a demo mutation is how a side project stops being a demo.
No second model call to explain the status. Explanation text is how scope leaks back in.
No claim about a token pool, a machine size, or an end date. Unverified numbers stay out of the README as well as this page.

Failure notes worth keeping

A few failures are more instructive than the happy path.

A card with an empty allowed_intents list should exit on load. A slice that allows everything is not a slice.
A live timeout should surface as live_call_failed with detail set to the exception type. The demo script can then say the host did not answer, which is a true statement.
A fixture output that omits a field the reviewer expects should be fixed in the card, not patched in the runner. Hidden defaults recreate the unfinished product.
Editing skipped without editing the spoken demo is a process bug. The command output is the script.

Clear field names do more work here than a comment. If skipped needs a paragraph to explain itself, the cut is still fuzzy and the card is not ready to demo.

Test plan before calling it a demo

These checks are local and manual until they are pasted into a real file and run. Until then they are a plan, not a result.

Parse failure: truncate the JSON and confirm a non-zero exit with card_not_json.
Missing field: delete skipped and confirm card_missing_field.
Fixture path: allowed intent, no --live, result equals fixture.output.
Reject path: unknown intent, no socket, exit code 2.
Live guard: --live and an empty base URL, no guessed host, no fixture fallback.
Skip visibility: every string in skipped appears in the report for both success and refusal.
Timeout lock: timeout_seconds stays at 10. A hung process must not become the demo.

A single assertion can lock check 3 once the function is imported:

def test_fixture_path():
    card = {
        "slice_id": "invoice-status-v0",
        "allowed_intents": ["lookup_invoice_status"],
        "fixture": {"output": {"status": "open"}},
        "skipped": ["refunds and other writes"],
        "live": {"env_base_url": "AGENT_SLICE_BASE_URL", "path": "/v0/slice"},
    }
    report = decide(card, "lookup_invoice_status", live=False)
    assert report["mode"] == "fixture"
    assert report["result"]["status"] == "open"
    assert report["skipped"] == ["refunds and other writes"]

Run it only after the file exists in the repo. A pasted assertion is not a passing suite. Record the command and the exit code in the README next to the skip list, so the next session does not have to reconstruct the demo from memory.

Who should not use this

This runner is a scope fence for a side project. It is not authentication, not authorization, and not a sandbox. A person who can edit the card can widen the slice. A person who can set the base URL can send the payload to an unintended host.

Skip the approach when any of these are true:

The demo must mutate real billing data or other customer state.
A reviewer has already been promised several intents. Cut the promise before writing code.
The audience needs a latency, cost, or uptime figure. None were measured.
The host must stay up unattended. This draft does not establish that.
Secrets need more care than one env var that is never printed. The example does not redact arbitrary logs.
The work is a multi-tenant product. A JSON card in a repo root is the wrong boundary.

Clear fields beat a cleaner abstraction that hides the skip list. If a comment is required to explain skipped, the field name is wrong, not the reader.

After the card is boring

Leave the card in the repo root. Add a second intent only by copying the card to a new slice_id and deleting the old promises from the spoken demo. If a free model route and a free server are still available for that next slice, spend them on the one step the fixture cannot show, and confirm the current terms before relying on either. The weekend result is the cut. A longer catalog can wait.

Stamp the Run: A Weekend Receipt Book for Agent Side Projects

Charlie Hu — Wed, 23 Sep 2026 17:16:49 +0000

Weekend agent loops fail in the dark. Tools fire, files change, and the process exits with no record of why. A receipt book — one JSON file per run — is the smallest Saturday-scoped fix that still leaves a working demo.

This write-up is a labeled weekend build log, not a production tracing guide. The code is a self-contained example. It records stop reasons, tool names, and touched paths. It does not replay raw model traffic.

Scope cut for one weekend

In scope:

A frozen receipt schema on disk
A tiny Python store with open, record_tool, record_file, and close
A CLI an agent loop can shell out to
Tests that fail if a run ends without a stop reason

Skipped on purpose:

Provider token invoices and live cost dashboards
OpenTelemetry and distributed trace graphs
Encryption at rest and multi-user auth
Concurrent writers and an HTTP API

The cut is the product. A receipt that always closes beats a half-finished observability stack.

The receipt schema

Each run writes receipts/<run_id>.json. Fields earn their keep or they stay out.

{
  "run_id": "9f3c1a2e-6b44-4d1a-9c0e-0c7b2d8a1111",
  "started_at": "2026-09-23T10:00:00+00:00",
  "ended_at": null,
  "status": "open",
  "stop_reason": null,
  "tool_calls": [],
  "files_touched": [],
  "call_count": 0,
  "notes": []
}

Rules that keep the file greppable:

status is only open or closed.
close refuses to write when stop_reason is missing.
Tool records store a name, ok/error, and a 200-character detail cap.
File records store a path, an action (read | write | delete), and a dry_run flag.
call_count is a local increment, not a vendor bill.

A cassette records raw model I/O for replay. This receipt is the opposite: a human summary that is safe to commit, grep, and diff.

Working demo: the store

Label: example code, not a published package. Python 3.11+ and the standard library are enough.

# receipt_book.py
from __future__ import annotations

import argparse
import json
import uuid
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Literal

ROOT = Path("receipts")
DETAIL_CAP = 200
StopReason = Literal["success", "max_turns", "tool_error", "user_abort", "unknown"]
FileAction = Literal["read", "write", "delete"]


def _now() -> str:
    return datetime.now(timezone.utc).isoformat()


def _path(run_id: str) -> Path:
    ROOT.mkdir(parents=True, exist_ok=True)
    return ROOT / f"{run_id}.json"


def _load(run_id: str) -> dict[str, Any]:
    path = _path(run_id)
    if not path.exists():
        raise FileNotFoundError(f"no receipt for {run_id}")
    return json.loads(path.read_text(encoding="utf-8"))


def _save(doc: dict[str, Any]) -> None:
    path = _path(doc["run_id"])
    tmp = path.with_suffix(".json.tmp")
    tmp.write_text(json.dumps(doc, indent=2, sort_keys=True) + "\n", encoding="utf-8")
    tmp.replace(path)


def open_run() -> str:
    run_id = str(uuid.uuid4())
    _save(
        {
            "run_id": run_id,
            "started_at": _now(),
            "ended_at": None,
            "status": "open",
            "stop_reason": None,
            "tool_calls": [],
            "files_touched": [],
            "call_count": 0,
            "notes": [],
        }
    )
    return run_id


def record_tool(run_id: str, name: str, ok: bool, detail: str = "") -> None:
    doc = _load(run_id)
    if doc["status"] != "open":
        raise RuntimeError("cannot record on a closed receipt")
    doc["tool_calls"].append(
        {"name": name, "ok": ok, "detail": detail[:DETAIL_CAP], "at": _now()}
    )
    doc["call_count"] += 1
    _save(doc)


def record_file(run_id: str, path: str, action: FileAction, dry_run: bool) -> None:
    doc = _load(run_id)
    if doc["status"] != "open":
        raise RuntimeError("cannot record on a closed receipt")
    doc["files_touched"].append(
        {"path": path, "action": action, "dry_run": dry_run, "at": _now()}
    )
    _save(doc)


def close_run(run_id: str, stop_reason: StopReason) -> dict[str, Any]:
    doc = _load(run_id)
    if doc["status"] == "closed":
        return doc
    if not stop_reason:
        raise ValueError("stop_reason is required")
    doc["status"] = "closed"
    doc["stop_reason"] = stop_reason
    doc["ended_at"] = _now()
    _save(doc)
    return doc


def main() -> None:
    parser = argparse.ArgumentParser(prog="receipt")
    sub = parser.add_subparsers(dest="cmd", required=True)
    sub.add_parser("open")
    p_tool = sub.add_parser("tool")
    p_tool.add_argument("run_id")
    p_tool.add_argument("name")
    p_tool.add_argument("--ok", action="store_true")
    p_tool.add_argument("--detail", default="")
    p_file = sub.add_parser("file")
    p_file.add_argument("run_id")
    p_file.add_argument("path")
    p_file.add_argument("action", choices=["read", "write", "delete"])
    p_file.add_argument("--dry-run", action="store_true")
    p_close = sub.add_parser("close")
    p_close.add_argument("run_id")
    p_close.add_argument(
        "stop_reason",
        choices=["success", "max_turns", "tool_error", "user_abort", "unknown"],
    )
    args = parser.parse_args()
    if args.cmd == "open":
        print(open_run())
    elif args.cmd == "tool":
        record_tool(args.run_id, args.name, args.ok, args.detail)
    elif args.cmd == "file":
        record_file(args.run_id, args.path, args.action, args.dry_run)
    elif args.cmd == "close":
        close_run(args.run_id, args.stop_reason)


if __name__ == "__main__":
    main()

Atomic replace through a .tmp file is the whole durability story. A crash mid-write should not leave half a JSON object.

Saturday commands look like this:

RUN_ID=$(python receipt_book.py open)
python receipt_book.py tool "$RUN_ID" list_dir --ok --detail "src/"
python receipt_book.py file "$RUN_ID" src/app.py write --dry-run
python receipt_book.py close "$RUN_ID" success
cat "receipts/${RUN_ID}.json"

A one-liner then lists every run on Sunday morning:

python - <<'PY'
import json
from pathlib import Path
for p in sorted(Path("receipts").glob("*.json")):
    doc = json.loads(p.read_text())
    print(
        f"{doc['run_id'][:8]} {doc['status']:6} {doc['stop_reason']!s:10} "
        f"calls={doc['call_count']} files={len(doc['files_touched'])}"
    )
PY

Open rows are the ones that died without close. That grep is the debugging workflow.

Wiring a toy agent loop

Label: example loop. The planner is a stub. Swap it for any local or remote model client without touching the receipt schema.

# toy_loop.py
from receipt_book import close_run, open_run, record_file, record_tool

MAX_TURNS = 4
ALLOWED = {"list_dir", "read_file", "dry_write"}


def planner(turn: int) -> dict:
    # Placeholder planner. Real loops call a model here.
    if turn == 0:
        return {"tool": "list_dir", "arg": "src"}
    if turn == 1:
        return {"tool": "dry_write", "arg": "src/app.py"}
    return {"tool": "stop", "arg": "success"}


def run() -> str:
    run_id = open_run()
    try:
        for turn in range(MAX_TURNS):
            step = planner(turn)
            name = step["tool"]
            if name == "stop":
                close_run(run_id, "success")
                return run_id
            if name not in ALLOWED:
                record_tool(run_id, name, False, "blocked")
                close_run(run_id, "tool_error")
                return run_id
            record_tool(run_id, name, True, step["arg"])
            if name == "dry_write":
                record_file(run_id, step["arg"], "write", dry_run=True)
        close_run(run_id, "max_turns")
        return run_id
    except Exception as exc:
        record_tool(run_id, "loop", False, str(exc))
        close_run(run_id, "unknown")
        raise


if __name__ == "__main__":
    print(run())

The loop always closes. Exceptions still write unknown. That is the entire reliability claim for the weekend.

Tests that fail closed

# test_receipt_book.py
from pathlib import Path

import pytest

import receipt_book as rb


def test_close_requires_stop_reason(tmp_path, monkeypatch):
    monkeypatch.setattr(rb, "ROOT", tmp_path)
    run_id = rb.open_run()
    with pytest.raises(ValueError):
        rb.close_run(run_id, "")  # type: ignore[arg-type]


def test_records_then_closes(tmp_path, monkeypatch):
    monkeypatch.setattr(rb, "ROOT", tmp_path)
    run_id = rb.open_run()
    rb.record_tool(run_id, "list_dir", True, "src")
    rb.record_file(run_id, "src/app.py", "write", True)
    doc = rb.close_run(run_id, "success")
    assert doc["status"] == "closed"
    assert doc["call_count"] == 1
    assert Path(tmp_path, f"{run_id}.json").exists()


def test_no_writes_after_close(tmp_path, monkeypatch):
    monkeypatch.setattr(rb, "ROOT", tmp_path)
    run_id = rb.open_run()
    rb.close_run(run_id, "user_abort")
    with pytest.raises(RuntimeError):
        rb.record_tool(run_id, "list_dir", True, "")


def test_dry_write_leaves_a_file_row(tmp_path, monkeypatch):
    monkeypatch.setattr(rb, "ROOT", tmp_path)
    run_id = rb.open_run()
    rb.record_tool(run_id, "dry_write", True, "src/app.py")
    rb.record_file(run_id, "src/app.py", "write", True)
    doc = rb.close_run(run_id, "success")
    assert doc["files_touched"][0]["dry_run"] is True

pytest -q test_receipt_book.py

A missing stop reason is a failed test, not a log line someone might notice later. The last test encodes an invariant: a dry_write tool call should leave a file row, or the receipt is lying.

Decision table: stamp vs skip

Event	Stamp on the receipt	Skip this weekend
Tool name and ok/error	Yes	Full stdout dumps
File path and action	Yes	File contents
Stop reason	Yes	Secret-bearing stack traces
Local call count	Yes	Vendor token invoices
Raw model prompt	No	Cassette / replay fixtures

The table is the scope cut in one place. If a field is not in the left column, it does not ship before Monday.

Failure analysis from a dry run

Three failure shapes show up in side-project agent loops. The receipt book only helps if each shape maps to a row.

Process killed. kill -9 after _save of an open receipt leaves status=open and ended_at=null. Sunday's listing command surfaces those files. Manual close with unknown is allowed; the CLI will not invent a success.
Planner returns an unknown tool. The loop records ok=false, detail blocked, then closes with tool_error. The allowlist stays in the loop, not in the receipt schema.
Dry-write never recorded. tool_calls contains dry_write while files_touched is empty. That mismatch is a bug in the loop, not in the model. The fourth test above is there to catch it.

None of those cases need a trace backend. They need a file that still exists after the shell is gone.

Where a free remote planner fits

Local loops still need a planner when the weekend machine should not host a large model. A remote coding assistant can return the next tool name. The receipt file stays on disk beside the repo.

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

MonkeyCode offers free model access and a free server option. Those two properties matter here for one reason: the planner can live off-laptop while the receipt file, allowlisted tools, and dry-run writes stay local. The schema does not depend on that product. A different remote endpoint works the same way. This account's relationship is product outreach, not an independent benchmark lab.

A practical split for the same weekend constraint:

Keep receipt_book.py and the tool allowlist on the laptop.
Send the planner only a short state card: last tool, last error, remaining turns.
Write whatever the planner returns onto the receipt before executing it.
Close the receipt even if the remote call fails.

Free remote capacity is optional fuel, not the architecture. The receipt still closes if the network does not.

What this weekend skipped

No token accounting against a vendor bill. call_count is a local counter. No redaction beyond the 200-character cap, so secrets can still leak through detail. No concurrent writers: two processes sharing one run_id can clobber records. No HTTP surface and no UI. The CLI is the API. cat is the UI.

Skipping those items is how the demo stays runnable before Monday. Adding any one of them usually consumes the rest of the weekend.

Limitations

The store is a JSON file. It is not a ledger. Clock skew, a kill after the .tmp write but before replace, and copied receipts across machines are all unhandled. Detail truncation hides the exact error that mattered. Call counts are not money.

The toy planner is a stub. It does not prove model quality, latency, or safety. Dry-run flags are advisory. A loop that ignores dry_run=True will still write to disk.

Who should not use this approach

Teams that already emit structured traces for every tool call
Agents that write production data or customer files
Anyone who needs a legally complete audit log
Multi-tenant services
Workflows that treat a receipt as authorization to re-run destructive tools

Those cases need a sandbox, a real allowlist, and an observability pipeline. A closed JSON receipt will not make an agent safe. It will make Sunday debugging shorter. That is the only claim this weekend build makes.

Stage the Tools: A Weekend Dry-Run Bus for Agent Side Projects

Charlie Hu — Tue, 22 Sep 2026 15:29:02 +0000

Weekend agent side projects usually fail at the tool boundary, not inside the prompt. A model proposes a call, the host runs it, and a missing key or a second retry writes to the wrong path. A dry-run bus records the intended call, checks a tiny contract, and forwards only after that check passes.

This article is a scoped weekend build log for that bus. The working demo is one Python module, a JSONL ticket log, and a short test file. Distributed queues, vendor lock-in, and production tracing were left on the floor.

The problem the bus is for

Side-project agents tend to grow a single run_tool(name, args) function. That function talks to the filesystem, the network, or a shell. It is convenient. It is also how a sloppy loop mutates local state before anyone reads the trace.

Tool-calling tutorials often jump straight to a live API. That is the wrong first step for a Saturday project. The first step is a ticket. Every proposed call becomes a row that can be inspected, rejected, or released.

A dry-run bus sits in front of execution. Live model traffic stays optional until the tickets look honest.

Weekend scope that survived the cut

The build kept three jobs. Everything else was treated as next-month work.

Kept

A JSONL ticket log on disk, one object per line.
A per-tool contract for required keys and simple JSON types.
A live adapter that stays off unless an environment flag is set.

Cut on purpose

Redis, Kafka, or any networked queue.
OpenTelemetry exporters and flame graphs.
Prompt assembly, memory, and retrieval.
Automatic dollar forecasts or vendor price tables.
Multi-user auth.

The goal is a demo that runs before Sunday night. A platform can wait.

Artifact: a ticketed tool bus

The following module is a proposed weekend sketch. It is labeled as unexecuted design until the tests below are run on a local machine. Save it as toolbus.py.

from __future__ import annotations

import json
import os
import time
import uuid
from dataclasses import asdict, dataclass, field
from pathlib import Path
from typing import Any, Callable, Mapping

Json = dict[str, Any]
LiveFn = Callable[[str, Json], Json]

CONTRACTS: dict[str, dict[str, type]] = {
    "read_file": {"path": str},
    "write_file": {"path": str, "contents": str},
    "http_get": {"url": str},
}

FORBIDDEN_KEYS = {"api_key", "token", "password", "authorization"}


@dataclass
class Ticket:
    ticket_id: str
    tool: str
    args: Json
    status: str
    reason: str = ""
    ts: float = field(default_factory=time.time)

    def row(self) -> Json:
        return asdict(self)


class ContractError(ValueError):
    pass


def validate(tool: str, args: Mapping[str, Any]) -> None:
    spec = CONTRACTS.get(tool)
    if spec is None:
        raise ContractError(f"unknown tool: {tool}")
    missing = [k for k in spec if k not in args]
    if missing:
        raise ContractError(f"missing keys: {missing}")
    for key, expected in spec.items():
        if not isinstance(args[key], expected):
            raise ContractError(f"{key} expected {expected.__name__}")
    leaked = FORBIDDEN_KEYS.intersection(args):
    if leaked:
        raise ContractError(f"forbidden keys: {sorted(leaked)}")
    if tool == "http_get":
        url = str(args["url"])
        if not url.startswith(("https://", "http://127.0.0.1", "http://localhost")):
            raise ContractError("url scheme not allowed")
    if tool in {"read_file", "write_file"}:
        path = Path(str(args["path"])).resolve()
        root = Path.cwd().resolve()
        if root not in path.parents and path != root:
            raise ContractError("path escapes workspace")


class ToolBus:
    def __init__(self, ledger: Path, live: LiveFn | None = None) -> None:
        self.ledger = ledger
        self.live = live
        self.ledger.parent.mkdir(parents=True, exist_ok=True)
        self.ledger.touch(exist_ok=True)

    def _append(self, ticket: Ticket) -> None:
        with self.ledger.open("a", encoding="utf-8") as handle:
            handle.write(json.dumps(ticket.row(), ensure_ascii=True) + "\n")

    def stage(self, tool: str, args: Json, *, execute: bool = False) -> Ticket:
        ticket_id = uuid.uuid4().hex[:12]
        try:
            validate(tool, args)
        except ContractError as exc:
            ticket = Ticket(ticket_id, tool, dict(args), "rejected", str(exc))
            self._append(ticket)
            return ticket

        if not execute:
            ticket = Ticket(ticket_id, tool, dict(args), "staged", "dry-run")
            self._append(ticket)
            return ticket

        if self.live is None:
            ticket = Ticket(ticket_id, tool, dict(args), "blocked", "no live adapter")
            self._append(ticket)
            return ticket

        result = self.live(tool, dict(args))
        ticket = Ticket(
            ticket_id,
            tool,
            {"args": dict(args), "result_keys": sorted(result)},
            "executed",
            "live",
        )
        self._append(ticket)
        return ticket

    def pending(self) -> list[Json]:
        rows: list[Json] = []
        for line in self.ledger.read_text(encoding="utf-8").splitlines():
            if not line.strip():
                continue
            row = json.loads(line)
            if row.get("status") == "staged":
                rows.append(row)
        return rows

The bus never executes on stage() unless execute=True. That is the whole weekend trick. Staging is cheap. Execution is a separate, explicit act.

A live adapter can be a local function. It can also be a small HTTP client pointed at an environment URL. The bus does not care. The ledger does.

import json
import urllib.request


def http_live(tool: str, args: dict) -> dict:
    url = os.environ["TOOLBUS_LIVE_URL"]
    payload = json.dumps({"tool": tool, "args": args}).encode("utf-8")
    req = urllib.request.Request(
        url,
        data=payload,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=10) as resp:
        return json.loads(resp.read().decode("utf-8"))

Leave TOOLBUS_LIVE_URL unset during the first evening. The dry-run path still writes tickets. That is enough to review a loop without spending a model call.

Working demo

Create a scratch folder and install nothing beyond the Python standard library.

mkdir -p /tmp/toolbus-demo && cd /tmp/toolbus-demo
cat > toolbus.py <<'PY'
# paste the module above
PY

A tiny driver shows the three ticket states: rejected, staged, and blocked.

# save as demo.py
from pathlib import Path
from toolbus import ToolBus

bus = ToolBus(Path("tickets.jsonl"))

print(bus.stage("wipe_disk", {"path": "/"}).status)
print(bus.stage("read_file", {"path": "README.md"}).status)
print(bus.stage("read_file", {"path": "README.md"}, execute=True).status)
print(len(bus.pending()))

printf '# demo\n' > README.md
python demo.py
cat tickets.jsonl

Expected shape of the log, not a measured benchmark:

wipe_disk lands as rejected with unknown tool.
The first read_file lands as staged.
The second read_file lands as blocked because no live adapter was wired.
pending() returns the staged row only.

That output is the demo. A reader can screenshot the JSONL file and stop. The live lane is optional homework.

Tests that prove the cut is honest

Save the following as test_toolbus.py. The tests pin behavior, not performance.

from pathlib import Path

from toolbus import ToolBus


def test_unknown_tool_is_rejected(tmp_path: Path) -> None:
    bus = ToolBus(tmp_path / "t.jsonl")
    ticket = bus.stage("shell", {"cmd": "ls"})
    assert ticket.status == "rejected"


def test_path_escape_is_rejected(tmp_path: Path) -> None:
    bus = ToolBus(tmp_path / "t.jsonl")
    ticket = bus.stage("write_file", {"path": "../out.txt", "contents": "x"})
    assert ticket.status == "rejected"


def test_dry_run_does_not_call_live(tmp_path: Path) -> None:
    calls: list[str] = []

    def live(tool: str, args: dict) -> dict:
        calls.append(tool)
        return {"ok": True}

    bus = ToolBus(tmp_path / "t.jsonl", live=live)
    ticket = bus.stage("http_get", {"url": "http://127.0.0.1:9/health"})
    assert ticket.status == "staged"
    assert calls == []


def test_execute_uses_live_adapter(tmp_path: Path) -> None:
    def live(tool: str, args: dict) -> dict:
        return {"status": 200, "tool": tool}

    bus = ToolBus(tmp_path / "t.jsonl", live=live)
    ticket = bus.stage(
        "http_get",
        {"url": "http://127.0.0.1:9/health"},
        execute=True,
    )
    assert ticket.status == "executed"

pip install pytest
pytest -q test_toolbus.py

If those four tests pass, the weekend scope is done. Extra assertions about latency or token counts were not part of the cut.

Decision table for dry-run versus live

Use the table as a gate, not as a slogan.

Signal on the ticket	Action	Why
Unknown tool name	Reject	The allow-set is the contract.
Missing or mistyped args	Reject	Live models invent keys.
Forbidden secret-shaped keys	Reject	Tickets are logged in plaintext JSONL.
Path outside the workspace	Reject	Side projects live in one folder.
Contract ok, `execute=False`	Stage	Human or test review still pending.
Contract ok, no live adapter	Block	Fail closed.
Contract ok, live adapter set	Execute	Only this row may touch the network.

The table is the product of the weekend. The Python is just a way to enforce it.

Where a free model lane belongs

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

The bus does not require a hosted model. A free model lane becomes useful only after pending() looks boring: same tools, same keys, no escaped paths. At that point a live adapter can point at a remote endpoint. MonkeyCode's free model access and free server option can host that live lane so the laptop is not both the agent and the dummy API. The bus, the ledger, and the tests stay local.

Do not put secrets in tickets. Do not treat a free lane as a production SLA. The adapter above is a weekend stub with a ten-second timeout and no retries.

What this weekend skipped

Several tempting features were written on a sticky note and then ignored.

Replay of staged tickets into a real filesystem write. Replay needs a second review step.
Canonical JSON hashing for cache hits. Hashing is a different article.
Streaming model output. The bus only sees completed tool argument objects.
Redaction of values already inside file contents. The forbidden-key check is shallow.
A web UI for the JSONL file. cat is enough for one developer.

Skipping those items is the difference between a demo and a half-finished platform. The demo is the point.

Limitations and who should not use this

The contract table is tiny. It understands str and a couple of path rules. Nested objects, arrays, and vendor-specific tool schemas are out of scope. The ledger is append-only plaintext. Anyone with disk access can read every staged URL and path.

This approach is a poor fit for:

Multi-tenant agents that handle other people's data.
Workloads that need an audit log with integrity protection.
Tools that must run with real credentials on the first call.
Long-running workers that already have a queue and a poison-letter policy.

Those projects need a real workflow engine. A weekend JSONL file will lie to them.

The live HTTP helper also has no backoff, no idempotency key, and no TLS pinning beyond what the Python runtime provides. Treat it as a teaching adapter. Replace it before any shared environment sees traffic.

Closing

Stage the tools first. Execute later. A Sunday-night side project stays recoverable when every model-proposed call has a ticket, a contract result, and a line on disk. Wire a free remote lane only after the dry-run log is dull. The dull log is the win.

Cap the Turns: A Weekend Call Envelope for Agent Side Projects

Charlie Hu — Mon, 21 Sep 2026 13:51:58 +0000

A weekend agent loop usually dies from unbounded turns, not from a weak prompt. A file-backed call envelope that refuses the next model or tool invocation after a local budget keeps the experiment from burning idle capacity overnight. The sketch below is small enough to finish in a sitting and strict enough to prove the stop with a test.

The failure this weekend actually needed to stop

Side-project agents retry, reflect, and call tools in a loop. The loop looks healthy. Logs stay green. Tokens still leave the process. Circuit breakers trip on errors. Tool allowlists block the wrong function. Neither construct stops a polite agent that never decides it is done.

Overnight runs make the gap obvious. A single missed max_steps in a toy orchestrator can spend a courtesy budget that was meant to last the week. The envelope treats remaining turns as a first-class resource, not as a comment in a README. Eval suites still matter, but they do not run while the laptop is closed. A hard local halt does.

Scope cut

The lab kept five jobs and dropped the rest. Scope was cut before any client code was written, because the weekend only pays for a working refusal.

In scope

Persist remaining call budget in a JSON file.
Wrap both model calls and tool calls behind one try_consume() gate.
Return a structured refusal the orchestrator can handle without a stack-trace dump.
Ship a CLI to inspect, reset, and dry-run the envelope.
Prove the halt with a unit test that does not talk to a network.

Out of scope for this weekend

Distributed locks across several workers.
Vendor-accurate token billing.
Streaming usage callbacks from a provider.
Multi-tenant quotas.
A web dashboard.

The cut is the point. A finished envelope that stops is more useful than a half-built billing platform.

Envelope rules

The gate is deliberately boring. One process. One file. One lock. Model calls and tool calls share a single counter because weekend agents waste capacity on both.

Event	Remaining calls	Action
`try_consume("model")` and remaining > 0	decrement by 1	allow
`try_consume("tool")` and remaining > 0	decrement by 1	allow
remaining == 0	unchanged	refuse with `EnvelopeEmpty`
`reset(n)`	set to n	allow future consumes
crash mid-write	previous JSON	next start reloads last complete file

Splitting budgets by kind looks sophisticated. It also delays the halt test. That split was left for another sitting.

Working demo

The following Python module is a lab sketch. It is not a production quota service. Copy it into envelope.py and run it locally.

from __future__ import annotations

import argparse
import json
import os
import tempfile
import threading
from dataclasses import dataclass
from pathlib import Path
from typing import Literal

Kind = Literal["model", "tool"]


class EnvelopeEmpty(RuntimeError):
    def __init__(self, kind: Kind, remaining: int) -> None:
        super().__init__(
            f"envelope empty; refused {kind} call; remaining={remaining}"
        )
        self.kind = kind
        self.remaining = remaining


@dataclass
class EnvelopeState:
    remaining: int
    consumed_model: int
    consumed_tool: int

    def to_dict(self) -> dict:
        return {
            "remaining": self.remaining,
            "consumed_model": self.consumed_model,
            "consumed_tool": self.consumed_tool,
        }

    @classmethod
    def from_dict(cls, data: dict) -> "EnvelopeState":
        return cls(
            remaining=int(data["remaining"]),
            consumed_model=int(data.get("consumed_model", 0)),
            consumed_tool=int(data.get("consumed_tool", 0)),
        )


class CallEnvelope:
    def __init__(self, path: Path) -> None:
        self.path = path
        self._lock = threading.Lock()
        self.path.parent.mkdir(parents=True, exist_ok=True)
        if not self.path.exists():
            self._write(
                EnvelopeState(remaining=0, consumed_model=0, consumed_tool=0)
            )

    def _read(self) -> EnvelopeState:
        raw = json.loads(self.path.read_text(encoding="utf-8"))
        return EnvelopeState.from_dict(raw)

    def _write(self, state: EnvelopeState) -> None:
        fd, tmp_name = tempfile.mkstemp(dir=str(self.path.parent), suffix=".tmp")
        try:
            with os.fdopen(fd, "w", encoding="utf-8") as handle:
                json.dump(state.to_dict(), handle, indent=2)
                handle.write("\n")
            os.replace(tmp_name, self.path)
        except Exception:
            if os.path.exists(tmp_name):
                os.remove(tmp_name)
            raise

    def reset(self, remaining: int) -> EnvelopeState:
        if remaining < 0:
            raise ValueError("remaining must be >= 0")
        with self._lock:
            state = EnvelopeState(
                remaining=remaining, consumed_model=0, consumed_tool=0
            )
            self._write(state)
            return state

    def snapshot(self) -> EnvelopeState:
        with self._lock:
            return self._read()

    def try_consume(self, kind: Kind) -> EnvelopeState:
        with self._lock:
            state = self._read()
            if state.remaining <= 0:
                raise EnvelopeEmpty(kind, state.remaining)
            state.remaining -= 1
            if kind == "model":
                state.consumed_model += 1
            else:
                state.consumed_tool += 1
            self._write(state)
            return state


def guarded_model_call(envelope: CallEnvelope, prompt: str) -> str:
    envelope.try_consume("model")
    # Lab stub: replace with the project's real client after tests pass.
    return f"stub-response:{len(prompt)}"


def guarded_tool_call(envelope: CallEnvelope, name: str, payload: dict) -> dict:
    envelope.try_consume("tool")
    return {"tool": name, "ok": True, "echo": payload}


def run_agent_loop(
    envelope: CallEnvelope, steps: list[tuple[Kind, str]]
) -> list[str]:
    log: list[str] = []
    for kind, payload in steps:
        try:
            if kind == "model":
                text = guarded_model_call(envelope, payload)
                log.append(f"model ok: {text}")
            else:
                result = guarded_tool_call(envelope, payload, {"src": "lab"})
                log.append(f"tool ok: {result['tool']}")
        except EnvelopeEmpty as exc:
            log.append(f"halt: {exc}")
            break
    return log


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Weekend call envelope")
    parser.add_argument("--path", default=".agent-envelope.json")
    sub = parser.add_subparsers(dest="cmd", required=True)
    reset = sub.add_parser("reset")
    reset.add_argument("remaining", type=int)
    sub.add_parser("status")
    consume = sub.add_parser("consume")
    consume.add_argument("kind", choices=["model", "tool"])
    demo = sub.add_parser("demo")
    demo.add_argument("--budget", type=int, default=3)
    return parser


def main() -> None:
    args = build_parser().parse_args()
    envelope = CallEnvelope(Path(args.path))
    if args.cmd == "reset":
        state = envelope.reset(args.remaining)
        print(json.dumps(state.to_dict()))
        return
    if args.cmd == "status":
        print(json.dumps(envelope.snapshot().to_dict(), indent=2))
        return
    if args.cmd == "consume":
        try:
            state = envelope.try_consume(args.kind)
            print(json.dumps(state.to_dict()))
        except EnvelopeEmpty as exc:
            print(json.dumps({"error": str(exc), "remaining": exc.remaining}))
            raise SystemExit(2)
        return
    if args.cmd == "demo":
        envelope.reset(args.budget)
        steps: list[tuple[Kind, str]] = [
            ("model", "plan the edit"),
            ("tool", "read_file"),
            ("model", "apply the edit"),
            ("tool", "run_tests"),
            ("model", "summarize"),
        ]
        for line in run_agent_loop(envelope, steps):
            print(line)
        print(json.dumps(envelope.snapshot().to_dict(), indent=2))


if __name__ == "__main__":
    main()

The stub model function is intentional. The envelope must be testable without a vendor key. Swap guarded_model_call for the project's real client only after the halt behavior is proven.

Commands to run the demo

python envelope.py reset 3
python envelope.py status
python envelope.py consume model
python envelope.py consume tool
python envelope.py demo --budget 3

Expected demo shape: three successful consumes, then a halt line, then a snapshot with remaining at 0. The fourth and fifth planned steps never run. That refusal is the whole product of the weekend.

Inspect the file after the demo. The JSON is the audit trail this sitting can afford.

cat .agent-envelope.json

A typical snapshot looks like this:

{
  "remaining": 0,
  "consumed_model": 2,
  "consumed_tool": 1
}

If remaining is still positive after five planned steps, the gate never wrapped the loop. Fix that before adding retries, reflection, or a second tool.

Test plan

Save this beside the module as test_envelope.py. The tests never open a socket. If they fail, the envelope is wrong. If they pass, the agent loop can be wired next.

from pathlib import Path

import pytest

from envelope import CallEnvelope, EnvelopeEmpty, run_agent_loop


def test_halt_before_extra_model_call(tmp_path: Path) -> None:
    path = tmp_path / "env.json"
    envelope = CallEnvelope(path)
    envelope.reset(2)
    log = run_agent_loop(
        envelope,
        [
            ("model", "one"),
            ("tool", "two"),
            ("model", "three"),
        ],
    )
    assert log[0].startswith("model ok")
    assert log[1].startswith("tool ok")
    assert log[2].startswith("halt")
    snap = envelope.snapshot()
    assert snap.remaining == 0
    assert snap.consumed_model == 1
    assert snap.consumed_tool == 1


def test_empty_reset_refuses_immediately(tmp_path: Path) -> None:
    envelope = CallEnvelope(tmp_path / "env.json")
    envelope.reset(0)
    with pytest.raises(EnvelopeEmpty):
        envelope.try_consume("model")

pytest test_envelope.py -q

Add one more check when the real client lands: a dry-run flag that records intended consumes without calling the network. The envelope already returns state. Logging that state is cheaper than debugging a surprise bill later.

Parking the loop off the laptop

A local envelope still needs somewhere to run the process. Laptops sleep. SSH sessions drop. A long-lived worker that only has to stay awake is enough for a weekend lab.

MonkeyCode is one lane for that kind of sitting. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The project is open source and, per the operator, offers free model access plus a free server option. The envelope does not depend on that lane. The same JSON file works in front of any client the side project already uses.

Keep the integration boring. Export the envelope path as an environment variable. Run the same python envelope.py demo as a process that outlives a closed lid. Point the real model client at whatever endpoint the lab already trusts. Do not teach the envelope to parse vendor invoices. Call counts are the only signal this weekend believes.

Readers who already keep agent loops on a laptop can park that same process on the free server option if they want the envelope to survive sleep. No other product step is required for the demo to be useful.

What this weekend skipped

Several tempting features were cut on purpose. Each skip kept the demo honest.

Token estimators. Character-length heuristics lie. They create false confidence.
Per-kind budgets. Two counters look neat and delay the halt test.
Redis. A side project with one worker does not need a network lock.
Auto-reset at midnight. Silent refills hide leaks.
Prompt-cache awareness. The envelope counts turns, not billed tokens.
A pretty status page. python envelope.py status already prints JSON.

A green pytest run at the end of the sitting beat a larger design that still called the model "just once more." The skipped list is also a backlog filter: nothing on it is required to stop an unbounded loop.

Limitations and who should skip this

The file is not a ledger. Two processes on one file will race even with os.replace. The lock is in-process only. Crash recovery keeps the last complete JSON, which can lose an in-flight decrement or fail to decrement if the process dies before _write. Neither case is acceptable for paid production traffic.

Do not use this envelope when any of the following is true:

Several workers share one budget.
The agent spends real money and needs vendor-accurate usage.
Compliance requires an immutable audit log.
The orchestrator already has a job queue with a dead-letter path and a max-attempts field that is actually enforced.

Teams with those needs want a real quota service, not a weekend JSON file. The sketch is for a single operator, a single process, and a budget measured in turns rather than currency.

What the sitting actually produced

The working demo is a counter, a refusal, and a test. That is enough to stop a chatty agent before Monday. Wire the project's real model client only after pytest is green. Leave billing, dashboards, and multi-worker locks for a weekend that has already earned them.