loki-mode 8.5.2 → 8.6.1

package/README.md

@@ -121,6 +121,22 @@ usually load-bearing.
 Every coding agent tells you it finished. Loki hands you something you can
 check yourself.
 
+**We are not the only tool that checks its own work, and you should be
+suspicious of anyone who claims to be.** Lovable runs a security scan on every
+publish and can block the publish outright. Claude Code's review has a step that
+checks findings against actual code behavior. Replit says its agent tests its
+own work.
+
+The difference is what you are left holding. Their output lives in their
+dashboard: a findings count in a dialog, a check run that by design never blocks
+a merge. Ours is a **file**. It is bound to a specific diff by `diff_sha256`, it
+records what was NOT proven as prominently as what was, and someone who has
+never installed Loki can re-verify it from the repository alone. Commit it,
+attach it to the PR, hand it to an auditor.
+
+Portable, diff-bound, and honest about its gaps -- that is the claim, and it is
+the one worth checking.
+
 Each run writes a receipt to `.loki/proofs/<run_id>/` that separates
 **deterministic FACTS** (the git diff with base and head SHAs plus a
 `diff_sha256`, the test command and its exit code, the build command and its

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 v8.2.0
+# Loki Mode v8.6.1
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -469,4 +469,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v8.2.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v8.6.1 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-8.5.2
+8.6.1

package/autonomy/loki

@@ -985,8 +985,44 @@ show_help() {
     echo "  loki cockpit                  # Live multi-repo cockpit (terminal image)"
     echo "  loki remote                   # Remote session (phone/browser)"
     echo ""
+    # COMPLETE COMMAND INDEX. The curated sections above stay curated -- they
+    # are the onboarding path and stuffing 112 commands into them would make
+    # the first screen useless. But a command that appears NOWHERE in help does
+    # not exist to a user: measured, 43 of 112 were unreachable from here,
+    # including `loki proof` -- the Evidence Receipt, which is the whole trust
+    # argument. Discoverability is an adoption lever, not tidiness.
+    #
+    # tests/test-help-discoverability.sh fails the build when a real command is
+    # missing from this list, so a new command cannot ship invisible.
+    echo ""
+    echo "All commands:"
+    echo "  agent analyze api assets audit bench checkpoint (cp) ci cleanup"
+    echo "  cluster cockpit code compliance completions compound config context (ctx)"
+    echo "  cost council crash dashboard demo deploy docker docs doctor dogfood"
+    echo "  enterprise explain export failover github grill heal help import init"
+    echo "  issue kpis logs magic mcp memory metrics migrate modernize monitor"
+    echo "  next notify onboard open optimize otel own (handoff) pause plan preview"
+    echo "  projects proof (receipt) provider quick quickstart rc remote report reset"
+    echo "  resume review rollback run sandbox secrets secure self-update sentrux"
+    echo "  serve setup-skill share ship spec start state stats status steer stop"
+    echo "  syslog telemetry template test tour trigger trust trust-metrics"
+    echo "  ultracode update verify version voice watch watchdog web welcome why"
+    echo "  wiki worktree (wt)"
+    echo ""
+    echo "Any command: loki <command> --help"
+    echo ""
     echo "Phase A-J features (v7.5.18 - v7.5.28) are default-on. See CHANGELOG."
     echo ""
+    echo "Environment variables an operator would set: docs/environment-variables.md"
+    echo "Cost controls (budget, iteration and wall-clock caps): docs/cost-controls.md"
+    echo "Already have a codebase? Start read-only: docs/brownfield.md"
+    echo "No egress allowed? What runs disconnected: docs/air-gapped.md"
+    echo "Where this is going: docs/STRATEGY-2026-2028.md"
+    echo ""
+    echo "Scripting Loki? Exit codes for every command are documented in"
+    echo "docs/exit-codes.md. Severity rises with the code, and 'loki start'"
+    echo "has a richer contract under LOKI_DURABLE_STATE=1 for k8s and ECS."
+    echo ""
     echo "Environment Variables:"
     echo "  Opt-outs: LOKI_HOOK_EVENTS=off, LOKI_DYNAMIC_PROMPT_SECTIONS=keep,"
     echo "  LOKI_MEMORY_BASE_PATH (shared memory dir for app graph)"
@@ -1400,8 +1436,6 @@ cmd_start() {
     local positional_arg=""           # raw positional arg for mode detection
     local issue_ref_explicit=""       # --issue value (when explicit_mode=issue)
     local issue_mode_args=()          # captured issue-mode flags (--dry-run, --pr, etc.)
-    local issue_dry_run=false
-    local issue_no_start=false
     local issue_output_file=""
     local issue_use_worktree=false
     local issue_create_pr=false
@@ -1462,6 +1496,9 @@ cmd_start() {
                 echo "  --no-plan             Skip auto-shown PRD analysis at startup"
                 echo "  --brief \"TEXT\"        Zero-config fast first run from a one-line brief"
                 echo "  --yes, -y             Skip confirmation prompts (auto-confirm)"
+                echo "  --quiet               Suppress [INFO]/[STEP]; warnings and errors still print"
+                echo "  --log-level LEVEL     debug | info | warn | error (default: info)"
+                echo "  --max-duration DUR    Wall-clock cap: seconds, or 90m / 2h (default: none)"
                 echo ""
                 echo "Issue-mode options (only used when input is an ISSUE-REF):"
                 echo "  --dry-run             Preview generated PRD without starting"
@@ -1472,6 +1509,16 @@ cmd_start() {
                 echo "  --ship                Worktree + PR + auto-merge"
                 echo "  --detach, -d          Run in background"
                 echo ""
+                echo "Preview without spending (any input mode):"
+                echo "  loki plan <PRD>       Analyze a spec WITHOUT executing: complexity,"
+                echo "                        estimated iterations, tokens, and cost. Add --json"
+                echo "                        for machine-readable output. This is the dry run"
+                echo "                        for PRD and brief mode; --dry-run above is"
+                echo "                        issue-mode only."
+                echo "  LOKI_CONFIG_DUMP=1 loki start"
+                echo "                        Print the resolved LOKI_* configuration and exit"
+                echo "                        without starting a run or spending anything."
+                echo ""
                 echo "Environment Variables:"
                 echo "  LOKI_PRD_FILE         Path to PRD file (alternative to positional arg)"
                 echo "  LOKI_AUTO_CONFIRM     Set to 'true'/'false' to control prompts (takes precedence over CI)"
@@ -1661,6 +1708,52 @@ cmd_start() {
                 export LOKI_AUTO_CONFIRM=true
                 shift
                 ;;
+            # Wall-clock cap. Accepts plain seconds or a suffix (30m, 2h) --
+            # an operator setting a build timeout thinks in minutes and hours,
+            # and forcing them to compute 7200 invites the off-by-3600 error.
+            --max-duration)
+                if [[ -n "${2:-}" ]]; then
+                    local _md="$2" _mdn _mdmul=1
+                    case "$_md" in
+                        *s) _mdn="${_md%s}" ;;
+                        *m) _mdn="${_md%m}"; _mdmul=60 ;;
+                        *h) _mdn="${_md%h}"; _mdmul=3600 ;;
+                        *)  _mdn="$_md" ;;
+                    esac
+                    if ! [[ "$_mdn" =~ ^[0-9]+$ ]] || [ "$_mdn" -eq 0 ]; then
+                        echo "Error: --max-duration must be a positive duration (e.g. 5400, 90m, 2h); got '$2'" >&2
+                        return 1
+                    fi
+                    export LOKI_MAX_DURATION=$(( _mdn * _mdmul ))
+                    shift 2
+                else
+                    echo "Error: --max-duration requires a value (e.g. 90m)" >&2
+                    return 1
+                fi
+                ;;
+            # Verbosity. --quiet suppresses [INFO]/[STEP]; warnings and errors
+            # always print, so a quiet run can still say why it failed.
+            --quiet)
+                export LOKI_LOG_LEVEL=warn
+                shift
+                ;;
+            --log-level)
+                if [[ -n "${2:-}" ]]; then
+                    case "$2" in
+                        debug|info|warn|error)
+                            export LOKI_LOG_LEVEL="$2"
+                            ;;
+                        *)
+                            echo "Error: --log-level must be debug, info, warn, or error (got '$2')" >&2
+                            return 1
+                            ;;
+                    esac
+                    shift 2
+                else
+                    echo "Error: --log-level requires a value (debug|info|warn|error)" >&2
+                    return 1
+                fi
+                ;;
             --bmad-project)
                 if [[ -n "${2:-}" ]]; then
                     bmad_project_path="$2"
@@ -1836,12 +1929,10 @@ cmd_start() {
                 ;;
             # v6.84.0: issue-mode flags (only meaningful when input is an issue)
             --dry-run)
-                issue_dry_run=true
                 issue_mode_args+=("--dry-run")
                 shift
                 ;;
             --no-start)
-                issue_no_start=true
                 issue_mode_args+=("--no-start")
                 shift
                 ;;
@@ -9879,6 +9970,7 @@ cmd_config() {
             echo "  issue.provider       Default issue provider: github, gitlab, jira, azure_devops"
             echo "  blind_validation     Blind validation mode: true, false (default: true)"
             echo "  adversarial_testing  Adversarial testing: true, false (default: true)"
+            echo "  log_level            Output verbosity: debug, info, warn, error (default: info)"
             echo "  spawn_timeout        [DEPRECATED] No effect since WAVE9 (no consumer); accepted for back-compat"
             echo "  spawn_retries        [DEPRECATED] No effect since WAVE9 (no consumer); accepted for back-compat"
             echo "  notify.slack         Slack webhook URL"
@@ -9954,6 +10046,12 @@ cmd_config_set() {
                 *) echo -e "${RED}Invalid $key: $value (expected: true, false)${NC}"; return 1 ;;
             esac
             ;;
+        log_level)
+            case "$value" in
+                debug|info|warn|error) ;;
+                *) echo -e "${RED}Invalid log_level: $value (expected: debug, info, warn, error)${NC}"; return 1 ;;
+            esac
+            ;;
         spawn_timeout|spawn_retries)
             if ! echo "$value" | grep -qE '^[0-9]+$'; then
                 echo -e "${RED}Invalid $key: $value (expected: integer)${NC}"; return 1
@@ -9985,7 +10083,7 @@ cmd_config_set() {
             echo -e "${RED}Unknown configuration key: '$key'${NC}"
             echo ""
             echo "Valid keys: maxTier, provider, issue.provider, blind_validation,"
-            echo "  adversarial_testing, spawn_timeout, spawn_retries, budget,"
+            echo "  adversarial_testing, log_level, spawn_timeout, spawn_retries, budget,"
             echo "  model.planning, model.development, model.fast,"
             echo "  notify.slack, notify.discord"
             echo ""
@@ -11308,6 +11406,25 @@ except Exception:
         echo ""
         echo "Then re-run: loki doctor"
         echo "Meanwhile 'loki tour' works right now -- no provider, no key, no spend."
+        # Adoption signal: which CLASS of dependency stopped this first run.
+        # Mapped to an enum here rather than forwarding the blocker TEXT, so
+        # the payload can never carry a path or a version. Best-effort and
+        # backgrounded: telemetry must never delay or fail a doctor run, and
+        # every existing opt-out still gates it downstream.
+        if declare -f loki_emit_first_run_blocked >/dev/null 2>&1; then
+            local _blk_key="other"
+            case "$_doctor_blockers" in
+                *"No AI provider CLI"*) _blk_key="no_provider" ;;
+                *"Node.js is not installed"*|*"Node.js must be"*) _blk_key="node" ;;
+                *"Python 3 is not installed"*|*"Python 3 must be"*) _blk_key="python3" ;;
+                *"jq is not installed"*) _blk_key="jq" ;;
+                *"git is not installed"*) _blk_key="git" ;;
+                *"curl is not installed"*) _blk_key="curl" ;;
+                *"Free up disk"*) _blk_key="disk" ;;
+                *"broken symlink"*) _blk_key="skill_symlink" ;;
+            esac
+            ( loki_emit_first_run_blocked "$_blk_key" >/dev/null 2>&1 </dev/null & ) 2>/dev/null || true
+        fi
         return 1
     elif [ "$warn_count" -gt 0 ]; then
         echo -e "${YELLOW}All required checks passed with some warnings.${NC}"
@@ -11477,6 +11594,35 @@ if disk_status == 'pass': pass_count += 1
 elif disk_status == 'fail': fail_count += 1
 elif disk_status == 'warn': warn_count += 1
 
+# AGGREGATE PROVIDER CHECK. Each provider CLI is individually optional --
+# you need Claude OR Codex OR Cline OR Aider, not all four -- so no single
+# one can be marked required. But having NONE is a blocker, and the text
+# path reports it as one (the No-AI-provider branch near autonomy/loki:11000).
+#
+# --json omitted this entirely, so on a host with no provider the two
+# outputs gave OPPOSITE verdicts: the text path exited 1 while --json
+# reported zero failures and ok true. An operator gating a pipeline on the
+# JSON got a pass on a machine that cannot run a build -- the fake-green
+# this project exists to refuse.
+#
+# CAUTION: this block lives inside python3 -c with a DOUBLE-QUOTED program,
+# so an apostrophe or a double quote in a comment terminates the shell
+# string and mangles the program. First attempt did exactly that: doctor
+# --json printed nothing and exited 0. Keep this comment quote-free.
+_provider_cmds = ('claude', 'codex', 'cline', 'aider')
+_any_provider = any(shutil.which(_p) is not None for _p in _provider_cmds)
+ai_provider = {
+    'found': _any_provider,
+    'status': 'pass' if _any_provider else 'fail',
+    'required': 'required',
+    'detail': None if _any_provider
+              else 'No AI provider CLI. Fix: npm install -g @anthropic-ai/claude-code',
+}
+if _any_provider:
+    pass_count += 1
+else:
+    fail_count += 1
+
 result = {
     'loki_mode_version': os.environ.get('LOKI_VERSION', 'unknown'),
     'checks': checks,
@@ -11484,6 +11630,7 @@ result = {
         'available_gb': disk_gb,
         'status': disk_status
     },
+    'ai_provider': ai_provider,
     'sentrux': sentrux,
     'receipt_signing': receipt_signing,
     'memory': memory,
@@ -15589,6 +15736,35 @@ for fn in sorted(os.listdir(root)) if os.path.isdir(root) else []:
 # dependency staleness is NOT computed offline -> reported as 'unknown', never guessed.
 dep_lock_present = len(found_lockfiles) > 0 if found_manifests else None
 
+# RUNTIME + TOP DEPENDENCIES, read from the manifest itself. Offline-safe: this
+# reports what the file DECLARES, never what is current upstream (that stays
+# 'unknown' -- see dependency_staleness above).
+#
+# Why it matters: after 'how far behind am I', the next question a legacy
+# modernization buyer asks is 'what is this even built on'. Answering
+# 'package.json exists' and nothing more leaves them to open the file
+# themselves, which is the work they were trying to delegate.
+runtime_info = {'declared_runtime': None, 'declared_dependencies': None, 'framework_hints': []}
+try:
+    if 'package.json' in found_manifests:
+        with open(os.path.join(root, 'package.json')) as _f:
+            _pkg = json.load(_f)
+        _eng = (_pkg.get('engines') or {}).get('node')
+        runtime_info['declared_runtime'] = ('node ' + _eng) if _eng else 'node (engine unspecified)'
+        _deps = dict(_pkg.get('dependencies') or {})
+        runtime_info['declared_dependencies'] = len(_deps)
+        # Name only frameworks actually present. A hint is a FACT from the file,
+        # not an inference about what the project "probably" is.
+        for _fw in ('express', 'react', 'next', 'vue', 'angular', 'fastify', 'koa', 'nest'):
+            if _fw in _deps:
+                runtime_info['framework_hints'].append(_fw + ' ' + str(_deps[_fw]))
+    elif 'pyproject.toml' in found_manifests or 'requirements.txt' in found_manifests:
+        runtime_info['declared_runtime'] = 'python (version unspecified in manifest)'
+except (OSError, ValueError):
+    # A malformed manifest is not a crash and not a guess: leave the fields None
+    # so the report says nothing rather than something wrong.
+    pass
+
 todo_density = round((todo_count / total_loc) * 1000, 2) if total_loc else 0.0
 
 # --- 4-level maturity model (Ad hoc -> Planned -> Systematic -> Optimized) ---
@@ -15683,6 +15859,7 @@ report = {
         'lockfiles': found_lockfiles,
         'dependency_lock_present': dep_lock_present,
         'dependency_staleness': 'unknown',  # not computable offline; never guessed
+        'runtime': runtime_info,
     },
     'maturity': {
         'level': maturity_level,
@@ -29711,6 +29888,7 @@ cmd_ci() {
                 echo "  --github-comment     Post review results as PR comment (needs GITHUB_TOKEN)"
                 echo "  --fail-on <levels>   Set exit code 1 on severity: critical,high,medium,low"
                 echo "  --format <fmt>       Output format: json, markdown, github (default: markdown)"
+                echo "  --json               Alias for --format json"
                 echo "  --help, -h           Show this help"
                 echo ""
                 echo "Exit codes:"
@@ -29753,6 +29931,15 @@ cmd_ci() {
                 ci_fail_on="$(echo "$ci_fail_on" | tr '[:upper:]' '[:lower:]')"
                 shift
                 ;;
+            # --json is an alias for --format json. `loki ci` could already
+            # emit JSON, but only under a flag name no other command uses, so a
+            # script author reaching for the repo-wide --json convention found
+            # nothing and concluded the capability was missing. Same output,
+            # one spelling everywhere.
+            --json)
+                ci_format="json"
+                shift
+                ;;
             --format)
                 shift
                 ci_format="${1:-markdown}"
@@ -32523,7 +32710,8 @@ 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 "  open <id>            Open .loki/proofs/<id>/index.html in a browser"
+            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)"
             echo ""
             echo "Options for 'share':"
@@ -32608,6 +32796,38 @@ PYEOF
             fi
             exit 0
             ;;
+        md)
+            # Paste-able Markdown for a PR comment, a Slack message, or a
+            # ticket. The renderer already existed -- render_evidence_receipt_md
+            # in lib/proof-pr.sh -- but was reachable ONLY when Loki opened a PR
+            # itself. So the one form of the receipt built for humans to forward
+            # could not be produced on demand, which is the built-and-unreachable
+            # pattern this project keeps finding.
+            #
+            # Reuses that renderer rather than adding a second one: two writers
+            # of one artifact drift, and the drift surfaces as a PR body and a
+            # pasted summary disagreeing about the same run.
+            local id="${1:-}"
+            if [ -z "$id" ]; then
+                echo -e "${RED}Missing proof id.${NC} Use 'loki proof list'." >&2
+                exit 2
+            fi
+            local pj="${proofs_dir}/${id}/proof.json"
+            if [ ! -f "$pj" ]; then
+                echo -e "${RED}Proof not found: ${id}${NC}" >&2
+                echo "Use 'loki proof list' to see available proofs." >&2
+                exit 1
+            fi
+            local _pr_lib="$_LOKI_SCRIPT_DIR/lib/proof-pr.sh"
+            if [ ! -f "$_pr_lib" ]; then
+                echo -e "${RED}Renderer not found: ${_pr_lib}${NC}" >&2
+                exit 3
+            fi
+            # shellcheck source=/dev/null
+            source "$_pr_lib"
+            render_evidence_receipt_md "$pj"
+            exit 0
+            ;;
         verify)
             # Deterministic re-check of a receipt against the repo: re-hashes the
             # canonical proof (tamper check) and re-derives the diff from the

package/autonomy/run.sh

@@ -1508,11 +1508,39 @@ log_header() {
     echo -e "${BLUE}╚════════════════════════════════════════════════════════════════╝${NC}"
 }
 
-log_info() { echo -e "${GREEN}[INFO]${NC} $*"; }
-log_warn() { echo -e "${YELLOW}[WARN]${NC} $*"; }
+# VERBOSITY. LOKI_LOG_LEVEL is one of debug|info|warn|error (default info);
+# LOKI_QUIET=1 is shorthand for warn.
+#
+# Implemented at these five functions rather than at 527 call sites, which is
+# both the smaller diff and the only version that cannot drift -- a new
+# log_info added next year is covered without anyone remembering to gate it.
+#
+# WHY THIS IS NEEDED DESPITE GOOD TTY DETECTION. The heavy decoration (HUD,
+# completion card, start headline) is already `[ -t 1 ]`-guarded and vanishes
+# off a TTY, so CI output was never the wall of banners it might have been.
+# But 527 log_info/log_step calls are unguarded and print regardless, and a
+# pipeline that wants only warnings had no way to ask. log_debug already
+# honored LOKI_DEBUG; the other levels honored nothing.
+#
+# ERRORS ARE NEVER SUPPRESSED. `error` is the floor: the quietest setting still
+# prints failures. A verbosity flag that can hide the reason a build failed is
+# a footgun, not a feature.
+_loki_log_threshold() {
+    case "${LOKI_LOG_LEVEL:-$([ "${LOKI_QUIET:-0}" = "1" ] && echo warn || echo info)}" in
+        debug) echo 0 ;;
+        info)  echo 1 ;;
+        warn)  echo 2 ;;
+        error) echo 3 ;;
+        *)     echo 1 ;;   # unrecognized value behaves as the default, never silences
+    esac
+}
+_loki_log_enabled() { [ "$1" -ge "$(_loki_log_threshold)" ]; }
+
+log_info() { _loki_log_enabled 1 && echo -e "${GREEN}[INFO]${NC} $*" || true; }
+log_warn() { _loki_log_enabled 2 && echo -e "${YELLOW}[WARN]${NC} $*" || true; }
 log_warning() { log_warn "$@"; }  # Alias for backwards compatibility
 log_error() { echo -e "${RED}[ERROR]${NC} $*"; }
-log_step() { echo -e "${CYAN}[STEP]${NC} $*"; }
+log_step() { _loki_log_enabled 1 && echo -e "${CYAN}[STEP]${NC} $*" || true; }
 log_debug() { [[ "${LOKI_DEBUG:-}" == "true" ]] && echo -e "${CYAN}[DEBUG]${NC} $*" >&2 || true; }
 
 #===============================================================================
@@ -13293,6 +13321,17 @@ ${dependency_context}"
             "diff_bytes=$_review_diff_bytes" \
             "limit_bytes=$_review_max_bytes" \
             "iteration=${ITERATION_COUNT:-0}" 2>/dev/null || true
+        # Classify this as INFRASTRUCTURE, not a finding. The discriminator is
+        # otherwise set at :14912, which this early return never reaches, so the
+        # variable stayed "" from the reset at :12959 and the consumer at :22126
+        # read a file-size condition as "Critical/High findings" -- escalating to
+        # PAUSE over a diff that was merely too large to send.
+        #
+        # Still fail-closed: the review did NOT pass, and nothing here converts a
+        # skipped review into a green one. It only records WHY it could not run,
+        # which is the difference between "your code is bad" and "we could not
+        # look at it".
+        _LOKI_REVIEW_FAILURE_KIND="infrastructure_inconclusive"
         return 1
     fi
 
@@ -16470,6 +16509,46 @@ check_max_iterations() {
     return 1
 }
 
+# WALL-CLOCK CAP. Returns 0 (stop) when the run has exceeded LOKI_MAX_DURATION
+# seconds. Unset or 0 = no cap, which is the default and exactly today's
+# behavior.
+#
+# WHY A THIRD BOUND. Spend was already capped (LOKI_BUDGET_LIMIT) and so were
+# iterations (LOKI_MAX_ITERATIONS), but a run that STALLS is bounded by neither:
+# a hung provider call or a wedged subprocess burns hours while spending almost
+# nothing and completing no iteration, so neither existing breaker ever trips.
+# It runs until something external kills it -- and an external kill leaves no
+# terminal status, so the receipt cannot say what happened.
+#
+# Kubernetes operators already have activeDeadlineSeconds in the Job spec, but
+# that SIGKILLs the pod: no status is written, no receipt, and the platform
+# sees a crash rather than a deliberate stop. This cap stops the loop cleanly
+# at the next iteration boundary so the run still explains itself.
+#
+# It is checked at the boundary, not mid-iteration: interrupting an agent
+# mid-write is how you get a half-applied change. So the effective stop time is
+# the cap plus the remainder of the current iteration, which the log states
+# rather than pretending to be exact.
+check_max_duration() {
+    local cap="${LOKI_MAX_DURATION:-0}"
+    case "$cap" in
+        ''|*[!0-9]*) return 1 ;;   # unset or non-numeric: no cap, never stop
+    esac
+    [ "$cap" -eq 0 ] && return 1
+
+    local start="${_LOKI_RUN_START_EPOCH:-0}"
+    [ "$start" -eq 0 ] 2>/dev/null && return 1
+
+    local now elapsed
+    now=$(date +%s)
+    elapsed=$((now - start))
+    if [ "$elapsed" -ge "$cap" ]; then
+        log_warn "Wall-clock cap reached (${elapsed}s elapsed, LOKI_MAX_DURATION=${cap}s). Stopping at the iteration boundary."
+        return 0
+    fi
+    return 1
+}
+
 # Load latest ledger content for context injection
 load_ledger_context() {
     local ledger_content=""
@@ -20577,6 +20656,18 @@ except Exception as exc:
             return 20
         fi
 
+        # Wall-clock cap. Checked alongside the iteration cap and treated the
+        # same way: a distinct terminal status so the receipt and `loki why`
+        # can say the run ran out of TIME rather than iterations or money, and
+        # exit 20 because re-running the same spec under the same cap will hit
+        # the same wall. The operator raises LOKI_MAX_DURATION (or narrows the
+        # spec) and submits again.
+        if check_max_duration; then
+            save_state "$retry" "max_duration_reached" 20
+            emit_completion_summary max_duration
+            return 20
+        fi
+
         # Increment after all pre-attempt stop checks pass.
         ((ITERATION_COUNT++))
 
@@ -24266,11 +24357,12 @@ except Exception:
     #
     # Contract (LOKI_DURABLE_STATE=1 only; local/CI exit codes are unchanged):
     #   0  = success / human-controlled clean stop (council approved, completion
-    #        promise, force-stop, or paused/interrupted/budget/stopped where a
-    #        human will resume). Job -> Complete, no retry.
+    #        promise, force-stop, or paused/interrupted/stopped where a HUMAN
+    #        chose to stop and will resume). Job -> Complete, no retry.
     #   20 = deterministic terminal failure (failed, max_iterations_reached,
-    #        max_retries_exceeded, exited, policy_blocked). Re-running on the same
-    #        inputs fails the same way -> Job must NOT retry. The Helm Job pairs
+    #        max_retries_exceeded, budget_exceeded, max_duration_reached,
+    #        policy_blocked). Re-running on
+    #        the same inputs fails the same way -> Job must NOT retry. The Helm Job pairs
     #        this with restartPolicy: Never + a podFailurePolicy rule that maps
     #        exit 20 to FailJob (no retry), so a deterministic failure does not
     #        burn the backoffLimit (the Job records the failure; an operator
@@ -24283,9 +24375,25 @@ except Exception:
         _final_state_file="$(_loki_state_file)"
         _final_status=$(LOKI_STATE_FILE="$_final_state_file" python3 -c "import json, os; print(json.load(open(os.environ['LOKI_STATE_FILE'])).get('status','unknown'))" 2>/dev/null || echo "unknown")
         case "$_final_status" in
-            council_approved|council_force_approved|deterministic_gates_passed|completion_promise_fulfilled|force_stopped|paused|interrupted|budget_exceeded|stopped)
+            council_approved|council_force_approved|deterministic_gates_passed|completion_promise_fulfilled|force_stopped|paused|interrupted|stopped)
                 result=0 ;;
-            failed|max_iterations_reached|max_retries_exceeded|policy_blocked|inconclusive_spec_contradiction)
+            # budget_exceeded belongs HERE, not with the human-controlled stops.
+            # It sat in the result=0 arm on the rationale that "a human will
+            # resume", which is true of `paused` (a human pressed pause) and
+            # false of a cost breaker firing inside a k8s Job or a CI pipeline,
+            # where there is no human. A build killed mid-work then reported
+            # SUCCESS: the Job went Complete, the pipeline went green, and an
+            # incomplete build looked finished. That is a false green produced
+            # by our own gate, which is precisely what the Evidence Receipt
+            # exists to prevent.
+            #
+            # It is deterministic rather than retryable: re-running the same
+            # inputs against the same cap exhausts the same budget and fails
+            # identically, so retrying only burns money to reach the same place.
+            # The operator raises the cap (or narrows the spec) and submits a
+            # NEW Job -- the same remedy as max_iterations_reached, which is why
+            # it shares that code.
+            failed|max_iterations_reached|max_retries_exceeded|budget_exceeded|max_duration_reached|policy_blocked|inconclusive_spec_contradiction)
                 result=20 ;;
             *)
                 # Unknown/running/exited terminal: leave $result as-is (nonzero on a

package/autonomy/telemetry.sh

@@ -187,6 +187,20 @@ _loki_known_command() {
     esac
 }
 
+# Clamp a doctor blocker to a FIXED ENUM. Same discipline as
+# _loki_known_command: an unrecognized value becomes "other" rather than being
+# forwarded, so a new blocker string added later cannot silently start leaking
+# text. Deliberately coarse -- we need to know WHICH CLASS of dependency stops
+# a first run, never the user's paths, versions, or hostnames.
+_loki_known_blocker() {
+    case "${1:-}" in
+        no_provider|node|python3|jq|git|curl|disk|skill_symlink)
+            printf '%s' "$1" ;;
+        *)
+            printf 'other' ;;
+    esac
+}
+
 loki_telemetry() {
     _loki_telemetry_enabled || return 0
     local event="$1"; shift
@@ -297,6 +311,37 @@ loki_emit_funnel_once() {
 # fields are excluded on purpose: headline is a bounded enum (VERIFIED / VERIFIED
 # WITH GAPS / NOT VERIFIED), never spec/project text; files_changed is a COUNT,
 # never paths.
+# loki_emit_first_run_blocked <blocker-key>: fire ONE first_run_blocked event
+# naming the CLASS of dependency that stopped a first run.
+#
+# WHY THIS EXISTS. `first_start_attempted` already fires, so we know a first run
+# was ATTEMPTED and nothing about whether it succeeded. That is the wrong half:
+# an attempt that dies at `doctor` looks identical to one that built something.
+# Without this, the question that decides an adoption strategy -- does a trial
+# fail on capability, discoverability, or trust -- has no data behind it.
+#
+# The measured motivation is concrete: on a host with no provider CLI the Bun
+# route used to print "Some required prerequisites are missing" and stop, while
+# bash pointed at `loki tour`. That was a dead end for a first-time evaluator
+# and nobody could see it happening.
+#
+# WHAT IT SENDS, and deliberately no more: one enum from _loki_known_blocker.
+# Never a path, a version, a hostname, a spec, or a command line. Coarse on
+# purpose -- "node" is actionable, "/Users/x/.nvm/versions/node/v18" is a leak.
+# An adoption tool that exfiltrates a user's environment would cost exactly the
+# trust this product sells.
+#
+# Once per install (the funnel marker), under the strict analytics gate, and
+# every existing opt-out still wins because it routes through the same
+# _loki_analytics_enabled check as everything else.
+loki_emit_first_run_blocked() {
+    local _blocker
+    _blocker="$(_loki_known_blocker "${1:-}")"
+    loki_emit_funnel_once "first-run-blocked" "first_run_blocked" \
+        "blocker=${_blocker}" 2>/dev/null || true
+    return 0
+}
+
 loki_emit_build_verified() {
     _loki_analytics_enabled || return 0
     local _proof="$1"