DEV Community: Harper Xu

Name Failure Domains Before Apply

Harper Xu — Sun, 11 Oct 2026 21:50:30 +0000

You do not start an architecture review inside the diff. You start by naming the failure domain that can hurt you. A clean patch can still cross a boundary you never drew.

Think of the change as water in a set of pipes. The pipes matter more than the color of the water. If a pipe leaks, the patch quality will not save you.

Your first constraint is the scope of files. You name the files the change may touch. You also name the files it must not touch.

A suggestion that wanders past that fence fails review. That remains true even when the code compiles. Scope is a wall, not a hopeful wish.

Your second constraint is the path data takes. Prompts, file snippets, and test logs either stay on your machine or they leave. You write that choice down before you ask any model for help.

Your third constraint is where the patch lands. Apply stays on a branch that you control. Or it lands on a machine you do not administer.

Those two targets are different failure domains entirely. Do not blur them because the suggestion looks small. A small diff can still open the wrong door.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option. This review uses only those two supplied facts.

It does not assume a model name or a quota. It also skips hardware shape and any duration. You read the live plan yourself before you rely on either offer.

Treat the free server as a rented workbench, not as your archive. You can try a patch there when your laptop is the wrong place. You still keep the source of truth on a host you can inspect.

Here is the data flow you should draw before you paste anything. Your intent stays written in your own notes. The context you select then moves to the model.

The suggestion comes back to you as text. That text then sits in a review file. Apply happens only after the domain map says yes.

That flow has four hops, and each hop can fail alone. A failure in hop two does not excuse a failure in hop four. You review them as separate rooms in one building.

Hop one is the intent you already wrote. You write the constraint in a short file, not in a chat scroll. If the constraint is fuzzy, the model will invent a goal.

You cannot review an invented goal after the fact. A fuzzy intent is how drift enters the building. Write the goal in one sentence you can test.

Hop two is the egress of selected context. You choose snippets, not the whole tree, unless the tree is already public. Secrets, tokens, and customer paths do not ride along.

If you cannot redact, you do not send. Egress is a door you choose to open. Once the snippet leaves, you cannot pull the meaning back.

Hop three is the proposal text you received. The model returns a suggestion you can store. You store it as a patch file with a timestamp.

You do not apply it from the chat window. The chat is a transcript, not a release. A transcript can vanish, while a patch file can be diffed.

Hop four is where you apply the patch. You apply on a branch, or you apply inside the free server sandbox. You run the tests that belong to the touched files.

A green test on the wrong host is not evidence. Evidence is a file you can still open tomorrow. If that file is missing tomorrow, the hop already failed.

Failure domains are the rooms where a hop can burn you. Name each one before you admire the diff. You can use five names and keep them stable.

The egress domain fails when private data leaves. The drift domain fails when the patch solves a different problem. The apply domain fails when the patch lands on the wrong ref.

The custody domain fails when you cannot retrieve remote files. The evidence domain fails when no file can prove what ran. Five rooms share one building and no excuse.

The custody domain is about getting files back. It is not about how much room you were given. A free server may hold a workspace for a while.

That hold is not a backup you can trust. It is also not a promise you should invent. Read the current plan, then assume the workspace can vanish.

You can encode this review as a small gate. The gate reads a manifest you write by hand. It refuses apply when the map is incomplete or unsafe.

The script below is a proposal you can run locally. This proposal claims no benchmark and no vendor API. It only checks the map you already wrote.

Use hold when the map is fine but you are not ready. Hold stores the decision without landing any patch. Apply stays closed until you change that target on purpose.

#!/usr/bin/env python3
# Local domain gate. Proposal only. It makes no network calls.

import json
import sys

REQUIRED = (
    "intent",
    "touched",
    "forbidden",
    "egress",
    "apply_target",
    "evidence",
)
TARGETS = {"local-branch", "free-server-sandbox", "hold"}
EVIDENCE = {"patch-file", "patch-file+tests"}

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

def domain_failures(spec):
    failures = []
    missing = [key for key in REQUIRED if not spec.get(key)]
    if missing:
        failures.append("map-incomplete:" + ",".join(missing))
        return failures
    if spec.get("egress") == "external" and spec.get("secrets") is True:
        failures.append("egress-domain:secrets-would-leave")
    overlap = set(spec.get("touched") or []) & set(spec.get("forbidden") or [])
    if overlap:
        failures.append("drift-domain:forbidden-overlap")
    target = spec.get("apply_target")
    if target not in TARGETS:
        failures.append("apply-domain:unknown-target")
    if target == "free-server-sandbox" and not spec.get("source_of_truth"):
        failures.append("custody-domain:no-local-source-of-truth")
    if spec.get("evidence") not in EVIDENCE:
        failures.append("evidence-domain:no-local-artifact")
    if target != "hold" and spec.get("waiver") != "reviewed":
        failures.append("gate:apply-without-waiver")
    return failures

def paths_in_diff(diff_text):
    paths = []
    for line in diff_text.splitlines():
        if line.startswith("+++ b/"):
            paths.append(line[6:])
    return paths

def extra_paths(diff_text, touched):
    allowed = set(touched)
    return [path for path in paths_in_diff(diff_text) if path not in allowed]

def main():
    spec = load(sys.argv[1])
    failures = domain_failures(spec)
    if len(sys.argv) > 2:
        with open(sys.argv[2], encoding="utf-8") as handle:
            extra = extra_paths(handle.read(), spec.get("touched") or [])
        if extra:
            failures.append("drift-domain:patch-outside-touched")
    if failures:
        print("REFUSE")
        for item in failures:
            print(item)
        return 2
    print("ALLOW")
    print("target=" + spec["apply_target"])
    return 0

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

Save that checker as domain_gate.py on your machine. Then write a manifest that matches a real change. Do not let a model fill the forbidden list.

That list is your constraint, not a suggestion. A model that edits the fence is already inside drift. You keep the pen when you write that list.

{
  "intent": "Rename the retry helper without changing its public signature.",
  "touched": ["src/retry.py", "tests/test_retry.py"],
  "forbidden": ["src/secrets.py", ".env", "deploy/"],
  "egress": "external",
  "secrets": false,
  "apply_target": "local-branch",
  "source_of_truth": "git@origin/main",
  "evidence": "patch-file+tests",
  "waiver": "reviewed"
}

Run the domain gate before you apply anything. A refuse result is the review, not a nuisance. Read the exit code before you read the diff.

python3 domain_gate.py review.json suggestion.patch
status=$?
echo "exit=${status}"
test "${status}" -eq 0 || exit "${status}"
git switch -c review/retry-helper
git apply --check suggestion.patch
git apply suggestion.patch
python3 -m pytest tests/test_retry.py -q

If the gate prints an egress failure, stop and redact. If it prints a custody failure, keep the patch file local. Do not treat the free server as the archive.

Walk a concrete miss so the rooms feel real. You asked for a rename of a retry helper. The suggestion also edits the config loader to be helpful.

The touched paths and forbidden paths now overlap. The gate refuses, and that refuse is the architecture talking. You do not negotiate with the patch to stay green.

REFUSE
drift-domain:forbidden-overlap

You shrink the request and then ask again. You keep the same forbidden list in place. Helpful extra edits are drift, even when they look kind.

Walk a second miss on the free server. Tests pass in the sandbox during the afternoon. Next morning the workspace is gone, and so is your only copy.

The evidence domain failed when the patch never came home. The free server did not betray a quota you invented. It simply was never meant to be your archive.

You change the order of hops, not the slogan. Write the patch file locally before any remote run. Copy out logs you care about before you close the session.

A second manifest shows the safer sandbox path. You still name a source of truth you control. The free server is where you try the hop.

{
  "intent": "Try the same rename where the local machine is busy.",
  "touched": ["src/retry.py", "tests/test_retry.py"],
  "forbidden": [".env", "secrets/"],
  "egress": "external",
  "secrets": false,
  "apply_target": "free-server-sandbox",
  "source_of_truth": "/work/repo",
  "evidence": "patch-file+tests",
  "waiver": "reviewed"
}

python3 domain_gate.py sandbox.json suggestion.patch
# copy only touched files, run the tests, bring the patch file back

You should change the gate next, not the model. Turn the waiver into a commit message line, not a loose flag. Add a check that the patch edits only touched paths.

Expire sandbox copies on a clock you choose. A vendor clock is not your own constraint. Bring the patch home before you call the hop done.

Do not change the model as your first move. A sharper model does not shrink an unnamed failure domain. It only writes a more confident patch in the same pipes.

Here is the analogy to keep on the wall. A building inspector does not start by praising the paint. The inspector walks the load path, the exits, and the fire spread.

Your domain map is the inspection walk itself. The diff is only the paint on the wall. Fresh paint on a cracked beam is still a cracked beam.

Limits sit in plain sight for this gate. This gate cannot see secrets you forgot to mark. It cannot prove the free server isolated your work.

It cannot tell you a quota or a region. It cannot tell you how long a workspace lives. Those facts change, so you read them at use time.

This article will not freeze those live facts for you. Do not use this approach for regulated data that must stay local. Do not use it when you need a durable build farm.

Do not use it if a tool should merge to the default branch. The gate is a review aid, not a release system. If the manifest and the patch disagree, believe the manifest.

Throw the patch away and ask for a smaller suggestion. You should not widen touched paths just to make the gate go green. That move hides drift instead of naming it.

A green gate on a lying map is worse than a red gate. Free model access helps when the hop is small and the map is complete. A free server helps when you need a disposable place to run that hop.

Neither offer replaces the walk through failure domains. If you try that walk with MonkeyCode, confirm the live plan first. Then run this gate on a scratch branch before you trust a suggestion.

Review the Free Lane Before You Cross

Harper Xu — Sat, 10 Oct 2026 18:25:19 +0000

A free lane is useful only after you name its failure domains. You do not receive custody because the invoice says zero. You receive a temporary neighbor that can propose and can check.

People can generate a patch in minutes, and that speed is the trap. The patch still has to cross rooms that do not share a fate. You review the crossing before you celebrate the speed.

That neighbor can leak, stall, or invent a confident diff. Your review starts with boundaries, not with excitement about price. Price is a constraint, and constraints belong on the diagram.

The outreach brief supplied two availability claims for this review. One claim is free model access, and the other is a free server option. Neither claim names a token cap, a machine size, or an end date.

The brief presents MonkeyCode as an open source project you can inspect. You place that project in the neighbor seat, not in the custody seat. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

This review uses it only as that remote neighbor, not as a proven benchmark. Do not freeze a quota from a chat, a slide, or an old post. A number you cannot open on the project page is not a plan.

You check the live page on the day you depend on the lane. A stale allowance will bend the design around a promise you cannot keep. You would rather drop the lane than invent a limit.

Hold the constraints

You keep four constraints even when the lane costs nothing. The packet may describe the work, but it may not carry secrets. The free server may check code, but it must not hold production keys.

The proposal may look finished, but it must not merge itself. A fifth rule sits quietly beneath those four hard constraints. The free workspace is ephemeral, so you do not store state there.

If a check needs a cache, you rebuild that cache inside the job. You also cap time, because a free neighbor can stall without warning. A hung check should fail closed, and your queue should move on.

Walk the four rooms

Picture the path as four rooms with one-way doors. Room one is your editor, where the spec and the tests already live. Room two is the packet builder, which strips names, tokens, and host paths.

Room three is the free model, which may only see that stripped packet. It returns a patch proposal and a short note about assumed versions. Room four is the free server, which may run only an allowed check.

Those doors do not reverse, and that direction is the point. Logs may come home, but home state does not chase them. You apply nothing until a local gate accepts the returned diff.

The model room and the server room are different failure domains. A clever diff is not permission to execute that diff abroad. You insert a broker so those rooms cannot talk in raw editor text.

Watch a retry bug tempt you

Take a retry helper that fails only when a key is missing. You will want to paste the environment file, because the trace mentions it. That urge is the transit failure, and it shows up early.

The packet builder should drop the file and keep the error class. The model can still suggest a test that stubs the missing key. The free server can run that test if the command is allowed.

You do not send the real key to make the foreign run look real. A leaked run is a worse design, not a more honest one. Realism stops where custody starts, and custody stays on your machine.

Name the failure domains

Four failure domains sit on that path, and they do not share a fate. The model domain fails by being wrong, stale, or overly sure. You treat its patch as a draft from a fast colleague, not as law.

The transit domain fails when the packet holds more than the task. A send crosses a boundary, even when the destination looks friendly and free. You redact before send, and you log the redaction, not the secret.

The free server domain fails as a shared, short-lived workshop. A noisy neighbor can slow you, and a reset can delete scratch files. You assume the disk vanishes, and you assume the network is hostile.

The local domain fails when you skip the gate because the run looked green. Green on a foreign host is a clue, not a release decision. Your machine still owns format, review, merge, and the final test.

Encode the review

You can encode this review as a small Python gate. The script below is a proposal, and this draft did not execute it. It refuses a packet that crosses a domain line you already named.

Run it against a fixture before you trust it in a hook. A reject on a dirty packet is the success case you want first. An accept should be rare, boring, and easy to explain.

#!/usr/bin/env python3
'''Proposal only. This gate was not run against a live service.'''

import json
import sys
from pathlib import Path

FORBIDDEN_KEYS = {
    'api_key', 'token', 'secret', 'password', 'private_key', 'authorization',
}
FORBIDDEN_PARTS = {'ssh', 'scp', 'curl', 'wget', 'nc', 'kubectl', 'terraform'}
ALLOWED_HEADS = {'pytest', 'python', 'ruff', 'git'}


def load_packet(path):
    data = json.loads(path.read_text(encoding='utf-8'))
    if not isinstance(data, dict):
        raise SystemExit('packet must be an object')
    return data


def looks_like_secret(text):
    markers = ('sk-', 'ghp_', 'AKIA', '-----BEGIN', 'xoxb-')
    return any(marker in text for marker in markers)


def find_secret_paths(value, prefix=''):
    hits = []
    if isinstance(value, dict):
        for key, item in value.items():
            path = f'{prefix}.{key}' if prefix else key
            if str(key).lower() in FORBIDDEN_KEYS:
                hits.append(path)
            hits.extend(find_secret_paths(item, path))
    elif isinstance(value, list):
        for index, item in enumerate(value):
            hits.extend(find_secret_paths(item, f'{prefix}[{index}]'))
    elif isinstance(value, str) and looks_like_secret(value):
        hits.append(prefix or 'value')
    return hits


def review(packet):
    failures = []
    domain = packet.get('domain')
    if domain not in {'proposal', 'check'}:
        failures.append('domain must be proposal or check')
    if packet.get('contains_secrets') is True:
        failures.append('packet admits secrets')
    for hit in find_secret_paths(packet.get('inputs', {})):
        failures.append(f'secret-like field: {hit}')
    command = str(packet.get('command') or '')
    parts = command.split()
    head = parts[0] if parts else ''
    if domain == 'proposal' and command:
        failures.append('proposal domain cannot carry a command')
    if domain == 'check':
        if head not in ALLOWED_HEADS:
            failures.append('command not allowed: ' + (head or 'empty'))
        if any(part in FORBIDDEN_PARTS for part in parts):
            failures.append('command crosses a network or admin line')
        timeout = int(packet.get('timeout_seconds') or 0)
        if timeout <= 0 or timeout > 120:
            failures.append('timeout must sit between 1 and 120 seconds')
    if packet.get('persist_workspace') is True:
        failures.append('remote workspace must not persist')
    if packet.get('apply_on_remote') is True:
        failures.append('remote apply is forbidden')
    return failures


def main():
    if len(sys.argv) != 2:
        raise SystemExit('usage: review_free_lane.py <packet.json>')
    packet = load_packet(Path(sys.argv[1]))
    failures = review(packet)
    if failures:
        print('reject')
        for item in failures:
            print(item)
        return 2
    print('accept')
    print(packet.get('domain'))
    return 0


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

Save the proposal as review_free_lane.py and keep the fixtures beside it. The dirty fixture is the case you want to see fail first. The clean fixture is the narrow case you are willing to send.

{
  "domain": "check",
  "contains_secrets": false,
  "persist_workspace": false,
  "apply_on_remote": false,
  "timeout_seconds": 30,
  "command": "curl https://example.invalid",
  "inputs": {
    "note": "retry failed",
    "api_key": "sk-demo-not-real"
  }
}

{
  "domain": "check",
  "contains_secrets": false,
  "persist_workspace": false,
  "apply_on_remote": false,
  "timeout_seconds": 60,
  "command": "pytest tests/test_retry.py",
  "inputs": {
    "error_class": "MissingKey",
    "note": "stub the key in the test"
  }
}

mkdir -p fixtures
jq -n --arg note 'stub the missing key' \
  '{domain:"check",contains_secrets:false,persist_workspace:false,apply_on_remote:false,timeout_seconds:60,command:"pytest tests/test_retry.py",inputs:{error_class:"MissingKey",note:$note}}' \
  > fixtures/clean.json
python3 review_free_lane.py fixtures/dirty.json
echo dirty_exit:$?
python3 review_free_lane.py fixtures/clean.json
echo clean_exit:$?

A dirty fixture should fail on a secret-shaped field and a network command. A clean fixture should pass with pytest and a short timeout. You keep both fixtures beside the script so the rule stays visible.

Expect the dirty file to print reject and exit two. Expect the clean file to print accept and exit zero. Those outcomes are designed behavior, not a measured run from this draft.

You do not pipe a raw chat log into this gate. A chat log is a swamp of paths, names, and half secrets. The packet is a small contract, and the contract is what you review.

Change the design next

The next design change is a narrow broker between the two remote rooms. The broker may forward a proposal id, but not a raw buffer. That cut stops a bad draft from becoming a server script.

After the first quiet week, you split reads from any write tool. You pin allowed commands in a file the gate reads each run. You store job ids locally, beside the spec, not on the server.

A later run should rebuild the check from the spec and the job id. That leaves durable history on the machine that already holds the repo. You would not add deploy rights just to make the lane feel finished.

You would also record which domain produced each artifact in the log. A proposal diff and a check log should never wear the same label. Mixed labels are how a foreign green bar sneaks into a release note.

Say the limits

This design has sharp edges, and you should say them out loud. The gate scans shapes, but it can miss a secret hidden in prose. A determined paste can still bypass a script that you forget to run.

Shared tenancy means timing noise, so do not benchmark the free server here. This draft records no latency, no token count, and no hardware claim. If a page quotes those figures, cite that page, not this review.

The model can recommend an API that your lockfile no longer contains. You confirm package versions locally before you accept the patch. Free access can also shrink or pause, so keep a local fallback flow.

Who should walk away

Do not use this path for regulated data, customer dumps, or private keys. Do not use it when you cannot explain the packet to a reviewer. Do not use it as a production runner or as a durable disk.

If policy forbids third-party inference, the free model is already out. If you need a guaranteed quota, wait until the live page states one. You can still learn the gate on a toy repo with fake values.

The useful move is boring, and that boredom is why it survives. You name the domains, cut the packet, and keep the merge local. A free neighbor can speed a draft, but it cannot own the system.

Read the current MonkeyCode limits, then try one toy repo only. Stop if the live page no longer matches the brief you were given.

Split the Draft Room From the Runner

Harper Xu — Fri, 09 Oct 2026 14:52:14 +0000

A free model and a free server are two failure domains. You do not join them just because both bills read zero. Cost is not the same thing as control.

You still own the repo, the secrets, and the merge button. The remote side may draft text or execute a job. Neither remote room should write your main branch.

Think of two rented rooms with a short hallway. One room holds a writer who only returns paper. The other room holds a drill that only runs jobs.

You pass a folder through that hallway only. You do not let the drill edit the original blueprint. Paper can be wrong without moving a single brick.

A running drill can still crack a borrowed floor. Treat each room as a place that can fail alone. Do not let a shared price tag erase that split.

Name the constraints

Start with constraints, not with a tool logo. Your context budget is finite, and today's ceiling is unknown. Your free runner may vanish, throttle, or share a noisy neighbor.

Assume no durable disk on that borrowed runner. Assume no private network that you personally control. Assume no promise that tomorrow will match today.

Model text is untrusted input on your desk. Server logs are untrusted input on your desk too. A green line in a log is a claim, not a merge.

Your main branch accepts a commit only after a local read. You perform that read on your own machine. A remote checkmark does not replace your own read.

You also constrain the path itself before any send. Secrets never enter the hallway between those rooms. Generated files never return home with write rights.

A retry starts from a known local tree. It does not resume a half-written remote folder. Partial state is a failed copy, not a useful clue.

Move one change

Picture one small change, not a whole platform. You edit locally, and then you add a worktree. That experiment cannot touch your current branch.

A filter walks that worktree before any copy leaves. It marks each file local-only, shareable, or review-first. The mark is a latch on the hallway door.

Only shareable text may become a prompt bundle. The bundle is a copy, and the worktree stays source. You can delete the bundle without losing the change.

The writer room returns a single patch file. You store that patch beside the worktree, not inside it. You do not drop it onto your main checkout.

You read the patch before you apply any hunk. An empty patch is a failed draft, so you delete it. A patch aimed at an unknown path is a failed draft.

If the patch looks sane, apply it inside the worktree only. Then you sync that worktree into the runner room. The runner executes the tests and prints plain logs.

Logs come home as files you can store. The runner does not push commits back to you. The runner does not open a review on your behalf.

You read those logs beside the local diff. A pass means the job finished the command you asked. It does not mean the design itself is right.

A failure means you now have a local task. It does not mean you discard the diff and start blind. You widen the next bundle only when you mean to.

That loop is the architecture you can defend. A vendor may sit in either rented room. The rooms stay separate even when one offer covers both.

Run a gate

The script below is a proposal you can run locally. It is not a benchmark, and it is not a product. It only stamps a domain on each path before a copy.

#!/usr/bin/env python3
# Proposal: stamp a domain on each file before a remote copy.
import json
import sys
from pathlib import Path

LOCAL_ONLY = {'.env', '.pem', 'id_rsa', 'credentials.json'}
TEXT_EXT = {'.py', '.md', '.txt', '.json', '.toml', '.yml'}

def kind_of(path: Path) -> str:
    if path.name in LOCAL_ONLY or path.name.startswith('.env'):
        return 'local-only'
    if path.suffix in TEXT_EXT:
        return 'shareable-text'
    return 'review-first'

def main(root: str) -> int:
    base = Path(root)
    rows = []
    blocked = 0
    for path in base.rglob('*'):
        if not path.is_file():
            continue
        if '.git' in path.parts:
            continue
        kind = kind_of(path)
        if kind == 'local-only':
            blocked += 1
        rows.append({'path': str(path), 'domain': kind})
    report = {'root': str(base), 'blocked': blocked, 'files': rows}
    json.dump(report, sys.stdout, indent=2)
    print()
    return 1 if blocked else 0

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

Run the gate before any sync leaves the desk. A non-zero exit means a denied name was present. Fix that locally, and do not override the exit code.

git worktree add ../draft-room HEAD
python3 boundary.py ../draft-room
echo boundary_exit=$?

Use a toy tree before you touch a real repo. The hidden env file should force a non-zero exit. A zero exit on that tree means the gate is wrong.

mkdir -p /tmp/gate-demo/src
printf '%s\n' 'print(1)' > /tmp/gate-demo/src/app.py
printf '%s\n' 'SECRET=1' > /tmp/gate-demo/.env
python3 boundary.py /tmp/gate-demo
echo expect_nonzero=$?

If the exit is zero, build the bundle from shareable text. Keep that bundle inside a separate scratch directory. Do not point a tool at the raw worktree by habit.

mkdir -p ../scratch/bundle
find ../draft-room -type f -name '*.py' > ../scratch/bundle/manifest.txt
find ../draft-room -type f -name '*.md' >> ../scratch/bundle/manifest.txt
wc -l ../scratch/bundle/manifest.txt

After a reviewed patch lands in the worktree, sync a copy. The host name below is only a placeholder string. Replace it with the runner you actually control today.

rsync -a --delete --exclude '.git' --exclude '.env' \
  ../draft-room/ runner.example:/tmp/job-184/
ssh runner.example 'cd /tmp/job-184 && python3 -m pytest -q'

Bring logs back as files with a stable name. Do not treat the terminal scrollback as the record. A later reader cannot audit a window you already closed.

ssh runner.example 'cd /tmp/job-184 && python3 -m pytest -q' \
  > ../scratch/pytest.log
wc -l ../scratch/pytest.log
git -C ../draft-room rev-parse HEAD > ../scratch/source-rev.txt

Read the failure rooms

The writer room fails when the patch is empty or truncated. It also fails when the patch names a file you withheld. You drop that patch file and keep the recorded revision.

Main never notices that failed draft at all. That silence is the point of the extra worktree. A bad draft should stay cheap to discard.

The hallway fails when the remote copy is only partial. A retry must not continue a broken upload in place. Delete the remote job directory, then sync from the worktree.

If you resume a partial tree, you test a fiction. That fiction can look exactly like a product bug. Often it is only a torn folder on disk.

The runner room fails when the job is killed mid-command. It also fails when the disk vanishes or the clock expires. Missing logs are a failed run, not a quiet pass.

Write that rule where your future self will see it. A vanished machine feels a lot like silence. Silence is easy to misread as a clean success.

Your own desk can fail in the same afternoon. You might apply the patch in the wrong worktree. You might sync an older folder after a newer edit.

Stamp the git revision into the report before the sync. Compare that stamp when the logs finally return. If the revisions differ, throw those logs away.

These domains should fail alone, not as one blob. A writer outage should not erase a saved runner result. A runner outage should not force a wider prompt.

Widen the prompt only after the filter runs again. A second send is a new copy, not a harmless retry. Keep the bundle list attached to that exact send.

Change the stamp next

The next change is a domain stamp on every artifact. You do not need a smarter prompt before that stamp. You need to see which room produced each byte.

Each patch file should record the source revision and bundle hash. Label that file with the plain word remote-draft. Do not put a guessed model name inside the stamp.

Each log file should record the job id and same revision. Label that file with the plain word remote-run. You can then match paper to drill without a dashboard.

Make the remote job id idempotent on purpose. A second sync of the same revision should replace the folder. It should not nest another copy inside the first one.

Double trees create failures that look like flaky tests. Those failures are usually two copies of one job. Replace the folder, and the false flake disappears.

Store the stamp beside the commit message when you merge. Future you should see which room produced the diff. Future you should also see which room produced the log.

That provenance stays on your desk with the commit. It does not require trust in either rented room. It only requires that you wrote the stamp before you forgot.

Next, teach the filter to scan file contents for secrets. The script above trusts file names and suffixes only. A token pasted into a Python string will sail through.

Until that scan exists, read the bundle yourself. The name check is a latch, not a real lock. A clean exit lets you look, not send by reflex.

Where a free offer fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator describes MonkeyCode as an open-source project. It includes free model access and a free server option.

This draft does not verify a token quota or machine size. It also does not verify a region or a duration. Those terms move, so read the current project page first.

Confirm the repository and the license on that page. A remembered offer is not a standing contract. Design the rooms before you design around a price.

If you try that offer, keep it inside the rooms above. Point the writer at the bundle, not at your home directory. Point the runner at the job path, not at production.

Then keep the stamps next to the result. The offer itself is only a supply choice. The boundary is the part you should keep.

Confirm the live terms, then clone a toy repo. Run the boundary script before either room sees real work. Let the gate feel boring before you trust the hallway.

Skip this when

Skip this flow when the repo holds regulated data. Also skip it when you lack approval to send filtered text. A name filter is not a legal review.

Skip this flow when you need a production runtime. A free shared runner is a lab bench, not a shop floor. Do not hang a customer path on a borrowed bench.

Skip this flow when your team requires signed builds. Locked runners and a real audit trail belong in your pipeline. One local JSON file is not that audit trail.

Skip this flow when you wanted a public scoreboard. There is no accuracy number in this article. There is no speed claim and no tool ranking either.

The artifact is a gate plus a path. It shows where bytes are allowed to travel. It does not show which writer is best.

Limits you should keep

The classifier trusts suffixes and file names alone. Renamed secret files can still sail through the gate. Binary assets land in review-first, and the script never opens them.

You can still sync a forbidden file if you bypass the exit. The gate is voluntary on a solo desk. A voluntary gate fails when you treat it as décor.

The sample commands assume SSH and rsync exist locally. Those commands do not create the remote runner. They do not prove the remote disk started empty.

A dirty job directory is its own failure domain. Prefer a fresh path for every new job id. Delete that path after the logs are safely home.

Nothing here measures how often a draft compiles. If you need that number, count it on your own tree. Do not borrow a figure from a marketing page.

Do not freeze yesterday's quota into a design document. Quotas change, and this article did not measure one. Design for a missing room, not for a permanent gift.

You can change the stamp format without moving the rooms. Keep the writer from running code on your behalf. Keep the runner from opening reviews in your name.

Keep the merge decision on your own desk. That split survives a price change and a model swap. It also survives a week when the free box is gone.

Capacity Is Not Custody

Harper Xu — Thu, 08 Oct 2026 10:25:48 +0000

A free runner can lend you spare cycles. It cannot lend you custody of the merge. You still own the secrets and the rollback.

That split is the architecture you should draw. Treat raw capacity as a rented loading dock. Custody is the vault behind your own lock.

You may draft builds on a shared machine. You should not let that machine bless main.

The dock can be free today and gone tomorrow. The vault stays on your host either way.

Name the constraints first

Start from constraints, not from a model menu. A shared free server is noisy, preemptible, and visible to its operator. Those three facts should bend every arrow you draw.

You do not know the neighbor on that host. You do not know when the slot dies. You do not know who can read the work directory.

Design as if all three facts are hostile. Treat a quiet neighbor as luck, not as a control. A shared disk is still a shared disk.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator describes MonkeyCode as an open source project. Confirm the license in the repository before you depend on it.

Free model access is a supplied availability claim. A free server option is the other supplied claim. Recheck both in the current project documentation.

Do not assume a quota, a chip, or a duration. Docs can change faster than a blog post. Your design should still survive a smaller offer.

Follow the box, not the chat

Picture a parcel dock at a shared warehouse. You hand over a sealed box, not the warehouse keys. The label, the weight limit, and the return address stay yours.

You hash the work tree on your own host. You pack that digest with an allowlist and a timeout. You send the envelope plus a narrow diff context.

The free runner may build or test inside that box. It returns logs, a status, and an optional patch. Your host checks digest, paths, and patch size first.

A human merges only after those checks pass. The runner never receives your remote git credentials. The model output never becomes the merge button.

Keep the box boring

Keep the box boring and easy to audit. A digest, a lease, and a path allowlist are enough. Add a timeout and a single command name.

Source context should be the smallest useful diff. Do not upload your home directory to save time. Do not upload environment files to buy a green check.

If the test needs a fixture, generate it inside the box. If the test needs a secret, keep it off this runner. Move that secret test to a private gate you control.

The return path is three files, not a chat log. You want a status file, a log file, and a patch file. Bind them with the lease id before you read prose.

Three failure domains

Separate those failures before you share one dashboard. A dead slot, a wrong tree, and a leaked file differ. They need different owners and different response alarms.

Capacity fails when the shared slot vanishes mid-run. You retry that same envelope, or you stop. You do not widen context to rescue a dead slot.

Identity fails when green belongs to another tree. The result must echo your digest and your lease. Your host drops anything that does not match.

Custody fails when the box held something private. You cannot audit a stranger's disk after the fact. Prevention is the only reliable control on this path.

An unexecuted local gate

The following script is an unexecuted reference design. It does not call a network or apply a patch. It only scores whether a bundle is safe to review.

These commands write local files and nothing else. They do not submit a job to any server. You add a transport only after this gate exists.

# Unexecuted. Disposable clone only.
LEASE=$(uuidgen 2>/dev/null || echo local-review-001)
EXP=$(( $(date +%s) + 600 ))
git rev-parse HEAD > /tmp/tree.txt
git diff --binary HEAD -- . \
  ':(exclude).env' \
  ':(exclude).env.*' \
  ':(exclude)**/*secret*' \
  ':(exclude)**/*.pem' > /tmp/draft.patch
SHA=$(sha256sum /tmp/draft.patch | awk '{print $1}')
python3 - <<PY
import json
from pathlib import Path
local = {
    "lease_id": "$LEASE",
    "expires_at": $EXP,
    "tree": Path("/tmp/tree.txt").read_text().strip(),
    "patch_sha256": "$SHA",
}
Path("/tmp/local-lease.json").write_text(json.dumps(local, indent=2) + "\n")
print("local lease written; do not upload this file")
PY

Write the lease file on your host only. Do not upload that file with the job box. Your gate compares the echo to the local file.

On macOS, use shasum -a 256 instead of sha256sum. The date command here assumes a Unix host.

If uuidgen is missing, the sample uses a fixed lease id. Do not run two drafts with that same fixed id. A collision here would mix two unrelated results.

#!/usr/bin/env python3
"""Unexecuted gate. Proposal only. Not a measured benchmark."""
import hashlib
import json
import sys
import time
from pathlib import Path

MAX_PATCH_BYTES = 200_000
ALLOWED_PREFIXES = ("src/", "tests/", "docs/")

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

def gate(local: dict, result: dict, patch: Path, now: int) -> int:
    if now > int(local["expires_at"]):
        print("reject: expired")
        return 2
    if result.get("lease_id") != local.get("lease_id"):
        print("reject: lease")
        return 3
    if digest(patch) != local.get("patch_sha256"):
        print("reject: digest")
        return 4
    if result.get("patch_sha256") != local.get("patch_sha256"):
        print("reject: result digest")
        return 5
    raw = patch.read_bytes()
    if len(raw) > MAX_PATCH_BYTES:
        print("reject: size")
        return 6
    text = raw.decode("utf-8", errors="replace")
    for line in text.splitlines():
        if not line.startswith("+++ b/"):
            continue
        rel = line[6:]
        if not rel.startswith(ALLOWED_PREFIXES):
            print(f"reject: path {rel}")
            return 7
    print("review: ok")
    return 0

if __name__ == "__main__":
    local = json.loads(Path(sys.argv[1]).read_text())
    result = json.loads(Path(sys.argv[2]).read_text())
    raise SystemExit(gate(local, result, Path(sys.argv[3]), int(time.time())))

Save the checker as gate.py beside a disposable clone. Pass the local lease, the result file, and the patch. A zero exit means you may open the diff.

Any other exit means you stop and discard the bundle. The path check looks at added file headers only. A hostile patch can still hide a bad path.

That is why a human still reads the diff. No timing and no pass rate belong in this draft. Run the sample yourself before you trust the codes.

Replace every placeholder before you run a copy. Do not point this sample at a production remote. Do not store real tokens in the envelope fields.

Do not treat a printed review ok as a merge approval. A green word in a terminal is not a signature. You still read the diff on a machine you trust.

What you would change next

The gate above is a local filter, not a full plane. Next, split logs from artifacts on the return path. Logs can live in a noisy, expiring bucket.

Artifacts need a content hash and a tight path. Add a local kill switch before any review step. A deny file can block a runner id or a time window.

You flip that file without redeploying a generator. You would also pin the runner image digest you accept. If the offer cannot show an image digest, say unknown.

Record unknown as unknown in the review note. You cannot set the runner firewall if you do not administer it. So your client refuses jobs that need outbound network.

If a task needs outbound, run it on a machine you administer. Silence in the envelope should mean no extra route. Do not infer a private network from a free slot.

Who should walk away

Skip this pattern when the tree holds customer data. Skip it when a secret is required to run the test. Skip it when you need an audit-grade runner log.

A free shared slot is a poor audit log. You do not control retention on that machine. You do not control who else can see the disk.

Solo work on a public toy repo can fit. A production tree with keys nearby does not fit. If you cannot read the returned patch, do not merge it.

People who want a permanent quota should wait for a written offer. People who want a private chip should not infer one. This draft is a boundary design, not a capacity promise.

Hold the line

Capacity can be borrowed for a draft run. Custody of the merge cannot be borrowed at all. Keep the free runner on the dock side of that line.

If you try the supplied free access, read the current docs first. Then keep this gate on your own host.

Draw Three Lines Before Free Capacity

Harper Xu — Thu, 08 Oct 2026 08:03:40 +0000

A free server does not earn trust in your repo. A free model does not earn your secrets either. You still review the path before either one runs.

Free capacity changes your bill, not your trust boundary. You can spend less and still leak the same files. That is the review you owe the job before you call anything remote.

Picture a borrowed workshop two blocks from your house. You may use the bench while the lights stay on. You do not nail your house keys to that bench.

MonkeyCode offers free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Treat both offers as capacity, not as a trust upgrade.

Write the constraints first

Write the constraints before you write the prompt. Your repo stays on a machine you control. The free server may run builds, not hold your secrets.

The free model may draft text, not apply a patch. Context you send must be the smallest pack that still works. You do not know the quota, the reset, or the preemption window.

You also do not know how long the free server option lasts. So your design must survive a sudden stop. A vanished bench should leave your house intact.

Name the three lines in a file you can diff. The first line is custody of the repo. The second line is custody of the prompt pack.

The third line is custody of the result you accept. If a line is fuzzy, you do not cross it yet. Fuzzy custody turns a convenience plane into a trust plane.

Follow one job across the lines

Follow one coding job from intent to a local result. You write the task in a file on your machine. You pack only the files the task names.

That pack crosses the network to the free model. The model returns a proposal, not a merged commit. You read the proposal on the host before anything applies.

A later build may run on the free server. The build log comes back as evidence, not as authority. You decide on the host whether the evidence is enough.

Think of the flow as a relay with three batons. The first baton is intent, and it never leaves home. The second baton is the pack, and it is the only remote copy.

The third baton is a proposal you can throw away. A build on the free server is a fourth lap, not a new owner. Ownership stays with the machine that holds the git directory.

Notice what never belongs on the free server. Your credentials, your full history, and your private notes stay home. The server sees a build input you already decided to share.

Notice what never belongs in the model call. A dump of the whole tree is not a context pack. A pack is a named list with a reason for each path.

Do not merge the failure domains

A timeout in the model is not a failure of your repo. A preempted free server is not a failure of your tests. A bad proposal is not a failure of your git history.

Those are three domains, and you should not merge them. If you merge them, one stall looks like a broken tree. You then retry the whole job and send context again.

That retry spends more free capacity and widens egress. Separate domains let you retry the cheap part only. You resend a pack, or you rerun a build, not both by habit.

Give each domain a local status the other cannot overwrite. Model status lives next to the proposal hash. Server status lives next to the build log hash.

Repo status lives in git, and only you move it. A remote log must not flip that status by itself. That rule is the whole point of the review.

Run a gate before the call

The next change is a gate that runs before any free call. The gate reads a small job file you keep beside the repo. It refuses the call when a line is crossed.

This script is an example you can copy and run locally. It is not a benchmark, and it is not a product feature. It only checks the manifest you wrote by hand.

#!/usr/bin/env python3
# Local architecture gate for a free-capacity coding job.
# Example only. It does not call a model or a server.
import json
import sys
from pathlib import Path

SECRET_PARTS = (".env", "id_rsa", "credentials", ".pem", "secret")
REMOTE_APPLY = {"remote", "server", "model"}

def load(path):
    return json.loads(Path(path).read_text())

def problems(job):
    found = []
    if job.get("repo_custody") != "host":
        found.append("repo custody must stay on the host")
    if job.get("apply_site") in REMOTE_APPLY:
        found.append("apply must not run on the free path")
    if job.get("prompt_custody") != "host":
        found.append("prompt pack must be built on the host")
    for rel in job.get("context_paths", []):
        low = rel.lower()
        if any(part in low for part in SECRET_PARTS):
            found.append("secret-like path in pack: " + rel)
        if rel.startswith("/") or rel.startswith(".."):
            found.append("path escapes the repo: " + rel)
    if not job.get("context_paths"):
        found.append("empty pack is not a reviewed pack")
    if job.get("result_custody") != "host":
        found.append("result custody must return to the host")
    return found

def main():
    if len(sys.argv) != 2:
        print("usage: python3 review_free_path.py job.json")
        return 2
    job = load(sys.argv[1])
    found = problems(job)
    if found:
        print("BLOCK")
        for item in found:
            print("- " + item)
        return 1
    print("PASS")
    print("task=" + job.get("task_id", "unset"))
    print("paths=" + str(len(job.get("context_paths", []))))
    return 0

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

Pair the script with a manifest you can review in git. The sample below is intentionally boring and small. Boring is what you want before a remote call.

{
  "task_id": "job-184",
  "repo_custody": "host",
  "prompt_custody": "host",
  "apply_site": "host",
  "result_custody": "host",
  "context_paths": ["src/retry.py", "tests/test_retry.py"]
}

Run the gate, then read the verdict before you spend capacity. A pass does not mean the model is right. A pass means your lines are still drawn.

python3 review_free_path.py job.json
python3 review_free_path.py job-bad.json

A clean manifest should print PASS and the task id. A bad manifest should print BLOCK and the crossed line. Keep both files so the drill stays repeatable.

Break the sample on purpose so you trust the gate. Point apply_site at server and expect a block. Add a secret-like path and expect a second block.

That drill is the architecture review, not a quality demo. You are testing your lines, not the model. The free server stays idle until the gate prints PASS.

What you would change next

After the gate is boring, split status by domain. Write model state, server state, and repo state in three fields. Do not let one field stand in for the others.

Next, cap the pack by an explicit file list. If the task needs a fourth file, you edit the list. You do not let a tool widen the list in silence.

Next, store the proposal hash beside the task id. You can drop the proposal without dropping the task. The task remains yours even if the free call dies.

Next, treat a free-server build as optional evidence. If the server vanishes, your local tests still run. The missing log is a server-domain failure, not a repo failure.

Do not add a scheduler that retries every domain together. A combined retry hides which line actually broke. You want a small retry that names its domain.

Who should leave this path alone

Skip this path if the repo holds regulated data. Skip it if you cannot read every file you might send. Skip it if a failed build must page someone at night.

A free server is a poor home for that pager duty. Skip it when you need a verified quota, duration, or hardware spec. Write those facts down only after you check them yourself.

This review does not prove the free offer will remain. It does not measure speed, quality, or uptime. It only checks whether your path respects the lines.

You can try the free model path on a throwaway repo. Run the gate before you touch the free server option.

Leave Apply on the Host

Harper Xu — Thu, 24 Sep 2026 21:09:16 +0000

You should leave apply on your own host. A guest generator may propose the patch only. It should never own your local git worktree.

That split is the architecture you should review first. Generation can live on a free remote server. Landing the change stays on a machine you control.

A guest resembles a contractor waiting in the lobby. They may slide one drawing under the glass. They may not badge in and edit the live rack.

Seat the process before the files

The risky question is which process can update HEAD. A clever diff is still just text until something applies it. If the guest can commit, a bad run becomes history.

Picture three rooms joined by one narrow door. The host room holds the clone, the hooks, and the tests. The lobby holds one proposal file and nothing else.

The guest room holds the generator and its scratch disk. You do not back up that scratch disk. You do not treat it as a second source of truth.

You copy a narrow task into that lobby. The guest reads the bundle and writes one diff. Your host then decides if that diff may land.

A free server is useful only in the guest room. MonkeyCode's free model access and free server option can fill that seat. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

This draft does not state model names or quotas. It also skips hardware claims and duration claims. Those terms change, and this draft does not verify them.

The operator describes the project as open source. This article does not invent a license line or a repository URL. You should read the current project page before you rely on access.

A free option is a seat, not a promise of uptime. If the guest disappears, your host should still build. Design the door so an empty lobby is a boring Tuesday.

What you let through the door

You should send the task, the allowed paths, and short slices. You should not send your home directory or token cache. A full chat log is also the wrong parcel for this door.

The guest needs enough context to draft a diff. It does not need the keys to your other repos. Wider context makes a wider leak, even when generation is free.

Keep the export on the host, in a script you can read. The sample below is a proposal you can run locally. It does not call a remote API, and it is not a benchmark.

#!/usr/bin/env bash
# propose-export.sh - host-side proposal, not a recorded run
set -euo pipefail
TASK="${1:?task file}"
ALLOW="${2:?allowlist file}"
OUT="${3:-./.review/lobby/bundle.txt}"
mkdir -p "$(dirname "$OUT")"
{
  printf 'TASK\n'
  sed -n '1,80p' "$TASK"
  printf '\nALLOW\n'
  sed -n '1,200p' "$ALLOW"
  printf '\nSLICES\n'
  while IFS= read -r path; do
    [ -f "$path" ] || continue
    printf '\n--- %s\n' "$path"
    sed -n '1,160p' "$path"
  done < "$ALLOW"
} > "$OUT"
wc -c "$OUT"

Read that byte count before you upload the bundle. If the file looks too wide, shrink the allowlist. Then export again and read the count a second time.

A free server does not make a wide bundle safer. It only makes generation against that bundle cheaper to start. Cheap generation is not the same as a contained bundle.

Name the files in the allowlist for this task only. Do not reuse last week's list out of habit. Three named files still describe a guest seat.

Opening the whole tree turns the guest into a tenant. That tenant can see more than the task required. You should feel that widening as a design change, not as a convenience.

How the host fails closed

The guest drops the proposal diff in the lobby. Your apply gate runs on the host, as you, on a detached worktree. If the patch is dirty, the main worktree never moves.

Think of the detached worktree as a scratch bench in the shop. You can clamp the drawing there and try the cut. You do not move the finished cabinet until the cut is clean.

#!/usr/bin/env bash
# apply-gate.sh - host-side proposal, unexecuted as a suite
set -euo pipefail
DIFF="${1:?proposal.diff}"
ALLOW="${2:?allowlist file}"
ROOT="$(git rev-parse --show-toplevel)"
WT="$(mktemp -d)"
cleanup() {
  git -C "$ROOT" worktree remove --force "$WT" 2>/dev/null || rm -rf "$WT"
}
trap cleanup EXIT
git -C "$ROOT" worktree add --detach "$WT" HEAD
python3 "$ROOT/scripts/path_gate.py" --diff "$DIFF" --allow "$ALLOW"
git -C "$WT" apply --check "$DIFF"
git -C "$WT" apply "$DIFF"
git -C "$WT" diff --stat HEAD
test -x "$ROOT/scripts/run_suite.sh"
"$ROOT/scripts/run_suite.sh" "$WT"

The suite check fails closed when the runner script is missing. That is deliberate, so a quiet skip cannot look like a pass. Point the gate at your real suite before you use it on a branch.

The path gate is the lock on the shop door. It rejects a diff that touches a file outside the allowlist. It rejects a gate edit when the gate is missing from the allowlist.

#!/usr/bin/env python3
# path_gate.py - proposal checker, not a measured control.
import argparse
import pathlib
import sys

def touched(diff_text):
    paths = set()
    for line in diff_text.splitlines():
        if line.startswith('+++ b/') or line.startswith('--- a/'):
            raw = line.split(chr(9), 1)[0][6:]
            if raw != '/dev/null':
                paths.add(raw)
    return paths

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('--diff', required=True)
    parser.add_argument('--allow', required=True)
    args = parser.parse_args()
    allow_path = pathlib.Path(args.allow)
    allow = {ln.strip() for ln in allow_path.read_text().splitlines() if ln.strip()}
    diff_text = pathlib.Path(args.diff).read_text()
    bad = sorted(touched(diff_text) - allow)
    if bad:
        print('rejected paths:', ', '.join(bad))
        return 2
    print('path gate passed')
    return 0

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

This checker reads path headers, not a full diff parser. Renames and quoted paths can slip past a shallow read. Replace it before you trust the seat on a real repo.

Walk a bad patch through that checker before you trust the seat. Use a diff that edits a workflow while the allowlist names one file. You want exit code two, and you want your branch still clean.

You can stage that drill with two local files. No remote account is required for the drill. The point is the locked door, not the generator brand.

printf 'src/app.py\n' > /tmp/allow.txt
cat > /tmp/bad.diff << 'EOF'
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1 +1 @@
-name: ci
+name: opened
EOF
python3 scripts/path_gate.py --diff /tmp/bad.diff --allow /tmp/allow.txt
echo exit:$?
git status --short

Run the drill on a throwaway clone, not on your main checkout. The checker only reads the diff and the allowlist. It should not need network, credentials, or a running guest.

Record the exit code next to the task name in your notes. A passing drill today does not certify next month's server image. You re-run the drill when the gate script changes.

Network loss is a separate break from a bad diff. If the guest server dies mid-draft, the lobby stays empty or half written. The trap removes the temporary worktree, and your HEAD stays put.

A half-written diff should fail the apply check. That failure is a closed door, not an incident. You delete the lobby file and you ask for a fresh proposal.

What you would change next

This seat is a review sketch, not a finished platform. The next change is to split the test user from the apply user. The runner should read the worktree and write logs only.

A later host step may commit after those logs look right. That step should be a different script, with a different user. One process should not both grade the work and file the grade.

You should also stop treating one green local suite as enough. A second witness should apply the same diff on a clean checkout. Your existing CI job can be that witness without the guest disk.

If the two results disagree, you leave the patch in the lobby. You do not merge to soothe a deadline. Disagreement is a signal that the seat is still too wide.

Shrink the allowlist every time the task changes. A guest that may edit three named files is still a guest. A guest that may edit the repo has become a tenant.

Tenants need an owner, a retention story, and a revoke path. A free server option is a weak place to invent those controls later. Put the revoke on the host door, where you already hold the keys.

Do not use this seating if the tree holds production secrets. Do not use it when policy forbids sending source off the machine. Do not use it if you need a signed retention story.

Skip the seat when that story is not yet published. In those cases, keep the generator local or skip generation. A free remote seat cannot outrank a written rule.

In that case the lobby door should stay shut. Local tools can still draft inside the host room. You lose the free guest, and you keep the cabinet.

If your host gate already rejects bad paths, a free guest can draft. Read the current access terms on the project site before you depend on them. Then keep apply on the host, beside the hooks you already trust.

Replay the Job, Not the Chat

Harper Xu — Wed, 23 Sep 2026 17:09:41 +0000

Chat history is the wrong control plane for generation. You need a job you can replay later.

A chat is a river that only flows forward. A job is a crate you can restack after a crash.

Most coding agents still behave like chat rooms. They retry by appending more words to a transcript. That design fails under cancel, timeout, and double submit.

You already know this pattern from payment APIs. Clients send an idempotency key with every charge. The server refuses a second write for the same key.

Treat a model call as a write with a key. Do not treat it as a conversation you continue.

Constraints before tools

Three hard constraints sit under this job architecture. The job document is immutable once you enqueue it. The generator may crash, but it may not edit the job.

The receipt is the only success signal you trust. Logs are evidence. They are not permission to apply.

The apply host has one writer for a given path. Two receipts cannot win the same file without a merge. If both land, you have a split brain.

Think of the generator as a day laborer. You hand over a work order, not house keys and a diary. The laborer returns a crate with a packing slip.

You inspect the slip first. You do not unpack into production on vibes.

Data flow you can point at

Here is the data flow you actually want. Your planner never calls the model in-process.

It writes a job file to a local queue directory. That file names the allowed paths and the instruction. It also names an idempotency key you minted.

A worker picks the job and ships a minimal bundle. The remote generator sees those files, not your chat memory. It also never sees your apply credentials.

The worker waits for an artifact and a receipt. Your verifier checks the receipt before any apply step. Failed checks leave the tree untouched.

If the worker dies, you replay the same job file. You do not invent a follow-up prompt. Replay is the recovery path, not clever chat.

A disposable remote fits this worker role. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode provides free model access and a free server option you can aim the worker at for scratch generation. Keep secrets off that host. Keep the queue and the apply step on machines you control.

A job you can hash twice

Label this example as a proposed local contract. It is not a production service. Run it against a toy repo first.

# genjob.py
from __future__ import annotations

import hashlib, json, time, uuid
from dataclasses import dataclass, asdict
from pathlib import Path
from typing import Mapping

SCHEMA = "genjob.v1"


def sha256_bytes(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()


def sha256_file(path: Path) -> str:
    return sha256_bytes(path.read_bytes())


def canonical(obj: object) -> bytes:
    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()


@dataclass(frozen=True)
class GenerationJob:
    schema: str
    job_id: str
    idempotency_key: str
    created_at: int
    instruction: str
    allowed_paths: tuple[str, ...]
    inputs: Mapping[str, str]  # path -> sha256
    attempt: int

    def digest(self) -> str:
        body = asdict(self)
        body["allowed_paths"] = list(self.allowed_paths)
        body["inputs"] = dict(sorted(self.inputs.items()))
        return sha256_bytes(canonical(body))

    def write(self, queue_dir: Path) -> Path:
        payload = asdict(self)
        payload["allowed_paths"] = list(self.allowed_paths)
        payload["inputs"] = dict(self.inputs)
        payload["digest"] = self.digest()
        path = queue_dir / f"{self.idempotency_key}.json"
        if path.exists():
            old = json.loads(path.read_text())
            if old.get("digest") != payload["digest"]:
                raise ValueError("idempotency key reused with a different job")
            return path
        path.write_text(json.dumps(payload, indent=2))
        return path


def mint_job(repo: Path, instruction: str, allowed: list[str]) -> GenerationJob:
    inputs = {}
    for rel in allowed:
        p = repo / rel
        if not p.is_file():
            raise FileNotFoundError(rel)
        inputs[rel] = sha256_file(p)
    key = sha256_bytes(canonical({
        "instruction": instruction,
        "inputs": inputs,
    }))[:32]
    return GenerationJob(
        schema=SCHEMA,
        job_id=str(uuid.uuid4()),
        idempotency_key=key,
        created_at=int(time.time()),
        instruction=instruction,
        allowed_paths=tuple(allowed),
        inputs=inputs,
        attempt=1,
    )

The idempotency key is not a random souvenir. It is a hash of instruction plus input digests. Same work order, same key.

If you change one file, the key changes. That is the point. You are not continuing a chat. You are submitting a new write.

Receipts beat transcripts

A receipt is a small JSON object. It names the job digest it claims to satisfy. It also names the output hashes.

# receipt.py
from __future__ import annotations

import json
from dataclasses import dataclass
from pathlib import Path
from genjob import GenerationJob, sha256_file, SCHEMA

ALLOWED_STATUS = {"ok", "rejected", "aborted"}


@dataclass(frozen=True)
class Receipt:
    schema: str
    job_digest: str
    idempotency_key: str
    status: str
    outputs: dict[str, str]  # path -> sha256
    worker_id: str

    @classmethod
    def load(cls, path: Path) -> "Receipt":
        raw = json.loads(path.read_text())
        rec = cls(**raw)
        if rec.schema != SCHEMA:
            raise ValueError("receipt schema mismatch")
        if rec.status not in ALLOWED_STATUS:
            raise ValueError("unknown receipt status")
        return rec


def verify_receipt(job: GenerationJob, rec: Receipt, out_dir: Path) -> None:
    if rec.idempotency_key != job.idempotency_key:
        raise ValueError("receipt key does not match job")
    if rec.job_digest != job.digest():
        raise ValueError("receipt digest does not match job")
    if rec.status != "ok":
        raise ValueError(f"job not applyable: {rec.status}")
    extra = set(rec.outputs) - set(job.allowed_paths)
    if extra:
        raise ValueError(f"receipt wrote outside contract: {sorted(extra)}")
    for rel, digest in rec.outputs.items():
        got = sha256_file(out_dir / rel)
        if got != digest:
            raise ValueError(f"artifact drift at {rel}")

Notice what the verifier does not read. It does not read the model name. It does not read the chat. It does not read the worker's opinions.

If the artifact drifted, you reject. If the path set grew, you reject. If the digest drifted, you reject.

Rejection is a first-class result. It is not an awkward silence in a thread.

Commands for a tiny control plane

Keep the queue on disk so you can see it. Hidden broker magic helps until it lies.

# proposed local flow, not a hosted product
mkdir -p .gen/queue .gen/running .gen/receipts .gen/out

python - <<'PY'
from pathlib import Path
from genjob import mint_job
job = mint_job(
    Path("."),
    "Add a timeout to fetch_user and keep the public signature.",
    ["src/user.py", "tests/test_user.py"],
)
print(job.write(Path(".gen/queue")))
print(job.idempotency_key, job.digest())
PY

# worker claims exactly one job
jobfile=$(ls .gen/queue | head -n 1)
mv ".gen/queue/$jobfile" ".gen/running/$jobfile"

# ship only allowed files; never the whole repo
python ship_bundle.py ".gen/running/$jobfile" /tmp/bundle.tgz

# remote generate happens here; local apply happens later
# scp /tmp/bundle.tgz free-server:
# ssh free-server 'python generate.py && python emit_receipt.py'

python - <<'PY'
from pathlib import Path
from genjob import GenerationJob
from receipt import Receipt, verify_receipt
import json
raw = json.loads(Path(".gen/running").glob("*.json").__iter__().__next__().read_text())
raw.pop("digest")
job = GenerationJob(**raw)
rec = Receipt.load(next(Path(".gen/receipts").glob("*.json")))
verify_receipt(job, rec, Path(".gen/out"))
print("receipt ok; apply may run")
PY

The mv is the lock. One job file cannot live in two directories. If the worker dies after the move, you still have the job.

You can push it back to the queue. You can raise attempt in a new file with a new job_id. You keep the same idempotency key only when the document is identical.

That last rule saves you from ghost patches. Duplicate submits collapse. Changed submits become new jobs.

Failure domains, named on purpose

Name the planes or they will merge in a panic. The planner plane writes jobs and never applies. The worker plane talks to a generator and never holds production secrets.

The generator plane is rented, cheap, and forgetful. The receipt plane is a small store you can audit. The apply plane is the only plane that may write your tree.

Chat mixed those planes in one process. That is why a cancelled stream still felt like a half commit. Partial tokens are not a receipt.

If the free server vanishes, the job remains. You replay against another generator later. The contract did not live in that process.

If the apply host crashes after verify, you still have outputs. You run apply again with the same receipt. Apply must be idempotent too, or you built a new river.

A useful apply trick is content addressing. Write to .gen/out/<digest>/<path>. Then rename into the repo only after verify. Rename is closer to atomic than a streaming patch.

What this architecture refuses

It refuses session memory as a substitute for inputs. If the model needed a file, the job must list that file. Hidden context is an untracked dependency.

It refuses streaming apply. Tokens may stop at line twelve. A receipt either exists or it does not.

It refuses unbounded path sets. "Edit whatever you want" is not a work order. It is a blank check.

It also refuses to pretend free remote capacity is a production control plane. Scratch generate. Local verify. Local apply.

Who should not use this

Do not use this if you need a pair-programmer in a live buffer. The job shape is slower than chat for tiny edits. The extra files will annoy you.

Do not use this if your instruction embeds secrets. Replay stores the instruction. A queue directory is a leak waiting for a sync tool.

Do not use this on a shared branch with several apply hosts. One writer per path is a real constraint. Without a merge plane, two receipts will fight.

Do not use this as a substitute for tests. A receipt proves the worker returned the bytes it claimed. It does not prove the patch is correct.

Skip it for throwaway spikes in a personal sandbox. A crate factory for a ten-line script is ceremony. Save the ceremony for patches you might have to defend.

What I would change next

The next cut is a signed receipt, not a prettier prompt. The worker should sign the job digest and the output hashes. The apply host should verify that signature with a pinned key.

The cut after that is a real apply queue. Generate and apply still share too much airtime in this sketch. Apply should pull receipts, never push them into the tree from the worker.

I would also drop attempt into a child object. Retries are operational, not semantic. Mixing them into the job digest creates noise you will later regret.

None of that requires a smarter model. It requires a control plane that survives a killed SSH session.

You do not need a longer transcript. You need a job you can pick up tomorrow, hash again, and apply without guessing what the chat meant. If you try a disposable generator for the worker plane, keep the queue local, and let the receipt be the only handshake that may open the repo.

Keep Memory Off the Remote Generator

Harper Xu — Tue, 22 Sep 2026 15:22:25 +0000

Keep all durable memory off the remote generator. You own the cache, the identity, and apply rights. The remote model is a compiler, not a colleague.

A free remote server will not keep your session. It can retry, stall, or drop mid-stream. Design for that failure before you prompt.

Think about a CI worker you do not own. You ship a job ticket and then wait. You never leave the deploy key there.

Constraints

This remote generation path gives you three hard constraints. You still do not control end-to-end latency. You also do not control the server-side retries.

You do not control the remote process lifetime. The output remains untrusted text even after success. It is not a merged commit by itself.

Secrets must never ride inside the prompt body. Apply rights must never live beside the model. Mix those two and you built a trap.

Availability on a free path is not an SLA. You should treat silence as a normal outcome. Your local plane remains the system of record.

Network partitions are not rare events here. The compiler host can vanish between poll calls. Your ticket must still mean one apply.

Give every compile job a local time budget. The budget is a constraint, not a guess. When it expires, the key stays unapplied.

Data flow

Start from a frozen worktree, not chat history. Hash the tree, the intent file, and a nonce. That tuple becomes your only idempotency key.

HEAD is not enough for a dirty tree. Uncommitted edits still sit outside that commit hash. Freeze the worktree or refuse to generate.

A fresh nonce stops accidental key reuse tomorrow. A wall clock would make identical jobs diverge. Keep time out of the identity tuple.

You send only the envelope the compiler needs. The remote side returns bytes or a failure. You write those bytes under the key.

Data still moves one way during the generate step. The envelope leaves your host as a job. The artifact returns as bytes under the key.

Apply must read the local artifact file only. It should never read the live HTTP stream. A dead stream can still leave a file.

If the server retries, the key already exists. The second payload collapses into the first file. That is how you survive duplicate 200s.

Treat this like a package registry, not chat. Chat is a poor store for patches. A content-addressed file is a real store.

Here is a proposed orchestrator for that flow. Label it as example code, not production. You should adapt paths before you run it.

# proposed_orchestrator.py — example only, not production telemetry
import hashlib, json, os, time, urllib.request
from pathlib import Path

CACHE = Path(".gen-cache")
APPLIED = CACHE / "applied.json"

def idempotency_key(tree_hash: str, intent: str, nonce: str) -> str:
    raw = f"{tree_hash}\n{intent}\n{nonce}".encode()
    return hashlib.sha256(raw).hexdigest()[:16]

def store_artifact(key: str, body: bytes) -> Path:
    CACHE.mkdir(exist_ok=True)
    path = CACHE / f"{key}.diff"
    if not path.exists():
        path.write_bytes(body)
    return path

def already_applied(key: str) -> bool:
    if not APPLIED.exists():
        return False
    return key in json.loads(APPLIED.read_text())

def mark_applied(key: str) -> None:
    data = json.loads(APPLIED.read_text()) if APPLIED.exists() else {}
    data[key] = int(time.time())
    APPLIED.write_text(json.dumps(data, indent=2))

def post_job(url: str, envelope: dict, timeout: int = 30) -> bytes:
    req = urllib.request.Request(
        url,
        data=json.dumps(envelope).encode(),
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=timeout) as resp:
        return resp.read()

You pin the tree before the request leaves. A dirty worktree makes the key a lie. Freeze the index first, then compile remotely.

# freeze the review surface before you generate
git update-index -q --refresh
git diff --quiet && git diff --cached --quiet || {
  echo "worktree dirty; refuse generate" >&2
  exit 1
}
TREE=$(git rev-parse HEAD)
INTENT=$(sha256sum intent.md | awk '{print $1}')
NONCE=$(openssl rand -hex 8)
echo "$TREE $INTENT $NONCE"

Poll with the same key until bytes land. Do not start apply from the live stream. The cache file is the only apply input.

# proposed poll loop — example only
def wait_for_artifact(url, key, envelope, cancel_path, budget=120):
    deadline = time.time() + budget
    while time.time() < deadline:
        if Path(cancel_path).exists():
            raise RuntimeError("local cancel flag set")
        cached = CACHE / f"{key}.diff"
        if cached.exists():
            return cached
        try:
            body = post_job(url, envelope, timeout=20)
            return store_artifact(key, body)
        except TimeoutError:
            time.sleep(2)
            continue
    raise TimeoutError("generation budget exhausted")

Cancellation should live on your local disk. A flag file is a boring honest signal. The remote job may keep running anyway.

You still refuse apply after that flag. Spend on the wire may continue briefly. Your repo does not have to follow it.

Put the flag next to the cache, not in chat. Chat delete does not cancel a running job. The apply gate should watch the flag path.

Failure domains

Draw three boxes and keep them hostile. The compiler box can lie, stall, or duplicate. The cache box can fill or go stale.

The apply box can still break the tree. Do not share credentials across those three boxes. The compiler token must not write git objects.

The apply token must not call the model. A duplicate HTTP 200 is not another patch. It is the same key arriving twice.

Your cache makes that collapse into one file. A partial diff is a failed compile. Truncation belongs in the compiler failure domain.

Apply should reject a truncated envelope right away. If the cache disk fills, you stop generation. Filling the disk is a local failure.

That failure still beats a silent double apply. Keep those domains on separate credentials at all times. One leaked token should not do both jobs.

Apply never talks to the compiler host itself. Git is a local tool in this design. That split is how rollback stays yours.

You can aim that local plane at a remote generator. MonkeyCode offers free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Point the compiler URL at that option when useful. Keep cache and apply steps on your machine. The free server is the untrusted compiler host.

What you should change next

What you should change next is explicit signing. This section is a proposal, not a field report. The apply plane should refuse an unsigned diff.

You should add per-path leases inside the worktree. Two keys must not touch the same file. A lease file would make that conflict visible.

You should add a dead-letter directory for rejects. Failed apply is its own failure domain. Do not retry it through the model by default.

You should add an explicit cancel protocol later. Today the flag only stops local apply. A real protocol would also stop wire spend.

Do not use this if chat is your record. People who live in threads will hate it. The design throws the thread away on purpose.

Do not use this for secrets that cannot leave. A remote compiler is still an egress path. A local model belongs in that case instead.

Do not use this when you need a contractual SLA. A free server is a courtesy, not a promise. On-call generation needs a named service contract.

The pattern also fails on huge binary blobs. Hashing and caching diffs assumes text patches only. Generated binary assets still need a different store.

A real compiler is deterministic in normal practice. A remote model is not deterministic at all. The idempotency key covers transport, not patch semantics.

Two runs with one key should store one file. They will not guarantee the same future bytes. Freeze the artifact after the first success.

You still need a human or a verifier. This architecture does not grade the patch quality. It only stops double apply and lost bytes.

Latency will stay ugly on a shared free path. Backpressure belongs in your local poll budget. Do not hide it behind a spinner UI.

Wire a tiny apply gate around the cache. The gate checks the key, the lease, and truncation. Then it runs a dry-apply before git write.

# proposed_apply_gate.py — example only
import subprocess, sys
from pathlib import Path

def looks_truncated(diff: str) -> bool:
    if not diff.endswith("\n"):
        return True
    if "diff --git " not in diff:
        return True
    return False

def dry_apply(diff_path: Path) -> None:
    subprocess.run(
        ["git", "apply", "--check", str(diff_path)],
        check=True,
    )

def apply_once(key: str, diff_path: Path) -> None:
    if already_applied(key):
        raise SystemExit(f"key {key} already applied")
    text = diff_path.read_text(errors="replace")
    if looks_truncated(text):
        raise SystemExit("truncated artifact; stay in compiler domain")
    dry_apply(diff_path)
    subprocess.run(["git", "apply", str(diff_path)], check=True)
    mark_applied(key)

if __name__ == "__main__":
    key, path = sys.argv[1], Path(sys.argv[2])
    apply_once(key, path)

Run it only against a cached artifact path. Never pipe the HTTP body into git apply. The file is the contract you can re-read.

python proposed_apply_gate.py "$KEY" ".gen-cache/${KEY}.diff"

If you try the local cache pattern, keep apply local. The generator can stay cheap and remote. Your repo should remain the only memory that matters.

Pin the Patch Contract, Not the Model

Harper Xu — Mon, 21 Sep 2026 13:38:47 +0000

A remote generator is a vendor you cannot pin. Pin the patch contract instead of the endpoint. Treat every model swap as an architecture event.

Chat output is not a safe apply API. That leftover hole sits in the contract. An unpinned model can ship a well-formed lie.

The constraint you actually have

You do not own the remote model you call. You do not pin its weights like a library. You also do not freeze its decoding path.

A free remote path makes this constraint visible. The generator can move overnight without any notice. Your repository does not move with that generator.

Your old tests may still pass after the swap. They mostly remember yesterday's habits and shapes. They do not name today's intent at all.

Think of the model as a shipping carrier. You do not control the truck on that route. You control the crate and the seal.

MonkeyCode offers free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Use that path as an untrusted vendor. Never hand that path your apply credentials.

Data flow worth drawing

Keep the data flow one-directional and dull. Intent leaves your repo as a typed request. A patch returns as a typed envelope.

Apply never reads chat prose as input. Chat remains a scratchpad only, nothing more. The envelope is the object you store.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "PatchEnvelope",
  "type": "object",
  "additionalProperties": false,
  "required": ["intent_id", "base_sha", "files", "tests"],
  "properties": {
    "intent_id": { "type": "string", "minLength": 8 },
    "base_sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
    "files": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["path", "action", "diff"],
        "properties": {
          "path": {
            "type": "string",
            "pattern": "^(src|tests)/[A-Za-z0-9_./-]+$"
          },
          "action": { "enum": ["modify", "add"] },
          "diff": { "type": "string", "minLength": 1 }
        }
      }
    },
    "tests": {
      "type": "array",
      "minItems": 1,
      "items": { "type": "string", "pattern": "^tests/" }
    }
  }
}

Save the schema as contracts/patch-envelope.schema.json. The schema is the pin you actually own. The model is not the pin you own.

Your generator may run on a free remote server. That server still sits outside the apply room. Source leaves your tree only as packed intent.

Secrets stay on your side of the door. Envelopes come back for review on your side. Review never happens in the generator room itself.

# tools/pack_intent.py
# Proposal: freeze an intent before any remote call.
import argparse, json, subprocess, datetime, sys

parser = argparse.ArgumentParser()
parser.add_argument("--intent-id", required=True)
parser.add_argument("--goal", required=True)
parser.add_argument("--allow", action="append", required=True)
args = parser.parse_args()
base = subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip()
intent = {
    "intent_id": args.intent_id,
    "goal": args.goal,
    "base_sha": base,
    "allow": args.allow,
    "packed_at": datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ"),
}
json.dump(intent, sys.stdout, indent=2)
print(file=sys.stderr)

python3 tools/pack_intent.py \
  --intent-id "timeout-$(date +%s)" \
  --goal "fail closed when the HTTP client exceeds 2s" \
  --allow 'src/**' --allow 'tests/**' \
  > /tmp/intent.json

That command does not generate any code. It only freezes the request for later use. Generation runs later against this frozen file.

Do not generate against a chat scroll. Chat scrolls are not replayable objects later. Frozen files survive a later model swap.

Failure domains

Draw three rooms with locked doors between them. The intent room holds a repo view. The generator room holds the remote model only.

The apply room holds your apply credentials. A model swap lives only next door. It must not open the apply door.

Schema failure needs a fourth locked room. Call that fourth room the envelope gate. The gate holds no apply credentials at all.

If the envelope fails schema, you drop it. Do not tidy a bad envelope inside apply. Hand repair mixes vendor text with trusted edits.

Network failure is not an apply retry. You may retry generate only after a drop. Apply then needs a completely fresh envelope.

Give that envelope a new intent id. Colliding intent ids hide those retries from audit. Hidden retries will break a later audit.

Model drift looks like a quiet roommate. The produced diff can still apply cleanly. Your old tests can still pass afterward.

The new behavior was never named in tests. That silence is the real outage mode. Passing tests are not a named contract.

The envelope therefore requires named tests for the intent. Those tests are not the whole suite. They are this intent's contract, nothing else.

A gate you can run locally

Treat the next script as a proposal. It fails closed on purpose, not open. It is not a production service yet.

# tools/gate_envelope.py
# Proposal: fail closed on schema, path, or base mismatch.
import json, subprocess, sys, pathlib
from jsonschema import Draft202012Validator

ROOT = pathlib.Path(__file__).resolve().parents[1]
schema = json.loads((ROOT / "contracts/patch-envelope.schema.json").read_text())
envelope = json.loads(pathlib.Path(sys.argv[1]).read_text())
Draft202012Validator(schema).validate(envelope)

head = subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip()
if envelope["base_sha"] != head:
    sys.exit("base_sha does not match HEAD; regenerate, do not apply")

for item in envelope["files"]:
    path = pathlib.Path(item["path"])
    if path.is_absolute() or ".." in path.parts:
        sys.exit(f"rejected path: {path}")
    if item["action"] == "modify" and not path.exists():
        sys.exit(f"modify target missing: {path}")

print("envelope accepted for review")

Install the checker, then run it locally. Do this before any apply step runs. Skip this step and the rooms collapse.

python3 -m pip install jsonschema
python3 tools/gate_envelope.py /tmp/envelope.json
git apply --check /tmp/proposed.diff

A dry apply check is not behavior proof. It only proves that the diff parses. Behavior proof lives in the named tests.

mapfile -t T < <(python3 -c 'import json,sys; print("\n".join(json.load(open(sys.argv[1]))["tests"]))' /tmp/envelope.json)
pytest -q "${T[@]}"

If the model also wrote those tests, stop. You have built a circular test gate. Circular gates smile and let poison through.

Write the tests in the intent room. Keep high-risk tests off the model path. Let the model fill implementation details only.

Add a stub generator in CI next. The stub must emit invalid envelopes on purpose. CI must fail when the gate is missing.

# tools/stub_generator.py
# Proposal: negative fixture for the envelope gate.
import json, sys
bad = {
    "intent_id": "x",
    "base_sha": "not-a-sha",
    "files": [{"path": "../etc/passwd", "action": "modify", "diff": ""}],
    "tests": ["not-a-test"],
}
json.dump(bad, sys.stdout)

python3 tools/stub_generator.py --invalid > /tmp/bad.json || true
if python3 tools/gate_envelope.py /tmp/bad.json; then
  echo "gate failed open" >&2
  exit 1
fi

A green pipeline with no negative stub is theater. Theater is how drift lands in main. Force that drift to die in generate.

Decision matrix

Use this table as a hard gate. Do not use mood as a substitute. Mood belongs only in later review comments.

Signal	Generator room	Apply room
Model endpoint changed	Regenerate envelope	Block
Schema invalid	Drop output	Block
`base_sha` mismatch	Pack a new intent	Block
Path outside allowlist	Drop output	Block
Named tests missing	Reject intent	Block
Named tests pass, extra files appear	Drop output	Block
Reviewer note only, no envelope	Ignore	Block

The apply column is boring on purpose. Apply does not improvise on bad input. Improvisation stays in the generate room only.

Cheap failure belongs in the generate room. Expensive failure belongs nowhere in this design. The gate exists to keep them apart.

What you would change next

Store intent, envelope, and test output together. That bundle is your replay handle later. Replay is how you survive a model swap.

Then shrink what you send on the remote path. Stop shipping whole files for a local change. Send a function body when that is enough.

Less repo in the generator room always helps. The blast radius shrinks with the payload. Hostile disks then hold less of you.

If you use a free server, treat its disk as hostile. Do not mount your working tree on it. Send the packed intent file only, nothing else.

Add dual control on apply as a later change. One person accepts the envelope in review. Another person then runs the apply command.

Chat approval is not dual control at all. Chat history is vapor after the session. Vapor does not bind an apply action.

Limitations

This gate does not score model quality. It checks shape, path, and named tests. A wrong patch can still fit the crate.

The schema forbids deletes and absolute paths today. That rule will block some legitimate work. Widen it only with an explicit intent flag.

Remote generation moves source across a public network. Skip this remote path for any secrets. Skip it for customer data as well.

Skip it for unreleased product code too. Air-gapped teams should generate only on local hosts. Some teams should not generate remotely at all.

Teams without a human reviewer should stop here. The gate is a lock, not judgment. Locks do not read product intent for you.

Do not point apply credentials at the generator host. A free server remains a separate room. Shared credentials merge the rooms you drew.

If you try a free remote generator, start small. Use a throwaway branch and this gate. Leave production apply untouched until the gate holds.

Verification Needs Its Own Failure Domain

Harper Xu — Sun, 20 Sep 2026 11:36:42 +0000

Generated tests cannot vouch for generated code. They fail in the same places. You need a separate verification domain.

A model that writes a function also writes its exam. That is one author grading itself. You would not ship that in any other system.

Think of a locksmith who also prints the inspection sticker. The door looks certified from the hallway. The sticker never left the same workshop. Your AI pipeline often works exactly that way.

You already split generate from apply in other reviews. This piece is not that split. This is about the oracle that claims the patch is safe.

Constraints you actually have

You do not control the model's private checks. You control what may enter main. That is the only honest constraint you own.

The context window is not a specification. It is mixed, stale, and incomplete. Treat it as contaminated input, not as law.

Time fights you as well. A generated suite can pass tonight. It can miss the bug you will hit on Friday.

Cost fights you too. Cheap tokens invite extra tests from the same session. Extra tests from the same author add theater, not coverage.

You also cannot prove a hidden property the corpus never stated. Silence is not green. Green requires an oracle you already trusted.

Data flow that stays honest

Keep three streams, and never braid them. The corpus is frozen and human-owned. The candidate is generated and untrusted. The verdict is computed on a third host.

You send the model a task envelope only. You receive a patch, nothing else. You refuse tests, scripts, and CI edits from that reply.

The verifier host clones a clean tree. It applies the patch in a sandbox. It runs only the frozen corpus against that tree.

If the corpus is silent on a change, you fail closed. New behavior without an old oracle is a hole. You write the oracle first, then you generate.

Here is a proposed local gate. Label it unexecuted until you wire it. Do not treat it as a certified toolchain.

#!/usr/bin/env bash
# verify_gate.sh — proposed local gate, not production gospel
set -euo pipefail

PATCH=${1:?patch file required}
CORPUS=${2:?frozen corpus directory required}
ROOT=$(git rev-parse --show-toplevel)
WORKDIR=$(mktemp -d)
trap 'rm -rf "$WORKDIR"' EXIT

git clone --local "$ROOT" "$WORKDIR/tree"
git -C "$WORKDIR/tree" apply --check "$PATCH"
git -C "$WORKDIR/tree" apply "$PATCH"

# Product code may change. The scorekeeper may not.
if awk '/^diff --git /{f=0} /^diff --git .*\/(tests|spec)\// {f=1} f && /^\+\+\+ /{print}' "$PATCH" | grep -q .
then
  echo "refuse: patch touches tests; corpus stays frozen" >&2
  exit 2
fi

cd "$WORKDIR/tree"
python -m pytest "$CORPUS" -q --maxfail=1

That script encodes one architectural rule. The patch may change product code. It may not smuggle its own scorekeeper into the tree.

Pair the gate with a contract the corpus already owns. The generator should never receive this file if you can help it. Hidden oracles beat prompt-fed oracles.

# contracts/test_quote_shape.py
# Proposed example. Wire it before you invite a generator.

from app.billing import quote


def test_quote_never_goes_negative():
    total = quote(items=[], coupon="WELCOME")
    assert total >= 0


def test_quote_rejects_unknown_sku():
    try:
        quote(items=[{"sku": "nope", "qty": 1}], coupon=None)
    except ValueError:
        return
    raise AssertionError("unknown sku must fail")

You own those checks before any model runs. They describe money, not style. A generator that never saw them cannot teach to the test.

Move the patch across the boundary as a file. Do not pipe a chat transcript into pytest. Files have hashes. Chat logs do not.

# proposed flow on your verifier host
sha256sum candidate.patch > candidate.patch.sha256
./verify_gate.sh ./candidate.patch ./contracts

If the hash and the verdict disagree later, you have a story. If you only kept the chat, you have fog.

Failure domains, drawn as rooms

Picture three rooms with locked doors. Room A writes candidates. Room B stores the corpus. Room C applies merges.

Room A can burn down. You lose drafts and prompts. That loss is acceptable. Drafts are cheap. Oracles are not.

Room B must not share a filesystem with A. Shared disks are shared fate. Shared prompt history is shared fate too.

Room C accepts only artifacts that B already blessed. It does not chat with a model. It does not fetch "just one more test."

Most teams collapse A and B onto one laptop. That laptop then talks to CI with your identity. One prompt injection now poisons code and proof together.

This is not a review of the generator host itself. You already know that host is a blast radius. This review is about the oracle living next door and pretending it is independent.

If verification shares memory, credentials, or logs with generation, it is not independent. A unit test written in the same session is a roommate, not a referee. Roommates do not audit the lease.

Network policy should make the rooms boring. Room A reaches a model endpoint only. Room B reaches nothing outbound. Room C reaches your registry, not a chatbot.

Logs need the same split. Generator traces stay in A. Corpus hashes stay in B. Merge tickets in C cite both, and never mix the files.

# proposed record, written by the verifier, not the model
patch_sha256:  9f3c…
corpus_sha256: 41aa…
pytest_exit:   0
verifier_host: verify-07
generator_host: (cited, never trusted)

That record is the architecture. The model is a printer in Room A. Printers do not sign the building permit.

Where a disposable generator host fits

You still need somewhere to produce candidates. That somewhere should be disposable. It should never hold the frozen corpus.

MonkeyCode offers free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Park generation there so Room A is not your laptop.

Keep the oracle off that box. Do not upload contracts to a throwaway server. Do not let the apply identity live there either.

A short pattern looks like this. Generate on the remote box. Pull a patch file home. Verify on a host that never held the prompt.

# proposed; your generator command stays yours
ssh generator 'python gen_candidate.py > /tmp/candidate.patch'
scp generator:/tmp/candidate.patch ./candidate.patch
./verify_gate.sh ./candidate.patch ./contracts

If the free server vanishes, you lost drafts. You did not lose the exam. That is the point of the room split.

Do not send production snippets to any shared generator to "make tests." That inverts the flow. The exam would then be written from the crime scene.

What you should change next

Sign the corpus and verify the signature in CI. A writable tests directory is an unsigned exam. Unsigned exams invite the author back into the grading room.

Add a path denylist in the merge queue, not only in a laptop script. The script above is a teacher. The queue is the lock.

# proposed merge-queue fragment
policy:
  refuse_if_patch_touches:
    - contracts/**
    - tests/**
    - .github/workflows/**
  require:
    - contracts_signature
    - verify_gate_exit_zero

Then grow oracles that are not example-based. Property tests and golden files age better than one happy-path pytest. Generated unit tests age like unused coupons.

If you can afford it, run two verifiers. Same patch, two hosts, one corpus hash. Disagreement is a signal. Agreement is still not proof of missing properties.

Mutation testing against the frozen corpus is the next honest metric. If killing a line does not fail a contract, you lacked an oracle. You did not lack another generated test.

Limitations, and who should not bother

This split fails when you have no frozen corpus. A greenfield spike still needs a human oracle first. Do not generate the product and the proof in one sitting and call it architecture.

This also fails when the product is the test suite. Fuzz harnesses and compiler tests need a different shape. Do not copy this gate onto those trees without redesign.

Regulated or safety-critical work needs more than pytest and a shell script. This article does not offer a certified method. Do not file it as one.

Solo prototypes can ignore the three rooms for a day. Do not ignore them the day you attach CI credentials. Theater starts at the first green badge you did not earn.

You should not use a remote generator for private data you cannot expose. Free compute is not a data policy. Room A still egresses whatever you paste.

Verification is a failure domain, not a plugin. If the author still writes the exam, you are grading a mirror. Keep the mirror in Room A, and keep the exam in Room B.

Every Prompt Is an Egress Event

Harper Xu — Sat, 19 Sep 2026 09:42:17 +0000

Every prompt you send is an egress event. Treat that generator like any other foreign network. You cannot unsay a secret after the packet leaves.

Architecture reviews start with constraints, not with models. Your working tree holds tokens, hostnames, and private paths. A remote generate plane must not receive that class.

This piece is an architecture review of the prompt path. It maps constraints, data flow, and failure domains. Then it gives you a local gate you can run.

Constraints on the prompt path

You do not control the remote generate host. You also do not control its disks or operators. That is normal for any compiler you did not build.

Free remote capacity makes this constraint sharper today. A free generate plane still sits off your laptop. Courtesy does not move the trust boundary one inch.

So you classify each path before you pack. You pack the allowed files before you send. You send only what a stranger may read.

Think of a shipping crate sitting on a dock. Customs inspects that crate before the ship sails. Your context pack is the same kind of crate.

Do not argue with the ocean after departure. Build a dock inspection you actually run.

The crate is not the whole warehouse. A generate prompt does not deserve the warehouse. It deserves a labeled box with a short inventory.

Data flow and failure domains

The flow stays simple once you name hops. The local editor reads the working tree first. A local gate then classifies each file path.

Allowed files fold into a narrow context pack. Denied files stay on the local disk. Detected secrets abort the whole export at once.

The pack leaves through a single client process. A remote model returns a patch artifact later. You review that artifact before any apply step.

Notice the data that never crosses the wire. Local production environment files never leave your laptop. Cloud keys and internal host maps stay put.

The generator only sees structure you marked public. It may see interfaces, tests, and safe comments. It must never see the plant combination lock.

Keep a policy file in the same repository. You review those edits like firewall rule changes. Treat a policy edit as an architecture change.

# egress_policy.yml — lives locally, never rides with the pack
allow:
  - "src/**/*.py"
  - "tests/**/*.py"
  - "README.md"
deny:
  - "**/.env*"
  - "**/*secret*"
  - "**/credentials*"
  - "**/*.pem"
  - "ops/**"
max_file_bytes: 65536
max_pack_files: 40

Do not upload that deny list with the pack. The deny list names rooms you keep locked. A foreign compiler does not need your floor plan.

Name failure domains or you will mix them. Domain A is the working tree on disk. Domain B is the classified pack you export.

Domain C is the remote generate service itself. Domain D is the reviewed patch you might apply. Do not share credentials across those four domains.

A leak in Domain B is an export incident. A crash in Domain C is only downtime. Do not treat those two failures as equal.

Convenience is how teams mix the domains. The usual mix-up looks harmless in a chat box. Speed is not a reason to skip inspection.

You dump the repository into the prompt window. The dump crosses Domain A into Domain C uninspected. That hop is the incident, not the model brand.

That is not a coding style problem at all. That is an egress control problem on the wire. Fast prompts still leave the building as data.

Another failure mode is quiet oversharing of topology. A helper module still hardcodes a staging hostname. The name is not a key, yet it maps your network.

Classification is more than a search for cloud tokens. You also label environment topology as restricted data. Hostnames can be as sensitive as passwords here.

A third failure is a resend without classify. You tweak one sentence and fire the pack again. Re-run the gate against the same working tree.

Run the gate on your machine every time. Do not run inspection on the generate host. The inspector belongs on the dock you own.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. Some teams place a remote helper in Domain C. MonkeyCode's free model access and free server option can fill that hop.

They still must not see Domain A files. The gate below does not depend on that product.

A gate you can run

The script below acts as the dock inspector. It is a labeled local example, not production magic. You should run it on a throwaway clone first.

#!/usr/bin/env python3
"""Local egress gate for a generate prompt pack.

Labeled example: run on a disposable clone, not production data.
"""
from __future__ import annotations

import fnmatch
import json
import re
import sys
from pathlib import Path

ROOT = Path(".").resolve()
POLICY = {
    "allow": ["src/**/*.py", "tests/**/*.py", "README.md"],
    "deny": [
        "**/.env*",
        "**/*secret*",
        "**/credentials*",
        "**/*.pem",
        "ops/**",
        "**/.git/**",
    ],
    "max_file_bytes": 65536,
    "max_pack_files": 40,
}

SECRET_RE = re.compile(
    r"(?i)(api[_-]?key|secret|token|password|begin [a-z]+ private key)\s*[:=]"
)

def rel(path: Path) -> str:
    return path.resolve().relative_to(ROOT).as_posix()

def denied(path: str) -> bool:
    return any(fnmatch.fnmatch(path, pat) for pat in POLICY["deny"])

def allowed(path: str) -> bool:
    return any(fnmatch.fnmatch(path, pat) for pat in POLICY["allow"])

def classify(path: Path) -> str:
    name = rel(path)
    if denied(name):
        return "deny"
    if not allowed(name):
        return "unlisted"
    if path.stat().st_size > POLICY["max_file_bytes"]:
        return "too_large"
    text = path.read_text(encoding="utf-8", errors="replace")
    if SECRET_RE.search(text):
        return "secret"
    return "ok"

def build_pack() -> dict:
    files = []
    for path in ROOT.rglob("*"):
        if not path.is_file():
            continue
        status = classify(path)
        if status in {"deny", "unlisted"}:
            continue
        if status != "ok":
            raise SystemExit(f"egress blocked: {rel(path)} ({status})")
        body = path.read_text(encoding="utf-8", errors="replace")
        files.append({"path": rel(path), "bytes": len(body.encode("utf-8"))})
        if len(files) > POLICY["max_pack_files"]:
            raise SystemExit("egress blocked: pack too wide")
    return {"root_name": ROOT.name, "files": files, "policy_sent": False}

def main() -> None:
    pack = build_pack()
    out = ROOT / "egress_pack.json"
    out.write_text(json.dumps(pack, indent=2), encoding="utf-8")
    print(f"pack ready: {out} files={len(pack['files'])}")
    print("send only listed file bodies, never the deny list")
    print("do not attach the rest of the tree")

if __name__ == "__main__":
    main()

Exercise the gate with a planted secret on purpose. You want the refusal, not a green pack.

mkdir -p src tests
printf 'print("ok")\n' > src/app.py
printf 'API_KEY=planted-value\n' > src/leaky.py
python3 egress_gate.py
# expected: egress blocked: src/leaky.py (secret)

Move the leaky file out of the allow paths. The gate should then build a narrow pack. Read the pack file before any client upload.

rm src/leaky.py
printf 'def test_ok():\n    assert True\n' > tests/test_app.py
python3 egress_gate.py
cat egress_pack.json

Wire your generate client to that manifest only. If the client can read extra paths, stop. A client that ignores the pack list is unsafe.

Watch the policy_sent field in the manifest. It must stay false on every upload. Domain C should never learn your deny patterns.

Change three things after this first gate works. Today the classifier is a regex plus glob. Regex will miss custom tokens and encoded blobs.

Next you attach a sensitivity label per directory. Store those labels in .egress-labels beside the code. The gate should fail closed on unlabeled paths.

Next, split human comments from machine generated comments. Generated comments often echo internal ticket numbers still. Those ticket numbers can map your org chart.

Next, give Domain C a throwaway identity only. Do not reuse the cloud credentials of apply. Generation needs no deploy role at all.

This approach is not for every team. Skip it if regulated data cannot leave the building. Skip it if legal forbids any remote generate hop.

Skip it if you paste whole repositories into a browser. The gate cannot save a copy-paste habit. Architecture does not outrun a human dump.

The scanner will false-negative on novel secret shapes. It will false-positive on the word token in docs. Read every refusal and do not mute the gate.

You also still need a human patch review. Egress control is not the same as correctness control. A clean pack can still yield a bad patch.

Remote generate remains useful under these strict rules. You still keep speed for boilerplate and tests. You keep the plant keys on the dock.

Hash the Envelope Before You Generate

Harper Xu — Fri, 18 Sep 2026 08:03:11 +0000

You do not control generation until inputs are pinned. A chat box is not an interface. It is an unbounded failure domain.

Most teams argue about models and prompts. That debate skips the real contract. The contract is everything the model may see.

Think of a compiler, not a conversation. You do not feed it your home directory. You pass sources, flags, and a working directory. Generation needs that same envelope.

Constraints you already have

Your apply host already holds secrets. It holds deploy keys and cloud tokens. Config files still name production hosts.

Dump the working tree into a prompt and you copy that surface. The model host becomes a second production context. That copy almost never has your real controls.

You also lose replay. Yesterday's tree is not today's tree. A floating context window cannot be audited later. Reviewers then guess which files the model actually saw.

So the constraint stays simple. The generate plane may read a hashed envelope. Nothing else crosses that boundary. If a file is not named, it does not exist.

Data flow that actually holds

Start from the apply host, not a chat UI. The apply host already knows the branch. It already knows the ticket. It should write a generation request as a file.

That file names allowed paths and a base commit. It names the task in one short sentence. It also names forbidden globs so secrets stay out.

You hash every included blob. You hash the request document itself. Then you send only that bundle to the generate host. The host never mounts your working tree. It never inherits your shell environment.

It writes a patch and a receipt. The receipt repeats the hashes. Reviewers check receipt against request. Apply happens only after that match. Chat logs are leftover debris. Receipts are the audit trail.

Here is a concrete envelope. Treat it as a checked-in contract. Do not treat it as a prompt.

{
  "apiVersion": "generate.local/v1",
  "kind": "GenerationEnvelope",
  "metadata": {
    "id": "ticket-1842-rename-retry",
    "createdAt": "2026-09-18T12:00:00Z"
  },
  "spec": {
    "baseCommit": "9f3c1a0e8b77d2c1a4e6f0b9c8d7e6f5a4b3c2d1",
    "task": "Rename retry helper; keep public signatures.",
    "include": [
      "src/retry.ts",
      "src/retry.test.ts"
    ],
    "excludeGlobs": [
      "**/.env",
      "**/*secret*",
      "**/*.pem",
      "**/node_modules/**"
    ],
    "maxBytes": 65536,
    "output": {
      "format": "unified-diff",
      "maxFiles": 4,
      "maxBytes": 32768
    }
  }
}

Keep that document small on purpose. Small envelopes fail closed. Giant envelopes only pretend to be architecture.

A validator you can run today

Do not trust a human to pack the bundle. Humans paste extra files under time pressure. A script should refuse the model call instead.

Save this as pin_envelope.py. It reads the envelope and copies allowed files. It writes a tarball plus SHA-256 sums. If it exits non-zero, you stop.

#!/usr/bin/env python3
"""Build a pinned generation envelope. Refuse unbounded context."""
from __future__ import annotations

import hashlib
import io
import json
import sys
import tarfile
from pathlib import Path

MAX_FILE_BYTES = 32 * 1024


def sha256_bytes(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()


def load_envelope(path: Path) -> dict:
    doc = json.loads(path.read_text(encoding="utf-8"))
    if doc.get("kind") != "GenerationEnvelope":
        raise SystemExit("kind must be GenerationEnvelope")
    spec = doc.get("spec") or {}
    if not spec.get("baseCommit"):
        raise SystemExit("spec.baseCommit is required")
    if not spec.get("include"):
        raise SystemExit("spec.include must list files")
    return doc


def assert_allowed(root: Path, rel: str, exclude_globs: list[str]) -> Path:
    path = (root / rel).resolve()
    if not str(path).startswith(str(root.resolve())):
        raise SystemExit(f"path escapes workspace: {rel}")
    if not path.is_file():
        raise SystemExit(f"missing file: {rel}")
    for glob in exclude_globs:
        if path.match(glob) or Path(rel).match(glob):
            raise SystemExit(f"excluded by glob {glob}: {rel}")
    return path


def main() -> None:
    if len(sys.argv) != 4:
        raise SystemExit("usage: pin_envelope.py ENV.json WORKDIR OUTDIR")
    env_path = Path(sys.argv[1])
    workdir = Path(sys.argv[2]).resolve()
    outdir = Path(sys.argv[3])
    outdir.mkdir(parents=True, exist_ok=True)

    doc = load_envelope(env_path)
    spec = doc["spec"]
    exclude = spec.get("excludeGlobs") or []
    max_bytes = int(spec.get("maxBytes") or 65536)

    blobs = []
    total = 0
    for rel in spec["include"]:
        path = assert_allowed(workdir, rel, exclude)
        data = path.read_bytes()
        if len(data) > MAX_FILE_BYTES:
            raise SystemExit(f"file too large: {rel}")
        total += len(data)
        if total > max_bytes:
            raise SystemExit("envelope exceeds spec.maxBytes")
        blobs.append((rel, data, sha256_bytes(data)))

    receipt = {
        "envelopeSha256": sha256_bytes(env_path.read_bytes()),
        "baseCommit": spec["baseCommit"],
        "files": [
            {"path": p, "sha256": h, "bytes": len(d)}
            for p, d, h in blobs
        ],
    }
    receipt_path = outdir / "receipt.json"
    receipt_path.write_text(json.dumps(receipt, indent=2) + "\n", encoding="utf-8")

    tar_path = outdir / "context.tar"
    with tarfile.open(tar_path, "w") as tar:
        tar.add(env_path, arcname="envelope.json")
        tar.add(receipt_path, arcname="receipt.json")
        for rel, data, _ in blobs:
            info = tarfile.TarInfo(name=f"tree/{rel}")
            info.size = len(data)
            tar.addfile(info, fileobj=io.BytesIO(data))

    print(f"wrote {tar_path}")
    print(f"envelope sha256 {receipt['envelopeSha256']}")


if __name__ == "__main__":
    main()

Run it against a throwaway tree first. Confirm the happy path before you argue policy.

mkdir -p /tmp/demo/src /tmp/out
printf 'export function retry() { return 1 }\n' > /tmp/demo/src/retry.ts
printf 'test("retry", () => {})\n' > /tmp/demo/src/retry.test.ts
printf 'SECRET=not-for-models\n' > /tmp/demo/.env
python3 pin_envelope.py envelope.json /tmp/demo /tmp/out
sha256sum /tmp/out/context.tar /tmp/out/receipt.json

Then force a negative path. Point include at .env and watch it die. That failure is the architecture working. Do not "fix" it by widening the glob list.

python3 - <<'PY'
import json
from pathlib import Path
doc = json.loads(Path("envelope.json").read_text())
doc["spec"]["include"] = [".env"]
Path("/tmp/bad.json").write_text(json.dumps(doc, indent=2))
PY
python3 pin_envelope.py /tmp/bad.json /tmp/demo /tmp/out-bad
# expected: excluded by glob **/.env

If that command succeeds, your exclude list is theater. Stop there and repair the envelope. Do not call a model with a broken packer.

Failure domains this split creates

The envelope builder can fail. It can hash the wrong commit. That failure stays local and reviewable. It does not talk to a model. You fix the document and rerun the hasher.

The generate host can fail next. It can ignore the envelope and ask for more files. Your network policy must deny that fetch. No extra clone. No extra archive. No "just one more path."

The model can fail after that. It can emit a diff outside include. The apply plane must reject that diff. A receipt that names two files cannot apply three. Pretty summaries do not override path math.

Review can fail last. People rubber-stamp fluent prose. Force the review UI to show hashes first. Show the path list before any explanation. Hide the story until the receipt matches.

Notice the chat transcript is not in this chain. If your only record is a thread, you have no architecture. You have a memory of a conversation.

Where a free generate host fits

You still need somewhere to run the model call. That host should not be your laptop checkout. It should not be the deploy runner either. Those two machines already hold the blast radius you are trying to shrink.

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

MonkeyCode offers free model access and a free server option. Those two facts matter as generate-plane placement, not as a slogan. You upload a pinned tarball. You take back a diff and a receipt. You do not mount the apply workspace on that server.

If you already have an isolated generate runner, keep it. The envelope does not require a vendor. It requires a boundary you can hash. A free server is useful when you lack a spare isolate. It is harmful if you paste a checkout into a web chat. That paste is the old unbounded interface in a new tab.

What you change next

Store envelopes in git beside the ticket branch. Reviewers then see the input contract. They stop guessing from a dumped thread. The pull request should include envelope.json and receipt.json before any patch.

Make CI refuse generate jobs without receipt.json. A job that only stores a patch is incomplete. Incomplete jobs should never reach humans. Incomplete jobs should never reach git apply.

Shrink include until the task actually breaks. Then add one file, not ten. That pain shows which files were ritual. Ritual context is how secrets leak into prompts.

Bind output paths to the same allowlist. A retry rename should not rewrite Dockerfile. If the model needs more files, it requests a new envelope. It does not scrape the disk. A second envelope is cheaper than a silent extra file.

An apply-side check that stays boring

After the model returns, do not merge on tone. Verify the diff against the receipt. Keep the check smaller than the model call.

#!/usr/bin/env bash
set -euo pipefail
receipt="$1"
diff="$2"
python3 - "$receipt" "$diff" <<'PY'
import json, re, sys
receipt = json.load(open(sys.argv[1]))
allowed = {row["path"] for row in receipt["files"]}
text = open(sys.argv[2]).read()
paths = set(re.findall(r'(?m)^(?:--- |\+\+\+ )[ab]/(.+)$', text))
extra = sorted(p for p in paths if p not in allowed)
if extra:
    raise SystemExit("diff escapes envelope: " + ", ".join(extra))
print("diff stays inside envelope")
PY

Wire it like this against a known-good receipt.

chmod +x check_diff.sh
./check_diff.sh /tmp/out/receipt.json proposed.patch

That script is boring on purpose. Architecture that needs a speech is usually a leak. If the check and the hasher disagree, you have two sources of truth. Delete one.

Limitations and who should skip this

This workflow assumes you can name the files. Broad refactors across two hundred modules will fight the allowlist. That fight is useful. It is also slow. Do not pretend otherwise.

The hasher does not judge code quality. It only pins bytes. You still need tests on the apply plane. You still need a human at the review gate. A green hash is not a green build.

Do not put customer data in include just because the script allows it. Pinning is not a privacy policy. It is a blast-radius cap. Caps fail when you stuff the envelope with everything "just in case."

Skip this in a scratch repo with no secrets. A teaching demo can stay in a chat window. Production checkouts cannot. Skip this if the generate host can still read $HOME. An envelope on paper with a mounted home directory is theater.

You now have a typed inbound envelope, a hasher, and an apply check. The model sits downstream of those three. Keep it there. If you try a free generate host, send the tarball, not the repo. The receipt must echo the hashes you printed locally. Anything else is a different system than the one you reviewed.