Five Assumption Checks Before Putting Agent Tasks on Shared Machines

Five Assumption Checks Before Putting Agent Tasks on Shared Machines

When Agent tasks fail on shared hardware, the cause is often not the model itself but a workspace that suddenly turns read-only, clock drift that expires tokens, an external host that gets blocked, or two tasks writing to the same directory at once. These problems don't show up in capability evaluations because they don't ask "what can this machine do" but rather "what state do you assume it will always stay in."

The original author proposes a lightweight operational framework: turn implicit assumptions into five checks, three roles, and a single Wiki page, all verified before a task starts.

Why Shared Environments Make Assumptions Fail More Easily

On a dedicated host the environment is stable, so you never think about it. But the essence of a free tier or shared instance is: the machine is shared, may be reclaimed, and you have no authority to configure it. The original notes that MonkeyCode offers free model access and free server options, pushing Agent running costs close to zero — and this is exactly what tempts teams to stop documenting environment assumptions, because retrying looks cheaper than writing docs.

The core argument is here: the lower the cost, the easier it is to skip environment verification. But a single silent write failure, or a single 401 from an expired token, costs far more troubleshooting time than checking in advance.

Five Assumptions Worth Checking

The checklist the original gives deliberately excludes performance measurement and model comparison, focusing only on environment assumptions. Each one is cheap to verify but expensive to discover late.

Assumption	Consequence if false	Low-cost check
Workspace is writable and has space headroom	Writes fail mid-run, or the disk silently fills up	touch a probe file, then use df -Pm
System clock is roughly correct	Token expiry, cache TTL, and log ordering all go wrong	Compare against the HTTP Date response header
Every host the task needs is reachable	Calls hang until timeout instead of the server returning	Send a HEAD request to each host
Credentials exist and won't be printed	An hour wasted on an invisible 401	Length check plus a short hash
Only you are writing during this run	Two Agents interleave writes to the same directory	Run flock on a run lock

Note there are no throughput claims and no model comparisons. This is an assumption ledger, not a benchmark. The author recommends putting the preflight script in the code repository rather than someone's home directory, so reviewers can read exactly what was checked.

flock and advisory locks: flock is a file-descriptor-based advisory lock on Linux. It does not prevent other processes from writing to the same directory at the kernel level; it only works for cooperating processes that are willing to acquire the same lock first. This is why the original stresses that it "only blocks cooperating runs, not deliberate ones." The purpose of exec 9>"$LOCK" is to bind the lock file to file descriptor 9, after which flock -n 9 attempts to acquire the lock non-blockingly; once the script exits, the descriptor closes and the lock is released automatically, avoiding deadlock leftovers. Note that flock depends on filesystem support; behavior on network filesystems such as NFS may differ from local disks, so cross-host cooperation should use a lease-based distributed lock instead.

Portable output from df -Pm: -P forces POSIX format, guaranteeing each line has a fixed six columns and long device names don't wrap; -m outputs in MB. The point of combining them is to let scripts parse available space using a stable column number (usually column 4) rather than relying on human-readable -h output. If the target system lacks GNU coreutils (such as BusyBox or macOS), df -Pm arguments may not be accepted, so the preflight script needs a fallback branch for that.

Three Roles and Two Handoffs

The number of roles should be small enough that a small team will actually carry them out.

Run Owner: writes the run row, maintains the five assumptions, and pastes the preflight report onto the Wiki page. Has no authority to declare a task ready.

Box Steward: responsible for the shared host or tier, maintains the egress allowlist, and is the only one who can sign off on exceptions. When a check fails but the task must still run, the Steward records which assumption was waived and until when.

Reviewer: reads the run row and report hash before merging. The Reviewer's job is not to rerun the script but to notice that the report is three days old, or that the run row quietly gained an egress host.

Both handoffs are Wiki edits rather than message notifications: any FAIL triggers Run Owner → Box Steward; after the gate passes, Run Owner → Reviewer. This way the next person to touch the task inherits the reasoning process.

In Practice: Preflight Script and Gate

The original provides a ready-to-apply preflight.sh whose core logic asserts the five assumptions and prints results line by line, exiting with a non-zero code on any failure. A few implementation details worth noting:

• The workspace check uses mkdir -p plus a touch probe, then gets available MB from df -Pm, with a default threshold of 512MB
• The clock check takes the Date header from the first egress host, compares it with local UTC time, with a default tolerance of 120 seconds
• The credential check outputs only the first 10 chars of sha256, never the original value
• The run lock uses exec 9>"$LOCK" plus flock -n 9

The author specifically flags portability: the script assumes bash 4+ (for the ${!SECRET_VAR} indirect expansion), GNU coreutils, and flock; on macOS you need to replace date -u -d with gdate or a Python one-liner.

The gate script gate.sh solves the problem that "a preflight nobody reads is just decoration": it refuses to start a task when the report is incomplete, confirming item by item that all five keyword categories — workspace, clock, egress, secret, run — have OK records, and finally uses the report hash (first 12 chars of sha256) as a fingerprint that can be pasted into the Wiki.

${!SECRET_VAR} indirect expansion: this is the indirect variable reference syntax introduced in bash 4. When variable names are dynamically assembled (for example, API_TOKEN and CI_TOKEN sharing one piece of check logic), ${!name} first expands the value of name, then uses that value as the variable name to retrieve its contents. bash 3.2 (the version shipped with macOS) does not support this syntax, and the script will immediately report bad substitution. Portable alternatives are eval or printf -v, but eval carries injection risk when secrets are involved, so the original recommends upgrading the toolchain outright rather than patching around it.

Report hash as a fingerprint: the gate uses the first 12 chars of sha256 to identify a report, which is a compromise: a full hash is too long to paste conveniently, while 12 chars (48 bit) makes collision probability negligible at team scale, and is enough for the Reviewer to confirm that "the report I read" and "the report the gate let through" are the same one. The hash only proves the content wasn't changed, not that it's true, so the Reviewer still needs to judge whether the report is stale.

One-Page Wiki Template

The Wiki page the original gives contains a run row, steps, and an exceptions table. The run row records job, box, workdir, egress, secret, deadline_utc, and the steps go from preflight to gate to appending the exit code and elapsed time after the run.

One easily overlooked step: after the run ends, append "the first line of output that scrolled by." The author notes this line usually explains the cause of the next failure, and recording it while the run is fresh costs nothing.

The exceptions table records the date, the waived assumption, the signer, and the expiry time — far cheaper than a postmortem.

The design intent of the run row: the run row is a line of structured fields rather than free text, so that placement decisions, environment assumptions, and responsible parties can be retrieved and compared in one fixed location. deadline_utc uses UTC rather than local time precisely to match the baseline of the clock check, avoiding ambiguity during handoffs caused by timezone conversion. Writing box= into the run row is equivalent to tagging the task with "which machine it depends on," so that when a shared machine is reclaimed or an allowlist changes, affected runs can be traced back.

Where the Task Belongs: Write It in the Run Row

The original uses a table to pull placement decisions out of chat and back into documentation: interactive debugging goes on the local machine; repeatable batch processing goes on a shared free machine; anything needing a stable public IP or inbound port goes on a host you manage yourself; large datasets or GPUs go on a paid, adequately sized host; confidential or regulated data goes in your own environment.

Whichever row you pick, write it into the box= field of the run row. Your future self won't remember why the task moved, and a table is cheaper than a postmortem.

Limitations and Who Shouldn't Use It

The original candidly lists the boundaries: preflight is a point-in-time assertion, proving only the environment at the moment you run it — a shared machine may change its mind ten minutes later; the gate is a speed bump, not a guarantee; it doesn't measure performance, quality, or cost; the flock check is advisory, only blocking cooperating runs, not deliberate ones.

If configuration management or existing health checks already cover your hosts, if you run fully controlled single-tenant infrastructure, or if tasks start in under a second and can't tolerate probes, you shouldn't adopt this process. Regulated workloads should skip it too: the five checks tell you a machine is usable, not that it's auditable.

For teams wanting to practice first, the original suggests using MonkeyCode's free model access and free server options to figure out what your task actually assumes on a machine you can throw away — starting from the project's own documentation, and making the run row match the current constraints.

One-line Summary

Turn the implicit environment assumptions of Agents on shared hardware into verifiable gates, using five checks, three roles, and a one-page Wiki.

Paragraph Summary

The article points out that Agent task failures on shared hardware usually stem from environment assumptions breaking down — read-only workspaces, clock drift, blocked egress hosts, missing credentials, or concurrent writes — rather than insufficient model capability. Cheap retries tempt teams to stop recording these assumptions. The author proposes a lightweight framework: five cheaply verifiable checks (workspace writable and with space, clock skew, egress reachability, credentials present and never printed, exclusive run lock), three roles (Run Owner, Box Steward, Reviewer) with handoffs completed via two Wiki edits, plus preflight and gate scripts that only allow startup when the report is complete, with the report hash as an auditable fingerprint. The article is also candid about the boundaries: it's a point-in-time assertion rather than a guarantee, it doesn't measure performance, and it doesn't apply to single-tenant controlled environments or regulated workloads.