phase-loop-runtime 0.7.10__tar.gz → 0.7.11__tar.gz

{phase_loop_runtime-0.7.10 → phase_loop_runtime-0.7.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.10
+Version: 0.7.11
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author-email: ViperJuice <viperjuice@users.noreply.github.com>
 License-Expression: Apache-2.0
@@ -24,6 +24,8 @@ Requires-Dist: packaging>=21
 Requires-Dist: websockets<16,>=12
 Requires-Dist: rfc8785<0.2,>=0.1.4
 Requires-Dist: tomli<3,>=2; python_version < "3.11"
+Provides-Extra: visual
+Requires-Dist: Pillow<13,>=10; extra == "visual"
 
 # phase-loop-runtime
 

{phase_loop_runtime-0.7.10 → phase_loop_runtime-0.7.11}/protocol/protocol.md

@@ -588,7 +588,7 @@ The accepted syntax is line-oriented markdown:
 ## Execution Policy
 - work-unit defaults: work-unit=`lane_execute`, effort=`medium`, unsupported=`inherit_default`, inherit-default=`true`
 - execute: executor=`pi`, model=`auto`, effort=`medium`, work-unit=`lane_execute`, reason=`simple bounded lane default`
-- repair: executor=`claude`, model=`claude-opus-4-8`, effort=`high`, work-unit=`repair`
+- repair: executor=`claude`, model=`claude-sonnet-5`, effort=`medium`, work-unit=`repair`
 - SL-2: executor=`gemini`, model=`phase-loop-execute-medium`, effort=`medium`, work-unit=`lane_execute`, unsupported=`fallback`, fallback=`phase-loop-execute-medium`
 ```
 

{phase_loop_runtime-0.7.10 → phase_loop_runtime-0.7.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phase-loop-runtime"  # PyPI dist name; NOT "agent-harness" (an unrelated third-party PyPI project)
-version = "0.7.10"
+version = "0.7.11"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -60,6 +60,17 @@ dependencies = [
     "tomli>=2,<3; python_version < '3.11'",
 ]
 
+[project.optional-dependencies]
+# FAV visual-evidence gate (agent-harness#91, round-3 CR): the runner-side
+# `derive_visual_observation` decodes the referenced image artifact and
+# computes pixel stats FROM THE ACTUAL PIXELS, so self-reported
+# non_black_pixels/pixel_min/pixel_max can never override a real decode.
+# Pillow is imported LAZILY inside the derivation (models.py) -- it is NOT a
+# hard core dependency; an install without the `visual` extra still runs
+# every other command, and the visual-evidence gate itself fails CLOSED
+# (never silently passes on self-reported numbers) when Pillow is absent.
+visual = ["Pillow>=10,<13"]
+
 [project.urls]
 Homepage = "https://github.com/ViperJuice/agent-harness"
 Repository = "https://github.com/ViperJuice/agent-harness"

{phase_loop_runtime-0.7.10 → phase_loop_runtime-0.7.11}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.10"
+__version__ = "0.7.11"

{phase_loop_runtime-0.7.10 → phase_loop_runtime-0.7.11}/src/phase_loop_runtime/_contract_docs/phase-loop/protocol.md

@@ -588,7 +588,7 @@ The accepted syntax is line-oriented markdown:
 ## Execution Policy
 - work-unit defaults: work-unit=`lane_execute`, effort=`medium`, unsupported=`inherit_default`, inherit-default=`true`
 - execute: executor=`pi`, model=`auto`, effort=`medium`, work-unit=`lane_execute`, reason=`simple bounded lane default`
-- repair: executor=`claude`, model=`claude-opus-4-8`, effort=`high`, work-unit=`repair`
+- repair: executor=`claude`, model=`claude-sonnet-5`, effort=`medium`, work-unit=`repair`
 - SL-2: executor=`gemini`, model=`phase-loop-execute-medium`, effort=`medium`, work-unit=`lane_execute`, unsupported=`fallback`, fallback=`phase-loop-execute-medium`
 ```
 
@@ -1862,6 +1862,24 @@ These fields are the shared child-exit reduction contract. Adapters may add
 transport-specific metadata elsewhere, but they must not rename or omit these
 summary fields.
 
+The following visual-avatar-evidence fields (FAV, issue #91) are OPTIONAL — they
+are emitted only when the native closeout carried them (an avatar/browser-media
+phase that attached runner-owned visual evidence or a typed opt-out). Ordinary
+phases omit them entirely, but when present they are part of the reduction
+contract the closeout validator inspects, so they must not be silently dropped:
+
+- `visual_evidence_path`
+- `visual_evidence_observed`
+- `visual_evidence_opt_out`
+
+`visual_render_declared` (FAV, issue #272) is likewise OPTIONAL and emitted
+only when carried by the native closeout. It is the DECLARED signal: the
+visual-evidence gate's BLOCK decision reads this bool (plus evidence
+validity once declared) and NOTHING else -- an owned avatar/browser-media
+surface or an explicit visible-render claim in the plan text never blocks on
+their own; they only raise a non-blocking `visual_render_undeclared_surface`
+advisory when the phase never declared.
+
 ## Monitor Payloads
 
 `build_notification_payload(...)` must emit exactly these top-level fields:

phase_loop_runtime-0.7.11/src/phase_loop_runtime/_contract_docs/runtime/verification-evidence-contract.md

@@ -0,0 +1,72 @@
+# Verification Evidence Contract
+
+VC freezes the additive verification evidence artifact for future runner wiring. Until a later phase consumes it, the only producer is `phase_loop_runtime.verification_evidence.run_verification`.
+
+`run_verification(repo, run_dir, commands, suite_command, env_refresh, timeout_s, operational_exemptions=None, python_pin=None, phase_alias=None) -> VerificationResult` writes two sibling files under the supplied run directory. The optional `phase_alias` is the LIVE run alias (ah#85). `verification.json`'s `phase_alias` resolves in strict precedence order: the operator env override (`PHASE_LOOP_PHASE_ALIAS` / `PHASE_ALIAS`) wins if set, else the supplied `phase_alias` (the live run alias) if provided, else `.phase-loop/state.json:current_phase`, else `"unknown"`. Threading the live alias on the execute path keeps the artifact from mis-attributing the phase after a mid-run roadmap amendment changes `current_phase`; the env override remains the highest-priority operator escape-hatch.
+
+- `verification.json`
+- `verification.log`
+
+`verification.json` uses schema version 2 and contains exactly these top-level fields:
+
+- `schema_version`
+- `run_id`
+- `phase_alias`
+- `commands`
+- `env_refresh`
+- `suite`
+- `started_at`
+- `finished_at`
+- `log_sha256`
+
+Each `commands[]` item contains `argv`, `cwd`, `exit_code`, `duration_s`, and `log_offset`. `env_refresh`, when present, contains `triggered`, `manifests`, `install_argv`, and `exit_code`. `suite`, when present, contains `argv`, `exit_code`, and `duration_s`.
+
+**Schema v2 (agent-harness#209), additive.** Every stage (`commands[]`, `env_refresh`, `suite`) may additionally carry `log_end_offset` (the exclusive byte end of that stage's output in `verification.log`) and `failure_kind` (the runner-OBSERVED failure origin, one of `timeout` / `error` / `nonzero_exit`), and `env_refresh`/`suite` additionally carry their own `log_offset` (start). These fields are captured at execution time and omitted when null; `failure_kind` is never re-derived from `exit_code` downstream (a child that itself returns 124/127 stays `nonzero_exit`, not `timeout`/`error`). **v1 back-compat:** a v1 artifact (without these fields) still loads — the missing fields default to `None`. `load_verification_artifact` accepts `schema_version` in `{1, 2}`.
+
+`verification.log` stores raw combined stdout and stderr from the recorded subprocesses, followed (agent-harness#243) by a single trailing seal line `verification-artifact-sha256:<hex>` — a canonical digest of `verification.json` (see the whole-artifact integrity paragraph). `log_offset` is the start byte offset for each stage's output and `log_end_offset` (v2) is its exclusive end (both point strictly before the seal trailer, so a stage's `raw_tail` never includes it). `log_sha256` is the SHA-256 digest of the final log bytes (seal trailer included).
+
+**Failure diagnostics (verdict layer, non-frozen).** `validate_verification_artifact` returns `VerificationArtifactValidation`; its `to_json()` includes a `diagnostics` list. On the `nonzero_exit` verdict (where the log is already sha-authenticated), it carries one entry per failing stage — in declared order `commands` → `env_refresh` → `suite` — each `{role, index, argv, exit_code, failure_kind, raw_tail, truncated, diagnostic_status}`. `raw_tail` is a bounded (`DIAGNOSTIC_TAIL_BYTES`) tail sliced from the stage's exact `[log_offset, log_end_offset)` region; `diagnostic_status` is `missing_output` when a failing stage produced no captured bytes (still emitted, with typed context — a failed verdict is never diagnostic-empty). Diagnostics are NOT built on the `log_sha256_mismatch` / `missing_log` integrity branches (an unauthenticated log's tail could be forged); those block on the integrity failure, which is the more severe reason.
+
+**Diagnostic offset-integrity (threat model).** Each failing stage's `raw_tail` is sliced from its recorded `[log_offset, log_end_offset)` region, validated fail-closed against its execution-order neighbours' recorded offsets (`prev.log_end_offset <= log_offset <= log_end_offset <= next.log_offset`, bounded by `[0, len(log)]`); any violation yields an empty tail, never a slice into an adjacent stage. This makes a **single-field** offset tamper (which produces an inconsistent chain) fail closed. This neighbour-bounds check is the offset-integrity guard for an **unsealed** artifact (see below); on a **sealed** artifact it remains in place as defense-in-depth, but the whole-artifact seal (which covers offsets — see next paragraph) now catches offset tampers first, including a **coordinated** multi-field tamper across two stages that stays internally consistent with the neighbour-bounds check (e.g. extending one stage's `log_end_offset` and moving the next stage's `log_offset` to the same value).
+
+**Whole-artifact integrity (agent-harness#243).** Beyond the per-stage offset table (which `log_sha256` does not cover), the ENTIRE `verification.json` is sealed. At write time a canonical digest of the artifact payload — **all fields except the derived `log_sha256`**, including the per-stage `log_offset`/`log_end_offset` fields — is embedded as the `verification-artifact-sha256:<hex>` trailer line in `verification.log`, and then `log_sha256` is computed over the whole log — so the log's SHA also seals the artifact digest. At validate time, the digest is recomputed from `verification.json` and compared to the sealed trailer BEFORE the pass/fail branch (after `log_sha256_mismatch` / the load-time malformed/oversized guards, so the log is already authenticated) — a FAILING artifact is seal-protected too, not just a would-be-PASS one. A mismatch yields `artifact_seal_mismatch` and fails closed. This catches a **multi-field / structural** edit the per-stage checks miss — most importantly a verdict-flipping edit such as deleting a failed `commands[]` entry to forge a pass, and (since offsets are covered) a coordinated per-stage offset tamper that would otherwise pass the neighbour-bounds check. The seal is keyless (an editor who can rewrite the artifact, the log trailer, AND recompute `log_sha256` can still re-seal — the same trust level #209 assumed), so this raises the bar to a coordinated multi-file edit rather than being cryptographically unforgeable; it is defense-in-depth. **Back-compat / sealed-vs-unsealed split:** an artifact whose log carries no seal trailer (a v1/older run, or an externally-built log) skips the seal check entirely and still validates — for that unsealed case, the per-stage neighbour-bounds check above remains the sole offset-integrity guard, exactly as under #209. Separately, an artifact larger than `MAX_ARTIFACT_BYTES` is rejected `oversized_artifact` before it is parsed.
+
+**Redaction posture (agent-harness#243, agent-harness#266).** `raw_tail` is a bounded excerpt of `verification.log` bytes surfaced into every PERSISTED copy of a validation payload — the real egress widening this redaction narrows (the `DIAGNOSTIC_TAIL_BYTES` cap bounds record size, not disclosure — a secret is tiny). A prior round redacted only the rebuilt closeout record, on the premise that the other persisted copies (`launch.json`, the `child_automation` copy, the `events.jsonl` ledger event, the hotfix `artifact_validation`) were local-artifact-trust-class and not read into any prompt/egress path. That premise was FALSE and is corrected here: `phase-loop state --json` / `inspect_state()` reads the entire `launch.json` back out verbatim as `latest_launch_metadata`, and the harness SKILL directs agents to run `state --json` for exact state; the repair prompt separately directs an agent to inspect `events.jsonl` directly. Both are deterministic egress paths for whatever `runner_verification`/`artifact_validation` carries.
+
+Redaction is therefore now applied **at the SOURCE** — the single point each of these code paths first captures a `VerificationArtifactValidation.to_json()` payload into something that will be persisted (`redaction.apply_diagnostics_redaction`, a thin SSOT wrapper around `redact_diagnostics_metadata_only`) — rather than only in the closeout record after the fact. Any diagnostic whose fields carry a secret/PII-shaped value (detected with the same `_FORBIDDEN_METADATA_PATTERNS` the closeout malformed-metadata gate enforces) is redacted to METADATA-ONLY: `raw_tail` and `argv` are dropped, leaving role/index/exit_code/failure_kind/truncated plus byte/arg counts, a `redacted` flag, and a `redaction_reason`. Because redaction happens at the source, every downstream persisted copy inherits the redacted form: the closeout record, `launch.json` (and therefore `state --json` / `inspect_state()`), the `child_automation` copy, the `events.jsonl` ledger event (including the `reconcile --verification-log` manual-repair event), and the hotfix `artifact_validation` (both the ledger event and the printed CLI payload). The on-disk `verification.log` is left FULL — it is the intentional local source of truth and is never redacted; only these persisted, potentially-re-read copies are narrowed. `PHASE_LOOP_VERIFY_REDACT_DIAGNOSTICS=all` forces full `raw_tail`/`argv` suppression on every diagnostic across all of these source-redacted copies.
+
+**Whole-summary redaction (agent-harness#243 CR recheck of #266).** The above closed the nested `diagnostics` list, but a cross-vendor CR recheck (codex) found a SIBLING field persisted right beside it still carried the identical secret unredacted: `runner._run_execute_verification`'s persisted summary (`runner_verification`, and therefore `launch.json` / `state --json` / `child_automation` / the ledger event) sets `suite_command` to the raw resolved suite argv — for a FAILING suite, the exact secret-bearing command that produced the now-redacted diagnostic. `apply_diagnostics_redaction` therefore now walks the WHOLE payload it is given, not just a top-level `diagnostics` key: it recurses into every nested dict/list-of-dicts, redacting a `diagnostics` list at ANY depth as above, and separately checks every OTHER field whose name looks command/argv-shaped (a narrow heuristic — `command`, `argv`, or `cmd` as a substring, e.g. `suite_command`, `install_argv`) against the same `_FORBIDDEN_METADATA_PATTERNS` matcher; a match replaces the whole field value with a `"<redacted:<field>>"` placeholder (a command argv has no safe partial-redaction shape, unlike a diagnostic's structured metadata). A non-secret `suite_command` passes through unchanged. The heuristic is deliberately name-scoped rather than a blanket scan of every field, so it never touches legitimate absolute path fields (`artifact_path`, `verification_artifact_path`, `verification_log_path`) that would otherwise spuriously match the `absolute_private_path` pattern under a checkout rooted at `/home/<user>/...`.
+
+**Redaction is best-effort, not a guarantee (agent-harness#243).** The scrub is a single shared, pattern-based matcher (`_FORBIDDEN_METADATA_PATTERNS`'s `secret_like_value` entry) over `keyword=value`-shaped text, where `keyword` is one of `api_key` / `secret` / `token` / `password` (case-insensitive) and `value` is a 12+ character alphanumeric run. It recognizes that shape across the common quoting/escaping forms a captured command or log line actually takes — plain (`key=value`), single- or double-quoted (`key='value'` / `key="value"`), backslash-escaped (`key: \"value\"`, from shell/JSON re-quoting), and JSON (`"key":"value"`) — applied at the SOURCE across every persisted egress copy (closeout, `launch.json` / `state --json`, `child_automation`, the ledger event, hotfix `artifact_validation`), while `verification.log` itself is left FULL and unredacted. Coverage also extends to a STRUCTURED argv list: a pre-split `["--token", "<value>"]` pair (e.g. inside a diagnostic's `argv`) is joined into a synthesized `flag=value` composite and matched the same way, because the flag and value are already separate structured elements there — no prose ambiguity to resolve.
+
+It is explicitly **not** a guarantee against arbitrary secret encodings: a value that is base64-encoded, otherwise obfuscated, split across separate fields with no adjacent keyword, or paired with a keyword this pattern does not enumerate, will NOT be recognized and will pass through unredacted. Closing those cases is out of scope for a pattern matcher and remains the operator's responsibility (e.g. via `PHASE_LOOP_VERIFY_REDACT_DIAGNOSTICS=all` to force full suppression regardless of pattern match, or by not letting a verification command emit a secret in the first place).
+
+**Command-context-scoped flag-aware redaction (agent-harness#269, follow-up to #243, cross-vendor CR).** A space-separated CLI flag embedded in a command STRING — e.g. `"curl --token <value>"`, as `discovery.py` stores an `operational_exemptions[].command` — was previously undetected, and an earlier round documented that as a *permanent* limit: a `--token AKIA...SECRET` string and an ordinary sentence like `"Document the --token configuration behavior."` are both, character-for-character, `-{1,2}keyword` + whitespace + a 12+ character alphanumeric run, so a pattern applied to *every* leaf (including free-text closeout prose) genuinely cannot tell a high-entropy secret from a benign following word using that shape alone — a dash-anchored pattern that tried to close the gap by widening the shared, prose-facing matcher was tried and reverted for exactly that reason (it reintroduced a FATAL false positive on `metadata_redaction_diagnostic`, blocking a legitimate closeout `blocker_summary`/`next_action`/finding that merely mentioned a flag name in prose). A later cross-vendor CR round showed the "inherent" framing was wrong: the ambiguity is inherent to *prose*, not to a command STRING. A field already identified by name as command-context (`suite_command`, `operational_exemptions[].command`, an `argv` element — the same `_looks_like_command_field` heuristic the whole-summary redaction above uses) can never legitimately hold prose; its value IS a command, so `--flag VALUE` there is unambiguously a flag+value pair, never a sentence. A separate flag-aware matcher is therefore applied **only** to command-context field values, in addition to the existing strict `[:=]`-assignment matcher: it recognizes long flags (`--token VALUE`), short flags (`-t VALUE`), `=`-separated (`--token=VALUE`), and quoted flags/values (`'--token' 'VALUE'`, `"--token" "VALUE"`), with whitespace or `=` as the separator. This matcher is **never** added to the generic leaf matcher (`_forbidden_metadata_kind`) that backs prose fields or the fatal `metadata_redaction_diagnostic` gate — those stay permanently prose-safe, matching only the strict `[:=]`-assignment shape, so `"Document the --token configuration behavior."` in a `blocker_summary`/`next_action` is never false-flagged. `verification.log` (local, full, never redacted) remains the debugging source of truth regardless. The genuinely remaining out-of-scope case — base64/obfuscated/split-across-fields encodings a name-and-shape matcher cannot enumerate — is unchanged; see the paragraph above.
+
+The JSON artifact is written atomically by creating a same-directory temporary file and replacing `verification.json`. Re-running identical command inputs rewrites the same artifact shape and log content, except for timestamps and durations.
+
+Command failures, missing executables, and timeouts are evidence data. They are represented by nonzero `exit_code` values and do not make `run_verification` raise. Programmer errors, such as a missing repo or a run directory outside the repo, raise before evidence is written.
+
+The plan-time validator API is `validate_verification_commands(repo, commands) -> list[ValidationFinding]`. It is read-only and returns structured findings for empty argv, unresolved `argv[0]`, explicit repo-relative path references that do not exist, and cwd/path references that resolve outside the repo.
+
+`load_verification_artifact(path)` validates the persisted artifact and returns `VerificationResult`.
+
+Evidence marked `evidence: operational` can be recorded for operator inspection, but it cannot mark runner-executed verification as passed. A later runner phase must still reduce actual command exit data before claiming verification success.
+
+## Hotfix Consumers
+
+`phase-loop hotfix --init-stub <path>` writes a minimal stub with `objective`
+and `verification_command` fields without creating a run directory.
+
+`phase-loop hotfix --reason <text> --plan <stub-path>` is an emergency
+consumer of the same IF-0-VC-1 evidence path. It creates
+`.phase-loop/runs/<ts>-hotfix-<slug>/`, runs dependency-manifest env refresh,
+the stub verification command, and the effective suite command through
+`run_verification`, then validates the resulting artifact before ledger
+closeout. A passed hotfix event must include `work_unit: hotfix`, the redacted
+reason, plan stub, `verification_artifact_path`, `verification_log_path`, and
+the artifact validation summary. A missing, malformed, tampered, or nonzero
+artifact blocks the hotfix closeout instead of reporting `passed`.
+
+Use hotfix for a single bounded change with no interface freeze. Anything that
+changes interfaces, roadmap scope, or downstream work uses a roadmap phase.

{phase_loop_runtime-0.7.10 → phase_loop_runtime-0.7.11}/src/phase_loop_runtime/advisor_board/CONTRACTS.md

@@ -28,8 +28,9 @@ equivalence is proven by a test (not asserted in prose).
   the **agy/gemini leg where effort is embedded in the model-name string**
   (`render_gemini_model`, panel_invoker.py:1016). Built-3 lanes are concrete;
   breadth lanes raise `EffortMappingError` until ABDREG/ABDHOME/ABDOMNI.
-  Round-trip (proven): claude→`--effort max` (:324), codex→
-  `-c model_reasoning_effort=xhigh` (:992), gemini→`"Gemini 3.1 Pro (High)"` (:1016).
+  Round-trip (proven): claude→`--effort max`, codex→
+  `-c model_reasoning_effort=xhigh`, Gemini Flash→`gemini-3.6-flash-high`;
+  explicit legacy Pro display names remain compatible.
 - **Seat identity for result re-keying** — `Seat.seat_key` is a stable LABEL over
   every distinguishing field (lane, model, effort, lens), so lens-only-different
   seats get distinct keys. It is not a guaranteed-unique id — a board may hold two
@@ -74,18 +75,23 @@ equivalence is proven by a test (not asserted in prose).
   API-key var; an api-key seat (only behind the board opt-in) scrubs everything
   then injects **only the seat vendor's** key(s). Never silent — an api-key seat
   without the opt-in raises.
+- **Claude Fable/Opus = subscription TUI only** — the shared scrub additionally
+  removes Anthropic tokens, alternate base URLs, credential-helper inputs, and
+  Bedrock/Vertex/Foundry/Mantle/AWS-provider selectors. Run-isolated settings
+  disable `apiKeyHelper`; `claude auth status --json` must prove first-party
+  `claude.ai` subscription auth before the exact-model self-PTY launch. The
+  homebrew backing is mandatory; alternate backings fail before gateway access.
+  API-key fallback and native Task/subagent fulfillment are forbidden.
 - **`VENDOR_API_KEY_VARS`** — the flat `_API_KEY_VARS` tuple re-keyed by vendor
   family; its union equals today's tuple (proven), so scrubbing stays
   byte-equivalent.
 
 ## IF-0-ABDFREEZE-4 — Back-compat contract · `fixtures.py` + `tests/test_advisor_board_backcompat.py`
 
-- The `default` board (`DEFAULT_BOARD`) resolves to today's three seats in
-  `PANEL_LEGS` order, and each seat renders to today's exact model string + effort
-  args (cross-checked against `panel_invoker.DEFAULT_LEG_MODELS` and the
-  codex/claude/agy arg forms). Full assertions (launch order, payloads, env/auth,
-  timeout/retry, result keys, output formatting, failure semantics, `invoke_panel`
-  API) land in ABDVERIFY; this ships the **scaffold + the default-board fixture**.
+- The model-first `default` board (`DEFAULT_BOARD`) resolves four vendors in
+  `DEFAULT_BOARD_VENDOR_ORDER`: Codex/Sol, Gemini/Flash high, Claude/Fable, and
+  Grok 4.5. The separate legacy `PANEL_LEGS` tuple and explicit `invoke_panel`
+  API remain the frozen three-leg Codex/Gemini/Claude boundary.
 - `advisor-panel` stays a working alias of `advisor-board` — the rename + alias is
   ABDRESOLVE; this contract only *states* the invariant.
 - **Behavior-neutrality proof:** `git diff` on `panel_invoker.py` is empty and the
@@ -179,9 +185,9 @@ the real matrix at `load_boards()` time (`tests/test_advisor_board_config.py`,
   implementer stays Sonnet. The `default` board (`fixtures.DEFAULT_BOARD`) is
   byte-pinned to this Fable `invoke_panel` panel by the golden proof
   (`tests/test_advisor_board_golden.py`); the sole sanctioned delta stays `seat_key`.
-- **`code-review` = three frontier vendors, always.** codex `gpt-5.6-sol`,
-  `Gemini 3.1 Pro`, and `claude-fable-5`, each on the `adversarial` lens (supersedes
-  the prior two-seat codex+sonnet composition).
+- **`default` and `code-review` are four-vendor frontier boards.** Gemini uses
+  `gemini-3.6-flash` at its `high` ceiling alongside Sol, Fable, and Grok 4.5;
+  `code-review` preserves availability-aware backfill and distinct lenses.
 - **Divergent-thinking boards keep Sonnet.** `brainstorm` / `doc-edit` /
   `legal-brainstorm` deliberately retain `claude-sonnet-5` — a diverse voice, a
   low-stakes copyedit, a cheap aggressive ideation seat — where it is the right tool.
@@ -190,7 +196,7 @@ the real matrix at `load_boards()` time (`tests/test_advisor_board_config.py`,
   (`schema.py`), so the legal lenses/purposes need no enum extension.
 - **Catch-alls for unmodeled tasks (`general`, `solo`).** So the board library is not
   limited to the pre-modeled domains: `general` is the domain-agnostic top-tier PANEL
-  (three frontier vendors — gpt-5.6-sol/adversarial, Gemini 3.1 Pro/alternative,
+  (three frontier vendors — gpt-5.6-sol/adversarial, gemini-3.6-flash/alternative,
   claude-fable-5/completeness — hand it any task + brief), and `solo` is the
   single-MEMBER form (one `claude-fable-5` seat) for a quick top-end opinion when a
   panel is overkill. A ONE-seat board validates + resolves through `invoke_board` like
@@ -200,7 +206,7 @@ the real matrix at `load_boards()` time (`tests/test_advisor_board_config.py`,
   (`adversarial`/`alternative`/`completeness`) and purpose (`general`) are free-form
   strings, so no enum extension.
 - **Deep-seat FOLLOW-ON (documented, NOT built here).** The richer legal treatment —
-  four lenses per seat, an apex-Opus (`claude-opus-4-8`) seat, a verify-round, and
+  four lenses per seat, an apex-Opus (`claude-opus-5`) seat, a verify-round, and
   retrieval-grounded citation-verification — is a deliberate follow-on. The current
   legal boards ship the single-primary-lens-per-seat form; the deep-seat form layers
   onto the same seat/board schema (no schema change) when built.

{phase_loop_runtime-0.7.10 → phase_loop_runtime-0.7.11}/src/phase_loop_runtime/advisor_board/__init__.py

@@ -26,6 +26,7 @@ and the ``LedgerWriter`` cross-language transport seam. This is the one place th
 package touches ``panel_invoker`` — an OPT-IN ``sink=`` on ``invoke_board``;
 ``sink=None`` stays byte-neutral.
 """
+
 from __future__ import annotations
 
 from .schema import (
@@ -37,8 +38,14 @@ from .schema import (
     CONFIG_RELATIVE_PATH,
     EFFORT_LEVELS,
     PROVIDER_BACKINGS,
+    SCOPED_RESEARCH_CAPABILITY,
+    SCOPED_RESEARCH_GATEWAY_TOOLS,
+    SCOPED_RESEARCH_PMCP_VERSION,
+    SCOPED_RESEARCH_SERVERS,
+    SCOPED_RESEARCH_TOOL_PATTERNS,
     Board,
     HostContext,
+    ResearchPolicy,
     Seat,
     board_config_path,
     identify_host_leg,
@@ -101,10 +108,12 @@ from .config import (
     load_boards,
 )
 from .backing import (
+    CLAUDE_SUBSCRIPTION_BLOCKED_ENV_VARS,
     VENDOR_API_KEY_VARS,
     BackingDecision,
     all_vendor_key_vars,
     resolve_seat_env,
+    scrub_subscription_env,
     select_backing,
 )
 from .backing_omnigent import (
@@ -127,6 +136,25 @@ from .events import (
     NullSink,
     best_effort_forward,
 )
+from .research import (
+    MCP_SERVER_NAME,
+    RESEARCH_CAPABLE_LANES,
+    ResearchAuditError,
+    ResearchInvocation,
+    ResearchLedger,
+    ResearchRunConfig,
+    ResearchSeatConfig,
+    ResearchUnavailable,
+    claude_mcp_config,
+    codex_mcp_args,
+    materialize_research_run,
+    mcp_tool_names,
+    probe_research_capability,
+    reduce_research_audit,
+    research_instructions,
+    scrub_research_env,
+    unavailable_ledger,
+)
 from .observability import (
     LEDGER_RECORD_KIND,
     LEDGER_RECORD_SCHEMA,
@@ -149,6 +177,7 @@ from .fixtures import (
     CANONICAL_LEG_ORDER,
     CANONICAL_VALID_PAIRS,
     DEFAULT_BOARD,
+    DEFAULT_BOARD_VENDOR_ORDER,
     DEFAULT_SEAT_EFFORT_ARGS,
     DEFAULT_SEAT_RENDERED_MODEL,
     DEFAULT_SEATS,
@@ -178,6 +207,7 @@ __all__ = [
     "Seat",
     "Board",
     "HostContext",
+    "ResearchPolicy",
     "EFFORT_LEVELS",
     "AUTH_LANES",
     "AUTH_SUBSCRIPTION",
@@ -186,6 +216,11 @@ __all__ = [
     "BACKING_HOMEBREW",
     "BACKING_OMNIGENT",
     "CONFIG_RELATIVE_PATH",
+    "SCOPED_RESEARCH_CAPABILITY",
+    "SCOPED_RESEARCH_PMCP_VERSION",
+    "SCOPED_RESEARCH_SERVERS",
+    "SCOPED_RESEARCH_GATEWAY_TOOLS",
+    "SCOPED_RESEARCH_TOOL_PATTERNS",
     "board_config_path",
     "identify_host_leg",
     "seat_vendor_family",
@@ -241,7 +276,9 @@ __all__ = [
     "load_boards",
     # backing + auth
     "VENDOR_API_KEY_VARS",
+    "CLAUDE_SUBSCRIPTION_BLOCKED_ENV_VARS",
     "all_vendor_key_vars",
+    "scrub_subscription_env",
     "BackingDecision",
     "select_backing",
     "resolve_seat_env",
@@ -256,6 +293,24 @@ __all__ = [
     "OmnigentGatewayUnavailable",
     "SeatRunOutcome",
     "classify_http_failure",
+    # governed PMCP research
+    "MCP_SERVER_NAME",
+    "RESEARCH_CAPABLE_LANES",
+    "ResearchUnavailable",
+    "ResearchAuditError",
+    "ResearchSeatConfig",
+    "ResearchRunConfig",
+    "ResearchInvocation",
+    "ResearchLedger",
+    "probe_research_capability",
+    "materialize_research_run",
+    "research_instructions",
+    "claude_mcp_config",
+    "codex_mcp_args",
+    "mcp_tool_names",
+    "scrub_research_env",
+    "reduce_research_audit",
+    "unavailable_ledger",
     # events
     "AdvisorBoardEvent",
     "EventSink",
@@ -281,6 +336,7 @@ __all__ = [
     "BoardObserver",
     # fixtures
     "DEFAULT_BOARD",
+    "DEFAULT_BOARD_VENDOR_ORDER",
     "DEFAULT_SEATS",
     "DEFAULT_SEAT_RENDERED_MODEL",
     "DEFAULT_SEAT_EFFORT_ARGS",

{phase_loop_runtime-0.7.10 → phase_loop_runtime-0.7.11}/src/phase_loop_runtime/advisor_board/backing.py

@@ -48,6 +48,38 @@ VENDOR_API_KEY_VARS: dict[str, tuple[str, ...]] = {
     "gemini": ("GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"),
 }
 
+# Credentials and routing selectors that can move a Claude Code process away
+# from the first-party Claude.ai subscription lane.  This is deliberately
+# broader than ``VENDOR_API_KEY_VARS``: the latter remains the frozen cross-
+# vendor API-key map, while this set also covers helpers, gateways, and cloud
+# providers that Claude Code gives precedence over subscription OAuth.
+CLAUDE_SUBSCRIPTION_BLOCKED_ENV_VARS: tuple[str, ...] = (
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_CUSTOM_HEADERS",
+    "ANTHROPIC_BEDROCK_BASE_URL",
+    "ANTHROPIC_BEDROCK_MANTLE_BASE_URL",
+    "ANTHROPIC_VERTEX_BASE_URL",
+    "ANTHROPIC_VERTEX_PROJECT_ID",
+    "ANTHROPIC_FOUNDRY_API_KEY",
+    "ANTHROPIC_FOUNDRY_BASE_URL",
+    "ANTHROPIC_FOUNDRY_RESOURCE",
+    "ANTHROPIC_AWS_BASE_URL",
+    "ANTHROPIC_AWS_WORKSPACE_ID",
+    "AWS_BEARER_TOKEN_BEDROCK",
+    "CLAUDE_CODE_API_KEY_HELPER_TTL_MS",
+    "CLAUDE_CODE_USE_ANTHROPIC_AWS",
+    "CLAUDE_CODE_USE_BEDROCK",
+    "CLAUDE_CODE_USE_FOUNDRY",
+    "CLAUDE_CODE_USE_MANTLE",
+    "CLAUDE_CODE_USE_VERTEX",
+    "CLAUDE_CODE_SKIP_BEDROCK_AUTH",
+    "CLAUDE_CODE_SKIP_FOUNDRY_AUTH",
+    "CLAUDE_CODE_SKIP_MANTLE_AUTH",
+    "CLAUDE_CODE_SKIP_VERTEX_AUTH",
+)
+
 
 def all_vendor_key_vars() -> tuple[str, ...]:
     """Every vendor API-key var (scrub set for a subscription seat)."""
@@ -59,6 +91,18 @@ def all_vendor_key_vars() -> tuple[str, ...]:
     return tuple(seen)
 
 
+def scrub_subscription_env(base_env: Mapping[str, str]) -> dict[str, str]:
+    """Return a subscription-only child environment.
+
+    All vendor API keys are removed. Claude-specific credential helpers,
+    custom request headers, alternate endpoints, and cloud-provider selectors
+    are removed as well so a Claude seat cannot silently escape the first-party
+    subscription lane.
+    """
+    blocked = set(all_vendor_key_vars()) | set(CLAUDE_SUBSCRIPTION_BLOCKED_ENV_VARS)
+    return {key: value for key, value in base_env.items() if key not in blocked}
+
+
 # --- backing selector -------------------------------------------------------
 
 
@@ -107,16 +151,21 @@ def resolve_seat_env(
     silent key can never slip through. Pure and side-effect-free; ABDHOME wires
     it into the subprocess/gateway env.
     """
-    env = {k: v for k, v in base_env.items() if k not in all_vendor_key_vars()}
+    env = scrub_subscription_env(base_env)
     if seat.auth == AUTH_SUBSCRIPTION:
         return env
     if seat.auth == AUTH_API_KEY:
+        vendor = seat_vendor_family(seat)
+        if vendor == "claude" and seat.model.lower().startswith(("claude-fable-", "claude-opus-")):
+            raise ValueError(
+                f"seat {seat.seat_key} requires Claude Code TUI subscription auth; "
+                "api_key fallback is forbidden"
+            )
         if not allow_api_key_fallback:
             raise ValueError(
                 f"seat {seat.seat_key} requests the api_key lane but the board did not "
                 "opt in (allow_api_key_fallback=False) — never-silent-key"
             )
-        vendor = seat_vendor_family(seat)
         for var in VENDOR_API_KEY_VARS.get(vendor, ()):  # ONLY this vendor's key(s)
             if var in base_env:
                 env[var] = base_env[var]
@@ -126,7 +175,9 @@ def resolve_seat_env(
 
 __all__ = [
     "VENDOR_API_KEY_VARS",
+    "CLAUDE_SUBSCRIPTION_BLOCKED_ENV_VARS",
     "all_vendor_key_vars",
+    "scrub_subscription_env",
     "BackingDecision",
     "select_backing",
     "resolve_seat_env",

{phase_loop_runtime-0.7.10 → phase_loop_runtime-0.7.11}/src/phase_loop_runtime/advisor_board/composition.py

@@ -6,7 +6,7 @@ its MAX thinking and each carrying a DISTINCT review lens:
     grok    grok-4.5         max   lens=adversarial
     claude  claude-fable-5   max   lens=correctness
     codex   gpt-5.6-sol      max   lens=red-team
-    gemini  Gemini 3.1 Pro   high  lens=alternative-approach   (high == its ceiling)
+    gemini  Gemini 3.6 Flash high  lens=alternative-approach   (high == its ceiling)
 
 The load-bearing behavior is the **availability-aware fallback**: a panel must
 NEVER collapse to one or two reviewers just because one or two vendors are down.
@@ -47,7 +47,7 @@ _VENDOR_SEAT: dict[str, dict[str, str]] = {
     "grok": {"model": "grok-4.5", "harness": "grok", "effort": "max", "lens": "adversarial"},
     "claude": {"model": "claude-fable-5", "harness": "claude", "effort": "max", "lens": "correctness"},
     "codex": {"model": "gpt-5.6-sol", "harness": "codex", "effort": "max", "lens": "red-team"},
-    "gemini": {"model": "Gemini 3.1 Pro", "harness": "gemini", "effort": "high", "lens": "alternative-approach"},
+    "gemini": {"model": "gemini-3.6-flash", "harness": "gemini", "effort": "high", "lens": "alternative-approach"},
 }
 
 # Distinct lenses the backfill cycles through (each vendor's primary lens is drawn

{phase_loop_runtime-0.7.10 → phase_loop_runtime-0.7.11}/src/phase_loop_runtime/advisor_board/config.py

@@ -18,12 +18,13 @@ built-in ``presets``. Contract:
 
 A missing config file is not an error: the built-in presets load on their own.
 """
+
 from __future__ import annotations
 
 from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
 
 try:  # Python 3.11+
     import tomllib  # type: ignore[import-not-found]
@@ -37,6 +38,7 @@ from .schema import (
     AUTH_LANES,
     PROVIDER_BACKINGS,
     Board,
+    ResearchPolicy,
     Seat,
     board_config_path,
 )
@@ -44,7 +46,7 @@ from .schema import (
 # Recognised keys — anything else is a hard error (no silent drop).
 _KNOWN_TOP_KEYS: frozenset[str] = frozenset({"default_board", "boards"})
 _KNOWN_BOARD_KEYS: frozenset[str] = frozenset(
-    {"name", "purpose", "allow_api_key_fallback", "seats"}
+    {"name", "purpose", "allow_api_key_fallback", "research_enabled", "seats"}
 )
 _KNOWN_SEAT_KEYS: frozenset[str] = frozenset(
     {"model", "effort", "harness", "lens", "auth", "backing", "host_leg"}
@@ -114,7 +116,9 @@ def _parse_seat(raw: Mapping[str, Any], where: str) -> Seat:
     if "model" not in raw:
         raise BoardConfigError(f"{where} is missing the required 'model' key")
     if "effort" not in raw:
-        raise BoardConfigError(f"{where} (model={raw['model']!r}) is missing the required 'effort' key")
+        raise BoardConfigError(
+            f"{where} (model={raw['model']!r}) is missing the required 'effort' key"
+        )
     auth = raw.get("auth", AUTH_LANES[0])
     backing = raw.get("backing", PROVIDER_BACKINGS[0])
     try:
@@ -145,7 +149,8 @@ def _parse_board(raw: Mapping[str, Any], index: int) -> Board:
     if not isinstance(seats_raw, list):
         raise BoardConfigError(f"board {name!r} 'seats' must be a list of seat tables")
     seats = tuple(
-        _parse_seat(seat, f"board {name!r} seats[{i}]") for i, seat in enumerate(seats_raw)
+        _parse_seat(seat, f"board {name!r} seats[{i}]")
+        for i, seat in enumerate(seats_raw)
     )
     try:
         return Board(
@@ -155,6 +160,9 @@ def _parse_board(raw: Mapping[str, Any], index: int) -> Board:
             allow_api_key_fallback=_require_bool(
                 raw, "allow_api_key_fallback", False, where
             ),
+            research_policy=ResearchPolicy(
+                enabled=_require_bool(raw, "research_enabled", False, where)
+            ),
         )
     except (ValueError, TypeError) as exc:
         # Board.__post_init__ (e.g. api_key seat without opt-in) -> config error.
@@ -203,7 +211,9 @@ def load_boards(
     # Availability-aware code-review (before the user overlay so a user override wins).
     compose_probe = is_available
     if compose_probe is None and matrix is not None:
-        compose_probe = getattr(getattr(matrix, "harnesses", None), "is_available", None)
+        compose_probe = getattr(
+            getattr(matrix, "harnesses", None), "is_available", None
+        )
     # #151: the LIVE convening path is auth-aware by DEFAULT — a PATH-present but
     # unauthenticated vendor is dropped and backfilled. Pass an explicit ``auth_ok``
     # so the composer never falls through to its is_available-injected pass-through
@@ -211,7 +221,9 @@ def load_boards(
     # gate short-circuits for vendors that fail the availability probe, so a host
     # with no vendor CLI never shells out.
     compose_auth = auth_ok if auth_ok is not None else default_board_auth_ok
-    composed_review = compose_review_board(is_available=compose_probe, auth_ok=compose_auth)
+    composed_review = compose_review_board(
+        is_available=compose_probe, auth_ok=compose_auth
+    )
     boards[composed_review.name] = composed_review
 
     cfg_path = path if path is not None else board_config_path(env)