Add append mode to WriteFile

[Otávio Carvalho (otaviocarvalho)]

Summary

Adds an optional append flag to WriteFileRequest (field 4, additive). When set on the first stream message, the guest opens the target with O_CREATE|O_WRONLY|O_APPEND instead of O_CREATE|O_WRONLY|O_TRUNC, creating the file if absent. Default behavior is unchanged: the flag defaults to false, and truncate remains the pinned, regression-tested path.

The flag follows the same first-message-open semantics as path and mode: the open happens once on the first chunk; subsequent messages are payload-only.

Use case

I operate a small fleet of autonomous agents on a self-hosted single-node k3s cluster (a NUC). The agents execute inside env guests and persist session state as append-only JSONL transcripts — one line per event (tool calls, outputs, checkpoints) — while a host-side supervisor tails those transcripts for resume-after-restart, dashboards, and off-cluster log shipping.

The workload is strictly incremental, which is where whole-file WriteFile semantics break down:

• Cost. Persisting one line requires a read-modify-write of the entire file. A transcript growing to a few hundred KB makes persisting N events O(N²) in bytes over the wire, with a full client-side buffer on every write.
• Concurrency. These files have multiple actors: the session process writes while host-side watchers tail and rotate. Whole-file writes open a lost-update window between actors; O_APPEND makes each write an atomic tail placement, so concurrent writers compose without external coordination.
• Current workarounds. Writes are routed through in-guest shell redirection, which bypasses the RPC layer (unaccounted bytes_written, unstructured errors), or handled with client-side segment ledgers that drift from filesystem state.

Append restores stream semantics for a file at minimal surface cost: one bool on an existing message. Checkpoint journals and other event-sourced state have the same access shape.

Deliberately out of scope here: directory enumeration — tracked separately in #74.

Compatibility

• Additive proto field: clients unaware of it send no field → false → truncate. No behavior change for existing callers.
• api proxies WriteFileRequest opaquely, so no api-side change; the flag traverses every proxy/route transparently (covered end-to-end through the real router + guest).

Tests

• TestAppendPreservesExistingContent — append retains prior bytes; multiple chunks arrive in order; bytes_written counts only new bytes
• TestAppendCreatesNewFile — append to a missing path creates it with the requested mode
• TestDefaultWriteStillTruncates — regression guard: unset flag preserves truncate semantics
• TestProxyAppendWrite — flag survives client → api → router → guest (real guest server behind the router)

All green: go test ./guest/filesystem/ ./internal/apiservice/ -count=1.

Notes for reviewers

• The flag is honored on the first message only (same rule as path/mode); later messages carry chunks.
• No LIST/GLOB in this change — filed as Idea: LIST/GLOB — enumerate guest files without shelling out #74 to keep this PR minimal; append alone unblocks transcript-style writes.