loki-mode 9.17.2 → 9.18.4

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Autonomous spec-driven build system with a built-in trust layer. It does not call work done until it is verified (RARV-C closure loop, 8 quality gates, completion council, verified-completion evidence gate). Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v9.17.2
+# Loki Mode v9.18.4
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -470,4 +470,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v9.17.2 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v9.18.4 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-9.17.2
+9.18.4

package/autonomy/loki

@@ -556,6 +556,355 @@ require_jq() {
     fi
 }
 
+# --- remote submit (loki start --remote <url>) --------------------------------
+#
+# Submits a spec to a deployed trigger-server's POST /jobs instead of building
+# locally, then polls GET /jobs/<id> until the job reaches a terminal state.
+#
+# The bearer token is read from LOKI_REMOTE_TOKEN or LOKI_REMOTE_TOKEN_FILE and
+# is NEVER placed in argv (the process list is world-readable) and never logged.
+# It reaches curl through `--config -` on stdin.
+
+# Extract the host from a URL: strip scheme, userinfo, then cut at the first
+# '/', ':' or '?'. Compared EXACTLY, never by prefix -- "http://localhost*"
+# would happily accept http://localhost.evil.com and leak a bearer token.
+loki_remote_host() {
+    local url="$1"
+    local rest="${url#*://}"
+    rest="${rest##*@}"
+    rest="${rest%%/*}"
+    rest="${rest%%\?*}"
+    # Strip a :port, but keep an [::1] literal intact.
+    case "$rest" in
+        \[*\]*) rest="${rest%%\]*}]" ;;
+        *) rest="${rest%%:*}" ;;
+    esac
+    printf '%s' "$rest"
+}
+
+loki_remote_is_local_host() {
+    case "$(loki_remote_host "$1")" in
+        localhost|127.0.0.1|\[::1\]|::1) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+# Read the token from env or a file. Never echoed, never passed as an argument.
+loki_remote_token() {
+    if [ -n "${LOKI_REMOTE_TOKEN:-}" ]; then
+        printf '%s' "$LOKI_REMOTE_TOKEN"
+        return 0
+    fi
+    if [ -n "${LOKI_REMOTE_TOKEN_FILE:-}" ] && [ -f "${LOKI_REMOTE_TOKEN_FILE}" ]; then
+        # Mounted secrets end with a newline; strip it or every compare fails.
+        tr -d '\r\n' < "${LOKI_REMOTE_TOKEN_FILE}"
+        return 0
+    fi
+    return 1
+}
+
+# curl with the Authorization header fed on stdin via --config, so the token
+# never appears in argv. Usage: loki_remote_curl <token> <curl-args...>
+loki_remote_curl() {
+    local _tok="$1"; shift
+    printf 'header = "Authorization: Bearer %s"\n' "$_tok" \
+        | curl --config - "$@"
+}
+
+loki_remote_submit() {
+    local url="$1"
+    local spec="$2"
+
+    url="${url%/}"
+
+    if [ -z "$spec" ]; then
+        echo -e "${RED}loki: --remote needs a spec to submit${NC}" >&2
+        echo "  e.g. loki start ./prd.md --remote $url" >&2
+        return 1
+    fi
+
+    # A bearer token over plaintext to a remote host is a credential leak.
+    # Loopback is exempt (it never leaves the machine); anything else needs an
+    # explicit opt-in so the leak is a decision, not an accident.
+    case "$url" in
+        http://*)
+            if ! loki_remote_is_local_host "$url" && [ "${LOKI_REMOTE_INSECURE:-}" != "1" ]; then
+                echo -e "${RED}loki: refusing to send a bearer token over plaintext http to $(loki_remote_host "$url")${NC}" >&2
+                echo "  Use https://, or set LOKI_REMOTE_INSECURE=1 to override." >&2
+                return 1
+            fi
+            ;;
+    esac
+
+    local token
+    if ! token="$(loki_remote_token)" || [ -z "$token" ]; then
+        echo -e "${RED}loki: no remote token configured${NC}" >&2
+        echo "  Set LOKI_REMOTE_TOKEN or LOKI_REMOTE_TOKEN_FILE (never pass it as an argument)." >&2
+        return 1
+    fi
+
+    require_jq || return 1
+
+    local body resp
+    body="$(jq -nc --arg s "$spec" '{spec:$s}')"
+
+    echo "Submitting to $url ..."
+    if ! resp="$(loki_remote_curl "$token" -fsS --max-time 30 \
+            -H "Content-Type: application/json" \
+            -X POST --data "$body" "$url/jobs" 2>&1)"; then
+        # NEVER fall back to a local run: a user who asked for remote and
+        # silently got a local build would pay local spend they did not ask for.
+        echo -e "${RED}loki: remote submit failed: $url/jobs${NC}" >&2
+        echo "  Is the server reachable, and is LOKI_REMOTE_TOKEN correct?" >&2
+        echo "  Not falling back to a local build (you asked for --remote)." >&2
+        return 1
+    fi
+
+    local job_id
+    job_id="$(printf '%s' "$resp" | jq -r '.id // empty' 2>/dev/null)"
+    if [ -z "$job_id" ]; then
+        echo -e "${RED}loki: remote accepted the request but returned no job id${NC}" >&2
+        return 1
+    fi
+    echo "Job $job_id queued on $url"
+
+    local poll_sec="${LOKI_REMOTE_POLL_SEC:-5}"
+    local max_polls="${LOKI_REMOTE_MAX_POLLS:-720}"
+    local status="" last="" i=0
+    while [ "$i" -lt "$max_polls" ]; do
+        i=$((i+1))
+        if ! resp="$(loki_remote_curl "$token" -fsS --max-time 30 \
+                "$url/jobs/$job_id" 2>&1)"; then
+            echo -e "${RED}loki: lost contact with $url while polling job $job_id${NC}" >&2
+            return 1
+        fi
+        status="$(printf '%s' "$resp" | jq -r '.status // empty' 2>/dev/null)"
+        if [ "$status" != "$last" ]; then
+            echo "  [$job_id] $status"
+            last="$status"
+        fi
+        case "$status" in
+            passed|failed|unknown|error|rejected*)
+                break
+                ;;
+        esac
+        sleep "$poll_sec"
+    done
+
+    # A TAMPERED receipt fails the whole submit regardless of the job status:
+    # reporting a build as successful while holding proof that its own receipt
+    # was altered would make the receipt decorative.
+    local _receipt_rc=0
+    loki_remote_fetch_receipt "$url" "$token" "$job_id" || _receipt_rc=$?
+    if [ "$_receipt_rc" -ne 0 ]; then
+        echo -e "${RED}loki: remote job $job_id returned a receipt that failed verification${NC}" >&2
+        return 1
+    fi
+
+    # Gate on the BUILD's outcome, not on "a build was launched". The server
+    # reports passed / failed / unknown as distinct terminal statuses (see
+    # JOB_TERMINAL_STATUSES in trigger-server.py). Anything that is not
+    # "passed" exits non-zero so a CI pipeline cannot go green on a failed
+    # build. "unknown" -- the build detached and its exit code was never
+    # observed -- fails CLOSED: an outcome nobody observed is not a pass.
+    case "$status" in
+        passed) return 0 ;;
+        unknown)
+            echo -e "${RED}loki: remote job $job_id outcome UNKNOWN${NC}" >&2
+            echo "  The build detached and its exit code was never observed." >&2
+            echo "  An unobserved outcome is not a pass; treating it as a failure." >&2
+            return 1
+            ;;
+        "")     echo -e "${RED}loki: job $job_id did not reach a terminal status${NC}" >&2; return 1 ;;
+        *)      echo -e "${RED}loki: remote job $job_id failed: $status${NC}" >&2; return 1 ;;
+    esac
+}
+
+# Fetch the Evidence Receipt and write it where a local run puts it, so
+# `loki proof` works on a remote build, then VERIFY it here -- on the machine
+# that did NOT produce it. That is the entire point: a receipt you can only
+# check by asking the builder whether it is good proves nothing.
+#
+# Returns 0 when the receipt verified or is honestly reported as unverifiable,
+# and NON-ZERO when the receipt is TAMPERED. Absence of a receipt is not a
+# failure (a build may legitimately produce none); a receipt that fails its
+# own integrity check is.
+loki_remote_fetch_receipt() {
+    local url="$1" token="$2" job_id="$3"
+    local dir="${LOKI_DIR:-.loki}/proofs/$job_id"
+    local tmp resp
+
+    if ! resp="$(loki_remote_curl "$token" -fsS --max-time 30 \
+            "$url/jobs/$job_id/proof" 2>/dev/null)"; then
+        echo "  (no evidence receipt available from $url for $job_id)" >&2
+        return 0
+    fi
+    # Only write something that parses as JSON: a proxy error page must not
+    # land in .loki/proofs/ looking like a receipt.
+    if ! printf '%s' "$resp" | jq -e . >/dev/null 2>&1; then
+        echo "  (remote returned a non-JSON receipt for $job_id; not written)" >&2
+        return 0
+    fi
+    mkdir -p "$dir"
+    tmp="$dir/.proof.json.$$"
+    printf '%s' "$resp" > "$tmp" && mv "$tmp" "$dir/proof.json"
+    echo "  Evidence Receipt: $dir/proof.json"
+
+    loki_remote_verify_receipt "$dir/proof.json"
+}
+
+# Verify a fetched receipt locally and print exactly what was and was not
+# proven. Exit 1 ONLY on tamper.
+#
+# THREE OUTCOMES, NEVER COLLAPSED INTO TWO:
+#   VERIFIED  a gpg signature is present and valid  -> integrity AND provenance
+#   UNSIGNED  the hash matches, no signature        -> integrity ONLY
+#   TAMPERED  hash mismatch or bad signature        -> exit 1
+#
+# UNSIGNED is not a weaker VERIFIED, it is a different claim. docs/VERIFICATION-COST.md
+# records that the unsigned path is FORGEABLE: whoever rewrites the facts and
+# the headline into a mutually consistent lie and recomputes the hash passes
+# every check here. A user who trusts a "verified" label meaning only "these
+# bytes are self-consistent" is worse off than one who knows they hold no proof,
+# because they will stop looking. So the word "verified" is never printed for an
+# unsigned receipt.
+#
+# There is a FOURTH state and it must not be folded into UNSIGNED: a signature
+# is present but gpg is not installed here, so it could not be checked. Saying
+# UNSIGNED there would be a false statement about the receipt (it IS signed),
+# and saying VERIFIED would be a false statement about this machine (it checked
+# nothing). It gets its own line and never claims verification.
+# Ask gpg WHY a signature failed. Echoes "nopubkey" when the signing key is
+# absent (uncheckable), "" otherwise (a genuinely bad signature, or we could
+# not tell). Fails toward "" so an unclear answer keeps the loud TAMPERED
+# verdict rather than silently downgrading a real forgery to a soft warning.
+loki_remote_gpg_status() {
+    local pj="$1"
+    local d="${TMPDIR:-/tmp}/loki-sigcheck.$$"
+    mkdir -p "$d" || return 0
+    python3 - "$pj" "$d" <<'PY' 2>/dev/null || { rm -rf "$d"; return 0; }
+import json, sys, os
+proof = json.load(open(sys.argv[1]))
+d = sys.argv[2]
+sig = (proof.get("verification") or {}).get("gpg_signature") or ""
+proof.pop("verification", None)
+open(os.path.join(d, "canon.bin"), "wb").write(
+    json.dumps(proof, sort_keys=True, separators=(",", ":")).encode())
+open(os.path.join(d, "sig.asc"), "w").write(sig)
+PY
+    local st
+    st="$(gpg --status-fd 1 --verify "$d/sig.asc" "$d/canon.bin" 2>/dev/null)"
+    rm -rf "$d"
+    case "$st" in
+        *NO_PUBKEY*) printf 'nopubkey' ;;
+        *) printf '' ;;
+    esac
+}
+
+loki_remote_verify_receipt() {
+    local pj="$1"
+    local verifier="${_LOKI_SCRIPT_DIR}/lib/proof-verify.py"
+
+    if [ ! -f "$verifier" ] || ! command -v python3 >/dev/null 2>&1; then
+        echo "  NOT VERIFIED: no local verifier available (need python3 and lib/proof-verify.py)" >&2
+        return 0
+    fi
+
+    # Whether the receipt CARRIES a signature is read from the receipt itself,
+    # not inferred from the verifier's gpg verdict. proof-verify.py reports
+    # gpg_ok="n/a" for two distinct situations -- no signature present, and gpg
+    # unavailable on this machine -- so gpg_ok alone cannot tell them apart, and
+    # collapsing them is exactly how a signed receipt gets mislabelled UNSIGNED.
+    local signed=0
+    if jq -e '.verification.gpg_signature // empty' "$pj" >/dev/null 2>&1; then
+        signed=1
+    fi
+
+    # Deliberately NOT gated on the verifier's exit code or its `ok` field.
+    # `ok` includes diff_drift, re-derived against the LOCAL repo -- which is
+    # not the machine that produced this build, so an honest remote receipt
+    # drifts by construction and would report TAMPERED on every single run.
+    # A false BLOCK is the more damaging direction (docs/VERIFICATION-COST.md):
+    # 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
+    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)"
+
+    if [ "$hash_ok" != "true" ]; then
+        echo -e "  ${RED}TAMPERED: the receipt's integrity hash does not match its contents.${NC}" >&2
+        echo "    proof.json was edited after it was written. Do not trust this build." >&2
+        return 1
+    fi
+
+    # Drift is REPORTED, never a verdict. This receipt was produced in a cluster
+    # pod and is being checked against a different tree, so drift is the normal
+    # result and says nothing about tampering -- docs/VERIFICATION-COST.md:
+    # hash_ok is integrity, `ok` folds in tree_drift and false-alarms here.
+    # Stated rather than suppressed: silently dropping a true fact because it is
+    # inconvenient is the same error as folding UNCHECKED into UNSIGNED.
+    if [ "$(printf '%s' "$out" | jq -r '[.diff_drift,.tree_drift]|index(true)!=null' 2>/dev/null)" = "true" ]; then
+        echo "  Drift: this tree differs from the one the receipt records. Expected --"
+        echo "    the build ran elsewhere. Not tampering, and not part of the verdict."
+    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
+    # first is an accusation. Reporting a missing key as TAMPERED would send a
+    # user hunting a forgery that never happened, and would train them to shrug
+    # at a real TAMPERED -- the same error as calling an unsigned receipt
+    # verified, just pointed the other way.
+    #
+    # proof-verify.py returns a bare boolean, so the distinction is drawn here
+    # from gpg's own status codes: BADSIG = bad over this content, NO_PUBKEY /
+    # ERRSIG = could not be checked.
+    if [ "$signed" -eq 1 ] && [ "$gpg_ok" = "false" ]; then
+        local _why=""
+        if command -v gpg >/dev/null 2>&1; then
+            _why="$(loki_remote_gpg_status "$pj")"
+        fi
+        if [ "$_why" = "nopubkey" ]; then
+            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
+            echo "    Import the publisher's public key and re-run: loki proof verify $(basename "$(dirname "$pj")")" >&2
+            # Non-zero: a caller who asked for a signed receipt did not get
+            # proof, and in CI that must not pass silently. The message states
+            # plainly that no fault was found in the content, so this is a
+            # missing-proof exit, not an accusation of tampering.
+            return 1
+        fi
+        echo -e "  ${RED}TAMPERED: the receipt carries a gpg signature that does not verify.${NC}" >&2
+        echo "    Either the contents or the signature was altered. Do not trust this build." >&2
+        return 1
+    fi
+
+    if [ "$signed" -eq 1 ] && [ "$gpg_ok" = "true" ]; then
+        echo -e "  ${GREEN}VERIFIED${NC}: integrity hash matches and the gpg signature is valid."
+        echo "    Proven: these receipt bytes are unaltered, and they were signed by the"
+        echo "    holder of the signing key. Verify that key is one you trust."
+        echo "    NOT proven: that the code is correct. A receipt records which checks ran."
+        return 0
+    fi
+
+    if [ "$signed" -eq 1 ]; then
+        # gpg_ok is "n/a" with a signature present: gpg is missing here.
+        echo -e "  ${YELLOW}NOT CHECKED${NC}: the receipt is signed, but gpg is unavailable on this machine."
+        echo "    Its integrity hash matches. The signature was NOT checked, so provenance"
+        echo "    is unproven here. Install gpg and re-run: loki proof verify $(basename "$(dirname "$pj")")"
+        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"
+    echo "    controls the builder can rewrite the facts and recompute the hash."
+    echo "    For provenance, the build must set LOKI_PROOF_GPG_KEY (docs/SIGNED-RECEIPTS.md)."
+    return 0
+}
+
 # Emit event (non-blocking)
 # Usage: emit_event <type> <source> <action> [key=value ...]
 emit_event() {
@@ -1495,6 +1844,7 @@ cmd_start() {
     local mirofish_bg=false
     local mirofish_disabled=false
     local no_plan=false  # v6.81.1: --no-plan opts out of auto-plan display
+    local remote_url="${LOKI_REMOTE_URL:-}"   # --remote: submit to a deployed cluster
 
     # v6.84.0: unified entry point -- explicit mode overrides + issue-mode args
     local explicit_mode=""            # "prd" | "issue" | "" (auto-detect)
@@ -1532,6 +1882,10 @@ cmd_start() {
                 echo "  --brief \"TEXT\"        Force zero-config brief mode (fast first run)"
                 echo ""
                 echo "Options:"
+                echo "  --remote URL          Submit to a deployed Loki (POST /jobs) instead of"
+                echo "                        building locally; polls until the job finishes."
+                echo "                        Token from LOKI_REMOTE_TOKEN / LOKI_REMOTE_TOKEN_FILE"
+                echo "                        (never an argument). Env: LOKI_REMOTE_URL."
                 echo "  --provider NAME       AI provider: claude (default), codex, cline, aider"
                 echo "  --parallel            Enable parallel mode with git worktrees"
                 echo "  --allow-haiku         Enable Haiku model for the fast tier (default: disabled)"
@@ -2058,6 +2412,19 @@ cmd_start() {
             --config=*|--vars=*|--env-file=*)
                 shift
                 ;;
+            --remote)
+                if [ "$#" -ge 2 ]; then
+                    remote_url="$2"
+                    shift 2
+                else
+                    echo "loki: --remote requires a URL (e.g. --remote https://loki.example.com)" >&2
+                    exit 1
+                fi
+                ;;
+            --remote=*)
+                remote_url="${1#--remote=}"
+                shift
+                ;;
             --)
                 # End-of-options: everything after is positional. Lets a caller
                 # pass an untrusted spec that might start with '-' safely, e.g.
@@ -2084,6 +2451,18 @@ cmd_start() {
         esac
     done
 
+    # --remote: submit to a deployed cluster instead of building locally.
+    #
+    # Branches HERE, after arg parsing but BEFORE the provider pre-flight and
+    # provider_offer_gate below: those require a provider CLI on PATH, and the
+    # whole point of a remote submit is that this machine is not doing the
+    # work. Gating a remote submit on a local provider install would defeat it.
+    if [ -n "$remote_url" ]; then
+        local _remote_spec="${brief_text:-${prd_file:-$positional_arg}}"
+        loki_remote_submit "$remote_url" "$_remote_spec"
+        return $?
+    fi
+
     # Explicit-provider pre-flight. Runs BEFORE provider_offer_gate below, and
     # is deliberately narrower than it.
     #
@@ -11364,6 +11743,10 @@ cmd_doctor() {
 
     local pass_count=0
     local fail_count=0
+    # Set to 1 when the bundled SDK is the ONLY usable provider (no CLI on PATH).
+    # Declared here, not inside the branch that sets it, so the "Next:" block at
+    # the end of this function always reads an initialized value.
+    local _doctor_sdk_only=0
     # FUNNEL FIX (v8.2.x): collect the NAME + FIX of every hard failure, not just
     # a count. A first-time user on a bare machine sees 15 warnings (sentrux, GPG
     # signing, bash 4, Bun, python3.12, truecolor, inline-image probe -- all
@@ -11528,6 +11911,12 @@ cmd_doctor() {
             echo -e "  ${GREEN}PASS${NC}  Bundled Claude Agent SDK is usable -- 'loki start' needs no separate CLI"
             echo -e "         ${YELLOW}Note: loki demo/quick/quickstart still need a provider CLI on PATH${NC}"
             echo -e "         ${YELLOW}      Install: npm install -g @anthropic-ai/claude-code${NC}"
+            # The note above was only half the fix. The final "Next:" line at the
+            # bottom of this function recommended quickstart unconditionally, so a
+            # user reading a GREEN doctor followed its LAST line straight into
+            # quickstart.sh:476 exit 2. Record the state here (where the predicate
+            # is already evaluated) and let the recommendation read it.
+            _doctor_sdk_only=1
             pass_count=$((pass_count + 1))
         else
             echo -e "  ${RED}FAIL${NC}  No AI provider CLI installed -- at least one is required"
@@ -12050,8 +12439,17 @@ else:
     # on fail_count==0 above, so a failing setup is never told to build. The
     # --json path returns long before this code, so machine output is untouched.
     echo ""
-    echo "Next: loki quickstart (guided first build from your idea, no PRD needed)"
-    echo "      or loki demo (builds a sample todo app end to end) or loki start ./prd.md"
+    if [ "$_doctor_sdk_only" = "1" ]; then
+        # SDK-only host: quickstart and demo stay on the bash route and need a
+        # binary on PATH, so recommending them here is a green doctor pointing at
+        # an exit 2. Recommend only what actually runs, plus the one command that
+        # unlocks the rest.
+        echo "Next: loki start ./prd.md (runs on the bundled SDK, no CLI install needed)"
+        echo "      For loki quickstart/demo: npm install -g @anthropic-ai/claude-code"
+    else
+        echo "Next: loki quickstart (guided first build from your idea, no PRD needed)"
+        echo "      or loki demo (builds a sample todo app end to end) or loki start ./prd.md"
+    fi
     # Best-effort stale-install nudge (stderr only; never blocks; off on
     # non-TTY/CI). Reached only on the human-readable path (--json returns above).
     maybe_print_update_hint
@@ -25040,6 +25438,60 @@ TELEM_DISABLE_PY
             echo "  OTEL tracing can be configured with 'loki telemetry enable [endpoint]'."
             ;;
 
+        analytics)
+            # Opt-in gate for build-outcome analytics (telemetry.sh
+            # _loki_analytics_enabled). That gate reads ANALYTICS_ENABLED=true from
+            # ~/.loki/config, and until now NOTHING in this repo ever wrote that
+            # key -- docs/PRIVACY.md told users to hand-edit the file. So the
+            # first-run funnel (first_start_attempted / first_run_blocked /
+            # build_verified) could not fire for anyone, and drop-off was
+            # structurally unmeasurable.
+            #
+            # Stays STRICTLY OPT-IN and default OFF: this only gives the existing
+            # consent a way to be expressed. Same filter-then-append shape as
+            # start|on above, so it is idempotent and never clobbers other keys.
+            local global_config="${HOME}/.loki/config"
+            local _an_action="${1:-status}"
+            case "$_an_action" in
+                on)
+                    mkdir -p "${HOME}/.loki"
+                    if [ -f "$global_config" ]; then
+                        grep -v "^ANALYTICS_ENABLED=" "$global_config" > "${global_config}.tmp" 2>/dev/null || true
+                        mv "${global_config}.tmp" "$global_config"
+                    fi
+                    echo "ANALYTICS_ENABLED=true" >> "$global_config"
+                    echo -e "${BOLD}Build analytics enabled${NC}"
+                    echo ""
+                    echo "  Opt-in saved to: $global_config"
+                    echo "  Only already-computed scalars are sent -- never code, spec text, or paths."
+                    echo "  Requires telemetry to be on as well (loki telemetry status)."
+                    echo "  Run 'loki telemetry analytics off' to opt back out."
+                    ;;
+                off)
+                    if [ -f "$global_config" ]; then
+                        grep -v "^ANALYTICS_ENABLED=" "$global_config" > "${global_config}.tmp" 2>/dev/null || true
+                        mv "${global_config}.tmp" "$global_config"
+                    fi
+                    echo -e "${BOLD}Build analytics disabled${NC}"
+                    echo ""
+                    echo "  ANALYTICS_ENABLED removed from: $global_config"
+                    echo "  Nothing build-related is sent. This is the default state."
+                    ;;
+                status)
+                    if [ -f "$global_config" ] && grep -q "^ANALYTICS_ENABLED=true" "$global_config" 2>/dev/null; then
+                        echo -e "  Build analytics: ${GREEN}enabled${NC} (you opted in; opt out with: loki telemetry analytics off)"
+                    else
+                        echo -e "  Build analytics: ${YELLOW}off${NC} (the default; opt in with: loki telemetry analytics on)"
+                    fi
+                    ;;
+                *)
+                    echo -e "${RED}Unknown analytics action: $_an_action${NC}"
+                    echo "Usage: loki telemetry analytics on|off|status"
+                    return 1
+                    ;;
+            esac
+            ;;
+
         --help|-h|help)
             echo -e "${BOLD}loki telemetry${NC} - OpenTelemetry management"
             echo ""
@@ -25053,6 +25505,8 @@ TELEM_DISABLE_PY
             echo "  off                 Opt out of all anonymous diagnostics (telemetry + crash)"
             echo "  start               Alias for 'on' (persistent opt-in across all sessions)"
             echo "  stop                Alias for 'off' (persistent opt-out across all sessions)"
+            echo "  analytics on|off|status"
+            echo "                      Opt in/out of build-outcome analytics (off by default)"
             echo ""
             echo "Anonymous diagnostics are OFF by default. Nothing is collected or"
             echo "sent unless you opt in. See docs/PRIVACY.md for the full disclosure."