A Replay Hash for Public Bundles That May Use a Remote Seat

The scene starts on a regional train, where a half-finished agent run is still open on a laptop. The working tree holds a public OpenAPI fragment, a generated test scaffold, and an uncommitted environment file. Halfway through a tunnel the network drops, while the agent still wants to expand the public schema and rewrite the scaffold. The environment file must stay on the machine, yet the schema expansion does not need local secrets or a live private API.

That split is the placement problem this note treats, because one tree can contain both exportable files and files that must never leave. Local inference keeps secrets, sockets, and uncommitted context beside the editor, at the cost of battery, heat, and a slower model. A remote worker can absorb a stateless rewrite, but only after the bundle has been proven public and safely replayable. The costly mistake is exporting the whole tree because one generated file inside it looks boring and safe.

A receipt instead of a hunch

A residency receipt is a small JSON record written on the laptop before any selected file is allowed to leave. It names the job, lists the public paths, counts secret-name hits, and records why the chosen seat is local or remote. The hash of that record becomes the replay key when connectivity returns after the tunnel and a remote result arrives. The receipt does not move bytes by itself, and it only refuses a bad export while documenting a permitted one.

The remote seat in this workflow is a free server option paired with free model access for eligible public jobs. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Those two availability claims are operator-supplied for this draft and are not a quota, a hardware spec, or a duration. Current product documentation should be read before a team treats either option as capacity it can plan around.

What the receipt is willing to trust

The classifier trusts three facts that a laptop can establish without opening a network connection at all. A filename denylist catches common secret carriers such as environment files, private keys, and credential dumps. A job card states whether the work needs offline continuity, uncommitted context, or a private local socket. A latency class marks the job as batch or interactive, because a remote seat cannot win a tight edit loop.

The script does not guess token prices, measure round-trip time, or rank one model above another model. It also refuses to open file contents for a deep secret scan, and that limit is discussed later in this note. The practical point is a reproducible gate that a second machine can repeat on the same fixture and the same job card. Anything beyond the three local facts stays outside the decision so the receipt remains small enough to hash and store.

A policy sketch, not a timing study

The table below is a policy sketch for the train scenario, not a set of measured timings or cost figures. A free server wins only on the public batch rows, and only when the receipt hash matches the bundle that will be uploaded. Interactive work stays on the laptop because the wait for a remote round trip dominates the edit itself. Secret material and private dependencies stay local even when a remote seat is idle and described as free to use.

Job shape	Secret hits	Offline or private dependency	Latency class	Seat
Public schema expansion	none	no	batch	free server
Scaffold rewrite of public files	none	no	batch	free server
Same rewrite during a live edit	none	no	interactive	local
Environment file present in the tree	one or more	either	either	local
Private API client generation	none	yes	batch	local
Replay after the tunnel with the same hash	none	no	batch	remote replay

Build the gate in four steps

The Python below is an illustrative workflow that a reader can save and run against local fixtures. It is not a client for a hosted product, and it is not offered here as a benchmark or a capacity test. Each step writes or checks one artifact so a failed export can be explained from the receipt alone. The code is a proposal, and this article does not claim that the snippet was executed against a live remote seat.

1. Declare the job card

Write a job card that states identity, latency class, and the dependency flags the classifier will read. Keep that card beside the fixture so the same decision can be repeated after the train leaves the tunnel. A missing dependency flag should be treated as a reason to stay local, not as permission to export the tree. The sample card below describes a batch schema expansion that claims no offline need and no uncommitted context.

{
  "job_id": "schema-expand-014",
  "latency_class": "batch",
  "requires_offline": false,
  "needs_uncommitted_context": false
}

2. Scan names before contents travel

The scanner walks a work directory and separates common secret filenames from the remaining ordinary files. It skips Git internals so that a normal repository clone is not mistaken for part of the upload payload. It does not upload anything, and a hit on an environment file or a key suffix forces the local seat. The job card can look clean and still lose, because the tree itself is evidence the card cannot override.

SECRET_NAMES = {".env", ".env.local", "id_rsa", "credentials.json", "secrets.yaml"}
SECRET_SUFFIXES = {".pem", ".key", ".p12"}

def looks_secret(path):
    if path.name in SECRET_NAMES or path.name.startswith(".env"):
        return True
    return path.suffix in SECRET_SUFFIXES

3. Classify and stamp a hash

Classification is a pure function of the job card plus the filename scan, with no clock and no network call. Reasons accumulate instead of being overwritten, so a later review can see every block that forced the local seat. The receipt hash covers the seat, the reasons, the public paths, and the secret count in one canonical JSON form. A changed file list produces a changed hash, which stops a stale remote result from being applied to a newer tree.

import hashlib
import json

def classify(job, secret_hits, public_files):
    reasons = []
    if secret_hits:
        reasons.append("secret-material-present")
    if job.get("requires_offline") or job.get("needs_uncommitted_context"):
        reasons.append("local-dependency")
    if job.get("latency_class") != "batch":
        reasons.append("not-batch")
    seat = "local" if reasons else "free-server"
    payload = {
        "job_id": job["job_id"],
        "seat": seat,
        "reasons": reasons,
        "public_files": sorted(public_files),
        "secret_count": len(secret_hits),
    }
    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
    payload["receipt_sha256"] = hashlib.sha256(canonical.encode()).hexdigest()
    return payload

4. Replay only on a matching receipt

When the tunnel ends, the laptop recomputes the receipt before it accepts any result that claims to match the job. A matching hash means the public bundle is unchanged and the seat is still the free-server value recorded earlier. A mismatch means the remote output is stale relative to the tree and must be discarded rather than applied. The local seat never sends the secret hits, because those paths are absent from the public file list by construction.

Run the same check on two fixtures

Create one public fixture and one dirty fixture, then point the same script at each directory in turn. The public fixture should receive a free-server seat and a hash that stays stable across two identical runs. The dirty fixture should receive a local seat and a secret count of at least one because of the environment file. Neither command needs a network, which is the property that actually matters while the laptop is still in the tunnel.

mkdir -p fixtures/public fixtures/dirty
printf 'openapi: 3.0.3\ninfo:\n  title: Demo\n' > fixtures/public/openapi.yaml
printf 'openapi: 3.0.3\n' > fixtures/dirty/openapi.yaml
printf 'API_TOKEN=example\n' > fixtures/dirty/.env
python3 residency_receipt.py job.json fixtures/public
python3 residency_receipt.py job.json fixtures/dirty

A minimal driver loads the job card, scans the work directory, and prints the receipt as formatted JSON. The process exit code stays zero for both seats, because a local decision is a successful refusal rather than a crash. A usage error is the only non-zero path in this sketch, and it fires when the arguments are missing or unreadable. Missing job-card flags default to the cautious local seat, so an incomplete card cannot sneak a bundle off the machine.

#!/usr/bin/env python3
"""Illustrative residency receipt. Not a hosted client and not a benchmark."""

import hashlib
import json
import sys
from pathlib import Path

SECRET_NAMES = {".env", ".env.local", "id_rsa", "credentials.json", "secrets.yaml"}
SECRET_SUFFIXES = {".pem", ".key", ".p12"}

def looks_secret(path: Path) -> bool:
    name = path.name
    if name in SECRET_NAMES or name.startswith(".env"):
        return True
    return path.suffix in SECRET_SUFFIXES

def scan_tree(root: Path):
    secret_hits = []
    public_files = []
    for path in root.rglob("*"):
        if not path.is_file() or ".git" in path.parts:
            continue
        rel = str(path.relative_to(root))
        if looks_secret(path):
            secret_hits.append(rel)
        else:
            public_files.append(rel)
    return secret_hits, public_files

def classify(job, secret_hits, public_files):
    reasons = []
    if secret_hits:
        reasons.append("secret-material-present")
    if job.get("requires_offline") or job.get("needs_uncommitted_context"):
        reasons.append("local-dependency")
    if job.get("latency_class") != "batch":
        reasons.append("not-batch")
    seat = "local" if reasons else "free-server"
    payload = {
        "job_id": job["job_id"],
        "seat": seat,
        "reasons": reasons,
        "public_files": sorted(public_files),
        "secret_count": len(secret_hits),
    }
    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
    payload["receipt_sha256"] = hashlib.sha256(canonical.encode()).hexdigest()
    return payload

def main() -> int:
    if len(sys.argv) != 3:
        print("usage: residency_receipt.py <job.json> <workdir>", file=sys.stderr)
        return 2
    job_path = Path(sys.argv[1])
    root = Path(sys.argv[2])
    if not job_path.is_file() or not root.is_dir():
        print("job card or workdir is missing", file=sys.stderr)
        return 2
    job = json.loads(job_path.read_text())
    job.setdefault("requires_offline", True)
    job.setdefault("needs_uncommitted_context", True)
    job.setdefault("latency_class", "interactive")
    secret_hits, public_files = scan_tree(root)
    print(json.dumps(classify(job, secret_hits, public_files), indent=2))
    return 0

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

Where a free server actually earns the seat

A free server earns the seat when the receipt says free-server and the work is a stateless transform of already public files. Schema expansion, license-header insertion, and a rewrite of generated tests fit that shape when they ignore uncommitted secrets. Offline continuity is not required, and the result can wait until the tunnel ends without blocking the editor. Free model access matters in that narrow case only as a way to run the transform without first provisioning a paid seat.

Local execution remains the better seat when the tree contains secret-looking names or a private dependency. The same local seat wins when the engineer is inside an interactive edit loop where added latency becomes the product. It also wins when the network is down and the result is required before the laptop can reconnect to any server. A free option does not change those three cases, because the cost is residency and wait rather than the invoice.

Limitations and who should skip this

The filename scan misses secrets pasted into ordinary source files, notebooks, logs, and shell history on the machine. Teams that need content inspection should place a dedicated scanner in front of this gate and keep the receipt as a second check. The hash does not prove that a remote worker ignored paths the laptop never sent in the public list. It only proves that the laptop decision and the public file list were unchanged between export and replay.

This sketch should not be used for regulated data, customer records, or any tree whose policy forbids all egress. It should not be used as a capacity plan, a quota claim, or a statement about how long a free seat remains open. No model name, hardware shape, or duration is established in this note, and a free server can be unavailable on a given day. Readers who need measured latency should time their own path and keep those numbers out of the receipt until the method is written down.

A next check that stays on the laptop

Operators who already separate local and remote agent work can place this receipt in front of the export step. They can compare the printed seat with the notes they already keep for placement, sleep, and patch overlap. The useful outcome is a repeatable refusal when the tunnel, a secret file, or the edit loop keeps the job on the laptop. Running the two fixtures above is enough to see the split, before any remote seat is asked to accept a bundle.