runtime: re-init RKLLM on rc=-1 + restore FULL EXAMPLE w/ anti-mimicry framing

Two model-quality fixes for failures observed in lab transcripts:

1. RKLLM rc=-1 recovery

The native rkllm_run returns -1 when the runtime is in a stuck
state — most commonly after an aborted prior generation leaves
the KV cache in a half-state. Lab 2026-05-28: clicking "Try
again with the same question" reliably hit
`[RKLLM_GENERATE_FAILED] rkllm_run returned -1` at T+0s,
killing the session.

The bridge now catches the rc=-1 case specifically (substring
match on "returned -1" in the error message so other
RKLLMLoadError shapes — timeouts, callback errors, init failures
— bubble unchanged), destroys + re-inits the runtime, and
retries the same generate() call ONCE with keep_history=0
(cache was wiped). If the retry also fails, the bridge emits
the error event AND a synthetic insufficient_data verdict in
the same stream so the app's Try-Again CTA surfaces (raw error
events have no Try-Again gate; only synthetic-verdict
root_causes trigger it).

2. FULL EXAMPLE restored with anti-mimicry framing

Earlier today (c919a1d) the FULL EXAMPLE three-turn flow was
deleted from the system prompt on advisor input — the model was
pattern-copying entire example structures, not just numbers.
Lab transcripts since then show the model producing
unanchored prose (e.g. "# Onboarding\n\nThe Blox app asks you
to name the symptom...") that has zero relation to the user's
request. Net effect of the deletion: the model has even less
format anchoring than before.

Restored a SHAPE-only example that uses uppercase placeholders
(<TOOL_NAME>, <ONE_SENTENCE_FROM_YOUR_DATA>, etc.) and an
explicit "mimic the STRUCTURE, not the words. Do NOT mention
any of the placeholder labels in your output" framing.
Counters the pattern-copy risk by removing memorable content
to copy. Added "Do NOT use markdown headings" to the
FIRST ACTION section since lab transcripts showed the model
emitting `# Onboarding`-style headers despite the existing
"no markdown" rule elsewhere — the closer the rule is to the
first-token directive, the more reliably small models honor it.

Two new unit tests:
  - rc=-1 → destroy + re-init + retry succeeds → verdict came
    through
  - rc=-1 → re-init retry ALSO fails → error event + synthetic
    insufficient_data verdict emitted, recoverable=true, Try-Again
    button reachable

All 258 existing tests still pass.

Bigger-picture concern (out of scope for this commit, surfaced
to user): Qwen3-1.7B fine-tuned on 174 examples appears to be
overfitting to specific training phrases and falling back to
those phrases on novel inputs. The longer-term fix is either
(a) audit + clean the training set, (b) move to Qwen2.5-3B as
the original plan specified, or (c) drop the fine-tune entirely
and use a more directive system prompt with the stock model.
The user picked this "quick win" path; deeper options remain on
the table.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: ehsan6sha

src/runtime/rkllm_runtime.py

@@ -625,7 +625,27 @@ def destroy(self) -> None:
 
 Your VERY FIRST output token MUST start a <tool_call> block. Do NOT
 repeat these instructions back. Do NOT acknowledge. Do NOT explain
-what you are about to do. Start with `<tool_call>{{"name":"diag/`.
+what you are about to do. Do NOT use markdown headings (#, ##).
+Start with `<tool_call>{{"name":"diag/`.
+
+# FORMAT SHAPE — mimic the STRUCTURE, not the words
+
+Below is the SHAPE a healthy session takes across three model turns.
+**The words are placeholders. Do NOT copy them. Do NOT mention any
+of the placeholder labels in your output.** Use the actual user
+request + real <tool_response> data you receive to fill in your own
+content.
+
+Turn 1 (after the user's request arrives):
+<tool_call>{{"name":"diag/<TOOL_NAME>","arguments":{{}}}}</tool_call>
+
+Turn 2 (after the runtime injects a <tool_response>...</tool_response>
+into your context):
+<tool_call>{{"name":"diag/<NEXT_TOOL>","arguments":{{}}}}</tool_call>
+
+Turn 3 (when you've seen enough tool data to decide):
+<verdict>{{"summary":"<ONE_SENTENCE_FROM_YOUR_DATA>","severity":"<green|yellow|red>","root_cause":"<SHORT_TOKEN>"}}</verdict>
+<recommendation>{{"action_name":"<one_of_the_action_names_above>","args":{{}},"reasoning":"<WHY_FROM_YOUR_DATA>","confidence":<0_TO_1>,"tier":<2_OR_3>}}</recommendation>
 
 # VERDICT RULES
 
@@ -1183,13 +1203,89 @@ async def run_troubleshoot(
                     ),
                 )
             except RKLLMLoadError as e:
-                yield {
-                    "type": "error",
-                    "code": "RKLLM_GENERATE_FAILED",
-                    "message": str(e)[:500],
-                    "recoverable": False,
-                }
-                return
+                err_msg = str(e)
+                # rc=-1 from rkllm_run typically indicates the runtime
+                # is in a stuck state (KV cache corruption after an
+                # aborted prior generation, partial template state,
+                # etc.). The only known recovery is destroy + re-init.
+                # Try ONCE per turn — if the retry also fails, surface
+                # the error AND emit a synthetic insufficient_data
+                # verdict so the app's Try-Again button still surfaces
+                # (the bare error event currently has no Try-Again gate).
+                #
+                # We only attempt re-init for the rc=-1 family ("returned -1"
+                # in the message) — other errors (timeouts, callback
+                # signalled RUN_ERROR, init failed) point at deeper
+                # issues that re-init won't fix and that should bubble
+                # to the user with the original message intact.
+                reinit_ok = False
+                if "returned -1" in err_msg:
+                    try:
+                        logger.warning(
+                            "rkllm_run returned -1; destroying + re-initializing runtime"
+                        )
+                        self._runtime.destroy()
+                        self._runtime.init_model()
+                        reinit_ok = True
+                    except Exception as reinit_e:  # noqa: BLE001
+                        logger.exception(
+                            "rkllm re-init failed after rc=-1: %s", reinit_e
+                        )
+
+                if reinit_ok:
+                    # Retry the SAME generate() call once. keep_history
+                    # is reset because destroy() wiped the KV cache.
+                    try:
+                        output = await loop.run_in_executor(
+                            None,
+                            lambda r=next_role, c=next_content, t=next_thinking: (
+                                self._runtime.generate(
+                                    c,
+                                    role=r,
+                                    enable_thinking=t,
+                                    keep_history=0,  # cache was wiped
+                                    timeout_s=PER_TURN_TIMEOUT_S,
+                                )
+                            ),
+                        )
+                    except (RKLLMLoadError, asyncio.TimeoutError) as retry_e:
+                        # Retry also failed — surface both the error
+                        # event AND a synthetic verdict so Try-Again
+                        # is reachable.
+                        yield {
+                            "type": "error",
+                            "code": "RKLLM_GENERATE_FAILED",
+                            "message": f"after re-init retry: {str(retry_e)[:400]}",
+                            "recoverable": True,
+                        }
+                        yield {
+                            "type": "verdict",
+                            "payload": {
+                                "summary": "Blox AI runtime stalled; please try again.",
+                                "severity": "yellow",
+                                "root_cause": "insufficient_data",
+                            },
+                        }
+                        return
+                else:
+                    # Initial -1 + re-init failed, OR a non--1 RKLLM
+                    # error. Surface as before + emit a synthetic
+                    # verdict so Try-Again is reachable.
+                    yield {
+                        "type": "error",
+                        "code": "RKLLM_GENERATE_FAILED",
+                        "message": err_msg[:500],
+                        "recoverable": True,
+                    }
+                    yield {
+                        "type": "verdict",
+                        "payload": {
+                            "summary": "Blox AI runtime stalled; please try again.",
+                            "severity": "yellow",
+                            "root_cause": "insufficient_data",
+                        },
+                    }
+                    return
             except asyncio.TimeoutError:
                 yield {
                     "type": "error",

tests/test_rkllm_runtime.py

@@ -586,6 +586,109 @@ def test_guardrail_does_not_drop_when_user_did_NOT_complain_about_connectivity()
     assert out[0]["confidence"] == 0.6  # but still capped
 
 
+def test_rkllm_minus_one_triggers_destroy_reinit_and_retry():
+    """Lab 2026-05-28: clicking Retry on a previous session sometimes
+    hit `rkllm_run returned -1` at T+0s — the native runtime gets
+    stuck after an aborted prior generation. The bridge now destroys
+    + re-inits the runtime + retries the same generate() call ONCE
+    before yielding the error. If the retry succeeds, the model's
+    output proceeds normally; if it fails, we yield the error AND
+    a synthetic insufficient_data verdict so the app's Try-Again
+    CTA surfaces (raw error events have no Try-Again gate)."""
+    import asyncio
+    from src.runtime.rkllm_runtime import RKLLMBackend, RKLLMLoadError
+
+    state = {"calls": 0, "destroyed": False, "reinited": False}
+
+    class FlakyRuntime:
+        def generate(self, prompt, role="user", enable_thinking=False, keep_history=0, timeout_s=90.0):
+            state["calls"] += 1
+            if state["calls"] == 1:
+                raise RKLLMLoadError("rkllm_run returned -1")
+            # After re-init, second call succeeds with a verdict-only
+            # output (no tool_call) so the loop terminates cleanly on
+            # the next condition check. The runtime guard fires only
+            # once per generate call, so loop-iteration ends here.
+            return (
+                '<verdict>{"summary":"ok now","severity":"green","root_cause":"recovered_after_reinit"}</verdict>'
+            )
+
+        def destroy(self):
+            state["destroyed"] = True
+
+        def init_model(self):
+            state["reinited"] = True
+
+    backend = RKLLMBackend(loaded=True, _runtime=FlakyRuntime())
+    backend.wire_runtime_deps(tool_executor=None, action_signer=lambda x: "f" * 64)
+
+    async def collect():
+        return [ev async for ev in backend.run_troubleshoot("retry")]
+
+    events = asyncio.run(collect())
+    # Runtime was destroyed + re-inited
+    assert state["destroyed"] is True
+    assert state["reinited"] is True
+    # 2 calls inside turn 0 (initial -1 + retry) is what we want; the
+    # no-evidence guardrail then overrides because no tool calls
+    # succeeded, but the runtime calls are bounded.
+    assert state["calls"] == 2
+    # A verdict came through — either the model's recovered_after_reinit
+    # OR the no-evidence guardrail's insufficient_data override (both
+    # acceptable here; the point is the runtime recovered).
+    verdicts = [e for e in events if e["type"] == "verdict"]
+    assert len(verdicts) == 1
+    assert verdicts[0]["payload"]["root_cause"] in (
+        "recovered_after_reinit",
+        "insufficient_data",
+    ), verdicts[0]
+
+
+def test_rkllm_minus_one_retry_failure_emits_error_plus_synthetic_verdict():
+    """If the re-init retry ALSO returns -1 (or any other failure),
+    the bridge emits the error event AND a synthetic insufficient_data
+    verdict in the same stream so the app's synthetic-detector
+    triggers the Try-Again button. Without the second yield the user
+    is stuck on a bare error with only Start-new-chat."""
+    import asyncio
+    from src.runtime.rkllm_runtime import RKLLMBackend, RKLLMLoadError
+
+    state = {"calls": 0}
+
+    class StuckRuntime:
+        def generate(self, prompt, role="user", enable_thinking=False, keep_history=0, timeout_s=90.0):
+            state["calls"] += 1
+            raise RKLLMLoadError("rkllm_run returned -1")
+
+        def destroy(self):
+            pass
+
+        def init_model(self):
+            pass
+
+    backend = RKLLMBackend(loaded=True, _runtime=StuckRuntime())
+    backend.wire_runtime_deps(tool_executor=None, action_signer=lambda x: "f" * 64)
+
+    async def collect():
+        return [ev async for ev in backend.run_troubleshoot("retry")]
+
+    events = asyncio.run(collect())
+
+    # Two generate attempts were made (original + retry post re-init)
+    assert state["calls"] == 2
+    types = [e["type"] for e in events]
+    # Error event present
+    assert "error" in types
+    err = next(e for e in events if e["type"] == "error")
+    assert err["code"] == "RKLLM_GENERATE_FAILED"
+    assert "after re-init retry" in err["message"]
+    assert err["recoverable"] is True
+    # Synthetic insufficient_data verdict present so Try-Again surfaces
+    assert "verdict" in types
+    verdict = next(e for e in events if e["type"] == "verdict")
+    assert verdict["payload"]["root_cause"] == "insufficient_data"
+
+
 def test_run_troubleshoot_terminates_when_model_only_emits_prose():
     """If the model produces no verdict + no tool_calls, the backend
     INJECTS a force-verdict directive + gives the model one more chance.