fix(preflight): break retry loops and give usable hints (#340, #334, #347, #305, #304)

[MattGyverLee]

Fixes five preflight/recovery problems that sent models (especially weaker ones) into retry loops or left them without a usable hint.

Closes #340
Closes #334
Closes #347
Closes #305
Closes #304

Changes

• bug: api_discovery_required inline discovery says 'resubmit' but identical resubmit is rejected again (loop) #340 -- api_discovery_required loop. When the gate inlines get_object_api docs, the inlined entities are now recorded as discovered, so the "resubmit" hint is true and an identical resubmit passes. The read-only redirect only grants them on the auto-discovery set (write isolation, Discover-and-run: execute read-only code with inline discovery instead of rejecting #47).
• dx: partial_module_structure rejects drive retry loops (identical resubmits, no assistance) #334 -- partial_module_structure retry loops.
  • A byte-identical resubmit of just-rejected code is detected and gets _assistance on the first repeat, for every gate. It fires only when the answer would repeat, so a resubmit that now legitimately passes (bug: api_discovery_required inline discovery says 'resubmit' but identical resubmit is rejected again (loop) #340, skip_module_check) isn't mislabeled.
  • operations.jsonl assistance_triggered now reflects what the response carries; it was hardcoded False.
  • The rejection leads with a mechanical bare-snippet auto_fixed_code, naming the def Main line removed. It is declined, with auto_fix_unavailable_reason, when inlining would change when names bind, delete a scaffold name the body reads, or rewrite a multi-line string.
  • Recipe pointers come from dx: recipes are never used -- surface them in search_by_capability and failure next_steps #335's shared path, once (see the merge note).
• bug: run_module drops report messages when the script raises #347 -- report messages lost on exception. The runner's except-branch now returns messages and summary alongside error, as run_scan already did.
• [WM] Preflight-check from flexicon import X names (and flexicon.Lexicon) with did-you-mean instead of raw ImportError #305 -- invented flexicon imports.
  • The new preflight error unknown_import rejects from flexicon import X / import flexicon.X when X doesn't exist, with did-you-mean suggestions (WfiWordformOperations -> WordformOperations, flexicon.Lexicon -> flexicon.code.Lexicon) and an access_path for accessors imported as classes.
  • flexicon is read statically (find_spec + ast, never imported), with an index fallback, and the check fails open.
  • A runtime flexicon ImportError gets the same candidates.
  • Contract: additive under tool-responses/1.x. The code count goes from 47 to 48, with a detail model, golden, TOOL-CONTRACT row and eval case.
• [WM] Guessed project.<X>Operations accessors: missing_imports gives circular import advice and invalid_api_chain misses sub-threshold names; map Operations suffix to facade accessor, emit access_path in search #304 -- guessed project.<X>Operations.
  • invalid_api_chain always flags project.<Name>Operations and maps it to the facade accessor (WordformOperations -> project.Wordforms).
  • missing_imports no longer suggests importing a name that is only used as project.<Name>.
  • Import aliases now resolve to the indexed class, which closes the project.Wordforms / WfiWordformOperations gap left by fix(preflight,index): #306 follow-ups -- real Operations class in chain gate, delegated/transaction writes marked mutating, stale gate counts #342.
  • search_by_capability and get_object_api derive access_path when the index lacks it.

Merge with main

Merged origin/main (#353 recipes, #354 write gate). Conflicts were in execution.py (_attach_assistance_if_loop), session.py and CHANGELOG.md; both sides were kept. The branch's own #334 recipe helper was dropped in favor of #335's _closest_recipes_for_failure, which already covers partial_module_structure and leaves out the recipe the code came from. Before that, a reject carried two recipe pointers; a test now asserts one.

Pattern audit

• [WM] Guessed project.<X>Operations accessors: missing_imports gives circular import advice and invalid_api_chain misses sub-threshold names; map Operations suffix to facade accessor, emit access_path in search #304/[WM] Preflight-check from flexicon import X names (and flexicon.Lexicon) with did-you-mean instead of raw ImportError #305: other accessor and import resolution sites. scripts/check_doc_snippets.py now uses the same alias resolver as the chain gate.
• bug: api_discovery_required inline discovery says 'resubmit' but identical resubmit is rejected again (loop) #340: the read-only redirect's inline-discovery path is handled too (auto-discovery set only).
• bug: run_module drops report messages when the script raises #347: run_scan's error path already copied messages; no other runner template drops them.

Tests

• Full offline suite (-m "not requires_flex"): 5090 passed, 4 skipped.
• scripts/validate_integrity.py server clean; pre-commit clean.
• An independent adversarial review ran on the branch, and its findings were fixed (the bare-snippet binding check and the identical-resubmit false-positive commits).

Live verification

None. These are offline preflight and response-shape changes; no FLEx project was opened.

Merge interactions

#343 (exclusive-access gate, draft) also adds an error code and edits execution.py. Whichever lands second needs the code count (48 here) and goldens reconciled.

🤖 Generated with Claude Code