loki-mode 7.81.1 → 7.83.0

package/autonomy/run.sh

@@ -2674,34 +2674,35 @@ except Exception:
     fi
 
     # ---- Durable human-readable file: .loki/COMPLETION.txt --------------------
+    # Presentation-only receipt: a single fixed-width label column, the live-app
+    # URL elevated right under the outcome headline, and a consistent rule line.
+    # Stays pure ASCII (no emoji, no dashes, no color codes) so it pastes cleanly
+    # into a PR description or a chat. Same facts and values as before.
     {
         echo "Loki Mode run summary"
         echo "====================="
         echo ""
-        echo "Outcome:   $outcome_label"
-        echo "Branch:    $branch"
-        echo "Files changed: $files_changed (+$insertions / -$deletions)"
-        echo "Finished:  $ts"
-        echo ""
-        if [ -n "$delegate_branch" ]; then
-            echo "Delegate branch: $delegate_branch"
-        fi
-        if [ -n "$pr_url" ]; then
-            echo "Pull request: $pr_url"
-        elif [ "$outcome" = "complete" ]; then
-            echo "Pull request: not opened (set LOKI_DELEGATE_PR=1 to open one)"
-        fi
-        echo ""
+        printf '%-14s %s\n' "Outcome:" "$outcome_label"
         if [ -n "$live_app_url" ]; then
             # Compute the dashboard scheme the same way start_dashboard does
             # (url_scheme is local to that function, not visible here).
             local _dash_scheme="http"
             [ -n "${LOKI_TLS_CERT:-}" ] && [ -n "${LOKI_TLS_KEY:-}" ] && _dash_scheme="https"
-            echo "Your app is live at: $live_app_url  (served locally on this machine)"
-            echo "  Dashboard: ${_dash_scheme}://127.0.0.1:${DASHBOARD_PORT:-57374}/  (App Runner -> Live App)"
-            echo ""
+            printf '%-14s %s\n' "Live app:" "$live_app_url  (served locally on this machine)"
+            printf '%-14s %s\n' "Dashboard:" "${_dash_scheme}://127.0.0.1:${DASHBOARD_PORT:-57374}/  (App Runner -> Live App)"
+        fi
+        printf '%-14s %s\n' "Branch:" "$branch"
+        printf '%-14s %s\n' "Files:" "$files_changed (+$insertions / -$deletions)"
+        printf '%-14s %s\n' "Finished:" "$ts"
+        if [ -n "$delegate_branch" ]; then
+            printf '%-14s %s\n' "Delegate:" "$delegate_branch"
         fi
-        echo "Tasks: pending=$pending in_progress=$in_progress completed=$completed failed=$failed"
+        if [ -n "$pr_url" ]; then
+            printf '%-14s %s\n' "Pull request:" "$pr_url"
+        elif [ "$outcome" = "complete" ]; then
+            printf '%-14s %s\n' "Pull request:" "not opened (set LOKI_DELEGATE_PR=1 to open one)"
+        fi
+        printf '%-14s %s\n' "Tasks:" "pending=$pending in_progress=$in_progress completed=$completed failed=$failed"
         echo ""
         if [ -n "$evidence_inconclusive_line" ]; then
             echo "$evidence_inconclusive_line"
@@ -2901,10 +2902,130 @@ emit_completion_summary() {
     local outcome="${1:-complete}"
     local urgency="${2:-normal}"
     build_completion_summary "$outcome"
+    # Render the screenshot-worthy completion card inline on a foreground TTY run,
+    # AFTER the durable files are written. The card re-reads the persisted
+    # completion.json (never recomputes) so it can never diverge from the file.
+    print_completion_card
     send_notification "${_LOKI_SUMMARY_TITLE:-Run finished}" "${_LOKI_SUMMARY_BODY:-}" "$urgency"
     return 0
 }
 
+#===============================================================================
+# print_completion_card  (visible-delight completion card)
+#
+# Display-only. Renders a boxed summary card to the interactive TTY at the close
+# of a foreground run: outcome, branch, files changed (+ins/-del), the live-app
+# URL with a "try it" line when an app is running, the copy-pasteable review
+# command, and the recorded-assumptions count. This is the single most
+# screenshot-worthy moment of a run, which was previously only written to a file.
+#
+# It reads ONLY from the already-persisted .loki/state/completion.json (written
+# by build_completion_summary just before this is called) and the app-runner
+# state, so the card and the durable file are guaranteed identical. Nothing is
+# computed or written here.
+#
+# Gate (same shape as the HUD at the colors block): interactive stdout, not
+# --bg, and not opted out via LOKI_COMPLETION_CARD=0. Off-TTY / --bg / --json
+# paths emit nothing, so machine output stays byte-identical. Wrapped so any
+# internal failure still returns 0 and can never abort the completion path.
+#===============================================================================
+print_completion_card() {
+    # Gate first: emit nothing unless interactive TTY, not background, not opted out.
+    if ! { [ -t 1 ] && [ "${BACKGROUND_MODE:-false}" != "true" ] && [ "${LOKI_COMPLETION_CARD:-1}" != "0" ]; }; then
+        return 0
+    fi
+
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+    local _cj="$loki_dir/state/completion.json"
+    [ -f "$_cj" ] || return 0
+
+    # Pull the fields we render straight from the persisted record. The python3
+    # call emits one field per line in a fixed order; we read them line by line
+    # so empty fields (e.g. no pr_url) keep their positions (a single delimiter
+    # split would collapse adjacent empties). Any failure leaves the card
+    # unrendered. Trailing-newline guard: NUL-free, fields are single-line.
+    local _fields
+    _fields="$(python3 -c "
+import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(0)
+def g(k):
+    v=d.get(k,'')
+    return '' if v is None else str(v).replace('\n',' ')
+for k in ['outcome','branch','files_changed','insertions','deletions',
+          'review_cmd','pr_url','assumptions_total','assumptions_high']:
+    print(g(k))
+" "$_cj" 2>/dev/null)" || return 0
+    [ -z "$_fields" ] && return 0
+
+    local _outcome _branch _files _ins _del _review _pr _atotal _ahigh
+    {
+        IFS= read -r _outcome
+        IFS= read -r _branch
+        IFS= read -r _files
+        IFS= read -r _ins
+        IFS= read -r _del
+        IFS= read -r _review
+        IFS= read -r _pr
+        IFS= read -r _atotal
+        IFS= read -r _ahigh
+    } <<EOF
+$_fields
+EOF
+
+    # Human outcome label (mirror build_completion_summary's mapping).
+    local _label
+    case "$_outcome" in
+        complete)        _label="Completed" ;;
+        max_iterations)  _label="Max iterations" ;;
+        stopped)         _label="Stopped" ;;
+        force_stopped)   _label="Stopped (not verified-complete)" ;;
+        failed)          _label="Failed" ;;
+        intervention)    _label="Needs input" ;;
+        *)               _label="$_outcome" ;;
+    esac
+
+    # Live app URL (best-effort), same read as build_completion_summary.
+    local _url="" _app_state="$loki_dir/app-runner/state.json"
+    if [ -f "$_app_state" ]; then
+        _url="$(python3 -c "import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+    print(d.get('url','') if d.get('status')=='running' else '')
+except Exception:
+    print('')" "$_app_state" 2>/dev/null)" || _url=""
+    fi
+
+    # Box width matches log_header (66 inner columns). Render lines that fit;
+    # this is decoration, so over-wide content is simply not boxed-truncated
+    # (the durable file carries the full text).
+    echo ""
+    echo -e "${GREEN}+================================================================+${NC}"
+    echo -e "${GREEN}|${NC} ${BOLD}Loki Mode: ${_label}${NC}"
+    echo -e "${GREEN}|${NC}"
+    if [ -n "$_url" ]; then
+        echo -e "${GREEN}|${NC} ${BOLD}${CYAN}Your app is live at ${_url}${NC}  ${DIM}- open it to try it${NC}"
+        echo -e "${GREEN}|${NC}"
+    fi
+    echo -e "${GREEN}|${NC} Branch: ${BOLD}${_branch}${NC}"
+    echo -e "${GREEN}|${NC} Files:  ${BOLD}${_files}${NC} changed  ${GREEN}+${_ins}${NC} / ${RED}-${_del}${NC}"
+    case "$_atotal" in ''|0) : ;; *)
+        echo -e "${GREEN}|${NC} Spec assumptions recorded: ${BOLD}${_atotal}${NC} (${_ahigh} high) ${DIM}see .loki/assumptions/ledger.md${NC}"
+        ;;
+    esac
+    if [ -n "$_pr" ]; then
+        echo -e "${GREEN}|${NC} Pull request: ${_pr}"
+    fi
+    echo -e "${GREEN}|${NC}"
+    echo -e "${GREEN}|${NC} ${DIM}Review the work:${NC}"
+    echo -e "${GREEN}|${NC}   ${_review}"
+    echo -e "${GREEN}+================================================================+${NC}"
+    echo ""
+    return 0
+}
+
 #===============================================================================
 # on_run_complete  (Slice 3: opt-in local git output on success)
 #
@@ -3979,9 +4100,18 @@ EOF
     if [ -n "$BUDGET_LIMIT" ]; then
         # Validate budget limit is numeric before writing JSON
         if ! echo "$BUDGET_LIMIT" | grep -qE '^[0-9]+(\.[0-9]+)?$'; then
-            log_warn "Invalid BUDGET_LIMIT '$BUDGET_LIMIT', defaulting to 0"
-            BUDGET_LIMIT=0
+            log_warn "Invalid BUDGET_LIMIT '$BUDGET_LIMIT', ignoring (no cap set)"
+            BUDGET_LIMIT=""
+        fi
+        # Mirror the CLI guard: a non-positive cap (0/0.00) would make
+        # check_budget_limit pause before any work runs. Treat it as "no cap"
+        # rather than a silent pre-work pause.
+        if [ -n "$BUDGET_LIMIT" ] && ! awk -v b="$BUDGET_LIMIT" 'BEGIN{exit !(b+0 > 0)}'; then
+            log_warn "BUDGET_LIMIT '$BUDGET_LIMIT' is not greater than 0, ignoring (no cap set)"
+            BUDGET_LIMIT=""
         fi
+    fi
+    if [ -n "$BUDGET_LIMIT" ]; then
         cat > ".loki/metrics/budget.json" << BUDGET_EOF
 {
   "limit": $BUDGET_LIMIT,
@@ -10386,20 +10516,32 @@ check_primary_recovery() {
 # Returns: 0 if rate limit detected, 1 otherwise
 is_rate_limited() {
     local log_file="$1"
-
-    # Generic patterns that work across all providers
-    # - HTTP 429 status code
-    # - "rate limit" / "rate-limit" / "ratelimit" text
-    # - "too many requests" text
-    # - "quota exceeded" text
-    # - "request limit" text
-    # - "retry after" / "retry-after" headers
-    if grep -qiE '(429|rate.?limit|too many requests|quota exceeded|request limit|retry.?after)' "$log_file" 2>/dev/null; then
+    [ -f "$log_file" ] || return 1
+
+    # Only consider the TAIL of the log: a real provider rate-limit appears at the
+    # END of the iteration (the call that failed), not buried in mid-run prose.
+    # Scanning the whole file false-positived on the agent's OWN output (a build
+    # that printed or generated rate-limiting code -- "rate limit", "429",
+    # "retry-after" as source/text -- wrongly triggered a multi-minute wait).
+    local tail_txt
+    tail_txt=$(tail -n 40 "$log_file" 2>/dev/null) || return 1
+
+    # Require an ERROR CONTEXT, not a bare keyword: a rate-limit token must
+    # co-occur (same line) with a genuine provider-error frame -- an explicit
+    # error word ("Error"/"failed"/"exceeded"), an HTTP/status frame, or the
+    # canonical "429 Too Many Requests" phrasing. This distinguishes a real
+    # failing API line from the words "rate limit"/"retry-after"/"429" appearing
+    # in the model's own generated source or prose. Note: a bare "429" or a bare
+    # "retry-after" is NOT sufficient on its own (both occur in generated code).
+    local _err='(error|errored|failed|exceeded|http[ /]?[0-9]|status[: ]+[0-9]|too many requests)'
+    local _rl='(rate.?limit|too many requests|quota exceeded|request limit|429[ )"]*too many|retry.?after)'
+    if printf '%s\n' "$tail_txt" | grep -qiE "(${_rl}).*(${_err})|(${_err}).*(${_rl})" 2>/dev/null; then
         return 0
     fi
 
-    # Claude-specific: "resets Xam/pm" format
-    if grep -qE 'resets [0-9]+[ap]m' "$log_file" 2>/dev/null; then
+    # Claude-specific: the explicit "resets Xam/pm" reset-time line is itself an
+    # unambiguous provider rate-limit signal (the CLI only prints it on a limit).
+    if printf '%s\n' "$tail_txt" | grep -qE 'resets [0-9]+[ap]m' 2>/dev/null; then
         return 0
     fi
 
@@ -16572,6 +16714,35 @@ main() {
         exit 1
     fi
 
+    # v7.82: one-line "Building:" headline under the start banner so the opening
+    # frame reflects the user's own intent (their PRD / brief / this codebase),
+    # not a generic banner. Display-only, derived from already-resolved values:
+    # PRD basename for a file, the recorded brief text for a brief run, or fixed
+    # text for a no-arg in-repo run. Truncated to one tidy line. Gated to an
+    # interactive TTY, not --bg, and opt-out via LOKI_START_HEADLINE=0, so the
+    # off-TTY / background path is byte-identical (no output). Best-effort; a
+    # failure here must never affect parsing or the build flow.
+    if [ -t 1 ] && [ "${BACKGROUND_MODE:-false}" != "true" ] && [ "${LOKI_START_HEADLINE:-1}" != "0" ]; then
+        local _headline=""
+        if [ -n "$PRD_PATH" ]; then
+            _headline="$(basename "$PRD_PATH" 2>/dev/null || echo "$PRD_PATH")"
+        elif [ -f ".loki/state/brief.txt" ]; then
+            # Recorded one-line brief (written by cmd_start). Collapse to a single
+            # line and truncate to ~60 chars so the banner stays clean.
+            local _brief
+            _brief="$(tr '\n' ' ' < .loki/state/brief.txt 2>/dev/null | sed 's/  */ /g; s/^ //; s/ $//')"
+            if [ -n "$_brief" ]; then
+                if [ "${#_brief}" -gt 60 ]; then
+                    _brief="${_brief:0:57}..."
+                fi
+                _headline="\"$_brief\""
+            fi
+        fi
+        [ -z "$_headline" ] && _headline="analyzing this codebase"
+        echo -e "  ${BOLD}${CYAN}Building: ${_headline}${NC}"
+        echo ""
+    fi
+
     # Handle background mode
     if [ "$BACKGROUND_MODE" = "true" ]; then
         # Initialize .loki directory first

package/completions/_loki

@@ -11,7 +11,7 @@ function _loki {
     case $state in
         (args)
             case $line[1] in
-                start)
+                start|quick)
                     _loki_start
                     ;;
                 council)
@@ -67,8 +67,12 @@ function _loki {
                     _arguments \
                         '--follow[Follow logs in real-time]' \
                         '-f[Follow logs in real-time]' \
-                        '--lines[Number of lines]:number:' \
-                        '-n[Number of lines]:number:'
+                        '--tail[Number of lines to show]:number:' \
+                        '-n[Number of lines to show]:number:' \
+                        '--all[Show all lines]' \
+                        '-a[Show all lines]' \
+                        '--help[Show help]' \
+                        '-h[Show help]'
                     ;;
                 issue)
                     _loki_issue
@@ -97,7 +101,7 @@ function _loki {
                         '1:subcommand:(list show open share)'
                     ;;
                 completions)
-                    _arguments '1:shell:(bash zsh)'
+                    _arguments '1:shell:(bash zsh install)'
                     ;;
                 monitor)
                     _directories
@@ -118,6 +122,7 @@ function _loki_commands {
     commands=(
         'start:Start Loki Mode'
         'quick:Quick single-task mode'
+        'quickstart:Guided first build from your idea'
         'monitor:Monitor Docker Compose services with auto-fix'
         'demo:Interactive 60-second demo'
         'init:Interactive PRD builder'
@@ -125,11 +130,16 @@ function _loki_commands {
         'pause:Pause execution'
         'resume:Resume execution'
         'status:Show status'
+        'next:Run the right next step for the current build'
+        'ship:Finish the build (gates + PR advice) in one command'
+        'why:Explain why the last run did what it did'
         'dashboard:Dashboard commands'
+        'web:Start the web app surface'
         'logs:View session logs'
         'serve:Start API server'
         'api:API server commands'
         'sandbox:Docker sandbox commands'
+        'docker:Run Loki in a Docker container'
         'notify:Notification commands'
         'import:Import GitHub issues'
         'issue:GitHub issue commands'
@@ -149,8 +159,66 @@ function _loki_commands {
         'metrics:Session productivity report'
         'share:Share session report as GitHub Gist'
         'proof:Inspect/share proof-of-run artifacts'
+        'preview:Preview the locally-running app'
+        'deploy:Deploy the built product (CI/CD-aware)'
         'context:Context window management'
+        'ctx:Context window management (alias)'
         'code:Codebase intelligence'
+        'web:Start the web dashboard'
+        'plan:Preview the build plan for a spec'
+        'report:Reporting commands (cost, kpis, share)'
+        'cost:Show cost of recent runs'
+        'kpis:Key performance indicators'
+        'stats:Session statistics'
+        'preview:Open the running app preview'
+        'deploy:Advisory deploy command (print-only)'
+        'docker:Run Loki in a Docker container'
+        'mcp:MCP server commands'
+        'magic:Spec-driven component generation'
+        'assets:Export/import shareable team assets'
+        'spec:Living spec drift detection'
+        'verify:Deterministic PR verification'
+        'grill:Interrogate a spec before building'
+        'trust:Visible trust trajectory'
+        'trust-metrics:Trust metrics report'
+        'why:Explain the last build outcome'
+        'heal:Legacy system healing'
+        'modernize:Modernize a legacy system'
+        'migrate:Migration commands'
+        'analyze:Analyze a codebase'
+        'compliance:Compliance reporting'
+        'crash:Crash report management'
+        'otel:OpenTelemetry management'
+        'wiki:Wiki commands'
+        'explain:Explain Loki concepts'
+        'optimize:Optimization commands'
+        'review:Code review commands'
+        'export:Export session data'
+        'test:Run tests'
+        'ci:CI helpers'
+        'watch:Watch mode'
+        'audit:Audit commands'
+        'syslog:System log commands'
+        'cluster:Cluster commands'
+        'failover:Failover commands'
+        'remote:Remote execution commands'
+        'worktree:Git worktree commands'
+        'wt:Git worktree commands (alias)'
+        'trigger:Trigger commands'
+        'cleanup:Clean up Loki state'
+        'rollback:Roll back a change'
+        'update:Update Loki Mode'
+        'self-update:Update Loki Mode'
+        'setup-skill:Set up the Claude Code skill'
+        'quickstart:Quickstart guide'
+        'sentrux:Sentrux integration'
+        'state:Inspect run state'
+        'template:PRD template commands'
+        'ultracode:Ultra code review'
+        'voice:Voice commands'
+        'bench:Run benchmarks'
+        'open:Open a project resource'
+        'rc:Release candidate commands'
         'version:Show version'
         'completions:Output shell completions'
         'help:Show help'
@@ -160,7 +228,7 @@ function _loki_commands {
 
 function _loki_start {
     _arguments \
-        '--provider[AI provider]:provider name:(claude codex gemini)' \
+        '--provider[AI provider]:provider name:(claude codex cline aider)' \
         '--parallel[Parallel mode]' \
         '--background[Background mode]' \
         '--bg[Background mode]' \
@@ -174,7 +242,17 @@ function _loki_start {
         '-y[Skip confirmation prompts]' \
         '--budget[Cost budget limit in USD]:amount:' \
         '--max-iterations[Max iterations]:number:' \
-        '*:PRD File:_files'
+        '*:spec file:_loki_spec_files'
+}
+
+# Bias spec completion toward the file shapes Loki accepts (.md/.json/.txt/
+# .yaml/.yml), while still offering directories so the user can navigate into a
+# subfolder. Mirrors the bash completion. Makes the most-common command
+# tab-driven and typo-proof, cutting "PRD file not found" mistakes.
+function _loki_spec_files {
+    _alternative \
+        'specs:spec file:_files -g "*.(md|json|txt|yaml|yml)"' \
+        'dirs:directory:_files -/'
 }
 
 function _loki_council {

package/completions/loki.bash

@@ -5,7 +5,7 @@ _loki_completion() {
     _init_completion || return
 
     # Main subcommands (must match autonomy/loki main case statement)
-    local main_commands="start quick monitor demo init stop pause resume status dashboard logs serve api sandbox notify import github issue config provider reset memory compound checkpoint council dogfood projects enterprise secrets doctor watchdog audit metrics syslog onboard share proof explain plan report test ci watch telemetry agent context code run export review optimize heal migrate cluster worktree trigger failover remote version completions help"
+    local main_commands="start quick monitor demo init stop pause resume status next ship dashboard web serve api sandbox notify import github issue config provider reset memory compound checkpoint council dogfood projects enterprise secrets doctor watchdog audit metrics syslog onboard share proof explain plan report cost kpis stats test ci watch telemetry agent context ctx code run export review optimize heal modernize migrate cluster worktree wt trigger failover remote deploy docker mcp magic assets analyze compliance crash open otel preview quickstart rc rollback self-update sentrux setup-skill spec state template trust trust-metrics ultracode update verify voice why wiki bench cleanup logs grill docs cp version completions help"
 
     # 1. If we are on the first argument (subcommand)
     if [[ $cword -eq 1 ]]; then
@@ -15,10 +15,13 @@ _loki_completion() {
 
     # 2. Handle subcommands and their specific flags/args
     case "${words[1]}" in
-        start)
+        start|quick)
             # If the previous word was --provider, show provider names
             if [[ "$prev" == "--provider" ]]; then
-                COMPREPLY=( $(compgen -W "claude codex gemini" -- "$cur") )
+                # Active providers (loki rejects gemini since v7.5.18; cline/aider
+                # are supported). Keep in sync with providers/loader.sh
+                # SUPPORTED_PROVIDERS.
+                COMPREPLY=( $(compgen -W "claude codex cline aider" -- "$cur") )
                 return 0
             fi
 
@@ -29,8 +32,23 @@ _loki_completion() {
                 return 0
             fi
 
-            # Otherwise, default to file completion (for PRD files)
-            COMPREPLY=( $(compgen -f -- "$cur") )
+            # Bias toward the spec-shaped files Loki actually accepts
+            # (.md/.json/.txt/.yaml/.yml), plus directories so the user can still
+            # navigate into a subfolder. This makes the most-common command
+            # tab-driven and typo-proof, cutting "PRD file not found" mistakes.
+            # If the spec-filtered set is empty (no specs here), fall back to
+            # generic file completion so nothing the user could type is lost.
+            local _specs _dirs _eg_was_set=0
+            shopt -q extglob && _eg_was_set=1
+            shopt -s extglob
+            _specs=$(compgen -f -X '!*.@(md|json|txt|yaml|yml)' -- "$cur")
+            [[ "$_eg_was_set" -eq 0 ]] && shopt -u extglob
+            _dirs=$(compgen -d -- "$cur")
+            if [[ -n "$_specs" || -n "$_dirs" ]]; then
+                COMPREPLY=( $_specs $_dirs )
+            else
+                COMPREPLY=( $(compgen -f -- "$cur") )
+            fi
             ;;
 
         council)
@@ -119,7 +137,7 @@ _loki_completion() {
 
         logs)
             if [[ "$cur" == -* ]]; then
-                COMPREPLY=( $(compgen -W "--follow -f --lines -n --help" -- "$cur") )
+                COMPREPLY=( $(compgen -W "--tail -n --all -a --follow -f --help -h" -- "$cur") )
                 return 0
             fi
             ;;
@@ -195,7 +213,7 @@ _loki_completion() {
             ;;
 
         completions)
-            COMPREPLY=( $(compgen -W "bash zsh" -- "$cur") )
+            COMPREPLY=( $(compgen -W "bash zsh install" -- "$cur") )
             ;;
 
         context|ctx)

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "7.81.1"
+__version__ = "7.83.0"
 
 # Expose the control app for easy import
 try:

package/dashboard/audit.py

@@ -21,6 +21,7 @@ import logging.handlers
 import os
 import socket
 import sys
+import threading
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Optional
@@ -47,6 +48,16 @@ _SYSLOG_PROTO = os.environ.get("LOKI_AUDIT_SYSLOG_PROTO", "udp").lower().strip()
 INTEGRITY_ENABLED = os.environ.get("LOKI_AUDIT_NO_INTEGRITY", "").lower() not in ("true", "1", "yes")
 _last_hash: str = "0" * 64  # Genesis hash
 
+# Serializes the chain read-modify-write + file append in log_event(). Without
+# it, concurrent callers (the dashboard fans audit writes out across async
+# handlers / asyncio.to_thread workers) interleave the unsynchronized
+# _last_hash RMW with the file append: lines get written in a different order
+# than the hashes were chained, which breaks the tamper-evident chain so
+# verify_all_logs() reports valid:False even though no entry was tampered with.
+# Holding this lock makes "compute hash, update _last_hash, append the line" a
+# single atomic step so on-disk line order always matches chain order.
+_hash_lock = threading.Lock()
+
 
 def _recover_last_hash() -> str:
     """Recover the last integrity hash from the most recent audit log file.
@@ -254,20 +265,35 @@ def log_event(
         "details": details or {},
     }
 
-    # Tamper-evident chain hash
+    # Tamper-evident chain hash + file append, serialized as one atomic step.
+    #
+    # The chain hash is a read-modify-write of the module-global _last_hash, and
+    # the line must land in the file in the same order the hashes were chained.
+    # _hash_lock guards the whole "compute hash -> update _last_hash -> append"
+    # critical section so concurrent callers cannot interleave and break the
+    # chain (see _hash_lock definition above).
+    #
+    # NOTE for async callers: log_event() does blocking file I/O while holding
+    # this lock. When called from an asyncio handler it SHOULD be offloaded with
+    # `await asyncio.to_thread(audit.log_event, ...)` so a slow disk does not
+    # stall the dashboard event loop. The thread-safety here is what makes that
+    # offload safe; rewriting every call site to async is a separate, larger
+    # change and is intentionally not done here.
     global _last_hash
-    if INTEGRITY_ENABLED:
-        entry_json = json.dumps(entry, sort_keys=True, default=str)
-        entry["_integrity_hash"] = _compute_chain_hash(entry_json, _last_hash)
-        _last_hash = entry["_integrity_hash"]
+    with _hash_lock:
+        if INTEGRITY_ENABLED:
+            entry_json = json.dumps(entry, sort_keys=True, default=str)
+            entry["_integrity_hash"] = _compute_chain_hash(entry_json, _last_hash)
+            _last_hash = entry["_integrity_hash"]
 
-    log_file = _get_current_log_file()
-    _rotate_logs_if_needed(log_file)
+        log_file = _get_current_log_file()
+        _rotate_logs_if_needed(log_file)
 
-    with open(log_file, "a") as f:
-        f.write(json.dumps(entry) + "\n")
+        with open(log_file, "a") as f:
+            f.write(json.dumps(entry) + "\n")
 
-    # Forward to syslog if configured
+    # Forward to syslog if configured (outside the lock: fire-and-forget and
+    # must never extend the critical section / block other writers).
     _forward_to_syslog(entry)
 
     return entry