phase-loop-runtime 0.7.16__tar.gz → 0.7.18__tar.gz

{phase_loop_runtime-0.7.16 → phase_loop_runtime-0.7.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.16
+Version: 0.7.18
 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.16      # …or pin an exact version
+pip install phase-loop-runtime==0.7.18      # …or pin an exact version
 ```
 
 To pin a specific tag from source instead, substitute a tag from

{phase_loop_runtime-0.7.16 → phase_loop_runtime-0.7.18}/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.16      # …or pin an exact version
+pip install phase-loop-runtime==0.7.18      # …or pin an exact version
 ```
 
 To pin a specific tag from source instead, substitute a tag from

{phase_loop_runtime-0.7.16 → phase_loop_runtime-0.7.18}/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.16"
+version = "0.7.18"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -154,6 +154,7 @@ phase_loop_runtime = [
 [tool.pytest.ini_options]
 markers = [
     "dotfiles_integration: test requires a dotfiles fleet tree (skipped standalone)",
+    "quarantine(reason): known flake tracked by an OPEN issue; deselected on pull-request CI only (agent-harness#1029)",
 ]
 
 [tool.setuptools.data-files]

{phase_loop_runtime-0.7.16 → phase_loop_runtime-0.7.18}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.16"
+__version__ = "0.7.18"

{phase_loop_runtime-0.7.16 → phase_loop_runtime-0.7.18}/src/phase_loop_runtime/_contract_docs/phase-loop/protocol.md

@@ -2659,6 +2659,73 @@ Fields:
 A synthetic `_train_review_` record (`node_id="_train_review_"`) is appended
 when the train-level review panel approves. Its `status` is `"approved"`.
 
+An approval with usable-reviewer evidence may also carry the optional
+`review_packet_sha256` field, omitted on historical and non-review records.
+Reuse requires its exact immutable packet bytes and the current usable-reviewer
+floor; a legacy approval without the digest cannot authorize pending merges.
+
+The version-1 train review packet binds train order/edges, full admitted heads,
+PR identities, live base tips, unique merge bases, tree IDs, changed-path/mode/blob
+inventory, full substantive patches, acceptance and head-bound evidence.
+`--review-material FILE` declares supporting material for every exact node ID;
+local command/disposal evidence is labelled operator-supplied attestation.
+GitHub check runs are fetched by identity and checked against the admitted head.
+Optional explicit whole-subtree disposal certificates bind full inventories and
+unabridged diff hashes; they certify deletion mechanics, not generatedness.
+Operator-only removal sidecars never enter reviewer scratch.
+
+`run-train --governed --review-only --review-material FILE --preview-review DIR`
+prepares identical review material before broker construction, leases, recovery,
+admission or models. A ready receipt is not approval. The rendered prompt,
+including framing and instructions, must fit 512 KiB; the separate 1 MiB packet
+parser limit does not establish readiness. There is no truncation fallback.
+
+`run-train --governed --monitoring-policy heartbeat_only` runs the train-level review
+under review monitoring policy v1 heartbeat-only: the frozen four-vendor default board
+(any other composition is refused), no model deadline, no native host seat. The policy
+is bound into the review authorization and passed to the invoker, which refuses a
+mismatch. Native emission/fill, a non-governed run or an unqualified Gemini route is
+refused before ledger, broker, publish or packet effects (CLI and direct callers), and
+re-checked before any seat launches. The bounded review path is unchanged.
+
+Trusted-opt-in FAB readmission during ordinary governed merging first freezes
+the entire prospective packet against proposed-head evidence without granting
+authority. Existing broker readmission and fresh complete durable bindings must
+then match before those identical bytes enter review/cache/native sinks. Current
+readmission eligibility is checked immediately before recovery. While FAB promotion
+is active, real repository revocation is replayed before recovery, sinks, approval
+and each merge. Review-only/native emission perform no recovery/readmission; preview
+does not consult broker evidence. No late head advancement follows train review.
+Transport readiness does not attest actual provider consumption of all content.
+
+Production stores read-back packets under `review-packets/<sha256>/` beside the
+ledger. Missing/corrupt packet storage holds. Explicit fresh material invalidates
+changed approvals; omitted material retains stored snapshots without asserting
+checks were refreshed. Native fills retain artifact/brief/composition validation.
+Partial resumes keep original merged-node sections only after validating their
+complete admission bindings (node, branch, PR, head and FAB run) and live merge
+outcomes; unavailable history holds rather than
+reconstructing scope from current main. Observed pending base/head drift before
+approval and each merge requires a fresh packet. GitHub's existing head pin
+remains independent; these reads do not atomically pin the base.
+
+Direct patch text preserves LF/TAB and reversibly escapes backslashes, CR and
+disallowed Unicode. JSON sections decode as outer escapes, JSON, then nested
+`content.text` escapes, including four-digit `\u` and supplementary eight-digit
+`\U` escapes (the latter are not standard JSON escapes).
+`raw_sha256` hashes original bytes; `escaped_sha256`
+hashes intermediate escaped text; preview `presentation_sha256` hashes the
+final rendered section. Readback integrity is not a power-loss durability
+guarantee; that recovery work is tracked in agent-harness#977.
+Packet identity, material and revocation checkpoints, including finalization,
+storage and checks immediately before review and approval, use `review_halted`
+before recovery/readmission begins and `merge_halted` afterward. The per-node
+recovery/readmission handler alone appends a blocked row, and only after that
+node's helper began; later packet holds retain the latest durable binding.
+Panel rejections and native-fill refusals remain `review_halted`; merge-loop
+refusals remain `merge_halted`. All retain the typed reason and prior merges. Malformed
+stored metadata and excessive JSON nesting yield a typed hold and preview receipt.
+
 Idempotent resume: re-running `run_train` reads the ledger to skip nodes that
 are already `pr_open` (confirmed via a live `_pr_is_open` check) or already
 `merged`. A `blocked` node in the ledger is retried on resume.

{phase_loop_runtime-0.7.16 → phase_loop_runtime-0.7.18}/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`
@@ -486,13 +494,139 @@ a landing decision. `tests/test_president_wiring.py`.
   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 only brokered subscription/homebrew Claude TUI, Codex,
-and Grok, with no timeout overrides, capture, research, API fallback, gateway,
-or native host seat. Whole-board capability preflight precedes availability,
-auth, session creation, and provider dispatch. Gemini/agy remains unsupported.
+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;
@@ -523,3 +657,52 @@ PID ownership is established after network entry but before the capability bound
 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.