Add shadow rollout gate command

Author: rylinjames

README.md

@@ -379,6 +379,20 @@ to collect a single shadow trace where production actions stay live and
 candidate actions are appended as `shadow_result` evidence for
 `tether policy diff --shadow`.
 
+For the self-serve rollout decision, run the shadow gate directly:
+
+```bash
+tether policy shadow-gate ./traces/shadow.jsonl.gz \
+  --packet-dir /tmp/tether-shadow-rollout \
+  --profile lab-shadow \
+  --min-compared 100 \
+  --wait-timeout-s 5
+```
+
+It writes a hashed packet with `policy-diff.json` and
+`promotion-decision.json`, then exits `0` for `PROMOTE`, `1` for `HOLD`, and
+`4` for `ROLLBACK`.
+
 ```bash
 tether prove ./p0 \
   --embodiment franka \

docs/cli_reference.md

@@ -144,22 +144,35 @@ path exported by `tether profiles init`.
 
 ## `tether policy`
 
-Policy rollout gates that operate on recorded traces. Today the main command is
-`policy diff`: compare a baseline trace with a candidate trace, or compare a
-single shadow trace's recorded production actions against shadow evidence
-(`shadow_result` rows, with legacy `routing.shadow_actions` still supported).
+Policy rollout gates that operate on recorded traces. The common self-serve
+path is `policy shadow-gate`: turn a recorded shadow rollout into a proof
+packet plus one operator decision. Use `policy diff` when you only need the raw
+baseline/candidate or shadow comparison report.
 
 ```bash
 # Offline promotion check: same observations, candidate policy output
 tether policy diff ./traces/v1.jsonl.gz ./traces/v2.jsonl.gz --fail-on any
 
 # Shadow rollout check: live actions vs shadow actions in one trace
 tether policy diff ./traces/shadow.jsonl.gz --shadow --output policy-diff.json
+
+# Self-serve shadow promotion gate
+tether policy shadow-gate ./traces/shadow.jsonl.gz \
+  --packet-dir ./shadow-rollout-packet \
+  --profile lab-shadow \
+  --min-compared 100 \
+  --wait-timeout-s 5
 ```
 
-The report includes action cosine/max-delta, latency regressions, shape failures,
-guard regressions, request mismatches, metadata warnings, and a pass/warn/fail
-verdict. Exit code `3` means the selected `--fail-on` gate tripped.
+`policy shadow-gate` writes `deployment-proof.json`, `policy-diff.json`,
+`promotion-decision.json`, and `MANIFEST.json`. Exit codes: `0` means
+`PROMOTE`, `1` means `HOLD`, `4` means `ROLLBACK`, and `2` means the trace,
+packet, or profile could not be loaded.
+
+The underlying policy-diff report includes action cosine/max-delta, latency
+regressions, shape failures, guard regressions, request mismatches, metadata
+warnings, and a pass/warn/fail verdict. Exit code `3` from `policy diff` means
+the selected `--fail-on` gate tripped.
 
 ---
 

docs/deploy_proof.md

@@ -52,6 +52,25 @@ tether profiles show warehouse-safe
 tether profiles init warehouse-safe --output warehouse-safe.yml
 ```
 
+## Shadow rollout gate
+
+For a candidate already mirrored with `tether serve --shadow-policy --record`,
+use `policy shadow-gate` to build the rollout packet and promotion decision in
+one step:
+
+```bash
+tether policy shadow-gate ./traces/shadow.jsonl.gz \
+  --packet-dir /tmp/tether-shadow-rollout \
+  --profile lab-shadow \
+  --min-compared 100 \
+  --wait-timeout-s 5
+```
+
+The command waits for pending `shadow_result` rows, writes `policy-diff.json`,
+verifies a hashed packet, and writes `promotion-decision.json`. Its top-level
+decision is `PROMOTE`, `HOLD`, or `ROLLBACK`; the embedded promotion report
+still uses `BLOCK` for a failed inactive candidate.
+
 ## What it checks
 
 - Deploy diagnostics via the same checks as `tether doctor --json --model`.

src/tether/cli.py

@@ -5595,6 +5595,112 @@ def policy_diff_cmd(
         raise typer.Exit(3)
 
 
+@policy_app.command("shadow-gate")
+def policy_shadow_gate_cmd(
+    trace: str = typer.Argument(
+        ...,
+        help="Shadow trace file recorded by `tether serve --shadow-policy --record`.",
+    ),
+    packet_dir: str = typer.Option(
+        "./shadow-rollout-packet",
+        "--packet-dir",
+        help="Output packet directory for deployment-proof, policy-diff, and promotion decision artifacts.",
+    ),
+    profile: str = typer.Option(
+        "lab-shadow",
+        "--profile",
+        help="Promotion profile name or YAML/JSON path. Default: lab-shadow.",
+    ),
+    candidate_active: bool = typer.Option(
+        False,
+        "--candidate-active",
+        help="Return ROLLBACK instead of HOLD when gates fail for an active candidate.",
+    ),
+    min_compared: int = typer.Option(
+        1,
+        "--min-compared",
+        help="Minimum compared shadow requests required before a PROMOTE decision is allowed.",
+    ),
+    wait_timeout_s: float = typer.Option(
+        0.0,
+        "--wait-timeout-s",
+        help="Seconds to wait for pending background shadow_result rows to flush.",
+    ),
+    poll_s: float = typer.Option(
+        0.25,
+        "--poll-s",
+        help="Polling interval while waiting for shadow_result rows.",
+    ),
+    fail_on: str = typer.Option(
+        "any",
+        "--fail-on",
+        help="Policy diff gate: none/actions/latency/guard/shape/any.",
+    ),
+    min_action_cos: float = typer.Option(
+        0.995,
+        "--min-action-cos",
+        help="Minimum cosine similarity before the action diff fails.",
+    ),
+    max_action_delta: float = typer.Option(
+        0.10,
+        "--max-action-delta",
+        help="Max absolute action delta before the action diff fails.",
+    ),
+    max_latency_regression_pct: float = typer.Option(
+        0.10,
+        "--max-latency-regression-pct",
+        help="Max shadow latency regression as a fraction, e.g. 0.10 = 10%.",
+    ),
+    use_existing_packet: bool = typer.Option(
+        False,
+        "--use-existing-packet",
+        help="Use an existing deployment-proof.json in --packet-dir instead of writing a shadow-only proof packet.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Print the full JSON report instead of a compact summary.",
+    ),
+) -> None:
+    """Turn shadow trace evidence into PROMOTE, HOLD, or ROLLBACK."""
+    from tether.shadow_rollout import (
+        ShadowRolloutError,
+        format_shadow_rollout_human,
+        run_shadow_rollout_gate,
+    )
+
+    try:
+        report = run_shadow_rollout_gate(
+            trace=trace,
+            packet_dir=packet_dir,
+            profile=profile,
+            candidate_active=candidate_active,
+            min_compared=min_compared,
+            wait_timeout_s=wait_timeout_s,
+            poll_s=poll_s,
+            fail_on=fail_on,
+            min_action_cos=min_action_cos,
+            max_action_delta=max_action_delta,
+            max_latency_regression_pct=max_latency_regression_pct,
+            use_existing_packet=use_existing_packet,
+        )
+    except ShadowRolloutError as exc:
+        err_console.print(f"[red]Shadow rollout gate failed:[/red] {exc}")
+        raise typer.Exit(2)
+
+    if json_output:
+        typer.echo(json.dumps(report, indent=2, sort_keys=True))
+    else:
+        console.print(format_shadow_rollout_human(report), markup=False)
+
+    decision = report.get("decision")
+    if decision == "PROMOTE":
+        raise typer.Exit(0)
+    if decision == "ROLLBACK":
+        raise typer.Exit(4)
+    raise typer.Exit(1)
+
+
 app.add_typer(models_app, name="models")
 app.add_typer(train_app, name="train")
 app.add_typer(validate_app, name="validate")

src/tether/promote.py

@@ -37,6 +37,8 @@
         "max_policy_guard_regressions": 0,
         "max_policy_shape_failures": 0,
         "max_policy_missing_candidate": 0,
+        "max_policy_shadow_pending": 0,
+        "max_policy_shadow_errors": 0,
         "max_roundtrip_p95_ms": None,
         "max_warm_roundtrip_p95_ms": None,
         "max_deadline_misses": None,
@@ -492,6 +494,8 @@ def _evaluate_policy_diff(
         ("max_policy_guard_regressions", "guard_regressions"),
         ("max_policy_shape_failures", "shape_failures"),
         ("max_policy_missing_candidate", "missing_candidate"),
+        ("max_policy_shadow_pending", "shadow_pending"),
+        ("max_policy_shadow_errors", "shadow_errors"),
     )
     for threshold_key, summary_key in threshold_map:
         limit = _threshold(profile, threshold_key)