zero-gpu: run LFM2.5-24B-A2B on the xlarge slice from a mounted volume

BUILD.json

@@ -1,7 +1,7 @@
 {
-  "built_at": "2026-10-27T17:07:51",
-  "commit": "173cb13",
-  "files": 49,
+  "built_at": "2026-10-29T13:31:34",
+  "commit": "c778551",
+  "files": 53,
   "with_store": false,
   "with_card": true
 }

README.md

@@ -1,146 +1,153 @@
----
-title: traceforge
-emoji: 🧭
-colorFrom: indigo
-colorTo: green
-sdk: gradio
-sdk_version: 6.30.0
-app_file: app.py
-pinned: false
-license: other
-short_description: Turn real agent traces into ideal-world references
----
-
-# traceforge
-
-Turn a real agent trace into its **ideal-world reference**: the same work,
-with the dead ends removed, gated for structure and grounding.
-
-This Space is the portable face of the traceforge pipeline. The pipeline
-itself is unchanged — triage labels every message, a windowed rewriter
-produces the ideal path, and a judge admits only traces that pass the six
-pillars. The UI hides that machinery behind three actions.
-
-## Submit a trace
-
-Upload a JSON/JSONL trace (traceforge native, OpenAI chat, or a bare message
-list) or paste it. The app computes a **content hash** of the seed and
-queues it.
-
-**One seed, one output.** The hash covers the conversation content — message
-text, tool calls and the set of tools the agent had — and excludes session
-ids, timestamps, cwd and tool-call ids. Submitting the same trace twice
-returns the existing output instead of creating a second one. That is what
-makes the output dataset a set, not a log.
-
-## Sponsor a dataset
-
-Upload a JSONL of traces. Every row is hashed; new seeds are queued and
-attributed to the sponsor name you give, known seeds are skipped. Processed
-rows join the public output dataset. The dashboard shows the sponsor
-leaderboard.
-
-## Dashboard
-
-Public statistics over this Space's corpus and, when bundled, the reference
-corpus: seeds, outputs, queue, failure rate, task mix, languages, runtime
-distribution, and **time sensitivity**.
-
-## No API key? ZeroGPU runs the model for you
-
-The Space has two modes:
-
-- **Remote endpoint** — set `TRACEFORGE_BASE_URL` and `TRACEFORGE_LLM_KEY`
-  in the Space settings. Fast, any trace size.
-- **Local ZeroGPU** — with no endpoint configured, the Space runs
-  `Qwen/Qwen2.5-3B-Instruct` on Hugging Face ZeroGPU. The GPU is attached
-  only while a call runs, and the time is charged to **your** HF account's
-  daily ZeroGPU quota, not to the Space owner: 2 min/day anonymous, 5 min
-  free account, 40 min PRO. Idle time costs nothing.
-
-Local mode is for small traces (up to 24 KB) — a 3B model on a 120 s GPU
-slice cannot rewrite a 300 KB trace inside a free daily quota. Larger
-traces need a remote endpoint.
-
-Local mode gates the rewrite structurally, for grounding, and for identity,
-then rejects a rewrite that is identical to the seed. The LLM judge is off
-there: a 3B judge invents violations and often omits `answer_quality`, so
-it adds noise rather than signal. A remote endpoint keeps the full judge.
-
-A seed that already reads as ideal comes back as **no change** rather than
-an output or a failure — the pipeline had nothing to edit.
-
-## Time sensitivity
-
-A trace whose correct answer is a fact that changes over time is a bad
-training target when the agent had no way to look that fact up. Train on it
-and the model learns to *assert* the fact from its weights — "the current
-president is X" — which is wrong the moment X changes.
-
-The same question is a good target when the agent had a retrieval tool. The
-ideal path calls the tool and answers from its result, so what the model
-imitates is the procedure (search, read, answer), not the fact. The
-procedure does not decay.
-
-| class | meaning |
-|---|---|
-| `time_sensitive` | temporal fact, no retrieval tool — the answer decays |
-| `time_anchored` | temporal fact, but a retrieval tool can fetch it |
-| `not_time_sensitive` | no time-dependent fact in the task |
-
-`time_anchored` carries a sub-flag: whether the tool was actually **called**.
-A temporal task with a search tool available but never used is anchored in
-principle — the ideal rewrite should make the agent call it — but the raw
-trace answered from weights, so it needs a rewrite rather than a pass.
-
-The detector is deliberately conservative: a false `time_sensitive` throws
-away a good trace, so a pattern must name the **fact** (an officeholder, a
-price, a released version, the weather), not just a temporal word. "The
-current branch" and "the latest fix round" are local artifacts of the
-session, not decaying facts.
-
-## Configuration
-
-Set these as Space secrets / variables:
-
-| variable | meaning |
-|---|---|
-| `TRACEFORGE_BASE_URL` | OpenAI-compatible endpoint (`…/v1`) |
-| `TRACEFORGE_LLM_KEY` | bearer token |
-| `TRACEFORGE_MODEL` | writer/judge model id |
-| `TRACEFORGE_TRIAGE_MODEL` | cheap labeler (default: `TRACEFORGE_MODEL`) |
-| `TRACEFORGE_JUDGE_MODEL` | judge override (default: `TRACEFORGE_MODEL`) |
-| `TRACEFORGE_DATA_DIR` | store root (default `./data/space`) |
-| `TRACEFORGE_SPACE_WORKERS` | parallel pipeline workers (default 1) |
-
-Without an endpoint the app still starts and the dashboard still works; the
-Submit tab reports that the pipeline is not configured instead of hanging.
-
-## Storage
-
-The store is content-addressed on disk:
-
-```
-data/space/index.jsonl          append-only journal (last row per hash wins)
-data/space/seeds/<hash>.json    the seed exactly as submitted
-data/space/outputs/<hash>.json  the improved trace
-```
-
-A Hugging Face Space's disk is ephemeral unless persistent storage is
-attached. For a durable public corpus, mount persistent storage at
-`/data` and set `TRACEFORGE_DATA_DIR=/data/space`, or sync the store to a
-dataset repo.
-
-## Local use
-
-```bash
-pip install -e ".[webui]"
-python app.py                       # http://127.0.0.1:7860
-traceforge space serve --port 7860
-traceforge space hash trace.json    # print the seed hash
-traceforge space stats              # store census
-```
-
-## License
-
-Private research corpus. All rights reserved.
+---
+title: traceforge
+emoji: 🧭
+colorFrom: indigo
+colorTo: green
+sdk: gradio
+sdk_version: 6.30.0
+app_file: app.py
+pinned: false
+license: other
+short_description: Turn real agent traces into ideal-world references
+---
+
+# traceforge
+
+Turn a real agent trace into its **ideal-world reference**: the same work,
+with the dead ends removed, gated for structure and grounding.
+
+This Space is the portable face of the traceforge pipeline. The pipeline
+itself is unchanged — triage labels every message, a windowed rewriter
+produces the ideal path, and a judge admits only traces that pass the six
+pillars. The UI hides that machinery behind three actions.
+
+## Submit a trace
+
+Upload a JSON/JSONL trace (traceforge native, OpenAI chat, or a bare message
+list) or paste it. The app computes a **content hash** of the seed and
+queues it.
+
+**One seed, one output.** The hash covers the conversation content — message
+text, tool calls and the set of tools the agent had — and excludes session
+ids, timestamps, cwd and tool-call ids. Submitting the same trace twice
+returns the existing output instead of creating a second one. That is what
+makes the output dataset a set, not a log.
+
+## Sponsor a dataset
+
+Upload a JSONL of traces. Every row is hashed; new seeds are queued and
+attributed to the sponsor name you give, known seeds are skipped. Processed
+rows join the public output dataset. The dashboard shows the sponsor
+leaderboard.
+
+## Dashboard
+
+Public statistics over this Space's corpus and, when bundled, the reference
+corpus: seeds, outputs, queue, failure rate, task mix, languages, runtime
+distribution, and **time sensitivity**.
+
+## No API key? ZeroGPU runs the model for you
+
+The Space has two modes:
+
+- **Remote endpoint** — set `TRACEFORGE_BASE_URL` and `TRACEFORGE_LLM_KEY`
+  in the Space settings. Fast, any trace size.
+- **Local ZeroGPU** — with no endpoint configured, the Space runs
+  `LiquidAI/LFM2.5-24B-A2B` (24B total, 2.45B active) on Hugging Face
+  ZeroGPU. The GPU is attached only while a call runs, and the time is
+  charged to **your** HF account's daily ZeroGPU quota, not to the Space
+  owner: 2 min/day anonymous, 5 min free account, 40 min PRO. Idle time
+  costs nothing.
+
+The 24B checkpoint is 48 GB of bf16 weights, so local mode asks for the
+96 GB `xlarge` slice — the default 48 GB `large` slice is the weights and
+nothing else — and xlarge spends **2x quota per second**. The weights are
+also mounted as a read-only volume rather than downloaded, because 48 GB
+does not fit the Space's 50 GB ephemeral disk.
+
+Local mode is for small traces (up to 24 KB) — one 120 s slice cannot
+rewrite a 300 KB trace inside a free daily quota. Larger traces need a
+remote endpoint.
+
+Local mode gates the rewrite structurally, for grounding, and for identity,
+then rejects a rewrite that is identical to the seed. The LLM judge is off
+there: it would double the quota cost per trace. A remote endpoint keeps
+the full judge.
+
+A seed that already reads as ideal comes back as **no change** rather than
+an output or a failure — the pipeline had nothing to edit.
+
+## Time sensitivity
+
+A trace whose correct answer is a fact that changes over time is a bad
+training target when the agent had no way to look that fact up. Train on it
+and the model learns to *assert* the fact from its weights — "the current
+president is X" — which is wrong the moment X changes.
+
+The same question is a good target when the agent had a retrieval tool. The
+ideal path calls the tool and answers from its result, so what the model
+imitates is the procedure (search, read, answer), not the fact. The
+procedure does not decay.
+
+| class | meaning |
+|---|---|
+| `time_sensitive` | temporal fact, no retrieval tool — the answer decays |
+| `time_anchored` | temporal fact, but a retrieval tool can fetch it |
+| `not_time_sensitive` | no time-dependent fact in the task |
+
+`time_anchored` carries a sub-flag: whether the tool was actually **called**.
+A temporal task with a search tool available but never used is anchored in
+principle — the ideal rewrite should make the agent call it — but the raw
+trace answered from weights, so it needs a rewrite rather than a pass.
+
+The detector is deliberately conservative: a false `time_sensitive` throws
+away a good trace, so a pattern must name the **fact** (an officeholder, a
+price, a released version, the weather), not just a temporal word. "The
+current branch" and "the latest fix round" are local artifacts of the
+session, not decaying facts.
+
+## Configuration
+
+Set these as Space secrets / variables:
+
+| variable | meaning |
+|---|---|
+| `TRACEFORGE_BASE_URL` | OpenAI-compatible endpoint (`…/v1`) |
+| `TRACEFORGE_LLM_KEY` | bearer token |
+| `TRACEFORGE_MODEL` | writer/judge model id |
+| `TRACEFORGE_TRIAGE_MODEL` | cheap labeler (default: `TRACEFORGE_MODEL`) |
+| `TRACEFORGE_JUDGE_MODEL` | judge override (default: `TRACEFORGE_MODEL`) |
+| `TRACEFORGE_DATA_DIR` | store root (default `./data/space`) |
+| `TRACEFORGE_SPACE_WORKERS` | parallel pipeline workers (default 1) |
+
+Without an endpoint the app still starts and the dashboard still works; the
+Submit tab reports that the pipeline is not configured instead of hanging.
+
+## Storage
+
+The store is content-addressed on disk:
+
+```
+data/space/index.jsonl          append-only journal (last row per hash wins)
+data/space/seeds/<hash>.json    the seed exactly as submitted
+data/space/outputs/<hash>.json  the improved trace
+```
+
+A Hugging Face Space's disk is ephemeral unless persistent storage is
+attached. For a durable public corpus, mount persistent storage at
+`/data` and set `TRACEFORGE_DATA_DIR=/data/space`, or sync the store to a
+dataset repo.
+
+## Local use
+
+```bash
+pip install -e ".[webui]"
+python app.py                       # http://127.0.0.1:7860
+traceforge space serve --port 7860
+traceforge space hash trace.json    # print the seed hash
+traceforge space stats              # store census
+```
+
+## License
+
+Private research corpus. All rights reserved.

data/dataset/dataset_card.json

@@ -1,12 +1,12 @@
 {
-  "traces": 3924,
+  "traces": 4563,
   "languages": {
-    "en": 3769,
-    "de": 155
+    "en": 4370,
+    "de": 193
   },
   "language_pct": {
-    "en": 96.0,
-    "de": 4.0
+    "en": 95.8,
+    "de": 4.2
   },
   "topic_language_matrix": {
     "languages": [
@@ -15,99 +15,99 @@
     ],
     "rows": {
       "review": {
-        "en": 1202,
-        "de": 63,
-        "total": 1265
+        "en": 1399,
+        "de": 80,
+        "total": 1479
       },
       "implement": {
-        "en": 657,
-        "de": 39,
-        "total": 696
+        "en": 876,
+        "de": 43,
+        "total": 919
       },
       "debug": {
-        "en": 634,
-        "de": 22,
-        "total": 656
+        "en": 720,
+        "de": 26,
+        "total": 746
       },
       "research": {
-        "en": 521,
-        "de": 6,
-        "total": 527
+        "en": 552,
+        "de": 7,
+        "total": 559
       },
       "other": {
-        "en": 283,
-        "de": 4,
-        "total": 287
+        "en": 291,
+        "de": 6,
+        "total": 297
       },
       "test": {
-        "en": 149,
-        "de": 11,
-        "total": 160
+        "en": 174,
+        "de": 15,
+        "total": 189
       },
       "ops": {
-        "en": 105,
-        "de": 2,
-        "total": 107
-      },
-      "data-analysis": {
-        "en": 83,
+        "en": 108,
         "de": 4,
-        "total": 87
+        "total": 112
       },
       "refactor": {
-        "en": 76,
+        "en": 99,
         "de": 3,
-        "total": 79
+        "total": 102
+      },
+      "data-analysis": {
+        "en": 90,
+        "de": 6,
+        "total": 96
       },
       "creative": {
-        "en": 49,
+        "en": 51,
         "de": 0,
-        "total": 49
+        "total": 51
       },
       "office-docs": {
         "en": 10,
-        "de": 1,
-        "total": 11
+        "de": 3,
+        "total": 13
       }
     },
     "totals": {
-      "en": 3769,
-      "de": 155,
-      "total": 3924
+      "en": 4370,
+      "de": 193,
+      "total": 4563
     }
   },
   "tools_and_prompt": {
     "tools": {
-      "rows": 3924,
-      "with_tools": 3923,
-      "pct": 100.0,
+      "rows": 4563,
+      "with_tools": 4557,
+      "pct": 99.9,
       "by_source": {
-        "derived-from-observed-calls": 3509,
-        "claude-request-shape": 414,
-        "none": 1
+        "derived-from-observed-calls": 4098,
+        "claude-request-shape": 459,
+        "none": 6
       }
     },
     "system_prompt": {
-      "rows": 3924,
-      "with_system": 1726,
-      "pct": 44.0,
+      "rows": 4563,
+      "with_system": 1826,
+      "pct": 40.0,
       "by_source": {
-        "none": 2198,
+        "none": 2737,
         "raw-system-row": 663,
-        "claude-request-shape": 414,
-        "codex-base-instructions": 355,
+        "claude-request-shape": 459,
+        "codex-base-instructions": 408,
         "in-trace": 292,
-        "hermes-system-prompts": 2
+        "hermes-system-prompts": 4
       }
     }
   },
   "provenance": {
     "basis": "session-id prefix (the improver overwrites meta.source)",
     "counts": {
-      "real-session": 1723,
-      "subagent": 737,
+      "real-session": 2187,
+      "subagent": 913,
       "nemotron-agentic-ka": 581,
-      "split-segment": 509,
+      "split-segment": 508,
       "nemotron-agentic-tc": 370,
       "nemotron-swe-3c63eaaa": 1,
       "nemotron-swe-6ca796dd": 1,
@@ -115,11 +115,11 @@
       "nemotron-swe-e8ff278b": 1
     },
     "pct": {
-      "real-session": 43.9,
-      "subagent": 18.8,
-      "nemotron-agentic-ka": 14.8,
-      "split-segment": 13.0,
-      "nemotron-agentic-tc": 9.4,
+      "real-session": 47.9,
+      "subagent": 20.0,
+      "nemotron-agentic-ka": 12.7,
+      "split-segment": 11.1,
+      "nemotron-agentic-tc": 8.1,
       "nemotron-swe-3c63eaaa": 0.0,
       "nemotron-swe-6ca796dd": 0.0,
       "nemotron-swe-bc9ee6b7": 0.0,
@@ -127,105 +127,105 @@
     }
   },
   "agent_roles": {
-    "orchestrator": 3187,
-    "subagent": 737
+    "orchestrator": 3650,
+    "subagent": 913
   },
   "tasks": {
-    "review": 1265,
-    "implement": 696,
-    "debug": 656,
-    "research": 527,
-    "other": 287,
-    "test": 160,
-    "ops": 107,
-    "data-analysis": 87,
-    "refactor": 79,
-    "creative": 49,
-    "office-docs": 11
+    "review": 1479,
+    "implement": 919,
+    "debug": 746,
+    "research": 559,
+    "other": 297,
+    "test": 189,
+    "ops": 112,
+    "refactor": 102,
+    "data-analysis": 96,
+    "creative": 51,
+    "office-docs": 13
   },
   "messages": {
-    "total": 130671,
+    "total": 152211,
     "by_role": {
-      "system": 1726,
-      "user": 4345,
-      "assistant": 63391,
-      "tool": 61209
+      "user": 5045,
+      "assistant": 73803,
+      "tool": 71537,
+      "system": 1826
     },
     "per_trace": {
-      "mean": 33.3,
-      "median": 22.0,
-      "p90": 71,
-      "max": 252
+      "mean": 33.4,
+      "median": 23,
+      "p90": 68,
+      "max": 274
     }
   },
   "tool_calls": {
-    "total": 61209,
+    "total": 71537,
     "per_trace": {
-      "mean": 15.6,
-      "median": 10.0,
-      "p90": 34,
-      "max": 125
+      "mean": 15.7,
+      "median": 10,
+      "p90": 33,
+      "max": 143
     },
-    "traces_with_none": 1,
-    "distinct_tools": 553,
+    "traces_with_none": 6,
+    "distinct_tools": 556,
     "top_tools": {
-      "Bash": 22977,
-      "exec": 11517,
-      "terminal": 3660,
-      "read_file": 2835,
-      "Read": 2673,
-      "Edit": 2210,
-      "search_files": 1716,
-      "execute_code": 1581,
-      "tool_call": 1511,
-      "Grep": 939,
-      "skill_view": 861,
-      "patch": 738,
+      "Bash": 26609,
+      "exec": 13574,
+      "terminal": 4730,
+      "read_file": 3641,
+      "Read": 3012,
+      "Edit": 2493,
+      "search_files": 2247,
+      "execute_code": 1970,
+      "tool_call": 1679,
+      "Grep": 1007,
+      "skill_view": 966,
+      "patch": 875,
+      "wait": 489,
       "unlock_discoverable_agent_tool": 457,
-      "call_discoverable_agent_tool": 457,
-      "wait": 411
+      "call_discoverable_agent_tool": 457
     }
   },
   "user_turns": {
     "per_trace": {
       "mean": 1.1,
-      "median": 1.0,
+      "median": 1,
       "p90": 1,
       "max": 18
     },
-    "single_turn_traces": 3617,
-    "multi_turn_traces": 307
+    "single_turn_traces": 4211,
+    "multi_turn_traces": 352
   },
   "tokens": {
     "method": "chars/4 (prose proxy); scale by ~1.15 for a central estimate",
     "budget": 131072,
-    "chars_total": 318237136,
-    "est_total": 79559284,
+    "chars_total": 374416612,
+    "est_total": 93604153,
     "per_trace": {
-      "mean": 20274.7,
-      "median": 16510.5,
-      "p90": 46090,
+      "mean": 20513.4,
+      "median": 16365,
+      "p90": 46390,
       "max": 121769
     },
     "fits_budget": {
       "4096": {
-        "traces": 1026,
-        "pct": 26.1
+        "traces": 1139,
+        "pct": 25.0
       },
       "8192": {
-        "traces": 1264,
-        "pct": 32.2
+        "traces": 1463,
+        "pct": 32.1
       },
       "16384": {
-        "traces": 1950,
-        "pct": 49.7
+        "traces": 2282,
+        "pct": 50.0
       },
       "65536": {
-        "traces": 3875,
-        "pct": 98.8
+        "traces": 4514,
+        "pct": 98.9
       },
       "131072": {
-        "traces": 3924,
+        "traces": 4563,
         "pct": 100.0
       }
     }
@@ -234,69 +234,69 @@
   "supervision": {
     "contract": "loss on assistant spans only; tool/user/system spans are masked context",
     "chars_by_role": {
-      "system": 12435083,
-      "user": 5887077,
-      "assistant": 12168420,
-      "tool": 287746556
+      "user": 7445197,
+      "assistant": 13944527,
+      "tool": 339128629,
+      "system": 13898259
     },
-    "assistant_share_pct": 3.8,
-    "tool_share_pct": 90.4
+    "assistant_share_pct": 3.7,
+    "tool_share_pct": 90.6
   },
   "difficulty": {
     "basis": "tool calls in the ideal path (proxy, not a score)",
     "bands": {
       "D1": {
         "label": "one-shot / single edit",
-        "traces": 111,
-        "pct": 2.8
+        "traces": 136,
+        "pct": 3.0
       },
       "D2": {
         "label": "short loop",
-        "traces": 680,
-        "pct": 17.3
+        "traces": 786,
+        "pct": 17.2
       },
       "D3": {
         "label": "multi-step",
-        "traces": 1253,
-        "pct": 31.9
+        "traces": 1384,
+        "pct": 30.3
       },
       "D4": {
         "label": "long session",
-        "traces": 857,
-        "pct": 21.8
+        "traces": 1057,
+        "pct": 23.2
       },
       "D5": {
         "label": "very long session",
-        "traces": 1023,
-        "pct": 26.1
+        "traces": 1200,
+        "pct": 26.3
       }
     },
     "tool_calls": {
-      "mean": 15.6,
-      "median": 10.0,
-      "p90": 34,
-      "max": 125
+      "mean": 15.7,
+      "median": 10,
+      "p90": 33,
+      "max": 143
     },
     "messages": {
-      "mean": 33.3,
-      "median": 22.0,
-      "p90": 71,
-      "max": 252
+      "mean": 33.4,
+      "median": 23,
+      "p90": 68,
+      "max": 274
     },
     "est_tokens": {
-      "mean": 20274.7,
-      "median": 16510.5,
-      "p90": 46090,
+      "mean": 20513.4,
+      "median": 16365,
+      "p90": 46390,
       "max": 121769
     }
   },
   "safety_filter": {
     "applied": true,
-    "traces_in": 4155,
-    "traces_kept": 3924,
-    "traces_excluded": 231,
-    "excluded_secret": 207,
-    "excluded_personal": 24,
+    "traces_in": 4831,
+    "traces_kept": 4563,
+    "traces_excluded": 268,
+    "excluded_secret": 239,
+    "excluded_personal": 29,
     "rule": "drop any trace carrying credential material (passwords, tokens, private keys, connection strings with real credentials) or third-party personal data (private legal correspondence, home addresses, phone numbers, IBANs). Code, internal hostnames, business contact addresses and the owner's own identity stay.",
     "report": "safety_report.json"
   },
@@ -304,7 +304,7 @@
     "classes": {
       "time_sensitive": 13,
       "time_anchored": 12,
-      "not_time_sensitive": 3899
+      "not_time_sensitive": 4538
     },
     "labels": {
       "time_sensitive": "answer decays: temporal fact, no retrieval tool",

requirements.txt

@@ -1,6 +1,6 @@
-gradio>=6.0
-pyyaml>=6
-huggingface_hub>=0.24
-spaces>=0.2
-transformers>=4.44
-accelerate>=0.33
+gradio>=6.0
+pyyaml>=6
+huggingface_hub>=0.24
+spaces>=0.2
+transformers>=5.0
+accelerate>=0.33

traceforge/balance.py

@@ -0,0 +1,833 @@
+"""Corpus balance: the target mix, the measured mix, and the gap plan.
+
+The seed pool is not a sample of the deployment distribution. It is whatever
+the owner's harnesses happened to record, and that shape is biased in three
+ways that matter for training:
+
+  language    ~94% English. German is 5.9% of Common Crawl against English's
+              45.9%, and the base models saw even less (LLaMA-2: 0.17% de),
+              so a corpus that mirrors the web under-serves German twice over.
+  task        `review` is a third of the corpus because review subagents are
+              cheap to spawn, not because a third of real work is read-only.
+  difficulty  long sessions dominate; the short end is thin.
+
+This module makes the target explicit and measurable:
+
+    policy   the target shares per axis (config/balance.yaml, editable)
+    census   the measured counts per axis and per (language, task) cell
+    report   actual vs target, per axis and joint, plus a balance score
+    plan     the cells to GENERATE, largest deficit first
+    select   a deterministic downsample of over-target cells, so the shipped
+             mix can be balanced today without waiting for generation
+
+The joint target is the product of the marginals: target(de, debug) =
+P(de) * P(debug). That is the independence assumption, and it is deliberate —
+it forces German coverage into every task bucket instead of letting a 30%
+German share be 30% review.
+
+Nothing here calls a model or touches the network. It reads exported rows
+(``{"messages", "meta"}``) or ``Trace`` objects and returns plain dicts, so
+the CLI, the dashboard and the tests all share one implementation.
+"""
+from __future__ import annotations
+
+import collections
+import hashlib
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Optional
+
+from traceforge.classify import TASKS, detect_language
+from traceforge.difficulty import BANDS, band, count_calls
+
+# --------------------------------------------------------------- the policy
+
+# Measured 2026-10-28 on the 4,463-trace export, and the evidence behind each
+# number is in docs/BALANCE.md. Short version:
+#   language   Kew et al. 2024 (Findings EMNLP) find 12.5-18.75% non-English
+#              sufficient to elicit cross-lingual generalisation and IO
+#              language agreement; 30% is comfortably above that band and
+#              ~5x the web-natural German share, which compensates for the
+#              pretraining deficit. The owner's stated acceptable split.
+#   task       coding stays the majority (56%) but `review` drops from 33% to
+#              10%: it is read-only, so it teaches inspection and not action,
+#              and its current share is a sampling artifact of review
+#              subagents. Non-coding buckets get real coverage because the
+#              proof harness showed coverage gaps surface as regressions.
+#   difficulty a fat middle with a long-horizon tail: D1 is near-useless
+#              (OpenThoughts-Agent: filtering <5 turns is the single largest
+#              data win), D4+D5 stay at 48% because long-horizon is where
+#              agents actually fail.
+DEFAULT_POLICY: dict[str, Any] = {
+    "language": {"en": 0.70, "de": 0.30},
+    "task": {
+        "debug": 0.16,
+        "implement": 0.16,
+        "test": 0.08,
+        "refactor": 0.06,
+        "review": 0.10,
+        "research": 0.12,
+        "data-analysis": 0.09,
+        "ops": 0.08,
+        "office-docs": 0.06,
+        "creative": 0.04,
+        "other": 0.05,
+    },
+    "difficulty": {"D1": 0.02, "D2": 0.18, "D3": 0.32, "D4": 0.28, "D5": 0.20},
+    # Harness: the three harnesses the owner actually deploys into, balanced
+    # against each other. Measured 2026-10-29: claude 32.5%, codex 24.9%,
+    # hermes 17.4%, nemotron 19.5%. A corpus that is a third claude is not
+    # "mixed" — it teaches one harness's tool vocabulary and error strings.
+    # nemotron keeps a 1% residual: it is real agentic data, but it is not a
+    # deployment target, so it must not be a fifth of the corpus.
+    "harness": {
+        "claude-code": 0.32,
+        "codex": 0.32,
+        "hermes": 0.32,
+        "nemotron": 0.02,
+        "other": 0.02,
+    },
+    # A share within this many points of target counts as on-target. 0.02 is
+    # ~90 traces at the current corpus size: tight enough to be a goal, loose
+    # enough that a single generation wave does not flip the verdict.
+    "tolerance": 0.02,
+}
+
+POLICY_PATH = os.path.join("config", "balance.yaml")
+
+# Languages the corpus targets. Kept next to the policy so adding one is a
+# one-line change here plus a share in config/balance.yaml, not a hunt through
+# the validator.
+LANGUAGES: tuple[str, ...] = ("en", "de")
+
+# Harness families. The raw `source` values are per-READER ("claude-sidechain",
+# "nemotron-agentic-ka", "tui"), which is too fine to balance against: what
+# matters for robustness is the harness the model will actually be dropped
+# into. Measured 2026-10-29 on 4,890 promoted traces: codex 24.9%,
+# claude-sidechain 19.1%, claude-code 13.4%, nemotron-ka 11.9%, tui 9.1%,
+# desktop 8.3%, nemotron-tc 7.6%, no-raw 5.5% — i.e. one harness family
+# (claude) at 32.5% and hermes at 17.4%, so a corpus that looks "mixed" is
+# really claude-heavy.
+HARNESSES: tuple[str, ...] = ("claude-code", "codex", "hermes", "nemotron", "other")
+
+_HARNESS_OF_SOURCE: dict[str, str] = {
+    "claude-code": "claude-code",
+    "claude-sidechain": "claude-code",
+    "codex": "codex",
+    "tui": "hermes",
+    "desktop": "hermes",
+    "hermes": "hermes",
+    "nemotron-agentic-ka": "nemotron",
+    "nemotron-agentic-tc": "nemotron",
+    "nemotron-swe": "nemotron",
+    "nemotron": "nemotron",
+}
+
+
+def harness_of(source: Optional[str]) -> str:
+    """Map a raw `source` value onto a harness family.
+
+    Unknown values land in "other" rather than being dropped: a new reader
+    must show up in the report as an imbalance, not vanish from it.
+    """
+    return _HARNESS_OF_SOURCE.get((source or "").strip().lower(), "other")
+
+
+@dataclass
+class BalancePolicy:
+    """Target shares per axis. Shares must sum to 1.0 per axis."""
+
+    language: dict[str, float] = field(default_factory=dict)
+    task: dict[str, float] = field(default_factory=dict)
+    difficulty: dict[str, float] = field(default_factory=dict)
+    harness: dict[str, float] = field(default_factory=dict)
+    tolerance: float = 0.02
+    source: str = "builtin"
+
+    @classmethod
+    def load(cls, path: Optional[str] = None) -> "BalancePolicy":
+        """Load a YAML policy, falling back to the built-in defaults.
+
+        A missing file is not an error: the defaults ARE the policy until the
+        owner edits one. A malformed file IS an error — silently training
+        against a typo'd target is worse than refusing to start.
+        """
+        if not path:
+            return cls.from_dict(DEFAULT_POLICY, source="builtin")
+        if not os.path.exists(path):
+            return cls.from_dict(DEFAULT_POLICY, source="builtin")
+        import yaml  # optional dependency, same as Config.load
+
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+        return cls.from_dict(data, source=path)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], source: str = "dict") -> "BalancePolicy":
+        unknown_axes = set(data) - {"language", "task", "difficulty", "harness",
+                                    "tolerance"}
+        if unknown_axes:
+            # A typo'd axis name ("tasks:") would otherwise be ignored and the
+            # built-in default silently used — training against a target the
+            # owner never wrote is worse than refusing to start.
+            raise ValueError(
+                f"balance policy: unknown axis {sorted(unknown_axes)}; "
+                f"expected language / task / difficulty / harness / tolerance"
+            )
+        merged = {
+            "language": dict(DEFAULT_POLICY["language"]),
+            "task": dict(DEFAULT_POLICY["task"]),
+            "difficulty": dict(DEFAULT_POLICY["difficulty"]),
+            "harness": dict(DEFAULT_POLICY["harness"]),
+            "tolerance": DEFAULT_POLICY["tolerance"],
+        }
+        for key in ("language", "task", "difficulty", "harness"):
+            if key in data and data[key]:
+                merged[key] = {str(k): float(v) for k, v in data[key].items()}
+        if "tolerance" in data:
+            merged["tolerance"] = float(data["tolerance"])
+        pol = cls(
+            language=merged["language"],
+            task=merged["task"],
+            difficulty=merged["difficulty"],
+            harness=merged["harness"],
+            tolerance=merged["tolerance"],
+            source=source,
+        )
+        pol.validate()
+        return pol
+
+    def validate(self) -> None:
+        for axis, shares in (
+            ("language", self.language),
+            ("task", self.task),
+            ("difficulty", self.difficulty),
+            ("harness", self.harness),
+        ):
+            if not shares:
+                raise ValueError(f"balance policy: empty {axis} axis")
+            negative = {k: v for k, v in shares.items() if v < 0}
+            if negative:
+                # {"en": 1.2, "de": -0.2} sums to 1.0 and would otherwise pass,
+                # producing a negative target that silently disables the cell.
+                raise ValueError(
+                    f"balance policy: negative {axis} share(s) {negative}"
+                )
+            total = sum(shares.values())
+            if abs(total - 1.0) > 0.01:
+                raise ValueError(
+                    f"balance policy: {axis} shares sum to {total:.3f}, "
+                    f"expected 1.0"
+                )
+            unknown = set(shares) - set(_known_keys(axis))
+            if unknown:
+                raise ValueError(
+                    f"balance policy: unknown {axis} key(s) {sorted(unknown)}; "
+                    f"known: {sorted(_known_keys(axis))}"
+                )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "language": dict(self.language),
+            "task": dict(self.task),
+            "difficulty": dict(self.difficulty),
+            "harness": dict(self.harness),
+            "tolerance": self.tolerance,
+            "source": self.source,
+        }
+
+    def joint_target(self, language: str, task: str) -> float:
+        """Target share of one (language, task) cell: the product of marginals."""
+        return self.language.get(language, 0.0) * self.task.get(task, 0.0)
+
+
+def _known_keys(axis: str) -> tuple[str, ...]:
+    if axis == "language":
+        return LANGUAGES
+    if axis == "task":
+        return tuple(TASKS)
+    if axis == "harness":
+        return HARNESSES
+    return tuple(code for code, _, _, _ in BANDS)
+
+
+# ------------------------------------------------------------------ census
+
+
+def _record_fields(rec: Any, labels: Optional[dict[str, str]] = None):
+    """(session_id, language, task, difficulty, harness) for one record.
+
+    Accepts an exported row (``{"messages", "meta"}``) or a ``Trace``. The
+    language comes from ``meta.language`` when the exporter wrote it and from
+    the first user row otherwise — the same detector the P5 gate uses, so the
+    balance report and the gate cannot disagree about what a German trace is.
+
+    The harness comes from ``meta.harness`` (written by the exporter from
+    ``Trace.harness``), falling back to ``meta.source`` for rows exported
+    before that field existed. A promoted trace's ``source`` is
+    "traceforge-splice", which is why the fallback alone is not enough.
+    """
+    if hasattr(rec, "to_dict"):
+        rec = rec.to_dict()
+    meta = rec.get("meta") or {}
+    msgs = rec.get("messages") or []
+    # Two shapes reach this function: an exported row ({"messages", "meta"})
+    # and Trace.to_dict() (flat: session_id / task at the top level). Reading
+    # only "meta" silently put every Trace in the "unknown" cell, which made
+    # the export cap drop the whole corpus — so accept both.
+    sid = (meta.get("traceforge_session_id") or meta.get("session_id")
+           or rec.get("session_id") or "")
+    lang = meta.get("language") or rec.get("language")
+    if not lang:
+        first_user = next(
+            (m.get("content") or "" for m in msgs if m.get("role") == "user"), ""
+        )
+        lang = detect_language(first_user)
+    task = labels.get(sid) if labels else None
+    if not task:
+        task = meta.get("task") or rec.get("task")
+    task = task or "unknown"
+    diff = band(count_calls(rec))
+    harness = harness_of(
+        meta.get("harness") or rec.get("harness")
+        or meta.get("source") or rec.get("source"))
+    return sid, lang, task, diff, harness
+
+
+def load_labels(path: str) -> dict[str, str]:
+    """sid -> task from ``data/tasks.jsonl`` (last row per sid wins)."""
+    labels: dict[str, str] = {}
+    if not os.path.exists(path):
+        return labels
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            sid = row.get("session_id")
+            if sid and row.get("task"):
+                labels[sid] = row["task"]
+    return labels
+
+
+def census(
+    records: Iterable[Any], labels: Optional[dict[str, str]] = None
+) -> dict[str, Any]:
+    """Count records per axis and per (language, task) / (language, difficulty)."""
+    lang: collections.Counter = collections.Counter()
+    task: collections.Counter = collections.Counter()
+    diff: collections.Counter = collections.Counter()
+    harn: collections.Counter = collections.Counter()
+    lt: collections.Counter = collections.Counter()
+    ld: collections.Counter = collections.Counter()
+    td: collections.Counter = collections.Counter()
+    n = 0
+    for rec in records:
+        _, lg, tk, d, hs = _record_fields(rec, labels)
+        n += 1
+        lang[lg] += 1
+        task[tk] += 1
+        diff[d] += 1
+        harn[hs] += 1
+        lt[f"{lg}|{tk}"] += 1
+        ld[f"{lg}|{d}"] += 1
+        td[f"{tk}|{d}"] += 1
+    return {
+        "n": n,
+        "language": dict(lang),
+        "task": dict(task),
+        "difficulty": dict(diff),
+        "harness": dict(harn),
+        "language_task": dict(lt),
+        "language_difficulty": dict(ld),
+        "task_difficulty": dict(td),
+        "unlabeled": int(task.get("unknown", 0)),
+    }
+
+
+# ------------------------------------------------------------------ report
+
+
+def _axis_rows(
+    counts: dict[str, int], targets: dict[str, float], n: int, tolerance: float
+) -> list[dict[str, Any]]:
+    """One row per key: actual, target, delta, verdict."""
+    keys = list(targets) + [k for k in counts if k not in targets]
+    rows = []
+    for key in keys:
+        actual_n = int(counts.get(key, 0))
+        share = actual_n / n if n else 0.0
+        target = float(targets.get(key, 0.0))
+        target_n = target * n
+        delta = actual_n - target_n
+        if target == 0.0:
+            status = "extra" if actual_n else "ok"
+        elif abs(share - target) <= tolerance:
+            status = "ok"
+        elif share < target:
+            status = "under"
+        else:
+            status = "over"
+        rows.append({
+            "key": key,
+            "n": actual_n,
+            "share": round(share, 4),
+            "target": round(target, 4),
+            "target_n": round(target_n, 1),
+            "delta_n": round(delta, 1),
+            "status": status,
+        })
+    rows.sort(key=lambda r: (-r["target"], r["key"]))
+    return rows
+
+
+def _tvd(rows: list[dict[str, Any]]) -> float:
+    """Total variation distance between actual and target shares."""
+    return round(0.5 * sum(abs(r["share"] - r["target"]) for r in rows), 4)
+
+
+def report(census_data: dict[str, Any], policy: BalancePolicy) -> dict[str, Any]:
+    """Actual vs target per axis and joint, plus a single balance score.
+
+    ``balance_score`` = 1 - TVD over the (language, task) grid, so 1.0 is a
+    perfectly balanced corpus and 0.0 is maximally skewed. Unlabeled traces
+    are excluded from the score (they are a labeling defect, not a mix
+    property) and reported separately.
+    """
+    n = int(census_data.get("n") or 0)
+    tol = policy.tolerance
+    axes = {
+        "language": _axis_rows(census_data.get("language", {}),
+                               policy.language, n, tol),
+        "task": _axis_rows(census_data.get("task", {}),
+                           policy.task, n, tol),
+        "difficulty": _axis_rows(census_data.get("difficulty", {}),
+                                 policy.difficulty, n, tol),
+        "harness": _axis_rows(census_data.get("harness", {}),
+                              policy.harness, n, tol),
+    }
+    # joint grid: every (language, task) cell the policy names, plus any
+    # observed cell the policy does not (reported as "extra", target 0)
+    lt_counts = census_data.get("language_task", {})
+    joint = []
+    for lg, p_lg in policy.language.items():
+        for tk, p_tk in policy.task.items():
+            key = f"{lg}|{tk}"
+            actual_n = int(lt_counts.get(key, 0))
+            target = p_lg * p_tk
+            share = actual_n / n if n else 0.0
+            delta = actual_n - target * n
+            if abs(share - target) <= tol:
+                status = "ok"
+            elif share < target:
+                status = "under"
+            else:
+                status = "over"
+            joint.append({
+                "language": lg, "task": tk, "key": key,
+                "n": actual_n, "share": round(share, 4),
+                "target": round(target, 4),
+                "target_n": round(target * n, 1),
+                "delta_n": round(delta, 1), "status": status,
+            })
+    for key, actual_n in lt_counts.items():
+        lg, _, tk = key.partition("|")
+        if lg in policy.language and tk in policy.task:
+            continue
+        joint.append({
+            "language": lg, "task": tk, "key": key, "n": int(actual_n),
+            "share": round(actual_n / n, 4) if n else 0.0,
+            "target": 0.0, "target_n": 0.0, "delta_n": float(actual_n),
+            "status": "extra",
+        })
+    joint.sort(key=lambda r: (-r["target"], r["language"], r["task"]))
+    scored = [r for r in joint if r["target"] > 0]
+    return {
+        "n": n,
+        "policy_source": policy.source,
+        "tolerance": tol,
+        "balance_score": round(1.0 - _tvd(scored), 4),
+        "axes": {axis: {"tvd": _tvd(rows), "rows": rows}
+                 for axis, rows in axes.items()},
+        "joint": {"tvd": _tvd(scored), "rows": joint},
+        "unlabeled": int(census_data.get("unlabeled") or 0),
+    }
+
+
+# -------------------------------------------------------------------- plan
+
+
+def plan(
+    report_data: dict[str, Any],
+    policy: BalancePolicy,
+    limit: Optional[int] = None,
+    min_need: float = 1.0,
+) -> list[dict[str, Any]]:
+    """The generation work order: under-target cells, largest deficit first.
+
+    Each row is one (language, task) cell with the number of traces needed to
+    reach its target at the CURRENT corpus size, plus the difficulty mix to
+    draw from. Cells already at or over target are omitted — generating more
+    of an over-represented cell makes the corpus worse, not better.
+    """
+    n = int(report_data.get("n") or 0)
+    diff_rows = report_data["axes"]["difficulty"]["rows"]
+    # the difficulty deficit, normalised: how much of the missing mass each
+    # band should absorb. A band already over target contributes 0.
+    deficit = {r["key"]: max(0.0, r["target_n"] - r["n"]) for r in diff_rows}
+    total_deficit = sum(deficit.values())
+    diff_mix = ({k: round(v / total_deficit, 4) for k, v in deficit.items()}
+                if total_deficit > 0 else dict(policy.difficulty))
+    rows = []
+    for cell in report_data["joint"]["rows"]:
+        if cell["status"] != "under":
+            continue
+        need = cell["target_n"] - cell["n"]
+        if need < min_need:
+            continue
+        rows.append({
+            "language": cell["language"],
+            "task": cell["task"],
+            "need": int(round(need)),
+            "have": cell["n"],
+            "target_n": cell["target_n"],
+            "share": cell["share"],
+            "target": cell["target"],
+            "difficulty_mix": diff_mix,
+        })
+    rows.sort(key=lambda r: (-r["need"], r["language"], r["task"]))
+    if limit:
+        rows = rows[:limit]
+    return rows
+
+
+def plan_total(rows: list[dict[str, Any]]) -> int:
+    return int(sum(r["need"] for r in rows))
+
+
+def converge(
+    census_data: dict[str, Any],
+    policy: BalancePolicy,
+) -> dict[str, Any]:
+    """The smallest corpus that is balanced by GENERATION ALONE.
+
+    Adding traces can never fix an over-target cell — it only dilutes it. So
+    the generation-only fixed point is the size at which the most
+    over-represented cell finally falls to its target share:
+
+        N* = max over cells of  have(cell) / target(cell)
+
+    That number is usually brutal (a cell at 33% against a 10% target needs
+    the corpus to grow 3.3x), which is the argument for capping the
+    over-target cells instead — see ``fill_to``.
+    """
+    n = int(census_data.get("n") or 0)
+    lt = census_data.get("language_task") or {}
+    worst = 0.0
+    binding = None
+    for key, have in lt.items():
+        lg, _, tk = key.partition("|")
+        target = policy.joint_target(lg, tk)
+        if target <= 0 or not have:
+            continue
+        need_n = have / target
+        if need_n > worst:
+            worst, binding = need_n, key
+    grow_to = int(-(-worst // 1))  # ceil
+    return {
+        "grow_to": grow_to,
+        "added": max(0, grow_to - n),
+        "binding_cell": binding,
+        "binding_share": round(lt.get(binding, 0) / n, 4) if binding and n else 0.0,
+        "binding_target": round(policy.joint_target(*binding.split("|")), 4)
+        if binding else 0.0,
+    }
+
+
+def fill_to(
+    census_data: dict[str, Any],
+    policy: BalancePolicy,
+    target_n: Optional[int] = None,
+) -> dict[str, Any]:
+    """At a chosen final size: what to DROP and what to GENERATE.
+
+    This is the planner the pipeline actually uses, because it is the only
+    strategy that reaches the target at a sane corpus size: cap the
+    over-target cells (cheap, immediate, deterministic) and generate the
+    under-target ones (expensive, targeted). ``target_n`` defaults to the
+    current size, i.e. "balance what we have".
+    """
+    n = int(census_data.get("n") or 0)
+    final_n = int(target_n or n)
+    lt = census_data.get("language_task") or {}
+    drops: dict[str, int] = {}
+    adds: dict[str, int] = {}
+    for lg, p_lg in policy.language.items():
+        for tk, p_tk in policy.task.items():
+            key = f"{lg}|{tk}"
+            have = int(lt.get(key, 0))
+            target = p_lg * p_tk * final_n
+            if have > target + 0.5:
+                drops[key] = int(round(have - target))
+            elif have < target - 0.5:
+                adds[key] = int(round(target - have))
+    return {
+        "final_n": final_n,
+        "drop": dict(sorted(drops.items(), key=lambda kv: -kv[1])),
+        "drop_total": sum(drops.values()),
+        "add": dict(sorted(adds.items(), key=lambda kv: -kv[1])),
+        "add_total": sum(adds.values()),
+        "add_by_language": {
+            lg: sum(v for k, v in adds.items() if k.startswith(lg + "|"))
+            for lg in policy.language
+        },
+    }
+
+
+# ---------------------------------------------------------------- selection
+
+
+def _harness_caps(census_data: dict[str, Any], policy: BalancePolicy) -> dict[str, int]:
+    """How many records to drop from each over-target harness family.
+
+    Same arithmetic as ``fill_to`` but on the harness axis alone: an
+    over-target family is cut to its target share of the CURRENT corpus size,
+    an under-target family keeps everything. Dropping cannot fix an
+    under-target family — that is generation's job, and the report shows the
+    residual gap so the pull can be pointed at it.
+    """
+    n = int(census_data.get("n") or 0)
+    counts = census_data.get("harness", {}) or {}
+    caps: dict[str, int] = {}
+    for hs, share in policy.harness.items():
+        if hs == "other":
+            # "other" is unknown provenance, not a harness: a trace lands
+            # there when its raw file is gone or a reader is unmapped. Capping
+            # it would silently delete promoted traces over a bookkeeping
+            # defect, so it is reported (loudly, see `report`) and never cut.
+            continue
+        have = int(counts.get(hs, 0))
+        target = share * n
+        if have > target + 0.5:
+            caps[hs] = int(round(have - target))
+    return caps
+
+
+def _stable_hash(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+BALANCE_AXES: tuple[str, ...] = ("language", "task", "harness")
+
+
+def select_balanced(
+    records: list[Any],
+    policy: BalancePolicy,
+    labels: Optional[dict[str, str]] = None,
+    axes: Optional[tuple[str, ...]] = None,
+) -> tuple[list[Any], dict[str, Any]]:
+    """Deterministically downsample over-target cells to hit the target mix.
+
+    Generation is the expensive half of rebalancing; capping the
+    over-represented cells is the cheap half, and it makes the SHIPPED mix
+    correct today. Selection inside a cell is by a stable hash of the session
+    id, so re-running after the corpus grows keeps prior choices stable and
+    never biases toward size, date or source.
+
+    Dropping alone can never fix an UNDER-target cell — it only shrinks the
+    corpus around it — so this uses the same cap as ``fill_to``: over-target
+    cells are cut to their target share of the current size, under-target
+    cells keep everything. The residual gap is what generation has to fill,
+    and the report shows it.
+
+    ``axes`` selects which caps to apply. The default applies all of them;
+    ``("harness",)`` applies only the harness cap, which is what you want when
+    the harness mix is the problem and the language/task mix is not — the
+    language/task caps are far more aggressive (they would drop 41% of the
+    current corpus) and applying them as a side effect of a harness fix would
+    be a surprise.
+
+    Returns (kept, stats). ``stats["dropped"]`` is per-cell, so a caller can
+    see exactly what the cap cost.
+    """
+    axes = tuple(axes) if axes else BALANCE_AXES
+    bad = set(axes) - set(BALANCE_AXES)
+    if bad:
+        raise ValueError(f"unknown balance axis {sorted(bad)}; "
+                         f"expected {list(BALANCE_AXES)}")
+    cells: dict[str, list[Any]] = collections.defaultdict(list)
+    by_harness: dict[str, list[Any]] = collections.defaultdict(list)
+    keys: dict[int, str] = {}
+    for rec in records:
+        sid, lg, tk, _, hs = _record_fields(rec, labels)
+        cells[f"{lg}|{tk}"].append(rec)
+        by_harness[hs].append(rec)
+        keys[id(rec)] = sid or _stable_hash(json.dumps(rec, sort_keys=True)[:512])
+
+    # One cap, computed once. An earlier version re-normalised the target to
+    # the KEPT total each round, which shrinks the corpus geometrically and
+    # converges to zero (round(0.5) == 0) — it deleted the whole dataset.
+    cen = census(records, labels)
+    caps = fill_to(cen, policy)["drop"] if "language" in axes or "task" in axes else {}
+    # Harness is a second, independent cap: a record has to survive BOTH the
+    # (language, task) cap and its harness cap. Applying them as an
+    # intersection rather than one after the other keeps the arithmetic
+    # honest — sequential caps would re-count the already-dropped records and
+    # over-cut the corpus.
+    hcaps = _harness_caps(cen, policy) if "harness" in axes else {}
+
+    dropped_ids: set[int] = set()
+    dropped: dict[str, int] = {}
+    for key, items in cells.items():
+        cap = int(caps.get(key, 0))
+        if cap <= 0:
+            continue
+        ordered = sorted(items, key=lambda r: _stable_hash(keys[id(r)]))
+        for rec in ordered[max(0, len(items) - cap):]:
+            dropped_ids.add(id(rec))
+        dropped[key] = min(cap, len(items))
+    for hs, items in by_harness.items():
+        cap = int(hcaps.get(hs, 0))
+        if cap <= 0:
+            continue
+        ordered = sorted(items, key=lambda r: _stable_hash(keys[id(r)]))
+        for rec in ordered[max(0, len(items) - cap):]:
+            dropped_ids.add(id(rec))
+        dropped[f"harness:{hs}"] = min(cap, len(items))
+
+    kept = [rec for rec in records if id(rec) not in dropped_ids]
+    stats = {
+        "in": len(records),
+        "out": len(kept),
+        "dropped": dict(sorted(dropped.items(), key=lambda kv: -kv[1])),
+        "dropped_total": len(dropped_ids),
+    }
+    return kept, stats
+
+
+# ------------------------------------------------------------------ output
+
+
+def format_report(report_data: dict[str, Any], top: int = 0) -> str:
+    """Human-readable table for the CLI and the dashboard log."""
+    n = report_data["n"]
+    lines = [
+        f"corpus balance · n={n} · score {report_data['balance_score']:.3f} "
+        f"(1.0 = on target) · policy {report_data['policy_source']}",
+    ]
+    if report_data.get("unlabeled"):
+        lines.append(f"  ! {report_data['unlabeled']} trace(s) carry no task "
+                     f"label (excluded from the score)")
+    # A corpus with no harness provenance reports 100% "other" and the axis
+    # silently does nothing. Say so instead of printing a table that looks
+    # like a measurement.
+    hrows = report_data["axes"]["harness"]["rows"]
+    other = next((r for r in hrows if r["key"] == "other"), None)
+    if other and other["share"] > 0.10:
+        lines.append(
+            f"  ! {other['n']} trace(s) ({other['share']*100:.1f}%) have no "
+            f"harness provenance — re-export, or run "
+            f"scripts/backfill_harness.py; the harness axis cannot balance "
+            f"what it cannot see"
+        )
+    for axis in ("language", "task", "difficulty", "harness"):
+        block = report_data["axes"][axis]
+        lines.append(f"\n  {axis}  (TVD {block['tvd']:.3f})")
+        rows = block["rows"]
+        if top:
+            rows = rows[:top]
+        for r in rows:
+            bar = _bar(r["share"], r["target"])
+            lines.append(
+                f"    {r['key']:<14s} {r['n']:>6d}  {r['share']*100:5.1f}%  "
+                f"target {r['target']*100:5.1f}%  {r['delta_n']:+8.0f}  "
+                f"{bar} {r['status']}"
+            )
+    under = [r for r in report_data["joint"]["rows"] if r["status"] == "under"]
+    over = [r for r in report_data["joint"]["rows"] if r["status"] == "over"]
+    lines.append(
+        f"\n  joint (language x task): {len(under)} cell(s) under target, "
+        f"{len(over)} over · TVD {report_data['joint']['tvd']:.3f}"
+    )
+    return "\n".join(lines)
+
+
+def format_plan(
+    rows: list[dict[str, Any]],
+    limit: int = 20,
+    fill: Optional[dict[str, Any]] = None,
+    grow: Optional[dict[str, Any]] = None,
+) -> str:
+    if not rows:
+        return "  plan: nothing to generate — every cell is at or over target"
+    total = plan_total(rows)
+    lines = [f"  plan: {total} trace(s) across {len(rows)} cell(s) in the next "
+             f"wave, largest deficit first"]
+    if fill:
+        by_lang = ", ".join(f"{k} {v}" for k, v in fill["add_by_language"].items())
+        lines.append(
+            f"  cap+fill at n={fill['final_n']}: drop {fill['drop_total']} "
+            f"over-target trace(s), generate {fill['add_total']} ({by_lang})"
+        )
+    if grow:
+        lines.append(
+            f"  generation-only alternative: grow to n≈{grow['grow_to']} "
+            f"(+{grow['added']}), bound by {grow['binding_cell']} at "
+            f"{grow['binding_share']*100:.1f}% against a "
+            f"{grow['binding_target']*100:.1f}% target"
+        )
+    for r in rows[:limit]:
+        lines.append(
+            f"    {r['language']}/{r['task']:<14s} need {r['need']:>5d}  "
+            f"(have {r['have']}, target {r['target_n']:.0f})"
+        )
+    if len(rows) > limit:
+        lines.append(f"    … {len(rows) - limit} more cell(s)")
+    return "\n".join(lines)
+
+
+def _bar(share: float, target: float, width: int = 12) -> str:
+    """A tiny actual-vs-target bar: '#' actual, '.' target, '|' the target mark."""
+    if target <= 0:
+        return " " * width
+    scale = max(share, target)
+    a = int(round(width * share / scale)) if scale else 0
+    t = int(round(width * target / scale)) if scale else 0
+    cells = ["."] * width
+    for i in range(min(a, width)):
+        cells[i] = "#"
+    if 0 <= t < width:
+        cells[t] = "|"
+    return "".join(cells)
+
+
+def write_report(
+    report_data: dict[str, Any],
+    path: str,
+    extra: Optional[dict[str, Any]] = None,
+) -> None:
+    """Persist the report for the dashboard (which must not import traceforge).
+
+    ``extra`` carries the plan / fill / grow blocks, so the dashboard can show
+    the work order without recomputing anything.
+    """
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    payload = dict(report_data)
+    if extra:
+        payload.update(extra)
+    payload["generated_at"] = _now()
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=1, ensure_ascii=False)
+    os.replace(tmp, path)
+
+
+def _now() -> str:
+    import datetime
+
+    return datetime.datetime.now().astimezone().isoformat(timespec="seconds")

traceforge/config.py

@@ -53,6 +53,12 @@ class Config:
     tool_result_chars: int = 1200
     tool_args_chars: int = 600
     include_reasoning: bool = False
+    # Export the reasoning channel into the training JSONL. The rewriter now
+    # WRITES reasoning (the source harnesses only record summaries), so the
+    # channel is worth keeping — but it is a separate decision from whether
+    # the rewriter SEES the source reasoning (include_reasoning, still off:
+    # the source text is a duplicated header or a timeline summary).
+    export_reasoning: bool = True
 
     # ------------------------------------------------------ improver harness
     model: Optional[str] = None  # None = hermes default profile model
@@ -135,6 +141,12 @@ class Config:
     rewrite_max_tokens: int = 8000  # per-window rewrite emit ceiling
     rewrite_timeout_s: int = 300   # per rewrite HTTP call
     judge_model: str = ""           # empty = same as cfg.model
+    # Rotating judge pool: when two or more ids are listed, every trace is
+    # judged by TWO of them (adjacent pairs, chosen deterministically from
+    # the session id) and passes only if both pass. Different families
+    # catch each other's blind spots, and the pool spreads the judge load
+    # across separate deployments instead of queueing behind the writer.
+    judge_models: list = field(default_factory=list)
     judge_max_tokens: int = 3000
     judge_timeout_s: int = 300
     # The final-window judge must report answer_quality; a missing value
@@ -148,6 +160,17 @@ class Config:
     judge_enabled: bool = True
     allow_task_reframe: bool = True  # intent-only FAIL + good answer ->
                                      # rewrite the task message once
+    # Dead-end distillation (2026-10-28, owner directive): a long session
+    # often tries several approaches, watches them fail, and lands on a
+    # different solution. The ideal rewrite routes around the failures (P2),
+    # so the negative knowledge dies with them. This stage compresses the
+    # dead ends into the final answer's reasoning channel: the promoted trace
+    # stays a clean one-shot solution and its reasoning carries "don't try X,
+    # it fails because Y". Grounded against the source's own tool results;
+    # an ungrounded block is dropped, never repaired.
+    distill: bool = True
+    distill_min_dead_ends: int = 2   # distinct failed calls to qualify
+    distill_max_chars: int = 1600    # block budget (reasoning cap is 1200)
 
     # --------------------------------------------------------------- extras
     raw_cache: bool = True  # cache normalized raw traces under data/traces/raw
@@ -196,6 +219,11 @@ class Config:
     # separate candidate traces (MASS arXiv 2610.12176: multi-agent
     # trajectories are the densest training signal; see export._agent_role).
     claude_sidechains: bool = True
+    # Where `traceforge synth run` materialises task workspaces. Empty =
+    # ~/traceforge-synth/ws, deliberately OUTSIDE the repo: the executor runs
+    # an agent with --yolo there, and a workspace under data/ would let a
+    # confused agent walk into the corpus.
+    synth_ws_root: str = ""
 
     def resolve(self, repo_root: str) -> "Config":
         self.state_db = self.state_db or os.path.join(self.hermes_home, "state.db")
@@ -221,6 +249,12 @@ class Config:
         seed_claude = os.path.join(repo_root, "harness-traces", "claude")
         if os.path.isdir(seed_claude):
             _add_unique(self.claude_projects_dirs, seed_claude)
+        # Public session dumps imported by scripts/import_hf_traces.py.
+        # Kept in its own dir so the provenance of a seed is visible from
+        # its path: local sessions under claude/, community ones here.
+        seed_claude_hf = os.path.join(repo_root, "harness-traces", "claude-hf")
+        if os.path.isdir(seed_claude_hf):
+            _add_unique(self.claude_projects_dirs, seed_claude_hf)
         seed_codex = os.path.join(repo_root, "harness-traces", "codex")
         if os.path.isdir(seed_codex):
             _add_unique(self.codex_roots, seed_codex)

traceforge/defects.py

@@ -38,6 +38,11 @@ DEFECTS: dict[str, tuple[str, str, str, str]] = {
     "D-TASK-05": ("harness_brief", "init",
                   "the only opening user message is a harness dispatch brief",
                   "unwrap the brief to the real task, or drop"),
+    "D-TASK-06": ("runtime_notice_task", "init",
+                  "the opening user row is a harness runtime/process notice, "
+                  "not a user request",
+                  "the splice/reframe path picked a mid-session notification "
+                  "as the task; re-attempt from the real task row"),
     "D-TASK-02": ("reframe_failed", "init",
                   "the task could not be reframed into a single intent",
                   "usually several tasks in one session; split it"),
@@ -114,6 +119,16 @@ _RULES: list[tuple[str, re.Pattern[str]]] = [
         r"|infra error|failed for every window|rate limit"
         r"|\bHTTP (?:5\d\d|429)\b", re.I)),
     ("D-TASK-05", re.compile(r"harness dispatch brief|dispatch brief", re.I)),
+    # 2026-10-28: `splice left no user message` (3 records) matched no rule
+    # and landed in D-UNK-01. The raw had a task; the splice dropped the
+    # user row, so it is a structural/format loss, not a taskless trace.
+    ("D-FMT-01", re.compile(r"splice left no user message", re.I)),
+    # 2026-10-29: 9 of 4,747 promoted traces opened with a harness notice
+    # ("[System: The active model ... changed", "[IMPORTANT: Background
+    # process proc_... completed") as the task row; a 4,000-raw sample found
+    # none at the source, so the splice/reframe path fabricated the task.
+    # validate_structural now rejects it; this code keeps the census honest.
+    ("D-TASK-06", re.compile(r"runtime/process notice", re.I)),
     ("D-TASK-04", re.compile(r"no user task message|no user task", re.I)),
     ("D-TASK-02", re.compile(r"reframe", re.I)),
     ("D-VER-02", re.compile(r"fabricated tool result|shares no content"
@@ -122,7 +137,14 @@ _RULES: list[tuple[str, re.Pattern[str]]] = [
     ("D-FMT-03", re.compile(r"final_blob|final answer is a (?:file )?dump", re.I)),
     ("D-FMT-04", re.compile(r"self_talk|self-talk", re.I)),
     ("D-FMT-05", re.compile(r"judge_residue|judge residue", re.I)),
-    ("D-FMT-06", re.compile(r"clip_marker|truncated", re.I)),
+    # 2026-10-28: the bare `truncated` alternative was a CO-OCCURRENCE
+    # matcher, not a cause. Judge violation text says "truncated" constantly
+    # ("final answer is truncated mid-sentence", "tool output is truncated"),
+    # and D-FMT-06 is checked before D-REP-01, so 30 of 5,678 records whose
+    # only error was `max repair rounds exceeded` were coded clip_marker and
+    # the repair-exhausted share was understated. Match the clip marker
+    # itself, which is what the gate emits.
+    ("D-FMT-06", re.compile(r"clip_marker|chars clipped|\[TRUNC", re.I)),
     ("D-SAFE-03", re.compile(r"identity_burn|co-authored-by", re.I)),
     ("D-REP-01", re.compile(r"max repair rounds|repair budget", re.I)),
     ("D-REP-03", re.compile(r"no writer artifact|writer produced nothing", re.I)),

traceforge/distill.py

@@ -0,0 +1,274 @@
+"""Distill a long exploration trace's dead ends into its reasoning channel.
+
+A real session often tries several approaches, watches them fail, and lands
+on a different solution. The ideal-world rewrite routes around the failures
+(P2: an ideal trace shows no failed call), so the negative knowledge — what
+was tried, why it failed, what not to repeat — is deleted with them. That is
+the most expensive knowledge in the trace: a model that only ever sees the
+working path learns nothing about the dead ends it will meet again.
+
+This stage compresses the dead ends into the reasoning channel of the final
+answer. The promoted trace stays a clean one-shot solution; its reasoning
+carries the distilled "don't try X, it fails because Y" evidence, so the
+corpus teaches both what works and what to route around.
+
+Grounding is deterministic: every salient fact in the block must appear in
+the source's own tool results (the same `_coverage` instrument the
+self-grounding gate uses). An ungrounded block is dropped, never repaired —
+the trace is already promotable without it, and a fabricated dead end is
+worse than no dead end.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from traceforge.trace import Message, Trace, _is_error_result
+
+# Two distinct failed calls is the floor: one failure is a typo, two is an
+# abandoned approach. Measured 2026-10-28 on 300 raws: 13.3% of the pool has
+# >=2 failed calls, 31% has >=1.
+MIN_DEAD_ENDS = 2
+MAX_EVIDENCE = 8          # dead ends shown to the model
+MAX_BLOCK_CHARS = 1600    # reasoning cap in _clean_reasoning is 1200
+
+DISTILL_HEADER = """You are compressing the DEAD ENDS of a real agent session into the
+reasoning channel of its ideal-world rewrite.
+
+The session tried several approaches, watched them fail, and landed on a
+different solution. The ideal trace keeps only the working path (an ideal
+execution shows no failed call), so the negative knowledge would be lost.
+Write the reasoning a flawless agent would have had — one that already knows
+which approaches fail here, and why.
+
+FAILED ATTEMPTS (verbatim evidence from the session's own tool results):
+{evidence}
+
+THE SOLUTION THAT WORKED (the ideal trace's final answer):
+{answer}
+
+Write ONE reasoning block, 300-{max_chars} characters, plain prose.
+
+Each dead end is ONE imperative rule, in this shape:
+  "Avoid <approach> — it fails because <the actual error or symptom>; <what
+   to do instead>."
+Lead with the most expensive dead end. Then the working path in one sentence.
+
+Hard rules:
+- Only facts visible in the evidence above. Never invent a file, error,
+  command, number, or tool name.
+- No narrative ("initial attempts", "subsequent attempts", "then I tried",
+  "eventually"). State the rule, not the story.
+- No hedging, no "let me think", no identity, no harness/context talk.
+- Do not restate the task and do not narrate the answer.
+
+Reply with ONLY: {{"reasoning": "<the block>"}}
+"""
+
+DISTILL_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {"reasoning": {"type": "string"}},
+    "required": ["reasoning"],
+}
+
+
+def _arg_digest(name: str, arguments: str) -> str:
+    """Fingerprint of a call, so a repeated failure counts once.
+
+    Delegates to splice's canonical digest (tool name + full canonical
+    arguments). A local copy that hashed only the argument KEYS collapsed
+    every `exec` call into one dead end — one implementation, no drift.
+    """
+    from traceforge.splice import _arg_digest as _canonical
+    return _canonical(name, arguments)
+
+
+def _error_text(body: str) -> str:
+    """The failure itself, not the wrapper around it.
+
+    A wrapped result ("Script completed Wall time 5.6 seconds Output: {...}")
+    hides the error behind the wrapper, so the model gets told "the command
+    failed" without being told why. Unwrap the first JSON object in the body
+    and prefer its error/output/stderr fields; fall back to the raw text.
+    """
+    import json as _json
+
+    text = body or ""
+    dec = _json.JSONDecoder()
+    for i, ch in enumerate(text[:3000]):
+        if ch != "{":
+            continue
+        try:
+            obj, _ = dec.raw_decode(text, i)
+        except ValueError:
+            continue
+        if not isinstance(obj, dict):
+            continue
+        parts: list[str] = []
+        code = obj.get("exit_code")
+        if isinstance(code, int) and code != 0:
+            parts.append(f"exit_code={code}")
+        for k in ("error", "stderr", "output", "message", "detail"):
+            v = obj.get(k)
+            if isinstance(v, str) and v.strip():
+                parts.append(v.strip())
+        if parts:
+            return " ".join(" ".join(parts).split())[:500]
+    return " ".join(text.split())[:500]
+
+
+def exploration_evidence(
+    trace: Trace, *, min_failures: int = MIN_DEAD_ENDS,
+) -> list[dict[str, str]]:
+    """Distinct failed calls in the source, with their error text.
+
+    Deduped by (tool, argument digest): retrying the same broken command
+    five times is ONE dead end, not five. Returns [] when the trace has
+    fewer than `min_failures` distinct failures — a trace with one typo is
+    not an exploration trace.
+    """
+    calls = {}
+    for m in trace.messages:
+        for tc in m.tool_calls:
+            if tc.id:
+                calls[tc.id] = tc
+    seen: set[str] = set()
+    out: list[dict[str, str]] = []
+    for m in trace.messages:
+        if m.role != "tool" or not m.tool_call_id:
+            continue
+        body = m.content or ""
+        if not _is_error_result(body):
+            continue
+        tc = calls.get(m.tool_call_id)
+        name = (tc.name if tc is not None else m.tool_name) or "?"
+        args = (tc.arguments if tc is not None else "") or ""
+        key = _arg_digest(name, args)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append({
+            "tool": name,
+            "args": " ".join(args.split())[:240],
+            "error": _error_text(body),
+        })
+        if len(out) >= MAX_EVIDENCE:
+            break
+    return out if len(out) >= min_failures else []
+
+
+def _render_evidence(evidence: list[dict[str, str]]) -> str:
+    lines = []
+    for n, e in enumerate(evidence, 1):
+        lines.append(
+            f"{n}. {e['tool']}({e['args']})\n   -> {e['error']}")
+    return "\n".join(lines)
+
+
+def validate_block(
+    block: str, source: Trace, *, max_chars: int = MAX_BLOCK_CHARS,
+) -> list[str]:
+    """Gate the distilled block. [] == usable.
+
+    The block is reasoning, so it gets the reasoning channel's rules
+    (identity, harness self-talk, deliberation, clip markers) plus the one
+    rule that matters for a dead end: every fact it names must be visible
+    in the source's own tool results.
+    """
+    from traceforge.audit import SELF_TALK_RE
+    from traceforge.grounding import _coverage, _evidence_corpus
+    from traceforge.identity import IDENTITY_RE
+    from traceforge.splice import CLIP_MARKER_PROBE, _DELIBERATION_RE
+
+    errs: list[str] = []
+    b = " ".join((block or "").split()).strip()
+    if len(b) < 200:
+        errs.append(f"block too short ({len(b)} chars)")
+    if len(b) > max_chars:
+        errs.append(f"block too long ({len(b)} > {max_chars} chars)")
+    if CLIP_MARKER_PROBE.search(b):
+        errs.append("block contained a clip marker")
+    if SELF_TALK_RE.search(b):
+        errs.append("block referenced harness plumbing")
+    if IDENTITY_RE.search(b):
+        errs.append("block contained an identity claim")
+    if _DELIBERATION_RE.search(b):
+        errs.append("block deliberated aloud")
+    probe = Trace(session_id="distill-probe",
+                  messages=[Message(role="assistant", content=b)])
+    cov, missing = _coverage(probe, _evidence_corpus(source))
+    if cov < 0.9:
+        errs.append(
+            "block not grounded in the source's tool results: "
+            + ", ".join(missing[:5]))
+    return errs
+
+
+def attach_to_final(
+    candidate: Trace, block: str, *, max_chars: int = MAX_BLOCK_CHARS,
+) -> bool:
+    """Put the block on the final assistant turn's reasoning channel.
+
+    Appends to reasoning the writer already supplied (the close's decision
+    logic is still useful); when the merge would blow the budget, the
+    distilled block wins — it is the part that carries the dead ends.
+    """
+    for m in reversed(candidate.messages):
+        if m.role != "assistant" or not (m.content or "").strip():
+            continue
+        existing = (m.reasoning or "").strip()
+        merged = f"{existing} {block}".strip() if existing else block
+        if len(merged) > max_chars + 600:
+            merged = block
+        m.reasoning = merged
+        return True
+    return False
+
+
+def distill_into_reasoning(
+    cfg,
+    source: Trace,
+    candidate: Trace,
+    task: str,
+    base: str,
+    key: str,
+) -> tuple[Optional[str], str]:
+    """One call: dead ends -> reasoning block on the final answer.
+
+    Returns (block, note). block is None when the trace is not an
+    exploration trace, the call failed, or the block was rejected; note
+    says which, so the caller can record it in the manifest.
+    """
+    if not getattr(cfg, "distill", True):
+        return None, "disabled"
+    evidence = exploration_evidence(
+        source, min_failures=getattr(cfg, "distill_min_dead_ends",
+                                     MIN_DEAD_ENDS))
+    if not evidence:
+        return None, "not an exploration trace"
+    answer = next(
+        (m.content for m in reversed(candidate.messages)
+         if m.role == "assistant" and (m.content or "").strip()), "")
+    max_chars = int(getattr(cfg, "distill_max_chars", MAX_BLOCK_CHARS))
+    from traceforge.splice import _post_chat
+    data, err = _post_chat(
+        base, key, cfg.model or "",
+        DISTILL_HEADER.format(
+            evidence=_render_evidence(evidence),
+            answer=(answer or "")[:2000],
+            max_chars=max_chars),
+        DISTILL_SCHEMA,
+        max_tokens=min(1200, max_chars // 2 + 200),
+        timeout_s=cfg.rewrite_timeout_s,
+        temperature=cfg.splice_temperature)
+    if not data:
+        return None, f"call failed: {err}"
+    block = data.get("reasoning")
+    if not isinstance(block, str) or not block.strip():
+        return None, "no reasoning in reply"
+    block = " ".join(block.split()).strip()
+    errs = validate_block(block, source, max_chars=max_chars)
+    if errs:
+        return None, "rejected: " + "; ".join(errs[:3])
+    if not attach_to_final(candidate, block, max_chars=max_chars):
+        return None, "no assistant turn to attach to"
+    return block, f"{len(evidence)} dead end(s), {len(block)} chars"

traceforge/export.py

@@ -118,6 +118,13 @@ def export_chat_jsonl(
                 "parent_session_id": t.parent_session_id,
                 "source": t.source,
             }
+            # The harness the session came from. `source` is the producer
+            # ("traceforge-splice"), so it cannot answer "which harness is
+            # this?" — and the harness-balance axis needs that answer.
+            harness = t.harness or (t.source if t.source not in
+                                    ("traceforge-splice", "unknown", None) else None)
+            if harness:
+                meta["harness"] = harness
             role = _agent_role(t)
             if role:
                 meta["agent_role"] = role

traceforge/grounding.py

@@ -150,7 +150,9 @@ def self_grounding_errors(t: Trace, min_coverage: float = 0.95) -> list[str]:
     cov, missing = _coverage(t, _evidence_corpus(t))
     if cov < min_coverage:
         shown = ", ".join(m[:80] for m in missing[:8])
-        return [f"self-grounding {cov:.0%} < {min_coverage:.0%}; facts not "
+        # One decimal, not `:.0%`: 0.947 rounds to "95%", and a gate that
+        # reports "self-grounding 95% < 95%" reads as a bug in the gate.
+        return [f"self-grounding {cov:.1%} < {min_coverage:.0%}; facts not "
                 f"in the trace's own tool results: {shown}"]
     return []
 
@@ -164,7 +166,7 @@ def validate_grounding(
     if cov < min_coverage:
         shown = ", ".join(m[:80] for m in missing[:8])
         errs.append(
-            f"fact grounding {cov:.0%} < {min_coverage:.0%}; "
+            f"fact grounding {cov:.1%} < {min_coverage:.0%}; "
             f"facts not in source trace: {shown}"
         )
     errs.extend(tool_result_fidelity_errors(ideal, real))

traceforge/identity.py

@@ -81,6 +81,70 @@ REFUSAL_RE = re.compile(
 # but we never edit user rows, so a harmful-request trace is not
 # promotable at all; that class dies at triage/judge level instead.
 
+# A vendor co-author trailer is an identity burn in the TARGET span: the
+# trainee learns to sign its commits "Co-Authored-By: Claude".  The gate
+# already rejects it, but the repair round rewrites the window from the same
+# source and reproduces the trailer, so the trace dies.  Measured 2026-10-28
+# on 9,195 workdirs: 259 failed the identity gate on this single string and
+# 188 of them had NO other violation — a purely mechanical defect paying for
+# 12-18 LLM calls per attempt.  Strip it instead of repairing it.
+#
+# The trailer lives inside tool-call ARGUMENTS (a `git commit -m "..."` body),
+# so the newline before it is usually the two characters backslash-n, not a
+# real newline.  Walk the string by hand rather than with one regex: the
+# character class that stops at "backslash or newline" is unreadable and the
+# escaped form is easy to get wrong.
+_TRAILER_HEAD_RE = re.compile(
+    r"co-?authored-?by:[ \t]*"
+    r"(?:claude|chatgpt|gpt-?[45o]|glm|gemini|qwen|gemma|llama|deepseek|"
+    r"copilot|sonnet|opus|anthropic|openai)\b",
+    re.IGNORECASE,
+)
+
+
+def strip_identity_trailers(text: str) -> str:
+    """Remove vendor co-author trailers from assistant text / tool args.
+
+    Returns the input unchanged when nothing matched — a clean row must come
+    back byte-identical (same rule as _sanitize_task_text: only tidy the tail
+    after an actual cut).
+    """
+    if not text or "authored" not in text.lower():
+        return text
+    out: list[str] = []
+    pos = 0
+    changed = False
+    for m in _TRAILER_HEAD_RE.finditer(text):
+        start, end = m.start(), m.end()
+        if start < pos:
+            continue
+        # walk back over the blank-line separator (real or escaped newline)
+        b = start
+        for _ in range(2):
+            if text[max(0, b - 2):b] == "\n":
+                b -= 2
+            elif b >= 1 and text[b - 1] == "\n":
+                b -= 1
+                if b >= 1 and text[b - 1] == "\r":
+                    b -= 1
+            else:
+                break
+        # walk forward to the end of the trailer line: a real newline or the
+        # backslash of the next escaped sequence (a heredoc terminator, a
+        # closing quote) ends it
+        e = end
+        while e < len(text) and text[e] != "\n" and text[e] != "\\":
+            e += 1
+        out.append(text[pos:b])
+        pos = e
+        changed = True
+    if not changed:
+        return text
+    out.append(text[pos:])
+    new = "".join(out)
+    return re.sub(r"(?:\n|\s)+$", "", new)
+
+
 # ---------------------------------------------------------------- system
 # The harness writes its own name into the SYSTEM prompt ("You are Claude
 # Code, Anthropic's official CLI for Claude"), and a model trained on that

traceforge/improver/harness.py

@@ -1,850 +1,941 @@
-"""Runs the improver as a Hermes Agent one-shot session (the harness).
-
-Design: for each trace we spawn
-
-    hermes chat --query-file <prompt.txt> --in <workdir> -Q
-        [--improver-model M] [--max-turns N] [--pass-session-id]
-
-The improver is a full agent: it can read the guidelines file, inspect the
-workdir, write its output with a tool, and re-validate it — agentic
-self-improvement inside the generation loop. The harness never trusts the
-improver's chat reply; it reads back the JSON file the improver wrote,
-then structural validation + repair loop run outside the model.
-"""
-from __future__ import annotations
-
-import dataclasses
-import json
-import os
-import shutil
-import subprocess
-import time
-from typing import Optional
-
-from traceforge import chunker
-from traceforge.config import Config
-from traceforge.grounding import CLIP_MARKER_RE as CLIP_MARKER_PROBE
-from traceforge.improver.prompt import build_prompt, write_prompt_file
-from traceforge.trace import Message, Trace, json_loads_lenient
-
-_TOOL_TAIL_ERROR = "last message role is 'tool' (expected assistant)"
-_EMPTY_ROW_RE = "message with empty content and no tool calls"
-
-
-def _only_tool_tail(errs: list[str]) -> bool:
-    """True when the artifact's ONLY defect is that it ends on a tool row."""
-    return bool(errs) and all(_TOOL_TAIL_ERROR in e for e in errs)
-
-
-def _drop_empty_assistant_rows(improved: Trace) -> bool:
-    """Remove assistant rows with no content and no calls. Returns changed.
-
-    The writer emits these as separators when it loses the thread. They
-    carry zero signal and a trainee must never learn to produce them, so
-    dropping is strictly better than paying a repair round to rewrite the
-    whole trace around one blank row.
-    """
-    kept = [m for m in improved.messages
-            if not (m.role == "assistant" and not m.tool_calls
-                    and not (m.content or "").strip())]
-    if len(kept) == len(improved.messages):
-        return False
-    improved.messages = kept
-    return True
-
-
-def _append_synth_final(cfg: Config, improved: Trace,
-                        source: Trace) -> Optional[Trace]:
-    """Close a trace that the writer left mid-call with a synthesized answer.
-
-    The writer stops after a tool call in ~3% of traces (output cap or turn
-    cap), leaving an artifact that is one row short of valid. A full repair
-    round rewrites the whole trace and usually reproduces the same cut, so
-    the cheap fix is the targeted one: ask for the closing answer only,
-    grounded in the tail that already exists. Same helper the splice path
-    uses for raw traces that were cut off mid-run.
-    """
-    from traceforge.splice import _resolve_endpoint, _synthesize_final_answer
-
-    try:
-        base, key = _resolve_endpoint(cfg)
-    except Exception as e:
-        print(f"  tool-tail synth skipped: endpoint {type(e).__name__}: {e}")
-        return None
-    ans, err = _synthesize_final_answer(
-        cfg, improved, source.first_task_message() or "", base, key)
-    if not ans:
-        print(f"  tool-tail synth failed: {(err or 'empty answer')[:120]}")
-        return None
-    improved.messages.append(Message(role="assistant", content=ans))
-    return improved
-
-CLIP_MARKER_ERROR = (
-    "artifact contains rendering clip markers (…[+N chars clipped]) "
-    "with no verifiable counts — reviewers reject these. Rewrite the tool "
-    "results verbatim from outputs.jsonl (contiguous portions fine)."
-)
-
-# Per-workdir file recording which gate rounds already PASSED for which
-# artifact content digest (see _load_gate_cache).
-GATE_CACHE_FILE = "gate_cache.json"
-
-# Bump whenever a JUDGE/GATE STANDARD changes (new pillar rule, ANSWER
-# note wording that changes verdicts, regex gate changes) — cached
-# passes recorded under an older standard must not replay. The value
-# rides in the cache file; _load_gate_cache discards stale files.
-GATE_CACHE_STANDARDS = "2026-10-08.1"  # +answer-focus rule (P1 FOCUS, over-answering = poor)  # +write-JSON deliverable forms, tool-tail carry, exact-args dup reads  # +mixed-turn surgical drops, usage-error detect, planner >=2 + write-fix chains  # +identity scans tool args (Co-Authored-By), degenerate prose gate  # +judge sees reasoning channel
-
-
-def _clip_markers_present(candidate) -> bool:
-    """True if any message content carries a rendering clip marker."""
-    blob = "\n".join((m.content or "") for m in candidate.messages)
-    return bool(CLIP_MARKER_PROBE.search(blob))
-
-
-def _artifact_digest(candidate) -> str:
-    """Stable content hash of an improved artifact.
-
-    Gate passes are keyed on this: structural/grounding/verify/review
-    PASSes are only replayed from cache when the artifact byte-content is
-    unchanged (the file may still have been rewritten with identical
-    bytes — that's fine, it's the same artifact).
-    """
-    import hashlib
-
-    h = hashlib.sha256()
-    for m in candidate.messages:
-        h.update((m.role or "").encode("utf-8"))
-        h.update(b"\x00")
-        h.update((m.content or "").encode("utf-8"))
-        h.update(b"\x01")
-        if m.tool_call_id:
-            h.update(m.tool_call_id.encode("utf-8"))
-        h.update(b"\x01")
-        if m.tool_name:
-            h.update(m.tool_name.encode("utf-8"))
-        h.update(b"\x02")
-        if m.tool_calls:
-            for tc in m.tool_calls:
-                h.update((tc.id or "").encode("utf-8"))
-                h.update((tc.name or "").encode("utf-8"))
-                h.update((tc.arguments or "").encode("utf-8"))
-                h.update(b"\x03")
-    return h.hexdigest()
-
-
-class ImproverResult:
-    def __init__(
-        self,
-        *,
-        session_id: str,
-        ok: bool,
-        improved: Optional[Trace],
-        reply: str,
-        hermes_session_id: Optional[str] = None,
-        errors: Optional[list[str]] = None,
-        attempts: int = 0,
-        duration_s: float = 0.0,
-    ):
-        self.session_id = session_id          # source trace session id
-        self.ok = ok
-        self.improved = improved
-        self.reply = reply
-        self.hermes_session_id = hermes_session_id
-        self.errors = errors or []
-        self.attempts = attempts
-        self.duration_s = duration_s
-
-    def to_dict(self) -> dict:
-        return {
-            "session_id": self.session_id,
-            "ok": self.ok,
-            "errors": self.errors,
-            "hermes_session_id": self.hermes_session_id,
-            "attempts": self.attempts,
-            "duration_s": round(self.duration_s, 1),
-        }
-
-
-def _run_hermes(
-    cfg: Config, prompt_path: str, workdir: str
-) -> tuple[int, str, Optional[str], str]:
-    """Invoke hermes chat one-shot; returns (exit_code, stdout, session_id)."""
-    cmd = [
-        "hermes", "chat",
-        "--query-file", prompt_path,
-        "--in", workdir,
-        "-Q",
-        "--format", "text",
-        "--pass-session-id",
-    ]
-    if cfg.model:
-        cmd += ["-m", cfg.model]
-    if cfg.provider:
-        cmd += ["--provider", cfg.provider]
-    if cfg.max_turns:
-        cmd += ["--max-turns", str(cfg.max_turns)]
-    if cfg.run_budget:
-        cmd += ["--run-budget", str(cfg.run_budget)]
-    if cfg.skills:
-        cmd += ["-s", ",".join(cfg.skills)]
-    proc = subprocess.run(
-        cmd,
-        capture_output=True,
-        text=True,
-        timeout=cfg.harness_timeout_s,
-        cwd=workdir,
-    )
-    session_id = None
-    for line in (proc.stdout or "").splitlines():
-        if line.strip().startswith("session_id:"):
-            session_id = line.split(":", 1)[1].strip() or None
-    return proc.returncode, proc.stdout, session_id, proc.stderr
-
-
-def _parse_improved(path: str) -> Optional[Trace]:
-    """Parse the improver-written improved.json into a Trace, leniently."""
-    if not os.path.exists(path):
-        return None
-    with open(path, "r", encoding="utf-8") as f:
-        raw = f.read()
-    # tolerate fenced code blocks from chatty models
-    raw = raw.strip()
-    if raw.startswith("```"):
-        raw = raw.split("\n", 1)[1] if "\n" in raw else ""
-        if raw.rstrip().endswith("```"):
-            raw = raw.rstrip()[: -3]
-    data = json_loads_lenient(raw)
-    if not isinstance(data, dict):
-        return None
-    msgs = data.get("messages")
-    if not isinstance(msgs, list):
-        return None
-    from traceforge.trace import Message, ToolCall
-
-    out = []
-    for d in msgs:
-        if not isinstance(d, dict) or "role" not in d:
-            return None
-        m = {
-            "role": d["role"],
-            "content": d.get("content"),
-            "reasoning": d.get("reasoning"),
-            "tool_call_id": d.get("tool_call_id"),
-            "tool_name": d.get("tool_name"),
-        }
-        m = {k: v for k, v in m.items() if v is not None}
-        if "tool_calls" in d and isinstance(d["tool_calls"], list):
-            m["tool_calls"] = [
-                {
-                    "id": str(tc.get("id", "")),
-                    "name": str(tc.get("name", "")),
-                    "arguments": tc.get("arguments") or "{}",
-                }
-                for tc in d["tool_calls"]
-                if isinstance(tc, dict)
-            ]
-        out.append(Message.from_dict(m))
-    return Trace(
-        session_id="improved-placeholder",  # set by caller
-        messages=out,
-        improved=True,
-    )
-
-
-def _append_status(cfg: Config, sid: str, status: dict) -> None:
-    """Append a stage-level status row to the manifest."""
-    import json as _json
-
-    os.makedirs(os.path.dirname(cfg.manifest_path), exist_ok=True)
-    row = {"session_id": sid, **status}
-    with open(cfg.manifest_path, "a", encoding="utf-8") as f:
-        f.write(_json.dumps(row, ensure_ascii=False) + "\n")
-
-
-def _load_gate_cache(workdir: str) -> dict:
-    """Read the workdir's gate-pass cache (digest -> list of gate rows).
-
-    Batches die at arbitrary points (turn interruptions, terminal close,
-    SIGTERM to the worker pool); without this, every verify/review round
-    already PAID FOR on an unchanged artifact is re-run from scratch on
-    the next resume. The cache is keyed by the artifact's content digest
-    so a rewritten (different) artifact never inherits stale passes.
-    Cached passes from an OLDER standards version are discarded — judge
-    rules evolve, and a verdict recorded under old rules must not
-    replay against new ones.
-    """
-    path = os.path.join(workdir, GATE_CACHE_FILE)
-    try:
-        with open(path, "r", encoding="utf-8") as f:
-            data = json.load(f)
-        if not isinstance(data, dict):
-            return {}
-        if data.get("standards") != GATE_CACHE_STANDARDS:
-            return {}
-        return data
-    except (OSError, json.JSONDecodeError):
-        return {}
-
-
-def _save_gate_cache(workdir: str, cache: dict) -> None:
-    """Persist the gate-pass cache atomically (workdir, per trace)."""
-    path = os.path.join(workdir, GATE_CACHE_FILE)
-    tmp = path + ".tmp"
-    cache = dict(cache)
-    cache["standards"] = GATE_CACHE_STANDARDS
-    with open(tmp, "w", encoding="utf-8") as f:
-        json.dump(cache, f, ensure_ascii=False)
-    os.replace(tmp, path)
-
-
-def _cache_gate_pass(cache: dict, digest: str, stage: str, round_no: int) -> None:
-    """Record a gate PASS for one artifact digest."""
-    rows = cache.setdefault(digest, [])
-    key = f"{stage}:{round_no}"
-    if key not in rows:
-        rows.append(key)
-
-
-def _acquire_workdir_lock(workdir: str) -> bool:
-    """O_EXCL pid lockfile; locks left by dead processes are stolen.
-
-    Two concurrent improve batches working the same sid corrupt each
-    other (shared improved.json / verdict.json — the verifier unlinks its
-    verdict file before each run) and burn double model time. The lock
-    makes one-improver-per-workdir structural, not a user discipline.
-    """
-    lock_path = os.path.join(workdir, ".lock")
-    my_pid = str(os.getpid())
-    for _ in range(3):
-        try:
-            fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
-            try:
-                os.write(fd, my_pid.encode())
-            finally:
-                os.close(fd)
-            return True
-        except FileExistsError:
-            try:
-                other = open(lock_path, encoding="utf-8").read().strip()
-            except OSError:
-                continue
-            pid = int(other) if other.isdigit() else -1
-            alive = False
-            if pid > 0:
-                try:
-                    os.kill(pid, 0)
-                    alive = True
-                except ProcessLookupError:
-                    alive = False
-                except PermissionError:
-                    alive = True  # exists, not ours: assume alive
-                except OverflowError:
-                    alive = False
-            if alive:
-                return False
-            try:
-                os.unlink(lock_path)  # stale lock from a dead run: steal
-            except OSError:
-                pass
-    return False
-
-
-def _release_workdir_lock(workdir: str) -> None:
-    """Drop our own lock (never another live run's)."""
-    lock_path = os.path.join(workdir, ".lock")
-    try:
-        with open(lock_path, encoding="utf-8") as f:
-            if f.read().strip() == str(os.getpid()):
-                os.unlink(lock_path)
-    except OSError:
-        pass
-
-
-def _write_outputs_index(
-    cfg: Config, trace: Trace, workdir: str, max_chars: int = 250_000
-) -> str:
-    """Full real tool outputs as outputs.jsonl, keyed by rendering index.
-
-    The compact rendering clips each tool result to a short head; P4
-    demands verbatim reuse, so the improver needs the unclipped text.
-    One JSON object per line: {"i": N, "tool", "args", "output"} where N
-    is the same [N] message index the rendering shows — the improver can
-    correlate a clipped result in its prompt with the full text here.
-
-    max_chars is a byte-blow safety valve (measured corpus max real
-    output: ~111KB), NOT a compression budget: the 20k cap this used to
-    apply hid exactly the mid-tail evidence (p95 = 20k) that P4 demands
-    the improver quote — on exactly the big traces where review kills
-    artifacts — forcing composed pseudo-outputs. Outputs beyond the
-    safety valve carry an honest total-marker, never a fake count.
-    """
-    path = os.path.join(workdir, "outputs.jsonl")
-    arg_of: dict[str, str] = {}
-    for m in trace.messages:
-        for tc in m.tool_calls:
-            arg_of[tc.id] = tc.arguments or "{}"
-    with open(path, "w", encoding="utf-8") as f:
-        for i, m in enumerate(trace.messages, 1):
-            if m.role != "tool" or not m.content:
-                continue
-            out = m.content
-            if len(out) > max_chars:
-                out = out[:max_chars] + f" …[+{len(out) - max_chars} chars total]"
-            f.write(json.dumps({
-                "i": i,
-                "tool": m.tool_name or "?",
-                "args": arg_of.get(m.tool_call_id or "", "")[:400],
-                "output": out,
-            }, ensure_ascii=False) + "\n")
-    return path
-
-
-def _generate_single(cfg, trace, rendered, workdir, output_path, errors, prev_path, sid):
-    """One single-shot improver invocation. Returns (candidate, reply, hsid, code, stderr) or raises Timeout."""
-    from traceforge.classify import detect_language
-    prompt = build_prompt(
-        rendered_trace=rendered,
-        guidelines_path=cfg.guidelines_path,
-        output_path=output_path,
-        outputs_path=os.path.join(workdir, "outputs.jsonl"),
-        errors=errors,
-        prev_path=prev_path,
-        language=detect_language(trace.first_task_message() or ""),
-    )
-    prompt_path = write_prompt_file(cfg.prompts_dir, sid, prompt)
-    try:
-        code, stdout, hsid, stderr = _run_hermes(cfg, prompt_path, workdir)
-    except subprocess.TimeoutExpired as e:
-        raise e
-    reply = (stdout or "").strip()
-    return _parse_improved(output_path), reply, hsid, code, stderr
-
-
-def improve_trace(
-    cfg: Config,
-    trace: Trace,
-    *,
-    max_attempts: int = 2,
-    validator=None,
-    status_cb=None,
-) -> ImproverResult:
-    """Run the agentic improver on one trace, with a validation repair loop.
-
-    Long traces (rendered size > cfg.chunk_max_chars) go through the staged
-    map-digest-write pipeline instead of the single shot. Every admitted
-    trace passes: N independent verification rounds (web fact-check) and
-    M independent review rounds (quality-pillar review) — all must PASS.
-
-    ``status_cb`` (optional) receives short human stage strings
-    ("improving", "digest", "verify 1/2", ...) for live progress display.
-    """
-    from traceforge.trace import Trace as _T
-    from traceforge.validate import validate_structural
-    from traceforge.grounding import validate_grounding
-    from traceforge.improver.verify import run_verifier
-    from traceforge.improver.review import run_review
-
-    def _status(s: str) -> None:
-        if status_cb is not None:
-            status_cb(s)
-
-    started = time.time()
-    sid = trace.session_id
-    workdir = os.path.join(cfg.improver_workdir, sid)
-    os.makedirs(workdir, exist_ok=True)
-    # One improver per workdir, structurally: concurrent batches on the
-    # same sid race on improved.json/verdict.json and pay the model twice.
-    if not _acquire_workdir_lock(workdir):
-        return ImproverResult(
-            session_id=sid, ok=False, improved=None, reply="",
-            hermes_session_id=None,
-            errors=["workdir locked by a live improver run — skipping"],
-            attempts=0, duration_s=0.0,
-        )
-    try:
-        return _improve_locked(cfg, trace, max_attempts, status_cb)
-    finally:
-        _release_workdir_lock(workdir)
-
-
-def _improve_locked(
-    cfg: Config, trace: Trace, max_attempts: int, status_cb
-) -> ImproverResult:
-    from traceforge.trace import Trace as _T
-    from traceforge.validate import validate_structural
-    from traceforge.grounding import validate_grounding
-    from traceforge.improver.verify import run_verifier
-    from traceforge.improver.review import run_review
-
-    def _status(s: str) -> None:
-        if status_cb is not None:
-            status_cb(s)
-
-    started = time.time()
-    sid = trace.session_id
-    workdir = os.path.join(cfg.improver_workdir, sid)
-    rendered = trace.render_compact(
-        user_chars=cfg.user_chars,
-        assistant_chars=cfg.assistant_chars,
-        tool_result_chars=cfg.tool_result_chars,
-        tool_args_chars=cfg.tool_args_chars,
-        include_reasoning=cfg.include_reasoning,
-    )
-    output_path = os.path.join(workdir, "improved.json")
-    # Full unclipped tool outputs on disk: P4's verbatim-reuse rule is
-    # only satisfiable when the improver can actually see the full text.
-    outputs_path = _write_outputs_index(cfg, trace, workdir)
-
-    errors: list[str] = []
-    prev_path: Optional[str] = None
-    attempts = 0
-    improved: Optional[Trace] = None
-    reply = ""
-    hermes_session_id: Optional[str] = None
-    # long-trace attempts don't run hermes chat directly (stages do); the
-    # loop below must not touch single-shot navigation vars on that path
-    code = 0
-    stderr = ""
-
-    for attempt in range(1, max_attempts + 1):
-        attempts = attempt
-        candidate = None
-        # Fast-path: when a previous run already left an artifact in this
-        # workdir, re-adjudicate it first (regate). Only pay the model for
-        # a fresh write when nothing usable exists on disk. This makes
-        # "rerun after a gate change" nearly free instead of a full
-        # re-write of every trace.
-        if attempt == 1 and os.path.exists(output_path):
-            _status("regate")
-            candidate = _parse_improved(output_path)
-            # Static pre-flight: an artifact that still carries rendering
-            # clip markers is dead on arrival at review (reviewers kill
-            # invented counts; grounding silently strips them). Fail it
-            # here — one static check instead of 4 deep-thinker
-            # sessions re-discovering it.
-            if candidate is not None and _clip_markers_present(candidate):
-                candidate = None
-                errors = [CLIP_MARKER_ERROR]
-                # keep the failed artifact as the repair reference: the
-                # next attempt must FIX it (REPAIR_HEADER + errors), not
-                # blind-rewrite from a fresh TASK_HEADER that would
-                # silently drop the specific clip-marker error.
-                prev_path = output_path
-        if candidate is not None:
-            reply = "REGATE (existing artifact)"
-            code = 0
-            stderr = ""
-        elif len(rendered) <= cfg.chunk_max_chars:
-            _status("improving" if attempt == 1 else f"repair {attempt}")
-            try:
-                candidate, reply_one, hsid, code, stderr = _generate_single(
-                    cfg, trace, rendered, workdir, output_path, errors,
-                    prev_path, sid,
-                )
-            except subprocess.TimeoutExpired:
-                errors = [f"harness timeout after {cfg.harness_timeout_s}s"]
-                continue
-            reply = reply_one
-            hermes_session_id = hsid
-            if reply.startswith("REJECTED"):
-                errors = [f"rejected by improver: {reply[:300]}"]
-                break
-        else:
-            # long-trace staged pipeline: digest -> map -> writer
-            from traceforge.improver import longtrace
-
-            chunk_dir = os.path.join(workdir, "chunks")
-            if prev_path is None:
-                _status("digest+map")
-                chunks = chunker.chunk_trace(
-                    trace,
-                    max_chars=cfg.chunk_max_chars,
-                    overlap_messages=cfg.chunk_overlap_messages,
-                    render_kwargs={
-                        "user_chars": cfg.user_chars,
-                        "assistant_chars": cfg.assistant_chars,
-                        "tool_result_chars": cfg.tool_result_chars,
-                        "tool_args_chars": cfg.tool_args_chars,
-                        "include_reasoning": cfg.include_reasoning,
-                    },
-                )
-                if not chunks:
-                    errors = ["chunking produced no chunks"]
-                    continue
-                longtrace.write_chunks(chunk_dir, chunks, trace)
-                _status(f"digest 0/{len(chunks)}")
-                digests, derrs = longtrace.digest_all(
-                    cfg, trace, chunks, workdir,
-                    progress_cb=lambda done, total: _status(
-                        f"digest {done}/{total}"
-                    ),
-                )
-                if derrs:
-                    errors = [f"digest failures: {derrs}"]
-                    continue
-                _status(f"map ({len(chunks)} chunks)")
-                map_d, merr = longtrace.build_map(cfg, trace, digests, workdir)
-                if map_d is None:
-                    errors = [f"map merge failed: {merr}"]
-                    continue
-                _append_status(cfg, sid, {
-                    "stage": "map", "chunks": len(chunks),
-                    "approx_tokens": sum(c.approx_chars for c in chunks) // 4,
-                })
-            # writer (also used for repair attempts on long traces)
-            map_d = longtrace._json_file(os.path.join(workdir, "session_map.json"))
-            if map_d is None:
-                errors = ["session map missing after long-trace stage"]
-                continue
-            _status("writer")
-            candidate, werr = longtrace.run_writer(
-                cfg, trace, map_d, chunk_dir, workdir, output_path,
-                repair_errors=errors if prev_path else None,
-            )
-            if candidate is None:
-                errors = [f"long-trace writer failed: {werr}"]
-                continue
-            reply = "WRITER DONE"
-        # The artifact on disk is the source of truth — NOT the exit code.
-        # The improver may hit its turn cap after writing a perfectly valid
-        # file (e.g. right after a repair); validate what exists regardless.
-        candidate = _parse_improved(output_path)
-        if candidate is None:
-            if code != 0:
-                stderr_tail = f"; stderr: {stderr.strip()[-500:]}" if stderr else ""
-                errors = [
-                    f"hermes chat exited with code {code} and "
-                    f"improved.json missing/unparseable{stderr_tail}"
-                ]
-            else:
-                errors = [
-                    "improved.json missing, unparseable, or missing 'messages'"
-                ]
-            continue
-        # Static clip-marker gate on EVERY path, not just regate: writers
-        # and repairs can still copy markers out of the clipped rendering.
-        # A marker artifact is dead on arrival at review (and grounding
-        # silently forgives it) — fail fast here instead of burning
-        # verifier + reviewer sessions on it.
-        if _clip_markers_present(candidate):
-            errors = [f"clip-marker gate: {CLIP_MARKER_ERROR}"]
-            # repair must fix THIS artifact (REPAIR_HEADER + errors), not
-            # blind-rewrite from a TASK_HEADER that drops the specifics
-            prev_path = output_path
-            continue
-        prev_path = output_path
-        improved = candidate
-        # Pipeline framing markers ("[trace segment k of n]", "[subagent
-        # brief — role: ...]") belong to the improver's INPUT; strip them
-        # before the gates so the echo check compares against the real task
-        # and the promoted artifact carries no scaffolding.
-        from traceforge.validate import strip_scaffold_markers
-        if strip_scaffold_markers(improved):
-            improved.save(output_path)
-        errs = validate_structural(improved)
-        if errs and any(_EMPTY_ROW_RE in e for e in errs):
-            # blank assistant rows are pure noise — drop them and re-check
-            # rather than paying a full rewrite to remove one empty row.
-            # Runs even when other errors are present: a trace with a blank
-            # row AND a tool tail must get both fixes, not neither.
-            if _drop_empty_assistant_rows(improved):
-                improved.save(output_path)  # repair must start from the fix
-                errs = validate_structural(improved)
-                if not errs:
-                    _status("dropped empty assistant rows")
-        if _only_tool_tail(errs):
-            # writer stopped mid-call: one row short of valid. Synthesize
-            # the closing answer instead of paying a full repair round
-            # that reproduces the same cut (measured: 49/1535 traces).
-            fixed = _append_synth_final(cfg, improved, trace)
-            if fixed is not None:
-                improved = fixed
-                # persist BEFORE re-validating: a later repair round reads
-                # prev_path from disk, so an in-memory-only fix is thrown
-                # away and the writer reproduces the same tool tail.
-                improved.save(output_path)
-                errs = validate_structural(improved)
-                if not errs:
-                    _status("final answer (tool-tail synth)")
-        if not errs:
-            errs = validate_grounding(improved, trace)
-        if not errs and (cfg.verify or cfg.review):
-            # Gate-pass cache: rounds that already PASSED for THIS exact
-            # artifact content are replayed instead of re-paid. Survives
-            # batch interruptions (turn cap, SIGTERM, terminal close); a
-            # rewritten artifact has a different digest and re-runs all
-            # rounds fresh.
-            digest = _artifact_digest(improved)
-            gate_cache = _load_gate_cache(workdir)
-            gate_pass_keys = set(gate_cache.get(digest, []))
-
-            def _gate_pass(stage: str, round_no: int) -> None:
-                _cache_gate_pass(gate_cache, digest, stage, round_no)
-                _save_gate_cache(workdir, gate_cache)
-
-            verify_failures: list[str] = []
-            # ---- N independent verification rounds (web fact-check)
-            # Strict admission: every round must end PASS. A transient ERROR
-            # (timeout, unparseable verdict) gets ONE in-place retry; a
-            # second ERROR surfaces as an error row — never silent
-            # under-verification, never a model repair for infra issues.
-            if cfg.verify:
-                passes = 0
-                vr = 1
-                while vr <= cfg.verify_rounds:
-                    if f"verify:{vr}" in gate_pass_keys:
-                        passes += 1  # already adjudicated on identical bytes
-                        _status(f"verify {vr}/{cfg.verify_rounds} (cached)")
-                        _append_status(cfg, sid, {
-                            "stage": "verify", "round": vr,
-                            "verdict": "PASS", "cached": True,
-                        })
-                        vr += 1
-                        continue
-                    _status(f"verify {vr}/{cfg.verify_rounds}")
-                    vres = run_verifier(cfg, output_path, workdir)
-                    if vres.verdict == "PASS":
-                        passes += 1
-                        _gate_pass("verify", vr)
-                        _append_status(cfg, sid, {
-                            "stage": "verify", "round": vr,
-                            "verdict": "PASS",
-                            "claims_checked": vres.claims_checked,
-                        })
-                        vr += 1
-                        continue
-                    if vres.verdict == "FAIL":
-                        claims = "\n".join(
-                            f'- "{u.get("claim", "?")}" — {u.get("why", "?")}'
-                            for u in vres.unsupported[:10]
-                        )
-                        verify_failures.append(
-                            f"[verify r{vr}] external claims unsupported:\n{claims}"
-                        )
-                        _append_status(cfg, sid, {
-                            "stage": "verify", "round": vr, "verdict": "FAIL",
-                            "claims_checked": vres.claims_checked,
-                        })
-                        break  # concrete FAIL: repair next attempt
-                    # transient ERROR: one in-place retry of the same round
-                    retry = run_verifier(cfg, output_path, workdir)
-                    if retry.verdict == "PASS":
-                        passes += 1
-                        _gate_pass("verify", vr)
-                        _append_status(cfg, sid, {
-                            "stage": "verify", "round": vr,
-                            "verdict": "PASS", "retried": True,
-                            "claims_checked": retry.claims_checked,
-                        })
-                        vr += 1
-                        continue
-                    if retry.verdict == "FAIL":
-                        claims = "\n".join(
-                            f'- "{u.get("claim", "?")}" — {u.get("why", "?")}'
-                            for u in retry.unsupported[:10]
-                        )
-                        verify_failures.append(
-                            f"[verify r{vr}] external claims unsupported:\n{claims}"
-                        )
-                        _append_status(cfg, sid, {
-                            "stage": "verify", "round": vr, "verdict": "FAIL",
-                            "retried": True,
-                            "claims_checked": retry.claims_checked,
-                        })
-                        break
-                    verify_failures.append(
-                        f"[verify r{vr}] infra error x2: "
-                        f"{vres.error or 'verifier error'} / "
-                        f"{retry.error or 'verifier error'}"
-                    )
-                    _append_status(cfg, sid, {
-                        "stage": "verify", "round": vr, "verdict": "ERROR",
-                        "error": (
-                            f"{vres.error or 'verifier error'} / "
-                            f"{retry.error or 'verifier error'}"
-                        )[:300],
-                    })
-                    break
-            # ---- M independent review rounds (quality pillars)
-            review_failures: list[str] = []
-            task_snip = trace.first_task_message() or "(no user message)"
-            if not verify_failures and cfg.review:
-                for rr in range(1, cfg.review_rounds + 1):
-                    if f"review:{rr}" in gate_pass_keys:
-                        _status(f"review {rr}/{cfg.review_rounds} (cached)")
-                        _append_status(cfg, sid, {
-                            "stage": "review", "round": rr, "verdict": "PASS",
-                            "cached": True,
-                        })
-                        continue
-                    _status(f"review {rr}/{cfg.review_rounds}")
-                    rres = run_review(
-                        cfg, output_path, task_snip, workdir, rr
-                    )
-                    if not rres.ok() and rres.verdict == "ERROR":
-                        rres = run_review(
-                            cfg, output_path, task_snip, workdir, rr
-                        )  # one in-place retry on transient infra error
-                    if rres.ok():
-                        _gate_pass("review", rr)
-                        _append_status(cfg, sid, {
-                            "stage": "review", "round": rr, "verdict": "PASS",
-                        })
-                        continue
-                    if rres.verdict == "FAIL":
-                        review_failures.append(
-                            "[review r%d] pillar violations:\n%s"
-                            % (rr, "\n".join(rres.violations[:10]))
-                        )
-                        _append_status(cfg, sid, {
-                            "stage": "review", "round": rr, "verdict": "FAIL",
-                        })
-                        break  # concrete FAIL: repair next attempt
-                    review_failures.append(
-                        f"[review r{rr}] infra error x2: {rres.error or 'review error'}"
-                    )
-                    _append_status(cfg, sid, {
-                        "stage": "review", "round": rr, "verdict": "ERROR",
-                        "error": (rres.error or "review error")[:300],
-                    })
-                    break
-            errs = verify_failures + review_failures
-        if errs:
-            # Infra failures (verifier/reviewer down) are NOT content errors:
-            # a model repair cannot fix them. Fail fast without re-running
-            # the improver so no model time is wasted on infrastructure.
-            if any("infra error x2" in e for e in errs):
-                return ImproverResult(
-                    session_id=sid, ok=False, improved=None, reply=reply,
-                    hermes_session_id=hermes_session_id,
-                    errors=errs, attempts=attempts,
-                    duration_s=time.time() - started,
-                )
-            errors = errs + (
-                [f"note: hermes exit code {code}"] if code != 0 else []
-            )
-            continue
-        improved.session_id = f"ideal-{sid}"
-        improved.parent_session_id = sid
-        # cfg.model None = default profile; the exact model is recoverable
-        # from hermes_session_id (recorded in the manifest).
-        improved.model = cfg.model or "hermes-default"
-        improved.source = "hermes-one-shot"
-        return ImproverResult(
-            session_id=sid, ok=True, improved=improved, reply=reply,
-            hermes_session_id=hermes_session_id, errors=[],
-            attempts=attempts, duration_s=time.time() - started,
-        )
-
-    return ImproverResult(
-        session_id=sid, ok=False, improved=None, reply=reply,
-        hermes_session_id=hermes_session_id, errors=errors,
-        attempts=attempts, duration_s=time.time() - started,
-    )
-
-
-def cleanup_workdir(cfg: Config, sid: str, keep: bool = False) -> None:
-    wd = os.path.join(cfg.improver_workdir, sid)
-    if not keep and os.path.isdir(wd):
+"""Runs the improver as a Hermes Agent one-shot session (the harness).
+
+Design: for each trace we spawn
+
+    hermes chat --query-file <prompt.txt> --in <workdir> -Q
+        [--improver-model M] [--max-turns N] [--pass-session-id]
+
+The improver is a full agent: it can read the guidelines file, inspect the
+workdir, write its output with a tool, and re-validate it — agentic
+self-improvement inside the generation loop. The harness never trusts the
+improver's chat reply; it reads back the JSON file the improver wrote,
+then structural validation + repair loop run outside the model.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import shutil
+import subprocess
+import time
+from typing import Optional
+
+from traceforge import chunker
+from traceforge.config import Config
+from traceforge.grounding import CLIP_MARKER_RE as CLIP_MARKER_PROBE
+from traceforge.improver.prompt import build_prompt, write_prompt_file
+from traceforge.trace import Message, Trace, json_loads_lenient
+
+_TOOL_TAIL_ERROR = "last message role is 'tool' (expected assistant)"
+_EMPTY_ROW_RE = "message with empty content and no tool calls"
+
+
+def _only_tool_tail(errs: list[str]) -> bool:
+    """True when the artifact's ONLY defect is that it ends on a tool row."""
+    return bool(errs) and all(_TOOL_TAIL_ERROR in e for e in errs)
+
+
+def _drop_empty_assistant_rows(improved: Trace) -> bool:
+    """Remove assistant rows with no content and no calls. Returns changed.
+
+    The writer emits these as separators when it loses the thread. They
+    carry zero signal and a trainee must never learn to produce them, so
+    dropping is strictly better than paying a repair round to rewrite the
+    whole trace around one blank row.
+    """
+    kept = [m for m in improved.messages
+            if not (m.role == "assistant" and not m.tool_calls
+                    and not (m.content or "").strip())]
+    if len(kept) == len(improved.messages):
+        return False
+    improved.messages = kept
+    return True
+
+
+def _drop_narration_rows(improved: Trace) -> bool:
+    """Remove standalone short announcement rows. Returns changed.
+
+    The writer keeps the source agent's "let me look at X" announcements as
+    standalone prose rows. Measured 2026-10-28 on the 4,505-trace corpus: 80
+    such rows, 56 of them in 52 traces sitting between a tool result and the
+    next call. The guidelines forbid narration and the judge cites it as P1
+    filler, but a repair round rewrites the window and reproduces it, so the
+    deterministic drop is the fix. The rule (short, prose-only, not the final
+    answer, not a reply to a user turn) lives in splice._drop_narration_rows
+    so both engines share one definition.
+    """
+    from traceforge.splice import _drop_narration_rows as _drop
+    msgs = improved.messages
+    out, _, reasons = _drop(msgs, list(range(len(msgs))))
+    if not reasons:
+        return False
+    improved.messages = out
+    return True
+
+
+def _strip_identity_trailers_trace(improved: Trace) -> bool:
+    """Strip vendor co-author trailers from assistant text / tool args.
+
+    The gate rejects them (identity burn in the TARGET span), but a repair
+    round rewrites the window from the same source and reproduces the
+    trailer. Measured 2026-10-28: 259 workdirs failed on this one string,
+    188 with no other violation. The rule lives in splice so both engines
+    share one definition.
+    """
+    from traceforge.splice import _strip_identity_trailers as _strip
+    msgs = improved.messages
+    out, _, reasons = _strip(msgs, list(range(len(msgs))))
+    if not reasons:
+        return False
+    improved.messages = out
+    return True
+
+
+def _append_synth_final(cfg: Config, improved: Trace,
+                        source: Trace) -> Optional[Trace]:
+    """Close a trace that the writer left mid-call with a synthesized answer.
+
+    The writer stops after a tool call in ~3% of traces (output cap or turn
+    cap), leaving an artifact that is one row short of valid. A full repair
+    round rewrites the whole trace and usually reproduces the same cut, so
+    the cheap fix is the targeted one: ask for the closing answer only,
+    grounded in the tail that already exists. Same helper the splice path
+    uses for raw traces that were cut off mid-run.
+    """
+    from traceforge.splice import _resolve_endpoint, _synthesize_final_answer
+
+    try:
+        base, key = _resolve_endpoint(cfg)
+    except Exception as e:
+        print(f"  tool-tail synth skipped: endpoint {type(e).__name__}: {e}")
+        return None
+    ans, err = _synthesize_final_answer(
+        cfg, improved, source.first_task_message() or "", base, key)
+    if not ans:
+        print(f"  tool-tail synth failed: {(err or 'empty answer')[:120]}")
+        return None
+    improved.messages.append(Message(role="assistant", content=ans))
+    return improved
+
+CLIP_MARKER_ERROR = (
+    "artifact contains rendering clip markers (…[+N chars clipped]) "
+    "with no verifiable counts — reviewers reject these. Rewrite the tool "
+    "results verbatim from outputs.jsonl (contiguous portions fine)."
+)
+
+# Per-workdir file recording which gate rounds already PASSED for which
+# artifact content digest (see _load_gate_cache).
+GATE_CACHE_FILE = "gate_cache.json"
+
+# Bump whenever a JUDGE/GATE STANDARD changes (new pillar rule, ANSWER
+# note wording that changes verdicts, regex gate changes) — cached
+# passes recorded under an older standard must not replay. The value
+# rides in the cache file; _load_gate_cache discards stale files.
+GATE_CACHE_STANDARDS = "2026-10-08.1"  # +answer-focus rule (P1 FOCUS, over-answering = poor)  # +write-JSON deliverable forms, tool-tail carry, exact-args dup reads  # +mixed-turn surgical drops, usage-error detect, planner >=2 + write-fix chains  # +identity scans tool args (Co-Authored-By), degenerate prose gate  # +judge sees reasoning channel
+
+
+def _clip_markers_present(candidate) -> bool:
+    """True if any message content carries a rendering clip marker."""
+    blob = "\n".join((m.content or "") for m in candidate.messages)
+    return bool(CLIP_MARKER_PROBE.search(blob))
+
+
+def _artifact_digest(candidate) -> str:
+    """Stable content hash of an improved artifact.
+
+    Gate passes are keyed on this: structural/grounding/verify/review
+    PASSes are only replayed from cache when the artifact byte-content is
+    unchanged (the file may still have been rewritten with identical
+    bytes — that's fine, it's the same artifact).
+    """
+    import hashlib
+
+    h = hashlib.sha256()
+    for m in candidate.messages:
+        h.update((m.role or "").encode("utf-8"))
+        h.update(b"\x00")
+        h.update((m.content or "").encode("utf-8"))
+        h.update(b"\x01")
+        if m.tool_call_id:
+            h.update(m.tool_call_id.encode("utf-8"))
+        h.update(b"\x01")
+        if m.tool_name:
+            h.update(m.tool_name.encode("utf-8"))
+        h.update(b"\x02")
+        if m.tool_calls:
+            for tc in m.tool_calls:
+                h.update((tc.id or "").encode("utf-8"))
+                h.update((tc.name or "").encode("utf-8"))
+                h.update((tc.arguments or "").encode("utf-8"))
+                h.update(b"\x03")
+    return h.hexdigest()
+
+
+class ImproverResult:
+    def __init__(
+        self,
+        *,
+        session_id: str,
+        ok: bool,
+        improved: Optional[Trace],
+        reply: str,
+        hermes_session_id: Optional[str] = None,
+        errors: Optional[list[str]] = None,
+        attempts: int = 0,
+        duration_s: float = 0.0,
+    ):
+        self.session_id = session_id          # source trace session id
+        self.ok = ok
+        self.improved = improved
+        self.reply = reply
+        self.hermes_session_id = hermes_session_id
+        self.errors = errors or []
+        self.attempts = attempts
+        self.duration_s = duration_s
+
+    def to_dict(self) -> dict:
+        return {
+            "session_id": self.session_id,
+            "ok": self.ok,
+            "errors": self.errors,
+            "hermes_session_id": self.hermes_session_id,
+            "attempts": self.attempts,
+            "duration_s": round(self.duration_s, 1),
+        }
+
+
+def _run_hermes(
+    cfg: Config, prompt_path: str, workdir: str
+) -> tuple[int, str, Optional[str], str]:
+    """Invoke hermes chat one-shot; returns (exit_code, stdout, session_id)."""
+    cmd = [
+        "hermes", "chat",
+        "--query-file", prompt_path,
+        "--in", workdir,
+        "-Q",
+        "--format", "text",
+        "--pass-session-id",
+    ]
+    if cfg.model:
+        cmd += ["-m", cfg.model]
+    if cfg.provider:
+        cmd += ["--provider", cfg.provider]
+    if cfg.max_turns:
+        cmd += ["--max-turns", str(cfg.max_turns)]
+    if cfg.run_budget:
+        cmd += ["--run-budget", str(cfg.run_budget)]
+    if cfg.skills:
+        cmd += ["-s", ",".join(cfg.skills)]
+    proc = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=cfg.harness_timeout_s,
+        cwd=workdir,
+    )
+    session_id = None
+    for line in (proc.stdout or "").splitlines():
+        if line.strip().startswith("session_id:"):
+            session_id = line.split(":", 1)[1].strip() or None
+    return proc.returncode, proc.stdout, session_id, proc.stderr
+
+
+def _parse_improved(path: str) -> Optional[Trace]:
+    """Parse the improver-written improved.json into a Trace, leniently."""
+    if not os.path.exists(path):
+        return None
+    with open(path, "r", encoding="utf-8") as f:
+        raw = f.read()
+    # tolerate fenced code blocks from chatty models
+    raw = raw.strip()
+    if raw.startswith("```"):
+        raw = raw.split("\n", 1)[1] if "\n" in raw else ""
+        if raw.rstrip().endswith("```"):
+            raw = raw.rstrip()[: -3]
+    data = json_loads_lenient(raw)
+    if not isinstance(data, dict):
+        return None
+    msgs = data.get("messages")
+    if not isinstance(msgs, list):
+        return None
+    from traceforge.trace import Message, ToolCall
+
+    out = []
+    for d in msgs:
+        if not isinstance(d, dict) or "role" not in d:
+            return None
+        m = {
+            "role": d["role"],
+            "content": d.get("content"),
+            "reasoning": d.get("reasoning"),
+            "tool_call_id": d.get("tool_call_id"),
+            "tool_name": d.get("tool_name"),
+        }
+        m = {k: v for k, v in m.items() if v is not None}
+        if "tool_calls" in d and isinstance(d["tool_calls"], list):
+            m["tool_calls"] = [
+                {
+                    "id": str(tc.get("id", "")),
+                    "name": str(tc.get("name", "")),
+                    "arguments": tc.get("arguments") or "{}",
+                }
+                for tc in d["tool_calls"]
+                if isinstance(tc, dict)
+            ]
+        out.append(Message.from_dict(m))
+    return Trace(
+        session_id="improved-placeholder",  # set by caller
+        messages=out,
+        improved=True,
+    )
+
+
+def _append_status(cfg: Config, sid: str, status: dict) -> None:
+    """Append a stage-level status row to the manifest."""
+    import json as _json
+
+    os.makedirs(os.path.dirname(cfg.manifest_path), exist_ok=True)
+    row = {"session_id": sid, **status}
+    with open(cfg.manifest_path, "a", encoding="utf-8") as f:
+        f.write(_json.dumps(row, ensure_ascii=False) + "\n")
+
+
+def _load_gate_cache(workdir: str) -> dict:
+    """Read the workdir's gate-pass cache (digest -> list of gate rows).
+
+    Batches die at arbitrary points (turn interruptions, terminal close,
+    SIGTERM to the worker pool); without this, every verify/review round
+    already PAID FOR on an unchanged artifact is re-run from scratch on
+    the next resume. The cache is keyed by the artifact's content digest
+    so a rewritten (different) artifact never inherits stale passes.
+    Cached passes from an OLDER standards version are discarded — judge
+    rules evolve, and a verdict recorded under old rules must not
+    replay against new ones.
+    """
+    path = os.path.join(workdir, GATE_CACHE_FILE)
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if not isinstance(data, dict):
+            return {}
+        if data.get("standards") != GATE_CACHE_STANDARDS:
+            return {}
+        return data
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _save_gate_cache(workdir: str, cache: dict) -> None:
+    """Persist the gate-pass cache atomically (workdir, per trace)."""
+    path = os.path.join(workdir, GATE_CACHE_FILE)
+    tmp = path + ".tmp"
+    cache = dict(cache)
+    cache["standards"] = GATE_CACHE_STANDARDS
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(cache, f, ensure_ascii=False)
+    os.replace(tmp, path)
+
+
+def _cache_gate_pass(cache: dict, digest: str, stage: str, round_no: int) -> None:
+    """Record a gate PASS for one artifact digest."""
+    rows = cache.setdefault(digest, [])
+    key = f"{stage}:{round_no}"
+    if key not in rows:
+        rows.append(key)
+
+
+def _acquire_workdir_lock(workdir: str) -> bool:
+    """O_EXCL pid lockfile; locks left by dead processes are stolen.
+
+    Two concurrent improve batches working the same sid corrupt each
+    other (shared improved.json / verdict.json — the verifier unlinks its
+    verdict file before each run) and burn double model time. The lock
+    makes one-improver-per-workdir structural, not a user discipline.
+    """
+    lock_path = os.path.join(workdir, ".lock")
+    my_pid = str(os.getpid())
+    for _ in range(3):
+        try:
+            fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            try:
+                os.write(fd, my_pid.encode())
+            finally:
+                os.close(fd)
+            return True
+        except FileExistsError:
+            try:
+                other = open(lock_path, encoding="utf-8").read().strip()
+            except OSError:
+                continue
+            pid = int(other) if other.isdigit() else -1
+            alive = False
+            if pid > 0:
+                try:
+                    os.kill(pid, 0)
+                    alive = True
+                except ProcessLookupError:
+                    alive = False
+                except PermissionError:
+                    alive = True  # exists, not ours: assume alive
+                except OverflowError:
+                    alive = False
+                except OSError:
+                    # Windows raises WinError 87 ("Falscher Parameter") for a
+                    # pid that does not exist instead of ProcessLookupError,
+                    # so an uncaught OSError here crashed the stale-lock
+                    # steal and left the lock in place forever. Any other
+                    # OSError means we cannot prove the owner is alive, and
+                    # stealing a stale lock is the safe direction: the work
+                    # is resumable, a permanently stuck lock is not.
+                    alive = False
+            if alive:
+                return False
+            try:
+                os.unlink(lock_path)  # stale lock from a dead run: steal
+            except OSError:
+                pass
+    return False
+
+
+def _release_workdir_lock(workdir: str) -> None:
+    """Drop our own lock (never another live run's).
+
+    The handle must be CLOSED before the unlink: Windows refuses to delete a
+    file that is still open, so the old `with open(...): os.unlink(...)` form
+    raised PermissionError, was swallowed by `except OSError`, and left every
+    workdir holding a dead-pid lock forever. POSIX allows unlinking an open
+    file, which is why this only ever showed up on Windows.
+    """
+    lock_path = os.path.join(workdir, ".lock")
+    try:
+        with open(lock_path, encoding="utf-8") as f:
+            owner = f.read().strip()
+    except OSError:
+        return
+    if owner != str(os.getpid()):
+        return
+    try:
+        os.unlink(lock_path)
+    except OSError:
+        pass
+
+
+def _write_outputs_index(
+    cfg: Config, trace: Trace, workdir: str, max_chars: int = 250_000
+) -> str:
+    """Full real tool outputs as outputs.jsonl, keyed by rendering index.
+
+    The compact rendering clips each tool result to a short head; P4
+    demands verbatim reuse, so the improver needs the unclipped text.
+    One JSON object per line: {"i": N, "tool", "args", "output"} where N
+    is the same [N] message index the rendering shows — the improver can
+    correlate a clipped result in its prompt with the full text here.
+
+    max_chars is a byte-blow safety valve (measured corpus max real
+    output: ~111KB), NOT a compression budget: the 20k cap this used to
+    apply hid exactly the mid-tail evidence (p95 = 20k) that P4 demands
+    the improver quote — on exactly the big traces where review kills
+    artifacts — forcing composed pseudo-outputs. Outputs beyond the
+    safety valve carry an honest total-marker, never a fake count.
+    """
+    path = os.path.join(workdir, "outputs.jsonl")
+    arg_of: dict[str, str] = {}
+    for m in trace.messages:
+        for tc in m.tool_calls:
+            arg_of[tc.id] = tc.arguments or "{}"
+    with open(path, "w", encoding="utf-8") as f:
+        for i, m in enumerate(trace.messages, 1):
+            if m.role != "tool" or not m.content:
+                continue
+            out = m.content
+            if len(out) > max_chars:
+                out = out[:max_chars] + f" …[+{len(out) - max_chars} chars total]"
+            f.write(json.dumps({
+                "i": i,
+                "tool": m.tool_name or "?",
+                "args": arg_of.get(m.tool_call_id or "", "")[:400],
+                "output": out,
+            }, ensure_ascii=False) + "\n")
+    return path
+
+
+def _generate_single(cfg, trace, rendered, workdir, output_path, errors, prev_path, sid):
+    """One single-shot improver invocation. Returns (candidate, reply, hsid, code, stderr) or raises Timeout."""
+    from traceforge.classify import detect_language
+    prompt = build_prompt(
+        rendered_trace=rendered,
+        guidelines_path=cfg.guidelines_path,
+        output_path=output_path,
+        outputs_path=os.path.join(workdir, "outputs.jsonl"),
+        errors=errors,
+        prev_path=prev_path,
+        language=detect_language(trace.first_task_message() or ""),
+    )
+    prompt_path = write_prompt_file(cfg.prompts_dir, sid, prompt)
+    try:
+        code, stdout, hsid, stderr = _run_hermes(cfg, prompt_path, workdir)
+    except subprocess.TimeoutExpired as e:
+        raise e
+    reply = (stdout or "").strip()
+    return _parse_improved(output_path), reply, hsid, code, stderr
+
+
+def improve_trace(
+    cfg: Config,
+    trace: Trace,
+    *,
+    max_attempts: int = 2,
+    validator=None,
+    status_cb=None,
+) -> ImproverResult:
+    """Run the agentic improver on one trace, with a validation repair loop.
+
+    Long traces (rendered size > cfg.chunk_max_chars) go through the staged
+    map-digest-write pipeline instead of the single shot. Every admitted
+    trace passes: N independent verification rounds (web fact-check) and
+    M independent review rounds (quality-pillar review) — all must PASS.
+
+    ``status_cb`` (optional) receives short human stage strings
+    ("improving", "digest", "verify 1/2", ...) for live progress display.
+    """
+    from traceforge.trace import Trace as _T
+    from traceforge.validate import validate_structural
+    from traceforge.grounding import validate_grounding
+    from traceforge.improver.verify import run_verifier
+    from traceforge.improver.review import run_review
+
+    def _status(s: str) -> None:
+        if status_cb is not None:
+            status_cb(s)
+
+    started = time.time()
+    sid = trace.session_id
+    workdir = os.path.join(cfg.improver_workdir, sid)
+    os.makedirs(workdir, exist_ok=True)
+    # One improver per workdir, structurally: concurrent batches on the
+    # same sid race on improved.json/verdict.json and pay the model twice.
+    if not _acquire_workdir_lock(workdir):
+        return ImproverResult(
+            session_id=sid, ok=False, improved=None, reply="",
+            hermes_session_id=None,
+            errors=["workdir locked by a live improver run — skipping"],
+            attempts=0, duration_s=0.0,
+        )
+    try:
+        return _improve_locked(cfg, trace, max_attempts, status_cb)
+    finally:
+        _release_workdir_lock(workdir)
+
+
+def _improve_locked(
+    cfg: Config, trace: Trace, max_attempts: int, status_cb
+) -> ImproverResult:
+    from traceforge.trace import Trace as _T
+    from traceforge.validate import validate_structural
+    from traceforge.grounding import validate_grounding
+    from traceforge.improver.verify import run_verifier
+    from traceforge.improver.review import run_review
+
+    def _status(s: str) -> None:
+        if status_cb is not None:
+            status_cb(s)
+
+    started = time.time()
+    sid = trace.session_id
+    workdir = os.path.join(cfg.improver_workdir, sid)
+    rendered = trace.render_compact(
+        user_chars=cfg.user_chars,
+        assistant_chars=cfg.assistant_chars,
+        tool_result_chars=cfg.tool_result_chars,
+        tool_args_chars=cfg.tool_args_chars,
+        include_reasoning=cfg.include_reasoning,
+    )
+    output_path = os.path.join(workdir, "improved.json")
+    # Full unclipped tool outputs on disk: P4's verbatim-reuse rule is
+    # only satisfiable when the improver can actually see the full text.
+    outputs_path = _write_outputs_index(cfg, trace, workdir)
+
+    errors: list[str] = []
+    prev_path: Optional[str] = None
+    attempts = 0
+    improved: Optional[Trace] = None
+    reply = ""
+    hermes_session_id: Optional[str] = None
+    # long-trace attempts don't run hermes chat directly (stages do); the
+    # loop below must not touch single-shot navigation vars on that path
+    code = 0
+    stderr = ""
+
+    for attempt in range(1, max_attempts + 1):
+        attempts = attempt
+        candidate = None
+        # Fast-path: when a previous run already left an artifact in this
+        # workdir, re-adjudicate it first (regate). Only pay the model for
+        # a fresh write when nothing usable exists on disk. This makes
+        # "rerun after a gate change" nearly free instead of a full
+        # re-write of every trace.
+        if attempt == 1 and os.path.exists(output_path):
+            _status("regate")
+            candidate = _parse_improved(output_path)
+            # Static pre-flight: an artifact that still carries rendering
+            # clip markers is dead on arrival at review (reviewers kill
+            # invented counts; grounding silently strips them). Fail it
+            # here — one static check instead of 4 deep-thinker
+            # sessions re-discovering it.
+            if candidate is not None and _clip_markers_present(candidate):
+                candidate = None
+                errors = [CLIP_MARKER_ERROR]
+                # keep the failed artifact as the repair reference: the
+                # next attempt must FIX it (REPAIR_HEADER + errors), not
+                # blind-rewrite from a fresh TASK_HEADER that would
+                # silently drop the specific clip-marker error.
+                prev_path = output_path
+        if candidate is not None:
+            reply = "REGATE (existing artifact)"
+            code = 0
+            stderr = ""
+        elif len(rendered) <= cfg.chunk_max_chars:
+            _status("improving" if attempt == 1 else f"repair {attempt}")
+            try:
+                candidate, reply_one, hsid, code, stderr = _generate_single(
+                    cfg, trace, rendered, workdir, output_path, errors,
+                    prev_path, sid,
+                )
+            except subprocess.TimeoutExpired:
+                errors = [f"harness timeout after {cfg.harness_timeout_s}s"]
+                continue
+            reply = reply_one
+            hermes_session_id = hsid
+            if reply.startswith("REJECTED"):
+                errors = [f"rejected by improver: {reply[:300]}"]
+                break
+        else:
+            # long-trace staged pipeline: digest -> map -> writer
+            from traceforge.improver import longtrace
+
+            chunk_dir = os.path.join(workdir, "chunks")
+            if prev_path is None:
+                _status("digest+map")
+                chunks = chunker.chunk_trace(
+                    trace,
+                    max_chars=cfg.chunk_max_chars,
+                    overlap_messages=cfg.chunk_overlap_messages,
+                    render_kwargs={
+                        "user_chars": cfg.user_chars,
+                        "assistant_chars": cfg.assistant_chars,
+                        "tool_result_chars": cfg.tool_result_chars,
+                        "tool_args_chars": cfg.tool_args_chars,
+                        "include_reasoning": cfg.include_reasoning,
+                    },
+                )
+                if not chunks:
+                    errors = ["chunking produced no chunks"]
+                    continue
+                longtrace.write_chunks(chunk_dir, chunks, trace)
+                _status(f"digest 0/{len(chunks)}")
+                digests, derrs = longtrace.digest_all(
+                    cfg, trace, chunks, workdir,
+                    progress_cb=lambda done, total: _status(
+                        f"digest {done}/{total}"
+                    ),
+                )
+                if derrs:
+                    errors = [f"digest failures: {derrs}"]
+                    continue
+                _status(f"map ({len(chunks)} chunks)")
+                map_d, merr = longtrace.build_map(cfg, trace, digests, workdir)
+                if map_d is None:
+                    errors = [f"map merge failed: {merr}"]
+                    continue
+                _append_status(cfg, sid, {
+                    "stage": "map", "chunks": len(chunks),
+                    "approx_tokens": sum(c.approx_chars for c in chunks) // 4,
+                })
+            # writer (also used for repair attempts on long traces)
+            map_d = longtrace._json_file(os.path.join(workdir, "session_map.json"))
+            if map_d is None:
+                errors = ["session map missing after long-trace stage"]
+                continue
+            _status("writer")
+            candidate, werr = longtrace.run_writer(
+                cfg, trace, map_d, chunk_dir, workdir, output_path,
+                repair_errors=errors if prev_path else None,
+            )
+            if candidate is None:
+                errors = [f"long-trace writer failed: {werr}"]
+                continue
+            reply = "WRITER DONE"
+        # The artifact on disk is the source of truth — NOT the exit code.
+        # The improver may hit its turn cap after writing a perfectly valid
+        # file (e.g. right after a repair); validate what exists regardless.
+        candidate = _parse_improved(output_path)
+        if candidate is None:
+            if code != 0:
+                stderr_tail = f"; stderr: {stderr.strip()[-500:]}" if stderr else ""
+                errors = [
+                    f"hermes chat exited with code {code} and "
+                    f"improved.json missing/unparseable{stderr_tail}"
+                ]
+            else:
+                errors = [
+                    "improved.json missing, unparseable, or missing 'messages'"
+                ]
+            continue
+        # Static clip-marker gate on EVERY path, not just regate: writers
+        # and repairs can still copy markers out of the clipped rendering.
+        # A marker artifact is dead on arrival at review (and grounding
+        # silently forgives it) — fail fast here instead of burning
+        # verifier + reviewer sessions on it.
+        if _clip_markers_present(candidate):
+            errors = [f"clip-marker gate: {CLIP_MARKER_ERROR}"]
+            # repair must fix THIS artifact (REPAIR_HEADER + errors), not
+            # blind-rewrite from a TASK_HEADER that drops the specifics
+            prev_path = output_path
+            continue
+        prev_path = output_path
+        improved = candidate
+        # Pipeline framing markers ("[trace segment k of n]", "[subagent
+        # brief — role: ...]") belong to the improver's INPUT; strip them
+        # before the gates so the echo check compares against the real task
+        # and the promoted artifact carries no scaffolding.
+        from traceforge.validate import strip_scaffold_markers
+        if strip_scaffold_markers(improved):
+            improved.save(output_path)
+        from traceforge.validate import strip_harness_citation
+        if strip_harness_citation(improved):
+            improved.save(output_path)
+        # Narration rows ("Writing the report.") are filler the trainee must
+        # never learn; drop them before the gates so the echo/grounding
+        # checks see the real turn sequence.
+        if _drop_narration_rows(improved):
+            improved.save(output_path)
+        # A vendor co-author trailer in the source's commit args is an
+        # identity burn the gate rejects; strip it before the gates so the
+        # repair round is not spent reproducing it.
+        if _strip_identity_trailers_trace(improved):
+            improved.save(output_path)
+        errs = validate_structural(improved)
+        if errs and any(_EMPTY_ROW_RE in e for e in errs):
+            # blank assistant rows are pure noise — drop them and re-check
+            # rather than paying a full rewrite to remove one empty row.
+            # Runs even when other errors are present: a trace with a blank
+            # row AND a tool tail must get both fixes, not neither.
+            if _drop_empty_assistant_rows(improved):
+                improved.save(output_path)  # repair must start from the fix
+                errs = validate_structural(improved)
+                if not errs:
+                    _status("dropped empty assistant rows")
+        if _only_tool_tail(errs):
+            # writer stopped mid-call: one row short of valid. Synthesize
+            # the closing answer instead of paying a full repair round
+            # that reproduces the same cut (measured: 49/1535 traces).
+            fixed = _append_synth_final(cfg, improved, trace)
+            if fixed is not None:
+                improved = fixed
+                # persist BEFORE re-validating: a later repair round reads
+                # prev_path from disk, so an in-memory-only fix is thrown
+                # away and the writer reproduces the same tool tail.
+                improved.save(output_path)
+                errs = validate_structural(improved)
+                if not errs:
+                    _status("final answer (tool-tail synth)")
+        if not errs:
+            errs = validate_grounding(improved, trace)
+        if not errs and (cfg.verify or cfg.review):
+            # Gate-pass cache: rounds that already PASSED for THIS exact
+            # artifact content are replayed instead of re-paid. Survives
+            # batch interruptions (turn cap, SIGTERM, terminal close); a
+            # rewritten artifact has a different digest and re-runs all
+            # rounds fresh.
+            digest = _artifact_digest(improved)
+            gate_cache = _load_gate_cache(workdir)
+            gate_pass_keys = set(gate_cache.get(digest, []))
+
+            def _gate_pass(stage: str, round_no: int) -> None:
+                _cache_gate_pass(gate_cache, digest, stage, round_no)
+                _save_gate_cache(workdir, gate_cache)
+
+            verify_failures: list[str] = []
+            # ---- N independent verification rounds (web fact-check)
+            # Strict admission: every round must end PASS. A transient ERROR
+            # (timeout, unparseable verdict) gets ONE in-place retry; a
+            # second ERROR surfaces as an error row — never silent
+            # under-verification, never a model repair for infra issues.
+            if cfg.verify:
+                passes = 0
+                vr = 1
+                while vr <= cfg.verify_rounds:
+                    if f"verify:{vr}" in gate_pass_keys:
+                        passes += 1  # already adjudicated on identical bytes
+                        _status(f"verify {vr}/{cfg.verify_rounds} (cached)")
+                        _append_status(cfg, sid, {
+                            "stage": "verify", "round": vr,
+                            "verdict": "PASS", "cached": True,
+                        })
+                        vr += 1
+                        continue
+                    _status(f"verify {vr}/{cfg.verify_rounds}")
+                    vres = run_verifier(cfg, output_path, workdir)
+                    if vres.verdict == "PASS":
+                        passes += 1
+                        _gate_pass("verify", vr)
+                        _append_status(cfg, sid, {
+                            "stage": "verify", "round": vr,
+                            "verdict": "PASS",
+                            "claims_checked": vres.claims_checked,
+                        })
+                        vr += 1
+                        continue
+                    if vres.verdict == "FAIL":
+                        claims = "\n".join(
+                            f'- "{u.get("claim", "?")}" — {u.get("why", "?")}'
+                            for u in vres.unsupported[:10]
+                        )
+                        verify_failures.append(
+                            f"[verify r{vr}] external claims unsupported:\n{claims}"
+                        )
+                        _append_status(cfg, sid, {
+                            "stage": "verify", "round": vr, "verdict": "FAIL",
+                            "claims_checked": vres.claims_checked,
+                        })
+                        break  # concrete FAIL: repair next attempt
+                    # transient ERROR: one in-place retry of the same round
+                    retry = run_verifier(cfg, output_path, workdir)
+                    if retry.verdict == "PASS":
+                        passes += 1
+                        _gate_pass("verify", vr)
+                        _append_status(cfg, sid, {
+                            "stage": "verify", "round": vr,
+                            "verdict": "PASS", "retried": True,
+                            "claims_checked": retry.claims_checked,
+                        })
+                        vr += 1
+                        continue
+                    if retry.verdict == "FAIL":
+                        claims = "\n".join(
+                            f'- "{u.get("claim", "?")}" — {u.get("why", "?")}'
+                            for u in retry.unsupported[:10]
+                        )
+                        verify_failures.append(
+                            f"[verify r{vr}] external claims unsupported:\n{claims}"
+                        )
+                        _append_status(cfg, sid, {
+                            "stage": "verify", "round": vr, "verdict": "FAIL",
+                            "retried": True,
+                            "claims_checked": retry.claims_checked,
+                        })
+                        break
+                    verify_failures.append(
+                        f"[verify r{vr}] infra error x2: "
+                        f"{vres.error or 'verifier error'} / "
+                        f"{retry.error or 'verifier error'}"
+                    )
+                    _append_status(cfg, sid, {
+                        "stage": "verify", "round": vr, "verdict": "ERROR",
+                        "error": (
+                            f"{vres.error or 'verifier error'} / "
+                            f"{retry.error or 'verifier error'}"
+                        )[:300],
+                    })
+                    break
+            # ---- M independent review rounds (quality pillars)
+            review_failures: list[str] = []
+            task_snip = trace.first_task_message() or "(no user message)"
+            if not verify_failures and cfg.review:
+                for rr in range(1, cfg.review_rounds + 1):
+                    if f"review:{rr}" in gate_pass_keys:
+                        _status(f"review {rr}/{cfg.review_rounds} (cached)")
+                        _append_status(cfg, sid, {
+                            "stage": "review", "round": rr, "verdict": "PASS",
+                            "cached": True,
+                        })
+                        continue
+                    _status(f"review {rr}/{cfg.review_rounds}")
+                    rres = run_review(
+                        cfg, output_path, task_snip, workdir, rr
+                    )
+                    if not rres.ok() and rres.verdict == "ERROR":
+                        rres = run_review(
+                            cfg, output_path, task_snip, workdir, rr
+                        )  # one in-place retry on transient infra error
+                    if rres.ok():
+                        _gate_pass("review", rr)
+                        _append_status(cfg, sid, {
+                            "stage": "review", "round": rr, "verdict": "PASS",
+                        })
+                        continue
+                    if rres.verdict == "FAIL":
+                        review_failures.append(
+                            "[review r%d] pillar violations:\n%s"
+                            % (rr, "\n".join(rres.violations[:10]))
+                        )
+                        _append_status(cfg, sid, {
+                            "stage": "review", "round": rr, "verdict": "FAIL",
+                        })
+                        break  # concrete FAIL: repair next attempt
+                    review_failures.append(
+                        f"[review r{rr}] infra error x2: {rres.error or 'review error'}"
+                    )
+                    _append_status(cfg, sid, {
+                        "stage": "review", "round": rr, "verdict": "ERROR",
+                        "error": (rres.error or "review error")[:300],
+                    })
+                    break
+            errs = verify_failures + review_failures
+        if errs:
+            # Infra failures (verifier/reviewer down) are NOT content errors:
+            # a model repair cannot fix them. Fail fast without re-running
+            # the improver so no model time is wasted on infrastructure.
+            if any("infra error x2" in e for e in errs):
+                return ImproverResult(
+                    session_id=sid, ok=False, improved=None, reply=reply,
+                    hermes_session_id=hermes_session_id,
+                    errors=errs, attempts=attempts,
+                    duration_s=time.time() - started,
+                )
+            errors = errs + (
+                [f"note: hermes exit code {code}"] if code != 0 else []
+            )
+            continue
+        improved.session_id = f"ideal-{sid}"
+        improved.parent_session_id = sid
+        # cfg.model None = default profile; the exact model is recoverable
+        # from hermes_session_id (recorded in the manifest).
+        improved.model = cfg.model or "hermes-default"
+        improved.source = "hermes-one-shot"
+        # Dead-end distillation (see traceforge/distill.py): the ideal path
+        # routes around the failed calls, so the negative knowledge would be
+        # lost. Compress it into the final answer's reasoning channel. Runs
+        # after every gate so a rejected block can never cost the trace.
+        try:
+            from traceforge.distill import distill_into_reasoning
+            from traceforge.splice import _resolve_endpoint
+            base, key = _resolve_endpoint(cfg)
+            block, note = distill_into_reasoning(
+                cfg, trace, improved, trace.first_task_message() or "",
+                base, key)
+            _append_status(cfg, sid, {
+                "stage": "distill", "ok": block is not None,
+                "note": note[:300]})
+        except Exception as e:  # never lose a promotable trace
+            _append_status(cfg, sid, {
+                "stage": "distill", "ok": False,
+                "note": f"{type(e).__name__}: {e}"[:300]})
+        return ImproverResult(
+            session_id=sid, ok=True, improved=improved, reply=reply,
+            hermes_session_id=hermes_session_id, errors=[],
+            attempts=attempts, duration_s=time.time() - started,
+        )
+
+    return ImproverResult(
+        session_id=sid, ok=False, improved=None, reply=reply,
+        hermes_session_id=hermes_session_id, errors=errors,
+        attempts=attempts, duration_s=time.time() - started,
+    )
+
+
+def cleanup_workdir(cfg: Config, sid: str, keep: bool = False) -> None:
+    wd = os.path.join(cfg.improver_workdir, sid)
+    if not keep and os.path.isdir(wd):
         shutil.rmtree(wd, ignore_errors=True)

traceforge/live.py

@@ -199,7 +199,11 @@ class LiveStats:
         delta_out = 0
         models: dict = {}
         for (sess, cwd, tin, tout, msgs, api, running, model) in rows:
-            key = (cwd or "").rstrip("/").rsplit("/", 1)[-1]
+            # The per-trace key is the workspace directory name. Splitting on
+            # "/" alone leaves the whole path on Windows (cwd uses "\"), so
+            # every per_trace() lookup missed and the sublines showed
+            # "telemetry pending" forever.
+            key = os.path.basename((cwd or "").replace("\\", "/").rstrip("/"))
             d = per.setdefault(key, {
                 "in": 0, "out": 0, "msgs": 0, "api": 0,
                 "runs": 0, "running": 0, "rate": 0.0, "models": set(),

traceforge/net.py

@@ -0,0 +1,72 @@
+"""Transient-failure policy for the pipeline's HTTP calls.
+
+The writer endpoint answers 503 while a model is loading or its queue is
+saturated, and drops connections (WinError 10054) under load. Both call
+sites used to treat EVERY HTTPError as "unknown request field" and switch
+to the next request variant, so a 503 burned all three variants in a few
+milliseconds and the trace failed with `rewrite windows failed: window
+N-M: HTTP 503`.
+
+Measured 2026-10-29 on data/manifest.jsonl: 5146 of 9795 failed traces
+carried an HTTP 503 and 619 a connection reset — 59% of the failure
+population was a transient endpoint condition, and each one burned a full
+attempt plus a re-queue. A 503 is not a schema problem: retry the SAME
+variant after a backoff, and only fall through to the next variant on a
+4xx that actually names a bad field.
+
+The backoff is bounded by the caller's own call deadline, so a genuinely
+dead endpoint still fails fast instead of holding a worker.
+"""
+from __future__ import annotations
+
+import random
+import urllib.error
+from typing import Optional
+
+# 408 request timeout, 425 too early, 429 rate limited, 5xx server side.
+# 500/502/504 are included because a proxy in front of a loading model
+# answers them exactly like a 503.
+TRANSIENT_STATUS = frozenset({408, 425, 429, 500, 502, 503, 504})
+
+# Backoff shape: 2s, 4s, 8s, 16s (capped), plus up to 25% jitter so eight
+# workers that hit the same 503 do not retry in lockstep.
+BASE_DELAY_S = 2.0
+MAX_DELAY_S = 20.0
+
+
+def is_transient_status(code: Optional[int]) -> bool:
+    return code in TRANSIENT_STATUS
+
+
+def is_transient_error(exc: BaseException) -> bool:
+    """True when retrying the same request could plausibly succeed."""
+    if isinstance(exc, urllib.error.HTTPError):
+        return is_transient_status(getattr(exc, "code", None))
+    return isinstance(exc, (urllib.error.URLError, TimeoutError, OSError))
+
+
+def retry_after_s(exc: BaseException) -> Optional[float]:
+    """The server's own Retry-After, when it sent a usable one."""
+    headers = getattr(exc, "headers", None)
+    if headers is None:
+        return None
+    try:
+        raw = headers.get("Retry-After")
+    except Exception:
+        return None
+    if not raw:
+        return None
+    try:
+        return max(0.0, float(str(raw).strip()))
+    except (TypeError, ValueError):
+        return None
+
+
+def backoff_s(attempt: int, exc: Optional[BaseException] = None) -> float:
+    """Seconds to wait before retry number `attempt` (0-based)."""
+    if exc is not None:
+        hinted = retry_after_s(exc)
+        if hinted is not None:
+            return min(hinted, MAX_DELAY_S)
+    delay = min(BASE_DELAY_S * (2 ** max(attempt, 0)), MAX_DELAY_S)
+    return delay * (1.0 + random.random() * 0.25)

traceforge/space/app.py

@@ -1,499 +1,501 @@
-"""Gradio app: submit a trace, sponsor a dataset, read the dashboard.
-
-The UI is deliberately thin — every decision lives in `SpacePipeline` and
-`TraceStore`, so the same code runs locally (`python app.py`) and on a
-Hugging Face Space (`app.py` at the repo root).
-
-Tabs
-  Submit     one trace (JSON / JSONL / pasted) -> hash -> queue -> output
-  Sponsor    a JSONL of traces -> hashed, deduped, queued, attributed
-  Dashboard  public stats: corpus, time sensitivity, tasks, sponsors, queue
-  Browse     the stored outputs, by hash
-"""
-from __future__ import annotations
-
-import html
-import json
-import os
-from typing import Any, Optional
-
-from traceforge.space.hashing import short_hash
-from traceforge.space.ingest import parse_records, read_upload
-from traceforge.space.jobs import get_worker
-from traceforge.space.pipeline import SpacePipeline, pipeline_ready, space_config
-from traceforge.space.stats import bar_rows, dashboard, pct
-from traceforge.space.store import DONE, FAILED, QUEUED, RUNNING, TraceStore
-
-REFRESH_S = 8.0
-
-CSS = """
-.tf-wrap { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
-.tf-kpis { display:grid; grid-template-columns:repeat(auto-fit,minmax(130px,1fr));
-           gap:8px; margin:6px 0 14px; }
-.tf-kpi { background:#161b22; border:1px solid #2a3140; border-radius:8px;
-          padding:9px 11px; }
-.tf-kpi .v { font-size:21px; font-weight:600; color:#e6edf3; line-height:1.2; }
-.tf-kpi .k { font-size:11px; color:#8b949e; text-transform:uppercase;
-             letter-spacing:.04em; }
-.tf-kpi .s { font-size:11px; color:#6e7681; }
-.tf-ok { color:#3fb950; } .tf-warn { color:#d29922; } .tf-bad { color:#f85149; }
-.tf-bar-row { display:grid; grid-template-columns:190px 1fr 64px; gap:8px;
-              align-items:center; font-size:12px; color:#9aa4b2; margin:3px 0; }
-.tf-bar-outer { background:#1b2029; border-radius:6px; height:14px;
-                overflow:hidden; border:1px solid #2a3140; }
-.tf-bar-inner { height:100%; background:linear-gradient(90deg,#2f81f7,#3fb950); }
-.tf-head { font-size:13px; color:#8b949e; margin:2px 0 8px; }
-.tf-pill { padding:2px 8px; border-radius:999px; font-size:11px;
-           border:1px solid #2a3140; }
-"""
-
-
-# --------------------------------------------------------------------- html
-
-def _esc(s: Any) -> str:
-    return html.escape(str(s if s is not None else ""))
-
-
-def _kpi(value: Any, key: str, sub: str = "", cls: str = "") -> str:
-    sub_html = f'<div class="s">{_esc(sub)}</div>' if sub else ""
-    return (f'<div class="tf-kpi"><div class="v {cls}">{_esc(value)}</div>'
-            f'<div class="k">{_esc(key)}</div>{sub_html}</div>')
-
-
-def _bars(counts: dict, total: Optional[int] = None) -> str:
-    rows = bar_rows(counts, total=total)
-    if not rows:
-        return '<div class="tf-head">no data yet</div>'
-    out = ['<div class="tf-wrap">']
-    for label, n, p in rows:
-        out.append(
-            '<div class="tf-bar-row">'
-            f'<span>{_esc(label)}</span>'
-            f'<span class="tf-bar-outer"><span class="tf-bar-inner" '
-            f'style="width:{max(0.0, min(100.0, p)):.1f}%"></span></span>'
-            f'<span>{n} · {p:.0f}%</span></div>'
-        )
-    out.append("</div>")
-    return "".join(out)
-
-
-def _status_pill(status: str, no_change: bool = False) -> str:
-    if no_change:
-        return '<span class="tf-pill tf-warn">no change</span>'
-    cls = {DONE: "tf-ok", FAILED: "tf-bad", RUNNING: "tf-warn",
-           QUEUED: "tf-warn"}.get(status, "")
-    return f'<span class="tf-pill {cls}">{_esc(status)}</span>'
-
-
-def _kpi_html(space: dict, ref: dict, worker: dict, ready: tuple[bool, str]) -> str:
-    ok, reason = ready
-    cards = [
-        _kpi(f"{space['seeds']:,}", "seeds", "distinct content hashes"),
-        _kpi(f"{space['done']:,}", "outputs",
-             f"{pct(space['done'], space['seeds']):.0f}% of seeds"),
-        _kpi(f"{space['queued']:,}", "queued",
-             f"{space['running']} running"),
-        _kpi(f"{space['failed']:,}", "failed", "errored or rejected"),
-        _kpi(f"{space.get('no_change', 0):,}", "no change",
-             "seed already ideal"),
-        _kpi(f"{len(space['sponsors'])}", "sponsors",
-             f"{sum(s['seeds'] for s in space['sponsors'])} seeds"),
-        _kpi(f"{space['duration_s']['median']:.0f}s", "median runtime",
-             f"p90 {space['duration_s']['p90']:.0f}s"),
-    ]
-    if ref.get("available"):
-        cards.append(_kpi(f"{ref.get('traces', 0):,}", "reference corpus",
-                          "published ideal traces"))
-    head = (
-        '<div class="tf-wrap"><div class="tf-head">'
-        f'<span class="tf-pill {"tf-ok" if ok else "tf-bad"}">'
-        f'{"pipeline ready" if ok else "pipeline not configured"}</span> '
-        f'{_esc(reason)} · worker {"alive" if worker.get("alive") else "stopped"}'
-        f' · queue {worker.get("queued", 0)}'
-        "</div></div>"
-    )
-    return head + '<div class="tf-wrap"><div class="tf-kpis">' + "".join(cards) + "</div></div>"
-
-
-def _ts_html(space: dict, ref: dict) -> str:
-    """Time sensitivity: the metric that says whether an answer decays."""
-    parts = ['<div class="tf-wrap"><div class="tf-head">'
-             "time sensitivity — a temporal fact answered from weights decays; "
-             "the same fact fetched with a tool does not</div>"]
-    space_ts = space.get("time_sensitivity") or {}
-    if space_ts:
-        parts.append("<b>this Space</b>")
-        parts.append(_bars(space_ts))
-    census = (ref or {}).get("time_sensitivity") or {}
-    if census.get("available"):
-        parts.append(f"<b>reference corpus</b> ({census.get('total', 0):,} traces)")
-        parts.append(_bars(census.get("classes") or {}))
-        parts.append(
-            f'<div class="tf-head">needs rewrite (tool available but never '
-            f'called): {census.get("needs_rewrite", 0):,}</div>')
-    if not space_ts and not census.get("available"):
-        parts.append('<div class="tf-head">no data yet</div>')
-    parts.append("</div>")
-    return "".join(parts)
-
-
-# ------------------------------------------------------------------- tables
-
-def _rows(records: list[dict], cols: list[str]) -> list[list]:
-    out = []
-    for r in records:
-        row = []
-        for c in cols:
-            v = r.get(c)
-            if c == "hash":
-                v = short_hash(v or "")
-            elif c == "time_sensitivity":
-                v = (v or {}).get("class", "")
-            elif isinstance(v, float):
-                v = round(v, 1)
-            row.append(v if v is not None else "")
-        out.append(row)
-    return out
-
-
-# ---------------------------------------------------------------------- app
-
-def build_app(store: Optional[TraceStore] = None,
-              pipeline: Optional[SpacePipeline] = None):
-    import gradio as gr
-
-    cfg = pipeline.cfg if pipeline else space_config()
-    store = store or (pipeline.store if pipeline else TraceStore(
-        os.path.join(cfg.data_dir)))
-    pipeline = pipeline or SpacePipeline(store, cfg)
-    worker = get_worker(pipeline)
-    ready = pipeline_ready(cfg)
-    dataset_dir = os.path.join(os.path.dirname(cfg.data_dir), "dataset")
-    cache_path = os.path.join(store.root, "reference_census.json")
-
-    # ------------------------------------------------------------- submit
-
-    def on_submit(file_path, pasted, sponsor, sync):
-        if not ready:
-            return (f"**pipeline not configured** — {ready[1]}. Nothing was "
-                    "queued.", None, None)
-        if file_path:
-            records, errors = read_upload(file_path)
-        else:
-            records, errors = parse_records(pasted or "")
-        if errors:
-            return (f"**parse errors**\n\n" + "\n".join(f"- {e}" for e in errors[:10]),
-                    None, None)
-        if not records:
-            return "**nothing to submit** — upload a file or paste JSON", None, None
-        if len(records) > 1:
-            return (f"**{len(records)} records** — the Submit tab takes one trace. "
-                    "Use **Sponsor a dataset** for a batch.", None, None)
-        try:
-            res = pipeline.submit(records[0], sponsor=sponsor)
-        except Exception as e:
-            return f"**submit failed**: {e}", None, None
-        h = res["hash"]
-        if res.get("duplicate") and res.get("status") == DONE:
-            path = store.output_path(h)
-            return (f"**already processed** — this seed hash already has an output.\n\n"
-                    f"`{h}`\n\nNo second output was created.", h,
-                    path if os.path.exists(path) else None)
-        if sync:
-            res = pipeline.process(h)
-        rec = pipeline.result(h)
-        md = _result_md(rec)
-        path = store.output_path(h) if rec.get("status") == DONE else None
-        return md, h, path if path and os.path.exists(path) else None
-
-    def on_check(h):
-        if not h:
-            return "no hash yet — submit a trace first", None
-        rec = pipeline.result(h)
-        path = store.output_path(h) if rec.get("status") == DONE else None
-        return _result_md(rec), path if path and os.path.exists(path) else None
-
-    def on_health():
-        from traceforge.space.local_llm import health
-        return health()
-
-    def on_probe():
-        from traceforge.space.local_llm import probe
-        r = probe()
-        if r.get("ok"):
-            return f"**local model answered:** `{r['text']}`"
-        return f"**local model failed:** `{r['error']}`"
-
-    def on_debug():
-        from traceforge.triage import _PARSE_DEBUG, _TRIAGE_DEBUG
-        return {"triage": list(_TRIAGE_DEBUG), "parse": list(_PARSE_DEBUG)}
-
-    def _result_md(rec: dict) -> str:
-        h = rec.get("hash") or ""
-        st = rec.get("status") or "unknown"
-        lines = [f"### {_status_pill(st, bool(rec.get('no_change')))} `{h}`", ""]
-        if rec.get("duplicate"):
-            lines.append("_duplicate submission — the existing record was returned_")
-            lines.append("")
-        if rec.get("task"):
-            lines.append(f"- task: **{rec['task']}** · language: **{rec.get('language', '?')}**")
-        if rec.get("n_messages"):
-            lines.append(f"- seed: {rec['n_messages']} messages · "
-                         f"{rec.get('n_tool_calls', 0)} tool calls")
-        if rec.get("n_messages_out"):
-            lines.append(f"- output: {rec['n_messages_out']} messages")
-        if rec.get("route"):
-            lines.append(f"- route: `{rec['route']}` · attempts: {rec.get('attempts', 0)}")
-        if rec.get("endpoint"):
-            lines.append(f"- endpoint: `{rec['endpoint']}`")
-        if rec.get("duration_s"):
-            lines.append(f"- runtime: {rec['duration_s']:.0f}s")
-        ts = rec.get("time_sensitivity") or {}
-        if ts.get("class"):
-            lines.append(f"- time sensitivity: **{ts['class']}** — {ts.get('label', '')}")
-            if ts.get("temporal_facts"):
-                lines.append(f"  - temporal facts: {', '.join(ts['temporal_facts'])}")
-            if ts.get("retrieval_available"):
-                lines.append(f"  - retrieval available: {', '.join(ts['retrieval_available'])}")
-            if ts.get("needs_rewrite"):
-                lines.append("  - the raw trace answered from weights although a "
-                             "retrieval tool was available")
-        ts2 = rec.get("time_sensitivity_improved") or {}
-        if ts2.get("class") and ts2.get("class") != ts.get("class"):
-            lines.append(f"- after rewrite: **{ts2['class']}**")
-        if rec.get("error"):
-            lines.append(f"- error: `{rec['error'][:600]}`")
-        if st == QUEUED:
-            lines.append("")
-            lines.append("_queued — the worker picks it up in submission order. "
-                         "Press **Check status** to refresh._")
-        return "\n".join(lines)
-
-    # ------------------------------------------------------------ sponsor
-
-    def on_sponsor(file_path, pasted, sponsor):
-        if not ready:
-            return (f"**pipeline not configured** — {ready[1]}. Nothing was "
-                    "queued.", [], "")
-        if file_path:
-            records, errors = read_upload(file_path)
-        else:
-            records, errors = parse_records(pasted or "")
-        if errors:
-            return (f"**parse errors**\n\n" + "\n".join(f"- {e}" for e in errors[:10]),
-                    [], "")
-        if not records:
-            return "**nothing to sponsor** — upload a JSONL of traces", [], ""
-        results = pipeline.submit_many(records, sponsor=sponsor)
-        new = sum(1 for r in results if not r.get("duplicate") and r.get("hash"))
-        dup = sum(1 for r in results if r.get("duplicate"))
-        err = sum(1 for r in results if not r.get("hash"))
-        rows = []
-        for r in results:
-            rows.append([
-                short_hash(r.get("hash") or ""),
-                r.get("status") or "error",
-                "duplicate" if r.get("duplicate") else ("new" if r.get("hash") else "error"),
-                r.get("n_messages", ""),
-                r.get("task", "")[:60] if r.get("task") else "",
-                (r.get("time_sensitivity") or {}).get("class", ""),
-                (r.get("error") or "")[:120],
-            ])
-        md = (f"**{len(records)} records** — {new} new, {dup} already known, "
-              f"{err} rejected. Sponsor: **{_esc(sponsor or 'anonymous')}**.\n\n"
-              "New seeds are queued; each one produces at most one output.")
-        return md, rows, sponsor or "anonymous"
-
-    # ---------------------------------------------------------- dashboard
-
-    def on_dashboard():
-        d = dashboard(store, dataset_dir=dataset_dir, cache_path=cache_path)
-        space, ref = d["space"], d["reference"]
-        w = worker.status()
-        kpis = _kpi_html(space, ref, w, ready)
-        ts = _ts_html(space, ref)
-        tasks = bar_rows(space.get("tasks") or {})
-        langs = bar_rows(space.get("languages") or {})
-        sponsors = [[s["sponsor"], s["seeds"], s["done"], s["failed"]]
-                    for s in space.get("sponsors") or []]
-        recent = _rows(d["recent"], ["hash", "status", "sponsor", "task",
-                                     "time_sensitivity", "duration_s"])
-        queue = _rows(d["queue"], ["hash", "sponsor", "task", "n_messages"])
-        ref_rows = []
-        if ref.get("available"):
-            card = ref.get("card") or {}
-            for k, v in (card.get("tasks") or {}).items():
-                ref_rows.append([k, v, pct(v, card.get("traces", 0))])
-        return kpis, ts, tasks, langs, sponsors, recent, queue, ref_rows
-
-    # ------------------------------------------------------------- browse
-
-    def browse_choices():
-        done = [r for r in store.all() if r.get("status") == DONE]
-        done.sort(key=lambda r: r.get("updated_at") or 0, reverse=True)
-        return gr.update(choices=[r["hash"] for r in done][:500])
-
-    def on_browse(h):
-        if not h:
-            return None, None
-        out = store.load_output(h)
-        if out is None:
-            return None, None
-        return out.to_dict(), store.output_path(h)
-
-    # ---------------------------------------------------------------- UI
-
-    with gr.Blocks(title="traceforge — ideal-world agent traces") as app:
-        gr.Markdown(
-            "# traceforge\n"
-            "Turn a real agent trace into its **ideal-world reference**: the same "
-            "work, with the dead ends removed, gated for structure and grounding.\n\n"
-            "Every seed is identified by a **content hash** — submitting the same "
-            "trace twice returns the existing output instead of creating a second one."
-        )
-
-        with gr.Tab("Submit a trace"):
-            with gr.Row():
-                with gr.Column(scale=3):
-                    file_in = gr.File(label="trace file (.json / .jsonl)",
-                                      file_types=[".json", ".jsonl"],
-                                      type="filepath")
-                    paste_in = gr.Textbox(
-                        label="…or paste a trace (JSON, JSONL, or a message list)",
-                        lines=10, placeholder='{"messages": [{"role": "user", ...}]}')
-                with gr.Column(scale=2):
-                    sponsor_in = gr.Textbox(label="your name / handle (optional)",
-                                            max_lines=1)
-                    sync_in = gr.Checkbox(
-                        label="process synchronously (debug — blocks until done)",
-                        value=os.environ.get("TRACEFORGE_SPACE_SYNC") == "1")
-                    btn_submit = gr.Button("Submit", variant="primary")
-                    btn_check = gr.Button("Check status")
-                    last_hash = gr.State("")
-            status_md = gr.Markdown("_no submission yet_")
-            out_file = gr.File(label="improved trace (download)", interactive=False)
-            with gr.Accordion("Local model (ZeroGPU)", open=False):
-                gr.Markdown(
-                    "With no remote endpoint configured, the Space runs "
-                    "`Qwen/Qwen2.5-3B-Instruct` on ZeroGPU. GPU time is charged "
-                    "to **your** HF daily quota, not to the Space owner. Local "
-                    "mode handles seeds up to 24 KB.")
-                btn_health = gr.Button("Check local model")
-                health_json = gr.JSON(label="local model status")
-                btn_probe = gr.Button("Test local model (loads it, ~60 s)")
-                probe_md = gr.Markdown()
-                btn_debug = gr.Button("Last triage replies")
-                debug_json = gr.JSON(label="triage debug")
-            btn_health.click(on_health, outputs=[health_json])
-            btn_probe.click(on_probe, outputs=[probe_md])
-            btn_debug.click(on_debug, outputs=[debug_json])
-
-            btn_submit.click(on_submit,
-                             inputs=[file_in, paste_in, sponsor_in, sync_in],
-                             outputs=[status_md, last_hash, out_file])
-            btn_check.click(on_check, inputs=[last_hash],
-                            outputs=[status_md, out_file])
-
-        with gr.Tab("Sponsor a dataset"):
-            gr.Markdown(
-                "Upload a JSONL of traces. Each row is hashed; **new** seeds are "
-                "queued for the pipeline and attributed to you, **known** seeds are "
-                "skipped. The processed rows join the public output dataset."
-            )
-            with gr.Row():
-                with gr.Column(scale=3):
-                    sp_file = gr.File(label="dataset (.jsonl)", file_types=[".jsonl"],
-                                      type="filepath")
-                    sp_paste = gr.Textbox(label="…or paste JSONL", lines=8)
-                with gr.Column(scale=2):
-                    sp_name = gr.Textbox(label="sponsor name", max_lines=1)
-                    sp_btn = gr.Button("Sponsor", variant="primary")
-            sp_md = gr.Markdown("_no dataset sponsored yet_")
-            sp_table = gr.Dataframe(
-                headers=["hash", "status", "new?", "messages", "task",
-                         "time sensitivity", "error"],
-                interactive=False, wrap=True, max_height=420,
-            )
-            sp_credit = gr.State("")
-            sp_btn.click(on_sponsor, inputs=[sp_file, sp_paste, sp_name],
-                         outputs=[sp_md, sp_table, sp_credit])
-
-        with gr.Tab("Dashboard"):
-            gr.Markdown("Public statistics. Refreshes automatically.")
-            dash_kpis = gr.HTML()
-            dash_ts = gr.HTML()
-            with gr.Row():
-                with gr.Column():
-                    gr.Markdown("### task mix (this Space)")
-                    dash_tasks = gr.Dataframe(
-                        headers=["task", "seeds", "pct"], interactive=False,
-                        wrap=True, max_height=300)
-                with gr.Column():
-                    gr.Markdown("### languages")
-                    dash_langs = gr.Dataframe(
-                        headers=["language", "seeds", "pct"], interactive=False,
-                        wrap=True, max_height=300)
-            with gr.Row():
-                with gr.Column():
-                    gr.Markdown("### sponsors")
-                    dash_sponsors = gr.Dataframe(
-                        headers=["sponsor", "seeds", "done", "failed"],
-                        interactive=False, wrap=True, max_height=300)
-                with gr.Column():
-                    gr.Markdown("### reference corpus — task mix")
-                    dash_ref = gr.Dataframe(
-                        headers=["task", "traces", "pct"], interactive=False,
-                        wrap=True, max_height=300)
-            gr.Markdown("### recent outputs")
-            dash_recent = gr.Dataframe(
-                headers=["hash", "status", "sponsor", "task",
-                         "time sensitivity", "runtime s"],
-                interactive=False, wrap=True, max_height=320)
-            gr.Markdown("### queue")
-            dash_queue = gr.Dataframe(
-                headers=["hash", "sponsor", "task", "messages"],
-                interactive=False, wrap=True, max_height=240)
-
-            dash_outputs = [dash_kpis, dash_ts, dash_tasks, dash_langs,
-                            dash_sponsors, dash_recent, dash_queue, dash_ref]
-            timer = gr.Timer(REFRESH_S)
-            timer.tick(on_dashboard, outputs=dash_outputs)
-            app.load(on_dashboard, outputs=dash_outputs)
-
-        with gr.Tab("Browse outputs"):
-            with gr.Row():
-                pick = gr.Dropdown(label="processed seed (by hash)", choices=[],
-                                   scale=4)
-                btn_reload = gr.Button("Reload list", scale=1)
-            preview = gr.JSON(label="improved trace", max_height=520)
-            dl = gr.File(label="download", interactive=False)
-            btn_reload.click(browse_choices, outputs=[pick])
-            pick.change(on_browse, inputs=[pick], outputs=[preview, dl])
-            app.load(browse_choices, outputs=[pick])
-
-    return app
-
-
-def main(argv: Optional[list[str]] = None) -> int:
-    import argparse
-
-    import gradio as gr
-
-    ap = argparse.ArgumentParser(description="traceforge Gradio app")
-    ap.add_argument("--host", default=os.environ.get("GRADIO_SERVER_NAME",
-                                                     "127.0.0.1"))
-    ap.add_argument("--port", type=int,
-                    default=int(os.environ.get("GRADIO_SERVER_PORT", "7860")))
-    ap.add_argument("--share", action="store_true")
-    args = ap.parse_args(argv)
-
-    app = build_app()
-    app.queue(default_concurrency_limit=4)
-    app.launch(server_name=args.host, server_port=args.port,
-               share=args.share, inbrowser=False, show_error=True,
-               css=CSS, theme=gr.themes.Base())
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+"""Gradio app: submit a trace, sponsor a dataset, read the dashboard.
+
+The UI is deliberately thin — every decision lives in `SpacePipeline` and
+`TraceStore`, so the same code runs locally (`python app.py`) and on a
+Hugging Face Space (`app.py` at the repo root).
+
+Tabs
+  Submit     one trace (JSON / JSONL / pasted) -> hash -> queue -> output
+  Sponsor    a JSONL of traces -> hashed, deduped, queued, attributed
+  Dashboard  public stats: corpus, time sensitivity, tasks, sponsors, queue
+  Browse     the stored outputs, by hash
+"""
+from __future__ import annotations
+
+import html
+import json
+import os
+from typing import Any, Optional
+
+from traceforge.space.hashing import short_hash
+from traceforge.space.ingest import parse_records, read_upload
+from traceforge.space.jobs import get_worker
+from traceforge.space.pipeline import SpacePipeline, pipeline_ready, space_config
+from traceforge.space.stats import bar_rows, dashboard, pct
+from traceforge.space.store import DONE, FAILED, QUEUED, RUNNING, TraceStore
+
+REFRESH_S = 8.0
+
+CSS = """
+.tf-wrap { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+.tf-kpis { display:grid; grid-template-columns:repeat(auto-fit,minmax(130px,1fr));
+           gap:8px; margin:6px 0 14px; }
+.tf-kpi { background:#161b22; border:1px solid #2a3140; border-radius:8px;
+          padding:9px 11px; }
+.tf-kpi .v { font-size:21px; font-weight:600; color:#e6edf3; line-height:1.2; }
+.tf-kpi .k { font-size:11px; color:#8b949e; text-transform:uppercase;
+             letter-spacing:.04em; }
+.tf-kpi .s { font-size:11px; color:#6e7681; }
+.tf-ok { color:#3fb950; } .tf-warn { color:#d29922; } .tf-bad { color:#f85149; }
+.tf-bar-row { display:grid; grid-template-columns:190px 1fr 64px; gap:8px;
+              align-items:center; font-size:12px; color:#9aa4b2; margin:3px 0; }
+.tf-bar-outer { background:#1b2029; border-radius:6px; height:14px;
+                overflow:hidden; border:1px solid #2a3140; }
+.tf-bar-inner { height:100%; background:linear-gradient(90deg,#2f81f7,#3fb950); }
+.tf-head { font-size:13px; color:#8b949e; margin:2px 0 8px; }
+.tf-pill { padding:2px 8px; border-radius:999px; font-size:11px;
+           border:1px solid #2a3140; }
+"""
+
+
+# --------------------------------------------------------------------- html
+
+def _esc(s: Any) -> str:
+    return html.escape(str(s if s is not None else ""))
+
+
+def _kpi(value: Any, key: str, sub: str = "", cls: str = "") -> str:
+    sub_html = f'<div class="s">{_esc(sub)}</div>' if sub else ""
+    return (f'<div class="tf-kpi"><div class="v {cls}">{_esc(value)}</div>'
+            f'<div class="k">{_esc(key)}</div>{sub_html}</div>')
+
+
+def _bars(counts: dict, total: Optional[int] = None) -> str:
+    rows = bar_rows(counts, total=total)
+    if not rows:
+        return '<div class="tf-head">no data yet</div>'
+    out = ['<div class="tf-wrap">']
+    for label, n, p in rows:
+        out.append(
+            '<div class="tf-bar-row">'
+            f'<span>{_esc(label)}</span>'
+            f'<span class="tf-bar-outer"><span class="tf-bar-inner" '
+            f'style="width:{max(0.0, min(100.0, p)):.1f}%"></span></span>'
+            f'<span>{n} · {p:.0f}%</span></div>'
+        )
+    out.append("</div>")
+    return "".join(out)
+
+
+def _status_pill(status: str, no_change: bool = False) -> str:
+    if no_change:
+        return '<span class="tf-pill tf-warn">no change</span>'
+    cls = {DONE: "tf-ok", FAILED: "tf-bad", RUNNING: "tf-warn",
+           QUEUED: "tf-warn"}.get(status, "")
+    return f'<span class="tf-pill {cls}">{_esc(status)}</span>'
+
+
+def _kpi_html(space: dict, ref: dict, worker: dict, ready: tuple[bool, str]) -> str:
+    ok, reason = ready
+    cards = [
+        _kpi(f"{space['seeds']:,}", "seeds", "distinct content hashes"),
+        _kpi(f"{space['done']:,}", "outputs",
+             f"{pct(space['done'], space['seeds']):.0f}% of seeds"),
+        _kpi(f"{space['queued']:,}", "queued",
+             f"{space['running']} running"),
+        _kpi(f"{space['failed']:,}", "failed", "errored or rejected"),
+        _kpi(f"{space.get('no_change', 0):,}", "no change",
+             "seed already ideal"),
+        _kpi(f"{len(space['sponsors'])}", "sponsors",
+             f"{sum(s['seeds'] for s in space['sponsors'])} seeds"),
+        _kpi(f"{space['duration_s']['median']:.0f}s", "median runtime",
+             f"p90 {space['duration_s']['p90']:.0f}s"),
+    ]
+    if ref.get("available"):
+        cards.append(_kpi(f"{ref.get('traces', 0):,}", "reference corpus",
+                          "published ideal traces"))
+    head = (
+        '<div class="tf-wrap"><div class="tf-head">'
+        f'<span class="tf-pill {"tf-ok" if ok else "tf-bad"}">'
+        f'{"pipeline ready" if ok else "pipeline not configured"}</span> '
+        f'{_esc(reason)} · worker {"alive" if worker.get("alive") else "stopped"}'
+        f' · queue {worker.get("queued", 0)}'
+        "</div></div>"
+    )
+    return head + '<div class="tf-wrap"><div class="tf-kpis">' + "".join(cards) + "</div></div>"
+
+
+def _ts_html(space: dict, ref: dict) -> str:
+    """Time sensitivity: the metric that says whether an answer decays."""
+    parts = ['<div class="tf-wrap"><div class="tf-head">'
+             "time sensitivity — a temporal fact answered from weights decays; "
+             "the same fact fetched with a tool does not</div>"]
+    space_ts = space.get("time_sensitivity") or {}
+    if space_ts:
+        parts.append("<b>this Space</b>")
+        parts.append(_bars(space_ts))
+    census = (ref or {}).get("time_sensitivity") or {}
+    if census.get("available"):
+        parts.append(f"<b>reference corpus</b> ({census.get('total', 0):,} traces)")
+        parts.append(_bars(census.get("classes") or {}))
+        parts.append(
+            f'<div class="tf-head">needs rewrite (tool available but never '
+            f'called): {census.get("needs_rewrite", 0):,}</div>')
+    if not space_ts and not census.get("available"):
+        parts.append('<div class="tf-head">no data yet</div>')
+    parts.append("</div>")
+    return "".join(parts)
+
+
+# ------------------------------------------------------------------- tables
+
+def _rows(records: list[dict], cols: list[str]) -> list[list]:
+    out = []
+    for r in records:
+        row = []
+        for c in cols:
+            v = r.get(c)
+            if c == "hash":
+                v = short_hash(v or "")
+            elif c == "time_sensitivity":
+                v = (v or {}).get("class", "")
+            elif isinstance(v, float):
+                v = round(v, 1)
+            row.append(v if v is not None else "")
+        out.append(row)
+    return out
+
+
+# ---------------------------------------------------------------------- app
+
+def build_app(store: Optional[TraceStore] = None,
+              pipeline: Optional[SpacePipeline] = None):
+    import gradio as gr
+
+    cfg = pipeline.cfg if pipeline else space_config()
+    store = store or (pipeline.store if pipeline else TraceStore(
+        os.path.join(cfg.data_dir)))
+    pipeline = pipeline or SpacePipeline(store, cfg)
+    worker = get_worker(pipeline)
+    ready = pipeline_ready(cfg)
+    dataset_dir = os.path.join(os.path.dirname(cfg.data_dir), "dataset")
+    cache_path = os.path.join(store.root, "reference_census.json")
+
+    # ------------------------------------------------------------- submit
+
+    def on_submit(file_path, pasted, sponsor, sync):
+        if not ready:
+            return (f"**pipeline not configured** — {ready[1]}. Nothing was "
+                    "queued.", None, None)
+        if file_path:
+            records, errors = read_upload(file_path)
+        else:
+            records, errors = parse_records(pasted or "")
+        if errors:
+            return (f"**parse errors**\n\n" + "\n".join(f"- {e}" for e in errors[:10]),
+                    None, None)
+        if not records:
+            return "**nothing to submit** — upload a file or paste JSON", None, None
+        if len(records) > 1:
+            return (f"**{len(records)} records** — the Submit tab takes one trace. "
+                    "Use **Sponsor a dataset** for a batch.", None, None)
+        try:
+            res = pipeline.submit(records[0], sponsor=sponsor)
+        except Exception as e:
+            return f"**submit failed**: {e}", None, None
+        h = res["hash"]
+        if res.get("duplicate") and res.get("status") == DONE:
+            path = store.output_path(h)
+            return (f"**already processed** — this seed hash already has an output.\n\n"
+                    f"`{h}`\n\nNo second output was created.", h,
+                    path if os.path.exists(path) else None)
+        if sync:
+            res = pipeline.process(h)
+        rec = pipeline.result(h)
+        md = _result_md(rec)
+        path = store.output_path(h) if rec.get("status") == DONE else None
+        return md, h, path if path and os.path.exists(path) else None
+
+    def on_check(h):
+        if not h:
+            return "no hash yet — submit a trace first", None
+        rec = pipeline.result(h)
+        path = store.output_path(h) if rec.get("status") == DONE else None
+        return _result_md(rec), path if path and os.path.exists(path) else None
+
+    def on_health():
+        from traceforge.space.local_llm import health
+        return health()
+
+    def on_probe():
+        from traceforge.space.local_llm import probe
+        r = probe()
+        if r.get("ok"):
+            return f"**local model answered:** `{r['text']}`"
+        return f"**local model failed:** `{r['error']}`"
+
+    def on_debug():
+        from traceforge.triage import _PARSE_DEBUG, _TRIAGE_DEBUG
+        return {"triage": list(_TRIAGE_DEBUG), "parse": list(_PARSE_DEBUG)}
+
+    def _result_md(rec: dict) -> str:
+        h = rec.get("hash") or ""
+        st = rec.get("status") or "unknown"
+        lines = [f"### {_status_pill(st, bool(rec.get('no_change')))} `{h}`", ""]
+        if rec.get("duplicate"):
+            lines.append("_duplicate submission — the existing record was returned_")
+            lines.append("")
+        if rec.get("task"):
+            lines.append(f"- task: **{rec['task']}** · language: **{rec.get('language', '?')}**")
+        if rec.get("n_messages"):
+            lines.append(f"- seed: {rec['n_messages']} messages · "
+                         f"{rec.get('n_tool_calls', 0)} tool calls")
+        if rec.get("n_messages_out"):
+            lines.append(f"- output: {rec['n_messages_out']} messages")
+        if rec.get("route"):
+            lines.append(f"- route: `{rec['route']}` · attempts: {rec.get('attempts', 0)}")
+        if rec.get("endpoint"):
+            lines.append(f"- endpoint: `{rec['endpoint']}`")
+        if rec.get("duration_s"):
+            lines.append(f"- runtime: {rec['duration_s']:.0f}s")
+        ts = rec.get("time_sensitivity") or {}
+        if ts.get("class"):
+            lines.append(f"- time sensitivity: **{ts['class']}** — {ts.get('label', '')}")
+            if ts.get("temporal_facts"):
+                lines.append(f"  - temporal facts: {', '.join(ts['temporal_facts'])}")
+            if ts.get("retrieval_available"):
+                lines.append(f"  - retrieval available: {', '.join(ts['retrieval_available'])}")
+            if ts.get("needs_rewrite"):
+                lines.append("  - the raw trace answered from weights although a "
+                             "retrieval tool was available")
+        ts2 = rec.get("time_sensitivity_improved") or {}
+        if ts2.get("class") and ts2.get("class") != ts.get("class"):
+            lines.append(f"- after rewrite: **{ts2['class']}**")
+        if rec.get("error"):
+            lines.append(f"- error: `{rec['error'][:600]}`")
+        if st == QUEUED:
+            lines.append("")
+            lines.append("_queued — the worker picks it up in submission order. "
+                         "Press **Check status** to refresh._")
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------ sponsor
+
+    def on_sponsor(file_path, pasted, sponsor):
+        if not ready:
+            return (f"**pipeline not configured** — {ready[1]}. Nothing was "
+                    "queued.", [], "")
+        if file_path:
+            records, errors = read_upload(file_path)
+        else:
+            records, errors = parse_records(pasted or "")
+        if errors:
+            return (f"**parse errors**\n\n" + "\n".join(f"- {e}" for e in errors[:10]),
+                    [], "")
+        if not records:
+            return "**nothing to sponsor** — upload a JSONL of traces", [], ""
+        results = pipeline.submit_many(records, sponsor=sponsor)
+        new = sum(1 for r in results if not r.get("duplicate") and r.get("hash"))
+        dup = sum(1 for r in results if r.get("duplicate"))
+        err = sum(1 for r in results if not r.get("hash"))
+        rows = []
+        for r in results:
+            rows.append([
+                short_hash(r.get("hash") or ""),
+                r.get("status") or "error",
+                "duplicate" if r.get("duplicate") else ("new" if r.get("hash") else "error"),
+                r.get("n_messages", ""),
+                r.get("task", "")[:60] if r.get("task") else "",
+                (r.get("time_sensitivity") or {}).get("class", ""),
+                (r.get("error") or "")[:120],
+            ])
+        md = (f"**{len(records)} records** — {new} new, {dup} already known, "
+              f"{err} rejected. Sponsor: **{_esc(sponsor or 'anonymous')}**.\n\n"
+              "New seeds are queued; each one produces at most one output.")
+        return md, rows, sponsor or "anonymous"
+
+    # ---------------------------------------------------------- dashboard
+
+    def on_dashboard():
+        d = dashboard(store, dataset_dir=dataset_dir, cache_path=cache_path)
+        space, ref = d["space"], d["reference"]
+        w = worker.status()
+        kpis = _kpi_html(space, ref, w, ready)
+        ts = _ts_html(space, ref)
+        tasks = bar_rows(space.get("tasks") or {})
+        langs = bar_rows(space.get("languages") or {})
+        sponsors = [[s["sponsor"], s["seeds"], s["done"], s["failed"]]
+                    for s in space.get("sponsors") or []]
+        recent = _rows(d["recent"], ["hash", "status", "sponsor", "task",
+                                     "time_sensitivity", "duration_s"])
+        queue = _rows(d["queue"], ["hash", "sponsor", "task", "n_messages"])
+        ref_rows = []
+        if ref.get("available"):
+            card = ref.get("card") or {}
+            for k, v in (card.get("tasks") or {}).items():
+                ref_rows.append([k, v, pct(v, card.get("traces", 0))])
+        return kpis, ts, tasks, langs, sponsors, recent, queue, ref_rows
+
+    # ------------------------------------------------------------- browse
+
+    def browse_choices():
+        done = [r for r in store.all() if r.get("status") == DONE]
+        done.sort(key=lambda r: r.get("updated_at") or 0, reverse=True)
+        return gr.update(choices=[r["hash"] for r in done][:500])
+
+    def on_browse(h):
+        if not h:
+            return None, None
+        out = store.load_output(h)
+        if out is None:
+            return None, None
+        return out.to_dict(), store.output_path(h)
+
+    # ---------------------------------------------------------------- UI
+
+    with gr.Blocks(title="traceforge — ideal-world agent traces") as app:
+        gr.Markdown(
+            "# traceforge\n"
+            "Turn a real agent trace into its **ideal-world reference**: the same "
+            "work, with the dead ends removed, gated for structure and grounding.\n\n"
+            "Every seed is identified by a **content hash** — submitting the same "
+            "trace twice returns the existing output instead of creating a second one."
+        )
+
+        with gr.Tab("Submit a trace"):
+            with gr.Row():
+                with gr.Column(scale=3):
+                    file_in = gr.File(label="trace file (.json / .jsonl)",
+                                      file_types=[".json", ".jsonl"],
+                                      type="filepath")
+                    paste_in = gr.Textbox(
+                        label="…or paste a trace (JSON, JSONL, or a message list)",
+                        lines=10, placeholder='{"messages": [{"role": "user", ...}]}')
+                with gr.Column(scale=2):
+                    sponsor_in = gr.Textbox(label="your name / handle (optional)",
+                                            max_lines=1)
+                    sync_in = gr.Checkbox(
+                        label="process synchronously (debug — blocks until done)",
+                        value=os.environ.get("TRACEFORGE_SPACE_SYNC") == "1")
+                    btn_submit = gr.Button("Submit", variant="primary")
+                    btn_check = gr.Button("Check status")
+                    last_hash = gr.State("")
+            status_md = gr.Markdown("_no submission yet_")
+            out_file = gr.File(label="improved trace (download)", interactive=False)
+            with gr.Accordion("Local model (ZeroGPU)", open=False):
+                gr.Markdown(
+                    "With no remote endpoint configured, the Space runs "
+                    "`LiquidAI/LFM2.5-24B-A2B` on ZeroGPU. GPU time is charged "
+                    "to **your** HF daily quota, not to the Space owner — the "
+                    "24B checkpoint needs the 96 GB `xlarge` slice, which "
+                    "costs 2x quota per second. Local mode handles seeds up "
+                    "to 24 KB.")
+                btn_health = gr.Button("Check local model")
+                health_json = gr.JSON(label="local model status")
+                btn_probe = gr.Button("Test local model (loads it, ~60 s)")
+                probe_md = gr.Markdown()
+                btn_debug = gr.Button("Last triage replies")
+                debug_json = gr.JSON(label="triage debug")
+            btn_health.click(on_health, outputs=[health_json])
+            btn_probe.click(on_probe, outputs=[probe_md])
+            btn_debug.click(on_debug, outputs=[debug_json])
+
+            btn_submit.click(on_submit,
+                             inputs=[file_in, paste_in, sponsor_in, sync_in],
+                             outputs=[status_md, last_hash, out_file])
+            btn_check.click(on_check, inputs=[last_hash],
+                            outputs=[status_md, out_file])
+
+        with gr.Tab("Sponsor a dataset"):
+            gr.Markdown(
+                "Upload a JSONL of traces. Each row is hashed; **new** seeds are "
+                "queued for the pipeline and attributed to you, **known** seeds are "
+                "skipped. The processed rows join the public output dataset."
+            )
+            with gr.Row():
+                with gr.Column(scale=3):
+                    sp_file = gr.File(label="dataset (.jsonl)", file_types=[".jsonl"],
+                                      type="filepath")
+                    sp_paste = gr.Textbox(label="…or paste JSONL", lines=8)
+                with gr.Column(scale=2):
+                    sp_name = gr.Textbox(label="sponsor name", max_lines=1)
+                    sp_btn = gr.Button("Sponsor", variant="primary")
+            sp_md = gr.Markdown("_no dataset sponsored yet_")
+            sp_table = gr.Dataframe(
+                headers=["hash", "status", "new?", "messages", "task",
+                         "time sensitivity", "error"],
+                interactive=False, wrap=True, max_height=420,
+            )
+            sp_credit = gr.State("")
+            sp_btn.click(on_sponsor, inputs=[sp_file, sp_paste, sp_name],
+                         outputs=[sp_md, sp_table, sp_credit])
+
+        with gr.Tab("Dashboard"):
+            gr.Markdown("Public statistics. Refreshes automatically.")
+            dash_kpis = gr.HTML()
+            dash_ts = gr.HTML()
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("### task mix (this Space)")
+                    dash_tasks = gr.Dataframe(
+                        headers=["task", "seeds", "pct"], interactive=False,
+                        wrap=True, max_height=300)
+                with gr.Column():
+                    gr.Markdown("### languages")
+                    dash_langs = gr.Dataframe(
+                        headers=["language", "seeds", "pct"], interactive=False,
+                        wrap=True, max_height=300)
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("### sponsors")
+                    dash_sponsors = gr.Dataframe(
+                        headers=["sponsor", "seeds", "done", "failed"],
+                        interactive=False, wrap=True, max_height=300)
+                with gr.Column():
+                    gr.Markdown("### reference corpus — task mix")
+                    dash_ref = gr.Dataframe(
+                        headers=["task", "traces", "pct"], interactive=False,
+                        wrap=True, max_height=300)
+            gr.Markdown("### recent outputs")
+            dash_recent = gr.Dataframe(
+                headers=["hash", "status", "sponsor", "task",
+                         "time sensitivity", "runtime s"],
+                interactive=False, wrap=True, max_height=320)
+            gr.Markdown("### queue")
+            dash_queue = gr.Dataframe(
+                headers=["hash", "sponsor", "task", "messages"],
+                interactive=False, wrap=True, max_height=240)
+
+            dash_outputs = [dash_kpis, dash_ts, dash_tasks, dash_langs,
+                            dash_sponsors, dash_recent, dash_queue, dash_ref]
+            timer = gr.Timer(REFRESH_S)
+            timer.tick(on_dashboard, outputs=dash_outputs)
+            app.load(on_dashboard, outputs=dash_outputs)
+
+        with gr.Tab("Browse outputs"):
+            with gr.Row():
+                pick = gr.Dropdown(label="processed seed (by hash)", choices=[],
+                                   scale=4)
+                btn_reload = gr.Button("Reload list", scale=1)
+            preview = gr.JSON(label="improved trace", max_height=520)
+            dl = gr.File(label="download", interactive=False)
+            btn_reload.click(browse_choices, outputs=[pick])
+            pick.change(on_browse, inputs=[pick], outputs=[preview, dl])
+            app.load(browse_choices, outputs=[pick])
+
+    return app
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    import argparse
+
+    import gradio as gr
+
+    ap = argparse.ArgumentParser(description="traceforge Gradio app")
+    ap.add_argument("--host", default=os.environ.get("GRADIO_SERVER_NAME",
+                                                     "127.0.0.1"))
+    ap.add_argument("--port", type=int,
+                    default=int(os.environ.get("GRADIO_SERVER_PORT", "7860")))
+    ap.add_argument("--share", action="store_true")
+    args = ap.parse_args(argv)
+
+    app = build_app()
+    app.queue(default_concurrency_limit=4)
+    app.launch(server_name=args.host, server_port=args.port,
+               share=args.share, inbrowser=False, show_error=True,
+               css=CSS, theme=gr.themes.Base())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

traceforge/space/local_llm.py

@@ -1,291 +1,406 @@
-"""Local OpenAI-compatible chat server for the Space's ZeroGPU fallback.
-
-When no remote endpoint is configured, the Space runs a small instruct
-model on Hugging Face ZeroGPU.  The pipeline talks to it exactly like a
-remote endpoint — a urllib POST to ``/v1/chat/completions`` — so no core
-module needs to know the difference.
-
-ZeroGPU bills the **visitor's** daily quota, not the Space owner's: the
-decorated function requests a GPU slice for the duration of one call and
-releases it afterwards, so idle time is free.  Quotas (2026): anonymous
-2 min/day, free account 5 min/day, PRO 40 min/day.
-
-The checkpoint is prefetched to disk at startup and loaded to the GPU on
-the first request, because a 3B fp16 model is ~6 GB and downloading it
-inside a 120 s GPU slice would eat the whole slice.
-"""
-from __future__ import annotations
-
-import json
-import os
-import threading
-import urllib.request
-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from typing import Any, Optional
-
-LOCAL_MODEL = (os.environ.get("TRACEFORGE_LOCAL_MODEL")
-               or "Qwen/Qwen2.5-3B-Instruct")
-LOCAL_MAX_NEW_TOKENS = int(os.environ.get("TRACEFORGE_LOCAL_MAX_NEW_TOKENS")
-                           or 2000)
-LOCAL_MAX_INPUT_TOKENS = int(os.environ.get("TRACEFORGE_LOCAL_MAX_INPUT_TOKENS")
-                             or 28000)
-GPU_DURATION_S = int(os.environ.get("TRACEFORGE_GPU_DURATION_S") or 120)
-LOCAL_DEVICE = os.environ.get("TRACEFORGE_LOCAL_DEVICE") or "cuda"
-
-_lock = threading.Lock()
-_model: Any = None
-_tok: Any = None
-_server: Optional[ThreadingHTTPServer] = None
-_server_url: Optional[str] = None
-LAST_ERROR: Optional[str] = None
-REQUESTS = 0
-LAST_REQUEST: Optional[dict] = None
-LAST_RESPONSE: Optional[str] = None
-
-# A Space can carry HTTP(S)_PROXY for outbound traffic; urllib would then
-# route the loopback call through it and the local server would never see
-# the request.  Bypass the proxy for loopback before any call is made.
-for _var in ("NO_PROXY", "no_proxy"):
-    _cur = os.environ.get(_var, "")
-    if "127.0.0.1" not in _cur:
-        os.environ[_var] = (_cur + ",127.0.0.1,localhost").strip(",")
-
-
-def _gpu(fn):
-    """``@spaces.GPU`` on a ZeroGPU Space, a no-op everywhere else."""
-    try:
-        import spaces  # type: ignore
-        return spaces.GPU(duration=GPU_DURATION_S)(fn)
-    except Exception:
-        return fn
-
-
-def _stub() -> bool:
-    """Wiring tests run without torch: return a canned JSON object."""
-    return os.environ.get("TRACEFORGE_LOCAL_STUB") == "1"
-
-
-def _load():
-    global _model, _tok
-    if _model is not None:
-        return _model, _tok
-    import torch
-    from transformers import AutoModelForCausalLM, AutoTokenizer
-
-    _tok = AutoTokenizer.from_pretrained(LOCAL_MODEL)
-    _model = AutoModelForCausalLM.from_pretrained(
-        LOCAL_MODEL,
-        torch_dtype=torch.float16 if LOCAL_DEVICE == "cuda" else torch.float32,
-        device_map=LOCAL_DEVICE,
-        low_cpu_mem_usage=True,
-    )
-    _model.eval()
-    return _model, _tok
-
-
-@_gpu
-def generate(messages: list[dict], *, max_tokens: int = 512,
-             temperature: float = 0.2) -> str:
-    """One chat completion on the local model (inside a GPU slice)."""
-    if _stub():
-        return '{"ok": true}'
-    import torch
-
-    model, tok = _load()
-    prompt = tok.apply_chat_template(messages, tokenize=False,
-                                     add_generation_prompt=True)
-    enc = tok(prompt, return_tensors="pt", truncation=True,
-              max_length=LOCAL_MAX_INPUT_TOKENS).to(LOCAL_DEVICE)
-    n = max(1, min(int(max_tokens or 512), LOCAL_MAX_NEW_TOKENS))
-    with torch.inference_mode():
-        out = model.generate(
-            **enc,
-            max_new_tokens=n,
-            do_sample=temperature > 0,
-            temperature=max(float(temperature), 0.01),
-            top_p=0.95,
-            pad_token_id=tok.eos_token_id,
-        )
-    text = tok.decode(out[0][enc["input_ids"].shape[1]:],
-                      skip_special_tokens=True)
-    return text.strip()
-
-
-def _friendly_error(e: Exception) -> str:
-    """Turn a ZeroGPU quota rejection into something a visitor can act on."""
-    msg = f"{type(e).__name__}: {e}"
-    low = msg.lower()
-    if "quota" in low or ("gpu" in low and "exceed" in low):
-        return ("ZeroGPU quota exhausted for this visitor. Anonymous visitors "
-                "get 2 min/day, a free HF account 5 min/day, PRO 40 min/day. "
-                "Sign in to huggingface.co or come back tomorrow.")
-    return msg
-
-
-class _Handler(BaseHTTPRequestHandler):
-    protocol_version = "HTTP/1.1"
-
-    def log_message(self, format, *args):  # keep the Space log readable
-        pass
-
-    def _send(self, code: int, obj: dict) -> None:
-        body = json.dumps(obj).encode("utf-8")
-        self.send_response(code)
-        self.send_header("Content-Type", "application/json")
-        self.send_header("Content-Length", str(len(body)))
-        self.end_headers()
-        self.wfile.write(body)
-
-    def do_GET(self):  # noqa: N802 - BaseHTTPRequestHandler API
-        if self.path.rstrip("/").endswith("/models"):
-            self._send(200, {"object": "list", "data": [
-                {"id": LOCAL_MODEL, "object": "model", "owned_by": "local"}]})
-        else:
-            self._send(404, {"error": "not found"})
-
-    def do_POST(self):  # noqa: N802 - BaseHTTPRequestHandler API
-        global REQUESTS, LAST_REQUEST
-        REQUESTS += 1
-        if not self.path.rstrip("/").endswith("/chat/completions"):
-            LAST_REQUEST = {"path": self.path, "error": "not found"}
-            self._send(404, {"error": "not found"})
-            return
-        try:
-            n = int(self.headers.get("Content-Length") or 0)
-            payload = json.loads(self.rfile.read(n).decode("utf-8"))
-        except Exception as e:
-            LAST_REQUEST = {"path": self.path, "error": f"bad json: {e}"}
-            self._send(400, {"error": f"bad json: {e}"})
-            return
-        messages = list(payload.get("messages") or [])
-        LAST_REQUEST = {"path": self.path, "bytes": n,
-                        "messages": len(messages),
-                        "max_tokens": payload.get("max_tokens")}
-        # The pipeline's prompts already ask for JSON, but a small model
-        # likes to wrap it in prose; make the constraint explicit.
-        if payload.get("structured_outputs") or payload.get("guided_json"):
-            messages = [{"role": "system",
-                         "content": "Return only one JSON object. No markdown "
-                                    "fences, no commentary."}] + messages
-        try:
-            with _lock:
-                text = generate(
-                    messages,
-                    max_tokens=int(payload.get("max_tokens") or 512),
-                    temperature=float(payload.get("temperature") or 0.2),
-                )
-        except Exception as e:
-            global LAST_ERROR
-            LAST_ERROR = _friendly_error(e)
-            import traceback
-            traceback.print_exc()
-            self._send(500, {"error": f"local model failed: {LAST_ERROR}"})
-            return
-        global LAST_RESPONSE
-        LAST_RESPONSE = (text or "")[:800]
-        self._send(200, {
-            "id": "local-0",
-            "object": "chat.completion",
-            "model": LOCAL_MODEL,
-            "choices": [{
-                "index": 0,
-                "finish_reason": "stop",
-                "message": {"role": "assistant", "content": text},
-            }],
-            "usage": {"prompt_tokens": 0, "completion_tokens": 0,
-                      "total_tokens": 0},
-        })
-
-
-def ensure_local_server() -> str:
-    """Start the loopback server once; return its ``/v1`` base URL."""
-    global _server, _server_url
-    if _server_url:
-        return _server_url
-    srv = ThreadingHTTPServer(("127.0.0.1", 0), _Handler)
-    srv.daemon_threads = True
-    threading.Thread(target=srv.serve_forever, name="local-llm",
-                     daemon=True).start()
-    _server = srv
-    _server_url = f"http://127.0.0.1:{srv.server_address[1]}/v1"
-    return _server_url
-
-
-def prefetch() -> None:
-    """Download the checkpoint in the background so the first call is fast."""
-    if _stub():
-        return
-
-    def _run():
-        try:
-            from huggingface_hub import snapshot_download
-            snapshot_download(LOCAL_MODEL, allow_patterns=[
-                "*.json", "*.safetensors", "*.txt", "*.model"])
-        except Exception:
-            pass
-
-    threading.Thread(target=_run, name="local-llm-prefetch",
-                     daemon=True).start()
-
-
-def local_model_id() -> str:
-    return LOCAL_MODEL
-
-
-def is_local_url(url: str) -> bool:
-    return bool(url) and url.startswith("http://127.0.0.1:")
-
-
-def _ping() -> dict:
-    if not _server_url:
-        return {"ok": False, "error": "no server"}
-    try:
-        with urllib.request.urlopen(_server_url + "/models", timeout=3) as r:
-            return {"ok": True, "status": r.status}
-    except Exception as e:
-        return {"ok": False, "error": f"{type(e).__name__}: {e}"}
-
-
-def probe() -> dict:
-    """One real chat call through the local server (loads the model)."""
-    if not _server_url:
-        return {"ok": False, "error": "no server"}
-    payload = {
-        "model": LOCAL_MODEL,
-        "messages": [{"role": "user",
-                      "content": "Reply with the single word: ok"}],
-        "max_tokens": 8,
-        "temperature": 0.0,
-    }
-    req = urllib.request.Request(
-        _server_url + "/chat/completions",
-        data=json.dumps(payload).encode("utf-8"),
-        headers={"Content-Type": "application/json"},
-        method="POST",
-    )
-    try:
-        with urllib.request.urlopen(req, timeout=180) as r:
-            data = json.loads(r.read().decode("utf-8"))
-        return {"ok": True,
-                "text": (data["choices"][0]["message"]["content"] or "")[:200]}
-    except Exception as e:
-        return {"ok": False, "error": f"{type(e).__name__}: {e}"}
-
-
-def health() -> dict:
-    """What the UI shows when the local model misbehaves."""
-    return {
-        "model": LOCAL_MODEL,
-        "device": LOCAL_DEVICE,
-        "loaded": _model is not None,
-        "stub": _stub(),
-        "gpu_duration_s": GPU_DURATION_S,
-        "server": _server_url or "",
-        "ping": _ping(),
-        "requests": REQUESTS,
-        "last_request": LAST_REQUEST,
-        "last_response": LAST_RESPONSE,
-        "proxy": {k: v for k, v in os.environ.items()
-                  if "proxy" in k.lower()},
-        "last_error": LAST_ERROR,
-    }
+"""Local OpenAI-compatible chat server for the Space's ZeroGPU fallback.
+
+When no remote endpoint is configured, the Space runs LFM2.5-24B-A2B (24B
+total, 2.45B active) on Hugging Face ZeroGPU.  The pipeline talks to it
+exactly like a remote endpoint — a urllib POST to
+``/v1/chat/completions`` — so no core module needs to know the difference.
+
+ZeroGPU bills the **visitor's** daily quota, not the Space owner's: the
+decorated function requests a GPU slice for the duration of one call and
+releases it afterwards, so idle time is free.  Quotas (2026): anonymous
+2 min/day, free account 5 min/day, PRO 40 min/day.
+
+Three facts drive the configuration here:
+
+* The bf16 checkpoint is ~48 GB of weights, so it needs the 96 GB
+  ``xlarge`` slice — the default ``large`` slice is 48 GB, i.e. exactly
+  the weights and nothing else — and xlarge costs 2x quota per second.
+* 48 GB does not fit the Space's 50 GB ephemeral disk next to torch and
+  transformers.  Mount the model repo as a read-only volume instead
+  (``TRACEFORGE_LOCAL_MOUNT``, see docs/SPACE.md).  Only when it is not
+  mounted is the checkpoint downloaded, and then free space is checked
+  first so the Space is not evicted mid-download.
+* The model always thinks before it answers (the chat template opens a
+  ``think`` block), so the reply is stripped back to the answer before it
+  reaches the pipeline's JSON parser.
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Optional
+
+LOCAL_MODEL = (os.environ.get("TRACEFORGE_LOCAL_MODEL")
+               or "LiquidAI/LFM2.5-24B-A2B")
+LOCAL_MAX_NEW_TOKENS = int(os.environ.get("TRACEFORGE_LOCAL_MAX_NEW_TOKENS")
+                           or 4096)
+LOCAL_MAX_INPUT_TOKENS = int(os.environ.get("TRACEFORGE_LOCAL_MAX_INPUT_TOKENS")
+                             or 28000)
+GPU_DURATION_S = int(os.environ.get("TRACEFORGE_GPU_DURATION_S") or 120)
+# 48 GB of bf16 weights do not fit the 48 GB "large" slice.
+GPU_SIZE = os.environ.get("TRACEFORGE_GPU_SIZE") or "xlarge"
+LOCAL_DEVICE = os.environ.get("TRACEFORGE_LOCAL_DEVICE") or "cuda"
+LOCAL_DTYPE = os.environ.get("TRACEFORGE_LOCAL_DTYPE") or "bfloat16"
+# Where the model repo is mounted read-only (docs/SPACE.md).  Loading from a
+# mount keeps 48 GB off the Space's 50 GB ephemeral disk.
+LOCAL_MOUNT = (os.environ.get("TRACEFORGE_LOCAL_MOUNT")
+               or "/models/lfm2.5-24b-a2b")
+# Free disk the download needs; the checkpoint is 48 GB and the Space has 50.
+LOCAL_DISK_GB = float(os.environ.get("TRACEFORGE_LOCAL_DISK_GB") or 50)
+
+_lock = threading.Lock()
+_model: Any = None
+_tok: Any = None
+_server: Optional[ThreadingHTTPServer] = None
+_server_url: Optional[str] = None
+LAST_ERROR: Optional[str] = None
+REQUESTS = 0
+LAST_REQUEST: Optional[dict] = None
+LAST_RESPONSE: Optional[str] = None
+# "idle" -> "running" -> "done" | "error"; "mounted" when no download is
+# needed.  A request that arrives before the checkpoint is on disk must fail
+# fast: downloading 48 GB inside a 120 s GPU slice would burn the whole slice.
+PREFETCH: dict = {"state": "idle", "error": "", "source": ""}
+
+# A Space can carry HTTP(S)_PROXY for outbound traffic; urllib would then
+# route the loopback call through it and the local server would never see
+# the request.  Bypass the proxy for loopback before any call is made.
+for _var in ("NO_PROXY", "no_proxy"):
+    _cur = os.environ.get(_var, "")
+    if "127.0.0.1" not in _cur:
+        os.environ[_var] = (_cur + ",127.0.0.1,localhost").strip(",")
+
+
+def _gpu(fn):
+    """``@spaces.GPU`` on a ZeroGPU Space, a no-op everywhere else."""
+    try:
+        import spaces  # type: ignore
+    except Exception:
+        return fn
+    try:
+        return spaces.GPU(duration=GPU_DURATION_S, size=GPU_SIZE)(fn)
+    except TypeError:  # `spaces` older than the size argument
+        return spaces.GPU(duration=GPU_DURATION_S)(fn)
+
+
+def _stub() -> bool:
+    """Wiring tests run without torch: return a canned JSON object."""
+    return os.environ.get("TRACEFORGE_LOCAL_STUB") == "1"
+
+
+def _model_source() -> str:
+    """Local directory when the checkpoint is mounted, else the hub id.
+
+    A mounted repo is a plain directory of safetensors, so ``from_pretrained``
+    reads it in place — no 48 GB copy on the Space's ephemeral disk.
+    """
+    explicit = (os.environ.get("TRACEFORGE_LOCAL_MODEL_PATH") or "").strip()
+    for cand in (explicit, LOCAL_MOUNT):
+        if cand and os.path.isfile(os.path.join(cand, "config.json")):
+            return cand
+    return LOCAL_MODEL
+
+
+def _torch_dtype():
+    import torch
+    if LOCAL_DEVICE != "cuda":
+        return torch.float32
+    return {"bfloat16": torch.bfloat16, "float16": torch.float16,
+            "float32": torch.float32}.get(LOCAL_DTYPE, torch.bfloat16)
+
+
+def _load():
+    global _model, _tok
+    if _model is not None:
+        return _model, _tok
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    src = _model_source()
+    _tok = AutoTokenizer.from_pretrained(src)
+    kwargs = dict(device_map=LOCAL_DEVICE, low_cpu_mem_usage=True)
+    try:
+        # transformers >= 5 renamed `torch_dtype` to `dtype`.
+        _model = AutoModelForCausalLM.from_pretrained(
+            src, dtype=_torch_dtype(), **kwargs)
+    except TypeError:  # transformers 4.x
+        _model = AutoModelForCausalLM.from_pretrained(
+            src, torch_dtype=_torch_dtype(), **kwargs)
+    _model.eval()
+    return _model, _tok
+
+
+_THINK_END = "</think>"
+
+
+def _strip_reasoning(text: str) -> str:
+    """Drop the model's ``think`` block; LFM2.5 always thinks first.
+
+    The chat template opens the block, so the reply is
+    ``reasoning ... answer``.  A reply that never closes the block was cut
+    off mid-thought and carries no answer — return "" so the caller sees an
+    empty completion instead of parsing reasoning as JSON.
+    """
+    if not text:
+        return ""
+    i = text.rfind(_THINK_END)
+    if i >= 0:
+        return text[i + len(_THINK_END):].strip()
+    if "think" in text:
+        return ""
+    return text.strip()
+
+
+def _prefetch_error() -> str:
+    """Why a request cannot run yet — the checkpoint is not on disk."""
+    state = PREFETCH.get("state")
+    if state == "error":
+        return (f"local model unavailable: {PREFETCH.get('error')}. "
+                "Mount the checkpoint as a volume (docs/SPACE.md) or set a "
+                "remote endpoint.")
+    return (f"local model is still downloading ({LOCAL_MODEL}, ~48 GB). "
+            "Try again in a few minutes.")
+
+
+@_gpu
+def generate(messages: list[dict], *, max_tokens: int = 512,
+             temperature: float = 0.2) -> str:
+    """One chat completion on the local model (inside a GPU slice)."""
+    if _stub():
+        return '{"ok": true}'
+    if PREFETCH.get("state") not in ("done", "mounted"):
+        # Never download inside the slice: 48 GB would eat the whole slice
+        # and the visitor's quota with it.
+        if PREFETCH.get("state") == "idle":
+            prefetch()
+        raise RuntimeError(_prefetch_error())
+    import torch
+
+    model, tok = _load()
+    prompt = tok.apply_chat_template(messages, tokenize=False,
+                                     add_generation_prompt=True)
+    enc = tok(prompt, return_tensors="pt", truncation=True,
+              max_length=LOCAL_MAX_INPUT_TOKENS).to(LOCAL_DEVICE)
+    n = max(1, min(int(max_tokens or 512), LOCAL_MAX_NEW_TOKENS))
+    with torch.inference_mode():
+        out = model.generate(
+            **enc,
+            max_new_tokens=n,
+            do_sample=temperature > 0,
+            temperature=max(float(temperature), 0.01),
+            top_p=0.95,
+            # The model card's generation parameters.
+            top_k=50,
+            repetition_penalty=1.05,
+            pad_token_id=tok.eos_token_id,
+        )
+    text = tok.decode(out[0][enc["input_ids"].shape[1]:],
+                      skip_special_tokens=True)
+    return _strip_reasoning(text)
+
+
+def _friendly_error(e: Exception) -> str:
+    """Turn a ZeroGPU quota rejection into something a visitor can act on."""
+    msg = f"{type(e).__name__}: {e}"
+    low = msg.lower()
+    if "quota" in low or ("gpu" in low and "exceed" in low):
+        return ("ZeroGPU quota exhausted for this visitor. Anonymous visitors "
+                "get 2 min/day, a free HF account 5 min/day, PRO 40 min/day. "
+                "Sign in to huggingface.co or come back tomorrow.")
+    return msg
+
+
+class _Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, format, *args):  # keep the Space log readable
+        pass
+
+    def _send(self, code: int, obj: dict) -> None:
+        body = json.dumps(obj).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):  # noqa: N802 - BaseHTTPRequestHandler API
+        if self.path.rstrip("/").endswith("/models"):
+            self._send(200, {"object": "list", "data": [
+                {"id": LOCAL_MODEL, "object": "model", "owned_by": "local"}]})
+        else:
+            self._send(404, {"error": "not found"})
+
+    def do_POST(self):  # noqa: N802 - BaseHTTPRequestHandler API
+        global REQUESTS, LAST_REQUEST
+        REQUESTS += 1
+        if not self.path.rstrip("/").endswith("/chat/completions"):
+            LAST_REQUEST = {"path": self.path, "error": "not found"}
+            self._send(404, {"error": "not found"})
+            return
+        try:
+            n = int(self.headers.get("Content-Length") or 0)
+            payload = json.loads(self.rfile.read(n).decode("utf-8"))
+        except Exception as e:
+            LAST_REQUEST = {"path": self.path, "error": f"bad json: {e}"}
+            self._send(400, {"error": f"bad json: {e}"})
+            return
+        messages = list(payload.get("messages") or [])
+        LAST_REQUEST = {"path": self.path, "bytes": n,
+                        "messages": len(messages),
+                        "max_tokens": payload.get("max_tokens")}
+        # The pipeline's prompts already ask for JSON, but a small model
+        # likes to wrap it in prose; make the constraint explicit.
+        if payload.get("structured_outputs") or payload.get("guided_json"):
+            messages = [{"role": "system",
+                         "content": "Return only one JSON object. No markdown "
+                                    "fences, no commentary."}] + messages
+        try:
+            with _lock:
+                text = generate(
+                    messages,
+                    max_tokens=int(payload.get("max_tokens") or 512),
+                    temperature=float(payload.get("temperature") or 0.2),
+                )
+        except Exception as e:
+            global LAST_ERROR
+            LAST_ERROR = _friendly_error(e)
+            import traceback
+            traceback.print_exc()
+            self._send(500, {"error": f"local model failed: {LAST_ERROR}"})
+            return
+        global LAST_RESPONSE
+        LAST_RESPONSE = (text or "")[:800]
+        self._send(200, {
+            "id": "local-0",
+            "object": "chat.completion",
+            "model": LOCAL_MODEL,
+            "choices": [{
+                "index": 0,
+                "finish_reason": "stop",
+                "message": {"role": "assistant", "content": text},
+            }],
+            "usage": {"prompt_tokens": 0, "completion_tokens": 0,
+                      "total_tokens": 0},
+        })
+
+
+def ensure_local_server() -> str:
+    """Start the loopback server once; return its ``/v1`` base URL."""
+    global _server, _server_url
+    if _server_url:
+        return _server_url
+    srv = ThreadingHTTPServer(("127.0.0.1", 0), _Handler)
+    srv.daemon_threads = True
+    threading.Thread(target=srv.serve_forever, name="local-llm",
+                     daemon=True).start()
+    _server = srv
+    _server_url = f"http://127.0.0.1:{srv.server_address[1]}/v1"
+    return _server_url
+
+
+def prefetch() -> None:
+    """Make the checkpoint available before the first GPU call.
+
+    A mounted repo needs nothing.  Otherwise the 48 GB download runs in the
+    background — but only after checking free disk, because the Space's
+    ephemeral disk is 50 GB and an eviction mid-download takes the whole app
+    down with it.
+    """
+    if _stub():
+        return
+    src = _model_source()
+    if src != LOCAL_MODEL:
+        PREFETCH.update(state="mounted", error="", source=src)
+        return
+    if PREFETCH.get("state") in ("running", "done"):
+        return
+
+    def _run():
+        PREFETCH.update(state="running", error="", source=LOCAL_MODEL)
+        try:
+            import shutil
+            cache = os.environ.get("HF_HOME") or os.path.expanduser("~")
+            free_gb = shutil.disk_usage(cache).free / 1e9
+            if free_gb < LOCAL_DISK_GB:
+                raise RuntimeError(
+                    f"needs {LOCAL_DISK_GB:.0f} GB of disk, {free_gb:.0f} GB "
+                    f"free under {cache}")
+            from huggingface_hub import snapshot_download
+            snapshot_download(LOCAL_MODEL, allow_patterns=[
+                "*.json", "*.safetensors", "*.txt", "*.model"])
+            PREFETCH.update(state="done")
+        except Exception as e:
+            PREFETCH.update(state="error", error=f"{type(e).__name__}: {e}")
+
+    threading.Thread(target=_run, name="local-llm-prefetch",
+                     daemon=True).start()
+
+
+def local_model_id() -> str:
+    return LOCAL_MODEL
+
+
+def is_local_url(url: str) -> bool:
+    return bool(url) and url.startswith("http://127.0.0.1:")
+
+
+def _ping() -> dict:
+    if not _server_url:
+        return {"ok": False, "error": "no server"}
+    try:
+        with urllib.request.urlopen(_server_url + "/models", timeout=3) as r:
+            return {"ok": True, "status": r.status}
+    except Exception as e:
+        return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+
+def probe() -> dict:
+    """One real chat call through the local server (loads the model)."""
+    if not _server_url:
+        return {"ok": False, "error": "no server"}
+    payload = {
+        "model": LOCAL_MODEL,
+        "messages": [{"role": "user",
+                      "content": "Reply with the single word: ok"}],
+        "max_tokens": 8,
+        "temperature": 0.0,
+    }
+    req = urllib.request.Request(
+        _server_url + "/chat/completions",
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=180) as r:
+            data = json.loads(r.read().decode("utf-8"))
+        return {"ok": True,
+                "text": (data["choices"][0]["message"]["content"] or "")[:200]}
+    except Exception as e:
+        return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+
+def health() -> dict:
+    """What the UI shows when the local model misbehaves."""
+    return {
+        "model": LOCAL_MODEL,
+        "source": _model_source(),
+        "device": LOCAL_DEVICE,
+        "dtype": LOCAL_DTYPE,
+        "loaded": _model is not None,
+        "stub": _stub(),
+        "gpu_duration_s": GPU_DURATION_S,
+        "gpu_size": GPU_SIZE,
+        "prefetch": dict(PREFETCH),
+        "server": _server_url or "",
+        "ping": _ping(),
+        "requests": REQUESTS,
+        "last_request": LAST_REQUEST,
+        "last_response": LAST_RESPONSE,
+        "proxy": {k: v for k, v in os.environ.items()
+                  if "proxy" in k.lower()},
+        "last_error": LAST_ERROR,
+    }

traceforge/space/pipeline.py

@@ -1,404 +1,406 @@
-"""The pipeline behind the web UI.
-
-`SpacePipeline` is the only thing the Gradio app talks to. It wraps the
-windowed splice engine (`improve_trace_splice`) so a trace that arrives as
-JSON — not as a session id in a local store — can be processed:
-
-    submit(record)      hash -> dedupe -> enqueue (idempotent)
-    process(hash)       run triage + rewrite + gates, store the output
-
-Configuration is environment-only, because a Space has no `~/.hermes`:
-
-    TRACEFORGE_BASE_URL      OpenAI-compatible endpoint (…/v1)
-    TRACEFORGE_LLM_KEY       bearer token
-    TRACEFORGE_MODEL         writer/judge model id
-    TRACEFORGE_TRIAGE_MODEL  cheap labeler (default: TRACEFORGE_MODEL)
-    TRACEFORGE_JUDGE_MODEL   judge override (default: TRACEFORGE_MODEL)
-    TRACEFORGE_DATA_DIR      store root (default: <repo>/data/space)
-
-`split_long` is deliberately OFF: splitting one submitted seed into N
-segments would produce N outputs for one hash, which is exactly what the
-one-seed-one-output rule forbids. The splice engine already windows a long
-trace internally.
-"""
-from __future__ import annotations
-
-import json
-import os
-import shutil
-import time
-from dataclasses import dataclass, field
-from typing import Any, Optional
-
-from traceforge.config import Config, repo_root_from_pkg
-from traceforge.space.hashing import fingerprint, output_hash, seed_hash
-from traceforge.space.ingest import trace_from_record
-from traceforge.space.store import (DONE, FAILED, QUEUED, REJECTED, RUNNING,
-                                    TraceStore)
-from traceforge.trace import Trace
-
-
-# ------------------------------------------------------------------- config
-
-def _env_int(name: str, default: int) -> int:
-    try:
-        return int(os.environ.get(name, "") or default)
-    except ValueError:
-        return default
-
-
-def _local_mode() -> bool:
-    """No remote endpoint and no key -> run the model on ZeroGPU."""
-    return (not (os.environ.get("TRACEFORGE_BASE_URL") or "").strip()
-            and not (os.environ.get("TRACEFORGE_LLM_KEY") or "").strip())
-
-
-def space_config(data_dir: Optional[str] = None, **overrides: Any) -> Config:
-    """A Config that needs no Hermes profile — env vars only."""
-    root = repo_root_from_pkg()
-    cfg = Config()
-    cfg.data_dir = (data_dir or os.environ.get("TRACEFORGE_DATA_DIR")
-                    or os.path.join(root, "data", "space"))
-    cfg.guidelines_path = os.path.join(root, "guidelines",
-                                       "IDEAL_TRACE_GUIDELINES.md")
-    cfg.provider = os.environ.get("TRACEFORGE_PROVIDER") or None
-    cfg.triage = True
-    cfg.splice = True
-    # The Space processes one submitted trace as one unit.
-    cfg.split_long = False
-    cfg.raw_cache = False
-    cfg.verify = False
-    cfg.review = False
-    if _local_mode():
-        # No remote endpoint: a small model on the visitor's ZeroGPU quota.
-        from traceforge.space.local_llm import (LOCAL_MODEL,
-                                                ensure_local_server, prefetch)
-        cfg.model = os.environ.get("TRACEFORGE_LOCAL_MODEL") or LOCAL_MODEL
-        cfg.triage_model = cfg.model
-        cfg.judge_model = ""
-        cfg.triage_base_url = ensure_local_server()
-        prefetch()
-        # A 3B model on a 120 s GPU slice: small windows, short outputs,
-        # one request at a time.  Every call is paid by the visitor's quota.
-        cfg.splice_max_chars = _env_int("TRACEFORGE_LOCAL_WINDOW_CHARS", 6000)
-        cfg.triage_max_chars = cfg.splice_max_chars
-        cfg.rewrite_max_tokens = _env_int("TRACEFORGE_LOCAL_REWRITE_TOKENS",
-                                          2000)
-        cfg.judge_max_tokens = _env_int("TRACEFORGE_LOCAL_JUDGE_TOKENS", 800)
-        # A 3B judge often omits answer_quality; the structural and
-        # grounding gates still run, and real violations still fail.
-        cfg.judge_require_answer_quality = False
-        cfg.judge_enabled = False
-        cfg.splice_workers = 1
-        cfg.triage_workers = 1
-        cfg.rewrite_timeout_s = _env_int("TRACEFORGE_REWRITE_TIMEOUT_S", 600)
-        cfg.judge_timeout_s = _env_int("TRACEFORGE_JUDGE_TIMEOUT_S", 600)
-    else:
-        cfg.model = os.environ.get("TRACEFORGE_MODEL") or "qwen-fable-selfhosted"
-        cfg.triage_model = (os.environ.get("TRACEFORGE_TRIAGE_MODEL")
-                            or cfg.model)
-        cfg.judge_model = os.environ.get("TRACEFORGE_JUDGE_MODEL") or ""
-        cfg.triage_base_url = (os.environ.get("TRACEFORGE_BASE_URL")
-                               or "").rstrip("/")
-        cfg.splice_workers = _env_int("TRACEFORGE_SPLICE_WORKERS", 4)
-        cfg.triage_workers = _env_int("TRACEFORGE_TRIAGE_WORKERS", 4)
-        cfg.rewrite_timeout_s = _env_int("TRACEFORGE_REWRITE_TIMEOUT_S", 300)
-        cfg.judge_timeout_s = _env_int("TRACEFORGE_JUDGE_TIMEOUT_S", 300)
-    for k, v in overrides.items():
-        setattr(cfg, k, v)
-    return cfg.resolve(root)
-
-
-def pipeline_ready(cfg: Config) -> tuple[bool, str]:
-    """(ready, reason). A Space without an endpoint must say so, not hang."""
-    from traceforge.space.local_llm import is_local_url, local_model_id
-    if is_local_url(cfg.triage_base_url):
-        return True, (f"local ZeroGPU model {local_model_id()} — GPU time is "
-                      "charged to the visitor's HF quota")
-    try:
-        from traceforge.triage import _resolve_endpoint
-        base, _key, model = _resolve_endpoint(cfg)
-    except Exception as e:  # RuntimeError from the resolver, or a bad config
-        return False, f"no LLM endpoint: {e}"
-    if not base:
-        return False, "no LLM endpoint configured (TRACEFORGE_BASE_URL)"
-    if not model:
-        return False, "no model configured (TRACEFORGE_MODEL)"
-    return True, f"{model} @ {base}"
-
-
-def _same_conversation(record: Any, improved: Trace) -> bool:
-    """True when the rewrite is the seed, message for message.
-
-    ``record`` may be the submitted dict or the raw ``Trace`` — the batch
-    passes the trace it loaded, the Space passes the stored seed.
-    """
-    try:
-        from traceforge.space.hashing import canonical_messages
-        seed = record.to_dict() if isinstance(record, Trace) else record
-        return (canonical_messages(seed) ==
-                canonical_messages(improved.to_dict()))
-    except Exception:
-        return False
-
-
-# ------------------------------------------------------- the one pipeline
-
-@dataclass
-class ProcessResult:
-    """What one trace produced. The only shape a caller has to understand."""
-
-    ok: bool
-    improved: Optional[Trace] = None
-    route: str = ""
-    attempts: int = 0
-    duration_s: float = 0.0
-    errors: list[str] = field(default_factory=list)
-    no_change: bool = False
-    task: str = ""
-    time_sensitivity: dict = field(default_factory=dict)
-    time_sensitivity_improved: dict = field(default_factory=dict)
-
-
-def _time_sensitivity(obj: Any) -> dict:
-    try:
-        from traceforge.timesensitivity import detect
-        d = detect(obj)
-        return {k: d[k] for k in ("class", "label", "temporal_facts",
-                                  "retrieval_available", "retrieval_called",
-                                  "needs_rewrite", "score")}
-    except Exception as e:
-        return {"class": "", "label": f"unavailable: {e}"}
-
-
-def process_trace(cfg: Config, trace: Trace, *, max_attempts: int = 2,
-                  seed: Any = None, reset_workdir: bool = False,
-                  label_task: bool = True,
-                  status_cb: Any = None) -> ProcessResult:
-    """THE pipeline: one trace in, one ideal trace out (or a reason).
-
-    Both the Gradio app (``SpacePipeline.process``) and the local batch
-    (``cli._improve_one``) call this, so the rewrite, the gates, the no-op
-    check and the time-sensitivity measurement exist once.
-
-    ``seed`` is the submitted record when the caller has one (the Space
-    does, and it may carry a ``tools`` array the Trace lost); the raw
-    ``trace`` is used otherwise.  ``reset_workdir`` is True for the Space,
-    where a re-queued seed must not regate a stale artifact, and False for
-    the batch, where the workdir cache is the resume mechanism.
-    """
-    started = time.time()
-    sid = trace.session_id
-    if reset_workdir:
-        shutil.rmtree(os.path.join(cfg.improver_workdir, sid),
-                      ignore_errors=True)
-
-    try:
-        from traceforge.splice import improve_trace_splice
-        raw = improve_trace_splice(cfg, trace, max_attempts=max_attempts,
-                                   status_cb=status_cb)
-        res = {"ok": raw.get("ok"), "improved": raw.get("improved"),
-               "errors": list(raw.get("errors") or []),
-               "route": raw.get("route") or "",
-               "attempts": raw.get("attempts") or 0,
-               "duration_s": raw.get("duration_s") or 0.0}
-    except Exception as e:
-        return ProcessResult(ok=False, errors=[f"pipeline crashed: {e}"],
-                             duration_s=time.time() - started)
-
-    if not res.get("ok") or res.get("improved") is None:
-        return ProcessResult(
-            ok=False, errors=list(res.get("errors") or ["no output"]),
-            route=res.get("route") or "", attempts=res.get("attempts") or 0,
-            duration_s=time.time() - started)
-
-    improved: Trace = res["improved"]
-
-    # The splice engine gates before returning; re-checking here makes the
-    # pipeline's own contract explicit and catches a regate path that
-    # bypassed the engine's gate chain.
-    try:
-        from traceforge.validate import validate_structural
-        errs = validate_structural(improved)
-    except Exception as e:
-        errs = [f"validator crashed: {e}"]
-    if not errs:
-        # The ideal must carry its own evidence: a rewrite that drops the
-        # tool result but keeps the claim passes source-grounding yet
-        # teaches the model to assert facts it never saw.
-        try:
-            from traceforge.grounding import self_grounding_errors
-            errs = self_grounding_errors(improved)
-        except Exception as e:
-            errs = [f"self-grounding check crashed: {e}"]
-    if errs:
-        return ProcessResult(
-            ok=False, errors=errs, route=res.get("route") or "",
-            attempts=res.get("attempts") or 0,
-            duration_s=time.time() - started)
-
-    # Task bucket: heuristic only — neither caller should spend an LLM call
-    # on a label the dashboard can derive for free. The batch turns this off
-    # because `traceforge classify` writes the authoritative LLM label and
-    # the benchmark prefers `trace.task` when it is set.
-    if label_task:
-        try:
-            from traceforge.classify import classify_heuristic
-            improved.task = classify_heuristic(improved).get("task") or ""
-        except Exception:
-            pass
-
-    seed_obj = seed if seed is not None else trace
-    return ProcessResult(
-        ok=True, improved=improved,
-        route=res.get("route") or "", attempts=res.get("attempts") or 0,
-        duration_s=time.time() - started,
-        no_change=_same_conversation(seed_obj, improved),
-        task=improved.task or "",
-        time_sensitivity=_time_sensitivity(seed_obj),
-        time_sensitivity_improved=_time_sensitivity(improved),
-    )
-
-
-# ----------------------------------------------------------------- pipeline
-
-class SpacePipeline:
-    """Submit / process / report, with the store as the only state."""
-
-    def __init__(self, store: TraceStore, cfg: Optional[Config] = None,
-                 *, max_attempts: int = 2):
-        self.store = store
-        self.cfg = cfg or space_config()
-        self.max_attempts = max_attempts
-
-    # ------------------------------------------------------------- submit
-
-    def submit(self, record: Any, *, sponsor: str = "",
-               source: str = "space-upload") -> dict:
-        return self.store.submit(record, sponsor=sponsor, source=source)
-
-    def submit_many(self, records: list[Any], *, sponsor: str = "",
-                    source: str = "space-sponsor") -> list[dict]:
-        out = []
-        for rec in records:
-            try:
-                out.append(self.submit(rec, sponsor=sponsor, source=source))
-            except Exception as e:
-                out.append({"hash": "", "status": "error",
-                            "error": str(e), "duplicate": False})
-        return out
-
-    # ------------------------------------------------------------ process
-
-    def process(self, h: str) -> dict:
-        """Run the pipeline for one queued hash. Never raises."""
-        rec = self.store.get(h)
-        if not rec:
-            return {"hash": h, "status": FAILED, "error": "unknown hash"}
-        if rec.get("status") == DONE:
-            return {**rec, "skipped": True}
-
-        sid = f"space-{h[:16]}"
-        started = time.time()
-        self.store.update(h, status=RUNNING, started_at=started,
-                          attempts=int(rec.get("attempts") or 0) + 1,
-                          endpoint=self.cfg.triage_base_url)
-        try:
-            record = self.store.load_seed(h)
-            from traceforge.space.local_llm import is_local_url
-            if is_local_url(self.cfg.triage_base_url):
-                size = len(json.dumps(record, ensure_ascii=False))
-                cap = _env_int("TRACEFORGE_LOCAL_MAX_CHARS", 24000)
-                if size > cap:
-                    return self._reject(
-                        h,
-                        f"local ZeroGPU mode handles seeds up to {cap // 1000} "
-                        f"KB; this one is {size // 1000} KB. Configure a "
-                        "remote endpoint for larger traces.",
-                        started)
-            trace = trace_from_record(record, fallback_id=sid,
-                                      source="space-upload")
-            trace.session_id = sid
-            trace.source = "space-upload"
-            trace.improved = False
-            trace.parent_session_id = None
-        except Exception as e:
-            return self._fail(h, [f"unparseable seed: {e}"], started)
-
-        # A fresh attempt must not regate a stale artifact from a previous
-        # run (the splice engine's stage-0 fast path would promote it as-is).
-        res = process_trace(self.cfg, trace, max_attempts=self.max_attempts,
-                            seed=record, reset_workdir=True)
-        if not res.ok or res.improved is None:
-            return self._fail(h, res.errors, started, route=res.route,
-                              attempts=res.attempts)
-
-        improved: Trace = res.improved
-        improved.session_id = sid
-        improved.parent_session_id = sid
-        improved.improved = True
-        improved.source = "traceforge-space"
-
-        # A no-op is not an ideal rewrite. The splice engine can return the
-        # seed unchanged when the writer decides nothing needs changing, and
-        # the judge accepts it because it violates nothing — but the Space
-        # would then count the input as an output. Measured on the deployed
-        # Space: a stale "current president" answer came back byte-identical
-        # in 11 s and was stored as `done`.
-        #
-        # It is not a failure either: a seed that already reads as ideal
-        # legitimately needs no edit. Record it as `no_change` so the UI can
-        # say so instead of counting it against the visitor.
-        if res.no_change:
-            return self._reject(
-                h, "no change needed: the rewrite is identical to the seed, "
-                   "so the seed already reads as an ideal trace", started,
-                route=res.route, attempts=res.attempts,
-                time_sensitivity=res.time_sensitivity, no_change=True,
-            )
-
-        self.store.put_output(h, improved)
-        duration = time.time() - started
-        row = self.store.update(
-            h, status=DONE, finished_at=time.time(), duration_s=round(duration, 1),
-            output_hash=output_hash(improved),
-            route=res.route,
-            attempts=res.attempts,
-            n_messages_out=len(improved.messages),
-            task=res.task or rec.get("task") or "",
-            time_sensitivity=res.time_sensitivity,
-            time_sensitivity_improved=res.time_sensitivity_improved,
-            error="",
-        )
-        return row
-
-    def _fail(self, h: str, errors: list[str], started: float, *,
-              route: Optional[str] = None, attempts: Any = None) -> dict:
-        msg = "; ".join(str(e) for e in errors)[:1200]
-        return self.store.update(
-            h, status=FAILED, finished_at=time.time(),
-            duration_s=round(time.time() - started, 1),
-            route=route or "", attempts=attempts or 0, error=msg,
-        )
-
-    def _reject(self, h: str, reason: str, started: float, *,
-                route: Optional[str] = None, attempts: Any = None,
-                **extra: Any) -> dict:
-        """A pipeline outcome that is not a failure and not an output."""
-        return self.store.update(
-            h, status=REJECTED, finished_at=time.time(),
-            duration_s=round(time.time() - started, 1),
-            route=route or "", attempts=attempts or 0, error=reason, **extra,
-        )
-
-    # -------------------------------------------------------------- report
-
-    def result(self, h: str) -> dict:
-        """Everything the UI needs about one hash."""
-        rec = self.store.get(h) or {"hash": h, "status": "unknown"}
-        out = self.store.load_output(h)
-        rec = dict(rec)
-        rec["has_output"] = out is not None
-        if out is not None:
-            rec["output_messages"] = len(out.messages)
-        return rec
+"""The pipeline behind the web UI.
+
+`SpacePipeline` is the only thing the Gradio app talks to. It wraps the
+windowed splice engine (`improve_trace_splice`) so a trace that arrives as
+JSON — not as a session id in a local store — can be processed:
+
+    submit(record)      hash -> dedupe -> enqueue (idempotent)
+    process(hash)       run triage + rewrite + gates, store the output
+
+Configuration is environment-only, because a Space has no `~/.hermes`:
+
+    TRACEFORGE_BASE_URL      OpenAI-compatible endpoint (…/v1)
+    TRACEFORGE_LLM_KEY       bearer token
+    TRACEFORGE_MODEL         writer/judge model id
+    TRACEFORGE_TRIAGE_MODEL  cheap labeler (default: TRACEFORGE_MODEL)
+    TRACEFORGE_JUDGE_MODEL   judge override (default: TRACEFORGE_MODEL)
+    TRACEFORGE_DATA_DIR      store root (default: <repo>/data/space)
+
+`split_long` is deliberately OFF: splitting one submitted seed into N
+segments would produce N outputs for one hash, which is exactly what the
+one-seed-one-output rule forbids. The splice engine already windows a long
+trace internally.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from traceforge.config import Config, repo_root_from_pkg
+from traceforge.space.hashing import fingerprint, output_hash, seed_hash
+from traceforge.space.ingest import trace_from_record
+from traceforge.space.store import (DONE, FAILED, QUEUED, REJECTED, RUNNING,
+                                    TraceStore)
+from traceforge.trace import Trace
+
+
+# ------------------------------------------------------------------- config
+
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(name, "") or default)
+    except ValueError:
+        return default
+
+
+def _local_mode() -> bool:
+    """No remote endpoint and no key -> run the model on ZeroGPU."""
+    return (not (os.environ.get("TRACEFORGE_BASE_URL") or "").strip()
+            and not (os.environ.get("TRACEFORGE_LLM_KEY") or "").strip())
+
+
+def space_config(data_dir: Optional[str] = None, **overrides: Any) -> Config:
+    """A Config that needs no Hermes profile — env vars only."""
+    root = repo_root_from_pkg()
+    cfg = Config()
+    cfg.data_dir = (data_dir or os.environ.get("TRACEFORGE_DATA_DIR")
+                    or os.path.join(root, "data", "space"))
+    cfg.guidelines_path = os.path.join(root, "guidelines",
+                                       "IDEAL_TRACE_GUIDELINES.md")
+    cfg.provider = os.environ.get("TRACEFORGE_PROVIDER") or None
+    cfg.triage = True
+    cfg.splice = True
+    # The Space processes one submitted trace as one unit.
+    cfg.split_long = False
+    cfg.raw_cache = False
+    cfg.verify = False
+    cfg.review = False
+    if _local_mode():
+        # No remote endpoint: LFM2.5-24B-A2B on the visitor's ZeroGPU quota.
+        from traceforge.space.local_llm import (LOCAL_MODEL,
+                                                ensure_local_server, prefetch)
+        cfg.model = os.environ.get("TRACEFORGE_LOCAL_MODEL") or LOCAL_MODEL
+        cfg.triage_model = cfg.model
+        cfg.judge_model = ""
+        cfg.triage_base_url = ensure_local_server()
+        prefetch()
+        # One 120 s xlarge slice per call, paid by the visitor's quota: small
+        # windows, one request at a time.  The model always thinks before it
+        # answers, so the rewrite budget has to cover reasoning *and* JSON.
+        cfg.splice_max_chars = _env_int("TRACEFORGE_LOCAL_WINDOW_CHARS", 6000)
+        cfg.triage_max_chars = cfg.splice_max_chars
+        cfg.rewrite_max_tokens = _env_int("TRACEFORGE_LOCAL_REWRITE_TOKENS",
+                                          3000)
+        cfg.judge_max_tokens = _env_int("TRACEFORGE_LOCAL_JUDGE_TOKENS", 1200)
+        # The LLM judge stays off in local mode: it doubles the visitor's
+        # quota cost per trace.  The structural, grounding and identity gates
+        # still run, and real violations still fail.
+        cfg.judge_require_answer_quality = False
+        cfg.judge_enabled = False
+        cfg.splice_workers = 1
+        cfg.triage_workers = 1
+        cfg.rewrite_timeout_s = _env_int("TRACEFORGE_REWRITE_TIMEOUT_S", 600)
+        cfg.judge_timeout_s = _env_int("TRACEFORGE_JUDGE_TIMEOUT_S", 600)
+    else:
+        cfg.model = os.environ.get("TRACEFORGE_MODEL") or "qwen-fable-selfhosted"
+        cfg.triage_model = (os.environ.get("TRACEFORGE_TRIAGE_MODEL")
+                            or cfg.model)
+        cfg.judge_model = os.environ.get("TRACEFORGE_JUDGE_MODEL") or ""
+        cfg.triage_base_url = (os.environ.get("TRACEFORGE_BASE_URL")
+                               or "").rstrip("/")
+        cfg.splice_workers = _env_int("TRACEFORGE_SPLICE_WORKERS", 4)
+        cfg.triage_workers = _env_int("TRACEFORGE_TRIAGE_WORKERS", 4)
+        cfg.rewrite_timeout_s = _env_int("TRACEFORGE_REWRITE_TIMEOUT_S", 300)
+        cfg.judge_timeout_s = _env_int("TRACEFORGE_JUDGE_TIMEOUT_S", 300)
+    for k, v in overrides.items():
+        setattr(cfg, k, v)
+    return cfg.resolve(root)
+
+
+def pipeline_ready(cfg: Config) -> tuple[bool, str]:
+    """(ready, reason). A Space without an endpoint must say so, not hang."""
+    from traceforge.space.local_llm import is_local_url, local_model_id
+    if is_local_url(cfg.triage_base_url):
+        return True, (f"local ZeroGPU model {local_model_id()} — GPU time is "
+                      "charged to the visitor's HF quota")
+    try:
+        from traceforge.triage import _resolve_endpoint
+        base, _key, model = _resolve_endpoint(cfg)
+    except Exception as e:  # RuntimeError from the resolver, or a bad config
+        return False, f"no LLM endpoint: {e}"
+    if not base:
+        return False, "no LLM endpoint configured (TRACEFORGE_BASE_URL)"
+    if not model:
+        return False, "no model configured (TRACEFORGE_MODEL)"
+    return True, f"{model} @ {base}"
+
+
+def _same_conversation(record: Any, improved: Trace) -> bool:
+    """True when the rewrite is the seed, message for message.
+
+    ``record`` may be the submitted dict or the raw ``Trace`` — the batch
+    passes the trace it loaded, the Space passes the stored seed.
+    """
+    try:
+        from traceforge.space.hashing import canonical_messages
+        seed = record.to_dict() if isinstance(record, Trace) else record
+        return (canonical_messages(seed) ==
+                canonical_messages(improved.to_dict()))
+    except Exception:
+        return False
+
+
+# ------------------------------------------------------- the one pipeline
+
+@dataclass
+class ProcessResult:
+    """What one trace produced. The only shape a caller has to understand."""
+
+    ok: bool
+    improved: Optional[Trace] = None
+    route: str = ""
+    attempts: int = 0
+    duration_s: float = 0.0
+    errors: list[str] = field(default_factory=list)
+    no_change: bool = False
+    task: str = ""
+    time_sensitivity: dict = field(default_factory=dict)
+    time_sensitivity_improved: dict = field(default_factory=dict)
+
+
+def _time_sensitivity(obj: Any) -> dict:
+    try:
+        from traceforge.timesensitivity import detect
+        d = detect(obj)
+        return {k: d[k] for k in ("class", "label", "temporal_facts",
+                                  "retrieval_available", "retrieval_called",
+                                  "needs_rewrite", "score")}
+    except Exception as e:
+        return {"class": "", "label": f"unavailable: {e}"}
+
+
+def process_trace(cfg: Config, trace: Trace, *, max_attempts: int = 2,
+                  seed: Any = None, reset_workdir: bool = False,
+                  label_task: bool = True,
+                  status_cb: Any = None) -> ProcessResult:
+    """THE pipeline: one trace in, one ideal trace out (or a reason).
+
+    Both the Gradio app (``SpacePipeline.process``) and the local batch
+    (``cli._improve_one``) call this, so the rewrite, the gates, the no-op
+    check and the time-sensitivity measurement exist once.
+
+    ``seed`` is the submitted record when the caller has one (the Space
+    does, and it may carry a ``tools`` array the Trace lost); the raw
+    ``trace`` is used otherwise.  ``reset_workdir`` is True for the Space,
+    where a re-queued seed must not regate a stale artifact, and False for
+    the batch, where the workdir cache is the resume mechanism.
+    """
+    started = time.time()
+    sid = trace.session_id
+    if reset_workdir:
+        shutil.rmtree(os.path.join(cfg.improver_workdir, sid),
+                      ignore_errors=True)
+
+    try:
+        from traceforge.splice import improve_trace_splice
+        raw = improve_trace_splice(cfg, trace, max_attempts=max_attempts,
+                                   status_cb=status_cb)
+        res = {"ok": raw.get("ok"), "improved": raw.get("improved"),
+               "errors": list(raw.get("errors") or []),
+               "route": raw.get("route") or "",
+               "attempts": raw.get("attempts") or 0,
+               "duration_s": raw.get("duration_s") or 0.0}
+    except Exception as e:
+        return ProcessResult(ok=False, errors=[f"pipeline crashed: {e}"],
+                             duration_s=time.time() - started)
+
+    if not res.get("ok") or res.get("improved") is None:
+        return ProcessResult(
+            ok=False, errors=list(res.get("errors") or ["no output"]),
+            route=res.get("route") or "", attempts=res.get("attempts") or 0,
+            duration_s=time.time() - started)
+
+    improved: Trace = res["improved"]
+
+    # The splice engine gates before returning; re-checking here makes the
+    # pipeline's own contract explicit and catches a regate path that
+    # bypassed the engine's gate chain.
+    try:
+        from traceforge.validate import validate_structural
+        errs = validate_structural(improved)
+    except Exception as e:
+        errs = [f"validator crashed: {e}"]
+    if not errs:
+        # The ideal must carry its own evidence: a rewrite that drops the
+        # tool result but keeps the claim passes source-grounding yet
+        # teaches the model to assert facts it never saw.
+        try:
+            from traceforge.grounding import self_grounding_errors
+            errs = self_grounding_errors(improved)
+        except Exception as e:
+            errs = [f"self-grounding check crashed: {e}"]
+    if errs:
+        return ProcessResult(
+            ok=False, errors=errs, route=res.get("route") or "",
+            attempts=res.get("attempts") or 0,
+            duration_s=time.time() - started)
+
+    # Task bucket: heuristic only — neither caller should spend an LLM call
+    # on a label the dashboard can derive for free. The batch turns this off
+    # because `traceforge classify` writes the authoritative LLM label and
+    # the benchmark prefers `trace.task` when it is set.
+    if label_task:
+        try:
+            from traceforge.classify import classify_heuristic
+            improved.task = classify_heuristic(improved).get("task") or ""
+        except Exception:
+            pass
+
+    seed_obj = seed if seed is not None else trace
+    return ProcessResult(
+        ok=True, improved=improved,
+        route=res.get("route") or "", attempts=res.get("attempts") or 0,
+        duration_s=time.time() - started,
+        no_change=_same_conversation(seed_obj, improved),
+        task=improved.task or "",
+        time_sensitivity=_time_sensitivity(seed_obj),
+        time_sensitivity_improved=_time_sensitivity(improved),
+    )
+
+
+# ----------------------------------------------------------------- pipeline
+
+class SpacePipeline:
+    """Submit / process / report, with the store as the only state."""
+
+    def __init__(self, store: TraceStore, cfg: Optional[Config] = None,
+                 *, max_attempts: int = 2):
+        self.store = store
+        self.cfg = cfg or space_config()
+        self.max_attempts = max_attempts
+
+    # ------------------------------------------------------------- submit
+
+    def submit(self, record: Any, *, sponsor: str = "",
+               source: str = "space-upload") -> dict:
+        return self.store.submit(record, sponsor=sponsor, source=source)
+
+    def submit_many(self, records: list[Any], *, sponsor: str = "",
+                    source: str = "space-sponsor") -> list[dict]:
+        out = []
+        for rec in records:
+            try:
+                out.append(self.submit(rec, sponsor=sponsor, source=source))
+            except Exception as e:
+                out.append({"hash": "", "status": "error",
+                            "error": str(e), "duplicate": False})
+        return out
+
+    # ------------------------------------------------------------ process
+
+    def process(self, h: str) -> dict:
+        """Run the pipeline for one queued hash. Never raises."""
+        rec = self.store.get(h)
+        if not rec:
+            return {"hash": h, "status": FAILED, "error": "unknown hash"}
+        if rec.get("status") == DONE:
+            return {**rec, "skipped": True}
+
+        sid = f"space-{h[:16]}"
+        started = time.time()
+        self.store.update(h, status=RUNNING, started_at=started,
+                          attempts=int(rec.get("attempts") or 0) + 1,
+                          endpoint=self.cfg.triage_base_url)
+        try:
+            record = self.store.load_seed(h)
+            from traceforge.space.local_llm import is_local_url
+            if is_local_url(self.cfg.triage_base_url):
+                size = len(json.dumps(record, ensure_ascii=False))
+                cap = _env_int("TRACEFORGE_LOCAL_MAX_CHARS", 24000)
+                if size > cap:
+                    return self._reject(
+                        h,
+                        f"local ZeroGPU mode handles seeds up to {cap // 1000} "
+                        f"KB; this one is {size // 1000} KB. Configure a "
+                        "remote endpoint for larger traces.",
+                        started)
+            trace = trace_from_record(record, fallback_id=sid,
+                                      source="space-upload")
+            trace.session_id = sid
+            trace.source = "space-upload"
+            trace.improved = False
+            trace.parent_session_id = None
+        except Exception as e:
+            return self._fail(h, [f"unparseable seed: {e}"], started)
+
+        # A fresh attempt must not regate a stale artifact from a previous
+        # run (the splice engine's stage-0 fast path would promote it as-is).
+        res = process_trace(self.cfg, trace, max_attempts=self.max_attempts,
+                            seed=record, reset_workdir=True)
+        if not res.ok or res.improved is None:
+            return self._fail(h, res.errors, started, route=res.route,
+                              attempts=res.attempts)
+
+        improved: Trace = res.improved
+        improved.session_id = sid
+        improved.parent_session_id = sid
+        improved.improved = True
+        improved.source = "traceforge-space"
+
+        # A no-op is not an ideal rewrite. The splice engine can return the
+        # seed unchanged when the writer decides nothing needs changing, and
+        # the judge accepts it because it violates nothing — but the Space
+        # would then count the input as an output. Measured on the deployed
+        # Space: a stale "current president" answer came back byte-identical
+        # in 11 s and was stored as `done`.
+        #
+        # It is not a failure either: a seed that already reads as ideal
+        # legitimately needs no edit. Record it as `no_change` so the UI can
+        # say so instead of counting it against the visitor.
+        if res.no_change:
+            return self._reject(
+                h, "no change needed: the rewrite is identical to the seed, "
+                   "so the seed already reads as an ideal trace", started,
+                route=res.route, attempts=res.attempts,
+                time_sensitivity=res.time_sensitivity, no_change=True,
+            )
+
+        self.store.put_output(h, improved)
+        duration = time.time() - started
+        row = self.store.update(
+            h, status=DONE, finished_at=time.time(), duration_s=round(duration, 1),
+            output_hash=output_hash(improved),
+            route=res.route,
+            attempts=res.attempts,
+            n_messages_out=len(improved.messages),
+            task=res.task or rec.get("task") or "",
+            time_sensitivity=res.time_sensitivity,
+            time_sensitivity_improved=res.time_sensitivity_improved,
+            error="",
+        )
+        return row
+
+    def _fail(self, h: str, errors: list[str], started: float, *,
+              route: Optional[str] = None, attempts: Any = None) -> dict:
+        msg = "; ".join(str(e) for e in errors)[:1200]
+        return self.store.update(
+            h, status=FAILED, finished_at=time.time(),
+            duration_s=round(time.time() - started, 1),
+            route=route or "", attempts=attempts or 0, error=msg,
+        )
+
+    def _reject(self, h: str, reason: str, started: float, *,
+                route: Optional[str] = None, attempts: Any = None,
+                **extra: Any) -> dict:
+        """A pipeline outcome that is not a failure and not an output."""
+        return self.store.update(
+            h, status=REJECTED, finished_at=time.time(),
+            duration_s=round(time.time() - started, 1),
+            route=route or "", attempts=attempts or 0, error=reason, **extra,
+        )
+
+    # -------------------------------------------------------------- report
+
+    def result(self, h: str) -> dict:
+        """Everything the UI needs about one hash."""
+        rec = self.store.get(h) or {"hash": h, "status": "unknown"}
+        out = self.store.load_output(h)
+        rec = dict(rec)
+        rec["has_output"] = out is not None
+        if out is not None:
+            rec["output_messages"] = len(out.messages)
+        return rec

traceforge/synth.py

@@ -0,0 +1,634 @@
+"""Synthetic traces from scratch, to fill the balance gaps.
+
+The pipeline rewrites traces that already exist. It cannot invent a German
+`data-analysis` session, because no such session was ever recorded — and that
+is exactly the hole the balance report measures. This module fills it:
+
+    plan     read the balance gap -> the (language, task, difficulty) cells
+    tasks    an LLM writes a SELF-CONTAINED task per cell, plus the starter
+             files it operates on (no dependency on the owner's repos)
+    run      a real agent executes the task in a throwaway workspace, so the
+             tool calls and their results are real, not fabricated
+    ingest   the captured session becomes a raw trace, and the existing
+             triage -> improve -> gate chain takes it from there
+
+Why execute instead of writing the trace directly: the gate chain rejects
+fabricated tool results (`self_grounding_errors`), and it is right to. A
+synthetic trace is only worth having if an agent actually ran the commands.
+That is also why this is expensive — one task is one agent session — and why
+the plan is targeted at the cells with the largest deficit instead of
+generating uniformly.
+
+State is an append-only journal (`data/synth/tasks.jsonl`, last row per id
+wins), so a killed run resumes: `run` picks up `pending` and re-queues
+`running` rows whose workspace has no captured trace.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any, Optional
+
+from traceforge import balance as bal
+from traceforge.classify import LANGUAGE_NAMES, TASKS
+from traceforge.difficulty import label as band_label
+
+# --------------------------------------------------------------- constants
+
+# How many tool calls each band should take. The generator gets this as a
+# concrete instruction ("aim for 6-10 tool calls"), because "make it hard" is
+# not actionable and produces either a one-liner or an unbounded epic.
+BAND_HINT = {
+    "D1": "1-2 tool calls: a single lookup or one edit",
+    "D2": "3-5 tool calls: read a file, change it, verify",
+    "D3": "6-10 tool calls: several files, a command run, a fix",
+    "D4": "11-20 tool calls: a small project, tests, an iteration",
+    "D5": "21+ tool calls: a multi-stage task with verification loops",
+}
+
+# A task must be runnable in an empty directory with only the files the
+# generator provides. These are the shapes that work; anything that needs the
+# owner's repos, credentials or the network is out of scope.
+TASK_SHAPES = {
+    "debug": "a small program that fails, with the failure reproducible from "
+             "the provided files",
+    "implement": "a small feature to add to the provided starter code",
+    "refactor": "existing code to restructure without changing behaviour",
+    "test": "code that needs tests written and run",
+    "review": "a diff or module to audit read-only, with findings to report",
+    "research": "a question answerable from the provided documents (or from "
+                "web search when the agent has it)",
+    "data-analysis": "a CSV/JSON dataset to analyse and summarise",
+    "ops": "a service/config to set up, run and verify locally",
+    "office-docs": "a spreadsheet/deck/document to produce from given data",
+    "creative": "a writing or design brief with a concrete deliverable",
+    "other": "a general task that does not fit the other buckets",
+}
+
+_SAFE_PATH_RE = re.compile(r"^[A-Za-z0-9._/-]+$")
+
+
+# ------------------------------------------------------------------- specs
+
+
+@dataclass
+class TaskSpec:
+    """One synthetic task: what to ask, what to start from, where it stands."""
+
+    id: str
+    language: str
+    task: str
+    difficulty: str
+    prompt: str
+    files: dict[str, str] = field(default_factory=dict)
+    status: str = "pending"          # pending|running|done|failed|rejected
+    session_id: Optional[str] = None
+    error: Optional[str] = None
+    created_at: str = ""
+    finished_at: Optional[str] = None
+    duration_s: Optional[float] = None
+    turns: Optional[int] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "TaskSpec":
+        known = {f for f in cls.__dataclass_fields__}
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+
+def _now() -> str:
+    import datetime
+
+    return datetime.datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def synth_dir(cfg) -> str:
+    return os.path.join(cfg.data_dir, "synth")
+
+
+def store_path(cfg) -> str:
+    return os.path.join(synth_dir(cfg), "tasks.jsonl")
+
+
+def ws_root(cfg) -> str:
+    """Where task workspaces live — OUTSIDE the repo by default.
+
+    The executor runs an agent with `--yolo` in this directory. Putting it
+    under `data/` would let a confused agent `cd ..` into the corpus and
+    rewrite it, so the default is a sibling of the repo's parent. Override
+    with `synth_ws_root` in the config.
+    """
+    configured = getattr(cfg, "synth_ws_root", "") or ""
+    if configured:
+        return os.path.expanduser(configured)
+    return os.path.expanduser(os.path.join("~", "traceforge-synth", "ws"))
+
+
+def runs_dir(cfg) -> str:
+    return os.path.join(synth_dir(cfg), "runs")
+
+
+def load_specs(cfg) -> dict[str, TaskSpec]:
+    """Last row per id wins — the journal is append-only."""
+    out: dict[str, TaskSpec] = {}
+    path = store_path(cfg)
+    if not os.path.exists(path):
+        return out
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            spec = TaskSpec.from_dict(row)
+            if spec.id:
+                out[spec.id] = spec
+    return out
+
+
+def append_spec(cfg, spec: TaskSpec) -> None:
+    os.makedirs(synth_dir(cfg), exist_ok=True)
+    with open(store_path(cfg), "a", encoding="utf-8") as f:
+        f.write(json.dumps(spec.to_dict(), ensure_ascii=False) + "\n")
+
+
+# ------------------------------------------------------------ task writing
+
+_TASK_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "prompt": {"type": "string"},
+        "files": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "content": {"type": "string"},
+                },
+                "required": ["path", "content"],
+            },
+        },
+        "why": {"type": "string"},
+    },
+    "required": ["prompt", "files"],
+}
+
+
+def _task_prompt(language: str, task: str, difficulty: str,
+                 avoid: list[str]) -> str:
+    lang_name = LANGUAGE_NAMES.get(language, language)
+    avoid_block = ""
+    if avoid:
+        avoid_block = (
+            "\nDo NOT repeat or lightly reword any of these existing tasks:\n"
+            + "\n".join(f"- {a}" for a in avoid[:12])
+        )
+    return (
+        "Write ONE self-contained agent task that a coding agent can complete "
+        "in an empty directory, using only the files you provide.\n\n"
+        f"Language: write the task prompt in {lang_name}. Every sentence the "
+        f"user would say is in {lang_name}; file contents and code may be in "
+        "any language, but prefer "
+        f"{lang_name} for prose inside the files.\n"
+        f"Task bucket: {task} — {TASK_SHAPES.get(task, '')}\n"
+        f"Difficulty: {BAND_HINT.get(difficulty, difficulty)} "
+        f"({band_label(difficulty)})\n\n"
+        "Hard requirements:\n"
+        "- The task must be completable offline in a fresh directory with only "
+        "the files you provide. No credentials, no private repos, no services "
+        "that need the internet.\n"
+        "- It must require REAL tool use: reading files, running commands, "
+        "editing code, or producing a file. A task answerable from memory is "
+        "useless.\n"
+        "- It must have a verifiable deliverable the agent can check itself "
+        "(a passing test, a file that exists, a command that exits 0).\n"
+        "- Provide 1-6 starter files with real, coherent content — enough that "
+        "the task is concrete, not a blank page. Keep each file under 120 "
+        "lines.\n"
+        "- Starter files must be syntactically valid and self-consistent: no "
+        "truncated imports, no placeholder bodies, no test that cannot run. If "
+        "the task is to FIX a bug, the failure must be a runtime failure the "
+        "agent can reproduce, never a syntax error in your own scaffold.\n"
+        "- The prompt is what the USER types: state the goal and the "
+        "constraints, not the steps. Do not write the solution.\n"
+        "- Paths are relative, no '..', no absolute paths.\n"
+        f"{avoid_block}\n"
+        "Answer with JSON only: {\"prompt\": str, \"files\": [{\"path\": str, "
+        "\"content\": str}], \"why\": str}."
+    )
+
+
+def _clean_files(raw: Any) -> dict[str, str]:
+    """Validate generated starter files: relative, safe, bounded."""
+    files: dict[str, str] = {}
+    if not isinstance(raw, list):
+        return files
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        path = str(item.get("path") or "").strip().lstrip("./")
+        content = item.get("content")
+        if not path or not isinstance(content, str):
+            continue
+        if not _SAFE_PATH_RE.match(path) or ".." in path.split("/"):
+            continue
+        if len(content) > 60_000:
+            continue
+        files[path] = content
+    return files
+
+
+def _similar(a: str, b: str) -> float:
+    import difflib
+
+    return difflib.SequenceMatcher(None, a[:600].lower(), b[:600].lower()).ratio()
+
+
+def existing_task_texts(cfg, limit: int = 1200) -> list[str]:
+    """First user message of the corpus, for dedup. Sampled, not exhaustive."""
+    path = os.path.join(cfg.data_dir, "dataset", "train.jsonl")
+    if not os.path.exists(path):
+        return []
+    texts: list[str] = []
+    step = 1
+    try:
+        total = sum(1 for _ in open(path, "rb"))
+        step = max(1, total // limit)
+    except OSError:
+        pass
+    with open(path, "r", encoding="utf-8") as f:
+        for i, line in enumerate(f):
+            if i % step:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            first = next((m.get("content") or "" for m in row.get("messages") or []
+                          if m.get("role") == "user"), "")
+            if first:
+                texts.append(first[:600])
+            if len(texts) >= limit:
+                break
+    return texts
+
+
+def generate_tasks(
+    cfg,
+    policy: bal.BalancePolicy,
+    cells: int = 0,
+    per_cell: int = 1,
+    model: Optional[str] = None,
+) -> list[TaskSpec]:
+    """Ask the LLM for one task per (cell, slot) and journal the specs."""
+    from traceforge import triage
+
+    base, key, default_model = triage._resolve_endpoint(cfg)
+    model = model or default_model
+    rep, cen = _report(cfg, policy)
+    work = bal.plan(rep, policy, limit=cells or None)
+    if not work:
+        print("  no under-target cell — nothing to generate")
+        return []
+    avoid = existing_task_texts(cfg)
+    specs: list[TaskSpec] = []
+    for cell in work:
+        for slot in range(per_cell):
+            band = _pick_band(cell["difficulty_mix"])
+            prompt = _task_prompt(cell["language"], cell["task"], band, avoid)
+            payload = {
+                "model": model,
+                "messages": [
+                    {"role": "system",
+                     "content": "You design agent training tasks. Answer with "
+                                "JSON only."},
+                    {"role": "user", "content": prompt},
+                ],
+                "temperature": 0.9,
+                "max_tokens": 4000,
+                "response_format": {
+                    "type": "json_schema",
+                    "json_schema": {"name": "synth_task",
+                                    "schema": _TASK_SCHEMA, "strict": True},
+                },
+            }
+            try:
+                data = triage._post_json(
+                    triage._chat_url(base), payload, key, cfg.triage_timeout_s)
+                obj = json.loads(triage._extract_content(data) or "{}")
+            except Exception as e:
+                print(f"  ! {cell['language']}/{cell['task']}: {e}")
+                continue
+            text = str(obj.get("prompt") or "").strip()
+            files = _clean_files(obj.get("files"))
+            if len(text) < 40 or not files:
+                print(f"  ! {cell['language']}/{cell['task']}: rejected "
+                      f"(prompt {len(text)} chars, {len(files)} file(s))")
+                continue
+            if any(_similar(text, a) > 0.8 for a in avoid):
+                print(f"  ! {cell['language']}/{cell['task']}: rejected "
+                      f"(near-duplicate of an existing task)")
+                continue
+            spec = TaskSpec(
+                id=f"synth-{uuid.uuid4().hex[:12]}",
+                language=cell["language"],
+                task=cell["task"],
+                difficulty=band,
+                prompt=text,
+                files=files,
+                status="pending",
+                created_at=_now(),
+            )
+            append_spec(cfg, spec)
+            specs.append(spec)
+            avoid.append(text[:600])
+            print(f"  + {spec.id}  {spec.language}/{spec.task} "
+                  f"{spec.difficulty}  {len(files)} file(s), "
+                  f"{len(text)} chars")
+    return specs
+
+
+def _pick_band(mix: dict[str, float]) -> str:
+    """Deterministic draw from the difficulty deficit mix (no RNG: the band
+    with the largest remaining deficit wins, so a batch spreads out)."""
+    if not mix:
+        return "D3"
+    return max(mix.items(), key=lambda kv: kv[1])[0]
+
+
+# -------------------------------------------------------------- execution
+
+
+def _hermes_bin() -> str:
+    exe = shutil.which("hermes")
+    if not exe:
+        raise RuntimeError("hermes CLI not found on PATH — the executor needs "
+                           "it to run a task for real")
+    return exe
+
+
+def materialize(cfg, spec: TaskSpec) -> str:
+    """Write the starter files into a fresh workspace and return its path.
+
+    NOTE (2026-10-29): a fresh HOST dir is not a fresh CONTAINER dir. The
+    executor's cwd is a fixed container path (`/data/agent/choucisan`) that
+    persists across tasks, so a task writing a file whose name an earlier task
+    already used gets `File has not been read yet`, falls back to `cat >` or
+    edits the stale file, and the captured trace then describes classes the
+    task never mentioned. Measured on the synth cohort: 494 raws / 393
+    attempted / 116 promoted = 29.5%, with refactoring 7.1% (2/28), debugging
+    6.7% (1/15) and hf_trace 0% (0/17); 3 of 3 sampled failures traced to a
+    stale file (a refactor task's inline `DataProcessor` was replaced by a
+    previous task's `data_processor.py`). Clear the container dir before each
+    run, or give each task a unique container path. Suite rule R-110.
+    """
+    ws = os.path.join(ws_root(cfg), spec.id)
+    if os.path.isdir(ws):
+        shutil.rmtree(ws, ignore_errors=True)
+    os.makedirs(ws, exist_ok=True)
+    for rel, content in spec.files.items():
+        dest = os.path.join(ws, *rel.split("/"))
+        os.makedirs(os.path.dirname(dest) or ws, exist_ok=True)
+        with open(dest, "w", encoding="utf-8", newline="\n") as f:
+            f.write(content)
+    return ws
+
+
+def _find_session(state_db: str, cwd: str, since: float) -> Optional[str]:
+    """The session the executor just created: newest session in this cwd.
+
+    The cwd is unique per task, so it is the discriminator — `--source synth`
+    would be cleaner but any non-default source tag makes the Hermes CLI fail
+    its model connection ("invalid_params"), so the executor runs with the
+    default source and the workspace path carries the provenance instead.
+    """
+    import sqlite3
+
+    if not os.path.exists(state_db):
+        return None
+    con = sqlite3.connect(f"file:{state_db}?mode=ro", uri=True)
+    try:
+        row = con.execute(
+            "SELECT id FROM sessions WHERE cwd=? AND started_at >= ? "
+            "ORDER BY started_at DESC LIMIT 1",
+            (cwd, since),
+        ).fetchone()
+        return row[0] if row else None
+    finally:
+        con.close()
+
+
+def execute_task(
+    cfg,
+    spec: TaskSpec,
+    max_turns: int = 40,
+    timeout: int = 1800,
+    model: Optional[str] = None,
+    provider: Optional[str] = None,
+) -> TaskSpec:
+    """Run one task with a real agent and capture the session as a raw trace."""
+    from traceforge.readers.hermes import HermesTraceReader
+
+    ws = materialize(cfg, spec)
+    spec.status = "running"
+    spec.error = None
+    append_spec(cfg, spec)
+    started = time.time()
+    cmd = [
+        _hermes_bin(), "chat", "--oneshot",
+        "--in", ws,
+        "--max-turns", str(max_turns),
+        "--format", "text",
+        "--yolo",
+    ]
+    if model:
+        cmd += ["-m", model]
+    if provider:
+        cmd += ["--provider", provider]
+    cmd += ["-q", spec.prompt]
+    try:
+        proc = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=timeout,
+            encoding="utf-8", errors="replace",
+        )
+        rc = proc.returncode
+    except subprocess.TimeoutExpired:
+        spec.status = "failed"
+        spec.error = f"timeout after {timeout}s"
+        spec.finished_at = _now()
+        spec.duration_s = round(time.time() - started, 1)
+        append_spec(cfg, spec)
+        return spec
+    sid = _find_session(cfg.state_db, ws, started - 5)
+    if not sid:
+        spec.status = "failed"
+        spec.error = (f"no session captured (exit {rc}); "
+                      f"stderr: {(proc.stderr or '')[-300:]}")
+        spec.finished_at = _now()
+        spec.duration_s = round(time.time() - started, 1)
+        append_spec(cfg, spec)
+        return spec
+    try:
+        trace = HermesTraceReader([cfg.state_db]).load_trace(sid)
+    except Exception as e:
+        spec.status = "failed"
+        spec.error = f"session {sid} could not be read: {e}"
+        spec.finished_at = _now()
+        append_spec(cfg, spec)
+        return spec
+    os.makedirs(runs_dir(cfg), exist_ok=True)
+    trace.save(os.path.join(runs_dir(cfg), f"{spec.id}.json"))
+    spec.session_id = sid
+    spec.status = "done"
+    spec.turns = sum(1 for m in trace.messages if m.tool_calls)
+    spec.finished_at = _now()
+    spec.duration_s = round(time.time() - started, 1)
+    append_spec(cfg, spec)
+    return spec
+
+
+def ingest(cfg, specs: Optional[dict[str, TaskSpec]] = None) -> int:
+    """Copy captured runs into data/traces/raw/ so the pipeline picks them up."""
+    from traceforge.trace import Trace
+
+    specs = specs if specs is not None else load_specs(cfg)
+    os.makedirs(cfg.raw_dir, exist_ok=True)
+    n = 0
+    for spec in specs.values():
+        if spec.status != "done" or not spec.session_id:
+            continue
+        src = os.path.join(runs_dir(cfg), f"{spec.id}.json")
+        if not os.path.exists(src):
+            continue
+        dest = os.path.join(cfg.raw_dir, f"{spec.session_id}.json")
+        if os.path.exists(dest):
+            continue
+        trace = Trace.load(src)
+        trace.save(dest)
+        n += 1
+    return n
+
+
+# -------------------------------------------------------------------- CLI
+
+
+def _report(cfg, policy: bal.BalancePolicy):
+    path = os.path.join(cfg.data_dir, "dataset", "train.jsonl")
+    labels = bal.load_labels(os.path.join(cfg.data_dir, "tasks.jsonl"))
+    records = []
+    if os.path.exists(path):
+        with open(path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    records.append(json.loads(line))
+    cen = bal.census(records, labels)
+    return bal.report(cen, policy), cen
+
+
+def _policy(args) -> bal.BalancePolicy:
+    return bal.BalancePolicy.load(getattr(args, "policy", None) or bal.POLICY_PATH)
+
+
+def cli_plan(cfg, args) -> int:
+    policy = _policy(args)
+    rep, cen = _report(cfg, policy)
+    rows = bal.plan(rep, policy, limit=getattr(args, "cells", 0) or None)
+    print(bal.format_report(rep, top=0))
+    print()
+    print(bal.format_plan(rows, limit=40,
+                          fill=bal.fill_to(cen, policy),
+                          grow=bal.converge(cen, policy)))
+    return 0
+
+
+def cli_tasks(cfg, args) -> int:
+    policy = _policy(args)
+    specs = generate_tasks(
+        cfg, policy,
+        cells=getattr(args, "cells", 0) or 0,
+        per_cell=getattr(args, "per_cell", 1) or 1,
+        model=getattr(args, "model", None),
+    )
+    print(f"\n  wrote {len(specs)} task(s) -> {store_path(cfg)}")
+    return 0 if specs else 1
+
+
+def cli_run(cfg, args) -> int:
+    specs = load_specs(cfg)
+    wanted = ("pending", "running")
+    if getattr(args, "retry_failed", False):
+        wanted = wanted + ("failed",)
+    pending = [s for s in specs.values() if s.status in wanted]
+    pending.sort(key=lambda s: s.created_at)
+    limit = getattr(args, "limit", 0) or 0
+    if limit:
+        pending = pending[:limit]
+    if not pending:
+        print("  no pending task — run `traceforge synth tasks` first")
+        return 0
+    print(f"  executing {len(pending)} task(s) "
+          f"(max {args.max_turns} turns, {args.timeout}s each)")
+    ok = 0
+    for spec in pending:
+        res = execute_task(
+            cfg, spec,
+            max_turns=getattr(args, "max_turns", 40),
+            timeout=getattr(args, "timeout", 1800),
+            model=getattr(args, "model", None),
+            provider=getattr(args, "provider", None),
+        )
+        mark = "OK  " if res.status == "done" else "FAIL"
+        print(f"  {mark} {res.id}  {res.language}/{res.task} "
+              f"{res.difficulty}  {res.duration_s}s  "
+              f"{res.turns or 0} turns"
+              + (f"  ({res.error})" if res.error else ""))
+        ok += res.status == "done"
+    print(f"\n  {ok}/{len(pending)} executed; "
+          f"run `traceforge synth ingest` to queue them for the pipeline")
+    return 0 if ok else 1
+
+
+def cli_ingest(cfg, args) -> int:
+    n = ingest(cfg)
+    print(f"  ingested {n} trace(s) into {cfg.raw_dir}")
+    print("  next: ./scripts/generate.sh  (triage -> improve -> gates -> export)")
+    return 0
+
+
+def cli_status(cfg, args) -> int:
+    specs = load_specs(cfg)
+    if not specs:
+        print("  no synthetic tasks yet — `traceforge synth plan` shows the gap")
+        return 0
+    by_status: dict[str, int] = {}
+    by_cell: dict[str, dict[str, int]] = {}
+    for s in specs.values():
+        by_status[s.status] = by_status.get(s.status, 0) + 1
+        cell = f"{s.language}/{s.task}"
+        by_cell.setdefault(cell, {})
+        by_cell[cell][s.status] = by_cell[cell].get(s.status, 0) + 1
+    print(f"  synthetic tasks: {len(specs)} total · "
+          + " · ".join(f"{k} {v}" for k, v in sorted(by_status.items())))
+    for cell, counts in sorted(by_cell.items()):
+        print(f"    {cell:<22s} " + " ".join(f"{k}={v}"
+                                             for k, v in sorted(counts.items())))
+    done = [s for s in specs.values() if s.status == "done"]
+    if done:
+        turns = sorted(s.turns or 0 for s in done)
+        print(f"  executed: median {turns[len(turns)//2]} tool-call turns, "
+              f"median {sorted(s.duration_s or 0 for s in done)[len(done)//2]:.0f}s")
+    return 0

traceforge/trace.py

@@ -102,6 +102,12 @@ class Trace:
     # task/topic bucket (see traceforge/classify.py). Persisted so export
     # can split the corpus deterministically and the label is reviewable.
     task: Optional[str] = None
+    # The harness the SOURCE session came from (claude-code, codex, tui,
+    # desktop, ...). `source` cannot carry it: the improve stage overwrites
+    # it with "traceforge-splice", so a promoted trace lost the one field
+    # the harness-balance axis needs. Set from the raw trace at improve
+    # time and preserved through every rewrite.
+    harness: Optional[str] = None
 
     # ------------------------------------------------------------------ meta
 
@@ -183,6 +189,7 @@ class Trace:
             "improved": self.improved,
             "parent_session_id": self.parent_session_id,
             "task": self.task,
+            "harness": self.harness,
             "messages": [m.to_dict() for m in self.messages],
         }
 
@@ -199,6 +206,7 @@ class Trace:
             improved=bool(d.get("improved", False)),
             parent_session_id=d.get("parent_session_id"),
             task=d.get("task"),
+            harness=d.get("harness"),
         )
 
     def save(self, path: str) -> None:
@@ -332,6 +340,41 @@ def json_loads_lenient(raw: Optional[str]) -> Any:
             break
     return None
 
+_TEST_SUMMARY_RE = re.compile(
+    r"(?:=+ FAILURES =+"
+    r"|short test summary info"
+    r"|^\s*\d+ (?:failed|passed|error)[,)]"
+    r"|^\s*FAILED \S+::"
+    r"|npm ERR!"
+    r"|error TS\d+"
+    r"|^\s*E\s+assert)", re.M)
+
+_EXEC_TOOLS = frozenset({
+    "exec", "bash", "shell", "sh", "run", "terminal", "exec_command",
+    "run_command", "run_terminal_cmd",
+})
+
+
+def is_failed_run(content: Optional[str],
+                  tool_name: Optional[str] = None) -> bool:
+    """A test/build run that FAILED, though the wrapper reported success.
+
+    `_is_error_result` reads the call's exit status. A wrapped exec
+    ("Script completed Wall time 5.6 seconds Output: {...}") can report
+    success while the pytest run inside printed a failure summary — the
+    judge then cites that result as P2 forever and the mechanical drop
+    never fires, because the result is not an "error result". Measured
+    2026-10-28: 16 of 56 P2-cited failures in one batch were this shape.
+
+    Only SUMMARY-shaped evidence counts. A file dump of a test file also
+    contains "assert", but no summary line — that distinction is what
+    keeps this from dropping legitimate reads.
+    """
+    if (tool_name or "").strip().lower() not in _EXEC_TOOLS:
+        return False
+    return bool(_TEST_SUMMARY_RE.search(content or ""))
+
+
 def _is_error_result(content: Optional[str]) -> bool:
     """True when a tool-result row is a FAILED call (P2 route-around
     signal for the splice window rewriter). Recognizes the common

traceforge/triage.py

@@ -29,6 +29,7 @@ from __future__ import annotations
 import json
 import os
 import threading
+import time
 import urllib.error
 import urllib.request
 from concurrent.futures import ThreadPoolExecutor, as_completed
@@ -36,6 +37,7 @@ from typing import Any, Optional
 
 from traceforge import chunker
 from traceforge.config import Config
+from traceforge.net import backoff_s, is_transient_status
 from traceforge.trace import Trace, json_loads_lenient
 
 ACTIONS = ("keep", "drop", "rephrase", "fact_check", "summarize")
@@ -131,8 +133,13 @@ def _resolve_endpoint(cfg: Config) -> tuple[str, str, str]:
         ) as f:
             prof = yaml.safe_load(f) or {}
         m = prof.get("model") or {}
-        # pinned provider block first (matches cfg.provider)
-        pv = (prof.get("providers") or {}).get(cfg.provider or "") or {}
+        # The pinned provider may come from the traceforge config
+        # (cfg.provider) or, when that is unset, from the profile's own
+        # model.provider. Without the fallback a config with no
+        # triage_base_url resolves nothing — providers[""] is empty — even
+        # though the profile has a working provider block with the URL.
+        provider = cfg.provider or m.get("provider") or ""
+        pv = (prof.get("providers") or {}).get(provider) or {}
         if not base:
             base = (pv.get("base_url") or m.get("base_url") or "").rstrip("/")
         if not key:
@@ -357,14 +364,26 @@ def _classify_window(
         if not model:
             payload.pop("model")
         payload.update(variant)
-        try:
-            data = _post_json(url, payload, key, cfg.triage_timeout_s)
-        except urllib.error.HTTPError as e:
-            # 400 on an unknown structured-output field: try next variant
-            last_err = f"HTTP {e.code}"
-            continue
-        except (urllib.error.URLError, TimeoutError, OSError) as e:
-            last_err = f"network: {e}"
+        data: Optional[dict[str, Any]] = None
+        for attempt in range(3):
+            try:
+                data = _post_json(url, payload, key, cfg.triage_timeout_s)
+                break
+            except urllib.error.HTTPError as e:
+                last_err = f"HTTP {e.code}"
+                if not is_transient_status(e.code):
+                    # 400 on an unknown structured-output field: the
+                    # request body is wrong, so try the next variant.
+                    break
+                # 503/429/5xx is the endpoint, not the body. Retrying the
+                # same variant is the only thing that can help; the old
+                # code fell through all three variants in milliseconds and
+                # the trace died as "triage failed for every window".
+                time.sleep(backoff_s(attempt, e))
+            except (urllib.error.URLError, TimeoutError, OSError) as e:
+                last_err = f"network: {e}"
+                time.sleep(backoff_s(attempt, e))
+        if data is None:
             continue
         raw = _extract_content(data)
         labels = parse_labels(raw, valid)

traceforge/validate.py

@@ -1,412 +1,488 @@
-"""Structural validation of an (improved) trace.
-
-Checks that are format-level facts, independent of the quality guidelines —
-guideline-scoring (quality rules) will be defined together with the user and
-plugged in as a separate, stricter validator later.
-"""
-from __future__ import annotations
-
-import difflib
-import json
-import re
-from typing import Optional
-
-from traceforge.trace import Message, Trace
-
-# template substitution tokens that leaked into message content, e.g.
-# "exec_reader_search_placeholder_0#" (agent-VM prompt template bug in
-# the source session). Word-ish identifier + "_placeholder_" + digits.
-_TEMPLATE_LEAK_RE = re.compile(
-    r"[a-z][a-z0-9_]*_placeholder_\d+", re.IGNORECASE)
-
-# rendering markers from trace.py's prompt rendering (the improver's INPUT
-# format). The improver occasionally echoes them into assistant prose —
-# e.g. a row whose whole content is "(tool-only turn)" — which a trainee
-# must never see. Length-based degenerate checks miss these because the
-# marker is 16 chars.
-_RENDER_MARKER_RE = re.compile(
-    r"^\s*(?:\(tool-only turn\)"
-    r"|\[\d+\]\s+(?:ASSISTANT|USER|SYSTEM|TOOL)\b"
-    r"|->\s*TOOL\s+\S+\s+args=)",
-    re.IGNORECASE)
-
-VALID_ROLES = {"system", "user", "assistant", "tool"}
-
-# An explicit translation request makes a language switch the CORRECT answer,
-# so the P5 gate must not fire on it.
-_LANG_SWITCH_RE = re.compile(
-    r"\b(?:übersetz|translate|translation|auf englisch|auf deutsch|"
-    r"in english|in german|ins englische|ins deutsche)\b", re.IGNORECASE)
-
-# Pipeline framing markers that belong to the improver's INPUT, not to the
-# training target: the splitter prepends "[trace segment k of n — ...]" and
-# the codex reader prepends "[subagent brief — role: ...]". A user never
-# types these, so they are stripped from user rows before promotion.
-_SCAFFOLD_RE = re.compile(
-    r"\[trace segment \d+ of \d+[^\]]*\]|\[subagent brief[^\]]*\]")
-
-# Code-ish spans removed before language scoring: fenced/inline code,
-# markdown link targets, URLs, absolute paths, and filenames. Their
-# identifiers are English by convention and would otherwise outvote the
-# prose's function words.
-_CODEISH_RE = re.compile(
-    r"```.*?```"
-    r"|`[^`\n]*`"
-    r"|!?\[[^\]]*\]\([^)]*\)"
-    r"|https?://\S+"
-    r"|(?:[A-Za-z]:)?(?:/[\w.\-]+){2,}"
-    r"|[\w.\-]+\.(?:py|ts|tsx|js|mjs|go|rs|md|json|ya?ml|sh|toml|txt)\b",
-    re.S)
-
-
-def _confident_lang(text: str, min_words: int) -> Optional[str]:
-    """'de'/'en' only when the call is unambiguous, else None.
-
-    Requires min_words function words AND a 70% dominant share, so a mixed
-    task or an answer quoting the other language does not trip the gate.
-    Code, paths, URLs and markdown link targets are removed first: an
-    English file path inside a German answer ("...-api-and-paired-...")
-    otherwise supplies enough English function words to flip the call.
-    """
-    from traceforge.classify import language_scores
-
-    de, en = language_scores(_CODEISH_RE.sub(" ", text))
-    total = de + en
-    if total < min_words:
-        return None
-    if max(de, en) / total < 0.7:
-        return None
-    return "de" if de > en else "en"
-
-
-def strip_scaffold_markers(t: Trace) -> int:
-    """Remove pipeline framing markers from user rows (in place).
-
-    Returns the number of rows changed. A row that is ONLY a marker is left
-    untouched (stripping it would create an empty user message).
-    """
-    changed = 0
-    for m in t.messages:
-        if m.role != "user" or not m.content:
-            continue
-        new = _SCAFFOLD_RE.sub("", m.content)
-        if new == m.content:
-            continue
-        new = re.sub(r"[ \t]+\n", "\n", new)
-        new = re.sub(r"\n{3,}", "\n\n", new).strip()
-        if not new:
-            continue
-        m.content = new
-        changed += 1
-    return changed
-
-
-def _norm_for_similarity(text: str) -> str:
-    """Collapse whitespace and case so formatting noise can't hide an echo."""
-    return re.sub(r"\s+", " ", text).strip().lower()
-
-
-# Unmistakable reframe-prompt text. The reframe model echoes its own rules
-# into the task message; a user never types any of this. The sanitizer cuts
-# it at reframe time, and this gate is the backstop that makes a leak fail
-# loudly instead of promoting silently (measured: 68 of 1044 traces).
-_REFRAME_PROMPT_RE = re.compile(
-    r"Same language as the current task message"
-    r"|The new task must ask ONLY"
-    r"|no meta commentary"
-    r"|answerable EXACTLY by the final answer"
-    r"|Reply with ONLY the JSON object"
-    r"|write that request as the new opening task message"
-    r"|A synthetic ideal-world agent trace"
-    r"|no mention of traces or reframing", re.IGNORECASE)
-
-# Harness dispatch briefs are NOT user messages. A codex subagent rollout opens
-# with the coordinator's dispatch text ("You are working inside Orca, a
-# multi-agent IDE. You are a dispatched worker. Your coordinator's Orca session
-# ID is: ... === CLI COMMANDS ==="), 6-7KB of orchestration boilerplate with
-# session/task ids and CLI docs. Promoted as-is, the trainee learns to emit
-# harness plumbing as the user turn. Measured 2026-10-22: 6 of 1046 improved
-# traces, 4 of them promoted by the running batch — so gate it, don't just
-# clean it.
-#
-# STRONG markers only (2026-10-24). The bare phrase `orca orchestration` used
-# to be an alternative here, and it is a CLI NAME, not boilerplate: it appears
-# in legitimate task rows ("...report via orca orchestration"), in the
-# harness's own "You have N orchestration messages" notifications, and quoted
-# inside compaction summaries. Measured on the raw pool: 43 traces matched
-# only that phrase, 42 of them with a real task row and no brief at all, and
-# 2 of the 20 recorded gate failures were clean traces killed by a quoted
-# mention at row 228. The four strong markers below appear in every real
-# brief and in nothing else.
-_HARNESS_BRIEF_RE = re.compile(
-    r"You are working inside Orca, a multi-agent IDE"
-    r"|You are a dispatched worker"
-    r"|Your coordinator's Orca session ID is"
-    r"|=== CLI COMMANDS ===", re.IGNORECASE)
-
-# Plumbing user rows: harness/validator chatter that an ideal trace routes
-# around. These MAY be dropped. A substantive user turn may NOT.
-_PLUMBING_USER_RE = re.compile(
-    r"(previous (final )?(response|answer|attempt).{0,40}"
-    r"(reject|invalid|not valid|validation error)"
-    r"|(rejected? by the).{0,40}(validator|contract)"
-    r"|^validation errors?\b|output contract validator"
-    r"|\[trace segment \d+ of \d+"
-    r"|\[subagent brief"
-    r"|\[CONTEXT COMPACTION"
-    r"|This session is being continued"
-    r"|^You have \d+ orchestration messages?\.)", re.IGNORECASE)
-
-
-def _is_plumbing_user_row(m) -> bool:
-    """A user row that is harness/validator plumbing, not a user request."""
-    if m.role != "user":
-        return False
-    c = (m.content or "")[:400]
-    return bool(_PLUMBING_USER_RE.search(c)) or bool(_HARNESS_BRIEF_RE.search(c))
-
-
-def substantive_user_turns(t: Trace) -> int:
-    """Count genuine user turns, ignoring plumbing and consecutive merges.
-
-    A turn group is a maximal run of user rows; it counts once when at least
-    one row in it is substantive. Consecutive rows are one turn because the
-    gate shape merges them (`_merge_same_role`), so a merge must not read as
-    a dropped turn.
-    """
-    n = 0
-    in_group = False
-    has_substantive = False
-    for m in t.messages:
-        if m.role == "user":
-            if not in_group:
-                in_group, has_substantive = True, False
-            if not _is_plumbing_user_row(m):
-                has_substantive = True
-        else:
-            if in_group and has_substantive:
-                n += 1
-            in_group = False
-    if in_group and has_substantive:
-        n += 1
-    return n
-
-
-def validate_structural(t: Trace) -> list[str]:
-    """Return a list of structural errors ([] = valid)."""
-    errors: list[str] = []
-    if not t.messages:
-        return ["trace has no messages"]
-
-    roles = [m.role for m in t.messages]
-    if roles[0] == "assistant":
-        errors.append("first message is assistant (expected user or system)")
-    if "user" not in roles:
-        errors.append("no user message in trace")
-    if roles[-1] not in ("assistant",):
-        errors.append(f"last message role is {roles[-1]!r} (expected assistant)")
-
-    # tool-call / tool-result pairing: a rewrite that drops a call but
-    # keeps its result (or strips a call's name) is not a valid
-    # conversation — the trainee would learn to answer without evidence.
-    # Measured on the Space's 3B local mode: it dropped the successful
-    # call and kept the failed call's error row, leaving an orphan result.
-    calls: dict[str, str] = {}
-    for i, m in enumerate(t.messages):
-        for tc in (m.tool_calls or []):
-            if not (tc.name or "").strip():
-                errors.append(f"[{i}] tool call has no function name")
-            if tc.id:
-                calls[tc.id] = tc.name
-    for i, m in enumerate(t.messages):
-        if m.role != "tool":
-            continue
-        cid = m.tool_call_id or ""
-        if cid and cid not in calls:
-            errors.append(
-                f"[{i}] tool result has no matching tool call ({cid!r}) "
-                "— the evidence was dropped")
-
-    # reframe-prompt leak: the reframe model echoes its own rule list into
-    # the task message. A user never types it, so the row is not a user row.
-    for i, m in enumerate(t.messages):
-        if m.role != "user" or not m.content:
-            continue
-        hit = _REFRAME_PROMPT_RE.search(m.content)
-        if hit:
-            errors.append(
-                f"[{i}] user message contains reframe-prompt text "
-                f"({hit.group(0)!r}) — the task must be the user's own words")
-        hb = _HARNESS_BRIEF_RE.search(m.content)
-        if hb:
-            errors.append(
-                f"[{i}] user message is a harness dispatch brief "
-                f"({hb.group(0)!r}) — not the user's own words")
-
-    # template placeholder leak: source-agent prompt templates sometimes
-    # bleed their substitution tokens ("exec_reader_search_placeholder_0#")
-    # into the assistant prose — a trainee must never see them. Any
-    # message STARTING with one fails structurally (repair gets a
-    # precise citation instead of the judge discovering it late).
-    for i, m in enumerate(t.messages):
-        if m.role != "assistant":
-            continue
-        head = (m.content or "").lstrip()[:120]
-        leak = _TEMPLATE_LEAK_RE.match(head)
-        if leak:
-            errors.append(
-                f"[{i}] assistant message starts with a leaked template "
-                f"placeholder token ({leak.group(0)!r}) "
-                "— rewrite the row as clean prose")
-        marker = _RENDER_MARKER_RE.match(head)
-        if marker:
-            errors.append(
-                f"[{i}] assistant message starts with a leaked rendering "
-                f"marker ({marker.group(0).strip()!r}) "
-                "— rewrite the row as clean prose")
-
-    # brief echo: the writer sometimes answers a long subagent brief by
-    # re-presenting it ("verbatim copy of the user's brief, no new
-    # reasoning"). The judge catches it late and expensively; a similarity
-    # check against the opening task catches it for free. Only the FIRST
-    # user task message is compared — quoting a later user message back is
-    # legitimate (confirming a correction), echoing the brief never is.
-    brief = t.first_task_message() or ""
-    if len(brief) >= 200:
-        brief_norm = _norm_for_similarity(brief)
-        for i, m in enumerate(t.messages):
-            if m.role != "assistant" or not m.content:
-                continue
-            if len(m.content) < 200:
-                continue
-            ratio = difflib.SequenceMatcher(
-                None, brief_norm, _norm_for_similarity(m.content),
-                autojunk=False).ratio()
-            if ratio >= 0.85:
-                errors.append(
-                    f"[{i}] assistant message is a {ratio:.0%} verbatim echo "
-                    "of the user's opening brief — answer the task instead "
-                    "of re-presenting it")
-
-    # First-turn echo: the writer sometimes opens by restating the task
-    # verbatim instead of doing work. The brief-echo check above needs 200
-    # chars on both sides, so a short echo slips through — measured
-    # 2026-10-22: 121 of 1094 traces (11%) had a 1.00-similarity first
-    # assistant turn with no tool call, and the user row was the agent's own
-    # plan ("Ich prüfe die drei Artefakte zuerst …").
-    first_asst = next((i for i, m in enumerate(t.messages)
-                       if m.role == "assistant"), None)
-    if first_asst is not None and brief:
-        m = t.messages[first_asst]
-        body = (m.content or "").strip()
-        if body and not m.tool_calls and len(body) >= 60:
-            ratio = difflib.SequenceMatcher(
-                None, _norm_for_similarity(brief[:600]),
-                _norm_for_similarity(body[:600]), autojunk=False).ratio()
-            if ratio >= 0.9:
-                errors.append(
-                    f"[{first_asst}] first assistant turn is a {ratio:.0%} "
-                    "verbatim echo of the user's task with no tool call — "
-                    "do work instead of restating the brief")
-
-    # P5 language: one language per trace. The judge catches a German task
-    # answered in English but misses the reverse, and the source traces are
-    # themselves mixed (an English brief answered in German by the source
-    # agent). A trainee must learn to answer in the task's language, so a
-    # CONFIDENT mismatch is a structural error with a precise citation.
-    # Confidence guards: both sides need enough function words and a clear
-    # ratio, so a German answer quoting English code (or a mixed task) does
-    # not trip it; an explicit translation request is exempt.
-    final_i = next((i for i in range(len(t.messages) - 1, -1, -1)
-                    if t.messages[i].role == "assistant"), None)
-    if final_i is not None and not _LANG_SWITCH_RE.search(brief):
-        final = t.messages[final_i].content or ""
-        if len(final) >= 120:
-            # 300 chars of the task: the instruction is at the top; a long
-            # quoted log further down (a German report pasting an English
-            # CI log) would otherwise flip the task's language.
-            task_lang = _confident_lang(brief[:300], 3)
-            ans_lang = _confident_lang(final[:800], 4)
-            if task_lang and ans_lang and task_lang != ans_lang:
-                errors.append(
-                    f"[{final_i}] final answer is in {ans_lang} but the task "
-                    f"is in {task_lang} — answer in the task's language (P5)")
-
-    # role alternation: no two user or two assistant messages back-to-back
-    prev: Optional[str] = None
-    for i, m in enumerate(t.messages):
-        if m.role not in VALID_ROLES:
-            errors.append(f"[{i}] invalid role {m.role!r}")
-        if m.role == "user" and prev == "user":
-            errors.append(f"[{i}] two consecutive user messages")
-        if m.role == "assistant" and prev == "assistant" and not (
-            m.tool_calls or t.messages[i - 1].tool_calls
-        ):
-            errors.append(f"[{i}] two consecutive text-only assistant turns")
-        prev = m.role
-
-    # tool pairing: every call answered exactly once, every result has a call
-    called: dict[str, str] = {}  # id -> tool name
-    answered: dict[str, int] = {}
-    for i, m in enumerate(t.messages):
-        for tc in m.tool_calls:
-            if not tc.id:
-                errors.append(f"[{i}] tool_call without id ({tc.name})")
-            elif tc.id in called:
-                errors.append(f"[{i}] duplicate tool_call id {tc.id}")
-            else:
-                called[tc.id] = tc.name
-            if not tc.name:
-                errors.append(f"[{i}] tool_call without name")
-            args = tc.arguments or "{}"
-            if not isinstance(args, str):
-                errors.append(
-                    f"[{i}] tool_call {tc.name} arguments must be a JSON string"
-                )
-            else:
-                try:
-                    json.loads(args)
-                except json.JSONDecodeError as e:
-                    errors.append(
-                        f"[{i}] tool_call {tc.name} arguments not valid JSON: {e}"
-                    )
-        if m.role == "tool":
-            tcid = m.tool_call_id
-            if not tcid:
-                errors.append(f"[{i}] tool result without tool_call_id")
-            elif tcid not in called:
-                errors.append(f"[{i}] tool result references unknown call {tcid}")
-            else:
-                answered[tcid] = answered.get(tcid, 0) + 1
-            if not (m.content or "").strip():
-                # empty result text (content None/"" — 019ff135 class:
-                # send_message {} -> content=None with tool_name set, so
-                # the old content-None-AND-tool_name-None check passed
-                # it). An SFT trainee must never learn to expect or emit
-                # result-less tool rows.
-                errors.append(f"[{i}] tool result is empty")
-
-    for tcid, name in called.items():
-        n = answered.get(tcid, 0)
-        if n == 0:
-            errors.append(f"tool call {tcid} ({name}) has no result")
-        elif n > 1:
-            errors.append(f"tool call {tcid} ({name}) has {n} results")
-
-    # empty-content sanity
-    for i, m in enumerate(t.messages):
-        if m.role in ("user", "assistant") and m.content in ("", None) and not m.tool_calls:
-            errors.append(f"[{i}] {m.role} message with empty content and no tool calls")
-
-    # degenerate short-prose assistant rows ("\n\n" connectors, "Now
-    # the fix:" fragments) — training noise; only NON-FINAL rows (the
-    # final answer may legitimately be terse) and rows without calls.
-    last = len(t.messages) - 1
-    for i, m in enumerate(t.messages):
-        if (m.role == "assistant" and i != last and not m.tool_calls
-                and m.content and len(m.content.strip()) < 15):
-            errors.append(
-                f"[{i}] degenerate assistant prose ({len(m.content.strip())} chars): "
-                f"{m.content.strip()[:40]!r}")
-
+"""Structural validation of an (improved) trace.
+
+Checks that are format-level facts, independent of the quality guidelines —
+guideline-scoring (quality rules) will be defined together with the user and
+plugged in as a separate, stricter validator later.
+"""
+from __future__ import annotations
+
+import difflib
+import json
+import re
+from typing import Optional
+
+from traceforge.trace import Message, Trace
+
+# template substitution tokens that leaked into message content, e.g.
+# "exec_reader_search_placeholder_0#" (agent-VM prompt template bug in
+# the source session). Word-ish identifier + "_placeholder_" + digits.
+_TEMPLATE_LEAK_RE = re.compile(
+    r"[a-z][a-z0-9_]*_placeholder_\d+", re.IGNORECASE)
+
+# rendering markers from trace.py's prompt rendering (the improver's INPUT
+# format). The improver occasionally echoes them into assistant prose —
+# e.g. a row whose whole content is "(tool-only turn)" — which a trainee
+# must never see. Length-based degenerate checks miss these because the
+# marker is 16 chars.
+_RENDER_MARKER_RE = re.compile(
+    r"^\s*(?:\(tool-only turn\)"
+    r"|\[\d+\]\s+(?:ASSISTANT|USER|SYSTEM|TOOL)\b"
+    r"|->\s*TOOL\s+\S+\s+args=)",
+    re.IGNORECASE)
+
+VALID_ROLES = {"system", "user", "assistant", "tool"}
+
+# An explicit translation request makes a language switch the CORRECT answer,
+# so the P5 gate must not fire on it.
+_LANG_SWITCH_RE = re.compile(
+    r"\b(?:übersetz|translate|translation|auf englisch|auf deutsch|"
+    r"in english|in german|ins englische|ins deutsche)\b", re.IGNORECASE)
+
+# Pipeline framing markers that belong to the improver's INPUT, not to the
+# training target: the splitter prepends "[trace segment k of n — ...]" and
+# the codex reader prepends "[subagent brief — role: ...]". A user never
+# types these, so they are stripped from user rows before promotion.
+_SCAFFOLD_RE = re.compile(
+    r"\[trace segment \d+ of \d+[^\]]*\]|\[subagent brief[^\]]*\]")
+
+# Code-ish spans removed before language scoring: fenced/inline code,
+# markdown link targets, URLs, absolute paths, and filenames. Their
+# identifiers are English by convention and would otherwise outvote the
+# prose's function words.
+_CODEISH_RE = re.compile(
+    r"```.*?```"
+    r"|`[^`\n]*`"
+    r"|!?\[[^\]]*\]\([^)]*\)"
+    r"|https?://\S+"
+    r"|(?:[A-Za-z]:)?(?:/[\w.\-]+){2,}"
+    r"|[\w.\-]+\.(?:py|ts|tsx|js|mjs|go|rs|md|json|ya?ml|sh|toml|txt)\b",
+    re.S)
+
+
+def _confident_lang(text: str, min_words: int) -> Optional[str]:
+    """'de'/'en' only when the call is unambiguous, else None.
+
+    Requires min_words function words AND a 70% dominant share, so a mixed
+    task or an answer quoting the other language does not trip the gate.
+    Code, paths, URLs and markdown link targets are removed first: an
+    English file path inside a German answer ("...-api-and-paired-...")
+    otherwise supplies enough English function words to flip the call.
+    """
+    from traceforge.classify import language_scores
+
+    de, en = language_scores(_CODEISH_RE.sub(" ", text))
+    total = de + en
+    if total < min_words:
+        return None
+    if max(de, en) / total < 0.7:
+        return None
+    return "de" if de > en else "en"
+
+
+def strip_scaffold_markers(t: Trace) -> int:
+    """Remove pipeline framing markers from user rows (in place).
+
+    Returns the number of rows changed. A row that is ONLY a marker is left
+    untouched (stripping it would create an empty user message).
+    """
+    changed = 0
+    for m in t.messages:
+        if m.role != "user" or not m.content:
+            continue
+        new = _SCAFFOLD_RE.sub("", m.content)
+        if new == m.content:
+            continue
+        new = re.sub(r"[ \t]+\n", "\n", new)
+        new = re.sub(r"\n{3,}", "\n\n", new).strip()
+        if not new:
+            continue
+        m.content = new
+        changed += 1
+    return changed
+
+
+# Harness memory-citation markup is not assistant prose. Codex memory makes
+# the model emit a trailing
+# `<oai-mem-citation><citation_entries>MEMORY.md:396-400|note=[...]</citation_entries></oai-mem-citation>`
+# block; the improver carries it into the ideal trace, where it teaches the
+# trainee to emit product-specific XML. Measured 2026-10-28: 62 of 4,487
+# promoted traces (1.4%), 66 assistant rows + 2 user rows, ALWAYS trailing
+# (the closing tag is the last thing in the row), and 411 raws carry it, so
+# the batch keeps producing them. Strip at promote, gate as backstop.
+_HARNESS_CITATION_RE = re.compile(
+    r"<oai-mem-citation>.*?</oai-mem-citation>"
+    r"|<citation_entries>.*?</citation_entries>", re.S)
+
+
+def strip_harness_citation(t: Trace) -> int:
+    # Remove harness memory-citation blocks from any row (in place).
+    # Returns the number of rows changed; a row that is ONLY the block is
+    # left untouched (stripping it would create an empty row).
+    changed = 0
+    for m in t.messages:
+        c = m.content
+        if not c or ("oai-mem-citation" not in c and "citation_entries" not in c):
+            continue
+        new = _HARNESS_CITATION_RE.sub("", c)
+        if new == c:
+            continue
+        new = re.sub(r"[ \t]+\n", "\n", new)
+        new = re.sub(r"\n{3,}", "\n\n", new).rstrip()
+        if not new.strip():
+            continue
+        m.content = new
+        changed += 1
+    return changed
+
+
+def _norm_for_similarity(text: str) -> str:
+    """Collapse whitespace and case so formatting noise can't hide an echo."""
+    return re.sub(r"\s+", " ", text).strip().lower()
+
+
+# Unmistakable reframe-prompt text. The reframe model echoes its own rules
+# into the task message; a user never types any of this. The sanitizer cuts
+# it at reframe time, and this gate is the backstop that makes a leak fail
+# loudly instead of promoting silently (measured: 68 of 1044 traces).
+_REFRAME_PROMPT_RE = re.compile(
+    r"Same language as the current task message"
+    r"|The new task must ask ONLY"
+    r"|no meta commentary"
+    r"|answerable EXACTLY by the final answer"
+    r"|Reply with ONLY the JSON object"
+    r"|write that request as the new opening task message"
+    r"|A synthetic ideal-world agent trace"
+    r"|no mention of traces or reframing", re.IGNORECASE)
+
+# Harness dispatch briefs are NOT user messages. A codex subagent rollout opens
+# with the coordinator's dispatch text ("You are working inside Orca, a
+# multi-agent IDE. You are a dispatched worker. Your coordinator's Orca session
+# ID is: ... === CLI COMMANDS ==="), 6-7KB of orchestration boilerplate with
+# session/task ids and CLI docs. Promoted as-is, the trainee learns to emit
+# harness plumbing as the user turn. Measured 2026-10-22: 6 of 1046 improved
+# traces, 4 of them promoted by the running batch — so gate it, don't just
+# clean it.
+#
+# STRONG markers only (2026-10-24). The bare phrase `orca orchestration` used
+# to be an alternative here, and it is a CLI NAME, not boilerplate: it appears
+# in legitimate task rows ("...report via orca orchestration"), in the
+# harness's own "You have N orchestration messages" notifications, and quoted
+# inside compaction summaries. Measured on the raw pool: 43 traces matched
+# only that phrase, 42 of them with a real task row and no brief at all, and
+# 2 of the 20 recorded gate failures were clean traces killed by a quoted
+# mention at row 228. The four strong markers below appear in every real
+# brief and in nothing else.
+_HARNESS_BRIEF_RE = re.compile(
+    r"You are working inside Orca, a multi-agent IDE"
+    r"|You are a dispatched worker"
+    r"|Your coordinator's Orca session ID is"
+    r"|=== CLI COMMANDS ===", re.IGNORECASE)
+
+# Plumbing user rows: harness/validator chatter that an ideal trace routes
+# around. These MAY be dropped. A substantive user turn may NOT.
+_PLUMBING_USER_RE = re.compile(
+    r"(previous (final )?(response|answer|attempt).{0,40}"
+    r"(reject|invalid|not valid|validation error)"
+    r"|(rejected? by the).{0,40}(validator|contract)"
+    r"|^validation errors?\b|output contract validator"
+    r"|\[trace segment \d+ of \d+"
+    r"|\[subagent brief"
+    r"|\[CONTEXT COMPACTION"
+    r"|This session is being continued"
+    r"|^You have \d+ orchestration messages?\."
+    r"|^\[System: The active model for this chat has changed"
+    r"|^\[IMPORTANT: Background process proc_"
+    r"|\[SYSTEM NOTIFICATION - NOT USER INPUT\]"
+    r"|<task-notification>"
+    r"|automated background-task event, NOT a message from the user)",
+    re.IGNORECASE)
+
+
+# Runtime/process notices are NOT a task. The harness writes them into the
+# user slot mid-session ("[System: The active model for this chat has changed
+# to glm via provider ...]", "[IMPORTANT: Background process proc_... completed
+# normally (exit code 0)."). Measured 2026-10-29 on the promoted corpus: 9 of
+# 4,747 traces (0.19%) opened with one of these as the task row, and a 4,000-raw
+# sample of the pool found ZERO raws whose first user row was a notice — so the
+# splice/reframe path fabricated the task from a mid-session notification, not
+# the reader. Three of the nine collapsed a 99-205 message session to 2-4
+# messages (the whole tool loop dropped). Strong markers only: both strings are
+# emitted by the harness and by nothing else.
+_RUNTIME_NOTICE_RE = re.compile(
+    r"^\s*(?:\[System: The active model for this chat has changed"
+    r"|\[IMPORTANT: Background process proc_"
+    r"|\[SYSTEM NOTIFICATION - NOT USER INPUT\]"
+    r"|<task-notification>)", re.IGNORECASE)
+
+
+def _is_plumbing_user_row(m) -> bool:
+    """A user row that is harness/validator plumbing, not a user request."""
+    if m.role != "user":
+        return False
+    c = (m.content or "")[:400]
+    return bool(_PLUMBING_USER_RE.search(c)) or bool(_HARNESS_BRIEF_RE.search(c))
+
+
+def substantive_user_turns(t: Trace) -> int:
+    """Count genuine user turns, ignoring plumbing and consecutive merges.
+
+    A turn group is a maximal run of user rows; it counts once when at least
+    one row in it is substantive. Consecutive rows are one turn because the
+    gate shape merges them (`_merge_same_role`), so a merge must not read as
+    a dropped turn.
+    """
+    n = 0
+    in_group = False
+    has_substantive = False
+    for m in t.messages:
+        if m.role == "user":
+            if not in_group:
+                in_group, has_substantive = True, False
+            if not _is_plumbing_user_row(m):
+                has_substantive = True
+        else:
+            if in_group and has_substantive:
+                n += 1
+            in_group = False
+    if in_group and has_substantive:
+        n += 1
+    return n
+
+
+def validate_structural(t: Trace) -> list[str]:
+    """Return a list of structural errors ([] = valid)."""
+    errors: list[str] = []
+    if not t.messages:
+        return ["trace has no messages"]
+
+    roles = [m.role for m in t.messages]
+    if roles[0] == "assistant":
+        errors.append("first message is assistant (expected user or system)")
+    if "user" not in roles:
+        errors.append("no user message in trace")
+    if roles[-1] not in ("assistant",):
+        errors.append(f"last message role is {roles[-1]!r} (expected assistant)")
+
+    # tool-call / tool-result pairing: a rewrite that drops a call but
+    # keeps its result (or strips a call's name) is not a valid
+    # conversation — the trainee would learn to answer without evidence.
+    # Measured on the Space's 3B local mode: it dropped the successful
+    # call and kept the failed call's error row, leaving an orphan result.
+    calls: dict[str, str] = {}
+    for i, m in enumerate(t.messages):
+        for tc in (m.tool_calls or []):
+            if not (tc.name or "").strip():
+                errors.append(f"[{i}] tool call has no function name")
+            if tc.id:
+                calls[tc.id] = tc.name
+    for i, m in enumerate(t.messages):
+        if m.role != "tool":
+            continue
+        cid = m.tool_call_id or ""
+        if cid and cid not in calls:
+            errors.append(
+                f"[{i}] tool result has no matching tool call ({cid!r}) "
+                "— the evidence was dropped")
+
+    # reframe-prompt leak: the reframe model echoes its own rule list into
+    # the task message. A user never types it, so the row is not a user row.
+    for i, m in enumerate(t.messages):
+        if m.role != "user" or not m.content:
+            continue
+        hit = _REFRAME_PROMPT_RE.search(m.content)
+        if hit:
+            errors.append(
+                f"[{i}] user message contains reframe-prompt text "
+                f"({hit.group(0)!r}) — the task must be the user's own words")
+        hb = _HARNESS_BRIEF_RE.search(m.content)
+        if hb:
+            errors.append(
+                f"[{i}] user message is a harness dispatch brief "
+                f"({hb.group(0)!r}) — not the user's own words")
+
+    # opening task row must be the user's own words, not a runtime notice.
+    first_user = next((i for i, m in enumerate(t.messages)
+                       if m.role == "user"), None)
+    if first_user is not None:
+        c0 = t.messages[first_user].content or ""
+        notice = _RUNTIME_NOTICE_RE.match(c0)
+        if notice:
+            errors.append(
+                f"[{first_user}] opening user row is a runtime/process notice "
+                f"({notice.group(0).strip()[:60]!r}) — the task must be the "
+                "user's own request, not harness telemetry")
+
+    # harness memory-citation markup: product-specific XML in the target row.
+    for i, m in enumerate(t.messages):
+        if m.content and _HARNESS_CITATION_RE.search(m.content):
+            errors.append(
+                f"[{i}] {m.role} message carries harness memory-citation markup "
+                "— strip it, the trainee must not learn product XML")
+
+    # template placeholder leak: source-agent prompt templates sometimes
+    # bleed their substitution tokens ("exec_reader_search_placeholder_0#")
+    # into the assistant prose — a trainee must never see them. Any
+    # message STARTING with one fails structurally (repair gets a
+    # precise citation instead of the judge discovering it late).
+    for i, m in enumerate(t.messages):
+        if m.role != "assistant":
+            continue
+        head = (m.content or "").lstrip()[:120]
+        leak = _TEMPLATE_LEAK_RE.match(head)
+        if leak:
+            errors.append(
+                f"[{i}] assistant message starts with a leaked template "
+                f"placeholder token ({leak.group(0)!r}) "
+                "— rewrite the row as clean prose")
+        marker = _RENDER_MARKER_RE.match(head)
+        if marker:
+            errors.append(
+                f"[{i}] assistant message starts with a leaked rendering "
+                f"marker ({marker.group(0).strip()!r}) "
+                "— rewrite the row as clean prose")
+
+    # brief echo: the writer sometimes answers a long subagent brief by
+    # re-presenting it ("verbatim copy of the user's brief, no new
+    # reasoning"). The judge catches it late and expensively; a similarity
+    # check against the opening task catches it for free. Only the FIRST
+    # user task message is compared — quoting a later user message back is
+    # legitimate (confirming a correction), echoing the brief never is.
+    brief = t.first_task_message() or ""
+    if len(brief) >= 200:
+        brief_norm = _norm_for_similarity(brief)
+        for i, m in enumerate(t.messages):
+            if m.role != "assistant" or not m.content:
+                continue
+            if len(m.content) < 200:
+                continue
+            ratio = difflib.SequenceMatcher(
+                None, brief_norm, _norm_for_similarity(m.content),
+                autojunk=False).ratio()
+            if ratio >= 0.85:
+                errors.append(
+                    f"[{i}] assistant message is a {ratio:.0%} verbatim echo "
+                    "of the user's opening brief — answer the task instead "
+                    "of re-presenting it")
+
+    # First-turn echo: the writer sometimes opens by restating the task
+    # verbatim instead of doing work. The brief-echo check above needs 200
+    # chars on both sides, so a short echo slips through — measured
+    # 2026-10-22: 121 of 1094 traces (11%) had a 1.00-similarity first
+    # assistant turn with no tool call, and the user row was the agent's own
+    # plan ("Ich prüfe die drei Artefakte zuerst …").
+    first_asst = next((i for i, m in enumerate(t.messages)
+                       if m.role == "assistant"), None)
+    if first_asst is not None and brief:
+        m = t.messages[first_asst]
+        body = (m.content or "").strip()
+        if body and not m.tool_calls and len(body) >= 60:
+            ratio = difflib.SequenceMatcher(
+                None, _norm_for_similarity(brief[:600]),
+                _norm_for_similarity(body[:600]), autojunk=False).ratio()
+            if ratio >= 0.9:
+                errors.append(
+                    f"[{first_asst}] first assistant turn is a {ratio:.0%} "
+                    "verbatim echo of the user's task with no tool call — "
+                    "do work instead of restating the brief")
+
+    # P5 language: one language per trace. The judge catches a German task
+    # answered in English but misses the reverse, and the source traces are
+    # themselves mixed (an English brief answered in German by the source
+    # agent). A trainee must learn to answer in the task's language, so a
+    # CONFIDENT mismatch is a structural error with a precise citation.
+    # Confidence guards: both sides need enough function words and a clear
+    # ratio, so a German answer quoting English code (or a mixed task) does
+    # not trip it; an explicit translation request is exempt.
+    final_i = next((i for i in range(len(t.messages) - 1, -1, -1)
+                    if t.messages[i].role == "assistant"), None)
+    if final_i is not None and not _LANG_SWITCH_RE.search(brief):
+        final = t.messages[final_i].content or ""
+        if len(final) >= 120:
+            # 300 chars of the task: the instruction is at the top; a long
+            # quoted log further down (a German report pasting an English
+            # CI log) would otherwise flip the task's language.
+            task_lang = _confident_lang(brief[:300], 3)
+            ans_lang = _confident_lang(final[:800], 4)
+            if task_lang and ans_lang and task_lang != ans_lang:
+                errors.append(
+                    f"[{final_i}] final answer is in {ans_lang} but the task "
+                    f"is in {task_lang} — answer in the task's language (P5)")
+
+    # role alternation: no two user or two assistant messages back-to-back
+    prev: Optional[str] = None
+    for i, m in enumerate(t.messages):
+        if m.role not in VALID_ROLES:
+            errors.append(f"[{i}] invalid role {m.role!r}")
+        if m.role == "user" and prev == "user":
+            errors.append(f"[{i}] two consecutive user messages")
+        if m.role == "assistant" and prev == "assistant" and not (
+            m.tool_calls or t.messages[i - 1].tool_calls
+        ):
+            errors.append(f"[{i}] two consecutive text-only assistant turns")
+        prev = m.role
+
+    # tool pairing: every call answered exactly once, every result has a call
+    called: dict[str, str] = {}  # id -> tool name
+    answered: dict[str, int] = {}
+    for i, m in enumerate(t.messages):
+        for tc in m.tool_calls:
+            if not tc.id:
+                errors.append(f"[{i}] tool_call without id ({tc.name})")
+            elif tc.id in called:
+                errors.append(f"[{i}] duplicate tool_call id {tc.id}")
+            else:
+                called[tc.id] = tc.name
+            if not tc.name:
+                errors.append(f"[{i}] tool_call without name")
+            args = tc.arguments or "{}"
+            if not isinstance(args, str):
+                errors.append(
+                    f"[{i}] tool_call {tc.name} arguments must be a JSON string"
+                )
+            else:
+                try:
+                    json.loads(args)
+                except json.JSONDecodeError as e:
+                    errors.append(
+                        f"[{i}] tool_call {tc.name} arguments not valid JSON: {e}"
+                    )
+        if m.role == "tool":
+            tcid = m.tool_call_id
+            if not tcid:
+                errors.append(f"[{i}] tool result without tool_call_id")
+            elif tcid not in called:
+                errors.append(f"[{i}] tool result references unknown call {tcid}")
+            else:
+                answered[tcid] = answered.get(tcid, 0) + 1
+            if not (m.content or "").strip():
+                # empty result text (content None/"" — 019ff135 class:
+                # send_message {} -> content=None with tool_name set, so
+                # the old content-None-AND-tool_name-None check passed
+                # it). An SFT trainee must never learn to expect or emit
+                # result-less tool rows.
+                errors.append(f"[{i}] tool result is empty")
+
+    for tcid, name in called.items():
+        n = answered.get(tcid, 0)
+        if n == 0:
+            errors.append(f"tool call {tcid} ({name}) has no result")
+        elif n > 1:
+            errors.append(f"tool call {tcid} ({name}) has {n} results")
+
+    # empty-content sanity
+    for i, m in enumerate(t.messages):
+        if m.role in ("user", "assistant") and m.content in ("", None) and not m.tool_calls:
+            errors.append(f"[{i}] {m.role} message with empty content and no tool calls")
+
+    # degenerate short-prose assistant rows ("\n\n" connectors, "Now
+    # the fix:" fragments) — training noise; only NON-FINAL rows (the
+    # final answer may legitimately be terse) and rows without calls.
+    last = len(t.messages) - 1
+    for i, m in enumerate(t.messages):
+        if (m.role == "assistant" and i != last and not m.tool_calls
+                and m.content and len(m.content.strip()) < 15):
+            errors.append(
+                f"[{i}] degenerate assistant prose ({len(m.content.strip())} chars): "
+                f"{m.content.strip()[:40]!r}")
+
     return errors