loki-mode 7.91.0 → 7.92.0

package/autonomy/run.sh

@@ -218,6 +218,11 @@ if [[ -z "${LOKI_RUNNING_FROM_TEMP:-}" ]] && [[ "${BASH_SOURCE[0]}" == "${0}" ]]
     # BUG-XC-011: Set trap BEFORE exec so the temp file gets cleaned up
     trap 'rm -f "$TEMP_SCRIPT"' EXIT
     export LOKI_RUNNING_FROM_TEMP=1
+    # Record the EXACT temp-copy path so the post-exec cleanup trap deletes THIS
+    # temp file and NEVER the canonical source (root cause of the recurring
+    # "run.sh self-deleted on build spawn" bug: an inherited LOKI_RUNNING_FROM_TEMP
+    # skips the self-copy block, leaving BASH_SOURCE[0]=the real run.sh).
+    export LOKI_TEMP_SCRIPT_PATH="$TEMP_SCRIPT"
     export LOKI_ORIGINAL_SCRIPT_DIR="$SCRIPT_DIR"
     export LOKI_ORIGINAL_PROJECT_DIR="$PROJECT_DIR"
     exec "$TEMP_SCRIPT" "$@"
@@ -227,9 +232,14 @@ fi
 SCRIPT_DIR="${LOKI_ORIGINAL_SCRIPT_DIR:-$SCRIPT_DIR}"
 PROJECT_DIR="${LOKI_ORIGINAL_PROJECT_DIR:-$PROJECT_DIR}"
 
-# Clean up temp script on exit (only when running from temp copy)
-if [[ "${LOKI_RUNNING_FROM_TEMP:-}" == "1" ]]; then
-    trap 'rm -f "${BASH_SOURCE[0]}" 2>/dev/null' EXIT
+# Clean up ONLY the recorded temp copy, and ONLY if it is a real temp file.
+# Deleting BASH_SOURCE[0] here was the bug: an inherited LOKI_RUNNING_FROM_TEMP
+# made BASH_SOURCE[0] the canonical source, so run.sh deleted itself on spawned
+# builds. Guard on the recorded path being a real /tmp/loki-run-* file.
+if [[ "${LOKI_RUNNING_FROM_TEMP:-}" == "1" ]] \
+   && [[ -n "${LOKI_TEMP_SCRIPT_PATH:-}" ]] \
+   && [[ "${LOKI_TEMP_SCRIPT_PATH}" == /tmp/loki-run-* || "${LOKI_TEMP_SCRIPT_PATH}" == "${TMPDIR:-/tmp}"loki-run-* ]]; then
+    trap 'rm -f "${LOKI_TEMP_SCRIPT_PATH}" 2>/dev/null' EXIT
 fi
 
 #===============================================================================
@@ -1040,6 +1050,179 @@ log_error() { echo -e "${RED}[ERROR]${NC} $*"; }
 log_step() { echo -e "${CYAN}[STEP]${NC} $*"; }
 log_debug() { [[ "${LOKI_DEBUG:-}" == "true" ]] && echo -e "${CYAN}[DEBUG]${NC} $*" >&2 || true; }
 
+#===============================================================================
+# Failure diagnosis helpers (T2.4 / T2.5 / T2.6)
+#
+# These make a failing or crashed build self-explanatory: a copy-pasteable
+# "loki why" hint on any non-zero exit, a durable CLASSIFIED LAST_ERROR record
+# on a failed iteration, and a best-effort terminal record on an untrapped
+# death. Every one is best-effort and NEVER alters the build's exit code.
+#===============================================================================
+
+# _loki_surface_why_hint (T2.4): print the "loki why" hint to stderr and write
+# it to .loki/NEXT_STEPS.txt. Called once from main() finalization when the run
+# failed (result != 0). Best-effort: never crashes, never changes exit code.
+_loki_surface_why_hint() {
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+    local hint="For a plain-language diagnosis of what happened, run: loki why"
+    printf '%s\n' "$hint" >&2 || true
+    mkdir -p "$loki_dir" 2>/dev/null || true
+    printf '%s\n' "$hint" > "$loki_dir/NEXT_STEPS.txt" 2>/dev/null || true
+    return 0
+}
+
+# _loki_write_last_error (T2.5): write a durable, classified failure record to
+# .loki/state/LAST_ERROR.json. Schema:
+#   {
+#     "iteration":   <int>,
+#     "error_class": "provider_empty_output"|"build_timeout"|"rate_limited"
+#                    |"auth_error"|"unknown",
+#     "brief":       "<one honest sentence>",
+#     "timestamp":   "<UTC ISO-8601>"
+#   }
+# This is what `loki why` (in autonomy/loki, NOT owned here) can later read.
+# Built via python3 so the free-text brief can never break the JSON. Entirely
+# best-effort: any failure is swallowed and the build is never crashed.
+# Usage: _loki_write_last_error <iteration> <error_class> <brief>
+_loki_write_last_error() {
+    local iteration="${1:-0}"
+    local error_class="${2:-unknown}"
+    local brief="${3:-An iteration failed.}"
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+    local state_dir="$loki_dir/state"
+    mkdir -p "$state_dir" 2>/dev/null || true
+    LOKI_LE_ITER="$iteration" \
+    LOKI_LE_CLASS="$error_class" \
+    LOKI_LE_BRIEF="$brief" \
+    LOKI_LE_FILE="$state_dir/LAST_ERROR.json" \
+    python3 -c "
+import json, os, tempfile
+try:
+    rec = {
+        'iteration': int(os.environ.get('LOKI_LE_ITER', '0') or 0),
+        'error_class': os.environ.get('LOKI_LE_CLASS', 'unknown'),
+        'brief': os.environ.get('LOKI_LE_BRIEF', ''),
+        'timestamp': __import__('datetime').datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'),
+    }
+    target = os.environ['LOKI_LE_FILE']
+    d = os.path.dirname(target)
+    fd, tmp = tempfile.mkstemp(dir=d, suffix='.json')
+    with os.fdopen(fd, 'w') as f:
+        json.dump(rec, f)
+    os.replace(tmp, target)
+except Exception:
+    pass
+" 2>/dev/null || true
+    return 0
+}
+
+# _loki_classify_iteration_error (T2.5 helper): map an iteration's signals to one
+# of the LAST_ERROR error_class values. Conservative: only returns a specific
+# class when a signal confidently supports it, else "unknown". Never fabricates
+# build_timeout (no timeout signal is detected here, so it is reserved for a
+# caller that has one). Echoes the class on stdout.
+# Usage: _loki_classify_iteration_error <iter_output_file> <empty_output_flag 0|1>
+_loki_classify_iteration_error() {
+    local iter_output="${1:-}"
+    local empty_flag="${2:-0}"
+    if [ "$empty_flag" = "1" ]; then
+        echo "provider_empty_output"
+        return 0
+    fi
+    # Rate limit: reuse the same detector the retry path uses.
+    if [ -n "$iter_output" ] && [ -f "$iter_output" ] && detect_rate_limit "$iter_output" 2>/dev/null | grep -qE '^[1-9]'; then
+        echo "rate_limited"
+        return 0
+    fi
+    # Auth error: a clear 401/403/unauthorized in the output tail.
+    if [ -n "$iter_output" ] && [ -f "$iter_output" ]; then
+        local _tail
+        _tail="$(tail -n 40 "$iter_output" 2>/dev/null || true)"
+        if printf '%s\n' "$_tail" | grep -qiE '(http[ /]?40[13]|status[: ]+40[13]|unauthorized|invalid api key|authentication[_ ]error|401 )' 2>/dev/null; then
+            echo "auth_error"
+            return 0
+        fi
+    fi
+    echo "unknown"
+    return 0
+}
+
+# _loki_terminal_record (T2.6, SAFE SUBSET): on an untrapped exit where the
+# persisted run status is still "running" (a true mid-provider-call crash on a
+# trappable signal -- SIGTERM/SIGINT/SIGHUP via the lock-release trap), leave a
+# best-effort, classified LAST_ERROR record so a post-crash `loki why` is not
+# stale. Piggybacks the existing lock-release EXIT trap (see main()) -- it does
+# NOT install a new broad EXIT trap.
+#
+# IMPORTANT (why this does NOT rewrite autonomy-state.json): the resume-detection
+# block in this file (search "Durable resume") keys the ENT-2 pod-loss resume on
+# prev_status == "running". Flipping the status to "exited" here would make a
+# crashed-but-resumable build (LOKI_DURABLE_STATE=1) reset to iteration 0 on the
+# next start, destroying durable progress. So this writes ONLY the LAST_ERROR
+# side-record (which is what `loki why` reads) and deliberately leaves the
+# status untouched. SIGKILL / power-loss are uncatchable (no trap fires); the
+# ENT-2 durable-resume path covers those. Never alters the exit code; best-effort.
+_loki_terminal_record() {
+    local state_file
+    state_file="$(_loki_state_file 2>/dev/null)" || return 0
+    [ -n "$state_file" ] || return 0
+    [ -f "$state_file" ] || return 0
+    local _status
+    _status="$(LOKI_TR_FILE="$state_file" python3 -c "
+import json, os
+try:
+    print(json.load(open(os.environ['LOKI_TR_FILE'])).get('status','unknown'))
+except Exception:
+    print('unknown')
+" 2>/dev/null || echo "unknown")"
+    # Only act on a genuinely mid-flight "running" status. Any settled status
+    # (council_approved, failed, exited, paused, ...) is left untouched.
+    [ "$_status" = "running" ] || return 0
+    # Leave a classified LAST_ERROR so `loki why` has something honest -- WITHOUT
+    # touching autonomy-state.json (preserving the ENT-2 "running" resume signal).
+    _loki_write_last_error "${ITERATION_COUNT:-0}" "unknown" \
+        "The build process exited unexpectedly before finishing (possible crash or kill)." 2>/dev/null || true
+    return 0
+}
+
+# _loki_write_rate_limit_signal (T2.7): write a best-effort
+# .loki/signals/RATE_LIMITED file. This is FORWARD-LAID infrastructure: no
+# consumer reads it yet (a future dashboard / external watcher could, to tell a
+# normal provider rate-limit wait apart from a hang). The user-visible signal
+# today is the log_info line at the wait site; this file is the durable record. Schema:
+#   {"rate_limited": true, "wait_seconds": <int>, "reset_time": "<string>"}
+# Built via python3 so the reset-time string can never break the JSON. Entirely
+# best-effort: never crashes, never alters the build.
+# Usage: _loki_write_rate_limit_signal <wait_seconds> <reset_time>
+_loki_write_rate_limit_signal() {
+    local wait_seconds="${1:-0}"
+    local reset_time="${2:-}"
+    local signals_dir="${TARGET_DIR:-.}/.loki/signals"
+    mkdir -p "$signals_dir" 2>/dev/null || true
+    LOKI_RL_WAIT="$wait_seconds" \
+    LOKI_RL_RESET="$reset_time" \
+    LOKI_RL_FILE="$signals_dir/RATE_LIMITED" \
+    python3 -c "
+import json, os, tempfile
+try:
+    w = os.environ.get('LOKI_RL_WAIT', '0')
+    try:
+        w = int(w)
+    except Exception:
+        w = 0
+    rec = {'rate_limited': True, 'wait_seconds': w, 'reset_time': os.environ.get('LOKI_RL_RESET', '')}
+    target = os.environ['LOKI_RL_FILE']
+    d = os.path.dirname(target)
+    fd, tmp = tempfile.mkstemp(dir=d, suffix='.json')
+    with os.fdopen(fd, 'w') as f:
+        json.dump(rec, f)
+    os.replace(tmp, target)
+except Exception:
+    pass
+" 2>/dev/null || true
+    return 0
+}
+
 # Live Build HUD (v7.71.0): a single append-only per-iteration status line on the
 # interactive TTY path. Pure additive stdout decoration -- never piped into any
 # tee, so the dashboard agent.log and the stream-json parser are untouched. The
@@ -1384,6 +1567,34 @@ emit_event_json() {
     log_debug "Event: $event_type - $json_data"
 }
 
+# Per-stage timeline event (v7.91.x). Emits one stage_complete record per
+# quality-gate / build stage so the SaaS timeline can show where build time
+# goes within an iteration (the provider call itself is already bracketed by
+# iteration_start/iteration_complete). This is purely ADDITIVE: it appends one
+# event line via emit_event_json and never changes a gate verdict, gate exit
+# code, or control flow. Duration is computed by the caller (whole-second
+# resolution, sufficient for multi-second gates) and carried on the event so
+# the SaaS does not have to infer it from coarse ISO timestamps.
+#   emit_stage_complete <stage_name> <status: pass|fail> <start_epoch_seconds>
+# Event shape:
+#   {type:"stage_complete", timestamp, data:{stage, status, duration_s, iteration}}
+# Best-effort: any failure is swallowed so it can never block the build.
+emit_stage_complete() {
+    local stage="$1"
+    local status="$2"
+    local t0="$3"
+    local now dur
+    now=$(date +%s 2>/dev/null) || return 0
+    [ -n "$t0" ] || return 0
+    dur=$(( now - t0 ))
+    [ "$dur" -ge 0 ] 2>/dev/null || dur=0
+    emit_event_json "stage_complete" \
+        "stage=$stage" \
+        "status=$status" \
+        "duration_s=$dur" \
+        "iteration=${ITERATION_COUNT:-0}" 2>/dev/null || true
+}
+
 # Trust-layer metrics event writer (benchmark program section 3). Appends one
 # durable record per trust event to .loki/metrics/trust-events.jsonl via the
 # Python writer (single source of truth for the JSONL schema). This is ADDITIVE
@@ -1760,9 +1971,93 @@ get_iteration_duration_ms() {
 # Supports Docker/K8s secret file mounts as fallback.
 #===============================================================================
 
+# Zero-friction preflight helpers (T1.1). These run for ALL environments
+# (not just Docker/K8s) BEFORE the build starts, via validate_api_keys. git is a
+# genuine hard requirement (the build inits a repo) so a missing git BLOCKS with a
+# copy-pasteable fix; node-version and network reachability are ADVISORY (warn and
+# continue, fail-open) so a probabilistic or optional signal never blocks a working
+# user. The goal: surface real problems early without ever wrongly refusing to start.
+#
+# _loki_check_node_version: ADVISORY only. If node is present and its major
+# version is < 18, log a warning (node only matters for node-based builds) and
+# continue. If node is absent entirely this is a NO-OP. Always returns 0 -- it
+# never blocks the build (fail-open); the real node call, if any, is the test.
+_loki_check_node_version() {
+    command -v node >/dev/null 2>&1 || return 0
+    local node_version major
+    node_version="$(node --version 2>/dev/null || echo '')"
+    # node --version -> "v20.11.0"; extract the leading major integer.
+    major="$(printf '%s' "$node_version" | sed -E 's/^v?([0-9]+).*/\1/')"
+    # Advisory only: node is OPTIONAL (absence is a no-op above, and many builds -
+    # Python/Go/Rust - never touch node). A present-but-old node only matters for
+    # node-based builds, so WARN and continue (fail-open); never hard-block a
+    # working user. The actual node call (only for JS/TS work) is the real test.
+    if [ -n "$major" ] && [[ "$major" =~ ^[0-9]+$ ]] && [ "$major" -lt 18 ]; then
+        log_warn "Node.js >= 18 recommended for node-based builds; found ${node_version:-unknown}. Upgrade if your project uses node: https://nodejs.org"
+    fi
+    return 0
+}
+
+# _loki_check_git_present: the build initializes a git repo, so git is required.
+_loki_check_git_present() {
+    if ! command -v git >/dev/null 2>&1; then
+        log_error "Git is required (the build initializes a repo). Install: https://git-scm.com/downloads"
+        return 1
+    fi
+    return 0
+}
+
+# _loki_check_network_reachable: ADVISORY only. A fast (3s) reachability probe to
+# the active provider endpoint that WARNS and continues if it cannot reach it -- a
+# curl failure does not prove the provider CLI cannot connect (3s timeout under
+# load, transient DNS, or a proxy set for the CLI but not the shell all curl-fail
+# while the real build succeeds). Always returns 0 (fail-open); the actual
+# provider call is the authoritative connectivity test. Skipped entirely when curl
+# is missing, when LOKI_SKIP_NET_PREFLIGHT=1, when ANTHROPIC_BASE_URL is set (alt
+# provider endpoint we cannot assume), or for any provider whose endpoint we do
+# not know. It NEVER blocks the build.
+_loki_check_network_reachable() {
+    local provider="${1:-claude}"
+    [ "${LOKI_SKIP_NET_PREFLIGHT:-}" = "1" ] && return 0
+    command -v curl >/dev/null 2>&1 || return 0
+    # Alternate provider base URL set -> do not assume the default endpoint.
+    [ -n "${ANTHROPIC_BASE_URL:-}" ] && return 0
+
+    local endpoint=""
+    case "$provider" in
+        claude) endpoint="https://api.anthropic.com" ;;
+        *)      return 0 ;;  # unknown endpoint -> fail open, never guess
+    esac
+
+    # Advisory only: a fast curl probe failing does NOT prove the provider CLI
+    # cannot connect (a 3s timeout under load, transient DNS, or a proxy set for
+    # the CLI but not the shell all curl-fail while the real build succeeds). WARN
+    # and continue - the actual provider call is the authoritative connectivity
+    # test. Silence this with LOKI_SKIP_NET_PREFLIGHT=1. Never hard-block here.
+    if ! curl -sS -m 3 -o /dev/null "$endpoint" 2>/dev/null; then
+        log_warn "Could not verify network reachability to the AI provider (firewall/VPN/transient?). Continuing; the provider call will be the real test. Silence with LOKI_SKIP_NET_PREFLIGHT=1."
+    fi
+    return 0
+}
+
 validate_api_keys() {
     local provider="${LOKI_PROVIDER:-claude}"
 
+    # Zero-friction preflight (T1.1): toolchain + reachability checks that apply
+    # to EVERY environment, run BEFORE the Docker/K8s early-return below so they
+    # are not silently skipped in the common local case. Node/git are genuinely
+    # required (node only when present-but-too-old); the network probe is
+    # fail-open and opt-out (LOKI_SKIP_NET_PREFLIGHT=1).
+    if ! _loki_check_node_version; then
+        return 1
+    fi
+    if ! _loki_check_git_present; then
+        return 1
+    fi
+    if ! _loki_check_network_reachable "$provider"; then
+        return 1
+    fi
+
     # CLI tools (claude, codex, cline, aider) use their own login sessions.
     # Only require API keys inside Docker/K8s where CLI login isn't available.
     if [[ ! -f "/.dockerenv" ]] && [[ -z "${KUBERNETES_SERVICE_HOST:-}" ]]; then
@@ -6189,6 +6484,152 @@ audit_log() {
     echo "$log_entry" >> "$audit_file"
 }
 
+#===============================================================================
+# Engine-owned workspace git-init (Plan #16, Option A-1)
+#===============================================================================
+
+# Resolve a path to its physical absolute form (symlinks + .. collapsed) using
+# whatever is available; falls back to the input unchanged. Portable across the
+# BSD (macOS) and GNU userlands the engine runs on.
+_loki_resolve_path() {
+    local p="${1:-}"
+    [ -n "$p" ] || { printf '%s' ""; return 0; }
+    if command -v realpath >/dev/null 2>&1; then
+        realpath "$p" 2>/dev/null && return 0
+    fi
+    # python3 is a hard engine dependency; use it as the portable fallback.
+    python3 - "$p" <<'PYRESOLVE' 2>/dev/null && return 0
+import os, sys
+print(os.path.realpath(sys.argv[1]))
+PYRESOLVE
+    printf '%s' "$p"
+}
+
+# True (0) when TARGET_DIR is an engine-owned, freshly-minted build workspace
+# that Loki may auto-git-init without surprising a user. Two honest signals:
+#   1. LOKI_AUTO_GIT_INIT=1  -- explicit opt-in (non-SaaS automation).
+#   2. LOKI_TARGET_DIR is set AND realpath-contained under one of the
+#      colon-separated LOKI_WORKSPACE_ROOTS dirs (the v7.91.0 SaaS route: the
+#      BFF mints <root>/<buildId> and the server pins LOKI_TARGET_DIR to it).
+# A user's own folder (`loki start ./prd.md`, no workspace, roots unset) is
+# NEVER engine-owned -- it must not get a silent .git. Realpath containment (not
+# a prefix string match) so /root/build-other does not match /root/build.
+_loki_workspace_is_engine_owned() {
+    [ "${LOKI_AUTO_GIT_INIT:-0}" = "1" ] && return 0
+
+    local roots_raw="${LOKI_WORKSPACE_ROOTS:-}"
+    [ -n "${LOKI_TARGET_DIR:-}" ] || return 1
+    [ -n "$roots_raw" ] || return 1
+
+    local ws_real root_real
+    ws_real="$(_loki_resolve_path "${TARGET_DIR:-.}")"
+    [ -n "$ws_real" ] || return 1
+
+    local IFS=':'
+    local root
+    for root in $roots_raw; do
+        [ -n "$root" ] || continue
+        root_real="$(_loki_resolve_path "$root")"
+        [ -n "$root_real" ] || continue
+        # Exact match or contained: ws == root, or ws starts with root + "/".
+        if [ "$ws_real" = "$root_real" ] || case "$ws_real" in "$root_real"/*) true ;; *) false ;; esac; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# Plan #16 Option A-1: establish git in an engine-owned build workspace so the
+# review/verify gate (run_code_review) and branch-isolation chain can actually
+# run. Without git history, run_code_review's diff resolves empty and the gate
+# SKIPS (silently reporting PASS) -- so a build that was never reviewed could
+# earn a VERIFIED receipt. This makes the gate RUN; it does NOT force a green
+# (a build whose review/tests fail still gets an honest verdict).
+#
+# Constraints honored:
+#   - Engine-owned workspaces ONLY (see _loki_workspace_is_engine_owned). A
+#     user's own folder is never silently git-init'd.
+#   - Already a git repo (user's repo OR the engine source tree) -> NO-OP. Only
+#     a non-git workspace is initialized.
+#   - One INITIAL commit (not a bare init): a zero-commit unborn HEAD breaks the
+#     start-SHA capture (git rev-parse HEAD) and re-trips the HEAD~1 skip. The
+#     commit uses --allow-empty because a greenfield workspace at build start
+#     holds only .loki/ (the spec lands in .loki/specs/), which .loki/.gitignore
+#     excludes -> nothing to stage -> a bare commit would fail and leave an
+#     unborn HEAD. --allow-empty guarantees a real HEAD either way.
+#   - Neutral repo-local identity (loki-build) so the initial commit AND the
+#     later commit_session_changes commit never inherit a developer's global git
+#     identity. Repo-local sticks on a freshly-init'd workspace (no revert hook).
+#   - Secrets never committed: brownfield files are staged through the same
+#     secret-scan guard (_commit_path_looks_secret / _commit_scan_secret_file)
+#     used by commit_session_changes; any offender unstages the whole set and
+#     the initial commit falls back to --allow-empty (HEAD still established).
+maybe_git_init_engine_workspace() {
+    command -v git >/dev/null 2>&1 || return 0
+    _loki_workspace_is_engine_owned || return 0
+
+    local ws="${TARGET_DIR:-.}"
+    [ -d "$ws" ] || return 0
+
+    # Already a git repo (user repo or engine source tree): do nothing.
+    if git -C "$ws" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        return 0
+    fi
+
+    log_info "Engine-owned workspace is not a git repo; initializing for review/verify gates"
+
+    if ! git -C "$ws" init -q >/dev/null 2>&1; then
+        log_warn "git init failed in engine workspace; review gate will skip (non-fatal)"
+        return 0
+    fi
+
+    # Neutral repo-local identity for the initial AND session-end commits.
+    git -C "$ws" config user.name "loki-build" >/dev/null 2>&1 || true
+    git -C "$ws" config user.email "loki-build@autonomi.dev" >/dev/null 2>&1 || true
+
+    # Self-ignore .loki/ runtime state so no commit ever stages it (mirrors
+    # setup_agent_branch). Idempotent.
+    mkdir -p "$ws/.loki" 2>/dev/null || true
+    [ -f "$ws/.loki/.gitignore" ] || printf '*\n' > "$ws/.loki/.gitignore" 2>/dev/null || true
+
+    # Stage everything except .loki/ and an obvious-secret-path denylist (same
+    # first-cut excludes commit_session_changes uses). The scan loop below is the
+    # real guarantee for nested/weak secrets.
+    git -C "$ws" add -A \
+        ':!.loki' ':!.loki/' \
+        ':!.env' ':!.env.*' ':!*.env' \
+        ':!*.key' ':!*.pem' ':!*.p12' ':!*.keystore' \
+        ':!id_rsa*' ':!*.token' ':!credentials*' >/dev/null 2>&1 || true
+
+    # Secret-scan staged files. ANY offender -> unstage all (safe default: never
+    # commit a possible secret). The --allow-empty commit below still runs so a
+    # real HEAD is established regardless.
+    local _offenders=""
+    local _f
+    while IFS= read -r -d '' _f; do
+        [ -f "$ws/$_f" ] || continue
+        if _commit_path_looks_secret "$ws/$_f" || _commit_scan_secret_file "$ws/$_f"; then
+            _offenders="${_offenders}${_offenders:+, }${_f}"
+        fi
+    done < <(git -C "$ws" diff --cached --name-only -z 2>/dev/null)
+
+    if [ -n "$_offenders" ]; then
+        git -C "$ws" reset >/dev/null 2>&1 || true
+        log_warn "Initial commit: possible secret in ${_offenders}; left unstaged (baseline commit will be empty)"
+    fi
+
+    # ONE initial commit. --allow-empty: a greenfield workspace stages nothing
+    # (only .loki/, which is ignored), so a bare commit would fail and leave an
+    # unborn HEAD -- the exact failure mode this whole block exists to avoid.
+    if git -C "$ws" commit --allow-empty -q -m "loki: initial build workspace baseline" >/dev/null 2>&1; then
+        log_info "Initialized git in engine workspace (initial baseline commit created)"
+        audit_log "WORKSPACE_GIT_INIT" "workspace=$ws"
+    else
+        log_warn "Initial baseline commit failed; review gate may skip (non-fatal)"
+    fi
+    return 0
+}
+
 #===============================================================================
 # Branch Protection for Agent Changes
 #===============================================================================
@@ -9673,17 +10114,89 @@ run_code_review() {
     # common case) because git ignores the exclude pathspec for paths it does not
     # track. ':(exclude).git/' is harmless (git never diffs .git/) and is kept
     # only for parity with the evidence-gate exclusion list.
-    local _review_pathspec=(-- . ':(exclude).loki/' ':(exclude).git/' ':(exclude)**/.loki/**')
-    local diff_content
-    diff_content=$(git -C "${TARGET_DIR:-.}" diff HEAD~1 "${_review_pathspec[@]}" 2>/dev/null || git -C "${TARGET_DIR:-.}" diff --cached "${_review_pathspec[@]}" 2>/dev/null || echo "")
+    # Finding #596 + Plan #16: exclude .loki/, .git/, AND the standard dependency
+    # / build noise dirs. The A-2 temp-index `git add -A` below stages EVERY
+    # untracked file, and a fresh greenfield workspace has no root .gitignore yet
+    # (only .loki/.gitignore, scoped to .loki/). Without these excludes a build
+    # that ran `npm install` / `pip install` before writing a .gitignore would
+    # stage node_modules/ (or .venv/, dist/, build/) into the temp index, bloat
+    # the review diff to multi-MB, overflow the reviewer prompt, force NO_OUTPUT,
+    # and defeat the gate -- exactly the Finding #596 class. The diff pathspec
+    # filters the OUTPUT regardless of what the temp index staged, so this one
+    # list fixes both diff_content and changed_files. Mirrors the metrics-path
+    # noise set (run.sh:12592-12598) plus __pycache__ and vendor.
+    local _review_pathspec=(-- . \
+        ':(exclude).loki/' ':(exclude).git/' ':(exclude)**/.loki/**' \
+        ':(exclude)node_modules/' ':(exclude)**/node_modules/**' \
+        ':(exclude)venv/' ':(exclude).venv/' ':(exclude)**/venv/**' ':(exclude)**/.venv/**' \
+        ':(exclude)dist/' ':(exclude)build/' ':(exclude)**/dist/**' ':(exclude)**/build/**' \
+        ':(exclude)__pycache__/' ':(exclude)**/__pycache__/**' \
+        ':(exclude)vendor/' ':(exclude)**/vendor/**')
+
+    # Plan #16 (A-2): make the review diff base robust to shallow/fresh history,
+    # and surface NEW (untracked) files -- the whole greenfield build is new
+    # files, which `git diff <base>` (tracked-only) never shows.
+    #
+    # Base preference, mirroring the proven metrics-path fallback chain:
+    #   1. ${_LOKI_RUN_START_SHA} when it resolves to a commit -- the correct
+    #      per-run baseline (captured at run start; also what the summary/"Review
+    #      the work" command uses). After A-1, a fresh workspace has exactly one
+    #      commit at iteration 1, so HEAD~1 does NOT resolve -- the start-SHA is
+    #      what makes the gate run on iteration 1.
+    #   2. HEAD~1 when it resolves (the live engine-source case, deep history).
+    #   3. the git empty-tree object (computed, never a hardcoded SHA-1 constant,
+    #      so it survives a SHA-256 repo) so a single-commit repo still yields a
+    #      real diff against an empty baseline instead of an empty string.
+    local _review_base=""
+    if [ -n "${_LOKI_RUN_START_SHA:-}" ] && \
+       git -C "${TARGET_DIR:-.}" rev-parse --verify --quiet "${_LOKI_RUN_START_SHA}^{commit}" >/dev/null 2>&1; then
+        _review_base="${_LOKI_RUN_START_SHA}"
+    elif git -C "${TARGET_DIR:-.}" rev-parse --verify --quiet 'HEAD~1^{commit}' >/dev/null 2>&1; then
+        _review_base="HEAD~1"
+    else
+        _review_base="$(git -C "${TARGET_DIR:-.}" hash-object -t tree /dev/null 2>/dev/null || echo "")"
+    fi
+
+    # Build the review diff against a THROWAWAY index (GIT_INDEX_FILE points at a
+    # fresh, nonexistent path) so a `git add -A` captures the full working tree --
+    # new + modified files alike -- WITHOUT touching the real index. This avoids
+    # disturbing any other porcelain consumer (the evidence hard gate's status
+    # read, create_checkpoint's `git stash create`, commit_session_changes). The
+    # `.loki/.gitignore` (`*`) keeps runtime state out; the pathspec is a belt-
+    # and-suspenders exclude. `diff --cached <base>` then compares that staged
+    # snapshot to the baseline -- a real unified diff the reviewer can read.
+    local diff_content=""
+    local changed_files=""
+    if [ -n "$_review_base" ]; then
+        local _rev_idx
+        _rev_idx="$(mktemp -u "${TMPDIR:-/tmp}/loki-revidx.XXXXXX")"
+        GIT_INDEX_FILE="$_rev_idx" git -C "${TARGET_DIR:-.}" add -A 2>/dev/null || true
+        diff_content=$(GIT_INDEX_FILE="$_rev_idx" git -C "${TARGET_DIR:-.}" diff --cached "$_review_base" "${_review_pathspec[@]}" 2>/dev/null || echo "")
+        changed_files=$(GIT_INDEX_FILE="$_rev_idx" git -C "${TARGET_DIR:-.}" diff --cached --name-only "$_review_base" "${_review_pathspec[@]}" 2>/dev/null || echo "")
+        rm -f "$_rev_idx" 2>/dev/null || true
+    fi
+
     if [ -z "$diff_content" ]; then
-        log_info "Code review: No diff to review, skipping"
+        # Honesty (Finding #596 class): a silent PASS on an empty diff is a trust
+        # gap ONLY when the run actually produced changes we failed to diff.
+        # Distinguish a genuine no-op iteration (nothing changed -> legitimate
+        # PASS) from "changes exist but we could not compute a diff" (must not
+        # pass silently). Use the same .loki/.git-excluding porcelain the
+        # evidence gate uses to detect real changes independent of the diff base.
+        local _dirty
+        _dirty=$(git -C "${TARGET_DIR:-.}" status --porcelain "${_review_pathspec[@]}" 2>/dev/null | head -1 || echo "")
+        if [ -n "$_dirty" ] || [ -n "$changed_files" ]; then
+            # Return non-zero so the gate dispatcher records a failure (it calls
+            # track_gate_failure on the else branch). Do NOT call track_gate_failure
+            # here: it echoes its count to stdout (callers capture it) and the
+            # dispatcher would double-count.
+            log_warn "Code review: workspace has changes but the review diff is empty (could not compute a diff base); NOT passing the gate silently"
+            return 1
+        fi
+        log_info "Code review: no changes this iteration, skipping (genuine no-op)"
         return 0
     fi
 
-    local changed_files
-    changed_files=$(git -C "${TARGET_DIR:-.}" diff --name-only HEAD~1 "${_review_pathspec[@]}" 2>/dev/null || git -C "${TARGET_DIR:-.}" diff --name-only --cached "${_review_pathspec[@]}" 2>/dev/null || echo "")
-
     log_header "CODE REVIEW: $review_id"
 
     # Phase 3 (v7.0.0): managed code-review council. When the flag is on,
@@ -15914,9 +16427,13 @@ if __name__ == "__main__":
         esac
 
         # BUG-EC-013: Detect empty provider output (0 bytes = no work done)
+        # T2.5: track this distinct cause so the failure path can classify the
+        # durable LAST_ERROR record as provider_empty_output specifically.
+        local _empty_output=0
         if [ -f "$iter_output" ] && [ ! -s "$iter_output" ] && [ $exit_code -eq 0 ]; then
             log_warn "Provider returned empty output (0 bytes) despite exit code 0 -- treating as error"
             exit_code=1
+            _empty_output=1
         fi
 
         save_state $retry "exited" $exit_code
@@ -16029,27 +16546,33 @@ if __name__ == "__main__":
             # Static analysis gate
             if [ "${PHASE_STATIC_ANALYSIS:-true}" = "true" ]; then
                 log_info "Quality gate: static analysis..."
+                local _stg_t0=$(date +%s 2>/dev/null); local _stg_ok=pass
                 if enforce_static_analysis; then
                     clear_gate_failure "static_analysis"
                 else
+                    _stg_ok=fail
                     local sa_count
                     sa_count=$(track_gate_failure "static_analysis")
                     gate_failures="${gate_failures}static_analysis,"
                     log_warn "Static analysis FAILED ($sa_count consecutive) - findings injected into next iteration"
                 fi
+                emit_stage_complete "static_analysis" "$_stg_ok" "$_stg_t0"
             fi
             # Secure-by-default scan (v7.87.0). Advisory by default (never
             # blocks); records .loki/quality/security-findings.json each
             # iteration. Blocks only on un-waived HIGH when LOKI_SECURE_GATE=block.
             log_info "Quality gate: security scan (advisory)..."
+            local _stg_t0=$(date +%s 2>/dev/null); local _stg_ok=pass
             if run_secure_scan; then
                 clear_gate_failure "security_scan"
             else
+                _stg_ok=fail
                 local sec_count
                 sec_count=$(track_gate_failure "security_scan")
                 gate_failures="${gate_failures}security_scan,"
                 log_warn "Security gate BLOCKED ($sec_count consecutive) - un-waived HIGH findings (LOKI_SECURE_GATE=block)"
             fi
+            emit_stage_complete "security_scan" "$_stg_ok" "$_stg_t0"
             # BUG-ST-002: Check pause signal between quality gates
             if [ -f "${TARGET_DIR:-.}/.loki/PAUSE" ] || [ -f "${TARGET_DIR:-.}/.loki/STOP" ]; then
                 log_warn "Pause/stop signal detected between quality gates - deferring remaining gates"
@@ -16063,11 +16586,13 @@ if __name__ == "__main__":
             # Test coverage gate
             if [ "${PHASE_UNIT_TESTS:-true}" = "true" ]; then
                 log_info "Quality gate: test suite (pass/fail)..."
+                local _stg_t0=$(date +%s 2>/dev/null); local _stg_ok=pass
                 # F49: isolate HOME so the project's suite cannot pollute the
                 # user's real home when it execs the generated app.
                 if _loki_with_app_sandbox enforce_test_coverage; then
                     clear_gate_failure "test_coverage"
                 else
+                    _stg_ok=fail
                     local tc_count
                     tc_count=$(track_gate_failure "test_coverage")
                     gate_failures="${gate_failures}test_coverage,"
@@ -16081,6 +16606,7 @@ if __name__ == "__main__":
                         log_warn "Test suite gate FAILED ($tc_count consecutive) - must pass next iteration"
                     fi
                 fi
+                emit_stage_complete "test_suite" "$_stg_ok" "$_stg_t0"
             fi
             # BUG-ST-002: Check pause signal between quality gates (after test coverage)
             if [ -f "${TARGET_DIR:-.}/.loki/PAUSE" ] || [ -f "${TARGET_DIR:-.}/.loki/STOP" ]; then
@@ -16093,26 +16619,32 @@ if __name__ == "__main__":
             # Mock integrity gate (P0-3): block on CRITICAL/HIGH mock problems.
             if [ "${LOKI_GATE_MOCK:-true}" = "true" ] && [ "$ITERATION_COUNT" -gt 0 ]; then
                 log_info "Quality gate: mock integrity..."
+                local _stg_t0=$(date +%s 2>/dev/null); local _stg_ok=pass
                 if enforce_mock_integrity; then
                     clear_gate_failure "mock_integrity"
                 else
+                    _stg_ok=fail
                     local mk_count
                     mk_count=$(track_gate_failure "mock_integrity")
                     gate_failures="${gate_failures}mock_integrity,"
                     log_warn "Mock integrity gate FAILED ($mk_count consecutive) - CRITICAL/HIGH mock problems"
                 fi
+                emit_stage_complete "mock_integrity" "$_stg_ok" "$_stg_t0"
             fi
             # Test mutation integrity gate (P0-3): block on HIGH test-fitting.
             if [ "${LOKI_GATE_MUTATION:-true}" = "true" ] && [ "$ITERATION_COUNT" -gt 0 ]; then
                 log_info "Quality gate: test mutation integrity..."
+                local _stg_t0=$(date +%s 2>/dev/null); local _stg_ok=pass
                 if enforce_mutation_integrity; then
                     clear_gate_failure "mutation_integrity"
                 else
+                    _stg_ok=fail
                     local mt_count
                     mt_count=$(track_gate_failure "mutation_integrity")
                     gate_failures="${gate_failures}mutation_integrity,"
                     log_warn "Mutation integrity gate FAILED ($mt_count consecutive) - HIGH test-fitting detected"
                 fi
+                emit_stage_complete "mutation_integrity" "$_stg_ok" "$_stg_t0"
             fi
             # LSP diagnostics gate (P1-5 bash-route parity, v7.51.0; default-on
             # advisory-surfacing as of v7.57.0). Closes the parity gap: the Bun
@@ -16148,6 +16680,7 @@ if __name__ == "__main__":
             # runLSPDiagnosticsWriter: cwd=REPO_ROOT, --root=ctx.cwd).
             if { [ "${LOKI_GATE_LSP_DIAGNOSTICS:-true}" = "true" ] || [ "${LOKI_GATE_LSP_DIAGNOSTICS:-true}" = "1" ]; } && [ "$ITERATION_COUNT" -gt 0 ]; then
                 log_info "Quality gate: LSP diagnostics..."
+                local _stg_t0=$(date +%s 2>/dev/null); local _stg_ok=pass
                 # WRITER: route-neutral Python, same program as the Bun route.
                 if [ "${LOKI_GATE_LSP_WRITER:-1}" != "0" ]; then
                     ( cd "$PROJECT_DIR" && LOKI_DIR="${TARGET_DIR:-.}/.loki" python3 -m mcp.lsp_proxy --write-diagnostics --root "${TARGET_DIR:-.}" ) >/dev/null 2>&1 || true
@@ -16181,6 +16714,7 @@ else:
                 fi
                 case "$_lsp_verdict" in
                     block*)
+                        _stg_ok=fail
                         local _lsp_e _lsp_w
                         _lsp_e=$(printf '%s' "$_lsp_verdict" | awk '{print $2}')
                         _lsp_w=$(printf '%s' "$_lsp_verdict" | awk '{print $3}')
@@ -16207,6 +16741,7 @@ else:
                         log_info "LSP diagnostics: no lsp-diagnostics.json artifact (lsp not available) -- gate did not run"
                         ;;
                 esac
+                emit_stage_complete "lsp_diagnostics" "$_stg_ok" "$_stg_t0"
             fi
             # Semantic test-authenticity gate -- mid-iteration ADVISORY arm
             # (v7.57.0 default-on surfacing). Clones the mock arm (~15126)
@@ -16259,9 +16794,11 @@ else:
             # Code review gate (upgraded from advisory, with escalation)
             if [ "$PHASE_CODE_REVIEW" = "true" ] && [ "$ITERATION_COUNT" -gt 0 ]; then
                 log_info "Quality gate: code review..."
+                local _stg_t0=$(date +%s 2>/dev/null); local _stg_ok=pass
                 if run_code_review; then
                     clear_gate_failure "code_review"
                 else
+                    _stg_ok=fail
                     local cr_count
                     cr_count=$(track_gate_failure "code_review")
                     # BUG-QG-007: Always append to gate_failures regardless of escalation tier
@@ -16286,7 +16823,7 @@ else:
                         esac
                     fi
                     if [ "$_phase1_overrode" = "true" ]; then
-                        : # BLOCK lifted; continue without escalation
+                        _stg_ok=pass # BLOCK lifted; continue without escalation
                     elif [ "$cr_count" -ge "$GATE_PAUSE_LIMIT" ]; then
                         log_error "Gate escalation: code_review failed $cr_count times (>= $GATE_PAUSE_LIMIT) - forcing PAUSE for human intervention"
                         echo "PAUSE" > "${TARGET_DIR:-.}/.loki/signals/GATE_ESCALATION"
@@ -16316,6 +16853,7 @@ else:
                         bun "${SCRIPT_DIR}/../loki-ts/dist/loki.js" internal phase1-hooks reflect "$ITERATION_COUNT" 2>/dev/null || true
                     fi
                 fi
+                emit_stage_complete "code_review" "$_stg_ok" "$_stg_t0"
             fi
             # Auto-generate docs (default-on) BEFORE the staleness check and the
             # gate, so neither nags the user to run 'loki docs generate' by hand.
@@ -16330,26 +16868,32 @@ else:
             # Documentation quality gate - Gate 7 (Documentation Coverage)
             if [ "${LOKI_GATE_DOC_COVERAGE:-true}" = "true" ] && [ "$ITERATION_COUNT" -gt 0 ]; then
                 log_info "Quality gate: documentation coverage..."
+                local _stg_t0=$(date +%s 2>/dev/null); local _stg_ok=pass
                 if run_doc_quality_gate; then
                     clear_gate_failure "doc_coverage"
                 else
+                    _stg_ok=fail
                     local dc_count
                     dc_count=$(track_gate_failure "doc_coverage")
                     gate_failures="${gate_failures}doc_coverage,"
                     log_warn "Documentation coverage gate: Score below threshold ($dc_count consecutive)"
                 fi
+                emit_stage_complete "doc_coverage" "$_stg_ok" "$_stg_t0"
             fi
             # Magic Modules debate gate - Gate 12 (v6.77.0)
             if [ "${LOKI_GATE_MAGIC_DEBATE:-true}" = "true" ] && [ "$ITERATION_COUNT" -gt 0 ]; then
                 log_info "Quality gate: magic modules debate..."
+                local _stg_t0=$(date +%s 2>/dev/null); local _stg_ok=pass
                 if run_magic_debate_gate; then
                     clear_gate_failure "magic_debate"
                 else
+                    _stg_ok=fail
                     local md_count
                     md_count=$(track_gate_failure "magic_debate")
                     gate_failures="${gate_failures}magic_debate,"
                     log_warn "Magic Modules debate gate: BLOCK severity detected ($md_count consecutive)"
                 fi
+                emit_stage_complete "magic_debate" "$_stg_ok" "$_stg_t0"
             fi
             # Store gate failures for prompt injection
             if [ -n "$gate_failures" ]; then
@@ -16684,6 +17228,24 @@ else:
         # the "Will retry" log_warn below. TTY-gated, `|| true`, never tee'd.
         render_build_hud "${ITERATION_COUNT:-0}" "${rarv_phase:-?}" "${duration:-0}" || true
 
+        # T2.5: durable, classified failure record for `loki why`. Best-effort,
+        # never crashes the build. Skip signal-induced exits (130 SIGINT /
+        # 143 SIGTERM / 137 SIGKILL): a user/operator interrupt is not an error
+        # to record (mirrors the crash-capture exclusion above). Classification
+        # is conservative -- provider_empty_output | rate_limited | auth_error,
+        # else unknown; never fabricates a class that no signal supports.
+        if [ "$exit_code" -ne 130 ] && [ "$exit_code" -ne 143 ] && [ "$exit_code" -ne 137 ]; then
+            local _err_class _err_brief
+            _err_class="$(_loki_classify_iteration_error "$iter_output" "${_empty_output:-0}")"
+            case "$_err_class" in
+                provider_empty_output) _err_brief="The provider returned no output (0 bytes) on this iteration -- no work was done." ;;
+                rate_limited)          _err_brief="The provider rate-limited the request; the build will wait and retry." ;;
+                auth_error)            _err_brief="The provider rejected the request as unauthorized (check your login or API key)." ;;
+                *)                     _err_brief="Iteration ${ITERATION_COUNT:-?} failed with exit code ${exit_code} (cause not classified)." ;;
+            esac
+            _loki_write_last_error "${ITERATION_COUNT:-0}" "$_err_class" "$_err_brief" || true
+        fi
+
         # Checkpoint failed iteration state (v5.57.0)
         create_checkpoint "iteration-${ITERATION_COUNT} failed (exit=$exit_code)" "iteration-${ITERATION_COUNT}-fail"
 
@@ -16703,7 +17265,15 @@ else:
             wait_time=$rate_limit_wait
             local human_time=$(format_duration $wait_time)
             log_warn "Rate limit detected! Waiting until reset (~$human_time)..."
-            log_info "Rate limit resets at approximately $(date -v+${wait_time}S '+%I:%M %p' 2>/dev/null || date -d "+${wait_time} seconds" '+%I:%M %p' 2>/dev/null || echo 'soon')"
+            local _reset_at
+            _reset_at="$(date -v+${wait_time}S '+%I:%M %p' 2>/dev/null || date -d "+${wait_time} seconds" '+%I:%M %p' 2>/dev/null || echo 'soon')"
+            log_info "Rate limit resets at approximately $_reset_at"
+            # T2.7: elevate the wait to an explicit, reassuring INFO line (the
+            # human time was previously only at DEBUG inside detect_rate_limit's
+            # calculated-backoff branch) so a multi-minute wait does not look
+            # like a hang, and persist a machine-readable signal for watchers.
+            log_info "Rate-limited by the provider; waiting ~${wait_time}s (resets ${_reset_at}). This is normal, not a hang."
+            _loki_write_rate_limit_signal "$wait_time" "$_reset_at" || true
             notify_rate_limit "$wait_time"
         else
             wait_time=$(calculate_wait $retry)
@@ -16743,6 +17313,10 @@ else:
         done
         echo ""
 
+        # T2.7: the wait is over -- clear the RATE_LIMITED signal so it never
+        # lingers stale once the build resumes. Best-effort.
+        rm -f "${TARGET_DIR:-.}/.loki/signals/RATE_LIMITED" 2>/dev/null || true
+
         # Clean up per-iteration output file
         rm -f "$iter_output" 2>/dev/null
 
@@ -17727,8 +18301,15 @@ main() {
         fi
         # Release on session-process exit so a fresh `loki start` can
         # immediately re-acquire after this one finishes / is killed.
+        # T2.6: piggyback the existing lock-release trap (we deliberately do NOT
+        # add a new broad EXIT trap) to write a best-effort terminal record on an
+        # untrapped non-zero exit where the run status is still "running" -- so a
+        # post-crash `loki why` is not stale. _loki_terminal_record is a strict
+        # no-op on every graceful path (status already settled) and never alters
+        # the exit code. SIGKILL/power-loss stay uncatchable (no trap fires); the
+        # ENT-2 durable-resume path covers those.
         # shellcheck disable=SC2064
-        trap "safe_release_lock '$lock_file'" EXIT INT TERM HUP
+        trap "_loki_terminal_record || true; safe_release_lock '$lock_file'" EXIT INT TERM HUP
 
         # Check PID file after acquiring lock
         if [ -f "$pid_file" ]; then
@@ -17843,6 +18424,13 @@ main() {
     # resume/rollback sees the restored state. Zero behavior change for local.
     _loki_object_store_hydrate_checkpoints || true
 
+    # Plan #16 (A-1): establish git in an engine-owned, non-git build workspace
+    # BEFORE branch setup + start-SHA capture (both need a resolvable HEAD), so
+    # the per-iteration review/verify gate actually runs instead of skipping on
+    # an empty diff. No-op for the engine source tree, a user's own repo, or a
+    # non-engine-owned folder. See maybe_git_init_engine_workspace.
+    maybe_git_init_engine_workspace
+
     # Setup agent branch protection (isolates agent changes to a feature branch)
     setup_agent_branch
 
@@ -17884,6 +18472,13 @@ main() {
         fi
     fi
 
+    # Clear any stale per-run diagnosis record from a PRIOR run before this one
+    # starts. LAST_ERROR.json is a single side-record; if it survived a previous
+    # failed run it must not surface next to THIS run's outcome (a stale error
+    # shown beside a fresh success would be a fake-green-adjacent lie). Mirrors
+    # the RATE_LIMITED signal clear. Best-effort; never blocks the run.
+    rm -f "${TARGET_DIR:-.}/.loki/state/LAST_ERROR.json" 2>/dev/null || true
+
     if [ "$PARALLEL_MODE" = "true" ]; then
         # Parallel mode: orchestrate multiple worktrees
         log_header "Running in Parallel Mode"
@@ -18133,6 +18728,13 @@ except (json.JSONDecodeError, OSError): pass
 " 2>/dev/null || true
     fi
 
+    # T2.4: on ANY non-zero final result, surface a plain-language next step
+    # (print to stderr + write .loki/NEXT_STEPS.txt). Single chokepoint at the
+    # finalization exit so it fires once and never double-prints on success.
+    if [ "$result" != "0" ]; then
+        _loki_surface_why_hint || true
+    fi
+
     exit $result
 }