feat: add failure-aware preflight and Qwen review

modelhub_submmit_api/README.md

@@ -20,6 +20,9 @@ It currently supports:
 - `hf_discovery.py`: ModelScope model discovery and inspection (keeps the legacy module name)
 - `modelhub_client.py`: ModelHub API client and token-pool routing
 - `history_stats.py`: online history aggregation, ranking, and warnings
+- `candidate_preflight.py`: repository, memory, context, and LLM-assisted compatibility gates
+- `failure_taxonomy.py`: deterministic/platform/semantic failure routing
+- `llm_classifier.py`: optional cached OpenAI-compatible ambiguity classifier
 - `template_selector.py`: template lookup and GPU normalization
 - `task_registry.py`: task-type and framework selection rules
 - `tests/`: unit tests and regression coverage
@@ -146,6 +149,32 @@ Common flags:
 - `--post-cycle-cooldown-seconds`: pause after a successful cycle before next cycle (default 2)
 - `--max-cycles`: optional hard stop for testing or batch windows
 
+Failure-informed preflight is enabled by default. It rejects deterministic
+missing-file and predicted-OOM cases, clamps unsafe context-length arguments,
+and records its decisions in `candidatePreflight` and each candidate's
+`preflightMetadata`. Use `--disable-candidate-preflight` only for diagnosis.
+
+The memory gate totals the complete recursive repository and applies the same
+20% overhead observed in ModelHub `PREFLIGHT_OOM` reports. All 14 currently
+verifiable GPU types have evidence-backed capacities; an incomplete repository
+size is deferred instead of estimated. See `../docs/gpu-memory-capacity-2026-08-10.md`.
+
+Optional Qwen review uses `MODELHUB_QWEN_ENDPOINT`, `MODELHUB_QWEN_MODEL`, and
+`MODELHUB_QWEN_API_KEY` (or `DASHSCOPE_API_KEY`). The generic
+`MODELHUB_LLM_CLASSIFIER_*` names remain supported. A root `.env` key named
+`dashscope` is loaded automatically, and the default model is `qwen3.7-flash`.
+Qwen is called only for
+unresolved architecture/remote-code semantics or ambiguous failure roots, with
+a default rolling limit of 20 calls/hour and one concurrent request. Only
+high-confidence denials block; an error, timeout, or abstention leaves the
+already-vetted candidate eligible.
+
+Outcome sync also classifies a bounded set of this worker's failed-task ZIP logs.
+Hard error signatures run first; ambiguous runtime roots can use the configured
+LLM. Platform faults are excluded from long-term compatibility scores and use a
+short 30-minute breaker after three consecutive failures. Failed log downloads
+are persisted and stop after three attempts.
+
 ## Output
 
 Run artifacts are written under: