[FIX] skills: file-write results are read back from disk (add write-file-b64)

[MartinEbner]

write-file and append-file return a static success atom (WRITE-FILE-SUCCESS) that certifies
only that the Prolog open/write/close calls succeeded — not that the intended content is on
disk. Two failure classes pass straight through it, both extensively documented by users running
agents on this stack: content mangled on the way to disk (nested quotes, backslashes) while the
write itself "succeeds", and the agent later claiming writes or byte counts with nothing in its
context to check against. "Read the file back after every write" as a prompt rule has repeatedly
proven unenforceable — the model skips it, and when asked to confirm it invents plausible numbers.
The check has to live in the harness, where it cannot be skipped.

This PR makes the skill result the verification. The file-writing skills route through a new
src/fileio.py (same py-call pattern as websearch/logger) and return a result built
exclusively from a read-back of the file on disk:

WRITE-VERIFIED file=/tmp/x.txt bytes=201 sha256=e02bd6c2bec42055 head='AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' tail='BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB'
APPEND-VERIFIED file=/tmp/log.txt bytes=12 sha256=2751a3a2f303ad21 head='line1\nline2\n' tail=''
WRITE-FAILED file=/nope/x.txt: [Errno 2] No such file or directory: '/nope/x.txt'
APPEND-FAILED file=/tmp/absent.txt: file does not exist

(real output of the implementation, not composed for the PR)

These values come from disk, not from the model — the agent relays them and can spot a mangled
write in the same cycle by comparing head/tail against what it intended. Failures return
explicit *-FAILED strings instead of raising into the loop (today a failed open surfaces as a
generic multi-command error with no file detail).

A new skill write-file-b64 takes base64-encoded content and writes the decoded bytes —
closing the quote/backslash-mangling class at the input side entirely (binary-safe; whitespace
inside the argument is tolerated, which future-proofs for #223's multi-line parsing — today's
line-based parser requires the argument on a single line, and the skill description says so).
The verified result then proves the round trip. Registered in helper.py command parsing and
lib_omegaclaw.metta like the other py-call modules; docs/reference-skills-io.md updated
(the Returns sections there said True, which was already out of date) with a write-file-b64
entry added.

Design notes:

• append-file keeps its contract: the file must exist, a trailing newline is added. Its bytes=
  reports the file size after the append (read-back ground truth), not the appended chunk size.
  On a missing file the result changes from a silent Prolog goal failure (no result at all) to
  the explicit APPEND-FAILED file=…: file does not exist.
• appendToHistory (memory.metta) keeps the Prolog-backed append under the name
  append-file-raw — it passes a (library …) file-spec term that only the Prolog open/4
  path resolves. After the rebase onto the merged OMEGA-239 (safe history/prompt reading), its
  exists-check + create collapses into the single append-file-raw call: append-file-raw
  drops the old body's leading exists_file guard, so open/4 in append mode creates a
  missing history file and the history path still self-heals (verified in PeTTa; exercised by
  mock/test_memory_missing_history_file_mock.py in run_mandatory). OMEGA-239's
  getPrompt/getHistory safe-reads are untouched.
• Nothing consumes the old WRITE-FILE-SUCCESS/APPEND-FILE-SUCCESS atoms (definition sites
  only), and string results are already the norm for skills (read-file, shell, metta,
  websearch).
• Result strings are single-line: head/tail snippets are 80 bytes with backslashes, newlines
  and carriage returns escaped (\\, \n, \r) — a literal backslash-n in content stays
  distinguishable from a real newline; sha256 is truncated to 16 hex chars and skipped for
  files over 2 MB. For files of 81–160 bytes the tail is omitted (head plus hash cover
  verification).
• Edge case, accepted: if the write lands but the read-back itself fails (file deleted or
  permissions changed in the same instant), the result is *-FAILED although bytes are on disk —
  erring on the side of the agent re-checking rather than trusting.
• write-file writes the exact bytes it was given (no implicit trailing newline).

Tests: Autotests/unit/test_fileio_verified_writes.py — 11 in-process unit tests (module
loaded by file path; no container, network, or token), wired into Autotests/run_mandatory:
disk read-back correctness (bytes/sha256/head/tail), quotes-and-backslashes land byte-exact,
UTF-8 byte counting, long-content snippets, a literal backslash-n stays distinguishable from a
real newline in snippets, append adds the newline and verifies the whole file, write-failure and
append-to-missing-file return explicit failure strings, b64 round-trip of hostile content,
line-wrapped b64 accepted, invalid b64 rejected without writing. The existing mock/ container
tests (test_create_file_mock etc.) exercise the rewired skills end-to-end.

Run: pytest --confcutdir=Autotests/unit Autotests/unit/ (the --confcutdir skips the
container-session fixture in the Autotests root conftest; CI runs the file via run_mandatory).

Related open PRs:

• Fix append-file concatenating without a newline (#204) #233 (fix for Bug 9: append-file Concatenates Without Newline After write-file #204, reworked since this description was first written): write-file is
  untouched there now and stays exact-bytes per the maintainer call on Bug 9: append-file Concatenates Without Newline After write-file #204 — so the design
  question originally flagged here is settled. The reworked Fix append-file concatenating without a newline (#204) #233 adds a Prolog line_separator/2
  so append-file starts on a fresh line when the file doesn't already end with a newline.
  Complementary: this PR keeps append-file's existing trailing-newline-only behavior, so it
  does not by itself fix Bug 9: append-file Concatenates Without Newline After write-file #204 (the read-back makes the concatenation visible, not prevented).
  Both PRs touch the same skills.metta lines, so whichever lands second resolves a small real
  conflict: if Fix append-file concatenating without a newline (#204) #233 lands first, this PR ports the line-start guard into fileio.append_file at
  rebase (read the last byte, prepend the newline when missing — the verified result then covers
  it); if this PR lands first, the same port applies on Fix append-file concatenating without a newline (#204) #233's side.
• [OMEGA-174] Multi-line command argument parsing of MeTTaClaw #223 (multi-line command argument parsing): complementary — better arg parsing reduces how
  often content arrives mangled; write-file-b64 bypasses the quoting layer entirely and the
  verified result proves byte exactness. The two-set registration in helper.py rebases
  mechanically onto [OMEGA-174] Multi-line command argument parsing of MeTTaClaw #223's rework (it keeps both sets).
• [OMEGA-240] skills | add get-io-policy skill #260 (get-io-policy): edits the same getSkills lines this PR rewrites (the append-file
  description line) — a small textual conflict, whichever lands second rebases mechanically.
  No semantic coupling: get-io-policy is read-only policy introspection.
• [FIX] telegram: don't abort remaining chunks when one chunk fails; greppable send-status log lines #240/[FIX] telegram: queue sends issued before the adapter is ready instead of dropping them #242 (ours): only overlap is one appended line each in Autotests/run_mandatory —
  trivial union rebase for whichever lands later.
• [OMEGA-181] System Versioning #238/Solution for the issues #206 and #199 #227 touch adjacent hunks of skills.metta/helper.py — mechanical merges either way.

(This branch is rebased onto current main, which already includes the merged #222 plugin API
and OMEGA-239 — both merged cleanly.)