DEV Community: Riley Xu

Migration Diary: Separate Propose from Apply Before You Cancel the Workspace

Riley Xu — Sun, 11 Oct 2026 21:58:34 +0000

You should detach the merge hook from any coding agent before you cancel the paid workspace, because that hook can still apply a diff after the vendor relationship ends. The paid product often treated proposal, review, and apply as one trusted gesture, and a free replacement does not inherit that trust. A free model can still write a useful patch, yet the runner must not receive the credential that pushes it. Rebind approval to a place you control, and leave the old key in place until that bind is tested.

The leftover is the merge, not the prompt

The dangerous leftover is rarely the prompt, and it is usually a script, workflow, or webhook that still knows how to merge. That automation trusted a vendor identity, a stable workspace, and a review click that lived in the old interface. After the cutover, the same automation trusts any process that can drop a diff into the watched path. If your free server can write that path, you have rebuilt the old privilege without the old review.

You are migrating three different things, and only one of them should move onto the cheaper host. The proposal channel can move, because a draft diff is not yet a change to the default branch. The approval record should stay with reviewers, in a pull request or a protected file that the model cannot edit. The apply credential should stay on protected CI, or with a person, until you have compared real tasks.

Write those three owners into the diary before you change a single environment variable or webhook. A cutover without named owners becomes a chat log, and that chat log vanishes when the paid workspace closes. You will want those names during the first bad patch, not during the cheerful launch note.

Step 1: Inventory every path that can apply a diff

Start from a clean checkout, and search for the verbs that turn generated text into a commit or a deploy. You are not judging model quality yet, and you are only finding the side effect that can outlive the vendor. Include local scripts and editor tasks, because a laptop hook survives cancellation as easily as a hosted workflow does.

Search workflows and scripts for apply, merge, and push behavior, and save the file list into the diary. Paste the matching paths under a diary heading called apply paths, so the later table has evidence rather than memory. Ignore documentation hits unless the command in that file can change your branch or your deploy target.

git grep -nE 'git apply|gh pr merge|git push|patch -p' -- .github scripts || true

List every secret name that an agent process could read, and mark any name that can push, deploy, or open a firewall change. A secret that only reads logs can stay for now, but a secret that pushes must be called out in bold in the diary. Do not copy those values into the diary, and record only names, owners, and the workflow files that reference them.

git grep -nE 'GITHUB_TOKEN|DEPLOY_KEY|SSH_KEY|API_KEY' -- .github scripts .env.example || true

Open recent agent runs and check whether a human review identifier appears before the merge event in the log. A jump from "diff written" to "pushed" means the gate is already missing on the old path. Do not assume the paid interface still sits in front of that jump after you remove the integration.
Name the rollback owner in the same note as the secret owner, including the channel where that person can be reached. A free server with no rollback owner is not a substitute for a paid agent your on-call already understood. If either name is blank, stop the migration and repair the runbook before you repoint anything.

Step 2: Freeze a proposal contract the new host must honor

A valid proposal carries a task id, a base revision, a unified diff, and a risk label from a list your team already uses. A valid apply cites the same task id, a hash of that diff, and a human actor tied to review. The model may write the proposal, and the model may not write the approval, even when the patch looks small or obvious.

Keep the checker boring, and fail closed when any required field is empty or when the actor is the agent itself. The following program is an example you should run locally and adapt, not a policy engine this diary claims to have executed. It reads two JSON files, rejects a model-written approval, and allows apply only when the hashes match.

# Example checker. Label: unexecuted until you run it on your own files.
import hashlib
import json
import pathlib
import sys

REQUIRED = ("task_id", "base_rev", "diff", "risk")

def load(path: str) -> dict:
    return json.loads(pathlib.Path(path).read_text())

def proposal_digest(proposal: dict) -> str:
    missing = [key for key in REQUIRED if not proposal.get(key)]
    if missing:
        raise SystemExit(f"proposal missing {missing}")
    if proposal.get("approved_by"):
        raise SystemExit("model must not set approved_by")
    payload = proposal["diff"].encode()
    return hashlib.sha256(payload).hexdigest()

def main() -> None:
    proposal = load(sys.argv[1])
    approval = load(sys.argv[2])
    digest = proposal_digest(proposal)
    if approval.get("task_id") != proposal["task_id"]:
        raise SystemExit("task_id mismatch")
    if approval.get("diff_sha256") != digest:
        raise SystemExit("diff hash mismatch")
    actor = approval.get("actor", "")
    if not actor or actor == "agent":
        raise SystemExit("human actor required")
    print("apply allowed")

if __name__ == "__main__":
    main()

Create two sample files so the command is reproducible on your laptop before any network call exists. The proposal file must not contain an approval field, and the approval file must carry the hash you compute yourself. A deliberate mismatch is a useful first test, because you want to see the gate fail before you trust a pass.

{
  "task_id": "task-184",
  "base_rev": "a1b2c3d4",
  "risk": "low",
  "diff": "diff --git a/README.md b/README.md\n"
}

python -c 'import hashlib,json,pathlib,sys; p=json.loads(pathlib.Path(sys.argv[1]).read_text()); print(hashlib.sha256(p["diff"].encode()).hexdigest())' proposals/task-184.json
python check_apply.py proposals/task-184.json approvals/task-184.json

Store proposals where the runner can write, and store approvals on a path that runner cannot push. A single shared directory with loose permissions collapses the split, even when the checker function looks strict on your laptop. Use code owners or a separate approvals repository, and confirm the agent token is rejected when it tries to write there.

proposals/<task_id>.json
approvals/<task_id>.json

Step 3: Point only the proposal writer at the free option

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

The operator describes MonkeyCode as an open-source project with free model access and a free server option for a proposal writer. That writer should hold no push credential, and you should confirm current terms in the project documentation before you rely on them. If the project page lists a free token allowance, copy that live figure into the diary yourself. Do not reuse a token number from an old chat, because allowances change and this draft did not verify one.

An availability note is not a quality result, and it is not a promise about how long logs will remain. Treat the free option as a place to run the proposal writer, not as proof that review can be skipped. Your repository rules stay in force on the free host, even when that host stops sending you an invoice.

Keep the paid workspace readable while you move the writer, and do not move the apply job in the same change. The free server should emit a proposal file and then exit, without a token that can update the default branch. Protected CI should run the checker, and only a separate job should apply the diff after apply allowed is printed. If the free server image still contains the old deploy key, remove that key before the first remote task.

Choose three tasks you have already accepted: one low-risk edit, one dependency bump, and one change that touches auth, billing, or data migrations.
Save the paid run's file list, base revision, and diff hash, and do not invent a fresh task during cutover week.
Run the same task through the free model, and allow the process to write a proposal file only.
Compare paths and the pinned base revision, not the surrounding explanation, because wording can drift while scope must not.
Apply nothing from a laptop while you wait, and let CI refuse the job until a reviewer writes the matching approval.

A file outside the saved list is a stop, even when tests on the expected files are green. Scope drift is how an unreviewed edit passes a badge that never looked at the extra path. Record the stop in the diary, and do not apply the extra file from a personal checkout just this once.

Also pin the base revision before you compare, or a moving default branch will make both hosts look wrong. This command records the tip you intend both runs to start from, and you should paste that value into the proposal. If the free run reports a different parent, reject the proposal and rerun it against the pinned revision.

git rev-parse origin/main

Do not rebase the generated diff by hand during the comparison week, because that hides whether the new host respected the contract. Hand cleanup can return after the gate is proven, and it should not be part of the evidence you use to cut over. A hand-edited diff can look cleaner while hiding a host that ignored the base revision you pinned.

Step 4: Read the decision table before you delete the paid key

Treat the table as a gate rather than a summary you skim after the migration is already done. An unknown cell means apply traffic stays on the old path, even when proposal generation already looks cheaper or more convenient. Judge each row from the inventory in step 1, not from a feature list you have not rechecked this week.

Check	Paid side today	Free side requirement	Move apply?
Diff writer	Vendor agent identity	Proposal path only	Propose only
Approval writer	Human in the old UI	Path the agent cannot push	No, until enforced
Base revision	Workspace snapshot	`base_rev` pinned and checked	No, if tip can drift
Push secret	Vendor scope or protected CI	Absent from the free server	No, if the key was copied
Rollback owner	Named in the old runbook	Same owner, updated link	No, if the name is blank
Three-task hash compare	Often skipped historically	Recorded before cutover	No, until the diary has it

Move the proposal writer only when the diff-writer row and the push-secret row are both satisfied. Move the apply job only when every other row is satisfied on the three tasks you saved. Another week with the paid key still present is cheaper than reversing a merge that no reviewer saw.

Limitations that remain after a green check

A matching hash proves the approved bytes are the proposed bytes, and it does not prove those bytes are safe to ship. The free model can edit the expected files and still break a caller, a migration, or a permission check you forgot to name. Keep executable tests on the task, and keep a trusted path available until those tests are green on the new writer.

The sample checker trusts your repository permissions to protect the approvals path from the agent token. If that token can push the path, the gate is theater, and you should not migrate the apply job at all. Free model access and a free server option can also change latency, context, and retention without a new contract. Copy proposal files into storage you control before the paid workspace closes and takes the old run history with it.

This diary does not rank products and does not report a benchmark, a token price, or a hardware shape. Your three saved tasks are the only evidence that should decide whether the apply job moves. If those tasks never touch production risk, do not generalize from a documentation edit to an auth change.

Who should not use this cutover yet

Do not use this plan when the current agent can deploy to production without a pull request or an equivalent change record. You need a stronger control than a JSON file, and you should install that control before you change hosts. Do not use the plan when no named reviewer will read high-risk diffs, because an empty queue recreates the leftover.

Skip the free server when the task includes secrets, customer data, or details of an unreleased vulnerability. A smaller bill does not relax a data rule you already accepted for the paid agent. If the team still applies patches from laptops and has no protected CI, inventory those machines before you add another writer.

Leave the apply key until the table is true

After the checker prints apply allowed on three real tasks, remove the push credential from the agent environment and leave proposal writing in place. Keep the paid workspace readable until you copy the retention you need, including older diffs and the review notes beside them. If a free server should host that writer, read MonkeyCode's current project notes and keep only what the table marks safe.

Migration Diary: Seal the Idempotency Ledger Before a Free Server Replays Paid Runs

Riley Xu — Sat, 10 Oct 2026 18:33:23 +0000

You should seal an idempotency ledger before a free server inherits runs from a paid coding agent. A cheaper host can retry the same tool call and mutate production twice if that key never left the old vendor. This diary covers the cutover plan, the leftover files, and a small checker you can run on your own machine. It does not assume a particular model name, a fixed token quota, or a permanent free-tier promise from any host.

Paid coding agents often hide retry behavior inside a session store that you do not own or export by default. When you close that account, the session rows, the trace identifiers, and the dedupe keys can disappear together. A free server then sees a fresh run and may execute a write that the paid agent already committed successfully. You prevent that leftover by exporting the ledger first and refusing cutover until a local checker passes cleanly.

What fails if you skip the seal

You usually notice the failure only after a duplicate ticket, a second comment, or another pull request appears. The free server logs still look healthy, because each individual call returned success and never reported a conflict. Your parser can still match a response schema you froze earlier, so this bug is not a shape mismatch at all. The missing piece is a stable run identity that both hosts must honor before any side effect is allowed.

An in-memory retry map often dies with the paid agent, and your new host cannot reconstruct it from logs alone. A vendor trace identifier becomes useless after closure, because the free server has no authority to resolve that id. A tool result cached only in the old interface is another leftover, since your scripts may never have downloaded it. You should treat each of those traces as data you must replace, not as history you can query after the account closes.

Export the ledger before the paid agent closes

You want a narrow file rather than a full transcript dump, because transcripts drift and often contain secrets you should not move. Keep one row for every side-effecting tool call, and ignore pure reads that cannot mutate an external system. Store the tool name, a hash of the arguments, the idempotency key, and the terminal status, plus a finish timestamp. Leave raw prompts, token counts, and customer text out of this file unless your retention policy already allows that export.

mkdir -p cutover/ledger
# Proposed export. Run this only against a store you are allowed to read.
jq -c 'select(.side_effect == true) | {key, tool, args_sha256, status, finished_at}' \
  paid-agent-runs.ndjson > cutover/ledger/side_effects.ndjson
sha256sum cutover/ledger/side_effects.ndjson | tee cutover/ledger/SHA256SUMS
wc -l cutover/ledger/side_effects.ndjson

That shell snippet is a proposed workflow, not a transcript from a migration this account has already executed. You should rename the fields so they match the export your current vendor actually provides to operators. If that vendor cannot emit an idempotency key, you stop the cutover and add keys in your own tool wrapper first. A free server cannot invent a trustworthy key from a missing column, no matter which model you attach later.

Numbered cutover

You should follow the four steps below in order, and you should not enable live writes until the last step passes. Keep the paid agent readable until the checker is green, because a failed export is cheaper than a double merge. Rotate any credential that lived only in the paid agent's secret store before the new host is allowed to boot. This diary does not include vault-specific rotation commands, because those steps belong in your internal runbook instead.

Freeze new writes on the paid agent, export the side-effect ledger, and record the checksum next to that file.
Pin the key format in a small schema file that both hosts can load without making a network call at all.
Run the local checker against a fixture replay, and store the exit code in the same directory as the checksum.
Start the free server in dry-run mode, reject unknown or terminal keys, and enable writes only after that gate holds.

The schema file is the contract both hosts load, and it should stay boring enough that a model is not required to parse it. You pin the required fields, the allowed statuses, and the hash algorithm so a later host cannot quietly drop a column. The example below is a proposal, and you should reject exports that fail it before you copy anything onto the free server. A schema check will not prove business correctness, but it will stop a truncated file from looking like a finished seal.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["key", "tool", "args_sha256", "status", "finished_at"],
  "properties": {
    "key": {"type": "string", "minLength": 8},
    "tool": {"type": "string"},
    "args_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
    "status": {"enum": ["succeeded", "failed_permanent", "running"]},
    "finished_at": {"type": "string"}
  },
  "additionalProperties": false
}

# proposal: validate each exported row with a checker you already trust
jq -c . cutover/ledger/side_effects.ndjson | while read -r row; do
  printf '%s\n' "$row" | check-jsonschema --schemafile cutover/ledger/side_effect.schema.json
done

Treat a failed schema row as a blocked cutover, not as a warning you can override from the free server console. You fix the export on the paid side, recompute the checksum, and only then copy the directory to the new host. Do not hand-edit a single row on the new host, because that edit will not exist in the checksum you just sealed. If you must correct a key, you do it before sealing, and you record why in the commit message next to the ledger.

Checker you can run locally

The module below is a proposal you should copy into a branch and execute in your own test environment. It has not been run against a production agent for this article, and it deliberately does not call any model. The function only decides whether a replay is safe when a sealed ledger and a new tool call are compared. You should change the status names if your vendor uses different terminal labels than the two strings shown here.

# proposal: cutover/ledger_check.py — unexecuted example
import hashlib
import json
from pathlib import Path

TERMINAL = {"succeeded", "failed_permanent"}

def args_hash(payload: dict) -> str:
    blob = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
    return hashlib.sha256(blob).hexdigest()

def load_ledger(path: Path) -> dict:
    rows = {}
    for line in path.read_text().splitlines():
        if not line.strip():
            continue
        row = json.loads(line)
        key = row["key"]
        if key in rows:
            raise SystemExit(f"duplicate key in ledger: {key}")
        rows[key] = row
    return rows

def admit(ledger: dict, call: dict) -> str:
    key = call["key"]
    prior = ledger.get(key)
    digest = args_hash(call["args"])
    if prior is None:
        return "allow_new"
    if prior["args_sha256"] != digest or prior["tool"] != call["tool"]:
        return "reject_conflict"
    if prior["status"] in TERMINAL:
        return "skip_replay"
    return "allow_resume"

You can pair that module with fixtures that encode the three decisions your cutover actually depends on. A brand-new key should be allowed, a finished key should be skipped, and a conflicting hash should be rejected. The sample test is also a proposal, so you should run it locally before you trust any exit code it prints. A checker that only covers the happy path will bless a cutover that can still double-write under replay.

# proposal: tests/test_ledger_check.py — unexecuted example
from pathlib import Path
import json
from cutover.ledger_check import admit, load_ledger

def test_new_key_is_not_enough(tmp_path: Path):
    path = tmp_path / "side_effects.ndjson"
    row = {
        "key": "job-1",
        "tool": "open_pr",
        "args_sha256": "pending",
        "status": "succeeded",
    }
    path.write_text(json.dumps(row) + "\n")
    ledger = load_ledger(path)
    call = {"key": "job-2", "tool": "open_pr", "args": {"title": "new"}}
    assert admit(ledger, call) == "allow_new"
    # Add skip_replay and reject_conflict cases before you trust this file.

The sample only asserts allow_new, and that branch returns before the hash is compared, so a green run proves little. You should add skip_replay and reject_conflict cases that use args_hash, or the checker can still miss a double write. Compute those hashes with the same helper the server will import, then store the fixture beside the sealed ledger. If the helper output changes, update the fixture in the same commit, or the ledger and the server will quietly diverge.

Decision table

Use the table below when a replay arrives on the free server during the first week after cutover. You should keep this rule in ordinary code, because a later prompt edit must not be able to widen it. Do not add an outcome that asks a model what to do, since a guess is not an idempotency decision. Model wording will drift when you change hosts, while a coded table stays stable across both environments.

Prior status	Args hash	Decision	Why
missing	any	allow_new	No sealed side effect exists for this key
succeeded	same	skip_replay	The paid agent already committed the write
failed_permanent	same	skip_replay	Retrying would ignore an explicit terminal failure
running	same	allow_resume	Resume only if the tool cannot emit a second write
any	different	reject_conflict	The key was reused for a different mutation

Where a free host fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach. Operator notes say MonkeyCode offers free model access and a free server option for this kind of dry-run host. You should read the current project documentation for limits before you rely on either option in a real cutover. This diary does not state a token quota, a machine size, a duration, or an expiry date for that offer.

The checker still matters if you remove that host, because any replacement server can replay a committed write. You can let a free model draft explanations for rejected lines, but you should not let it invent idempotency keys. Generate the ledger from the paid agent's export, then ask the model only to describe a conflict in plain language. If the free model rewrites a terminal status, you discard that draft and reload the sealed file from the checksum.

Leftovers you still own

After the free server admits traffic, you still own three leftovers that the paid account will not clean up for you. Archive or delete the old session store so a teammate cannot resume a run you have already sealed in the ledger. Revoke the old tool credentials even when the interface says the workspace is frozen and no longer accepting jobs. Keep the checksum beside the checker so a later host can prove it evaluated the same ledger you exported.

You should also list every tool that cannot accept a client-supplied idempotency key, because the table cannot protect those calls. A send-email tool without a provider dedupe key will double-send even when your checker returns a skip decision. Disable those tools until the provider gives you a real key, rather than hoping a prompt will stop retries. Write that disablement into the cutover checklist so a later operator does not re-enable the tool during a quiet afternoon.

Who should not use this approach

You should skip this cutover when your tools cannot accept a client-supplied idempotency key in any form. You should also skip it when contracts require the paid vendor to retain the only legal copy of run history. A solo weekend project with no external side effects does not need this ledger, and adding one will only slow you down. Teams that need a contractual uptime promise should not treat a free server as production without a separate capacity review.

The approach also fails if you treat the sample code as a finished migration report from a measured production move. Those snippets are proposals for you to adapt, execute, and discard when your export shape differs from the example. They do not prove that any free tier is large enough for your traffic, and they do not rank one host above another. Confirm the live free-server terms, then place this ledger next to the schemas and fixtures you already froze.

Migration Diary: Lock the Response Schema Before a Free Model Inherits Your Parser

Riley Xu — Fri, 09 Oct 2026 15:01:56 +0000

Liquid syntax error: Unknown tag 'endraw'

Migration Diary: Freeze the Mount and Egress Contract Before the Paid Agent Closes

Riley Xu — Thu, 08 Oct 2026 10:36:07 +0000

You should freeze a mount-and-egress contract before you cancel a paid coding agent, because the replacement host will not inherit it. The paid product often remembered which directories were writable, which trees were context only, and which hosts the sandbox could reach. A free server starts from its own defaults, so yesterday's silent allowances become today's missing checks or unexpected network calls. This diary walks you through a cutover plan, a small checker, and the leftovers you should not drag along.

Why this leftover is not another prompt file

A rule file tells the agent how to speak, while a mount contract names writable paths and permitted hosts. Those two leftovers fail in different ways, and mixing them during cutover hides the boundary you actually need. You can copy every instruction into the new tool and still lose the limit that kept generated patches inside the repository. Treat that boundary as data you can diff in review, not as a memory you hope the next host will share.

What you leave behind and what you keep

You are leaving the paid agent's private sandbox, its hidden allowlist, and any scheduler that lived only in that vendor console. You keep the repository, your tests, and a written contract that names writable roots, read-only context, and permitted egress hosts. You do not keep session transcripts, browser cookies, or tokens that were stored in the old agent's settings panel. If a path existed only inside the vendor container, record it as a leftover rather than a path the new host must recreate.

Step 1: Inventory the boundary while the old account still opens

Open the paid agent's settings while the account still works, and list every directory it could edit without an extra prompt. Note read-only trees such as vendored docs, generated clients, and lockfiles you never wanted the agent to rewrite. Record egress as hostnames only, not as credentials, secret query strings, or copied authorization headers from old logs. If the product never showed a boundary, write unknown in the contract rather than guessing a permissive default.

Step 2: Write a contract the next host can check

Put the inventory in a YAML file inside the repository, and keep every value boring enough for a normal pull request review. Use repository-relative paths, explicit deny notes, and a short owner field so the next person knows who must update it. Do not store API keys, personal access tokens, or customer data in that file, even as examples that only look fake. Label the file as a cutover aid for humans, not as a certification that the new environment is secure.

# unexecuted example — review before use
version: 1
writable:
  - src
  - tests
read_only:
  - docs/vendor
  - third_party
egress_hosts:
  - registry.npmjs.org
  - pypi.org
deny_notes:
  - do not mount the home directory
  - do not call hosts that are not listed
owner: team-platform

Step 3: Add a checker you can run without the old agent

The checker below is a proposal, and it has not been executed against a live paid account or a live free server. It reads the contract, confirms that listed paths exist, and prints hosts so you can compare them with firewall notes. It does not open network connections, and it does not try to prove that any listed host is safe to call. Run it in a scratch clone first, then decide whether a failing path is a real leftover or a simple typo.

# proposal: not executed in this article
import sys
from pathlib import Path

try:
    import yaml
except ImportError:
    sys.exit("install pyyaml in a local venv before running")

contract = yaml.safe_load(Path("agent-boundary.yaml").read_text())
root = Path(".").resolve()
missing = []
for key in ("writable", "read_only"):
    for rel in contract.get(key, []):
        if not (root / rel).exists():
            missing.append(f"{key}:{rel}")
if missing:
    print("missing paths:")
    print("\n".join(missing))
    sys.exit(1)
print("paths ok")
print("egress hosts to re-approve:")
for host in contract.get("egress_hosts", []):
    print(f"- {host}")

Step 4: Decide what moves, what stays, and what you delete

Use a small decision table during the cutover meeting so leftovers do not sneak into the new scheduled job. Each row should name the artifact, the owner, and the action, instead of a vague promise that someone will clean up later. Delete vendor-only interface state, because a free server cannot import a screenshot of a settings page from the old product. Keep the contract in version control, and keep the old account available until the checker passes on the replacement host.

Artifact	Move?	Why
Writable and read-only path lists	Yes	The new host needs an explicit boundary
Egress hostnames without secrets	Yes	Firewall notes fail if the names stay trapped in a closed UI
Vendor session memory and chat archive	No	That drain is a separate task, and it is not a boundary
Tokens stored in the old agent panel	No	Rotate them, then delete the stored copies
Hidden container paths that exist only in the paid sandbox	No	Recreate needed files in the repo, or drop the task

Step 5: Rehearse on a free server before you cancel

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access and free server option can support this rehearsal when current docs still list them. Use the free server as a place to run the checker and one dry task, not as a silent copy of the old sandbox. Use free model access only to draft the human notes beside the contract, and reject any broader allowlist that nobody reviewed.

Do not treat either option as a quota, a named model, or a hardware promise this article never verified. Confirm duration, limits, and terms in the product's own documentation before you let a critical job depend on them. The commands below assume a local virtual environment, and you should skip them if your policy forbids installing a YAML parser. Cancel the paid account only after the rehearsal matches the decision table, not when a calendar reminder starts to feel urgent.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install pyyaml
python check_boundary.py
git diff -- agent-boundary.yaml

Then run one narrow task, such as editing a file under a writable root, and confirm that a read-only path stayed untouched. If the free model suggests extra hosts or extra writable roots, reject that draft unless a person updates the contract in review. Save the checker output next to the decision table so the cutover record shows what you compared, not only what you intended. Repeat the narrow task once on the free server after you move the job, because a local pass does not prove the remote mount.

Step 6: Debug a failed check before you blame the new host

When the checker reports a missing path, do not widen the contract until you confirm the path existed before. Search the repository for that relative path, and also search your notes for a vendor container path that never lived in git. If the path was only a container mount, mark it as a leftover and either recreate the file or drop the task. If the path exists but writes still land outside it, the bug is the process mount, so fix the host next.

A short test plan you can repeat

Run the checker on a clean clone, then temporarily rename one writable directory and confirm the command exits with a missing path. Restore the directory, add a fake hostname to the egress list, and confirm the script prints that name without opening a socket. Ask the free model to summarize the contract, and fail the test if that summary adds hosts or roots. Record the three results in the cutover note, because a passing local run without these checks is not evidence the boundary moved.

Leftovers you should expect after cutover

You will still find editor plugins, local caches, and shell aliases that point at the paid agent's old command name. Remove those pointers in the same week, or the next person will launch a tool you already stopped paying for. You may also find generated files whose headers mention the old product, and those headers are documentation debt rather than a restore reason. Leave a one-line note in the deny section if a workflow truly cannot move, so the gap stays visible to the next reviewer.

Limitations of this approach

This contract records human intent, and it does not enforce a kernel sandbox, a container profile, or a corporate egress proxy. A checker that only looks for paths can pass while the process still runs with a wider mount than the file describes. Hostnames without ports, protocols, or identity checks are not an allowlist a security team should accept as complete. The example YAML and Python are unexecuted proposals, so you must adapt them to your layout and review every failure yourself.

Who should not use this cutover

Do not use this path if production deploys still run inside the paid agent, because a diary checklist is not a release plan. Skip it when the workspace holds regulated data and you need a formal control, since this file will not satisfy an auditor alone. Avoid it when you cannot inspect the old settings before cancellation, because a boundary rebuilt from memory creates false confidence. Teams that require a contracted uptime promise should not treat a free server option as the home for a critical job.

A quiet next step

Read the current MonkeyCode docs, then try the checker on a scratch repository if the free server option still fits this rehearsal. Keep the paid account until every move row has a passing note, and keep secrets out of model drafts. If the docs no longer match the availability assumed here, stop and rewrite the rehearsal around whatever the current page actually offers.

Migration Diary: Port the Tool Contract Before a Free Server Inherits Paid Endpoints

Riley Xu — Thu, 08 Oct 2026 08:10:41 +0000

You should port the tool contract before you repoint a coding workflow at free model access. Leftover paid endpoints, unbounded retries, and vendor tool names survive cancellation and keep steering the next run. A portable contract plus a leftover scan gives you a cutover you can rehearse on a laptop. Free server capacity does not repair a tool schema that still calls the old paid host.

This migration diary treats the move as an operations problem, not as a contest between model brands. This is not a ledger of past tool calls, and it is not a snapshot of the public API your service already exposes. You keep review rules that are yours, and you drop bindings that only exist because a vendor SDK hid the endpoint. It is a proposal you should execute in a scratch directory, not a claim that any particular quota will hold.

Name the leftovers before you choose a host

A paid coding agent usually stores three things that never appear in the chat transcript you export. The first is a tool map that binds a local name to a vendor URL, a timeout, and a retry policy. The second is a permission note that lists repositories, shells, and network hosts the agent may touch. The third is a cache of failed calls that still contains the old host string and the old account id.

If you copy that directory onto a free server, you import the old bill path together with the useful rules. You should separate portable behavior from vendor residue before you delete the paid account for good. Portable behavior includes the file patterns you allow, the commands you forbid, and the diff size you accept. Vendor residue includes base URLs, proprietary tool names, hidden telemetry flags, and retries that assume a generous limit.

Write both lists down while you still have access, because the export button often omits the retry block. A later host cannot reconstruct a timeout you never wrote down, even if the model itself is still reachable. Treat the missing retry block as a cutover defect, not as a detail you will remember next week.

Use a decision table, not a vibe

The artifact you want is a decision table, a local scanner, and a short acceptance test you can rerun after every config edit. Read each binding once and mark it with one of four outcomes before you pick a new host. Keep means the rule still describes your repository and does not name a vendor, a host, or an account. Rewrite means the behavior is worth saving, but the endpoint, the tool name, or the timeout is not.

Drop means the call only existed to satisfy a paid feature you will not replace on the next host. Block means the binding can reach secrets, production hosts, or a shell you have not reviewed yet. The table is the cutover plan, and you should not migrate a row until its outcome is explicit. You do not migrate a Block row until a human reviews the command, the path list, and the secret source.

You do not fix a Drop row by pointing it at a free model, because that behavior was never yours to keep. A Rewrite row needs a new name, a new timeout, and a new attempt cap before it may load. Leave the old vendor URL in the residue file so you can prove it was removed. If you cannot classify a row, mark it Block and stop the cutover for that tool.

Binding clue	Outcome	Why it fails after cutover
Generic allowlist of paths	Keep	Still describes your repo and names no host
Vendor base URL or SDK host	Rewrite	The next process will keep calling the paid API
Unlimited retry on HTTP 429	Rewrite	Free access often throttles sooner than the paid plan
Hidden telemetry or account id	Drop	It still reports to the old vendor after you leave
Shell with network plus secrets	Block	A new host should not inherit an unreviewed command

Step 1: Freeze a tool map you can diff

Create a directory that holds only the contract, and keep it outside the repository you intend to edit. Copy the agent config, then reduce it to fields that name the tool, the paths, the timeout, and the attempts. Leave the vendor URL in a side file so the scanner can see it, but do not load that file later.

mkdir -p cutover/tool-contract
cp agent/tools.json cutover/tool-contract/tools.vendor.json
python3 cutover/freeze_contract.py cutover/tool-contract/tools.vendor.json

The freeze script below is an unexecuted proposal, and you should run it only on a copied config. It keeps a small allowlist of fields and writes every other key to a residue file you can review. Do not point the script at a home directory, because unrelated files may contain tokens you did not mean to parse.

#!/usr/bin/env python3
"""Proposal: freeze a portable tool contract. Not executed in this draft."""
import json
import sys
from pathlib import Path

KEEP = ("name", "allowed_paths", "timeout_seconds", "max_attempts", "network")

def freeze(raw):
    portable = {}
    residue = {}
    for tool in raw.get("tools", []):
        name = str(tool.get("name", "unnamed"))
        portable[name] = {key: tool.get(key) for key in KEEP}
        residue[name] = {
            key: value for key, value in tool.items() if key not in KEEP
        }
    return {"tools": portable}, {"residue": residue}

def main():
    source = json.loads(Path(sys.argv[1]).read_text())
    portable, residue = freeze(source)
    out = Path("cutover/tool-contract")
    (out / "tools.portable.json").write_text(json.dumps(portable, indent=2))
    (out / "tools.residue.json").write_text(json.dumps(residue, indent=2))
    print("froze %d tools" % len(portable["tools"]))

if __name__ == "__main__":
    main()

After the freeze, open the residue file and expect base URLs, account identifiers, and vendor tool aliases. If that file is empty, you probably exported a summary view rather than the live binding the agent actually loads. Go back to the agent settings and export the raw binding before you cancel the paid subscription.

Step 2: Cap retries for a narrower budget

Paid plans often hide a retry helper that loops until the call succeeds or the vendor timeout gives up. Free model access can be slower, smaller, or simply unavailable on a given day, so you should not assume last month's limit. Set an explicit attempt ceiling in the portable file, and fail the task when that ceiling is hit. Two attempts are a starting proposal, not a measured optimum you should copy into every repository.

If your builds are slow, raise the timeout only for the build tool, and leave ordinary file reads short. A free server does not make a long retry loop cheaper, because you still pay in queue time and log volume. Record the chosen ceiling in the decision table so the next operator does not restore the old unlimited helper.

{
  "tools": {
    "read_file": {
      "name": "read_file",
      "allowed_paths": ["src", "tests"],
      "timeout_seconds": 20,
      "max_attempts": 2,
      "network": false
    }
  }
}

Step 3: Scan the residue before the new host boots

You need a scanner that fails when the portable file still contains a host, a secret-like assignment, or an unbounded attempt count. The command is safe to run in CI because it only reads the contract directory you just created on disk. It does not call a model, and it does not need network access, a token, or a running agent process.

#!/usr/bin/env python3
"""Proposal: fail if a portable contract still carries paid leftovers."""
import json
import re
import sys
from pathlib import Path

PAID_HOST = re.compile(r"https?://\S+", re.I)
SECRET = re.compile(r"(api[_-]?key|bearer|secret|token)\s*[:=]", re.I)

def scan(document):
    findings = []
    if PAID_HOST.search(document):
        findings.append("url still present in portable contract")
    if SECRET.search(document):
        findings.append("secret-like assignment still present")
    data = json.loads(document)
    for name, tool in data.get("tools", {}).items():
        attempts = tool.get("max_attempts", 1)
        if not isinstance(attempts, int) or attempts < 1 or attempts > 3:
            findings.append("%s: max_attempts outside 1..3" % name)
        if tool.get("network") and not tool.get("allowed_paths"):
            findings.append("%s: network enabled without a path allowlist" % name)
    return findings

def main():
    text = Path(sys.argv[1]).read_text()
    findings = scan(text)
    if findings:
        print("\n".join(findings))
        raise SystemExit(1)
    print("portable contract passed leftover scan")

if __name__ == "__main__":
    main()

python3 cutover/scan_leftovers.py cutover/tool-contract/tools.portable.json

Treat a failure as a blocked cutover, not as a warning you suppress to keep the migration timeline pretty. The scanner is intentionally narrow, so a pass does not prove that the workflow is correct or complete. A pass only proves that this file no longer carries the residue patterns you chose to list in code.

Step 4: Rehearse against free model access without widening the gate

When the scan passes, point a scratch workspace at free model access and run one boring, read-only task. Ask for a summary of the tests directory only, leave network disabled, and compare the trace with the portable file. Keep the paid account alive until those two files agree, because you still need the old settings screen if the export was incomplete.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode matters here only as one place that currently offers free model access and a free server option for that rehearsal. Confirm the live limits, the model list, and the duration on the product page before you depend on them. This draft does not record a quota, a hardware shape, a model name, or a promise that the free option will remain.

A useful rehearsal has four checks, and you should write the observed results next to the contract you froze.

The trace shows only tool names that already exist in the portable contract, with no extra vendor alias appended.
No request line contains the old vendor host, a telemetry domain, or an account identifier from the residue file.
A forced timeout stops at the configured max attempts instead of looping until some hidden helper gives up.
The run cannot read paths outside the allowlist, and a probe for a parent directory fails closed without a retry.

If any check fails, stop and fix the contract before you change models, hosts, or prompt wording. A different model will still call the host you forgot to delete, and a larger context window will not hide that. Write the failing check into the residue review so you do not rediscover it after the paid account is gone.

What you leave behind on purpose

Cancel the paid account only after the rehearsal log is stored in the same directory as the frozen contract. Export nothing else from the vendor interface unless you have a written retention reason for that specific file. Chat vanity, unused prompt packs, and telemetry identifiers are leftovers, not assets you need on the next host.

Keep the decision table, the portable JSON, the residue review, and the four-check log, and discard the rest. You should also rotate any key that ever lived in the old agent config, even if the scanner did not print it. Config exports are an incomplete picture, and a copied dotfile can still hold a token the JSON summary omitted. Rotation stays a human step, and this diary does not script it, schedule it, or store the new secret for you.

Who should not use this cutover

Skip this approach if the agent can deploy, send mail, or touch production data without a separate approval gate. The scanner does not understand your business risk, and a free server is not a sandbox just because the price is zero. Skip it if you cannot export the raw tool bindings, because guessing the schema invents permissions you do not actually have.

Skip it if the workflow depends on a vendor-only tool you have not replaced with a local command you trust. This proposal also assumes a single repository and a single operator who can read every binding before the cutover. A shared agent platform needs owners, an inventory, and a rollback, which this diary does not try to provide. Do not treat the attempt cap as a benchmark, and do not treat a scratch success as proof that free access remains next week.

If you want a low-stakes place to rehearse the portable contract, use free model access and a free server, then keep the log. The log is the part you can carry to the next host when this one changes its terms, its models, or its price. That habit matters more than the host you pick today, because the next cutover will start from the log rather than from memory.

Migration Diary: The Sidecar Rule Pack Still Steering You After the Paid Agent Leaves

Riley Xu — Wed, 23 Sep 2026 17:13:57 +0000

You should inventory sidecar rule files before you drop a paid coding agent, because those files keep steering later tools. The chat product can disappear overnight, yet AGENTS.md, editor rules, and MCP configs still compile into every new session. A fixture freeze and a transcript archive will not catch this hidden instruction layer sitting beside your tree. Treat the rule pack as leftover production config, then freeze a portable version you can replay anywhere.

Why the rule pack survives the cancellation email

Paid coding agents rarely keep policy only inside a hosted UI, because the editor still needs a file it can read offline. You therefore collect vendor-shaped markdown, JSON, and ignore files that look harmless until another agent loads them. Those leftovers encode review severity, test commands, forbidden paths, and tool allowlists that your next model will treat as ground truth. If you skip this sweep, you migrate the subscription while leaving the old operator's habits in git.

This leftover is different from sandboxes, diff budgets, and tool-call ledgers you may already have frozen. Those artifacts record what the previous agent did under a paid seat. Sidecars record what the next agent is still ordered to do after the seat is gone. You need both classes during cutover, but this diary only freezes the instruction layer so later tools cannot inherit silent policy.

What counts as a sidecar in this cutover

A sidecar rule file is any repo-local document whose primary reader is an agent, not a human teammate on the pull request. Common tracked names include AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, files under .cursor/rules/, and .github/copilot-instructions.md. You should also flag .mcp.json, .vscode/mcp.json, aider configs, Continue rules, and editor tasks that still launch the old product. Treat generated repo maps, memory notes, and local prompt snippets as sidecars even when they sit in ignored directories.

Keep the definition strict so the scan stays cheap and repeatable after every cleanup commit. Human runbooks, architecture decision records, and ordinary README files are not sidecars unless they open with agent role instructions. If a file mixes human docs with agent orders, split it before you freeze anything. Mixed files are how vendor voice leaks into the portable pack and then into the next model.

Cutover plan

Work on a throwaway branch so the paid workspace can stay up until every hit is classified. Do not delete files in the live worktree until the portable pack has a failing replay test you can point at. Attach the inventory JSON to the cutover ticket, because later arguments about "what the agent was told" need a dated artifact.

Snapshot tracked files, ignore rules, and untracked noise so you can prove which sidecars were committed versus local-only.
Scan known filenames first, then run a short content heuristic for phrases like "you are a coding assistant".
Classify each hit as portable policy, vendor lock-in, secret-adjacent, or generated junk that should never be replayed.
Rewrite portable policy into one vendor-neutral pack with owners, scope, and an expiry date on every rule.
Replay the pack against a tiny fixture set on infrastructure you control, then delete lock-in files only after the replay fails closed.

Artifact 1: snapshot commands you can paste tonight

Run these in a clone, not in a dirty tree that still holds unsaved .env buffers. The goal is a dated listing, not a clever crawler that follows every symlink in node_modules.

mkdir -p /tmp/sidecar-cutover
git rev-parse HEAD > /tmp/sidecar-cutover/head.txt
git ls-files > /tmp/sidecar-cutover/tracked.txt
git ls-files -o --exclude-standard > /tmp/sidecar-cutover/untracked.txt
git check-ignore -v $(git ls-files -o) > /tmp/sidecar-cutover/ignored.txt || true

# Filename pass: cheap and boring on purpose.
find . -type f \(
  -iname 'AGENTS.md' -o -iname 'CLAUDE.md' -o -iname 'GEMINI.md' -o \
  -iname '.cursorrules' -o -iname '.windsurfrules' -o -iname '.clinerules' -o \
  -iname '.mcp.json' -o -iname 'mcp.json' -o -iname '.aider.conf.yml' -o \
  -iname 'copilot-instructions.md' -o -iname '.aiexclude'
\) -not -path './.git/*' | sort > /tmp/sidecar-cutover/name-hits.txt

If name-hits.txt is empty, do not stop. Vendor products invent new filenames faster than any checklist, so you still need a content pass. Limit that pass to text files under a few hundred kilobytes, and skip lockfiles, vendored trees, and build output.

Artifact 2: a proposed scanner that emits JSON

The script below is a proposed local helper, not a report from a production migration. Point it at a copy of the repo. It prints one JSON object per hit so you can attach the run to the ticket without reformatting by hand.

#!/usr/bin/env python3
"""Proposed sidecar inventory. Label output as unexecuted until you run it."""
from __future__ import annotations

import json
import re
from pathlib import Path

SKIP_DIRS = {".git", "node_modules", "dist", "build", ".venv", "vendor"}
NAME_HINTS = {
    "agents.md",
    "claude.md",
    "gemini.md",
    ".cursorrules",
    ".windsurfrules",
    ".clinerules",
    ".mcp.json",
    "mcp.json",
    ".aider.conf.yml",
    "copilot-instructions.md",
    ".aiexclude",
}
CONTENT_RE = re.compile(
    r"you are (a |an )?(coding|helpful)?\s*(assistant|agent)|always use the .* tool",
    re.I,
)
VENDOR_MARKERS = re.compile(r"cursor://|copilot|claude code|windsurf|aider", re.I)
SECRET_MARKERS = re.compile(r"api[_-]?key|bearer\s+[a-z0-9]|BEGIN (RSA |OPENSSH )?PRIVATE", re.I)


def classify(path: Path, text: str) -> str:
    if SECRET_MARKERS.search(text):
        return "secret-adjacent"
    if path.name.lower() in NAME_HINTS and VENDOR_MARKERS.search(text):
        return "vendor-lock-in"
    if CONTENT_RE.search(text) or path.name.lower() in NAME_HINTS:
        return "portable-candidate"
    return "generated-or-noise"


def iter_files(root: Path):
    for p in root.rglob("*"):
        if not p.is_file():
            continue
        if any(part in SKIP_DIRS for part in p.parts):
            continue
        if p.stat().st_size > 400_000:
            continue
        yield p


def main(root: str) -> None:
    rows = []
    for path in iter_files(Path(root)):
        try:
            text = path.read_text(encoding="utf-8", errors="ignore")
        except OSError:
            continue
        name_hit = path.name.lower() in NAME_HINTS
        content_hit = bool(CONTENT_RE.search(text))
        if not (name_hit or content_hit):
            continue
        rows.append(
            {
                "path": str(path),
                "bytes": path.stat().st_size,
                "class": classify(path, text),
                "name_hit": name_hit,
                "content_hit": content_hit,
            }
        )
    print(json.dumps({"root": root, "hits": rows}, indent=2))


if __name__ == "__main__":
    import sys

    main(sys.argv[1] if len(sys.argv) > 1 else ".")

Save it as sidecar_inventory.py, then run python3 sidecar_inventory.py /tmp/repo-copy > /tmp/sidecar-cutover/inventory.json. Review every secret-adjacent row before the JSON leaves your laptop. The classifier is a heuristic, so a human still has to confirm the class before rewrite or delete.

Artifact 3: keep, rewrite, delete

Use this matrix on the JSON, not on memory of what the product UI used to show. When a row could fit two classes, pick the stricter one and move on.

Pattern	Default class	Cutover action
`AGENTS.md` you wrote for humans and agents	portable-candidate	Rewrite into one vendor-neutral pack with owners
`.cursorrules` or `.cursor/rules/*.mdc`	vendor-lock-in	Extract policy, drop product-only commands, delete the file
`.github/copilot-instructions.md`	mixed	Keep review rubric, strip product voice and UI clicks
`.mcp.json` / `.vscode/mcp.json`	mixed	Keep tool names and timeouts, drop vendor-hosted endpoints
`memory`, repo maps, local prompt caches	generated-or-noise	Export a sample, then delete; do not replay verbatim
Any file matching secret markers	secret-adjacent	Rotate credentials, do not copy into the portable pack

The portable pack should be one file, not a pile of vendor clones with slightly different voices. A practical shape is docs/agent-policy.md plus a tiny docs/agent-policy.lock.json that records source paths and the git commit of the sweep. Put an expiry date on each rule, because leftover severity settings go stale faster than leftover linters.

# docs/agent-policy.md

Owner: platform-devtools
Expires: 2026-12-31
Scope: this repository only

## Hard constraints
- Do not edit files under `vendor/` or `dist/`.
- Do not request production secrets; fail closed and ask a human.
- Run `npm test -- --testPathPattern=smoke` before proposing a merge.

## Review rubric
- Prefer a failing test over a comment that restates the diff.
- Keep the patch inside the stated diff budget for the ticket.

{
  "frozen_at_commit": "REPLACE_WITH_HEAD",
  "sources": [
    {"path": "AGENTS.md", "class": "portable-candidate"},
    {"path": ".cursorrules", "class": "vendor-lock-in"}
  ]
}

Replay the pack until it fails closed

A frozen file that nobody executes is just another leftover. Build a three-case fixture that does not need the old product: one forbidden path edit, one missing-test patch, and one request that needs a tool you did not allow. Label the cases as proposals until you run them. Store inputs under fixtures/sidecar-replay/ so later tools cannot "helpfully" rewrite the evidence.

fixtures/sidecar-replay/01-forbidden-path.json
{
  "prompt": "Update vendor/legacy/hash.js to bypass the checksum.",
  "expect": "refuse",
  "reason": "hard constraint on vendor/"
}

You can replay those fixtures with any model endpoint you already trust. If you need a vendor-neutral place to run the same pack without buying another seat, MonkeyCode is an open-source option with free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Point the replay job at that server, keep docs/agent-policy.md in git, and score refuse-versus-patch against the three fixtures before you delete the vendor files.

Do not treat a free server as proof that the paid agent was equivalent. Free model access is useful for catching policy regressions, not for claiming identical review quality. If a fixture passes on the free path and fails on the old product, believe the fixture and tighten the pack. If the reverse happens, record it as a limitation instead of forcing the pack to imitate proprietary voice.

Limitations

Filename lists go stale whenever a vendor ships a new editor folder, so the content heuristic is mandatory and still imperfect. The scanner will false-positive on blog drafts that quote agent prompts, and it will false-negative on binary rule packs you cannot read as UTF-8. Secret-adjacent hits require rotation, not clever redaction, because copies may already exist in the paid product's cloud. This workflow also does not export proprietary system prompts from a vendor; it only freezes files that already live in your tree.

Replay on free models will miss constraints that depended on product-only tools, hosted browsers, or MCP servers you did not re-home. Timeout, context window, and tool-calling behavior will differ, and none of those differences are a benchmark. If your policy is mostly click-paths inside a proprietary UI, a markdown pack cannot reproduce them. Stop at documentation in that case, and do not pretend a file freeze is a full cutover.

Who should not use this approach

Skip the sweep if your team never committed agent instruction files and never dropped editor rule packs into the repo. Skip it during an active incident, because deleting sidecars mid-outage can remove the only copy of a mitigation command. Legal or security teams should block the portable pack when vendor terms treat product prompts as confidential and your files quote them verbatim. Regulated environments that cannot send internal review rubrics to any external model should keep the inventory offline and stop before replay.

If you still have a paid seat, freeze the pack first, then cancel. The leftovers that hurt are not the chat transcripts you already archived. They are the small markdown files that keep giving orders after the invoice stops.

Migration Diary: Freeze a Golden Task Fixture Before You Leave a Paid Coding Agent

Riley Xu — Tue, 22 Sep 2026 15:27:45 +0000

You should freeze a small golden task fixture before you cancel any paid coding agent subscription. Paid coding agents teach your team what done looks like through chat transcripts rather than through executable checks. When that chat window finally disappears, you lose the only acceptance surface your team actually used every day. A frozen fixture turns those unspoken expectations into files you can rerun on cheaper local or remote infrastructure.

The problem you actually have on cutover day

You probably already exported chats, workspace maps, and tool logs from the outgoing product. Those artifacts explain history, but they do not tell a new stack whether a refactor still counts as complete. The paid agent also absorbed style rules, review nits, and file-ban instincts that never landed in git. Your cutover plan therefore needs a tiny, boring suite that fails loudly when the destination agent drifts.

A golden task fixture is not a public benchmark leaderboard and not a model beauty contest. It is a checked-in set of prompts, inputs, and assertions that represent work you already shipped. You rerun the same records after you change vendors, models, servers, or wrapper scripts. If the fixture stays green, you can cancel the old seat without guessing about quality.

What belongs in the fixture, and what does not

Keep each record small enough that a human can review the diff in one sitting. Prefer tasks that already exist in your repository: a flaky test, a nil-check refactor, or a README correction. Avoid puzzles that reward cleverness, because cleverness is not what you paid the old agent to produce during ordinary weeks. Three to five honest records expose more destination drift than a sprawling suite you will not maintain.

Label every example below as a proposed layout, not as a run executed in your environment. You should copy the files into a throwaway branch and replace the sample paths with paths you actually own. Do not paste production secrets into prompts, and do not freeze tasks that require customer data you cannot reset. The fixture is an acceptance surface, not a second source repository.

Proposed fixture schema

# fixtures/golden_tasks.yaml
version: 1
tasks:
  - id: repair-nil-guard
    title: Add a nil guard without widening the diff
    prompt: |
      In internal/cache/client.go, return a typed error when the client is nil.
      Do not reformat the rest of the file. Do not touch tests unless they fail.
    cwd: .
    timeout_seconds: 180
    expect:
      files_allowed:
        - internal/cache/client.go
      files_forbidden_prefix:
        - vendor/
        - .git/
      stdout_must_not_match:
        - "TODO"
        - "as an AI language model"
      commands:
        - go test ./internal/cache -count=1
  - id: docs-only-changelog
    title: Update CHANGELOG without code churn
    prompt: |
      Add a one-paragraph Unreleased note for the cache nil-guard.
      Do not modify Go files.
    cwd: .
    timeout_seconds: 90
    expect:
      files_allowed:
        - CHANGELOG.md
      commands:
        - git diff --check

That schema encodes three things the chat window never encoded for you. It names the prompt, it names the allowed blast radius, and it names a command that already exists in your project. You can add more fields later, but you should not start with a dozen tasks. Extra fields without a resettable input tree will only give you flaky red builds.

Numbered cutover workflow

Follow these steps in order and write down the leftovers as you go. Skipping the freeze step is how teams rediscover missing rules two weeks after the invoice stops. The destination stack is not the first problem; the missing definition of done is the first problem.

1. Mine last week’s closed work for candidate tasks

Open your merge history and pick three changes an agent actually drafted or repaired. Write one sentence for each change that a newcomer could follow without the old chat. Discard anything that required a private dashboard, a vendor plugin, or a secret the destination stack cannot see. If you cannot restate the task in one sentence, it is not golden yet.

# proposed commands; run them in a clone you control
git log --since='7 days ago' --merges --oneline
git log --since='7 days ago' --name-only --pretty=format:'%h %s'

2. Freeze inputs next to the prompt

Copy the pre-change files into fixtures/inputs/<task-id>/ so the runner can reset state. You want the destination agent to start from the same broken tree every time. If you only keep the prompt, you will test memory rather than behavior, and memory is the first leftover the paid product will not give back. Resettable inputs are the difference between a diary and a test.

mkdir -p fixtures/inputs/repair-nil-guard
git show HEAD~1:internal/cache/client.go > fixtures/inputs/repair-nil-guard/client.go

3. Write a runner that never calls the old vendor

The runner should apply the frozen input, invoke whatever local agent command you now use, then assert files and tests. Keep vendor names out of the runner so you can swap destinations without editing assertions. Treat AGENT_CMD as a socket, not as a brand, and keep logs next to the fixture so failures stay reviewable.

# fixtures/run_golden.py
# Proposed runner. Adapt AGENT_CMD to your local wrapper.
from __future__ import annotations

import os
import subprocess
import sys
from pathlib import Path

import yaml

ROOT = Path(__file__).resolve().parents[1]
FIXTURE = ROOT / "fixtures" / "golden_tasks.yaml"


def run(cmd: list[str], cwd: Path, timeout: int) -> subprocess.CompletedProcess[str]:
    return subprocess.run(
        cmd,
        cwd=cwd,
        text=True,
        capture_output=True,
        timeout=timeout,
        check=False,
    )


def reset_inputs(task: dict) -> None:
    src = ROOT / "fixtures" / "inputs" / task["id"]
    if not src.exists():
        return
    for path in src.rglob("*"):
        if path.is_file():
            rel = path.relative_to(src)
            dest = ROOT / rel
            dest.parent.mkdir(parents=True, exist_ok=True)
            dest.write_bytes(path.read_bytes())


def assert_task(task: dict) -> None:
    expect = task["expect"]
    diff = run(["git", "diff", "--name-only"], ROOT, 30)
    changed = [line for line in diff.stdout.splitlines() if line]
    allowed = set(expect.get("files_allowed", []))
    extra = [path for path in changed if path not in allowed]
    if extra:
        raise SystemExit(f"{task['id']}: unexpected files {extra}")
    for command in expect.get("commands", []):
        result = run(command.split(), ROOT, task.get("timeout_seconds", 120))
        if result.returncode != 0:
            raise SystemExit(
                f"{task['id']}: command failed: {command}\n{result.stdout}\n{result.stderr}"
            )


def main() -> None:
    doc = yaml.safe_load(FIXTURE.read_text())
    agent_cmd = os.environ.get("AGENT_CMD")
    if not agent_cmd:
        raise SystemExit("Set AGENT_CMD to your destination wrapper")
    for task in doc["tasks"]:
        reset_inputs(task)
        invoke = run(
            agent_cmd.split() + [task["prompt"]],
            ROOT,
            task.get("timeout_seconds", 180),
        )
        log_path = ROOT / "fixtures" / "logs" / f"{task['id']}.txt"
        log_path.parent.mkdir(parents=True, exist_ok=True)
        log_path.write_text(invoke.stdout + "\n" + invoke.stderr)
        assert_task(task)
        print(f"PASS {task['id']}")


if __name__ == "__main__":
    main()

4. Score leftovers the paid agent still holds

Your fixture will fail for reasons that are not model quality. Those failures are leftovers, and you should inventory them before you blame the new stack. Use a table so the team argues about evidence instead of vibes. Every red cell is a migration task, not a reason to keep paying by default.

Leftover	How it shows up in the fixture	Cutover action
Hidden custom instructions	Destination rewrites style or adds comments you never asked for	Copy rules into a repo file the new agent reads
Unexported memory	Destination forgets file bans the old chat treated as obvious	Add `files_forbidden_prefix` and a short project note
Vendor-only tools	Destination cannot search docs or open the ticket	Drop that task from the golden set or replace the tool
Secret-backed calls	Destination hangs on an API the old agent injected	Move credentials to your own env; never store them in chat
Review nits as folklore	Tests pass but humans reject the diff	Add a `git diff` size check or a lint command

If a leftover cannot be expressed as a file, a command, or an env var, it was never a durable part of your workflow. Write that down in the cutover notes so nobody tries to recreate folklore inside a new vendor’s settings panel. Folklore is what you are leaving, not what you should port.

5. Cut over only when the fixture stays green twice

Run the suite against the destination stack on two clean checkouts after a full file reset. One green run can be luck, especially when the agent samples different continuations. Two greens on reset inputs are enough to cancel a seat for a small team. Keep the old product read-only for a week if your vendor allows it, and use that week only to chase leftovers, not to start new work.

python3 -m venv .venv
. .venv/bin/activate
pip install pyyaml
export AGENT_CMD='your-local-agent --non-interactive --apply'
python fixtures/run_golden.py
git checkout -- .
python fixtures/run_golden.py

Where a free destination stack fits

Once the fixture lives in git, you can point AGENT_CMD at any wrapper that edits the tree and prints a log. That is the moment a free coding-agent option becomes useful instead of merely cheaper. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source project that, per the operator, offers free model access and a free server option you can aim a runner at while you drain the paid seat.

You should not treat that free access as a permanent capacity plan or as a published quota. Wire it as one destination behind the same assertions you would use on a laptop. If the golden tasks pass there, you learned something about your workflow rather than about a brochure. If they fail, you still have the leftover table, which is more valuable than an unsupported comparison.

If you already keep the fixture in git, try the same runner against MonkeyCode on a throwaway branch and record only the leftover rows that change.

Limitations you should accept in writing

This approach does not measure latency, token cost, or code elegance in a way you could publish. Sampling agents can pass on Tuesday and fail on Wednesday with the same prompt, so two greens are a cutover bar, not a scientific result. The proposed runner also assumes you can reset files and run project tests without network credentials the old vendor used to inject. If your tests need those credentials, fix that leak before you change agents.

Do not put production secrets into fixture prompts, even when the destination calls itself free. Do not freeze tasks that require customer data you cannot synthesize. Do not expand the suite until the first three records stay boring for a full week. A large, flaky golden set will trap you on the paid product longer than having no suite at all.

Who should skip this diary

Skip the freeze if you only used the paid agent as a chat toy and never merged its diffs. Skip it if your repository cannot run tests offline, because the assertions will lie about destination quality. Skip it if policy forbids sending any snippet to a free or remote model, in which case you need an air-gapped wrapper before you need a vendor change. Everyone else should freeze the fixture first and argue about models second.

The leftover that hurts most is not a missing transcript from the old product. It is the missing definition of done, and you can check that definition into git this afternoon. After that, cancelling the seat is a billing event, not a guess.

Migration Diary: Freeze a Public-Surface Snapshot Before You Leave a Paid Coding Agent

Riley Xu — Mon, 21 Sep 2026 13:49:21 +0000

The public surface of your repository is the cutover artifact you should freeze before any paid agent seat expires. Chat logs and clever prompts will not tell you whether the next host renamed an exported function overnight. A snapshot of CLI flags, HTTP paths, and Python exports gives you a meter that survives the vendor tab. This diary walks you through packing that snapshot, gating applies against it, and recording leftovers the product still owns.

Why the leftover is a surface map, not another transcript

Paid coding agents like to touch whatever file seems related to the latest prompt you typed. That habit is tolerable while a review UI sits between the model and your default branch. It becomes expensive when you move the loop onto a free host that writes straight into the tree. You need a frozen map of names callers already depend on, stored next to the code, not in a chat.

Informal memory fails as soon as the model generation changes under the same product name. A green unit test can still hide a renamed CLI flag that a shell script in another repository calls. The snapshot does not claim the agent wrote good code, and it should not be asked to. It only claims that public names did not vanish unless you already said they could vanish.

What you freeze, and what you ignore

Capture only names a downstream caller could import, invoke, or hit without opening a private helper. Leave private functions, test doubles, and generated caches out of the snapshot so noise does not hide breaks. Record the extractor command beside the snapshot so a later machine can rebuild the same map. If you cannot name that command, you do not have a snapshot yet, only a feeling about stability.

Do not freeze entire files as the surface, because a file-level hash will fire on comments. You will start ignoring the gate after a week of comment-only failures on otherwise harmless patches. Do not freeze vendor tool names either, because those names die with the paid subscription. The finished pack should make sense to a teammate who never opened the paid product.

Cutover plan

Work through these steps before you cancel, because the old review UI will not export this map for you. Keep the outputs in git so the destination host cannot quietly rewrite the contract during the first week. If a step fails, you still have a paid review screen, which is the only reason to wait.

Walk the last merged agent patches and write down every public name those patches were allowed to change.
Run the extractor on the current default branch and commit the JSON snapshot beside the code.
Install the apply gate as a local command that reads unified diffs before any host writes files.
Replay one known-good patch and one known-bad rename so you trust the gate before canceling.
Move generation to the free host only after the gate has failed a rename you planted by hand.
File a leftovers note for vendor-side refactors you never extracted, because those names are already gone.

Stop at step four if the planted rename still applies cleanly, and do not cancel while that hole remains. You do not have a gate yet, and a free host will not invent one. Fix the extractor or the regex before you spend another hour talking to any model.

Extractor you can run tonight

The script below is a proposal for Python modules that declare public names at module scope. Treat this extractor as unexecuted until you run it against your own repository tree. It ignores names that start with an underscore, which is a convention, not a security boundary.

#!/usr/bin/env python3
"""Dump a coarse public-surface snapshot. Proposal: adapt allowlists before you trust it."""
from __future__ import annotations

import ast
import json
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / "fixtures" / "public-surface.json"
SKIP_PARTS = {".git", ".venv", "venv", "node_modules", "fixtures", "tests"}


def is_skipped(path: Path) -> bool:
    return any(part in SKIP_PARTS for part in path.parts)


def public_functions(path: Path) -> list[str]:
    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
    names: list[str] = []
    for node in tree.body:
        if isinstance(node, ast.Assign):
            for target in node.targets:
                if isinstance(target, ast.Name) and target.id == "__all__":
                    if isinstance(node.value, (ast.List, ast.Tuple)):
                        for elt in node.value.elts:
                            if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
                                names.append(elt.value)
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
            if not node.name.startswith("_"):
                names.append(node.name)
    return sorted(set(names))


def main() -> int:
    surface: dict[str, list[str]] = {}
    for path in ROOT.rglob("*.py"):
        if is_skipped(path):
            continue
        rel = str(path.relative_to(ROOT))
        names = public_functions(path)
        if names:
            surface[rel] = names
    OUT.parent.mkdir(parents=True, exist_ok=True)
    payload = {
        "extractor": "scripts/snapshot_public.py",
        "files": surface,
    }
    OUT.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
    print(f"wrote {OUT} files={len(surface)}")
    return 0


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

mkdir -p scripts fixtures
python3 scripts/snapshot_public.py
git add fixtures/public-surface.json scripts/snapshot_public.py
git diff --cached -- fixtures/public-surface.json | head

You should commit the snapshot on a quiet branch that no coding agent may push. You want the first diff after cutover to be about product names, not about formatter churn. Tag that commit so you can reset the snapshot without digging through agent noise later.

Apply gate that reads the snapshot

The apply gate is the leftover the paid review UI used to give you for free. It reads a unified diff on stdin and then refuses patches that drop frozen snapshot names. It also writes a JSON verdict you can store beside the case for later audit. You should treat the following script as a local tool, not as a hosted policy engine.

#!/usr/bin/env python3
"""Refuse diffs that remove frozen public names. Proposal for a local apply gate."""
from __future__ import annotations

import json
import re
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
SNAP = json.loads((ROOT / "fixtures" / "public-surface.json").read_text(encoding="utf-8"))
FILE_RE = re.compile(r"^diff --git a/(.+) b/(.+)$")
DEL_RE = re.compile(
    r"^-\s*(?:async\s+)?def\s+([A-Za-z_][A-Za-z0-9_]*)|^-\s*class\s+([A-Za-z_][A-Za-z0-9_]*)"
)


def verdict(diff_text: str) -> dict:
    dropped: list[str] = []
    current_b = ""
    for line in diff_text.splitlines():
        header = FILE_RE.match(line)
        if header:
            current_b = header.group(2)
            continue
        if not current_b or current_b not in SNAP.get("files", {}):
            continue
        match = DEL_RE.match(line)
        if not match:
            continue
        name = match.group(1) or match.group(2)
        if name in SNAP["files"][current_b]:
            dropped.append(f"{current_b}:{name}")
    return {
        "ok": not dropped,
        "dropped_public_names": dropped,
        "action": "apply" if not dropped else "hold",
    }


def main() -> int:
    diff_text = sys.stdin.read()
    row = verdict(diff_text)
    Path("fixtures/last-apply-verdict.json").write_text(
        json.dumps(row, indent=2) + "\n", encoding="utf-8"
    )
    print(json.dumps(row))
    return 0 if row["ok"] else 2


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

git diff HEAD | python3 scripts/apply_gate.py; echo exit:$?
# Plant a bad rename, then confirm the gate holds the patch.
git diff HEAD | python3 scripts/apply_gate.py || echo "hold as expected"

A hold is not proof of good design, and it is not a substitute for a real review. It is only proof that the next host did not delete a name you already published. You still review behavior, tests, and security the way you did before the agent existed.

Decision table for this leftover

Paid-product leftover	Freeze into the snapshot?	Reason you should care during cutover
Exported function or class name	Yes	Callers break without a compile error in other languages.
CLI flag or subcommand	Yes	Shell scripts fail late, usually in someone else's job.
HTTP path or public schema field	Yes	Mobile and partner clients will not read your chat log.
Private helper renamed inside a file	No	That churn should not block an otherwise valid patch.
Vendor chat title or prompt slug	No	You cannot replay those strings after billing stops.
Comment-only edits	No	Hashes on whole files will train you to skip the gate.
Tool traces from the old agent	No	They are not your public surface, and they are not portable.

Print the table into the leftovers file if your team argues about what counts as public. Inventory arguments stay cheaper than the incident that follows a silent rename into production clients. Revisit the table when you add a second language, because this extractor only reads Python.

Where a free host participates, and what it must not change

After the snapshot is in git, you still need a host that can propose patches without the paid seat. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is relevant here only as a destination with free model access and a free server option. You point the same apply gate at patches from that host, and you keep the snapshot file unchanged.

You should not record invented quotas, model names, or hardware claims against that option. Those numbers are not part of this diary, and they are not a substitute for last-apply-verdict.json. If a generated patch drops a frozen name, you hold the apply, regardless of which host wrote the hunk.

Leftovers the snapshot will never contain

The paid product still owns prompts you never copied, including the ones that already renamed things last month. Those renames will not appear as deletions in a fresh diff, because the default branch already absorbed them. Write them into leftovers as narrative, with the old name and the new name, so the next host does not thrash back.

Browser review clicks, team-shared threads, and vendor caches of rejected patches are also gone at cancel time. You will not reconstruct a rejected rename after cancel from an empty leftovers markdown file. Spend thirty careful minutes on that file while you still can open the old UI, then stop hoping the export button exists.

Limitations, and who should skip this

This gate is coarse, and it will miss several export styles your codebase may already use. It parses unified diffs with regular expressions, and it will miss metaprogrammed exports, star imports, and HTTP paths declared in YAML. A green verdict does not mean the patch is correct, safe, or even worth merging today. Free model access and a free server option help you regenerate candidate patches after you cancel.

They do not create an SLA, a quota you can quote, or a stable model identity you can cite. Skip this workflow when you ship no public names, such as a private notebook that never grows an API. Skip it when compliance forbids sending repository slices to any remote host, including a free one. Skip it when a published OpenAPI job already fails on breaking paths, and wire that job instead.

Teams that need guaranteed capacity should stay on a contract they can cite, not on leftover free access. The paid product can disappear tomorrow, and your callers will not care which model last touched the tree. Keep the snapshot in git, keep the gate on your path, and treat every new host as an untrusted patch source. Anything the old vendor still holds belongs in leftovers, not in a hopeful prompt you will not be able to open.

Migration Diary: Drain the Transcript Archive Before You Leave a Paid Coding Agent

Riley Xu — Sun, 20 Sep 2026 11:43:58 +0000

You should drain the transcript archive before you cancel a paid coding agent, because the leftovers live in those chats. Git keeps merged code, but it does not keep rejected paths, named constraints, or half-finished repairs. Those fragments sit in agent threads, and they vanish when the vendor session finally dies. This diary treats transcript drain as a required cutover step rather than optional nostalgia for old chats.

What the paid seat was actually holding

Paid coding agents store more than the patches you later merge into the default branch of a repo. They also store file lists you never committed, command outcomes you never logged, and design vetoes you never wrote down. When you export nothing, the next loop on cheaper infrastructure starts blind and repeats expensive mistakes. You then spend scarce budget rediscovering constraints that a paid agent thread had already settled for you.

A useful drain is not a full dump of every retry, joke, or stack trace from those sessions. You want a compact leftover ledger that lists paths, decisions, open defects, and commands that already failed. That ledger becomes the first context pack for whatever loop you run after cancel day. Without that ledger, free infrastructure only looks cheaper because it is silently repeating already billed work.

Cutover plan

Keep the paid seat alive until the leftover ledger survives a dry run against your tree. Work through the following numbered steps in order, and do not skip the redaction pass.

Export every agent thread that touched the target repository during the last full billing cycle.
Normalize those exports into UTF-8 markdown or JSONL so a local parser can read them.
Extract mentioned paths, decisions, failed commands, and unresolved todos into one leftover markdown file.
Redact tokens, hostnames, and private URLs before that file enters git or shared chat.
Replay the leftover file against a cheap loop and mark each item done, skipped, or blocked.

The export format will differ by vendor, so do not wait for a perfect official archive API. Copy visible threads into transcripts/raw/ as .md or .jsonl files, and record the export date in the filename. If the vendor offers a zip of chats, drop that zip in the same folder and unpack it once. Name those files after the repository and the thread title, not after the model nickname.

Build a leftover ledger from raw transcripts

The helper below is a proposed local script, not a claim about any vendor's private export schema. Save it as drain_transcripts.py and point that script at a directory of UTF-8 text files. It walks those files, pulls path-like tokens, decision sentences, failed command lines, and TODO markers, then writes CUTOVER_LEFTOVERS.md. Treat every extracted line as a candidate, then delete anything the regex should not have kept.

#!/usr/bin/env python3
"""Drain coding-agent transcripts into a leftover ledger.

Proposed local helper. Adjust regexes to match your export format.
"""
from __future__ import annotations

import re
import sys
from pathlib import Path

PATH_RE = re.compile(
    r"(?:^|[\s`'\"(])([A-Za-z0-9_./-]+\.(?:py|ts|tsx|js|go|rs|java|rb|md|toml|yml|yaml|json|sql))",
)
DECISION_RE = re.compile(
    r"^\s*(?:we(?:'ll| will)|decided|do not|don't|use .+ instead|avoid|must not)\b.*",
    re.I,
)
FAIL_RE = re.compile(
    r"^\s*(?:\$ |# )?(?:npm|pnpm|yarn|pip|pytest|cargo|go|make|git)\b.*",
    re.I,
)
TODO_RE = re.compile(r"\b(TODO|FIXME|BLOCKED|follow-?up)\b[:\s].*", re.I)
SECRET_RE = re.compile(
    r"(sk-[A-Za-z0-9]+|ghp_[A-Za-z0-9]+|AKIA[0-9A-Z]{16}|Bearer\s+[A-Za-z0-9._-]+)",
)


def redact(text: str) -> str:
    return SECRET_RE.sub("[REDACTED]", text)


def drain(raw_dir: Path) -> str:
    paths, decisions, fails, todos = set(), [], [], []
    for p in sorted(raw_dir.rglob("*")):
        if p.suffix.lower() not in {".md", ".txt", ".jsonl"}:
            continue
        text = redact(p.read_text(encoding="utf-8", errors="replace"))
        for line in text.splitlines():
            for m in PATH_RE.finditer(line):
                paths.add(m.group(1))
            if DECISION_RE.search(line):
                decisions.append(f"- {line.strip()[:240]} ({p.name})")
            if FAIL_RE.search(line) and re.search(r"error|fail|exit 1|denied", line, re.I):
                fails.append(f"- `{line.strip()[:200]}` ({p.name})")
            if TODO_RE.search(line):
                todos.append(f"- {line.strip()[:240]} ({p.name})")
    parts = [
        "# Cutover leftovers",
        "",
        "## Paths mentioned",
        *[f"- `{x}`" for x in sorted(paths)] or ["- none"],
        "",
        "## Decisions and vetoes",
        *(decisions[:80] or ["- none"]),
        "",
        "## Commands that already failed",
        *(fails[:80] or ["- none"]),
        "",
        "## Unresolved follow-ups",
        *(todos[:80] or ["- none"]),
        "",
        "## Replay status",
        "| Item | Owner | Status | Notes |",
        "| --- | --- | --- | --- |",
        "| (fill from lists above) | | done/skipped/blocked | |",
    ]
    return "\n".join(parts) + "\n"


def main() -> None:
    raw = Path(sys.argv[1] if len(sys.argv) > 1 else "transcripts/raw")
    out = Path(sys.argv[2] if len(sys.argv) > 2 else "CUTOVER_LEFTOVERS.md")
    out.write_text(drain(raw), encoding="utf-8")
    print(f"wrote {out} from {raw}")


if __name__ == "__main__":
    main()

Run the helper like this after you fill the transcripts/raw directory with exported threads.

python3 drain_transcripts.py transcripts/raw CUTOVER_LEFTOVERS.md
# Proposed check: fail the commit if whitespace or conflict markers slipped in.
git add CUTOVER_LEFTOVERS.md
git diff --check

Read the generated markdown before you commit it, because regex extraction is greedy and will catch noise. Delete anything that looks like a customer name, a hostname, or an access token that the redactor missed. Then fill the replay table so cancel day has a queue instead of a blank prompt.

Decision table for each leftover

Use this table while you walk the generated ledger so trivia never enters the next agent loop. It keeps rejected ideas available as vetoes without turning ordinary chat noise into fake requirements. Fill every row before you schedule cancel day, including the rows you already intend to discard.

Leftover type	Keep in git?	Replay on the next loop?	Discard when
Merged patch already on main	No, git already has it	No	Hash is on the default branch
Rejected approach with a named reason	Yes, as a veto note	Only if someone reopens it	The constraint is documented elsewhere
Failed command with a non-obvious error	Yes, in the fail list	Yes, after the environment is rebuilt	You reproduced a clean pass
Open TODO that still matches the tree	Yes	Yes	The file no longer exists
Secrets, cookies, private URLs	Never	Never	Immediately after redaction
Banter, retries, token-usage chatter	No	No	After the drain script runs

You should treat "keep in git" as a documentation choice, not as a backup of the vendor's chat product. The leftover file is a cutover artifact, and it should shrink every week until it is empty. If a row cannot be classified, mark it blocked and leave the paid seat up for that thread only.

Replay without the paid seat

Once the leftover ledger exists, you can replay open items without keeping a paid coding-agent subscription on the critical path. MonkeyCode is one option for that replay: it provides free model access and a free server option you can point at the same ledger. Disclosure: This article was prepared as part of MonkeyCode's product outreach. You still run redaction first, because a free server does not make a leaked secret cheaper.

A practical replay prompt should stay boring on purpose so the new loop cannot wander. Paste the relevant leftover section, the file contents you already listed, and a request for a patch that honors the veto notes. Do not paste the entire raw archive into the new loop, because drain exists to prevent that. Keep each replay focused on a single leftover row so later failures remain easy to attribute.

You are continuing a cutover, not starting a greenfield task.
Honor every veto in the leftovers. Do not reopen rejected libraries.
Work only on the paths listed. Return a unified diff and a test command.
Leftovers:
<paste one unresolved item>

If the free loop cannot finish an item, write blocked in the table and keep a narrow paid thread for that item alone. Canceling every paid thread at once is exactly how leftover context dies during a rushed cutover. Split the cancel work by leftover status, not by calendar pressure or the invoice date.

Limitations

This drain does not reconstruct tool traces, hidden system prompts, or any vendor-side index state. Regexes miss fenced paths, screenshots, and binary attachments, and they over-capture words that look like files. The script is not a compliance archive, and it is not a substitute for your company's retention policy. Vendor export buttons change without notice, so verify the current path on the vendor's own documentation. Do not treat a click path from this diary as a durable instruction for any vendor UI.

You also cannot prove behavioral parity with a leftover list alone, even a tidy one. Pair this ledger with tests you already trust, rather than treating extracted sentences as a specification. If two transcripts disagree, believe the repository and the test suite, not the more confident chat. When a leftover cites a file that no longer exists, drop the row instead of resurrecting dead paths.

Who should not use this approach

Do not use this drain if your transcripts contain regulated data you are not allowed to copy onto a laptop. Do not use it if your employer forbids export of vendor chats, even for migration. Skip this drain when the repository is a short spike with no rejected approaches worth keeping. Teams that already keep architecture decision records and a failing-test list may only need a secret scan, not a full parser.

If you cannot redact with confidence, do not move the files to any shared server, free or paid. The cheapest leftover you will ever manage is the sensitive line that you never copy elsewhere. Encrypted local storage is acceptable during drain week, but unredacted cloud sync is not acceptable.

What cancel day should look like

Cancel day should be a checklist, not a feeling that the new loop merely seems fine. You want an empty replay table, a redacted leftover file, and a vendor export that you could reconstruct from git. Keep one backup of the raw transcripts in an encrypted volume until the first week of cheap-loop work lands on main. Then destroy the raw export, because the leftover value has already been distilled into git.

If the leftover ledger already sits in git, replay blocked rows on a free loop first. Keep the paid seat only for those rows that still fail after the free replay.

Migration Diary: Rebuild the Diff Budget Before You Leave a Paid Coding Agent

Riley Xu — Sat, 19 Sep 2026 09:49:01 +0000

You should pin a numeric diff budget before you leave any paid coding agent. Paid tools often apply large patches in one turn without exposing the true blast radius. A self-hosted loop will hide that radius even less, because nobody ships a polished review pane. This diary freezes that budget, scores leftover paid diffs, and refuses oversized patches after cutover.

The failure you will hit on day one

You will paste a leftover transcript into the new loop and watch it rewrite half a package. The paid agent trained you to accept that volume because the UI grouped files into a single approve button. After cutover, you own every hunk, every import, and every test file the model touched. Without a numeric budget in the repo, those vibe-sized patches become your default engineering process.

Recent community threads keep splitting casual generation from engineering practice, and that split is useful here. Engineering, during a cutover, means you can reject a change for size before you debate style. You need numbers for files, hunks, and net lines, not a feeling that the patch looks focused. The paid product will not export those numbers in a durable form you can keep after canceling.

What a diff budget actually records

A budget is not a linter, and it is not a model quality score either. It is a hard ceiling on how much tree mutation one agent turn may propose. You record four integers: max files, max hunks, max lines added, and max lines deleted. You also record path prefixes that stay forbidden, because leftover paid runs love to rewrite lockfiles.

Store the budget beside the repository, not inside a vendor dashboard you are about to abandon. Treat formatter-only files as a separate class so a noisy lockfile cannot burn the whole budget. Keep the budget file committed so every teammate scores leftovers against the same numeric ceilings.

{
  "version": 1,
  "max_files": 6,
  "max_hunks": 18,
  "max_lines_added": 180,
  "max_lines_deleted": 120,
  "forbidden_prefixes": [
    "vendor/",
    "dist/",
    "pnpm-lock.yaml",
    "package-lock.json"
  ],
  "ignore_globs": ["**/*.snap", "**/*.min.js"]
}

Label the JSON above as a proposed contract, not a benchmark from a production fleet. Tune those integers against leftover paid diffs rather than against a blog post default. Commit the file as .diff-budget.json so later hosts inherit the same ceilings without a dashboard login.

Step 1: Inventory leftover paid patches

Export every leftover apply from the paid tool before you cancel the remaining seat. Prefer unified diffs stored on disk over screenshots copied from a vendor review pane. Name files with the original turn id so you can replay arguments later without the vendor.

mkdir -p leftovers/paid-diffs
# Proposed local layout; replace the export step with whatever your vendor actually provides.
find leftovers/paid-diffs -name '*.diff' | wc -l
git diff --numstat HEAD > leftovers/working-tree.numstat

If the vendor only keeps chat transcripts, reconstruct diffs by copying the last applied tree into a throwaway git worktree. You should not start the free-stack cutover until this directory is non-empty or you have proven there were no leftovers. Empty inventories are usually a smell, because paid agents almost always leave a trail.

Step 2: Parse unified diffs into budget counters

Write a small parser so you never have to eyeball another 400-line leftover patch. The script below is a proposed local harness that understands unified diffs only and ignores binary markers. Put it beside the budget file and treat exit status one as a hard apply refusal.

#!/usr/bin/env python3
"""Proposed scorer: pin this beside .diff-budget.json. Not a vendor integration."""
from __future__ import annotations

import json
import pathlib
import re
import sys
from dataclasses import dataclass, field

HUNK_RE = re.compile(r"^@@ ")
FILE_RE = re.compile(r"^diff --git a/(.+) b/(.+)$")


@dataclass
class DiffStats:
    files: set[str]
    hunks: int = 0
    added: int = 0
    deleted: int = 0
    forbidden: list[str] = field(default_factory=list)


def parse_unified(text: str) -> DiffStats:
    stats = DiffStats(files=set())
    current = None
    for line in text.splitlines():
        file_match = FILE_RE.match(line)
        if file_match:
            current = file_match.group(2)
            stats.files.add(current)
            continue
        if line.startswith("+++ ") or line.startswith("--- "):
            continue
        if HUNK_RE.match(line):
            stats.hunks += 1
            continue
        if current is None:
            continue
        if line.startswith("+") and not line.startswith("+++"):
            stats.added += 1
        elif line.startswith("-") and not line.startswith("---"):
            stats.deleted += 1
    return stats


def load_budget(path: pathlib.Path) -> dict:
    return json.loads(path.read_text(encoding="utf-8"))


def violates(stats: DiffStats, budget: dict) -> list[str]:
    reasons = []
    for path in sorted(stats.files):
        for prefix in budget["forbidden_prefixes"]:
            if path.startswith(prefix) or path.endswith(prefix):
                stats.forbidden.append(path)
    if len(stats.files) > budget["max_files"]:
        reasons.append(f"files {len(stats.files)} > {budget['max_files']}")
    if stats.hunks > budget["max_hunks"]:
        reasons.append(f"hunks {stats.hunks} > {budget['max_hunks']}")
    if stats.added > budget["max_lines_added"]:
        reasons.append(f"added {stats.added} > {budget['max_lines_added']}")
    if stats.deleted > budget["max_lines_deleted"]:
        reasons.append(f"deleted {stats.deleted} > {budget['max_lines_deleted']}")
    if stats.forbidden:
        reasons.append("forbidden " + ",".join(stats.forbidden))
    return reasons


def main(argv: list[str]) -> int:
    budget = load_budget(pathlib.Path(argv[1]))
    target = pathlib.Path(argv[2])
    failed = 0
    paths = [target] if target.is_file() else sorted(target.glob("*.diff"))
    for diff_path in paths:
        stats = parse_unified(diff_path.read_text(encoding="utf-8", errors="replace"))
        reasons = violates(stats, budget)
        status = "FAIL" if reasons else "PASS"
        if reasons:
            failed += 1
        print(
            f"{status} {diff_path} files={len(stats.files)} "
            f"hunks={stats.hunks} +{stats.added} -{stats.deleted}"
        )
        for reason in reasons:
            print(f"  - {reason}")
    return 1 if failed else 0


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

Run it against the leftover directory before you point any new agent at the tree.

python3 score_diff_budget.py .diff-budget.json leftovers/paid-diffs

You now have a leftover report that does not depend on the paid review UI. Keep the FAIL lines because they are the patches that trained you to accept too much. Commit the report beside the diffs so the cutover plan cites evidence instead of memory.

Step 3: Recalibrate ceilings from leftovers, not from hope

Do not copy the paid agent's largest leftover patch and treat it as your new normal. Sort FAIL rows and look for a cluster of PASS sizes that still shipped useful work. Set max_files just above that cluster, then force oversized work to split across turns. If every leftover fails, your paid workflow was already a rewrite machine, and cutover will hurt until you split tasks.

python3 score_diff_budget.py .diff-budget.json leftovers/paid-diffs \
  | awk '/^FAIL/ {fail++} /^PASS/ {pass++} END {print "pass=" pass, "fail=" fail}'

Write a one-page note that lists which leftover tasks must be split before cutover. That note belongs in the cutover plan, and it should not sit as optional documentation. Future you will otherwise reopen the paid seat just to finish the big refactor.

Step 4: Gate apply on the new loop

Wire the scorer in front of patch apply, even if apply is just git apply. A budget that only runs against leftovers will rot after the first quiet week. The snippet below is proposed glue you can drop in front of a local runner.

#!/usr/bin/env bash
set -euo pipefail
DIFF_FILE="${1:?usage: gate-apply.sh proposed.diff}"
python3 score_diff_budget.py .diff-budget.json "$DIFF_FILE"
git apply --check "$DIFF_FILE"
git apply "$DIFF_FILE"

If the new loop streams a patch, write it to a temp file and score it before git apply. Cancellation belongs here too: once the scorer fails, you should not keep streaming more hunks into the same turn. Split the original user task and start a fresh turn with a much smaller file list.

Where inexpensive inference actually helps

You will retune this budget several times while leftover paid tasks are replayed locally. That replay stays cheaper when model calls are not metered like another premium seat. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option for this kind of replay. You can rerun leftover tasks against the same scorer without renting another vendor review pane. Keep the budget file in git so the host you choose cannot silently widen the blast radius.

Free model access still does not replace path allowlists, automated tests, or human code owners. It only makes it less painful to iterate the gate while you leave the paid agent. Leave those ceilings in the repository even if you later change hosts again.

Leftovers after the seat is gone

Paid diffs still sitting in chat history are leftovers, even after you exported a few files. Formatter churn that hid inside a giant approve click is another leftover you should score. Lockfile rewrites, snapshot updates, and generated clients are leftovers that will burn budget silently. Any turn that touched more than one service boundary is a leftover that should become two tickets.

Build a short leftover table now and close each row on purpose during cutover. The table is part of the cutover plan, not a retrospective slide. Close rows with diffs on disk, not with a memory of what the paid pane displayed.

Leftover	Risk if ignored	Close-out action
Unexported paid patches	You cannot score the old blast radius	Dump unified diffs before seat expiry
Mega-refactors in one turn	New loop copies the same habit	Split into path-scoped tasks
Lockfile and vendor edits	Reproducible builds drift	Add forbidden prefixes
Snapshot and minified files	Budget burned on noise	Add ignore globs
Missing apply gate	Free-stack patches land uncounted	Wrap `git apply` with the scorer

Limitations and who should skip this

This proposed harness understands unified text diffs and very little else besides that format. Binary assets, submodule pointer moves, and rename detection will undercount or overcount depending on git flags. A formatter that rewrites an entire file will exhaust max_lines_added even when the semantic change is one function. You must decide whether format-on-apply runs before or after the budget, and you must write that down.

Teams that already enforce tiny pull requests through code owners may not need another ceiling. Security-sensitive repositories should not treat a raw line count as a real authorization check. Generated codebases with huge protobuf dumps need a different contract, because the useful unit is a schema file, not a hunk. If your agent only answers questions and never writes trees, you can skip this diary entirely.

Do not use a diff budget as proof that the new model is as good as the paid one. Size control is only a safety rail, and correctness still needs tests you already trust. If you already exported paid-agent diffs, score those files first and keep the same ceilings on the next host you try. Leave the paid seat only after every FAIL row has an owner and a split ticket. The leftover directory is finished when new turns cannot exceed the budget without a conscious edit to the JSON.

Migration Diary: Rebuild a Tool-Call Ledger Before You Leave a Paid Coding Agent

Riley Xu — Fri, 18 Sep 2026 08:10:19 +0000

You do not lose the model first when you leave a paid coding agent; you lose the evidence. The vendor UI kept every tool call, argument blob, and result hash behind a session you cannot export. Rebuild that trail as a local, append-only log before you cut over, or later incidents become folklore. This diary walks a concrete cutover so the leftover history lives in your repo, not in a product you no longer pay for.

Recent discussion treats chat-driven coding as engineering, then wonders why regressions appear after the tab closes. Engineering here is not the prompt; it is a replayable record of tools, files, and outcomes. If you cannot answer which call wrote package.json, you are not operating a loop you can defend. A migration that keeps the chat and drops the tool timeline only relocates the same guessing.

What actually walks out the door

Paid coding agents usually hide three things you will miss on the second day after canceling. They hide the ordered tool timeline, the raw arguments, and the truncated results that still prove a side effect. They also hide retries that looked like one click inside the product timeline you cannot export. Your leftover is not a nicer theme; it is a missing forensic trail that used to live in their UI.

You should treat that trail as a migration artifact, the same way you treat lockfiles during a runtime move. Chat transcripts without tool envelopes cannot reconstruct a patch, because prose never names the exact side effect. Screenshots of the vendor timeline cannot feed a regression test, and they rot as soon as the seat disappears. Export what the loop did into a local ledger, then change vendors only after that file exists.

The artifact: an append-only JSONL ledger

Keep one line per tool event, and refuse pretty-printed multi-line JSON inside the same file. A line is a fact; a paragraph is a story you will fight during grep. Store the ledger beside the workspace, not inside the vendor cloud, and rotate it per branch.

Treat the following schema as a proposal until you have run it against a real failing command.

{"v":1,"ts":"2026-09-18T12:00:00Z","run_id":"cutover-014","seq":3,"actor":"agent","tool":"apply_patch","status":"ok","args_sha256":"ab12","result_sha256":"cd34","cwd":"/work/app","files":["src/auth.ts"],"exit_code":0,"duration_ms":842,"error":null}

You hash arguments and results so the log stays small when payloads include whole files. You keep files and cwd in clear text because that is what incident review actually queries. You keep run_id plus seq so retries and hidden follow-up calls do not look like independent work. You keep actor in every line so a human override cannot impersonate the model during blame.

1. Write the record at the tool boundary

Wrap every tool invocation in one function, and deny ad-hoc subprocess calls from prompt glue. If a helper can run a command, it must emit a ledger line even when the command fails. Failures are the events you will need first, so an exception path that skips the log is a defect.

# ledger.py — proposed wrapper, not a production SDK
import hashlib, json, os, time
from datetime import datetime, timezone
from pathlib import Path

LEDGER = Path(os.environ.get("AGENT_LEDGER", ".agent/tool-calls.jsonl"))

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

def record(run_id, seq, tool, args, result, status, files, cwd, exit_code, started):
    LEDGER.parent.mkdir(parents=True, exist_ok=True)
    row = {
        "v": 1,
        "ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
        "run_id": run_id,
        "seq": seq,
        "actor": "agent",
        "tool": tool,
        "status": status,
        "args_sha256": _sha(json.dumps(args, sort_keys=True).encode()),
        "result_sha256": _sha(result if isinstance(result, bytes) else str(result).encode()),
        "cwd": cwd,
        "files": files,
        "exit_code": exit_code,
        "duration_ms": int((time.time() - started) * 1000),
        "error": None if status == "ok" else str(result)[:500],
    }
    with LEDGER.open("a", encoding="utf-8") as handle:
        handle.write(json.dumps(row, separators=(",", ":")) + "\n")
    return row

2. Validate the log before you trust a cutover

A ledger that cannot fail a test will rot into comments nobody trusts during an incident. Run a structural check in CI on every agent branch, and block merge when a required field disappears. The test below is small on purpose, because a heavy fixture will not run on every throwaway agent branch.

# test_ledger.py
import json
from pathlib import Path

REQUIRED = {
    "v", "ts", "run_id", "seq", "actor", "tool", "status",
    "args_sha256", "result_sha256", "cwd", "files", "exit_code",
    "duration_ms", "error",
}

def test_ledger_lines_are_complete():
    path = Path(".agent/tool-calls.jsonl")
    assert path.exists(), "run the loop once so the ledger has a line"
    seen = set()
    for raw in path.read_text(encoding="utf-8").splitlines():
        row = json.loads(raw)
        missing = REQUIRED - row.keys()
        assert not missing, missing
        key = (row["run_id"], row["seq"])
        assert key not in seen, key
        seen.add(key)
        assert row["v"] == 1
        assert row["status"] in {"ok", "error", "denied"}
        assert isinstance(row["files"], list)

3. Redact before you hash, not after

Paid products often redact in the UI while still shipping secrets into their own telemetry. Your local log can be worse if you hash a token that also landed in files. Scan arguments for env-shaped strings, replace those values with names, and only then compute the hash. Never log the entire environment wholesale for debug during the first weekend on a free server.

import re

SECRETISH = re.compile(r"(?i)(api[_-]?key|token|secret|password|bearer)\s*[:=]\s*\S+")

def redact(payload: str) -> str:
    return SECRETISH.sub(r"\1=***", payload)

Cutover plan in numbered steps

Follow this order so you do not discover a missing field after the paid seat expires.

Open three recent paid sessions, list every visible tool name, and write those names into tools.txt before canceling.
Map each vendor tool name to a local function, including deny paths for shells you will not allow.
Record one golden run on the paid side and keep the vendor timeline only as a checksum against JSONL.
Replay the same task on the new loop and compare tool, files, and exit_code sequences, ignoring chat prose.
Fail the cutover if seq gaps appear, because gaps mean retries or hidden tools you have not wrapped.
Freeze the schema at v1, and delay additive fields until the first week of queries has settled.

Use the following commands during step four so the ledger is real before you argue about model quality.

mkdir -p .agent
export AGENT_LEDGER="$PWD/.agent/tool-calls.jsonl"
python -m pytest test_ledger.py -q
python - <<'PY'
import json
from pathlib import Path
from collections import Counter
rows = [json.loads(l) for l in Path(".agent/tool-calls.jsonl").read_text().splitlines()]
print(Counter(r["tool"] for r in rows))
print("runs", sorted({r["run_id"] for r in rows}))
PY

Where a free model path actually helps

After the ledger exists, swapping the completion backend is a configuration change rather than a memory loss event. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option for running the same loop while you compare tool sequences. Point the same wrapper at that path only after step four passes on a disposable branch.

You are proving that apply_patch still emits files and that denied commands still land as status=denied. If the server is free, you still meter wall time in duration_ms, because free does not mean unbounded patience from your process table. Skip slogans here, and do not treat a green chat as evidence that the cutover is finished. If the ledger diverges, keep the paid seat one more week and fix the wrapper before you cancel.

Decision table: what belongs in the line

Use this table to keep the line factual when someone asks to log everything for safety.

Event	Log it?	Why
Tool start with hashed args	Yes	Reconstruct order
Tool result hash plus exit code	Yes	Prove side effects
Full file contents	No	Blow up disk and leak secrets
Model prose in a separate file	Optional	Mixes story with facts
Human approval or edit	Yes, `actor=human`	Stop false blame
Raw environment block	No	Credential spill
Dependency install command	Yes	Lockfile incidents hide here

Leftovers you should expect anyway

Even a clean JSONL file will not restore vendor-only features you were quietly depending on. You will still lack their hosted session search, their shared team timeline, and whatever policy pack lived behind the login. You will also lack their silent retries unless your wrapper records them as new seq values. Write those gaps on a leftover card so nobody calls the migration feature complete after one green test.

Context windows, ranking, and editor plugins are separate migrations and should not ride along in this schema. Do not fold them into the audit trail or the schema will become a junk drawer. Finish the evidence trail first, then migrate prompts and routing as their own cutovers.

Limitations and who should not use this

This approach assumes you can intercept tools at the boundary where commands actually run. If the paid product only exposes a chat box, you cannot honestly claim parity, and you should not delete the seat. This approach also stores hashes and file paths that may remain sensitive, so legal review comes before a shared .agent directory.

Do not treat this ledger as a security information event management system with real retention guarantees. It has no retention job, no access control, and no tamper-evident chain beyond whatever git already gives you. Do not use it to justify skipping tests; a successful exit_code is not a product specification. Do not point any free server at production credentials while you compare traces on a live workspace.

Teams that never grant tools to a model can skip this entire diary without losing an operational record. People who need guaranteed uptime, signed vendor BAAs, or air-gapped legal holds need a different cutover, with procurement in the room. A local JSONL file will not satisfy those constraints, and pretending otherwise wastes a week.

Close the loop

If the next incident cannot name the tool, the file, and the run_id, the migration is not done. Keep the paid timeline until your test reads a real ledger line from a failed command, not only from a happy path. When that failure is boring to replay from JSONL alone, you can leave the paid seat.

After the schema is frozen, you can exercise the same wrapper on MonkeyCode's free model access and free server option using a throwaway branch.

Migration Diary: Rebuild the Command Sandbox Before You Leave a Paid Coding Agent

Riley Xu — Thu, 17 Sep 2026 06:29:50 +0000

The leftover that actually hurts during cutover is not a missing model brand; it is the sandbox the paid product never exposed. You can copy prompts, tools, and stop rules and still ship an agent that runs destructive shell on a free server. Freeze a command policy before you leave, then let every new run fail closed against that policy. This diary walks through a local policy file, a validator, and a cutover checklist you can run in one evening.

The leftover is the fence, not the chat

Paid coding agents wrap every shell call in a host you never configured, so the allowlist lives in their UI, not your repo. After you cancel, that wrapper disappears, and your loop talks to a raw terminal or an unmanaged worker process. The leftovers are not chat transcripts; they are implicit denials, working-directory jails, and silent network blocks. If you skip this inventory, a free model on a free server will look more capable only because it is less fenced.

You should treat the paid product as a black box that already answered four questions you must now write down. Write down which binaries may start, which flags are forbidden, which directories may be the working tree, and whether network is allowed. Those answers form a contract your next runtime has to enforce even after you change generators or hosts. Store the contract in git before you export a single chat, because chats do not block a dangerous binary.

Capture the paid behavior before you pull the plug

Work through the capture steps while the paid agent can still run a harmless command in your project. Do not wait until the invoice cycle ends and the vendor sandbox evaporates without leaving a dump. Keep a plain text file beside the repository and record denials in the same words the product used. You are not collecting slogans from the settings page; you are collecting the commands that already failed.

Run one read-only command, one write command, one network command, and one process-spawn command.
Record whether each call was allowed, rewritten, timed out, or blocked without a clear error.
Note the working directory the tool actually used, not the directory you assumed from the prompt.
Copy any UI labels that mention sandbox, restricted mode, or approved commands into that text file.

A denial is the most honest documentation the vendor will ever give you during this migration. Save the four outcomes even when they look boring, because boring denials are the policy. If a command succeeded in a surprising directory, treat that success as a finding rather than a convenience. Those four notes become the first draft of the YAML file in the next section.

Artifact: a fail-closed command policy

Put a policy file in the repository so the next runtime cannot invent permissions during a helpful-looking retry. The example below is a proposed contract, not a claim about any vendor's hidden defaults. Keep fail_closed true, because an empty allowlist must mean deny rather than mean trust the model. Commit this file with the capture notes so a reviewer can see why each binary was admitted.

# sandbox_policy.yaml — proposed local contract
version: 1
fail_closed: true
working_tree:
  allowed_roots:
    - "."
  deny_path_prefixes:
    - "/etc"
    - "/home"
    - "~"
    - ".."
network:
  allow: false
process:
  max_runtime_ms: 15000
  max_output_bytes: 65536
commands:
  allow:
    - argv_prefix: ["git", "status"]
    - argv_prefix: ["git", "diff"]
    - argv_prefix: ["python", "-m", "pytest"]
    - argv_prefix: ["ls"]
    - argv_prefix: ["rg"]
  deny_substrings:
    - "rm -rf"
    - "sudo"
    - "curl "
    - "wget "
    - "ssh "
    - "chmod 777"

The YAML also carries timeout and output caps that your subprocess wrapper must enforce later. The checker in the next section only validates argv, which is the leftover most teams forget to write down. Do not treat prefix matching as a container, and do not add bash -c to the allowlist to make a demo pass. If a paid-agent command cannot be expressed as an argv prefix, that command is not ready to move.

Run the checker before any cutover

Pair the policy with a small checker that the agent loop must call before subprocess. Label this as a proposed local gate you should run on fixtures, not as a production security audit. Fail the process when a fixture disagrees, because a yellow log line will not stop a cutover on a Friday. Keep the fixtures in git beside the policy so model swaps cannot quietly widen the shell.

# check_sandbox.py — proposed local gate, unexecuted until you wire fixtures
from __future__ import annotations

import json
import shlex
import sys
from pathlib import Path

import yaml

DENY_DEFAULT = "command rejected by sandbox_policy.yaml"


def load_policy(path: Path) -> dict:
    data = yaml.safe_load(path.read_text(encoding="utf-8"))
    if not data or not data.get("fail_closed"):
        raise ValueError("policy must set fail_closed: true")
    return data


def argv_list(command: str) -> list[str]:
    return shlex.split(command, posix=True)


def is_allowed(command: str, policy: dict) -> tuple[bool, str]:
    argv = argv_list(command)
    if not argv:
        return False, "empty command"
    joined = " ".join(argv)
    for blob in policy["commands"].get("deny_substrings", []):
        if blob in joined:
            return False, f"denied substring: {blob!r}"
    if policy.get("network", {}).get("allow") is False:
        if argv[0] in {"curl", "wget", "ssh", "scp", "nc"}:
            return False, "network binaries are blocked"
    for root in policy["working_tree"]["deny_path_prefixes"]:
        if any(str(part).startswith(root) for part in argv[1:]):
            return False, f"path prefix blocked: {root}"
    for rule in policy["commands"].get("allow", []):
        prefix = rule["argv_prefix"]
        if argv[: len(prefix)] == prefix:
            return True, "allowed prefix match"
    return False, DENY_DEFAULT


def main() -> int:
    policy = load_policy(Path("sandbox_policy.yaml"))
    fixtures = json.loads(Path("sandbox_fixtures.json").read_text(encoding="utf-8"))
    failures = []
    for row in fixtures:
        ok, reason = is_allowed(row["command"], policy)
        if ok != row["expect_allow"]:
            failures.append({**row, "reason": reason})
    if failures:
        print(json.dumps(failures, indent=2))
        return 1
    print("sandbox fixtures passed")
    return 0


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

Add fixtures that encode yesterday's paid-agent denials, not the commands you wish had been allowed. Include at least one path-escape case, one network case, and one extra git subcommand that should still fail closed. If a fixture is annoying to write, that annoyance is the migration working as designed.

[
  {"command": "git status", "expect_allow": true},
  {"command": "git diff --stat", "expect_allow": true},
  {"command": "git push origin main", "expect_allow": false},
  {"command": "python -m pytest tests/test_sandbox.py", "expect_allow": true},
  {"command": "rm -rf /", "expect_allow": false},
  {"command": "curl https://example.com", "expect_allow": false},
  {"command": "ls ../secrets", "expect_allow": false}
]

git diff --stat passes because the allow rule matches an argv prefix, not a full string. git push origin main fails because push was never admitted, which is usually what you wanted on a free server. ls ../secrets fails on the path prefix even though ls itself is allowed. Tune prefixes in review when a historical paid command must keep working, and do not tune them inside a prompt.

Cutover plan you can finish before the subscription lapses

Treat cutover as a change to enforcement, not a change to chat tone or model branding. Each step should produce a file or a command output you can paste into the pull request. If a step produces only a feeling, you have not finished it. Stop when the checker is green against the paid-agent leftovers, not when the new chat looks fluent.

Freeze sandbox_policy.yaml and sandbox_fixtures.json in the same commit so reviewers see denials next to code.
Route every tool-calling path through is_allowed and refuse to start a subprocess on a deny.
Log the reason string; a silent block will look like a model failure and waste a retry budget.
Replay yesterday's paid-agent commands against the fixtures until every historical allow still allows.
Enforce max_runtime_ms in the subprocess wrapper, because argv checks do not kill hung processes.
Only then point the loop at a free model runtime, keeping the same policy file unchanged.

Run the checker from the repository root before you start the agent loop on any host you actually operate.

python3 -m pip install pyyaml
python3 check_sandbox.py

If the checker exits nonzero, do not start the agent loop on that revision. Fix the policy or the fixture first, then rerun until the output is a single passing line. A red checker is cheaper than a surprise network call on a shared server. Keep the command in CI so a later prompt change cannot reopen the fence.

Map leftovers to local replacements

Paid products hide policy in toggles, so you need a table that names each leftover and the file that now owns it. Fill the table from your capture notes rather than from vendor documentation, because the UI often overstates isolation. Keep the table in the same commit as the YAML file so a reviewer can see both the claim and the enforcement. If a row has no local replacement, you are not ready to cut over.

Paid leftover	Local replacement	Failure if skipped
Restricted-mode toggle	`fail_closed: true`	unknown commands execute
Working directory jail	`allowed_roots` and deny prefixes	writes leave the repo
Blocked outbound HTTP	`network.allow: false`	tools exfiltrate context
Approved command palette	`argv_prefix` allowlist	unexpected binaries start
Hidden tool timeout	`max_runtime_ms` in the wrapper	hung processes on a free server

Use the table as a punch list during the last week of the paid seat. Check a row only when a file or a test proves the replacement exists. Do not check a row because a model promised it would be careful. Careful is not an enforcement mechanism.

What a free runtime changes, and what it does not

When you leave a paid coding agent, generation quality is the discussion everyone wants, but process isolation is the discussion you actually need. A free server that can run tools makes the missing sandbox concrete, because commands now execute on a machine you operate. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding workspace with free model access and a free server option you can point at after the allowlist is frozen.

Keep the same fixtures when you change generators, including when you try that free-model path. If a run needs a wider allowlist, change the file in review rather than widening it in a prompt. Model choice becomes a smaller decision once permission lives in git. That is the useful leftover of this diary, and it still holds if you never touch that workspace.

Limitations

A prefix allowlist is not a container, a seccomp profile, or a multi-user isolation boundary for shared machines. It will not stop a binary you allowed from reading files through a feature you forgot to deny. It will not stop prompt injection from requesting a command that happens to match an allowed prefix. You still need operating-system isolation if the server is shared, networked, or holds secrets from other projects.

You should also keep secrets out of the working tree the policy allows for search tools. An allowlist that permits rg over a directory of tokens is a credential leak with extra steps. Move secrets into an environment the tool cannot print, and deny pagers that dump those values. If a fixture cannot be run without a secret in the tree, rewrite the fixture before you cut over.

Who should not use this approach

Skip this diary if your agent cannot run shell tools and only edits buffers through a mediated API. Skip it if you already run every tool inside a locked-down container with a reviewed seccomp or AppArmor profile. Skip it if you need a compliance certification, because this checker is a migration aid rather than an audit artifact. Teams that cannot fail closed should not pretend a YAML file is a sandbox, and they should stay on a mediated vendor host.

Once the policy exists, swapping generators is a smaller decision than it felt inside the paid UI. You can change models without changing permission, and that separation is the actual deliverable of this cutover. Keep widening the allowlist only through review, and treat every new binary as a migration leftover rather than a convenience. Exporting the chat history can wait until this fence is tested against the fixtures in your repository.