phase-loop-runtime 0.7.1__tar.gz → 0.7.2__tar.gz

{phase_loop_runtime-0.7.1 → phase_loop_runtime-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.1
+Version: 0.7.2
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author: ViperJuice
 License-Expression: Apache-2.0

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

{phase_loop_runtime-0.7.1 → phase_loop_runtime-0.7.2}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"

{phase_loop_runtime-0.7.1 → phase_loop_runtime-0.7.2}/src/phase_loop_runtime/cli.py

@@ -1360,6 +1360,19 @@ def _main(parser: argparse.ArgumentParser, args: argparse.Namespace, command: st
     return _run_returncode(snapshot, results)
 
 
+def _native_agent_request_json(leg: object) -> dict | None:
+    """Serialize a leg's ``needs_native_agent`` request (ABDNATIVE / #183) to a
+    JSON-safe dict, or ``None`` when the seat is not deferred to a native Agent.
+
+    Structural (``getattr`` + ``to_dict``) so it does not force a ``panel_invoker``
+    import onto the bare CLI path."""
+    request = getattr(leg, "needs_native_agent", None)
+    if request is None:
+        return None
+    to_dict = getattr(request, "to_dict", None)
+    return to_dict() if callable(to_dict) else None
+
+
 def _advisor_board_command(*, args: argparse.Namespace) -> int:
     """LEGACY (CLEANSHIP P7): run the 4-vendor advisor board as the RUNNABLE
     agent-facing default. Composes availability-aware seats via
@@ -1419,10 +1432,43 @@ def _advisor_board_command(*, args: argparse.Namespace) -> int:
     # expected non-OK), the board is below its independence floor → exit nonzero.
     usable = usable_count >= FLOOR_SEATS
     exit_code = 0 if usable else 1
+    # #183 / ABDNATIVE: LOUD requested-vs-delivered shortfall. A floor-satisfying
+    # board can still be SHORT an explicitly-requested seat (the claude/Fable seat
+    # deferred to a native Agent), and a bare `usable:true` masks that. Report
+    # requested (every composed seat), delivered (usable OK+text), and — the
+    # affordance — the seats a native harness can FILL itself (each carries the
+    # typed `needs_native_agent` request). Exit stays floor-based (unchanged): the
+    # shortfall is a REPORTING signal, not a gate flip.
+    # CR F3: derive unfilled seats PER-LEG (`not leg.usable`), never by seat_key
+    # membership. Seats are collision-aware LABELS (schema permits byte-identical
+    # seats with the SAME key), so a key-set difference would let a duplicate key —
+    # one seat OK, its twin failed — hide the failed twin: requested=2/delivered=1
+    # but zero unfilled reported = a silent drop. Per-leg is positional and exact.
+    requested_seats = len(board.seats)
+    unfilled_legs = [leg for leg in result.legs if not leg.usable]
+    fillable_legs = [leg for leg in unfilled_legs if leg.needs_native_agent is not None]
+    shortfall = {
+        "requested_seats": requested_seats,
+        "delivered_seats": usable_count,
+        "unfilled_seats": [
+            {
+                "seat_key": leg.seat_key,
+                "leg": leg.leg,
+                "status": leg.status,
+                "needs_native_agent": _native_agent_request_json(leg),
+            }
+            for leg in unfilled_legs
+        ],
+        "natively_fillable_seats": len(fillable_legs),
+    }
     if bool(getattr(args, "json", False)):
         payload = {
             "board": board.name,
             "usable": usable,
+            # Requested-vs-delivered so a Bash-invoking harness sees a dropped seat.
+            "requested_seats": requested_seats,
+            "delivered_seats": usable_count,
+            "shortfall": shortfall,
             "independence": {
                 "level": independence.level,
                 "distinct_vendors": independence.distinct_vendors,
@@ -1438,6 +1484,9 @@ def _advisor_board_command(*, args: argparse.Namespace) -> int:
                     "status": leg.status,
                     "detail": leg.detail,
                     "text": leg.text,
+                    # ABDNATIVE (#183): a deferred claude/Fable seat carries the
+                    # typed native-fill request the harness must run; None otherwise.
+                    "needs_native_agent": _native_agent_request_json(leg),
                 }
                 for leg in result.legs
             ],
@@ -1460,6 +1509,18 @@ def _advisor_board_command(*, args: argparse.Namespace) -> int:
     # The statuses/verdicts are ADVISORY evidence — the operator reconciles them; a
     # non-OK leg (DEGRADED/UNAVAILABLE/…) is a gap to fill, not a passed review.
     print("advisor-board: verdicts are advisory — reconcile the legs; check each leg status.")
+    # #183: surface the requested-vs-delivered shortfall LOUDLY (stderr) so a
+    # floor-satisfying board is never mistaken for the full requested board, and
+    # name the seats a native harness can fill itself.
+    if unfilled_legs:
+        print(
+            f"advisor-board: delivered {usable_count}/{requested_seats} requested seats — "
+            f"{len(unfilled_legs)} unfilled ({len(fillable_legs)} natively fillable):",
+            file=sys.stderr,
+        )
+        for leg in unfilled_legs:
+            fill = " → run a native Fable Agent to fill this seat" if leg.needs_native_agent else ""
+            print(f"advisor-board:   [{leg.status}] {leg.seat_key}{fill}", file=sys.stderr)
     if not usable:
         print(
             f"advisor-board: only {usable_count} usable review leg(s) < floor {FLOOR_SEATS} "

phase_loop_runtime-0.7.2/src/phase_loop_runtime/deploy/phase-loop-task-message-broker.service

@@ -0,0 +1,34 @@
+[Unit]
+Description=Phase-loop task-message source broker
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=viperjuice
+Group=viperjuice
+EnvironmentFile=/etc/phase-loop/task-message-broker.env
+ExecStart=/opt/phase-loop-task-message-broker/bin/phase-loop task-message-broker-serve --host 127.0.0.1 --port 18765 --control-socket /home/viperjuice/.codex/app-server-control/app-server-control.sock --authority codex-app-server://claw.taile09692.ts.net --token-sha256 ${TASK_MESSAGE_TOKEN_SHA256} --agent-harness-sha ${AGENT_HARNESS_SHA}
+Restart=on-failure
+RestartSec=2
+UMask=0077
+NoNewPrivileges=yes
+PrivateDevices=yes
+PrivateTmp=yes
+ProtectHome=tmpfs
+BindReadOnlyPaths=/home/viperjuice/.codex/app-server-control/app-server-control.sock
+ProtectSystem=strict
+InaccessiblePaths=/proc
+ProtectControlGroups=yes
+ProtectKernelModules=yes
+ProtectKernelTunables=yes
+LockPersonality=yes
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+RestrictRealtime=yes
+RestrictSUIDSGID=yes
+SystemCallArchitectures=native
+IPAddressDeny=any
+IPAddressAllow=localhost
+
+[Install]
+WantedBy=multi-user.target

{phase_loop_runtime-0.7.1 → phase_loop_runtime-0.7.2}/src/phase_loop_runtime/panel_invoker.py

@@ -196,6 +196,15 @@ class PanelLegResult:
     # default 3-leg board stay byte-for-byte identical (one seat per vendor ==
     # seat_key == leg). ABDHOME wires the per-seat spawn; this freezes the identity.
     seat_key: str | None = None
+    # ABDNATIVE (#183 companion, Bug 2): the typed native-fill request is exposed by
+    # the ``needs_native_agent`` PROPERTY below and stored in the non-field
+    # ``_needs_native_agent`` attribute (attached via ``attach_native_agent_request``
+    # / ``object.__setattr__``). It is DELIBERATELY NOT a dataclass field (CR F2):
+    # ``dataclasses.asdict`` and any field-walking serializer (golden,
+    # AdvisorBoardEvent) enumerate ``fields()`` only, so the affordance is
+    # structurally UNABLE to leak into the (status, text) golden surface. The
+    # property reads a default of ``None`` so a plain leg (none attached) is never
+    # an AttributeError.
 
     def __post_init__(self) -> None:
         object.__setattr__(self, "status", normalize_leg_status(self.status))
@@ -206,6 +215,21 @@ class PanelLegResult:
     def usable(self) -> bool:
         return self.status == "OK" and bool(self.text.strip())
 
+    @property
+    def needs_native_agent(self) -> "NativeAgentLegRequest | None":
+        return getattr(self, "_needs_native_agent", None)
+
+
+def attach_native_agent_request(
+    leg: PanelLegResult, request: "NativeAgentLegRequest"
+) -> PanelLegResult:
+    """Attach a native-fill request to a (frozen) ``PanelLegResult`` post-creation
+    (CR F2): stored in the NON-field ``_needs_native_agent`` so ``asdict``/golden
+    serializers never see it; read back via the ``needs_native_agent`` property.
+    Returns ``leg`` for call-site convenience."""
+    object.__setattr__(leg, "_needs_native_agent", request)
+    return leg
+
 
 @dataclass(frozen=True)
 class PanelResult:
@@ -215,6 +239,16 @@ class PanelResult:
     def usable_legs(self) -> tuple[PanelLegResult, ...]:
         return tuple(leg for leg in self.legs if leg.usable)
 
+    @property
+    def native_fill_requests(self) -> tuple["NativeAgentLegRequest", ...]:
+        """ABDNATIVE (#183 companion): the deferred seats a driving host can fill
+        natively (each carries seat_key/model/effort/lens + the review contract).
+        A non-empty result means the board is SHORT those seats until they are
+        filled — the loud requested-vs-delivered signal the caller must not miss."""
+        return tuple(
+            leg.needs_native_agent for leg in self.legs if leg.needs_native_agent is not None
+        )
+
 
 def available_panel_legs(probe: Callable[[str], bool] | None = None) -> tuple[str, ...]:
     """Metadata-only liveness preflight: which panel legs have their CLI present.
@@ -1400,12 +1434,18 @@ def _normalize_claude_agent_state(value: object) -> str:
 #   under_claude_code       — we are INSIDE a Claude Code session; the driving
 #                             session supplies the leg as its own NATIVE Agent
 #                             (Task tool). Spawning a second Claude TUI here is
-#                             the wrong route.
-#   native_adapter_required — a headless / no-tty host (e.g. the Codex Desktop
-#                             tool shell: CLAUDECODE unset, stdin/stdout not a
-#                             tty) with no controlling terminal to drive a TUI.
-#                             The host fulfills the leg through its own native
-#                             sub-agent adapter (see native_agent_leg_request()).
+#                             the wrong route. This is the RUNTIME-EMITTED defer
+#                             code (the only case `_exec_claude_tui_leg` defers).
+#   native_adapter_required — an AFFORDANCE/fallback for a host that fulfills the
+#                             leg via its OWN sub-agent adapter instead of the
+#                             runtime's self-PTY TUI (see native_agent_leg_request()).
+#                             #183: the runtime NO LONGER defers a headless / no-tty
+#                             NON-Claude host by default — `_run_claude_tui_session`
+#                             self-allocates its own PTY, so the leg RUNS there. This
+#                             code is produced only by a standalone
+#                             `native_agent_leg_request(env=<non-Claude>)` call, for
+#                             a host that cannot drive the TUI or prefers its own
+#                             agent (e.g. the Codex Desktop tool shell).
 _CLAUDE_LEG_DEFERRED_UNDER_CLAUDE_CODE = "under_claude_code"
 _CLAUDE_LEG_DEFERRED_NATIVE_ADAPTER = "native_adapter_required"
 
@@ -1416,10 +1456,10 @@ _CLAUDE_LEG_DEFERRED_REASONS: dict[str, str] = {
         "runtime must not spawn a second Claude TUI here."
     ),
     _CLAUDE_LEG_DEFERRED_NATIVE_ADAPTER: (
-        "claude leg not run by the runtime in this headless / no-tty host (no "
-        "controlling terminal to drive a Claude TUI); the driving host (e.g. "
-        "Codex Desktop) must fulfill it via its native sub-agent adapter — see "
-        "native_agent_leg_request()."
+        "claude leg available as an AFFORDANCE for this headless / no-tty host: "
+        "#183 the runtime runs the self-PTY TUI here by default, but a host that "
+        "cannot drive a TUI (or prefers its own agent) may fulfill the leg via its "
+        "native sub-agent adapter — see native_agent_leg_request()."
     ),
 }
 
@@ -1465,6 +1505,17 @@ class NativeAgentLegRequest:
     caller's inputs (:func:`native_agent_leg_request`) and is NEVER threaded
     through the governed ``(status, text)`` spawn boundary — keeping the panel /
     advisor-board golden byte-identical (#92 A4).
+
+    ABDNATIVE (#183 companion, Bug 2): when the board attaches this to a deferred
+    leg in the ``PanelResult`` (``PanelLegResult.needs_native_agent``), it carries
+    the SEAT cognition the driver must reproduce — ``seat_key`` / ``effort`` /
+    ``lens`` (the model is already here) — plus the ``artifact_ref`` the board was
+    given and the effective ``brief_ref`` (so the native fill reviews under the SAME
+    acceptance brief as the runtime legs — the ``instructions`` field already carries
+    the resolved brief text). These are optional (``None``) so the pure standalone
+    builder and its existing callers are byte-unchanged; ``to_dict`` OMITS every
+    ``None`` optional key, so a bare #125 builder call serializes to exactly the
+    original 8-key shape (byte-compat).
     """
 
     leg: str
@@ -1475,10 +1526,25 @@ class NativeAgentLegRequest:
     instructions: str
     verdict_required: bool
     verdict_contract: str
+    # ABDNATIVE seat cognition (set when surfaced on a board result; None for the
+    # pure standalone builder call). ``seat_key``/``effort``/``lens`` tell the
+    # driver exactly which cognition to reproduce; ``artifact_ref`` names the
+    # material the board reviewed; ``brief_ref`` names the effective review brief
+    # (the driver usually already holds artifact + brief).
+    seat_key: str | None = None
+    effort: str | None = None
+    lens: str | None = None
+    artifact_ref: str | None = None
+    brief_ref: str | None = None
 
     def to_dict(self) -> dict[str, object]:
-        """JSON-serializable form for a host driver to consume across a tool boundary."""
-        return {
+        """JSON-serializable form for a host driver to consume across a tool boundary.
+
+        Byte-compat (CR F1): the eight base keys are always present; each ADDITIVE
+        optional key is emitted ONLY when set, so a bare ``native_agent_leg_request``
+        call (all optionals ``None``) serializes to the exact original 8-key shape
+        that #125's callers depend on."""
+        out: dict[str, object] = {
             "leg": self.leg,
             "model": self.model,
             "mode": self.mode,
@@ -1488,6 +1554,11 @@ class NativeAgentLegRequest:
             "verdict_required": self.verdict_required,
             "verdict_contract": self.verdict_contract,
         }
+        for key in ("seat_key", "effort", "lens", "artifact_ref", "brief_ref"):
+            value = getattr(self, key)
+            if value is not None:
+                out[key] = value
+        return out
 
 
 # The terminal-verdict contract a native-fulfilled review leg must satisfy so its
@@ -1510,6 +1581,12 @@ def native_agent_leg_request(
     mode: str = "review",
     env: Mapping[str, str] | None = None,
     model: str | None = None,
+    seat_key: str | None = None,
+    effort: str | None = None,
+    lens: str | None = None,
+    artifact_ref: str | None = None,
+    brief_ref: str | None = None,
+    instructions: str | None = None,
 ) -> NativeAgentLegRequest:
     """Build the structured request a host driver fulfills for a deferred leg (#125).
 
@@ -1518,6 +1595,15 @@ def native_agent_leg_request(
     ``UNAVAILABLE`` for this leg). ``mode`` selects the review vs advisory brief +
     verdict contract; ``env`` selects the deferred-reason code (under Claude Code
     vs native-adapter-required); ``model`` defaults to the seat's canonical model.
+
+    ABDNATIVE (#183 companion): the board passes the deferred seat's cognition
+    (``seat_key`` / ``effort`` / ``lens``), the reviewed ``artifact_ref``, and the
+    effective ``brief_ref`` so the surfaced request fully specifies the native fill.
+    ``instructions`` (CR F5) OVERRIDES the default ``_mode_instructions(mode)`` with
+    the RESOLVED effective brief — so a board invoked with a custom ``brief_ref``
+    hands the native seat the SAME acceptance brief as the runtime legs, not the
+    default. All default ``None`` — the bare standalone call is byte-unchanged
+    (#125 callers/tests unaffected).
     """
     reason, detail = _claude_leg_deferred_reason(env)
     verdict_required = mode != "advisory"
@@ -1527,11 +1613,16 @@ def native_agent_leg_request(
         mode=mode,
         reason=reason,
         detail=detail,
-        instructions=_mode_instructions(mode),
+        instructions=instructions if instructions is not None else _mode_instructions(mode),
         verdict_required=verdict_required,
         verdict_contract=(
             _REVIEW_VERDICT_CONTRACT if verdict_required else _ADVISORY_VERDICT_CONTRACT
         ),
+        seat_key=seat_key,
+        effort=effort,
+        lens=lens,
+        artifact_ref=artifact_ref,
+        brief_ref=brief_ref,
     )
 
 
@@ -1547,8 +1638,12 @@ def _tui_capable(
     env: Mapping[str, str] | None = None,
     isatty: Callable[[], bool] | None = None,
 ) -> bool:
-    """The TUI leg needs a real controlling terminal. False under Claude Code OR
-    when stdin/stdout is not a tty (headless/detached)."""
+    """True iff the PARENT has a usable controlling terminal AND we are not under
+    Claude Code. Retained as a capability predicate, but as of #183 it is NO LONGER
+    the gate for running the claude TUI leg: ``_exec_claude_tui_leg`` gates on
+    ``_under_claude_code`` alone, because ``_run_claude_tui_session`` self-allocates
+    its own PTY and never needs the parent's tty. Kept for callers/tests that
+    genuinely want to know whether the parent is terminal-attached."""
     if _under_claude_code(env):
         return False
     check = isatty if isatty is not None else (lambda: sys.stdin.isatty() and sys.stdout.isatty())
@@ -1584,28 +1679,43 @@ def _exec_claude_tui_leg(
     ``resolve_seat_env`` result so per-seat effort + active env scrubbing reach the
     real launch.
     """
-    supported, support_detail = _claude_code_support_status()
-    if not supported:
-        return "UNAVAILABLE", support_detail
-
-    if not _tui_capable(env):
-        # Under Claude Code / no controlling terminal: do NOT spawn a Claude TUI
-        # we cannot drive (issue #92). Degrade cleanly with the existing
-        # UNAVAILABLE status and EMPTY review text — the empty text is
-        # load-bearing (A4): an UNAVAILABLE leg with empty text becomes a
-        # non-gating `panel_leg_degraded` warn, never a block, and `usable`
-        # (status=="OK") never counts it as an AGREE. The driving session/host
-        # must supply this leg natively (Claude Code: a Task Agent; Codex Desktop
-        # / headless: its native sub-agent adapter — see native_agent_leg_request).
-        # #125: log the machine-branchable reason code so the distinction between
-        # "under Claude Code" and "native-adapter-required" is visible in the audit
-        # line, not just blended into one sentence.
+    # CR F4: the under-Claude-Code deferral MUST come BEFORE the local-CLI support
+    # check. Inside Claude Code the driving session fulfills the leg as its own
+    # native Task Agent (its authed session), which does NOT depend on a standalone
+    # `claude` CLI being installed/current on the host. Checking support first would
+    # return `UNAVAILABLE` + a NON-empty support detail on a Claude-Code host that
+    # lacks the local CLI — and `_run_seat`'s deferral signature is UNAVAILABLE +
+    # EMPTY text, so the native-fill request would never be attached: a silent drop.
+    # Defer first (empty text, native request emitted), THEN check local support for
+    # the run path.
+    if _under_claude_code(env):
+        # #92: INSIDE Claude Code, do NOT spawn a SECOND Claude TUI we cannot
+        # drive. Degrade cleanly with the existing UNAVAILABLE status and EMPTY
+        # review text — the empty text is load-bearing (A4): an UNAVAILABLE leg
+        # with empty text becomes a non-gating `panel_leg_degraded` warn, never a
+        # block, and `usable` (status=="OK") never counts it as an AGREE. The
+        # driving Claude Code session supplies this leg natively (a Task Agent) —
+        # see the `needs_native_agent` request the board attaches at the
+        # invoke_board layer (ABDNATIVE / #183).
+        #
+        # #183 (owner-confirmed reconciliation): a merely non-TTY parent is NOT a
+        # defer reason. `_run_claude_tui_session` SELF-ALLOCATES its own PTY
+        # (pty.openpty), so a headless NON-Claude caller (e.g. Codex Desktop) with
+        # valid Claude Max OAuth runs the leg RIGHT HERE — the old `_tui_capable`
+        # parent-tty gate over-blocked that case. `native_adapter_required` is now
+        # an AFFORDANCE/fallback (via native_agent_leg_request()) for a host that
+        # cannot drive the TUI or prefers its own sub-agent, NOT the default that
+        # silently dropped the seat.
         reason_code, reason_detail = _claude_leg_deferred_reason(env)
         logging.getLogger(__name__).warning(
             "advisor-panel claude leg deferred [%s]: %s", reason_code, reason_detail
         )
         return "UNAVAILABLE", ""
 
+    supported, support_detail = _claude_code_support_status()
+    if not supported:
+        return "UNAVAILABLE", support_detail
+
     env = _subscription_env() if env is None else dict(env)
     output_file = out_dir / "panel-claude.txt"
     prompt = _render_claude_tui_prompt(artifact, review_dir, output_file, mode)
@@ -2701,7 +2811,40 @@ def invoke_board(
             status = "DEGRADED"
         if status == "OK" and not str(text).strip():
             status = "EMPTY"
-        return PanelLegResult(leg=leg, status=status, text=str(text), seat_key=seat.seat_key)
+        # ABDNATIVE (#183 companion, Bug 2): when the claude/Fable seat DEFERS (the
+        # runtime cannot drive the leg here: #92 under Claude Code, or a headless
+        # host), surface a typed native-fill request ON THE RESULT so a driving
+        # harness sees "YOUR seat to fill" — not a log line + a bare UNAVAILABLE.
+        # The deferral signature is UNAVAILABLE with EMPTY text (the #92 A4
+        # invariant); the support-missing UNAVAILABLE carries a non-empty detail and
+        # is a genuine "no claude here", not a fillable seat. Reuse the shipped #125
+        # builder; pass the seat cognition + reviewed artifact + the EFFECTIVE brief
+        # (CR F5: the native seat must review under the SAME acceptance contract as
+        # the runtime legs — `_resolve_brief` gives the exact `review-instructions.md`
+        # the other seats got). None for every other leg (golden byte-identity holds).
+        result = PanelLegResult(leg=leg, status=status, text=str(text), seat_key=seat.seat_key)
+        if leg == "claude" and status == "UNAVAILABLE" and not str(text).strip():
+            try:
+                effective_instructions = _resolve_brief(mode, brief_ref)
+            except (ValueError, OSError):
+                # brief_ref was already validated on the run path that reached the
+                # defer; fall back to the mode brief rather than crash the seat.
+                effective_instructions = _mode_instructions(mode)
+            request = native_agent_leg_request(
+                leg=leg,
+                mode=mode,
+                env=env_source,
+                model=seat.model,
+                seat_key=seat.seat_key,
+                effort=seat.effort,
+                lens=seat.lens,
+                artifact_ref=str(artifact_ref) if isinstance(artifact_ref, str) else None,
+                brief_ref=str(brief_ref) if isinstance(brief_ref, str) else None,
+                instructions=effective_instructions,
+            )
+            # CR F2: attach post-creation (non-field) so asdict/golden can't see it.
+            attach_native_agent_request(result, request)
+        return result
 
     # Fan the seats out concurrently (parallel by default; max_concurrency=1 →
     # sequential); results come back in SEAT ORDER (positional re-key + golden

{phase_loop_runtime-0.7.1 → phase_loop_runtime-0.7.2}/src/phase_loop_runtime/skills_bundle/claude-advisor-board/SKILL.md

@@ -39,7 +39,9 @@ Legs fan out concurrently, so panel wall-clock ≈ max(leg), not sum. Each leg's
 
 ## Use
 
-**On a Harness Code host, run the claude/Fable leg as a NATIVE Agent, not the runtime TUI.** When you are *inside* Harness Code, the runtime runs the non-<harness> board legs (`grok`, `codex`, `gemini` — whichever are available AND authenticated) and returns the `claude` leg as `UNAVAILABLE` ("deferred to native Agent") by design — it must not spawn a second Harness TUI. Supply the <harness> leg yourself with the Task tool (a Fable/Harness Agent given the same `review-instructions.md` + `review-bundle.md`), require it to end with `AGREE`/`PARTIALLY AGREE`/`DISAGREE`, and reconcile it with ALL the runtime legs (do NOT drop `grok` — the board is 4-vendor, not the old 3-leg panel). A `UNAVAILABLE` <harness> leg is a *gap to fill*, not an acceptable board short a seat.
+**On a Harness Code host, run the claude/Fable leg as a NATIVE Agent, not the runtime TUI.** When you are *inside* Harness Code, the runtime runs the non-<harness> board legs (`grok`, `codex`, `gemini` — whichever are available AND authenticated) and returns the `claude` leg as `UNAVAILABLE` ("deferred to native Agent") by design — it must not spawn a second Harness TUI. Supply the <harness> leg yourself with the Task tool (a Fable review Agent given the same `review-instructions.md` + `review-bundle.md`), require it to end with `AGREE`/`PARTIALLY AGREE`/`DISAGREE`, and reconcile it with ALL the runtime legs (do NOT drop `grok` — the board is 4-vendor, not the old 3-leg panel). A `UNAVAILABLE` <harness> leg is a *gap to fill*, not an acceptable board short a seat.
+
+**Fill the deferred seat from the typed request — do not silently run a degraded board.** A deferred seat now carries a machine-readable `needs_native_agent` request on the RESULT (`result.legs[i].needs_native_agent`, also `result.native_fill_requests`, and per-leg + under `shortfall` in `advisor-board --json`). It packages `{seat_key, model, effort, lens, reason, instructions, verdict_contract, artifact_ref}` — everything you need to fill the seat, so filling is the obvious next step, not prose to decode. When a seat has `needs_native_agent`, the DEFAULT action is: run a native Fable review Agent with the Task tool (`model: fable`, at the request's `lens` and `effort`), give it the staged `review-instructions.md` + `review-bundle.md` (the `artifact_ref` names the material), require the `verdict_contract` terminal verdict, and reconcile that verdict with the runtime legs in your own context. The runtime does NOT merge the native verdict back for you — the result marks the gap; you fill it. Under-running the board (accepting the shortfall) is allowed only as an EXPLICIT, provenance-tagged choice — record which requested seats you left unfilled and why — never a silent 3-of-4. The requested-vs-delivered shortfall (`requested_seats` / `delivered_seats` / `natively_fillable_seats`) is the loud signal that you are short a seat.
 
 1. Prefer the repo's governed phase-loop path when reviewing phase execution or pre-merge work.
 2. For a standalone smoke or diagnostic, run `phase-loop advisor-board <artifact>` (or, in-process, compose with `compose_review_board` and pass the material's path via `artifact_ref` to `phase_loop_runtime.panel_invoker.invoke_board`).
@@ -59,6 +61,9 @@ board = compose_review_board()
 result = invoke_board(board, "", artifact_ref="path/to/bundle.md")
 for leg in result.legs:
     print(leg.seat_key, leg.status)
+    if leg.needs_native_agent:  # deferred seat → fill with a native Fable Task Agent
+        req = leg.needs_native_agent
+        print("  fill natively:", req.model, req.effort, req.lens, req.reason)
 ```
 
-Under Harness Code, expect the `claude` leg to report `UNAVAILABLE` (deferred to the native Agent) — the runtime does not spawn a Harness TUI here. Supply the <harness> leg natively (Task tool) and reconcile it with ALL the runtime legs (`grok` + `codex` + `gemini`, whichever are up and authed) — the board is 4-vendor, so do not drop `grok`.
+Under Harness Code, expect the `claude` leg to report `UNAVAILABLE` (deferred to the native Agent) and carry a `needs_native_agent` request — the runtime does not spawn a Harness TUI here. Fill the seat with a native Fable Task Agent (`model: fable`, at `req.lens` / `req.effort`), then reconcile its verdict with ALL the runtime legs (`grok` + `codex` + `gemini`, whichever are up and authed) — the board is 4-vendor, so do not drop `grok`. Leaving the seat unfilled is an explicit, provenance-tagged choice, never a silent short-a-seat board.

{phase_loop_runtime-0.7.1 → phase_loop_runtime-0.7.2}/src/phase_loop_runtime/skills_bundle/claude-advisor-panel/SKILL.md

@@ -39,7 +39,9 @@ Legs fan out concurrently, so panel wall-clock ≈ max(leg), not sum. Each leg's
 
 ## Use
 
-**On a Harness Code host, run the claude/Fable leg as a NATIVE Agent, not the runtime TUI.** When you are *inside* Harness Code, the runtime runs the non-<harness> board legs (`grok`, `codex`, `gemini` — whichever are available AND authenticated) and returns the `claude` leg as `UNAVAILABLE` ("deferred to native Agent") by design — it must not spawn a second Harness TUI. Supply the <harness> leg yourself with the Task tool (a Fable/Harness Agent given the same `review-instructions.md` + `review-bundle.md`), require it to end with `AGREE`/`PARTIALLY AGREE`/`DISAGREE`, and reconcile it with ALL the runtime legs (do NOT drop `grok` — the board is 4-vendor, not the old 3-leg panel). A `UNAVAILABLE` <harness> leg is a *gap to fill*, not an acceptable board short a seat.
+**On a Harness Code host, run the claude/Fable leg as a NATIVE Agent, not the runtime TUI.** When you are *inside* Harness Code, the runtime runs the non-<harness> board legs (`grok`, `codex`, `gemini` — whichever are available AND authenticated) and returns the `claude` leg as `UNAVAILABLE` ("deferred to native Agent") by design — it must not spawn a second Harness TUI. Supply the <harness> leg yourself with the Task tool (a Fable review Agent given the same `review-instructions.md` + `review-bundle.md`), require it to end with `AGREE`/`PARTIALLY AGREE`/`DISAGREE`, and reconcile it with ALL the runtime legs (do NOT drop `grok` — the board is 4-vendor, not the old 3-leg panel). A `UNAVAILABLE` <harness> leg is a *gap to fill*, not an acceptable board short a seat.
+
+**Fill the deferred seat from the typed request — do not silently run a degraded board.** A deferred seat now carries a machine-readable `needs_native_agent` request on the RESULT (`result.legs[i].needs_native_agent`, also `result.native_fill_requests`, and per-leg + under `shortfall` in `advisor-board --json`). It packages `{seat_key, model, effort, lens, reason, instructions, verdict_contract, artifact_ref}` — everything you need to fill the seat, so filling is the obvious next step, not prose to decode. When a seat has `needs_native_agent`, the DEFAULT action is: run a native Fable review Agent with the Task tool (`model: fable`, at the request's `lens` and `effort`), give it the staged `review-instructions.md` + `review-bundle.md` (the `artifact_ref` names the material), require the `verdict_contract` terminal verdict, and reconcile that verdict with the runtime legs in your own context. The runtime does NOT merge the native verdict back for you — the result marks the gap; you fill it. Under-running the board (accepting the shortfall) is allowed only as an EXPLICIT, provenance-tagged choice — record which requested seats you left unfilled and why — never a silent 3-of-4. The requested-vs-delivered shortfall (`requested_seats` / `delivered_seats` / `natively_fillable_seats`) is the loud signal that you are short a seat.
 
 1. Prefer the repo's governed phase-loop path when reviewing phase execution or pre-merge work.
 2. For a standalone smoke or diagnostic, run `phase-loop advisor-board <artifact>` (or, in-process, compose with `compose_review_board` and pass the material's path via `artifact_ref` to `phase_loop_runtime.panel_invoker.invoke_board`).
@@ -59,6 +61,9 @@ board = compose_review_board()
 result = invoke_board(board, "", artifact_ref="path/to/bundle.md")
 for leg in result.legs:
     print(leg.seat_key, leg.status)
+    if leg.needs_native_agent:  # deferred seat → fill with a native Fable Task Agent
+        req = leg.needs_native_agent
+        print("  fill natively:", req.model, req.effort, req.lens, req.reason)
 ```
 
-Under Harness Code, expect the `claude` leg to report `UNAVAILABLE` (deferred to the native Agent) — the runtime does not spawn a Harness TUI here. Supply the <harness> leg natively (Task tool) and reconcile it with ALL the runtime legs (`grok` + `codex` + `gemini`, whichever are up and authed) — the board is 4-vendor, so do not drop `grok`.
+Under Harness Code, expect the `claude` leg to report `UNAVAILABLE` (deferred to the native Agent) and carry a `needs_native_agent` request — the runtime does not spawn a Harness TUI here. Fill the seat with a native Fable Task Agent (`model: fable`, at `req.lens` / `req.effort`), then reconcile its verdict with ALL the runtime legs (`grok` + `codex` + `gemini`, whichever are up and authed) — the board is 4-vendor, so do not drop `grok`. Leaving the seat unfilled is an explicit, provenance-tagged choice, never a silent short-a-seat board.

{phase_loop_runtime-0.7.1 → phase_loop_runtime-0.7.2}/src/phase_loop_runtime/skills_bundle/codex-advisor-board/SKILL.md

@@ -44,22 +44,23 @@ Legs fan out concurrently, so panel wall-clock ≈ max(leg), not sum. Each leg's
 3. Require every leg to end with `AGREE`, `PARTIALLY AGREE`, or `DISAGREE`.
 4. Treat `EMPTY`, `TIMEOUT`, `ERROR`, `DEGRADED`, and `UNAVAILABLE` as structured evidence, not successful reviews.
 5. Keep provider API keys out of the environment; the runtime strips known API-key variables and uses local subscription CLIs.
-6. The runtime never spawns a Claude TUI it cannot drive, so on a deferred host the `claude` leg returns `UNAVAILABLE` with empty text — the driving host supplies that leg through its OWN native sub-agent, not the runtime. See "Fulfilling the deferred claude leg natively" below.
+6. On a Claude Code host the runtime DEFERS the `claude` leg (`UNAVAILABLE`, empty text) so you supply it as a native `Task` Agent (#92); on a headless NON-Claude host (e.g. Harness Desktop) the runtime now RUNS the leg itself through a self-allocated PTY (#183), so it is NOT deferred there. See "Fulfilling the deferred claude leg natively" below for the Claude-Code defer and the native-adapter fallback.
 
-## Fulfilling The Deferred Claude Leg Natively (#125)
+## Fulfilling The Deferred Claude Leg Natively (#125 / #183)
 
-When there is no controlling terminal to drive a Claude TUI, the runtime defers the `claude` leg (`status="UNAVAILABLE"`, empty text — never counted as an AGREE, recorded as a non-gating `panel_leg_degraded` warn). There are TWO deferral cases, and the runtime now distinguishes them with a machine-branchable reason code:
+The runtime defers the `claude` leg (`status="UNAVAILABLE"`, empty text — never counted as an AGREE, recorded as a non-gating `panel_leg_degraded` warn) ONLY when it cannot drive a Claude TUI here. Two machine-branchable reason codes:
 
-- `under_claude_code` — you are running INSIDE a Claude Code session (`CLAUDECODE=1`). The driving Claude Code session supplies the leg as its own native `Task` Agent.
-- `native_adapter_required` — a headless / no-tty host such as the **Harness Desktop** tool shell (`CLAUDECODE` unset, stdin/stdout not a tty). The Harness host fulfills the leg through its native sub-agent adapter (`multi_agent_v1.spawn_agent`).
+- `under_claude_code` — you are running INSIDE a Claude Code session (`CLAUDECODE=1`). The driving Claude Code session supplies the leg as its own native `Task` Agent. This is the case the RUNTIME actually defers.
+- `native_adapter_required` — an AFFORDANCE / fallback (#183). On a headless / no-tty host such as the **Harness Desktop** tool shell (`CLAUDECODE` unset, stdin/stdout not a tty) the runtime now RUNS the self-PTY TUI itself, so the leg is NOT deferred by default. Use this path only when the runtime cannot run the TUI (no Claude support on the host) or you PREFER to fulfill the leg through your own native sub-agent adapter (`multi_agent_v1.spawn_agent`).
 
-Do NOT accept the 2-leg board silently. From Harness Desktop, ask the runtime for the structured request instead of parsing the log line, then fulfill it natively:
+Do NOT accept a short board silently. When the leg IS deferred (under Claude Code), or when you deliberately opt into the native-adapter fallback, ask the runtime for the structured request instead of parsing the log line, then fulfill it natively:
 
 ```python
 from phase_loop_runtime.panel_invoker import native_agent_leg_request
 
 req = native_agent_leg_request(mode="review")   # env defaults to os.environ
-# req.reason == "native_adapter_required" on a Harness/no-tty host
+# req.reason == "native_adapter_required" on a non-Claude host (affordance),
+# "under_claude_code" inside a Claude Code session.
 # spawn a Harness native sub-agent seeded with the SAME review bundle you passed the
 # board, plus req.instructions (the review brief) and req.verdict_contract, on
 # req.model (Fable by default). req.to_dict() is JSON for the tool boundary.

{phase_loop_runtime-0.7.1 → phase_loop_runtime-0.7.2}/src/phase_loop_runtime/skills_bundle/codex-advisor-panel/SKILL.md

@@ -44,22 +44,23 @@ Legs fan out concurrently, so panel wall-clock ≈ max(leg), not sum. Each leg's
 3. Require every leg to end with `AGREE`, `PARTIALLY AGREE`, or `DISAGREE`.
 4. Treat `EMPTY`, `TIMEOUT`, `ERROR`, `DEGRADED`, and `UNAVAILABLE` as structured evidence, not successful reviews.
 5. Keep provider API keys out of the environment; the runtime strips known API-key variables and uses local subscription CLIs.
-6. The runtime never spawns a Claude TUI it cannot drive, so on a deferred host the `claude` leg returns `UNAVAILABLE` with empty text — the driving host supplies that leg through its OWN native sub-agent, not the runtime. See "Fulfilling the deferred claude leg natively" below.
+6. On a Claude Code host the runtime DEFERS the `claude` leg (`UNAVAILABLE`, empty text) so you supply it as a native `Task` Agent (#92); on a headless NON-Claude host (e.g. Harness Desktop) the runtime now RUNS the leg itself through a self-allocated PTY (#183), so it is NOT deferred there. See "Fulfilling the deferred claude leg natively" below for the Claude-Code defer and the native-adapter fallback.
 
-## Fulfilling The Deferred Claude Leg Natively (#125)
+## Fulfilling The Deferred Claude Leg Natively (#125 / #183)
 
-When there is no controlling terminal to drive a Claude TUI, the runtime defers the `claude` leg (`status="UNAVAILABLE"`, empty text — never counted as an AGREE, recorded as a non-gating `panel_leg_degraded` warn). There are TWO deferral cases, and the runtime now distinguishes them with a machine-branchable reason code:
+The runtime defers the `claude` leg (`status="UNAVAILABLE"`, empty text — never counted as an AGREE, recorded as a non-gating `panel_leg_degraded` warn) ONLY when it cannot drive a Claude TUI here. Two machine-branchable reason codes:
 
-- `under_claude_code` — you are running INSIDE a Claude Code session (`CLAUDECODE=1`). The driving Claude Code session supplies the leg as its own native `Task` Agent.
-- `native_adapter_required` — a headless / no-tty host such as the **Harness Desktop** tool shell (`CLAUDECODE` unset, stdin/stdout not a tty). The Harness host fulfills the leg through its native sub-agent adapter (`multi_agent_v1.spawn_agent`).
+- `under_claude_code` — you are running INSIDE a Claude Code session (`CLAUDECODE=1`). The driving Claude Code session supplies the leg as its own native `Task` Agent. This is the case the RUNTIME actually defers.
+- `native_adapter_required` — an AFFORDANCE / fallback (#183). On a headless / no-tty host such as the **Harness Desktop** tool shell (`CLAUDECODE` unset, stdin/stdout not a tty) the runtime now RUNS the self-PTY TUI itself, so the leg is NOT deferred by default. Use this path only when the runtime cannot run the TUI (no Claude support on the host) or you PREFER to fulfill the leg through your own native sub-agent adapter (`multi_agent_v1.spawn_agent`).
 
-Do NOT accept the 2-leg board silently. From Harness Desktop, ask the runtime for the structured request instead of parsing the log line, then fulfill it natively:
+Do NOT accept a short board silently. When the leg IS deferred (under Claude Code), or when you deliberately opt into the native-adapter fallback, ask the runtime for the structured request instead of parsing the log line, then fulfill it natively:
 
 ```python
 from phase_loop_runtime.panel_invoker import native_agent_leg_request
 
 req = native_agent_leg_request(mode="review")   # env defaults to os.environ
-# req.reason == "native_adapter_required" on a Harness/no-tty host
+# req.reason == "native_adapter_required" on a non-Claude host (affordance),
+# "under_claude_code" inside a Claude Code session.
 # spawn a Harness native sub-agent seeded with the SAME review bundle you passed the
 # board, plus req.instructions (the review brief) and req.verdict_contract, on
 # req.model (Fable by default). req.to_dict() is JSON for the tool boundary.

{phase_loop_runtime-0.7.1 → phase_loop_runtime-0.7.2}/src/phase_loop_runtime/task_message_broker_client.py

@@ -16,7 +16,7 @@ from urllib.request import HTTPRedirectHandler, Request, build_opener
 import rfc8785
 
 from .task_message_broker import decode_strict_json
-from .task_message_resolver import APPROVAL_CONTRACT_VERSION, FAILURE_CODES, TaskMessageResolverError
+from .task_message_resolver import APPROVAL_CONTRACT_VERSIONS, FAILURE_CODES, TaskMessageResolverError
 
 
 COMMIT_SHA = re.compile(r"[0-9a-f]{40}")
@@ -256,7 +256,7 @@ class TaskMessageBrokerClient:
             return False
         return (
             isinstance(approval_document, dict)
-            and approval_document.get("contract_version") == APPROVAL_CONTRACT_VERSION
+            and approval_document.get("contract_version") in APPROVAL_CONTRACT_VERSIONS
             and approval_document.get("authorized") is True
             and approval_document.get("source_thread_id") == thread_id
             and approval_document.get("source_message_id") == message_id