Align Environment Files.create write semantics

[SaladDay]

Environment Files.create now follows the observed official write semantics. It creates missing parent directories, never overwrites an existing path, and bounds inline data at 5 MiB decoded. Symlink safety is unchanged, and initial Session files, Skills, Plugins and cold resume keep their install behavior. The pinned baseline is unchanged (SDK 3.13.0 / d7c41ef / agents=v1).

Behavior

• Missing parents are created one component at a time with mkdirat, mode 0700, under the held no-follow directory walk. This happens only after the body digest is verified. An existing symlink or non-directory component still rejects.
• No replacement:
  • An existing file, FIFO, hard link, symlink leaf or symlink parent returns 400 invalid_request_error, param null, with "environment.files paths must not traverse symlinks or overwrite existing files".
  • A directory destination returns "file path conflicts with an existing environment file".
  • The final install uses renameat2(RENAME_NOREPLACE), with a linkat fallback. Neither can replace a destination, even under races.
  • A rejected write leaves no committed receipt, changes no bytes and consumes no Source File.
• Inline bound: inline data above 5 MiB decoded returns 400 with "environment.files[0].data exceeds the 5 MiB decoded limit". This is checked before the provisioning check, the Source File lookup and any Worker work. file_id copies keep the 50 MiB bound.
• Scope of the new mode:
  • Only Files.create uses it, through an explicit create argument to the write helper, used by the daemon local workspace writer for both Core-managed Docker and self_hosted Runtimes.
  • Initial Session files and Skills keep the 4-argument replace mode. Plugins use a separate installer. Cold resume does not reinstall files.
• Mixed versions fail safe:
  • A new daemon with an old helper rejects writes with invalid_input.
  • An old daemon keeps replace semantics until its image is rebuilt.
  • An old Core ignores the new reason field.
• Client and Core Web: the 5 MiB inline bound is applied. A Base64-check stack overflow at about 4 MiB is fixed, so exact 5 MiB uploads work.
• Documented differences:
  • An overwrite of a file written by an earlier Files.create gets the "must not traverse symlinks or overwrite" message, not the official tracked "file path conflicts…" message. Core's write receipts store only a digest, so it can't tell reliably and cheaply.
  • A normal rejection leaves nothing behind. Only a race, an I/O error or a device mismatch after directory creation can leave empty 0700 parent directories.

Evidence

• HE-10..16 (campaign scan 2), with the official limit table from the Environments Files guide.
• Recorded in environment-files.md, operation-evidence.md (register FW, row 27), official-semantics-alignment.md and environment-templates.md.

Validation

• Live acceptance on Core-managed Docker openai_hosted with Codex. Each phase's Core, daemon and helpers were built from the same tree and checked by sha256 inside the Runtime container. No model Turns.

  Case	main	candidate
  Nested path with missing parents	400 generic	201, listed
  Repeat of an earlier Files.create path	201, overwritten	400, bytes unchanged
  Directory destination	201 (created a file) / 400 generic	400 "file path conflicts…"
  File created by setup_commands	201, overwritten	400, sha256 unchanged
  Symlink parent to /tmp	400 generic	400 official message, /tmp/x.txt absent
  Inline 5 MiB + 1 / exactly 5 MiB	201 / 201 (over-limit file written)	400 official message / 201
  file_id copy of about 6 MiB	201	201, sha256 matches
  Tenant B	404	404

  RENAME_NOREPLACE is supported on the Runtime volume filesystem; a probe returned EEXIST. Cleanup and secret scans passed.

• Tests:

  • Rust installer tests: parents, conflicts, directory destination, symlink parent and leaf, FIFO, hard link, races and the fallback. Also fmt and clippy.
  • Daemon localworkspace tests, including the native-helper test run with the built helper; this test is opt-in outside this batch.
  • Gateway, Worker and API tests.
  • Real-PostgreSQL tests: no receipt on rejection, tenant B.
  • TS client and Core Web tests.

• Server gate: all make check targets plus Web typecheck, core-doctor, unit tests and build pass. The Playwright browser cases were not run on the server (no Google Chrome; the user approved the skip). make openapi is byte-identical.

• Independent blind review by a fresh Claude Code subagent (the user-approved replacement for GPT-6 Astra). It found no blockers and confirmed:

  • no-follow creation;
  • no replacement under races;
  • unchanged replace-mode callers;
  • fail-safe mixed versions;
  • consistent error mapping.

  Its documentation follow-ups are applied in the last commit, verified by focused tests and the gate without a new review, per the user's rule.

Runtime images (Codex, Claude and MiniMax Docker images, the E2B template and user-managed bundles) must be rebuilt for the new write semantics. No full protocol compatibility is claimed.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}