DEV Community: Avery Li

The Pairing Transcript That Froze Retry Methods Before Generated Code Shipped

Avery Li — Sun, 20 Sep 2026 11:54:39 +0000

A pairing session should freeze retry methods and an idempotency key rule before any generated client code is allowed to ship. Free coding models write retry loops quickly, and those loops often treat every HTTP method as safe to repeat. The cost appears later as duplicate charges, repeated side effects, and logs that cannot name a canonical attempt. This article records one senior pairing as a transcript, then turns the kept decision into a checker.

The session below is a labeled worked example for a local HTTP helper, not a report of a named production outage. The pairing is completed before a model is asked to implement retries, timeouts, or backoff curves for the client. The artifact is a YAML transcript, a Python checker, a constrained client, and a small invariant test file. Teams can run the checker in CI without adopting any particular coding assistant or remote development host.

The problem the pairing had to stop

Internal tools often grow a retry wrapper after the first timeout appears in shared logs. A model can emit exponential backoff, jitter, and status-code lists in a single pass that looks complete. That output still leaves POST and PATCH inside the retry set, which is the failure mode the senior was asked to block. Review that only checks latency and HTTP status will bless the wrapper while remaining silent about duplicate side effects.

Generated tests are getting easier to produce, and that ease is part of the trap rather than the fix. A suite can prove that a call eventually returns 200 and still never ask whether the server ran a charge twice. The pairing therefore spends its time on method semantics and key identity, not on polishing sleep curves. The transcript is the review object; the later patch is only allowed to fill the envelope the transcript already closed.

Step 1: write the senior questions into a file

The pairing opens with a short question list that the senior expects answered in writing. Each answer names an owner file and a constraint, not a feeling about reliability or user impact. The worked example uses four questions only, so the session cannot wander into unrelated refactors or framework rewrites. Chat history is not the source of truth once the YAML exists on the branch.

# pairing-session.yaml
session_id: retry-helper-2026-09-20
status: kept
questions:
  - id: Q1
    ask: Which HTTP methods may the helper retry without creating duplicate side effects?
    answer: Only GET, HEAD, and PUT appear on the allowlist. POST and PATCH stay out.
    owner_file: retry_policy.yaml
  - id: Q2
    ask: What header makes two attempts the same logical request when a method is retried?
    answer: Idempotency-Key must be present, and the prefix must stay inv-2026-09-.
    owner_file: retry_policy.yaml
  - id: Q3
    ask: May generated development traffic leave the workstation for a remote coding host?
    answer: Development completion may use a remote coding host. Runtime product traffic may not.
    owner_file: egress_policy.yaml
  - id: Q4
    ask: Where do secrets for the product API live during generation and during tests?
    answer: Secrets stay in local env files that the generator cannot write. Tests use fixtures.
    owner_file: secrets.policy

Those four answers already bound the patch surface for anyone who reads the pull request later. A model prompt can receive the YAML as context, but reviewers still read the file rather than a screenshot of a conversation. If a later patch changes methods or the key prefix, the pairing status is no longer kept and the session must be reopened on purpose.

Step 2: publish the dead ends before anyone codes

Dead ends are rejected designs with a reason that a checker or a reviewer can quote without a meeting. The pairing does not keep a polite maybe for a future cleanup pull request. Each dead end blocks a tempting patch that generated code produces often when the prompt says make it more resilient. Writing them down is cheaper than arguing the same three designs after the helper already merged.

Retry every 5xx response for every method, because POST charges and webhook delivery would repeat under load.
Add exponential backoff without a method allowlist, because delay does not make a non-idempotent call safe to replay.
Let the client mint raw UUIDs as keys, because collisions across services would not share a frozen namespace.
Route runtime API calls through the same host used for code generation, because development egress is not an app dependency.

dead_ends:
  - id: D1
    rejected: retry_all_5xx
    reason: Status-code retries ignore method semantics and duplicate POST side effects.
  - id: D2
    rejected: backoff_without_allowlist
    reason: Timing policy cannot substitute for an explicit method allowlist.
  - id: D3
    rejected: unprefixed_uuid_keys
    reason: Keys without the frozen prefix cannot be grepped or revoked as a family.
  - id: D4
    rejected: runtime_via_codegen_host
    reason: A coding host is not an approved production hop for product HTTP.

When a later patch revives retry_all_5xx, the reviewer can point at D1 instead of reconstructing the argument from memory. The implementation step stays narrow because the pairing already spent its attention on the rejected shapes. That is the whole point of recording dead ends in the same commit as the helper.

Step 3: keep one decision and refuse to reopen it in the patch

The pairing keeps a single decision that later patches must not reopen while claiming to be a small cleanup. Extra improvements, including smarter jitter and hedged requests, wait for a new session with a new identifier. The kept decision in this example is narrow on purpose so a lexical checker can enforce it. Broad reliability slogans are not decisions.

Kept decision: the helper may retry only allowlisted methods, and every retried attempt must send Idempotency-Key values that start with inv-2026-09-.

kept_decision:
  id: KD-retry-allowlist
  summary: Retry GET, HEAD, and PUT only, with a frozen Idempotency-Key prefix.
  allow_methods: [GET, HEAD, PUT]
  deny_methods: [POST, PATCH, DELETE]
  key_header: Idempotency-Key
  key_prefix: inv-2026-09-
  max_attempts: 3
  reopen: false

The same rule can be read as a table during review, which is useful when the YAML is long and the patch is not.

Method	Retry allowed	Pairing reason
GET	yes	Read path in this service has no billed side effect
HEAD	yes	Metadata read is treated as idempotent
PUT	yes	Same body and key must replace one resource
POST	no	Creates charges, mail, or webhook work
PATCH	no	Partial updates are not frozen as idempotent here
DELETE	no	Replay can remove a resource the caller already replaced

Generated code likes to reopen policy while renaming functions and extracting a shared transport layer. The reopen: false flag tells both humans and tools that a new pairing is required to change methods or the prefix. Without that flag, the transcript becomes commentary and the next model run wins.

Step 4: fail CI when the patch violates the kept decision

A transcript that cannot fail CI will lose to the next generated patch, usually before lunch. The checker below is a labeled example for this tree, not production-hardened policy software. Operators should run it against their own filenames and extend the regexes if the client uses helpers. The senior accepted a cheap gate that catches the common generated pattern, not a soundness proof of every call path.

# check_kept_decision.py
from __future__ import annotations

import re
import sys
from pathlib import Path

import yaml

ALLOWED = {"GET", "HEAD", "PUT"}
DENIED = {"POST", "PATCH", "DELETE"}
PREFIX = "inv-2026-09-"
KEY_HEADER = "Idempotency-Key"

RETRY_CALL = re.compile(
    r"retry_request\(\s*method\s*=\s*[\"'](\w+)[\"']",
    re.MULTILINE,
)
KEY_LITERAL = re.compile(
    r"[\"']Idempotency-Key[\"']\s*:\s*f?[\"']([^\"']+)[\"']"
)

def load_decision(path: Path) -> dict:
    data = yaml.safe_load(path.read_text())
    decision = data["kept_decision"]
    if decision.get("reopen") is True:
        raise SystemExit("kept decision was reopened without a new pairing session")
    return decision

def scan_source(root: Path) -> list[str]:
    failures: list[str] = []
    for path in root.glob("*.py"):
        if path.name.startswith("check_"):
            continue
        text = path.read_text()
        for match in RETRY_CALL.finditer(text):
            method = match.group(1).upper()
            if method in DENIED or method not in ALLOWED:
                failures.append(
                    f"{path}: retry on {method} violates KD-retry-allowlist"
                )
        for match in KEY_LITERAL.finditer(text):
            value = match.group(1)
            if not value.startswith(PREFIX) and PREFIX not in value:
                failures.append(f"{path}: idempotency key missing prefix {PREFIX}")
        if "retry_request(" in text and KEY_HEADER not in text:
            failures.append(f"{path}: retry_request used without {KEY_HEADER}")
    return failures

def main() -> int:
    decision = load_decision(Path("pairing-session.yaml"))
    if set(decision["allow_methods"]) != ALLOWED:
        print("pairing allow_methods drifted from checker constants", file=sys.stderr)
        return 1
    failures = scan_source(Path("."))
    for item in failures:
        print(item, file=sys.stderr)
    return 1 if failures else 0

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

The checker is lexical on purpose, and that limitation belongs in the pairing notes rather than in a later excuse. It will miss getattr tricks, dynamic method names, and retries written in another language. Catching the default shape that models emit is still worth a few dozen lines, because that is the shape that otherwise merges.

Step 5: implement only inside the frozen envelope

After the transcript and checker exist, implementation can proceed without reopening method policy. The client below follows the kept decision and refuses denied methods before any network call is attempted. Comments and names label this as unexecuted sample code for the article. Production services still need a server that honors the same key.

# retry_client.py
from __future__ import annotations

from dataclasses import dataclass

ALLOWED_METHODS = frozenset({"GET", "HEAD", "PUT"})
KEY_PREFIX = "inv-2026-09-"

@dataclass(frozen=True)
class RetryEnvelope:
    method: str
    url: str
    idempotency_key: str
    attempts: int = 3

class PolicyError(ValueError):
    pass

def validate_envelope(env: RetryEnvelope) -> None:
    method = env.method.upper()
    if method not in ALLOWED_METHODS:
        raise PolicyError(f"{method} is outside the pairing allowlist")
    if not env.idempotency_key.startswith(KEY_PREFIX):
        raise PolicyError("idempotency key missing frozen prefix")
    if env.attempts > 3:
        raise PolicyError("attempt budget exceeds kept decision")

def retry_request(method: str, url: str, key: str, send):
    env = RetryEnvelope(method=method, url=url, idempotency_key=key)
    validate_envelope(env)
    headers = {"Idempotency-Key": env.idempotency_key}
    last_error = None
    for _ in range(env.attempts):
        try:
            return send(env.method, env.url, headers)
        except TimeoutError as exc:
            last_error = exc
    assert last_error is not None
    raise last_error

A small test file records the pairing as executable examples instead of a narrative in the pull request. These tests are the reviewer's fast path when a model sends a larger transport refactor. They do not prove exactly-once behavior on the server; they prove the client still refuses the dead ends.

# test_retry_invariants.py
import pytest
from retry_client import PolicyError, retry_request

def test_post_is_rejected():
    with pytest.raises(PolicyError):
        retry_request(
            "POST",
            "https://api.example.internal/charges",
            "inv-2026-09-a",
            lambda *args: None,
        )

def test_get_requires_prefix():
    with pytest.raises(PolicyError):
        retry_request(
            "GET",
            "https://api.example.internal/items/1",
            "other-a",
            lambda *args: None,
        )

def test_get_with_prefix_calls_send():
    seen = {}

    def send(method, url, headers):
        seen["method"] = method
        seen["headers"] = headers
        return 200

    status = retry_request(
        "GET",
        "https://api.example.internal/items/1",
        "inv-2026-09-a",
        send,
    )
    assert status == 200
    assert seen["headers"]["Idempotency-Key"].startswith("inv-2026-09-")

Local commands stay ordinary and do not require a vendor dashboard for the policy gate.

python -m pytest test_retry_invariants.py
python check_kept_decision.py

Where free model access belongs after the freeze

Generated patches arrive faster than policy arguments, which is why the transcript is committed before any implementation branch is opened. After that freeze, a coding assistant can draft the helper against the YAML without reopening the method allowlist. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source project that, per this account's operator, offers free model access and a free server option for development drafting.

Those options apply to drafting helpers like this retry client, not to production request paths or secret storage. Dead end D4 still forbids using a coding host as a runtime hop for product HTTP traffic. If a team wants a drafting host for that implementation step, MonkeyCode's free model access and free server option can host the session while the YAML and checker stay in review.

The same transcript works if a human intern writes retry_client.py by hand. Removing the product sentence does not remove the pairing, the table, or the tests. That is the test for whether the workflow is real engineering work rather than a story about tools.

Limitations

The lexical checker will miss retries hidden behind getattr, wrappers in other languages, or method names built from configuration at runtime. The frozen prefix is a review aid, not a cryptographic guarantee of exactly-once processing across services. The server on the other side must still honor the key, and this article does not implement server-side deduplication or an outbox.

No duration, quota, hardware, or benchmark is claimed for any coding host in this writeup. A free development server is not described as a production SLA, and it should not be treated as one in capacity planning. Teams that need those numbers should measure their own workloads against primary sources they control.

Who should not use this approach

Skip the workflow when the client already sits behind a queue that deduplicates by business key. Skip it when legal review forbids sending source to a remote coding host, even for drafting. Skip it when every service mints keys differently and no prefix can be frozen without a platform change.

Payment, webhook, and mail senders should not treat this helper as a substitute for an outbox or a broker with replay control. Teams without a senior who can answer the four questions should not ship a generated retry wrapper and call the pairing complete. In those cases the honest kept decision is to refuse generated retries until the ownership model exists.

The Pairing Kept a Rollback Contract Before Any Free Model Touched Staging

Avery Li — Sat, 19 Sep 2026 10:01:21 +0000

A pairing session with a senior engineer should freeze a rollback contract before any free coding model is allowed to change a shared server. The contract records every question asked, every dead-end hypothesis, and exactly one kept decision about how a patch may land. Without that freeze, free-model access turns a staging host into an unreviewed experiment rather than an engineering change. The workflow below treats the pairing log itself as the merge gate, not the generated patch from any model.

The problem the pairing is meant to catch

Free coding models make it cheap to emit a diff, and a shared staging process makes it cheap to apply that diff. Industry talk about vibe coding often stops at taste, while the operational failure is a host that changed without a reversible plan. A senior pairing partner notices that gap because the partner has been paged for similar silent edits. The pairing therefore refuses to let the model speak to the server until a rollback contract exists on disk.

Where a free model and a free server fit

Teams sometimes reach for MonkeyCode when they need free model access and a free server option for agent trials.

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

Those two availability facts do not replace review, ownership, or a rollback path on the host that will run the patch. The pairing log described below still applies if every product name is removed from the working method.

Worked example: overlapping POST /jobs

The following session is a labeled worked example, not a claim about a production outage at a named company. A staging service accepts POST /jobs and occasionally drops the last item when two requests overlap. The junior engineer wants a free model to rewrite the handler on the shared host immediately. The senior engineer refuses that path until four questions, two dead ends, and one kept decision are written to pairing_log.json.

1. Freeze the staging file and the failing test

The pairing starts by freezing what staging currently does, not by asking a model for a better handler. A health check and a copy of the running file become the rollback baseline for the rest of the session. The senior engineer will not discuss prompt text until those two artifacts exist beside the repository. The commands below assume a local staging replica that mirrors the shared host layout for this exercise.

mkdir -p app .pairing_frozen/app
python3 - <<'PY'
from pathlib import Path
src = Path("app/jobs.py")
if not src.exists():
    raise SystemExit("app/jobs.py missing; stop before any model edit")
Path(".pairing_frozen/app/jobs.py").write_text(src.read_text())
Path(".pairing_frozen/stamp").write_text("frozen\n")
print("froze", src, "->", ".pairing_frozen/app/jobs.py")
PY
python3 test_overlap.py --expect-fail

The buggy handler used in the example is a read-copy-write on a process-wide list, which loses items under overlapping POSTs. The unused lock in the file is deliberate, because it shows how a model can “see” a lock and still patch the wrong region. The pairing freezes this file first so later rollback does not depend on git history being clean.

# app/jobs.py — labeled worked example, currently racy
from http.server import BaseHTTPRequestHandler
import json
import threading

JOBS = []
_lock = threading.Lock()  # present, but the handler never takes it


class Handler(BaseHTTPRequestHandler):
    def log_message(self, format, *args):
        return

    def do_POST(self):
        length = int(self.headers.get("Content-Length", "0"))
        payload = json.loads(self.rfile.read(length) or b"{}")
        current = list(JOBS)
        current.append(payload)
        JOBS[:] = current  # overlap can drop an append
        body = json.dumps({"stored": len(JOBS)}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

# test_overlap.py — twenty concurrent posts against a threaded server
from __future__ import annotations

import importlib.util
import json
import sys
import threading
import urllib.request
from http.server import ThreadingHTTPServer
from pathlib import Path


def load_jobs():
    path = Path(__file__).parent / "app" / "jobs.py"
    spec = importlib.util.spec_from_file_location("jobs", path)
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    return mod


def main() -> None:
    mod = load_jobs()
    server = ThreadingHTTPServer(("127.0.0.1", 0), mod.Handler)
    threading.Thread(target=server.serve_forever, daemon=True).start()
    port = server.server_address[1]
    errors: list[str] = []

    def post(n: int) -> None:
        req = urllib.request.Request(
            f"http://127.0.0.1:{port}/jobs",
            data=json.dumps({"id": n}).encode(),
            headers={"Content-Type": "application/json"},
            method="POST",
        )
        try:
            with urllib.request.urlopen(req, timeout=2) as resp:
                resp.read()
        except Exception as exc:  # noqa: BLE001
            errors.append(str(exc))

    workers = [threading.Thread(target=post, args=(i,)) for i in range(20)]
    for worker in workers:
        worker.start()
    for worker in workers:
        worker.join()
    server.shutdown()
    stored = len(mod.JOBS)
    print(f"posted=20 stored={stored} errors={len(errors)}")
    lost = stored < 20
    expect_fail = "--expect-fail" in sys.argv
    if expect_fail and lost:
        sys.exit(0)
    if expect_fail and not lost:
        sys.exit("race did not drop jobs; freeze a failing baseline instead")
    if not expect_fail and (lost or errors):
        sys.exit("overlap still drops jobs; restore the frozen handler")
    sys.exit(0)


if __name__ == "__main__":
    main()

2. Store the senior questions as required fields

Spoken chat transcripts vanish quickly, so the senior's questions are stored as required fields in pairing_log.json. Each question has an owner, a one-line answer, and a timestamp so later patches cannot pretend the discussion never happened. The pairing session does not proceed while any answer field is still empty in that log. The four questions used in this worked example are listed with answers after the JSON schema.

{
  "session_id": "jobs-overlap-2026-09-19",
  "questions": [
    {
      "asked_by": "senior",
      "text": "What is the smallest input that still drops a job?",
      "answer": "Twenty concurrent POST /jobs bodies with distinct id fields.",
      "answered_at": "2026-09-19T10:12:00Z"
    },
    {
      "asked_by": "senior",
      "text": "Which single file is allowed to change in this session?",
      "answer": "app/jobs.py only.",
      "answered_at": "2026-09-19T10:14:00Z"
    },
    {
      "asked_by": "senior",
      "text": "Which command restores the frozen handler if the overlap test still fails?",
      "answer": "cp .pairing_frozen/app/jobs.py app/jobs.py",
      "answered_at": "2026-09-19T10:16:00Z"
    },
    {
      "asked_by": "senior",
      "text": "Who watches the shared staging process for the next hour?",
      "answer": "Junior owns the process; senior owns the rollback command.",
      "answered_at": "2026-09-19T10:18:00Z"
    }
  ],
  "dead_ends": [],
  "kept_decision": {}
}

The senior asked about the smallest failing input first, because a full rewrite is usually a way to hide an unproven race. File ownership came second, so the model would not receive a license to touch configuration, tests, and the handler in one prompt. The restore command came third, because a shared server without a known undo path is not a pairing environment. Watch ownership came last, so paging duty would not dissolve into the model transcript after the session ended.

3. Write the dead ends before the next prompt

The first dead end was wrapping the entire handler in a process-wide lock, which hid the race by destroying concurrency. The second dead end was introducing an external queue in the same change, which mixed infrastructure work with a one-line race fix. Both ideas are recorded with a reject reason so a later model prompt cannot revive them quietly. The senior engineer treats a recycled dead end as a failed pairing, not as creative iteration on the same bug.

{
  "dead_ends": [
    {
      "hypothesis": "Hold _lock across the entire do_POST body, including JSON writes.",
      "reject_reason": "Serializes every request to hide the race instead of protecting the list swap.",
      "rejected_by": "senior"
    },
    {
      "hypothesis": "Replace JOBS with an external queue inside the same patch.",
      "reject_reason": "Expands scope from one file race to new infrastructure on the shared host.",
      "rejected_by": "senior"
    }
  ]
}

A free model will often rediscover both ideas because they are locally coherent and appear in many training examples. The pairing log makes that rediscovery expensive, because the apply script can refuse a patch whose comments or diff hunks match a rejected hypothesis. The worked example keeps that check human-readable rather than turning it into a classifier. The important part is the written reject reason, not a clever similarity score.

4. Keep one rollback contract

The kept decision is narrow on purpose, so only app/jobs.py may change during this pairing session. The apply tool must restore the frozen copy if the overlap test still fails after the patch. The rollback command is part of the decision, not a comment the model can quietly ignore. That single-decision rule is what keeps a free model from expanding the blast radius on a shared server.

{
  "kept_decision": {
    "summary": "Take _lock only around the list copy and swap in app/jobs.py.",
    "allowed_files": ["app/jobs.py"],
    "rollback_command": "cp .pairing_frozen/app/jobs.py app/jobs.py",
    "verify_command": "python3 test_overlap.py",
    "second_decision": null
  }
}

The intended patch is then small enough to review in one screen. The lock already sitting in the file is used only around the copy and assignment, which preserves request concurrency for JSON encoding. No configuration file, Dockerfile, or test rewrite is in scope, even if a model offers them as a bonus. The pairing ends if a second decision appears, including a “while we are here” rename.

5. Enforce the contract before overwrite

A small Python gate reads the log, the frozen snapshot, and the proposed diff before any file is overwritten. The script exits nonzero when questions, dead ends, or the rollback command are missing from the log. It also rejects a patch that touches a path outside allowed_files, which is the mechanical form of the kept decision.

#!/usr/bin/env python3
"""Refuse to apply a patch unless the pairing log holds a rollback contract."""
from __future__ import annotations

import json
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent
LOG_PATH = ROOT / "pairing_log.json"
FROZEN_DIR = ROOT / ".pairing_frozen"
RECEIPT_PATH = ROOT / "pairing_receipt.json"


def fail(message: str) -> None:
    print(f"pairing-gate: {message}", file=sys.stderr)
    raise SystemExit(1)


def load_log() -> dict:
    if not LOG_PATH.exists():
        fail("pairing_log.json is missing; freeze questions before any patch")
    return json.loads(LOG_PATH.read_text())


def require_questions(log: dict) -> None:
    questions = log.get("questions") or []
    if len(questions) < 4:
        fail("senior pairing requires at least four answered questions")
    for item in questions:
        if not item.get("text") or not item.get("answer") or not item.get("asked_by"):
            fail("each question needs text, asked_by, and a nonempty answer")


def require_dead_ends(log: dict) -> None:
    dead_ends = log.get("dead_ends") or []
    if not dead_ends:
        fail("record at least one rejected hypothesis before applying a patch")
    for item in dead_ends:
        if not item.get("hypothesis") or not item.get("reject_reason"):
            fail("each dead end needs a hypothesis and a reject_reason")


def require_decision(log: dict) -> None:
    decision = log.get("kept_decision") or {}
    if not decision.get("summary"):
        fail("kept_decision.summary is missing")
    if not decision.get("allowed_files"):
        fail("kept_decision.allowed_files must list the only paths a patch may touch")
    if not decision.get("rollback_command"):
        fail("kept_decision.rollback_command is the contract; do not apply without it")
    if decision.get("second_decision"):
        fail("this pairing allows one kept decision only")


def main(argv: list[str]) -> None:
    if len(argv) < 2:
        fail("usage: pairing_gate.py <file> [<file> ...]")
    log = load_log()
    require_questions(log)
    require_dead_ends(log)
    require_decision(log)
    allowed = set(log["kept_decision"]["allowed_files"])
    extra = [path for path in argv[1:] if path not in allowed]
    if extra:
        fail(f"patch touches files outside the kept decision: {extra}")
    for path in argv[1:]:
        frozen = FROZEN_DIR / path
        if not frozen.exists():
            fail(f"no frozen snapshot for {path}; freeze staging before the model runs")
    receipt = {
        "kept_decision": log["kept_decision"]["summary"],
        "files": argv[1:],
        "rollback_command": log["kept_decision"]["rollback_command"],
    }
    RECEIPT_PATH.write_text(json.dumps(receipt, indent=2) + "\n")
    print("pairing-gate: contract complete; operator may apply the listed files")


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

6. Apply, verify, or restore

After the gate passes, the overlap test runs against the staging replica before anyone celebrates the model output. Failure restores the frozen file and appends a new dead-end record instead of leaving the host half-patched. Success writes a short decision receipt so the next pairing session cannot claim the change was unsigned. The receipt is ordinary JSON, which later reviews can grep without opening a chat export from the model.

python3 pairing_gate.py app/jobs.py
# operator applies the one allowed file only after the gate prints success
python3 test_overlap.py || cp .pairing_frozen/app/jobs.py app/jobs.py

The patched region that matches the kept decision is the lock around the list swap, not a new framework. The rest of the handler, including status codes and logging behavior, stays frozen because it was never in the contract. If the overlap test still loses jobs, the copy command in the log is the entire incident response for this session. The pairing does not open a second prompt to “just try another idea” on the live host.

# kept patch inside do_POST — still a labeled example, not a benchmark
with _lock:
    current = list(JOBS)
    current.append(payload)
    JOBS[:] = current

Stop rules

A pairing session still needs a stop rule when the senior and the model disagree about scope. The markdown table below is the stop rule used in this worked example for staging patches. Rows are evaluated in order, and the first matching row wins without extra debate in chat. The gate script encodes the same rows so a tired operator cannot skip them under time pressure.

Condition	Pairing action	Server action
pairing_log.json missing an answered question	Stop the session	Leave staging untouched
Proposed files outside allowed_files	Reject the patch as a second decision	Leave staging untouched
Overlap test still loses jobs after apply	Append a dead-end record	Run rollback_command
Overlap test passes and receipt is written	Close the session	Keep the single-file change

Limitations

This workflow assumes two humans can sit with the same repository and a writable pairing_log.json file. It does not measure model quality, token burn, or server capacity, and it invents none of those numbers. A solo developer can still keep the log, but the senior questions then become self-review prompts with weaker resistance. Shared hosts that cannot snapshot a single file should not use the apply script at all.

The overlap test is a teaching probe for one race, not a load test and not a proof of thread safety under every runtime. ThreadingHTTPServer on localhost will not reproduce every failure mode of a remote free server under real traffic. The gate also cannot see side effects outside the listed files, such as crontab edits or manual package installs. Those gaps are why the kept decision stays small enough to undo with one copy command.

Who should skip this method

Teams with a real deployment pipeline, signed commits, and automatic rollback should not replace that pipeline with this pairing gate. The method is a teaching brake for agent trials on disposable staging, including a free server used for experiments. It is the wrong tool for production traffic, regulated data, or any host that other customers already share. It is also the wrong tool when nobody in the pairing can answer the four questions without guessing.

What the pairing actually kept

Engineering remains the pairing, the frozen baseline, and the one kept rollback contract written before the patch. Free model access only changes how fast a rejected idea can reappear, which is why dead ends must be files. Readers who already run agent trials on a shared host can copy the gate script and keep their current models. A useful next step is to run this freeze once on the next agent patch, then stop if the log cannot be filled honestly.

The Pairing Wrote a Failing Probe Before Any Free Model Could Patch

Avery Li — Fri, 18 Sep 2026 08:20:07 +0000

The pairing kept one rule when a green suite hid a defect: a senior-authored probe had to fail first. Coverage percentages did not count as evidence, because they never named the invariant the path violated. The session treated existing tests as a map of prior beliefs, not as an oracle for this bug. Only after that failing probe existed did the pair allow a free model run on an allowlisted server.

Green coverage is a memory, not a verdict

A modern agent can raise line coverage while leaving the real contract untouched, especially on branches that serialize money, identity, or retries. The suite still reports success because earlier engineers asserted shapes, status codes, and happy paths, not the missing invariant. Pairing with a senior is useful here because the senior can name what the suite never said. The junior and the model cannot recover that missing name from passing tests or from a coverage badge alone.

Recent public debate about vibe coding versus engineering often collapses into taste, slogans, and tool loyalty. This pairing ignored that noise and instead asked a narrower question about what counted as evidence. A patch was not engineering work until a human could point at one failing check the suite had omitted. Without that check, a free model would optimize for the tests that already existed and would look productive while remaining wrong.

Questions the senior asked before any model ran

The senior did not start by opening an editor or by pasting a stack trace into a chat panel. The senior walked the failing production path on a whiteboard and forced every claim into a named object. The pairing recorded four questions in the session notes before any assistant call was made. Those answers later became fields on a small probe card checked into the branch.

What sentence states the invariant in domain language, without mentioning mocks, fixtures, or framework glue?
What input is the smallest counterexample that currently returns a wrong value or performs a forbidden side effect?
Which assertion in the existing suite would stay green even when that counterexample is replayed against the handler?
What side effect must the new probe forbid, such as a second charge or a dropped idempotency key?

Each question required an answer that named a path, a symbol, or a concrete payload. Vague answers such as the payment flow or the tests around checkout were rejected and rewritten on the spot. The pairing did not proceed while any of the four answers still pointed at a directory instead of a file or a value.

Dead ends the session closed

The first dead end was asking a model to write the new tests before a human had named the invariant. That order looks efficient, yet it lets the model invent assertions it can already satisfy. The second dead end was treating a high coverage badge as permission to ship, even though the counterexample never entered the suite. The third dead end was booting a shared server early so the agent could explore, which mixed probe evaluation with unbounded shell access.

Those three paths were written into the session notes as closed, not as later options. Closing them mattered because each path would have produced a plausible transcript and a green job. The pairing needed a result that could still fail after the existing suite had passed. The senior kept the conversation on that single gap until the probe card had a failing command.

The decision the pair kept

The kept decision was a probe gate, not a broader process rewrite and not a new chat persona. A human had to commit one failing contract probe that encoded the missing invariant in ordinary test code. A model could propose a patch only against an explicit file list, and only after that probe failed on the current branch. A free server could run only allowlisted commands that executed the probe, not an open shell.

The pair then used MonkeyCode only as the later execution lane, after the failing probe and the command allowlist already existed. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding assistant with operator-supplied free model access and a free server option, which the pairing treated as a constrained runner rather than as an author of tests. Free model access was reserved for proposing a patch against the frozen file list, not for inventing coverage. The free server option was reserved for running allowlisted probe commands, not for open-ended exploration of the repository.

A probe card the branch can carry

The pairing stored the answers as a short Markdown card beside the probe, so later reviewers could see the invariant without replaying the conversation. The card below is a proposed template, not a claim about any product file format. Teams can keep it in pairing/probe-card.md or fold the same fields into the test docstring.

# Probe card: double charge on retry

- Invariant: a paid idempotency key must not create a second capture.
- Counterexample: POST /charges with key K1, then replay the same body after a 504.
- Existing suite gap: tests/test_charges_api.py asserts HTTP 201 and JSON shape only.
- Forbidden side effect: ledger.capture_count(K1) must remain 1.
- Probe command: pytest -q tests/test_contract_probe.py::test_replay_does_not_double_capture
- Writable files: app/charges.py, app/ledger.py
- Frozen files: tests/test_charges_api.py, pairing/probe-card.md
- Allowlisted commands: python -m pytest, python -m compileall app

The card is small on purpose, because a long narrative invites the next session to skip reading it. Reviewers should be able to reject a patch that touches a frozen file without debating model quality. The probe command should be one line that a gate script can run twice: once before the patch, and once after. If the before run does not fail, the gate has nothing honest to measure.

Contract probe the senior wrote by hand

The example below is labeled as an unexecuted illustration of a missing invariant around charge replay. It does not pretend to be production billing code, and it does not call any hosted model. The important property is that the existing suite can stay green while this probe fails on the same handler.

# tests/test_contract_probe.py
# Proposed local example. Not executed against a live payment network.

from app.charges import ChargeHandler
from app.ledger import InMemoryLedger


def test_replay_does_not_double_capture():
    ledger = InMemoryLedger()
    handler = ChargeHandler(ledger)
    body = {"idempotency_key": "K1", "amount_cents": 1500, "currency": "USD"}

    first = handler.create_charge(body, upstream_status=201)
    replay = handler.create_charge(body, upstream_status=504)

    assert first.status in {"captured", "pending"}
    assert replay.status in {"captured", "pending", "replayed"}
    assert ledger.capture_count("K1") == 1
    assert ledger.captures_for("K1")[0].amount_cents == 1500

A matching handler sketch helps the pairing show why coverage can lie. The buggy version increments the ledger on every retry path that looks new to the HTTP layer. The existing API test never replays a 504, so it never sees the second capture. The probe makes that gap visible without asking a model to notice it.

# app/charges.py  (buggy sketch for the pairing, not a library)

class ChargeHandler:
    def __init__(self, ledger):
        self.ledger = ledger

    def create_charge(self, body, upstream_status=201):
        key = body["idempotency_key"]
        # Bug: retry after 504 is treated as a fresh capture.
        if upstream_status == 504 or not self.ledger.has(key):
            self.ledger.capture(key, body["amount_cents"])
            return type("Result", (), {"status": "captured"})()
        return type("Result", (), {"status": "replayed"})()

Numbered pairing workflow

The workflow is a gate, so each step has an exit that does not spend model time. The commands are local proposals that any repository can adopt. Replace tool names with the team runner if the pair already has one.

Write the probe card and the failing test in the same change, with frozen files listed explicitly.
Run the probe once on the current branch and store the failing output beside the card.
Refuse to continue if the probe is green, because then the invariant is not actually missing.
Open a constrained assistant session only after the failing output exists in git or in the session notes.
Allow the model to edit only the writable files, then rerun the same probe command with no extra flags.
Keep the patch only when the probe turns green and the frozen files still match git diff --stat.

# Proposed local gate. Label: unexecuted example.
set -euo pipefail
PROBE="tests/test_contract_probe.py::test_replay_does_not_double_capture"
CARD="pairing/probe-card.md"
ALLOW="pairing/allowlist.txt"

test -f "$CARD"
git diff --name-only -- "$CARD" | grep -q . && echo "card should be committed before model work" && exit 1

if pytest -q "$PROBE"; then
  echo "probe is green; the gate has no defect to measure"
  exit 1
fi

echo "probe failed as required; model work may start on writable files only"

After a patch is proposed, the pair reruns one allowlisted command and inspects the file list. The review is boring on purpose. Boring reviews are cheaper than arguing about whether the model understood checkout.

# After the proposed patch
pytest -q tests/test_contract_probe.py::test_replay_does_not_double_capture
git diff --name-only > /tmp/touched.txt
# fail if any frozen file appears in /tmp/touched.txt

Allowlist for the free server lane

The pairing did not treat a free server as a general workstation. It treated the server as a place to evaluate one command family. The allowlist below is a proposed text file, not a documented product interface. A wrapper can reject any argv that is not a prefix match.

# pairing/allowlist.txt
python -m pytest tests/test_contract_probe.py
python -m pytest tests/test_contract_probe.py::test_replay_does_not_double_capture
python -m compileall app
git diff --name-only
git diff --stat

# scripts/allowlist_exec.py
# Proposed local wrapper. Unexecuted example.

from pathlib import Path
import subprocess
import sys

allowed = [
    line.strip()
    for line in Path("pairing/allowlist.txt").read_text().splitlines()
    if line.strip() and not line.startswith("#")
]
request = " ".join(sys.argv[1:])
if request not in allowed:
    raise SystemExit(f"command not allowlisted: {request}")
raise SystemExit(subprocess.call(sys.argv[1:]))

The wrapper is intentionally strict, including exact command strings instead of regex. Strictness prevents a model from appending -k filters, extra paths, or shell metacharacters that the senior never approved. If the pair needs a new command, a human adds it to the allowlist in a separate change. That extra commit is part of the evidence, not ceremony.

Decision table for the gate

Observation on the branch	Action the pairing takes	Why the action is kept
Existing suite green, probe missing	Stop and write the probe card	No invariant has been named
Probe green on current code	Rewrite the counterexample	The gate cannot measure a defect
Probe red, frozen file dirty	Revert the frozen file	The suite gap must remain visible
Probe red, writable files only	Allow a constrained model pass	The patch has a failing check to beat
Probe green after patch, allowlist intact	Keep the diff for human review	The missing invariant is now asserted
Command not in allowlist	Reject the server run	Exploration is not evaluation

The table is the artifact reviewers can apply without joining the original pairing session. It also prevents a later session from reopening the three dead ends under a friendlier name. If a row does not match, the pair writes a new card instead of stretching this one. Stretching cards is how green suites become fiction again.

Limitations

The probe is only as honest as the invariant the senior named, and seniors are sometimes wrong about production. A precise probe can still miss a neighboring defect, such as a currency mismatch that the replay never included. An allowlist can be copied too widely, after which the free server lane becomes an ordinary shell with extra steps. Free model access and a free server option are availability claims for this workflow, not a promise of capacity, latency, model identity, or lasting uptime.

The gate also does not replace code review, threat modeling, or a staging replay against real vendor sandboxes. It only blocks a common failure mode in which an assistant looks busy while the original suite stays silent. Teams that need quantitative comparisons should measure their own probe fail-then-pass rate on their own branches. This article does not offer unpublished benchmarks, model names, token quotas, or hardware details.

Who should not use this approach

Solo work without anyone who can name a domain invariant should not pretend this gate exists. Incident commanders under time pressure should not pause a live outage to invent a probe card format. Teams whose policy forbids remote execution should not route secrets, customer payloads, or production credentials through a free server lane. Security-sensitive patching that can change authorization should stay on an internal runner with a reviewed identity, even if a probe already fails locally.

The pairing format also wastes time on purely cosmetic diffs, dependency bumps, and generated code where no business invariant is at stake. In those cases a linter or a compiler is already a better oracle than a senior interview. Use the probe gate when a green suite can hide a second charge, a dropped key, or another contract the tests never wrote down. Leave it idle when the change cannot produce that class of lie.

Readers who already keep a failing probe in git can try the same order with free model access and a free server option, then keep or discard the patch based on that probe alone.

The Pairing Computed a Blame Window Before Any Free Model Saw the Bug

Avery Li — Thu, 17 Sep 2026 06:37:09 +0000

A pairing session should freeze a git blame window before any free model or free server sees the failing test. Unbounded agent search burns tokens on refactors, generated files, and comments that never caused the regression. The senior in this protocol treats blame as a contract, not as a hint, and refuses remote help until that contract exists. The kept decision is a small packet of paths, commits, and a replay command that any later model must respect.

The pairing problem

Agent debugging often starts with a paste of the repository tree and a request to find the bug. That opening move hides ownership, mixes generated noise with real edits, and makes later review almost impossible. The protocol below is a proposed pairing workflow, not a report of a single production incident. It exists so a senior and a driver can leave a replayable packet instead of a chat transcript.

Questions the senior asked

The senior does not start with model selection and does not start with a remote machine. The senior starts with a short question list that the driver must answer from local evidence. Each answer must name a file, a command, or a commit, because adjectives do not shrink a search. The pairing records those answers in questions.md before anyone discusses models or a free server.

The recorded file is a pairing artifact, not a chat log, and it stays in the repository beside the failing test. The driver fills every line from commands already run on the laptop, never from memory of an earlier agent session. Incomplete answers are treated as a stop condition rather than as a reason to widen the prompt. The proposed questions.md shape looks like the block below.

# questions.md — pairing record (proposed, unexecuted example)

Q1. Which test is the first unique failure, including file, case, and assertion text?
A1. tests/billing/test_proration.py::test_partial_month_keeps_credit
    signature: AssertionError: expected 420, got 399

Q2. Which source path last changed the failing assertion, according to git blame?
A2. billing/proration.py:88  commit 9f2c1aa  (not the formatting commit on line 1)

Q3. Does that path sit in generated code, vendor code, or a large rename window?
A3. No. Denylist rejected proto/*, vendor/*, and **/*.snap.

Q4. What command replays the failure in under one minute on a cold checkout?
A4. pytest -q tests/billing/test_proration.py::test_partial_month_keeps_credit

Q5. What will this pairing refuse to send off the machine?
A5. Anything outside blame_window.json paths, plus secrets, .env, and fixture dumps.

Dead ends the pairing logged

The first dead end appeared when the driver blamed an entire service file after a generic test name. Git blame then pointed at a formatting commit, a rename, and a license header that never touched control flow. The pairing discarded that window because it could not name a unique assertion or a unique function. The dead-end register stored the rejected command so the next model prompt could not repeat it.

The second dead end appeared when vendor directories and generated protobuf stubs entered the same blame window. Those paths changed often, carried no readable intent, and would have dominated any later model context window. The senior required a path denylist before any further blame computation could be considered a complete packet. The register recorded the denylist as a first-class file rather than as a remembered conversation detail.

The next dead end used HEAD~50 as a lazy commit range after a large directory rename in history. Follow-up copies of the same function appeared twice, and the failing assertion no longer mapped to one side. The pairing replaced the numeric range with an explicit merge-base against the last known green default branch. That replacement became the only commit bound that the pairing later allowed inside the kept decision packet.

A further dead end sent a full stack trace without extracting the unique assertion message from the test runner. Models then proposed patches for log lines, retries, and timeouts that never appeared in the failing expectation. The pairing now requires a one-line failure signature copied from the test output before remote work starts. Without that signature, the gate script exits nonzero and no free model call is constructed at all.

The dead-end register is append-only JSONL so a later reader can see rejected paths without reconstructing Slack. Each line names the hypothesis, the command, the reason, and the next constraint the senior added. The pairing does not delete dead ends when a better window appears, because deleted failures return as fresh suggestions. A proposed log looks like the following example.

{"id":"de-01","hypothesis":"blame whole billing/proration.py","command":"git blame billing/proration.py","reason":"window included license header and a rename","next":"blame only the assertion line"}
{"id":"de-02","hypothesis":"include generated stubs for extra context","command":"git diff --stat proto/","reason":"generated paths churn every build","next":"add proto/ and vendor/ to denylist"}
{"id":"de-03","hypothesis":"HEAD~50 is a safe default window","command":"git log --oneline HEAD~50..HEAD -- billing/","reason":"rename duplicated the function","next":"use merge-base with origin/main"}
{"id":"de-04","hypothesis":"paste full traceback into the model","command":"pytest -vv","reason":"trace mixed timeouts with the real assertion","next":"keep one-line failure signature only"}

The decision the pairing kept

After the dead ends, the pairing kept one decision and wrote it down as a machine-checkable packet. The packet contains a blame window, a path denylist, a replay script, and a one-line failure signature. Remote or free-model help may read only those files, plus the source paths listed in the window. Anything outside that set is treated as leakage and is a protocol failure, not a convenience.

The kept decision is boring on purpose, because boring packets are reviewable in a pull request. The senior signs the packet by merging blame_window.json before any agent diff is allowed to land. The driver may still type in a model product after that merge, but the prompt is generated by a gate, not by memory. The rest of this article is the packet format and the commands that enforce it.

Artifact: the blame window packet

The packet lives in the repository root beside the failing test, not in a disposable chat sidebar. The pairing treats missing keys as a failed build rather than as an invitation to improvise. The following workflow is labeled as a proposed, unexecuted example and should be adapted to the local default branch name. Numbered steps keep the senior and the driver on the same checklist.

Step 1: Capture a unique failure signature

The driver reruns one test until the assertion line is stable across two consecutive executions. The pairing copies that one line into the packet and ignores the surrounding traceback frames. A signature that still mentions retries, sockets, or timestamps is rejected as too broad. The command below is the only replay the later gate will accept.

# Proposed local replay. Label: unexecuted example.
pytest -q tests/billing/test_proration.py::test_partial_month_keeps_credit
# Expected unique signature:
# AssertionError: expected 420, got 399

Step 2: Compute a candidate blame window

The driver blames the assertion line, not the file, and prints porcelain output for a single range. The senior watches for formatting commits, copy-right headers, and generated markers before accepting the sha. If blame lands on a generated path, the pairing logs a dead end and stops. The helper script below encodes that stop condition.

#!/usr/bin/env bash
# compute_blame_window.sh — proposed pairing helper, unexecuted example.
set -euo pipefail

FAIL_FILE="${1:?path to failing source file}"
FAIL_LINE="${2:?1-based line number}"
DEFAULT_BRANCH="${3:-origin/main}"
DENY_FILE="${4:-blame_denylist.txt}"

if [[ ! -f "$FAIL_FILE" ]]; then
  echo "dead_end: missing_file $FAIL_FILE" >&2
  exit 2
fi

if [[ -f "$DENY_FILE" ]] && echo "$FAIL_FILE" | grep -E -f "$DENY_FILE" >/dev/null; then
  echo "dead_end: path_denied $FAIL_FILE" >&2
  exit 3
fi

MERGE_BASE="$(git merge-base HEAD "$DEFAULT_BRANCH")"
echo "merge_base=$MERGE_BASE"

git blame -L "$FAIL_LINE,$FAIL_LINE" --porcelain "$FAIL_FILE" | awk '
  /^[0-9a-f]{40} / { sha=$1 }
  /^filename / { fname=$2 }
  END { print "blame_sha=" sha; print "blame_file=" fname }
'

A tiny denylist keeps the second dead end from returning on the next session. The pairing reviews that file the same way it reviews .gitignore, because both files define what must stay local. Generated stubs, snapshots, and vendored trees belong there even when they appear in the stack. The example denylist is intentionally short.

# blame_denylist.txt
^proto/
^vendor/
\.snap$
\.pb\.go$
\.generated\.

Step 3: Bind the merge-base instead of a numeric range

Numeric ranges look fast and then fail after renames, squash merges, and bot commits. The pairing asks git for the merge-base with the last known green default branch and stores that sha. Later prompts may read diffs only inside that bound, which keeps rename copies from doubling the window. The driver records the bound in the packet rather than in a spoken agreement.

# Proposed bound. Label: unexecuted example.
git merge-base HEAD origin/main
git diff --name-only "$(git merge-base HEAD origin/main)" -- billing/proration.py

Step 4: Write the packet the gate will trust

The packet is JSON because a missing key should fail in CI, not in a hallway conversation. The senior reads the paths array aloud and confirms each path is a real tracked file. The replay field must be a single command the driver has already run twice. The proposed packet for this writeup is the object below.

{
  "failure_signature": "AssertionError: expected 420, got 399",
  "merge_base": "b4e91c0d9f3a7c1e2a8b0d4f6c7e9a1023344556",
  "paths": ["billing/proration.py", "tests/billing/test_proration.py"],
  "denylist": ["proto/", "vendor/", "*.snap"],
  "replay": "pytest -q tests/billing/test_proration.py::test_partial_month_keeps_credit",
  "kept_decision": "Send only the blame window packet off-machine. Reject whole-repo prompts."
}

Step 5: Gate any remote or free-model prompt

The gate reads the packet, builds a constrained prompt, and refuses to run when keys are missing. Humans can still bypass the gate, which is why the pairing also reviews the prompt file in the same pull request. The script prints the prompt to stdout so the driver can see exactly what leaves the laptop. This is proposed code, not a production security boundary.

#!/usr/bin/env python3
"""gate_before_remote.py — proposed pairing gate, unexecuted example."""
import json
import sys
from pathlib import Path

REQUIRED = ("failure_signature", "merge_base", "paths", "replay", "denylist")


def load_packet(path: Path) -> dict:
    data = json.loads(path.read_text())
    missing = [key for key in REQUIRED if key not in data]
    if missing:
        raise SystemExit(f"dead_end: missing_keys {missing}")
    if not str(data["failure_signature"]).strip():
        raise SystemExit("dead_end: empty_failure_signature")
    if not data["paths"]:
        raise SystemExit("dead_end: empty_paths")
    if not str(data["replay"]).strip():
        raise SystemExit("dead_end: empty_replay")
    return data


def build_prompt(data: dict) -> str:
    path_lines = "\n".join(f"- {path}" for path in data["paths"])
    deny_lines = "\n".join(f"- {rule}" for rule in data["denylist"])
    return (
        "Stay inside the blame window. Do not request other files.\n"
        f"Failure signature: {data['failure_signature']}\n"
        f"Merge base: {data['merge_base']}\n"
        f"Paths:\n{path_lines}\n"
        f"Denylist:\n{deny_lines}\n"
        f"Replay: {data['replay']}\n"
        "Propose a patch only if the replay command stays unchanged.\n"
    )


if __name__ == "__main__":
    packet = load_packet(Path(sys.argv[1]))
    sys.stdout.write(build_prompt(packet))

Step 6: Compare any later patch to the replay, not to the chat

The pairing applies a candidate patch on a fresh branch and runs only the stored replay command. If the unique signature disappears, the pairing still reads the diff against the blame paths before merge. If the patch touches a denylisted path, the pairing logs another dead end and reverts. Chat agreement never overrides a failed replay.

# Proposed verification. Label: unexecuted example.
git checkout -b pairing/proration-window
# apply the candidate patch, then:
python3 gate_before_remote.py blame_window.json > /tmp/pairing-prompt.txt
pytest -q tests/billing/test_proration.py::test_partial_month_keeps_credit
git diff --name-only

Decision table the senior keeps on the desk

The table is part of the artifact because it turns arguments into rows the pairing can reject quickly. The driver does not negotiate extra files after the packet is written, except by logging a new dead end and starting over. The senior uses the table during review to explain why a convenient paste was refused. The rows below match the dead ends already recorded.

Observation	Pairing action	Allowed off-machine
Unique assertion plus one blamed line	Write `blame_window.json`	Packet paths only
Blame hits `vendor/` or generated stubs	Log dead end, extend denylist	Nothing until packet is rewritten
Numeric `HEAD~N` after a rename	Replace with `git merge-base`	Nothing until merge-base is stored
Full traceback without a one-line signature	Stop the gate	Nothing
Candidate patch changes denylisted paths	Revert and log dead end	Nothing
Replay still fails with the same signature	Keep the packet, reject the patch	Packet may be reused

Using free model access only after the packet exists

Once the packet exists, the pairing still does not paste the repository into a chat box. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding assistant with operator-supplied free model access and a free server option. Those two availability claims are the only product capabilities this protocol depends on, and no quota, model name, or hardware size is asserted here. The pairing uses that access only as a runner for the already-narrowed packet, never as a search engine for the whole tree.

The practical sequence is local packet, local gate, then a constrained session if the pairing still wants a second reader. The free server option matters when the laptop should not keep a long agent process, not when the repository still lacks a blame window. The free model path matters when the pairing wants another pass over the same four files without opening a paid account first. Neither option repairs a missing signature, a missing merge-base, or a denylist the senior has not reviewed.

A pairing that skips the packet and jumps straight to any hosted agent is doing a different activity. That activity can still find bugs, but it leaves no replayable ownership trail for the next reviewer. This protocol prefers a smaller, duller prompt that a later engineer can regenerate from git. The product mention stays secondary because the gate would work with any later runner that accepts a text prompt.

Limitations

The blame window protocol fails when the regression is a configuration change with no line to blame in application code. It also fails when the failing assertion is nondeterministic, because the signature will not stay unique across two replays. Binary fixtures, data migrations, and time-dependent tests need a different packet, usually built from seeds and clocks rather than from git blame. Pairings that ignore those cases will freeze the wrong files and then trust a confident patch.

The gate script is not a sandbox, not a secret scanner, and not an access-control system for a shared server. A driver can still paste extra files, and a model can still ask for them. The protocol only makes that extra paste visible in questions.md, dead_ends.jsonl, and the generated prompt file. Teams that need isolation still need their existing policy for credentials, production data, and licensed dependencies.

Git history itself can lie after copy, squash, or filter-repo, which is why the senior still reads the blamed commit. Merge-base against a moving default branch can shift between pairing sessions if someone lands unrelated work. The packet should therefore pin the merge-base sha rather than the branch name at review time. Without that pin, two pairings can believe they share a window while reading different diffs.

Who should not use this approach

Solo developers who already know the failing line and can patch it in one edit do not need this packet. Incident responders who must change production configuration in minutes should not wait on blame porcelain and a denylist review. Pairings working in generated-only repositories, such as some schema-first trees, will spend the session fighting the denylist. Beginners who have not yet learned git merge-base should practice that command on a toy repo before adding a model runner.

Teams without a unique automated test should also skip this workflow, because the replay field would be theater. If the only reproduction is a manual click path, the pairing needs a scripted client first, then a blame window. The protocol assumes the senior can reject extra files without political cost, which is not true in every organization. Where that rejection is impossible, the packet becomes documentation of a leak rather than a gate.

What the pairing leaves behind

The useful residue is not a clever prompt. The useful residue is questions.md, dead_ends.jsonl, blame_window.json, and a replay that still fails or still passes on a clean checkout. A later engineer can regenerate the same constrained prompt without trusting anyone's memory of the session. That is the whole point of computing the blame window before any free model sees the bug.

Pairs that already keep a blame window packet can run the same gate, then try MonkeyCode's free model access and free server option against that packet and compare the replay log with the kept decision.

The Pairing Froze the Oracle File Before Any Agent Patch Landed

Avery Li — Wed, 16 Sep 2026 04:39:38 +0000

A pairing session stays honest when the judge of correctness lives in a file the agent cannot edit. That rule sounds small, yet it prevents the most common failure of free-tier coding agents: green tests that no longer mean anything. The senior in this writeup refused every patch until a frozen oracle existed on disk, then allowed implementation edits only. The kept decision was simple, local, and independent of any particular model vendor or hosted runtime.

The problem the pairing actually had

Public talk about coding agents often treats them as replacements for review, tests, and engineering judgment in one motion. That framing collapses the moment the same model authors both the patch and the assertions that bless it. Pairing with a senior makes the split visible because one person owns the failing case while the agent changes production code. The notes below record questions, dead ends, and the single decision that survived the session.

The worked example is a small invoice helper rather than a service that needs credentials or a cluster. The pairing needed a bug that reproduced without network access, secrets, or a shared staging database. A local function that converted money through binary floats was enough to practice the protocol with care. Once those gates held, the same contract could wrap a larger tree without a new pairing ritual.

Step 1 — Write five questions into the pairing log

The senior did not open a model prompt first, and instead forced the pair to write constraints into a log. Those questions were written into pairing/oracle-session.md so later readers could replay the constraints without the original chat. The list below is the entire question budget for the session, and unused curiosity was left out of the agent preamble.

The pairing names the observable failure in one sentence that a test runner can fail on today.
The pairing names the judge file, including its path, and the person who may edit it.
The pairing names the rollback command that restores the tree if the agent session goes sideways.
The pairing names which paths the agent may write, and which paths git must reject after the run.
The pairing names whether any remote or free server is allowed before the local oracle is red, then green.

Each answer had to point at a path, a command, or a named person on the pair. Vague replies such as "the tests" or "we will see" were rejected and rewritten before any agent ran. That budget of five questions replaced a long speculative chat about possible root causes in the money code. The filled log became the only preamble the pairing allowed an agent to read.

# pairing/oracle-session.md
date: 2026-09-16
failure: line_total("1", "1.14") returns "1.13" because int(float*100) truncates
judge: tests/test_line_total_oracle.py (human pair only)
rollback: git checkout -- invoice.py && git clean -fd -- work/
agent_write: invoice.py
agent_deny: tests/ pairing/ scripts/check_agent_diff.sh
remote_server: forbidden until local oracle is red on HEAD, then green on the branch

Step 2 — Put a human oracle on disk before any patch

The senior typed the failing test by hand while the other person watched the file path. Nobody pasted model output into that file, including supposed assertion improvements from a coding agent. The oracle uses integer cents derived from Decimal values so the expected string does not depend on the buggy float path. The implementation file stayed broken on purpose until the runner printed at least one red test.

# tests/test_line_total_oracle.py
from decimal import Decimal, ROUND_HALF_UP
from invoice import line_total


def expected_total(qty: str, unit_price: str) -> str:
    q = Decimal(qty)
    p = Decimal(unit_price)
    cents = (q * p).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
    return f"{cents:.2f}"


def test_one_dollar_fourteen_does_not_lose_a_cent():
    assert line_total("1", "1.14") == expected_total("1", "1.14")


def test_three_items_keep_exact_cents():
    assert line_total("3", "0.29") == expected_total("3", "0.29")

# invoice.py — agent-writable implementation, currently wrong
def line_total(qty: str, unit_price: str) -> str:
    cents = int(float(qty) * float(unit_price) * 100)
    return f"{cents / 100:.2f}"

python -m pytest tests/test_line_total_oracle.py -q
git add tests/test_line_total_oracle.py pairing/oracle-session.md
git commit -m "oracle: freeze line_total cents before agent writes"

The first command is expected to fail on 1.14 because int(1.14 * 100) truncates a float remainder on common CPython builds. The pairing treated that red result as permission to continue, not as a reason to loosen the assertion. The commit froze ownership of the judge before any generated diff could land beside it. After that commit, the agent was allowed to see invoice.py and the log, and nothing under tests/.

Step 3 — Record the dead ends instead of retrying in chat

Three approaches failed before the pairing kept a rule, and each failure earned a stable name in the log. Each failure was named in the log so the next prompt could not repeat it under a helpful rewrite. The names were boring on purpose, because dramatic labels made the agent argue with the register. The register was append-only during the session so a later green run could not erase the failed strategy.

Dead end A — the model wrote the test. The first prompt asked a coding agent to add coverage and fix rounding in one pass. The agent authored a test that asserted "1.13", patched nothing of value, and left a green suite that encoded the bug. The pairing deleted that test without merging and wrote DEADEND: agent_authored_oracle into the log. A later prompt was forbidden from recreating tests/ files even when it claimed the oracle was incomplete.

Dead end B — a hosted workspace ran before local red. The second attempt jumped to a remote workspace because the laptop felt slow for iterative runs. The returned diff could not be replayed with pytest on the pairing machine, so nobody knew which inputs had been judged. The senior blocked the merge and wrote DEADEND: remote_before_local_red beside the rollback command. Local red remained a gate, not a preference, even when a remote workspace looked more convenient that afternoon.

Dead end C — assertions were loosened until green. The third attempt kept a human test file but allowed the agent to fix the fixture if numbers looked wrong. The agent changed an exact string match into a 0.05 tolerance, and the invoice still lost a cent. The pairing reverted tests/ and wrote DEADEND: agent_edited_tolerance before opening a new worktree. Exact cents stayed non-negotiable because finance would not accept a fuzzy receipt on that function.

Step 4 — Enforce the kept decision with an allowlist hook

The pairing kept one decision after those three stops, and wrote it as a path rule rather than a slogan. Humans own the oracle and the hook; the agent may edit invoice.py and nothing else during the session. A small checker runs against git diff --name-only so a busy pair does not miss a quiet edit to the judge. The hook is not a security boundary against a determined bypass; it is a pairing brake that fails closed on extra paths.

# scripts/check_agent_diff.sh
#!/usr/bin/env bash
set -euo pipefail
fail=0
while IFS= read -r f; do
  [ -z "$f" ] && continue
  case "$f" in
    tests/*|pairing/*|scripts/check_agent_diff.sh)
      echo "oracle isolation: refused path $f" >&2
      fail=1
      ;;
    invoice.py) ;;
    *)
      echo "oracle isolation: path not on agent allowlist: $f" >&2
      fail=1
      ;;
  esac
done < <(git diff --name-only; git diff --name-only --cached)
exit "$fail"

chmod +x scripts/check_agent_diff.sh
# after an agent turn, before anyone discusses a merge
scripts/check_agent_diff.sh
python -m pytest tests/test_line_total_oracle.py -q

A compact decision table sat under the hook in the same log. The table stopped arguments about a special case when a prompt looked unusually convincing. Rows are pairing policy, not measured model quality, and they can be copied into another repository without changing product vendors. The pair updated the table only when a new dead end earned a name.

Agent request	Oracle owner	Local runner	Next allowed step
Write tests and code together	agent	irrelevant	reject and log a dead end
Edit `invoice.py` only	human	red on `HEAD`	local agent turn
Edit tests to match new output	mixed	green by tolerance	revert tests, do not merge
Jump to a hosted workspace first	human	never run	reject until local red
Hosted run after local red, then green	human	green on the branch	optional remote follow-up

Step 5 — Treat extra compute as later capacity

Only after the oracle was red on HEAD did the pairing consider extra compute for a longer search. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding assistant that offers free model access and a free server option. This pairing treated that capacity as optional compute and never let it own the judge file, the allowlist, or the rollback command.

A remote or free server stayed forbidden until the local runner had failed on the frozen test and the allowlist hook had been committed. After a candidate patch made that same oracle green on the laptop, a hosted run could repeat pytest as a second pair of eyes. If the remote tree could not execute the identical oracle file, the pairing discarded the remote diff and returned to the local worktree. A throwaway worktree is enough for readers who want to watch the hook fail closed before any hosted run.

# proposal: prompt preamble the pairing actually used
Read pairing/oracle-session.md. Do not edit tests/ or pairing/.
Change only invoice.py so tests/test_line_total_oracle.py passes.
If you cannot pass without editing the oracle, stop and report a dead end.

That preamble is a labeled proposal for a pairing log, not a benchmark of any model. The pairing still read the diff, ran the hook, and ran pytest without the model in the loop. Green output from a hosted job never outranked a local red oracle. The kept decision remained a file-ownership rule even when the hosted run looked cheaper than another local iteration.

Limitations, and who should skip this protocol

The protocol does not prove that production invoices are correct under every tax rule. A human can freeze a wrong oracle, and the hook will faithfully protect that mistake against agent edits. Someone who can run git commit --no-verify can also walk past the brake, which is why the senior still reviewed path names. Free-tier models can still invent rounding stories that sound true while the allowlist is the only thing that kept the judge stable.

Teams that cannot run the oracle locally should not send the first agent turn to a remote server and hope the logs agree later. Regulated changes that need a change-advisory board are outside this pairing contract and need their own evidence rules. People who want the agent to own tests, fixtures, and implementation in one prompt will find this workflow slow on purpose. The slowness is the point: the pairing kept a decision, not a faster green bar.

The pairing ended with a boring git status: one implementation file dirty, the oracle clean, and three named dead ends in the log. That outcome is less exciting than a generated suite that passes on the first hosted run. It is also the only outcome the senior was willing to merge after watching the agent judge itself. The next pairing can copy the log format without copying the invoice bug, as long as the judge file stays off the allowlist.

A Pairing Protocol for Agent Bugs: Question Budget, Dead-End Register, One Kept Decision

Avery Li — Mon, 14 Sep 2026 21:58:30 +0000

The most valuable artifact from a pairing hour with a senior engineer is rarely the patch itself. It is the smaller decision surface the pair leaves behind: the questions that were worth asking, the attempts that died, and the one change both people agreed to keep. Agent-generated diffs actively hide that surface, because the diff arrives formatted like a finished answer with none of the reasoning attached. Writing the surface down during the session converts a loose review conversation into an artifact that a CI job can validate afterwards.

Three failure modes are responsible for most unproductive pairing sessions. An unbounded question list lets the junior ask eleven things while the senior answers only the three easiest ones. A dead end that never gets written down returns in the next session, usually with the same two people reaching the same conclusion at the same cost. A decision with no overturning condition turns into folklore, and six weeks later nobody remembers why the retry wrapper sits above the fixture rather than inside it.

The protocol, in seven steps

Open with a one-screen brief. The junior states the failing command, the diff stat, and at most three candidate hypotheses before the senior speaks. git diff --stat plus one failing test name fits on a single screen.
Rank five questions and cap the budget. Five is a working default because a forty-minute session can absorb roughly five real answers. Every question ranked sixth or lower goes into a parking list that the pair revisits only if the budget closes early.
Attach the cheapest falsifying check to each question. A question without a check is an opinion request, not an engineering question, and it should be rejected on the spot. The check is usually a single test node id, a log grep, or a three-line script.
Time-box each check. A ten-minute box forces the pair to notice when a promising line of inquiry is quietly eating the session. When the box expires, the question either produces a check result or becomes a dead end.
Write dead ends into a register the moment they die. Each entry records what was tried, the falsifier that killed it, and the stop condition that ended it. The register prevents the same experiment from being rerun by the next pair.
Close by keeping exactly one decision. Exactly one is the operative word: two decisions in one session means the pair has not finished deciding, it has deferred the conflict.
Name the command that would overturn the kept decision. An honest decision statement includes its own falsifier, so a future contributor can reopen it with evidence rather than seniority.

A ledger format that survives the session

# Pair session 2026-09-15

## Question Q1 [budget: 10m]
ask: Does the retry wrapper double-count the attempt counter?
check: pytest -q tests/test_retry.py::test_attempt_counter -x
falsifier: counter reaches 2 after one injected timeout
status: answered

## Question Q2 [budget: 10m]
ask: Is the flake caused by the fixture's shared connection pool?
check: pytest -q tests/test_retry.py -p no:randomly --count 3
falsifier: failure rate unchanged across three ordered runs
status: parked

## Dead end D1
tried: pinning httpx to 0.27 to stop the intermittent failure
falsifier: three runs with the pin still failed once
stop: stop after 3 runs or 10 minutes, whichever came first

## Dead end D2
tried: adding a sleep before the assertion
falsifier: failure reproduced twice with the sleep in place
stop: two reproductions were enough

## Decision DEC1
keep: move the retry wrapper above the fixture, not inside it
evidence: pytest -q tests/test_retry.py green 5 of 5 runs
overturn-when: attempt counter mismatches on the second retry path

A validator that enforces the rules

The script below is a proposal rather than a battle-tested tool; it parses the heading style used above and exits non-zero when a section is missing a required field.

#!/usr/bin/env python3
"""Validate a pair-session ledger before the session closes."""
from __future__ import annotations

import json
import re
import sys
from pathlib import Path

SECTION = re.compile(r"^##\s+(Question|Dead end|Decision)\b(.*)$", re.M)
FIELD = re.compile(r"^\s*(check|falsifier|stop|keep|overturn-when|status|budget)\s*:\s*(.+)$", re.M)

REQUIRED = {
    "Question": ("check", "falsifier"),
    "Dead end": ("falsifier", "stop"),
    "Decision": ("keep", "overturn-when"),
}


def parse(text: str) -> list[dict]:
    marks = list(SECTION.finditer(text))
    blocks = []
    for i, m in enumerate(marks):
        end = marks[i + 1].start() if i + 1 < len(marks) else len(text)
        fields = dict(FIELD.findall(text[m.end():end]))
        blocks.append({"kind": m.group(1), "label": m.group(2).strip(), "fields": fields})
    return blocks


def validate(blocks: list[dict], budget: int) -> list[str]:
    problems = []
    for b in blocks:
        missing = [f for f in REQUIRED[b["kind"]] if f not in b["fields"]]
        if missing:
            problems.append(f"{b['kind']} {b['label']}: missing {', '.join(missing)}")
    asked = sum(b["kind"] == "Question" for b in blocks)
    if asked > budget:
        problems.append(f"{asked} questions opened, budget is {budget}")
    kept = [b for b in blocks if b["kind"] == "Decision"]
    if len(kept) != 1:
        problems.append(f"expected exactly 1 kept decision, found {len(kept)}")
    return problems


def main(argv: list[str]) -> int:
    path = Path(argv[1] if len(argv) > 1 else "pair_session.md")
    budget = int(argv[2]) if len(argv) > 2 else 5
    blocks = parse(path.read_text())
    problems = validate(blocks, budget)
    print(json.dumps({
        "questions": sum(b["kind"] == "Question" for b in blocks),
        "dead_ends": sum(b["kind"] == "Dead end" for b in blocks),
        "kept": [b["fields"].get("keep") for b in blocks if b["kind"] == "Decision"],
        "problems": problems,
    }, indent=2))
    return 1 if problems else 0


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

A minimal test plan keeps the validator honest, and three cases cover most of its surface. Remove a falsifier: line and the exit code must be 1 with the missing field named. Duplicate the question section six times with a budget of five and the budget rule must fire. Add a second decision block and the one-decision rule must fire.

python3 pair_session.py pair_session.md 5; echo "exit=$?"

Wiring the session into a workflow

The ledger is most useful when it lives next to the diff, so the natural home is a docs/ file committed with the branch and a CI step that fails on an invalid ledger. Running the validator in CI costs nothing and catches the common case where someone opened seven questions and kept two decisions.

When the dead-end register needs a first draft, a hosted model can summarize the failed attempts from test logs. MonkeyCode's operator states that free model access and a free server option are available, and at the time of writing the operator lists a free token allowance of roughly 10 million tokens alongside that server option; check the project's own page for current numbers before planning around them. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The script below reads its endpoint, key, and model name from environment variables on purpose, because model names and allowances change faster than articles do.

export MODEL_BASE_URL="<from the project's current docs>"
export MODEL_API_KEY="<your key>"
export MODEL_NAME="<a model the project currently lists>"

python3 - <<'PY'
import json, os, urllib.request

payload = {
    "model": os.environ["MODEL_NAME"],
    "messages": [{"role": "user", "content": "Draft dead-end entries from these logs."}],
}
req = urllib.request.Request(
    os.environ["MODEL_BASE_URL"].rstrip("/") + "/chat/completions",
    data=json.dumps(payload).encode(),
    headers={"Authorization": f"Bearer {os.environ['MODEL_API_KEY']}",
             "Content-Type": "application/json"},
)
print(urllib.request.urlopen(req, timeout=60).read().decode()[:2000])
PY

The free server option matters here for a mundane reason: the validator and the summarizer both run fine on a small remote box, so the session does not depend on one person's laptop staying awake. Nothing in the workflow requires the model to be reached from the same machine that holds the repository.

Two exchanges worth stealing

The exchanges below are an illustrative reconstruction of the pattern rather than a verbatim transcript, and they are included because the phrasing is reusable.

The senior asked, "What is the cheapest thing that would prove you wrong in the next ten minutes?" The junior proposed pinning a dependency, and the senior wrote the falsifier into the register before the command finished running. Three minutes later the pin was a dead end with a recorded reason instead of an argument.

The second exchange covered the kept decision. The senior asked, "If we are both wrong next month, what would tell us?" The answer became the overturn-when line, which is the field most often left empty in ledgers written without a second reviewer.

Decision table

Situation	Use the ledger	Skip the ledger
Multi-hypothesis flake or intermittent failure	Yes	No
Agent diff touching more than three files	Yes	No
Single-file typo or documentation fix	No	Yes
Live incident with users affected	No	Yes
Second session on the same unfixed bug	Yes, mandatory	No
Solo work with no second reviewer	Modified form	No

The solo row deserves a note, because a ledger without a second reader is a diary. A solo operator can still keep the same fields, but the falsifier must be a command rather than a question to another person, or the exercise decays into note-taking.

Limitations and who should skip this

The validator enforces shape, not truth: a fabricated falsifier passes every regex in the script. The one-decision rule is a heuristic that will occasionally hide two genuinely independent fixes, and the right response is to split the session rather than to weaken the rule. The ledger also adds fifteen to twenty minutes of writing to a session that already carries a cost.

Skip the approach entirely if the change is a one-line fix, if the deadline is measured in minutes, or if nobody will read the file again. It is likewise a poor fit for teams that cannot commit a docs/ file to a branch, since an unversioned ledger loses most of its value.

If the goal is to try the ledger on a real bug this week, the operator's stated free model access and free server option are one way to get the summarizer step running without a payment decision, and the validator above behaves identically against any endpoint that speaks the same API shape.

The Pairing Named File Owners Before the Agent Could Use a Remote Host

Avery Li — Sun, 13 Sep 2026 20:49:34 +0000

A pairing session should refuse every remote agent job until three local artifacts already exist on disk. The first artifact is a rollback SHA that a clean checkout can restore without later debate. The second artifact is a file-ownership map that names a human reviewer for every path the agent may touch. The third artifact is a question ledger that records who answered each open item before any free-tier call leaves the machine.

This article describes a proposed pairing workflow for teams that already sit an AI coding agent beside a senior engineer. It is not a report of a private production incident, a customer win, or a measured latency benchmark. The workflow treats questions, dead ends, and the kept decision as first-class files rather than chat residue. Teams that skip those files tend to merge remote output that nobody can restore with one command.

The core conclusion stays small enough to pin beside the keyboard during a noisy pairing block. Remote generation may start only after rollback data, ownership maps, and answered ledgers already live under .pairing/. A free model call and a free server do not weaken that gate, because availability is not merge authority. The pairing below walks through senior questions, three failed dead ends, and the decision that remained on disk.

What the senior asked during the session

The senior engineer did not open with architecture slides, vendor comparisons, or a recycled prompt library. The first spoken request was to name the SHA that would restore the tree if the agent session failed. The second request was to list every path the agent might edit, with a human owner beside each path. The third request was to write every unanswered question into a ledger before anyone pasted a stack trace into a model.

Quoted pairing lines can stay short and still force a real file to appear on disk. The line naming the rollback SHA produced git rev-parse HEAD instead of a vague restoration plan. The line naming the owner of each path blocked glob patterns that hid review from the senior. The line naming who answered each item stopped the junior from treating the model as a silent teammate.

Dead end one: generate first, own later

The junior wanted to ship a dirty working tree to a remote host just to watch the agent move. That path failed because a dirty tree has no honest rollback SHA that a later bisect can trust. Generated files mixed with leftover debug prints, so ownership could not be assigned without a blame fight. The pairing reset the tree, wrote the SHA while HEAD was clean, and only then discussed remote work.

Dead end two: let the loop pick the files

The agent proposed a retry loop that grepped the repository and patched every match it considered similar. The senior rejected that loop because a grep result is not a review contract and not an owner list. Two extra iterations rewrote a logging helper that nobody in the pairing had agreed to touch. The pairing stopped the loop, restored the helper from the rollback SHA, and required an owners file.

Dead end three: treat the chat as the log

The junior saved a long chat export and then called that export the official pairing decision record. Chat order is not merge order, and later edits in the same thread silently replace earlier constraints. A reviewer who was absent from the call cannot reconstruct owners, answers, or the rollback point from prose. The pairing discarded the export as evidence and required three small files that a diff can review.

The decision that survived the three dead ends

After those three dead ends, the pairing kept one rule and wrote it into the repository. No remote agent job is allowed to start until .pairing/rollback, .pairing/owners.txt, and .pairing/questions.tsv all exist on disk. Those files are the kept decision, not a retrospective paragraph written after a merge already landed. If a later pairing wants a different policy, it must change the files and the gate together.

Artifact: a decision table, three files, and a gate

The following files and the gate script are a proposed, unexecuted example for a local pairing branch. They do not claim production uptime, token quotas, hardware capacity, or any permanent free-tier promise. A team should copy them into a scratch branch, run the commands, and then delete them if the gate is too strict. The script exits nonzero when any required pairing file is missing, empty, or still marked unanswered.

Dead end	What the junior tried	Why the senior stopped it	File that remains
Generate first	Push a dirty tree to a remote host	No honest rollback SHA	`.pairing/rollback`
Loop picks files	Grep-and-patch similar symbols	No human owner contract	`.pairing/owners.txt`
Chat as log	Treat a transcript export as evidence	Not reviewable in a later diff	`.pairing/questions.tsv`

The table is the pairing memory of the three dead ends, reduced to files a later reviewer can open. Owners and questions use boring text so the gate never needs a YAML library on a pairing laptop. A comment line starting with # is ignored, which keeps examples readable during the session. The rollback file remains a raw SHA because extra commentary would invite another chat-shaped decision log.

# .pairing/owners.txt
# format: path<TAB>human-owner
# globs are rejected by pairing_gate.py
src/billing/invoice.py  alex
src/billing/totals.py   alex
tests/billing/test_invoice.py   alex

# .pairing/questions.tsv
# columns: id, status, owner, question, answer
# status must be answered or deferred; open fails the gate
id  status  owner   question    answer
Q1  answered    sam What SHA restores this tree Use git rev-parse HEAD while porcelain is empty
Q2  answered    alex    Who owns invoice.py alex reviews any diff under src/billing/invoice.py
Q3  deferred    sam Do we retune tax rounding   Reopen after rollback plus owned invoice tests pass

# Proposed commands. Run them on a scratch branch, not on main.
git status --porcelain
git rev-parse HEAD
mkdir -p .pairing
git rev-parse HEAD > .pairing/rollback
printf '%s\n' 'src/billing/invoice.py   alex' > .pairing/owners.txt
python3 pairing_gate.py

#!/usr/bin/env python3
"""Proposed pairing gate. Unexecuted example. Standard library only."""
from __future__ import annotations

import pathlib
import subprocess
import sys

ROOT = pathlib.Path.cwd()
PAIRING = ROOT / ".pairing"
ROLLBACK = PAIRING / "rollback"
OWNERS = PAIRING / "owners.txt"
QUESTIONS = PAIRING / "questions.tsv"
ALLOWED_STATUS = {"answered", "deferred"}


def fail(message: str) -> None:
    print(f"pairing-gate: {message}", file=sys.stderr)
    raise SystemExit(1)


def git(*args: str) -> str:
    result = subprocess.run(
        ["git", *args],
        cwd=ROOT,
        check=False,
        capture_output=True,
        text=True,
    )
    if result.returncode != 0:
        fail(f"git {' '.join(args)} failed: {result.stderr.strip()}")
    return result.stdout.strip()


def read_rows(path: pathlib.Path) -> list[str]:
    if not path.is_file():
        fail(f"missing {path}")
    lines = []
    for raw in path.read_text(encoding="utf-8").splitlines():
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        lines.append(raw.rstrip("\n"))
    if not lines:
        fail(f"{path} has no data rows")
    return lines


def main() -> None:
    git("rev-parse", "--is-inside-work-tree")
    porcelain = git("status", "--porcelain")
    if porcelain:
        fail("working tree is dirty; restore or stash before remote work")

    sha = ROLLBACK.read_text(encoding="utf-8").strip() if ROLLBACK.is_file() else ""
    if not sha or any(ch.isspace() for ch in sha):
        fail("rollback file must contain a single SHA")
    git("cat-file", "-t", sha)
    head = git("rev-parse", "HEAD")
    if sha != head:
        fail(f"rollback {sha} does not match HEAD {head}")

    owned = {}
    for row in read_rows(OWNERS):
        if "\t" not in row:
            fail(f"owner row must be path<TAB>human: {row}")
        path, owner = row.split("\t", 1)
        path, owner = path.strip(), owner.strip()
        if not path or not owner:
            fail(f"empty path or owner: {row}")
        if any(ch in path for ch in "*?["):
            fail(f"globs are not owners: {path}")
        if owner.lower() in {"agent", "model", "bot"}:
            fail(f"owner must be a human: {owner}")
        owned[path] = owner

    answered = 0
    for index, row in enumerate(read_rows(QUESTIONS)):
        parts = row.split("\t")
        if index == 0 and parts and parts[0] == "id":
            continue
        if len(parts) != 5:
            fail(f"question row must have five TSV columns: {row}")
        qid, status, owner, question, answer = [part.strip() for part in parts]
        if status not in ALLOWED_STATUS:
            fail(f"{qid} status {status} is not answered or deferred")
        if not owner or not question:
            fail(f"{qid} needs an owner and a question")
        if status == "answered" and not answer:
            fail(f"{qid} is answered but the answer cell is empty")
        if status == "deferred" and not answer:
            fail(f"{qid} is deferred but has no reopen reason")
        answered += 1

    print("pairing-gate: ok")
    print(f"rollback={sha}")
    print(f"owned_paths={len(owned)}")
    print(f"ledger_rows={answered}")


if __name__ == "__main__":
    main()

The gate is intentionally boring so a pairing can run it before anyone opens a browser tab. It refuses a dirty tree, an unknown SHA, an empty owner map, and any question still marked open. It does not compile the project, run the test suite, or judge whether the remote model wrote good code. Those checks stay with the human owners after the agent returns a patch against the rollback SHA.

Numbered pairing workflow

1. Freeze a clean rollback SHA

The pairing inspects git status --porcelain and restores or stashes anything that would poison the SHA. The pairing writes the output of git rev-parse HEAD into .pairing/rollback while the working tree is still empty. The pairing confirms restoration with a dry git reset --hard against that SHA on a throwaway clone. Only after that clone matches HEAD does the pairing treat the SHA as a real rollback point.

git clone --no-checkout . /tmp/rollback-check
git -C /tmp/rollback-check reset --hard "$(cat .pairing/rollback)"
git -C /tmp/rollback-check rev-parse HEAD

2. Write owners before any path is eligible

Each eligible path gets one human owner who will read the later diff before merge. Shared libraries and generated fixtures stay off the list until someone volunteers in the pairing notes. If the agent wants a new path, the pairing amends the owners file first and reruns the gate. An owner name that matches a model label is rejected, because models do not accept review mail.

3. Fill the question ledger before any prompt

Every question the senior asked becomes a row with an owner, a status, and a one-line answer. Unanswered rows block the gate even when the junior already drafted a long prompt for the agent. Deferred rows need a reason, a later SHA, and a human who will reopen the ledger. The pairing reads the ledger aloud once so silent assumptions cannot hide inside the prompt text.

4. Run the local gate

The pairing runs python3 pairing_gate.py from the repository root and treats a nonzero exit as a stop. A passing gate means the three files exist, the tree is clean, and no question remains open. A failing gate is not a prompt-engineering problem, and the pairing does not retry the model to fix it. The pairing edits the files, reruns the command, and only then discusses whether a remote job is still needed.

5. Bound the remote job against owned paths

Disclosure: This article was prepared as part of MonkeyCode's product outreach. Once the local gate passes, a bounded generation job may use MonkeyCode free model access and the free server option. The remote host is a scratch worker, not a source of truth and not a substitute for the owners file. The prompt must paste the owned paths and the rollback SHA so the agent cannot widen the blast radius. Output that touches an unowned path is discarded, even when the generated patch looks locally elegant.

# After a remote patch lands in /tmp/agent.patch, keep owned paths only.
git worktree add /tmp/owned-review "$(cat .pairing/rollback)"
git -C /tmp/owned-review apply --check /tmp/agent.patch
# Reviewers then inspect only paths listed in .pairing/owners.txt.

6. Merge only the owned diff

The pairing checks out the rollback SHA in a clean worktree and applies only the owned-path diff. Human owners read that diff against the question ledger rather than against the original chat transcript. Tests that the pairing already trusted must still pass on the rollback SHA plus the owned diff. Anything the remote host wrote outside those paths stays untracked and is deleted before merge.

git -C /tmp/owned-review diff --name-only "$(cat .pairing/rollback)"
# Compare that list to .pairing/owners.txt before anyone runs git merge.

Limitations and who should not use this

This workflow assumes a Git repository, two people who can interrupt each other, and a clean tree. Solo developers who need a fast scratch pad will find the gate louder than the bug they came to fix. Incident responders working on a live outage should not pause to invent owners files during a page. Teams without a senior who will actually reject unowned paths will only produce three more empty documents.

The article does not measure model quality, server throughput, or how long a free tier remains available. Those numbers change, and no pairing file in this workflow pretends to freeze a vendor capability. The gate also cannot detect a wrong but confidently answered ledger row, which remains a human failure mode. Security-sensitive repositories should keep secrets out of ledgers, prompts, and every remote scratch host they use.

What the pairing kept

The pairing asked for a rollback SHA, named file owners, and wrote answers before any remote agent work. Three dead ends tried to skip those files, and each one mixed generated noise with unowned edits. The decision that remained is local and boring: keep the three files, run the gate, then maybe generate. Remote availability can wait; an unowned patch cannot be honestly merged, even when the host itself was free.

The Pairing Merged a Transcript File Before It Merged Any Agent Diff

Avery Li — Sat, 12 Sep 2026 18:51:34 +0000

The pairing should treat the session transcript as the first merge artifact, not the generated patch. A senior engineer can review questions, recorded dead ends, and one named keep without trusting an unverified agent diff. The working tree stays clean when drafts run on a rehearsal host that the team can destroy. This article proposes a concrete protocol, a small transcript schema, and a merge gate that refuses patches without that packet.

Why generated diffs fail senior review

Agent drafts often arrive as a pile of files with no record of what was tried and discarded. Seniors then reverse-engineer intent from the diff, which hides failed approaches that still constrain the design. Reviewers cannot tell whether a rename was a reasoned keep or the last of several unlogged guesses. The protocol below records each question, each dead end, and a single keep so the review packet stands without the chat.

Loop-style coding assistants make this gap worse when they retry silently on the same protected tree. A pairing that cannot point at a rehearsal command for each failure will relitigate the same dead end after lunch. The proposed gate requires every dead end to cite a command, an exit code, and a host outside the protected clone.

Proposed pairing roles and constraints

This section describes a proposed workflow, not a measured case study from a named production team. The junior or coding agent may draft only on a throwaway rehearsal host that reviewers can delete. The senior answers only those questions that already name a repository path and a proving command. The merge referee is a small checker that reads pairing-transcript.json and blocks the pull request when required fields are missing.

The kept decision is not a paragraph in chat or a vague thumbs-up in a review thread. It is one machine-readable object with an identifier, a rationale, and the files it may touch. Later patches that fall outside that allow-list fail the same checker without further debate. The pairing stops generating once that keep is named, instead of opening a fourth architectural fork.

The transcript schema

The pairing writes one JSON document that a hook can validate during the same session. Each question names the file under discussion and the command that would prove an answer. Each dead end stores the rehearsal command, the observed exit status, and a one-line reason the approach is closed. The keep object appears at most once and lists the paths the eventual patch may change.

{
  "session_id": "2026-09-13-auth-cookie-rotate",
  "protected_clone": "/work/app",
  "rehearsal_host": "rehearsal.example.internal",
  "questions": [
    {
      "id": "q1",
      "asked_by": "junior",
      "text": "Should rotate_cookie write Set-Cookie in the handler or a middleware?",
      "names_path": "src/http/session.ts",
      "proving_command": "npm test -- session.test.ts"
    }
  ],
  "dead_ends": [],
  "keep": null
}

The schema stays small so a pairing can fill it while talking rather than reconstructing it from memory afterward. Empty dead-end arrays remain legal only while questions are still open and no keep has been named. The checker later rejects a keep that names paths never mentioned in a question or in a recorded dead end.

Numbered pairing procedure

1. Freeze the protected clone

The pairing clones the service into a read-only working copy and refuses agent writes against that tree. A second clone, or a disposable host, receives every experimental edit and every proving command. The senior confirms both roots in the transcript before any model call is allowed to start. Secrets from the protected clone must not be copied into the rehearsal host.

#!/usr/bin/env bash
set -euo pipefail
PROTECTED="/work/app"
REHEARSAL="/tmp/rehearsal-app"
git clone -- "$PROTECTED" "$REHEARSAL"
chmod -R a-w "$PROTECTED/.git"
printf 'protected=%s\nrehearsal=%s\n' "$PROTECTED" "$REHEARSAL"

The script only prepares two trees and does not imply extra product features, quotas, or hardware. Teams may replace the local rehearsal directory with a short-lived virtual machine when network isolation matters more than convenience. The protected clone remains the only candidate for merge, even when the rehearsal host looks healthier during the afternoon.

2. Record every question before anyone answers

The junior writes the next question into the transcript with a path and a proving command. The senior declines questions that lack those two fields, because later readers cannot check them. A small helper appends the question and refuses free-form chat as the system of record. Models that emit patches before a question exists are ignored, regardless of how fluent the draft looks.

# pairing_log.py — proposed helper, not a production service
import json
from pathlib import Path

def append_question(path: Path, item: dict) -> None:
    data = json.loads(path.read_text())
    if not item.get("names_path") or not item.get("proving_command"):
        raise ValueError("question must name a path and a proving command")
    data["questions"].append(item)
    path.write_text(json.dumps(data, indent=2) + "\n")

This step is the pairing throttle, not a style lecture about prompt writing. The senior still owns the answers; the log only makes each question durable enough for a merge referee. A question that cannot name a file is usually an architecture debate and should wait until a path exists.

3. Run candidate edits only on the rehearsal host

Drafts execute against the rehearsal tree and never against the protected clone. Each attempt records the command that was supposed to pass and the exit code that actually returned. A non-zero exit becomes a dead-end candidate, not an invitation to edit the real branch. The pairing copies command output back to the senior and leaves binaries on the rehearsal host.

#!/usr/bin/env bash
set -euo pipefail
REHEARSAL="${REHEARSAL:?}"
CMD="${1:?}"
set +e
( cd "$REHEARSAL" && bash -lc "$CMD" )
status=$?
set -e
python3 - <<'PY' "$CMD" "$status"
import json, sys
print(json.dumps({"command": sys.argv[1], "exit_code": int(sys.argv[2])}))
PY

If the rehearsal place is a remote free server, the same rule still applies to every file that moves. Pull logs and failing assertions, not mystery build caches that nobody can replay. The senior should be able to quote the command later inside a dead-end object without asking the model to remember it.

4. Promote a failure into a named dead end

A failed rehearsal is not yet a dead end, because the pairing may still lack a reason the approach cannot be repaired. The senior names it a dead end only after that reason can be written in one line beside the command evidence. The dead-end object also points at the question it closes, so later readers do not retry it casually. Missing links back to a question fail the helper instead of entering the log.

def append_dead_end(path: Path, item: dict) -> None:
    required = ("id", "command", "exit_code", "reason", "closes_question")
    missing = [k for k in required if k not in item]
    if missing:
        raise ValueError(f"dead end missing {missing}")
    data = json.loads(path.read_text())
    qids = {q["id"] for q in data["questions"]}
    if item["closes_question"] not in qids:
        raise ValueError("dead end must close a recorded question")
    data["dead_ends"].append(item)
    path.write_text(json.dumps(data, indent=2) + "\n")

The following dead ends are labeled illustrations, not timed benchmarks or claimed production incidents. The first closes a middleware-only design after the rehearsal test could not see the rotated cookie on a redirect. The second closes a handler-only design after duplicate Set-Cookie headers appeared in the captured rehearsal response. Both entries exist so the keep does not look like an unexplained preference.

[
  {
    "id": "d1",
    "closes_question": "q1",
    "command": "npm test -- session.test.ts",
    "exit_code": 1,
    "reason": "middleware Set-Cookie never reached the redirected client fixture"
  },
  {
    "id": "d2",
    "closes_question": "q1",
    "command": "npm test -- session.test.ts",
    "exit_code": 1,
    "reason": "handler-only write duplicated Set-Cookie on rotate after login"
  }
]

5. Name exactly one keep

After dead ends accumulate, the senior writes a single keep object and stops the drafting loop. The keep lists allowed paths, the proving command that must pass on a clean checkout, and the question it answers. A second keep in the same session is a protocol violation and fails the checker. Additional model output that touches other files is discarded even when it looks helpful.

def set_keep(path: Path, keep: dict) -> None:
    data = json.loads(path.read_text())
    if data.get("keep"):
        raise ValueError("session already has a keep")
    allowed = set(keep.get("allowed_paths") or [])
    mentioned = {q["names_path"] for q in data["questions"]}
    mentioned |= {
        p for d in data["dead_ends"] for p in d.get("touched_paths", [])
    }
    if not allowed or not allowed.issubset(mentioned):
        raise ValueError("keep paths must be a non-empty subset of questioned paths")
    data["keep"] = keep
    path.write_text(json.dumps(data, indent=2) + "\n")

In the illustrative cookie pairing, the senior kept a small helper called from login and from rotate, not a new middleware stack. The allow-list named src/http/session.ts and src/http/session.test.ts and nothing else. That keep is the decision the pairing retains; the discarded agent APIs remain visible only as dead ends. Implementation after the keep can be typed by a human or applied as a tightly scoped patch.

6. Gate the merge on the transcript

A pre-commit or CI step loads the transcript and the proposed diff before anyone argues about style. It rejects the change when questions lack proving commands, when dead ends lack rehearsal exit codes, or when the keep is missing. It also rejects files that are not in keep.allowed_paths. The transcript stays in the pull request so later readers can see which questions produced the keep.

# check_pairing_gate.py — proposed merge referee
import json, subprocess, sys
from pathlib import Path

def changed_files() -> set[str]:
    out = subprocess.check_output(
        ["git", "diff", "--name-only", "origin/main"], text=True
    )
    return {line.strip() for line in out.splitlines() if line.strip()}

def main() -> int:
    data = json.loads(Path("pairing-transcript.json").read_text())
    if not data.get("questions"):
        print("gate: no questions recorded")
        return 1
    if any(not q.get("proving_command") for q in data["questions"]):
        print("gate: a question lacks a proving command")
        return 1
    if data.get("keep") is None:
        print("gate: senior has not named a keep")
        return 1
    if not data.get("dead_ends"):
        print("gate: no dead ends recorded; pairing looks untested")
        return 1
    extra = changed_files() - set(data["keep"]["allowed_paths"])
    extra.discard("pairing-transcript.json")
    if extra:
        print(f"gate: files outside keep {sorted(extra)}")
        return 1
    return 0

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

Wire the referee from a local hook so a missing transcript never reaches review by accident. The hook should fail closed when the JSON is absent, not skip the gate on a quiet working tree. Teams that already run required checks can add this command beside the existing test job.

#!/usr/bin/env bash
set -euo pipefail
python3 check_pairing_gate.py

Decision table for the senior

Signal in the session	Senior response	Transcript action
Question with no path or command	Do not answer	Reject the append
Rehearsal command exits non-zero, cause still unclear	Ask one follow-up	Leave dead_ends unchanged
Rehearsal command exits non-zero, approach cannot be repaired here	Close the approach	Append a dead end
Two remaining designs still pass rehearsal	Do not keep yet	Record another question
Exactly one design fits the remaining constraints	Name the keep	Write keep and stop drafting
Patch touches a path outside the keep	Block merge	Fail the gate

The table is the pairing memory when the chat is noisy and the model offers a fourth design. Seniors can point at a row instead of restating philosophy in every session. Juniors can see why a fluent agent patch still failed the gate. The keep remains a file, not a vibe.

Where a free rehearsal host fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach. A pairing that needs a disposable machine can use a coding assistant with free model access and a free server option, such as MonkeyCode, as the rehearsal place rather than the source of truth. The models draft only after a question exists in the transcript, and the server runs proving commands that the senior can quote in a dead end. The protected clone still never receives those writes until the keep is named and the gate passes.

The same protocol works with a local directory if a remote host is unnecessary for isolation. Product availability can change, and this article does not claim model names, quotas, hardware sizes, or lasting uptime. Teams should verify current access on the product surface they actually use, then keep the transcript format stable so the gate does not depend on a vendor. Readers who already isolate agent drafts may try the gate against a free rehearsal host when a throwaway environment is the missing piece.

Limitations

The protocol does not measure model quality and does not replace design review for security-sensitive changes. A dishonest transcript can still pass the checker if humans collude, because the gate validates structure rather than truth. Rehearsal hosts can diverge from production in operating system, CPU, or secret material, so a green rehearsal command is not a production proof. JSON logs also add ceremony that tiny typo fixes do not deserve.

Pairings that last ten minutes should skip the full schema and use a normal review on the protected clone. Long sessions benefit because dead ends otherwise vanish into scrollback and return as new agent suggestions. The gate also cannot see intent that never became a question, so seniors still need to refuse off-transcript architecture changes in the comment thread.

Who should not use this approach

Teams that cannot provision an isolated rehearsal tree should not send agent writes anywhere near the protected clone. Regulated environments that forbid unreviewed model output should keep models out of both trees, including free ones. Pairings that lack a senior willing to name a keep will only produce a thicker chat log with prettier JSON. People searching for an autonomous agent that merges itself will not find that behavior here.

The point of the protocol is to slow generation until a human decision is durable in a file. If the team wants maximum throughput of unreviewed patches, a transcript gate will feel like friction, and that friction is intentional. Treat the rehearsal host, free or otherwise, as disposable infrastructure. Treat the transcript as the thing the pairing actually keeps.

The Pairing Parked Free-Tier Calls Until Each Question Named a Proof

Avery Li — Fri, 11 Sep 2026 16:23:33 +0000

The pairing parked every free-tier model call until each open question named a local proof command and a file owner. Exploratory chat without that ledger row wasted the shared tier and left no replayable evidence for later review. The senior kept the ledger, the proof command, and a disposable free server for agent shells after faster habits failed. This walkthrough records the questions, the failed shortcuts, the artifact, and the numbered protocol the desk used next.

The rule the pairing kept

A remote model turn was treated as a scarce review step, not as a substitute for reading the tree. Each question needed a ledger row with an owner, a target path, a proof command, and a keep-or-drop rule before anyone pasted a prompt. Agent command execution stayed off the reviewer laptop and ran on a disposable free server so local editor state could not leak into the result. The pairing accepted a patch only when a clean replay of the proof command matched the ledger's expected signal.

This protocol is a proposed pairing-desk workflow, not a production incident runbook and not a measured benchmark of any model. Teams should adapt the files below to their own repository layout, test runner, and CI image. The examples are labeled unexecuted because no private environment log is attached to this article. Readers should treat every command as something to run inside a throwaway clone.

Why shared free-tier pairing collapses without a ledger

Free-tier model access is useful during pairing, but the context window fills with questions that nobody later remembers owning. Two people talking through a failing checkout will restate the same hypothesis across three prompts and then lose the one command that actually failed. A shared free server helps isolate agent shells from the reviewer laptop, yet isolation does not invent a decision record if the chat scrollback is the only artifact. The ledger exists so the next pairing hour can start from proof commands rather than from reconstructed folklore.

The product surface matters only when the agent needs a named file list and a place to run shells that is not the reviewer workstation. MonkeyCode participates here as free model access plus a free server option for those isolated command runs. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The keep rule still stands if that product name is removed, because the pairing accepts patches from proof commands rather than from vendor chrome.

Artifact: the question ledger

The pairing kept a JSONL file at pairing/question-ledger.jsonl on the branch, never inside a private chat export. Each line is one question the senior was willing to spend a free-tier turn on after a local proof existed. Rows without a proof command were illegal, and the validator below rejects them before any remote call is allowed. The sample row is a template for a checkout discount stack, not a claim about a live production incident.

{
  "id": "Q-014",
  "asked_by": "reviewer",
  "owned_by": "author",
  "question": "Does checkout skip the coupon when the cart already has a staff discount?",
  "target_paths": ["app/checkout/price.py", "tests/test_price_stack.py"],
  "proof_command": "python -m pytest tests/test_price_stack.py::test_staff_discount_blocks_coupon -q",
  "expected_signal": "FAILED",
  "remote_call_allowed": false,
  "keep_rule": "keep the agent patch only if the proof command flips FAILED to PASSED on a clean tree"
}

A short validator makes the completeness rule mechanical so the pairing does not argue about missing fields in the moment. The same-owner check is intentional, because the agent must not become the missing second name on the row. Run the script from a throwaway clone and treat a nonzero exit as a hard stop.

# pairing/validate_ledger.py
# Proposed local gate. Label: unexecuted against a private repository.
from __future__ import annotations

import json
import sys
from pathlib import Path

REQUIRED = (
    "id",
    "asked_by",
    "owned_by",
    "question",
    "target_paths",
    "proof_command",
    "expected_signal",
    "remote_call_allowed",
    "keep_rule",
)


def load_rows(path: Path) -> list[dict]:
    rows = []
    for line_no, raw in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
        if not raw.strip() or raw.lstrip().startswith("#"):
            continue
        try:
            row = json.loads(raw)
        except json.JSONDecodeError as exc:
            raise SystemExit(f"ledger line {line_no} is not JSON: {exc}") from exc
        missing = [key for key in REQUIRED if key not in row]
        if missing:
            raise SystemExit(f"{row.get('id', line_no)} missing {missing}")
        if not row["target_paths"] or not str(row["proof_command"]).strip():
            raise SystemExit(f"{row['id']} needs target_paths and proof_command")
        if row["asked_by"] == row["owned_by"] and row.get("allow_same_owner") is not True:
            raise SystemExit(f"{row['id']} needs a second owner before a remote call")
        rows.append(row)
    return rows


def main() -> None:
    ledger = Path(sys.argv[1] if len(sys.argv) > 1 else "pairing/question-ledger.jsonl")
    rows = load_rows(ledger)
    blocked = [row["id"] for row in rows if not row["remote_call_allowed"]]
    print(f"ok {len(rows)} rows; remote still blocked for {blocked or 'none'}")


if __name__ == "__main__":
    main()

Walkthrough: questions, failed shortcuts, and the keep rule

The reconstructed session started with a failing checkout test and a temptation to paste the pricing module into a free-tier prompt. The senior asked who owned the question, which file could answer it, and which command would falsify the current story. Those three asks produced the first ledger row before any assistant panel received repository text. The agent stayed parked while the desk walked the shortcuts that usually feel faster than writing a proof command.

Failed shortcut: dump the module and hope the model notices the stack

The author offered to dump price.py into the prompt so the free-tier model could inspect the discount stack without reading tests. The senior refused that dump because a paste has no expected signal and cannot be replayed by the next reviewer on a clean tree. The pairing ran the proof command as a read-only local observation and recorded FAILED plus the assertion name inside the ledger row. A remote call became legal only after that row existed, and the prompt could include those two named paths only.

Failed shortcut: let the agent run on the reviewer laptop

The author then proposed starting the agent inside the reviewer working tree because a free server clone would add several extra minutes. The senior blocked that shortcut because agent shells mix unsaved editor buffers with local environment variables that never appear in review. A disposable free server clone has no open editor and no developer secrets sitting in the interactive shell history. The pairing copied the branch there, reran the proof command, and treated every unlisted command as outside the pairing contract.

Failed shortcut: keep the first fluent answer as the decision

The free-tier model returned a fluent patch that added a second flag on the coupon object and left the failing test untouched in spirit. The senior did not keep that patch, because the keep rule required the original proof command to flip on a clean tree. A second remote call was allowed only after the ledger gained a new row that named the flag hypothesis and a new test path. The decision the pairing kept was the later patch that reordered the discount stack and left the coupon object unchanged.

Numbered protocol the desk ran next

The pairing encoded the afternoon as eight gates so the next session would not reinvent the same argument. Each step is a stop, and skipping a gate returns the desk to the previous file rather than to a longer prompt. Commands below assume a throwaway clone, a Unix shell, and a test file that already fails for a known reason.

Create a branch and an empty ledger file before anyone opens a chat panel for the bug.
Write one JSONL row per question, including owner, paths, proof command, expected signal, and keep rule.
Run python pairing/validate_ledger.py and refuse to continue if the process exits nonzero.
Execute the proof command on the reviewer laptop only as a read-only observation, never as an agent loop.
Flip remote_call_allowed to true only after the expected signal is captured beside the ledger row.
Send the model the ledger row, the named files, and the command output, not the rest of the repository.
Apply candidate diffs on a free server clone, then replay the same proof command against the keep rule.
Merge only the diff that satisfies the keep rule; append dropped attempts as ledger notes, not as chat folklore.

# Proposed pairing gate. Label: run in a throwaway clone.
set -euo pipefail
git checkout -b pairing/q-014-price-stack
mkdir -p pairing
test -f pairing/question-ledger.jsonl
python pairing/validate_ledger.py pairing/question-ledger.jsonl

# Read-only local observation. Do not start an agent on this laptop.
python -m pytest tests/test_price_stack.py::test_staff_discount_blocks_coupon -q \
  | tee pairing/Q-014.local.log

# After remote_call_allowed is true, clone on a disposable free server:
# git clone "$REPO" /tmp/q-014
# git -C /tmp/q-014 checkout pairing/q-014-price-stack
# apply the candidate diff, then rerun the same proof command and tee the log.

A tiny keep-or-drop helper makes the eighth gate less theatrical during review. The signal parser is deliberately coarse and should be replaced with the team's actual test reporter. Treat UNCLEAR as a drop, because an ambiguous log is not a keep rule.

# pairing/keep_drop.py
# Proposed helper. Label: unexecuted; wire to the team's log files.
from pathlib import Path
import sys


def last_signal(log_path: Path) -> str:
    text = log_path.read_text(encoding="utf-8")
    lowered = text.lower()
    failed = "failed" in lowered
    passed = "passed" in lowered
    if failed and not passed:
        return "FAILED"
    if passed and not failed:
        return "PASSED"
    return "UNCLEAR"


def main() -> None:
    before = last_signal(Path(sys.argv[1]))
    after = last_signal(Path(sys.argv[2]))
    if before == "FAILED" and after == "PASSED":
        print("KEEP")
        return
    print("DROP")
    raise SystemExit(2)


if __name__ == "__main__":
    main()

# Label: unexecuted. Compare the local failing log with the free-server replay log.
python pairing/keep_drop.py pairing/Q-014.local.log pairing/Q-014.server.log

Decision table the senior used during review

The table below is the keep artifact for the session. It is not a scorecard, and it does not rank models, vendors, or prompt styles. Rows move left to right only when the previous column is already written down. The table is deliberately boring, because boring gates are the entire point of pairing against a scarce shared free tier.

Question state	Local proof	Remote call	Agent shell	Outcome the pairing kept
Spoken only	Missing	Blocked	Blocked	No row, no prompt
Row without a second owner	Command listed	Blocked	Blocked	Validator fails
Row with a FAILED log	Captured	Allowed on named files	Free server only	Prompt may run
Fluent patch, proof still FAILED	Captured	New row required	Free server only	DROP
Patch flips FAILED to PASSED	Captured	No extra files	Free server replay	KEEP

Limitations and who should not use this

The protocol assumes the failure is already expressible as a command, which many design debates and product questions are not. It also assumes a second person can own the question, so solo late-night work will not satisfy the same-owner check without an explicit override flag. A free server clone will not help if the bug exists only against production data that cannot be copied into that isolate. Teams that need guaranteed capacity, air-gapped networks, or secret-bearing laptops as the execution surface should not park agent shells on a shared free server.

The validator does not measure model quality and does not prove that free-tier access will remain available in any given week. Operators should verify current product terms from primary sources before planning a sprint around availability claims. This article does not claim token quotas, hardware sizes, durations, permanence, or speedups, because those figures were not supplied as verified facts. If the keep rule cannot be written in one sentence, the pairing should not spend a free-tier turn yet.

The Pairing Kept One Decision After Three Dead Ends

Avery Li — Wed, 09 Sep 2026 16:39:10 +0000

The pair should not start a free-tier coding agent until three human artifacts already exist in writing. Those artifacts are the questions already asked, the dead ends already tried, and one decision the pair will keep if the workspace is deleted. Free model access and a free server do not replace that freeze, because agents still reopen paths the humans already rejected. This walkthrough records a reconstructed pairing that reached that freeze rule only after three failed attempts.

Pairing notes decay faster than diffs

Senior engineers often remember the rejected approaches more clearly than they remember the accepted patch itself. Junior partners usually remember only the accepted patch and forget why three other shapes already died. Agents sitting between them remember neither, because they receive a prompt that starts at the current tree. The familiar waste is an agent rediscovering a dead end the pair already closed ten minutes earlier.

Chat transcripts vanish when the window closes, and inline comments inside the working tree pollute the eventual reviewable diff. Prompt preambles look convenient until the agent summarizes them and drops the owners of each answer. The pairing therefore needed a receipt that lives outside the repository and outside the model context window. That pairing receipt becomes the only merge-worthy object, while the agent workspace remains a disposable copy.

Three dead ends the pair actually walked

The walkthrough below is a reconstructed pairing on authorization middleware, labeled as a proposal rather than a production incident report. The junior partner wanted retries around a policy client that timed out after two hundred milliseconds. The senior refused those retries because they amplified tail latency on the shared gateway path. The agent, when invited too early, reopened both retries and a stale allow cache from memory.

Dead end one wrapped the policy client in a three-shot retry with backoff and failed a local load script against the p99 SLO. Dead end two cached the last good policy for thirty seconds and then served a stale allow after a revoke fixture. Dead end three asked an agent to invent a timeout policy from the open tree, which simply rediscovered the first two failures. The kept decision after those three attempts was to fail closed on policy timeout, emit a metric, and never retry.

The senior asked who owned the fail-closed choice, who had measured the p99 script, and who would delete the agent workspace. The junior owned the measurement script, the senior owned the fail-closed rule, and both owned the delete step. Questions without named owners were treated as incomplete, even when the group felt they had already agreed. That rule later became field validation in the receipt checker rather than a social reminder during the next session.

A receipt the agent is forbidden to edit

The JSON document below is a proposal for a pairing receipt, not an executed production record from a live incident. Teams can keep pairing/receipt.json on the operator machine and copy a read-only snapshot into a disposable workspace. The agent may read that snapshot as constraint text, but any write to the receipt invalidates the whole remote session. Verbose receipts survive pairing better than compressed prompts the model is free to summarize away.

{
  "session_id": "2026-09-09-authz-middleware",
  "repo": "payments-gateway",
  "agent_may_edit_receipt": false,
  "questions": [
    {
      "id": "Q1",
      "asked_by": "senior",
      "text": "Does the middleware fail closed when the policy service times out?",
      "answered_by": "junior",
      "answer": "Current code fails open after 200ms; that is the pairing bug."
    },
    {
      "id": "Q2",
      "asked_by": "junior",
      "text": "Can we retry the policy call inside the request path?",
      "answered_by": "senior",
      "answer": "No. Retries amplify tail latency. Fail closed and emit a metric."
    },
    {
      "id": "Q3",
      "asked_by": "senior",
      "text": "Who deletes the free-tier workspace after local replay?",
      "answered_by": "both",
      "answer": "Either partner may delete it; merge requires evidence it was deleted."
    }
  ],
  "dead_ends": [
    {
      "id": "D1",
      "attempt": "Three-shot retry with backoff around the policy client.",
      "symptom": "Local load script pushed p99 past the gateway SLO.",
      "abandoned_because": "Retries were forbidden by Q2."
    },
    {
      "id": "D2",
      "attempt": "Cache the last good policy for thirty seconds.",
      "symptom": "Stale allow survived a revoke in the fixture set.",
      "abandoned_because": "Authorization must not serve a cached allow after revoke."
    },
    {
      "id": "D3",
      "attempt": "Let the agent invent timeout handling from the open tree.",
      "symptom": "The agent reopened D1 and D2 because the prompt omitted them.",
      "abandoned_because": "The agent had no receipt, only current files."
    }
  ],
  "kept_decision": {
    "id": "K1",
    "statement": "On policy timeout, fail closed, record a metric, and do not retry.",
    "agent_must_not_reopen": ["D1", "D2"],
    "success_test": "test_policy_timeout_fails_closed"
  },
  "workspace": {
    "kind": "disposable-free-tier",
    "merge_rule": "keep only diffs that still pass after a clean local replay"
  }
}

Target shape the kept decision required

The application change below is not production code and should be read as a proposal for local replay. It exists so the named success test has a concrete function to call after the agent session ends. The agent is allowed to move toward this shape only after the receipt validates on the operator machine.

# policy_middleware.py — proposal / unexecuted example
class Deny:
    def __init__(self, reason: str) -> None:
        self.reason = reason


class PolicyTimeout(Exception):
    pass


def authorize(request, policy_client, metrics):
    try:
        return policy_client.evaluate(request, timeout_ms=200)
    except PolicyTimeout:
        metrics.increment("policy.timeout.fail_closed")
        return Deny(reason="policy_timeout")

# tests/test_policy_timeout_fails_closed.py — proposal / unexecuted example
from policy_middleware import Deny, PolicyTimeout, authorize


class FakePolicyClient:
    def evaluate(self, request, timeout_ms):
        raise PolicyTimeout()


class FakeMetrics:
    def __init__(self) -> None:
        self.counts = {}

    def increment(self, name: str) -> None:
        self.counts[name] = self.counts.get(name, 0) + 1

    def count(self, name: str) -> int:
        return self.counts.get(name, 0)


def test_policy_timeout_fails_closed():
    metrics = FakeMetrics()
    result = authorize(object(), FakePolicyClient(), metrics)
    assert isinstance(result, Deny)
    assert result.reason == "policy_timeout"
    assert metrics.count("policy.timeout.fail_closed") == 1

The brief the agent may receive is also a proposal, not a captured production prompt. It restates the receipt instead of replacing the receipt with a shorter summary. Summaries were dead end three in prose form, because they dropped owners and abandoned symptoms.

# agent_brief.txt — proposal, not a production prompt dump
You may edit application files only.
You may not edit pairing/receipt.json.
You may not reopen dead ends D1 or D2.
Kept decision K1 is closed.
Run test_policy_timeout_fails_closed before claiming done.

Numbered workflow used after the third dead end

The steps below form a method a pair can run in one sitting with git and Python 3. They assume the disposable workspace can be deleted without losing the only copy of the receipt. The order is the control plane, not a suggestion the agent may reorder. Reversing the order recreates dead end three and spends free-tier capacity on memory the pair already paid for in conversation.

Create pairing/receipt.json on the operator machine, not on the shared server, before anyone types a model prompt.
Record every question already asked, including the owner of each answer, even when that answer remains unknown for now.
Record every dead end already walked, with a symptom a later reader can retest without the original chat history.
Record exactly one kept decision and the test name that would prove that decision on a clean tree.
Run the checker shown below so missing owners, empty symptoms, or extra kept decisions fail closed immediately.
Copy a read-only snapshot of the receipt into a disposable workspace that may use free model access later.
Allow the agent to change application code only, and reject any write against pairing/receipt.json without debate.
Replay the candidate diff in a clean local clone, keep the receipt, and then delete the free-tier workspace.

Checker the pair ran before the first agent call

The checker below is a proposal and is not claimed as a production merge gate. It fails when a question lacks an owner, when a dead end lacks a symptom, or when the kept decision is missing a test name. A failing checker is a successful pairing outcome, because it keeps the free-tier session from starting. The humans are not finished until this process exits zero.

# pairing_check.py — proposal / unexecuted example
from __future__ import annotations

import json
import sys
from pathlib import Path

ALLOWED_KINDS = {"disposable-free-tier", "local-throwaway"}


def load_receipt(path: Path) -> dict:
    data = json.loads(path.read_text(encoding="utf-8"))
    if not isinstance(data, dict):
        raise ValueError("pairing receipt must be a JSON object")
    return data


def require(cond: bool, message: str, errors: list[str]) -> None:
    if not cond:
        errors.append(message)


def check(data: dict) -> list[str]:
    errors: list[str] = []
    questions = data.get("questions") or []
    dead_ends = data.get("dead_ends") or []
    kept = data.get("kept_decision") or {}
    workspace = data.get("workspace") or {}

    require(isinstance(questions, list) and questions, "at least one question is required", errors)
    for item in questions:
        qid = item.get("id", "?")
        require(bool(item.get("asked_by")), f"{qid}: asked_by is required", errors)
        require(bool(item.get("answered_by")), f"{qid}: answered_by is required", errors)
        require(bool(item.get("answer")), f"{qid}: answer is required", errors)

    require(isinstance(dead_ends, list) and dead_ends, "at least one dead end is required", errors)
    for item in dead_ends:
        did = item.get("id", "?")
        require(bool(item.get("symptom")), f"{did}: symptom is required", errors)
        require(bool(item.get("abandoned_because")), f"{did}: abandoned_because is required", errors)

    require(isinstance(kept, dict), "kept_decision must be a single object", errors)
    require(bool(kept.get("statement")), "kept_decision.statement is required", errors)
    require(bool(kept.get("success_test")), "kept_decision.success_test is required", errors)
    require(workspace.get("kind") in ALLOWED_KINDS, "workspace.kind must be disposable", errors)
    require(data.get("agent_may_edit_receipt") is False, "agent_may_edit_receipt must be false", errors)
    return errors


def main() -> int:
    path = Path(sys.argv[1] if len(sys.argv) > 1 else "pairing/receipt.json")
    errors = check(load_receipt(path))
    if errors:
        print("pairing receipt rejected:")
        for err in errors:
            print(f"- {err}")
        return 1
    print(f"pairing receipt accepted: {path}")
    return 0


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

Commands the pair can run on the operator machine before any remote session starts are listed next. They are a proposed operator sequence, not a claim that a particular cloud account was used. The chmod 0444 line is the pairing's real enforcement, not a comment hidden inside the model prompt.

mkdir -p pairing /tmp/agent-workspace
python3 pairing_check.py pairing/receipt.json
install -m 0444 pairing/receipt.json /tmp/agent-workspace/PAIRING_RECEIPT.json
test ! -w /tmp/agent-workspace/PAIRING_RECEIPT.json
git clone --no-local . /tmp/clean-replay
git -C /tmp/clean-replay status --short
python3 -m pytest /tmp/clean-replay/tests/test_policy_timeout_fails_closed.py
rm -rf /tmp/agent-workspace

If the remote workspace can rewrite the receipt, the session is already contaminated and should be discarded at once. Local replay still happens on the operator clone, which never mounted the free-tier disk as an authority. That split keeps the laptop as the source of truth for both the receipt and the eventual merge. The deleted workspace is a successful ending, not a lost experiment.

Decision table left on the whiteboard

Signal in the pairing	Human action	Agent allowed	What gets kept
Questions exist, no owners	Stop and name owners	No	Nothing
Dead ends exist only in chat	Copy them into the receipt	No	Nothing
More than one kept decision	Split the pairing into two sessions	No	Nothing
Receipt validates, test missing	Write the success test first	No	The receipt only
Receipt validates, test named	Start a disposable workspace	Yes, application files only	Diff that replays locally
Agent edits the pairing receipt	Discard the workspace	After discard, no	Previous receipt

The table is the pairing's control plane, and the agent is a worker behind that plane. The worker does not vote on dead ends, owners, or the kept decision. If a later prompt tries to reopen D1 or D2, the pair discards the workspace instead of negotiating with the model. Negotiation was how dead end three entered the original session.

Test plan the pair can rerun without a model

The cases below are a reproducible test plan for the method, not a vendor benchmark and not a claim about model quality. Each case names an input, an expected checker result, and whether an agent session may start. Pairs can run the same cases on a laptop without any remote server and still learn whether the freeze is real.

A receipt with an unanswered question must exit nonzero, and the disposable agent session must not start afterward.
A receipt that omits success_test must exit nonzero, because the kept decision is not yet falsifiable on a clean tree.
A receipt that sets agent_may_edit_receipt to true must exit nonzero, even when every question already has an owner.
A writable snapshot in /tmp/agent-workspace must fail the test ! -w check, and that workspace must be deleted.
A clean clone must run test_policy_timeout_fails_closed after the candidate diff lands, before anyone discusses merge.

Where free model access and a free server actually help

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is cited here only as a coding-agent project that currently offers free model access and a free server option. Those two options make a burn-after-use pairing sandbox cheap enough for a pair to delete without budget theater. They do not create pairing memory, and they should not start until the receipt already validates on the operator machine.

After the receipt validates, a disposable workspace becomes rational rather than decorative for this kind of pairing. Free model access lowers the cost of a session the pair has already agreed to delete after local replay. A free server option keeps that session off the laptop that must stay clean for the replay clone. Neither benefit appears if the pair skips the receipt, because the agent will spend the free tier rewalking D1 and D2.

No model names, quotas, hardware, duration, or permanence are claimed here, because those details were not verified for this article. The method still works against any throwaway directory the pair can delete, including a local folder with no remote server. Vendor availability can change, so the receipt and the local replay remain the durable parts of the workflow. The remote session is a rented whiteboard, not a source of record.

Limitations and who should skip this

This workflow is slow on purpose, and that slowness is a poor fit for some real work. Pairs debugging a one-line typo should not write a receipt novel before fixing the obvious typo in front of them. Pairs without a shared definition of fail-closed versus fail-open will produce logs that look complete and still ship the wrong decision. The checker cannot see whether a dead-end symptom is true; it only sees whether the field is empty.

Do not use this approach for incident response under a hard clock, where writing owners would delay a needed rollback. Do not place credentials, production dumps, or customer records on a shared free server in the name of pairing convenience. Do not treat a free-tier workspace as the branch that will be merged, even when the generated diff looks tidy in the remote editor. Do not ask an agent to summarize the receipt into a shorter prompt if that summary drops owners or abandoned symptoms.

The kept decision is a human object, and it has to survive after the workspace is gone. If the pair cannot defend fail-closed timeout handling without the agent in the room, the pairing is not finished. In that case the next step is another human question, not another free-tier run. The receipt exists to make that pause visible instead of polite.

The pairing described here kept one decision after three dead ends: fail closed on policy timeout, never retry, and throw away every free-tier workspace that cannot replay that decision on a clean local tree. The questions and the dead ends outlived the agent session, which was the point of writing them down first. Readers who already have a free-tier coding-agent server can snapshot this receipt into a throwaway session, replay locally, and then delete the remote copy. The decision that remains should still make sense when nobody is paired and the model is not running.

Separate Probe and Patch Windows Before an Agent Touches the Tree

Avery Li — Mon, 07 Sep 2026 14:27:53 +0000

Agent pairing remains unreviewable when chat text is treated as the plan and the working tree is treated as the proof. The session described below keeps one surviving decision: the agent may probe freely, but it may not edit until a structured decision record exists. That record must name a local oracle command the senior already trusts, and the command must fail closed when evidence is missing. The protocol stays useful after product names are removed, because the review gate lives in files and tests.

The pairing setup this protocol assumes

The following write-up is a proposed pairing protocol, labeled as such because it is not a production postmortem. It assumes a brownfield repository, a senior reviewer who rejects chat summaries, and an agent that can read files. It also assumes the pair can copy the repo into a disposable workspace that can be deleted after the session. Private credentials stay off that workspace, and the laptop remains the only place where a patch may be applied.

What the senior blocked

The junior wanted the agent to start editing a flaky checkout service after a short verbal brief. The senior stopped the share-screen session before the first write, because the agent had no named verification command. The working tree already contained unrelated local changes, so a successful chat answer could not be distinguished from an accidental edit. The pairing would have produced a diff that nobody could replay without the original conversation.

Questions the senior asked before any tool write

The senior did not request architecture slogans, fashionable agent terms, or a demonstration of autonomous looping. The senior instead demanded evidence that could be rerun after the chat window had closed. The answers were written into a file before the agent received permission to touch tracked sources.

Name the exact command that proves the current failure on a clean checkout.
Name the files the agent is allowed to read during the probe window.
Name the files the agent is forbidden to write until the decision record is accepted.
Name the unknown that should abort the session instead of inviting a guess.

Those four answers became the header of the decision record used later in the session. Anything the agent could not answer remained listed as an unknown with an abort rule. Unknowns were treated as abort conditions rather than as invitations to improvise a plausible patch.

Dead ends that consumed the first hour

The first dead end was pasting a stack trace into chat and requesting a patch immediately. The model returned a confident diff against a helper that no longer existed on the main branch. The junior branch was twelve commits behind, so the generated hunk could not apply on a clean tree. The pair deleted that diff instead of negotiating with it.

The second dead end was allowing the agent to run formatters across the entire repository during exploration. The later review could not separate the intended fix from a storm of unrelated whitespace changes. The senior reverted the sandbox and marked repository-wide formatters as a deny-list action during probe. Formatting could return only after the functional oracle was green.

The third dead end was trusting a generated summary after the sandbox had already rewritten a migration file. The summary omitted the migration, so a reviewer who read only the chat would have merged a silent schema change. Each dead end shared one shape: generation was allowed to outrun evidence the senior could rerun. The senior froze writes at that point and demanded a record a later reviewer could reject without the transcript.

The decision the pair kept

After those loops, the pair kept one decision and discarded the rest of the earlier improvisation. Probe work may run in a disposable environment so the primary clone never receives experimental writes. The agent must emit decision-record.json before any write to tracked source files is permitted.

The senior reviews that file, runs the named oracle, and only then opens a bounded patch window. If the oracle is missing or exits nonzero, the protocol fails closed and the session produces no diff. Chat logs can remain as scratch paper, but they are not an input to merge review.

A probe window that does not own the repository

A disposable probe host can be a local container or a short-lived remote box with a throwaway clone. MonkeyCode's free model access and free server option can host that probe window when the laptop must stay clean. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The laptop still runs the oracle and the final git apply step, because a remote workspace is not the source of truth. Free remote capacity is relevant only for reading the tree, running probes, and drafting the decision record. The mergeable artifact remains a patch that a clean laptop worktree can recreate.

Workflow: probe, record, oracle, then patch

The steps below are meant to be copied into a pairing checklist rather than performed from memory. Each step produces a file or an exit code, which keeps the next person from depending on the original call.

1. Freeze the laptop clone

The pair creates a clean worktree so the oracle is not lying about unrelated dirty files.

git fetch origin
git worktree add /tmp/checkout-oracle origin/main
cd /tmp/checkout-oracle
git status --porcelain
test -z "$(git status --porcelain)"

The empty porcelain output is the baseline, and any later path must be explained in the decision record. If porcelain is not empty, the pair stops and moves those files aside before any agent command runs. A dirty worktree lets accidental local edits masquerade as successful repairs when the later review begins.

2. Copy a probe clone onto the disposable host

The pair copies a shallow clone to the probe host without env files, deploy keys, or session tokens.

git clone --depth 1 --branch main "$REPO_URL" /tmp/probe-src
rsync -a --delete \
  --exclude '.env*' \
  --exclude '*.pem' \
  --exclude '.git/config' \
  /tmp/probe-src/ probe-host:~/probe-src/

The probe host may use free model access for reading files and proposing the record, not for merging. The copy is disposable on purpose, and it should be destroyed when the pairing session ends. Any secret that would make the probe host more convenient should stay on the laptop instead.

3. Constrain the agent to probe commands

The agent receives an allowlist that can list, read, search, and run tests, but cannot overwrite tracked files.

# probe-allowlist.txt
allow: ls, cat, sed -n, rg, git log, git blame, git show, pytest, npm test
deny: git commit, git push, git apply, tee, cp, mv, rm, chmod

#!/usr/bin/env bash
# proposed example: probe-shell.sh as the agent's command runner
set -euo pipefail
cmd="$*"
deny_re='(git[[:space:]]+(commit|push|apply|rebase)|[[:space:]]tee[[:space:]]| rm | mv | cp )'
if [[ "$cmd" =~ $deny_re ]]; then
  printf 'blocked by probe-shell: %s\n' "$cmd" >&2
  exit 78
fi
bash -lc "$cmd"

This wrapper is a proposed example, not production sandboxing, and a determined process can still bypass it. The point is social and mechanical friction, not a security boundary against a hostile agent runtime. Keep the wrapper in the repo so the next pairing session does not reinvent the deny list from chat.

4. Emit a rejectable decision record

The agent writes only decision-record.json during the probe window, using the schema in the next section. The senior should be able to reject the file in a normal review comment without opening the chat log. If the agent also wants to narrate, that narration stays out of the repository and out of the pull request body.

5. Validate the record before human review

A tiny validator checks required keys, abort unknowns, and the presence of an oracle command string. Validation runs on the laptop against the file copied back from the probe host. A record that fails validation never reaches the patch window, which is cheaper than arguing with a speculative diff.

6. Run the oracle on the laptop worktree

The oracle runs against /tmp/checkout-oracle, not against the probe host, so remote side effects cannot fake green tests.

python3 validate_record.py decision-record.json
ORACLE="$(python3 -c 'import json; print(json.load(open("decision-record.json"))["oracle"]["command"])')"
bash -lc "$ORACLE"

The oracle command must already exist in the project, such as a focused pytest node or a language-native test runner. A sentence that claims tests should pass is not an oracle, and the validator below rejects that shape. The senior watches the exit code rather than the model's summary of the exit code.

7. Open a bounded patch window

Only after a zero exit from the oracle may the agent propose a patch file, still not a live edit. The pair applies the patch on the laptop, reruns the oracle, and then continues ordinary review.

git apply --check agent.patch
git apply agent.patch
bash -lc "$ORACLE"

If git apply --check needs fuzz, the patch returns to the probe window instead of being massaged by hand. Hand massaging reintroduces the original problem, which was an edit that could not be replayed from evidence. The pull request then contains the record, the patch, and the oracle command, not a chat export.

Artifact: schema, sample record, validator, and decision table

The artifact is intentionally small so a pairing session can adopt it without a platform migration. Copy the schema and validator into the repo, then treat a missing record as a failed CI check for agent-authored branches.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AgentDecisionRecord",
  "type": "object",
  "required": ["problem", "probe_evidence", "unknowns", "write_targets", "oracle", "abort_rules"],
  "properties": {
    "problem": { "type": "string", "minLength": 24 },
    "probe_evidence": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["path", "command", "observation"],
        "properties": {
          "path": { "type": "string" },
          "command": { "type": "string" },
          "observation": { "type": "string", "minLength": 8 }
        }
      }
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["text", "abort_if_unknown"],
        "properties": {
          "text": { "type": "string" },
          "abort_if_unknown": { "type": "boolean" }
        }
      }
    },
    "write_targets": {
      "type": "array",
      "minItems": 1,
      "items": { "type": "string" }
    },
    "oracle": {
      "type": "object",
      "required": ["command", "expected_exit"],
      "properties": {
        "command": { "type": "string", "minLength": 3 },
        "expected_exit": { "type": "integer" }
      }
    },
    "abort_rules": {
      "type": "array",
      "minItems": 1,
      "items": { "type": "string" }
    }
  }
}

The sample below is a proposed fixture that the validator should reject until the historical invoice unknown is resolved. That rejection is the point of the pairing rule, not a defect in the fixture.

{
  "problem": "Checkout total drifts by one cent when tax is computed on a rounded line item.",
  "probe_evidence": [
    {
      "path": "services/checkout/tax.py",
      "command": "rg -n 'round(' services/checkout",
      "observation": "round() is applied per line before tax, then applied again on the sum."
    }
  ],
  "unknowns": [
    {
      "text": "Whether historical invoices must keep the old rounding.",
      "abort_if_unknown": true
    }
  ],
  "write_targets": ["services/checkout/tax.py", "services/checkout/test_tax.py"],
  "oracle": {
    "command": "pytest -q services/checkout/test_tax.py",
    "expected_exit": 0
  },
  "abort_rules": [
    "Do not patch if abort_if_unknown is true.",
    "Do not format files outside write_targets."
  ]
}

#!/usr/bin/env python3
"""validate_record.py — proposed checker for agent decision records."""
from __future__ import annotations

import json
import re
import sys
from pathlib import Path

REQUIRED = (
    "problem",
    "probe_evidence",
    "unknowns",
    "write_targets",
    "oracle",
    "abort_rules",
)


def fail(msg: str) -> None:
    print(f"invalid decision-record: {msg}", file=sys.stderr)
    raise SystemExit(2)


def main(path: str) -> None:
    data = json.loads(Path(path).read_text(encoding="utf-8"))
    missing = [key for key in REQUIRED if key not in data]
    if missing:
        fail(f"missing keys: {missing}")
    if len(data["problem"]) < 24:
        fail("problem statement is too short to review")
    if not data["probe_evidence"]:
        fail("probe_evidence must contain at least one observation")
    oracle = data["oracle"].get("command", "")
    if not re.search(r"(pytest|npm test|go test|cargo test|make test)", oracle):
        fail("oracle.command must be a concrete test runner, not a narrative")
    if any(item.get("abort_if_unknown") for item in data["unknowns"]):
        fail("an aborting unknown is still open; patch window stays closed")
    print("decision-record accepted for human review")


if __name__ == "__main__":
    if len(sys.argv) != 2:
        fail("usage: validate_record.py decision-record.json")
    main(sys.argv[1])

The validator above is deliberately harsh: an open aborting unknown fails the file before a human spends time on the prose. Teams that want a warning can move aborting unknowns into an advisory list, but this pairing kept the hard stop. The checkout session did not open a patch window until the invoice unknown was either answered from a product owner or rewritten as an explicit non-goal.

Decision table used during the session

Condition	Probe window	Patch window
Oracle command missing or narrative	Keep probing	Blocked
Unknown with `abort_if_unknown: true`	Record it and stop guessing	Blocked
Formatter or rewrite outside `write_targets`	Deny the command	Blocked
Oracle exits 0 on the clean laptop worktree	Not used	Patch may be applied
Patch applies only with fuzz or manual edits	Return to probe	Blocked
Secrets or `.env` files appear in the probe copy	Abort the host	Blocked

A short test plan for the protocol itself

Feed the validator a record with an empty probe_evidence array and expect exit status 2.
Feed a record whose oracle is tests should pass and expect the same failure.
Feed a record with abort_if_unknown: true and confirm the patch window never opens.
On a clean worktree, run a known failing oracle and confirm the pair does not apply agent.patch.
After a valid record and a green oracle, apply the patch with git apply --check before git apply.

Those checks exercise the protocol, not the checkout tax logic, and they should be committed beside the validator. A pairing team that cannot fail the validator on purpose does not yet have a gate. The senior in this session treated a green validator as permission to read, not as permission to merge.

How the senior rejected records

The senior rejected the record when any unknown had abort_if_unknown set true and a guess appeared in the proposed patch. The senior also rejected the record when the oracle command was a narrative sentence instead of a shell line. A third rejection reason was a file path in write_targets that never appeared in the probe allowlist. Those rejections were cheaper than reviewing a speculative diff, because they happened before the tree moved.

Limitations

The decision record does not prove that the patch is correct; it only proves that the pair named evidence and a rerunnable command. The probe-shell wrapper is not a sandbox, and it will not contain an agent that can execute arbitrary binaries already on the host. A free remote server may lack private packages, so a green probe test can still fail on the laptop oracle.

Time-sensitive model quality, quotas, and hardware details are omitted here because they change and were not independently measured for this article. The protocol adds latency on purpose, and that delay will annoy pairs who optimize for message count. Teams that need a guaranteed hosted runtime, private dependency caches, or production credentials on the probe host will need a different isolation design.

Who should not use this approach

Incident responders who must patch a live failure in minutes should not insert this record gate in front of a hotfix. Teams whose repositories are saturated with secrets should not copy a tree onto a shared or free remote host at all. Regulated environments that forbid third-party model inference should keep probe work on approved machines and ignore any hosted option. Developers who want the agent to own the merge button should pick another workflow rather than weaken the oracle.

The pair kept a narrow surviving decision after discarding an hour of speculative diffs and chat summaries. The agent may probe and draft a rejectable record, then propose a patch only after the local oracle runs. Chat text never becomes the plan, and the disposable host never becomes the repository of record. Teams that need a throwaway probe box can try MonkeyCode's free model access and free server option while keeping the oracle local.

Blind Replay Before Merge: Keep Only the Agent Diff a Clean Environment Recreates

Avery Li — Mon, 07 Sep 2026 03:46:43 +0000

An agent-written patch that lives only inside one long chat session is not a reviewable change for merge. Hidden constraints from that conversation never reach the repository, the failing tests, or the next reviewer. A pairing session that wants a durable result should keep only the diff a second memory-free environment can recreate. The brief, not the transcript, becomes the source of truth for that recreation before anyone discusses merge.

Chat windows quietly store rejected files, private service names, and half-stated architecture that later readers will never see. A senior pairing partner should treat that hidden context as contamination rather than as extra helpful memory for the model. The protocol below is a worked example of that stance, not a report of a named production incident. The two roles are a driver chasing an agent-assisted patch and a senior who refuses to merge from chat history alone.

Pairing setup for a known failing test

The shared codebase is a small HTTP service whose readiness probe still returns 503 under a test that already exists. The driver wants an assistant to edit the health handler and move on quickly. The senior wants a change that someone else could regenerate from the repository without the original thread. Work starts only after both people can describe done in file-level terms on disk.

Until that description exists beside the code, every generated diff stays on a throwaway branch with no merge discussion. The pairing treats speed on the first attempt as optional and replayability on the second attempt as mandatory. That split is the whole method, and the rest of this article only makes it checkable.

What the senior asked, written down immediately

The senior did not open with a cleverer prompt or a longer system message for the same window. The senior demanded answers that a stranger could follow, then wrote those answers into the repository. The recorded questions targeted outcome, verification, blast radius, and isolation, not conversational tone.

Name the file-level outcome that would make this task done without referring to earlier chat turns at all.
Name the test that already fails today, plus the tests that must remain green after the patch lands.
Name every path the agent is forbidden to touch, including settings, lockfiles, and generated folders.
Name the check that proves the second environment never received the first conversation or its cookies.

Those items feel heavy until the first patch depends on a filename the model heard only verbally. After that miss, the written answers become the pairing contract instead of optional notes in a scratch buffer. The driver still gets a first attempt, but that attempt no longer counts as evidence.

Dead ends the pair walked into anyway

The first dead end was asking the original chat to summarize requirements for a fresh session in another window. The summary still smuggled nicknames, skipped the exact error code, and omitted the test command entirely. A second environment that received only that summary produced a broad refactor instead of a readiness fix. The pair learned that a model-written recap is still part of the contaminated thread.

The second dead end was exporting the full transcript and calling the dump a brief for replay. Transcripts include rejected approaches, which many models treat as extra requirements rather than as discarded history. The clean environment then rebuilt a path the senior had already thrown away during pairing. Volume of context was not the missing ingredient; a stable contract was.

The third dead end was comparing the two patches by eye inside the original editor session. Visual memory of the chat hid extra files, renamed tests, and a lockfile bump that nobody had approved. The pair needed a mechanical gate that did not depend on anyone remembering the thread. After that, merge talk required a command exit code, not a vibe that the diffs looked close.

The decision that survived the dead ends

The pair kept one rule after the third failure, and they wrote it at the top of the brief. A patch is mergeable only when a clean environment, given the repository and a short brief, produces a change the existing tests accept. Chat-only diffs remain on a disposable branch even when they look almost identical to the replayed result.

That decision trades a fast first attempt for a replayable second attempt that a later reviewer can understand. It is slower than merging the first green-looking diff from the original window. It is faster than debugging a production miss that only the original model session ever understood. The senior kept the rule because similarity without replay is not regeneration.

Artifact: a blind-replay pack on disk

The pairing writes three files before any second model call starts. They live in the service repository, not in a vendor chat product, and they are labeled here as a proposed pack. None of the files encode a model brand, a quota, or a hardware story, because those details change and should not become the protocol.

The written brief

# brief.md
Task: make GET /health/ready return 200 when this process can serve traffic.
Current failure: tests/test_ready.py::test_ready_ok fails with HTTP 503.
Allowed paths:
- app/health.py
- tests/test_ready.py
Forbidden paths:
- app/settings.py
- any file under migrations/
Done when:
- pytest tests/test_ready.py -q exits 0
- git diff --stat shows only allowed paths
Halt when:
- the model proposes editing forbidden paths
- the same test command fails twice with the same traceback

The brief names outcomes, commands, and halt conditions in language a stranger can execute. It does not narrate earlier pairing banter, rejected filenames, or the senior's asides. A second environment that cannot succeed from this file is telling the pair the brief is still incomplete. Incomplete briefs get revised; they do not get more transcript pasted underneath.

The replay manifest

# replay_manifest.yaml
task_id: health-ready-2026-09-06
brief: brief.md
test_command: pytest tests/test_ready.py -q
allowed_paths:
  - app/health.py
  - tests/test_ready.py
forbidden_globs:
  - app/settings.py
  - migrations/**
max_model_rounds: 3
require_clean_worktree: true

The manifest is deliberately small so the pair can read it during the session without scrolling a policy novel. It freezes the test command and the path contract before anyone invites a model back into the loop. Round limits belong here because a clean environment can still retry its way into a different architecture. The pairing stops at the recorded round count even when the assistant asks for one more try.

A mechanical gate

The following script is a proposed local check, not a measured benchmark against any hosted assistant. It compares the worktree against the path contract, then runs the frozen test command.

# replay_gate.py
from pathlib import Path
import subprocess
import sys
import yaml


def git_changed_files() -> list[str]:
    out = subprocess.check_output(
        ["git", "diff", "--name-only", "HEAD"],
        text=True,
    )
    return [line.strip() for line in out.splitlines() if line.strip()]


def main(manifest_path: str) -> int:
    spec = yaml.safe_load(Path(manifest_path).read_text())
    if spec.get("require_clean_worktree") is False:
        print("replay_gate: refuse to run without a frozen worktree contract")
        return 2
    changed = git_changed_files()
    allowed = set(spec["allowed_paths"])
    forbidden = set(spec["forbidden_globs"])
    extra = [path for path in changed if path not in allowed]
    blocked = [path for path in changed if path in forbidden]
    if extra or blocked:
        print("replay_gate: path contract failed", extra, blocked)
        return 2
    test = subprocess.run(spec["test_command"], shell=True)
    if test.returncode != 0:
        print("replay_gate: tests failed")
        return test.returncode
    print("replay_gate: brief, paths, and tests agreed")
    return 0


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

Run the gate after the second environment finishes, not after the first chat looks convincing in the sidebar.

git status --short
python replay_gate.py replay_manifest.yaml

A zero exit code is the earliest moment the senior will talk about merge. A nonzero exit code sends the pair back to the brief, not back into the original thread to negotiate tone.

Numbered pairing workflow

Write brief.md together, out loud, until the senior can follow it without any remaining chat scrollback.
Freeze the failing test command and the path contract in replay_manifest.yaml before a model is invited back.
Let the first environment propose a patch on a throwaway branch, then park that branch without merging it.
Open a second environment that has the repository, the brief, the manifest, and no transcript at all.
Allow at most the recorded number of model rounds, then stop even if the assistant wants another attempt.
Run python replay_gate.py replay_manifest.yaml on the second environment's worktree and keep the exit code.
Keep the second patch if the gate passes; otherwise revise the brief and repeat the clean run, not the hidden chat.

The first environment is allowed to be messy, speculative, and full of rejected files. The second environment is the only one that earns a merge discussion, because it never saw the contamination. If the two patches disagree, the brief was underspecified, and the pair edits the brief instead of averaging the diffs by hand.

Where a free model and a free server actually help

A blind replay needs a place that has not inherited cookies, chat memory, or editor plugins from the first session. Local reuse of the same assistant window fails that requirement even when the pasted prompt looks new. Isolation is the feature; a second tab in the original product is usually still the original product.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option, which can host that second environment when the pair wants a workspace that does not carry the original thread. The protocol does not depend on a particular model name, hardware story, or quota, and it should keep working if the pair uses another clean machine instead. A pairing group that needs a disposable second workspace can run the same brief there, then keep the gate even if they later switch hosts.

The useful part remains isolation, not branding. If the free server still shares identity with the first chat, the replay is not blind and the gate is theater. Shared identity includes reused threads, cloned plugin state, and briefs that quietly embed the first session's private names.

Limitations the gate will not hide

This protocol does not prove architectural taste or product judgment. Two environments can agree on a clumsy patch that existing tests do not hate, especially when the tests are thin. Tests that were generated inside the first chat must be thrown away before replay, or the second run only proves self-consistency. The gate also cannot see secrets that leaked into the brief, so production hostnames and tokens have to be redacted before anyone copies the pack.

Free shared environments remain the wrong place for proprietary code, customer data, or credentials, because a clean server is still someone else's computer. Round limits stop endless retries, but they do not stop a wrong approach that fits the path contract. Reviewers still have to read the second diff as if a human had typed it, because the gate checks contracts rather than intent.

Who should not use this approach

Teams that already require human-written patches and use models only for comments do not need a second environment for merge. People working in regulated codebases that forbid third-party execution should stay on approved machines and skip hosted replay workspaces. Anyone hoping the replay will replace code review will be disappointed, because a passing gate is not a design review. Drivers who cannot name a failing test yet should write that test first, since a brief without a command is only prose.

What the pairing actually kept

The pair kept the brief, the manifest, the gate, and the second-environment patch that the gate accepted. They discarded the original chat diff even when it looked similar in the editor. Similarity without replay is not evidence that the next reader could regenerate the change from the repository alone.

The senior's last recorded note was short and operational rather than motivational. Merge discussion starts after replay_gate.py exits zero on a workspace that never had the first transcript. That is the decision the pairing kept, and it is the only souvenir from the session that belongs in the tree.