loki-mode 9.18.4 → 9.20.0

package/autonomy/loki

@@ -750,7 +750,11 @@ loki_remote_fetch_receipt() {
     printf '%s' "$resp" > "$tmp" && mv "$tmp" "$dir/proof.json"
     echo "  Evidence Receipt: $dir/proof.json"
 
-    loki_remote_verify_receipt "$dir/proof.json"
+    # The URL is passed so the receipt's attestation can be checked against that
+    # server's published JWKS. Without it the attestation is simply not checked
+    # and the verdict falls back to the gpg path, which is the pre-existing
+    # behaviour rather than a downgrade.
+    loki_remote_verify_receipt "$dir/proof.json" "$url"
 }
 
 # Verify a fetched receipt locally and print exactly what was and was not
@@ -801,6 +805,121 @@ PY
     esac
 }
 
+# Check a receipt's JWKS attestation against the server's PUBLISHED key set.
+#
+# This is the half gpg cannot do over a network. gpg proves provenance only if
+# you already hold the publisher's key, which a submitter who ran
+# `loki start --remote` never does -- so the honest gpg outcome there is
+# NOT CHECKED, and it stays that way until someone performs an out-of-band key
+# import. Fetching /.well-known/jwks.json over the same TLS the API already
+# uses removes that step.
+#
+# Prints "ok", "bad", or "" (could not check). Fails toward "" so an
+# unreachable JWKS never manufactures a verdict in either direction -- an
+# absent measurement is not evidence, and inventing a PASS here would be worse
+# than inventing a FAIL.
+loki_remote_attestation_status() {
+    local pj="$1" url="$2"
+    [ -n "$url" ] || { printf ''; return 0; }
+    command -v python3 >/dev/null 2>&1 || { printf ''; return 0; }
+    local tok
+    tok="$(jq -r '.verification.attestation // empty' "$pj" 2>/dev/null)"
+    [ -n "$tok" ] || { printf ''; return 0; }
+    python3 - "$pj" "$url" "${_LOKI_SCRIPT_DIR}" <<'PY' 2>/dev/null || printf ''
+import json, sys, hashlib, urllib.request
+sys.path.insert(0, sys.argv[3])
+try:
+    from receipt_jwt import verify_attestation
+except ImportError:
+    sys.exit(1)          # -> "" : cannot check, never a verdict
+proof = json.load(open(sys.argv[1]))
+tok = (proof.get("verification") or {}).get("attestation") or ""
+if not tok:
+    sys.exit(1)
+try:
+    with urllib.request.urlopen(
+            sys.argv[2].rstrip("/") + "/.well-known/jwks.json", timeout=10) as r:
+        jwks = json.loads(r.read())
+except Exception:
+    sys.exit(1)          # unreachable JWKS is UNCHECKED, not a failure
+ok, claims = verify_attestation(tok, jwks)
+if not ok:
+    print("bad"); sys.exit(0)
+# The signature verifying is not enough on its own: it must attest to THIS
+# receipt. Recompute the digest the same way the receipt records it (with
+# `verification` stripped) and require the signed claim to match, or a valid
+# token lifted from a different run would vouch for these bytes.
+proof.pop("verification", None)
+canon = json.dumps(proof, sort_keys=True, separators=(",", ":")).encode()
+print("ok" if claims.get("receipt_sha256") == hashlib.sha256(canon).hexdigest()
+      else "bad")
+PY
+}
+
+# Check a receipt's attestation against a key set given as a URL OR a file.
+#
+# The file form is what makes this usable by a third party with no network and
+# no Loki install: hand them proof.json and jwks.json and they can check both
+# integrity and provenance themselves. That is the whole claim -- "a receipt you
+# can check yourself" is false if checking requires our infrastructure.
+#
+# Prints "ok", "bad", "none" (no attestation present), or "" (could not check).
+# "none" and "" are deliberately distinct: one is a fact about the receipt, the
+# other is an absent measurement, and collapsing them would report an unchecked
+# receipt as an unattested one.
+# NOTE: this shares its verification logic with loki_remote_attestation_status
+# above. The two differ only in their key-set source (that one is URL-only, from
+# a live fetch during a --remote run; this one also accepts a FILE for the
+# offline third-party case). If you change the digest-recompute rule, CHANGE
+# BOTH -- they are covered by different tests
+# (test-remote-attestation-verdict.sh and test-proof-verify-jwks.sh), so a
+# one-sided edit passes one suite and silently weakens the other. Mutation
+# testing found exactly this: a mutation applied to the first copy left every
+# assertion of the second suite green.
+loki_proof_attestation_check() {
+    local pj="$1" src="$2"
+    [ -n "$src" ] || { printf ''; return 0; }
+    command -v python3 >/dev/null 2>&1 || { printf ''; return 0; }
+    python3 - "$pj" "$src" "${_LOKI_SCRIPT_DIR}" <<'PY' 2>/dev/null || printf ''
+import json, sys, os, hashlib, urllib.request
+sys.path.insert(0, sys.argv[3])
+try:
+    from receipt_jwt import verify_attestation
+except ImportError:
+    sys.exit(1)                      # "" : cannot check
+try:
+    proof = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(1)
+tok = (proof.get("verification") or {}).get("attestation") or ""
+if not tok:
+    print("none"); sys.exit(0)       # a FACT about the receipt, not an error
+src = sys.argv[2]
+try:
+    if os.path.isfile(src):
+        jwks = json.load(open(src))
+    else:
+        if not src.startswith(("http://", "https://")):
+            sys.exit(1)
+        url = src if src.rstrip("/").endswith("jwks.json") else \
+            src.rstrip("/") + "/.well-known/jwks.json"
+        with urllib.request.urlopen(url, timeout=10) as r:
+            jwks = json.loads(r.read())
+except Exception:
+    sys.exit(1)                      # "" : unreachable/unreadable, no verdict
+ok, claims = verify_attestation(tok, jwks)
+if not ok:
+    print("bad"); sys.exit(0)
+# A verifying signature is not enough: it must attest to THESE bytes. Recompute
+# the digest the way the receipt records it, so a token lifted from another run
+# cannot vouch for this one.
+proof.pop("verification", None)
+canon = json.dumps(proof, sort_keys=True, separators=(",", ":")).encode()
+print("ok" if claims.get("receipt_sha256") == hashlib.sha256(canon).hexdigest()
+      else "bad")
+PY
+}
+
 loki_remote_verify_receipt() {
     local pj="$1"
     local verifier="${_LOKI_SCRIPT_DIR}/lib/proof-verify.py"
@@ -828,6 +947,10 @@ loki_remote_verify_receipt() {
     # a gate that cries wolf every time trains users to ignore the verdict.
     # Only hash_ok and gpg_ok are load-bearing here; drift is not our verdict.
     local out hash_ok gpg_ok
+    # Second argument is the remote URL when this receipt came from a cluster;
+    # empty for a local receipt, which simply means no attestation is checked.
+    local _attest_url="${2:-}" _attest=""
+    _attest="$(loki_remote_attestation_status "$pj" "$_attest_url")"
     out="$(python3 "$verifier" "$pj" "${TARGET_DIR:-.}" 2>/dev/null)"
     hash_ok="$(printf '%s' "$out" | jq -r '.hash_ok // false' 2>/dev/null)"
     gpg_ok="$(printf '%s' "$out" | jq -r '.gpg_ok | tostring' 2>/dev/null)"
@@ -849,6 +972,18 @@ loki_remote_verify_receipt() {
         echo "    the build ran elsewhere. Not tampering, and not part of the verdict."
     fi
 
+    # An attestation that does not verify is an ACCUSATION, and it is checked
+    # before the gpg branches because it is the stronger statement: the server's
+    # own published key says this token does not cover these bytes. Either the
+    # receipt was altered after the server signed it, or the token was lifted
+    # from a different run. Both mean: do not trust this build.
+    if [ "$_attest" = "bad" ]; then
+        echo -e "  ${RED}TAMPERED: the receipt's attestation does not verify against the server's published keys.${NC}" >&2
+        echo "    Either these bytes were altered after signing, or the attestation" >&2
+        echo "    belongs to a different run. Do not trust this build." >&2
+        return 1
+    fi
+
     # gpg_ok=false covers TWO facts that must never be conflated: the signature
     # is cryptographically bad over this content (the receipt was ALTERED), and
     # gpg could not evaluate it at all (we do not hold the public key). Only the
@@ -866,6 +1001,17 @@ loki_remote_verify_receipt() {
             _why="$(loki_remote_gpg_status "$pj")"
         fi
         if [ "$_why" = "nopubkey" ]; then
+            # JWKS exists precisely for this case: the gpg key is absent, but a
+            # remote-issued receipt can still prove provenance against the
+            # server's published key set, with no out-of-band import.
+            if [ "$_attest" = "ok" ]; then
+                echo -e "  ${GREEN}VERIFIED${NC}: integrity hash matches and the receipt's attestation is valid."
+                echo "    Proven: these bytes are unaltered, and the build server signed them"
+                echo "    with a key published at ${_attest_url}/.well-known/jwks.json."
+                echo "    The gpg key is not in your keyring; the attestation covers provenance."
+                echo "    NOT proven: that the code is correct. A receipt records which checks ran."
+                return 0
+            fi
             echo -e "  ${YELLOW}NOT CHECKED${NC}: the receipt is signed, but the signing key is not in your keyring." >&2
             echo "    Nothing is wrong with the contents: the integrity hash matches. The" >&2
             echo "    signature could not be evaluated, so PROVENANCE is unproven here." >&2
@@ -897,6 +1043,20 @@ loki_remote_verify_receipt() {
         return 0
     fi
 
+    # No gpg signature, but a verified attestation. This is the normal shape for
+    # a cluster build: the receiver signs, the build never holds a gpg key, and
+    # provenance is still proven -- so calling it UNSIGNED would understate what
+    # was actually checked, the mirror of the error we refuse in the other
+    # direction.
+    if [ "$_attest" = "ok" ]; then
+        echo -e "  ${GREEN}VERIFIED${NC}: integrity hash matches and the receipt's attestation is valid."
+        echo "    Proven: these bytes are unaltered, and they were signed by the build"
+        echo "    server whose key is published at ${_attest_url}/.well-known/jwks.json."
+        echo "    Verify that server is one you trust."
+        echo "    NOT proven: that the code is correct. A receipt records which checks ran."
+        return 0
+    fi
+
     echo -e "  ${YELLOW}UNSIGNED${NC}: integrity hash matches. This is NOT proof of provenance."
     echo "    Proven: the receipt is internally consistent with its own hash."
     echo "    NOT proven: who produced it. An unsigned receipt is forgeable -- whoever"
@@ -1501,7 +1661,7 @@ show_landing() {
 }
 
 # Detect argument type for unified `loki start` (v6.84.0)
-# Returns one of: prd | issue | empty | unknown
+# Returns one of: prd | issue | repo | empty | unknown
 # Logic:
 #   - empty arg -> "empty"
 #   - file path ending in .md/.json/.txt AND exists on disk -> "prd"
@@ -1565,7 +1725,10 @@ detect_arg_type() {
     # BUT only if a file with that literal name does NOT exist on disk
     # (ambiguity resolution: files-on-disk win over issue-number heuristic).
     if [[ "$arg" =~ ^#?[0-9]+$ ]]; then
-        if [ -e "$arg" ]; then
+        if [ -d "$arg" ]; then
+            # Directory on disk wins -- same rule as the -d branch below.
+            echo "repo"
+        elif [ -e "$arg" ]; then
             # File on disk wins -- treat as PRD
             echo "prd"
         else
@@ -1574,6 +1737,20 @@ detect_arg_type() {
         return 0
     fi
 
+    # An existing DIRECTORY is a repo to improve, not a spec to build from.
+    # Before this, a directory fell into the "prd" branch below and was handed
+    # to run.sh as a PRD path; it has no .md-family extension, so the
+    # not-found guard skipped it and the run silently proceeded as if no spec
+    # had been given. `loki start <dir>` now means "work on that repo".
+    # ponytail: a directory named `spec.md` still returns "prd" -- the
+    # extension branch at the top of this function wins. Deliberate: an
+    # explicit spec extension is the stronger signal. Move this block above
+    # that branch if directories-with-spec-names ever matter.
+    if [ -d "$arg" ]; then
+        echo "repo"
+        return 0
+    fi
+
     # An existing file on disk is unambiguously a PRD, even if its name has
     # spaces -- a real path the user pointed at wins over the brief heuristic.
     if [ -e "$arg" ]; then
@@ -1862,9 +2039,10 @@ cmd_start() {
             --help|-h)
                 echo -e "${BOLD}loki start${NC} - Unified entry point for Loki Mode (v6.84.0)"
                 echo ""
-                echo "Usage: loki start [PRD|ISSUE-REF] [options]"
+                echo "Usage: loki start [REPO|PRD|ISSUE-REF] [options]"
                 echo ""
                 echo "Modes (auto-detected from input):"
+                echo "  REPO mode   - existing directory -> one bounded verified improvement"
                 echo "  PRD mode    - path ending in .md/.json/.txt/.yaml -> build from PRD"
                 echo "  ISSUE mode  - GitHub/GitLab/Jira/Azure DevOps URL, owner/repo#N,"
                 echo "                PROJ-123, #123, or bare number -> generate PRD from issue"
@@ -1873,6 +2051,7 @@ cmd_start() {
                 echo "  no input    - analyze current directory, auto-generate PRD"
                 echo ""
                 echo "Arguments:"
+                echo "  REPO                  Existing project directory"
                 echo "  PRD                   Path to PRD file (.md/.json/.txt/.yaml)"
                 echo "  ISSUE-REF             Issue URL, number, or tracker key (see above)"
                 echo ""
@@ -1947,6 +2126,7 @@ cmd_start() {
                 echo ""
                 echo "Examples:"
                 echo "  loki start                              # Interactive, analyze current dir"
+                echo "  loki start ./my-project                 # Improve an existing project"
                 echo "  loki start \"build a todo app\"           # BRIEF mode (zero-config fast run)"
                 echo "  loki start --brief \"snake\"              # BRIEF mode (single-word escape hatch)"
                 echo "  loki start ./prd.md                     # PRD mode"
@@ -2557,6 +2737,22 @@ cmd_start() {
         detected_type="empty"
     fi
 
+    # Resolve the directory while the positional path is still relative to the
+    # caller, then enter it before creating any .loki state. Quoted `cd --`
+    # keeps spaces and shell metacharacters inert.
+    if [ "$detected_type" = "repo" ]; then
+        local repo_target
+        repo_target=$(cd -- "$positional_arg" 2>/dev/null && pwd -P) || {
+            echo -e "${RED}Error: cannot enter repository directory: $positional_arg${NC}" >&2
+            return 1
+        }
+        cd -- "$repo_target" || return 1
+        if [ "$LOKI_DIR" = ".loki" ]; then
+            LOKI_DIR="$repo_target/.loki"
+        fi
+        export LOKI_REPO_TARGET="$repo_target"
+    fi
+
     # ISSUE mode: delegate to cmd_run's code path. To avoid duplicating ~450
     # lines of issue-fetching + PR-creation logic, we re-dispatch through
     # cmd_run with reconstructed args. cmd_run then calls cmd_start again
@@ -2638,12 +2834,43 @@ cmd_start() {
         echo ""
     fi
 
+    # REPO mode: `loki start <directory>`. We already cd'd into the target
+    # above, so this is the no-arg codebase path with one difference -- a
+    # synthesized brief that bounds the work to ONE high-value improvement
+    # instead of "build out the whole project".
+    #
+    # Deliberately does NOT call set_ttfv_lightweight_profile: that helper
+    # turns the council and the code-review phase OFF, and the whole point of
+    # this entry point is to hand back VERIFIED evidence. Scope is bounded by
+    # the brief text, not by disabling the gates that check the work. The run
+    # keeps full depth, so it reports LOKI_TTFV=repo -- the same honest
+    # full-depth signal the no-arg path uses.
+    if [ "$detected_type" = "repo" ]; then
+        local version
+        version=$(get_version)
+        mkdir -p "$LOKI_DIR" 2>/dev/null || true
+        find "$LOKI_DIR" -maxdepth 1 -name 'repo-prd-*.md' -mtime +1 -delete 2>/dev/null || true
+        local repo_prd="$LOKI_DIR/repo-prd-$$.md"
+        synthesize_repo_prd "$repo_prd"
+        prd_file="$repo_prd"
+
+        echo -e "${BOLD}Loki Mode v$version - Repo improvement${NC}"
+        echo ""
+        echo -e "${CYAN}Repo:${NC} $LOKI_REPO_TARGET"
+        echo -e "${DIM}Loki will inspect this project, pick one high-value improvement,${NC}"
+        echo -e "${DIM}implement it, test it, and produce verified evidence.${NC}"
+        echo -e "${DIM}Full depth: quality gates and completion council stay ON.${NC}"
+        echo -e "${DIM}Scope it yourself instead with: loki start \"<what you want>\".${NC}"
+        echo ""
+    fi
+
     # R7: existing-repo no-arg path also gets the TTFV "what next" framing at the
     # end of the run. Execution here is UNCHANGED (full-depth no-PRD codebase
     # analysis + generated-PRD-reuse); we only add accurate end-of-run framing.
     # The signal value ("repo") drives the full-depth wording in run.sh so the
     # message does not falsely claim a lightweight pass.
-    if [ "$detected_type" = "empty" ] && [ -z "${LOKI_TTFV:-}" ]; then
+    if { [ "$detected_type" = "empty" ] || [ "$detected_type" = "repo" ]; } \
+       && [ -z "${LOKI_TTFV:-}" ]; then
         export LOKI_TTFV=repo
     fi
 
@@ -6307,6 +6534,34 @@ else
     DASHBOARD_DEFAULT_HOST="127.0.0.1"
 fi
 
+# EXPOSED BIND REQUIRES AUTH (issue #188).
+#
+# dashboard/auth.py:788 returns True -- allow -- when neither LOKI_ENTERPRISE_AUTH
+# nor OIDC is configured. That makes all 166 Depends(require_scope) endpoints
+# open. On loopback that is defensible: the trust boundary is the machine.
+# Bound to 0.0.0.0 it is not, and NEITHER the Dockerfile NOR the Helm chart set
+# any auth env, so an operator following the shipped chart gets an
+# unauthenticated dashboard on every interface without choosing it.
+#
+# Refuses to start rather than auto-minting a token. An auto-token an operator
+# never sees is worse than a refusal: they believe they are protected, and the
+# credential is sitting in a container they did not know to guard. A refusal is
+# loud, happens at deploy time rather than after exposure, and names the fix.
+#
+# LOKI_DASHBOARD_ALLOW_INSECURE_BIND=1 is the deliberate override, for a cluster
+# whose network policy already bounds ingress. Named so it appears in a diff and
+# a reviewer can ask why it is set.
+_loki_dashboard_bind_is_safe() {
+    local _host="${1:-}"
+    case "$_host" in
+        127.0.0.1|localhost|::1|"") return 0 ;;
+    esac
+    [ "${LOKI_DASHBOARD_ALLOW_INSECURE_BIND:-}" = "1" ] && return 0
+    [ "${LOKI_ENTERPRISE_AUTH:-}" = "true" ] || [ "${LOKI_ENTERPRISE_AUTH:-}" = "1" ] && return 0
+    [ -n "${LOKI_OIDC_ISSUER:-}" ] && [ -n "${LOKI_OIDC_CLIENT_ID:-}" ] && return 0
+    return 1
+}
+
 cmd_dashboard() {
     local subcommand="${1:-}"
 
@@ -6461,6 +6716,23 @@ cmd_dashboard_start() {
         esac
     done
 
+    # Refuse an exposed bind with auth disabled (issue #188). Checked AFTER
+    # argument parsing so an explicit --host is covered, not just the default.
+    if ! _loki_dashboard_bind_is_safe "$host"; then
+        echo -e "${RED}Refusing to start: binding $host with authentication disabled.${NC}" >&2
+        echo "" >&2
+        echo "  Every dashboard endpoint would be reachable on all interfaces with no" >&2
+        echo "  credential. dashboard/auth.py allows all requests when neither" >&2
+        echo "  LOKI_ENTERPRISE_AUTH nor OIDC is configured." >&2
+        echo "" >&2
+        echo "  Pick one:" >&2
+        echo "    LOKI_ENTERPRISE_AUTH=true          enable token auth (loki dashboard token create)" >&2
+        echo "    LOKI_OIDC_ISSUER + _CLIENT_ID      enable OIDC" >&2
+        echo "    --host 127.0.0.1                   bind loopback only" >&2
+        echo "    LOKI_DASHBOARD_ALLOW_INSECURE_BIND=1   accept the exposure deliberately" >&2
+        exit 2
+    fi
+
     # Validate port is numeric
     if [[ ! "$port" =~ ^[0-9]+$ ]]; then
         echo -e "${RED}Invalid port: $port${NC}"
@@ -7967,12 +8239,23 @@ cmd_preview() {
 # build started, so it has NO running-app precondition. Folding it into preview
 # would force preview's running-app gate onto a feature that must not have one.
 #
-# HARD INVARIANT (DEPLOY-PLAN LOCK 5 + BRANCH-LIFECYCLE LOCK B4): PRINT-ONLY.
-# cmd_deploy NEVER runs a cloud CLI (vercel/netlify/flyctl/wrangler) -- not even
-# `--version` -- and NEVER runs `git push` or `gh pr create`. Tool detection is
-# `command -v` ONLY. Loki advises; the human runs the printed command. This keeps
-# the README promise ("Does not deploy -- human runs deploy commands") literally
-# true. Only the clipboard tools (pbcopy/wl-copy/...) and `command -v` may run.
+# HARD INVARIANT (DEPLOY-PLAN LOCK 5 + BRANCH-LIFECYCLE LOCK B4): PRINT-ONLY BY
+# DEFAULT. Without --execute, cmd_deploy NEVER runs a cloud CLI
+# (vercel/netlify/flyctl/wrangler) -- not even `--version`. Tool detection is
+# `command -v` ONLY. Loki advises; the human runs the printed command.
+#
+# --execute (added for receipt-gated deploy) is the ONLY path that runs a deploy
+# command, and it is gated on an Evidence Receipt that VERIFIES this exact tree
+# (see the RECEIPT-GATED EXECUTION block below). The invariants that survive
+# unconditionally, with or without --execute:
+#   - NEVER `git push`, NEVER `gh pr create`. Out of scope entirely.
+#   - NEVER a destructive cloud operation (delete/destroy/teardown/drop),
+#     refused even with a perfect receipt.
+#   - NEVER reads or forwards cloud credentials. The deploy command inherits the
+#     user's already-authenticated CLI session; Loki does not touch credential
+#     files or secret-bearing env vars.
+# Only the clipboard tools (pbcopy/wl-copy/...), `command -v`, and -- under
+# --execute alone -- the gated deploy command itself may run.
 #
 # This whole block is contiguous (helpers + cmd_deploy) so a test can extract it
 # by name anchor, mirroring tests/test-preview-public.sh.
@@ -8193,7 +8476,16 @@ $options
 EOF
 
     if [ "$printed" = true ]; then
-        echo "Loki does not deploy for you. Review, then run the command yourself."
+        # This sentence is TRUE only on the print-only path. Under --execute the
+        # very next thing that happens may be the deploy running, and printing
+        # "Loki does not deploy for you" immediately before Loki deploys is
+        # exactly the kind of false statement this feature exists to not make.
+        # _LOKI_DEPLOY_EXECUTING is set by cmd_deploy for this one decision.
+        if [ "${_LOKI_DEPLOY_EXECUTING:-false}" = true ]; then
+            echo "Reviewing this command against the evidence gate (--execute)."
+        else
+            echo "Loki does not deploy for you. Review, then run the command yourself."
+        fi
         if [ "$do_clip" = true ] && [ -n "$first_cmd" ]; then
             _deploy_copy_clipboard "$first_cmd"
         fi
@@ -8208,9 +8500,493 @@ EOF
     return 1
 }
 
-# cmd_deploy [--dir <path>] [--no-clip] [--help]
+# =============================================================================
+# RECEIPT-GATED EXECUTION (--execute). Everything below is INERT unless the user
+# passes --execute on THIS invocation; the default path stays print-only.
+#
+# The design idea: a deploy is an action a VERIFIED RECEIPT AUTHORIZES. Not
+# "let the agent run gcloud" -- the gate is the evidence artifact we already
+# ship, and it must hold on every one of four independent checks.
+#
+# FAIL CLOSED IS THE WHOLE CONTRACT. Every helper here answers "" or a REFUSE
+# reason when it cannot evaluate its check. An unevaluated gate is not a pass:
+# no receipt, no python3, no gpg, a non-repo dir and an unresolvable anchor all
+# REFUSE. That direction is deliberate -- a gate that cannot tell you whether
+# the tree was verified must not deploy it.
+# =============================================================================
+
+# _deploy_receipt_verdict <proof.json>
+# Echoes exactly one of VERIFIED | UNSIGNED | UNCHECKED | TAMPERED, the same four
+# verdicts loki_remote_verify_receipt reports (see its header at loki:756).
+# The vocabulary is REUSED, not reinvented, because a second set of words for
+# the same four states is how they get collapsed into two.
+#
+# Deliberately NOT loki_remote_verify_receipt itself: that function returns 0 for
+# UNSIGNED, which is right for its caller (submit) and wrong here (integrity is
+# not provenance). We read the same signed/hash_ok/gpg_ok triple and let the
+# CALLER decide which verdicts authorize.
+#
+# hash_ok is read, NOT the top-level `ok` and NOT the exit code: `ok` folds in
+# tree_drift, and proof-verify.py exits 1 on drift alone. Gating on either would
+# refuse every honest receipt whose tree moved -- the false-alarm direction
+# docs/VERIFICATION-COST.md documents. Anything unreadable is TAMPERED-or-worse,
+# so the fallback verdict is UNCHECKED (never a pass).
+_deploy_receipt_verdict() {
+    local pj="$1"
+    local verifier="${_LOKI_SCRIPT_DIR}/lib/proof-verify.py"
+
+    [ -f "$pj" ] || { printf '%s' "UNCHECKED"; return 0; }
+    if [ ! -f "$verifier" ] || ! command -v python3 >/dev/null 2>&1; then
+        printf '%s' "UNCHECKED"; return 0
+    fi
+
+    local out hash_ok gpg_ok signed=0
+    out="$(python3 "$verifier" "$pj" "${TARGET_DIR:-.}" 2>/dev/null || true)"
+
+    # "The verifier did not RUN" and "the verifier says the hash is bad" are
+    # different facts and must not collapse. If they do, a broken python3
+    # produces the verdict TAMPERED -- an accusation of forgery for a check that
+    # never executed. That is the same error the signed path is careful to avoid
+    # with NO_PUBKEY (see loki:852): it sends a user hunting a forgery that never
+    # happened, and trains them to shrug at a real TAMPERED. Unparseable output
+    # is UNCHECKED, which still REFUSES -- fail-closed, honestly labelled.
+    if [ -z "$out" ] || ! printf '%s' "$out" | python3 -c 'import json,sys;json.load(sys.stdin)' >/dev/null 2>&1; then
+        printf '%s' "UNCHECKED"; return 0
+    fi
+
+    hash_ok="$(printf '%s' "$out" | python3 -c 'import json,sys;print(str(json.load(sys.stdin).get("hash_ok",False)).lower())' 2>/dev/null || printf 'false')"
+    gpg_ok="$(printf '%s' "$out" | python3 -c 'import json,sys;print(str(json.load(sys.stdin).get("gpg_ok","n/a")).lower())' 2>/dev/null || printf 'n/a')"
+
+    # Whether the receipt CARRIES a signature is read from the receipt, never
+    # inferred from gpg_ok -- gpg_ok is "n/a" both for "no signature" and for
+    # "gpg missing here", and conflating those mislabels a signed receipt.
+    if python3 -c 'import json,sys;sys.exit(0 if (json.load(open(sys.argv[1])).get("verification") or {}).get("gpg_signature") else 1)' "$pj" 2>/dev/null; then
+        signed=1
+    fi
+
+    if [ "$hash_ok" != "true" ]; then printf '%s' "TAMPERED"; return 0; fi
+    if [ "$signed" -eq 0 ]; then printf '%s' "UNSIGNED"; return 0; fi
+    case "$gpg_ok" in
+        true)  printf '%s' "VERIFIED" ;;
+        # Signed but the signature does not verify: contents or signature were
+        # altered. A missing PUBLIC KEY is a different fact (uncheckable, not an
+        # accusation), so it reports UNCHECKED -- which refuses here anyway.
+        false) if command -v gpg >/dev/null 2>&1 && [ "$(loki_remote_gpg_status "$pj")" = "nopubkey" ]; then
+                   printf '%s' "UNCHECKED"
+               else
+                   printf '%s' "TAMPERED"
+               fi ;;
+        *)     printf '%s' "UNCHECKED" ;;
+    esac
+    return 0
+}
+
+# _deploy_anchor_ok <proof.json> <dir>
+# Echoes "" when the receipt anchors to the tree in front of us, else a REFUSE
+# reason. Two checks, and BOTH are load-bearing:
+#
+#   1. resolve_anchor (autonomy/lib/outcome_ledger.py:122) -- sha algebra proving
+#      base..head is reachable and produces exactly the receipt's file set.
+#   2. head_sha == live HEAD.
+#
+# Check 2 is NOT redundant, and this was MEASURED rather than assumed: on a
+# fixture where the tree advanced one commit past the receipt, resolve_anchor
+# still returned ("anchored", None) -- correctly, because it answers "can I
+# follow this receipt to measure outcomes", not "does this receipt describe the
+# tree I am about to ship". Without check 2 a receipt for an ANCESTOR commit
+# authorizes deploying code it never verified, which is the exact failure this
+# feature exists to prevent.
+_deploy_anchor_ok() {
+    local pj="$1" dir="${2:-.}"
+    command -v python3 >/dev/null 2>&1 || { printf '%s' "anchor could not be evaluated (python3 unavailable)"; return 0; }
+    git -C "$dir" rev-parse --git-dir >/dev/null 2>&1 || { printf '%s' "anchor could not be evaluated (not a git repository)"; return 0; }
+
+    local live_head
+    live_head="$(git -C "$dir" rev-parse HEAD 2>/dev/null || printf '')"
+    [ -n "$live_head" ] || { printf '%s' "anchor could not be evaluated (no HEAD commit)"; return 0; }
+
+    # _LOKI_SCRIPT_DIR is a plain shell var, so it is passed EXPLICITLY here --
+    # relying on it being exported would silently fall back to a bare "lib" path
+    # and report every receipt as unevaluable.
+    PJ="$pj" LIVE_HEAD="$live_head" LOKI_LIB="${_LOKI_SCRIPT_DIR}/lib" \
+        python3 - "$dir" <<'PYANCHOR' 2>/dev/null || printf '%s' "anchor could not be evaluated (anchor check failed to run)"
+import json, os, sys
+sys.dont_write_bytecode = True
+sys.path.insert(0, os.environ.get("LOKI_LIB", ""))
+try:
+    from outcome_ledger import resolve_anchor
+except Exception:
+    print("anchor could not be evaluated (outcome_ledger unavailable)", end="")
+    raise SystemExit(0)
+d = json.load(open(os.environ["PJ"]))
+git = (d.get("facts") or {}).get("git") or {}
+base, head = git.get("base_sha") or "", git.get("head_sha") or ""
+files = git.get("diff") or d.get("files_changed") or []
+if not isinstance(files, list):
+    files = []
+state, reason = resolve_anchor(base, head, files, sys.argv[1])
+if state != "anchored":
+    # TWO DIFFERENT FACTS, and collapsing them makes this gate unusable.
+    #
+    # Measured on this repository: 8 of 9 receipts carry NO facts.git.base_sha,
+    # which matches the "0 of 9 anchored" figure already published in
+    # docs/VERIFICATION-COST.md. Refusing both cases identically means the gate
+    # rejects ~89% of real receipts on anchoring alone -- and a gate that always
+    # refuses teaches users to reach for an override, which is worse than no
+    # gate at all.
+    #
+    #   UNANCHORED  no baseline was recorded. We can prove neither match nor
+    #               mismatch. Refuse by DEFAULT, but let the caller override
+    #               per invocation, and record that nothing was proven.
+    #   MISMATCH    a baseline WAS recorded and it does not resolve to this
+    #               tree. That is positive evidence of the wrong build, and no
+    #               override may bypass it.
+    #
+    # The override covers "unknown", never "known wrong". Emitting a machine
+    # readable prefix so the caller can tell the two apart without parsing prose.
+    #
+    # DISCRIMINATED ON THE REASON NAME, not on `not base`. MEASURED: the receipt
+    # this repo's gate actually selects carries base_sha=4b825dc6 (the empty
+    # tree), so `base` is TRUTHY and a `not base` test files it under MISMATCH --
+    # the one case blocking the repo would stay unoverridable. resolve_anchor
+    # returns base_sha_empty (line 135) BEFORE the greenfield check (line 137),
+    # so reaching greenfield_no_baseline proves base_sha was non-empty.
+    #
+    # Exactly two reasons mean "no baseline was recorded", and together they
+    # cover all 9 receipts here (8 base_sha_empty, 1 greenfield_no_baseline).
+    # Every OTHER reason keeps refusing, including with the flag set:
+    #   not_reachable_from_head, diff_range_mismatch -- positive evidence of a
+    #     DIFFERENT change. Mismatch by construction.
+    #   change_not_committed, sha_not_in_history, head_sha_empty, no_git -- the
+    #     check could not be evaluated, and this gate's stated doctrine is that
+    #     an unevaluable check is a refusal, not a pass.
+    if reason in ("base_sha_empty", "greenfield_no_baseline"):
+        print("UNANCHORED:receipt records no baseline (%s), so it cannot be tied "
+              "to this tree" % reason, end="")
+    else:
+        print("receipt does not anchor to this tree (%s)" % (reason or "unresolvable"), end="")
+elif head != os.environ["LIVE_HEAD"]:
+    # Anchored but STALE: the receipt verified an ancestor, not this tree.
+    print("receipt records a different commit (%s) than HEAD (%s)"
+          % (head[:12], os.environ["LIVE_HEAD"][:12]), end="")
+PYANCHOR
+    return 0
+}
+
+# _deploy_is_destructive <command>
+# Returns 0 (true) if the command names a destructive cloud operation. Refused
+# even under --execute with a perfect receipt: a receipt authorizes shipping the
+# verified tree, never tearing an environment down. Word-boundary matched so
+# "wrangler pages deploy dist" is not caught by "destroy" appearing in a path.
+_deploy_is_destructive() {
+    printf '%s' "${1:-}" | grep -Eqi '(^|[^[:alnum:]_-])(delete|destroy|teardown|down|drop|rm|remove|purge|prune|wipe|scale-down)([^[:alnum:]_-]|$)'
+}
+
+# _deploy_tree_clean <dir>
+# Echoes "" when the working tree is clean, else a REFUSE reason. A dirty tree
+# means the bytes about to ship are NOT the bytes that were verified, which is
+# precisely the failure the receipt gate exists to prevent. A non-repo is
+# UNEVALUABLE, not clean -- it lands in REFUSE with a named reason.
+_deploy_tree_clean() {
+    local dir="${1:-.}"
+    git -C "$dir" rev-parse --git-dir >/dev/null 2>&1 || { printf '%s' "working tree could not be evaluated (not a git repository)"; return 0; }
+    local st rc=0
+    st="$(git -C "$dir" status --porcelain 2>/dev/null)" || rc=$?
+    # A git that could not report is UNEVALUABLE, never "clean" and never
+    # "dirty": naming it dirty invents a specific finding out of a failed
+    # measurement, and the user would go looking for edits that do not exist.
+    [ "$rc" -eq 0 ] || { printf '%s' "working tree could not be evaluated (git status failed)"; return 0; }
+    [ -z "$st" ] || printf '%s' "working tree is dirty ($(printf '%s\n' "$st" | grep -c '') uncommitted change(s))"
+    return 0
+}
+
+# _deploy_latest_receipt <dir>
+# Echoes the newest .loki/proofs/<id>/proof.json path, or "" if none exists.
+# Newest-by-name: proof ids are timestamp-prefixed, so lexical order is
+# chronological. Absence is not an error here; the caller turns "" into the
+# named REFUSE reason "no receipt".
+_deploy_latest_receipt() {
+    local dir="${1:-.}"
+    local proofs="$dir/${LOKI_DIR:-.loki}/proofs"
+    # LOKI_DIR may already be absolute (it is elsewhere in this CLI); prefer it
+    # directly when it resolves, else fall back to the dir-relative form.
+    [ -d "${LOKI_DIR:-}/proofs" ] && proofs="${LOKI_DIR}/proofs"
+    [ -d "$proofs" ] || { printf '%s' ""; return 0; }
+    local newest=""
+    local d
+    for d in "$proofs"/*/; do
+        [ -f "$d/proof.json" ] || continue
+        newest="$d/proof.json"
+    done
+    printf '%s' "$newest"
+    return 0
+}
+
+# _deploy_record <dir> <command> <exit_code> <run_id> <anchor_sha>
+# Writes the executed deploy's own record. A deploy with no record of itself
+# defeats the entire premise of gating on evidence.
+#
+# NOT written into .loki/proofs/: a hand-written JSON there carries no integrity
+# hash, so `loki proof verify` would read it as a TAMPERED receipt -- a
+# self-inflicted false alarm. It lives in .loki/deploys/ where it cannot be
+# mistaken for a verifiable receipt.
+_deploy_record() {
+    local dir="${1:-.}" command="$2" rc="$3" run_id="$4" anchor="$5"
+    # WHICH of the three applied: anchored (the receipt was tied to this tree)
+    # or unanchored_overridden (it was not, and the operator said go anyway).
+    # "refused" needs no value: a refusal never reaches this function, so the
+    # existence of a record already means one of the two above.
+    local anchor_state="${6:-anchored}"
+    local ddir="$dir/.loki/deploys"
+    [ -d "${LOKI_DIR:-}" ] && ddir="${LOKI_DIR}/deploys"
+    mkdir -p "$ddir" 2>/dev/null || return 0
+    local f="$ddir/$(date -u +%Y%m%dT%H%M%SZ)-$$.json"
+    DR_CMD="$command" DR_RC="$rc" DR_RUN="$run_id" DR_ANCHOR="$anchor" DR_OUT="$f" \
+    DR_STATE="$anchor_state" \
+        python3 -c '
+import json, os, datetime
+state = os.environ.get("DR_STATE") or "anchored"
+json.dump({
+    "recorded_at": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    "command": os.environ["DR_CMD"],
+    "exit_code": int(os.environ["DR_RC"]),
+    "authorizing_run_id": os.environ["DR_RUN"],
+    "anchor_sha": os.environ["DR_ANCHOR"],
+    "anchor_state": state,
+    # Spelled out so a reader months later does not have to know the vocabulary
+    # to judge how strong the authorization was.
+    "anchor_proven": state == "anchored",
+}, open(os.environ["DR_OUT"], "w"), indent=2)
+' 2>/dev/null || return 0
+    printf '%s' "$f"
+    return 0
+}
+
+# _deploy_first_installed_command <dir> <type>
+# Echoes the idiomatic deploy command for the FIRST installed CLI of this type,
+# or "" if none is installed. Same ordering and same canonical strings
+# _deploy_print_cloud_options prints, so --execute can never run a command that
+# differs from the one the advisory showed. `command -v` only; no CLI is run.
+_deploy_first_installed_command() {
+    local dir="${1:-.}" type="${2:-}"
+    local options provider cli command docs
+    options="$(_deploy_options_for_type "$type")"
+    while IFS='|' read -r provider cli command docs; do
+        [ -n "$cli" ] || continue
+        if command -v "$cli" >/dev/null 2>&1; then
+            printf '%s' "$command"
+            return 0
+        fi
+    done <<EOF
+$options
+EOF
+    printf '%s' ""
+    return 0
+}
+
+# _deploy_try_execute <dir> <type>
+# The ONLY place a deploy command is ever run. Evaluates the gate, and either
+# executes + records, or REFUSES naming every failed check. Returns the deploy
+# command's exit code on execution, 1 on refusal.
+#
+# Ordering matters: the advisory has ALREADY been printed by the caller, so a
+# refusal still leaves the user with exactly the output they get today.
+_deploy_try_execute() {
+    local dir="${1:-.}" type="${2:-}"
+
+    local command
+    command="$(_deploy_first_installed_command "$dir" "$type")"
+    if [ -z "$command" ]; then
+        echo "" >&2
+        echo -e "${RED}REFUSED: --execute found no installed deploy CLI for this ${type} project.${NC}" >&2
+        echo "  Nothing was run. Install one of the CLIs listed above and re-run." >&2
+        return 1
+    fi
+
+    local reasons
+    reasons="$(_deploy_gate "$dir" "$command")"
+
+    # Split the marker out BEFORE the emptiness test: it is a fact about how
+    # the gate passed, never a reason it failed. Left in, it would refuse every
+    # overridden deploy and print the marker as a reason.
+    local anchor_state="anchored"
+    case "$reasons" in
+        *"$_DEPLOY_ANCHOR_MARKER"*)
+            anchor_state="unanchored_overridden"
+            # Shell substitution, NOT `grep -v`: under `set -e` a grep that
+            # filters out every line exits 1 and aborts the deploy silently --
+            # measured, and it looked exactly like the gate refusing.
+            reasons="${reasons//$_DEPLOY_ANCHOR_MARKER/}"
+            # Drop the blank line the removal left WITHOUT joining the real
+            # reasons together: sed deletes empty lines only, so a refusal that
+            # also carries other reasons still prints them one per line.
+            reasons="$(printf '%s' "$reasons" | sed '/^[[:space:]]*$/d')"
+            ;;
+    esac
+
+    if [ -n "$reasons" ]; then
+        echo ""
+        echo -e "${RED}REFUSED: not deploying. The evidence gate did not pass.${NC}" >&2
+        echo "  Would have run: ${command}" >&2
+        echo "" >&2
+        # printf '%s\n', NOT '%s': command substitution strips the trailing
+        # newline, and `read` then DISCARDS a final unterminated line -- so a
+        # single-reason refusal printed no reasons at all. A refusal that names
+        # nothing is the one thing this gate must never do.
+        printf '%s\n' "$reasons" | while IFS= read -r r; do
+            [ -n "$r" ] && echo "  - ${r}" >&2
+        done
+        echo "" >&2
+        echo "  A check that could not be EVALUATED is a refusal, not a pass." >&2
+        echo "  Nothing was executed. The advisory command above is unchanged." >&2
+        return 1
+    fi
+
+    # Gate passed. Capture the authorizing receipt's identity for the record.
+    local pj run_id anchor
+    pj="$(_deploy_latest_receipt "$dir")"
+    run_id="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("run_id") or "")' "$pj" 2>/dev/null || printf '')"
+    anchor="$(git -C "$dir" rev-parse HEAD 2>/dev/null || printf '')"
+
+    echo ""
+    if [ "$anchor_state" = "unanchored_overridden" ]; then
+        # "VERIFIED this tree" would be FALSE here: the receipt's checks passed,
+        # but nothing tied it to the code about to ship. Saying so is the whole
+        # point of allowing the override rather than weakening the gate.
+        echo -e "${YELLOW}Evidence gate PASSED with the anchor UNPROVEN (--allow-unanchored).${NC}"
+        echo "  Receipt ${run_id:-unknown} passed its own checks, but records no baseline,"
+        echo "  so it was NOT tied to this tree (${anchor:0:12}). You authorized this."
+    else
+        echo -e "${GREEN}Evidence gate PASSED.${NC} Receipt ${run_id:-unknown} VERIFIED this tree (${anchor:0:12})."
+    fi
+    echo "Running: ${command}"
+    echo ""
+
+    # Run in the project dir. No credential env var is read, set, or forwarded:
+    # the command inherits the user's already-authenticated CLI session as-is.
+    #
+    # eval is used because the canonical commands carry their own flags
+    # ("vercel --prod", "netlify deploy --prod --dir=<out>") and must word-split.
+    # The string is NOT user input: it comes from the hardcoded
+    # _deploy_options_for_type table, and the only path here has already passed
+    # the destructive-operation check in _deploy_gate.
+    local rc=0
+    ( cd "$dir" && eval "$command" ) || rc=$?
+
+    local rec
+    rec="$(_deploy_record "$dir" "$command" "$rc" "${run_id:-unknown}" "${anchor:-unknown}" \
+        "$anchor_state")"
+    echo ""
+    if [ "$rc" -eq 0 ]; then
+        echo -e "${GREEN}Deploy command exited 0.${NC}"
+    else
+        echo -e "${RED}Deploy command exited ${rc}.${NC}" >&2
+    fi
+    if [ -n "$rec" ]; then
+        echo "Deploy record: ${rec}"
+    else
+        # The deploy ALREADY RAN. Failing to record it silently is the exact
+        # thing this feature exists to prevent -- an executed deploy with no
+        # evidence of itself -- so it is reported LOUDLY rather than swallowed.
+        # Not an error exit: the deploy's own exit code is the honest verdict on
+        # the deploy, and overriding it would misreport what happened.
+        echo -e "${RED}WARNING: the deploy ran but its record could NOT be written.${NC}" >&2
+        echo "  Command: ${command}" >&2
+        echo "  Authorizing receipt run_id: ${run_id:-unknown}; anchor: ${anchor:-unknown}" >&2
+        echo "  Record this yourself: a deploy with no record of itself is unevidenced." >&2
+    fi
+    return "$rc"
+}
+
+# Emitted by _deploy_gate (not a refusal reason) when the anchor was UNPROVEN
+# and the operator overrode it. The gate runs inside $( ), so this travels on
+# stdout; a global assigned in the subshell would not survive.
+_DEPLOY_ANCHOR_MARKER="__LOKI_ANCHOR_UNPROVEN__"
+
+# _deploy_gate <dir> <command>
+# THE GATE. Echoes "" when all four checks pass, else the REFUSE reason(s), one
+# per line. Every check is evaluated so a refusal names everything wrong at once
+# rather than making the user re-run to discover the next problem.
+# The opt-in (check 4) is the CALLER's --execute flag and is not re-checked here.
+_deploy_gate() {
+    local dir="${1:-.}" command="${2:-}"
+    local reasons=""
+
+    # Hard limit, checked FIRST: no receipt authorizes a destructive operation.
+    if _deploy_is_destructive "$command"; then
+        reasons="${reasons}destructive operation refused: no receipt authorizes delete/destroy/teardown/drop
+"
+    fi
+
+    # An UNFILLED <placeholder> is a command written for a HUMAN to complete,
+    # not one to run. Executing it is at best a shell syntax error and at worst
+    # an unintended redirection ("--dir=<build-output>" redirects stdin from a
+    # file named build-output). Guessing the value would be worse still: we
+    # would deploy a directory nobody chose.
+    case "$command" in
+        *"<"*">"*) reasons="${reasons}deploy command contains an unfilled placeholder -- run it yourself with the real value: ${command}
+" ;;
+    esac
+
+    local pj
+    pj="$(_deploy_latest_receipt "$dir")"
+    if [ -z "$pj" ]; then
+        reasons="${reasons}no Evidence Receipt found (nothing has verified this tree)
+"
+    else
+        local verdict
+        verdict="$(_deploy_receipt_verdict "$pj")"
+        case "$verdict" in
+            VERIFIED) : ;;
+            UNSIGNED)  reasons="${reasons}receipt is UNSIGNED: integrity holds but provenance is unproven (set LOKI_PROOF_GPG_KEY; docs/SIGNED-RECEIPTS.md)
+" ;;
+            UNCHECKED) reasons="${reasons}receipt is UNCHECKED: its signature could not be evaluated here, so nothing was proven
+" ;;
+            TAMPERED)  reasons="${reasons}receipt is TAMPERED: its integrity hash does not match its contents
+" ;;
+            *)         reasons="${reasons}receipt verdict could not be determined
+" ;;
+        esac
+        local anchor_reason
+        anchor_reason="$(_deploy_anchor_ok "$pj" "$dir")"
+        case "$anchor_reason" in
+            UNANCHORED:*)
+                # Nothing was PROVEN either way. Overridable per invocation, and
+                # only the UNANCHORED-prefixed line is dropped: discarding the
+                # whole anchor check (or skipping the call) would also swallow
+                # the stale-receipt refusal, silently turning this flag into
+                # "skip anchoring entirely".
+                if [ "${LOKI_DEPLOY_ALLOW_UNANCHORED:-false}" = "true" ]; then
+                    # Emitted on STDOUT as a non-reason marker, not stored in a
+                    # variable: _deploy_gate is called inside $( ), so a global
+                    # assigned here dies with the subshell. The caller strips
+                    # this line before treating what remains as refusal reasons.
+                    reasons="${reasons}${_DEPLOY_ANCHOR_MARKER}
+"
+                else
+                    reasons="${reasons}${anchor_reason#UNANCHORED:} (re-run with --allow-unanchored to deploy anyway; nothing about the tree will have been proven)
+"
+                fi
+                ;;
+            "") : ;;
+            *)  # Positive evidence of the wrong build. No flag bypasses this.
+                reasons="${reasons}${anchor_reason}
+" ;;
+        esac
+    fi
+
+    local dirty
+    dirty="$(_deploy_tree_clean "$dir")"
+    [ -n "$dirty" ] && reasons="${reasons}${dirty}
+"
+
+    printf '%s' "$reasons"
+    return 0
+}
+
+# cmd_deploy [--dir <path>] [--no-clip] [--execute] [--help]
 # Advisory orchestration: detect project type + CI/CD pipeline + installed cloud
-# CLIs, then PRINT the canonical deploy command(s). PRINT-ONLY (see block header).
+# CLIs, then PRINT the canonical deploy command(s). PRINT-ONLY BY DEFAULT.
 # Placed LAST in the contiguous deploy block (all helpers above it) so the SDET
 # can extract from the first helper def to the close of cmd_deploy and capture the
 # whole self-contained unit (mirrors test-preview-public.sh, where cmd_preview is
@@ -8218,31 +8994,90 @@ EOF
 cmd_deploy() {
     local dir="${TARGET_DIR:-.}"
     local do_clip=true
+    local do_execute=false
+    # `local` so an AMBIENT LOKI_DEPLOY_ALLOW_UNANCHORED=true in the environment
+    # cannot opt in: it is reset to false on every invocation and only the flag
+    # below sets it. Same rule --execute already follows -- no env var or config
+    # file alone weakens this gate.
+    local LOKI_DEPLOY_ALLOW_UNANCHORED=false
 
     # Arg parse (mirror cmd_preview: lenient on unknown args -> no behavior drift).
     while [ $# -gt 0 ]; do
         case "${1:-}" in
             --help|-h|help)
-                echo -e "${BOLD}Loki Mode -- advisory deploy command (print-only)${NC}"
+                echo -e "${BOLD}Loki Mode -- deploy command advisory (print-only by default)${NC}"
                 echo ""
-                echo "Usage: loki deploy [--dir <path>] [--no-clip]"
+                echo "Usage: loki deploy [--dir <path>] [--no-clip] [--execute]"
                 echo ""
                 echo "Detects your project type and your installed cloud CLI (and any"
                 echo "CI/CD pipeline), then PRINTS the exact deploy command for YOU to run."
-                echo "It is advisory only: it NEVER deploys, NEVER runs a cloud CLI (not"
-                echo "even --version), and NEVER runs 'git push'. Loki does not access your"
-                echo "cloud account. You run the printed command. Detection is read-only."
+                echo "By default this is print-only and advisory: it NEVER deploys and"
+                echo "NEVER runs a cloud CLI (not even --version). It NEVER runs"
+                echo "'git push' on ANY path. Detection is read-only. You run the"
+                echo "printed command."
                 echo ""
                 echo "If a CI/CD pipeline (GitHub Actions, GitLab CI, Jenkins, CircleCI,"
                 echo "Azure Pipelines, Bitbucket) is detected, the primary advice is the"
                 echo "git push + pull-request path, because your pipeline deploys on merge."
                 echo ""
+                echo -e "${BOLD}--execute: a deploy authorized by a verified receipt${NC}"
+                echo ""
+                echo "With --execute, Loki runs the detected deploy command ONLY when ALL"
+                echo "of these hold. Any one failing REFUSES, and the refusal names which:"
+                echo "  1. An Evidence Receipt exists for this tree and its integrity hash"
+                echo "     matches (hash_ok)."
+                echo "  2. Its verdict is VERIFIED. UNSIGNED, UNCHECKED and TAMPERED all"
+                echo "     refuse -- integrity is not provenance."
+                echo "  3. The receipt anchors to the commit being deployed. A receipt for"
+                echo "     a different commit does not authorize this deploy."
+                echo "     Two outcomes are distinguished here, and only one is overridable:"
+                echo "       UNANCHORED  the receipt records no baseline, so neither a match"
+                echo "                   nor a mismatch can be proven. Refuses by default;"
+                echo "                   --allow-unanchored proceeds and records that the"
+                echo "                   anchor was never proven."
+                echo "       MISMATCH    a baseline IS recorded and resolves to a different"
+                echo "                   tree. That is evidence of the wrong build, and"
+                echo "                   --allow-unanchored does NOT bypass it."
+                echo "  4. You passed --execute on THIS invocation. No env var or config"
+                echo "     file alone can opt in."
+                echo ""
+                echo "It FAILS CLOSED: if a check cannot be evaluated at all (no receipt,"
+                echo "gpg unavailable, anchor unresolvable, not a git repo), that is a"
+                echo "REFUSAL, not a pass. A refusal still prints the advisory command."
+                echo ""
+                echo "Hard limits, with or without --execute:"
+                echo "  - NEVER runs a destructive cloud operation (delete, destroy,"
+                echo "    teardown, drop). Refused even with a valid receipt."
+                echo "  - NEVER runs 'git push' and NEVER creates a PR. Out of scope."
+                echo "  - NEVER reads or forwards cloud credentials. The deploy command"
+                echo "    inherits your already-authenticated CLI session."
+                echo "  - REFUSES if the working tree is dirty: deploying something other"
+                echo "    than what was verified is the exact failure this prevents."
+                echo ""
+                echo "Every executed deploy writes its own record to .loki/deploys/:"
+                echo "the command, its exit code, the authorizing receipt's run_id, the"
+                echo "resolved anchor, and anchor_state -- so a reader can tell later"
+                echo "whether the anchor was proven or explicitly overridden."
+                echo ""
                 echo "Options:"
                 echo "  --dir <path>   Project directory to scan (default: current dir)"
                 echo "  --no-clip      Do not copy the idiomatic command to the clipboard"
+                echo "  --execute      Run the deploy command if the receipt gate passes"
+                echo "  --allow-unanchored"
+                echo "                 Proceed when the receipt records NO baseline (nothing"
+                echo "                 about this tree is proven). Never bypasses a recorded"
+                echo "                 mismatch. Per-invocation only; no env var opts in."
                 echo "  --help, -h     Show this help and exit"
                 return 0
                 ;;
+            --execute)
+                do_execute=true
+                ;;
+            --allow-unanchored)
+                # Per-invocation, like --execute: exported for the gate to read,
+                # never persisted and never settable by config alone.
+                LOKI_DEPLOY_ALLOW_UNANCHORED=true
+                ;;
             --dir)
                 # Guard against a missing OR flag-shaped value: an unguarded
                 # shift when --dir is the last arg underflows under set -e, and a
@@ -8263,6 +9098,10 @@ cmd_deploy() {
     # Resolve to '.' if the chosen dir does not exist (honest, no crash).
     [ -d "$dir" ] || dir="."
 
+    # Tells the advisory printer which closing sentence is TRUE for this run.
+    # Scoped to this invocation only.
+    local _LOKI_DEPLOY_EXECUTING="$do_execute"
+
     # Detect CI/CD pipeline FIRST (BRANCH-LIFECYCLE LOCK B3 precedence).
     local cicd=""
     cicd="$(_deploy_detect_cicd "$dir" || true)"
@@ -8327,6 +9166,21 @@ cmd_deploy() {
                 : # No installed cloud CLI; the pipeline path already advised. Fine.
             fi
         fi
+        # --execute applies to the CLOUD command only. git push / PR creation
+        # stay out of scope entirely, so on the pipeline path --execute never
+        # touches the primary (git) advice above -- it can only run the
+        # secondary cloud command, and only if the receipt gate passes.
+        if [ "$do_execute" = true ]; then
+            if [ -n "$type" ]; then
+                _deploy_try_execute "$dir" "$type"
+                return $?
+            fi
+            echo "" >&2
+            echo -e "${RED}REFUSED: --execute has nothing to run here.${NC}" >&2
+            echo "  No deployable project type detected, and Loki never runs 'git push'" >&2
+            echo "  or creates a PR. Run the git advice above yourself." >&2
+            return 1
+        fi
         return 0
     fi
 
@@ -8346,6 +9200,14 @@ cmd_deploy() {
     # honest install hint) when NO matching CLI is installed.
     local rc=0
     _deploy_print_cloud_options "$dir" "$type" "$do_clip" "true" || rc=$?
+
+    # Execute ONLY if the user opted in on THIS invocation and the advisory
+    # above found something to run. The advisory has already printed, so a
+    # refusal below still leaves the user with today's output.
+    if [ "$do_execute" = true ] && [ "$rc" -eq 0 ]; then
+        _deploy_try_execute "$dir" "$type"
+        return $?
+    fi
     return $rc
 }
 
@@ -14205,6 +15067,35 @@ $brief_text
 BRIEFEOF
 }
 
+# Build a bounded input for `loki start <repo-directory>`. This intentionally
+# contains no caller-controlled path: repository identity comes from cwd, while
+# the task remains stable, reviewable, and safe to render into a prompt.
+synthesize_repo_prd() {
+    local out_file="$1"
+    mkdir -p "$(dirname "$out_file")" 2>/dev/null || true
+    cat > "$out_file" <<'REPOEOF'
+# Existing Repository Improvement
+
+## Outcome
+Inspect this repository's instructions, product signals, and current tests.
+Select one small, high-value user-facing improvement and implement it completely.
+
+## Success Criteria
+- The improvement has a clear user outcome and a bounded diff.
+- Focused tests or checks prove the changed behavior.
+- Existing unrelated work is preserved.
+- Loki's normal outcome evidence identifies what changed and what passed.
+
+## Constraints
+- Make one coherent improvement, not a broad rewrite.
+- Reuse the repository's established architecture and dependencies.
+- Keep the change easy to review and roll back.
+- Do not claim deployment, adoption, or customer value without evidence.
+
+**Mode:** Existing repository improvement (full verification)
+REPOEOF
+}
+
 # Quick mode - lightweight single-task execution
 cmd_quick() {
     # v7.6.3 B-11 fix: --help previously fell through to provider invocation
@@ -34288,6 +35179,13 @@ cmd_proof() {
             echo "  show <id>            Pretty-print .loki/proofs/<id>/proof.json"
             echo "  verify <id>          Re-check a receipt against the repo (tamper + drift);"
             echo "                       exit 0 clean, 1 tamper/drift. Verify it yourself."
+            echo ""
+            echo "Options for 'verify':"
+            echo "  --human              Render the verdict and every failure reason as prose"
+            echo "  --jwks <url|file>    Also check the receipt's attestation against a published"
+            echo "                       key set. Accepts a server URL or a local jwks.json, so a"
+            echo "                       third party can check WHO produced a receipt with no API"
+            echo "                       token, no gpg key import, and no network."
             echo "  md <id>              Paste-able Markdown for a PR comment or Slack
   open <id>            Open .loki/proofs/<id>/index.html in a browser"
             echo "  share <id>           Publish the proof page as a GitHub Gist (opt-in)"
@@ -34503,14 +35401,31 @@ PYEOF
             # stdout verbatim, are unaffected. The flag is STRIPPED from the
             # positional args rather than assumed at a fixed index, so it works
             # before or after the id.
-            local _pv_human=0 _pv_args=()
-            local _pv_a
+            # --jwks <url-or-file> additionally checks the receipt's
+            # attestation against a published key set. This is the third-party
+            # path: an auditor who was handed a proof.json can check WHO
+            # produced it without running a build, without our API token, and
+            # without importing a gpg key. A FILE is accepted as well as a URL
+            # so an air-gapped reviewer, handed the receipt and the key set on
+            # disk, can still verify -- requiring the network would exclude
+            # exactly the reviewer who most needs this.
+            local _pv_human=0 _pv_jwks="" _pv_args=()
+            local _pv_a _pv_want_jwks=0
             for _pv_a in "$@"; do
+                if [ "$_pv_want_jwks" -eq 1 ]; then
+                    _pv_jwks="$_pv_a"; _pv_want_jwks=0; continue
+                fi
                 case "$_pv_a" in
                     --human) _pv_human=1 ;;
+                    --jwks) _pv_want_jwks=1 ;;
+                    --jwks=*) _pv_jwks="${_pv_a#--jwks=}" ;;
                     *) _pv_args+=("$_pv_a") ;;
                 esac
             done
+            if [ "$_pv_want_jwks" -eq 1 ]; then
+                echo -e "${RED}--jwks needs a URL or file path.${NC}" >&2
+                exit 2
+            fi
             set -- "${_pv_args[@]+"${_pv_args[@]}"}"
 
             local id="${1:-}"
@@ -34531,12 +35446,53 @@ PYEOF
                 echo -e "${RED}Verifier not found (autonomy/lib/proof-verify.py).${NC}"
                 exit 2
             fi
+            # `|| _pv_rc=$?` is load-bearing: this script runs under `set -e`
+            # (loki:22), so a bare call to a verifier that exits 1 on drift --
+            # its NORMAL result -- aborts the whole command before the exit
+            # status can be read. Without the guard the attestation block below
+            # is unreachable on exactly the receipts it exists to check.
+            local _pv_rc=0
             if [ "$_pv_human" -eq 1 ]; then
-                python3 "$verifier" --human "$pj" "${TARGET_DIR:-.}"
+                python3 "$verifier" --human "$pj" "${TARGET_DIR:-.}" || _pv_rc=$?
             else
-                python3 "$verifier" "$pj" "${TARGET_DIR:-.}"
+                python3 "$verifier" "$pj" "${TARGET_DIR:-.}" || _pv_rc=$?
+            fi
+
+            # The attestation check runs AFTER, and can only make the verdict
+            # worse, never better. A valid attestation does not excuse a failed
+            # integrity hash: the signature proves who produced the bytes, not
+            # that the bytes are internally consistent. Folding the two together
+            # would let a signed-but-tampered receipt exit 0.
+            if [ -n "$_pv_jwks" ]; then
+                local _pv_att
+                _pv_att="$(loki_proof_attestation_check "$pj" "$_pv_jwks")"
+                case "$_pv_att" in
+                    ok)
+                        echo "attestation: VERIFIED against ${_pv_jwks}" >&2
+                        echo "  Proven: these bytes were signed by the holder of a key in that set." >&2
+                        echo "  NOT proven: that the code is correct. A receipt records which checks ran." >&2
+                        ;;
+                    bad)
+                        echo -e "${RED}attestation: FAILED -- the token does not cover these bytes.${NC}" >&2
+                        echo "  Either the receipt was altered after signing, or the attestation" >&2
+                        echo "  belongs to a different run. Do not trust this receipt." >&2
+                        _pv_rc=1
+                        ;;
+                    none)
+                        echo -e "${YELLOW}attestation: ABSENT -- this receipt carries no attestation.${NC}" >&2
+                        echo "  Nothing was checked against ${_pv_jwks}. The receipt may still be" >&2
+                        echo "  gpg-signed; this says only that it has no JWKS attestation." >&2
+                        ;;
+                    *)
+                        # Unreachable key set, unreadable file, missing python
+                        # deps. NOT a verdict: an absent measurement must never
+                        # read as either a pass or an accusation.
+                        echo -e "${YELLOW}attestation: NOT CHECKED -- could not read a key set from ${_pv_jwks}.${NC}" >&2
+                        echo "  This is not a failure of the receipt. Nothing was proven either way." >&2
+                        ;;
+                esac
             fi
-            exit $?
+            exit "$_pv_rc"
             ;;
         open)
             local id="${1:-}"