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

{phase_loop_runtime-0.7.0 → phase_loop_runtime-0.7.1}/MANIFEST.in

@@ -3,3 +3,4 @@ include protocol/protocol.md
 recursive-include src/phase_loop_runtime *.py py.typed
 recursive-include src/phase_loop_runtime/baml_src *.baml
 recursive-include src/phase_loop_runtime/advisor_board *.toml *.md
+recursive-include src/phase_loop_runtime/deploy *.service

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

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

{phase_loop_runtime-0.7.0 → phase_loop_runtime-0.7.1}/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.0"
+version = "0.7.1"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -111,6 +111,7 @@ phase_loop_runtime = [
     "_contract_docs/**",
     "_test_fixtures/**",
     "skills_bundle/**",
+    "deploy/*.service",
     # advisor_board ships its frozen config-format fixture + contract doc so a
     # pinned install resolves them via importlib.resources (ABDFREEZE).
     "advisor_board/fixtures/*.toml",

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

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

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

@@ -254,7 +254,13 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--quiet-warning-seconds", type=int, default=600)
     parser.add_argument("--quiet-blocker-seconds", type=int, default=1800)
     parser.add_argument("--no-heartbeat", action="store_true")
-    parser.add_argument("--closeout-mode", choices=CLOSEOUT_MODES, default="manual")
+    # PUSHFLOW: SUPPRESS (not default="manual") so an unset closeout mode leaves NO
+    # attribute — `_resolve_run_closeout_mode` then applies the command-aware default
+    # (push for the outer run loop, manual elsewhere). A value passed in THIS
+    # before-subcommand position survives the subcommand parse (the run/resume/dry-run
+    # subparser also uses SUPPRESS), so an explicit `--closeout-mode` wins in BOTH
+    # option positions (was clobbered to the subparser default before).
+    parser.add_argument("--closeout-mode", choices=CLOSEOUT_MODES, default=argparse.SUPPRESS)
     parser.add_argument("--work-unit-mode", action="store_true")
     parser.add_argument("--rotate-executors")
     parser.add_argument("--rotation-mode", choices=("phase", "work_unit"), default="phase")
@@ -285,7 +291,24 @@ def build_parser() -> argparse.ArgumentParser:
             sub.add_argument("--mode", help="The execution mode: execute, repair, or review.")
         _add_common_subparser_args(sub, name=name)
         if name in {"run", "resume", "dry-run"}:
-            sub.add_argument("--closeout-mode", choices=CLOSEOUT_MODES)
+            # PUSHFLOW: closeout pushes by DEFAULT for run/resume/dry-run (the outer
+            # orchestration loop). An explicit --closeout-mode always wins; when none
+            # is given the default is `push` (was `manual`), so phase-owned work lands
+            # on origin instead of accumulating locally. --no-push restores the prior
+            # `manual` default for operators who want to withhold the push. The push
+            # itself degrades gracefully with no push remote (recorded as push_refused
+            # by the runner, never an error). See _resolve_run_closeout_mode.
+            # SUPPRESS so an unset value does NOT overwrite a before-subcommand
+            # `--closeout-mode` with None, and so the absent case falls through to the
+            # command-aware push default in _resolve_run_closeout_mode.
+            sub.add_argument("--closeout-mode", choices=CLOSEOUT_MODES, default=argparse.SUPPRESS)
+            sub.add_argument(
+                "--no-push",
+                action="store_true",
+                help="Suppress the push-by-default closeout: fall back to manual "
+                "closeout (the prior default) instead of pushing phase-owned work to "
+                "origin. Ignored when --closeout-mode is given explicitly.",
+            )
             sub.add_argument(
                 "--governed",
                 action="store_true",
@@ -346,6 +369,13 @@ def build_parser() -> argparse.ArgumentParser:
             )
             sub.add_argument("--path", help="Report freshness holders for a single repo-relative path. Omit to report every path touched by an active worktree.")
             sub.add_argument("--base", help="Diff base ref (default: origin/<default-branch>, falling back to origin/main).")
+            sub.add_argument(
+                "--fail-on-ahead",
+                action="store_true",
+                help="PUSHFLOW opt-in soft-block: exit non-zero when any worktree is more than "
+                "AHEAD_WARN_THRESHOLD commits ahead of the base ref (unpushed local divergence). "
+                "Default is WARN-only; never human_required.",
+            )
         if name == "consiliency-lease":
             sub.description = (
                 "CS-0.10c: local-file LeaseStore -- soft, TTL+heartbeat path-set leases so parallel "
@@ -755,18 +785,37 @@ def build_parser() -> argparse.ArgumentParser:
             name,
             help="Probe or resolve an exact authenticated Codex task-message source.",
         )
-        task_message_sub.add_argument("--endpoint", required=True, help="Authenticated Codex app-server ws:// or wss:// endpoint.")
+        task_message_transport = task_message_sub.add_mutually_exclusive_group(required=True)
+        task_message_transport.add_argument("--endpoint", help="Authenticated Codex app-server ws:// or wss:// endpoint.")
+        task_message_transport.add_argument("--broker-url", help="Authenticated task-message broker HTTPS endpoint.")
+        task_message_transport.add_argument(
+            "--control-socket",
+            help="Absolute local managed app-server control socket; use only on the source host over an independently authenticated channel.",
+        )
         task_message_sub.add_argument("--authority", required=True, help="Pinned source authority identity.")
         task_message_sub.add_argument(
             "--token-env",
-            required=True,
+            required=False,
             help="Environment variable containing the app-server bearer token; the token is never printed.",
         )
         task_message_sub.add_argument("--timeout-seconds", type=float, default=10.0)
+        task_message_sub.add_argument("--heartbeat-timeout-seconds", type=float, default=15.0)
         if name == "task-message-resolve":
             task_message_sub.add_argument("--thread-id", required=True)
             task_message_sub.add_argument("--message-id", required=True)
             task_message_sub.add_argument("--max-source-age-seconds", type=int, default=900)
+    task_message_broker_sub = subparsers.add_parser(
+        "task-message-broker-serve",
+        help="Serve the loopback-only authenticated task-message broker.",
+    )
+    task_message_broker_sub.add_argument("--host", default="127.0.0.1")
+    task_message_broker_sub.add_argument("--port", type=int, default=18765)
+    task_message_broker_sub.add_argument("--control-socket", required=True)
+    task_message_broker_sub.add_argument("--authority", required=True)
+    task_message_broker_sub.add_argument("--token-sha256", required=True)
+    task_message_broker_sub.add_argument("--agent-harness-sha", required=True)
+    task_message_broker_sub.add_argument("--heartbeat-seconds", type=float, default=5.0)
+    task_message_broker_sub.add_argument("--timeout-seconds", type=float, default=10.0)
     # DECOUPLE SL-1: dotfiles-domain commands are added here, only when a profile
     # plugin is installed/opted-in. A clean wheel registers none.
     _register_profile_commands(subparsers)
@@ -812,6 +861,32 @@ def main(argv: list[str] | None = None) -> int:
         return 2
 
 
+def _resolve_run_closeout_mode(args: argparse.Namespace, command: str) -> str:
+    """PUSHFLOW: resolve the effective closeout mode for the outer run loop.
+
+    Precedence (explicit-wins in EITHER option position, then the flipped default):
+
+    1. An explicit ``--closeout-mode`` always wins. Both the top-level and the
+       ``run``/``resume``/``dry-run`` subparser use ``argparse.SUPPRESS``, so the
+       attribute exists only when the operator passed it (before OR after the
+       subcommand); a value given before the subcommand is no longer clobbered.
+    2. Otherwise, for the outer orchestration loop (``run``/``resume``/``dry-run``,
+       including the implicit no-subcommand forms) the default flips to ``"push"``
+       so phase-owned work lands on origin instead of accumulating unpushed — unless
+       ``--no-push`` restores ``"manual"``. The runner degrades to ``push_refused``
+       when there is no push remote (never an error).
+    3. Every other command that reaches ``run_loop`` (``execute``, ``maintain-skills``)
+       keeps the prior ``"manual"`` default — the push flip is scoped to the outer
+       loop and must never turn an inner ``execute`` leg into a pusher.
+    """
+    explicit = getattr(args, "closeout_mode", None)
+    if explicit:
+        return explicit
+    if command in {"run", "resume", "dry-run"}:
+        return "manual" if getattr(args, "no_push", False) else "push"
+    return "manual"
+
+
 def _main(parser: argparse.ArgumentParser, args: argparse.Namespace, command: str) -> int:
     allow_cross_phase_dirty_reason = getattr(args, "allow_cross_phase_dirty", None)
     if allow_cross_phase_dirty_reason is not None:
@@ -884,6 +959,8 @@ def _main(parser: argparse.ArgumentParser, args: argparse.Namespace, command: st
         return _outside_agent_validate_command(args=args)
     if command in {"task-message-probe", "task-message-resolve"}:
         return _task_message_command(args=args, resolve=command == "task-message-resolve")
+    if command == "task-message-broker-serve":
+        return _task_message_broker_serve_command(args=args)
     if command == "advisor-board":
         return _advisor_board_command(args=args)
     if command == "docs-audit":
@@ -918,6 +995,20 @@ def _main(parser: argparse.ArgumentParser, args: argparse.Namespace, command: st
             print(json.dumps(report.to_json(), indent=2))
         else:
             print(worktree_index.render_human(report))
+        # PUSHFLOW: opt-in soft-block on unpushed local divergence. WARN-only by
+        # default (the count is already in the report/render); --fail-on-ahead makes
+        # it exit non-zero. Never human_required.
+        if getattr(args, "fail_on_ahead", False):
+            over = worktree_index.worktrees_ahead_over_threshold(report)
+            if over:
+                names = ", ".join(f"{wt.branch or wt.path} (+{wt.commits_ahead_of_origin})" for wt in over)
+                print(
+                    f"FAIL: {len(over)} worktree(s) more than {worktree_index.AHEAD_WARN_THRESHOLD} "
+                    f"commits ahead of {report.base_ref} (unpushed local divergence): {names}",
+                    file=sys.stderr,
+                    flush=True,
+                )
+                return 1
         return 0
     if command == "consiliency-lease":
         repo_arg = args.repo or "."
@@ -1221,7 +1312,7 @@ def _main(parser: argparse.ArgumentParser, args: argparse.Namespace, command: st
         quiet_warning_seconds=args.quiet_warning_seconds or 600,
         quiet_blocker_seconds=args.quiet_blocker_seconds or 1800,
         heartbeat_enabled=not bool(args.no_heartbeat),
-        closeout_mode=args.closeout_mode or "manual",
+        closeout_mode=_resolve_run_closeout_mode(args, command),
         enable_tier_3=bool(getattr(args, "enable_tier_3", False)),
         tier_3_budget=3 if getattr(args, "tier_3_budget", 3) is None else getattr(args, "tier_3_budget", 3),
         command_adapter_name=args.command_name,
@@ -1453,8 +1544,7 @@ def _outside_agent_validate_command(args: argparse.Namespace) -> int:
 def _task_message_command(args: argparse.Namespace, *, resolve: bool) -> int:
     from .task_message_resolver import CodexAppServerTaskMessageResolver, TaskMessageResolverError
 
-    token = os.environ.get(args.token_env, "")
-    if not token:
+    if args.control_socket and args.token_env:
         error = TaskMessageResolverError(
             "attestation_invalid",
             authority=args.authority,
@@ -1463,19 +1553,50 @@ def _task_message_command(args: argparse.Namespace, *, resolve: bool) -> int:
         )
         print(json.dumps(error.metadata(), indent=2, sort_keys=True))
         return 2
-    try:
-        resolver = CodexAppServerTaskMessageResolver(
-            endpoint=args.endpoint,
-            bearer_token=token,
+    remote_transport = bool(args.endpoint or args.broker_url)
+    token = os.environ.get(args.token_env, "") if remote_transport and args.token_env else ""
+    if remote_transport and not token:
+        error = TaskMessageResolverError(
+            "attestation_invalid",
             authority=args.authority,
-            max_source_age_seconds=getattr(args, "max_source_age_seconds", 900),
-            timeout_seconds=args.timeout_seconds,
-        )
-        payload = (
-            resolver.resolve(thread_id=args.thread_id, message_id=args.message_id).payload()
-            if resolve
-            else resolver.probe()
+            thread_id=getattr(args, "thread_id", None),
+            message_id=getattr(args, "message_id", None),
         )
+        print(json.dumps(error.metadata(), indent=2, sort_keys=True))
+        return 2
+    try:
+        if args.broker_url:
+            from .task_message_broker_client import TaskMessageBrokerClient
+
+            broker = TaskMessageBrokerClient(
+                broker_url=args.broker_url,
+                bearer_token=token,
+                authority=args.authority,
+                heartbeat_timeout_seconds=args.heartbeat_timeout_seconds,
+            )
+            payload = (
+                broker.resolve(
+                    thread_id=args.thread_id,
+                    message_id=args.message_id,
+                    max_source_age_seconds=args.max_source_age_seconds,
+                )
+                if resolve
+                else broker.probe()
+            )
+        else:
+            resolver = CodexAppServerTaskMessageResolver(
+                endpoint=args.endpoint,
+                bearer_token=token or None,
+                control_socket=args.control_socket,
+                authority=args.authority,
+                max_source_age_seconds=getattr(args, "max_source_age_seconds", 900),
+                timeout_seconds=args.timeout_seconds,
+            )
+            payload = (
+                resolver.resolve(thread_id=args.thread_id, message_id=args.message_id).payload()
+                if resolve
+                else resolver.probe()
+            )
     except ValueError:
         error = TaskMessageResolverError(
             "attestation_invalid",
@@ -1492,6 +1613,39 @@ def _task_message_command(args: argparse.Namespace, *, resolve: bool) -> int:
     return 0
 
 
+def _task_message_broker_serve_command(args: argparse.Namespace) -> int:
+    from .task_message_broker import BrokerConfig, TaskMessageBroker, build_server, verified_installed_agent_harness_sha
+    from .task_message_resolver import CodexAppServerTaskMessageResolver
+
+    try:
+        agent_harness_sha = verified_installed_agent_harness_sha(args.agent_harness_sha)
+        config = BrokerConfig(
+            authority=args.authority,
+            token_sha256=args.token_sha256,
+            agent_harness_sha=agent_harness_sha,
+            heartbeat_seconds=args.heartbeat_seconds,
+        )
+
+        def resolver_factory(max_source_age_seconds: int) -> CodexAppServerTaskMessageResolver:
+            return CodexAppServerTaskMessageResolver(
+                control_socket=args.control_socket,
+                authority=args.authority,
+                max_source_age_seconds=max_source_age_seconds,
+                timeout_seconds=args.timeout_seconds,
+            )
+
+        server = build_server(args.host, args.port, TaskMessageBroker(config, resolver_factory))
+    except ValueError:
+        return 2
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        return 130
+    finally:
+        server.server_close()
+    return 0
+
+
 def _parse_lane_ir_override(parser: argparse.ArgumentParser, args: argparse.Namespace, command: str) -> tuple[str, ...]:
     raw = getattr(args, "allow_lane_ir_override", None)
     if raw is None:

{phase_loop_runtime-0.7.0 → phase_loop_runtime-0.7.1}/src/phase_loop_runtime/closeout_validators.py

@@ -36,12 +36,24 @@ REVIEW_MODE_ENV = "PHASE_LOOP_REVIEW"
 
 @dataclass(frozen=True)
 class ReviewFinding:
-    """A single review-gate observation about a closeout."""
+    """A single review-gate observation about a closeout.
+
+    ``reason`` is the SHORT gate-generated summary (``panel leg gemini raised a
+    blocking concern``). ``body`` (issue #80) is the ACTUAL panel finding text — the
+    concrete review a non-human repair reads to know WHAT to fix; the runner's
+    panel scratch dir is torn down after the leg completes, so if the body is not
+    carried here it is lost. ``reviewed_sha`` (issue #88) binds the verdict to the
+    exact reviewed commit so a consumer can reject a verdict computed against a
+    different head (SHA-bound agent-review-gate). Both are optional so every
+    existing caller and persisted finding stay byte-for-byte unchanged.
+    """
 
     code: str
     reason: str
     severity: ReviewSeverity = "warn"
     blocker_class: str | None = None
+    body: str | None = None
+    reviewed_sha: str | None = None
 
     def __post_init__(self) -> None:
         if self.severity not in REVIEW_SEVERITIES:
@@ -56,6 +68,13 @@ class ReviewFinding:
         }
         if self.blocker_class is not None:
             payload["blocker_class"] = self.blocker_class
+        # #80: persist the actual finding body so it survives the panel-scratch
+        # teardown and reaches durable state/handoff/ledger artifacts.
+        if self.body is not None:
+            payload["body"] = self.body
+        # #88: persist the reviewed commit the verdict is bound to.
+        if self.reviewed_sha is not None:
+            payload["reviewed_sha"] = self.reviewed_sha
         return payload
 
 
@@ -177,6 +196,66 @@ def apply_review_findings(
     }
 
 
+def verdict_binds_to(finding: ReviewFinding, head_sha: str | None) -> bool:
+    """#88 SHA-bound agent-review-gate: True iff ``finding``'s verdict was computed
+    against ``head_sha``.
+
+    A finding with no recorded ``reviewed_sha`` is UNBOUND — it cannot vouch for any
+    specific commit, so it never binds (fail-closed). A ``head_sha`` of ``None``
+    (unknown head) likewise cannot be vouched for. Binding is an exact match: a
+    verdict reviewed at an earlier head must NOT be trusted for a newer head."""
+    if not finding.reviewed_sha or not head_sha:
+        return False
+    return finding.reviewed_sha == head_sha
+
+
+def ratification_findings(decision) -> tuple[ReviewFinding, ...]:
+    """Translate a ``ratification_policy.RatificationDecision`` into closeout findings
+    (the posture wiring for IF-0-POLICY-1).
+
+    * ``escalate``  -> a single ``block`` finding with ``blocker_class=
+      "review_gate_block"`` — a NON-human, agent-recoverable hold (never
+      ``human_required``), carrying the actionable shortfall detail as ``body`` and
+      the reviewed SHA (#88 binding).
+    * ``proceed_degraded`` -> a single ``warn`` finding recording the durable audit
+      trail that a degraded board was knowingly accepted (the loop continues).
+    * ``ratified`` -> no finding (a clean pass is non-gating; the caller persists
+      ``decision.to_audit()`` separately if it wants the positive record).
+
+    Import is function-local so this module has no hard dependency on
+    ``ratification_policy`` (and there is no import cycle).
+    """
+    from .ratification_policy import ESCALATE, PROCEED_DEGRADED, shortfall_detail
+
+    detail = shortfall_detail(decision)
+    reviewed_sha = decision.facts.reviewed_sha
+    if decision.status == ESCALATE:
+        return (
+            ReviewFinding(
+                code=f"ratification_shortfall_{decision.gate or 'gate'}",
+                reason=f"ratification policy not met for {decision.gate or 'gate'}: {detail}",
+                severity="block",
+                blocker_class="review_gate_block",
+                body=detail,
+                reviewed_sha=reviewed_sha,
+            ),
+        )
+    if decision.status == PROCEED_DEGRADED:
+        return (
+            ReviewFinding(
+                code=f"ratification_degraded_{decision.gate or 'gate'}",
+                reason=(
+                    f"ratification proceeded on a degraded board for "
+                    f"{decision.gate or 'gate'}: {detail}"
+                ),
+                severity="warn",
+                body=detail,
+                reviewed_sha=reviewed_sha,
+            ),
+        )
+    return ()
+
+
 def load_builtin_closeout_validators() -> None:
     """Import the built-in validator modules so they self-register.
 

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

@@ -0,0 +1,29 @@
+[Unit]
+Description=Phase-loop task-message source broker
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+EnvironmentFile=%h/.config/phase-loop/task-message-broker.env
+ExecStart=%h/.local/share/phase-loop-task-message-broker/bin/phase-loop task-message-broker-serve --host 127.0.0.1 --port 18765 --control-socket %h/.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
+PrivateTmp=yes
+ProtectHome=tmpfs
+BindReadOnlyPaths=%h/.local/share/phase-loop-task-message-broker
+BindReadOnlyPaths=%h/.codex/app-server-control/app-server-control.sock
+ProtectSystem=strict
+ProtectControlGroups=yes
+ProtectKernelTunables=yes
+LockPersonality=yes
+MemoryDenyWriteExecute=yes
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+RestrictRealtime=yes
+RestrictSUIDSGID=yes
+SystemCallArchitectures=native
+
+[Install]
+WantedBy=default.target

{phase_loop_runtime-0.7.0 → phase_loop_runtime-0.7.1}/src/phase_loop_runtime/discovery.py

@@ -1114,18 +1114,23 @@ def _discovery_allow_completed() -> bool:
 
 
 def _phase_manifest_entries(repo: Path) -> tuple[object, ...]:
+    # agent-harness#164 (IF-0-MANIFEST-1): consume the manifest PER-ENTRY. A
+    # structural failure (unparseable / bad schema / plans-not-array) hides the
+    # whole manifest, but a single stale/renamed/missing/parse-hostile entry is
+    # skipped (treated orphaned) instead of silently degrading ALL entries to
+    # regex discovery. `valid_phase_entries` materializes only the valid rows,
+    # tolerating an unparseable sibling; the skipped entry's operator signal
+    # (manifest_plan_file_missing) is emitted independently by
+    # reconcile._reconcile_plan_manifest.
     try:
-        from .plan_manifest import read_manifest, validate_manifest
+        from .plan_manifest import valid_phase_entries
     except Exception:
         return ()
     manifest_path = repo / "plans" / "manifest.json"
-    if manifest_path.exists() and not validate_manifest(manifest_path).valid:
+    if not manifest_path.exists():
         return ()
-    try:
-        manifest = read_manifest(repo)
-    except Exception:
-        return ()
-    return tuple(entry for entry in manifest.plans if entry.type == "phase")
+    entries = valid_phase_entries(manifest_path)
+    return entries if entries is not None else ()
 
 
 def plan_is_stale(plan: Path, roadmap: Path) -> bool: