writer: the rail owns `file`, so stop rejecting plans over it

Reported from a live 3-hop write that converged on attempt 3 of 3:

attempt 1: subject 1 is missing name, locked, context;
@hero_face must keep file 'gibsonlethal.webp', not
'hero_face.webp'; @hero_face needs desc
attempt 2: subject 1 is missing name, locked, context;
@hero_face needs desc; @hero_outfit needs desc
repair turn: desc and subject prose are required by the schema

The filename error cost two attempts, not one. `_only_register_prose_gaps`
fires the tightened-schema repair -- the one that removes the empty path from
the grammar, because a legal `"subjects": {}` is the cheapest completion and
repair prose does not outvote it -- only when EVERY error is a prose gap. A file
mismatch is not one, so attempt 1 got the weak generic turn and the repair that
works was held back a full round.

It was never the writer's field. The rail pins a tag to a picture, and validate
holds the right filename in `by_tag` while rejecting the plan for not having it
-- the same argument already written down for `mp` in `_restore_rail_only`. The
model is not even guessing here: it renames a real file to match the tag it was
handed. Tidy, and wrong.

`_restore_pinned_files` puts it back before validate sees it, keyed on a real
tag match, and prints what it changed. Deliberately NOT a RAIL_ONLY_FIELD: that
loop drops a field the rail cannot supply, which is right for `mp` and
destructive for `file`, because on a brief-only write the model's filename off
the folder listing is the only one there.

Verified against the reported errors verbatim: those three give the weak turn,
the same three minus the filename give the tightened one. validate keeps the
mismatch error as the backstop for hand-authored plans, and its test stays.

Six new tests; all 9 checks pass. DEVLOG section 35.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014VB4Dw6F79643vySkf19KV

docs/DEVLOG.md

@@ -1854,3 +1854,58 @@ and this does not.
 The lesson is the older one, in a new place: a control that *displays* a value
 it has not committed is worse than one that displays nothing. Section 31 caught
 a lint that cried wolf; this is a dropdown that cried yes.
+
+## 35. The rail already had the answer (2026-09-02)
+
+The Arch reporter from section 34, writing their first plan once the panel
+worked:
+
+    attempt 1: subject 1 is missing name, locked, context;
+               @hero_face must keep file 'gibsonlethal.webp', not
+               'hero_face.webp'; @hero_face needs desc
+    attempt 2: subject 1 is missing name, locked, context;
+               @hero_face needs desc; @hero_outfit needs desc
+    repair turn: desc and subject prose are required by the schema
+    wrote a 3-hop plan in 3 attempt(s)
+
+It converged, one attempt from failing. The interesting line is the middle one
+on attempt 1, and not for the reason it looks like.
+
+`_only_register_prose_gaps` fires the tightened-schema repair -- the one that
+removes the empty path from the grammar, because section 31 established that
+while `"subjects": {}` is legal it is also the cheapest legal completion and no
+amount of repair prose outvotes it. That gate requires EVERY error to be a
+prose gap. A file mismatch is not one. So attempt 1 got the weak generic
+"change only what the errors name" turn, attempt 2 produced the same subject
+error again, and only then -- with the file error gone -- did the mechanism
+that actually works get to run.
+
+**One misnamed file cost two attempts: its own, and the round it kept the real
+repair from firing in.**
+
+It was never the model's field. The rail pins a tag to a picture, and
+`validate` is holding the correct filename in `by_tag` at the moment it rejects
+the plan for not having it. This is the argument already written down for `mp`
+in `_restore_rail_only` -- *spend an attempt on a rejection the rail already had
+the answer to* -- and `file` is a stronger case than `mp` ever was, because the
+model is not even guessing: it is renaming a real file to match the tag it was
+given. `gibsonlethal.webp` becomes `hero_face.webp`. Tidy, and wrong.
+
+`_restore_pinned_files` now puts it back before validate sees it, keyed on a
+real tag match, and prints what it changed.
+
+**Why it is not simply another `RAIL_ONLY_FIELD`.** That loop drops a field the
+rail cannot supply, which is exactly right for `mp` -- an invented megapixel cap
+is never wanted -- and destructive for `file`. On a brief-only write the rail is
+empty and the filename the model read off the folder listing is the only one
+there. The repair has to touch pinned rows and nothing else, which is the whole
+difference between restoring a field and owning one.
+
+Checked against the reported errors verbatim: three errors give the weak turn,
+the same three minus the filename give the tightened one. The plan that took
+three attempts should now take two, and a rail whose filenames do not resemble
+their tags -- which is most rails, since photographs arrive named by the camera
+or the download -- stops being a hazard at all.
+
+The older lesson underneath: every field the node can determine and chooses to
+reject instead is an attempt spent, and attempts are a budget of three.

planner.py

@@ -948,6 +948,52 @@ def _restore_rail_only(ref_text, pinned):
     return json.dumps(obj, indent=2) if touched else ref_text
 
 
+def _restore_pinned_files(ref_text, pinned):
+    """Make the rail authoritative for `file` on the rows it pins.
+
+    -> (ref_text, {tag: filename}) for whatever had to be put back.
+
+    The rail pins a tag to a picture, so `file` is not the writer's field to
+    choose on a pinned row -- and `validate` is already holding the right value
+    in `by_tag` at the moment it rejects the plan for not having it. A model
+    that has just looked at the photograph names the file after the tag:
+    `gibsonlethal.webp` came back as `hero_face.webp`, which is tidy, and wrong.
+
+    That cost two attempts rather than one. `_only_register_prose_gaps` fires
+    the tightened-schema repair -- the one that takes the empty path out of the
+    grammar -- only when EVERY error is a prose gap, and a file mismatch is not
+    one. So the round that could have been repaired properly got the weak
+    generic turn instead, and the mechanism that works was delayed until the
+    next one. Live 2026-09-02: converged on attempt 3 of 3, one from failing.
+
+    Keyed on a real tag match ONLY, and deliberately NOT a `RAIL_ONLY_FIELD`:
+    that loop DROPS a field the rail cannot supply, which is correct for `mp`
+    and destructive here. On a brief-only write the rail is empty and the
+    model's filename, read off the folder listing, is the only one there.
+    """
+    obj = _parse_obj(ref_text)
+    if not isinstance(obj, dict):
+        return ref_text, {}
+    by_tag = {}
+    for p in (pinned or []):
+        if not isinstance(p, dict):
+            continue
+        tag = str(p.get("tag") or "").lstrip("@").strip()
+        fname = str(p.get("file") or "").strip()
+        if tag and fname:
+            by_tag[tag] = fname
+    fixed = {}
+    for r in (obj.get("refs") or []):
+        if not isinstance(r, dict):
+            continue
+        tag = str(r.get("tag") or "").lstrip("@").strip()
+        want = by_tag.get(tag)
+        if want and str(r.get("file") or "").strip() != want:
+            r["file"] = want
+            fixed[tag] = want
+    return (json.dumps(obj, indent=2) if fixed else ref_text), fixed
+
+
 def _remap_pinned_tags(shot_text, ref_text, pinned):
     """Rename invented tags back to the rail's, matching on `file`.
 
@@ -1212,6 +1258,15 @@ async def write_plan(brief, hops, *, complete_fn, files=None,
             # Before validate, so a restored `mp` is what the lints and the
             # returned plan both see, on the failure path as well as the ok one.
             ref_text = _restore_rail_only(ref_text, pinned)
+            # Same argument as `mp` above, and the same place to make it: the
+            # rail owns `file` on a row it pins, so a renamed one is repaired
+            # here rather than spending an attempt -- and, worse, blocking the
+            # tightened-schema repair by not being a prose gap.
+            ref_text, refiled = _restore_pinned_files(ref_text, pinned)
+            if refiled:
+                print(f"[{TAG}] rail filenames restored: "
+                      + ", ".join(f"@{t} -> {f}" for t, f in refiled.items()),
+                      flush=True)
         if not shot_text:
             last_errors = ["the reply contained no JSON. Answer with the two "
                            "JSON blocks and nothing else."]

tools/check_planner.py

@@ -241,6 +241,31 @@ def main():
     ck("a pinned row cannot change file",
        any("cook_face.png" in e for e in errs), "; ".join(errs[:1]))
 
+    # ...but the writer loop repairs it before validate ever sees it, because
+    # the rail already holds the answer. gemma renamed gibsonlethal.webp to
+    # hero_face.webp live on 2026-09-02: one attempt for the mismatch itself,
+    # and a second because a file error is not a prose gap, so it suppressed
+    # the tightened-schema repair for a whole round.
+    healed, refiled = PL._restore_pinned_files(json.dumps(stolen), pinned)
+    ck("the rail's filename is put back", refiled == {"ref_1": "cook_face.png"},
+       repr(refiled))
+    errs2, _ = PL.validate(json.dumps(rail_shots), healed,
+                           hops=2, known_files=[p["file"] for p in pinned],
+                           pinned=pinned)
+    ck("and the repaired plan then validates", not errs2, "; ".join(errs2[:2]))
+    ck("a register needing no repair is returned unchanged",
+       PL._restore_pinned_files(healed, pinned) == (healed, {}))
+
+    # NOT a RAIL_ONLY_FIELD. That loop drops what the rail cannot supply, which
+    # would delete the only filename a brief-only write has.
+    loose = json.dumps({"refs": [{"tag": "someone", "file": "found.png",
+                                  "subject": 1, "desc": "a face"}],
+                        "subjects": {}})
+    ck("a brief-only write keeps the filename the model chose",
+       PL._restore_pinned_files(loose, []) == (loose, {}))
+    ck("and so does a tag the rail does not pin",
+       PL._restore_pinned_files(loose, pinned) == (loose, {}))
+
     extra = json.loads(json.dumps(rail))
     extra["refs"].append({"tag": "hallway", "file": "apron.png"})
     errs, _ = PL.validate(json.dumps(rail_shots), json.dumps(extra),