Publish reviewed AI Engineering Lab snapshot

LOCAL_QWEN.md

@@ -1,6 +1,6 @@
 # Optional key-free planning model
 
-This integration is off by default in source. The reviewed deployment enabled it on free ZeroGPU. The first hosted run loaded Qwen and made a tool call, then repeated the call and was stopped by the guard. The follow-up correction below still needs a successful hosted smoke before chat is described as ready.
+This integration is off by default in source. The reviewed deployment enabled it on free ZeroGPU. The first hosted run repeated a tool call and was stopped. The second reached final validation but returned an extra JSON wrapper. The format correction below still needs a successful hosted smoke before chat is described as ready.
 
 ## Activation
 
@@ -37,9 +37,9 @@ The model can select only the existing read-only planning tools. Typed workload
 
 The original agent validates final catalog IDs and tradeoff codes against recorded tool results. Python renders the accepted selection. Raw model prose is not an approved price comparison. The UI shows the answer as literal text and exposes the complete audit record as JSON. Before a new run, it clears the old answer and trace. A failed generation returns an explicit failure with no cached or fabricated substitute.
 
-After a completed tool response, the local adapter adds a checkpoint containing the effective calls and a Selection schema restricted to returned candidate IDs. It tells the model to finish if the requested comparisons are covered. A second turn may request a distinct missing comparison or break-even calculation. The third turn omits tools and rejects further tool output. The adapter never selects candidates on the model's behalf. Original repeat rejection and final ID validation remain unchanged.
+After a completed tool response, the local adapter adds a checkpoint containing effective calls, returned IDs, allowed codes, and four required response fields. It tells the model to finish if the requested comparisons are covered. A second turn may request a distinct missing comparison or break-even calculation. The third turn omits tools and rejects further tool output. One observed `selection_schema` wrapper is removed only when its contents already include all four fields and pass strict validation. The usage record flags that normalization. No choices or defaults are inserted. Original repeat rejection and final ID validation remain unchanged.
 
-Server failure logs contain only the exception class and an allowlisted reason code, such as `invalid_final_selection` or `turn_limit`. They do not contain exception bodies, prompts, raw model output, or tracebacks. Unknown failures receive `unclassified_runtime_error`.
+The application catches model errors inside the GPU callback before they cross the Spaces decorator. It returns a closed failure envelope with an allowlisted reason code, such as `invalid_final_selection` or `turn_limit`. Application logs omit exception bodies, prompts, raw model output, and tracebacks. Unknown failures receive `unclassified_runtime_error`. Hosting infrastructure can still record its own operational metadata.
 
 ## Release review
 

PUBLIC_MANIFEST.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "public-ai-lab-release/1",
-  "created_at": "2026-08-31T01:31:45.813385+00:00",
+  "created_at": "2026-08-31T01:46:02.860848+00:00",
   "owner": "Yogesh18018",
   "space_sdk": "gradio",
   "space_hardware": "zero-a10g",
@@ -9,8 +9,8 @@
   "files": [
     {
       "path": "LOCAL_QWEN.md",
-      "bytes": 4699,
-      "sha256": "b844706b4f2b97415eb9f0ab212e9b4e910d740568343ccd155fceb9fb642755"
+      "bytes": 5032,
+      "sha256": "1b9ac653e56ff25be72e1a52588492d531395942ad73772eb2c5ea698def3288"
     },
     {
       "path": "PUBLICATION.md",
@@ -19,8 +19,8 @@
     },
     {
       "path": "README.md",
-      "bytes": 7124,
-      "sha256": "5f104b476dd2cf026d2194566dde545615ab92f2f1adad70eb8acc757ff8d5b6"
+      "bytes": 7158,
+      "sha256": "82b625850f3e9ffc7a02cfa0bf4fe8f9226055e851dd2648a96b370ebf171718"
     },
     {
       "path": "app.py",
@@ -39,8 +39,8 @@
     },
     {
       "path": "lab/local_planner.py",
-      "bytes": 5186,
-      "sha256": "fa676c4c27f07f413ba6b94e680d67e520eb4223056af4e3bbe8caa6bb5c8e40"
+      "bytes": 8812,
+      "sha256": "a4620bb148486f7e94b1d9949fa6587caf64d6793a0fd4629fb621e45aa1971d"
     },
     {
       "path": "lab/paths.py",
@@ -54,8 +54,8 @@
     },
     {
       "path": "lab/ui.py",
-      "bytes": 29065,
-      "sha256": "0d6c843e4fd95e701080b26a686d8de70be0cc4ba24b948517c24322198728d3"
+      "bytes": 29412,
+      "sha256": "5a34fe8c6b16ac1c944cf6d88c7c8cbc30ef6c3d159b23190c6b790ead6b7b9e"
     },
     {
       "path": "projects/document_rag/data/samples/api_contract.md",
@@ -129,8 +129,8 @@
     },
     {
       "path": "projects/inference_planner/README.md",
-      "bytes": 6692,
-      "sha256": "b34af81cf8e3c862ecc2c6a7862d26e31d7c75fb0bd85554317f649abe98ca92"
+      "bytes": 6790,
+      "sha256": "c7f4ed42d05b0f5cea939547f7b7f4b30fdc495733b556b3748ef8fb844f40ec"
     },
     {
       "path": "projects/inference_planner/data/hardware_snapshot.json",
@@ -144,8 +144,8 @@
     },
     {
       "path": "projects/inference_planner/local_model_notes.md",
-      "bytes": 6307,
-      "sha256": "758bc0c069053705e4ee4fd70628a59ab839c34da429921922b99719475c5bd9"
+      "bytes": 6871,
+      "sha256": "e941b8cd21e05197c4d2d6b5d9b3fe0c9018a96b2d7a4cff84f192f5f4affc09"
     },
     {
       "path": "projects/inference_planner/outputs/live_agent_smoke.json",
@@ -184,8 +184,8 @@
     },
     {
       "path": "projects/inference_planner/planner/local_model.py",
-      "bytes": 16568,
-      "sha256": "a4f1df91e0de3f64d46c016a10f4c930acc7726182eb57901c29410e35d19e9c"
+      "bytes": 18306,
+      "sha256": "25b83f2cc02093c6ef60defc608e79e50763c915d5fceab8141b1be9f49a6ec1"
     },
     {
       "path": "projects/inference_planner/planner/service.py",
@@ -204,8 +204,8 @@
     },
     {
       "path": "projects/inference_planner/tests/test_local_model.py",
-      "bytes": 20734,
-      "sha256": "a6bee095041f5488e5ae0b61d539dfd0801a1be3aea82252aca342d2edc14b73"
+      "bytes": 25155,
+      "sha256": "ba7f0ce065582b406b33878642f77a89228adaebac68c2a32bc21d40082fccf0"
     },
     {
       "path": "projects/llm_evaluation_workbench/data/rubrics/bias_checks.md",
@@ -428,8 +428,8 @@
     },
     {
       "path": "tests/test_local_planner.py",
-      "bytes": 11600,
-      "sha256": "e4ea4cd2bfd5daf551bb9ef5fa7fd53abef911ab35c0f8bb98cb2cb258185b1e"
+      "bytes": 18459,
+      "sha256": "5bbf729865c1984c076162c6edf39baa3a93e31ab257d6fb085849cb167e946d"
     },
     {
       "path": "tests/test_publication.py",

README.md

@@ -54,8 +54,8 @@ Native PyTorch training code is included under `projects/newssnap/src/models`. A
 - The app does not write visitor text to its project files or a persistent vector index. Each retrieval request uses a unique ephemeral collection and deletes it in a `finally` block.
 - There are no file uploads or downloadable server paths. The launch configuration blocks the application directory from Gradio file serving.
 - Results and input fields can remain in the visitor's browser until cleared or the page is closed. Hosting infrastructure may retain operational request metadata. This is not a confidential-data service.
-- Provider generation is disabled in the prepared release. No API-key field is exposed.
-- A separate key-free Qwen planner can be enabled by the deployment owner after review. It uses the same typed cost tools and renders only validated catalog selections. It remains off by default. See `LOCAL_QWEN.md` for its startup guards, limits, and unverified GPU status.
+- External-provider generation is disabled in the public deployment. No API-key field is exposed.
+- The key-free Qwen planner uses the same typed cost tools and renders only validated catalog selections. It is off by default in source and enabled in the reviewed Space. See `LOCAL_QWEN.md` for its startup guards, limits, and current verification status.
 - The planner has an optional owner-only assistant. It remains unavailable unless the deployment owner separately configures the required model, key, enable flag, and access token. It requires the owner's code and explicit per-request send consent. No secrets are included in this release. The code field is cleared after a request.
 - GPU use follows Hugging Face's normal ZeroGPU queue and visitor quotas. Queueing time is not included in the measured classification latency.
 
@@ -69,7 +69,7 @@ The platform also installs `gradio[oauth,mcp]==6.10.0`. That version's MCP extra
 
 `suggested_hardware` is descriptive metadata. It does **not** allocate hardware. The guarded publication script separately requests `SpaceHardware.ZERO_A10G`, whose API value is `zero-a10g`.
 
-For local tests, create an isolated Python 3.12 environment, install `requirements-dev.txt`, and install `torch==2.8.0` from the official CPU wheel index. Run `python -m pytest`. The app also runs on CPU for local checks. GPU execution must be verified on the new Space before describing the public classifier as tested on ZeroGPU.
+For local tests, create an isolated Python 3.12 environment, install `requirements-dev.txt`, and install `torch==2.8.0` from the official CPU wheel index. Run `python -m pytest`. The app also runs on CPU for local checks. The hosted classifier passed anonymous API and browser checks on ZeroGPU on August 31, 2026 UTC. Recheck inference after changing its model or runtime.
 
 ## Source layout
 

lab/local_planner.py

@@ -3,6 +3,9 @@
 import logging
 import os
 from threading import Lock
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, ValidationError
 
 from .classification import zero_gpu_enabled
 from .services import pricing_catalog
@@ -12,7 +15,34 @@ _startup_attempted = False
 _startup_lock = Lock()
 _run_lock = Lock()
 
-FAILURE_CODES = {
+FailureReason = Literal[
+    "input_token_limit",
+    "incomplete_generation",
+    "invalid_tool_json",
+    "missing_first_tool",
+    "incomplete_tool_block",
+    "invalid_final_selection",
+    "invalid_tool_call",
+    "turn_limit",
+    "agent_time_limit",
+    "process_call_budget",
+    "runtime_not_ready",
+    "invalid_request",
+    "invalid_result",
+    "unclassified_runtime_error",
+]
+
+
+class LocalPlannerFailure(BaseModel):
+    """Only this small, closed failure record may cross the GPU process boundary."""
+
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    status: Literal["error"]
+    reason: FailureReason
+
+
+FAILURE_CODES: dict[str, FailureReason] = {
     "The local model input exceeded the token limit or batch format.": "input_token_limit",
     "The local model output was truncated. No partial tool call was accepted.": "incomplete_generation",
     "The local model returned invalid tool-call JSON.": "invalid_tool_json",
@@ -26,13 +56,76 @@ FAILURE_CODES = {
     "The optional local Qwen planner is not ready.": "runtime_not_ready",
 }
 
+FAILURE_MESSAGES: dict[FailureReason, str] = {
+    "input_token_limit": "The request exceeded the local model's input-token limit.",
+    "incomplete_generation": "The local model stopped before completing its response.",
+    "invalid_tool_json": "The local model returned a tool call that failed JSON validation.",
+    "missing_first_tool": "The local model did not select a required planning tool.",
+    "incomplete_tool_block": "The local model returned an incomplete tool call.",
+    "invalid_final_selection": "The model's selected options could not be verified against the tool results.",
+    "invalid_tool_call": "The local model selected an invalid or repeated planning tool.",
+    "turn_limit": "The local model reached its three-turn limit.",
+    "agent_time_limit": "The local comparison exceeded its time limit.",
+    "process_call_budget": "The local model's process call allowance has been reached.",
+    "runtime_not_ready": "The local Qwen runtime is not ready.",
+    "invalid_request": "Check the question and workload controls. Some values were not accepted.",
+    "invalid_result": "The local runtime returned an invalid result.",
+    "unclassified_runtime_error": "The local runtime could not complete this request.",
+}
+
+
+def local_failure(error: Exception) -> LocalPlannerFailure:
+    """Match known literal arguments without formatting an exception or its cause."""
+    reason: FailureReason = "unclassified_runtime_error"
+    if isinstance(error, ValidationError):
+        reason = "invalid_request"
+    else:
+        arguments = BaseException.args.__get__(error)
+        if len(arguments) == 1 and type(arguments[0]) is str:
+            reason = FAILURE_CODES.get(arguments[0], reason)
+    return LocalPlannerFailure(status="error", reason=reason)
+
+
+def local_failure_status(failure: LocalPlannerFailure) -> str:
+    return (
+        f"No comparison was accepted. {FAILURE_MESSAGES[failure.reason]} "
+        "The cost calculators remain available."
+    )
+
+
+def read_local_failure(record: object) -> LocalPlannerFailure | None:
+    """Reject malformed envelopes before treating a result as a successful comparison."""
+    invalid = LocalPlannerFailure(status="error", reason="invalid_result")
+    if type(record) is not dict:
+        return invalid
+    if any(key in record for key in ("status", "reason", "error")):
+        try:
+            return LocalPlannerFailure.model_validate(record)
+        except ValidationError:
+            return invalid
+    if type(record.get("answer")) is not str or not record["answer"].strip():
+        return invalid
+    return None
+
 
 def log_local_failure(error: Exception) -> None:
     """Log a class and an allowlisted reason code, never prompts or exception bodies."""
-    reason = FAILURE_CODES.get(str(error), "unclassified_runtime_error")
-    logging.getLogger(__name__).warning(
-        "Local Qwen request failed (%s; %s).", type(error).__name__, reason
-    )
+    reason = local_failure(error).reason
+    error_name = type(error).__name__
+    if error_name not in {
+        "AgentError",
+        "ValidationError",
+        "RuntimeError",
+        "ValueError",
+        "TypeError",
+        "TimeoutError",
+        "KeyError",
+        "ImportError",
+        "MemoryError",
+        "OSError",
+    }:
+        error_name = "Exception"
+    logging.getLogger(__name__).warning("Local Qwen request failed (%s; %s).", error_name, reason)
 
 
 def local_qwen_requested() -> bool:

lab/ui.py

@@ -17,8 +17,11 @@ from .classification import (
 )
 from .local_planner import (
     initialize_local_qwen,
+    local_failure,
+    local_failure_status,
     log_local_failure,
     local_qwen_status,
+    read_local_failure,
     run_local_comparison,
     validate_local_request,
 )
@@ -175,7 +178,14 @@ def run_owner_chat(
 
 @spaces.GPU(duration=110)
 def run_qwen_on_gpu(payload: dict) -> dict:
-    return run_local_comparison(payload, consent=True)
+    try:
+        return run_local_comparison(payload, consent=True)
+    except Exception as error:
+        # Spaces can print escaping exceptions with their causes and input details.
+        # Return only a validated reason code from inside the GPU callback instead.
+        failure = local_failure(error)
+        log_local_failure(error)
+        return failure.model_dump(mode="json")
 
 
 def run_public_qwen(
@@ -201,6 +211,9 @@ def run_public_qwen(
     try:
         request = validate_local_request(payload, consent)
         record = run_qwen_on_gpu(request.model_dump())
+        failure = read_local_failure(record)
+        if failure is not None:
+            return local_failure_status(failure), "", None
         return (
             "Local Qwen comparison completed. Inspect the source-backed selections below.",
             record["answer"],
@@ -208,12 +221,7 @@ def run_public_qwen(
         )
     except Exception as error:
         log_local_failure(error)
-        return (
-            "No comparison was accepted. The local model may be unavailable or may have failed "
-            "the format, evidence, token, or time checks. The cost calculators remain available.",
-            "",
-            None,
-        )
+        return local_failure_status(local_failure(error)), "", None
 
 
 @spaces.GPU(duration=20)

projects/inference_planner/README.md

@@ -20,7 +20,7 @@ The optional assistant calls three read-only planning tools and selects options
 - **Break-even:** cost-only request threshold. Capacity is calculated only when the user supplies measured requests per second for the exact deployment.
 - **Tool-calling assistant:** validated function arguments, user-controlled workload inputs, three model turns at most, five tools at most, a fixed provider URL, and an owner access code. Final selections must reference returned options. Unsupported prose and additional claims are rejected.
 
-The public Gradio interface is in `../public_ai_lab`. Its calculation tools work without a model-provider secret. Live LLM chat is disabled unless the deployment owner explicitly configures it. A replay or a cost table is never presented as a live LLM response.
+The public Gradio interface is in `../public_ai_lab`. Its calculation tools work without a model-provider secret. A separately enabled Qwen backend runs on free ZeroGPU. The optional NVIDIA backend requires private owner configuration. A replay or a cost table is never presented as a live LLM response. See the lab verification record for hosted chat status.
 
 ## Sources and freshness
 

projects/inference_planner/local_model_notes.md

@@ -1,6 +1,6 @@
 # Optional local Qwen backend
 
-Status: implemented and tested with injected doubles on August 30, 2026. No model weights were downloaded. Real Qwen inference, tool-selection quality, GPU latency and ZeroGPU deployment have **not** been tested. The public wrapper has not been changed by this task.
+Status: implemented and tested with injected doubles on August 30–31, 2026. The public ZeroGPU wrapper loaded the pinned Qwen model. Its first real comparison repeated a tool call and was stopped. A second run reached final validation but added a JSON wrapper and was rejected. The revised response instructions and narrow format normalization need a hosted check. See the lab verification record for current public status.
 
 ## Model identity
 
@@ -42,14 +42,16 @@ result = run_agent(ChatRequest.model_validate(user_payload), client)
 - Maximum three tool calls per completion. The unchanged agent also enforces five tools total, three model turns, repeated-call rejection, typed scenario values and source-grounded final selections.
 - The process-local daily `CallBudget` is retained. It is not a durable, per-user or provider-side quota and resets with a new process. Reuse one client and serialize requests in the wrapper.
 - No free-form model prose becomes a validated answer. The current agent validates the model's final `Selection` and renders it from recorded tool results.
+- After tool results, a checkpoint lists completed effective calls, returned candidate IDs, allowed codes, and four response fields. The model still chooses the IDs. A second turn can request a distinct missing calculation. The third turn has no tools and must finish. Original repeat rejection remains enabled.
+- A single observed `selection_schema` envelope can be unwrapped only when its value already contains all four fields and passes strict Selection validation. Nested wrappers, extra fields, omitted fields, and invalid values are rejected. No defaults or selections are inserted. Usage records flag an actual normalization. The original agent still rejects unknown IDs and empty selections when candidates exist.
 
 ## Loading and ZeroGPU handoff
 
-The wrapper owner must explicitly approve and implement loading. Use the pinned revision for both model and tokenizer, `trust_remote_code=False`, safetensors and compatible reviewed dependencies. The adapter trusts the objects supplied by the caller and does not itself authenticate their checkpoint provenance. Keep model allocation out of this adapter.
+The wrapper implements guarded startup loading with the pinned revision for both model and tokenizer, `trust_remote_code=False`, safetensors and reviewed dependencies. The adapter receives those objects and does not itself authenticate their checkpoint provenance. Model allocation stays outside this adapter.
 
 Current [official ZeroGPU documentation](https://huggingface.co/docs/hub/spaces-zerogpu) lists the Gradio SDK and PyTorch 2.8.0 onward. An older local CPU PyTorch environment is not a ZeroGPU compatibility test. Follow the documented startup CUDA-placement approach under `spaces` emulation, then decorate the GPU-dependent callback with `spaces.GPU`. Serialize this callback with the classifier callback if they share GPU resources. Set its duration for the whole bounded agent loop, not for one token-generation call.
 
-Eligible personal accounts may host two ZeroGPU Spaces free under the current policy. Account age, verification, good standing, queueing and daily compute quotas still apply. Eligibility was not checked. This is not unlimited free compute, and paid-account credit behavior must be reviewed before enabling it. No hosted NVIDIA key is needed by this local adapter.
+The lab's account was accepted for a free ZeroGPU Space. Native visitor quotas and queueing still apply. No paid hardware was requested. No hosted NVIDIA key is needed by this adapter.
 
 ## Verification
 
@@ -62,15 +64,15 @@ ruff check planner/local_model.py tests/test_local_model.py
 ruff format --check planner/local_model.py tests/test_local_model.py
 ```
 
-Observed with `ai-three-planner` on August 30, 2026:
+Observed with the planner environment on August 30–31, 2026:
 
-- Adapter tests: **66 passed in 0.37 seconds**.
-- Adapter plus existing agent tests: **83 passed in 0.42 seconds**.
+- Adapter tests: **93 passed**, including follow-up, exact-envelope, and filter-guidance regressions.
+- Complete planner suite: **384 passed**.
 - Ruff: all checks passed. Both files are formatted.
 
-The tests use explicit tensor, tokenizer and model doubles. They verify interface wiring and safeguards, including the existing agent's tool-to-selection round trip. They do **not** prove that Qwen will select the right tools or valid IDs on real questions. A real, authorized smoke test must precede any claim that public model chat works. No GPU allocation, provider inference, deployment, model download or secret access occurred in this task.
+The adapter tests use explicit tensor, tokenizer and model doubles. They verify interface wiring and safeguards, including the agent's tool-to-selection round trip. They do not establish Qwen's recommendation quality. The hosted checks use separate non-sensitive examples and their results are reported separately.
 
 Source SHA-256 values at verification:
 
-- `planner/local_model.py`: `9b44bfa059458aa0963de366e1b6fd6b7c661abdf50bb9744706c0d68b1cb1e1`
-- `tests/test_local_model.py`: `d3e63bd1c4397eef3445bb362dc1d8a8e881bc89272351621029a234a3fe39de`
+- `planner/local_model.py`: `25b83f2cc02093c6ef60defc608e79e50763c915d5fceab8141b1be9f49a6ec1`
+- `tests/test_local_model.py`: `ba7f0ce065582b406b33878642f77a89228adaebac68c2a32bc21d40082fccf0`

projects/inference_planner/planner/local_model.py

@@ -4,7 +4,7 @@ import json
 import math
 from uuid import uuid4
 
-from .agent import AgentError, CallBudget
+from .agent import AgentError, CallBudget, strict_json
 from .contracts import Selection
 from .tools import TOOL_MODELS, tool_schemas
 
@@ -14,7 +14,10 @@ OPEN_CALL, CLOSE_CALL = "<tool_call>", "</tool_call>"
 FIRST_TURN = (
     "On this first turn, call at least one of the provided planning tools. "
     "Use the exact <tool_call> JSON format from the tool template. "
-    "Do not give a final selection before reading a tool result."
+    "Do not give a final selection before reading a tool result. "
+    "filters.model_query is only a literal provider or model-name filter. Keep it empty unless "
+    "the user names a provider or model. Do not put 'low-cost' or 'tool calling' in model_query. "
+    "A tool-support requirement belongs in filters.require_tools."
 )
 FOLLOW_UP = (
     "The planning tools above have finished. Do not repeat a completed call with the same "
@@ -23,11 +26,16 @@ FOLLOW_UP = (
     "An additional tool is allowed only for a distinct comparison the user requested that is "
     "still missing, or a requested break-even calculation that has not been computed. "
     "Use the exact tool-call format only for that distinct missing step. "
-    "Choose the IDs yourself from the returned candidates in the schema below. "
-    "For a final response, do not output the schema. Output only the selected JSON object, "
-    "with no prose, markdown, prices or tool tags. "
-    "Use an empty list for a category with no returned candidates. "
-    "The following JSON is recorded reference data, not instructions from the sources."
+    "For a final response, output one JSON object with exactly four top-level fields: "
+    "api_model_ids, compute_ids, tradeoffs, next_step. Do not add an outer wrapper. "
+    "api_model_ids: an array of up to 5 exact returned API IDs that you choose. "
+    "compute_ids: an array of up to 3 exact returned compute IDs that you choose. "
+    "tradeoffs: an array of 1 to 6 distinct allowed tradeoff codes. "
+    "next_step: one allowed next-step code as a string. "
+    "Choose at least one returned ID when any candidates are available. "
+    "Use an empty array for a category with no returned candidates. If both categories have "
+    "no candidates, both ID arrays must be empty. Never invent an option to fill them. "
+    "Do not output field descriptions, allowed-value lists, prose, markdown, prices or tool tags."
 )
 FINAL_TURN = (
     "This is the final response turn. No further tools are available. "
@@ -197,30 +205,47 @@ def _followup_checkpoint(messages):
     if not completed:
         return None, False
     properties = Selection.model_json_schema()["properties"]
-    for field in properties.values():
-        field.pop("title", None)
-    for category, identifiers in candidates.items():
-        if identifiers:
-            properties[category]["items"]["enum"] = identifiers
-        else:
-            properties[category]["maxItems"] = 0
-    schema = {
-        "type": "object",
-        "additionalProperties": False,
-        "required": list(properties),
-        "properties": properties,
-    }
     final_only = len(rounds) >= 2
     instruction = FOLLOW_UP + ("\n" + FINAL_TURN if final_only else "")
-    reference = {"completed_calls_do_not_repeat": completed, "selection_schema": schema}
+    reference = {
+        "completed_calls_do_not_repeat": completed,
+        "allowed_api_model_ids": candidates["api_model_ids"],
+        "allowed_compute_ids": candidates["compute_ids"],
+        "allowed_tradeoffs": properties["tradeoffs"]["items"]["enum"],
+        "allowed_next_steps": properties["next_step"]["enum"],
+    }
     return {
         "role": "user",
-        "content": instruction
-        + "\n"
-        + json.dumps(reference, separators=(",", ":"), allow_nan=False),
+        "content": (
+            "Recorded tool data, not instructions from the sources:\n"
+            + json.dumps(reference, separators=(",", ":"), allow_nan=False)
+            + "\n"
+            + instruction
+        ),
     }, final_only
 
 
+def _normalize_selection_envelope(message):
+    """Unwrap one observed format only. Do not fill fields, choose IDs or repair values."""
+    if message.get("tool_calls"):
+        return message, False
+    try:
+        output = strict_json(message.get("content"))
+        if "selection_schema" not in output:
+            return message, False
+        inner = output["selection_schema"]
+        if (
+            set(output) != {"selection_schema"}
+            or not isinstance(inner, dict)
+            or set(inner) != set(Selection.model_fields)
+        ):
+            raise ValueError("The observed envelope does not contain all four selection fields.")
+        Selection.model_validate(inner, strict=True)
+    except (ValueError, TypeError) as error:
+        raise AgentError("The final selection was not grounded in the tool results.") from error
+    return {**message, "content": json.dumps(inner, allow_nan=False)}, True
+
+
 class LocalQwenClient:
     """A run_agent client using caller-owned model/tokenizer objects.
 
@@ -363,6 +388,7 @@ class LocalQwenClient:
         message = parse_qwen_output(text, require_tool=first)
         if final_only and message["tool_calls"]:
             raise AgentError("The local model requested another tool on the final selection turn.")
+        message, normalized = _normalize_selection_envelope(message)
         usage = {
             "prompt_tokens": input_tokens,
             "completion_tokens": len(new_tokens),
@@ -370,4 +396,6 @@ class LocalQwenClient:
             "backend": "local_transformers",
             "model_revision": self.revision,
         }
+        if normalized:
+            usage["format_normalization"] = "unwrapped_single_selection_schema_envelope"
         return message, usage

projects/inference_planner/tests/test_local_model.py

@@ -439,7 +439,7 @@ def completed_history(name="compare_api_options", arguments=None, result=None, c
 def checkpoint_reference(tokenizer):
     message = tokenizer.calls[-1][0][-1]
     assert message["role"] == "user"
-    return json.loads(message["content"].rsplit("\n", 1)[1])
+    return json.loads(message["content"].split("\n", 2)[1])
 
 
 def test_followup_uses_only_completed_returned_ids_and_effective_arguments():
@@ -463,9 +463,10 @@ def test_followup_uses_only_completed_returned_ids_and_effective_arguments():
     assert reference["completed_calls_do_not_repeat"] == [
         {"name": "compare_api_options", "effective_arguments": arguments}
     ]
-    fields = reference["selection_schema"]["properties"]
-    assert fields["api_model_ids"]["items"]["enum"] == ["fixture/returned", "fixture/second"]
-    assert fields["compute_ids"]["maxItems"] == 0
+    assert reference["allowed_api_model_ids"] == ["fixture/returned", "fixture/second"]
+    assert reference["allowed_compute_ids"] == []
+    assert "selection_schema" not in tokenizer.calls[-1][0][-1]["content"]
+    assert "exactly four top-level fields" in tokenizer.calls[-1][0][-1]["content"]
     assert "invented/user-requested" not in json.dumps(reference)
     assert "Untrusted prose" not in json.dumps(reference)
     assert "final Selection JSON NOW" in tokenizer.calls[-1][0][-1]["content"]
@@ -493,10 +494,14 @@ def test_third_turn_is_schema_only_and_does_not_prefill_a_selection():
     reference = checkpoint_reference(tokenizer)
     assert FINAL_TURN in tokenizer.calls[-1][0][-1]["content"]
     assert tokenizer.calls[-1][1]["tools"] == []
-    assert reference["selection_schema"]["properties"]["compute_ids"]["items"]["enum"] == [
-        "fixture/gpu"
-    ]
-    assert set(reference) == {"completed_calls_do_not_repeat", "selection_schema"}
+    assert reference["allowed_compute_ids"] == ["fixture/gpu"]
+    assert set(reference) == {
+        "completed_calls_do_not_repeat",
+        "allowed_api_model_ids",
+        "allowed_compute_ids",
+        "allowed_tradeoffs",
+        "allowed_next_steps",
+    }
     assert output["content"] == json.dumps(SELECTION)  # Unchanged generated text, not a fallback.
 
 
@@ -540,9 +545,9 @@ def test_break_even_ids_are_grounded_in_its_returned_api_and_compute_rows():
             result={"api": {"model_id": "fixture/api"}, "compute": {"id": "fixture/compute"}},
         )
     )
-    fields = checkpoint_reference(tokenizer)["selection_schema"]["properties"]
-    assert fields["api_model_ids"]["items"]["enum"] == ["fixture/api"]
-    assert fields["compute_ids"]["items"]["enum"] == ["fixture/compute"]
+    reference = checkpoint_reference(tokenizer)
+    assert reference["allowed_api_model_ids"] == ["fixture/api"]
+    assert reference["allowed_compute_ids"] == ["fixture/compute"]
 
 
 def test_invalid_completed_record_fails_before_generation():
@@ -552,3 +557,98 @@ def test_invalid_completed_record_fails_before_generation():
     with pytest.raises(AgentError, match="invalid completed tool records"):
         client.complete(messages)
     assert model.calls == []
+
+
+def test_first_turn_distinguishes_literal_name_filters_from_capability_filters():
+    client, _, tokenizer = make_client()
+    client.complete([{"role": "user", "content": "Compare low-cost tool calling."}], first=True)
+    prompt = tokenizer.calls[0][0][0]["content"]
+    assert "literal provider or model-name filter" in prompt
+    assert "Keep it empty unless" in prompt
+    assert "Do not put 'low-cost' or 'tool calling' in model_query" in prompt
+    assert "filters.require_tools" in prompt
+
+
+def test_known_single_wrapper_preserves_model_choices_and_records_normalization():
+    original = {**SELECTION, "tradeoffs": ["cache_assumptions"], "next_step": "measure_token_usage"}
+    client, _, _ = make_client([block(), json.dumps({"selection_schema": original})])
+    result = run_agent(ChatRequest(question="Compare this workload"), client, FixtureTools())
+    assert result["selection"] == original
+    assert (
+        result["usage"][-1]["format_normalization"] == "unwrapped_single_selection_schema_envelope"
+    )
+    assert "$3.2000" in result["answer"]
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        {"selection_schema": {"selection_schema": SELECTION}},
+        {"selection_schema": SELECTION, "extra": "do not discard"},
+        {"selection_schema": json.dumps(SELECTION)},
+        {"selection_schema": []},
+        {"selection_schema": None},
+        {"selection_schema": {"type": "object", "properties": {}}},
+        {
+            "selection_schema": {
+                key: value for key, value in SELECTION.items() if key != "api_model_ids"
+            }
+        },
+        {
+            "selection_schema": {
+                key: value for key, value in SELECTION.items() if key != "next_step"
+            }
+        },
+        {"selection_schema": {**SELECTION, "extra": "do not discard"}},
+        {"selection_schema": {**SELECTION, "tradeoffs": []}},
+        {"selection_schema": {**SELECTION, "api_model_ids": "fixture/model"}},
+        {"selection_schema": {**SELECTION, "next_step": "invented_code"}},
+        {"result": SELECTION},
+    ],
+)
+def test_envelope_normalization_never_repairs_incomplete_or_unrecognized_output(payload):
+    client, _, _ = make_client([block(), json.dumps(payload)])
+    with pytest.raises(AgentError, match="not grounded"):
+        run_agent(ChatRequest(question="Compare this workload"), client, FixtureTools())
+
+
+def test_duplicate_wrapper_keys_are_not_silently_repaired():
+    raw = (
+        '{"selection_schema":'
+        + json.dumps(SELECTION)
+        + ',"selection_schema":'
+        + json.dumps(SELECTION)
+        + "}"
+    )
+    client, _, _ = make_client([block(), raw])
+    with pytest.raises(AgentError, match="not grounded"):
+        run_agent(ChatRequest(question="Compare this workload"), client, FixtureTools())
+
+
+@pytest.mark.parametrize("api_ids", [[], ["invented/model"]])
+def test_normalized_selection_still_rejects_empty_or_unknown_choices_when_candidates_exist(api_ids):
+    selection = {**SELECTION, "api_model_ids": api_ids}
+    client, _, _ = make_client([block(), json.dumps({"selection_schema": selection})])
+    with pytest.raises(AgentError, match="not grounded"):
+        run_agent(ChatRequest(question="Compare this workload"), client, FixtureTools())
+
+
+def test_genuine_no_match_keeps_empty_lists_without_inventing_options():
+    class NoMatches:
+        def execute(self, name, arguments):
+            return {"options": [], "source_url": "https://openrouter.ai/api/v1/models"}
+
+    selection = {**SELECTION, "api_model_ids": [], "compute_ids": []}
+    client, _, tokenizer = make_client([block(), json.dumps({"selection_schema": selection})])
+    result = run_agent(ChatRequest(question="Compare this workload"), client, NoMatches())
+    assert result["selection"] == selection
+    assert "No options matched" in result["answer"]
+    reference = checkpoint_reference(tokenizer)
+    assert reference["allowed_api_model_ids"] == reference["allowed_compute_ids"] == []
+
+
+def test_bare_valid_selection_is_not_rewritten_or_marked_as_normalized():
+    client, _, _ = make_client([block(), json.dumps(SELECTION)])
+    result = run_agent(ChatRequest(question="Compare this workload"), client, FixtureTools())
+    assert result["selection"] == SELECTION
+    assert "format_normalization" not in result["usage"][-1]

tests/test_local_planner.py

@@ -226,10 +226,11 @@ def test_same_typed_agent_and_cached_catalog_are_used(monkeypatch):
     assert result["model_revision"] == MODEL_REVISION
 
 
-def test_missing_consent_never_requests_gpu(monkeypatch):
+@pytest.mark.parametrize("consent", [False, None, 0, 1, "true"])
+def test_missing_consent_never_requests_gpu(monkeypatch, consent):
     monkeypatch.setattr(ui, "run_qwen_on_gpu", lambda *a: pytest.fail("Unexpected GPU request"))
     status, answer, record = ui.run_public_qwen(
-        "Compare options", False, 1000, 2000, 500, 160, 8, 16, 4, False
+        "Compare options", consent, 1000, 2000, 500, 160, 8, 16, 4, False
     )
     assert "Approve" in status
     assert answer == ""
@@ -271,6 +272,192 @@ def test_failure_log_has_only_type_and_reviewed_code(caplog, message, reason):
     assert message not in caplog.text
 
 
+def public_inputs(**updates):
+    return {
+        "question": "Compare options",
+        "consent": True,
+        "requests": 1000,
+        "incoming": 2000,
+        "outgoing": 500,
+        "hours": 160,
+        "parameters": 8,
+        "bits": 16,
+        "kv_cache": 4,
+        "expose_port": False,
+        **updates,
+    }
+
+
+@pytest.fixture
+def gpu_body():
+    # Spaces returns the undecorated function when ZeroGPU is disabled. Never run
+    # these fake-model tests against an allocation-capable runtime.
+    assert ui.zero_gpu_enabled() is False
+    return ui.run_qwen_on_gpu
+
+
+@pytest.mark.parametrize(
+    "updates",
+    [
+        {"question": ""},
+        {"question": "private question " * 200},
+        {"requests": -1},
+        {"requests": float("nan")},
+        {"incoming": 0},
+        {"hours": 745},
+        {"parameters": float("inf")},
+        {"bits": 7},
+        {"kv_cache": -1},
+    ],
+)
+def test_invalid_public_controls_never_request_gpu(monkeypatch, updates):
+    enable_reviewed_runtime(monkeypatch)
+    monkeypatch.setattr(local_planner, "_client", object())
+    monkeypatch.setattr(ui, "run_qwen_on_gpu", lambda *a: pytest.fail("Unexpected GPU request"))
+    status, answer, record = ui.run_public_qwen(**public_inputs(**updates))
+    assert "Check the question and workload controls" in status
+    assert "private question" not in status
+    assert answer == ""
+    assert record is None
+
+
+def test_unready_public_runtime_never_requests_gpu(monkeypatch):
+    monkeypatch.setattr(ui, "run_qwen_on_gpu", lambda *a: pytest.fail("Unexpected GPU request"))
+    status, answer, record = ui.run_public_qwen(**public_inputs())
+    assert "local Qwen runtime is not ready" in status
+    assert answer == ""
+    assert record is None
+
+
+@pytest.mark.parametrize("message,reason", list(local_planner.FAILURE_CODES.items()))
+def test_gpu_helper_returns_safe_envelope_before_exception_can_escape(
+    monkeypatch, gpu_body, caplog, capsys, message, reason
+):
+    import json
+
+    from planner.agent import AgentError
+
+    payload = {"question": "PRIVATE_INPUT_SENTINEL"}
+
+    def fail(received, consent):
+        assert received is payload
+        assert consent is True
+        raise AgentError(message) from ValueError("PRIVATE_CAUSE_SENTINEL")
+
+    monkeypatch.setattr(ui, "run_local_comparison", fail)
+    record = gpu_body(payload)
+    assert record == {"status": "error", "reason": reason}
+    assert local_planner.LocalPlannerFailure.model_validate(record).reason == reason
+    captured = capsys.readouterr()
+    exposed = json.dumps(record) + caplog.text + captured.out + captured.err
+    assert message not in exposed
+    assert "PRIVATE_" not in exposed
+    assert "Traceback" not in exposed
+
+
+def test_gpu_failure_never_formats_exception_arguments_or_causes(monkeypatch, gpu_body, caplog):
+    import json
+
+    class UnprintableError(RuntimeError):
+        def __str__(self):
+            pytest.fail("Exception formatting must not run")
+
+        def __repr__(self):
+            pytest.fail("Exception repr must not run")
+
+    def fail(*args, **kwargs):
+        raise UnprintableError({"private": "PRIVATE_BODY_SENTINEL"}) from UnprintableError(
+            "PRIVATE_CAUSE_SENTINEL"
+        )
+
+    monkeypatch.setattr(ui, "run_local_comparison", fail)
+    record = gpu_body({})
+    assert record == {"status": "error", "reason": "unclassified_runtime_error"}
+    assert "PRIVATE_" not in json.dumps(record) + caplog.text
+    assert "UnprintableError" not in caplog.text
+
+
+@pytest.mark.parametrize("reason", list(local_planner.FAILURE_MESSAGES))
+def test_public_callback_handles_every_allowed_failure_without_a_result(monkeypatch, reason):
+    from planner.contracts import ChatRequest
+
+    monkeypatch.setattr(ui, "validate_local_request", lambda payload, _: ChatRequest(**payload))
+    monkeypatch.setattr(ui, "run_qwen_on_gpu", lambda _: {"status": "error", "reason": reason})
+    status, answer, record = ui.run_public_qwen(**public_inputs())
+    assert "No comparison was accepted" in status
+    assert local_planner.FAILURE_MESSAGES[reason] in status
+    assert answer == ""
+    assert record is None
+
+
+@pytest.mark.parametrize(
+    "returned",
+    [
+        None,
+        [],
+        {"status": "error"},
+        {"reason": "turn_limit"},
+        {"status": "success", "reason": "turn_limit"},
+        {"status": "error", "reason": "PRIVATE_UNREVIEWED_REASON"},
+        {"status": "error", "reason": ["turn_limit"]},
+        {"status": "error", "reason": "turn_limit", "answer": "PRIVATE_OLD_ANSWER"},
+        {"error": "PRIVATE_RAW_FAILURE", "answer": "PRIVATE_OLD_ANSWER"},
+        {"answer": None},
+        {"answer": {"private": "PRIVATE_UNVALIDATED_ANSWER"}},
+        {"answer": "  "},
+    ],
+)
+def test_malformed_gpu_results_are_not_mistaken_for_success(monkeypatch, returned):
+    from planner.contracts import ChatRequest
+
+    monkeypatch.setattr(ui, "validate_local_request", lambda payload, _: ChatRequest(**payload))
+    monkeypatch.setattr(ui, "run_qwen_on_gpu", lambda _: returned)
+    status, answer, record = ui.run_public_qwen(**public_inputs())
+    assert "local runtime returned an invalid result" in status
+    assert "PRIVATE_" not in status
+    assert answer == ""
+    assert record is None
+
+
+def test_gpu_success_is_returned_unchanged_and_later_failure_clears_it(monkeypatch, gpu_body):
+    from planner.contracts import ChatRequest
+
+    original = {
+        "answer": "Recorded source-backed comparison",
+        "selection": {"api_model_ids": ["fixture/model"]},
+        "tool_trace": [{"tool": "recorded test tool"}],
+        "usage": [{"total_tokens": 3}],
+        "backend": "local_transformers_zerogpu",
+        "provider_calls": 0,
+    }
+    monkeypatch.setattr(ui, "run_local_comparison", lambda *a, **k: original)
+    assert gpu_body({}) is original
+    monkeypatch.setattr(ui, "validate_local_request", lambda payload, _: ChatRequest(**payload))
+    monkeypatch.setattr(ui, "run_qwen_on_gpu", gpu_body)
+    status, answer, record = ui.run_public_qwen(**public_inputs())
+    assert "comparison completed" in status
+    assert answer is original["answer"]
+    assert record is original
+
+    def fail(*args, **kwargs):
+        raise RuntimeError("PRIVATE_LATER_FAILURE")
+
+    monkeypatch.setattr(ui, "run_local_comparison", fail)
+    status, answer, record = ui.run_public_qwen(**public_inputs())
+    assert "No comparison was accepted" in status
+    assert "PRIVATE_" not in status
+    assert answer == ""
+    assert record is None
+
+
+def test_failure_codes_and_status_messages_have_the_same_closed_set():
+    from typing import get_args
+
+    reasons = set(get_args(local_planner.FailureReason))
+    assert set(local_planner.FAILURE_MESSAGES) == reasons
+    assert set(local_planner.FAILURE_CODES.values()) <= reasons
+
+
 def test_disabled_local_planner_has_no_model_endpoint(monkeypatch):
     monkeypatch.setattr(ui, "planner_chat_status", lambda: {"enabled": False, "protected": False})
     app = ui.build_app()