loki-mode 5.37.0 → 5.38.0

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Multi-agent autonomous startup system. Triggers on "Loki Mode". Takes PRD to deployed product with zero human intervention. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v5.37.0
+# Loki Mode v5.38.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -260,4 +260,4 @@ The following features are documented in skill modules but not yet fully automat
 | Quality gates 3-reviewer system | Implemented (v5.35.0) | 5 specialist reviewers in `skills/quality-gates.md`; execution in run.sh |
 | Benchmarks (HumanEval, SWE-bench) | Infrastructure only | Runner scripts and datasets exist in `benchmarks/`; no published results |
 
-**v5.37.0 | enterprise: TLS, OIDC/SSO, audit default-on, budget controls, watchdog, secrets, OpenClaw | ~260 lines core**
+**v5.38.0 | feat: branch protection, prometheus metrics, log integrity, OpenClaw bridge | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-5.37.0
+5.38.0

package/autonomy/loki

@@ -321,6 +321,7 @@ show_help() {
     echo "  memory [cmd]     Cross-project learnings (list|show|search|stats)"
     echo "  compound [cmd]   Knowledge compounding (list|show|search|run|stats)"
     echo "  council [cmd]    Completion council (status|verdicts|convergence|force-review|report)"
+    echo "  metrics          Prometheus/OpenMetrics metrics from dashboard"
     echo "  dogfood          Show self-development statistics"
     echo "  secrets [cmd]    API key status and validation (status|validate)"
     echo "  reset [target]   Reset session state (all|retries|failed)"
@@ -4309,6 +4310,12 @@ main() {
         watchdog)
             cmd_watchdog "$@"
             ;;
+        audit)
+            cmd_audit "$@"
+            ;;
+        metrics)
+            cmd_metrics "$@"
+            ;;
         version|--version|-v)
             cmd_version
             ;;
@@ -4326,6 +4333,87 @@ main() {
     esac
 }
 
+# Agent action audit log
+cmd_audit() {
+    local subcommand="${1:-help}"
+    local audit_file="$LOKI_DIR/logs/agent-audit.jsonl"
+
+    case "$subcommand" in
+        log)
+            if [ ! -f "$audit_file" ]; then
+                echo -e "${YELLOW}No audit log found at $audit_file${NC}"
+                echo "Agent action auditing records entries during loki sessions."
+                exit 0
+            fi
+            local lines="${2:-50}"
+            echo -e "${BOLD}Agent Audit Log${NC} (last $lines entries)"
+            echo "---"
+            tail -n "$lines" "$audit_file" | while IFS= read -r line; do
+                if command -v python3 &>/dev/null; then
+                    python3 -c "
+import json, sys
+try:
+    e = json.loads(sys.argv[1])
+    ts = e.get('timestamp', '?')
+    act = e.get('action', '?')
+    desc = e.get('description', '')
+    it = e.get('iteration', 0)
+    print(f'  [{ts}] [{act}] iter={it} {desc}')
+except: print(f'  {sys.argv[1]}')
+" "$line" 2>/dev/null || echo "  $line"
+                else
+                    echo "  $line"
+                fi
+            done
+            ;;
+        count)
+            if [ ! -f "$audit_file" ]; then
+                echo -e "${YELLOW}No audit log found${NC}"
+                exit 0
+            fi
+            echo -e "${BOLD}Agent Action Counts${NC}"
+            echo "---"
+            if command -v python3 &>/dev/null; then
+                python3 -c "
+import json, sys
+from collections import Counter
+counts = Counter()
+for line in open(sys.argv[1]):
+    try:
+        e = json.loads(line)
+        counts[e.get('action', 'unknown')] += 1
+    except: pass
+for action, count in sorted(counts.items(), key=lambda x: -x[1]):
+    print(f'  {action:25s} {count}')
+print(f'  {\"---\":25s} ---')
+print(f'  {\"TOTAL\":25s} {sum(counts.values())}')
+" "$audit_file" 2>/dev/null
+            else
+                echo "  python3 required for count summary"
+            fi
+            ;;
+        --help|-h|help)
+            echo -e "${BOLD}loki audit${NC} - Agent action audit log"
+            echo ""
+            echo "Usage: loki audit <subcommand>"
+            echo ""
+            echo "Subcommands:"
+            echo "  log [N]     Show last N audit log entries (default: 50)"
+            echo "  count       Count actions by type"
+            echo "  help        Show this help"
+            echo ""
+            echo "The agent audit log records actions taken during Loki sessions,"
+            echo "including CLI invocations, git commits, and session lifecycle events."
+            echo "Log file: $audit_file"
+            ;;
+        *)
+            echo -e "${RED}Unknown audit subcommand: $subcommand${NC}"
+            echo "Run 'loki audit help' for usage."
+            exit 1
+            ;;
+    esac
+}
+
 # Reset session state
 cmd_reset() {
     require_jq
@@ -6962,6 +7050,51 @@ for line in sys.stdin:
     esac
 }
 
+# Fetch and display Prometheus metrics from dashboard
+cmd_metrics() {
+    local subcommand="${1:-}"
+    local port="${LOKI_DASHBOARD_PORT:-57374}"
+    local host="127.0.0.1"
+
+    case "$subcommand" in
+        help|--help|-h)
+            echo -e "${BOLD}loki metrics${NC} - Prometheus/OpenMetrics metrics"
+            echo ""
+            echo "Usage: loki metrics [options]"
+            echo ""
+            echo "Fetches metrics from the dashboard API in Prometheus/OpenMetrics format."
+            echo "The dashboard must be running (loki dashboard start or loki serve)."
+            echo ""
+            echo "Options:"
+            echo "  help    Show this help"
+            echo ""
+            echo "Environment:"
+            echo "  LOKI_DASHBOARD_PORT   Dashboard port (default: 57374)"
+            echo ""
+            echo "Examples:"
+            echo "  loki metrics          # Display all metrics"
+            echo "  loki metrics | grep loki_cost_usd   # Filter specific metric"
+            ;;
+        "")
+            # Fetch metrics from dashboard
+            local url="http://${host}:${port}/metrics"
+            local response
+            response=$(curl -sf "$url" 2>/dev/null)
+            if [ $? -ne 0 ]; then
+                echo -e "${RED}Error: Could not connect to dashboard at ${url}${NC}"
+                echo "Make sure the dashboard is running: loki serve"
+                exit 1
+            fi
+            echo "$response"
+            ;;
+        *)
+            echo -e "${RED}Unknown metrics command: $subcommand${NC}"
+            echo "Run 'loki metrics help' for usage."
+            exit 1
+            ;;
+    esac
+}
+
 # Output shell completion scripts
 cmd_completions() {
     local shell="${1:-bash}"

package/autonomy/run.sh

@@ -135,6 +135,11 @@
 #   LOKI_PROMPT_INJECTION - Enable HUMAN_INPUT.md processing (default: false)
 #                           Set to "true" only in trusted environments
 #
+# Branch Protection (agent isolation):
+#   LOKI_BRANCH_PROTECTION     - Create feature branch for agent changes (default: false)
+#                                Agent works on loki/session-<timestamp>-<pid> branch
+#                                Creates PR on session end if gh CLI is available
+#
 # Process Supervision (opt-in):
 #   LOKI_WATCHDOG              - Enable process health monitoring (default: false)
 #   LOKI_WATCHDOG_INTERVAL     - Check interval in seconds (default: 30)
@@ -1800,6 +1805,7 @@ merge_feature() {
             if resolve_conflicts_with_ai "$feature"; then
                 # AI resolved conflicts, commit the merge
                 git commit -m "feat: Merge $feature (AI-resolved conflicts)"
+                audit_agent_action "git_commit" "Committed changes" "merge=$feature,resolution=ai"
                 log_info "Merged with AI conflict resolution: $feature"
             else
                 # AI resolution failed, abort merge
@@ -3403,6 +3409,145 @@ EOF
     echo "$log_entry" >> "$audit_file"
 }
 
+#===============================================================================
+# Branch Protection for Agent Changes
+#===============================================================================
+
+setup_agent_branch() {
+    # Create an isolated feature branch for agent changes.
+    # This prevents agents from committing directly to the main branch.
+    # Controlled by LOKI_BRANCH_PROTECTION env var (default: false).
+    local branch_protection="${LOKI_BRANCH_PROTECTION:-false}"
+
+    if [ "$branch_protection" != "true" ]; then
+        log_info "Branch protection disabled (LOKI_BRANCH_PROTECTION=${branch_protection})"
+        return 0
+    fi
+
+    # Ensure we are inside a git repository
+    if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+        log_warn "Not a git repository - skipping branch protection"
+        return 0
+    fi
+
+    local timestamp
+    timestamp=$(date +%s)
+    local branch_name="loki/session-${timestamp}-$$"
+
+    log_info "Branch protection enabled - creating agent branch: $branch_name"
+
+    # Create and checkout the feature branch
+    if ! git checkout -b "$branch_name" 2>/dev/null; then
+        log_error "Failed to create agent branch: $branch_name"
+        return 1
+    fi
+
+    # Store the branch name for later use (PR creation, cleanup)
+    mkdir -p .loki/state
+    echo "$branch_name" > .loki/state/agent-branch.txt
+
+    log_info "Agent branch created: $branch_name"
+    audit_log "BRANCH_PROTECTION" "branch=$branch_name"
+    echo "$branch_name"
+}
+
+create_session_pr() {
+    # Push the agent branch and create a PR if gh CLI is available.
+    # Called during session cleanup to submit agent changes for review.
+    local branch_file=".loki/state/agent-branch.txt"
+
+    if [ ! -f "$branch_file" ]; then
+        # No agent branch was created (branch protection was off)
+        return 0
+    fi
+
+    local branch_name
+    branch_name=$(cat "$branch_file" 2>/dev/null)
+
+    if [ -z "$branch_name" ]; then
+        return 0
+    fi
+
+    log_info "Pushing agent branch: $branch_name"
+
+    # Check if there are any commits on this branch beyond the base
+    local commit_count
+    commit_count=$(git rev-list --count HEAD ^"$(git merge-base HEAD main 2>/dev/null || echo HEAD)" 2>/dev/null || echo "0")
+
+    if [ "$commit_count" = "0" ]; then
+        log_info "No commits on agent branch - skipping PR creation"
+        return 0
+    fi
+
+    # Push the branch
+    if ! git push -u origin "$branch_name" 2>/dev/null; then
+        log_warn "Failed to push agent branch: $branch_name"
+        return 1
+    fi
+
+    # Create PR if gh CLI is available
+    if command -v gh &>/dev/null; then
+        local pr_url
+        pr_url=$(gh pr create \
+            --title "Loki Mode: Agent session changes ($branch_name)" \
+            --body "Automated changes from Loki Mode agent session.
+
+Branch: \`$branch_name\`
+Session PID: $$
+Created: $(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            --head "$branch_name" 2>/dev/null) || true
+
+        if [ -n "$pr_url" ]; then
+            log_info "PR created: $pr_url"
+            audit_log "PR_CREATED" "branch=$branch_name,url=$pr_url"
+        else
+            log_warn "Failed to create PR - branch pushed to: $branch_name"
+        fi
+    else
+        log_info "gh CLI not available - branch pushed to: $branch_name"
+        log_info "Create a PR manually for branch: $branch_name"
+    fi
+}
+
+#===============================================================================
+# Agent Action Auditing
+#===============================================================================
+
+audit_agent_action() {
+    # Record agent actions to a JSONL audit trail.
+    # Fire-and-forget: errors are silently ignored to avoid blocking execution.
+    # Args: action_type, description, [details]
+    local action_type="${1:-unknown}"
+    local description="${2:-}"
+    local details="${3:-}"
+    local audit_file=".loki/logs/agent-audit.jsonl"
+
+    (
+        mkdir -p .loki/logs 2>/dev/null
+
+        # Requires python3 for JSON formatting; skip silently if unavailable
+        command -v python3 &>/dev/null || exit 0
+
+        local timestamp
+        timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+        local iter="${ITERATION_COUNT:-0}"
+        local pid="$$"
+
+        python3 -c "
+import json, sys
+entry = {
+    'timestamp': sys.argv[1],
+    'action': sys.argv[2],
+    'description': sys.argv[3],
+    'details': sys.argv[4],
+    'iteration': int(sys.argv[5]),
+    'pid': int(sys.argv[6])
+}
+print(json.dumps(entry))
+" "$timestamp" "$action_type" "$description" "$details" "$iter" "$pid" >> "$audit_file" 2>/dev/null
+    ) &
+}
+
 check_staged_autonomy() {
     # In staged autonomy mode, write plan and wait for approval
     local plan_file="$1"
@@ -5870,6 +6015,9 @@ run_autonomous() {
         log_info "RARV Phase: $rarv_phase -> Tier: $CURRENT_TIER ($tier_param)"
 
         set +e
+        # Audit: record CLI invocation
+        audit_agent_action "cli_invoke" "Starting iteration $ITERATION_COUNT" "provider=${PROVIDER_NAME:-claude},tier=$CURRENT_TIER"
+
         # Provider-specific invocation with dynamic tier selection
         case "${PROVIDER_NAME:-claude}" in
             claude)
@@ -6763,8 +6911,12 @@ main() {
         load_solutions_context "general development"
     fi
 
+    # Setup agent branch protection (isolates agent changes to a feature branch)
+    setup_agent_branch
+
     # Log session start for audit
     audit_log "SESSION_START" "prd=$PRD_PATH,dashboard=$ENABLE_DASHBOARD,staged_autonomy=$STAGED_AUTONOMY,parallel=$PARALLEL_MODE"
+    audit_agent_action "session_start" "Session started" "prd=$PRD_PATH,provider=${PROVIDER_NAME:-claude}"
 
     # Emit session start event for dashboard
     emit_event_json "session_start" \
@@ -6859,6 +7011,10 @@ main() {
             --context "{\"provider\":\"${PROVIDER_NAME:-claude}\",\"iterations\":$ITERATION_COUNT,\"exit_code\":$result}"
     fi
 
+    # Create PR from agent branch if branch protection was enabled
+    create_session_pr
+    audit_agent_action "session_stop" "Session ended" "result=$result,iterations=$ITERATION_COUNT"
+
     # Cleanup
     stop_dashboard
     stop_status_monitor

package/autonomy/sandbox.sh

@@ -820,8 +820,8 @@ start_sandbox() {
         "--security-opt=no-new-privileges:true"
         "--cap-drop=ALL"
         "--cap-add=CHOWN"
-        "--cap-add=SETUID"
-        "--cap-add=SETGID"
+        # SETUID/SETGID intentionally omitted: container runs as non-root (UID 1000)
+        # and should not be able to change UID/GID, which would undermine isolation
 
         # Network
         "--network=$SANDBOX_NETWORK"

package/dashboard/__init__.py

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

package/dashboard/audit.py

@@ -5,10 +5,20 @@ Enabled by default. Disable with LOKI_AUDIT_DISABLED=true environment variable.
 Legacy env var LOKI_ENTERPRISE_AUDIT=true always enables audit (backward compat).
 
 Audit logs: ~/.loki/dashboard/audit/
+
+Syslog forwarding (optional):
+  Set LOKI_AUDIT_SYSLOG_HOST to enable forwarding to a centralized syslog server.
+  LOKI_AUDIT_SYSLOG_PORT defaults to 514.
+  LOKI_AUDIT_SYSLOG_PROTO defaults to "udp" (also supports "tcp").
 """
 
+import hashlib
 import json
+import logging
+import logging.handlers
 import os
+import socket
+import sys
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Optional
@@ -25,12 +35,58 @@ AUDIT_DIR = Path.home() / ".loki" / "dashboard" / "audit"
 MAX_LOG_SIZE_MB = int(os.environ.get("LOKI_AUDIT_MAX_SIZE_MB", "10"))
 MAX_LOG_FILES = int(os.environ.get("LOKI_AUDIT_MAX_FILES", "10"))
 
+# Syslog forwarding (optional, off by default)
+_SYSLOG_HOST = os.environ.get("LOKI_AUDIT_SYSLOG_HOST", "").strip()
+_SYSLOG_PORT = int(os.environ.get("LOKI_AUDIT_SYSLOG_PORT", "514"))
+_SYSLOG_PROTO = os.environ.get("LOKI_AUDIT_SYSLOG_PROTO", "udp").lower().strip()
+
+# Integrity chain hashing (tamper-evident logging)
+# Disable with LOKI_AUDIT_NO_INTEGRITY=true
+INTEGRITY_ENABLED = os.environ.get("LOKI_AUDIT_NO_INTEGRITY", "").lower() not in ("true", "1", "yes")
+_last_hash: str = "0" * 64  # Genesis hash
+
+# Actions considered security-relevant (logged at WARNING level in syslog)
+_SECURITY_ACTIONS = frozenset({
+    "delete", "kill", "stop", "login", "logout",
+    "create_token", "revoke_token",
+})
+
+_syslog_handler: logging.handlers.SysLogHandler | None = None
+SYSLOG_ENABLED: bool = False
+
+if _SYSLOG_HOST:
+    try:
+        _socktype = socket.SOCK_STREAM if _SYSLOG_PROTO == "tcp" else socket.SOCK_DGRAM
+        _syslog_handler = logging.handlers.SysLogHandler(
+            address=(_SYSLOG_HOST, _SYSLOG_PORT),
+            facility=logging.handlers.SysLogHandler.LOG_LOCAL0,
+            socktype=_socktype,
+        )
+        _syslog_handler.setFormatter(logging.Formatter("loki-audit: %(message)s"))
+        SYSLOG_ENABLED = True
+    except Exception as _exc:
+        print(
+            f"[loki-audit] WARNING: Failed to configure syslog handler "
+            f"({_SYSLOG_HOST}:{_SYSLOG_PORT}/{_SYSLOG_PROTO}): {_exc}",
+            file=sys.stderr,
+        )
+        _syslog_handler = None
+
 
 def _ensure_audit_dir() -> None:
     """Ensure the audit directory exists."""
     AUDIT_DIR.mkdir(parents=True, exist_ok=True)
 
 
+def _compute_chain_hash(entry_json: str, prev_hash: str) -> str:
+    """Compute a SHA-256 chain hash linking this entry to the previous one.
+
+    Each hash depends on the previous entry's hash, creating a tamper-evident
+    chain. If any entry is modified, all subsequent hashes will be invalid.
+    """
+    return hashlib.sha256((prev_hash + entry_json).encode("utf-8")).hexdigest()
+
+
 def _get_current_log_file() -> Path:
     """Get the current audit log file (date-based)."""
     _ensure_audit_dir()
@@ -68,6 +124,30 @@ def _cleanup_old_logs() -> None:
         oldest.unlink()
 
 
+def _forward_to_syslog(entry: dict) -> None:
+    """Forward an audit entry to syslog if configured. Fire-and-forget."""
+    if _syslog_handler is None:
+        return
+    try:
+        message = json.dumps(entry, separators=(",", ":"))
+        action = entry.get("action", "")
+        is_security = action in _SECURITY_ACTIONS or not entry.get("success", True)
+        level = logging.WARNING if is_security else logging.INFO
+        record = logging.LogRecord(
+            name="loki-audit",
+            level=level,
+            pathname="",
+            lineno=0,
+            msg=message,
+            args=(),
+            exc_info=None,
+        )
+        _syslog_handler.emit(record)
+    except Exception:
+        # Fire-and-forget: never block the main audit write path
+        pass
+
+
 def log_event(
     action: str,
     resource_type: str,
@@ -115,12 +195,22 @@ def log_event(
         "details": details or {},
     }
 
+    # Tamper-evident chain hash
+    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"]
+
     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")
 
+    # Forward to syslog if configured
+    _forward_to_syslog(entry)
+
     return entry
 
 
@@ -257,3 +347,67 @@ def get_audit_summary(days: int = 7) -> dict:
 def is_audit_enabled() -> bool:
     """Check if audit logging is enabled (on by default, disable with LOKI_AUDIT_DISABLED=true)."""
     return ENTERPRISE_AUDIT_ENABLED
+
+
+def verify_log_integrity(log_file: str) -> dict:
+    """Verify the integrity chain of a JSONL audit log file.
+
+    Reads each line, recomputes the chain hash from the genesis hash,
+    and compares it to the stored _integrity_hash. If any entry has been
+    tampered with, all subsequent hashes will also fail to match.
+
+    Args:
+        log_file: Path to the JSONL audit log file to verify.
+
+    Returns:
+        A dict with:
+          - valid (bool): True if the entire chain is intact.
+          - entries_checked (int): Number of entries verified.
+          - first_tampered_line (int | None): 1-based line number of the
+            first entry where the hash chain broke, or None if valid.
+    """
+    prev_hash = "0" * 64  # Genesis hash
+    entries_checked = 0
+
+    try:
+        with open(log_file, "r") as f:
+            for line_num, line in enumerate(f, start=1):
+                line = line.strip()
+                if not line:
+                    continue
+
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    return {
+                        "valid": False,
+                        "entries_checked": entries_checked,
+                        "first_tampered_line": line_num,
+                    }
+
+                stored_hash = entry.pop("_integrity_hash", None)
+                if stored_hash is None:
+                    # Entry has no integrity hash -- chain is broken
+                    return {
+                        "valid": False,
+                        "entries_checked": entries_checked,
+                        "first_tampered_line": line_num,
+                    }
+
+                entry_json = json.dumps(entry, sort_keys=True, default=str)
+                expected_hash = _compute_chain_hash(entry_json, prev_hash)
+
+                if stored_hash != expected_hash:
+                    return {
+                        "valid": False,
+                        "entries_checked": entries_checked,
+                        "first_tampered_line": line_num,
+                    }
+
+                prev_hash = stored_hash
+                entries_checked += 1
+
+    except FileNotFoundError:
+        return {"valid": True, "entries_checked": 0, "first_tampered_line": None}
+
+    return {"valid": True, "entries_checked": entries_checked, "first_tampered_line": None}

package/dashboard/auth.py

@@ -35,6 +35,23 @@ OIDC_CLIENT_ID = os.environ.get("LOKI_OIDC_CLIENT_ID", "")
 OIDC_AUDIENCE = os.environ.get("LOKI_OIDC_AUDIENCE", "")  # Usually same as client_id
 OIDC_ENABLED = bool(OIDC_ISSUER and OIDC_CLIENT_ID)
 
+# Role-to-scope mapping (predefined roles)
+ROLES = {
+    "admin": ["*"],  # Full access
+    "operator": ["control", "read", "write"],  # Start/stop/pause, view+edit dashboard
+    "viewer": ["read"],  # Read-only dashboard access
+    "auditor": ["read", "audit"],  # Read dashboard + audit logs
+}
+
+# Scope hierarchy: higher scopes implicitly grant lower ones (single-level lookup).
+# * -> control -> write -> read
+# Each scope explicitly lists ALL scopes it grants (no transitive resolution).
+_SCOPE_HIERARCHY = {
+    "*": {"control", "write", "read", "audit", "admin"},
+    "control": {"write", "read"},
+    "write": {"read"},
+}
+
 if OIDC_ENABLED:
     import logging as _logging
     _logging.getLogger("loki.auth").warning(
@@ -98,10 +115,39 @@ def _constant_time_compare(a: str, b: str) -> bool:
     return secrets.compare_digest(a.encode(), b.encode())
 
 
+def resolve_scopes(role_or_scopes) -> list[str]:
+    """Resolve a role name or scope list into a concrete list of scopes.
+
+    Args:
+        role_or_scopes: Either a role name (str), a single scope (str),
+                        or a list of scopes.
+
+    Returns:
+        List of scope strings.
+    """
+    if isinstance(role_or_scopes, list):
+        return role_or_scopes
+    if isinstance(role_or_scopes, str):
+        if role_or_scopes in ROLES:
+            return list(ROLES[role_or_scopes])
+        return [role_or_scopes]
+    return ["*"]
+
+
+def list_roles() -> dict[str, list[str]]:
+    """Return the predefined role-to-scope mapping.
+
+    Returns:
+        Dict mapping role names to their scope lists.
+    """
+    return dict(ROLES)
+
+
 def generate_token(
     name: str,
     scopes: Optional[list[str]] = None,
     expires_days: Optional[int] = None,
+    role: Optional[str] = None,
 ) -> dict:
     """
     Generate a new API token.
@@ -110,12 +156,16 @@ def generate_token(
         name: Human-readable name for the token
         scopes: Optional list of permission scopes (default: all)
         expires_days: Optional expiration in days (None = never expires)
+        role: Optional role name (admin, operator, viewer, auditor).
+              If provided, scopes are resolved from the role.
+              Cannot be combined with explicit scopes.
 
     Returns:
         Dict with token info (includes raw token - only shown once)
 
     Raises:
-        ValueError: If name is empty/too long or expires_days is invalid
+        ValueError: If name is empty/too long, expires_days is invalid,
+                    or role is unrecognized
     """
     # Validate inputs
     if not name or not name.strip():
@@ -124,9 +174,19 @@ def generate_token(
         raise ValueError("Token name too long (max 255 characters)")
     if expires_days is not None and expires_days <= 0:
         raise ValueError("expires_days must be positive (or None for no expiration)")
+    if role is not None and role not in ROLES:
+        raise ValueError(
+            f"Unknown role '{role}'. Valid roles: {', '.join(ROLES.keys())}"
+        )
 
     name = name.strip()
 
+    # Resolve scopes: role takes precedence if provided
+    if role is not None:
+        resolved_scopes = resolve_scopes(role)
+    else:
+        resolved_scopes = scopes
+
     # Generate secure random token
     raw_token = f"loki_{secrets.token_urlsafe(32)}"
     token_hash, token_salt = _hash_token(raw_token)
@@ -150,12 +210,14 @@ def generate_token(
         "name": name,
         "hash": token_hash,
         "salt": token_salt,
-        "scopes": scopes or ["*"],
+        "scopes": resolved_scopes or ["*"],
         "created_at": datetime.now(timezone.utc).isoformat(),
         "expires_at": expires_at,
         "last_used": None,
         "revoked": False,
     }
+    if role is not None:
+        token_entry["role"] = role
 
     tokens["tokens"][token_id] = token_entry
     _save_tokens(tokens)
@@ -247,6 +309,8 @@ def list_tokens(include_revoked: bool = False) -> list[dict]:
             "last_used": token.get("last_used"),
             "revoked": token.get("revoked", False),
         }
+        if "role" in token:
+            safe_token["role"] = token["role"]
         result.append(safe_token)
 
     return result
@@ -297,17 +361,32 @@ def validate_token(raw_token: str) -> Optional[dict]:
 
 def has_scope(token_info: dict, required_scope: str) -> bool:
     """
-    Check if a token has a required scope.
+    Check if a token has a required scope, respecting scope hierarchy.
+
+    Hierarchy (higher scopes implicitly grant lower ones):
+        * -> control -> write -> read
+        * also grants audit, admin, and all other scopes
 
     Args:
         token_info: Token metadata from validate_token
         required_scope: The scope to check
 
     Returns:
-        True if token has the scope (or wildcard)
+        True if token has the scope (directly or via hierarchy)
     """
     scopes = token_info.get("scopes", [])
-    return "*" in scopes or required_scope in scopes
+
+    # Direct match
+    if required_scope in scopes:
+        return True
+
+    # Check hierarchy: does any held scope implicitly grant the required one?
+    for scope in scopes:
+        implied = _SCOPE_HIERARCHY.get(scope, set())
+        if required_scope in implied:
+            return True
+
+    return False
 
 
 # ---------------------------------------------------------------------------

package/dashboard/server.py

@@ -26,6 +26,7 @@ from fastapi import (
     WebSocketDisconnect,
 )
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import PlainTextResponse
 from pydantic import BaseModel, Field
 from sqlalchemy import select, update, delete
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -246,7 +247,13 @@ app = FastAPI(
 # Add CORS middleware - restricted to localhost by default.
 # Set LOKI_DASHBOARD_CORS to override (comma-separated origins).
 _cors_default = "http://localhost:57374,http://127.0.0.1:57374"
-_cors_origins = os.environ.get("LOKI_DASHBOARD_CORS", _cors_default).split(",")
+_cors_raw = os.environ.get("LOKI_DASHBOARD_CORS", _cors_default)
+if _cors_raw.strip() == "*":
+    logger.warning(
+        "LOKI_DASHBOARD_CORS is set to '*' -- all origins are allowed. "
+        "This is insecure for production deployments."
+    )
+_cors_origins = _cors_raw.split(",")
 app.add_middleware(
     CORSMiddleware,
     allow_origins=[o.strip() for o in _cors_origins if o.strip()],
@@ -827,7 +834,36 @@ async def move_task(
 # WebSocket endpoint
 @app.websocket("/ws")
 async def websocket_endpoint(websocket: WebSocket) -> None:
-    """WebSocket endpoint for real-time updates."""
+    """WebSocket endpoint for real-time updates.
+
+    When enterprise auth or OIDC is enabled, a valid token must be passed
+    as a query parameter: ``/ws?token=loki_xxx`` (or a JWT for OIDC).
+    Browsers cannot send Authorization headers on WebSocket upgrade
+    requests, so query-parameter auth is the standard approach.
+    """
+    # --- WebSocket authentication gate ---
+    # NOTE: Query-parameter auth is used because browsers cannot send
+    # Authorization headers on WS upgrade. Tokens may appear in reverse
+    # proxy access logs -- configure log sanitization for /ws in production.
+    # FastAPI Depends() is not supported on @app.websocket() routes.
+    if auth.is_enterprise_mode() or auth.is_oidc_mode():
+        ws_token: Optional[str] = websocket.query_params.get("token")
+        if not ws_token:
+            await websocket.close(code=1008)  # Policy Violation
+            return
+
+        token_info: Optional[dict] = None
+        # Try OIDC first for JWT-style tokens
+        if auth.is_oidc_mode() and not ws_token.startswith("loki_"):
+            token_info = auth.validate_oidc_token(ws_token)
+        # Fall back to enterprise token auth
+        if token_info is None and auth.is_enterprise_mode():
+            token_info = auth.validate_token(ws_token)
+
+        if token_info is None:
+            await websocket.close(code=1008)  # Policy Violation
+            return
+
     await manager.connect(websocket)
     try:
         # Send initial connection confirmation
@@ -1043,7 +1079,7 @@ async def get_auth_info():
 class TokenCreateRequest(BaseModel):
     """Schema for creating a token."""
     name: str = Field(..., min_length=1, max_length=255, description="Human-readable token name")
-    scopes: Optional[list[str]] = Field(None, description="Permission scopes (default: ['*'] for all)")
+    scopes: Optional[Any] = Field(None, description="Permission scopes (default: ['*'] for all)")  # list[str], Any for Python 3.8
     expires_days: Optional[int] = Field(None, gt=0, description="Days until expiration (must be positive)")
 
 
@@ -1051,7 +1087,7 @@ class TokenResponse(BaseModel):
     """Schema for token response."""
     id: str
     name: str
-    scopes: list[str]
+    scopes: Any  # list[str], Any for Python 3.8
     created_at: str
     expires_at: Optional[str]
     last_used: Optional[str]
@@ -2584,6 +2620,186 @@ async def get_process_health(token: Optional[dict] = Depends(auth.get_current_to
     return result
 
 
+# =============================================================================
+# Prometheus / OpenMetrics Endpoint
+# =============================================================================
+
+
+def _build_metrics_text() -> str:
+    """Build Prometheus/OpenMetrics format metrics text from .loki/ flat files."""
+    lines = []  # type: list[str]  -- comment-style for Python 3.8
+    loki_dir = _get_loki_dir()
+
+    # Validate LOKI_DIR exists before attempting to read metrics
+    if not loki_dir.is_dir():
+        return "# loki_up 0\n"
+
+    # -- Read dashboard-state.json (primary data source) ----------------------
+    state: dict = {}
+    state_file = loki_dir / "dashboard-state.json"
+    if state_file.exists():
+        try:
+            state = json.loads(state_file.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # 1. loki_session_status (gauge) ------------------------------------------
+    mode = state.get("mode", "")
+    status_val = 0  # stopped
+    if mode == "paused":
+        status_val = 2
+    elif mode in ("autonomous", "running"):
+        status_val = 1
+    else:
+        # Also check PID file
+        pid_file = loki_dir / "loki.pid"
+        if pid_file.exists():
+            try:
+                pid = int(pid_file.read_text().strip())
+                os.kill(pid, 0)
+                status_val = 1
+            except (ValueError, OSError, ProcessLookupError):
+                pass
+
+    lines.append("# HELP loki_session_status Current session status (0=stopped, 1=running, 2=paused)")
+    lines.append("# TYPE loki_session_status gauge")
+    lines.append(f"loki_session_status {status_val}")
+    lines.append("")
+
+    # 2. loki_iteration_current (gauge) ---------------------------------------
+    iteration = state.get("iteration", 0)
+    lines.append("# HELP loki_iteration_current Current iteration number")
+    lines.append("# TYPE loki_iteration_current gauge")
+    lines.append(f"loki_iteration_current {iteration}")
+    lines.append("")
+
+    # 3. loki_iteration_max (gauge) -------------------------------------------
+    max_iterations = int(os.environ.get("LOKI_MAX_ITERATIONS", "1000"))
+    lines.append("# HELP loki_iteration_max Maximum configured iterations")
+    lines.append("# TYPE loki_iteration_max gauge")
+    lines.append(f"loki_iteration_max {max_iterations}")
+    lines.append("")
+
+    # 4. loki_tasks_total (gauge, label: status) ------------------------------
+    tasks = state.get("tasks", {})
+    pending_count = len(tasks.get("pending", []))
+    in_progress_count = len(tasks.get("inProgress", []))
+    completed_count = len(tasks.get("completed", []))
+    failed_count = len(tasks.get("failed", []))
+
+    lines.append("# HELP loki_tasks_total Number of tasks by status")
+    lines.append("# TYPE loki_tasks_total gauge")
+    lines.append(f'loki_tasks_total{{status="pending"}} {pending_count}')
+    lines.append(f'loki_tasks_total{{status="in_progress"}} {in_progress_count}')
+    lines.append(f'loki_tasks_total{{status="completed"}} {completed_count}')
+    lines.append(f'loki_tasks_total{{status="failed"}} {failed_count}')
+    lines.append("")
+
+    # 5. loki_agents_active (gauge) -------------------------------------------
+    # 6. loki_agents_total (counter) ------------------------------------------
+    agents_active = 0
+    agents_total = 0
+    agents_file = loki_dir / "state" / "agents.json"
+    if agents_file.exists():
+        try:
+            agents_data = json.loads(agents_file.read_text())
+            if isinstance(agents_data, list):
+                agents_total = len(agents_data)
+                agents_active = sum(
+                    1 for a in agents_data
+                    if isinstance(a, dict) and a.get("status") == "active"
+                )
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Fallback to dashboard-state.json agents
+    if agents_total == 0:
+        state_agents = state.get("agents", [])
+        if isinstance(state_agents, list):
+            agents_total = len(state_agents)
+            agents_active = sum(
+                1 for a in state_agents
+                if isinstance(a, dict) and a.get("status") == "active"
+            )
+
+    lines.append("# HELP loki_agents_active Number of currently active agents")
+    lines.append("# TYPE loki_agents_active gauge")
+    lines.append(f"loki_agents_active {agents_active}")
+    lines.append("")
+
+    lines.append("# HELP loki_agents_total Total number of agents registered")
+    lines.append("# TYPE loki_agents_total gauge")
+    lines.append(f"loki_agents_total {agents_total}")
+    lines.append("")
+
+    # 7. loki_cost_usd (gauge) ------------------------------------------------
+    estimated_cost = 0.0
+    efficiency_dir = loki_dir / "metrics" / "efficiency"
+    if efficiency_dir.exists():
+        try:
+            for eff_file in efficiency_dir.glob("*.json"):
+                try:
+                    data = json.loads(eff_file.read_text())
+                    cost = data.get("cost_usd")
+                    if cost is not None:
+                        estimated_cost += float(cost)
+                    else:
+                        inp = data.get("input_tokens", 0)
+                        out = data.get("output_tokens", 0)
+                        estimated_cost += _calculate_model_cost(
+                            data.get("model", "sonnet").lower(), inp, out
+                        )
+                except (json.JSONDecodeError, KeyError, TypeError):
+                    pass
+        except OSError:
+            pass
+
+    lines.append("# HELP loki_cost_usd Estimated total cost in USD")
+    lines.append("# TYPE loki_cost_usd gauge")
+    lines.append(f"loki_cost_usd {round(estimated_cost, 6)}")
+    lines.append("")
+
+    # 8. loki_events_total (counter) ------------------------------------------
+    events_count = 0
+    events_file = loki_dir / "events.jsonl"
+    if events_file.exists():
+        try:
+            content = events_file.read_text()
+            events_count = sum(1 for line in content.strip().split("\n") if line.strip())
+        except OSError:
+            pass
+
+    lines.append("# HELP loki_events_total Total number of events recorded")
+    lines.append("# TYPE loki_events_total counter")
+    lines.append(f"loki_events_total {events_count}")
+    lines.append("")
+
+    # 9. loki_uptime_seconds (gauge) ------------------------------------------
+    uptime_seconds = 0.0
+    started_at = state.get("startedAt", "")
+    if started_at:
+        try:
+            start_dt = datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+            uptime_seconds = (datetime.now(timezone.utc) - start_dt).total_seconds()
+            if uptime_seconds < 0:
+                uptime_seconds = 0.0
+        except (ValueError, TypeError):
+            pass
+
+    lines.append("# HELP loki_uptime_seconds Seconds since session started")
+    lines.append("# TYPE loki_uptime_seconds gauge")
+    lines.append(f"loki_uptime_seconds {round(uptime_seconds, 1)}")
+    lines.append("")
+
+    return "\n".join(lines) + "\n"
+
+
+@app.get("/metrics", response_class=PlainTextResponse)
+async def prometheus_metrics():
+    """Prometheus/OpenMetrics compatible metrics endpoint."""
+    return _build_metrics_text()
+
+
 # =============================================================================
 # Static File Serving (Production/Docker)
 # =============================================================================

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 Complete installation instructions for all platforms and use cases.
 
-**Version:** v5.37.0
+**Version:** v5.38.0
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "5.37.0",
+  "version": "5.38.0",
   "description": "Multi-agent autonomous startup system for Claude Code, Codex CLI, and Gemini CLI",
   "keywords": [
     "claude",

package/providers/gemini.sh

@@ -49,7 +49,7 @@ PROVIDER_MAX_PARALLEL=1
 
 # Model Configuration
 # Gemini CLI supports --model flag to specify model
-# Primary: gemini-3-pro-preview (latest as of Jan 2026)
+# Primary: gemini-3-pro-preview (preview names - may change when GA is released)
 # Fallback: gemini-3-flash-preview (for rate limit scenarios)
 PROVIDER_MODEL="gemini-3-pro-preview"
 PROVIDER_MODEL_FALLBACK="gemini-3-flash-preview"
@@ -69,7 +69,9 @@ PROVIDER_TASK_MODEL_VALUES=()
 # Context and Limits
 PROVIDER_CONTEXT_WINDOW=1000000  # Gemini 3 has 1M context
 PROVIDER_MAX_OUTPUT_TOKENS=65536
-PROVIDER_RATE_LIMIT_RPM=60
+# Rate limit varies by tier: Free=5-15 RPM, Tier1=150+ RPM, Tier2=500+ RPM
+# Default to conservative free-tier value; override with LOKI_GEMINI_RPM env var
+PROVIDER_RATE_LIMIT_RPM="${LOKI_GEMINI_RPM:-15}"
 
 # Cost (USD per 1K tokens, approximate for Gemini 3 Pro)
 PROVIDER_COST_INPUT_PLANNING=0.00125