@yahyahammad/venastine 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
@@ -0,0 +1,1382 @@
1
+ """
2
+ core/reasoning/orchestrator.py
3
+
4
+ Sequences the deep-research pipeline: Pass 0 -> 1 -> 2 -> gate D0 -> (3a -> 3b
5
+ for factual claims) -> 3c -> 4 (all claims) -> Pass 5 (code) -> D1 -> the
6
+ 6a/6b/D2 retry loop -> 6c (template) -> merge -> final synthesis.
7
+
8
+ SCOPE OF THIS VERSION: core sequential pipeline with optional ensemble
9
+ mode (ROADMAP §10: N-candidate Pass 1 generation + cross-candidate
10
+ consistency check feeding Pass 5's scoring). No filesystem output yet
11
+ (returns a PipelineRun object; the /output/<run_id>/ file-writing system
12
+ is a separate, later piece of work).
13
+
14
+ ROADMAP §11 (critic-model routing): when a critic pair is configured,
15
+ Pass 3a, 3b, and 6c (which re-runs 3a/3b logic) use the critic
16
+ provider/model instead of the generator's. Every other pass keeps using
17
+ the main provider_name/model. This prevents a model from checking its
18
+ own output for errors with the same blind spots. §45 (SQ7) moved WHERE
19
+ that pair comes from: core/pipeline_models.resolve("critic") owns the
20
+ precedence -- a `/critic` choice in the user-tier store, else
21
+ config.CRITIC_MODEL -- so the routing is reachable without editing the
22
+ checkout, which for §11's whole life it was not.
23
+
24
+ ROADMAP §3 (malformed-JSON recovery): JSON-emitting passes are wrapped in
25
+ _run_pass_with_json_retry, which on a parse failure re-enters the SAME
26
+ pass-thread via RunAgentLoop.continue_conversation() with a corrective
27
+ follow-up message. The failed assistant turn is already in the thread's
28
+ history (see _run()'s always-persist fix in core/loop.py), so the model
29
+ sees its own prior output in context. Up to config.MAX_JSON_RETRIES
30
+ corrective attempts are made; a final ValueError surfaces unrecoverable
31
+ failures.
32
+
33
+ ROADMAP §5 (durable pipeline persistence): each run is wrapped in a
34
+ try/except that records status='failed' (with a snapshot of the partial
35
+ run) before re-raising, so a mid-pipeline crash still leaves a durable
36
+ record. A data-only update_pipeline_run() checkpoint fires after every
37
+ run.log() trace line, so even a hard kill (KeyboardInterrupt / SystemExit,
38
+ which bypass the except Exception block) leaves the record populated
39
+ through the last completed pass. load_pipeline_run() in
40
+ pipeline_storage.py provides the read API.
41
+
42
+ ROADMAP_v2 §22 (pipeline observability): the pipeline is a GENERATOR
43
+ yielding PipelineEvents (core/reasoning/events.py), so a shell can render
44
+ pass boundaries, trace lines, claim tiers and retries as they happen
45
+ rather than waiting for the whole run. Two names:
46
+
47
+ stream_deep_research_pipeline() the generator
48
+ run_pipeline_to_completion() the drainer, for a caller that wants
49
+ only the finished PipelineRun
50
+
51
+ DECISION P3 IS RETIRED, and it is worth saying why rather than quietly
52
+ dropping a name. P3 kept a third, synchronous `run_deep_research_pipeline()`
53
+ -- the drainer applied to the generator -- so that "every existing caller:
54
+ main.py, tui/app.py and fifteen test sites" would go on working unchanged.
55
+ Both shells then left of their own accord: `main.run_research` and
56
+ `tui/app.py` iterate the generator so they can render progress, each with a
57
+ comment saying it deliberately does not call the wrapper. That left a
58
+ public function with no production caller and fifty call sites in tests,
59
+ while this docstring went on naming it the live entry point. The
60
+ convenience moved to `tests/conftest.run_pipeline`, which is what it had
61
+ become; P3's argument was sound and its premise expired.
62
+
63
+ Decision P2: a pass's own LoopEvents are NOT forwarded up as LoopEvents --
64
+ _run_pass TRANSLATES a chosen subset into PipelineEvents (§26 amended this;
65
+ §22 had kept a pass fully opaque). It iterates
66
+ RunAgentLoop.stream_deep_research_mode() directly. `run_deep_research_mode`,
67
+ the synchronous wrapper this line used to name, is gone for
68
+ `run_deep_research_pipeline`'s reason and one layer down.
69
+ """
70
+
71
+ from __future__ import annotations
72
+
73
+ import json
74
+ import logging
75
+
76
+ import config
77
+ import prompts.system_prompts as system_prompts
78
+ from core import pipeline_models
79
+ from core.config_loader import effective_confidence, effective_source_scoring
80
+ from core.loop import RunAgentLoop, advertisement_facts
81
+ from core.reasoning.base import Claim, PipelineRun, resolve_by_id
82
+ from core.reasoning.confidence_scoring import run_confidence_tiering
83
+ from core.reasoning.events import PipelineEvent
84
+ from core.reasoning.json_retry import parse_json_response as _parse_json_response
85
+ from core.reasoning.json_retry import retry_until_json
86
+ from core.reasoning.payload_validation import validate as _validate_payload
87
+ from core.reasoning.pipeline_storage import create_pipeline_run, update_pipeline_run
88
+ from core.reasoning.scholar import ScholarLookup
89
+ from core.reasoning.source_corpus import SourceCorpus
90
+ from core.reasoning.source_scoring import make_scorer, score_grounding_sources
91
+ from safety.policy_enforcement import redact_secrets
92
+ from tools.registry import registry
93
+
94
+ logger = logging.getLogger(__name__)
95
+
96
+ DEFAULT_PROVIDER = "ANTHROPIC"
97
+ FLAGGED_TIERS = {"LOW", "UNVERIFIED"}
98
+ MAX_RETRIES = config.MAX_PIPELINE_RETRIES
99
+ # The JSON-retry budget lives in core/reasoning/json_retry.py since the
100
+ # §20 extraction; a second constant here was a dead knob that invited
101
+ # no-op patches (review §19-20 f9).
102
+
103
+ _CLAIM_INPUT_FIELDS = {"id", "text", "type", "entities", "source_span", "asserted_by_candidates"}
104
+
105
+
106
+ # ============================================================================
107
+ # ---- Small helpers ----------------------------------------------------------
108
+ # ============================================================================
109
+
110
+ class _Progress:
111
+ """The ONE place a trace line becomes durable and becomes an event
112
+ (§22 AC3).
113
+
114
+ Before §22 this file paired every `run.log(...)` with an
115
+ `update_pipeline_run(...)` at twenty call sites, and `run.trace` had
116
+ THREE writers: those, review.py's fifteen `run.log()` calls (which
117
+ checkpointed nowhere), and json_retry.py's bare `trace.append()` per
118
+ failed parse. So "§5's persistence fires on every trace line" was
119
+ already untrue, and adding a per-call-site event emission would have
120
+ made it two independent writers of related data -- the bug shape §22
121
+ warns about by name.
122
+
123
+ So both are DERIVED from `run.trace` itself. `checkpoint()` emits
124
+ every line appended since it last ran and then persists. Because the
125
+ watermark reads the list rather than the call site, review.py's and
126
+ json_retry.py's lines are picked up too, WITHOUT either module being
127
+ edited or knowing this exists.
128
+
129
+ The watermark lives here rather than on PipelineRun because base.py
130
+ is data only and §5 serializes that object -- a field meaningful
131
+ only inside a live generator has no business in a persisted row.
132
+ """
133
+
134
+ def __init__(self, run: PipelineRun) -> None:
135
+ self.run = run
136
+ self._emitted = 0
137
+
138
+ def checkpoint(self, message: str | None = None):
139
+ """Log (optionally), PERSIST, then emit every un-emitted line.
140
+
141
+ Persist BEFORE emitting, not after. A generator only advances
142
+ while someone iterates it, so a consumer that abandons the run
143
+ between the yield and the persist would take that checkpoint down
144
+ with it -- §5's durability would silently start depending on a
145
+ UI's willingness to keep reading. This way, a line is already in
146
+ the record by the time anyone is told about it.
147
+
148
+ Monotonic: `_emitted` only ever advances, so no line can be
149
+ yielded twice however many times this is called.
150
+ """
151
+ if message is not None:
152
+ self.run.log(message)
153
+ update_pipeline_run(self.run.run_id, self.run)
154
+ while self._emitted < len(self.run.trace):
155
+ line = self.run.trace[self._emitted]
156
+ self._emitted += 1
157
+ yield PipelineEvent(kind="trace_line", text=line)
158
+
159
+
160
+ # One pass_activity event per this many characters streamed. A per-token
161
+ # event would be thousands of post_message hand-offs per pass, which is the
162
+ # cost Transcript.stream_delta already exists to avoid on the chat path.
163
+ _ACTIVITY_CHARS = 2000
164
+
165
+ # §26's _param_digest, and its two truncation constants, MOVED to
166
+ # safety/policy_enforcement.py in §27 -- beside redact_secrets, because
167
+ # §27's replay renderer is its second caller and the redact-before-truncate
168
+ # ordering must not exist twice. Imported under its own name rather than
169
+ # aliased back to the old private one: an alias would leave two spellings
170
+ # for one function, and a reader who greps the old name here should be sent
171
+ # to where it now lives, not handed a local rebinding.
172
+
173
+
174
+ def _translate(pass_id: str, stream, corpus=None):
175
+ """Turn one pass's LoopEvents into PipelineEvents, and return the
176
+ ModelResponse the pass produced (ROADMAP_v2 §26).
177
+
178
+ THE one place a LoopEvent becomes a PipelineEvent. Both _run_pass and
179
+ _run_pass_with_json_retry consume this rather than each iterating the
180
+ stream themselves -- two emission sites for the same translation is how
181
+ they drift, and this file has the twenty-checkpoint version of that
182
+ mistake in its own history (see _Progress).
183
+
184
+ What is translated is a SUBSET, chosen for what a person watching a
185
+ ten-pass run needs:
186
+
187
+ tool_call / tool_result the thing §22 P2 made invisible. A pass
188
+ making fourteen fetch_url calls over
189
+ several minutes looked exactly like one
190
+ that had hung.
191
+ pass_activity for the passes that call no tools at all.
192
+ Throttled: a total, every _ACTIVITY_CHARS.
193
+
194
+ What is NOT translated, and why:
195
+
196
+ token_delta text seven of the ten passes emit raw JSON, so
197
+ streaming pass output into a transcript
198
+ buries the report under it. Only the volume
199
+ escapes, never the content.
200
+ thinking_delta §38 (O5). Not translated AND not counted
201
+ into pass_activity's running total, so
202
+ `chars` keeps meaning one thing -- output
203
+ streamed so far -- rather than quietly
204
+ becoming two instruments the way batch 27
205
+ item 9 describes for the token figures. The
206
+ cost is stated rather than hidden: a pass
207
+ that thinks for minutes before writing
208
+ anything shows no activity, which is the
209
+ shape §26 built pass_activity to cure. Flip
210
+ it here if that turns up in a real run.
211
+ permission_request §25's ApprovalProvider already carries this
212
+ to the shell and blocks on the answer. A
213
+ second rendering of a question already on
214
+ screen is not observability.
215
+ notice a pass's compaction notices, forwarded as
216
+ trace LINES. M6 makes these backstop-only,
217
+ but "rare" is not "silent" -- §21's rule
218
+ has no exception for the pipeline, and a
219
+ backstop fold rewrites what the REST of
220
+ the pass sees. This used to drop them with
221
+ the claim that they "already reach the
222
+ shell as WARNING log records", which was
223
+ true of blocked and failed compactions and
224
+ FALSE of successful ones (INFO only --
225
+ audit #172). A trace line lands in
226
+ trace.md and both shells print it.
227
+
228
+ §45 (SQ2). `corpus` is a SECOND SINK for tool results, not a change to
229
+ what is translated. The rule above -- a successful result body never
230
+ reaches the UI -- is unchanged; this is a different consumer with a
231
+ different need, and the scoring stage cannot check a quote against a
232
+ page nobody kept. None, the default, collects nothing: that is every
233
+ caller that predates §45 and every test double."""
234
+ names: dict = {} # tool_call id -> name, since tool_result has none
235
+ streamed = 0
236
+ announced = 0
237
+ while True:
238
+ # next() rather than `for event in stream`, because a for loop
239
+ # SWALLOWS the generator's return value -- and the response is
240
+ # returned rather than read off the terminal event precisely
241
+ # because thread_id is attached after the loop finishes. A for
242
+ # loop here would hand every pass a response with no thread_id,
243
+ # and the only symptom would be §3's JSON retry silently starting
244
+ # a new thread instead of correcting the failed one.
245
+ try:
246
+ event = next(stream)
247
+ except StopIteration as stop:
248
+ return stop.value
249
+
250
+ if event.token_delta:
251
+ streamed += len(event.token_delta)
252
+ if streamed - announced >= _ACTIVITY_CHARS:
253
+ announced = streamed
254
+ yield PipelineEvent(kind="pass_activity", pass_id=pass_id,
255
+ chars=streamed)
256
+ if event.notice:
257
+ yield PipelineEvent(
258
+ kind="trace_line",
259
+ text=f"compaction during {pass_id}: {event.notice['text']}")
260
+ if event.tool_call_start:
261
+ name = event.tool_call_start.get("name")
262
+ names[event.tool_call_start.get("id")] = name
263
+ yield PipelineEvent(
264
+ kind="tool_call", pass_id=pass_id, tool=name,
265
+ # §42 (RA3): through the registry, so a tool's
266
+ # declared rationale param is dropped here too -- a
267
+ # pass row is as narrow as a transcript line.
268
+ text=registry.call_digest(
269
+ name, event.tool_call_start.get("input")))
270
+ if event.tool_result:
271
+ result = event.tool_result.get("result")
272
+ failed = isinstance(result, dict) and "error" in result
273
+ name = names.get(event.tool_result.get("id"))
274
+ if corpus is not None and not failed:
275
+ # BEFORE the yield, for #42's reason one layer up: a
276
+ # generator only advances while someone iterates it, so
277
+ # collecting after the yield would make the corpus depend
278
+ # on a consumer continuing to read. `corpus.add` ignores
279
+ # every tool it does not recognise.
280
+ corpus.add(name, result)
281
+ yield PipelineEvent(
282
+ kind="tool_result", pass_id=pass_id,
283
+ tool=name,
284
+ ok=not failed,
285
+ # Redacted here too, though dispatch() already ran the
286
+ # result through check_output_policy. One rule owned at one
287
+ # boundary -- "nothing leaves this function unredacted" --
288
+ # beats depending on a guarantee made two layers away that
289
+ # a later refactor could quietly drop.
290
+ text=redact_secrets(str(result.get("error"))) if failed else None)
291
+
292
+
293
+ def _check_not_truncated(pass_id: str, response, trace: list[str] | None):
294
+ """A pass that ended on a stop condition did NOT finish; say so.
295
+
296
+ `_run_pass` used to return `response.text` and discard `stop_reason`,
297
+ so a pass cut off by the token budget looked exactly like one that
298
+ completed -- and because a budget stop returns the last response AS
299
+ IT STANDS, a pass that was mid-tool-call returned the EMPTY STRING.
300
+
301
+ That is not hypothetical. A Pass 1 making 14 tool calls crossed the
302
+ old 250k ceiling, returned "", and the orchestrator stored it as
303
+ raw_response. Pass 2 was then handed "Response to extract claims
304
+ from:\\n" and correctly answered that there was nothing to extract --
305
+ in a shape that is not a claim list -- and the run finally died in
306
+ Claim's constructor, three passes and one confusing TypeError away
307
+ from the thing that actually went wrong.
308
+
309
+ TWO outcomes, because truncation is not uniformly fatal:
310
+
311
+ * truncated WITH text -- degraded but usable. The pass produced an
312
+ answer and was cut off finishing it; downstream passes can work
313
+ with that. Traced, so the report's own audit log says the answer
314
+ was incomplete, and the run continues.
315
+ * truncated with NO text -- unusable. Everything downstream is
316
+ working from an empty string, and the only question is how many
317
+ passes it takes to produce an incomprehensible error. Raise here,
318
+ naming the pass and the stop reason.
319
+ """
320
+ stop = getattr(response, "stop_reason", None)
321
+ if stop in (None, "complete"):
322
+ return
323
+ text = (getattr(response, "text", "") or "").strip()
324
+ # #4: the figures turn a bare reason into a diagnosis. A user who
325
+ # reads token_budget_exceeded as a context problem is repeating the
326
+ # exact misreading item 9 recorded.
327
+ billed = getattr(response, "turn_billed_tokens", None)
328
+ figures = (f" billed {billed:,} this turn"
329
+ if isinstance(billed, int) else "")
330
+ if not text:
331
+ raise ValueError(
332
+ f"{pass_id} ended on {stop!r} with no text{figures}. A stop "
333
+ f"condition returns the last response as it stands, so a pass "
334
+ f"cut off mid-tool-call yields an empty string -- and every "
335
+ f"later pass would be working from nothing. "
336
+ f"(config.MAX_ITERATIONS and a configured settings.json "
337
+ f"max_token_budget spend cap are the two ceilings that "
338
+ f"produce this.)"
339
+ )
340
+ message = (f"{pass_id}: TRUNCATED ({stop}{figures}) -- the pass was cut "
341
+ f"off but produced output; continuing with what it returned.")
342
+ logger.warning("%s", message)
343
+ if trace is not None:
344
+ trace.append(message)
345
+
346
+
347
+ def _ensemble_roster(ensemble_mode: bool) -> list[dict]:
348
+ """The (provider_name, model) pairs Pass 1 runs on, or [] when ensemble
349
+ mode is off. Raises ValueError on a roster that cannot produce a
350
+ meaningful consistency signal (ROADMAP §10 revisit, E1/E5).
351
+
352
+ A separate function so every refusal is testable without running a
353
+ pipeline, and so the reasons stay together: this replaces §16's
354
+ sampling-parameter guard, which refused for a mechanism that no longer
355
+ exists.
356
+
357
+ Validated by SHAPE only -- provider names and API keys are not checked
358
+ here (E6). §16's /model warns rather than refuses on an empty API_KEY so
359
+ a local OpenAI-compatible endpoint stays usable, and MCP's posture is
360
+ that validation happens by connecting. A candidate whose provider is
361
+ unreachable is named, traced and skipped at run time instead.
362
+ """
363
+ if not ensemble_mode:
364
+ return []
365
+
366
+ roster = config.ENSEMBLE_MODELS
367
+ if not roster:
368
+ raise ValueError(
369
+ "Ensemble mode is on but config.ENSEMBLE_MODELS is empty. "
370
+ "Diversity comes from different models now, not from a raised "
371
+ "temperature (ROADMAP §10 revisit), so the roster is required. "
372
+ "Set it in config.py to a list of at least two distinct "
373
+ '{"provider_name": ..., "model": ...} entries, or disable '
374
+ "ensemble_mode. There is deliberately no settings.json key for "
375
+ "the roster -- see E2."
376
+ )
377
+
378
+ for entry in roster:
379
+ if not isinstance(entry, dict) or not entry.get("provider_name") or not entry.get("model"):
380
+ raise ValueError(
381
+ f"Malformed config.ENSEMBLE_MODELS entry {entry!r}: every "
382
+ f'entry needs both "provider_name" and "model".'
383
+ )
384
+
385
+ # DISTINCT pairs, not merely two entries. Repeating one model N times
386
+ # would generate N near-identical candidates -- there is no sampling
387
+ # variation left to make them differ -- and then report maximal
388
+ # cross-candidate consistency for every claim, which Pass 5 reads as
389
+ # confidence. That is precisely the failure §16's guard was added to
390
+ # prevent, and this config is the way to recreate it.
391
+ distinct = {(e["provider_name"], e["model"]) for e in roster}
392
+ if len(distinct) < 2:
393
+ raise ValueError(
394
+ f"Ensemble mode needs at least two DISTINCT models; "
395
+ f"config.ENSEMBLE_MODELS resolves to {len(distinct)} "
396
+ f"({sorted(distinct)}). One model cannot disagree with itself, so "
397
+ f"every claim would score maximal consistency and Pass 5 would "
398
+ f"read that as confidence."
399
+ )
400
+ return list(roster)
401
+
402
+
403
+ def _pass_failed_event(pass_id: str, exc: BaseException) -> PipelineEvent:
404
+ """E14/#115. The one shape a pass failure is reported in: a
405
+ pass_complete carrying ok=False, mirroring tool_result's
406
+ outcome-plus-reason contract. A NEW kind was considered and rejected
407
+ -- tool_result already established payload-carried outcomes in this
408
+ very event set, and a second mechanism for 'ended' would make every
409
+ future consumer learn which applies where. The text is TRUNCATED:
410
+ the trace line (run.log at whatever site caught this) carries the
411
+ full cause, and an event payload is not the place to duplicate it
412
+ unboundedly."""
413
+ return PipelineEvent(
414
+ kind="pass_complete", pass_id=pass_id, ok=False,
415
+ text=f"{type(exc).__name__}: {exc}"[:200])
416
+
417
+
418
+ def _run_pass(pass_id: str, pass_input: str, model: str, provider_name: str,
419
+ temperature: float | None = None, authorization=None,
420
+ trace: list[str] | None = None, pass_threads: list | None = None,
421
+ effort: str | None = None, corpus=None):
422
+ """One LLM-backed pass. Every actual model call in this file goes
423
+ through this single function.
424
+
425
+ §22: a GENERATOR that yields the pass boundary and returns the
426
+ response text (`text = yield from _run_pass(...)`). The pass id is
427
+ named once here rather than restated beside twelve call sites.
428
+
429
+ §26: the pass is now ITERATED rather than called, through _translate,
430
+ so what it does between its start and its end is visible. Same shape
431
+ as §22's own change to the shells -- the drainer still exists and is
432
+ still what every other caller uses.
433
+
434
+ Batch 25 (#139): effort reaches the passes like authorization does --
435
+ threaded from the shell's setting through the pipeline, validated per
436
+ RECEIVING model by effort_for() inside the loop, so an ensemble roster
437
+ or critic routing needs no effort-specific handling here.
438
+ """
439
+ yield PipelineEvent(kind="pass_start", pass_id=pass_id)
440
+ try:
441
+ response = yield from _translate(pass_id, RunAgentLoop.stream_deep_research_mode(
442
+ pass_input=pass_input, model=model, pass_id=pass_id, provider_name=provider_name,
443
+ temperature=temperature, authorization=authorization, effort=effort,
444
+ ), corpus=corpus)
445
+ _record_granted_calls(pass_id, response, authorization)
446
+ _record_pass_thread(pass_id, response, pass_threads)
447
+ _check_not_truncated(pass_id, response, trace)
448
+ except Exception as exc:
449
+ # E14/#115, UNIFORM: a fatal pass reports itself before its
450
+ # exception propagates, so no shell is left holding a row that
451
+ # only ever says "running" -- the same property the ensemble
452
+ # skip path needs, reached from the one site both share.
453
+ yield _pass_failed_event(pass_id, exc)
454
+ raise
455
+ yield PipelineEvent(kind="pass_complete", pass_id=pass_id, ok=True)
456
+ return response.text
457
+
458
+
459
+ def _record_pass_thread(pass_id: str, response, pass_threads) -> None:
460
+ """Note which thread this pass ran in (§27 T2 / AC6).
461
+
462
+ BEFORE _check_not_truncated, which can raise: the thread of a pass that
463
+ died mid-tool-call is the single most useful one to be able to open, and
464
+ recording after the check would lose exactly that one.
465
+
466
+ `pass_threads` IS `run.pass_threads`, shared by reference for the same
467
+ reason §25's granted_calls is: one object means the record is already on
468
+ the run at every §5 checkpoint and on the failure path, rather than
469
+ being assembled at the end by a run that reached the end.
470
+
471
+ A separate optional argument rather than a `run` parameter, because
472
+ `trace` beside it is a list too and _run_pass_with_json_retry takes it
473
+ positionally in twelve call sites -- swapping both for the run object is
474
+ a bigger change than §27 asked for. Default None keeps every test double
475
+ that calls these two functions working.
476
+ """
477
+ if pass_threads is None:
478
+ return
479
+ thread_id = getattr(response, "thread_id", None)
480
+ if thread_id is None:
481
+ return
482
+ pass_threads.append({"pass": pass_id, "thread_id": str(thread_id)})
483
+
484
+
485
+ def _record_granted_calls(pass_id: str, response, authorization) -> None:
486
+ """Note calls that ran on a pre-flight grant (§25 audit trail).
487
+
488
+ Authorization moved up-front, so accountability moves after: this is
489
+ the record of what one launch-time yes actually authorised, for a run
490
+ nobody was watching.
491
+
492
+ Accumulated ON THE AUTHORIZATION BUNDLE rather than in module state or
493
+ a thirteenth argument. The bundle is already shared by reference across
494
+ every pass -- that is how GrantBudget counts one ceiling rather than
495
+ ten -- and what the authorization was spent on is authorization state.
496
+ A module global would also break the moment two pipelines ran.
497
+ """
498
+ if authorization is None:
499
+ return
500
+ for call in getattr(response, "granted_calls", ()) or ():
501
+ authorization.granted_calls.append({"pass": pass_id, **call})
502
+
503
+
504
+ def _run_pass_with_json_retry(
505
+ pass_id: str,
506
+ pass_input: str,
507
+ model: str,
508
+ provider_name: str,
509
+ trace: list[str] | None = None,
510
+ temperature: float | None = None,
511
+ authorization=None,
512
+ pass_threads: list | None = None,
513
+ claim_ids: list | None = None,
514
+ ensemble: bool = False,
515
+ effort: str | None = None,
516
+ corpus=None,
517
+ ):
518
+ """Runs one JSON-emitting pass and recovers from malformed JSON.
519
+
520
+ The recovery itself lives in core/reasoning/json_retry.py, shared with
521
+ §20's reviewer. All this function adds is the pass's own first attempt
522
+ and the two pass-specific facts the shared loop cannot know: which
523
+ system prompt to continue under, and that a retry's tool calls belong
524
+ on the same §25 audit trail as the original attempt's.
525
+
526
+ ROADMAP §3: attempts = max_retries + 1 (1 initial +
527
+ config.MAX_JSON_RETRIES corrective, per core/reasoning/json_retry.py).
528
+ Unrecoverable failure raises ValueError with the final parse error
529
+ attached; the caller's try/except turns that into a durable
530
+ status='failed' record.
531
+
532
+ §30 (B3): the payload spec is bound HERE, from the pass id, rather
533
+ than passed in by each of the eight call sites. A call site that
534
+ forgot the argument would be silently unvalidated, which is the exact
535
+ condition this batch exists to remove -- and payload_validation.validate
536
+ raises on a pass id it has no spec for, so an eleventh JSON-emitting
537
+ pass cannot arrive by omission.
538
+
539
+ This function still returns TEXT, deliberately, even though it now
540
+ parses the payload internally to check it. Around twenty test sites
541
+ patch or drain it and assert on the returned string, and §20's
542
+ reviewer shares retry_until_json's contract; re-parsing a short string
543
+ is cheaper than moving twenty seams in the batch that adds the check.
544
+
545
+ `claim_ids` is the set the APPLY step will resolve against -- every
546
+ claim for 3a/3b/5/6c, the currently-flagged batch for 6a -- because
547
+ validating against a wider set would accept an entry that then lands
548
+ on nothing.
549
+
550
+ §22: a generator, like _run_pass, and for the same reason. The
551
+ corrective attempts inside retry_until_json need no event kind of
552
+ their own -- that function already appends a trace line per failed
553
+ parse, so _Progress's watermark carries them to the consumer at the
554
+ next checkpoint with json_retry.py untouched. pass_complete fires
555
+ after the retries resolve, so a pass is not reported finished while
556
+ it is still arguing with the model about JSON.
557
+
558
+ §26 limit, stated rather than fixed: the FIRST attempt is translated,
559
+ the retries are not. retry_until_json reaches the model through
560
+ continue_conversation(), which drains its own loop internally, so a
561
+ tool call made while correcting malformed JSON produces no tool_call
562
+ event. Making it visible means a streaming sibling for
563
+ continue_conversation too, which is chat's entry point as well -- a
564
+ larger change than the thing it would show.
565
+
566
+ §45 inherits that limit rather than widening it: a page fetched during
567
+ a corrective retry reaches no corpus either, so a source cited only
568
+ from such a fetch scores with `similarity_method: "llm"` like any
569
+ other source with no captured text. It degrades to the documented
570
+ fallback instead of to a wrong number, which is why the limit is
571
+ stated here and not worked around.
572
+ """
573
+ yield PipelineEvent(kind="pass_start", pass_id=pass_id)
574
+ try:
575
+ response = yield from _translate(pass_id, RunAgentLoop.stream_deep_research_mode(
576
+ pass_input=pass_input, model=model, pass_id=pass_id, provider_name=provider_name,
577
+ temperature=temperature, authorization=authorization, effort=effort,
578
+ ), corpus=corpus)
579
+ _record_granted_calls(pass_id, response, authorization)
580
+ # §27: the retries re-enter THIS thread (continue_conversation), so one
581
+ # entry per pass is the whole truth however many corrections it took.
582
+ _record_pass_thread(pass_id, response, pass_threads)
583
+ # BEFORE the retry loop. A truncated pass returned no JSON because it
584
+ # was cut off, not because the model wrote malformed JSON -- sending
585
+ # a "your last response did not parse" nudge into a thread that has
586
+ # already exhausted its budget spends more of it to be told the same
587
+ # thing, and reports a parse failure for something that never parsed
588
+ # because it was never finished.
589
+ _check_not_truncated(pass_id, response, trace)
590
+
591
+ text = retry_until_json(
592
+ response,
593
+ label=pass_id,
594
+ # pass_prompt(), NOT the raw pass file: BOTH the original attempt
595
+ # and its retry must carry the same catalogs, or a retry silently
596
+ # sees a different tool set than the attempt it is correcting.
597
+ # #68 makes that literal -- the same AUTHORIZATION decides the
598
+ # catalogs here as decided them for the attempt.
599
+ system_prompt=system_prompts.pass_prompt(
600
+ pass_id, *advertisement_facts(authorization)),
601
+ model=model,
602
+ provider_name=provider_name,
603
+ trace=trace,
604
+ temperature=temperature,
605
+ authorization=authorization,
606
+ effort=effort,
607
+ on_response=lambda r: _record_granted_calls(pass_id, r, authorization),
608
+ # The retry re-enters THIS pass's thread. No separate pass
609
+ # ceiling any more (#4): omitting the kwarg lets the wrapper
610
+ # resolve the configured spend cap, exactly as the pass itself
611
+ # did.
612
+ validate=lambda payload: _validate_payload(
613
+ pass_id, payload, claim_ids=claim_ids, ensemble=ensemble),
614
+ )
615
+ except Exception as exc:
616
+ # E14/#115: same uniform failure report as _run_pass -- a JSON
617
+ # pass that exhausts its retries is a pass that ended badly,
618
+ # whatever the exception class.
619
+ yield _pass_failed_event(pass_id, exc)
620
+ raise
621
+ yield PipelineEvent(kind="pass_complete", pass_id=pass_id, ok=True)
622
+ return text
623
+
624
+
625
+ def _claim_from_json(raw: dict) -> Claim:
626
+ """Filters to known input fields so an unexpected extra key from the
627
+ model doesn't crash claim construction; required fields (id/text/type)
628
+ still raise if genuinely missing."""
629
+ filtered = {k: v for k, v in raw.items() if k in _CLAIM_INPUT_FIELDS}
630
+ return Claim(**filtered)
631
+
632
+
633
+ # ROADMAP_v2 §30 (B5). THE THREE _apply_* FUNCTIONS RETURN WHAT THEY
634
+ # APPLIED, and their checkpoint lines interpolate that rather than the
635
+ # count the pass was ASKED about.
636
+ #
637
+ # `Pass 3a: grounded {len(unique_entities)} unique entities across
638
+ # {len(factual_claims)} factual claim(s).` is emitted verbatim whether
639
+ # every entry landed or none did -- it is built entirely from this side of
640
+ # the call. Driven with 3a/3b answering about ids Pass 2 never issued, the
641
+ # run reported grounding 4 entities across 3 claims while grounding
642
+ # nothing, then spent four more model calls in the 6a/6c loop and reported
643
+ # that nothing could be verified. base.py:87 calls the trace "at least as
644
+ # trustworthy an artifact as the final report itself"; a line derived from
645
+ # its own input cannot be.
646
+ #
647
+ # A count of CLAIMS TOUCHED, not entries consumed: a pass that answers
648
+ # twice about one claim has affected one claim, and the reader is deciding
649
+ # whether the pass did its job.
650
+
651
+
652
+ def _apply_grounding(claims: list[Claim], grounding_entries: list[dict]) -> int:
653
+ by_id = resolve_by_id(claims)
654
+ applied = set()
655
+ for entry in grounding_entries:
656
+ claim = by_id.get(entry.get("claim_id"))
657
+ if claim:
658
+ claim.grounding_sources = entry.get("sources", [])
659
+ claim.grounding_status = entry.get("status")
660
+ applied.add(claim.id)
661
+ return len(applied)
662
+
663
+
664
+ def _ground_and_score(run: PipelineRun, grounding_entries: list[dict], corpus,
665
+ scorer=None, knobs=None, scholar=None) -> int:
666
+ """Apply Pass 3a/6b's grounding, then everything §45 derives from it.
667
+
668
+ THE ONE SEAM BOTH GROUNDING SITES GO THROUGH. There are two -- Pass 3a
669
+ and Pass 6b's re-validation -- and §45 adds work that has to happen at
670
+ both: a source scored only on the run's first grounding would carry a
671
+ stale number after a revision changed the claim it was scored against.
672
+ Deriving beside each call instead is the shape the "fix at the
673
+ producer" rule exists to prevent, and a third caller could then arrive
674
+ without it.
675
+
676
+ Returns what `_apply_grounding` returned, so the checkpoint lines that
677
+ interpolate it keep reporting what was APPLIED rather than what the
678
+ pass was asked about (§30, B5).
679
+
680
+ `run.source_documents` is refreshed HERE, and this is its only writer.
681
+ Late enough to include everything grounding retrieved, and early
682
+ enough that a run dying in a later pass still carries the evidence it
683
+ had already gathered -- the failure path being where an unattended
684
+ run's record matters most.
685
+ """
686
+ applied = _apply_grounding(run.claims, grounding_entries)
687
+ if corpus is not None:
688
+ run.source_documents = corpus.artifact_entries()
689
+ knobs = knobs or {}
690
+ score_grounding_sources(
691
+ run, corpus=corpus, scorer=scorer, scholar=scholar,
692
+ overrides=knobs.get("domain_overrides"),
693
+ **{k: knobs[k] for k in ("window_chars", "max_windows",
694
+ "claim_min_chars",
695
+ "authority_adjustment_cap") if k in knobs})
696
+ return applied
697
+
698
+
699
+ def _sources_were_scored(run: PipelineRun) -> bool:
700
+ """Whether §45's scoring stage ran for this run.
701
+
702
+ Pass 5 needs this because an empty source list is AMBIGUOUS on its own
703
+ -- "the model claimed grounded and cited nothing" on a scored run,
704
+ "this claim was built without a scoring stage" everywhere else -- and
705
+ only the first should cost a claim its grounding weight.
706
+
707
+ Derived from the run rather than tracked in a flag, so it cannot go
708
+ stale: the stage runs exactly when Pass 3a produced grounding, which
709
+ is exactly when some factual claim carries a status.
710
+ """
711
+ return any(c.grounding_status is not None for c in run.claims)
712
+
713
+
714
+ def _apply_critic(claims: list[Claim], critic_entries: list[dict]) -> int:
715
+ by_id = resolve_by_id(claims)
716
+ applied = set()
717
+ for entry in critic_entries:
718
+ claim = by_id.get(entry.get("claim_id"))
719
+ if claim:
720
+ claim.fallacies = entry.get("fallacies", [])
721
+ claim.contradictions = entry.get("contradictions", [])
722
+ claim.critic_severity = entry.get("severity", 0.0)
723
+ applied.add(claim.id)
724
+ return len(applied)
725
+
726
+
727
+ def _apply_assumption_flags(claims: list[Claim], assumptions: dict) -> int:
728
+ by_id = resolve_by_id(claims)
729
+ applied = set()
730
+ for claim_id, flags in assumptions.get("per_claim_flags", {}).items():
731
+ claim = by_id.get(claim_id)
732
+ if claim:
733
+ claim.assumption_flags = flags
734
+ applied.add(claim.id)
735
+ return len(applied)
736
+
737
+
738
+ def _synthesis_input(run: PipelineRun, directives: list | None = None) -> str:
739
+ """What final synthesis reads.
740
+
741
+ A FUNCTION, not a string built once. §20 re-runs synthesis after a
742
+ correction is accepted, and reusing the string built before the review
743
+ would regenerate the report from the UNCORRECTED claims -- producing a
744
+ report that changed for no reason while the correction silently went
745
+ nowhere.
746
+ """
747
+ text = (
748
+ f"Original query:\n{run.user_query}\n\n"
749
+ f"Final annotated claims:\n{json.dumps([vars(c) for c in run.claims])}\n\n"
750
+ f"Coverage gaps:\n{json.dumps(run.coverage_gaps)}"
751
+ )
752
+ if directives:
753
+ text += (
754
+ "\n\nA reviewer raised the following about the previous draft of "
755
+ "this report, and a human approved each one. Address them:\n"
756
+ + "\n".join(f"- {d}" for d in directives)
757
+ )
758
+ return text
759
+
760
+
761
+ def _review_stage(run: PipelineRun, progress: _Progress, model: str,
762
+ provider_name: str, authorization, review,
763
+ enabled: bool = False, effort: str | None = None):
764
+ """ROADMAP_v2 §20. Opt-in review of the finished run, with every
765
+ correction consented to individually.
766
+
767
+ §22: a generator, because it logs, checkpoints and runs a pass. It
768
+ takes the run's _Progress rather than making its own, so review.py's
769
+ trace lines -- which never checkpointed at all before §22 -- land on
770
+ the same watermark as everything else.
771
+
772
+ Called from INSIDE the orchestrator (V3) rather than left to each
773
+ shell. The obvious alternative -- a post-pipeline stage the caller
774
+ invokes, mirroring write_run_artifacts -- is exactly the shape that
775
+ produced this project's live asymmetry: that function has one
776
+ production call site, so /research in the TUI writes no output
777
+ directory at all. The consent OBJECT still comes from the shell,
778
+ because only a shell knows how to reach a human.
779
+
780
+ `enabled` and `review` are SEPARATE on purpose. "The user asked for a
781
+ review" and "someone can be asked about its findings" are different
782
+ facts, and collapsing them loses the case that matters: --review on a
783
+ piped run must still produce findings and still change nothing (V6).
784
+ If the consent object alone enabled the stage, that run would skip the
785
+ review entirely and report nothing at all.
786
+
787
+ A consent object with `enabled` false still runs it, because a caller
788
+ that went to the trouble of building one wants the review.
789
+
790
+ Batch 25 (#139): effort inherits into the reviewer (V7's rule applied
791
+ to one more axis) and into the re-synthesis pass below.
792
+ """
793
+ if not enabled and review is None:
794
+ return
795
+
796
+ from core.reasoning import review as review_module
797
+
798
+ findings, thread_id = review_module.run_review(
799
+ run, model, provider_name, authorization, effort=effort)
800
+ run.log(f"Review: {len(findings)} finding(s) raised.")
801
+ # The findings' CONTENT is durable from this checkpoint on (review
802
+ # r1-2): a kill during the consent walk used to leave only the count,
803
+ # with what the reviewer found unrecoverable. Trace is serialized by
804
+ # every update_pipeline_run, so this needs no new column (V8).
805
+ for f in findings:
806
+ target = f.get("claim_id") or "report"
807
+ excerpt = str(f.get("proposed") or "")[:80]
808
+ run.log(f"Review: finding -- {f.get('kind')} correction to {target}"
809
+ + (f": {excerpt}" if excerpt else ""))
810
+ yield from progress.checkpoint()
811
+
812
+ decisions = review_module.walk_consent(
813
+ findings, review, run, model=model, provider_name=provider_name,
814
+ thread_id=thread_id, authorization=authorization, effort=effort)
815
+ run.subagent_reviews = decisions
816
+ yield from progress.checkpoint()
817
+
818
+ # Deferred commit (review f4): corrections land on a copy, and the
819
+ # live claims/report change only after the re-synthesis succeeds. A
820
+ # failed re-synthesis therefore persists a consistent record -- the
821
+ # pre-fix order stored corrected claims beside the stale report.
822
+ changed, corrected, applied = review_module.apply_deferred(run, decisions)
823
+ if changed:
824
+ original_claims = run.claims
825
+ run.claims = corrected
826
+ try:
827
+ run.final_report = yield from _run_pass(
828
+ "Final synthesis",
829
+ _synthesis_input(run, review_module.synthesis_directives(decisions)),
830
+ model, provider_name, authorization=authorization,
831
+ trace=run.trace,
832
+ pass_threads=run.pass_threads,
833
+ effort=effort,
834
+ )
835
+ except Exception as e:
836
+ # CONTAINED, not re-raised. A provider error on this one call
837
+ # is the same transient class as a reviewer call failing, and
838
+ # f1 settled that an optional stage must not flip a finished
839
+ # ten-pass run to status='failed'. The deferred commit already
840
+ # guarantees a consistent record: the pre-review claims and the
841
+ # report generated from them, which is a complete run's output
842
+ # minus the corrections -- and the trace says which.
843
+ #
844
+ # A failure that escapes this STAGE (a bug, not a transient
845
+ # provider error) still reaches the pipeline's except and
846
+ # records status='failed'. That distinction is the whole
847
+ # policy, and both halves are test-pinned.
848
+ logger.exception("Review re-synthesis failed; corrections not applied.")
849
+ run.claims = original_claims
850
+ review_module.log_outcomes(run, decisions, applied, committed=False)
851
+ run.log(f"Review: re-synthesis failed ({e}); accepted corrections "
852
+ f"NOT applied -- claims and report left unchanged.")
853
+ yield from progress.checkpoint()
854
+ return
855
+ review_module.log_outcomes(run, decisions, applied, committed=True)
856
+ # NOT re-reviewed. The regress is cut deliberately: a review of the
857
+ # re-synthesised report would need its own consent pass, and so on.
858
+ run.log(f"Review: {len(applied)} correction(s) accepted; final "
859
+ f"synthesis re-run. The re-synthesised report is not "
860
+ f"re-reviewed.")
861
+ else:
862
+ review_module.log_outcomes(run, decisions, applied, committed=False)
863
+ run.log("Review: no correction applied; report unchanged.")
864
+ yield from progress.checkpoint()
865
+
866
+
867
+ def _stage(pass_id: str):
868
+ """One event for a stage that made ZERO model calls (§26).
869
+
870
+ A separate kind from pass_start/pass_complete rather than a pair of
871
+ those, because a code stage cannot meaningfully be "running": it
872
+ completes in the time it takes to yield, and a consumer that showed it
873
+ as in-progress would be showing a state that never exists. Pass 5 and
874
+ Pass 6c are passes by the pipeline's numbering and stages by their
875
+ cost, and this is the field that says which.
876
+
877
+ Before this, every zero-LLM stage was invisible to both shells -- not
878
+ by decision but because _run_pass was the only thing that emitted a
879
+ boundary, and it wraps a model call. So a sidebar showed Pass 4
880
+ followed by Pass 6a with the tiering that decided which claims were
881
+ flagged in between, unmentioned.
882
+ """
883
+ yield PipelineEvent(kind="stage", pass_id=pass_id)
884
+
885
+
886
+ def _tier_events(run: PipelineRun):
887
+ """One claim_tiered event per claim, after a tiering pass.
888
+
889
+ Called after EVERY run_confidence_tiering() -- Pass 5 and each 6b
890
+ round -- so a consumer sees a claim's tier change rather than only
891
+ its first value. Repeats are by design: the events are a stream of
892
+ "this is the tier now", and a panel re-renders from the latest.
893
+
894
+ Derived from run.claims after the fact rather than emitted inside
895
+ confidence_scoring.py, which makes zero LLM calls and knows nothing
896
+ about events; §22's own warning about two writers of related data
897
+ applies to the tiering just as it does to the trace.
898
+ """
899
+ for claim in run.claims:
900
+ yield PipelineEvent(kind="claim_tiered", claim_id=claim.id,
901
+ tier=claim.confidence_tier)
902
+
903
+
904
+ def _apply_fallback(claim: Claim) -> None:
905
+ """D2 exhausted / fallback branch -- pure code, no LLM call."""
906
+ claim.confidence_tier = "UNVERIFIED"
907
+ claim.annotation = (
908
+ f"[UNVERIFIED] Could not be adequately verified after {claim.retry_count} "
909
+ f"revision attempt(s). Treat with caution."
910
+ )
911
+ claim.final_text = claim.revision_text or claim.text
912
+
913
+
914
+ # ============================================================================
915
+ # ---- The pipeline ------------------------------------------------------
916
+ # ============================================================================
917
+
918
+ def run_pipeline_to_completion(gen) -> PipelineRun:
919
+ """Consumes a stream_deep_research_pipeline() generator fully,
920
+ discarding intermediate events, and returns the finished PipelineRun.
921
+
922
+ The exact counterpart of core.loop.run_to_completion(), including the
923
+ RuntimeError: a generator that ends without its terminal event has a
924
+ bug, and returning None instead would push the failure into whichever
925
+ caller dereferences the run first.
926
+ """
927
+ final = None
928
+ for event in gen:
929
+ if event.kind == "run_complete":
930
+ final = event.run
931
+ if final is None:
932
+ raise RuntimeError(
933
+ "Pipeline generator completed without yielding a run_complete event"
934
+ )
935
+ return final
936
+
937
+
938
+ def stream_deep_research_pipeline(
939
+ user_query: str,
940
+ model: str,
941
+ provider_name: str = DEFAULT_PROVIDER,
942
+ ensemble_mode: bool | None = None,
943
+ ensemble_n: int | None = None,
944
+ authorization=None,
945
+ review=None,
946
+ subagent_review: bool | None = None,
947
+ effort: str | None = None,
948
+ ):
949
+ """The pipeline, as a generator of PipelineEvents (§22). The terminal
950
+ `run_complete` event carries the finished PipelineRun.
951
+
952
+ ABANDONMENT (§22, recorded rather than fixed). A consumer that stops
953
+ iterating early -- a TUI quitting mid-run -- raises GeneratorExit
954
+ inside the try below, which `except Exception` deliberately does not
955
+ catch. The record therefore stays status='running', populated through
956
+ the last checkpoint. That is honest: the run was abandoned, not
957
+ failed, and forcing 'failed' would make an interrupted run
958
+ indistinguishable from a broken one. Both shipped consumers drain
959
+ fully.
960
+
961
+ authorization (§25): a core.approval.RunAuthorization built by the
962
+ shell that launched this run, or None for the pre-§25 behaviour (no
963
+ grants, nobody to ask, every approval-gated tool hidden from every
964
+ pass). Carried, not interpreted -- the decisions about WHAT may be
965
+ granted live in core/reasoning/authorization.py, and the enforcement
966
+ lives in core/loop.py.
967
+
968
+ review (§20): a core.interaction.ResponseChannel, or None (§23 moved
969
+ it there from core.approval.ReviewConsent). Carried the same
970
+ way and for the same reason -- only a shell knows how to reach a
971
+ human. A SECOND parameter rather than a field on the authorization
972
+ bundle: that bundle answers "may this gated call proceed?" and this
973
+ answers "may this edit be applied?". None means nothing is applied,
974
+ even when the review itself runs (V6).
975
+
976
+ subagent_review (§20/D9): whether the review stage runs at all. None
977
+ falls back to config.SUBAGENT_REVIEW, matching ensemble_mode's
978
+ pattern. Separate from `review` because --review on a piped run must
979
+ still produce findings while applying nothing."""
980
+ ensemble_mode = config.ENSEMBLE_MODE if ensemble_mode is None else ensemble_mode
981
+ subagent_review = (config.SUBAGENT_REVIEW if subagent_review is None
982
+ else subagent_review)
983
+
984
+ # §10 revisit (E4). `ensemble_n` is vestigial: N is len(ENSEMBLE_MODELS)
985
+ # now, because a separately configured count could disagree with the
986
+ # roster that produced the candidates, and the denominator of a
987
+ # confidence score must not be able to lie. The parameter and the
988
+ # settings.json key are KEPT rather than removed -- unknown settings keys
989
+ # raise, so deleting the key would make every existing settings.json that
990
+ # sets it fail to load.
991
+ if ensemble_n is not None:
992
+ logger.warning(
993
+ "Ignoring ensemble_n=%s: the number of candidates is "
994
+ "len(config.ENSEMBLE_MODELS) now (ROADMAP §10 revisit, E3). "
995
+ "Change the roster in config.py to change N.",
996
+ ensemble_n,
997
+ )
998
+
999
+ roster = _ensemble_roster(ensemble_mode)
1000
+
1001
+ run = PipelineRun(user_query=user_query)
1002
+
1003
+ # §45 (SQ2). RUN-SCOPED, and attached to every pass rather than only to
1004
+ # the two that ground. The question it answers is "what did this run
1005
+ # retrieve from this URL", which is not a per-pass question: a page
1006
+ # Pass 1 fetched and Pass 3a then cited without re-fetching is still
1007
+ # evidence about that URL, and scoping the corpus to 3a would report
1008
+ # no captured text for it and fall back to the model's own number.
1009
+ corpus = SourceCorpus()
1010
+
1011
+ # §45 (SQ2). Resolved ONCE, before Pass 0, so the warning about
1012
+ # running without one is the first thing the trace says rather than
1013
+ # something a reader meets forty lines in beside a score it already
1014
+ # explains. One scorer for the whole run, because its vector cache and
1015
+ # its give-up flag are both run-scoped: a claim is embedded once
1016
+ # however many sources it has, and a provider that is down stays down.
1017
+ scoring_knobs = effective_source_scoring(warn=True)
1018
+ scorer = make_scorer(run, floor=scoring_knobs["similarity_floor"],
1019
+ ceiling=scoring_knobs["similarity_ceiling"])
1020
+
1021
+ # §45 (SQ9). OFF by default, so an out-of-the-box run makes no call
1022
+ # the user did not ask for. One lookup object for the run, for the
1023
+ # scorer's reason: its cohort cache and its give-up flag are both
1024
+ # run-scoped.
1025
+ scholar = ScholarLookup(knobs=scoring_knobs)
1026
+
1027
+ # §45 (SQ6). Both knob sections resolved ONCE, here, with warn=True so
1028
+ # a mistyped weight is said once per run rather than once per claim --
1029
+ # `effective_compaction`'s gating, for its reason. score_claim stays a
1030
+ # pure function of its arguments, and a run's numbers cannot change
1031
+ # halfway through it.
1032
+ confidence_weights = effective_confidence(warn=True)
1033
+
1034
+ # §25 audit trail: ONE list, shared, not two kept in step. The run and
1035
+ # the authorization bundle now refer to the same object, so a granted
1036
+ # call is visible on the PipelineRun the moment it happens -- including
1037
+ # at every §5 checkpoint and on the FAILURE path, which is where an
1038
+ # unattended run's record matters most. Copying at the end instead
1039
+ # would lose the trail on exactly the runs most worth auditing, and two
1040
+ # writers of related data is the bug shape §22 warns about by name.
1041
+ if authorization is not None:
1042
+ run.granted_calls = authorization.granted_calls
1043
+
1044
+ # ROADMAP §5 minimal core: create the durable record up front. On a
1045
+ # mid-pipeline crash, the except block below flips status to 'failed'
1046
+ # and persists a snapshot of the partial run before re-raising.
1047
+ run.run_id = create_pipeline_run(user_query)
1048
+
1049
+ # ROADMAP §11: resolve critic provider/model once. When no critic is
1050
+ # configured these fall back to the main provider/model — no-op
1051
+ # routing.
1052
+ #
1053
+ # §45 (SQ7): through pipeline_models.resolve rather than
1054
+ # config.CRITIC_MODEL directly, so a `/critic` choice reaches the CLI,
1055
+ # the TUI and a spawned run alike. That function owns the precedence —
1056
+ # the user-tier store outranks config.py — and owning it in one place
1057
+ # is the point: §11 gave this routing to config.py alone, which meant
1058
+ # the methodology's own "a model must not check its own output" was
1059
+ # available only to whoever could edit the checkout.
1060
+ critic = pipeline_models.resolve("critic")
1061
+ critic_provider = critic["provider_name"] if critic else provider_name
1062
+ critic_model = critic["model"] if critic else model
1063
+
1064
+ progress = _Progress(run)
1065
+
1066
+ try:
1067
+ # --- Pass 0: preliminary plan ---
1068
+ run.plan = _parse_json_response((yield from _run_pass_with_json_retry("Pass 0", user_query, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, effort=effort)))
1069
+ yield from progress.checkpoint(f"Pass 0: plan produced ({len(run.plan.get('key_entities_or_subjects', []))} key entities anticipated).")
1070
+
1071
+ # --- Pass 1: initial generation (ensemble mode: N candidates) ---
1072
+ pass1_input = f"Original query:\n{user_query}\n\nPreliminary plan (loose context, may deviate freely):\n{json.dumps(run.plan)}"
1073
+ effective_n = 0
1074
+ if roster:
1075
+ # A LOOP, not a comprehension: _run_pass is a generator now
1076
+ # (§22), and a comprehension would collect generator objects
1077
+ # without ever running a pass.
1078
+ #
1079
+ # One candidate per roster entry, each on its OWN provider/model
1080
+ # (E1). No new plumbing: _run() calls api_initialization() itself
1081
+ # and effort_for() validates against the receiving model, so a
1082
+ # heterogeneous roster is correct by construction -- the same way
1083
+ # §11 already routes 3a/3b/6c to critic_provider/critic_model.
1084
+ candidates = []
1085
+ for entry in roster:
1086
+ label = f"{entry['provider_name']}/{entry['model']}"
1087
+ try:
1088
+ candidates.append((yield from _run_pass(
1089
+ "Pass 1", pass1_input, entry["model"], entry["provider_name"],
1090
+ authorization=authorization, trace=run.trace,
1091
+ pass_threads=run.pass_threads, effort=effort)))
1092
+ except Exception as e:
1093
+ # NAMED, TRACED, SKIPPED (E7) -- §20's containment rule.
1094
+ # An optional generation strategy must not flip a
1095
+ # ten-pass run to status='failed' because one provider
1096
+ # was unreachable. Same posture MCP takes per server.
1097
+ message = (f"Pass 1: ensemble candidate on {label} failed "
1098
+ f"({type(e).__name__}: {e}) — skipped.")
1099
+ logger.warning("%s", message)
1100
+ run.log(message)
1101
+ continue
1102
+ run.log(f"Pass 1: ensemble candidate {len(candidates)} generated on {label}.")
1103
+ # E13/#77: the record keeps every surviving candidate.
1104
+ # The metadata half sits beside the trace's candidate-N
1105
+ # lines so a stored asserted_by_candidates tag names
1106
+ # models this run can still identify; the text half feeds
1107
+ # the per-candidate artifacts and Pass 3b's input -- the
1108
+ # two places that must be able to check a claim against
1109
+ # what its number actually said. pipeline_storage strips
1110
+ # `text` at serialization; see PipelineRunRecord.
1111
+ run.candidates.append({
1112
+ "candidate": len(candidates),
1113
+ "provider_name": entry["provider_name"],
1114
+ "model": entry["model"],
1115
+ "chars": len(candidates[-1]),
1116
+ "text": candidates[-1],
1117
+ })
1118
+
1119
+ # Labels come from the SURVIVORS, never from position in the
1120
+ # roster (E11). Labelling by roster position leaves a gap when a
1121
+ # candidate fails -- "Candidate 1, Candidate 3" -- so Pass 2
1122
+ # would tag a claim both survivors asserted as [1, 3] while the
1123
+ # denominator said 2, and a unanimous claim would be scored as
1124
+ # dissented-against. A silently deflated confidence score is the
1125
+ # exact failure class this section exists to remove.
1126
+ effective_n = len(candidates)
1127
+ if effective_n >= 2:
1128
+ run.raw_response = candidates[0]
1129
+ pass2_input = "\n\n".join(
1130
+ f"Candidate {i + 1}:\n{c}" for i, c in enumerate(candidates)
1131
+ )
1132
+ run.log(f"Pass 1: ensemble mode — {effective_n} candidate(s) "
1133
+ f"across {effective_n} model(s); consistency is measured "
1134
+ f"out of {effective_n}.")
1135
+ else:
1136
+ # DEGRADE TO THE SINGLE-CANDIDATE PATH (E7), rather than
1137
+ # scoring one candidate as an ensemble of one -- which would
1138
+ # give every claim consistency 1.0 and a zero penalty while
1139
+ # reporting that agreement as if it had been corroborated.
1140
+ # ensemble_n=0 is not a degraded formula, it is the correct
1141
+ # one when there is nothing to compare against.
1142
+ effective_n = 0
1143
+ if candidates:
1144
+ run.raw_response = candidates[0]
1145
+ pass2_input = f"Response to extract claims from:\n{run.raw_response}"
1146
+ run.log("Pass 1: only one ensemble candidate survived — "
1147
+ "scoring WITHOUT a disagreement penalty, since one "
1148
+ "candidate cannot disagree with itself.")
1149
+ else:
1150
+ raise RuntimeError(
1151
+ "Pass 1: every ensemble candidate failed; there is no "
1152
+ "response to extract claims from. See the trace for "
1153
+ "each provider's error."
1154
+ )
1155
+ else:
1156
+ run.raw_response = yield from _run_pass("Pass 1", pass1_input, model, provider_name, authorization=authorization, corpus=corpus, trace=run.trace, pass_threads=run.pass_threads, effort=effort)
1157
+ pass2_input = f"Response to extract claims from:\n{run.raw_response}"
1158
+ run.log("Pass 1: initial generation complete.")
1159
+ yield from progress.checkpoint()
1160
+
1161
+ # --- Pass 2: claim extraction & classification ---
1162
+ claims_json = _parse_json_response((yield from _run_pass_with_json_retry("Pass 2", pass2_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, ensemble=effective_n >= 2, effort=effort)))
1163
+ run.claims = [_claim_from_json(c) for c in claims_json]
1164
+ for claim in run.claims:
1165
+ yield PipelineEvent(kind="claim_extracted", claim_id=claim.id,
1166
+ text=claim.text)
1167
+ yield from progress.checkpoint(f"Pass 2: extracted {len(run.claims)} claim(s).")
1168
+
1169
+ # --- gate D0: route by claim type (pure code) ---
1170
+ factual_claims = [c for c in run.claims if c.type == "factual"]
1171
+ non_factual_claims = [c for c in run.claims if c.type != "factual"]
1172
+ yield from _stage("D0")
1173
+ yield from progress.checkpoint(
1174
+ f"D0: {len(factual_claims)} factual claim(s) routed to 3a/3b, "
1175
+ f"{len(non_factual_claims)} synthesis/speculative claim(s) routed directly to Pass 4."
1176
+ )
1177
+
1178
+ # --- Pass 3a + 3b: only for factual claims, batched by deduplicated entity ---
1179
+ if factual_claims:
1180
+ unique_entities = sorted({e for c in factual_claims for e in c.entities})
1181
+ pass3a_input = (
1182
+ f"Factual claims:\n{json.dumps([vars(c) for c in factual_claims])}\n\n"
1183
+ f"Deduplicated entities to research (search each ONCE, map results back "
1184
+ f"to every claim referencing it):\n{json.dumps(unique_entities)}"
1185
+ )
1186
+ grounding_json = _parse_json_response((yield from _run_pass_with_json_retry("Pass 3a", pass3a_input, critic_model, critic_provider, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in run.claims], effort=effort)))
1187
+ grounded = _ground_and_score(run, grounding_json, corpus, scorer,
1188
+ scoring_knobs, scholar)
1189
+ yield from progress.checkpoint(f"Pass 3a: grounded {grounded} of {len(factual_claims)} factual claim(s), across {len(unique_entities)} deduplicated entities.")
1190
+
1191
+ # E13/#77. Two or more survivors: the claims were extracted
1192
+ # from the UNION of the candidates, so the critic sees every
1193
+ # candidate under the labels Pass 2 used -- a claim only
1194
+ # candidate 3 asserted is checked against text that actually
1195
+ # contains it, and contradictions ACROSS candidates are
1196
+ # findable. Handing it bare `raw_response` (candidate 1)
1197
+ # asked an ill-posed question: find conflicts within a text
1198
+ # much of your input did not come from.
1199
+ if len(run.candidates) >= 2:
1200
+ pass3b_input = (
1201
+ "\n\n".join(
1202
+ f"Candidate {entry['candidate']}:\n{entry['text']}"
1203
+ for entry in run.candidates)
1204
+ + f"\n\nFactual claims with grounding:\n{json.dumps([vars(c) for c in factual_claims])}"
1205
+ )
1206
+ else:
1207
+ pass3b_input = (
1208
+ f"Raw response:\n{run.raw_response}\n\n"
1209
+ f"Factual claims with grounding:\n{json.dumps([vars(c) for c in factual_claims])}"
1210
+ )
1211
+ critic_json = _parse_json_response((yield from _run_pass_with_json_retry("Pass 3b", pass3b_input, critic_model, critic_provider, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in run.claims], effort=effort)))
1212
+ critiqued = _apply_critic(run.claims, critic_json)
1213
+ yield from progress.checkpoint(f"Pass 3b: critique applied to {critiqued} of {len(factual_claims)} factual claim(s).")
1214
+ else:
1215
+ # A stage, not a silence. "3a/3b did not run" is a fact about
1216
+ # the run's shape -- it means nothing was factual -- and a
1217
+ # panel that simply skipped from Pass 2 to Pass 3c would leave
1218
+ # the reader to infer it from an absence.
1219
+ yield from _stage("Pass 3a/3b")
1220
+ yield from progress.checkpoint("Pass 3a/3b: skipped -- no factual claims to ground or critique.")
1221
+
1222
+ # --- Pass 3c: completeness, independent of Pass 1's raw_response ---
1223
+ pass3c_input = f"Original query:\n{user_query}\n\nPreliminary plan:\n{json.dumps(run.plan)}"
1224
+ run.completeness = _parse_json_response((yield from _run_pass_with_json_retry("Pass 3c", pass3c_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, effort=effort)))
1225
+ yield from progress.checkpoint(
1226
+ f"Pass 3c: coverage_score={run.completeness.get('coverage_score')}, "
1227
+ f"{len(run.completeness.get('gaps', []))} gap(s) identified."
1228
+ )
1229
+
1230
+ # --- Pass 4: assumption audit -- ALL claims, plus completeness ---
1231
+ pass4_input = (
1232
+ f"Original query:\n{user_query}\n\n"
1233
+ f"All claims:\n{json.dumps([vars(c) for c in run.claims])}\n\n"
1234
+ f"Completeness findings:\n{json.dumps(run.completeness)}"
1235
+ )
1236
+ run.assumptions = _parse_json_response((yield from _run_pass_with_json_retry("Pass 4", pass4_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in run.claims], effort=effort)))
1237
+ flagged_count = _apply_assumption_flags(run.claims, run.assumptions)
1238
+ yield from progress.checkpoint(f"Pass 4: assumption audit complete, {flagged_count} of {len(run.claims)} claim(s) flagged.")
1239
+
1240
+ # --- Pass 5: confidence tiering (0 LLM calls) ---
1241
+ run_confidence_tiering(run, ensemble_n=effective_n,
1242
+ sources_scored=_sources_were_scored(run),
1243
+ weights=confidence_weights)
1244
+ yield from _stage("Pass 5")
1245
+ yield from _tier_events(run)
1246
+ yield from progress.checkpoint("Pass 5: confidence tiers assigned (pure code, zero LLM calls).")
1247
+
1248
+ # --- D1 + the 6a/6b/D2 retry loop ---
1249
+ flagged = [c for c in run.claims if c.confidence_tier in FLAGGED_TIERS]
1250
+ yield from _stage("D1")
1251
+ yield from progress.checkpoint(f"D1: {len(flagged)} claim(s) flagged for revision, {len(run.claims) - len(flagged)} already clean.")
1252
+
1253
+ while flagged:
1254
+ # --- Pass 6a: ONE batched call across every currently-flagged claim ---
1255
+ pass6a_input = json.dumps([
1256
+ {
1257
+ "claim": vars(c),
1258
+ "critic_feedback": {"fallacies": c.fallacies, "contradictions": c.contradictions},
1259
+ "grounding_feedback": c.grounding_sources,
1260
+ "assumption_flags": c.assumption_flags,
1261
+ }
1262
+ for c in flagged
1263
+ ])
1264
+ revisions = _parse_json_response((yield from _run_pass_with_json_retry("Pass 6a", pass6a_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in flagged], effort=effort)))
1265
+
1266
+ # COUNT THE ROUND, NOT THE REVISION. The increment used to live
1267
+ # inside the loop below, so only a claim Pass 6a NAMED counted --
1268
+ # and 6a is one batched call across every flagged claim, which is
1269
+ # exactly the shape a model drops an item from. A claim it omitted
1270
+ # could never reach D2's cap, so `while flagged:` had no bound at
1271
+ # all: two model calls per round, for ever. An omission, an empty
1272
+ # list and an
1273
+ # unknown id are indistinguishable here -- the lookup returns None
1274
+ # and the `if claim:` skips in silence -- which is why the bound
1275
+ # cannot be data the model supplies.
1276
+ #
1277
+ # Counting the round makes D2's cap bound the loop by
1278
+ # construction, and since `flagged` only ever shrinks, every claim
1279
+ # still in it exhausts on the same round.
1280
+ for claim in flagged:
1281
+ claim.retry_count += 1
1282
+
1283
+ revised = 0
1284
+ for rev in revisions:
1285
+ # Resolved WITHIN the batch, first-wins like
1286
+ # PipelineRun.claim_by_id: 6a was only asked about `flagged`,
1287
+ # and a revision naming a claim outside it would land on one
1288
+ # already finished -- while carrying a retry_count this round
1289
+ # did not increment, so the event below would report a stale
1290
+ # attempt number.
1291
+ claim = next((c for c in flagged if c.id == rev["claim_id"]), None)
1292
+ if claim:
1293
+ revised += 1
1294
+ claim.revision_text = rev["revised_text"]
1295
+ # §22's "which claim, which attempt" -- emitted from the
1296
+ # claim retry loop, which is the retry the section means.
1297
+ # A JSON-parse retry is a different thing and reaches the
1298
+ # consumer as a trace_line, via json_retry.py's own line.
1299
+ yield PipelineEvent(kind="retry", claim_id=claim.id,
1300
+ attempt=claim.retry_count)
1301
+ yield from progress.checkpoint(f"Pass 6a: revised {revised} of {len(flagged)} claim(s) in this retry round.")
1302
+
1303
+ # --- Pass 6b: re-validate the revised subset only (batched, reuses Pass 5's code) ---
1304
+ pass6b_input = json.dumps([vars(c) for c in flagged])
1305
+ revalidation = _parse_json_response((yield from _run_pass_with_json_retry("Pass 6b", pass6b_input, critic_model, critic_provider, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in run.claims], effort=effort)))
1306
+ _ground_and_score(run, revalidation.get("grounding", []), corpus,
1307
+ scorer, scoring_knobs, scholar)
1308
+ _apply_critic(run.claims, revalidation.get("critic", []))
1309
+ # 6b's own checkpoint below already reports an EFFECT -- how
1310
+ # many claims came out clean -- rather than what it was asked
1311
+ # about, so it needs no count from these two.
1312
+ # Pass 5's function again -- code, not a call. Scoped to THIS
1313
+ # round's batch: 6b is only asked about `flagged`, and re-tiering
1314
+ # the whole run once per round recomputes claims that are already
1315
+ # finished, from score data those rounds did not change.
1316
+ run_confidence_tiering(run, ensemble_n=effective_n, claims=flagged,
1317
+ sources_scored=_sources_were_scored(run),
1318
+ weights=confidence_weights)
1319
+ yield from _tier_events(run)
1320
+
1321
+ still_flagged = [c for c in flagged if c.confidence_tier in FLAGGED_TIERS]
1322
+ yield from progress.checkpoint(f"Pass 6b: {len(flagged) - len(still_flagged)} claim(s) now clean, {len(still_flagged)} still flagged.")
1323
+
1324
+ # --- D2: retry cap check (pure code) ---
1325
+ exhausted = [c for c in still_flagged if c.retry_count >= MAX_RETRIES]
1326
+ if exhausted:
1327
+ # ONCE per round, outside the per-claim loop. D2 is one
1328
+ # decision applied to every claim that ran out of retries;
1329
+ # emitting inside the loop would put a D2 row in the panel
1330
+ # per claim, so a round that exhausted six claims would
1331
+ # read as six separate stages.
1332
+ yield from _stage("D2")
1333
+ for c in exhausted:
1334
+ _apply_fallback(c)
1335
+ yield PipelineEvent(kind="claim_tiered", claim_id=c.id,
1336
+ tier=c.confidence_tier)
1337
+ yield from progress.checkpoint(f"D2: claim {c.id} exhausted retries ({c.retry_count}) -> fallback UNVERIFIED.")
1338
+
1339
+ flagged = [c for c in still_flagged if c.retry_count < MAX_RETRIES]
1340
+
1341
+ # --- Pass 6c: annotate (templated, 0 LLM calls) ---
1342
+ for claim in run.claims:
1343
+ if claim.final_text is None:
1344
+ claim.final_text = claim.revision_text or claim.text
1345
+ if claim.annotation is None:
1346
+ claim.annotation = f"[{claim.confidence_tier}]"
1347
+ yield from _stage("Pass 6c")
1348
+ yield from progress.checkpoint("Pass 6c: annotation complete (templated, zero LLM calls).")
1349
+
1350
+ # --- Merge (pure code) ---
1351
+ yield from _stage("Merge")
1352
+ yield from progress.checkpoint(f"Merge: final claim set assembled -- {len(run.claims)} claim(s), {len(run.coverage_gaps)} coverage gap(s).")
1353
+
1354
+ # --- Final synthesis ---
1355
+ run.final_report = yield from _run_pass("Final synthesis", _synthesis_input(run), model, provider_name, authorization=authorization, corpus=corpus, trace=run.trace, pass_threads=run.pass_threads, effort=effort)
1356
+ yield from progress.checkpoint("Final synthesis complete.")
1357
+
1358
+ # --- §20: review, consent, correct ---
1359
+ yield from _review_stage(run, progress, model, provider_name,
1360
+ authorization, review,
1361
+ enabled=subagent_review, effort=effort)
1362
+
1363
+ update_pipeline_run(run.run_id, run, status="complete")
1364
+ yield PipelineEvent(kind="run_complete", run=run)
1365
+ return
1366
+ except Exception:
1367
+ # Persist the partial state before the exception propagates. The
1368
+ # update is best-effort: if storage itself is what failed, we must
1369
+ # not mask the original error, so a second failure here is logged
1370
+ # (via the real logger -- it reaches stderr through Python's
1371
+ # lastResort handler even before logging_setup is wired in) and the
1372
+ # original exception still re-raises. run.log() would be inert here:
1373
+ # the propagated exception carries no reference back to this local
1374
+ # `run`, and persistence already failed, so a trace entry would
1375
+ # never reach anywhere durable.
1376
+ try:
1377
+ update_pipeline_run(run.run_id, run, status="failed")
1378
+ except Exception as persist_error:
1379
+ logger.error(
1380
+ f"Failed to persist failure state for run {run.run_id}: {persist_error}"
1381
+ )
1382
+ raise