phase-loop-runtime 0.7.15__tar.gz → 0.7.17__tar.gz

{phase_loop_runtime-0.7.15 → phase_loop_runtime-0.7.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.15
+Version: 0.7.17
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author-email: ViperJuice <viperjuice@users.noreply.github.com>
 License-Expression: Apache-2.0
@@ -49,7 +49,7 @@ To install just this runtime package directly:
 
 ```sh
 pip install phase-loop-runtime              # latest compatible release
-pip install phase-loop-runtime==0.7.15      # …or pin an exact version
+pip install phase-loop-runtime==0.7.17      # …or pin an exact version
 ```
 
 To pin a specific tag from source instead, substitute a tag from

{phase_loop_runtime-0.7.15 → phase_loop_runtime-0.7.17}/README.md

@@ -19,7 +19,7 @@ To install just this runtime package directly:
 
 ```sh
 pip install phase-loop-runtime              # latest compatible release
-pip install phase-loop-runtime==0.7.15      # …or pin an exact version
+pip install phase-loop-runtime==0.7.17      # …or pin an exact version
 ```
 
 To pin a specific tag from source instead, substitute a tag from

{phase_loop_runtime-0.7.15 → phase_loop_runtime-0.7.17}/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.15"
+version = "0.7.17"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"

{phase_loop_runtime-0.7.15 → phase_loop_runtime-0.7.17}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.15"
+__version__ = "0.7.17"

{phase_loop_runtime-0.7.15 → phase_loop_runtime-0.7.17}/src/phase_loop_runtime/advisor_board/CONTRACTS.md

@@ -95,14 +95,17 @@ equivalence is proven by a test (not asserted in prose).
   deferred seat natively and the fill counts only once bound (EC-REVIEWTRUTH-14,
   agent-harness#921) — the host×seat routing rule above.
 - **`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.
+  family; its union equals today's tuple (proven). It is also the api-key INJECTION map.
+  `scrub_subscription_env` additionally removes `SUBSCRIPTION_SCRUB_ONLY_VARS`
+  (`XAI_API_KEY`, `GROK_CODE_XAI_API_KEY`; agent-harness#864): the api-key variables of the
+  subscription-only grok harness, scrubbed but never injectable -- and
+  `GROK_SUBSCRIPTION_BLOCKED_ENV_VARS`, grok's endpoint redirects.
 
 ## IF-0-ABDFREEZE-4 — Back-compat contract · `fixtures.py` + `tests/test_advisor_board_backcompat.py`
 
 - 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.6. The separate legacy `PANEL_LEGS` tuple and explicit `invoke_panel`
+  `DEFAULT_BOARD_VENDOR_ORDER`: Codex/Sol, Gemini/Flash high, Claude/Opus 5.5, and
+  Grok 4.7. 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.
@@ -184,24 +187,27 @@ The seven built-in presets (`presets.PRESETS`). Every preset self-validates agai
 the real matrix at `load_boards()` time (`tests/test_advisor_board_config.py`,
 `tests/test_advisor_board_integration.py`).
 
-- **Review-class = Fable, decoupled from the implementer.** Pre-merge and legal
-  review are mid-tier decisions where being wrong is expensive, so the review-class
-  boards (`default`, `code-review`, `legal-review`, `legal-strategy-review`) seat
-  Fable (`claude-fable-5-1`) on the claude lane — NOT the implementer model
+- **Review-class = Opus 5.5 (for now), decoupled from the implementer.** Pre-merge
+  and legal review are mid-tier decisions where being wrong is expensive, so the
+  review-class boards (`default`, `code-review`, `legal-review`,
+  `legal-strategy-review`) seat Opus 5.5 (`claude-opus-5-5`) on the claude lane — the
+  maintainer's review default "for now" (2026-09-23), Fable (`claude-fable-5-1`)
+  before that and still selectable — NOT the implementer model
   `profiles.CLAUDE_IMPLEMENTER_MODEL` (`claude-sonnet-5`). `panel_invoker.DEFAULT_LEG_MODELS["claude"]`
   is the SINGLE source of truth for the panel's default claude model: the claude
   leg builder (`_claude_tui_command`) and the Agent-View attempt both read it, so
   the *legacy* `invoke_panel` path AND the live governed gates
   (`governed_review` / `governed_premerge`, which call `invoke_panel` with no model
-  override) review on Fable. `CLAUDE_IMPLEMENTER_MODEL` is untouched — the
+  override) review on Opus 5.5. `CLAUDE_IMPLEMENTER_MODEL` is untouched — the
   implementer stays Sonnet. The `default` board (`fixtures.DEFAULT_BOARD`) is
-  byte-pinned to this Fable `invoke_panel` panel by the golden proof
+  byte-pinned to this `invoke_panel` panel by the golden proof
   (`tests/test_advisor_board_golden.py`); the sole sanctioned delta stays `seat_key`.
 - **`default` and `code-review` are four-vendor frontier boards.** Gemini uses
-  `gemini-3.8-flash` at its `high` ceiling alongside Sol, Fable, and Grok 4.6;
+  `gemini-3.8-flash` at its `high` ceiling alongside Sol, Opus 5.5, and Grok 4.7;
   `code-review` preserves availability-aware backfill and distinct lenses.
-- **President availability ladder.** Review findings go first to Fable, then
-  Sol, Grok 4.6, and Gemini 3.8 Flash. Descent occurs only for a typed
+- **President availability ladder.** Review findings go first to the `fable` seat
+  (Opus 5.5 by default — the rung names the seat, not the model), then
+  Sol, Grok 4.7, and Gemini 3.8 Flash. Descent occurs only for a typed
   `president_unavailable` result, never because a president dissents. The ladder
   is EXECUTED (not merely declared) by every `requires_president` landing policy —
   see ABDPRES below.
@@ -214,8 +220,8 @@ the real matrix at `load_boards()` time (`tests/test_advisor_board_config.py`,
 - **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-6-astra/adversarial, gemini-3.8-flash/alternative,
-  claude-fable-5-1/completeness — hand it any task + brief), and `solo` is the
-  single-MEMBER form (one `claude-fable-5-1` seat) for a quick top-end opinion when a
+  claude-opus-5-5/completeness — hand it any task + brief), and `solo` is the
+  single-MEMBER form (one `claude-opus-5-5` seat) for a quick top-end opinion when a
   panel is overkill. A ONE-seat board validates + resolves through `invoke_board` like
   any other (bare/single seats are supported). Both default to TOP-END models: an
   unanticipated task cannot be assumed low-stakes, so the safe default is frontier —
@@ -450,7 +456,9 @@ a landing decision. `tests/test_president_wiring.py`.
   seated rung with it: the governed caller must receive that as a board result it
   persists, not as an error it never records. Only a caller-contract error
   (`president_round_limit`) propagates as `PresidentPolicyError`.
-- **Execution route (fail-closed by design).** `president_adapter.build_president_invoke`
+- **Execution route — SUPERSEDED by ABDPRESROUTE below** (agent-harness#952): a seated
+  rung now runs through `public_board_president.v1`. The text of this bullet records the
+  pre-PRESROUTE route. `president_adapter.build_president_invoke`
   binds the ladder to a board's seats (`seat_for_rung`: rung alias → seat model →
   harness). An UNSEATED rung answers typed `president_unavailable` (the ladder
   descends). A SEATED rung answers `failed` / `president_execution_route_unavailable`
@@ -485,3 +493,216 @@ a landing decision. `tests/test_president_wiring.py`.
 - **Standalone launchers.** A caller that wants the four-seat board without a
   president passes an explicit `review_policy=ReviewLandingPolicy(required_seats=...,
   requires_president=False)` rather than a president-requiring tier.
+
+## ABDPRESROUTE — The president operation · `president_operation.py`, `president_adapter.py`, `advisor_board/backing.py`, `panel_invoker.invoke_board` (IF-0-PRESROUTE-1, Consiliency/agent-harness#952)
+
+The president's OWN HARDEN-authorized operation, `public_board_president.v1`, beside —
+never through — the review operation `public_board_review.v1`. Frozen falsifiers:
+`tests/test_president_wiring.py`, `tests/test_govlean_panel_policy.py` (SL-0,
+`content_tdd_receipt.v1`), golden `tests/data/president_ruling_v1.golden.json`.
+
+- **Callable.** `president_operation.run_president_operation(*, brief, findings,
+  authorization, invoke, max_substantive_rounds) -> PresidentOperationResult(ruling,
+  authorization_identity, rung_index, brief_digest, findings_digest)`. It refuses an
+  authorization whose `operation` is not exactly `public_board_president.v1`
+  (`PresidentPolicyError("president_operation_authorization_mismatch")`) BEFORE any rung
+  is invoked, then walks `PRESIDENT_LADDER` through `invoke` with the president prompt
+  built from the findings; the brief is digested, not sent.
+- **Digests.** `brief_digest = sha256(brief)`; `findings_digest =
+  sha256("\n".join(findings))` in prompt order; lowercase hex. On a board, the brief is
+  the composed president prompt `_president_prompt(findings)`.
+- **Completion grammar.** Per-finding `FINDING <id>: BLOCKING|DEFERRED — <reason>`,
+  terminal `FORCING DECISION: <decision>` (`_valid_president_grammar`); a launched rung's
+  turn is complete when its last line is a non-empty `FORCING DECISION:`
+  (`_completion_ok(text, "president")`), never a review verdict.
+- **Authorization.** `backing.prepare_president_isolation_authorization(board, brief)`
+  mints `PresidentIsolationAuthorization` (same seal as review isolation;
+  `child_credentialless=True`, `child_network_egress=False`, `live_tree_exposed=False`,
+  `api_fallback=False`; subscription routes; brief digest; repository identity when the
+  launch has one — the operation reads no tree). The adapter revalidates it
+  (`revalidate_president_isolation_authorization`) immediately before a rung launches and
+  launches that authorization's route; a seat the authorization does not route (Claude
+  included) is refused without launching.
+- **Rung routes** (`president_adapter.build_president_invoke(..., monitoring_policy=)`).
+  Unseated rung → typed `president_unavailable` (descend). `sol` / `grok` → the brokered
+  `_exec_leg` in a throwaway directory, whose only launch is `launch_provider`. `gemini` →
+  the broker's acknowledged agy stream with the PRESIDENT's own final instruction (a ruling,
+  not a review verdict), launched through `_run_leg_with_liveness` → `launch_provider` and
+  decoded by `_broker_gemini_stream_result`; with the agy subscription credential it runs in
+  the broker's agy profile, without one in an empty private HOME (no credential of any kind),
+  so the provider itself refuses and the failure is typed. `fable` under Claude Code (from the passed `base_env`; the adapter
+  falls back to the process environment only when none is passed, so it never spawns a
+  second TUI) → a deferred native fill `{"status": "native_fill_deferred", rung,
+  brief_digest, findings_digest}`, refused with `president_fill_heartbeat_refused` under
+  `heartbeat_only`. `fable` elsewhere → the brokered self-PTY session
+  (`_run_claude_tui_session`, tools off, no directory grant). A failed launch is a typed
+  `failed` (`president_invocation_failed`, no descent).
+- **Ladder** (EC-PRESROUTE-3). `PRESIDENT_LADDER` is the seat-alias tuple; each alias
+  resolves to its vendor's registry PIN through `DEFAULT_REVIEW_SEAT_ALIASES` (where the
+  `model-id-source:` markers live). No model id is spelled in the ladder.
+- **Brokered, monitored launch** (agent-harness#1001). Every non-native rung launch runs
+  under the isolation a review seat gets: `isolated_network` egress (no retained
+  capabilities), a single-use broker capability minted by
+  `backing.derive_president_leg_authorization` from the operation's lease
+  (`prepare_president_isolation_authorization(..., monitoring_policy=)` registers it;
+  `activate_/close_president_isolation_authorization` bracket each launch) carrying the
+  PRESIDENT operation identity, and the `ParentUnixBroker` over read-only staged bytes (the
+  brief and a fixed president instruction marker). Under `heartbeat_only` the transport runs
+  with a `_ReviewMonitor` -- no model-thinking deadline, no silence kill; cancellation (the
+  board's `cancel_event`) and owner loss are the only stops -- and the gemini rung uses the
+  owned heartbeat agy profile, and the Claude rung hands the broker's quiescence latch to its
+  TUI session. A missing canonical repository, an empty egress prefix (always -- the
+  authorization declares no network egress) or a cancelled operation
+  (`president_operation_cancelled`, which stops the walk) is a typed refusal before any provider
+  starts. Under BOUNDED monitoring only, a patched transport or launch site is the in-process
+  control seam and is not brokered (never evidence), as for review seats; `heartbeat_only` is
+  always brokered.
+- **Configured ladder** (agent-harness#998 follow-up). `PRESIDENT_LADDER` is the BUILT-IN
+  order; the effective order is `advisor_board.config.load_president_ladder(repo_dir, *,
+  env, path)`: built-in < the user file's `[president] ladder`
+  (`$XDG_CONFIG_HOME/agent-harness/advisor-boards.toml`) < the repository's
+  `<repo>/.agent-harness/advisor-boards.toml` (`[president]` only; `[[boards]]` there is
+  refused). A ladder is a non-empty list of distinct seat aliases or alias-table model ids
+  (`validate_president_ladder`); a malformed one or an unknown key is `BoardConfigError`,
+  never a silent fall-back. The seam carries it (`build_president_invoke(..., ladder=)`,
+  `PresidentInvoke.ladder`); `invoke_president` walks `effective_president_ladder(invoke)`
+  (the seam's ladder, else the built-in), and `rung_index` is the rung's position in THAT
+  ladder. The phase-loop runner (`_run_legible_panel`), `advisor-board --landing-tier` and
+  `invoke_board`'s auto-wired seam load it; a malformed ladder is refused before any seat
+  (`president_ladder_invalid` / CLI exit 2). The user layer follows the environment it is
+  given: the auto-wired seam reads it from the passed `base_env` (its `XDG_CONFIG_HOME`,
+  else its `HOME`; neither ⇒ no user layer), never from the process HOME.
+- **Defer → resume** (EC-PRESROUTE-2). A deferred Fable rung makes `invoke_board` return
+  the seats with `PanelResult.needs_native_president` = `{rung, brief_digest,
+  findings_digest, prompt}` and no ruling, persisting `president.pending.json`
+  (`president.pending.v1`: the request plus the findings and seat verdicts it was built
+  from) to `stream_dir`; a deferral without `stream_dir` is refused
+  (`president_native_fill_stream_required`). `invoke_board(..., native_president_fill=
+  {rung, brief_digest, findings_digest, text})` RESUMES after the same factory /
+  revalidation gate and before any seat launches -- no seat is re-run, so seats that would
+  word things differently cannot strand the route. The pending request is BOUND to its run
+  (resolved-artifact digest, the review-brief digest captured ONCE before any seat runs,
+  the board's ordered seat keys, mode, landing policy, president ladder and the seat each
+  rung resolves to under the run's `review_seat_aliases`) and the resume
+  refuses any difference. A new deferral removes any `president.ruling.json` an earlier
+  run left in the stream (after its pending request is written); every persisted ruling
+  removes any pending request (so an older request cannot later resume over it). The
+  resume and the ruling record resolve the rung through the run's `review_seat_aliases`. The fill is accepted only when that binding matches, the
+  stored verdicts are this board's seats in order and re-derive the stored findings, the
+  pending rung is this board's natively filled (Claude) rung, the persisted digests
+  recompute from the stored findings, the fill's rung and BOTH digests equal them, and the
+  text passes the ruling grammar for those findings. An accepted request is CONSUMED (it
+  answers once). This guards against a stale or mismatched stream, not a caller who forges
+  its own stream directory (the stream is the caller's durable context); otherwise `president_fill_digest_mismatch` (or
+  `president_ruling_format_missing` / `president_native_fill_stream_required`) and nothing
+  is persisted. The resumed result carries the deferred seats' verdicts (republished to the
+  stream) and the ruling. Under Claude Code, `invoke_board` wires the adapter itself when no
+  seam is passed -- keyed on the PASSED `base_env` only, never the process environment.
+- **Ruling record** (EC-PRESROUTE-5). Every president ruling a board obtains on a call that
+  has a review stream (`stream_dir`; the runner and the CLI always pass one, and the native
+  path refuses without one) is written atomically to `<stream_dir>/president.ruling.json`.
+  A stream-less call -- which the frozen SL-0 corpus exercises on several president nodes --
+  returns its ruling unrecorded, since there is no stream to record it in. Schema
+  `president.ruling.v1`:
+  `schema`, `authorization_identity` (`public_board_president.v1`), `rung_index`,
+  `model_id` (the ruling rung's registry PIN on the board), `format_reask_count`,
+  `brief_digest`, `findings_digest`, `forcing_decision`, `finding_rulings`
+  (`[{id, disposition, reason}]`). `president_operation.president_ruling_record(result)`
+  builds the same shape from a `PresidentOperationResult`.
+- **Override expiry** (EC-PRESROUTE-4). `panel_invoker.enforce_requires_president(tier,
+  *, requires_president)` refuses a `plan`/`production_code` landing carrying
+  `requires_president=False` (`requires_president_override_refused`); `invoke_board`
+  calls it whenever a `landing_tier` is given. The interim ratification note is EXPIRED.
+- **CLI.** `advisor-board --landing-tier <tier>` runs the board under a tier (a president
+  tier binds the seam to the driving process's environment);
+  `--native-president FILL.json` resumes a deferred rung against the pending request
+  under `--native-fill-dir`/`native-fill/president/`.
+
+## Review monitoring policy v1 (agent-harness#892)
+
+The opt-in policy vocabulary is `bounded | heartbeat_only`; omission is bounded.
+Heartbeat-only permits brokered subscription/homebrew Claude TUI, Codex and
+Grok, plus the qualified Gemini extension below. It permits no timeout overrides,
+capture, research, API fallback, gateway or native host seat. Whole-board
+capability preflight precedes availability, auth, session creation and provider
+dispatch. Missing or changed Gemini capability refuses the requested whole board;
+its membership is never reduced or backfilled to satisfy this policy.
+
+The requested/effective policy is bound to the operation lease and minted leg.
+Heartbeat-only admission expires 10 seconds after minting and is single-use;
+complete frame receipt and ownership are checked before inference. Admitted
+model response waiting has no aggregate wall-clock deadline or silence cutoff.
+It makes one attempt, including when that attempt completes empty.
+Cancellation and owner loss retain child/provider/server ownership until
+quiescence; unproven quiescence cannot become successful evidence.
+Private staged inputs and diagnostics are retained when quiescence cannot be
+proven; that retention is failure evidence, not successful cleanup.
+
+`review_monitoring.v1` is a separate metadata-only opt-in record: invocation and
+seat position, requested/effective policy, admission window, null model/silence
+deadlines, last observed progress age, observation state, and terminal reason.
+Genuine output within the existing print-read observation interval is
+`progress_observed`; older output or no output is `progress_unobserved`.
+The TUI timestamp is refreshed by novel output lines, review-file growth and
+transcript growth — a startup banner is novel output and refreshes it; only
+repeated cosmetic repaints do not, once the existing novelty detector has seen
+their text. The CPU-tick heartbeat never refreshes it.
+Neither state is a health attestation or permission to terminate. Frozen
+broker request/response keys, status literals, and observer envelopes are unchanged.
+
+When staging requires egress isolation, acquisition follows staged-tree and operation
+authorization revalidation. Heartbeat-only holds the network helper lifetime through
+an owner pipe, with no aggregate expiry; owner exit closes both helpers. Provider
+PID ownership is established after network entry but before the capability bounding
+set is emptied. Every launch retains the common provider launch seam and broker
+threads inherit its ContextVar prefix. EgressUnavailable stays DEGRADED with empty
+review text and the exception in detail; sandbox facts describe actual enforcement.
+
+### Qualified Gemini extension (agent-harness#905)
+
+The Linux x64 subscription `agy` 1.2.10 entry image must match SHA256
+`aea7ed8df1e79b716c0ccd14c7d8086db75b14da535ffb7febdec9a488deff67`.
+The running Python/kernel must support sealed memfds, pidfds and pidfd signaling;
+Python version alone is not a capability check. Unknown images or missing
+capabilities refuse before availability/auth effects. Required bwrap mount/gate
+flags are checked at admission, before inference. Measure help through the
+admitted `agy` filename: the usage line includes that name, while the same
+archive member invoked as `antigravity` produces different help bytes. The
+measured help defines literal `--print-timeout 0` as waiting for completion.
+A quick real completion establishes compatibility; clock controls establish
+that old runtime deadlines and silence cannot terminate a healthy heartbeat-only
+operation.
+
+The sealed image and deny-all settings are read-only mounts inside a private
+HOME owned by the existing PID/mount namespace. A private symlink references the
+subscription credential; no credential payload is copied, logged or restored.
+Heartbeat credential lookup uses the supplied scrubbed HOME, recording a process
+HOME fallback truthfully if HOME is absent. Legitimate refresh writes survive.
+The real qualification driver requires an explicit HOME and checks target
+presence before and after, without reading its contents.
+
+The broker transports same-session acknowledged input over stdin, with no tree
+attachment, `--add-dir`, permission bypass, retry or native thinking timer. Empty,
+rejected and nonzero-exit streams remain non-votes with fixed diagnostics;
+provider stdout/stderr and arbitrary exception strings are not substituted for
+review prose. Native timeout under zero has a distinct diagnostic. Bounded
+retry timing and supported positive deadline argv remain unchanged; accepted
+Gemini review prose excludes stderr.
+
+Namespace init identity is held before execution is released. Cancellation
+reaps before closing a blocked execution gate; abrupt owner death can release
+its EOF gate shortly before the parent-death signal takes effect. There is no
+strict zero-exec claim for abrupt loss. Cleanup requires namespace-init exit
+and corroborating observations, including detached/nested descendants. Failed
+quiescence cannot yield a usable vote. No receipt proves remote billing settlement.
+
+`phase-loop-runtime/scripts/qualify_gemini_heartbeat.py` separately qualifies
+completion, cancellation after observed progress, and abrupt owner loss. Its
+receipts bind package source, image/help/profile/helper hashes, inputs, argv,
+monitoring, broker records and local cleanup observations. Helper evidence is
+sampled, not a complete exec audit; the entry image pin does not freeze helper
+images. Directory validation accounts for every attempt in the declared series
+root, rejecting failures, omissions and terminal/admission mismatches. Preserve
+failed series; diagnose a changed candidate before another attempt. Validation
+uses that host's measured helper images. These receipts do not replace the
+historical bounded-success evidence verifier.