devlyn-cli 2.10.0 → 3.0.0

package/config/skills/_shared/collect-codex-findings.py

@@ -1,25 +1,42 @@
 #!/usr/bin/env python3
-"""Normalize raw Codex pair-JUDGE stdout into canonical VERIFY JSONL."""
+"""Normalize raw pair-JUDGE stdout into canonical VERIFY JSONL."""
 
 from __future__ import annotations
 
 import argparse
 import json
 import pathlib
+import runpy
 import sys
 import tempfile
 from typing import Any
 
 
-FINDING_SEVERITIES = {"CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"}
+MERGE_CONTRACT = runpy.run_path(pathlib.Path(__file__).with_name("verify-merge-findings.py"))
+PARSER = runpy.run_path(pathlib.Path(__file__).with_name("judge-output-parser.py"))
+VERDICT_RANK = MERGE_CONTRACT["VERDICT_RANK"]
+finding_rank = MERGE_CONTRACT["finding_rank"]
 
 
 def reject_json_constant(token: str) -> None:
     raise ValueError(f"invalid JSON numeric constant: {token}")
 
 
+def reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"duplicate JSON key: {key}")
+        result[key] = value
+    return result
+
+
 def loads_strict_json(text: str) -> Any:
-    return json.loads(text, parse_constant=reject_json_constant)
+    return json.loads(
+        text,
+        parse_constant=reject_json_constant,
+        object_pairs_hook=reject_duplicate_keys,
+    )
 
 
 def atomic_write(path: pathlib.Path, text: str) -> None:
@@ -32,76 +49,418 @@ def atomic_write(path: pathlib.Path, text: str) -> None:
     pathlib.Path(tmp_name).replace(path)
 
 
-def collect(stdout_path: pathlib.Path) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
-    findings: list[dict[str, Any]] = []
-    summary: dict[str, Any] | None = None
-    with stdout_path.open(encoding="utf-8") as handle:
-        for line_no, line in enumerate(handle, 1):
-            raw = line.strip()
-            if not raw:
-                continue
-            if raw.startswith("# SUMMARY "):
-                try:
-                    item = loads_strict_json(raw.removeprefix("# SUMMARY ").strip())
-                except ValueError as exc:
-                    raise SystemExit(f"error: invalid SUMMARY JSON at {stdout_path}:{line_no}: {exc}")
-                if not isinstance(item, dict):
-                    raise SystemExit(f"error: SUMMARY is not an object at {stdout_path}:{line_no}")
-                summary = item
-                continue
-            if raw.startswith("#"):
-                continue
-            try:
-                item = loads_strict_json(raw)
-            except ValueError as exc:
-                raise SystemExit(f"error: invalid JSONL at {stdout_path}:{line_no}: {exc}")
-            if not isinstance(item, dict):
-                raise SystemExit(f"error: JSONL item is not an object at {stdout_path}:{line_no}")
-            severity = str(item.get("severity") or "").upper()
-            if severity not in FINDING_SEVERITIES:
-                raise SystemExit(f"error: finding missing valid severity at {stdout_path}:{line_no}")
-            findings.append(item)
+def collect_text(
+    text: str, source: pathlib.Path
+) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
+    findings, summary = PARSER["collect_text"](text, source)
+    if findings and summary is None:
+        raise SystemExit("error: findings without terminal verdict")
+    if summary is not None and summary["verdict"] == "PASS" and any(finding_rank(finding) == 2 for finding in findings):
+        raise SystemExit("error: verdict-binding finding cannot have a PASS verdict")
+    if not findings and (summary is None or summary.get("verdict") != "PASS"):
+        raise SystemExit("error: non-PASS verdict without JSONL findings")
+    return findings, summary
+
+
+def collect_stdout(stdout_path: pathlib.Path) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
+    findings, summary = PARSER["collect_stdout"](stdout_path)
+    if findings and summary is None:
+        raise SystemExit("error: findings without terminal verdict")
+    if summary is not None and summary["verdict"] == "PASS" and any(finding_rank(finding) == 2 for finding in findings):
+        raise SystemExit("error: verdict-binding finding cannot have a PASS verdict")
     if not findings and (summary is None or summary.get("verdict") != "PASS"):
-        raise SystemExit("error: non-PASS SUMMARY without JSONL findings")
+        raise SystemExit("error: non-PASS verdict without JSONL findings")
     return findings, summary
 
 
 def self_test() -> int:
+    try:
+        loads_strict_json('{"verdict":"PASS","verdict":"BLOCKED"}')
+    except ValueError as exc:
+        assert "duplicate JSON key" in str(exc)
+    else:
+        raise AssertionError("duplicate judge result key was accepted")
     with tempfile.TemporaryDirectory() as tmp:
         root = pathlib.Path(tmp)
-        stdout_path = root / "codex-judge.stdout"
+        stdout_path = root / "pair-judge.stdout"
         out_path = root / "verify.pair.findings.jsonl"
-        summary_path = root / "codex-judge.summary.json"
+        summary_path = root / "pair-judge.summary.json"
+
+        def assert_rejected(text: str, label: str, *message_parts: str) -> None:
+            stdout_path.write_text(text, encoding="utf-8")
+            try:
+                collect_stdout(stdout_path)
+            except SystemExit as exc:
+                message = str(exc)
+                assert all(part in message for part in message_parts)
+            else:
+                raise AssertionError(f"{label} must be rejected")
+
+        plain_finding = {"id": "a", "severity": "HIGH"}
+        plain_summary = {"verdict": "NEEDS_WORK"}
         stdout_path.write_text(
-            json.dumps({"id": "a", "severity": "HIGH"}) + "\n"
-            + '# SUMMARY {"verdict":"NEEDS_WORK"}\n',
+            json.dumps(plain_finding) + "\n"
+            + plain_summary["verdict"] + "\n",
             encoding="utf-8",
         )
-        findings, summary = collect(stdout_path)
+        findings, summary = collect_stdout(stdout_path)
+        assert findings == [plain_finding]
+        assert summary == plain_summary
         write_outputs(findings, summary, out_path, summary_path)
         assert out_path.read_text(encoding="utf-8").count("\n") == 1
         assert loads_strict_json(summary_path.read_text(encoding="utf-8"))["verdict"] == "NEEDS_WORK"
-        stdout_path.write_text('{"id":"nan","severity":NaN}\n', encoding="utf-8")
-        try:
-            collect(stdout_path)
-        except SystemExit as exc:
-            assert "invalid JSON numeric constant: NaN" in str(exc)
-        else:
-            raise AssertionError("NaN Codex stdout finding must not normalize")
+        assert_rejected(
+            '{"id":"nan","severity":NaN}\n',
+            "NaN pair-JUDGE stdout finding",
+            "invalid JSON numeric constant: NaN",
+        )
+        assert_rejected(
+            '# SUMMARY {"verdict":"PASS","verdict":"BLOCKED"}\n',
+            "duplicate pair-JUDGE summary verdict",
+            "duplicate JSON key: verdict",
+        )
         rejection_cases = (
-            ("", "no SUMMARY line"),
-            ('# SUMMARY {}\n', "empty SUMMARY object"),
-            ('# SUMMARY {"verdict":"pass"}\n', "lowercase pass"),
-            ('# SUMMARY {"verdict":"UNKNOWN"}\n', "unknown verdict"),
+            ("", "no verdict line", "non-PASS verdict without JSONL findings"),
+            (json.dumps(plain_finding) + "\n", "finding without terminal verdict", "findings without terminal verdict"),
+            ('{"verdict":"pass"}\n', "lowercase pass", "finding missing valid severity"),
+            ('{"verdict":"UNKNOWN"}\n', "unknown verdict", "finding missing valid severity"),
         )
-        for text, label in rejection_cases:
-            stdout_path.write_text(text, encoding="utf-8")
-            try:
-                collect(stdout_path)
-            except SystemExit as exc:
-                assert str(exc) == "error: non-PASS SUMMARY without JSONL findings"
-            else:
-                raise AssertionError(f"{label} must not normalize to PASS")
+        for text, label, message in rejection_cases:
+            assert_rejected(
+                text,
+                label,
+                message,
+            )
+
+        def envelope(text: Any, stop_reason: str = "EndTurn") -> str:
+            return json.dumps(
+                {
+                    "text": text,
+                    "stopReason": stop_reason,
+                    "sessionId": "session",
+                    "requestId": "request",
+                }
+            )
+
+        envelope_finding = {
+            "id": "envelope-finding",
+            "severity": "HIGH",
+            "detail": {"preserved": True},
+        }
+        envelope_summary = {"verdict": "NEEDS_WORK"}
+        stdout_path.write_text(
+            envelope(
+                json.dumps(envelope_finding)
+                + "\n" + envelope_summary["verdict"] + "\n"
+            ),
+            encoding="utf-8",
+        )
+        findings, summary = collect_stdout(stdout_path)
+        assert findings == [envelope_finding]
+        assert summary == envelope_summary
+
+        assert_rejected(
+            envelope("review completed without findings"),
+            "findings-less envelope text",
+            "invalid JSONL",
+        )
+        assert_rejected(
+            envelope('{"findings":[],"verdict":"PASS"}', "Cancelled"),
+            "Cancelled envelope",
+            "envelope stopReason must be 'EndTurn'",
+            "'Cancelled'",
+        )
+        assert_rejected(
+            envelope("", "UnknownStop"),
+            "unknown envelope stopReason",
+            "envelope stopReason must be 'EndTurn'",
+            "'UnknownStop'",
+        )
+        assert_rejected(
+            envelope(None),
+            "non-string envelope text",
+            "error: envelope text must be a string",
+        )
+        assert_rejected(
+            envelope("I will inspect the result.\n" + envelope_summary["verdict"] + "\n"),
+            "narrative envelope preamble",
+            "invalid JSONL",
+        )
+        dual_document = (
+            json.dumps(envelope_finding)
+            + json.dumps({"id": "second", "severity": "LOW"})
+            + "\n" + envelope_summary["verdict"] + "\n"
+        )
+        assert_rejected(
+            envelope(dual_document),
+            "concatenated envelope documents",
+            "invalid JSONL",
+        )
+        clean_summary = {"verdict": "PASS"}
+        stdout_path.write_text(
+            envelope(clean_summary["verdict"] + "\n"),
+            encoding="utf-8",
+        )
+        findings, summary = collect_stdout(stdout_path)
+        assert findings == []
+        assert summary == clean_summary
+        stdout_path.write_text(
+            json.dumps(
+                {
+                    "type": "system",
+                    "text": clean_summary["verdict"] + "\n",
+                    "stopReason": "EndTurn",
+                    "sessionId": "session",
+                    "requestId": "request",
+                }
+            ),
+            encoding="utf-8",
+        )
+        findings, summary = collect_stdout(stdout_path)
+        assert findings == []
+        assert summary == clean_summary
+
+        # R4: a valid plain finding may carry an unrelated `type` field. A
+        # first-line `type: system` finding is not a stream discriminator.
+        system_finding = {"id": "system-finding", "severity": "LOW", "type": "system"}
+        stdout_path.write_text(
+            json.dumps(system_finding) + "\n" + clean_summary["verdict"] + "\n",
+            encoding="utf-8",
+        )
+        findings, summary = collect_stdout(stdout_path)
+        assert findings == [system_finding]
+        assert summary == clean_summary
+
+        # iter-0106 — Grok whole-message NDJSON carrier (R2/R3).
+        def init_record(session: str = "s1") -> dict[str, Any]:
+            return {"type": "system", "subtype": "init", "session_id": session, "model": "grok-build"}
+
+        def assistant_record(
+            blocks: list[Any], stop_reason: str = "end_turn", session: str = "s1"
+        ) -> dict[str, Any]:
+            return {
+                "type": "assistant",
+                "message": {"id": "msg", "role": "assistant", "content": blocks, "stop_reason": stop_reason},
+                "parent_tool_use_id": None,
+                "session_id": session,
+            }
+
+        def result_record(
+            text: str,
+            session: str = "s1",
+            subtype: str = "success",
+            is_error: Any = False,
+            stop_reason: str = "end_turn",
+        ) -> dict[str, Any]:
+            return {
+                "type": "result",
+                "subtype": subtype,
+                "is_error": is_error,
+                "result": text,
+                "stop_reason": stop_reason,
+                "session_id": session,
+            }
+
+        def text_block(value: str) -> dict[str, Any]:
+            return {"type": "text", "text": value}
+
+        def stream(*records: Any) -> str:
+            return "".join(json.dumps(record) + "\n" for record in records)
+
+        pass_text = "PASS\n"
+        stdout_path.write_text(
+            stream(init_record(), assistant_record([text_block(pass_text)]), result_record(pass_text)),
+            encoding="utf-8",
+        )
+        findings, summary = collect_stdout(stdout_path)
+        assert findings == []
+        assert summary == {"verdict": "PASS"}
+
+        # A real tool turn precedes the contract, and the terminal message arrives
+        # as two text blocks whose in-order concatenation is the result text.
+        stream_finding = {"id": "stream-finding", "severity": "HIGH"}
+        head = json.dumps(stream_finding) + "\n"
+        tail = "# SUMMARY " + json.dumps({"verdict": "NEEDS_WORK"}) + "\n"
+        contract = head + tail
+        narration = assistant_record(
+            [
+                text_block("Let me read the file."),
+                {"type": "tool_use", "id": "call_1", "name": "read_file", "input": {"path": "src/main.rs"}},
+            ],
+            stop_reason="tool_use",
+        )
+        tool_result = {
+            "type": "user",
+            "message": {
+                "role": "user",
+                "content": [{"type": "tool_result", "tool_use_id": "call_1", "content": "fn main() {}"}],
+            },
+            "parent_tool_use_id": None,
+            "session_id": "s1",
+        }
+        stdout_path.write_text(
+            stream(
+                init_record(),
+                narration,
+                tool_result,
+                assistant_record([text_block(head), text_block(tail)]),
+                result_record(contract),
+            ),
+            encoding="utf-8",
+        )
+        findings, summary = collect_stdout(stdout_path)
+        assert findings == [stream_finding]
+        assert summary == {"verdict": "NEEDS_WORK"}
+
+        # The welded body is exactly the shape envelope recovery accepts, so this
+        # also proves the stream branch never falls through to that recovery.
+        welded = "I reviewed the diff.\n" + contract
+        stream_rejections = (
+            (
+                stream(init_record(), assistant_record([text_block(welded)]), result_record(welded)),
+                "narration welded into the terminal message",
+                "invalid JSONL",
+            ),
+            (
+                stream(
+                    init_record(),
+                    assistant_record([text_block(contract)]),
+                    assistant_record([text_block(contract)]),
+                    result_record(contract),
+                ),
+                "two terminal end_turn messages",
+                "exactly one final end_turn assistant message",
+            ),
+            (
+                stream(
+                    init_record(),
+                    assistant_record([text_block(contract)]),
+                    assistant_record([text_block("more")], stop_reason="tool_use"),
+                    result_record(contract),
+                ),
+                "end_turn message that is not the final assistant message",
+                "exactly one final end_turn assistant message",
+            ),
+            (
+                # The malformed line is the only defect: skipping it leaves a valid stream.
+                stream(init_record(), assistant_record([text_block(pass_text)]))
+                + '{"type":"assistant"\n'
+                + stream(result_record(pass_text)),
+                "malformed stream NDJSON inside an otherwise valid stream",
+                "invalid stream NDJSON",
+            ),
+            (
+                stream(init_record(), assistant_record([text_block(pass_text)])),
+                "stream without a terminal result",
+                "exactly one terminal result",
+            ),
+            (
+                stream(
+                    init_record(),
+                    assistant_record([text_block(pass_text)]),
+                    result_record(pass_text),
+                    tool_result,
+                ),
+                "data after the terminal result",
+                "exactly one terminal result",
+            ),
+            (
+                stream(
+                    init_record(),
+                    assistant_record([text_block(pass_text)]),
+                    tool_result,
+                    result_record(pass_text),
+                ),
+                "data between the terminal assistant and result",
+                "exactly one final end_turn assistant message",
+            ),
+            (
+                stream(
+                    init_record(),
+                    assistant_record([text_block(pass_text)]),
+                    result_record(pass_text, subtype="error_during_execution"),
+                ),
+                "error result subtype",
+                "not a successful end_turn",
+            ),
+            (
+                stream(
+                    init_record(),
+                    assistant_record([text_block(pass_text)]),
+                    result_record(pass_text, stop_reason="cancelled"),
+                ),
+                "cancelled result",
+                "not a successful end_turn",
+            ),
+            (
+                stream(
+                    init_record(),
+                    assistant_record([text_block(pass_text)]),
+                    result_record(pass_text, is_error=True),
+                ),
+                "error-flagged result",
+                "not a successful end_turn",
+            ),
+            (
+                stream(
+                    init_record(),
+                    assistant_record([text_block(pass_text)]),
+                    result_record("NEEDS_WORK\n"),
+                ),
+                "result text that disagrees with the terminal message",
+                "result text does not match the terminal message",
+            ),
+            (
+                stream(
+                    init_record(),
+                    assistant_record([text_block(pass_text)]),
+                    result_record(pass_text, session="s2"),
+                ),
+                "result from another session",
+                "session identity does not agree",
+            ),
+            (
+                stream(
+                    init_record(),
+                    {"type": "stream_event", "event": {"type": "content_block_delta"}, "session_id": "s1"},
+                    assistant_record([text_block(pass_text)]),
+                    result_record(pass_text),
+                ),
+                "partial-message frame",
+                "unknown stream record",
+            ),
+            (
+                stream(
+                    init_record(),
+                    {"type": "system", "subtype": "compact_boundary", "session_id": "s1"},
+                    assistant_record([text_block(pass_text)]),
+                    result_record(pass_text),
+                ),
+                "compact boundary",
+                "second system record",
+            ),
+            (
+                stream(
+                    init_record(),
+                    {"type": "unknown", "session_id": "s1"},
+                    assistant_record([text_block(pass_text)]),
+                    result_record(pass_text),
+                ),
+                "unknown record type",
+                "unknown stream record",
+            ),
+            (
+                stream(
+                    {"type": "system", "subtype": "compact_boundary", "session_id": "s1"},
+                    assistant_record([text_block(pass_text)]),
+                    result_record(pass_text),
+                ),
+                "stream that does not open with system/init",
+                "must open with system/init",
+            ),
+        )
+        for text, label, message in stream_rejections:
+            assert_rejected(text, label, message)
     return 0
 
 
@@ -122,9 +481,9 @@ def write_outputs(
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--devlyn-dir", default=".devlyn")
-    parser.add_argument("--stdout-file", default="codex-judge.stdout")
+    parser.add_argument("--stdout-file", default="pair-judge.stdout")
     parser.add_argument("--out", default="verify.pair.findings.jsonl")
-    parser.add_argument("--summary-out", default="codex-judge.summary.json")
+    parser.add_argument("--summary-out", default="pair-judge.summary.json")
     parser.add_argument("--self-test", action="store_true")
     args = parser.parse_args()
     if args.self_test:
@@ -135,7 +494,7 @@ def main() -> int:
     if not stdout_path.is_file():
         sys.stderr.write(f"error: {stdout_path} not found\n")
         return 1
-    findings, summary = collect(stdout_path)
+    findings, summary = collect_stdout(stdout_path)
     write_outputs(findings, summary, devlyn / args.out, devlyn / args.summary_out)
     print(json.dumps({"findings_count": len(findings), "summary": summary}, sort_keys=True))
     return 0

package/config/skills/_shared/engine-preflight.md

@@ -8,21 +8,22 @@ Each skill resolves the effective engine from its own SKILL.md default plus any
 
 Engine requirements have two classes:
 
-- **Explicit routes** — `--engine`, `--risk-probes`, `--pair-verify`. These are promises. If the required engine is unavailable, fail closed with `BLOCKED:<engine>-unavailable` and never downgrade to solo.
+- **Explicit routes** — `--engine`, `--risk-probes`, `--pair-verify`, configured executor/role/priority pins. These are promises. If the required engine is unavailable, fail closed with `BLOCKED:<engine>-unavailable` and never downgrade to solo.
 - **Automatic routes** — high-risk risk-probes remain conditional; VERIFY pair-JUDGE is selected by default unless `--no-pair` was passed. Both require an available OTHER engine. If it is absent, proceed solo and report the skipped route and reason. This is route selection, not a fallback.
 
 ## Role resolution
 
-Two configurable roles; the orchestrator role is whichever CLI the user opened and is not configurable here.
+The orchestrator is the CLI the user opened. PLAN remains orchestrator-fixed. Resolve the legacy executor as explicit `--engine` > `cwd/.devlyn/engines.json` `executor` > the invoking skill's supported default. BUILD_GATE and risk-probe derivation keep their existing routes.
 
-- **Executor** (IMPLEMENT / CLEANUP / primary VERIFY judge): explicit `--engine` flag > `cwd/.devlyn/engines.json` `executor` > built-in default `claude`. No parent-directory or global config lookup. Requires an adapter that is executor-eligible (below).
-- **Pair judge** (VERIFY pair-JUDGE, risk-probe derivation): first entry of `engines.json` `pair_judge_priority` that is (a) adapter-valid, (b) pair-judge-eligible (below), (c) not the primary judge engine, (d) available. When the key or file is absent: the binary claude↔codex complement.
+The role profiles and `--role-config` below apply only to `/devlyn:resolve`; `/devlyn:ideate` keeps its existing `--engine` / legacy executor selection and never inherits worker/judge profiles. `role-config.py` is resolve’s deterministic resolver. Optional project `roles.worker`, `roles.primary_judge`, and `roles.pair_judge` each require `engine` and accept exact `model`/`effort`; `/devlyn:resolve --role-config <path>` supplies the same `{"roles": {...}}` object for one run. Each entry replaces the entire lower entry. Worker/primary precedence is run role > `--engine` engine-only > project role > legacy executor. Pair precedence is run role > project role > existing `pair_judge_priority`/binary complement. An absent primary profile follows the legacy executor, not the worker profile. No parent/global devlyn config lookup.
 
-Validation is fail-closed: malformed JSON, any engine name without a `_shared/adapters/<name>.md` adapter file under `DEVLYN_SHARED_DIR`, or an adapter that declares itself ineligible for the requested role, halts with report-level `BLOCKED:invalid-engine-config` naming the offending entry. This is the plug-in point for new engines — ship an adapter file and the name becomes valid with zero skill-body changes. Availability probe default is `command -v <name>`; an adapter may declare a different probe. A pin is an explicit route (same promise class as `--engine`): pinned-but-unavailable → `BLOCKED:<engine>-unavailable`, never a silent downgrade. `engines.json` is machine-local config — not committed, not archived (`archive_run.py` moves only `PER_RUN_PATTERNS`).
+Worker controls IMPLEMENT/CLEANUP and their repair rounds only; primary/pair control VERIFY only. OTHER must differ from the resolved primary engine. Explicit same-engine pair is invalid; a legacy priority list skips the primary. `--no-pair` does not dispatch or check availability of an unused pair. Configured pins remain explicit promises, while an unconfigured unavailable automatic OTHER records its solo reason.
 
-**Role eligibility** — an adapter's optional `## Role eligibility` section (`_shared/adapters/README.md`) declares `executor: yes|no` / `pair_judge: yes|no` as fixed ASCII fields. Absent section = eligible for both roles (every adapter shipped before iter-0051). A completion-only local backend with no tool/file-edit access declares `executor: no`: an `executor <name>` pin against it is invalid config, not an availability gap, and fails the same `BLOCKED:invalid-engine-config` path above rather than `BLOCKED:<name>-unavailable`.
+Before the first phase, `/devlyn:resolve` freezes resolution with `state-phase-write.py --freeze-roles`; subsequent status/dispatch reads that state instead of mutable config. `state.engine` stays the legacy executor. The resolver rejects statically unsupported selected channel fields before PLAN, and validates adapter names and the existing ASCII `executor: yes|no` / `pair_judge: yes|no` eligibility markers; absent eligibility section means both. Malformed configuration fails with `BLOCKED:invalid-engine-config`.
 
-The explicit-vs-automatic split above applies unchanged to resolved engines: explicit routes (`--engine`, `--risk-probes`, `--pair-verify`, config pins) fail closed; automatic escalations select a cross-engine route only when the resolved pair-judge engine is available, else proceed solo and report the skip.
+Before each affected worker/judge, read `role-config.py --state .devlyn/pipeline.state.json --role <role> [--resolved-model <inherited-exact-model>]`. It returns source/channel, requested values and argv additions. Explicit Codex options require current version-matching native model metadata; refresh the native CLI's cache when missing/stale. Explicit Claude judge effort requires the adapter's version/exact-model capability declaration; model-only selection passes the exact ID without that effort declaration and validates the native result. No model/effort fields means unchanged phase defaults. Unknown support fails with `BLOCKED:unsupported-role-option`; no clamp, fallback or invented model identity. Native Agent workers reject unsupported explicit Claude fields without switching to a CLI worker. Show inherited/unknown values honestly; availability is not role fitness.
+
+Engine-only adapter routes remain supported according to existing eligibility. New adapters do not automatically gain explicit model/effort mappings. Status reports unavailable pins and unresolved legacy channels without weakening run freeze/dispatch. CLI presence is not authentication. Status never launches a model, changes user configuration or promotes a default.
 
 When a run or phase requires engine `<name>` (claude, codex, omp, or any adapter-backed engine), before spawning that phase: